@formigio/fazemos-cli 0.5.1 → 0.6.0

package/dist/index.js

@@ -5,7 +5,7 @@ import { config, getEnv, getToken, getActiveOrgId, setActiveOrgId, addEnvironmen
 import { login, signup, confirmSignup, adminLogin } from './auth.js';
 import { api, ApiError } from './api.js';
 import { execSync } from 'child_process';
-import { readFileSync, readdirSync } from 'fs';
+import { readFileSync, readdirSync, writeFileSync, mkdirSync, existsSync, statSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, resolve, basename } from 'path';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -25,6 +25,58 @@ function parseJson(val, flag) {
         process.exit(1);
     }
 }
+/** Resolve a value that may be `@filepath` (reads file contents) or inline text. */
+function resolveFileOrInline(val) {
+    if (val.startsWith('@')) {
+        const filePath = resolve(val.slice(1));
+        try {
+            return readFileSync(filePath, 'utf-8');
+        }
+        catch (err) {
+            throw new Error(`Cannot read --sections file "${filePath}": ${err.message}`);
+        }
+    }
+    return val;
+}
+/**
+ * Make a string safe to use as a filename: strip path separators and other
+ * shell-hostile characters, reject `..` traversal. Used by `agents export` so
+ * an agent display_name like `foo/bar` or `..` cannot escape the output dir.
+ */
+function safeFileName(name) {
+    const cleaned = name.replace(/[^\w.\- ]+/g, '_').trim();
+    if (!cleaned || cleaned === '.' || cleaned === '..') {
+        throw new Error(`Cannot derive safe filename from "${name}"`);
+    }
+    return cleaned;
+}
+/**
+ * Build the markdown content for an exported agent. With `includeFrontmatter`,
+ * prepends YAML frontmatter reconstructed from `agent_config`. Note: only
+ * `name` round-trips through `upload-all` today — the other fields are
+ * informational on import. String values are JSON-stringified to keep YAML
+ * valid even if a model name or role contains a colon.
+ */
+function buildAgentFileContent(agent, includeFrontmatter) {
+    const prompt = agent.agent_config?.systemPrompt || '';
+    if (!includeFrontmatter)
+        return prompt + '\n';
+    const ac = agent.agent_config || {};
+    const fm = ['---'];
+    fm.push(`name: ${JSON.stringify(agent.display_name)}`);
+    if (ac.model)
+        fm.push(`model: ${JSON.stringify(ac.model)}`);
+    if (ac.maxBudgetUsd != null)
+        fm.push(`maxBudgetUsd: ${ac.maxBudgetUsd}`);
+    if (ac.maxTurns != null)
+        fm.push(`maxTurns: ${ac.maxTurns}`);
+    if (ac.timeoutMs != null)
+        fm.push(`timeoutMs: ${ac.timeoutMs}`);
+    if (ac.roles?.length)
+        fm.push(`roles: ${JSON.stringify(ac.roles)}`);
+    fm.push('---');
+    return fm.join('\n') + '\n\n' + prompt + '\n';
+}
 const program = new Command();
 program
     .name('fazemos')
