@geraldmaron/construct 1.4.1 → 1.5.0

package/lib/providers/secret-audit-wiring.mjs

@@ -3,30 +3,53 @@
  * audit trail.
  *
  * enableSecretAuditTrail routes the value-free events from secret-resolver into the
- * append-only audit log (lib/audit-trail.mjs). Only actual op:// resolutions are
- * recorded — the prompt-bearing, security-significant events — not cache hits or
- * high-frequency plain reads, so the resolve path is not serialized behind a file
- * lock. The materialized secret value is never available to this layer and is never
- * written. Wiring is per-process: the CLI entrypoint enables it; worker and daemon
- * processes are a tracked follow-up.
+ * append-only audit log (lib/audit-trail.mjs). Two event types are recorded:
+ * - secret.op_read: an actual op:// CLI read (prompt-bearing, never cached)
+ * - secret.resolve (non-op): any plaintext tier resolution (project-env, config-env,
+ *   home-env, shell-rc, alt-store) — records the source tier, never the value
+ * Cache hits on op reads are skipped; op-ref resolve events are skipped because
+ * their paired op_read event carries the canonical record. The materialized secret
+ * value is never available to this layer and is never written.
  */
 
 import { appendAuditRecord } from '../audit-trail.mjs';
 import { setSecretAuditSink } from './secret-resolver.mjs';
 
 export function enableSecretAuditTrail({ file } = {}) {
+  const sink = file ? { file } : {};
   setSecretAuditSink((event) => {
-    if (event.event !== 'secret.op_read' || event.cacheHit) return;
-    appendAuditRecord(
-      {
-        ts: new Date().toISOString(),
-        tool: 'secret-resolver',
-        action: 'op_read',
-        ref: event.ref,
-        ok: event.ok,
-        code: event.code ?? null,
-      },
-      file ? { file } : {},
-    );
+    if (event.event === 'secret.op_read') {
+      if (event.cacheHit) return;
+
+      // Persisting the op:// ref (vault/item/field — not the value) into
+      // Construct's own audit JSONL is a recorded design decision (remediation
+      // plan Epic 6, construct-trxz.6), distinct from the mcp-platform-config.mjs
+      // prohibition on writing op:// refs into host-readable MCP config files.
+
+      appendAuditRecord(
+        {
+          ts: new Date().toISOString(),
+          tool: 'secret-resolver',
+          action: 'op_read',
+          ref: event.ref,
+          ok: event.ok,
+          code: event.code ?? null,
+        },
+        sink,
+      );
+    } else if (event.event === 'secret.resolve' && !event.isOpRef) {
+      appendAuditRecord(
+        {
+          ts: new Date().toISOString(),
+          tool: 'secret-resolver',
+          action: 'resolve',
+          varName: event.varName,
+          source: event.source ?? null,
+          ok: event.ok,
+          code: event.code ?? null,
+        },
+        sink,
+      );
+    }
   });
 }

package/lib/providers/secret-resolver.mjs

@@ -12,11 +12,12 @@
  * `$(op read 'op://...')` — it is resolved through the `op` CLI and cached for
  * the process lifetime so a single launch prompts at most once per reference.
  *
- * One divergence from loadConstructEnv is intentional and tracked separately: that
- * merge ranks the config files above process.env to defeat stale shell exports,
- * while this resolver honors a directly-passed env value first so a hermetic caller
- * can inject its own credentials. Unifying the process.env tier touches the live
- * LLM path and is deferred to a follow-up.
+ * The process.env tier follows one precedence ladder shared with loadConstructEnv:
+ * when file discovery is enabled (allowAmbient), the file tiers win over an ambient
+ * shell export so a stale export cannot shadow a managed config value, with the same
+ * carve-out that a materialized credential injected on the env beats a stored op://
+ * reference (preferInjectedCredential). A hermetic caller sets allowAmbient:false to
+ * suppress all file/rc discovery and use only the directly-injected env.
  *
  * resolveSecret performs the `op read` (and may surface a structured
  * SecretResolutionError); hasSecret only checks presence and never invokes the
@@ -24,14 +25,20 @@
  * value lives only in this module's cache and is never logged. allowAmbient lets
  * a hermetic caller (tests, embedded callers that inject their own env) suppress
  * file/rc discovery so a developer key never bleeds into an isolated run.
