@formigio/fazemos-cli 0.10.11 → 0.10.13

package/dist/index.js

@@ -7,6 +7,9 @@ getActiveProjectId, setActiveProjectId, clearActiveProjectId, findProjectBySlug,
 import { login, signup, confirmSignup, adminLogin } from './auth.js';
 import { api, ApiError, refreshAuthMeCache, invalidateAuthMeCache } from './api.js';
 import { isProjectConnectionUnavailable, renderProjectConnectionUnavailableCopy, } from './connectionErrorCopy.js';
+import { loadYaml, summarize } from './yaml/load.js';
+import { printFindings, printJson } from './yaml/format.js';
+import { validateManifest } from './manifest/checks.js';
 import { execSync } from 'child_process';
 import { readFileSync, readdirSync, writeFileSync, mkdirSync, existsSync, statSync } from 'fs';
 import { fileURLToPath } from 'url';
@@ -2466,14 +2469,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}`);
@@ -4718,7 +4765,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)
@@ -4729,6 +4777,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)) {
@@ -4765,8 +4829,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 {
@@ -4783,6 +4863,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) => ({
@@ -4805,6 +4896,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,
@@ -7453,6 +7550,135 @@ docs
         handleScopedError(err);
     }
 });
+// ── Spec-artifact validation (TOOL-1) ──────────────────────────────────
+//
+// Two top-level groups:
+//   fazemos yaml validate <path>      Generic YAML parse check
+//   fazemos manifest validate <path>  Architecture Design Manifest check
+//
+// Both support --json for structured output. Exit code 1 on errors, 0 on
+// warnings/info only. See CLAUDE.md "TOOL-1" for scope.
+const yamlGroup = program.command('yaml').description('Generic YAML file utilities. Offline; no API calls. Use as a cheap ' +
+    'author-time or CI gate before committing a YAML file or feeding it into ' +
+    'another tool. For Architecture Design Manifests, prefer `fazemos manifest ' +
+    'validate` instead — it runs YAML parse plus structural and custom checks.');
+yamlGroup
+    .command('validate')
+    .description('Parse a YAML file and report parse errors with line/column. Cheap pre-commit / CI gate.')
+    .argument('<path>', 'Path to a YAML file (.yaml or .yml). Absolute or relative to CWD.')
+    .option('--json', 'Emit structured JSON output instead of human-readable text. See --help for shape.')
+    .addHelpText('after', `
+Rule slugs (stable; safe to grep in --json output):
+  read.not_found       File at <path> does not exist
+  read.not_a_file      <path> exists but is not a regular file
+  read.io_error        Read failed (permissions, etc.)
+  yaml.parse_error     js-yaml could not parse the document
+
+Exit codes:
+  0   YAML parsed cleanly (no error findings)
+  1   Parse or read error finding present
+
+JSON output shape (--json):
+  {
+    "source":   "<path>",
+    "ok":       true | false,
+    "summary":  { "errors": <int>, "warnings": <int>, "infos": <int> },
+    "findings": [
+      { "severity": "error"|"warning"|"info",
+        "rule":     "<rule-slug>",
+        "message":  "<human-readable>",
+        "path":     "<dotted-path-into-doc>",  // optional
+        "line":     <int>,                     // optional (parse errors)
+        "column":   <int> }                    // optional (parse errors)
+    ]
+  }
+
+Examples:
+  fazemos yaml validate ./config.yaml
+  fazemos yaml validate ./fixture.yml --json | jq '.findings[]'`)
+    .action((path, opts) => {
+    const result = loadYaml(path);
+    const summary = summarize(result.findings);
+    if (opts.json)
+        printJson(result.source, result.findings, summary);
+    else
+        printFindings(result.source, result.findings, summary);
+    if (summary.errors > 0)
+        process.exit(1);
+});
+const manifestGroup = program.command('manifest').description('Architecture Design Manifest validation (the YAML companion to a tech ' +
+    'spec, conventionally at specs/tech/<area>/<feature>-manifest.yaml). ' +
+    'Offline; no API calls. Designed to run at three points: (1) author time ' +
+    'before commit, (2) in agent prompts (Marco / Dex) before review tokens ' +
+    'are spent, (3) in CI on PRs touching a manifest. Catches the recurring ' +
+    'miss class — audit-summary math, AC traceability, duplicate IDs — ' +
+    'without a workspace-level toolchain.');
+manifestGroup
+    .command('validate')
+    .description('Validate an Architecture Design Manifest: YAML parse + structural schema + custom checks (audit math, AC traceability, duplicate IDs).')
+    .argument('<path>', 'Path to a manifest YAML file. Convention: specs/tech/<area>/<feature>-manifest.yaml inside a workspace clone. Absolute paths also work.')
+    .option('--json', 'Emit structured JSON output instead of human-readable text. See --help for shape.')
+    .addHelpText('after', `
+What runs (in order):
+  1. js-yaml parse                          (rule slug: yaml.parse_error)
+  2. permissive structural schema (ajv)     (rule slugs: schema.*)
+  3. custom checks                          (rule slugs: audit.* / trace.* / ids.* / manifest.*)
+
+The schema requires feature.id + feature.title. It accepts both manifest shape
+variants seen in the wild — entry_points as map ({added, modified, replaced,
+unchanged, audit_summary}) OR as a flat list, traceability values as string OR
+object OR array-of-rows, rules as map OR array-of-{id, ...} entries.
+
+Rule slugs (stable; safe to grep in --json output):
+  audit.sum_mismatch         audit_summary.{added+modified+replaced+unchanged} ≠ total_in_this_manifest
+  audit.count_vs_array       audit_summary declared count ≠ actual entry_points.<bucket>[] length
+  trace.ac_task_missing      traceability.AC*.task references a task ID with no match in implementation.*.tasks
+                             (recurses through implementation.sequencing.* and similar nested buckets)
+  ids.duplicate_task         same task id in multiple implementation buckets
+  ids.duplicate              duplicate id in edge_cases / risks / phase_1_gate.questions
+  helper.callers_duplicate   (warning) api.internal_helper.callers lists same caller twice
+  schema.required            required field missing (feature.id, feature.title)
+  schema.type / schema.anyOf value has wrong shape
+  manifest.version_missing   (warning) add manifest_version: "0.1" at the top of the file
+  manifest.version_unknown   (warning) manifest_version is newer than this CLI knows; checks still ran
+  manifest.shape             root is not a YAML mapping
+  read.not_found / read.io_error / yaml.parse_error   file-level failures
+
+Exit codes:
+  0   no error-severity findings (warnings + infos OK)
+  1   any error-severity finding present
+
+JSON output shape (--json) — same as \`yaml validate --json\`:
+  {
+    "source":   "<path>",
+    "ok":       true | false,
+    "summary":  { "errors": <int>, "warnings": <int>, "infos": <int> },
+    "findings": [ { "severity", "rule", "message", "path"?, "line"?, "column"? } ]
+  }
+
+When to invoke:
+  - Author time, before commit (catches the recurring miss class earliest)
+  - Inside Marco / Dex agent prompts before review tokens are spent
+  - In CI on any PR that touches a *-manifest.yaml file
+
+Examples:
+  fazemos manifest validate ./specs/tech/platform/I45-...-manifest.yaml
+  fazemos manifest validate ./manifest.yaml --json | jq '.findings | map(select(.severity=="error"))'
+  fazemos manifest validate ./manifest.yaml --json | jq -r '.findings[] | "\\(.severity) \\(.rule) \\(.message)"'`)
+    .action((path, opts) => {
+    const loaded = loadYaml(path);
+    const findings = [...loaded.findings];
+    if (loaded.ok) {
+        findings.push(...validateManifest(loaded.value));
+    }
+    const summary = summarize(findings);
+    if (opts.json)
+        printJson(loaded.source, findings, summary);
+    else
+        printFindings(loaded.source, findings, summary);
+    if (summary.errors > 0)
+        process.exit(1);
+});
 // Skip auto-parse only when running under Vitest (which sets process.env.VITEST).
 // Tests import `program` and drive it via `program.parseAsync(...)` after mocking
 // `./api.js`. In every other context — direct invocation, npx tsx, OR the bin