@formigio/fazemos-cli 0.10.12 → 0.10.14

package/dist/index.js

@@ -22,6 +22,56 @@ function parseNumber(val) {
         throw new Error(`Invalid number: ${val}`);
     return n;
 }
+/**
+ * OPS-2 — Manual Interventions KPI cell formatter.
+ *
+ * Single source of CLI truth for the tri-state coloring rule encoded in
+ * rul_intervention_chip_thresholds_v1. Mirrors the web InterventionChip
+ * thresholds so the CLI MI column on `pl list`, the header line on
+ * `pl show`, and the `ops interventions` table all render the same way:
+ *
+ *   null  → `—` (no color)  — pre-migration row or unknown state
+ *   0     → green            — clean run
+ *   1-3   → amber            — some operator help
+ *   ≥4    → red              — carried
+ *   >999  → `999+`           — cap per rul_intervention_chip_count_cap_999plus
+ *
+ * Width: 5 chars (right-padded inside the chalk color call so colors don't
+ * count against the visible width). Callers can wrap with additional text
+ * (e.g. `MI:${cell}`) without breaking alignment.
+ */
+function formatManualInterventionCell(count) {
+    if (count === null || count === undefined) {
+        return chalk.gray('—'.padEnd(5));
+    }
+    const display = count > 999 ? '999+' : String(count);
+    const padded = display.padEnd(5);
+    if (count === 0)
+        return chalk.green(padded);
+    if (count <= 3)
+        return chalk.yellow(padded);
+    return chalk.red(padded);
+}
+/**
+ * OPS-2 — parse a duration string ('24h', '7d', '30d', '90d', etc.) into
+ * an ISO-8601 datetime `since` value for the GET /api/ops/manual-interventions
+ * `since` query param.
+ *
+ * Accepted units: `h` (hours), `d` (days), `w` (weeks). Unrecognised values
+ * throw and surface to the operator via the standard error path.
+ */
+function parseSinceDuration(val) {
+    const m = /^(\d+)([hdw])$/.exec(val.trim());
+    if (!m) {
+        throw new Error(`Invalid --since "${val}". Expected forms like 24h, 7d, 30d, 4w.`);
+    }
+    const n = Number(m[1]);
+    const unit = m[2];
+    const ms = unit === 'h' ? n * 3_600_000
+        : unit === 'd' ? n * 86_400_000
+            : n * 604_800_000;
+    return new Date(Date.now() - ms).toISOString();
+}
 function parseStreamSilenceAbortMs(val) {
     const n = Number(val);
     if (!Number.isInteger(n) || n < 30000 || n > 1800000) {
@@ -2469,14 +2519,58 @@ commitments
         process.exit(1);
     }
 });
