@kosuke-ai/kosuke 1.0.7 → 1.0.9

package/dist/runtime/attach.js

@@ -1,80 +1,298 @@
+import { readFileSync } from 'node:fs';
 import { Argument, Command, InvalidArgumentError, Option } from 'commander';
 import { buildRequest, execute, readWholeBody, UsageError } from './invoke.js';
+import { fieldsOf, formLabel, formUsage, leafShape, pathParamsFor, PERSONAL, scopeOf, selectForm, } from './variants.js';
 /**
- * One commander command per operation descriptor: positionals for path
- * params, a flag per top-level field, `--body`/`--body-file` for a whole
- * body and `--attach` where the operation takes files. The command's help is
- * the contract's summary, verbatim.
+ * One commander command per command name: positionals for path params, a flag per
+ * top-level field, `--body`/`--body-file` for a whole body and `--attach` where the
+ * operation takes files. A command with several forms (personal, all, a selector flag)
+ * is one leaf over all of them; `variants.ts` picks the form a call reaches. The help is
+ * the contract's summary, verbatim, and a `Forms:` list when there are several.
  */
-export function attachOperation(root, operation, runtime) {
-    return attachLeaf(root, operation.command, operation, runtime);
+export function attachCommand(root, forms, runtime, { reachable = () => true } = {}) {
+    const [only] = forms;
+    if (forms.length === 1 && !only.variant) {
+        // A hidden operation sits beside a hand-written command in a visible group.
+        return attachLeaf(root, only.command, only, runtime, {
+            hidden: only.hidden === true,
+            groupsHidden: false,
+        });
+    }
+    return attachForms(root, forms, runtime, reachable);
 }
-function attachLeaf(root, path, operation, runtime) {
-    const parent = groupFor(root, path.slice(0, -1));
-    const leaf = parent.command(path[path.length - 1]);
+/** A single-form leaf: the command as it was before forms, which aliases reuse. */
+export function attachLeaf(root, path, operation, runtime, { hidden, groupsHidden = hidden, fixed = {}, formerFlags = {} }) {
+    const parent = groupFor(root, path.slice(0, -1), { hidden: groupsHidden });
+    const leaf = parent.command(path[path.length - 1], { hidden });
     leaf.description(operation.summary);
     for (const name of operation.pathParams) {
         leaf.addArgument(new Argument(`<${name}>`, humanize(name)));
     }
-    const fields = dedupe([
-        ...operation.query,
-        ...(operation.body?.fields ?? []),
-        ...(operation.multipart ?? []),
-    ]);
-    for (const field of fields) {
-        leaf.addOption(optionFor(field));
-        // Both spellings, so a field whose meaningful value is false (members
-        // --no-include-invitations) can be said; neither given leaves it unsent.
-        if (field.kind === 'boolean') {
-            leaf.addOption(new Option(`--no-${field.flag}`, `Send ${field.name} as false.`));
+    const fields = fieldsOf(operation);
+    for (const field of fields)
+        addFieldOptions(leaf, field, field.description ?? '');
+    for (const [former, current] of Object.entries(formerFlags)) {
+        const field = fields.find((candidate) => candidate.flag === current);
+        if (!field) {
+            throw new Error(`kosuke ${path.join(' ')}: --${former} names --${current}, not a flag.`);
         }
+        const option = new Option(`--${former} <value>`).hideHelp();
+        // Repeated as it was, `--project-ids a --project-ids b`, or one JSON list.
+        if (field.repeated)
+            option.argParser(collect).default(undefined);
+        leaf.addOption(option);
     }
-    const takesBody = operation.body !== null || operation.multipart !== null;
-    if (takesBody) {
-        leaf.option('--body <json>', 'The whole request body as JSON; overrides field flags.');
-        leaf.option('--body-file <path>', 'Read the whole request body from a file, or - for stdin.');
-    }
-    if (operation.attachments) {
-        leaf.option('--attach <path>', 'Attach a file; repeat for several. Sends the request as multipart.', collect, []);
-    }
+    addBodyOptions(leaf, operation);
     leaf.action(async (...args) => {
         const options = args[args.length - 2];
         const positionals = args.slice(0, operation.pathParams.length);
-        const input = {
+        try {
+            checkFileFlags(options, fields.filter((field) => field.file).map((field) => field.flag));
+            // `personal` where a workspace id goes, on a command with no personal form. An alias
+            // leaf runs a personal form by its old path, which takes no workspace id at all.
+            if (!operation.variant)
+                selectForm([operation], { first: positionals[0], flags: {} });
+        }
+        catch (error) {
+            if (error instanceof UsageError)
+                leaf.error(error.message);
+            throw error;
+        }
+        const values = Object.fromEntries(fields.map((field) => {
+            const former = Object.entries(formerFlags).find(([, current]) => current === field.flag);
+            const formerValue = former
+                ? formerValueOf(field, options[optionKey(former[0])])
+                : undefined;
+            return [
+                field.name,
+                options[optionKey(field.flag)] ?? fileValue(field, options) ?? formerValue,
+            ];
+        }));
+        await run(leaf, runtime, operation, {
             pathParams: Object.fromEntries(operation.pathParams.map((name, i) => [name, positionals[i]])),
-            fields: Object.fromEntries(fields.map((field) => [field.name, options[optionKey(field.flag)]])),
+            fields: { ...values, ...fixed },
             wholeBody: readWholeBody({
                 body: options.body,
                 bodyFile: options.bodyFile,
             }),
             attachments: options.attach ?? [],
-        };
-        let request;
+        });
+    });
+    return leaf;
+}
+/** A leaf over several forms: the union of their flags, the form picked per call. */
+function attachForms(root, forms, runtime, reachable) {
+    const path = forms[0].command;
+    const shape = leafShape(forms);
+    const parent = groupFor(root, path.slice(0, -1));
+    const leaf = parent.command(path[path.length - 1]);
+    const visible = forms.filter(reachable);
+    const lead = forms.find((form) => scopeOf(form) === 'workspace') ?? forms[0];
+    leaf.description(lead.summary);
+    if (shape.scope) {
+        leaf.addArgument(new Argument(shape.scope.label, shape.scope.label === `<${PERSONAL}>`
+            ? 'The word personal: this command works on your own only.'
+            : `A ${humanize(shape.scope.name).toLowerCase()}` +
+                (shape.scope.label.includes(PERSONAL) ? ', or personal for your own' : '') +
+                (shape.scope.optional ? '; left out, every one you can reach' : '')));
+    }
+    for (const name of shape.positionals) {
+        leaf.addArgument(new Argument(`<${name}>`, humanize(name)));
+    }
+    for (const leafFlag of shape.flags) {
+        const fields = [...leafFlag.forms.values()];
+        const note = whoTakes(leafFlag, forms);
+        if (leafFlag.uniform && fields.length) {
+            const [field] = fields;
+            const required = fields.every((f) => f.required) && leafFlag.forms.size === forms.length;
+            addFieldOptions(leaf, { ...field, required }, appendNote(field.description ?? '', note));
+        }
+        else {
+            const values = forms
+                .filter((form) => form.variant?.when?.flag === leafFlag.flag)
+                .map((form) => form.variant.when.equals);
+            const choices = [...new Set([...values, ...fields.flatMap((field) => field.choices ?? [])])];
+            const description = [
+                fields.find((field) => field.description)?.description ?? '',
+                choices.length ? `One of ${choices.join(', ')}.` : '',
+            ]
+                .filter(Boolean)
+                .join(' ');
+            leaf.addOption(new Option(`--${leafFlag.flag} <value>`, appendNote(description, note)));
+            if (fields.some((field) => field.file)) {
+                leaf.addOption(new Option(`--${leafFlag.flag}-file <path>`, `Read --${leafFlag.flag} from a file, or - for stdin.`));
+            }
+            if (fields.length && fields.every((field) => field.kind === 'boolean')) {
+                leaf.addOption(new Option(`--no-${leafFlag.flag}`, `Send it as false.`));
+            }
+        }
+    }
+    addBodyOptions(leaf, {
+        body: forms.find((form) => form.body)?.body ?? null,
+        multipart: forms.find((form) => form.multipart)?.multipart ?? null,
+        attachments: forms.find((form) => form.attachments)?.attachments ?? false,
+    });
+    leaf.addHelpText('after', () => '\nForms:\n' +
+        visible.map((form) => `  ${formUsage(form, shape)}\n      ${form.summary}`).join('\n'));
+    leaf.action(async (...args) => {
+        const options = args[args.length - 2];
+        const operands = args.slice(0, args.length - 2);
+        const first = operands[0];
+        const positionals = (shape.scope ? operands.slice(1) : operands);
+        const given = {};
+        for (const leafFlag of shape.flags) {
+            const value = options[optionKey(leafFlag.flag)] ?? options[optionKey(`${leafFlag.flag}-file`)];
+            if (value !== undefined)
+                given[leafFlag.flag] = value;
+        }
+        let form;
         try {
-            request = buildRequest(operation, input);
+            checkFileFlags(options, shape.flags
+                .filter((leafFlag) => [...leafFlag.forms.values()].some((field) => field.file))
+                .map((leafFlag) => leafFlag.flag));
+            form = selectForm(forms, { first, flags: given }, reachable);
         }
         catch (error) {
             if (error instanceof UsageError)
                 leaf.error(error.message);
             throw error;
         }
-        const client = runtime.client({
-            anonymous: operation.anonymous,
-            answerTimeoutMs: operation.answerTimeoutMs,
+        const fields = {};
+        try {
+            for (const leafFlag of shape.flags) {
+                const field = leafFlag.forms.get(form);
+                if (!field || field.pathParam)
+                    continue;
+                const raw = options[optionKey(leafFlag.flag)];
+                fields[field.name] =
+                    raw === undefined
+                        ? fileValue(field, options)
+                        : leafFlag.uniform
+                            ? raw
+                            : parseForForm(field, raw);
+            }
+        }
+        catch (error) {
+            if (error instanceof UsageError || error instanceof InvalidArgumentError) {
+                leaf.error(error.message);
+            }
+            throw error;
+        }
+        await run(leaf, runtime, form, {
+            pathParams: pathParamsFor(form, shape, first, positionals, given),
+            fields,
+            wholeBody: readWholeBody({
+                body: options.body,
+                bodyFile: options.bodyFile,
+            }),
+            attachments: options.attach ?? [],
         });
-        const outcome = await execute(client, request);
-        runtime.output(outcome);
     });
     return leaf;
 }
-export function groupFor(root, path) {
+/** Build, send and print; a usage error is commander's, so it prints as one. */
+async function run(leaf, runtime, operation, input) {
+    let request;
+    try {
+        request = buildRequest(operation, input);
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            leaf.error(error.message);
+        throw error;
+    }
+    const client = runtime.client({
+        anonymous: operation.anonymous,
+        answerTimeoutMs: operation.answerTimeoutMs,
+    });
+    const outcome = await execute(client, request);
+    runtime.output(outcome);
+}
+/** `(personal only)`, `(workspace only)`, `(--provider claude_code, codex)`; empty for all. */
+function whoTakes(leafFlag, forms) {
+    const takers = forms.filter((form) => leafFlag.forms.has(form) || form.variant?.when?.flag === leafFlag.flag);
+    if (takers.length === forms.length)
+        return '';
+    const scopes = [...new Set(takers.map(scopeOf))];
+    const allOfScope = scopes.every((scope) => forms.filter((form) => scopeOf(form) === scope).every((form) => takers.includes(form)));
+    if (allOfScope)
+        return `(${scopes.join(' and ')} only)`;
+    const selected = takers.filter((form) => form.variant?.when);
+    if (selected.length === takers.length) {
+        const flag = selected[0].variant.when.flag;
+        return `(--${flag} ${selected.map((form) => form.variant.when.equals).join(', ')})`;
+    }
+    return `(${takers.map((form) => formLabel(form).replace(/^the | form$/g, '')).join(', ')})`;
+}
+function appendNote(description, note) {
+    return [description, note].filter(Boolean).join(' ');
+}
+/** A union flag the forms disagree on arrives as text, parsed by the chosen form's rule. */
+function parseForForm(field, raw) {
+    if (typeof raw !== 'string')
+        return raw;
+    if (field.choices && !field.choices.includes(raw)) {
+        throw new UsageError(`--${field.flag} must be one of ${field.choices.join(', ')}.`);
+    }
+    if (field.kind === 'number' || field.kind === 'integer')
+        return numberParser(field)(raw);
+    if (field.kind === 'json')
+        return jsonParser(raw);
+    if (field.kind === 'boolean')
+        return raw === 'true';
+    return field.repeated ? [raw] : raw;
+}
+/** The value of a renamed flag, by the rule its field had: one JSON list, or the values given. */
+function formerValueOf(field, raw) {
+    if (Array.isArray(raw))
+        return raw.flatMap((value) => formerValueOf(field, value));
+    if (typeof raw !== 'string')
+        return raw;
+    if (!field.repeated)
+        return field.kind === 'json' ? jsonParser(raw) : raw;
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [raw];
+    }
+    catch {
+        return [raw];
+    }
+}
+function addFieldOptions(leaf, field, description) {
+    leaf.addOption(optionFor({ ...field, description }));
+    if (field.file) {
+        leaf.addOption(new Option(`--${field.flag}-file <path>`, `Read ${field.name} from a file, or - for stdin.`));
+    }
+    // Both spellings, so a field whose meaningful value is false (members
+    // --no-include-invitations) can be said; neither given leaves it unsent.
+    if (field.kind === 'boolean') {
+        leaf.addOption(new Option(`--no-${field.flag}`, `Send ${field.name} as false.`));
+    }
+}
+function addBodyOptions(leaf, operation) {
+    const takesBody = operation.body !== null || operation.multipart !== null;
+    if (takesBody) {
+        leaf.option('--body <json>', 'The whole request body as JSON; overrides field flags.');
+        leaf.option('--body-file <path>', 'Read the whole request body from a file, or - for stdin.');
+    }
+    if (operation.attachments) {
+        leaf.option('--attach <path>', 'Attach a file; repeat for several. Sends the request as multipart.', collect, []);
+    }
+}
+/** A group created here is hidden when asked; one that already exists keeps what it is. */
+export function groupFor(root, path, { hidden = false } = {}) {
     let current = root;
     for (const segment of path) {
         const existing = current.commands.find((command) => command.name() === segment);
-        current = existing ?? current.command(segment).description(`${humanize(segment)} commands`);
+        current =
+            existing ?? current.command(segment, { hidden }).description(`${humanize(segment)} commands`);
     }
     return current;
 }
+/** A hand-written command's leaf at its listed path, its groups made as `groupFor` makes them. */
+export function leafAt(root, command) {
+    return groupFor(root, command.slice(0, -1)).command(command[command.length - 1]);
+}
 function optionFor(field) {
     const description = field.description ?? '';
     if (field.repeated)
@@ -127,6 +345,48 @@ function numberParser(field) {
         return value;
     };
 }
+/**
+ * A value given twice is ambiguous: `--x` and `--x-file` together, or stdin (`-`) named by two
+ * file flags, which only one of them could read.
+ */
+function checkFileFlags(options, fileFlags) {
+    for (const flag of fileFlags) {
+        if (options[optionKey(flag)] !== undefined &&
+            options[optionKey(`${flag}-file`)] !== undefined) {
+            throw new UsageError(`--${flag} and --${flag}-file are both given; give one.`);
+        }
+    }
+    const stdin = [...fileFlags.map((flag) => `${flag}-file`), 'body-file'].filter((flag) => options[optionKey(flag)] === '-');
+    if (stdin.length > 1) {
+        throw new UsageError(`${stdin.map((flag) => `--${flag}`).join(' and ')} both read stdin (-); only one can.`);
+    }
+}
+/**
+ * A field's value from `--<flag>-file`: the file's text, parsed as JSON for a nested field.
+ * Read at the call, so a large checklist or result never rides one shell argument.
+ */
+function fileValue(field, options) {
+    const path = field.file ? options[optionKey(`${field.flag}-file`)] : undefined;
+    if (typeof path !== 'string')
+        return undefined;
+    const text = readFieldFile(path);
+    if (field.kind !== 'json')
+        return text;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new UsageError(`--${field.flag}-file ${path} is not JSON.`);
+    }
+}
+function readFieldFile(path) {
+    try {
+        return path === '-' ? readFileSync(0, 'utf8') : readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new UsageError(`Could not read ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 function jsonParser(raw) {
     try {
         return JSON.parse(raw);
@@ -136,21 +396,7 @@ function jsonParser(raw) {
     }
 }
 function collect(value, previous) {
-    return [...previous, value];
-}
-/**
- * One option per flag. The generator gives the same wire name on the JSON and
- * the form branch one flag, and two wire names never one flag; this keys on
- * the flag because that is what commander refuses to register twice.
- */
-function dedupe(fields) {
-    const seen = new Set();
-    return fields.filter((field) => {
-        if (seen.has(field.flag))
-            return false;
-        seen.add(field.flag);
-        return true;
-    });
+    return [...(previous ?? []), value];
 }
 /** commander stores `--exclude-archived` as `excludeArchived`. */
 export function optionKey(flag) {

package/dist/runtime/former-commands.js

@@ -0,0 +1,89 @@
+import { FORMER_COMMANDS } from './aliases.js';
+import { attachLeaf } from './attach.js';
+import { PERSONAL, scopeOf } from './variants.js';
+/** Groups that forward to a live child, so a listing of what runs can leave them out. */
+const FORWARDERS = new WeakSet();
+export function isForwarder(command) {
+    return FORWARDERS.has(command);
+}
+/** `METHOD path`, the key an alias names an operation by. */
+export function operationKey(operation) {
+    return `${operation.method.toUpperCase()} ${operation.path}`;
+}
+/**
+ * Attaches every former name whose target this credential reaches: a hidden leaf where the
+ * old path is free, a forwarder where it is now a live group. Runs after every live command,
+ * so a forwarder finds its target.
+ */
+export function attachFormerCommands(root, operations, runtime, formerCommands = FORMER_COMMANDS) {
+    const byKey = new Map(operations.map((operation) => [operationKey(operation), operation]));
+    for (const former of formerCommands) {
+        const path = former.from.split(' ');
+        const existing = find(root, path);
+        if (former.operation) {
+            const operation = byKey.get(former.operation);
+            if (!operation)
+                continue;
+            if (existing) {
+                const target = find(root, operation.command);
+                if (!target)
+                    continue;
+                const { prefix, suffix } = formArguments(operation);
+                forward(existing, target, prefix, suffix);
+            }
+            else {
+                attachLeaf(root, path, operation, runtime, {
+                    hidden: true,
+                    ...(former.fixed ? { fixed: former.fixed } : {}),
+                    ...(former.formerFlags ? { formerFlags: former.formerFlags } : {}),
+                });
+            }
+        }
+        else if (former.handWritten) {
+            const target = find(root, former.handWritten.split(' '));
+            if (!target)
+                continue;
+            forward(existing ?? hiddenLeaf(root, path), target, [], []);
+        }
+    }
+}
+/** What reaches a form on its live command: `personal` first, a selector last. */
+function formArguments(operation) {
+    return {
+        prefix: scopeOf(operation) === 'personal' ? [PERSONAL] : [],
+        suffix: operation.variant?.when
+            ? [`--${operation.variant.when.flag}`, operation.variant.when.equals]
+            : [],
+    };
+}
+/**
+ * The old leaf's arguments, re-parsed by the live command. No options of its own, since
+ * commander reads an ancestor's options anywhere on the line and would take a child's flag.
+ */
+function forward(command, target, prefix, suffix) {
+    FORWARDERS.add(command);
+    command
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(async (...args) => {
+        const self = args[args.length - 1];
+        await target.parseAsync([...prefix, ...self.args, ...suffix], { from: 'user' });
+    });
+}
+function hiddenLeaf(root, path) {
+    let current = root;
+    for (const [index, segment] of path.entries()) {
+        const found = current.commands.find((command) => command.name() === segment);
+        current = found ?? current.command(segment, { hidden: true });
+        if (!found && index < path.length - 1)
+            current.description('');
+    }
+    return current;
+}
+function find(root, path) {
+    let current = root;
+    for (const segment of path) {
+        current = current?.commands.find((command) => command.name() === segment);
+    }
+    return current;
+}

package/dist/runtime/job-watch.js

@@ -2,7 +2,7 @@
  * Following one job's `/ws/jobs` stream to its end: the socket, the resume
  * cursor, the close codes and the status fallback, with everything that
  * touches the process or the network handed in, so each path is testable
- * without either. `kosuke sessions watch` is its one caller.
+ * without either. `kosuke sessions jobs watch` is its one caller.
  */
 export const JOB_TYPES = ['chat', 'deploy'];
 export const WATCH_EXIT = {