@credda/cli 0.1.5 → 1.0.0

package/dist/args.d.ts

@@ -0,0 +1,99 @@
+/**
+ * A small argument parser for the `credda` command surface.
+ *
+ * Hand-rolled deliberately: a dependency here would be a supply-chain risk
+ * taken on for string parsing. The surface has outgrown the "six commands and a
+ * dozen flags" this line used to claim -- it is 13 commands, 3 aliases and 27
+ * flags -- and the argument holds better at that size, not worse.
+ * The parser is spec-driven so `--help` is generated from the same data the
+ * parser validates against and cannot drift from it.
+ */
+export type FlagKind = 'boolean' | 'string' | 'number';
+export interface FlagSpec {
+    readonly kind: FlagKind;
+    readonly description: string;
+    /** Single-character alias, without the leading dash. */
+    readonly alias?: string;
+    /** Permitted values for a string flag. */
+    readonly choices?: readonly string[];
+    /** Placeholder shown in help, e.g. `<n>`. */
+    readonly valueName?: string;
+    /** Documented default, shown in help only. Never applied by the parser. */
+    readonly defaultNote?: string;
+}
+export interface CommandSpec {
+    readonly name: string;
+    readonly summary: string;
+    /**
+     * The argument portion of the usage line, without `credda ` or the command
+     * name. Both are composed from `name`, so an alias renders its own usage
+     * rather than the canonical command's.
+     */
+    readonly args: string;
+    readonly flags: Readonly<Record<string, FlagSpec>>;
+    /** Longer explanation appended to `credda <command> --help`. */
+    readonly details?: readonly string[];
+    /**
+     * The command this one is a spelling of. Parsing and help are unchanged; only
+     * dispatch resolves through it, so an alias cannot drift from its target.
+     */
+    readonly aliasOf?: string;
+}
+/** A user error: bad flag, missing value, unknown command. Never a bug. */
+export declare class UsageError extends Error {
+    /** The command whose usage should be printed, if one was identified. */
+    readonly command: string | null;
+    constructor(message: string, 
+    /** The command whose usage should be printed, if one was identified. */
+    command?: string | null);
+}
+export interface GlobalFlags {
+    readonly help: boolean;
+    readonly version: boolean;
+    readonly json: boolean;
+    readonly quiet: boolean;
+    readonly verbose: boolean;
+    readonly color: boolean;
+}
+export type FlagValue = string | number | boolean;
+export interface ParsedCommand {
+    readonly command: string | null;
+    readonly globals: GlobalFlags;
+    readonly flags: ReadonlyMap<string, FlagValue>;
+    readonly positionals: readonly string[];
+}
+/**
+ * A lookup that reads only what a table actually declares.
+ *
+ * `COMMANDS`, `GLOBAL_FLAGS` and each command's `flags` are plain object
+ * literals, so `table[name]` walks the prototype chain: every member of
+ * `Object.prototype` answers `!== undefined` and is accepted as a real command
+ * or flag.
+ *
+ * That is not theoretical. Against the shipped build:
+ *
+ *     credda investigate --constructor ./repo
+ *
+ * was accepted, and the flag SWALLOWED the next token as its value — so the
+ * repository path silently disappeared and the run began without it. The same
+ * argv with `--nope` correctly threw "Unknown flag". `credda toString` resolved
+ * as a command instead of "Unknown command", and `commandUsage('toString')`
+ * then threw a TypeError rather than printing usage.
+ *
+ * A CLI's whole contract is that it refuses what it does not understand. This
+ * makes the lookup answer for declared keys only.
+ */
+export declare function own<T>(table: Readonly<Record<string, T>>, name: string): T | undefined;
+export declare const GLOBAL_FLAGS: Readonly<Record<string, FlagSpec>>;
+/**
+ * Parses argv against a command table.
+ *
+ * `--` ends flag parsing; everything after it is positional. A bare `-` is a
+ * positional (it means stdin to `credda investigate`), not a flag.
+ */
+export declare function parseArgs(argv: readonly string[], commands: Readonly<Record<string, CommandSpec>>): ParsedCommand;
+/** Reads a string flag, or null when absent. */
+export declare function stringFlag(parsed: ParsedCommand, name: string): string | null;
+/** Reads a number flag, or null when absent. */
+export declare function numberFlag(parsed: ParsedCommand, name: string): number | null;
+export declare function boolFlag(parsed: ParsedCommand, name: string): boolean;