@@ -1870,6 +1922,16 @@ function allSteps(definition) {
 function findStepById(definition, stepId) {
     return allSteps(definition).find((s) => s.id === stepId);
 }
+/**
+ * Pipeline-sourced step inputs went through a schema migration: the old
+ * shape stored the pipeline input name under `pipeline_input`; the new shape
+ * uses `source: "pipeline"` + `source_pipeline_input`. Read sites should call
+ * this helper instead of touching either field directly so both shapes work.
+ * Returns undefined for step-sourced inputs.
+ */
+function getPipelineInputName(input) {
+    return input?.source_pipeline_input ?? input?.pipeline_input;
+}
 const VALID_IO_TYPES = ['text', 'markdown', 'number', 'boolean', 'url', 'json', 'object', 'array'];
 function requireDraftStatus(template) {
     if (template.status !== 'draft') {
@@ -1893,6 +1955,7 @@ const templates = program.command('templates').alias('tpl').description('Pipelin
     '    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 phases <id>" to list phase IDs needed by --phase options.\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
@@ -1920,7 +1983,7 @@ templates
 });
 templates
     .command('show')
-    .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.')
+    .description('Show template detail including phases, steps, I/O declarations, pipeline inputs, and revision number. 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 {
@@ -1929,7 +1992,7 @@ templates
         console.log(chalk.cyan(t.name));
         console.log(`  ID:      ${t.id}`);
         console.log(`  Status:  ${t.status}`);
-        console.log(`  Version: ${t.version}`);
+        console.log(`  Revision: ${t.version}`);
         // Pipeline-level inputs
         if (t.definition?.inputs?.length) {
             console.log(chalk.cyan('\n  Pipeline Inputs:'));
@@ -1942,7 +2005,7 @@ templates
         }
         if (t.definition?.phases) {
             for (const phase of t.definition.phases) {
-                console.log(chalk.cyan(`\n  Phase: ${phase.name}`));
+                console.log(chalk.cyan(`\n  Phase: ${phase.name}`) + chalk.dim(`  ${phase.id}`));
                 for (const step of phase.steps || []) {
                     const reviewer = step.reviewer ? ` reviewer:${step.reviewer}` : '';
                     const cycles = step.reviewer && step.max_review_cycles ? ` max-cycles:${step.max_review_cycles}` : '';
@@ -1958,8 +2021,9 @@ templates
                     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}`);
+                            const pName = getPipelineInputName(inp);
+                            if (pName) {
+                                console.log(`        ← ${inp.name} ← pipeline.${pName}`);
                             }
                             else {
                                 const srcStep = findStepById(t.definition, inp.source_step_id);
@@ -2064,13 +2128,23 @@ templates
                         description: s.description || '',
                         step_type: s.executionMode === 'script' ? 'script' : (s.agent ? 'agent' : 'human'),
                         role: s.role || s.agent || 'unassigned',
-                        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,
-                        })),
+                        inputs: (s.inputs || []).map((inp) => {
+                            const pipelineName = getPipelineInputName(inp);
+                            return {
+                                name: inp.name,
+                                ...(inp.source_step_id ? {
+                                    source: 'step',
+                                    source_step_id: idMap.get(inp.source_step_id) || inp.source_step_id,
+                                    source_output_name: inp.source_output_name,
+                                } : {}),
+                                ...(pipelineName ? {
+                                    source: 'pipeline',
+                                    source_pipeline_input: pipelineName,
+                                } : {}),
+                                ...(inp.description ? { description: inp.description } : {}),
+                                required: inp.required !== false,
+                            };
+                        }),
                         outputs: (s.outputs || []).map((o) => ({
                             name: o.name,
                             type: o.type || 'text',
@@ -2138,7 +2212,7 @@ templates
 // ── 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.')
+    .description('Update template name or description. Works on any status (draft, active, or archived). Does not modify the definition or bump the revision counter.')
     .argument('<id>', 'Template ID')
     .option('-n, --name <name>', 'New name')
     .option('-d, --description <desc>', 'New description')
@@ -2225,9 +2299,9 @@ templates
 });
 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.')
+    .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 phases" or "tpl show" to find phase IDs.')
     .argument('<templateId>', 'Template ID')
-    .requiredOption('--phase <phaseId>', 'Phase ID (from "tpl show" output)')
+    .requiredOption('--phase <phaseId>', 'Phase ID (from "tpl phases" or "tpl show" output)')
     .option('--force', 'Remove even if phase contains steps')
     .action(async (templateId, opts) => {
     try {
@@ -2256,9 +2330,9 @@ templates
 });
 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.')
+    .description('Edit a phase name or description. Template must be in draft status. Provide at least one of --name or --description. Use "tpl phases" to find phase IDs.')
     .argument('<templateId>', 'Template ID')
-    .requiredOption('--phase <phaseId>', 'Phase ID (from "tpl show" output)')
+    .requiredOption('--phase <phaseId>', 'Phase ID (from "tpl phases" or "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) => {
@@ -2294,9 +2368,9 @@ templates
 });
 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.')
+    .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 --sections to provide agent instructions (inline or @filepath). Use --after to control ordering. 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('--phase <phaseId>', 'Phase ID (from "tpl phases", "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")')
@@ -2309,6 +2383,9 @@ templates
     .option('--timeout <seconds>', 'Timeout in seconds for script steps', parseNumber)
     .option('--working-dir <dir>', 'Working directory for script steps (absolute path)')
     .option('--env <json>', 'Environment variables for script steps as JSON (e.g., \'{"KEY":"value"}\')')
+    .option('--sections <text>', 'Agent instructions / step content. Use @filepath to load from a file (e.g., --sections @steps/review.md)')
+    .option('--after <stepId>', 'Insert after this step within the same phase (sets sort_order to target + 1, shifts subsequent steps). Target must live in the phase named by --phase.')
+    .option('--sort-order <n>', 'Set sort_order directly (lower-level escape hatch)', parseNumber)
     .option('--agent-config <json>', 'Per-step agent config overrides as JSON (e.g., \'{"model":"opus","maxBudgetUsd":20}\'). Overrides agent member defaults for: model, maxBudgetUsd, maxTurns, timeoutMs, cwd, repos')
     .action(async (templateId, opts) => {
     try {
@@ -2349,6 +2426,9 @@ templates
                 execConfig.env = parseJson(opts.env, '--env');
             }
         }
+        // Default sort_order: max existing + 1, so non-contiguous gaps don't
+        // cause new steps to collide with existing ones (e.g. after a --after insert).
+        const maxSortOrder = phase.steps.reduce((m, s) => Math.max(m, s.sort_order ?? 0), -1);
         const step = {
             id: crypto.randomUUID(),
             name: opts.name,
@@ -2357,16 +2437,37 @@ templates
             role: opts.role || 'unassigned',
             inputs: [],
             outputs: [],
-            sections: '',
+            sections: opts.sections ? resolveFileOrInline(opts.sections) : '',
             reviewer: opts.reviewer || null,
             max_review_cycles: parseInt(opts.maxReviewCycles) || 0,
             execution_config: execConfig,
             parallel_group: opts.parallelGroup || null,
-            sort_order: phase.steps.length,
+            sort_order: maxSortOrder + 1,
         };
         if (opts.agentConfig)
             step.agent_config = parseJson(opts.agentConfig, '--agent-config');
+        // Positioning: --after or --sort-order
+        if (opts.after && opts.sortOrder !== undefined) {
+            console.error(chalk.red('Cannot use both --after and --sort-order'));
+            process.exit(1);
+        }
+        if (opts.after) {
+            const target = phase.steps.find((s) => s.id === opts.after);
+            if (!target) {
+                console.error(chalk.red(`Step "${opts.after}" not found in phase "${phase.name}"`));
+                process.exit(1);
+            }
+            step.sort_order = target.sort_order + 1;
+            for (const s of phase.steps) {
+                if (s.sort_order >= step.sort_order)
+                    s.sort_order++;
+            }
+        }
+        else if (opts.sortOrder !== undefined) {
+            step.sort_order = opts.sortOrder;
+        }
         phase.steps.push(step);
+        phase.steps.sort((a, b) => a.sort_order - b.sort_order);
         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}`);
@@ -2421,7 +2522,7 @@ templates
 });
 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.')
+    .description('Edit step properties including sections (agent instructions). 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)')
@@ -2436,13 +2537,14 @@ templates
     .option('--timeout <seconds>', 'Timeout in seconds for script steps', parseNumber)
     .option('--working-dir <dir>', 'Working directory for script steps (absolute path)')
     .option('--env <json>', 'Environment variables for script steps as JSON')
+    .option('--sections <text>', 'Agent instructions / step content. Use @filepath to load from a file (e.g., --sections @steps/review.md)')
     .option('--agent-config <json>', 'Per-step agent config overrides as JSON (merges with existing)')
     .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
             || opts.image || opts.command || opts.timeout !== undefined || opts.workingDir || opts.env
-            || opts.agentConfig;
+            || opts.agentConfig || opts.sections != null;
         if (!hasUpdate) {
             console.error(chalk.red('Provide at least one field to update'));
             process.exit(1);
@@ -2504,6 +2606,9 @@ templates
                 step.execution_config.env = parseJson(opts.env, '--env');
             }
         }
+        // sections (agent instructions)
+        if (opts.sections != null)
+            step.sections = resolveFileOrInline(opts.sections);
         // agent_config overrides (merge with existing)
         if (opts.agentConfig) {
             step.agent_config = { ...(step.agent_config || {}), ...parseJson(opts.agentConfig, '--agent-config') };
@@ -2517,6 +2622,28 @@ templates
     }
 });
 // ── Template I/O commands ──────────────────────────────────
