@kynetic-ai/spec 0.1.2 → 0.3.0

package/dist/cli/batch-context.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Batch execution context — minimal leaf module with zero kspec imports.
+ *
+ * Provides the batch-mode flag, exit interceptor, and output capture
+ * used by the batch execution engine. Kept dependency-free to avoid
+ * circular imports.
+ */
+/** Enable/disable batch mode. Only set during atomic batch execution. */
+export declare function setBatchMode(enabled: boolean): void;
+/** Check if we're inside a batch execution (atomic mode). */
+export declare function isBatchMode(): boolean;
+/**
+ * Thrown when process.exit() is called during batch dispatch.
+ * Caught by the batch executor to record the exit code as a failure.
+ */
+export declare class BatchExitError extends Error {
+    code: number;
+    constructor(code: number);
+}
+/**
+ * Override process.exit to throw BatchExitError instead.
+ * Must be paired with uninstallExitInterceptor() in a finally block.
+ */
+export declare function installExitInterceptor(): void;
+/** Restore the original process.exit. */
+export declare function uninstallExitInterceptor(): void;
+/**
+ * Captures console.log/error/warn output during a single command dispatch.
+ * Stores captured lines and restores originals on stop.
+ */
+export declare class OutputCapture {
+    private _lines;
+    private _origLog;
+    private _origError;
+    private _origWarn;
+    /** Start capturing console output. */
+    start(): void;
+    /** Stop capturing and restore console methods. */
+    stop(): void;
+    /** Get captured output as a single string. */
+    getOutput(): string;
+}
+//# sourceMappingURL=batch-context.d.ts.map

package/dist/cli/batch-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-context.d.ts","sourceRoot":"","sources":["../../src/cli/batch-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAEnD;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAID;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,IAAI,EAAE,MAAM,CAAC;gBACD,IAAI,EAAE,MAAM;CAKzB;AAID;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAM7C;AAED,yCAAyC;AACzC,wBAAgB,wBAAwB,IAAI,IAAI,CAK/C;AAID;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,UAAU,CAAqC;IACvD,OAAO,CAAC,SAAS,CAAoC;IAErD,sCAAsC;IACtC,KAAK,IAAI,IAAI;IAmBb,kDAAkD;IAClD,IAAI,IAAI,IAAI;IASZ,8CAA8C;IAC9C,SAAS,IAAI,MAAM;CAGpB"}

package/dist/cli/batch-context.js