package/dist/args.js

@@ -0,0 +1,222 @@
+/**
+ * A small argument parser for the `credda` command surface.
+ *
+ * Hand-rolled deliberately: a dependency here would be a supply-chain risk
+ * taken on for string parsing. The surface has outgrown the "six commands and a
+ * dozen flags" this line used to claim -- it is 13 commands, 3 aliases and 27
+ * flags -- and the argument holds better at that size, not worse.
+ * The parser is spec-driven so `--help` is generated from the same data the
+ * parser validates against and cannot drift from it.
+ */
+/** A user error: bad flag, missing value, unknown command. Never a bug. */
+export class UsageError extends Error {
+    command;
+    constructor(message, 
+    /** The command whose usage should be printed, if one was identified. */
+    command = null) {
+        super(message);
+        this.command = command;
+        this.name = 'UsageError';
+    }
+}
+/**
+ * A lookup that reads only what a table actually declares.
+ *
+ * `COMMANDS`, `GLOBAL_FLAGS` and each command's `flags` are plain object
+ * literals, so `table[name]` walks the prototype chain: every member of
+ * `Object.prototype` answers `!== undefined` and is accepted as a real command
+ * or flag.
+ *
+ * That is not theoretical. Against the shipped build:
+ *
+ *     credda investigate --constructor ./repo
+ *
+ * was accepted, and the flag SWALLOWED the next token as its value — so the
+ * repository path silently disappeared and the run began without it. The same
+ * argv with `--nope` correctly threw "Unknown flag". `credda toString` resolved
+ * as a command instead of "Unknown command", and `commandUsage('toString')`
+ * then threw a TypeError rather than printing usage.
+ *
+ * A CLI's whole contract is that it refuses what it does not understand. This
+ * makes the lookup answer for declared keys only.
+ */
+export function own(table, name) {
+    return Object.prototype.hasOwnProperty.call(table, name) ? table[name] : undefined;
+}
+export const GLOBAL_FLAGS = {
+    help: { kind: 'boolean', alias: 'h', description: 'Show help for the command and exit' },
+    version: { kind: 'boolean', description: 'Print the credda version and exit' },
+    json: { kind: 'boolean', description: 'Machine-readable JSONL on stdout; nothing else on stdout' },
+    quiet: { kind: 'boolean', description: 'Print only the final outcome line' },
+    verbose: { kind: 'boolean', description: 'Include debug-severity events' },
+    'no-color': { kind: 'boolean', description: 'Disable ANSI colour (also honoured: NO_COLOR)' },
+};
+/**
+ * Parses argv against a command table.
+ *
+ * `--` ends flag parsing; everything after it is positional. A bare `-` is a
+ * positional (it means stdin to `credda investigate`), not a flag.
+ */
+export function parseArgs(argv, commands) {
+    const globals = {
+        help: false,
+        version: false,
+        json: false,
+        quiet: false,
+        verbose: false,
+        'no-color': false,
+    };
+    const flags = new Map();
+    const positionals = [];
+    let command = null;
+    let spec = null;
+    let endOfFlags = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === undefined)
+            continue;
+        if (endOfFlags) {
+            positionals.push(token);
+            continue;
+        }
+        if (token === '--') {
+            endOfFlags = true;
+            continue;
+        }
+        if (token.startsWith('-') && token !== '-') {
+            const { name, inlineValue } = splitFlag(token);
+            const resolved = resolveFlag(name, spec, command);
+            if (resolved.kind === 'boolean') {
+                if (inlineValue !== null) {
+                    throw new UsageError(`The flag --${resolved.name} does not take a value.`, command);
+                }
+                if (resolved.global)
+                    globals[resolved.name] = true;
+                else
+                    flags.set(resolved.name, true);
+                continue;
+            }
+            let raw = inlineValue;
+            if (raw === null) {
+                const next = argv[i + 1];
+                // A negative number is a value, not a flag: `--since -2` must reach the
+                // command's own validation and produce its message, not "unknown flag".
+                const looksLikeFlag = next !== undefined &&
+                    next.startsWith('-') &&
+                    next !== '-' &&
+                    !(resolved.kind === 'number' && /^-\d/.test(next));
+                if (next === undefined || looksLikeFlag) {
+                    const placeholder = resolved.spec.valueName ?? `<${resolved.kind}>`;
+                    throw new UsageError(`The flag --${resolved.name} needs a value: --${resolved.name} ${placeholder}`, command);
+                }
+                raw = next;
+                i += 1;
+            }
+            flags.set(resolved.name, coerce(resolved.name, raw, resolved.spec, command));
+            continue;
+        }
+        if (command === null && positionals.length === 0) {
+            const found = own(commands, token);
+            if (found !== undefined) {
+                command = token;
+                spec = found;
+                continue;
+            }
+            // An unknown first word is an unknown command, not a positional.
+            throw new UsageError(`Unknown command '${token}'. Run 'credda --help' for the list of commands.`, null);
+        }
+        positionals.push(token);
+    }
+    return {
+        command,
+        globals: {
+            help: globals['help'] === true,
+            version: globals['version'] === true,
+            json: globals['json'] === true,
+            quiet: globals['quiet'] === true,
+            verbose: globals['verbose'] === true,
+            color: globals['no-color'] !== true,
+        },
+        flags,
+        positionals,
+    };
+}
+function splitFlag(token) {
+    const body = token.startsWith('--') ? token.slice(2) : token.slice(1);
+    const eq = body.indexOf('=');
+    if (eq === -1)
+        return { name: body, inlineValue: null };
+    return { name: body.slice(0, eq), inlineValue: body.slice(eq + 1) };
+}
+function resolveFlag(name, spec, command) {
+    const commandFlags = spec?.flags ?? {};
+    const direct = own(commandFlags, name);
+    if (direct !== undefined)
+        return { name, kind: direct.kind, spec: direct, global: false };
+    const globalSpec = own(GLOBAL_FLAGS, name);
+    if (globalSpec !== undefined)
+        return { name, kind: globalSpec.kind, spec: globalSpec, global: true };
+    for (const [key, candidate] of Object.entries(commandFlags)) {
+        if (candidate.alias === name)
+            return { name: key, kind: candidate.kind, spec: candidate, global: false };
+    }
+    for (const [key, candidate] of Object.entries(GLOBAL_FLAGS)) {
+        if (candidate.alias === name)
+            return { name: key, kind: candidate.kind, spec: candidate, global: true };
+    }
+    const known = [...Object.keys(commandFlags), ...Object.keys(GLOBAL_FLAGS)];
+    const suggestion = closest(name, known);
+    const where = command === null ? '' : ` for 'credda ${command}'`;
+    throw new UsageError(`Unknown flag '--${name}'${where}.${suggestion === null ? '' : ` Did you mean '--${suggestion}'?`}`, command);
+}
+function coerce(name, raw, spec, command) {
+    if (spec.kind === 'number') {
+        const value = Number(raw);
+        if (!Number.isFinite(value)) {
+            throw new UsageError(`The flag --${name} needs a number, but got '${raw}'.`, command);
+        }
+        return value;
+    }
+    if (spec.choices !== undefined && !spec.choices.includes(raw)) {
+        throw new UsageError(`Invalid value '${raw}' for --${name}. Expected one of: ${spec.choices.join(', ')}.`, command);
+    }
+    return raw;
+}
+/** Levenshtein-based suggestion, only offered when the edit distance is small. */
+function closest(input, candidates) {
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const distance = editDistance(input, candidate);
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    return bestDistance <= Math.max(1, Math.floor(input.length / 3)) ? best : null;
+}
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i, ...new Array(b.length).fill(0)];
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current[j] = Math.min((current[j - 1] ?? 0) + 1, (previous[j] ?? 0) + 1, (previous[j - 1] ?? 0) + cost);
+        }
+        previous = current;
+    }
+    return previous[b.length] ?? 0;
+}
+/** Reads a string flag, or null when absent. */
+export function stringFlag(parsed, name) {
+    const value = parsed.flags.get(name);
+    return typeof value === 'string' ? value : null;
+}
+/** Reads a number flag, or null when absent. */
+export function numberFlag(parsed, name) {
+    const value = parsed.flags.get(name);
+    return typeof value === 'number' ? value : null;
+}
+export function boolFlag(parsed, name) {
+    return parsed.flags.get(name) === true;
+}

