octwin-cli 0.8.5 → 0.8.6

package/CHANGELOG.md

@@ -5,6 +5,31 @@ Format: [Keep a Changelog](https://keepachangelog.com/) — newest first, bucket
 **Added · Changed · Deprecated · Removed · Fixed · Security**. The platform-wide view lives in the
 repo root [`CHANGELOG.md`](../../CHANGELOG.md); this file is the CLI-only cut that ships with the package.
 
+## [0.8.6] - 2026-09-04
+
+### Changed
+- **`validate` can no longer print a `✓` for a check that did not run.** Each of the eight
+  checks now RETURNS an `Outcome` — `passed`, `findings`, or `not-run` — and a single printer
+  renders all of them, groups the skips by reason, and computes the exit code. Previously each
+  check printed its own `✓` inside the `if` that held its data, with a `skipped[]` array and a
+  `skipReasons` Map maintained alongside; it was correct because someone was careful, and the
+  next check added was one `if` away from lying again.
+
+  It had lied twice, in the same shape: the KB-dependent block once printed ONE `✓` above six
+  checks whose own `✓`s lived inside their `if`s (so a run with no pulled KB read as "one check,
+  passed", and an entire backlog batch reached production that way), and `yamlDocs()` once
+  dropped an unparseable file so `validate` printed all-green over a pack the platform's importer
+  then refused. **An unparseable file is not "no findings", it is "no idea", and those must never
+  print the same** — a check that returns nothing now cannot reach the `passed` branch at all.
+
+  Output is unchanged for a normal run. `passed` carries its own line, so the reserved-entity
+  check keeps the narrower wording it uses when the catalog rules are absent from an older pull.
+  `--require-kb` is now one line over the returned skip list.
+
+  Verified 2026-09-04: all 23 marketplace packs exit 0 with no findings; a pack with no pulled KB
+  prints zero `✓` for the six KB-dependent checks plus one grouped ⚠ naming all six, and
+  `--require-kb` exits 1; a duplicate YAML key still exits 1 naming the file.
+
 ## [0.8.5] - 2026-09-02
 
 ### Added

package/dist/index.js

@@ -73,7 +73,8 @@ import { loadBuiltinNames, findBuiltinViolations, describeBuiltinFinding } from
 import { loadTemplateSpecs, findTemplateViolations, describeTemplateFinding } from './lib/template-check.js';
 import { loadSystemEntities, findEntityViolations, describeEntityFinding } from './lib/entity-check.js';
 import { loadDeclarationSpecs, findDeclarationViolations, describeDeclarationFinding } from './lib/declaration-check.js';
-import { describeKbLookup, findPlatformKbDir } from './lib/kb-path.js';
+import { findPlatformKbDir } from './lib/kb-path.js';
+import { reportChecks } from './lib/outcome.js';
 import { classifyPackPath, isSkippedDir } from './lib/pack-source.js';
 import { readPage, morePageHint } from './lib/page.js';
 import { kbOneLiner, buildKbIndexMarkdown, buildKbOutlineMarkdown, } from './lib/kb-index.js';
@@ -976,158 +977,161 @@ async function cmdValidate(flags) {
     const yamlDocs = () => parsed;
     // Checks that need the pulled KB. All of them DEGRADE when it is absent — the KB
     // is a gitignored cache wiped by every pull, so failing hard would break a fresh
-    // clone before the author could act. But a skip is ANNOUNCED, and remembered:
-    // the ✓ used to print above these blocks unconditionally while the per-check ✓s
-    // lived inside the `if`s, so a KB-less run read as "one check, passed". An entire
-    // backlog batch reached production that way. The defect is the silence, not the skip.
+    // clone before the author could act. But a skip is ANNOUNCED, and remembered.
     //
-    // Reasons are COLLECTED rather than printed inline. When the KB is missing, every
-    // check skips for the identical reason, and six copies of one sentence is how a
-    // reader learns to scroll past the ⚠ block — which is the same failure as not
-    // printing it. One line, naming all six.
-    const skipped = [];
-    const skipReasons = new Map();
-    const noteSkip = (label, lookup) => {
-        skipped.push(label);
-        // Group by the lookup's IDENTITY, then let `describeKbLookup` phrase the one
-        // line at print time — so the wording stays in the module that owns it and
-        // cannot drift into a doubled "SKIPPED — SKIPPED —".
-        const key = lookup.state === 'ok' ? 'ok'
-            : `${lookup.state}|${'dir' in lookup ? lookup.dir : ''}|${'reason' in lookup ? lookup.reason : ''}`;
-        const bucket = skipReasons.get(key) ?? { lookup, labels: [] };
-        bucket.labels.push(label);
-        skipReasons.set(key, bucket);
-    };
+    // Each check RETURNS an `Outcome` and prints nothing; `reportChecks` renders all of
+    // them and groups the skips by reason. That is the whole point: a check that returns
+    // nothing cannot reach the `passed` branch, so the false-`✓` this file printed twice
+    // before — once for six checks at a time, once over an unparseable file — is no longer
+    // a mistake anyone can make. See [`lib/outcome.ts`](./lib/outcome.ts).
     /** Stamp each finding with its source line — the walkers carry the node
      *  path; `files` holds the raw text the locator needs (E-08). */
     const withLines = (fs) => fs.map(f => ({ ...f, line: files[f.file] ? yamlLineOf(files[f.file], f.path) : null }));
-    const render = loadAllowedRenderKeys(packDir);
-    if (render.keys) {
-        const findings = withLines(yamlDocs().flatMap(([p, doc]) => findRenderKeyViolations(doc, p, render.keys, render.nested)));
-        if (findings.length) {
-            console.error(`✗ ${findings.length} render-intent field error${findings.length === 1 ? '' : 's'}:`);
-            for (const f of findings)
-                console.error(`  ✗ ${describeRenderFinding(f)}`);
-            die('fix these before deploying — the platform rejects them at load, and before that they rendered as nothing');
-        }
-        console.log('✓ render intents use only fields the platform renders');
-    }
-    else {
-        noteSkip('render-intent fields', render.lookup);
-    }
-    // Primitive `args:` keys, same source and same contract. Cannot see inside a
-    // `use:` template body (expansion is the platform's job); `--remote` covers that.
-    const args = loadPrimitiveArgSpecs(packDir);
-    if (args.specs) {
-        const findings = withLines(yamlDocs().flatMap(([p, doc]) => findArgViolations(doc, p, args.specs)));
-        if (findings.length) {
-            console.error(`✗ ${findings.length} primitive-argument error${findings.length === 1 ? '' : 's'}:`);
-            for (const f of findings)
-                console.error(`  ✗ ${describeArgFinding(f)}`);
-            die('fix these before deploying — an undeclared argument is dropped with no error at runtime');
-        }
-        console.log('✓ primitive arguments match their declared inputs');
-    }
-    else {
-        noteSkip('primitive arguments', args.lookup);
-    }
-    // Expression builtins — the function set is CLOSED and generated from the
-    // runtime, so an invented `$fn(` is checkable here and nowhere else offline.
-    const builtins = loadBuiltinNames(packDir);
-    if (builtins.names) {
-        const findings = withLines(yamlDocs().flatMap(([p, doc]) => findBuiltinViolations(doc, p, builtins.names)));
-        if (findings.length) {
-            console.error(`✗ ${findings.length} unknown expression function${findings.length === 1 ? '' : 's'}:`);
-            for (const f of findings)
-                console.error(`  ✗ ${describeBuiltinFinding(f)}`);
-            die('fix these before deploying — the evaluator cannot resolve them, and it fails mid-conversation');
-        }
-        console.log('✓ every $function() in an expression exists');
-    }
-    else {
-        noteSkip('expression functions', builtins.lookup);
-    }
-    // `use:` templates. A pack's OWN templates shadow the platform's, so they are
-    // named here and skipped — this check has no schema for them.
-    const templates = loadTemplateSpecs(packDir);
-    if (templates.specs) {
-        // A pack template is `templates/<name>.template.yaml` — the `.template`
-        // segment is part of the convention the expander scans for, NOT part of the
-        // name a `use:` writes. Capturing it would leave every pack that shadows a
-        // platform template (kaiian shadows `field_prompt_render`) reported as using
-        // one that does not exist.
-        const packTemplates = new Set(Object.keys(files)
-            .map(p => /^templates\/(.+)\.template\.ya?ml$/i.exec(p.replace(/\\/g, '/'))?.[1])
-            .filter((n) => !!n));
-        const findings = yamlDocs().flatMap(([p, doc]) => findTemplateViolations(doc, p, templates.specs, packTemplates));
-        if (findings.length) {
-            console.error(`✗ ${findings.length} template error${findings.length === 1 ? '' : 's'}:`);
-            for (const f of findings)
-                console.error(`  ✗ ${describeTemplateFinding(f)}`);
-            die('fix these before deploying — a template param that does not exist arrives as undefined, and renders as a blank');
-        }
-        console.log('✓ `use:` templates and their params exist');
-    }
-    else {
-        noteSkip('`use:` templates', templates.lookup);
-    }
-    // Reserved XRM entity keys — a boot error, which means the pack deploys clean
-    // and then fails to load on the first inbound message.
-    const system = loadSystemEntities(packDir);
-    if (system.entities) {
-        const findings = yamlDocs()
-            .filter(([p]) => /(^|[/\\])xrm\.ya?ml$/i.test(p))
-            .flatMap(([p, doc]) => findEntityViolations(doc, p, system.entities, system.rules));
-        if (findings.length) {
-            console.error(`✗ ${findings.length} reserved-entity error${findings.length === 1 ? '' : 's'}:`);
-            for (const f of findings)
-                console.error(`  ✗ ${describeEntityFinding(f)}`);
-            die('fix these before deploying — these fail at BOOT, after a deploy that reported success');
-        }
-        // Name the narrower promise when the catalog-level rules are absent (a KB
-        // pulled before they were published) — a ✓ that reads wider than what ran is
-        // the failure this file's skip contract exists to prevent.
-        console.log(system.rules
-            ? '✓ no entity collides with a reserved platform key, and no extension overrides a platform-owned one'
-            : '✓ no entity collides with a reserved platform key (re-pull for the `contact`/extension-override rules)');
-    }
-    else {
-        noteSkip('reserved entity keys', system.lookup);
-    }
-    // The declaration files themselves, against the published JSON Schemas.
-    // Deliberately narrow (see declaration-check.ts) — it walks away from anything
-    // it cannot read rather than guessing.
-    const decls = loadDeclarationSpecs(packDir);
-    if (decls.specs) {
-        const findings = yamlDocs().flatMap(([p, doc]) => {
-            const base = p.replace(/\\/g, '/').split('/').pop() ?? p;
-            const spec = decls.specs.get(base);
-            // Only a file at the PACK ROOT is a declaration — `flows/tools/xrm.yaml`
-            // would be a flow that happens to share a name.
-            if (!spec || p.replace(/\\/g, '/').includes('/'))
-                return [];
-            return findDeclarationViolations(doc, spec).map(f => ({ ...f, file: p }));
-        });
-        if (findings.length) {
-            console.error(`✗ ${findings.length} declaration error${findings.length === 1 ? '' : 's'}:`);
-            for (const f of findings)
-                console.error(`  ✗ ${describeDeclarationFinding(f)}`);
-            die('fix these before deploying — a declaration file is parsed strictly, and an unknown key is rejected');
-        }
-        // Deliberately narrow wording. Most of `xrm.yaml`'s field shapes are a Zod
-        // union, which renders as `anyOf` and which this check walks away from by
-        // design — so "matches its schema" would be a promise it does not keep, and
-        // an over-claimed ✓ is how an author stops reading `--remote` output.
-        console.log('✓ declaration files carry no unknown or missing keys (unions are left to --remote)');
-    }
-    else {
-        noteSkip('declaration schemas', decls.lookup);
-    }
-    // One ⚠ per distinct reason, naming every check it cost.
-    for (const { lookup, labels } of skipReasons.values()) {
-        const what = labels.length === 1 ? labels[0] : `${labels.length} checks (${labels.join(', ')})`;
-        console.log(`⚠ ${describeKbLookup(lookup, what)}`);
-    }
+    const checks = [
+        {
+            label: 'render-intent fields',
+            run: () => {
+                const render = loadAllowedRenderKeys(packDir);
+                if (!render.keys)
+                    return { kind: 'not-run', lookup: render.lookup };
+                const findings = withLines(yamlDocs().flatMap(([p, doc]) => findRenderKeyViolations(doc, p, render.keys, render.nested)));
+                return findings.length
+                    ? {
+                        kind: 'findings', noun: 'render-intent field error',
+                        lines: findings.map(describeRenderFinding),
+                        hint: 'fix these before deploying — the platform rejects them at load, and before that they rendered as nothing',
+                    }
+                    : { kind: 'passed', line: 'render intents use only fields the platform renders' };
+            },
+        },
+        {
+            // Primitive `args:` keys, same source and same contract. Cannot see inside a
+            // `use:` template body (expansion is the platform's job); `--remote` covers that.
+            label: 'primitive arguments',
+            run: () => {
+                const args = loadPrimitiveArgSpecs(packDir);
+                if (!args.specs)
+                    return { kind: 'not-run', lookup: args.lookup };
+                const findings = withLines(yamlDocs().flatMap(([p, doc]) => findArgViolations(doc, p, args.specs)));
+                return findings.length
+                    ? {
+                        kind: 'findings', noun: 'primitive-argument error',
+                        lines: findings.map(describeArgFinding),
+                        hint: 'fix these before deploying — an undeclared argument is dropped with no error at runtime',
+                    }
+                    : { kind: 'passed', line: 'primitive arguments match their declared inputs' };
+            },
+        },
+        {
+            // Expression builtins — the function set is CLOSED and generated from the
+            // runtime, so an invented `$fn(` is checkable here and nowhere else offline.
+            label: 'expression functions',
+            run: () => {
+                const builtins = loadBuiltinNames(packDir);
+                if (!builtins.names)
+                    return { kind: 'not-run', lookup: builtins.lookup };
+                const findings = withLines(yamlDocs().flatMap(([p, doc]) => findBuiltinViolations(doc, p, builtins.names)));
+                return findings.length
+                    ? {
+                        kind: 'findings', noun: 'unknown expression function',
+                        lines: findings.map(describeBuiltinFinding),
+                        hint: 'fix these before deploying — the evaluator cannot resolve them, and it fails mid-conversation',
+                    }
+                    : { kind: 'passed', line: 'every $function() in an expression exists' };
+            },
+        },
+        {
+            // `use:` templates. A pack's OWN templates shadow the platform's, so they are
+            // named here and skipped — this check has no schema for them.
+            label: '`use:` templates',
+            run: () => {
+                const templates = loadTemplateSpecs(packDir);
+                if (!templates.specs)
+                    return { kind: 'not-run', lookup: templates.lookup };
+                // A pack template is `templates/<name>.template.yaml` — the `.template`
+                // segment is part of the convention the expander scans for, NOT part of the
+                // name a `use:` writes. Capturing it would leave every pack that shadows a
+                // platform template (kaiian shadows `field_prompt_render`) reported as using
+                // one that does not exist.
+                const packTemplates = new Set(Object.keys(files)
+                    .map(p => /^templates\/(.+)\.template\.ya?ml$/i.exec(p.replace(/\\/g, '/'))?.[1])
+                    .filter((n) => !!n));
+                const findings = yamlDocs().flatMap(([p, doc]) => findTemplateViolations(doc, p, templates.specs, packTemplates));
+                return findings.length
+                    ? {
+                        kind: 'findings', noun: 'template error',
+                        lines: findings.map(describeTemplateFinding),
+                        hint: 'fix these before deploying — a template param that does not exist arrives as undefined, and renders as a blank',
+                    }
+                    : { kind: 'passed', line: '`use:` templates and their params exist' };
+            },
+        },
+        {
+            // Reserved XRM entity keys — a boot error, which means the pack deploys clean
+            // and then fails to load on the first inbound message.
+            label: 'reserved entity keys',
+            run: () => {
+                const system = loadSystemEntities(packDir);
+                if (!system.entities)
+                    return { kind: 'not-run', lookup: system.lookup };
+                const findings = yamlDocs()
+                    .filter(([p]) => /(^|[/\\])xrm\.ya?ml$/i.test(p))
+                    .flatMap(([p, doc]) => findEntityViolations(doc, p, system.entities, system.rules));
+                return findings.length
+                    ? {
+                        kind: 'findings', noun: 'reserved-entity error',
+                        lines: findings.map(describeEntityFinding),
+                        hint: 'fix these before deploying — these fail at BOOT, after a deploy that reported success',
+                    }
+                    // Name the narrower promise when the catalog-level rules are absent (a KB
+                    // pulled before they were published) — a ✓ that reads wider than what ran is
+                    // the failure this file's skip contract exists to prevent, and it is why
+                    // `passed` carries its own line instead of the printer inventing one.
+                    : {
+                        kind: 'passed',
+                        line: system.rules
+                            ? 'no entity collides with a reserved platform key, and no extension overrides a platform-owned one'
+                            : 'no entity collides with a reserved platform key (re-pull for the `contact`/extension-override rules)',
+                    };
+            },
+        },
+        {
+            // The declaration files themselves, against the published JSON Schemas.
+            // Deliberately narrow (see declaration-check.ts) — it walks away from anything
+            // it cannot read rather than guessing.
+            label: 'declaration schemas',
+            run: () => {
+                const decls = loadDeclarationSpecs(packDir);
+                if (!decls.specs)
+                    return { kind: 'not-run', lookup: decls.lookup };
+                const findings = yamlDocs().flatMap(([p, doc]) => {
+                    const base = p.replace(/\\/g, '/').split('/').pop() ?? p;
+                    const spec = decls.specs.get(base);
+                    // Only a file at the PACK ROOT is a declaration — `flows/tools/xrm.yaml`
+                    // would be a flow that happens to share a name.
+                    if (!spec || p.replace(/\\/g, '/').includes('/'))
+                        return [];
+                    return findDeclarationViolations(doc, spec).map(f => ({ ...f, file: p }));
+                });
+                return findings.length
+                    ? {
+                        kind: 'findings', noun: 'declaration error',
+                        lines: findings.map(describeDeclarationFinding),
+                        hint: 'fix these before deploying — a declaration file is parsed strictly, and an unknown key is rejected',
+                    }
+                    // Deliberately narrow wording. Most of `xrm.yaml`'s field shapes are a Zod
+                    // union, which renders as `anyOf` and which this check walks away from by
+                    // design — so "matches its schema" would be a promise it does not keep, and
+                    // an over-claimed ✓ is how an author stops reading `--remote` output.
+                    : { kind: 'passed', line: 'declaration files carry no unknown or missing keys (unions are left to --remote)' };
+            },
+        },
+    ];
+    const skipped = reportChecks(checks, {
+        log: (l) => console.log(l),
+        err: (l) => console.error(l),
+        die,
+    });
     // `--require-kb` is for CI, where a skip nobody reads is worse than a red build.
     if (skipped.length && flags['require-kb'] === true) {
         die(`--require-kb: ${skipped.length} check${skipped.length === 1 ? '' : 's'} could not run (${skipped.join(', ')})`);

package/dist/lib/outcome.js

@@ -0,0 +1,79 @@
+/**
+ * `Outcome` — what one `octwin validate` check ACTUALLY did, as a value.
+ *
+ * ## Why this exists
+ *
+ * `cmdValidate` used to hand-write its own `✓` per check, inside the `if` that had the
+ * check's data, with a `skipped[]` array and a `skipReasons` Map maintained alongside. It
+ * was correct because someone was careful, and the next check added was one `if` away from
+ * lying again. It had lied before, twice, in the same shape:
+ *
+ *   - the KB-dependent block printed ONE `✓` above six checks whose own `✓`s lived inside
+ *     their `if`s, so a run with no pulled KB read as "one check, passed". An entire backlog
+ *     batch reached production that way;
+ *   - `yamlDocs()` parsed inside `try { … } catch { return [] }`, so a file that failed to
+ *     parse was silently DROPPED and every later check skipped it — `validate` printed
+ *     all-green over a pack the platform's importer then refused with the same message, from
+ *     the same `yaml` version this CLI already had.
+ *
+ * **An unparseable file is not "no findings", it is "no idea", and those must never print the
+ * same.** So a check no longer prints; it RETURNS one of three things, and a single printer
+ * renders all of them. A check that returns nothing cannot reach the `passed` branch, which
+ * makes the false-`✓` unrepresentable rather than merely discouraged.
+ *
+ * ## Why `not-run` carries the lookup rather than a message
+ *
+ * `describeKbLookup` phrases it at print time, so the wording lives in the module that owns
+ * the three KB states and cannot drift into a doubled "SKIPPED — SKIPPED —". It also lets the
+ * printer GROUP by reason: when the KB is absent every check skips for the identical reason,
+ * and six copies of one sentence is how a reader learns to scroll past the ⚠ block — the same
+ * failure as not printing it at all.
+ */
+import { describeKbLookup } from './kb-path.js';
+/**
+ * Run every check in order and print exactly what each returned.
+ *
+ * Returns the labels that could not run, so the caller can decide what a partial pass means
+ * (`--require-kb` fails on any; an interactive run says which, last, where it is read).
+ *
+ * The first `findings` outcome terminates via `die`, matching the previous behaviour: an
+ * author fixes one class at a time, and printing six screens of unrelated findings buries the
+ * first. Order therefore matters and is the caller's to choose.
+ */
+export function reportChecks(checks, io) {
+    const notRun = [];
+    for (const check of checks) {
+        const outcome = check.run();
+        switch (outcome.kind) {
+            case 'passed':
+                io.log(`✓ ${outcome.line}`);
+                break;
+            case 'findings': {
+                const n = outcome.lines.length;
+                io.err(`✗ ${n} ${outcome.noun}${n === 1 ? '' : 's'}:`);
+                for (const line of outcome.lines)
+                    io.err(`  ✗ ${line}`);
+                io.die(outcome.hint);
+            }
+            // eslint-disable-next-line no-fallthrough -- `die` returns never; the case above cannot exit.
+            case 'not-run':
+                notRun.push({ label: check.label, lookup: outcome.lookup });
+                break;
+        }
+    }
+    // One ⚠ per distinct reason, naming every check it cost. Grouped by the lookup's IDENTITY.
+    const byReason = new Map();
+    for (const { label, lookup } of notRun) {
+        const key = lookup.state === 'ok'
+            ? 'ok'
+            : `${lookup.state}|${'dir' in lookup ? lookup.dir : ''}|${'reason' in lookup ? lookup.reason : ''}`;
+        const bucket = byReason.get(key) ?? { lookup, labels: [] };
+        bucket.labels.push(label);
+        byReason.set(key, bucket);
+    }
+    for (const { lookup, labels } of byReason.values()) {
+        const what = labels.length === 1 ? labels[0] : `${labels.length} checks (${labels.join(', ')})`;
+        io.log(`⚠ ${describeKbLookup(lookup, what)}`);
+    }
+    return notRun.map(n => n.label);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "octwin-cli",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "description": "Octwin external-pack developer CLI (by CEQUENS) — scaffold, validate, deploy, and check pure-YAML packs on your tenant.",
   "type": "module",
   "bin": {