@skrr-ai/cli 0.1.8

package/dist/commands/spaces/work-graph.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../base-command");
+/**
+ * The shape of the work in a space, and the claims its relations make.
+ *
+ * Four relations that were previously either undrawn or indistinguishable:
+ * containment ("part of"), dependency ("must wait for"), lineage ("was found
+ * while doing"), and goal membership. A reader — human or agent — needs them
+ * told apart, because they lead to opposite decisions about what to do next.
+ */
+class SpacesWorkGraph extends base_command_1.BaseCommand {
+    static description = 'Show a space’s work graph: tasks, goals, and what each relation between them claims';
+    static args = {
+        id: core_1.Args.string({ description: 'Space ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output the full graph as JSON' }),
+        kind: core_1.Flags.string({
+            description: 'Show only edges of one kind',
+            options: ['containment', 'dependency', 'lineage', 'membership'],
+        }),
+        attention: core_1.Flags.boolean({
+            description: 'Show only relations a person should look at (review findings and blockers)',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(SpacesWorkGraph);
+        let response;
+        try {
+            response = await data_provider_1.dataService.getSpaceWorkGraph(args.id);
+        }
+        catch (err) {
+            this.handleApiError(err);
+        }
+        // Same guard as `tasks workflow-context`: an unknown route falls through to
+        // the SPA and returns an HTML string, which reached `.nodes.map` as
+        // `undefined` and produced a TypeError instead of an explanation.
+        if (!response || typeof response !== 'object' || !Array.isArray(response.nodes)) {
+            this.failWithCliError({
+                message: 'The server did not return a work graph. This usually means the API is older than this CLI.',
+                code: 'UNEXPECTED_RESPONSE',
+                exit: 1,
+                retryable: false,
+            });
+        }
+        if (flags.json) {
+            this.log(JSON.stringify(response, null, 2));
+            return;
+        }
+        const titles = new Map(response.nodes.map((node) => [node.id, node]));
+        const label = (id) => {
+            const node = titles.get(id);
+            if (!node)
+                return id;
+            return node.identifier ? `${node.identifier} ${node.title}` : node.title;
+        };
+        const { summary } = response;
+        const boundary = summary.lineageBoundary;
+        this.log(`${summary.tasks} tasks` +
+            (boundary?.externalTasks ? ` + ${boundary.externalTasks} related across Spaces` : '') +
+            ` · ${summary.goals} goals · ${summary.edges} relations` +
+            (summary.attention ? ` · ${summary.attention} need attention` : ''));
+        if (response.truncated) {
+            // A truncated graph that does not say so reads as a complete one, and a
+            // reader would conclude the work does not exist rather than that it was
+            // not returned.
+            this.log(`(truncated at ${response.cap} tasks — this space has more)`);
+        }
+        if (boundary?.truncated) {
+            this.log(`(cross-Space lineage truncated at ${boundary.cap} external nodes)`);
+        }
+        this.log('');
+        let edges = response.edges;
+        if (flags.kind) {
+            edges = edges.filter((edge) => edge.kind === flags.kind);
+        }
+        if (flags.attention) {
+            edges = edges.filter((edge) => edge.attention);
+        }
+        if (!edges.length) {
+            this.log('No relations match.');
+            return;
+        }
+        // Grouped by kind so the four claims never blur into one list — which is
+        // the state this whole feature exists to get out of.
+        const byKind = new Map();
+        for (const edge of edges) {
+            byKind.set(edge.kind, [...(byKind.get(edge.kind) ?? []), edge]);
+        }
+        for (const [kind, group] of byKind) {
+            this.log(`${kind} (${group.length})`);
+            for (const edge of group) {
+                const mark = edge.attention ? ' !' : '';
+                this.log(`  ${label(edge.from)}  →  ${label(edge.to)}   [${edge.label}]${mark}`);
+            }
+            this.log('');
+        }
+    }
+}
+exports.default = SpacesWorkGraph;

package/dist/commands/spaces/workflow-templates/archive.d.ts

@@ -0,0 +1,16 @@
+import { BaseCommand } from '../../../base-command';
+/** Soft archive. Versions and the usage ledger are retained deliberately: a
+ *  workflow already built from this template has to stay explicable. */
+export default class SpacesWorkflowTemplatesArchive extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        spaceId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        templateId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/spaces/workflow-templates/archive.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const prompt_1 = require("../../../lib/prompt");
+/** Soft archive. Versions and the usage ledger are retained deliberately: a
+ *  workflow already built from this template has to stay explicable. */
+class SpacesWorkflowTemplatesArchive extends base_command_1.BaseCommand {
+    static description = 'Archive a workflow template while retaining its versions and usage';
+    static examples = [
+        '<%= config.bin %> spaces workflow-templates archive <space-id> <template-id>',
+        '<%= config.bin %> spaces workflow-templates archive <space-id> <template-id> --yes --json',
+    ];
+    static args = {
+        spaceId: core_1.Args.string({ description: 'Owning Space ID', required: true, ignoreStdin: true }),
+        templateId: core_1.Args.string({ description: 'Template ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        yes: core_1.Flags.boolean({ char: 'y', description: 'Skip the confirmation prompt' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(SpacesWorkflowTemplatesArchive);
+        let confirmed;
+        try {
+            confirmed = await (0, prompt_1.confirmDestructive)(`Archive workflow template ${args.templateId}? Published versions and usage history are retained.`, flags.yes);
+        }
+        catch (error) {
+            this.failWithCliError({
+                message: error.message,
+                code: 'WORKFLOW_TEMPLATE_CONFIRMATION_REQUIRED',
+                exit: error.exit ?? 1,
+                retryable: false,
+            });
+        }
+        if (!confirmed)
+            return this.log('Cancelled.');
+        let result;
+        try {
+            result = await data_provider_1.dataService.archiveSpaceWorkflowTemplate(args.spaceId, args.templateId);
+        }
+        catch (error) {
+            this.handleApiError(error, { subject: `workflow template ${args.templateId}` });
+        }
+        if (flags.json)
+            return this.log(JSON.stringify(result, null, 2));
+        this.log(`Archived template ${result.id}.`);
+    }
+}
+exports.default = SpacesWorkflowTemplatesArchive;

package/dist/commands/spaces/workflow-templates/create.d.ts

@@ -0,0 +1,21 @@
+import { BaseCommand } from '../../../base-command';
+/** Author a template from a body on disk. The server re-runs the portability
+ *  scrub itself, so a hand-written body is held to the same contract as one
+ *  extracted from a live canvas. */
+export default class SpacesWorkflowTemplatesCreate extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        spaceId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        title: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        description: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        tags: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        scope: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        body: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        publish: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/spaces/workflow-templates/create.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const prompt_1 = require("../../../lib/prompt");
+const workflow_templates_1 = require("../../../lib/workflow-templates");
+/** Author a template from a body on disk. The server re-runs the portability
+ *  scrub itself, so a hand-written body is held to the same contract as one
+ *  extracted from a live canvas. */
+class SpacesWorkflowTemplatesCreate extends base_command_1.BaseCommand {
+    static description = 'Create a workflow template from a body JSON file';
+    static examples = [
+        '<%= config.bin %> spaces workflow-templates create <space-id> --title "Approval loop" --body body.json',
+        '<%= config.bin %> spaces workflow-templates create <space-id> --title "Escalation" --body body.json --scope space --publish',
+        'skrr spaces workflow-templates show <space-id> <template-id> --body | <%= config.bin %> spaces workflow-templates create <space-id> --title Fork --body -',
+    ];
+    static args = {
+        spaceId: core_1.Args.string({ description: 'Owning Space ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output the created template as JSON' }),
+        title: core_1.Flags.string({ description: 'Template title', required: true }),
+        description: core_1.Flags.string({ description: 'What this fragment is for' }),
+        tags: core_1.Flags.string({ description: 'Comma list of tags' }),
+        scope: core_1.Flags.string({ description: 'private (default), space, or workspace' }),
+        body: core_1.Flags.string({
+            description: 'Path to body JSON — { semantic, presentation } or { nodes, edges } ("-" for stdin)',
+            required: true,
+        }),
+        publish: core_1.Flags.boolean({ description: 'Publish v1 immediately (required before insertion)' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(SpacesWorkflowTemplatesCreate);
+        let raw;
+        try {
+            raw = await (0, prompt_1.readJsonValue)(flags.body);
+        }
+        catch (error) {
+            this.failWithCliError({
+                message: error.message,
+                code: 'WORKFLOW_TEMPLATE_BODY_FILE_INVALID',
+                exit: 2,
+                retryable: false,
+            });
+        }
+        const plan = (0, workflow_templates_1.buildTemplateCreatePayload)({ ...flags, body: raw });
+        if (!plan.ok)
+            this.failWithCliError({ ...plan.error, exit: 2, retryable: false });
+        let template;
+        try {
+            template = await data_provider_1.dataService.createSpaceWorkflowTemplate(args.spaceId, plan.payload);
+        }
+        catch (error) {
+            this.handleApiError(error, { subject: `space ${args.spaceId}` });
+        }
+        if (flags.json)
+            return this.log(JSON.stringify(template, null, 2));
+        this.log(`Created template ${template.id}: ${template.title}`);
+        if (template.currentVersion) {
+            this.log(`Published version ${template.currentVersion}.`);
+        }
+        else {
+            this.log(`Next: skrr spaces workflow-templates publish ${args.spaceId} ${template.id}`);
+        }
+    }
+}
+exports.default = SpacesWorkflowTemplatesCreate;

package/dist/commands/spaces/workflow-templates/extract.d.ts

@@ -0,0 +1,27 @@
+import { BaseCommand } from '../../../base-command';
+/**
+ * Save-from-selection.
+ *
+ * The caller names node keys only: the server induces the subgraph from the
+ * LIVE draft, scrubs space-locked ids into slots, and derives the ports. A
+ * client-supplied body is not accepted anywhere, so the CLI and the canvas
+ * cannot produce different templates from the same selection.
+ */
+export default class SpacesWorkflowTemplatesExtract extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        spaceId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        workflowId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        nodes: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        title: import("@oclif/core/lib/interfaces").OptionFlag<string, import("@oclif/core/lib/interfaces").CustomOptions>;
+        description: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        tags: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        scope: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        publish: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/spaces/workflow-templates/extract.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const workflow_templates_1 = require("../../../lib/workflow-templates");
+/**
+ * Save-from-selection.
+ *
+ * The caller names node keys only: the server induces the subgraph from the
+ * LIVE draft, scrubs space-locked ids into slots, and derives the ports. A
+ * client-supplied body is not accepted anywhere, so the CLI and the canvas
+ * cannot produce different templates from the same selection.
+ */
+class SpacesWorkflowTemplatesExtract extends base_command_1.BaseCommand {
+    static description = 'Save part of a workflow draft as a reusable workflow template';
+    static examples = [
+        '<%= config.bin %> spaces workflow-templates extract <space-id> <workflow-id> --nodes task_1,approval_1 --title "Task with review"',
+        '<%= config.bin %> spaces workflow-templates extract <space-id> <workflow-id> --nodes task_1,approval_1 --title Review --scope space --json',
+        '<%= config.bin %> spaces workflow-templates extract <space-id> <workflow-id> --nodes task_1 --title Draft --no-publish',
+    ];
+    static args = {
+        spaceId: core_1.Args.string({ description: 'Owning Space ID', required: true, ignoreStdin: true }),
+        workflowId: core_1.Args.string({
+            description: 'Workflow definition to extract from',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output the created template as JSON' }),
+        nodes: core_1.Flags.string({
+            description: 'Comma list of node keys to extract from the live draft',
+            required: true,
+        }),
+        title: core_1.Flags.string({ description: 'Template title', required: true }),
+        description: core_1.Flags.string({ description: 'What this fragment is for' }),
+        tags: core_1.Flags.string({ description: 'Comma list of tags' }),
+        scope: core_1.Flags.string({ description: 'private (default), space, or workspace' }),
+        publish: core_1.Flags.boolean({
+            allowNo: true,
+            description: 'Publish v1 immediately (default: true; --no-publish leaves it a draft)',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(SpacesWorkflowTemplatesExtract);
+        const plan = (0, workflow_templates_1.buildTemplateExtractPayload)(flags);
+        if (!plan.ok)
+            this.failWithCliError({ ...plan.error, exit: 2, retryable: false });
+        let result;
+        try {
+            result = await data_provider_1.dataService.extractSpaceWorkflowTemplate(args.spaceId, args.workflowId, plan.payload);
+        }
+        catch (error) {
+            this.handleApiError(error, { subject: `workflow ${args.workflowId}` });
+        }
+        if (flags.json)
+            return this.log(JSON.stringify(result, null, 2));
+        this.log(`Created template ${result.template.id}: ${result.template.title}`);
+        this.log(`Nodes / edges: ${result.template.nodeCount} / ${result.template.edgeCount} · scope ${result.template.scope}`);
+        if (result.version)
+            this.log(`Published version ${result.version.version} (${result.version.id})`);
+        for (const slot of result.template.slots) {
+            this.log(`Slot: ${slot.ref} (${slot.kind}) ← ${slot.nodeKey}.${slot.configPath}`);
+        }
+        for (const input of result.template.inputs) {
+            this.log(`Input: $input.${input.name}${input.originalReference ? ` (was ${input.originalReference})` : ''}`);
+        }
+        for (const warning of result.warnings)
+            this.log(`Warning: ${warning}`);
+    }
+}
+exports.default = SpacesWorkflowTemplatesExtract;

package/dist/commands/spaces/workflow-templates/insert.d.ts

@@ -0,0 +1,26 @@
+import { BaseCommand } from '../../../base-command';
+/**
+ * Stamp a pinned template version into a workflow draft.
+ *
+ * The server performs the merge and owns the draft compare-and-swap, so this
+ * command sends a REQUEST (template, version, anchor, connection) rather than a
+ * merged draft. The returned draft is authoritative.
+ */
+export default class SpacesWorkflowTemplatesInsert extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        spaceId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        workflowId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        templateId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        version: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        at: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        after: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        between: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        slot: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/spaces/workflow-templates/insert.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const workflow_templates_1 = require("../../../lib/workflow-templates");
+/**
+ * Stamp a pinned template version into a workflow draft.
+ *
+ * The server performs the merge and owns the draft compare-and-swap, so this
+ * command sends a REQUEST (template, version, anchor, connection) rather than a
+ * merged draft. The returned draft is authoritative.
+ */
+class SpacesWorkflowTemplatesInsert extends base_command_1.BaseCommand {
+    static description = 'Insert a workflow template into an existing workflow draft';
+    static examples = [
+        '<%= config.bin %> spaces workflow-templates insert <space-id> <workflow-id> <template-id>',
+        '<%= config.bin %> spaces workflow-templates insert <space-id> <workflow-id> <template-id> --after task_1:success',
+        '<%= config.bin %> spaces workflow-templates insert <space-id> <workflow-id> <template-id> --between task_1,notify_1,success',
+        '<%= config.bin %> spaces workflow-templates insert <space-id> <workflow-id> <template-id> --slot agent_reviewer=agt_123 --at 400,200 --json',
+    ];
+    static args = {
+        spaceId: core_1.Args.string({ description: 'Owning Space ID', required: true, ignoreStdin: true }),
+        workflowId: core_1.Args.string({
+            description: 'Workflow definition to insert into',
+            required: true,
+            ignoreStdin: true,
+        }),
+        templateId: core_1.Args.string({
+            description: 'Template ID (`wft_…`, or `wftp_…` for a built-in)',
+            required: true,
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output the workflow and the insertion result as JSON' }),
+        version: core_1.Flags.integer({
+            description: 'Pin this template version instead of the current published one',
+        }),
+        at: core_1.Flags.string({ description: 'Top-left canvas position for the fragment, "x,y"' }),
+        after: core_1.Flags.string({
+            description: 'Connect from an existing node: "<nodeKey>" or "<nodeKey>:<outcome>"',
+        }),
+        between: core_1.Flags.string({
+            description: 'Splice onto an existing edge: "from,to" or "from,to,outcome"',
+        }),
+        slot: core_1.Flags.string({
+            multiple: true,
+            description: 'Bind a template slot: "ref=value" (repeatable; repeats become a list)',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(SpacesWorkflowTemplatesInsert);
+        const anchor = (0, workflow_templates_1.parseInsertAnchor)(flags.at);
+        if (!anchor.ok)
+            this.failWithCliError({ ...anchor.error, exit: 2, retryable: false });
+        const connect = (0, workflow_templates_1.buildInsertConnect)(flags);
+        if (!connect.ok)
+            this.failWithCliError({ ...connect.error, exit: 2, retryable: false });
+        const slotBindings = (0, workflow_templates_1.parseSlotBindings)(flags.slot);
+        if (!slotBindings.ok) {
+            this.failWithCliError({ ...slotBindings.error, exit: 2, retryable: false });
+        }
+        let template;
+        try {
+            template = await data_provider_1.dataService.getSpaceWorkflowTemplate(args.spaceId, args.templateId);
+        }
+        catch (error) {
+            this.handleApiError(error, { subject: `workflow template ${args.templateId}` });
+        }
+        const templateVersionId = (0, workflow_templates_1.resolveTemplateVersionId)(template, flags.version);
+        if (!templateVersionId.ok) {
+            this.failWithCliError({ ...templateVersionId.error, exit: 4, retryable: false });
+        }
+        // Read the revision pair immediately before the write. This is not a lock:
+        // a concurrent save still loses the server's compare-and-swap rather than
+        // being silently overwritten, which is exactly what the retry below is for.
+        const attempt = async () => {
+            const workflow = await data_provider_1.dataService.getSpaceWorkflow(args.spaceId, args.workflowId);
+            return data_provider_1.dataService.insertSpaceWorkflowTemplate(args.spaceId, args.workflowId, (0, workflow_templates_1.buildTemplateInsertPayload)({
+                templateId: args.templateId,
+                templateVersionId: templateVersionId.payload,
+                anchor: anchor.payload,
+                connect: connect.payload,
+                ...(slotBindings.payload ? { slotBindings: slotBindings.payload } : {}),
+                semanticRevision: workflow.draft.semanticRevision,
+                presentationRevision: workflow.draft.presentationRevision,
+            }));
+        };
+        let result;
+        try {
+            result = await attempt();
+        }
+        catch (error) {
+            if (!(0, workflow_templates_1.isWorkflowDraftConflict)(error)) {
+                this.handleApiError(error, { subject: `workflow ${args.workflowId}` });
+            }
+            // Someone saved between the read and the write. Only the revision pair
+            // was stale, so one re-read makes the identical request valid again.
+            try {
+                result = await attempt();
+            }
+            catch (retryError) {
+                if (!(0, workflow_templates_1.isWorkflowDraftConflict)(retryError)) {
+                    this.handleApiError(retryError, { subject: `workflow ${args.workflowId}` });
+                }
+                this.failWithCliError({
+                    message: `Workflow ${args.workflowId} is being edited concurrently; the insert lost the draft compare-and-swap twice. Retry once the canvas is idle.`,
+                    code: 'WORKFLOW_DRAFT_CONFLICT',
+                    status: 409,
+                    exit: 1,
+                    retryable: true,
+                });
+            }
+        }
+        if (flags.json)
+            return this.log(JSON.stringify(result, null, 2));
+        const { insertion, workflow } = result;
+        this.log(`Inserted ${template.title} into ${workflow.title} (${insertion.instanceId}).`);
+        this.log(`Nodes: ${insertion.insertedKeys.join(', ') || '-'}`);
+        this.log(`Draft revisions: semantic ${workflow.draft.semanticRevision}, presentation ${workflow.draft.presentationRevision}`);
+        for (const slot of insertion.unresolvedSlots) {
+            this.log(`Unresolved slot: ${slot.ref} (${slot.kind}) — bind with --slot ${slot.ref}=<id>`);
+        }
+        for (const input of insertion.unboundInputs) {
+            this.log(`Unbound input: $input.${input.name} — set it on the node that consumes it`);
+        }
+        for (const warning of insertion.warnings)
+            this.log(`Warning: ${warning}`);
+    }
+}
+exports.default = SpacesWorkflowTemplatesInsert;

package/dist/commands/spaces/workflow-templates/list.d.ts

@@ -0,0 +1,19 @@
+import { BaseCommand } from '../../../base-command';
+/** The library read. Code-owned presets are merged in server-side, so one
+ *  request returns built-ins, space, workspace, and private rows alike. */
+export default class SpacesWorkflowTemplatesList extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        spaceId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        scope: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        q: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        tags: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        limit: import("@oclif/core/lib/interfaces").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'include-unpublished': import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/spaces/workflow-templates/list.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const format_1 = require("../../../lib/format");
+const workflow_templates_1 = require("../../../lib/workflow-templates");
+/** The library read. Code-owned presets are merged in server-side, so one
+ *  request returns built-ins, space, workspace, and private rows alike. */
+class SpacesWorkflowTemplatesList extends base_command_1.BaseCommand {
+    static description = 'List workflow templates visible from a space (built-ins included)';
+    static examples = [
+        '<%= config.bin %> spaces workflow-templates list <space-id>',
+        '<%= config.bin %> spaces workflow-templates list <space-id> --scope builtin,space --json',
+        '<%= config.bin %> spaces workflow-templates list <space-id> --q approval --tags review',
+    ];
+    static args = {
+        spaceId: core_1.Args.string({ description: 'Owning Space ID', required: true, ignoreStdin: true }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output as JSON' }),
+        scope: core_1.Flags.string({
+            description: 'Comma list of scopes: builtin, space, workspace, private',
+        }),
+        q: core_1.Flags.string({ description: 'Full-text search over title, tags, and description' }),
+        tags: core_1.Flags.string({ description: 'Comma list of tags to filter by' }),
+        limit: core_1.Flags.integer({ description: 'Maximum templates to return (1-200)' }),
+        'include-unpublished': core_1.Flags.boolean({
+            description: 'Include templates that have never been published (yours only)',
+        }),
+    };
+    async run() {
+        this.requireAuth();
+        const { args, flags } = await this.parse(SpacesWorkflowTemplatesList);
+        const scope = (0, workflow_templates_1.parseTemplateScopeFilter)(flags.scope);
+        if (!scope.ok)
+            this.failWithCliError({ ...scope.error, exit: 2, retryable: false });
+        const tags = (0, workflow_templates_1.parseTemplateTags)(flags.tags);
+        if (!tags.ok)
+            this.failWithCliError({ ...tags.error, exit: 2, retryable: false });
+        let result;
+        try {
+            result = await data_provider_1.dataService.listSpaceWorkflowTemplates(args.spaceId, {
+                ...(scope.payload ? { scope: scope.payload } : {}),
+                ...(flags.q ? { q: flags.q } : {}),
+                ...(tags.payload?.length ? { tags: tags.payload } : {}),
+                ...(flags['include-unpublished'] ? { publishedOnly: false } : {}),
+                ...(flags.limit !== undefined ? { limit: flags.limit } : {}),
+            });
+        }
+        catch (error) {
+            this.handleApiError(error, { subject: `space ${args.spaceId}` });
+        }
+        if (flags.json)
+            return this.log(JSON.stringify(result, null, 2));
+        if (!result.templates.length)
+            return this.log('No workflow templates.');
+        (0, format_1.renderTable)(result.templates.map(workflow_templates_1.toTemplateListRow), [
+            { key: 'title', header: 'TITLE', maxWidth: 40 },
+            { key: 'scope', header: 'SCOPE' },
+            { key: 'version', header: 'VERSION' },
+            { key: 'nodes', header: 'NODES' },
+            { key: 'splice', header: 'SPLICE' },
+            { key: 'uses', header: 'USES' },
+            { key: 'id', header: 'ID' },
+        ], (line) => this.log(line));
+    }
+}
+exports.default = SpacesWorkflowTemplatesList;

package/dist/commands/spaces/workflow-templates/promote.d.ts

@@ -0,0 +1,31 @@
+import { BaseCommand } from '../../../base-command';
+/**
+ * `skrr spaces workflow-templates promote <space> <template>` — mint a standalone
+ * published workflow from a pinned template version.
+ *
+ * The other reuse path, `insert`, SPLICES a fragment into a draft: the nodes
+ * become part of the host graph and stop tracking the template. Promote is the
+ * opposite relationship — it materializes the version as its own
+ * `WorkflowDefinition` so a `workflow_call` node can reference it, and every
+ * caller keeps sharing one implementation.
+ *
+ * The server publishes the definition in the same request, because an
+ * unpublished one cannot be called and a half-promoted template is not a state
+ * worth exposing. A template with no published version is refused
+ * (`WORKFLOW_TEMPLATE_NOT_PUBLISHED`, 409) rather than promoted from its
+ * mutable authoring head.
+ */
+export default class SpacesWorkflowTemplatesPromote extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        spaceId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+        templateId: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        version: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        title: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}