Skip to content

matthewwong525/WongStack / .agents/plugins/browser/skills/hand-over

hand-over

Verified

scripts/keys.mjs

View on GitHub
// The key link's routes, mounted by `hand-over.mjs open --keys`, which checks the key and the guide first.
// Nothing here logs, and no value reaches argv, env, or any file but the live ones: only a check's own address.

import { execFileSync } from 'node:child_process';
import { randomBytes } from 'node:crypto';
import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
import { basename, dirname, join } from 'node:path';
import { slot } from '../../../scripts/lib/profile.mjs';

export const LIMITS = { names: 20, body: 128 * 1024, value: 32 * 1024, hint: 200, title: 40, why: 140, steps: 6, step: 140 };
const CHECK_TIMEOUT_MS = 8000;
export const KEY_ROUTES = new Set(['/keys', '/save', '/continue', '/done']);
export const NAME = /^[A-Z_][A-Z0-9_]*$/;
/** One line of a dotenv file: its name, then its value. */
export const ENTRY = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/;
// Written bare, a value of only these reads back unchanged in dotenv, wrangler, the memory parser, and a
// shell's `source`; `~` is left out, since a shell expands it.
const BARE = /^[A-Za-z0-9_\-.:/+=@]+$/;

/** The first sentence of a comment block, `#` marks stripped, capped at LIMITS.hint; '' for none. */
export function firstSentence(comments) {
  const text = comments.map(line => line.replace(/^\s*#+\s?/, '')).join(' ').replace(/\s+/g, ' ').trim();
  const sentence = /^.*?[.!?](?=\s|$)/.exec(text)?.[0] ?? text;
  return sentence.length > LIMITS.hint ? `${sentence.slice(0, LIMITS.hint - 1).trimEnd()}…` : sentence;
}

/** An example file's declared names, each with its hint: the comment block directly above it. */
export function declarations(text) {
  const found = new Map();
  const lines = text.split(/\r?\n/);
  lines.forEach((line, index) => {
    const name = line.match(ENTRY)?.[1];
    if (!name || found.has(name)) return;
    let top = index;
    while (top > 0 && /^\s*#/.test(lines[top - 1])) top--;
    found.set(name, firstSentence(lines.slice(top, index)));
  });
  return found;
}

const readText = file => (existsSync(file) ? readFileSync(file, 'utf8') : '');

/** True when `file` has a non-empty value for `name`. */
function hasValue(file, name) {
  return readText(file).split(/\r?\n/).some(line => {
    const match = line.match(ENTRY);
    return match?.[1] === name && !/^\s*(''|""|)\s*(#.*)?$/.test(match[2]);
  });
}

/** True when Git ignores `rel` in the checkout at `root`. */
export function isIgnored(root, rel) {
  try {
    execFileSync('git', ['check-ignore', '-q', rel], { cwd: root, stdio: 'ignore' });
    return true;
  } catch {
    return false;
  }
}

/** The files a key may go to, from the profile's `keyFiles(ctx)` slot: each `{ file, names?, app?, copy? }`, where
 * `names(name)` gives a name's hint, or null for one the file does not take. Empty, the top `.env` takes any name. */
export async function keyFiles(ctx) {
  const files = await slot('keyFiles');
  return files ? files(ctx) : [{ file: '.env' }];
}

/** Where each name goes: the one file of `files` that takes it. The link opens only when `undeclared`, `ambiguous`,
 * and `unignored` are empty. `ctx` is primary-root.mjs's result. */
export function resolveKeys(names, ctx, files) {
  const keys = [];
  const undeclared = [];
  const ambiguous = [];
  for (const name of names) {
    const where = files.map(entry => ({ entry, hint: entry.names ? entry.names(name) : '' })).filter(found => found.hint != null);
    if (!where.length) undeclared.push(name);
    else if (where.length > 1) ambiguous.push(name);
    else {
      const [{ entry: { file, app, copy }, hint }] = where;
      keys.push({ name, file, hint, ...(app && { app: true }), ...(copy && { copy }) });
    }
  }
  const roots = ctx.linked ? [ctx.primary, ctx.root] : [ctx.primary];
  const unignored = [...new Set(keys.map(key => key.file))].flatMap(file => roots
    .filter(root => !existsSync(dirname(join(root, file))) || !isIgnored(root, file))
    .map(root => join(root, file)));
  return { keys, undeclared, ambiguous, unignored };
}

/** The page's list: each key's name, hint, whether a value is set now, and its guide, the test as its host alone. */
export function describeKeys(config) {
  return config.keys.map(({ name, file, hint, guide, copy }) => {
    const { check, ...shown } = guide ?? {};
    return { name, hint, set: hasValue(join(config.primary, file), name) || Boolean(copy && hasValue(copy, name)), ...shown, ...(check && { checkHost: new URL(check.url).host }) };
  });
}

const isObject = value => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
const isText = (value, most) => typeof value === 'string' && Boolean(value.trim()) && value.length <= most && !/[\r\n\0]/.test(value);
const HEADER = /^[A-Za-z][A-Za-z0-9-]*$/;
const BANNED_HEADERS = new Set(['host', 'cookie', 'content-length']);
const QUERY = /^[A-Za-z0-9_.-]+$/;

/** An `https` address with a dotted host name as a URL; null for an IP literal, `localhost`, or one with a login. */
export function httpsUrl(address) {
  if (typeof address !== 'string' || !URL.canParse(address)) return null;
  const url = new URL(address);
  const host = url.hostname;
  const named = host.includes('.') && !host.endsWith('.') && !host.startsWith('[') && !/^[\d.]+$/.test(host) && !host.endsWith('.localhost');
  return url.protocol === 'https:' && named && !url.username && !url.password ? url : null;
}

/** Where a check's `auth` puts the key, `{header}` or `{query}`; null for a shape a guide may not use. */
export function authPlace(auth) {
  if (auth === 'bearer' || auth === 'basic') return { header: 'authorization' };
  const [kind, name, ...rest] = typeof auth === 'string' ? auth.split(':') : [];
  if (!name || rest.length) return null;
  if (kind === 'header') return HEADER.test(name) && !BANNED_HEADERS.has(name.toLowerCase()) ? { header: name } : null;
  return kind === 'query' && QUERY.test(name) ? { query: name } : null;
}

const GUIDE_FIELDS = new Set(['title', 'why', 'url', 'open', 'steps', 'check']);
const CHECK_FIELDS = new Set(['url', 'auth']);
/** Each reason a guide entry is refused, with the test that finds it. */
const GUIDE_FAULTS = [
  ['takes only title, why, url, open, steps, and check', entry => Object.keys(entry).some(field => !GUIDE_FIELDS.has(field))],
  [`title and open take 1 to ${LIMITS.title} characters on one line`, ({ title, open }) => [title, open].some(text => text !== undefined && !isText(text, LIMITS.title))],
  [`why takes 1 to ${LIMITS.why} characters on one line`, ({ why }) => why !== undefined && !isText(why, LIMITS.why)],
  ['url takes an https address with a host name', ({ url }) => url !== undefined && !httpsUrl(url)],
  ['open needs a url', ({ url, open }) => open !== undefined && url === undefined],
  [`steps takes at most ${LIMITS.steps} lines of 1 to ${LIMITS.step} characters`, ({ steps }) => steps !== undefined && !(Array.isArray(steps) && steps.length <= LIMITS.steps && steps.every(step => isText(step, LIMITS.step)))],
  ['check takes an https url with a host name and an auth of bearer, basic, header:<Name>, or query:<name>', ({ check }) => check !== undefined && !(isObject(check) && Object.keys(check).every(field => CHECK_FIELDS.has(field)) && httpsUrl(check.url) && authPlace(check.auth))],
];

/** Checks the parsed `--guide` file against the asked-for names. Resolves to `{guide}`, or to
 * `{fault: '<name>: <reason>'}` for the first entry that is not asked for or is badly shaped. */
export function checkGuide(guide, names) {
  if (!isObject(guide)) return { fault: 'guide: takes a JSON object keyed by key name' };
  for (const [name, entry] of Object.entries(guide)) {
    const reason = !names.includes(name) ? 'not an asked-for key' : !isObject(entry) ? 'takes an object' : GUIDE_FAULTS.find(([, found]) => found(entry))?.[0];
    if (reason) return { fault: `${name}: ${reason}` };
  }
  return { guide };
}

/** The one request that tests `value`: the check's address and headers, the key placed by its `auth`. */
function checkRequest({ url, auth }, value) {
  const target = new URL(url);
  const place = authPlace(auth);
  if (place.query) target.searchParams.set(place.query, value);
  const sent = auth === 'bearer' ? `Bearer ${value}` : auth === 'basic' ? `Basic ${Buffer.from(`${value}:`).toString('base64')}` : value;
  return { url: target.href, headers: place.header ? { [place.header]: sent } : {} };
}

/** Asks the service once whether it takes `value`: 'works' on 2xx, 'refused' on 401 or 403, else 'untested',
 * as for a redirect or a timeout. It follows no redirect, cancels the body unread, and keeps nothing. */
export async function checkKey(check, value, ask = globalThis.fetch) {
  try {
    const { url, headers } = checkRequest(check, value);
    const response = await ask(url, { method: 'GET', headers, redirect: 'manual', signal: AbortSignal.timeout(CHECK_TIMEOUT_MS) });
    await response.body?.cancel().catch(() => {});
    if (response.status >= 200 && response.status < 300) return 'works';
    return response.status === 401 || response.status === 403 ? 'refused' : 'untested';
  } catch {
    return 'untested';
  }
}

/** Text over several lines as one storable value: JSON compacted, other text as it is. A `'` inside the
 * JSON is written as its `'` escape, the same data, so single quotes hold any key file. */
function compact(text) {
  try {
    return JSON.stringify(JSON.parse(text)).replaceAll("'", '\\u0027');
  } catch {
    return text;
  }
}

/** A value as the page sent it, trimmed, its line breaks as `\n` and a JSON file's taken out; null when
 * it is empty or its stored form is too long. */
export function cleanValue(value) {
  if (typeof value !== 'string') return null;
  const text = value.replace(/\r\n?/g, '\n').trim();
  const clean = text.includes('\n') ? compact(text) : text;
  return clean && clean.replaceAll('\n', '\\n').length <= LIMITS.value && !clean.includes('\0') ? clean : null;
}

/** The live-file line for a key, or null for a value no quoting keeps whole. dotenv and the memory parser
 * unescape no quoted value, so quoting picks a mark the value lacks; only `\n` in double quotes is turned back. */
export function formatLine(name, value) {
  if (value.includes('\n')) return /["\\$`]/.test(value) ? null : `${name}="${value.replaceAll('\n', '\\n')}"`;
  if (BARE.test(value)) return `${name}=${value}`;
  if (!value.includes("'")) return `${name}='${value}'`;
  if (!/["\\$`]/.test(value)) return `${name}="${value}"`;
  return null;
}

/** Sets `name` in the dotenv file at `path`: its first line is replaced in place, keeping any `export`, and later
 * duplicates dropped; else appended. Written whole to a temp file beside it, mode 0600, then renamed over it. */
export function setKey(path, name, line) {
  const lines = readText(path).split('\n');
  let found = false;
  const next = [];
  for (const each of lines) {
    if (each.match(ENTRY)?.[1] !== name) next.push(each);
    else if (!found) {
      found = true;
      next.push(`${/^\s*export\s/.test(each) ? 'export ' : ''}${line}`);
    }
  }
  if (!found) {
    if (next.at(-1) === '') next.pop();
    next.push(line, '');
  }
  const temp = join(dirname(path), `${basename(path)}.${randomBytes(6).toString('hex')}.tmp`);
  try {
    writeFileSync(temp, next.join('\n'), { mode: 0o600, flag: 'wx' });
    renameSync(temp, path);
  } finally {
    rmSync(temp, { force: true });
  }
}

/** Writes one key's line to the primary worktree's file and any copy its key file names; false when it can't. */
function writeKey(config, { name, file, copy }, line) {
  try {
    setKey(join(config.primary, file), name, line);
    if (copy) setKey(copy, name, line);
    return true;
  } catch {
    return false;
  }
}

/** A request's JSON body, or a status: 413 past the byte limit, 400 when it isn't JSON. */
async function readBody(request) {
  const chunks = [];
  let size = 0;
  for await (const chunk of request) {
    size += chunk.length;
    if (size <= LIMITS.body) chunks.push(chunk);
  }
  if (size > LIMITS.body) return 413;
  try {
    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
  } catch {
    return 400;
  }
}

function reply(response, status, body) {
  const text = body ? JSON.stringify(body) : '';
  response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', 'content-length': Buffer.byteLength(text) }).end(text);
}

/** A save request's `[name, value]` pairs, or 400 unless it names at least one asked-for key and no
 * other, in `keys` and in any `force` list. */
export function checkKeys(body, asked) {
  if (!isObject(body) || !isObject(body.keys)) return 400;
  const force = body.force ?? [];
  if (!Array.isArray(force) || !force.every(name => asked.has(name))) return 400;
  const pairs = Object.entries(body.keys);
  return pairs.length && pairs.every(([name]) => asked.has(name)) ? pairs : 400;
}

/** The key routes for `config`. `onSaved(name)` hears each saved name; `onDone()` runs once the reply has
 * gone, on `/done` or when a save leaves no asked-for key unsaved. `onOpened()` hears each `GET /keys`. */
export function keyRoutes(config, { onSaved = () => {}, onDone = () => {}, onContinue = async () => null, isOpen = () => true, onOpened = () => {}, closesAt, fetch: ask = globalThis.fetch } = {}) {
  const asked = new Map(config.keys.map(key => [key.name, key]));
  const saved = new Set();
  let terminal = false;
  let queue = Promise.resolve();
  const serial = job => {
    const run = queue.then(job);
    queue = run.catch(() => {});
    return run;
  };
  /** One key's outcome: 'works' or 'untested' once written, 'refused' by its test and not written, or 'failed'. */
  const saveKey = async (key, value, forced) => {
    const clean = cleanValue(value);
    const line = clean === null ? null : formatLine(key.name, clean);
    if (!line) return 'failed';
    const verdict = key.guide?.check && !forced ? await checkKey(key.guide.check, clean, ask) : 'untested';
    return verdict === 'refused' || writeKey(config, key, line) ? verdict : 'failed';
  };
  const route = async (pathname, request, response) => {
    if (pathname === '/keys') {
      if (request.method !== 'GET') return reply(response, 405);
      onOpened();
      return reply(response, 200, { keys: describeKeys(config), closesAt, now: Date.now() });
    }
    if (request.method !== 'POST') return reply(response, 405);
    const body = pathname === '/done' ? null : await readBody(request);
    const outcome = await serial(async () => {
      if (terminal || !isOpen()) return { status: 410 };
      if (pathname === '/done') { terminal = true; return { cancelled: true }; }
      const pairs = typeof body === 'number' ? body : (pathname === '/continue' && isObject(body?.keys) && !Object.keys(body.keys).length ? [] : checkKeys(body, asked));
      if (typeof pairs === 'number') return { status: pairs };
      const result = { saved: [], failed: [], refused: [], checked: {} };
      for (const [name, value] of pairs) {
        const verdict = await saveKey(asked.get(name), value, body.force?.includes(name));
        if (verdict === 'failed' || verdict === 'refused') { result[verdict].push(name); continue; }
        result.saved.push(name);
        result.checked[name] = verdict;
        saved.add(name);
        onSaved(name);
      }
      const missing = [...asked.keys()].filter(name => !saved.has(name));
      const ready = !missing.length && !result.failed.length;
      if (ready) terminal = true;
      return { result, ready, missing };
    });
    if (outcome.status) return reply(response, outcome.status);
    if (outcome.cancelled) {
      response.once('finish', () => onDone(false));
      return reply(response, 200, { ok: true });
    }
    const receipt = outcome.ready && pathname === '/continue' ? await onContinue() : null;
    if (outcome.ready && pathname === '/save') response.once('finish', () => onDone(true));
    reply(response, 200, { ...outcome.result, ...(pathname === '/continue' && { ready: outcome.ready, missing: outcome.missing, ...(receipt && { receipt }) }) });
  };
  route.drain = () => queue;
  return route;
}
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall