@ekanos/cli 0.1.0

package/dist/context.d.ts

@@ -0,0 +1,81 @@
+import { CliError } from './errors.js';
+import { type ExitCode } from './exit-codes.js';
+/**
+ * A single writable sink. Real streams satisfy this; tests pass a capturing
+ * buffer so the stdout-purity invariant can be asserted byte-for-byte.
+ */
+export interface WriteStream {
+    write(chunk: string): void;
+    isTTY?: boolean;
+}
+export interface ContextInput {
+    /**
+     * The user's EXPLICIT preference, already parsed: `true` for `--json`,
+     * `false` for `--no-json`, `undefined` when neither was passed. The
+     * undefined case is what allows the mode to be inferred instead.
+     */
+    jsonFlag?: boolean;
+    stdout?: WriteStream;
+    stderr?: WriteStream;
+    /** Overrides process.env for CLAUDECODE detection (tests). */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * The agent-native output envelope, resolved ONCE at startup and threaded
+ * through every command.
+ *
+ * The load-bearing invariant: in JSON mode, stdout receives EXACTLY ONE JSON
+ * object for the whole process — nothing else, ever. Every progress line, warn,
+ * and scrap of human prose goes to stderr. This is the single most common way
+ * an agent's tool call breaks (a stray log line on stdout makes the JSON
+ * unparseable), so the context enforces it structurally: `succeed`/`fail` are
+ * the only writers of stdout, and a `settled` latch makes a second call throw
+ * rather than emit a second object.
+ */
+export declare class CliContext {
+    readonly jsonMode: boolean;
+    private readonly stdout;
+    private readonly stderr;
+    private settled;
+    constructor(input?: ContextInput);
+    /** Human/progress output — ALWAYS stderr, so stdout stays pure in JSON mode. */
+    log(message: string): void;
+    /** A warning — stderr, no ANSI. */
+    warn(message: string): void;
+    /**
+     * Emit the `claude-code-hint` protocol line to STDERR. Used on --help and on
+     * an unknown command so an agent reading stderr is told what to do next
+     * without the line ever touching stdout.
+     */
+    emitClaudeCodeHint(payload: Record<string, unknown>): void;
+    /**
+     * Terminal success. Writes the single stdout object (JSON mode) or a concise
+     * human line (human mode). Returns the OK exit code so the caller can end the
+     * process with it. Idempotent-by-latch: a second settle throws.
+     */
+    succeed(data: unknown, humanSummary?: string): ExitCode;
+    /**
+     * Terminal failure. Writes the single stdout error object (JSON mode) or the
+     * message + hint to stderr (human mode). Returns the error's exit code.
+     *
+     * `error.hint` is guaranteed non-empty by CliError's constructor, so the
+     * envelope's "every error carries a hint" invariant holds for every path
+     * that reaches here.
+     */
+    fail(error: CliError, data?: unknown): ExitCode;
+    /**
+     * The low-level failure emitter. Used directly by `test`, whose exit code is
+     * a TRANSPARENT passthrough of the delegated runner's exit code (which is not
+     * one of the CLI's own frozen numeric conditions) and whose error `code` is
+     * an out-of-taxonomy string. Enforces the same non-empty-hint invariant as
+     * CliError so no failure path can emit an empty hint.
+     */
+    failWith(params: {
+        code: string;
+        message: string;
+        hint: string;
+        exitCode: number;
+        data?: unknown;
+    }): number;
+    private settle;
+}

package/dist/context.js