+templates
+    .command('phases')
+    .description('List phase IDs and names in a template. Use this to discover phase IDs needed by --phase options in add-step, edit-phase, remove-phase, etc.')
+    .argument('<id>', 'Template ID')
+    .action(async (id) => {
+    try {
+        const data = await api('GET', `/api/pipeline-templates/${id}`);
+        const phases = data.template.definition?.phases || [];
+        if (!phases.length) {
+            console.log(chalk.yellow('No phases'));
+            return;
+        }
+        for (const p of phases) {
+            const stepCount = (p.steps || []).length;
+            console.log(`  ${chalk.dim(p.id)}  ${p.name} ${chalk.dim(`(${stepCount} steps)`)}`);
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 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.')
@@ -2690,11 +2817,13 @@ templates
         }
         const input = { name: opts.name, required: !opts.optional };
         if (opts.sourceStep) {
+            input.source = 'step';
             input.source_step_id = opts.sourceStep;
             input.source_output_name = opts.sourceOutput;
         }
         else {
-            input.pipeline_input = opts.pipelineInput;
+            input.source = 'pipeline';
+            input.source_pipeline_input = opts.pipelineInput;
         }
         if (opts.description)
             input.description = opts.description;
@@ -2799,7 +2928,7 @@ templates
             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));
+        const refs = allSteps(t.definition).filter((s) => (s.inputs || []).some((inp) => getPipelineInputName(inp) === 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'));
@@ -2873,9 +3002,10 @@ templates
                         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}"`));
+                const pipelineName = getPipelineInputName(inp);
+                if (pipelineName) {
+                    if (!pipelineInputs.find((p) => p.name === pipelineName)) {
+                        console.log(chalk.red(`  ✗ Step "${step.name}" input "${inp.name}" references missing pipeline input "${pipelineName}"`));
                         hasUnresolved = true;
                         errors++;
                     }
@@ -4428,6 +4558,97 @@ agentsCmd
         process.exit(1);
     }
 });