@@ -0,0 +1,93 @@
+/**
+ * Batch execution context — minimal leaf module with zero kspec imports.
+ *
+ * Provides the batch-mode flag, exit interceptor, and output capture
+ * used by the batch execution engine. Kept dependency-free to avoid
+ * circular imports.
+ */
+// ── Batch Mode Flag ──────────────────────────────────────────────────
+let _batchMode = false;
+/** Enable/disable batch mode. Only set during atomic batch execution. */
+export function setBatchMode(enabled) {
+    _batchMode = enabled;
+}
+/** Check if we're inside a batch execution (atomic mode). */
+export function isBatchMode() {
+    return _batchMode;
+}
+// ── Exit Interceptor ─────────────────────────────────────────────────
+/**
+ * Thrown when process.exit() is called during batch dispatch.
+ * Caught by the batch executor to record the exit code as a failure.
+ */
+export class BatchExitError extends Error {
+    code;
+    constructor(code) {
+        super(`process.exit(${code}) called during batch execution`);
+        this.name = "BatchExitError";
+        this.code = code;
+    }
+}
+let _originalExit = null;
+/**
+ * Override process.exit to throw BatchExitError instead.
+ * Must be paired with uninstallExitInterceptor() in a finally block.
+ */
+export function installExitInterceptor() {
+    if (_originalExit)
+        return; // Already installed
+    _originalExit = process.exit;
+    process.exit = ((code) => {
+        throw new BatchExitError(code ?? 0);
+    });
+}
+/** Restore the original process.exit. */
+export function uninstallExitInterceptor() {
+    if (_originalExit) {
+        process.exit = _originalExit;
+        _originalExit = null;
+    }
+}
+// ── Output Capture ───────────────────────────────────────────────────
+/**
+ * Captures console.log/error/warn output during a single command dispatch.
+ * Stores captured lines and restores originals on stop.
+ */
+export class OutputCapture {
+    _lines = [];
+    _origLog = null;
+    _origError = null;
+    _origWarn = null;
+    /** Start capturing console output. */
+    start() {
+        this._lines = [];
+        this._origLog = console.log;
+        this._origError = console.error;
+        this._origWarn = console.warn;
+        const capture = (...args) => {
+            this._lines.push(args
+                .map((a) => (typeof a === "string" ? a : JSON.stringify(a)))
+                .join(" "));
+        };
+        console.log = capture;
+        console.error = capture;
+        console.warn = capture;
+    }
+    /** Stop capturing and restore console methods. */
+    stop() {
+        if (this._origLog)
+            console.log = this._origLog;
+        if (this._origError)
+            console.error = this._origError;
+        if (this._origWarn)
+            console.warn = this._origWarn;
+        this._origLog = null;
+        this._origError = null;
+        this._origWarn = null;
+    }
+    /** Get captured output as a single string. */
+    getOutput() {
+        return this._lines.join("\n");
+    }
+}
+//# sourceMappingURL=batch-context.js.map

package/dist/cli/batch-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-context.js","sourceRoot":"","sources":["../../src/cli/batch-context.ts"],"names":[],"mappings":"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"}

