@cleocode/cleo 2026.4.158 → 2026.5.0

package/dist/cli/commands/schema.js

@@ -0,0 +1,177 @@
+/**
+ * CLI `schema` command — operation introspection for agents.
+ *
+ * Allows agents to inspect the full parameter signature and declared precondition
+ * gates for any CLEO operation before calling it, replacing trial-and-error.
+ *
+ * Usage:
+ *   cleo schema <domain.operation>
+ *   cleo schema tasks.add
+ *   cleo schema tasks.add --format human
+ *   cleo schema tasks.add --include-examples
+ *
+ * @task T340
+ * @epic T335
+ */
+import { describeOperation } from '@cleocode/lafs';
+import { defineCommand, showUsage } from 'citty';
+import { OPERATIONS } from '../../dispatch/registry.js';
+import { cliError, cliOutput } from '../renderers/index.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the target `OperationDef` from a `"domain.operation"` key.
+ *
+ * @param operationArg - The user-supplied string (e.g. `"tasks.add"`).
+ * @returns The matching `OperationDef`, or `null` if not found.
+ *
+ * @remarks
+ * The first dot separates domain from operation, so dotted operation names
+ * like `"complexity.estimate"` are handled correctly.
+ */
+function resolveOperationDef(operationArg) {
+    const dotIdx = operationArg.indexOf('.');
+    if (dotIdx === -1) {
+        // No domain separator — search all domains for unambiguous match
+        const matches = OPERATIONS.filter((op) => op.operation === operationArg);
+        if (matches.length === 1) {
+            return matches[0] ?? null;
+        }
+        return null;
+    }
+    const domain = operationArg.slice(0, dotIdx);
+    const operation = operationArg.slice(dotIdx + 1);
+    return OPERATIONS.find((op) => op.domain === domain && op.operation === operation) ?? null;
+}
+/**
+ * Format an `OperationSchema` as a human-readable summary table.
+ *
+ * @param schema - The operation schema to render.
+ * @returns Multi-line human-readable string.
+ */
+function renderSchemaHuman(schema) {
+    const lines = [];
+    lines.push(`Operation : ${schema.operation}`);
+    lines.push(`Gateway   : ${schema.gateway}`);
+    lines.push(`Description: ${schema.description}`);
+    lines.push('');
+    lines.push('Parameters:');
+    if (schema.params.length === 0) {
+        lines.push('  (none declared)');
+    }
+    else {
+        for (const p of schema.params) {
+            const req = p.required ? '[required]' : '[optional]';
+            const enumStr = p.enum ? `  enum: ${p.enum.join(' | ')}` : '';
+            let cliStr = '';
+            if (p.cli) {
+                const parts = [];
+                if (p.cli.positional)
+                    parts.push('positional');
+                if (p.cli.short)
+                    parts.push(`short: ${p.cli.short}`);
+                if (p.cli.flag)
+                    parts.push(`flag: --${p.cli.flag}`);
+                if (parts.length > 0)
+                    cliStr = `  cli: ${parts.join(', ')}`;
+            }
+            lines.push(`  ${p.name} (${p.type}) ${req}`);
+            lines.push(`    ${p.description}${enumStr}${cliStr}`);
+        }
+    }
+    if (schema.gates !== undefined) {
+        lines.push('');
+        lines.push('Gates:');
+        if (schema.gates.length === 0) {
+            lines.push('  (none declared — see note on static gate table)');
+        }
+        else {
+            for (const g of schema.gates) {
+                lines.push(`  ${g.name} → ${g.errorCode}`);
+                lines.push(`    ${g.description}`);
+                for (const t of g.triggers) {
+                    lines.push(`    - ${t}`);
+                }
+            }
+        }
+    }
+    if (schema.examples !== undefined && schema.examples.length > 0) {
+        lines.push('');
+        lines.push('Examples:');
+        for (const ex of schema.examples) {
+            lines.push(`  ${ex.command}`);
+            lines.push(`    ${ex.description}`);
+        }
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Command
+// ---------------------------------------------------------------------------
+/**
+ * Native citty command for `cleo schema <operation>`.
+ *
+ * Does NOT dispatch through the main dispatcher — schema introspection is
+ * pure metadata over the registry and does not require a live session or DB.
+ */
+export const schemaCommand = defineCommand({
+    meta: {
+        name: 'schema',
+        description: 'Introspect a CLEO operation: show params, types, enums, and declared gates',
+    },
+    args: {
+        operation: {
+            type: 'positional',
+            description: 'Operation key in domain.operation format (e.g. tasks.add)',
+            required: false,
+        },
+        format: {
+            type: 'string',
+            description: 'Output format: json (default) or human (pretty table)',
+            default: 'json',
+        },
+        'include-gates': {
+            type: 'boolean',
+            description: 'Include precondition gates in output (default: true)',
+            default: true,
+        },
+        'include-examples': {
+            type: 'boolean',
+            description: 'Include usage examples in output (default: false)',
+            default: false,
+        },
+    },
+    async run({ args, cmd }) {
+        if (!args.operation) {
+            await showUsage(cmd);
+            return;
+        }
+        const format = args.format ?? 'json';
+        const includeGates = args['include-gates'] !== false;
+        const includeExamples = args['include-examples'] === true;
+        const def = resolveOperationDef(args.operation);
+        if (def === null) {
+            cliError(`Unknown operation: "${args.operation}". Run \`cleo schema --list\` to see all operations.`, 4, {
+                name: 'E_NOT_FOUND',
+                fix: 'cleo schema --list',
+            });
+            process.exit(4);
+            return;
+        }
+        const schema = describeOperation(def, {
+            includeGates,
+            includeExamples,
+        });
+        if (format === 'human') {
+            console.log(renderSchemaHuman(schema));
+            return;
+        }
+        cliOutput(schema, {
+            command: 'schema',
+            operation: `schema.${args.operation}`,
+            message: `Schema for ${schema.operation}`,
+        });
+    },
+});
+//# sourceMappingURL=schema.js.map

package/dist/cli/commands/schema.js.map

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

package/dist/cli/commands/self-update.d.ts

@@ -0,0 +1,81 @@
+/**
+ * CLI `cleo self-update` command — upgrade the CLI BINARY itself via npm.
+ *
+ * Not to be confused with:
+ *   - `cleo update <taskId>` (see update.ts) — edit a task's fields
+ *   - `cleo upgrade` (see upgrade.ts) — repair current project's .cleo/ state
+ *
+ * Flow:
+ *   1. Check current installed version vs. npm registry / GitHub releases
+ *   2. If newer available, run `npm i -g @cleocode/cleo@<version>` (or equivalent)
+ *   3. After CLI upgrade, delegate to `runUpgrade()` for project-state repair
+ *      (same logic as `cleo upgrade`)
+ *
+ * Designed for LLM agents: structured JSON output, actionable fix commands.
+ *
+ * @task T4699
+ * @epic T4454
+ */
+/**
+ * Native citty command for `cleo self-update`.
+ *
+ * Global output flags (--json, --human, --quiet) are declared in args so
+ * citty parses them directly. This replaces the Commander.js optsWithGlobals()
+ * pattern that is unavailable in native citty commands.
+ */
+export declare const selfUpdateCommand: import("citty").CommandDef<{
+    readonly check: {
+        readonly type: "boolean";
+        readonly description: "Only check if update is available";
+    };
+    readonly status: {
+        readonly type: "boolean";
+        readonly description: "Show current vs latest version";
+    };
+    readonly version: {
+        readonly type: "string";
+        readonly description: "Update to specific version";
+    };
+    readonly channel: {
+        readonly type: "string";
+        readonly description: "Update channel: stable|beta";
+    };
+    readonly beta: {
+        readonly type: "boolean";
+        readonly description: "Shortcut for --channel beta";
+    };
+    readonly force: {
+        readonly type: "boolean";
+        readonly description: "Force update even if same version";
+    };
+    readonly 'post-update': {
+        readonly type: "boolean";
+        readonly description: "Run post-update diagnostics and migration only";
+    };
+    readonly 'no-auto-upgrade': {
+        readonly type: "boolean";
+        readonly description: "Skip automatic upgrade after update";
+    };
+    readonly 'auto-migrate': {
+        readonly type: "boolean";
+        readonly description: "Automatically migrate storage without prompting";
+    };
+    readonly 'check-projects': {
+        readonly type: "boolean";
+        readonly default: true;
+        readonly description: "Run cross-project health probe after upgrade (disable with --no-check-projects)";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output as JSON";
+    };
+    readonly human: {
+        readonly type: "boolean";
+        readonly description: "Force human-readable output";
+    };
+    readonly quiet: {
+        readonly type: "boolean";
+        readonly description: "Suppress non-essential output";
+    };
+}>;
+//# sourceMappingURL=self-update.d.ts.map

package/dist/cli/commands/self-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-update.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/self-update.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAiGH;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwP5B,CAAC"}