@cleocode/cleo 2026.4.158 → 2026.5.0

package/dist/cli/commands/add-batch.js

@@ -0,0 +1,148 @@
+/**
+ * CLI add-batch command — atomic batch creation of multiple tasks.
+ *
+ * Reads a JSON array of task definitions from a file or stdin and creates
+ * them atomically. More reliable than N sequential `cleo add` calls during
+ * epic decomposition.
+ *
+ * @task T090
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { defineCommand } from 'citty';
+import { dispatchRaw } from '../../dispatch/adapters/cli.js';
+import { cliError, cliOutput } from '../renderers/index.js';
+/**
+ * Native citty command for atomic batch creation of multiple tasks.
+ *
+ * Reads a JSON array of task definitions from a file or stdin and dispatches
+ * each as a `tasks.add` mutation. Partial failures are reported with a
+ * non-zero exit code while still reporting successful creations.
+ *
+ * @task T090
+ */
+export const addBatchCommand = defineCommand({
+    meta: { name: 'add-batch', description: 'Create multiple tasks atomically from a JSON file' },
+    args: {
+        file: {
+            type: 'string',
+            description: 'Path to JSON file (array of task objects). Use - for stdin.',
+        },
+        parent: {
+            type: 'string',
+            description: 'Default parent for all tasks (overridden by per-task parent)',
+        },
+        'dry-run': {
+            type: 'boolean',
+            description: 'Preview what would be created without making changes',
+        },
+    },
+    async run({ args }) {
+        const filePath = args.file;
+        const defaultParent = args.parent;
+        const dryRun = args['dry-run'];
+        // Read input
+        let raw;
+        if (!filePath || filePath === '-') {
+            // Read from stdin
+            const chunks = [];
+            for await (const chunk of process.stdin) {
+                chunks.push(chunk);
+            }
+            raw = Buffer.concat(chunks).toString('utf-8');
+            if (!raw.trim()) {
+                cliError('No input provided. Pass --file <path> or pipe JSON to stdin.', 'E_VALIDATION', {
+                    name: 'E_VALIDATION',
+                    fix: 'cleo add-batch --file tasks.json',
+                }, { operation: 'tasks.add-batch' });
+                process.exit(2);
+                return;
+            }
+        }
+        else {
+            if (!existsSync(filePath)) {
+                cliError(`File not found: ${filePath}`, 'E_NOT_FOUND', {
+                    name: 'E_NOT_FOUND',
+                    fix: `Verify the file path exists: ${filePath}`,
+                }, { operation: 'tasks.add-batch' });
+                process.exit(2);
+                return;
+            }
+            raw = readFileSync(filePath, 'utf-8');
+        }
+        let tasks;
+        try {
+            const parsed = JSON.parse(raw);
+            tasks = Array.isArray(parsed) ? parsed : [parsed];
+        }
+        catch {
+            cliError('Invalid JSON input. Expected an array of task objects.', 'E_VALIDATION', {
+                name: 'E_VALIDATION',
+                fix: 'Ensure the input is a valid JSON array of task objects',
+            }, { operation: 'tasks.add-batch' });
+            process.exit(2);
+            return;
+        }
+        if (tasks.length === 0) {
+            cliError('No tasks in input.', 'E_VALIDATION', {
+                name: 'E_VALIDATION',
+                fix: 'Provide at least one task object in the JSON array',
+            }, { operation: 'tasks.add-batch' });
+            process.exit(2);
+            return;
+        }
+        const results = [];
+        let failed = 0;
+        for (const task of tasks) {
+            const params = {
+                title: task.title,
+                ...(task.description && { description: task.description }),
+                parent: task.parent ?? defaultParent,
+                ...(task.type && { type: task.type }),
+                ...(task.priority && { priority: task.priority }),
+                ...(task.size && { size: task.size }),
+                ...(task.acceptance?.length && { acceptance: task.acceptance }),
+                ...(task.depends?.length && { depends: task.depends }),
+                ...(task.labels?.length && { labels: task.labels }),
+                ...(task.phase && { phase: task.phase }),
+                ...(task.notes && { notes: task.notes }),
+                ...(task.files?.length && { files: task.files }),
+                ...(dryRun && { dryRun: true }),
+            };
+            const response = await dispatchRaw('mutate', 'tasks', 'add', params);
+            if (response.success) {
+                const data = response.data;
+                const taskData = data?.task;
+                results.push({ title: task.title, id: taskData?.id });
+            }
+            else {
+                failed++;
+                results.push({
+                    title: task.title,
+                    error: response.error?.message ?? 'Unknown error',
+                });
+            }
+        }
+        const output = {
+            total: tasks.length,
+            created: tasks.length - failed,
+            failed,
+            dryRun: dryRun ?? false,
+            results,
+        };
+        if (failed > 0) {
+            cliOutput(output, {
+                command: 'add-batch',
+                message: `${failed} of ${tasks.length} tasks failed`,
+                operation: 'tasks.add-batch',
+            });
+            process.exit(1);
+        }
+        else {
+            cliOutput(output, {
+                command: 'add-batch',
+                operation: 'tasks.add-batch',
+            });
+        }
+    },
+});
+//# sourceMappingURL=add-batch.js.map