+agentsCmd
+    .command('export')
+    .description('Export all agent system prompts to a directory. Default: body only (matches what upload-all consumes). Use --include-frontmatter to also write readable YAML frontmatter — note that upload-all currently only reads the `name:` field, so the other frontmatter fields are informational.')
+    .argument('<output-dir>', 'Directory to write agent .md files to (created if needed)')
+    .option('--include-frontmatter', 'Include YAML frontmatter with agent config fields (name, model, maxBudgetUsd, maxTurns, timeoutMs, roles)')
+    .action(async (outputDir, opts) => {
+    try {
+        const orgId = getActiveOrgId();
+        if (!orgId) {
+            console.error(chalk.red('No active org'));
+            process.exit(1);
+        }
+        const resolvedDir = resolve(outputDir);
+        if (existsSync(resolvedDir) && statSync(resolvedDir).isFile()) {
+            console.error(chalk.red(`"${resolvedDir}" is a file, not a directory`));
+            process.exit(1);
+        }
+        mkdirSync(resolvedDir, { recursive: true });
+        const membersData = await api('GET', `/api/organizations/${orgId}/members?type=agent`);
+        const agents = membersData.members.filter((m) => m.member_type === 'agent');
+        let exported = 0;
+        let skipped = 0;
+        const writtenFiles = new Set();
+        for (const agent of agents) {
+            const prompt = agent.agent_config?.systemPrompt;
+            if (!prompt) {
+                console.log(chalk.yellow(`  ⊘ ${agent.display_name} — no systemPrompt`));
+                skipped++;
+                continue;
+            }
+            let fileName;
+            try {
+                fileName = `${safeFileName(agent.display_name)}.md`;
+            }
+            catch (err) {
+                console.log(chalk.yellow(`  ⊘ ${agent.display_name} — ${err.message}`));
+                skipped++;
+                continue;
+            }
+            if (writtenFiles.has(fileName)) {
+                console.log(chalk.yellow(`  ⊘ ${agent.display_name} — filename "${fileName}" already written by another agent (display name collision)`));
+                skipped++;
+                continue;
+            }
+            const content = buildAgentFileContent(agent, !!opts.includeFrontmatter);
+            writeFileSync(resolve(resolvedDir, fileName), content, 'utf-8');
+            writtenFiles.add(fileName);
+            console.log(chalk.green(`  ✓ ${agent.display_name}`));
+            exported++;
+        }
+        console.log(`\n${exported} agents exported to ${resolvedDir}${skipped ? `, ${skipped} skipped` : ''}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+agentsCmd
+    .command('export-definition')
+    .description('Export a single agent system prompt to a file. Matches agent by display name (case-insensitive). Default: body only. Use --include-frontmatter to also write readable YAML frontmatter — note that upload-definition only reads the body, so the frontmatter fields are informational.')
+    .argument('<name>', 'Agent display name')
+    .argument('<file>', 'Output file path')
+    .option('--include-frontmatter', 'Include YAML frontmatter with agent config fields (name, model, maxBudgetUsd, maxTurns, timeoutMs, roles)')
+    .action(async (name, file, opts) => {
+    try {
+        const orgId = getActiveOrgId();
+        if (!orgId) {
+            console.error(chalk.red('No active org'));
+            process.exit(1);
+        }
+        const membersData = await api('GET', `/api/organizations/${orgId}/members?type=agent`);
+        const norm = (s) => s.toLowerCase().replace(/[-_\s]+/g, ' ').trim();
+        const agent = membersData.members.find((m) => norm(m.display_name) === norm(name));
+        if (!agent) {
+            console.error(chalk.red(`Agent "${name}" not found`));
+            process.exit(1);
+        }
+        const prompt = agent.agent_config?.systemPrompt;
+        if (!prompt) {
+            console.error(chalk.red(`Agent "${agent.display_name}" has no systemPrompt`));
+            process.exit(1);
+        }
+        const content = buildAgentFileContent(agent, !!opts.includeFrontmatter);
+        writeFileSync(resolve(file), content, 'utf-8');
+        console.log(chalk.green(`Exported ${agent.display_name} to ${resolve(file)} (${prompt.length} chars)`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 // ── Health ──────────────────────────────────────────────────
 program
     .command('health')