@formigio/fazemos-cli 0.10.10 → 0.10.12

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';
@@ -26,6 +29,13 @@ function parseStreamSilenceAbortMs(val) {
     }
     return n;
 }
+function parseEvalMaxTurns(val) {
+    const n = Number(val);
+    if (!Number.isInteger(n) || n < 8 || n > 30) {
+        throw new Error(`eval_max_turns must be an integer between 8 and 30 (got ${val})`);
+    }
+    return n;
+}
 function formatMsHuman(ms) {
     if (ms >= 60000) {
         const min = ms / 60000;
@@ -2823,6 +2833,9 @@ templates
                     else if (step.outputs?.length) {
                         console.log('      Inputs: none');
                     }
+                    if (step.eval_max_turns != null) {
+                        console.log(`      Eval Max Turns: ${step.eval_max_turns}`);
+                    }
                     if (step.stream_silence_abort_ms) {
                         console.log(`      Stream Silence Abort: ${step.stream_silence_abort_ms.toLocaleString()}ms (${formatMsHuman(step.stream_silence_abort_ms)})`);
                     }
@@ -3179,6 +3192,7 @@ templates
     .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')
     .option('--stream-silence-abort-ms <ms>', 'Stream silence abort threshold in milliseconds (30000-1800000)', parseStreamSilenceAbortMs)
+    .option('--eval-max-turns <n>', 'Evaluator turn budget for tool-enabled (agent) evals on this step (8-30). Has no effect on script-typed steps (rejected by API).', parseEvalMaxTurns)
     .action(async (templateId, opts) => {
     try {
         if (!VALID_STEP_TYPES.includes(opts.type)) {
@@ -3240,6 +3254,8 @@ templates
             step.agent_config = parseJson(opts.agentConfig, '--agent-config');
         if (opts.streamSilenceAbortMs !== undefined)
             step.stream_silence_abort_ms = opts.streamSilenceAbortMs;
+        if (opts.evalMaxTurns !== undefined)
+            step.eval_max_turns = opts.evalMaxTurns;
         // Positioning: --after or --sort-order
         if (opts.after && opts.sortOrder !== undefined) {
             console.error(chalk.red('Cannot use both --after and --sort-order'));
@@ -3268,6 +3284,9 @@ templates
         if (step.stream_silence_abort_ms) {
             console.log(`  Stream Silence Abort: ${step.stream_silence_abort_ms.toLocaleString()}ms (${formatMsHuman(step.stream_silence_abort_ms)})`);
         }
+        if (step.eval_max_turns != null) {
+            console.log(`  Eval Max Turns: ${step.eval_max_turns}`);
+        }
     }
     catch (err) {
         console.error(chalk.red(err.message));
@@ -3337,12 +3356,20 @@ templates
     .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)')
     .option('--stream-silence-abort-ms <ms>', 'Stream silence abort threshold in milliseconds (30000-1800000)', parseStreamSilenceAbortMs)
+    .option('--eval-max-turns <n>', 'Evaluator turn budget for tool-enabled (agent) evals on this step (8-30). Mutually exclusive with --clear-eval-max-turns.', parseEvalMaxTurns)
+    .option('--clear-eval-max-turns', 'Remove a previously-set eval_max_turns from this step, reverting to runner default. Mutually exclusive with --eval-max-turns.')
     .action(async (templateId, opts) => {
     try {
+        if (opts.evalMaxTurns !== undefined && opts.clearEvalMaxTurns) {
+            console.error(chalk.red('--eval-max-turns and --clear-eval-max-turns are mutually exclusive'));
+            process.exit(1);
+            return;
+        }
         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.sections != null || opts.streamSilenceAbortMs !== undefined;
+            || opts.agentConfig || opts.sections != null || opts.streamSilenceAbortMs !== undefined
+            || opts.evalMaxTurns !== undefined || opts.clearEvalMaxTurns;
         if (!hasUpdate) {
             console.error(chalk.red('Provide at least one field to update'));
             process.exit(1);
@@ -3415,6 +3442,13 @@ templates
         if (opts.streamSilenceAbortMs !== undefined) {
             step.stream_silence_abort_ms = opts.streamSilenceAbortMs;
         }
+        // eval_max_turns: set or clear (mutually exclusive — checked above)
+        if (opts.evalMaxTurns !== undefined) {
+            step.eval_max_turns = opts.evalMaxTurns;
+        }
+        else if (opts.clearEvalMaxTurns) {
+            delete step.eval_max_turns;
+        }
         await api('PUT', `/api/pipeline-templates/${templateId}`, { definition: t.definition });
         console.log(chalk.green(`Updated step: ${step.name}`));
     }
@@ -7422,6 +7456,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