@@ -0,0 +1,125 @@
+import { EXIT_CODES } from './exit-codes.js';
+/**
+ * The agent-native output envelope, resolved ONCE at startup and threaded
+ * through every command.
+ *
+ * The load-bearing invariant: in JSON mode, stdout receives EXACTLY ONE JSON
+ * object for the whole process — nothing else, ever. Every progress line, warn,
+ * and scrap of human prose goes to stderr. This is the single most common way
+ * an agent's tool call breaks (a stray log line on stdout makes the JSON
+ * unparseable), so the context enforces it structurally: `succeed`/`fail` are
+ * the only writers of stdout, and a `settled` latch makes a second call throw
+ * rather than emit a second object.
+ */
+export class CliContext {
+    constructor(input = {}) {
+        var _a, _b, _c, _d;
+        this.settled = false;
+        const stdout = (_a = input.stdout) !== null && _a !== void 0 ? _a : defaultStream(process.stdout);
+        const stderr = (_b = input.stderr) !== null && _b !== void 0 ? _b : defaultStream(process.stderr);
+        const env = (_c = input.env) !== null && _c !== void 0 ? _c : process.env;
+        this.stdout = stdout;
+        this.stderr = stderr;
+        // Resolve JSON mode once. An EXPLICIT flag always wins: `--json` forces the
+        // envelope on even at a terminal, `--no-json` forces the human form even
+        // when piped. Only when the user expressed no preference is the mode
+        // inferred — from a non-TTY stdout (piped into another program or an agent)
+        // or the CLAUDECODE marker.
+        const nonTty = stdout.isTTY !== true;
+        this.jsonMode = (_d = input.jsonFlag) !== null && _d !== void 0 ? _d : (nonTty || env.CLAUDECODE === '1');
+    }
+    /** Human/progress output — ALWAYS stderr, so stdout stays pure in JSON mode. */
+    log(message) {
+        this.stderr.write(`${message}\n`);
+    }
+    /** A warning — stderr, no ANSI. */
+    warn(message) {
+        this.stderr.write(`${message}\n`);
+    }
+    /**
+     * Emit the `claude-code-hint` protocol line to STDERR. Used on --help and on
+     * an unknown command so an agent reading stderr is told what to do next
+     * without the line ever touching stdout.
+     */
+    emitClaudeCodeHint(payload) {
+        this.stderr.write(`claude-code-hint: ${JSON.stringify(payload)}\n`);
+    }
+    /**
+     * Terminal success. Writes the single stdout object (JSON mode) or a concise
+     * human line (human mode). Returns the OK exit code so the caller can end the
+     * process with it. Idempotent-by-latch: a second settle throws.
+     */
+    succeed(data, humanSummary) {
+        this.settle();
+        if (this.jsonMode) {
+            const envelope = { ok: true, data };
+            this.stdout.write(`${JSON.stringify(envelope)}\n`);
+        }
+        else {
+            this.stdout.write(`${humanSummary !== null && humanSummary !== void 0 ? humanSummary : 'OK'}\n`);
+        }
+        return EXIT_CODES.OK;
+    }
+    /**
+     * Terminal failure. Writes the single stdout error object (JSON mode) or the
+     * message + hint to stderr (human mode). Returns the error's exit code.
+     *
+     * `error.hint` is guaranteed non-empty by CliError's constructor, so the
+     * envelope's "every error carries a hint" invariant holds for every path
+     * that reaches here.
+     */
+    fail(error, data) {
+        this.failWith({
+            code: error.code,
+            message: error.message,
+            hint: error.hint,
+            exitCode: error.exitCode,
+            data,
+        });
+        return error.exitCode;
+    }
+    /**
+     * The low-level failure emitter. Used directly by `test`, whose exit code is
+     * a TRANSPARENT passthrough of the delegated runner's exit code (which is not
+     * one of the CLI's own frozen numeric conditions) and whose error `code` is
+     * an out-of-taxonomy string. Enforces the same non-empty-hint invariant as
+     * CliError so no failure path can emit an empty hint.
+     */
+    failWith(params) {
+        this.settle();
+        if (!params.hint || params.hint.trim().length === 0) {
+            throw new Error(`failWith for "${params.message}" was given an empty hint. Every CLI ` +
+                'error must carry an imperative remediation.');
+        }
+        if (this.jsonMode) {
+            const envelope = Object.assign(Object.assign({ ok: false }, (params.data !== undefined ? { data: params.data } : {})), { error: {
+                    code: params.code,
+                    message: params.message,
+                    hint: params.hint,
+                } });
+            this.stdout.write(`${JSON.stringify(envelope)}\n`);
+        }
+        else {
+            this.stderr.write(`Error: ${params.message}\n`);
+            this.stderr.write(`Hint: ${params.hint}\n`);
+        }
+        return params.exitCode;
+    }
+    settle() {
+        if (this.settled) {
+            throw new Error('CliContext settled twice — a command tried to emit a second ' +
+                'terminal result. In JSON mode this would corrupt stdout with two ' +
+                'objects. This is a bug in the command.');
+        }
+        this.settled = true;
+    }
+}
+function defaultStream(stream) {
+    return {
+        write: (chunk) => {
+            stream.write(chunk);
+        },
+        isTTY: stream.isTTY,
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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","sourcesContent":["import { CliError } from './errors';\nimport { EXIT_CODES, type ExitCode } from './exit-codes';\n\n/**\n * A single writable sink. Real streams satisfy this; tests pass a capturing\n * buffer so the stdout-purity invariant can be asserted byte-for-byte.\n */\nexport interface WriteStream {\n  write(chunk: string): void;\n  isTTY?: boolean;\n}\n\nexport interface ContextInput {\n  /**\n   * The user's EXPLICIT preference, already parsed: `true` for `--json`,\n   * `false` for `--no-json`, `undefined` when neither was passed. The\n   * undefined case is what allows the mode to be inferred instead.\n   */\n  jsonFlag?: boolean;\n  stdout?: WriteStream;\n  stderr?: WriteStream;\n  /** Overrides process.env for CLAUDECODE detection (tests). */\n  env?: Record<string, string | undefined>;\n}\n\n/** The success envelope. */\ninterface OkEnvelope {\n  ok: true;\n  data: unknown;\n}\n\n/** The error envelope. `data` is optional — validate carries its findings here. */\ninterface ErrEnvelope {\n  ok: false;\n  data?: unknown;\n  error: { code: string; message: string; hint: string };\n}\n\n/**\n * The agent-native output envelope, resolved ONCE at startup and threaded\n * through every command.\n *\n * The load-bearing invariant: in JSON mode, stdout receives EXACTLY ONE JSON\n * object for the whole process — nothing else, ever. Every progress line, warn,\n * and scrap of human prose goes to stderr. This is the single most common way\n * an agent's tool call breaks (a stray log line on stdout makes the JSON\n * unparseable), so the context enforces it structurally: `succeed`/`fail` are\n * the only writers of stdout, and a `settled` latch makes a second call throw\n * rather than emit a second object.\n */\nexport class CliContext {\n  readonly jsonMode: boolean;\n  private readonly stdout: WriteStream;\n  private readonly stderr: WriteStream;\n  private settled = false;\n\n  constructor(input: ContextInput = {}) {\n    const stdout = input.stdout ?? defaultStream(process.stdout);\n    const stderr = input.stderr ?? defaultStream(process.stderr);\n    const env = input.env ?? process.env;\n\n    this.stdout = stdout;\n    this.stderr = stderr;\n\n    // Resolve JSON mode once. An EXPLICIT flag always wins: `--json` forces the\n    // envelope on even at a terminal, `--no-json` forces the human form even\n    // when piped. Only when the user expressed no preference is the mode\n    // inferred — from a non-TTY stdout (piped into another program or an agent)\n    // or the CLAUDECODE marker.\n    const nonTty = stdout.isTTY !== true;\n    this.jsonMode = input.jsonFlag ?? (nonTty || env.CLAUDECODE === '1');\n  }\n\n  /** Human/progress output — ALWAYS stderr, so stdout stays pure in JSON mode. */\n  log(message: string): void {\n    this.stderr.write(`${message}\\n`);\n  }\n\n  /** A warning — stderr, no ANSI. */\n  warn(message: string): void {\n    this.stderr.write(`${message}\\n`);\n  }\n\n  /**\n   * Emit the `claude-code-hint` protocol line to STDERR. Used on --help and on\n   * an unknown command so an agent reading stderr is told what to do next\n   * without the line ever touching stdout.\n   */\n  emitClaudeCodeHint(payload: Record<string, unknown>): void {\n    this.stderr.write(`claude-code-hint: ${JSON.stringify(payload)}\\n`);\n  }\n\n  /**\n   * Terminal success. Writes the single stdout object (JSON mode) or a concise\n   * human line (human mode). Returns the OK exit code so the caller can end the\n   * process with it. Idempotent-by-latch: a second settle throws.\n   */\n  succeed(data: unknown, humanSummary?: string): ExitCode {\n    this.settle();\n    if (this.jsonMode) {\n      const envelope: OkEnvelope = { ok: true, data };\n      this.stdout.write(`${JSON.stringify(envelope)}\\n`);\n    } else {\n      this.stdout.write(`${humanSummary ?? 'OK'}\\n`);\n    }\n    return EXIT_CODES.OK;\n  }\n\n  /**\n   * Terminal failure. Writes the single stdout error object (JSON mode) or the\n   * message + hint to stderr (human mode). Returns the error's exit code.\n   *\n   * `error.hint` is guaranteed non-empty by CliError's constructor, so the\n   * envelope's \"every error carries a hint\" invariant holds for every path\n   * that reaches here.\n   */\n  fail(error: CliError, data?: unknown): ExitCode {\n    this.failWith({\n      code: error.code,\n      message: error.message,\n      hint: error.hint,\n      exitCode: error.exitCode,\n      data,\n    });\n    return error.exitCode;\n  }\n\n  /**\n   * The low-level failure emitter. Used directly by `test`, whose exit code is\n   * a TRANSPARENT passthrough of the delegated runner's exit code (which is not\n   * one of the CLI's own frozen numeric conditions) and whose error `code` is\n   * an out-of-taxonomy string. Enforces the same non-empty-hint invariant as\n   * CliError so no failure path can emit an empty hint.\n   */\n  failWith(params: {\n    code: string;\n    message: string;\n    hint: string;\n    exitCode: number;\n    data?: unknown;\n  }): number {\n    this.settle();\n    if (!params.hint || params.hint.trim().length === 0) {\n      throw new Error(\n        `failWith for \"${params.message}\" was given an empty hint. Every CLI ` +\n          'error must carry an imperative remediation.',\n      );\n    }\n    if (this.jsonMode) {\n      const envelope: ErrEnvelope = {\n        ok: false,\n        ...(params.data !== undefined ? { data: params.data } : {}),\n        error: {\n          code: params.code,\n          message: params.message,\n          hint: params.hint,\n        },\n      };\n      this.stdout.write(`${JSON.stringify(envelope)}\\n`);\n    } else {\n      this.stderr.write(`Error: ${params.message}\\n`);\n      this.stderr.write(`Hint: ${params.hint}\\n`);\n    }\n    return params.exitCode;\n  }\n\n  private settle(): void {\n    if (this.settled) {\n      throw new Error(\n        'CliContext settled twice — a command tried to emit a second ' +\n          'terminal result. In JSON mode this would corrupt stdout with two ' +\n          'objects. This is a bug in the command.',\n      );\n    }\n    this.settled = true;\n  }\n}\n\nfunction defaultStream(stream: NodeJS.WriteStream): WriteStream {\n  return {\n    write: (chunk: string) => {\n      stream.write(chunk);\n    },\n    isTTY: stream.isTTY,\n  };\n}\n"]}

package/dist/errors.d.ts

@@ -0,0 +1,41 @@
+import { type ErrorCode, type ExitCode } from './exit-codes.js';
+/**
+ * The one error type every command path throws. It carries the three things
+ * the envelope needs — a stable string `code`, a human `message`, and a
+ * non-empty imperative `hint` — plus the numeric `exitCode` the process ends
+ * with. Constructing one with an empty hint is a programming error and throws
+ * immediately, which is what lets `context.fail()` guarantee the envelope's
+ * "every error has a hint" invariant without a runtime check at the edge.
+ */
+export declare class CliError extends Error {
+    readonly code: ErrorCode;
+    readonly exitCode: ExitCode;
+    readonly hint: string;
+    constructor(params: {
+        code: ErrorCode;
+        exitCode: ExitCode;
+        message: string;
+        hint: string;
+    });
+}
+/** A usage error (unknown flag/command, bad argument). Exit 2. */
+export declare function usageError(message: string, hint: string): CliError;
+/** Validation produced error-severity findings. Exit 3. */
+export declare function validationError(message: string, hint: string): CliError;
+/** A precondition failure (missing tool, config, or file). Exit 9. */
+export declare function preconditionError(message: string, hint: string): CliError;
+/** An invalid-state failure (idempotency / ordering). Exit 7. */
+export declare function invalidStateError(message: string, hint: string): CliError;
+/** A not-found failure. Exit 6. */
+export declare function notFoundError(message: string, hint: string): CliError;
+/** Authentication is required but absent or expired. Exit 4. */
+export declare function authRequiredError(message: string, hint: string): CliError;
+/** Authenticated, but the server refused. Exit 5. */
+export declare function forbiddenError(message: string, hint: string): CliError;
+/** A network operation failed (DNS, TLS, timeout, 5xx). Exit 8. */
+export declare function networkError(message: string, hint: string): CliError;
+/**
+ * Coerce anything thrown into a CliError. A thrown CliError passes through; a
+ * plain Error becomes an INTERNAL (exit 1) with a generic-but-non-empty hint.
+ */
+export declare function toCliError(error: unknown): CliError;

package/dist/errors.js

@@ -0,0 +1,111 @@
+import { ERROR_CODES, EXIT_CODES, } from './exit-codes.js';
+/**
+ * The one error type every command path throws. It carries the three things
+ * the envelope needs — a stable string `code`, a human `message`, and a
+ * non-empty imperative `hint` — plus the numeric `exitCode` the process ends
+ * with. Constructing one with an empty hint is a programming error and throws
+ * immediately, which is what lets `context.fail()` guarantee the envelope's
+ * "every error has a hint" invariant without a runtime check at the edge.
+ */
+export class CliError extends Error {
+    constructor(params) {
+        super(params.message);
+        this.name = 'CliError';
+        if (!params.hint || params.hint.trim().length === 0) {
+            throw new Error(`CliError for "${params.message}" was constructed with an empty hint. ` +
+                'Every CLI error must carry an imperative remediation.');
+        }
+        this.code = params.code;
+        this.exitCode = params.exitCode;
+        this.hint = params.hint;
+    }
+}
+/** A usage error (unknown flag/command, bad argument). Exit 2. */
+export function usageError(message, hint) {
+    return new CliError({
+        code: ERROR_CODES.USAGE,
+        exitCode: EXIT_CODES.USAGE,
+        message,
+        hint,
+    });
+}
+/** Validation produced error-severity findings. Exit 3. */
+export function validationError(message, hint) {
+    return new CliError({
+        code: ERROR_CODES.VALIDATION,
+        exitCode: EXIT_CODES.VALIDATION,
+        message,
+        hint,
+    });
+}
+/** A precondition failure (missing tool, config, or file). Exit 9. */
+export function preconditionError(message, hint) {
+    return new CliError({
+        code: ERROR_CODES.PRECONDITION_FAILED,
+        exitCode: EXIT_CODES.PRECONDITION_FAILED,
+        message,
+        hint,
+    });
+}
+/** An invalid-state failure (idempotency / ordering). Exit 7. */
+export function invalidStateError(message, hint) {
+    return new CliError({
+        code: ERROR_CODES.INVALID_STATE,
+        exitCode: EXIT_CODES.INVALID_STATE,
+        message,
+        hint,
+    });
+}
+/** A not-found failure. Exit 6. */
+export function notFoundError(message, hint) {
+    return new CliError({
+        code: ERROR_CODES.NOT_FOUND,
+        exitCode: EXIT_CODES.NOT_FOUND,
+        message,
+        hint,
+    });
+}
+/** Authentication is required but absent or expired. Exit 4. */
+export function authRequiredError(message, hint) {
+    return new CliError({
+        code: ERROR_CODES.AUTH_REQUIRED,
+        exitCode: EXIT_CODES.AUTH_REQUIRED,
+        message,
+        hint,
+    });
+}
+/** Authenticated, but the server refused. Exit 5. */
+export function forbiddenError(message, hint) {
+    return new CliError({
+        code: ERROR_CODES.FORBIDDEN,
+        exitCode: EXIT_CODES.FORBIDDEN,
+        message,
+        hint,
+    });
+}
+/** A network operation failed (DNS, TLS, timeout, 5xx). Exit 8. */
+export function networkError(message, hint) {
+    return new CliError({
+        code: ERROR_CODES.NETWORK,
+        exitCode: EXIT_CODES.NETWORK,
+        message,
+        hint,
+    });
+}
+/**
+ * Coerce anything thrown into a CliError. A thrown CliError passes through; a
+ * plain Error becomes an INTERNAL (exit 1) with a generic-but-non-empty hint.
+ */
+export function toCliError(error) {
+    if (error instanceof CliError)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    return new CliError({
+        code: ERROR_CODES.INTERNAL,
+        exitCode: EXIT_CODES.INTERNAL,
+        message,
+        hint: 'This is an internal CLI error. Re-run with --json to capture the full ' +
+            'envelope and report it at npm@govastly.com if it persists.',
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  ERROR_CODES,\n  EXIT_CODES,\n  type ErrorCode,\n  type ExitCode,\n} from './exit-codes';\n\n/**\n * The one error type every command path throws. It carries the three things\n * the envelope needs — a stable string `code`, a human `message`, and a\n * non-empty imperative `hint` — plus the numeric `exitCode` the process ends\n * with. Constructing one with an empty hint is a programming error and throws\n * immediately, which is what lets `context.fail()` guarantee the envelope's\n * \"every error has a hint\" invariant without a runtime check at the edge.\n */\nexport class CliError extends Error {\n  readonly code: ErrorCode;\n  readonly exitCode: ExitCode;\n  readonly hint: string;\n\n  constructor(params: {\n    code: ErrorCode;\n    exitCode: ExitCode;\n    message: string;\n    hint: string;\n  }) {\n    super(params.message);\n    this.name = 'CliError';\n\n    if (!params.hint || params.hint.trim().length === 0) {\n      throw new Error(\n        `CliError for \"${params.message}\" was constructed with an empty hint. ` +\n          'Every CLI error must carry an imperative remediation.',\n      );\n    }\n\n    this.code = params.code;\n    this.exitCode = params.exitCode;\n    this.hint = params.hint;\n  }\n}\n\n/** A usage error (unknown flag/command, bad argument). Exit 2. */\nexport function usageError(message: string, hint: string): CliError {\n  return new CliError({\n    code: ERROR_CODES.USAGE,\n    exitCode: EXIT_CODES.USAGE,\n    message,\n    hint,\n  });\n}\n\n/** Validation produced error-severity findings. Exit 3. */\nexport function validationError(message: string, hint: string): CliError {\n  return new CliError({\n    code: ERROR_CODES.VALIDATION,\n    exitCode: EXIT_CODES.VALIDATION,\n    message,\n    hint,\n  });\n}\n\n/** A precondition failure (missing tool, config, or file). Exit 9. */\nexport function preconditionError(message: string, hint: string): CliError {\n  return new CliError({\n    code: ERROR_CODES.PRECONDITION_FAILED,\n    exitCode: EXIT_CODES.PRECONDITION_FAILED,\n    message,\n    hint,\n  });\n}\n\n/** An invalid-state failure (idempotency / ordering). Exit 7. */\nexport function invalidStateError(message: string, hint: string): CliError {\n  return new CliError({\n    code: ERROR_CODES.INVALID_STATE,\n    exitCode: EXIT_CODES.INVALID_STATE,\n    message,\n    hint,\n  });\n}\n\n/** A not-found failure. Exit 6. */\nexport function notFoundError(message: string, hint: string): CliError {\n  return new CliError({\n    code: ERROR_CODES.NOT_FOUND,\n    exitCode: EXIT_CODES.NOT_FOUND,\n    message,\n    hint,\n  });\n}\n\n/** Authentication is required but absent or expired. Exit 4. */\nexport function authRequiredError(message: string, hint: string): CliError {\n  return new CliError({\n    code: ERROR_CODES.AUTH_REQUIRED,\n    exitCode: EXIT_CODES.AUTH_REQUIRED,\n    message,\n    hint,\n  });\n}\n\n/** Authenticated, but the server refused. Exit 5. */\nexport function forbiddenError(message: string, hint: string): CliError {\n  return new CliError({\n    code: ERROR_CODES.FORBIDDEN,\n    exitCode: EXIT_CODES.FORBIDDEN,\n    message,\n    hint,\n  });\n}\n\n/** A network operation failed (DNS, TLS, timeout, 5xx). Exit 8. */\nexport function networkError(message: string, hint: string): CliError {\n  return new CliError({\n    code: ERROR_CODES.NETWORK,\n    exitCode: EXIT_CODES.NETWORK,\n    message,\n    hint,\n  });\n}\n\n/**\n * Coerce anything thrown into a CliError. A thrown CliError passes through; a\n * plain Error becomes an INTERNAL (exit 1) with a generic-but-non-empty hint.\n */\nexport function toCliError(error: unknown): CliError {\n  if (error instanceof CliError) return error;\n\n  const message = error instanceof Error ? error.message : String(error);\n  return new CliError({\n    code: ERROR_CODES.INTERNAL,\n    exitCode: EXIT_CODES.INTERNAL,\n    message,\n    hint:\n      'This is an internal CLI error. Re-run with --json to capture the full ' +\n      'envelope and report it at npm@govastly.com if it persists.',\n  });\n}\n"]}

package/dist/exit-codes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The frozen exit-code taxonomy. This is a PUBLIC CONTRACT: agents and CI
+ * branch on these numbers, so a value never changes meaning once shipped. New
+ * conditions get new numbers; they are never renumbered.
+ *
+ * This cut (init / validate / test) only ever emits 0, 1, 2, 3, and 9 — but
+ * the whole taxonomy is fixed here up front so later cuts (auth, publish, the
+ * remote gate) slot in without renumbering.
+ */
+export declare const EXIT_CODES: {
+    /** Success. */
+    readonly OK: 0;
+    /** An unexpected internal error — a bug in the CLI, not the user's input. */
+    readonly INTERNAL: 1;
+    /** Usage error: an unknown flag/command, a missing required argument. */
+    readonly USAGE: 2;
+    /** Validation produced error-severity findings (the definition is invalid). */
+    readonly VALIDATION: 3;
+    /** Authentication is required but absent. */
+    readonly AUTH_REQUIRED: 4;
+    /** Authenticated, but not permitted. */
+    readonly FORBIDDEN: 5;
+    /** A named resource (project, file, definition) was not found. */
+    readonly NOT_FOUND: 6;
+    /** The command cannot run in the current state (idempotency / ordering). */
+    readonly INVALID_STATE: 7;
+    /** A network operation failed. */
+    readonly NETWORK: 8;
+    /** A precondition failed (a required tool, config, or file is missing). */
+    readonly PRECONDITION_FAILED: 9;
+    /** A remote/publish gate rejected the submission. */
+    readonly GATE_FAILED: 10;
+};
+export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+/**
+ * Stable string codes carried in the JSON error envelope. Kept alongside the
+ * numeric exits so a machine reader can switch on a name without memorizing an
+ * integer. One code per numeric exit that this taxonomy can emit.
+ */
+export declare const ERROR_CODES: {
+    readonly INTERNAL: "internal";
+    readonly USAGE: "usage";
+    readonly VALIDATION: "validation";
+    readonly AUTH_REQUIRED: "auth_required";
+    readonly FORBIDDEN: "forbidden";
+    readonly NOT_FOUND: "not_found";
+    readonly INVALID_STATE: "invalid_state";
+    readonly NETWORK: "network";
+    readonly PRECONDITION_FAILED: "precondition_failed";
+    readonly GATE_FAILED: "gate_failed";
+};
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];

package/dist/exit-codes.js

@@ -0,0 +1,51 @@
+/**
+ * The frozen exit-code taxonomy. This is a PUBLIC CONTRACT: agents and CI
+ * branch on these numbers, so a value never changes meaning once shipped. New
+ * conditions get new numbers; they are never renumbered.
+ *
+ * This cut (init / validate / test) only ever emits 0, 1, 2, 3, and 9 — but
+ * the whole taxonomy is fixed here up front so later cuts (auth, publish, the
+ * remote gate) slot in without renumbering.
+ */
+export const EXIT_CODES = {
+    /** Success. */
+    OK: 0,
+    /** An unexpected internal error — a bug in the CLI, not the user's input. */
+    INTERNAL: 1,
+    /** Usage error: an unknown flag/command, a missing required argument. */
+    USAGE: 2,
+    /** Validation produced error-severity findings (the definition is invalid). */
+    VALIDATION: 3,
+    /** Authentication is required but absent. */
+    AUTH_REQUIRED: 4,
+    /** Authenticated, but not permitted. */
+    FORBIDDEN: 5,
+    /** A named resource (project, file, definition) was not found. */
+    NOT_FOUND: 6,
+    /** The command cannot run in the current state (idempotency / ordering). */
+    INVALID_STATE: 7,
+    /** A network operation failed. */
+    NETWORK: 8,
+    /** A precondition failed (a required tool, config, or file is missing). */
+    PRECONDITION_FAILED: 9,
+    /** A remote/publish gate rejected the submission. */
+    GATE_FAILED: 10,
+};
+/**
+ * Stable string codes carried in the JSON error envelope. Kept alongside the
+ * numeric exits so a machine reader can switch on a name without memorizing an
+ * integer. One code per numeric exit that this taxonomy can emit.
+ */
+export const ERROR_CODES = {
+    INTERNAL: 'internal',
+    USAGE: 'usage',
+    VALIDATION: 'validation',
+    AUTH_REQUIRED: 'auth_required',
+    FORBIDDEN: 'forbidden',
+    NOT_FOUND: 'not_found',
+    INVALID_STATE: 'invalid_state',
+    NETWORK: 'network',
+    PRECONDITION_FAILED: 'precondition_failed',
+    GATE_FAILED: 'gate_failed',
+};
+//# sourceMappingURL=exit-codes.js.map

package/dist/exit-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit-codes.js","sourceRoot":"","sources":["../src/exit-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,eAAe;IACf,EAAE,EAAE,CAAC;IACL,6EAA6E;IAC7E,QAAQ,EAAE,CAAC;IACX,yEAAyE;IACzE,KAAK,EAAE,CAAC;IACR,+EAA+E;IAC/E,UAAU,EAAE,CAAC;IACb,6CAA6C;IAC7C,aAAa,EAAE,CAAC;IAChB,wCAAwC;IACxC,SAAS,EAAE,CAAC;IACZ,kEAAkE;IAClE,SAAS,EAAE,CAAC;IACZ,4EAA4E;IAC5E,aAAa,EAAE,CAAC;IAChB,kCAAkC;IAClC,OAAO,EAAE,CAAC;IACV,2EAA2E;IAC3E,mBAAmB,EAAE,CAAC;IACtB,qDAAqD;IACrD,WAAW,EAAE,EAAE;CACP,CAAC;AAIX;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,UAAU,EAAE,YAAY;IACxB,aAAa,EAAE,eAAe;IAC9B,SAAS,EAAE,WAAW;IACtB,SAAS,EAAE,WAAW;IACtB,aAAa,EAAE,eAAe;IAC9B,OAAO,EAAE,SAAS;IAClB,mBAAmB,EAAE,qBAAqB;IAC1C,WAAW,EAAE,aAAa;CAClB,CAAC","sourcesContent":["/**\n * The frozen exit-code taxonomy. This is a PUBLIC CONTRACT: agents and CI\n * branch on these numbers, so a value never changes meaning once shipped. New\n * conditions get new numbers; they are never renumbered.\n *\n * This cut (init / validate / test) only ever emits 0, 1, 2, 3, and 9 — but\n * the whole taxonomy is fixed here up front so later cuts (auth, publish, the\n * remote gate) slot in without renumbering.\n */\nexport const EXIT_CODES = {\n  /** Success. */\n  OK: 0,\n  /** An unexpected internal error — a bug in the CLI, not the user's input. */\n  INTERNAL: 1,\n  /** Usage error: an unknown flag/command, a missing required argument. */\n  USAGE: 2,\n  /** Validation produced error-severity findings (the definition is invalid). */\n  VALIDATION: 3,\n  /** Authentication is required but absent. */\n  AUTH_REQUIRED: 4,\n  /** Authenticated, but not permitted. */\n  FORBIDDEN: 5,\n  /** A named resource (project, file, definition) was not found. */\n  NOT_FOUND: 6,\n  /** The command cannot run in the current state (idempotency / ordering). */\n  INVALID_STATE: 7,\n  /** A network operation failed. */\n  NETWORK: 8,\n  /** A precondition failed (a required tool, config, or file is missing). */\n  PRECONDITION_FAILED: 9,\n  /** A remote/publish gate rejected the submission. */\n  GATE_FAILED: 10,\n} as const;\n\nexport type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];\n\n/**\n * Stable string codes carried in the JSON error envelope. Kept alongside the\n * numeric exits so a machine reader can switch on a name without memorizing an\n * integer. One code per numeric exit that this taxonomy can emit.\n */\nexport const ERROR_CODES = {\n  INTERNAL: 'internal',\n  USAGE: 'usage',\n  VALIDATION: 'validation',\n  AUTH_REQUIRED: 'auth_required',\n  FORBIDDEN: 'forbidden',\n  NOT_FOUND: 'not_found',\n  INVALID_STATE: 'invalid_state',\n  NETWORK: 'network',\n  PRECONDITION_FAILED: 'precondition_failed',\n  GATE_FAILED: 'gate_failed',\n} as const;\n\nexport type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];\n"]}