+// [F24 §3.6 / R16-R20] cm reopen — Restore an open state on a closed
+// commitment. The close event stays in the audit trail (a new audit_log
+// row records the reopen with from_state and to_state='open'). Agents
+// cannot reopen — the API's permission predicate naturally excludes
+// service principals (requireMemberId throws when req.member.id is null).
+commitments
+    .command('reopen <id>')
+    .description('Restore an open state on a closed commitment. The close event stays in the audit trail.')
+    .option('--reason <text>', 'Optional human-readable note for the audit log (max 500 chars)')
+    .option('--json', 'Print the raw API response as JSON (machine-readable)')
+    .action(async (id, opts) => {
+    try {
+        const body = {};
+        if (opts.reason)
+            body.reason = opts.reason;
+        const data = await api('PATCH', `/api/commitments/${id}/reopen`, body);
+        if (opts.json) {
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        if (data.noop) {
+            console.log(chalk.yellow('This commitment is already open. Nothing to reopen.'));
+            return;
+        }
+        const c = data.commitment;
+        const prev = data.previousCompletedAt;
+        const prevFmt = prev ? new Date(prev).toISOString().slice(0, 16).replace('T', ' ') : null;
+        const tail = prevFmt ? ` The close on ${prevFmt} stays in the audit trail.` : '';
+        console.log(chalk.green(`Reopened. Commitment ${c.id} is open again.${tail}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+// [F24 §3.4 / R13-R14] cm execute — gained `--repos` option for
+// commitment-source clone overrides (mirrors the top-level execute flag).
+// The server-side endpoint now reads agent_config.repos as a fallback
+// when no body.repos is supplied; this CLI flag is the operator-side
+// override for `fazemos cm execute -w <ws> -c <cm> --repos <repos>`.
 commitments
     .command('execute')
     .description('Trigger an agent execution for a commitment. The API determines which agent to use based on the commitment\'s configuration. For more control, use the top-level "execute" command instead.')
     .requiredOption('-w, --worksheet <id>', 'Worksheet ID')
     .requiredOption('-c, --commitment <id>', 'Commitment ID (from "cm list" or "ws show" output)')
+    .option('--repos <repos>', 'Comma-separated repo names to clone for this execution (overrides the agent\'s default agent_config.repos)', (v) => v.split(','))
     .action(async (opts) => {
     try {
-        const data = await api('POST', `/api/worksheets/${opts.worksheet}/commitments/${opts.commitment}/execute`);
+        const body = {};
+        if (opts.repos)
+            body.repos = opts.repos;
+        const data = await api('POST', `/api/worksheets/${opts.worksheet}/commitments/${opts.commitment}/execute`, body);
         console.log(chalk.green('Execution triggered'));
         if (data.execution?.id)
             console.log(`  Execution ID: ${data.execution.id}`);
@@ -3956,7 +4050,18 @@ pipelines
         }
         for (const inst of data.instances) {
             const stepInfo = inst.total_steps ? ` — step ${inst.current_step ?? '?'}/${inst.total_steps}` : '';
-            console.log(`  ${chalk.cyan(inst.name)} (${inst.status})${stepInfo}`);
+            // OPS-2 — Manual Interventions KPI. The MI column renders inline next
+            // to the instance status with the prescribed tri-state coloring:
+            //   null → `—` (no color; pre-migration row or unknown)
+            //   0    → green
+            //   1-3  → amber
+            //   ≥4   → red
+            // Capped per rul_intervention_chip_count_cap_999plus: values > 999
+            // collapse to `999+` while the underlying count remains intact in
+            // the API response and JSON output for scripts.
+            const miCell = formatManualInterventionCell(inst.manual_intervention_count);
+            const envCell = inst.env_tag ? chalk.gray(` [${inst.env_tag}]`) : '';
+            console.log(`  ${chalk.cyan(inst.name)} (${inst.status}) MI:${miCell}${envCell}${stepInfo}`);
             console.log(`    ID: ${inst.id}`);
             if (opts.expand && inst.steps?.length) {
                 for (const s of inst.steps) {
@@ -3985,6 +4090,14 @@ pipelines
         console.log(`  ID:       ${inst.id}`);
         console.log(`  Status:   ${inst.status}`);
         console.log(`  Template: ${inst.template_name || inst.template_id}`);
+        // OPS-2 — Manual Interventions KPI header line. Same coloring rule as
+        // `pl list` (null=—, 0=green, 1-3=amber, 4+=red). env_tag is surfaced
+        // alongside so operators can read prod-vs-dev at a glance (the cycle
+        // exit criterion is prod-only).
+        console.log(`  Manual Interventions: ${formatManualInterventionCell(inst.manual_intervention_count)}`);
+        if (inst.env_tag) {
+            console.log(`  Env Tag:  ${inst.env_tag}`);
+        }
         if (inst.phases?.length) {
             for (const phase of inst.phases) {
                 console.log(chalk.cyan(`\n  Phase: ${phase.name}`));
@@ -4721,7 +4834,8 @@ program
     .argument('<source-id>', 'Action, commitment, or pipeline step ID')
     .requiredOption('--agent <name>', 'Agent name or member ID')
     .option('--source-type <type>', 'Source type (action, commitment, pipeline_step)', 'action')
-    .option('--prompt <prompt>', 'Additional prompt context')
+    .option('--prompt <prompt>', 'Operator instructions for this execution. Appended to the agent\'s built prompt as a labeled "## Operator Instructions" section. Takes precedence over runtime auto-completion instructions per the precedence rule (see architecture doc).')
+    .option('--no-auto-complete', 'Suppress the runtime auto-completion instruction. The agent will not be told to mark the source done. Use this for "draft, don\'t close" workflows where a human reviews and locks. Default: off. Pipeline-step source: ignored with a warning.')
     .option('--repos <repos>', 'Comma-separated repo names to clone (overrides agent config)', (v) => v.split(','))
     .option('--model <model>', 'Model override (e.g., opus, sonnet)')
     .option('--budget <usd>', 'Max budget override in USD', parseNumber)
@@ -4732,6 +4846,22 @@ program
             console.error(chalk.red(`Invalid source type. Must be one of: ${validTypes.join(', ')}`));
             process.exit(1);
         }
+        // [F24 §3.3 / EC3 / rul_no_auto_complete_pipeline_step_ignored]
+        // --no-auto-complete is ignored for pipeline_step sources to preserve
+        // back-compat for shipped pipeline executions. Layer-1 defense:
+        // CLI prints a warning and does NOT forward the flag onto
+        // context.noAutoComplete. Layer-2 defense lives in the agent's
+        // buildSelfReportingInstructions, which gates the noAutoComplete
+        // check on source_type !== 'pipeline_step' regardless.
+        //
+        // commander.js: `--no-auto-complete` produces opts.autoComplete=false
+        // (NOT opts.noAutoComplete=true) because of the `--no-` prefix
+        // convention. We surface that as the boolean `forwardSuppress` below.
+        const operatorOptedOut = opts.autoComplete === false;
+        if (operatorOptedOut && opts.sourceType === 'pipeline_step') {
+            console.error(chalk.yellow('Warning: --no-auto-complete is ignored for pipeline_step sources; pipeline steps always auto-complete.'));
+        }
+        const forwardSuppress = operatorOptedOut && opts.sourceType !== 'pipeline_step';
         // Resolve agent name to member ID if not already a UUID
         let agentMemberId = opts.agent;
         if (!/^[0-9a-f]{8}-[0-9a-f]{4}-/.test(agentMemberId)) {
@@ -4768,8 +4898,24 @@ program
                 url: `https://github.com/formigio/${r}.git`,
                 branch: 'main',
             })),
-            cwd: '/workspace',
         };
+        // [F24 §3.2 / D8 / rul_workspace_clone_contract] cwd defaulting per
+        // resolved repo count. Pre-F24 the CLI hardcoded cwd='/workspace',
+        // which is ALWAYS empty inside the runner (clones land at
+        // /home/agent/development/<repo>). BUG20's symptom ("'.git' missing")
+        // was just the cwd misalignment — the clone itself was already
+        // correct. Fix:
+        //   single repo  → /home/agent/development/<repo>  (align with clone)
+        //   multi repo   → unset, let runner pick first repo via its existing
+        //                  fallback at fazemos-agent-runner.ts:1075
+        //   zero repos   → /workspace (preserve chat_session and no-repo cases)
+        if (repoNames.length === 1) {
+            context.cwd = `/home/agent/development/${repoNames[0]}`;
+        }
+        else if (repoNames.length === 0) {
+            context.cwd = '/workspace';
+        }
+        // multi-repo: leave context.cwd unset — runner fallback chooses
         // Resolve worksheet context for actions/commitments
         if (opts.sourceType === 'action' || opts.sourceType === 'commitment') {
             try {
@@ -4786,6 +4932,17 @@ program
                         context.worksheetName = detail.worksheet?.name;
                         context.worksheetPurpose = detail.worksheet?.purpose;
                         context.actionDescription = match.description || match.name;
+                        // [F24 §3.3 / D3 / rul_action_completion_semantics]
+                        // Propagate the action's target_value into context so the
+                        // agent's buildSelfReportingInstructions can branch:
+                        //   target_value null|1 → binary auto-complete with -v 1
+                        //   target_value > 1    → emit a "non-binary target" note,
+                        //                          NO auto-completion command
+                        // Only meaningful for source_type='action'; we set it only
+                        // here (the action-resolution branch).
+                        if (opts.sourceType === 'action') {
+                            context.actionTargetValue = match.target_value ?? null;
+                        }
                         // Include linked outcomes
                         if (detail.outcomes?.length) {
                             context.outcomes = detail.outcomes.map((o) => ({
@@ -4808,6 +4965,12 @@ program
         }
         if (opts.prompt)
             context.prompt = opts.prompt;
+        // [F24 §3.3 / D2] Forward --no-auto-complete intent. The CLI guard
+        // above suppresses this for pipeline_step (forwardSuppress is false
+        // in that case). Agent's buildSelfReportingInstructions reads
+        // context.noAutoComplete; absent/false → default behavior.
+        if (forwardSuppress)
+            context.noAutoComplete = true;
         const body = {
             sourceType: opts.sourceType,
             sourceId,
@@ -6901,6 +7064,156 @@ ops
         process.exit(1);
     }
 });
+// ── OPS-2 — Manual Interventions KPI ─────────────────────────────────
+// Spec: specs/tech/platform/OPS-2-manual-intervention-kpi-tech-spec.md
+//
+// `fazemos ops interventions` has three operating modes:
+//
+//   1. bare        — windowed summary table + current zero-intervention
+//                    streak. Calls GET /api/ops/manual-interventions/summary.
+//                    Prod-only by default (cycle exit criterion is prod);
+//                    --include-dev inverts the env_tag filter for parity
+//                    with the API.
+//   2. --pipeline  — per-pipeline drill. Calls GET /api/pipeline-instances/:id
+//                    (response now carries manual_intervention_count +
+//                    env_tag) and surfaces the count + the env_tag fence so
+//                    operators can read the chip the same way the web does.
+//                    Forensic per-event detail lives behind `fazemos agents
+//                    events --type manual_intervention` (existing surface);
+//                    we print the hint so the operator doesn't have to
+//                    rediscover it.
+//   3. --since     — windowed list. Calls GET /api/ops/manual-interventions
+//                    with the resolved `since` timestamp. Defaults to
+//                    include-dev (false) → prod-only-NO; the GET list
+//                    endpoint defaults exclude_dev=false (the broader view
+//                    is more useful when scanning recent activity). The
+//                    --exclude-dev flag tightens to prod-only.
+//
+// Admin/owner gating is enforced server-side (403 FORBIDDEN); the CLI
+// surfaces the API's error verbatim so non-admin operators see the
+// authoritative reason rather than a stale local guess.
+ops
+    .command('interventions')
+    .description('Manual-intervention KPI. Bare mode shows the windowed summary table + '
+    + 'current zero-intervention streak (prod-only by default). '
+    + '--pipeline <id> drills into one pipeline. '
+    + '--since <duration> lists pipelines started in the window.')
+    .option('-w, --window <window>', 'Summary window: 24h, 7d, 30d', '7d')
+    .option('-p, --pipeline <id>', 'Drill into one pipeline_instance by ID')
+    .option('--since <duration>', 'List mode: filter by started_at >= now - duration (e.g. 24h, 7d, 30d)')
+    .option('-l, --limit <n>', 'List mode: max rows (default 50, max 200)', '50')
+    .option('--include-dev', 'Include dev-tagged pipelines in the summary / list (default: exclude)', false)
+    .option('--exclude-dev', 'Force exclude dev-tagged pipelines (default for summary; opt-in for list)', false)
+    .option('--json', 'Print the raw API response as JSON (machine-readable)')
+    .action(async (opts) => {
+    try {
+        // ── Mode 1: --pipeline <id> drill ────────────────────────────
+        if (opts.pipeline) {
+            const data = await api('GET', `/api/pipeline-instances/${opts.pipeline}`);
+            if (opts.json) {
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            const inst = data.instance;
+            if (!inst) {
+                console.error(chalk.red(`Pipeline ${opts.pipeline} not found`));
+                process.exit(1);
+            }
+            console.log(chalk.cyan(`Manual interventions on ${inst.name}`));
+            console.log(`  ID:        ${inst.id}`);
+            console.log(`  Status:    ${inst.status}`);
+            console.log(`  Env Tag:   ${inst.env_tag ?? chalk.gray('—')}`);
+            console.log(`  Count:     ${formatManualInterventionCell(inst.manual_intervention_count)}`);
+            if (inst.started_at) {
+                console.log(`  Started:   ${new Date(inst.started_at).toLocaleString()}`);
+            }
+            if (inst.completed_at) {
+                console.log(`  Completed: ${new Date(inst.completed_at).toLocaleString()}`);
+            }
+            console.log('');
+            console.log(chalk.gray('  Forensic per-event detail: query agent_events for the assignee/reviewer'));
+            console.log(chalk.gray('  identities that drove each increment. Example:'));
+            console.log(chalk.gray(`    fazemos agents events <agent-id> --type manual_intervention`));
+            return;
+        }
+        // ── Mode 2: --since <duration> windowed list ─────────────────
+        if (opts.since) {
+            const since = parseSinceDuration(opts.since);
+            const params = [`since=${encodeURIComponent(since)}`];
+            // For the list endpoint, the API default is exclude_dev=false (a
+            // broader scan-recent-activity surface). --exclude-dev tightens
+            // to prod-only. --include-dev is a no-op here (the default
+            // already includes dev) but accepted so the flag is symmetric
+            // across modes.
+            if (opts.excludeDev)
+                params.push('exclude_dev=true');
+            const limitN = Math.max(1, Math.min(200, Number(opts.limit) || 50));
+            params.push(`limit=${limitN}`);
+            const qs = `?${params.join('&')}`;
+            const data = await api('GET', `/api/ops/manual-interventions${qs}`);
+            if (opts.json) {
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            const rows = data.pipelines || [];
+            if (!rows.length) {
+                console.log(chalk.green(`No interventions in window since ${since}`));
+                return;
+            }
+            const scope = opts.excludeDev ? 'prod-only' : 'all envs';
+            console.log(chalk.cyan(`Manual interventions since ${since} (${scope}):`));
+            console.log('');
+            // Columns: MI | Env | Status | Started | Name (ID)
+            for (const r of rows) {
+                const mi = formatManualInterventionCell(r.manual_intervention_count);
+                const env = (r.env_tag ?? '—').padEnd(4);
+                const status = (r.status ?? '').padEnd(10);
+                const started = r.started_at ? new Date(r.started_at).toLocaleString() : '';
+                console.log(`  MI:${mi} ${chalk.gray(env)} ${status} ${chalk.gray(started)}`);
+                console.log(`           ${chalk.cyan(r.name)}  ${chalk.gray(r.pipeline_instance_id)}`);
+            }
+            return;
+        }
+        // ── Mode 3: bare summary ─────────────────────────────────────
+        // The summary endpoint defaults exclude_dev=true (cycle exit
+        // criterion is prod-only by spec). --include-dev inverts. The CLI
+        // is explicit either way so log lines are unambiguous.
+        const excludeDev = opts.includeDev ? false : true;
+        const window = opts.window || '7d';
+        const validWindows = ['24h', '7d', '30d'];
+        if (!validWindows.includes(window)) {
+            console.error(chalk.red(`Invalid --window "${window}". Must be one of: ${validWindows.join(', ')}`));
+            process.exit(1);
+        }
+        const qs = `?window=${window}&exclude_dev=${excludeDev}`;
+        const data = await api('GET', `/api/ops/manual-interventions/summary${qs}`);
+        if (opts.json) {
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        const scope = excludeDev ? 'prod-only' : 'all envs';
+        console.log(chalk.cyan(`Manual interventions — ${data.window} (${scope})`));
+        console.log('');
+        console.log(`  Total runs:           ${data.total_runs}`);
+        console.log(`  Total interventions:  ${data.total_interventions}`);
+        console.log(`  Avg per run:          ${typeof data.avg_per_run === 'number' ? data.avg_per_run.toFixed(2) : data.avg_per_run}`);
+        console.log(`  p95 per run:          ${data.p95_per_run}`);
+        console.log(`  Zero-intervention:    ${data.zero_intervention_runs} of ${data.total_runs} runs`);
+        // Streak gets the same green/amber/grey emphasis as the web chip:
+        // ≥5 is a celebration moment per Sage's spec; 1-4 amber; 0 grey.
+        const streak = data.zero_intervention_streak ?? 0;
+        const streakDisplay = streak >= 5
+            ? chalk.green(`${streak} 🎉`)
+            : streak >= 1
+                ? chalk.yellow(String(streak))
+                : chalk.gray('0');
+        console.log(`  Current streak:       ${streakDisplay}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 // ── F18 — Project-scoped docs surface ────────────────────────────────
 // Spec: specs/tech/platform/F18-project-scoped-docs-surface-tech-spec.md §8
 //