package/dist/cli/batch-exec.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Batch command parsing, validation, execution, and error reporting.
+ *
+ * Parses JSON batch input from stdin/file/inline, validates command paths
+ * against the CLI's introspection tree, executes in atomic or immediate
+ * mode, and produces helpful error messages.
+ */
+import type { Command } from "commander";
+import { type BatchCommand, type BatchExecResult, type BatchInput } from "../schema/batch.js";
+import type { CommandMeta } from "./introspection.js";
+export type BatchInputSource = {
+    type: "stdin";
+} | {
+    type: "file";
+    path: string;
+} | {
+    type: "inline";
+    json: string;
+};
+export declare class BatchParseError extends Error {
+    constructor(message: string);
+}
+export type BatchValidationErrorType = "unknown_command" | "missing_required" | "unknown_arg" | "rejected_command";
+export interface BatchValidationError {
+    /** Index in the batch array */
+    index: number;
+    /** Correlation ID if provided */
+    id?: string;
+    /** The command string from input */
+    command: string;
+    /** Error classification */
+    type: BatchValidationErrorType;
+    /** Human-readable error message */
+    message: string;
+    /** Suggested correction (e.g. closest command name) */
+    suggestion?: string;
+}
+export interface BatchValidationResult {
+    /** Whether all commands passed validation */
+    valid: boolean;
+    /** Validated commands (only present when valid) */
+    commands: BatchCommand[];
+    /** Validation errors */
+    errors: BatchValidationError[];
+}
+export interface ValidateBatchOptions {
+    /**
+     * Optional predicate to filter which commands are allowed.
+     * Extension point for allowed-commands task (@01KGR05NE).
+     * When provided, commands that don't pass the filter are rejected
+     * with a "rejected_command" error.
+     */
+    commandFilter?: (cmd: CommandMeta) => boolean;
+}
+/**
+ * Parse batch input from a source, returning validated commands.
+ *
+ * @throws {BatchParseError} on invalid JSON, empty array, or schema violations
+ */
+export declare function parseBatchInput(source: BatchInputSource): Promise<BatchInput>;
+/**
+ * Validate batch commands against the CLI's command tree.
+ *
+ * AC: @batch-command-schema ac-command-field — validates command paths
+ * AC: @batch-command-schema ac-args-mapping — validates arg names
+ * AC: @batch-command-schema ac-unknown-command — suggests similar commands
+ * AC: @batch-command-schema ac-missing-required — identifies missing args
+ * AC: @batch-command-schema ac-id-field — preserves id in errors
+ */
+export declare function validateBatchCommands(commands: BatchCommand[], program: CommandMeta, options?: ValidateBatchOptions): BatchValidationResult;
+/**
+ * Format validation errors for human or JSON output.
+ *
+ * @param result - Validation result containing errors
+ * @param json - If true, return JSON string; otherwise human-readable lines
+ * @returns Formatted error string
+ */
+export declare function reportBatchValidationErrors(result: BatchValidationResult, json?: boolean): string;
+export interface ExecuteBatchOptions {
+    /** Use atomic mode (default true) */
+    atomic: boolean;
+    /** Continue on error (implies immediate mode) */
+    continueOnError: boolean;
+    /** Validate-only mode */
+    dryRun: boolean;
+    /** JSON output */
+    json: boolean;
+}
+/**
+ * Build Commander argv from a BatchCommand and its CommandMeta.
+ *
+ * Translates { command: "inbox add", args: { content: "hello", tag: ["a","b"] } }
+ * into ["inbox", "add", "hello", "--tag", "a", "--tag", "b"]
+ *
+ * Positional args are emitted in Commander definition order (not JSON key order)
+ * to ensure correct argument mapping regardless of how the JSON was serialized.
+ */
+export declare function buildCommandArgv(cmd: BatchCommand, cmdMeta: CommandMeta): string[];
+/**
+ * Reset Commander command tree state between dispatches.
+ * Commander retains _optionValues between parseAsync calls.
+ */
+export declare function resetCommandTree(cmd: Command): void;
+/**
+ * Execute a batch of commands.
+ *
+ * AC: @batch-exec ac-default-atomic — atomic mode by default
+ * AC: @batch-exec ac-no-atomic-flag — immediate mode with --no-atomic
+ * AC: @batch-exec ac-stop-on-error — stop on first failure (default)
+ * AC: @batch-exec ac-continue — continue on error with --continue
+ * AC: @batch-exec ac-dry-run — validate without executing
+ * AC: @batch-exec ac-prevalidate — validation before any execution
+ * AC: @batch-exec ac-confirmation-suppressed — auto-append --force
+ */
+export declare function executeBatch(commands: BatchCommand[], program: Command, options: ExecuteBatchOptions): Promise<BatchExecResult>;
+//# sourceMappingURL=batch-exec.d.ts.map

package/dist/cli/batch-exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-exec.d.ts","sourceRoot":"","sources":["../../src/cli/batch-exec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAEzD,OAAO,EAEL,KAAK,YAAY,EAGjB,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAgBtD,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAIrC,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,MAAM,wBAAwB,GAChC,iBAAiB,GACjB,kBAAkB,GAClB,aAAa,GACb,kBAAkB,CAAC;AAEvB,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,IAAI,EAAE,wBAAwB,CAAC;IAC/B,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,KAAK,EAAE,OAAO,CAAC;IACf,mDAAmD;IACnD,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,wBAAwB;IACxB,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC;CAC/C;AAmCD;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,UAAU,CAAC,CA4BrB;AAkED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,oBAAoB,GAC7B,qBAAqB,CAkHvB;AAID;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,qBAAqB,EAC7B,IAAI,GAAE,OAAe,GACpB,MAAM,CA6BR;AAID,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,MAAM,EAAE,OAAO,CAAC;IAChB,iDAAiD;IACjD,eAAe,EAAE,OAAO,CAAC;IACzB,yBAAyB;IACzB,MAAM,EAAE,OAAO,CAAC;IAChB,kBAAkB;IAClB,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,EAAE,CA8DlF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAOnD;AAYD;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,eAAe,CAAC,CAmD1B"}