@cogitator-ai/cli 0.5.20 → 0.6.1

package/dist/index.js

@@ -2,47 +2,14 @@
 /**
  * Cogitator CLI
  */
-import { Command } from 'commander';
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { initCommand } from './commands/init.js';
-import { upCommand, downCommand } from './commands/up.js';
-import { runCommand } from './commands/run.js';
-import { statusCommand } from './commands/status.js';
-import { logsCommand } from './commands/logs.js';
-import { modelsCommand } from './commands/models.js';
-import { deployCommand } from './commands/deploy.js';
-import { assistantCommand } from './commands/assistant.js';
-import { buildCommand } from './commands/build.js';
-import { daemonCommand } from './commands/daemon.js';
-import { skillCommand } from './commands/skill.js';
-import { wizardCommand } from './commands/wizard.js';
-import { log } from './utils/logger.js';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
-const program = new Command()
-    .name('cogitator')
-    .description('Cogitator AI Agent Runtime CLI')
-    .version(pkg.version);
-program.addCommand(initCommand);
-program.addCommand(upCommand);
-program.addCommand(downCommand);
-program.addCommand(runCommand);
-program.addCommand(statusCommand);
-program.addCommand(logsCommand);
-program.addCommand(modelsCommand);
-program.addCommand(deployCommand);
-program.addCommand(assistantCommand);
-program.addCommand(buildCommand);
-program.addCommand(daemonCommand);
-program.addCommand(skillCommand);
-program.addCommand(wizardCommand);
-program.parseAsync().catch((error) => {
-    log.error(error instanceof Error ? error.message : String(error));
-    if (process.env.COGITATOR_DEBUG && error instanceof Error && error.stack) {
-        console.error(error.stack);
-    }
-    process.exit(1);
+import { CommanderError } from 'commander';
+import { createProgram } from './program.js';
+import { exitCodeOf, reportFailure } from './utils/cli.js';
+createProgram()
+    .parseAsync()
+    .catch((error) => {
+    if (error instanceof CommanderError)
+        process.exit(exitCodeOf(error));
+    process.exit(reportFailure(error, { json: process.argv.includes('--json') }));
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAExC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CAE/E,CAAC;AAEF,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE;KAC1B,IAAI,CAAC,WAAW,CAAC;KACjB,WAAW,CAAC,gCAAgC,CAAC;KAC7C,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAExB,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AAC9B,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;AACrC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAElC,OAAO,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC5C,GAAG,CAAC,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAClE,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QACzE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;GAEG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE3D,aAAa,EAAE;KACZ,UAAU,EAAE;KACZ,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IACxB,IAAI,KAAK,YAAY,cAAc;QAAE,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IACrE,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;AAChF,CAAC,CAAC,CAAC"}

package/dist/program.d.ts

@@ -0,0 +1,4 @@
+import { Command } from 'commander';
+/** The `cogitator` command with every subcommand. */
+export declare function createProgram(): Command;
+//# sourceMappingURL=program.d.ts.map

package/dist/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAiCpC,qDAAqD;AACrD,wBAAgB,aAAa,IAAI,OAAO,CA6BvC"}

package/dist/program.js

@@ -0,0 +1,61 @@
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { initCommand } from './commands/init.js';
+import { addCommand } from './commands/add.js';
+import { mcpCommand } from './commands/mcp.js';
+import { devCommand } from './commands/dev.js';
+import { doctorCommand } from './commands/doctor.js';
+import { evalCommand } from './commands/eval.js';
+import { upCommand, downCommand } from './commands/up.js';
+import { runCommand } from './commands/run.js';
+import { statusCommand } from './commands/status.js';
+import { logsCommand } from './commands/logs.js';
+import { modelsCommand } from './commands/models.js';
+import { deployCommand } from './commands/deploy.js';
+import { assistantCommand } from './commands/assistant.js';
+import { buildCommand } from './commands/build.js';
+import { daemonCommand } from './commands/daemon.js';
+import { skillCommand } from './commands/skill.js';
+import { wizardCommand } from './commands/wizard.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
+/** Commander errors reach the entry point from every command, so they exit with the same codes. */
+function configure(command) {
+    command.showSuggestionAfterError().exitOverride();
+    for (const sub of command.commands)
+        configure(sub);
+}
+/** The `cogitator` command with every subcommand. */
+export function createProgram() {
+    const program = new Command()
+        .name('cogitator')
+        .description('Cogitator AI Agent Runtime CLI')
+        .version(pkg.version);
+    for (const command of [
+        initCommand,
+        addCommand,
+        devCommand,
+        doctorCommand,
+        evalCommand,
+        mcpCommand,
+        upCommand,
+        downCommand,
+        runCommand,
+        statusCommand,
+        logsCommand,
+        modelsCommand,
+        deployCommand,
+        assistantCommand,
+        buildCommand,
+        daemonCommand,
+        skillCommand,
+        wizardCommand,
+    ]) {
+        program.addCommand(command);
+    }
+    configure(program);
+    return program;
+}
+//# sourceMappingURL=program.js.map

package/dist/program.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.js","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CAE/E,CAAC;AAEF,mGAAmG;AACnG,SAAS,SAAS,CAAC,OAAgB;IACjC,OAAO,CAAC,wBAAwB,EAAE,CAAC,YAAY,EAAE,CAAC;IAClD,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,QAAQ;QAAE,SAAS,CAAC,GAAG,CAAC,CAAC;AACrD,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE;SAC1B,IAAI,CAAC,WAAW,CAAC;SACjB,WAAW,CAAC,gCAAgC,CAAC;SAC7C,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACxB,KAAK,MAAM,OAAO,IAAI;QACpB,WAAW;QACX,UAAU;QACV,UAAU;QACV,aAAa;QACb,WAAW;QACX,UAAU;QACV,SAAS;QACT,WAAW;QACX,UAAU;QACV,aAAa;QACb,WAAW;QACX,aAAa;QACb,aAAa;QACb,gBAAgB;QAChB,YAAY;QACZ,aAAa;QACb,YAAY;QACZ,aAAa;KACd,EAAE,CAAC;QACF,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IACD,SAAS,CAAC,OAAO,CAAC,CAAC;IACnB,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/utils/add.d.ts

@@ -0,0 +1,81 @@
+import { type AddChanges, type AddPlan, type AddResult } from 'create-cogitator-app';
+export interface AddFlags {
+    memory?: string;
+    vectorStore?: string;
+    deploy?: string;
+    channel?: string[];
+    agent?: string[];
+}
+/** The addition the command line asks for, validated against the scaffolder's catalogs. */
+export declare function addChangesFrom(features: readonly string[], flags: AddFlags): AddChanges;
+/** A unified diff with additions in green, removals in red and hunk headers dimmed. */
+export declare function colorDiff(diff: string): string;
+/** What the addition does, for the terminal; with `diffs`, every file change in full. */
+export declare function formatAddPlan(plan: AddPlan, options: {
+    diffs: boolean;
+}): string;
+/** Why the addition was refused, with the change each conflicting file needs. */
+export declare function formatConflicts(plan: AddPlan): string;
+/** The plan as `--json` prints it: no file contents, diffs included. */
+export declare function addPlanJson(plan: AddPlan, result?: Pick<AddResult, 'written' | 'deleted' | 'install' | 'format'>): {
+    written?: string[] | undefined;
+    deleted?: string[] | undefined;
+    install?: {
+        status: "done";
+    } | {
+        status: "skipped";
+        reason: string;
+    } | {
+        status: string;
+        error: string;
+    } | undefined;
+    format?: {
+        status: "done";
+    } | {
+        status: "skipped";
+        reason: string;
+    } | {
+        status: string;
+        error: string;
+    } | undefined;
+    ok: boolean;
+    upToDate: boolean;
+    added: string[];
+    spec: {
+        name: string;
+        app: "server" | "channels" | "script" | "next" | "worker";
+        channels: ("telegram" | "discord" | "slack" | "webchat")[];
+        memory: "memory" | "sqlite" | "postgres" | "none" | "redis" | "mongodb";
+        vectorStore: "memory" | "postgres" | "qdrant";
+        features: ("harness" | "mcp" | "rag" | "workflows" | "durable" | "swarms" | "evals" | "otel" | "langfuse" | "voice" | "sandbox" | "a2a")[];
+        provider: "anthropic" | "openai" | "google" | "ollama";
+        model: string;
+        deploy: "none" | "docker" | "fly";
+        compose: boolean;
+        packageManager: "pnpm" | "npm" | "yarn" | "bun";
+        codingAgents: ("claude" | "cursor" | "codex")[];
+        preset?: string | undefined;
+        server?: "express" | "fastify" | "hono" | "koa" | "tetsu" | undefined;
+    };
+    command: string;
+    changes: {
+        path: string;
+        kind: "create" | "update" | "delete";
+        source: "generated" | "merged";
+        diff: string;
+    }[];
+    conflicts: import("create-cogitator-app").AddConflict[];
+    notes: import("create-cogitator-app").AddNote[];
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    removedDependencies: string[];
+    env: {
+        name: string;
+        required: boolean;
+        secret: boolean;
+        description: string;
+    }[];
+    services: string[];
+    warnings: string[];
+};
+//# sourceMappingURL=add.d.ts.map

package/dist/utils/add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/utils/add.ts"],"names":[],"mappings":"AACA,OAAO,EAQL,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,SAAS,EAEf,MAAM,sBAAsB,CAAC;AAG9B,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAmBD,2FAA2F;AAC3F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,QAAQ,GAAG,UAAU,CAwBvF;AAED,uFAAuF;AACvF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAW9C;AAYD,yFAAyF;AACzF,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAkDhF;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAarD;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CACzB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BvE"}

package/dist/utils/add.js

@@ -0,0 +1,151 @@
+import chalk from 'chalk';
+import { CHANNELS, CODING_AGENTS, closest, DEPLOY_TARGETS, FEATURES, MEMORIES, VECTOR_STORES, } from 'create-cogitator-app';
+import { UsageError } from './cli.js';
+function oneOf(what, value, allowed) {
+    const found = allowed.find((candidate) => candidate === value);
+    if (found)
+        return found;
+    const match = closest(value, allowed);
+    throw new UsageError(`Unknown ${what} "${value}".${match ? ` Did you mean "${match}"?` : ''} Use one of: ${allowed.join(', ')}.`);
+}
+/** Values of a repeatable flag, which also takes comma-separated lists. */
+function listOf(values) {
+    return (values ?? [])
+        .flatMap((value) => value.split(','))
+        .map((value) => value.trim())
+        .filter(Boolean);
+}
+/** The addition the command line asks for, validated against the scaffolder's catalogs. */
+export function addChangesFrom(features, flags) {
+    const changes = {
+        features: listOf(features).map((feature) => oneOf('feature', feature, FEATURES)),
+        channels: listOf(flags.channel).map((channel) => oneOf('channel', channel, CHANNELS)),
+        codingAgents: listOf(flags.agent).map((agent) => oneOf('coding agent', agent, CODING_AGENTS)),
+        ...(flags.memory && { memory: oneOf('memory', flags.memory, MEMORIES) }),
+        ...(flags.vectorStore && {
+            vectorStore: oneOf('vector store', flags.vectorStore, VECTOR_STORES),
+        }),
+        ...(flags.deploy && { deploy: oneOf('deploy target', flags.deploy, DEPLOY_TARGETS) }),
+    };
+    const empty = !changes.features?.length &&
+        !changes.channels?.length &&
+        !changes.codingAgents?.length &&
+        !changes.memory &&
+        !changes.vectorStore &&
+        !changes.deploy;
+    if (empty) {
+        throw new UsageError(`Name what to add: a feature (${FEATURES.join(', ')}), or --memory, --vector-store, --deploy, --channel, --agent`);
+    }
+    return changes;
+}
+/** A unified diff with additions in green, removals in red and hunk headers dimmed. */
+export function colorDiff(diff) {
+    return diff
+        .split('\n')
+        .map((line) => {
+        if (line.startsWith('+++') || line.startsWith('---'))
+            return chalk.bold(line);
+        if (line.startsWith('@@'))
+            return chalk.cyan(line);
+        if (line.startsWith('+'))
+            return chalk.green(line);
+        if (line.startsWith('-'))
+            return chalk.red(line);
+        return line;
+    })
+        .join('\n');
+}
+const MARKS = {
+    create: chalk.green('+'),
+    update: chalk.yellow('~'),
+    delete: chalk.red('-'),
+};
+function indentList(items) {
+    return items.map((item) => `  ${item}`);
+}
+/** What the addition does, for the terminal; with `diffs`, every file change in full. */
+export function formatAddPlan(plan, options) {
+    const out = [];
+    if (plan.upToDate)
+        return chalk.green('The project already has everything asked for, nothing to do.');
+    out.push(chalk.bold(`Adding ${plan.summary.join(', ')}`), '');
+    if (plan.changes.length > 0) {
+        out.push(chalk.bold('Files'));
+        for (const change of plan.changes) {
+            const how = change.source === 'merged' ? chalk.dim(' (merged with your edits)') : '';
+            out.push(`  ${MARKS[change.kind]} ${change.path}${how}`);
+        }
+        out.push('');
+    }
+    const deps = Object.entries({ ...plan.dependencies, ...plan.devDependencies });
+    if (deps.length > 0 || plan.removedDependencies.length > 0) {
+        out.push(chalk.bold('Dependencies'), ...indentList([
+            ...deps.map(([name, range]) => `${chalk.green('+')} ${name} ${chalk.dim(range)}`),
+            ...plan.removedDependencies.map((name) => `${chalk.red('-')} ${name}`),
+        ]), '');
+    }
+    if (plan.env.length > 0) {
+        out.push(chalk.bold('Environment'), ...indentList(plan.env.map((variable) => `${variable.name}${variable.required ? chalk.yellow(' (required)') : ''} ${chalk.dim(variable.description)}`)), '');
+    }
+    if (plan.services.length > 0) {
+        out.push(chalk.bold('Services'), ...indentList(plan.services), '');
+    }
+    for (const note of plan.notes) {
+        out.push(chalk.dim(`note: ${note.path ? `${note.path} ` : ''}${note.message}`));
+        if (options.diffs && note.diff)
+            out.push(colorDiff(note.diff));
+    }
+    for (const warning of plan.warnings)
+        out.push(chalk.yellow(`warning: ${warning}`));
+    if (options.diffs) {
+        for (const change of plan.changes)
+            if (change.diff)
+                out.push('', colorDiff(change.diff.trimEnd()));
+    }
+    return out.join('\n').trimEnd();
+}
+/** Why the addition was refused, with the change each conflicting file needs. */
+export function formatConflicts(plan) {
+    return [
+        chalk.red(`cogitator add would overwrite your changes to ${plan.conflicts.length} file${plan.conflicts.length === 1 ? '' : 's'}, so nothing was written:`),
+        ...plan.conflicts.flatMap((conflict) => [
+            '',
+            `${chalk.bold(conflict.path)}: ${conflict.reason}`,
+            colorDiff(conflict.diff.trimEnd()),
+        ]),
+        '',
+        'Apply these changes by hand, or set your edits aside and restore the generated files, then run cogitator add again.',
+    ].join('\n');
+}
+/** The plan as `--json` prints it: no file contents, diffs included. */
+export function addPlanJson(plan, result) {
+    const step = (value) => value && (value.status === 'failed' ? { status: 'failed', error: value.error.message } : value);
+    return {
+        ok: plan.conflicts.length === 0,
+        upToDate: plan.upToDate,
+        added: plan.summary,
+        spec: plan.to,
+        command: plan.command,
+        changes: plan.changes.map(({ path, kind, source, diff }) => ({ path, kind, source, diff })),
+        conflicts: plan.conflicts,
+        notes: plan.notes,
+        dependencies: plan.dependencies,
+        devDependencies: plan.devDependencies,
+        removedDependencies: plan.removedDependencies,
+        env: plan.env.map(({ name, required, secret, description }) => ({
+            name,
+            required,
+            secret,
+            description,
+        })),
+        services: plan.services,
+        warnings: plan.warnings,
+        ...(result && {
+            written: result.written,
+            deleted: result.deleted,
+            install: step(result.install),
+            format: step(result.format),
+        }),
+    };
+}
+//# sourceMappingURL=add.js.map

package/dist/utils/add.js.map

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

package/dist/utils/cli.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Exit codes every command uses: 0 when it did what was asked, 1 when it
+ * could not (a failed check, a failed deploy, a missing service), 2 when
+ * the command line itself is wrong.
+ */
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly failed: 1;
+    readonly usage: 2;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/** A failure a command reports to the user, with what to do about it. */
+export declare class CommandError extends Error {
+    readonly exitCode: ExitCode;
+    readonly hints: string[];
+    constructor(message: string, options?: {
+        hints?: string[];
+        exitCode?: ExitCode;
+        cause?: unknown;
+    });
+}
+/** A command line that cannot work: an unknown value, a missing argument. Exits 2. */
+export declare class UsageError extends CommandError {
+    constructor(message: string, hints?: string[]);
+}
+export declare function errorMessage(error: unknown): string;
+/** Whether `COGITATOR_DEBUG` asks for stack traces. */
+export declare function debugEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** The exit code of any error a command ends with. */
+export declare function exitCodeOf(error: unknown): ExitCode;
+/**
+ * Prints how a command failed: as `{ ok: false, error }` on stdout with
+ * `--json`, otherwise as a message with its hints on stderr, with the stack
+ * when COGITATOR_DEBUG is set. Returns the exit code.
+ */
+export declare function reportFailure(error: unknown, options: {
+    json: boolean;
+    env?: NodeJS.ProcessEnv;
+}): ExitCode;
+/** The `Examples:` block of a command's help: each command with what it does. */
+export declare function examplesHelp(examples: ReadonlyArray<readonly [command: string, description: string]>): string;
+/** Prints `value` as the JSON a `--json` command answers with. */
+export declare function printJson(value: unknown): void;
+/**
+ * Ends the process with the failure, for code that cannot throw to the
+ * command: event handlers of child processes and signal handlers.
+ */
+export declare function exitWithFailure(error: unknown): never;
+//# sourceMappingURL=cli.d.ts.map

package/dist/utils/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/utils/cli.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,IAAI;;;;CAA0C,CAAC;AAC5D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,OAAO,IAAI,CAAC,CAAC;AAExD,yEAAyE;AACzE,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;gBAGvB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAO3E;AAED,sFAAsF;AACtF,qBAAa,UAAW,SAAQ,YAAY;gBAC9B,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,MAAM,EAAO;CAIlD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnD;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAG1E;AAaD,sDAAsD;AACtD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAOnD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,GAClD,QAAQ,CA4BV;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,aAAa,CAAC,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC,GACvE,MAAM,CASR;AAED,kEAAkE;AAClE,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE9C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAErD"}

package/dist/utils/cli.js

@@ -0,0 +1,106 @@
+import chalk from 'chalk';
+import { CommanderError } from 'commander';
+/**
+ * Exit codes every command uses: 0 when it did what was asked, 1 when it
+ * could not (a failed check, a failed deploy, a missing service), 2 when
+ * the command line itself is wrong.
+ */
+export const EXIT = { ok: 0, failed: 1, usage: 2 };
+/** A failure a command reports to the user, with what to do about it. */
+export class CommandError extends Error {
+    exitCode;
+    hints;
+    constructor(message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = 'CommandError';
+        this.exitCode = options.exitCode ?? EXIT.failed;
+        this.hints = options.hints ?? [];
+    }
+}
+/** A command line that cannot work: an unknown value, a missing argument. Exits 2. */
+export class UsageError extends CommandError {
+    constructor(message, hints = []) {
+        super(message, { hints, exitCode: EXIT.usage });
+        this.name = 'UsageError';
+    }
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Whether `COGITATOR_DEBUG` asks for stack traces. */
+export function debugEnabled(env = process.env) {
+    const value = env.COGITATOR_DEBUG?.trim().toLowerCase();
+    return value !== undefined && value !== '' && value !== '0' && value !== 'false';
+}
+const USAGE_CODES = new Set([
+    'commander.unknownOption',
+    'commander.unknownCommand',
+    'commander.missingArgument',
+    'commander.missingMandatoryOptionValue',
+    'commander.optionMissingArgument',
+    'commander.invalidArgument',
+    'commander.excessArguments',
+    'commander.conflictingOption',
+]);
+/** The exit code of any error a command ends with. */
+export function exitCodeOf(error) {
+    if (error instanceof CommandError)
+        return error.exitCode;
+    if (error instanceof CommanderError) {
+        if (error.exitCode === 0)
+            return EXIT.ok;
+        return USAGE_CODES.has(error.code) ? EXIT.usage : EXIT.failed;
+    }
+    return EXIT.failed;
+}
+/**
+ * Prints how a command failed: as `{ ok: false, error }` on stdout with
+ * `--json`, otherwise as a message with its hints on stderr, with the stack
+ * when COGITATOR_DEBUG is set. Returns the exit code.
+ */
+export function reportFailure(error, options) {
+    const code = exitCodeOf(error);
+    const hints = error instanceof CommandError ? error.hints : [];
+    if (options.json) {
+        console.log(JSON.stringify({
+            ok: false,
+            error: {
+                message: errorMessage(error),
+                exitCode: code,
+                ...(hints.length > 0 && { hints }),
+            },
+        }, null, 2));
+        return code;
+    }
+    console.error(chalk.red('✗'), errorMessage(error));
+    for (const hint of hints)
+        console.error(chalk.dim(`  ${hint}`));
+    if (debugEnabled(options.env) && error instanceof Error && error.stack) {
+        console.error(chalk.dim(error.stack));
+    }
+    else if (!(error instanceof CommandError)) {
+        console.error(chalk.dim('  Set COGITATOR_DEBUG=1 for the stack trace.'));
+    }
+    return code;
+}
+/** The `Examples:` block of a command's help: each command with what it does. */
+export function examplesHelp(examples) {
+    const width = Math.max(...examples.map(([command]) => command.length));
+    return [
+        '',
+        'Examples:',
+        ...examples.map(([command, description]) => `  $ ${command.padEnd(width)}  ${chalk.dim(description)}`),
+    ].join('\n');
+}
+/** Prints `value` as the JSON a `--json` command answers with. */
+export function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+/**
+ * Ends the process with the failure, for code that cannot throw to the
+ * command: event handlers of child processes and signal handlers.
+ */
+export function exitWithFailure(error) {
+    process.exit(reportFailure(error, { json: false }));
+}
+//# sourceMappingURL=cli.js.map

package/dist/utils/cli.js.map

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

package/dist/utils/docs.d.ts

@@ -0,0 +1,39 @@
+export interface DocsLocation {
+    dir: string;
+    version: string;
+}
+export interface DocEntry {
+    /** Path inside the docs, such as `core/agents.md`. */
+    path: string;
+    title: string;
+    description: string;
+    section: string;
+}
+export interface DocsIndex extends DocsLocation {
+    entries: DocEntry[];
+}
+export interface DocHit extends DocEntry {
+    /** The heading of the part of the page that matched best. */
+    heading?: string;
+    snippet: string;
+    score: number;
+}
+/**
+ * The docs bundled with the @cogitator-ai/core a project installed, falling
+ * back to the one the CLI itself depends on.
+ */
+export declare function locateDocs(projectDir: string): DocsLocation;
+/** The catalog of pages, read from the `index.md` the docs ship with. */
+export declare function loadDocsIndex(location: DocsLocation): DocsIndex;
+/** Reads a page; `path#heading` returns only that part of the page. */
+export declare function readDoc(index: DocsIndex, reference: string): string;
+/** The anchor GitHub and Fumadocs give a heading. */
+export declare function slugOf(heading: string): string;
+/**
+ * Pages that answer `query`, best first. Titles weigh most, then the page
+ * descriptions, headings and body text; every term has to appear somewhere on
+ * a page for it to count, so `approval tool` finds the approvals guide rather
+ * than every page that mentions tools.
+ */
+export declare function searchDocs(index: DocsIndex, query: string, limit?: number): DocHit[];
+//# sourceMappingURL=docs.d.ts.map

package/dist/utils/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../src/utils/docs.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAU,SAAQ,YAAY;IAC7C,OAAO,EAAE,QAAQ,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,MAAO,SAAQ,QAAQ;IACtC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAuBD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAkB3D;AAKD,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAe/D;AAED,uEAAuE;AACvE,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAWnE;AAED,qDAAqD;AACrD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAO9C;AA2ED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,MAAM,EAAE,CA0C/E"}