+ * peekRawCredential shares the same tiers for a non-secret display value (a repo
+ * slug, a host URL) — shape-only, never resolving an op:// reference. Any
+ * status/detection surface (ADR-0049 §2) should use hasSecret/hasAnySecret/
+ * peekRawCredential rather than reimplementing file or shell-rc scanning.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { spawnSync } from 'node:child_process';
+import { spawnSync, spawn } from 'node:child_process';
 import { discoverAlternateRawForVar } from './credential-sources.mjs';
+import { locateOpBinary } from './op-locate.mjs';
 import { configDir } from '../config/xdg.mjs';
+import { preferInjectedCredential, parseEnvContent } from '../env-config.mjs';
 
 // The 1Password desktop integration prompts for biometric unlock on the first
 // read after the vault locks, and that interactive round-trip routinely takes
@@ -89,30 +96,145 @@ export function extractOpRef(rawValue) {
   return m ? m[2] : null;
 }
 
-function defaultOpRead(opRef) {
-  const result = spawnSync('op', ['read', opRef], { encoding: 'utf8', timeout: OP_READ_TIMEOUT_MS });
-  if (result.error && result.error.code === 'ENOENT') {
+// A 1Password service account (OP_SERVICE_ACCOUNT_TOKEN) makes `op read`/`op run`
+// non-interactive — no desktop app, no biometric, no `op signin` — which fits a
+// multi-process / daemon / headless runtime and CI. It is opt-in: with no token the
+// desktop app integration remains the default. The `op` CLI auto-detects the token
+// from its process env; forwarding it from the caller's env (not just the ambient
+// shell) lets Construct source it from the OS keychain at runtime rather than
+// storing it in plaintext. Note: a service account cannot read the built-in
+// Personal/Private vault and is rate-limited (1k reads/day on the Individual tier),
+// so it pairs with resolve-once, not per-process op read.
+// Docs: https://developer.1password.com/docs/service-accounts/
+
+export function opServiceAccountToken(env = process.env) {
+  const token = env?.OP_SERVICE_ACCOUNT_TOKEN;
+  return typeof token === 'string' && token.trim() ? token.trim() : null;
+}
+
+function defaultOpWhoami() {
+  const opPath = locateOpBinary();
+  if (!opPath) return { installed: false, signedIn: false };
+  const result = spawnSync(opPath, ['whoami'], { encoding: 'utf8', timeout: 5000 });
+  if (result.error && result.error.code === 'ENOENT') return { installed: false, signedIn: false };
+  return { installed: true, signedIn: result.status === 0 };
+}
+
+// Which 1Password auth mode `op` will use for a resolution, for doctor/diagnostics.
+// A service-account token is non-interactive; otherwise `op` relies on the desktop
+// app session, and `op whoami` reveals whether that session is live (a cold session
+// is the usual cause of repeated biometric prompts). `whoami` is checked, not `read`,
+// so it never prompts. Injectable for tests.
+
+export function describeOpAuthMode(env = process.env, { whoami = defaultOpWhoami } = {}) {
+  if (opServiceAccountToken(env)) {
+    return { mode: 'service-account', signedIn: true, detail: 'OP_SERVICE_ACCOUNT_TOKEN set — op read/op run authenticate non-interactively.' };
+  }
+  const state = whoami();
+  if (!state.installed) {
+    return { mode: 'op-absent', signedIn: false, detail: '1Password CLI (op) not installed — set keys directly or install op.' };
+  }
+  if (state.signedIn) {
+    return { mode: 'desktop-session', signedIn: true, detail: 'op is signed in via the desktop app session.' };
+  }
+  return {
+    mode: 'desktop-session',
+    signedIn: false,
+    detail: 'op is not signed in — enable Settings → Developer → Integrate with 1Password CLI, or set OP_SERVICE_ACCOUNT_TOKEN for non-interactive auth.',
+  };
+}
+
+function opReadChildEnv(env) {
+  const token = opServiceAccountToken(env);
+  return token ? { ...process.env, OP_SERVICE_ACCOUNT_TOKEN: token } : process.env;
+}
+
+// Map an `op read` outcome — from the sync spawnSync reader or the async spawn reader —
+// to the resolved secret or a classified SecretResolutionError. Both readers funnel
+// through here so their error taxonomy (OP_NOT_INSTALLED / OP_NOT_SIGNED_IN /
+// OP_READ_FAILED / OP_EMPTY) cannot drift apart.
+
+function interpretOpReadResult(opRef, { enoent, status, stdout, stderr }) {
+  if (enoent) {
     throw new SecretResolutionError('1Password CLI not found — install `op` or set the key directly.', 'OP_NOT_INSTALLED');
   }
-  if (result.status !== 0) {
-    const stderr = String(result.stderr || '').toLowerCase();
-    if (/sign in|signin|session|not currently|authenticate|authorization|no account/.test(stderr)) {
-      throw new SecretResolutionError('1Password CLI is not signed in — run `op signin` and retry.', 'OP_NOT_SIGNED_IN');
+  if (status !== 0) {
+    const err = String(stderr || '').toLowerCase();
+    if (/sign in|signin|session|not currently|authenticate|authorization|no account/.test(err)) {
+      throw new SecretResolutionError('1Password CLI is not signed in — enable the desktop app CLI integration (Settings → Developer) and unlock, or set OP_SERVICE_ACCOUNT_TOKEN for non-interactive access.', 'OP_NOT_SIGNED_IN');
     }
-    throw new SecretResolutionError(`op read failed for ${opRef}: ${String(result.stderr || '').trim().slice(0, 160)}`, 'OP_READ_FAILED');
+    throw new SecretResolutionError(`op read failed for ${opRef}: ${String(stderr || '').trim().slice(0, 160)}`, 'OP_READ_FAILED');
   }
-  const secret = String(result.stdout || '').trim();
+  const secret = String(stdout || '').trim();
   if (!secret) throw new SecretResolutionError(`op read returned an empty value for ${opRef}`, 'OP_EMPTY');
   return secret;
 }
 
-export function resolveOpRef(opRef, { opRead = defaultOpRead } = {}) {
+function defaultOpRead(opRef, { env = process.env } = {}) {
+  const opPath = locateOpBinary();
+  if (!opPath) {
+    throw new SecretResolutionError('1Password CLI not found — install `op` or set the key directly.', 'OP_NOT_INSTALLED');
+  }
+  const result = spawnSync(opPath, ['read', opRef], { encoding: 'utf8', timeout: OP_READ_TIMEOUT_MS, env: opReadChildEnv(env) });
+  return interpretOpReadResult(opRef, {
+    enoent: Boolean(result.error && result.error.code === 'ENOENT'),
+    status: result.status,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  });
+}
+
+// The MCP CallTool path resolves provider keys inside the single-threaded server, so
+// a spawnSync `op read` freezes the event loop — and its own Promise.race timeout
+// guard — for up to OP_READ_TIMEOUT_MS on the first op:// touch. This async reader
+// uses spawn so the loop keeps turning, killing the child at the same timeout and
+// mapping the outcome through the same interpretOpReadResult.
+
+function defaultOpReadAsync(opRef, { env = process.env } = {}) {
+  return new Promise((resolve, reject) => {
+    const opPath = locateOpBinary();
+    if (!opPath) {
+      reject(new SecretResolutionError('1Password CLI not found — install `op` or set the key directly.', 'OP_NOT_INSTALLED'));
+      return;
+    }
+    const child = spawn(opPath, ['read', opRef], { env: opReadChildEnv(env) });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let timer = null;
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      fn();
+    };
+    timer = setTimeout(() => {
+      try { child.kill('SIGKILL'); } catch { /* already exited */ }
+      finish(() => reject(new SecretResolutionError(`op read failed for ${opRef}: timed out after ${OP_READ_TIMEOUT_MS}ms`, 'OP_READ_FAILED')));
+    }, OP_READ_TIMEOUT_MS);
+    child.stdout?.on('data', (d) => { stdout += String(d); });
+    child.stderr?.on('data', (d) => { stderr += String(d); });
+    child.on('error', (opErr) => finish(() => {
+      if (opErr && opErr.code === 'ENOENT') {
+        reject(new SecretResolutionError('1Password CLI not found — install `op` or set the key directly.', 'OP_NOT_INSTALLED'));
+        return;
+      }
+      reject(opErr);
+    }));
+    child.on('close', (code) => finish(() => {
+      try { resolve(interpretOpReadResult(opRef, { enoent: false, status: code, stdout, stderr })); }
+      catch (err) { reject(err); }
+    }));
+  });
+}
+
+export function resolveOpRef(opRef, { opRead = defaultOpRead, env = process.env } = {}) {
   if (opCache.has(opRef)) {
     emitAudit({ event: 'secret.op_read', ref: opRef, cacheHit: true, ok: true });
     return opCache.get(opRef);
   }
   try {
-    const secret = opRead(opRef);
+    const secret = opRead(opRef, { env });
     opCache.set(opRef, secret);
     emitAudit({ event: 'secret.op_read', ref: opRef, cacheHit: false, ok: true });
     return secret;
@@ -127,11 +249,17 @@ function materialize(rawValue, opts) {
   return ref ? resolveOpRef(ref, opts) : unquote(rawValue);
 }
 
+// Delegates to env-config's parseEnvContent so a dotenv value never diverges
+// from loadConstructEnv's reading of the same file (construct-192h.10) — in
+// particular an unpaired quote (`KEY="abc`) resolves to the same byte-identical
+// value on both paths instead of the resolver's own quote-pairing regex leaving
+// the stray quote in place.
+
 function readDotenvVar(file, varName) {
   try {
     if (!fs.existsSync(file)) return null;
-    const m = fs.readFileSync(file, 'utf8').match(new RegExp(`^${varName}=(.+)$`, 'm'));
-    return m ? m[1].trim() : null;
+    const parsed = parseEnvContent(fs.readFileSync(file, 'utf8'));
+    return Object.prototype.hasOwnProperty.call(parsed, varName) ? parsed[varName] : null;
   } catch {
     return null;
   }
@@ -181,9 +309,8 @@ function readFromOpEnvCatalog(varName, { env, home }) {
 }
 
 function rawCandidate(varName, { env, cwd, home }) {
-  const direct = env?.[varName];
-  if (typeof direct === 'string' && direct.length > 0) return { raw: direct, source: 'env' };
-
+  // Pure file/store discovery: the ambient env tier is ranked by the callers
+  // (resolveSecret / hasSecret) so one precedence ladder governs env-vs-file.
   // File tier matches loadConstructEnv: the project .env (closest to the work)
   // wins over the machine-wide XDG config.env, which wins over a generic ~/.env.
   const files = [
@@ -218,18 +345,32 @@ function resolveAndAudit(varName, raw, source, opts) {
 
 export function resolveSecret(varName, { env = process.env, cwd = process.cwd(), allowAmbient = true, opRead } = {}) {
   const direct = env?.[varName];
-  if (typeof direct === 'string' && direct.length > 0) return resolveAndAudit(varName, direct, 'env', { opRead });
+  const hasDirect = typeof direct === 'string' && direct.length > 0;
+
+  // Hermetic mode: only the directly-injected env is consulted, no file/rc discovery,
+  // so a developer key never bleeds into an isolated run.
   if (!allowAmbient) {
+    if (hasDirect) return resolveAndAudit(varName, direct, 'env', { opRead, env });
     emitAudit({ event: 'secret.resolve', varName, source: null, isOpRef: false, ok: false });
     return null;
   }
+
   const home = os.homedir();
   const found = rawCandidate(varName, { env, cwd, home });
-  if (!found) {
-    emitAudit({ event: 'secret.resolve', varName, source: null, isOpRef: false, ok: false });
-    return null;
+
+  // Precedence parity with loadConstructEnv: the file tiers win over an ambient shell
+  // export, except a materialized credential injected on the env beats a stored op://
+  // reference so a single `op run` auth suffices.
+  if (found) {
+    if (hasDirect && preferInjectedCredential(direct, found.raw)) {
+      return resolveAndAudit(varName, direct, 'env', { opRead, env });
+    }
+    return resolveAndAudit(varName, found.raw, found.source, { opRead, env });
   }
-  return resolveAndAudit(varName, found.raw, found.source, { opRead });
+
+  if (hasDirect) return resolveAndAudit(varName, direct, 'env', { opRead, env });
+  emitAudit({ event: 'secret.resolve', varName, source: null, isOpRef: false, ok: false });
+  return null;
 }
 
 export function resolveFirstSecret(varNames, opts = {}) {
@@ -240,15 +381,81 @@ export function resolveFirstSecret(varNames, opts = {}) {
   return null;
 }
 
+// Async twins for the MCP CallTool hot path: file/rc discovery stays synchronous
+// (small local fs reads, not the blocking step), but op:// materialization uses
+// defaultOpReadAsync (spawn) instead of spawnSync so the single-threaded MCP server's
+// event loop keeps turning during a slow `op read`. The shared opCache means a value
+// resolved by either the sync or async path serves both, so a warm ref never re-spawns.
+
+export async function resolveOpRefAsync(opRef, { opRead = defaultOpReadAsync, env = process.env } = {}) {
+  if (opCache.has(opRef)) {
+    emitAudit({ event: 'secret.op_read', ref: opRef, cacheHit: true, ok: true });
+    return opCache.get(opRef);
+  }
+  try {
+    const secret = await opRead(opRef, { env });
+    opCache.set(opRef, secret);
+    emitAudit({ event: 'secret.op_read', ref: opRef, cacheHit: false, ok: true });
+    return secret;
+  } catch (err) {
+    emitAudit({ event: 'secret.op_read', ref: opRef, cacheHit: false, ok: false, code: err?.code });
+    throw err;
+  }
+}
+
+async function materializeAsync(rawValue, opts) {
+  const ref = extractOpRef(rawValue);
+  return ref ? resolveOpRefAsync(ref, opts) : unquote(rawValue);
+}
+
+async function resolveAndAuditAsync(varName, raw, source, opts) {
+  const isOpRef = Boolean(extractOpRef(raw));
+  try {
+    const value = await materializeAsync(raw, opts);
+    emitAudit({ event: 'secret.resolve', varName, source, isOpRef, ok: true });
+    return value;
+  } catch (err) {
+    emitAudit({ event: 'secret.resolve', varName, source, isOpRef, ok: false, code: err?.code });
+    throw err;
+  }
+}
+
+export async function resolveSecretAsync(varName, { env = process.env, cwd = process.cwd(), allowAmbient = true, opRead } = {}) {
+  const direct = env?.[varName];
+  const hasDirect = typeof direct === 'string' && direct.length > 0;
+
+  if (!allowAmbient) {
+    if (hasDirect) return resolveAndAuditAsync(varName, direct, 'env', { opRead, env });
+    emitAudit({ event: 'secret.resolve', varName, source: null, isOpRef: false, ok: false });
+    return null;
+  }
+
+  const home = os.homedir();
+  const found = rawCandidate(varName, { env, cwd, home });
+
+  if (found) {
+    if (hasDirect && preferInjectedCredential(direct, found.raw)) {
+      return resolveAndAuditAsync(varName, direct, 'env', { opRead, env });
+    }
+    return resolveAndAuditAsync(varName, found.raw, found.source, { opRead, env });
+  }
+
+  if (hasDirect) return resolveAndAuditAsync(varName, direct, 'env', { opRead, env });
+  emitAudit({ event: 'secret.resolve', varName, source: null, isOpRef: false, ok: false });
+  return null;
+}
+
 // Presence check that never runs `op read`: a stored op:// reference counts as
-// configured because the plaintext is resolved lazily at call time.
+// configured because the plaintext is resolved lazily at call time. `home`
+// defaults to os.homedir() but is overridable so a status/detection caller can
+// point at an injected homeDir without mutating process.env.HOME.
 
-export function hasSecret(varName, { env = process.env, cwd = process.cwd(), allowAmbient = true } = {}) {
+export function hasSecret(varName, { env = process.env, cwd = process.cwd(), allowAmbient = true, home } = {}) {
   const direct = env?.[varName];
   if (typeof direct === 'string' && direct.length > 0) return true;
   if (!allowAmbient) return false;
-  const home = os.homedir();
-  const found = rawCandidate(varName, { env, cwd, home });
+  const resolvedHome = home || os.homedir();
+  const found = rawCandidate(varName, { env, cwd, home: resolvedHome });
   return Boolean(found && typeof found.raw === 'string' && found.raw.length > 0);
 }
 
@@ -256,6 +463,31 @@ export function hasAnySecret(varNames, opts = {}) {
   return varNames.some((name) => hasSecret(name, opts));
 }
 
+// A non-secret configuration value (a repo slug, a Jira host URL, a Confluence
+// space key) still needs shape-based detection — file/rc presence and its raw
+// text — without ever resolving an op:// reference, so a display-only read
+// shares the same tiers as hasSecret rather than a caller re-implementing
+// dotenv/rc scanning. Returns null when nothing is found; never invokes `op read`.
+
+export function peekRawCredential(varName, { env = process.env, cwd = process.cwd(), allowAmbient = true, home } = {}) {
+  const direct = env?.[varName];
+  if (typeof direct === 'string' && direct.length > 0) return { raw: unquote(direct), source: 'env' };
+  if (!allowAmbient) return null;
+  const resolvedHome = home || os.homedir();
+  const found = rawCandidate(varName, { env, cwd, home: resolvedHome });
+  return found ? { raw: unquote(found.raw), source: found.source } : null;
+}
+
 export function __clearSecretCache() {
   opCache.clear();
 }
+
+// Read-only accessor for the materialized op:// cache. Callers that redact
+// durable output (lib/audit-trail.mjs) need to compare candidate strings
+// against known-resolved secret values without this module logging or
+// otherwise changing its own resolution behavior; this returns a snapshot
+// array, never the live Map, so a consumer cannot mutate the cache.
+
+export function __resolvedSecretValues() {
+  return Array.from(opCache.values());
+}

package/lib/publish-template.mjs

@@ -102,7 +102,7 @@ function stripCoverDuplicatesFromBody(body, metadata = {}) {
     out = out.replace(h1Re, '');
   }
   const lines = out.split('\n');
-  while (lines.length && /^-\s+\*\*(Date|Owner|Status)\*\*:/i.test(lines[0].trim())) {
+  while (lines.length && /^-\s+\*\*(Date|Owner|Status):?\*\*:?/i.test(lines[0].trim())) {
     lines.shift();
   }
   while (lines.length && lines[0].trim() === '') lines.shift();
@@ -135,9 +135,12 @@ export function parseArtifactMetadata(inputPath) {
     }
   }
 
+  // Authors write both `**Date**: x` and `**Date:** x`; the contract accepts
+  // either so the masthead never silently loses a field to colon placement.
+
   const h1 = body.match(/^#\s+(.+)$/m);
-  const ownerMatch = body.match(/\*\*Owner\*\*:\s*(\S+)/);
-  const dateMatch = body.match(/\*\*Date\*\*:\s*(\S+)/);
+  const ownerMatch = body.match(/\*\*Owner:?\*\*:?\s*(\S+)/i);
+  const dateMatch = body.match(/\*\*Date:?\*\*:?\s*(\S+)/i);
 
   return {
     title: fm.title || (h1 ? h1[1].trim() : path.basename(inputPath, path.extname(inputPath))),

package/lib/publish-tooling.mjs

@@ -14,6 +14,7 @@ import { detect as detectExport } from './document-export.mjs';
 import { locateRenderer } from './diagram.mjs';
 import { locateRecorder } from './demo.mjs';
 import { detectIngestPipeline } from './ingest-tooling.mjs';
+import { resolvePuppeteerExecutable } from './diagram-export.mjs';
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -32,11 +33,13 @@ export function detectFigureBinaries(env = process.env) {
   const d2 = whichBin('d2');
   const mmdc = whichBin('mmdc');
   const dot = whichBin('dot');
+  const chrome = resolvePuppeteerExecutable(env);
   const filter = fs.existsSync(diagramFilterPath());
   const missing = [];
   if (!filter) missing.push('diagram.lua (vendor/pandoc-ext/diagram.lua)');
   if (!d2 && !dot) missing.push('d2 or graphviz dot');
   if (!mmdc) missing.push('mmdc (@mermaid-js/mermaid-cli)');
+  if (mmdc && !chrome) missing.push('Chrome for mermaid-cli (set PUPPETEER_EXECUTABLE_PATH or install Google Chrome)');
   return {
     ok: true,
     present: missing.length === 0,
@@ -44,6 +47,7 @@ export function detectFigureBinaries(env = process.env) {
     d2,
     dot,
     mmdc,
+    chrome,
     missing,
     message: missing.length === 0
       ? 'Figure tooling ready (pandoc-ext/diagram + d2/mmdc)'

package/lib/publish.mjs

@@ -193,13 +193,21 @@ export function runPublish({
     }
   }
 
+  const exportOk = ledger.export?.ok !== false;
+  const validationOk = ledger.validation?.ok !== false;
+  const relOutput = ledger.export?.outputPath ? path.relative(cwd, ledger.export.outputPath) : null;
+
   return {
-    ok: ledger.export?.ok !== false,
+    ok: exportOk && validationOk,
     ledger,
     message: ledger.export?.skipped
       ? 'Publish source-only complete'
-      : ledger.export?.ok
+      : exportOk && validationOk
         ? `Published ${path.relative(cwd, ledger.export.outputPath)}`
+        : !validationOk && relOutput
+          ? preview
+            ? `Preview rendered with validation failures: ${relOutput}`
+            : `Publish blocked: output validation failed for ${relOutput}`
         : ledger.export?.message || detection.message,
   };
 }
@@ -235,12 +243,17 @@ Examples:
 `);
 }
 
-export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot } = {}) {
+// Every flag the publish spec declares maps to a behavior here; an unrecognized
+// `--flag` is collected into `unknown` so the CLI can warn instead of silently
+// dropping it (the pre-fix parser discarded --recording/--figures without a trace).
+
+export function parsePublishArgs(argv = []) {
   const options = {
     format: 'pdf',
     output: null,
     type: null,
     demos: [],
+    recordings: [],
     figures: true,
     strict: true,
     gate: true,
@@ -249,6 +262,7 @@ export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot }
     preview: false,
     help: false,
     input: null,
+    unknown: [],
   };
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -257,6 +271,7 @@ export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot }
     if (arg === '--strict') { options.strict = true; continue; }
     if (arg === '--no-strict') { options.strict = false; continue; }
     if (arg === '--source-only') { options.sourceOnly = true; continue; }
+    if (arg === '--figures') { options.figures = true; continue; }
     if (arg === '--no-figures') { options.figures = false; continue; }
     if (arg === '--no-gate') { options.gate = false; continue; }
     if (arg === '--preview') { options.preview = true; continue; }
@@ -269,8 +284,17 @@ export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot }
     if (arg.startsWith('--type=')) { options.type = arg.slice(7); continue; }
     if (arg === '--demo') { options.demos.push(argv[++i]); continue; }
     if (arg.startsWith('--demo=')) { options.demos.push(arg.slice(7)); continue; }
-    if (!arg.startsWith('--')) options.input = arg;
+    if (arg === '--recording') { options.recordings.push(argv[++i]); continue; }
+    if (arg.startsWith('--recording=')) { options.recordings.push(arg.slice('--recording='.length)); continue; }
+    if (!arg.startsWith('--')) { options.input = arg; continue; }
+    options.unknown.push(arg);
   }
+  return options;
+}
+
+export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot } = {}) {
+  const options = parsePublishArgs(argv);
+  for (const flag of options.unknown) console.error(`[publish] Ignoring unknown flag: ${flag}`);
 
   if (options.help) {
     printPublishHelp();
@@ -299,6 +323,7 @@ export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot }
     format: options.format,
     outputPath: options.output,
     demos: options.demos,
+    recordings: options.recordings,
     figures: options.figures,
     strict: options.strict,
     gate: options.gate,
@@ -346,6 +371,9 @@ export async function runPublishCli(argv = [], { cwd = process.cwd(), repoRoot }
   }
 
   console.error(result.message);
+  if (result.ledger?.validation?.ok === false) {
+    for (const failure of result.ledger.validation.failures || []) console.error(`  - ${failure}`);
+  }
   const exitCode = result.strict && (result.missing?.length || result.gateBlocked) ? 2 : 1;
   return { exitCode, result };
 }