@formigio/fazemos-cli 0.2.3 → 0.3.0

package/dist/index.js

@@ -697,8 +697,44 @@ commitments
         process.exit(1);
     }
 });
+// ── Template I/O helpers ───────────────────────────────────
+function allSteps(definition) {
+    const steps = [];
+    for (const phase of definition?.phases || []) {
+        for (const step of phase.steps || []) {
+            steps.push(step);
+        }
+    }
+    return steps;
+}
+function findStepById(definition, stepId) {
+    return allSteps(definition).find((s) => s.id === stepId);
+}
+const VALID_IO_TYPES = ['text', 'markdown', 'number', 'boolean', 'url', 'json', 'object', 'array'];
+function requireDraftStatus(template) {
+    if (template.status !== 'draft') {
+        console.error(chalk.yellow(`Template is "${template.status}" — edits require draft status`));
+        process.exit(1);
+    }
+}
+function findPhaseById(definition, phaseId) {
+    return (definition?.phases || []).find((p) => p.id === phaseId);
+}
+const VALID_STEP_TYPES = ['human', 'agent', 'script', 'gate'];
 // ── Templates ──────────────────────────────────────────────
-const templates = program.command('templates').alias('tpl').description('Pipeline template commands');
+const templates = program.command('templates').alias('tpl').description('Pipeline template commands.\n\n' +
+    '  Templates define multi-step workflows: template → phases → steps → I/O.\n' +
+    '  Lifecycle: draft → active → archived (archived → draft to unarchive).\n' +
+    '  Structural edits (add/remove/edit phases, steps, I/O) require draft status.\n\n' +
+    '  Typical workflow:\n' +
+    '    1. tpl create -n "Name"           Create empty draft template\n' +
+    '    2. tpl add-phase <id> --name ...  Add phases\n' +
+    '    3. tpl add-step <id> --phase ...  Add steps to phases\n' +
+    '    4. tpl add-output / add-input     Wire I/O between steps\n' +
+    '    5. tpl validate <id>              Check for errors\n' +
+    '    6. tpl activate <id>              Make available for instances\n\n' +
+    '  Use "tpl steps <id>" to list step IDs needed by --step options.\n' +
+    '  Use "tpl show <id>" to see full structure with I/O declarations.');
 templates
     .command('list')
     .description('List pipeline templates')
@@ -724,8 +760,8 @@ templates
 });
 templates
     .command('show')
