@formigio/fazemos-cli 0.10.24 → 0.10.25

package/dist/index.js

@@ -10,6 +10,7 @@ import { isProjectConnectionUnavailable, renderProjectConnectionUnavailableCopy,
 import { loadYaml, summarize } from './yaml/load.js';
 import { printFindings, printJson } from './yaml/format.js';
 import { validateManifest } from './manifest/checks.js';
+import { validatePath as validateRunbookPath } from './runbook/checks.js';
 import { findLocalRegistry, resolveRole, buildInboxFile, writeInboxFile, writeInboxFileAtPath, buildRolesSyncPayload, findUnprocessedInboxFiles, computeFileHash, gitCommitInboxFile, } from './dispatch.js';
 import { execSync } from 'child_process';
 import { registerPauseCommands } from './pause.js';
@@ -8238,6 +8239,87 @@ Examples:
     if (summary.errors > 0)
         process.exit(1);
 });
+// ── `fazemos runbook validate` — Runbook substrate validator (F39 TOOL-1) ──
+//
+// Validates Runbook step-doc frontmatter against the FROZEN schema
+// (projects/fazemos/runbooks/runbook.schema.json) + the per-template
+// flip-state ledger (projects/fazemos/runbooks/flip-state.json). Offline; no
+// API calls. A NEW command group (sibling to `yaml` / `manifest`) — a Runbook
+// doc is a different artifact (markdown-with-frontmatter, not a YAML manifest),
+// so it does not belong under `manifest validate`'s ADM contract. See the F39
+// tech spec §9. Scope: frontmatter shape + flip-state invariant ONLY — NOT
+// id→file resolution (F40), NOT contract-conformance-against-binding (F41).
+const runbookGroup = program.command('runbook').description('Runbook substrate validation (F39). A Runbook is the one reusable unit of ' +
+    'work: a declared I/O contract + a role hint + a procedure body, authored ' +
+    'as frontmatter on a step doc (steps/<Template>/<Step>.md). Offline; no API ' +
+    'calls. Run at author time, in Ollie\'s stewardship audit, or in CI on PRs ' +
+    'touching steps/** or runbooks/**.');
+runbookGroup
+    .command('validate')
+    .description('Validate Runbook step-doc frontmatter: frozen-schema shape + frozen enums + runbook_schema_version + F18 description contract + id shape/uniqueness + no-binding-leak + per-template flip-state invariant.')
+    .argument('<path>', 'Path to a Runbook step-doc (.md) or a directory of them (e.g. "steps/Hello Fazemos/"). Absolute or relative to CWD.')
+    .option('--json', 'Emit structured JSON output instead of human-readable text. See --help for shape.')
+    .addHelpText('after', `
+What runs (in order, per file):
+  1. frontmatter split + js-yaml parse      (rule slugs: runbook.no_frontmatter / runbook.frontmatter_parse_error / runbook.shape)
+  2. frozen schema (ajv, draft-07)          (rule slugs: schema.* — required/enum/type/pattern/additionalProperties)
+  3. runbook_schema_version present/known   (runbook.version_missing = ERROR; runbook.version_unknown = warning)
+  4. description (F18 contract)             (runbook.description_invalid: MISSING/EMPTY/MULTILINE)
+  5. runbook id kebab shape + uniqueness   (runbook.id_shape; runbook.id_duplicate across a directory run)
+  6. no binding/DAG leak                    (runbook.binding_leak — depends_on/source_*/step_type/template/cadence/… + top-level reviewer/eval_max_turns)
+  7. per-template flip-state invariant      (runbook.flip_state_unreadable / runbook.flip_state_mismatch)
+
+Schema source of truth: projects/fazemos/runbooks/runbook.schema.json (canonical;
+loaded from the workspace clone). The CLI vendors a copy as the absent-canonical
+fallback; a unit test diffs the two and fails on drift (F39 §9.2).
+
+Flip-state: projects/fazemos/runbooks/flip-state.json. flipped:true => the doc is
+authoritative (empty inline sections are correct — no false EMPTY_STEP_BODY alarm);
+flipped:false/absent => inline sections are authoritative (frontmatter accepted if
+present, transitional). An unreadable ledger is a hard error.
+
+Frozen enums (F39 §5.2; append-only within a major version):
+  type        text | number | boolean | url | filepath | json
+  format      text | filepath | url | commit_sha | integer | markdown | json
+  source_hint upstream | pipeline_param | dispatch_param | workspace_path
+
+Exit codes:
+  0   no error-severity findings (warnings + infos OK)
+  1   any error-severity finding present
+
+JSON output shape (--json) — same as \`manifest validate --json\`, one object per file:
+  { "source", "ok", "summary": { "errors", "warnings", "infos" }, "findings": [ … ] }
+
+When to invoke:
+  - Author time, before commit (catches STEP_UNRESOLVED-class defects before a render)
+  - Inside Ollie's stewardship / flip audit
+  - In CI on any PR touching steps/** or runbooks/**
+
+Examples:
+  fazemos runbook validate "projects/fazemos/steps/Hello Fazemos/Write a random fact.md"
+  fazemos runbook validate "projects/fazemos/steps/Hello Fazemos/" --json | jq '.[].findings[] | select(.severity=="error")'`)
+    .action((path, opts) => {
+    const results = validateRunbookPath(path);
+    let totalErrors = 0;
+    if (opts.json) {
+        const payload = results.map((r) => {
+            const summary = summarize(r.findings);
+            totalErrors += summary.errors;
+            return { source: r.source, ok: summary.errors === 0, summary, findings: r.findings };
+        });
+        console.log(JSON.stringify(payload, null, 2));
+    }
+    else {
+        for (const r of results) {
+            const summary = summarize(r.findings);
+            totalErrors += summary.errors;
+            printFindings(r.source, r.findings, summary);
+            console.log('');
+        }
+    }
+    if (totalErrors > 0)
+        process.exit(1);
+});
 // ── `fazemos dispatch` — role-to-role dispatch ─────────────────────
 //
 // F26 data flow (API write-through, Dex S-B):