package/dist/cli/commands/add-batch.js.map

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

package/dist/cli/commands/add.d.ts

@@ -0,0 +1,162 @@
+/**
+ * CLI add command — create a new task.
+ *
+ * Task CLI command convention: CLEO intentionally exposes task operations as
+ * split root commands (`add`, `update`, `list`, etc.) instead of a
+ * `tasks.ts` command group. Keep CLI-only compatibility aliases in the
+ * command file that owns the flag, then dispatch only canonical task params.
+ *
+ * Dispatches to `tasks.add` via dispatchRaw and emits advisory warnings and
+ * duplicate / dry-run notices from the response payload.
+ *
+ * @task T4460
+ * @epic T4454
+ */
+/**
+ * cleo add — create a new task.
+ *
+ * Accepts a positional title plus a full suite of optional flags that map
+ * directly to the `tasks.add` operation parameters.  Pipe-separated
+ * acceptance criteria (`--acceptance "AC1|AC2"`) and JSON array format are
+ * both supported.
+ *
+ * T944 additions: `--role` (intent axis) and `--scope` (granularity axis).
+ * `--kind` is accepted as a backward-compatible alias for `--role`.
+ * `--parent-id` and `--note` are CLI-only compatibility aliases for
+ * `--parent` and `--notes`.
+ *
+ * T1329: In strict mode, if no explicit `--parent` is provided and the task
+ * type is not 'epic', the command attempts to infer `--parent` from the active
+ * session's current task (`session.taskWork.taskId`). This reduces friction for
+ * creating subtasks under the active focus task.
+ */
+export declare const addCommand: import("citty").CommandDef<{
+    readonly title: {
+        readonly type: "positional";
+        readonly description: "Task title (3–500 characters)";
+        readonly required: false;
+    };
+    readonly status: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Task status (pending | active | blocked | done)";
+    };
+    readonly priority: {
+        readonly type: "string";
+        readonly alias: "p";
+        readonly description: "Task priority (low | medium | high | critical)";
+    };
+    readonly type: {
+        readonly type: "string";
+        readonly alias: "t";
+        readonly description: "Task type (epic | task | subtask | bug)";
+    };
+    readonly parent: {
+        readonly type: "string";
+        readonly description: "Parent task ID (makes this task a subtask)";
+    };
+    readonly 'parent-id': {
+        readonly type: "string";
+        readonly description: "Alias for --parent (legacy parentId compatibility)";
+    };
+    readonly size: {
+        readonly type: "string";
+        readonly description: "Scope size estimate (small | medium | large)";
+    };
+    readonly phase: {
+        readonly type: "string";
+        readonly alias: "P";
+        readonly description: "Phase slug to assign the task to";
+    };
+    readonly description: {
+        readonly type: "string";
+        readonly alias: "d";
+        readonly description: "Detailed task description (must differ meaningfully from title)";
+    };
+    readonly desc: {
+        readonly type: "string";
+        readonly description: "Task description (alias for --description)";
+    };
+    readonly labels: {
+        readonly type: "string";
+        readonly alias: "l";
+        readonly description: "Comma-separated labels";
+    };
+    readonly files: {
+        readonly type: "string";
+        readonly description: "Comma-separated file paths";
+    };
+    readonly 'files-infer': {
+        readonly type: "boolean";
+        readonly description: "Infer touched files from task title and description using GitNexus";
+    };
+    readonly acceptance: {
+        readonly type: "string";
+        readonly description: "Pipe-separated acceptance criteria (e.g. \"AC1|AC2|AC3\")";
+    };
+    readonly depends: {
+        readonly type: "string";
+        readonly alias: "D";
+        readonly description: "Comma-separated dependency task IDs";
+    };
+    readonly notes: {
+        readonly type: "string";
+        readonly description: "Initial note entry for the task";
+    };
+    readonly note: {
+        readonly type: "string";
+        readonly description: "Alias for --notes";
+    };
+    readonly position: {
+        readonly type: "string";
+        readonly description: "Position within sibling group";
+    };
+    readonly 'parent-search': {
+        readonly type: "string";
+        readonly description: "Resolve parent by title substring instead of exact ID (T090)";
+    };
+    readonly 'add-phase': {
+        readonly type: "boolean";
+        readonly description: "Create new phase if it does not exist";
+    };
+    readonly 'dry-run': {
+        readonly type: "boolean";
+        readonly description: "Show what would be created without making changes";
+    };
+    /**
+     * Task role axis — intent of work.
+     * Values: work | research | experiment | bug | spike | release
+     * @task T944
+     */
+    readonly role: {
+        readonly type: "string";
+        readonly description: "Task role / intent axis (work|research|experiment|bug|spike|release) — orthogonal to --type (T944)";
+    };
+    /**
+     * Backward-compatible alias for --role (fractal-ontology spec used "kind").
+     * @task T944
+     */
+    readonly kind: {
+        readonly type: "string";
+        readonly description: "Alias for --role (T944 fractal-ontology compat)";
+    };
+    /**
+     * Task scope axis — granularity of work.
+     * Values: project | feature | unit
+     * @task T944
+     */
+    readonly scope: {
+        readonly type: "string";
+        readonly description: "Task scope / granularity axis (project|feature|unit) — orthogonal to --type (T944)";
+    };
+    /**
+     * Bug severity. Only valid when --role bug.
+     * Values: P0 | P1 | P2 | P3
+     * @task T944
+     */
+    readonly severity: {
+        readonly type: "string";
+        readonly description: "Bug severity (P0|P1|P2|P3) — only valid with --role bug (T944)";
+    };
+}>;
+//# sourceMappingURL=add.d.ts.map