-    .description('Show template detail')
-    .argument('<id>', 'Template ID')
+    .description('Show template detail including phases, steps, I/O declarations, and pipeline inputs. Use this to inspect the full structure of a template and discover phase/step IDs needed by other commands.')
+    .argument('<id>', 'Template ID (use "tpl list" to find IDs)')
     .action(async (id) => {
     try {
         const data = await api('GET', `/api/pipeline-templates/${id}`);
@@ -734,11 +770,45 @@ templates
         console.log(`  ID:      ${t.id}`);
         console.log(`  Status:  ${t.status}`);
         console.log(`  Version: ${t.version}`);
+        // Pipeline-level inputs
+        if (t.definition?.inputs?.length) {
+            console.log(chalk.cyan('\n  Pipeline Inputs:'));
+            for (const inp of t.definition.inputs) {
+                const req = inp.required === false ? 'optional' : 'required';
+                const desc = inp.description ? ` — ${inp.description}` : '';
+                const def = inp.default_value != null ? ` [default: ${inp.default_value}]` : '';
+                console.log(`    ${inp.name} (${inp.type}, ${req})${desc}${def}`);
+            }
+        }
         if (t.definition?.phases) {
             for (const phase of t.definition.phases) {
                 console.log(chalk.cyan(`\n  Phase: ${phase.name}`));
                 for (const step of phase.steps || []) {
-                    console.log(`    ${step.name} (${step.stepType || 'human'}) — role: ${step.role || 'unassigned'}`);
+                    console.log(`    Step: ${step.name} [${step.role || 'unassigned'}] (${step.step_type || step.stepType || 'human'})`);
+                    if (step.outputs?.length) {
+                        console.log('      Outputs:');
+                        for (const o of step.outputs) {
+                            const req = o.required === false ? 'optional' : 'required';
+                            const desc = o.description ? ` — ${o.description}` : '';
+                            console.log(`        → ${o.name} (${o.type}, ${req})${desc}`);
+                        }
+                    }
+                    if (step.inputs?.length) {
+                        console.log('      Inputs:');
+                        for (const inp of step.inputs) {
+                            if (inp.pipeline_input) {
+                                console.log(`        ← ${inp.name} ← pipeline.${inp.pipeline_input}`);
+                            }
+                            else {
+                                const srcStep = findStepById(t.definition, inp.source_step_id);
+                                const srcName = srcStep ? srcStep.name : inp.source_step_id;
+                                console.log(`        ← ${inp.name} ← ${srcName}.${inp.source_output_name}`);
+                            }
+                        }
+                    }
+                    else if (step.outputs?.length) {
+                        console.log('      Inputs: none');
+                    }
                 }
             }
         }
@@ -750,7 +820,7 @@ templates
 });
 templates
     .command('create')
-    .description('Create a pipeline template')
+    .description('Create an empty pipeline template in draft status. After creation, use add-phase, add-step, and I/O commands to build the structure, then activate.')
     .requiredOption('-n, --name <name>', 'Template name')
     .option('-d, --description <desc>', 'Description')
     .action(async (opts) => {
@@ -770,30 +840,52 @@ templates
 });
 templates
     .command('import')
-    .description('Import a JOE template JSON file as a Fazemos pipeline template')
+    .description('Import a JOE template JSON file as a Fazemos pipeline template. Imports steps, outputs, inputs, and pipeline-level inputs. Step IDs are remapped to new UUIDs and input references are updated accordingly.')
     .argument('<file>', 'Path to JOE template JSON file')
     .action(async (file) => {
     try {
-        const { readFileSync } = await import('fs');
-        const { resolve } = await import('path');
         const raw = JSON.parse(readFileSync(resolve(file), 'utf-8'));
         // Map JOE template to Fazemos format
-        const steps = raw.steps || [];
-        // Group sequential steps into a single phase for now
+        const joeSteps = raw.steps || [];
+        // Build ID mapping so input source_step_id references survive UUID reassignment
+        const idMap = new Map();
+        for (const s of joeSteps) {
+            if (s.id)
+                idMap.set(s.id, crypto.randomUUID());
+        }
         const definition = {
+            inputs: (raw.inputs || []).map((i) => ({
+                name: i.name,
+                type: i.type || 'text',
+                required: i.required !== false,
+                ...(i.description ? { description: i.description } : {}),
+                ...(i.default_value != null ? { default_value: i.default_value } : {}),
+            })),
             phases: [{
                     id: crypto.randomUUID(),
                     name: raw.name || 'Main',
                     description: raw.description || '',
                     deliverables: [],
-                    steps: steps.map((s, i) => ({
-                        id: crypto.randomUUID(),
+                    steps: joeSteps.map((s, i) => ({
+                        id: idMap.get(s.id) || crypto.randomUUID(),
                         name: s.name,
                         description: s.description || '',
                         step_type: s.executionMode === 'script' ? 'script' : (s.agent ? 'agent' : 'human'),
                         role: s.role || s.agent || 'unassigned',
-                        inputs: [],
-                        outputs: [],
+                        inputs: (s.inputs || []).map((inp) => ({
+                            name: inp.name,
+                            ...(inp.source_step_id ? { source_step_id: idMap.get(inp.source_step_id) || inp.source_step_id, source_output_name: inp.source_output_name } : {}),
+                            ...(inp.pipeline_input ? { pipeline_input: inp.pipeline_input } : {}),
+                            ...(inp.description ? { description: inp.description } : {}),
+                            required: inp.required !== false,
+                        })),
+                        outputs: (s.outputs || []).map((o) => ({
+                            name: o.name,
+                            type: o.type || 'text',
+                            ...(o.description ? { description: o.description } : {}),
+                            required: o.required !== false,
+                            ...(o.format ? { format: o.format } : {}),
+                        })),
                         sections: s.sections || '',
                         reviewer: s.reviewer || null,
                         max_review_cycles: s.maxReviewCycles || 0,
@@ -813,7 +905,7 @@ templates
         };
         const data = await api('POST', '/api/pipeline-templates', body);
         const t = data.template;
-        console.log(chalk.green(`Imported: ${t.name} (${steps.length} steps)`));
+        console.log(chalk.green(`Imported: ${t.name} (${joeSteps.length} steps)`));
         console.log(`  ID: ${t.id}`);
     }
     catch (err) {
@@ -821,9 +913,25 @@ templates
         process.exit(1);
     }
 });
+templates
+    .command('update-definition')
+    .description('Update a template definition from a JSON file')
+    .argument('<id>', 'Template ID')
+    .argument('<file>', 'Path to definition JSON file')
+    .action(async (id, file) => {
+    try {
+        const definition = JSON.parse(readFileSync(resolve(file), 'utf-8'));
+        await api('PUT', `/api/pipeline-templates/${id}`, { definition });
+        console.log(chalk.green('Template definition updated'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 templates
     .command('activate')
-    .description('Activate a template (required before creating instances)')
+    .description('Activate a draft template (required before creating pipeline instances). Template must have at least one phase with at least one step. Status changes from draft → active.')
     .argument('<id>', 'Template ID')
     .action(async (id) => {
     try {
@@ -835,6 +943,763 @@ templates
         process.exit(1);
     }
 });
+// ── Template structure commands ─────────────────────────────
+templates
+    .command('update')
+    .description('Update template name or description. Works on any status (draft, active, or archived). Does not modify the definition or bump version.')
+    .argument('<id>', 'Template ID')
+    .option('-n, --name <name>', 'New name')
+    .option('-d, --description <desc>', 'New description')
+    .action(async (id, opts) => {
+    try {
+        if (!opts.name && opts.description == null) {
+            console.error(chalk.red('Provide --name and/or --description'));
+            process.exit(1);
+        }
+        const body = {};
+        if (opts.name)
+            body.name = opts.name;
+        if (opts.description != null)
+            body.description = opts.description;
+        const data = await api('PUT', `/api/pipeline-templates/${id}`, body);
+        console.log(chalk.green(`Updated: ${data.template.name}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('archive')
+    .description('Archive an active template. Archived templates cannot be used to create new instances. Use "tpl unarchive" to move back to draft for editing.')
+    .argument('<id>', 'Template ID')
+    .action(async (id) => {
+    try {
+        await api('PATCH', `/api/pipeline-templates/${id}/status`, { status: 'archived' });
+        console.log(chalk.green('Template archived'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('unarchive')
+    .description('Move an archived template back to draft status for editing. After edits, use "tpl activate" to make it available again.')
+    .argument('<id>', 'Template ID')
+    .action(async (id) => {
+    try {
+        await api('PATCH', `/api/pipeline-templates/${id}/status`, { status: 'draft' });
+        console.log(chalk.green('Template moved to draft'));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('add-phase')
+    .description('Add a phase to a template. Phases group steps into logical stages (e.g., "Design", "Build", "Test"). Template must be in draft status. Phase names must be unique within the template. Returns the generated phase ID needed by add-step.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--name <name>', 'Phase name (must be unique within the template)')
+    .option('--description <desc>', 'Phase description')
+    .action(async (templateId, opts) => {
+    try {
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        if (!t.definition.phases)
+            t.definition.phases = [];
+        if (t.definition.phases.find((p) => p.name === opts.name)) {
+            console.error(chalk.red(`Phase "${opts.name}" already exists`));
+            process.exit(1);
+        }
+        const phase = {
+            id: crypto.randomUUID(),
+            name: opts.name,
+            description: opts.description || '',
+            deliverables: [],
+            steps: [],
+        };
+        t.definition.phases.push(phase);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Added phase: ${opts.name}`));
+        console.log(`  ID: ${phase.id}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('remove-phase')
+    .description('Remove a phase from a template. Blocked if the phase contains steps unless --force is used. Template must be in draft status. Use "tpl show" to find phase IDs.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--phase <phaseId>', 'Phase ID (from "tpl show" output)')
+    .option('--force', 'Remove even if phase contains steps')
+    .action(async (templateId, opts) => {
+    try {
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        const idx = (t.definition.phases || []).findIndex((p) => p.id === opts.phase);
+        if (idx === -1) {
+            console.error(chalk.red(`Phase "${opts.phase}" not found`));
+            process.exit(1);
+        }
+        const phase = t.definition.phases[idx];
+        if (phase.steps?.length && !opts.force) {
+            console.error(chalk.yellow(`Phase "${phase.name}" has ${phase.steps.length} steps`));
+            console.error(chalk.yellow('Use --force to remove anyway'));
+            process.exit(1);
+        }
+        t.definition.phases.splice(idx, 1);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Removed phase: ${phase.name}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('edit-phase')
+    .description('Edit a phase name or description. Template must be in draft status. Provide at least one of --name or --description.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--phase <phaseId>', 'Phase ID (from "tpl show" output)')
+    .option('--name <name>', 'New phase name (must be unique within the template)')
+    .option('--description <desc>', 'New phase description')
+    .action(async (templateId, opts) => {
+    try {
+        if (!opts.name && opts.description == null) {
+            console.error(chalk.red('Provide --name and/or --description'));
+            process.exit(1);
+        }
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        const phase = findPhaseById(t.definition, opts.phase);
+        if (!phase) {
+            console.error(chalk.red(`Phase "${opts.phase}" not found`));
+            process.exit(1);
+        }
+        if (opts.name) {
+            if (t.definition.phases.find((p) => p.id !== opts.phase && p.name === opts.name)) {
+                console.error(chalk.red(`Phase name "${opts.name}" already exists`));
+                process.exit(1);
+            }
+            phase.name = opts.name;
+        }
+        if (opts.description != null)
+            phase.description = opts.description;
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Updated phase: ${phase.name}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('add-step')
+    .description('Add a step to a phase. Template must be in draft status. Step names must be unique within their phase. Returns the generated step ID needed by I/O commands (add-output, add-input, etc.). Use "tpl show" or "tpl steps" to find existing step IDs.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--phase <phaseId>', 'Phase ID (from "tpl show" or "tpl add-phase" output)')
+    .requiredOption('--name <name>', 'Step name (must be unique within the phase)')
+    .option('--type <type>', 'Step type: human (manual task), agent (AI agent), script (automated), gate (approval checkpoint)', 'human')
+    .option('--role <role>', 'Role or agent name (e.g., "kate", "marco", "dev-team")')
+    .option('--description <desc>', 'Step description')
+    .option('--reviewer <reviewer>', 'Reviewer role for review steps')
+    .option('--max-review-cycles <n>', 'Max review cycles before auto-approval', '0')
+    .option('--parallel-group <group>', 'Group name for parallel execution (steps in the same group run concurrently)')
+    .action(async (templateId, opts) => {
+    try {
+        if (!VALID_STEP_TYPES.includes(opts.type)) {
+            console.error(chalk.red(`Invalid step type "${opts.type}". Valid: ${VALID_STEP_TYPES.join(', ')}`));
+            process.exit(1);
+        }
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        const phase = findPhaseById(t.definition, opts.phase);
+        if (!phase) {
+            console.error(chalk.red(`Phase "${opts.phase}" not found`));
+            process.exit(1);
+        }
+        if (!phase.steps)
+            phase.steps = [];
+        if (phase.steps.find((s) => s.name === opts.name)) {
+            console.error(chalk.red(`Step "${opts.name}" already exists in phase "${phase.name}"`));
+            process.exit(1);
+        }
+        const step = {
+            id: crypto.randomUUID(),
+            name: opts.name,
+            description: opts.description || '',
+            step_type: opts.type,
+            role: opts.role || 'unassigned',
+            inputs: [],
+            outputs: [],
+            sections: '',
+            reviewer: opts.reviewer || null,
+            max_review_cycles: parseInt(opts.maxReviewCycles) || 0,
+            execution_config: null,
+            parallel_group: opts.parallelGroup || null,
+            sort_order: phase.steps.length,
+        };
+        phase.steps.push(step);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Added step: ${opts.name} (${opts.type}) to phase ${phase.name}`));
+        console.log(`  ID: ${step.id}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('remove-step')
+    .description('Remove a step from a template. Blocked if other steps reference this step\'s outputs as inputs unless --force is used. Template must be in draft status. Use "tpl steps" to find step IDs.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--step <stepId>', 'Step ID (from "tpl steps" output)')
+    .option('--force', 'Remove even if other steps reference this step\'s outputs')
+    .action(async (templateId, opts) => {
+    try {
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        // Find the step and its phase
+        let targetPhase = null;
+        let stepIdx = -1;
+        for (const phase of t.definition.phases || []) {
+            const idx = (phase.steps || []).findIndex((s) => s.id === opts.step);
+            if (idx !== -1) {
+                targetPhase = phase;
+                stepIdx = idx;
+                break;
+            }
+        }
+        if (!targetPhase) {
+            console.error(chalk.red(`Step "${opts.step}" not found`));
+            process.exit(1);
+        }
+        const step = targetPhase.steps[stepIdx];
+        // Check for references from other steps
+        const refs = allSteps(t.definition).filter((s) => s.id !== step.id && (s.inputs || []).some((inp) => inp.source_step_id === step.id));
+        if (refs.length && !opts.force) {
+            console.error(chalk.yellow(`Step "${step.name}" is referenced by: ${refs.map((r) => r.name).join(', ')}`));
+            console.error(chalk.yellow('Use --force to remove anyway'));
+            process.exit(1);
+        }
+        targetPhase.steps.splice(stepIdx, 1);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Removed step: ${step.name}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('edit-step')
+    .description('Edit step properties. Template must be in draft status. Provide at least one field to update. Use "tpl steps" to find step IDs.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--step <stepId>', 'Step ID (from "tpl steps" output)')
+    .option('--name <name>', 'New step name (must be unique within the phase)')
+    .option('--type <type>', 'Step type: human, agent, script, gate')
+    .option('--role <role>', 'Role or agent name')
+    .option('--description <desc>', 'Description')
+    .option('--reviewer <reviewer>', 'Reviewer role (empty string to clear)')
+    .option('--max-review-cycles <n>', 'Max review cycles')
+    .option('--parallel-group <group>', 'Parallel execution group (empty string to clear)')
+    .action(async (templateId, opts) => {
+    try {
+        const hasUpdate = opts.name || opts.type || opts.role || opts.description != null
+            || opts.reviewer != null || opts.maxReviewCycles != null || opts.parallelGroup != null;
+        if (!hasUpdate) {
+            console.error(chalk.red('Provide at least one field to update'));
+            process.exit(1);
+        }
+        if (opts.type && !VALID_STEP_TYPES.includes(opts.type)) {
+            console.error(chalk.red(`Invalid step type "${opts.type}". Valid: ${VALID_STEP_TYPES.join(', ')}`));
+            process.exit(1);
+        }
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        const step = findStepById(t.definition, opts.step);
+        if (!step) {
+            console.error(chalk.red(`Step "${opts.step}" not found`));
+            process.exit(1);
+        }
+        if (opts.name) {
+            // Check uniqueness within the step's phase
+            for (const phase of t.definition.phases || []) {
+                if (phase.steps?.find((s) => s.id === step.id)) {
+                    if (phase.steps.find((s) => s.id !== step.id && s.name === opts.name)) {
+                        console.error(chalk.red(`Step name "${opts.name}" already exists in phase "${phase.name}"`));
+                        process.exit(1);
+                    }
+                    break;
+                }
+            }
+            step.name = opts.name;
+        }
+        if (opts.type)
+            step.step_type = opts.type;
+        if (opts.role)
+            step.role = opts.role;
+        if (opts.description != null)
+            step.description = opts.description;
+        if (opts.reviewer != null)
+            step.reviewer = opts.reviewer || null;
+        if (opts.maxReviewCycles != null)
+            step.max_review_cycles = parseInt(opts.maxReviewCycles) || 0;
+        if (opts.parallelGroup != null)
+            step.parallel_group = opts.parallelGroup || null;
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Updated step: ${step.name}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+// ── Template I/O commands ──────────────────────────────────
+templates
+    .command('steps')
+    .description('List step IDs and names in a template. Use this to discover step IDs needed by --step options in add-output, add-input, remove-step, edit-step, etc.')
+    .argument('<id>', 'Template ID')
+    .action(async (id) => {
+    try {
+        const data = await api('GET', `/api/pipeline-templates/${id}`);
+        const steps = allSteps(data.template.definition);
+        if (!steps.length) {
+            console.log(chalk.yellow('No steps'));
+            return;
+        }
+        for (const s of steps) {
+            console.log(`  ${chalk.dim(s.id)}  ${s.name} [${s.role || 'unassigned'}]`);
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('add-output')
+    .description('Declare what a step produces. Outputs can be consumed by downstream steps via add-input. Template must be in draft status. Output names must be unique within the step.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--step <stepId>', 'Step ID (from "tpl steps" output)')
+    .requiredOption('--name <name>', 'Output name (unique within the step, e.g., "requirements", "metrics_data")')
+    .requiredOption('--type <type>', 'Data type: text, markdown, number, boolean, url, json, object, array')
+    .option('--description <desc>', 'Human-readable description of what this output contains')
+    .option('--optional', 'Mark as not required (default: required)')
+    .option('--format <format>', 'Format hint: file_path, commit_sha, semver, date, datetime, email, integer, percentage')
+    .action(async (templateId, opts) => {
+    try {
+        if (!VALID_IO_TYPES.includes(opts.type)) {
+            console.error(chalk.red(`Invalid type "${opts.type}". Valid: ${VALID_IO_TYPES.join(', ')}`));
+            process.exit(1);
+        }
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        const step = findStepById(t.definition, opts.step);
+        if (!step) {
+            console.error(chalk.red(`Step "${opts.step}" not found`));
+            process.exit(1);
+        }
+        if (!step.outputs)
+            step.outputs = [];
+        if (step.outputs.find((o) => o.name === opts.name)) {
+            console.error(chalk.red(`Output "${opts.name}" already exists on step "${step.name}"`));
+            process.exit(1);
+        }
+        const output = { name: opts.name, type: opts.type, required: !opts.optional };
+        if (opts.description)
+            output.description = opts.description;
+        if (opts.format)
+            output.format = opts.format;
+        step.outputs.push(output);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Added output → ${opts.name} (${opts.type}) to ${step.name}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('remove-output')
+    .description('Remove an output declaration from a step. Blocked if downstream steps consume this output via add-input unless --force is used. Template must be in draft status.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--step <stepId>', 'Step ID (from "tpl steps" output)')
+    .requiredOption('--name <name>', 'Output name to remove')
+    .option('--force', 'Remove even if downstream steps reference this output')
+    .action(async (templateId, opts) => {
+    try {
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        const step = findStepById(t.definition, opts.step);
+        if (!step) {
+            console.error(chalk.red(`Step "${opts.step}" not found`));
+            process.exit(1);
+        }
+        const idx = (step.outputs || []).findIndex((o) => o.name === opts.name);
+        if (idx === -1) {
+            console.error(chalk.red(`Output "${opts.name}" not found on step "${step.name}"`));
+            process.exit(1);
+        }
+        // Check for downstream references
+        const refs = allSteps(t.definition).filter((s) => (s.inputs || []).some((inp) => inp.source_step_id === step.id && inp.source_output_name === opts.name));
+        if (refs.length && !opts.force) {
+            console.error(chalk.yellow(`Output "${opts.name}" is referenced by: ${refs.map((r) => r.name).join(', ')}`));
+            console.error(chalk.yellow('Use --force to remove anyway'));
+            process.exit(1);
+        }
+        step.outputs.splice(idx, 1);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Removed output → ${opts.name} from ${step.name}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('add-input')
+    .description('Declare what a step consumes. Two modes (mutually exclusive):\n' +
+    '  Step-sourced: --source-step + --source-output (consumes output from another step)\n' +
+    '  Pipeline-sourced: --pipeline-input (consumes a template-level input)\n' +
+    'Validates that the source step/output/pipeline-input exists. Template must be in draft status.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--step <stepId>', 'Step ID receiving the input (from "tpl steps" output)')
+    .requiredOption('--name <name>', 'Local input name (unique within the step)')
+    .option('--source-step <stepId>', 'Upstream step ID that produces the data (use with --source-output)')
+    .option('--source-output <name>', 'Output name on the source step (use with --source-step)')
+    .option('--pipeline-input <name>', 'Pipeline-level input name (use instead of --source-step/--source-output)')
+    .option('--description <desc>', 'What this data is used for')
+    .option('--optional', 'Mark as not required (default: required)')
+    .action(async (templateId, opts) => {
+    try {
+        const hasSrc = opts.sourceStep || opts.sourceOutput;
+        const hasPipeline = opts.pipelineInput;
+        if (!hasSrc && !hasPipeline) {
+            console.error(chalk.red('Provide either --source-step + --source-output or --pipeline-input'));
+            process.exit(1);
+        }
+        if (hasSrc && hasPipeline) {
+            console.error(chalk.red('Cannot use both --source-step and --pipeline-input'));
+            process.exit(1);
+        }
+        if (hasSrc && (!opts.sourceStep || !opts.sourceOutput)) {
+            console.error(chalk.red('Both --source-step and --source-output are required for step-sourced inputs'));
+            process.exit(1);
+        }
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        const step = findStepById(t.definition, opts.step);
+        if (!step) {
+            console.error(chalk.red(`Step "${opts.step}" not found`));
+            process.exit(1);
+        }
+        if (!step.inputs)
+            step.inputs = [];
+        if (step.inputs.find((i) => i.name === opts.name)) {
+            console.error(chalk.red(`Input "${opts.name}" already exists on step "${step.name}"`));
+            process.exit(1);
+        }
+        // Validate references
+        if (opts.sourceStep) {
+            if (opts.sourceStep === step.id) {
+                console.error(chalk.red('Cannot reference own step (self-reference)'));
+                process.exit(1);
+            }
+            const srcStep = findStepById(t.definition, opts.sourceStep);
+            if (!srcStep) {
+                console.error(chalk.red(`Source step "${opts.sourceStep}" not found`));
+                process.exit(1);
+            }
+            if (!(srcStep.outputs || []).find((o) => o.name === opts.sourceOutput)) {
+                console.error(chalk.red(`Output "${opts.sourceOutput}" not declared on step "${srcStep.name}"`));
+                process.exit(1);
+            }
+        }
+        if (opts.pipelineInput) {
+            const pInputs = t.definition.inputs || [];
+            if (!pInputs.find((i) => i.name === opts.pipelineInput)) {
+                console.error(chalk.red(`Pipeline input "${opts.pipelineInput}" not found. Add it first with tpl add-pipeline-input`));
+                process.exit(1);
+            }
+        }
+        const input = { name: opts.name, required: !opts.optional };
+        if (opts.sourceStep) {
+            input.source_step_id = opts.sourceStep;
+            input.source_output_name = opts.sourceOutput;
+        }
+        else {
+            input.pipeline_input = opts.pipelineInput;
+        }
+        if (opts.description)
+            input.description = opts.description;
+        step.inputs.push(input);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        if (opts.sourceStep) {
+            const srcStep = findStepById(t.definition, opts.sourceStep);
+            console.log(chalk.green(`Added input ← ${opts.name} ← ${srcStep.name}.${opts.sourceOutput} to ${step.name}`));
+        }
+        else {
+            console.log(chalk.green(`Added input ← ${opts.name} ← pipeline.${opts.pipelineInput} to ${step.name}`));
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('remove-input')
+    .description('Remove an input declaration from a step. Template must be in draft status.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--step <stepId>', 'Step ID (from "tpl steps" output)')
+    .requiredOption('--name <name>', 'Input name to remove')
+    .action(async (templateId, opts) => {
+    try {
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        const step = findStepById(t.definition, opts.step);
+        if (!step) {
+            console.error(chalk.red(`Step "${opts.step}" not found`));
+            process.exit(1);
+        }
+        const idx = (step.inputs || []).findIndex((i) => i.name === opts.name);
+        if (idx === -1) {
+            console.error(chalk.red(`Input "${opts.name}" not found on step "${step.name}"`));
+            process.exit(1);
+        }
+        step.inputs.splice(idx, 1);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Removed input ← ${opts.name} from ${step.name}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('add-pipeline-input')
+    .description('Add a template-level input that is provided when creating a pipeline instance. Steps can consume these via "tpl add-input --pipeline-input <name>". Template must be in draft status.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--name <name>', 'Input name (unique within the template)')
+    .requiredOption('--type <type>', 'Data type: text, markdown, number, boolean, url, json, object, array')
+    .option('--description <desc>', 'Human-readable description')
+    .option('--optional', 'Not required at instance creation (default: required)')
+    .option('--default <value>', 'Default value')
+    .action(async (templateId, opts) => {
+    try {
+        if (!VALID_IO_TYPES.includes(opts.type)) {
+            console.error(chalk.red(`Invalid type "${opts.type}". Valid: ${VALID_IO_TYPES.join(', ')}`));
+            process.exit(1);
+        }
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        if (!t.definition.inputs)
+            t.definition.inputs = [];
+        if (t.definition.inputs.find((i) => i.name === opts.name)) {
+            console.error(chalk.red(`Pipeline input "${opts.name}" already exists`));
+            process.exit(1);
+        }
+        const input = { name: opts.name, type: opts.type, required: !opts.optional };
+        if (opts.description)
+            input.description = opts.description;
+        if (opts.default != null)
+            input.default_value = opts.default;
+        t.definition.inputs.push(input);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Added pipeline input: ${opts.name} (${opts.type})`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('remove-pipeline-input')
+    .description('Remove a template-level input. Blocked if steps reference this input via --pipeline-input unless --force is used. Template must be in draft status.')
+    .argument('<templateId>', 'Template ID')
+    .requiredOption('--name <name>', 'Pipeline input name to remove')
+    .option('--force', 'Remove even if steps reference this input')
+    .action(async (templateId, opts) => {
+    try {
+        const data = await api('GET', `/api/pipeline-templates/${templateId}`);
+        const t = data.template;
+        requireDraftStatus(t);
+        const inputs = t.definition.inputs || [];
+        const idx = inputs.findIndex((i) => i.name === opts.name);
+        if (idx === -1) {
+            console.error(chalk.red(`Pipeline input "${opts.name}" not found`));
+            process.exit(1);
+        }
+        // Block if steps reference it unless --force
+        const refs = allSteps(t.definition).filter((s) => (s.inputs || []).some((inp) => inp.pipeline_input === opts.name));
+        if (refs.length && !opts.force) {
+            console.error(chalk.yellow(`Pipeline input "${opts.name}" is referenced by: ${refs.map((r) => r.name).join(', ')}`));
+            console.error(chalk.yellow('Use --force to remove anyway'));
+            process.exit(1);
+        }
+        inputs.splice(idx, 1);
+        await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
+        console.log(chalk.green(`Removed pipeline input: ${opts.name}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+templates
+    .command('validate')
+    .description('Validate template I/O contracts. Checks for: circular dependencies between steps, missing source step/output references, self-references, duplicate input names per step. Also reports warnings for unreferenced outputs and info for steps with no outputs declared. Run before activating to catch errors early.')
+    .argument('<id>', 'Template ID')
+    .action(async (id) => {
+    try {
+        const data = await api('GET', `/api/pipeline-templates/${id}`);
+        const t = data.template;
+        const steps = allSteps(t.definition);
+        const pipelineInputs = t.definition.inputs || [];
+        console.log(`Validating: ${chalk.cyan(t.name)} (${id})\n`);
+        let passed = 0, warnings = 0, infos = 0, errors = 0;
+        // Check for duplicate input names per step
+        let hasDupes = false;
+        for (const step of steps) {
+            const names = (step.inputs || []).map((i) => i.name);
+            const dupes = names.filter((n, i) => names.indexOf(n) !== i);
+            if (dupes.length) {
+                console.log(chalk.red(`  ✗ Step "${step.name}" has duplicate input names: ${[...new Set(dupes)].join(', ')}`));
+                hasDupes = true;
+                errors++;
+            }
+        }
+        if (!hasDupes) {
+            console.log(chalk.green('  ✓ No duplicate input names'));
+            passed++;
+        }
+        // Check self-references
+        let hasSelfRef = false;
+        for (const step of steps) {
+            for (const inp of step.inputs || []) {
+                if (inp.source_step_id === step.id) {
+                    console.log(chalk.red(`  ✗ Step "${step.name}" input "${inp.name}" references itself`));
+                    hasSelfRef = true;
+                    errors++;
+                }
+            }
+        }
+        if (!hasSelfRef) {
+            console.log(chalk.green('  ✓ No self-references'));
+            passed++;
+        }
+        // Check all input references resolve
+        let hasUnresolved = false;
+        for (const step of steps) {
+            for (const inp of step.inputs || []) {
+                if (inp.source_step_id) {
+                    const src = findStepById(t.definition, inp.source_step_id);
+                    if (!src) {
+                        console.log(chalk.red(`  ✗ Step "${step.name}" input "${inp.name}" references missing step "${inp.source_step_id}"`));
+                        hasUnresolved = true;
+                        errors++;
+                    }
+                    else if (!(src.outputs || []).find((o) => o.name === inp.source_output_name)) {
+                        console.log(chalk.red(`  ✗ Step "${step.name}" input "${inp.name}" references missing output "${inp.source_output_name}" on step "${src.name}"`));
+                        hasUnresolved = true;
+                        errors++;
+                    }
+                }
+                if (inp.pipeline_input) {
+                    if (!pipelineInputs.find((p) => p.name === inp.pipeline_input)) {
+                        console.log(chalk.red(`  ✗ Step "${step.name}" input "${inp.name}" references missing pipeline input "${inp.pipeline_input}"`));
+                        hasUnresolved = true;
+                        errors++;
+                    }
+                }
+            }
+        }
+        if (!hasUnresolved) {
+            console.log(chalk.green('  ✓ All input references resolve'));
+            passed++;
+        }
+        // Cycle detection via topological sort (Kahn's algorithm)
+        const stepIds = steps.map((s) => s.id);
+        const adj = new Map();
+        const inDeg = new Map();
+        for (const sid of stepIds) {
+            adj.set(sid, []);
+            inDeg.set(sid, 0);
+        }
+        for (const step of steps) {
+            for (const inp of step.inputs || []) {
+                if (inp.source_step_id && stepIds.includes(inp.source_step_id)) {
+                    adj.get(inp.source_step_id).push(step.id);
+                    inDeg.set(step.id, (inDeg.get(step.id) || 0) + 1);
+                }
+            }
+        }
+        const queue = [];
+        for (const [id, deg] of inDeg) {
+            if (deg === 0)
+                queue.push(id);
+        }
+        let visited = 0;
+        while (queue.length) {
+            const cur = queue.shift();
+            visited++;
+            for (const next of adj.get(cur) || []) {
+                const nd = inDeg.get(next) - 1;
+                inDeg.set(next, nd);
+                if (nd === 0)
+                    queue.push(next);
+            }
+        }
+        if (visited < stepIds.length) {
+            console.log(chalk.red('  ✗ Cycle detected in step dependencies'));
+            errors++;
+        }
+        else {
+            console.log(chalk.green('  ✓ No cycles detected'));
+            passed++;
+        }
+        // Unreferenced outputs (warning)
+        for (const step of steps) {
+            for (const output of step.outputs || []) {
+                const referenced = steps.some((s) => (s.inputs || []).some((inp) => inp.source_step_id === step.id && inp.source_output_name === output.name));
+                if (!referenced) {
+                    console.log(chalk.yellow(`  ⚠ Step "${step.name}" output "${output.name}" is not consumed by any downstream step`));
+                    warnings++;
+                }
+            }
+        }
+        // Steps with no outputs (info)
+        for (const step of steps) {
+            if (!step.outputs?.length) {
+                console.log(chalk.dim(`  ℹ Step "${step.name}" has no outputs declared`));
+                infos++;
+            }
+        }
+        console.log(`\n${passed} check${passed !== 1 ? 's' : ''} passed${errors ? `, ${errors} error${errors !== 1 ? 's' : ''}` : ''}${warnings ? `, ${warnings} warning${warnings !== 1 ? 's' : ''}` : ''}${infos ? `, ${infos} info` : ''}`);
+        if (errors)
+            process.exit(1);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 // ── Pipelines ──────────────────────────────────────────────
 const pipelines = program.command('pipelines').alias('pl').description('Pipeline instance commands');
 pipelines