package/dist/commands.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The command table. This is the single source of truth for what the CLI
+ * accepts: the parser validates against it and `--help` is rendered from it,
+ * so documented flags and accepted flags cannot drift apart.
+ *
+ * ## What this CLI claims, and what it does not
+ *
+ * A run prepares an environment, reproduces the reported failure, captures its
+ * signature as evidence, diagnoses a cause where the evidence supports one,
+ * writes the patch and proves it with a test that fails before and passes
+ * after. It ends at a diff for a person to review. **It proposes and never
+ * merges**, and nothing here takes write access to a repository to do it.
+ *
+ * **How far a run goes is decided by the provider, not by a flag.** The fix
+ * stage is on the investigation path (ADR 0019) and is entered only when the
+ * configured provider can author code. Under `CREDDA_PROVIDER=auto` with no
+ * key the engine degrades to rule-based reasoning and stops after the
+ * diagnosis, because a rule-based patch is worse than none. `PATCH_PATH_STATES`
+ * in `packages/shared/src/states.ts` carries that gate and the evidence behind
+ * it. There is deliberately no switch here that overrides it: a flag would put
+ * an unevidenced claim one environment variable away from a customer.
+ *
+ * Two consequences this file carries: the old command names keep working and
+ * stop describing an output (see {@link INVESTIGATE}), and exit code 3 is
+ * reserved rather than reused (see {@link RESERVED_EXIT_CODES}).
+ */
+import { type CommandSpec } from './args.js';
+/**
+ * Exit codes. Documented here, in `--help`, and in docs/cli.md.
+ *
+ * An investigation that abstains is a success: NO_CHANGE_REQUIRED and
+ * INCONCLUSIVE both exit 0. Every non-zero code an investigation can return is
+ * a genuine failure.
+ *
+ * `credda triage` is the one command with two successful codes, and the second of
+ * them is non-zero. It is not an investigation and has no Outcome: it executes
+ * nothing, so "did it reach a verdict" is not a question about it. What a caller
+ * needs from it is which of two correct answers it gave, and 0 is the silent
+ * one. See {@link EXIT.COMMENT_READY} for why that way round.
+ *
+ * The report record (ADR 0012) adds no code, and the omission is a decision. Its
+ * confidence class is the obvious candidate -- something like "8:
+ * NOT_ESTABLISHED", the next free number -- and it is the wrong thing to encode.
+ * `NOT_ESTABLISHED` is the *correct* class for an abstention, which is the
+ * outcome this table already insists is a success: code 0 covers it for an
+ * investigation and for triage alike, and it is the only one of these eight
+ * codes that does. Giving it a non-zero code
+ * would make every CI that treats non-zero as failure fail on exactly the runs
+ * Credda gets right, and would create a second, contradictory answer to a
+ * question `outcome` already answers. The confidence class is a property of the
+ * record, readable with `credda report <id> --json`, and the exit code stays a
+ * statement about whether the run reached a verdict.
+ *
+ * ## Code 3 was held open, and is returned again
+ *
+ * `PATCH_REJECTED` is the exit code of a run that produced a change and then
+ * threw it away. ADR 0015 stopped anything from producing changes and held the
+ * code open rather than renumbering the table; ADR 0019 put the fix stage back
+ * on the path, so runs return 3 again and it means exactly what the old scripts
+ * were written against. {@link RESERVED_EXIT_CODES} is empty as a result, and
+ * kept, because a test reads it and a code moving between reserved and returned
+ * should move its reason with it.
+ */
+export declare const EXIT: {
+    /** Success, including NO_CHANGE_REQUIRED and INCONCLUSIVE. */
+    readonly SUCCESS: 0;
+    /** Credda itself failed: internal error, unreadable database, crash. */
+    readonly INTERNAL_ERROR: 1;
+    /** The command line or its inputs were wrong. Nothing was run. */
+    readonly USAGE_ERROR: 2;
+    /** A change was produced and independent verification rejected it. */
+    readonly PATCH_REJECTED: 3;
+    /** The run was cancelled (Ctrl-C). */
+    readonly CANCELLED: 4;
+    /**
+     * NO_RUNNABLE_CHECK: nothing runnable could be derived from the report, so
+     * nothing was executed against the repository. Not a success and not a crash.
+     * See `exitCodeFor` for why it is neither 0 nor 1.
+     */
+    readonly NO_RUNNABLE_CHECK: 5;
+    /**
+     * `credda triage` produced a comment, and it is on stdout. Nothing failed.
+     *
+     * ## Why the comment is the non-zero side and silence is 0
+     *
+     * Silence is the common case, not the exceptional one: half of real inbound
+     * produces nothing worth saying (`bench/harvest`, 50.6% of 729 issues). A
+     * code that turned every second opened issue into a red job would be switched
+     * off inside a week, and this repository's standing rule is already that
+     * abstention is a success. So silence exits 0, and it is 0 for the same
+     * reason NO_CHANGE_REQUIRED is.
+     *
+     * That leaves the comment needing a code of its own, because "post this" and
+     * "post nothing" are the two answers a caller has to tell apart and stdout
+     * being empty is a weaker signal than a number. Giving it a non-zero one is
+     * deliberate rather than reluctant: **every way of misreading this code then
+     * fails towards not posting.** A shell under `set -e` stops before the
+     * posting step; a caller that ignores the code and pipes stdout gets an empty
+     * document on the silent path; a caller that tests for 0 posts only silence,
+     * which posts nothing. The failure this product cannot afford is a
+     * confidently wrong refusal on a stranger's issue -- the dominant rule is
+     * still wrong 8.7% of the times it fires (Credda-io/core#7) -- so the
+     * direction of every mistake here has to be silence.
+     *
+     * 6 rather than reusing 5: NO_RUNNABLE_CHECK is a statement that nothing was
+     * executed against the repository, which is true of *every* triage run by
+     * design, so the two would stop meaning different things.
+     */
+    readonly COMMENT_READY: 6;
+    /**
+     * `credda cancel` reached a run that is still executing and asked it to stop.
+     * The request is delivered; the run has not stopped yet.
+     *
+     * ## Why this is not 0, and not 4
+     *
+     * `apps/api/src/routes/investigations.ts` answers the same question with two
+     * different HTTP statuses -- 200 CANCELLED when the run is genuinely over, 202
+     * CANCELLATION_REQUESTED when a process is still inside it holding a sandbox
+     * and a model budget. A shell has no status line to read. It has this number,
+     * and if both answers were 0 then `credda cancel $id && echo stopped` would
+     * print "stopped" over a container that is still running and still spending.
+     * That is the one false claim this whole route was written to avoid, so the
+     * two answers get two codes.
+     *
+     * 4 is the run's own code, returned by `credda investigate` when the run it
+     * was executing was cancelled. It is a statement that a run ended. This is a
+     * statement that one was asked to, made by a different process that cannot
+     * see whether it did. Reusing 4 would collapse exactly the distinction.
+     *
+     * Every way of misreading 7 fails towards waiting rather than towards
+     * assuming: `set -e` stops, a test for 0 does not proceed. `credda events
+     * <id> --follow` is how a caller learns the run actually ended.
+     */
+    readonly CANCELLATION_REQUESTED: 7;
+};
+/**
+ * Codes no run of this version can return, and the reason each is held open.
+ *
+ * A test reads this, so a code cannot quietly move between "reserved" and
+ * "returned" without the reason moving with it.
+ */
+export declare const RESERVED_EXIT_CODES: Readonly<Record<number, string>>;
+export declare const EXIT_CODE_HELP: readonly string[];
+export declare const COMMANDS: Readonly<Record<string, CommandSpec>>;
+/**
+ * The command an alias dispatches to. Unknown names are returned unchanged so
+ * the caller's own "unknown command" path still owns that message.
+ */
+export declare function canonicalCommand(name: string): string;
+/** Alias name to the command it stands for, for the root usage. */
+export declare function aliases(): readonly (readonly [string, string])[];
+export declare function rootUsage(): string;
+export declare function commandUsage(name: string): string;