package/dist/cli/commands/add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/add.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAkGnB;;;;OAIG;;;;;IAMH;;;OAGG;;;;;IAKH;;;;OAIG;;;;;IAMH;;;;OAIG;;;;;EAwGL,CAAC"}

package/dist/cli/commands/add.js

@@ -0,0 +1,279 @@
+/**
+ * CLI add command — create a new task.
+ *
+ * Task CLI command convention: CLEO intentionally exposes task operations as
+ * split root commands (`add`, `update`, `list`, etc.) instead of a
+ * `tasks.ts` command group. Keep CLI-only compatibility aliases in the
+ * command file that owns the flag, then dispatch only canonical task params.
+ *
+ * Dispatches to `tasks.add` via dispatchRaw and emits advisory warnings and
+ * duplicate / dry-run notices from the response payload.
+ *
+ * @task T4460
+ * @epic T4454
+ */
+import { getProjectRoot, inferTaskAddParams } from '@cleocode/core';
+import { defineCommand, showUsage } from 'citty';
+import { dispatchRaw, handleRawError } from '../../dispatch/adapters/cli.js';
+import { cliOutput } from '../renderers/index.js';
+/**
+ * cleo add — create a new task.
+ *
+ * Accepts a positional title plus a full suite of optional flags that map
+ * directly to the `tasks.add` operation parameters.  Pipe-separated
+ * acceptance criteria (`--acceptance "AC1|AC2"`) and JSON array format are
+ * both supported.
+ *
+ * T944 additions: `--role` (intent axis) and `--scope` (granularity axis).
+ * `--kind` is accepted as a backward-compatible alias for `--role`.
+ * `--parent-id` and `--note` are CLI-only compatibility aliases for
+ * `--parent` and `--notes`.
+ *
+ * T1329: In strict mode, if no explicit `--parent` is provided and the task
+ * type is not 'epic', the command attempts to infer `--parent` from the active
+ * session's current task (`session.taskWork.taskId`). This reduces friction for
+ * creating subtasks under the active focus task.
+ */
+export const addCommand = defineCommand({
+    meta: {
+        name: 'add',
+        description: 'Create a new task (requires active session)',
+    },
+    args: {
+        title: {
+            type: 'positional',
+            description: 'Task title (3–500 characters)',
+            required: false,
+        },
+        status: {
+            type: 'string',
+            alias: 's',
+            description: 'Task status (pending | active | blocked | done)',
+        },
+        priority: {
+            type: 'string',
+            alias: 'p',
+            description: 'Task priority (low | medium | high | critical)',
+        },
+        type: {
+            type: 'string',
+            alias: 't',
+            description: 'Task type (epic | task | subtask | bug)',
+        },
+        parent: {
+            type: 'string',
+            description: 'Parent task ID (makes this task a subtask)',
+        },
+        'parent-id': {
+            type: 'string',
+            description: 'Alias for --parent (legacy parentId compatibility)',
+        },
+        size: {
+            type: 'string',
+            description: 'Scope size estimate (small | medium | large)',
+        },
+        phase: {
+            type: 'string',
+            alias: 'P',
+            description: 'Phase slug to assign the task to',
+        },
+        description: {
+            type: 'string',
+            alias: 'd',
+            description: 'Detailed task description (must differ meaningfully from title)',
+        },
+        desc: {
+            type: 'string',
+            description: 'Task description (alias for --description)',
+        },
+        labels: {
+            type: 'string',
+            alias: 'l',
+            description: 'Comma-separated labels',
+        },
+        files: {
+            type: 'string',
+            description: 'Comma-separated file paths',
+        },
+        'files-infer': {
+            type: 'boolean',
+            description: 'Infer touched files from task title and description using GitNexus',
+        },
+        acceptance: {
+            type: 'string',
+            description: 'Pipe-separated acceptance criteria (e.g. "AC1|AC2|AC3")',
+        },
+        depends: {
+            type: 'string',
+            alias: 'D',
+            description: 'Comma-separated dependency task IDs',
+        },
+        notes: {
+            type: 'string',
+            description: 'Initial note entry for the task',
+        },
+        note: {
+            type: 'string',
+            description: 'Alias for --notes',
+        },
+        position: {
+            type: 'string',
+            description: 'Position within sibling group',
+        },
+        'parent-search': {
+            type: 'string',
+            description: 'Resolve parent by title substring instead of exact ID (T090)',
+        },
+        'add-phase': {
+            type: 'boolean',
+            description: 'Create new phase if it does not exist',
+        },
+        'dry-run': {
+            type: 'boolean',
+            description: 'Show what would be created without making changes',
+        },
+        /**
+         * Task role axis — intent of work.
+         * Values: work | research | experiment | bug | spike | release
+         * @task T944
+         */
+        role: {
+            type: 'string',
+            description: 'Task role / intent axis (work|research|experiment|bug|spike|release) — orthogonal to --type (T944)',
+        },
+        /**
+         * Backward-compatible alias for --role (fractal-ontology spec used "kind").
+         * @task T944
+         */
+        kind: {
+            type: 'string',
+            description: 'Alias for --role (T944 fractal-ontology compat)',
+        },
+        /**
+         * Task scope axis — granularity of work.
+         * Values: project | feature | unit
+         * @task T944
+         */
+        scope: {
+            type: 'string',
+            description: 'Task scope / granularity axis (project|feature|unit) — orthogonal to --type (T944)',
+        },
+        /**
+         * Bug severity. Only valid when --role bug.
+         * Values: P0 | P1 | P2 | P3
+         * @task T944
+         */
+        severity: {
+            type: 'string',
+            description: 'Bug severity (P0|P1|P2|P3) — only valid with --role bug (T944)',
+        },
+    },
+    async run({ args, cmd }) {
+        if (!args.title) {
+            await showUsage(cmd);
+            return;
+        }
+        const params = { title: args.title };
+        if (args.status !== undefined)
+            params['status'] = args.status;
+        if (args.priority !== undefined)
+            params['priority'] = args.priority;
+        if (args.type !== undefined)
+            params['type'] = args.type;
+        if (args.parent !== undefined)
+            params['parent'] = args.parent;
+        if (args['parent-id'] !== undefined)
+            params['parent'] = params['parent'] ?? args['parent-id'];
+        if (args.size !== undefined)
+            params['size'] = args.size;
+        if (args.phase !== undefined)
+            params['phase'] = args.phase;
+        if (args['add-phase'] !== undefined)
+            params['addPhase'] = args['add-phase'];
+        if (args.description !== undefined) {
+            params['description'] = args.description;
+        }
+        else if (args.desc !== undefined) {
+            params['description'] = args.desc;
+        }
+        if (args.labels)
+            params['labels'] = args.labels.split(',').map((s) => s.trim());
+        if (args.depends)
+            params['depends'] = args.depends.split(',').map((s) => s.trim());
+        if (args.notes !== undefined)
+            params['notes'] = args.notes;
+        if (args.note !== undefined)
+            params['notes'] = params['notes'] ?? args.note;
+        if (args.position !== undefined)
+            params['position'] = Number.parseInt(args.position, 10);
+        if (args['dry-run'] !== undefined)
+            params['dryRun'] = args['dry-run'];
+        if (args['parent-search'] !== undefined)
+            params['parentSearch'] = args['parent-search'];
+        // T944: orthogonal axes — --kind is a CLI alias for --role (ADR-057 D2)
+        // Aliasing lives at the CLI layer; wire format only uses 'role'.
+        if (args.role !== undefined)
+            params['role'] = args.role;
+        if (args.kind !== undefined)
+            params['role'] = params['role'] ?? args.kind;
+        if (args.scope !== undefined)
+            params['scope'] = args.scope;
+        if (args.severity !== undefined)
+            params['severity'] = args.severity;
+        // T1490: Delegate file inference, acceptance parsing, and parent inference
+        // to Core so the CLI layer stays a thin parse-and-delegate shell.
+        // Stderr output (warnings, notices) remains here in the CLI layer.
+        const inferred = await inferTaskAddParams(getProjectRoot(), {
+            title: args.title,
+            description: (args.description ?? args.desc),
+            filesInfer: args['files-infer'],
+            filesRaw: args.files,
+            acceptanceRaw: args.acceptance,
+            parentRaw: params['parent'],
+            type: params['type'],
+        });
+        // Emit stderr notices (CLI responsibility — Core never writes to stderr)
+        if (inferred.filesInferWarning) {
+            process.stderr.write('⚠ No files inferred by GitNexus. Use --files to specify files explicitly, or leave empty for atomicity check at spawn time.\n');
+        }
+        if (inferred.files)
+            params['files'] = inferred.files;
+        if (inferred.acceptance)
+            params['acceptance'] = inferred.acceptance;
+        // T1329: parent inference from active session's current task
+        if (inferred.inferredParent) {
+            params['parent'] = inferred.inferredParent;
+            process.stderr.write(`[cleo add] inferred --parent from current task: ${inferred.inferredParent}\n`);
+        }
+        const response = await dispatchRaw('mutate', 'tasks', 'add', params);
+        if (!response.success) {
+            handleRawError(response, { command: 'add', operation: 'tasks.add' });
+        }
+        const data = response.data;
+        // Display advisory warnings (T089: orphan prevention, etc.)
+        const dataWarnings = data?.warnings;
+        if (dataWarnings?.length) {
+            for (const w of dataWarnings) {
+                process.stderr.write(`⚠ ${w}\n`);
+            }
+        }
+        if (data?.duplicate) {
+            cliOutput(data, {
+                command: 'add',
+                message: 'Task with identical title was created recently',
+                operation: 'tasks.add',
+            });
+        }
+        else if (data?.dryRun) {
+            cliOutput(data, {
+                command: 'add',
+                message: 'Dry run - no changes made',
+                operation: 'tasks.add',
+            });
+        }
+        else {
+            cliOutput(data, { command: 'add', operation: 'tasks.add' });
+        }
+    },
+});
+//# sourceMappingURL=add.js.map

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

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

package/dist/cli/commands/admin.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CLI command group for system administration and diagnostics.
+ *
+ * Provides CLI access to admin.version, admin.health, admin.stats,
+ * admin.runtime, admin.smoke, admin.paths, admin.scaffold-hub,
+ * admin.cleanup, admin.job, admin.job.cancel, admin.install.global,
+ * and admin.context.inject via `cleo admin <subcommand>`.
+ *
+ * The `job` subgroup uses an explicit parent `run()` that delegates to
+ * `job list` when no subcommand is given (citty has no `isDefault` concept).
+ *
+ * @task T132
+ * @task T480 — add cleanup, job, job.cancel, install.global, context.inject subcommands.
+ */
+/**
+ * Root admin command group — registers all admin subcommands.
+ *
+ * Dispatches to the `admin` domain registry operations.
+ *
+ * @task T132
+ * @task T480
+ */
+export declare const adminCommand: import("citty").CommandDef<import("citty").ArgsDef>;
+//# sourceMappingURL=admin.d.ts.map

package/dist/cli/commands/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/admin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAqUH;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,qDAoBvB,CAAC"}