baldart 4.64.0 → 4.65.0

package/src/commands/doctor.js

@@ -479,6 +479,54 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) { /* never block doctor on i18n probe */ }
 
+    // ---- Design-system manifest + DTCG tokens (since v4.65.0) ----------
+    // Two backfills, both gated on has_design_system (no separate flag — the
+    // manifest rides on the design-system layer). (1) "default-on + nudge":
+    // when the registry exists but specs are missing or still prose-only (no
+    // machine-readable HEAD), nudge /design-system-init. (2) token SSOT: when
+    // paths.design_tokens is set, flag generated outputs that drifted from the
+    // DTCG source (or a hand-edited generated file).
+    state.dsManifestNudge = false;
+    state.dsManifestReason = '';
+    state.tokensStale = false;
+    state.tokensStalePaths = [];
+    try {
+      if (config && !config.__malformed && config.features && config.features.has_design_system === true) {
+        const dsRoot = (config.paths && config.paths.design_system) || '';
+        if (dsRoot) {
+          const compDir = path.join(cwd, dsRoot, 'components');
+          let specs = [];
+          try { specs = fs.readdirSync(compDir).filter((f) => f.endsWith('.md')); } catch (_) { specs = []; }
+          if (specs.length === 0) {
+            state.dsManifestNudge = true;
+            state.dsManifestReason = 'no per-component specs found';
+          } else {
+            // Cheap sample: does ANY spec carry a frontmatter HEAD (starts with `---`)?
+            const structured = specs.slice(0, 8).some((f) => {
+              try { return fs.readFileSync(path.join(compDir, f), 'utf8').startsWith('---'); }
+              catch (_) { return false; }
+            });
+            if (!structured) {
+              state.dsManifestNudge = true;
+              state.dsManifestReason = 'specs are prose-only (no machine-readable HEAD)';
+            }
+          }
+        }
+        // DTCG token SSOT staleness.
+        const src = (config.paths && config.paths.design_tokens) || '';
+        const outs = (config.design_tokens && config.design_tokens.outputs) || [];
+        if (src && outs.length) {
+          const TokensGenerator = require('../utils/tokens-generator');
+          const st = new TokensGenerator(cwd).isStale({ source: src, outputs: outs });
+          if (st.stale) {
+            state.tokensStale = true;
+            state.tokensStalePaths = (st.reasons || []).map((r) => r.path);
+            state.tokensStaleError = st.error || null;
+          }
+        }
+      }
+    } catch (_) { /* never block doctor on design-system probe */ }
+
     // ---- Auto-deploy allowlist presence (since v4.59.0) ----------------
     // Purely informational: git.auto_deploy bounds what `/new -auto-ship`
     // may execute as an OUTWARD action. An empty allowlist is the SAFE
@@ -1013,6 +1061,43 @@ function planActions(state) {
     });
   }
 
+  // ---- Design-system manifest + DTCG tokens (since v4.65.0) ----------
+  // (1) Rebuild stale generated token artifacts from the DTCG SSOT — offline,
+  // deterministic, idempotent → autoOk. (2) Nudge the manifest bootstrap when
+  // the registry is present but specs are missing/prose-only (the "default-on
+  // + nudge" behavior; informational, never auto-mutates source).
+  if (state.tokensStale) {
+    actions.push({
+      key: 'tokens-build',
+      label: state.tokensStaleError
+        ? 'Design tokens: DTCG source has an error — fix then rebuild'
+        : `Rebuild generated token artifacts from the DTCG source (${state.tokensStalePaths.join(', ')})`,
+      why: state.tokensStaleError
+        ? `paths.design_tokens is set but the DTCG source could not be parsed: ${state.tokensStaleError}. Fix the .tokens.json, then \`baldart tokens build\`.`
+        : 'The generated token output(s) drifted from the DTCG SSOT (a hand-edit to a generated file, or the source changed without a rebuild). `baldart tokens build` regenerates them (offline, no API cost). Edit `.tokens.json`, never the generated output.',
+      autoOk: !state.tokensStaleError, // a parse error needs a human; a plain rebuild is safe
+      run: async () => {
+        if (state.tokensStaleError) {
+          UI.warning(`DTCG source error: ${state.tokensStaleError}. Fix it, then run \`baldart tokens build\`.`);
+          return;
+        }
+        const tokens = require('./tokens');
+        await tokens.build({ cwd: state.cwd });
+      },
+    });
+  }
+  if (state.dsManifestNudge) {
+    actions.push({
+      key: 'ds-manifest-nudge',
+      label: `Design-system specs need a machine-readable upgrade — run /design-system-init (${state.dsManifestReason})`,
+      why: `features.has_design_system is true but ${state.dsManifestReason}. Agents fall back to reading the monolithic INDEX + component source (slow). Running /design-system-init (upgrade mode) generates the per-component frontmatter HEAD + a thin INDEX router so discovery reads small structured specs on demand. See framework/agents/component-manifest-schema.md.`,
+      autoOk: false, // a skill that reads source + enriches — never run unattended from doctor
+      run: async () => {
+        UI.info('Run `/design-system-init` in your editor to upgrade the per-component specs to the machine-readable HEAD and regenerate the thin INDEX router. See framework/docs/COMPONENT-MANIFEST-LAYER.md.');
+      },
+    });
+  }
+
   // Auto-deploy allowlist (since v4.59.0). Advisory print-only — surfaced ONLY
   // when the allowlist is non-empty (the safe default of empty/unset opens
   // nothing, so it warrants no nag). Reminds the user that `/new -auto-ship`

package/src/commands/tokens.js

@@ -0,0 +1,80 @@
+/**
+ * `baldart tokens build` — regenerate the stack-native token artifacts from the
+ * DTCG SSOT (since v4.65.0).
+ *
+ * The design-token source of truth is the DTCG `.tokens.json` at
+ * `paths.design_tokens`; the artifacts agents/components consume (tokens.ts, a
+ * CSS custom-property sheet) are GENERATED from it and carry a
+ * `baldart-generated` banner. This verb is what the `/design-system-init` skill,
+ * `baldart doctor`, and (later) a git hook CALL — none of them reimplement the
+ * generation (the SSOT for that is `src/utils/tokens-generator.js`).
+ *
+ * Config consumed (baldart.config.yml):
+ *   paths.design_tokens      → the DTCG source (.tokens.json)
+ *   design_tokens.outputs[]  → [{ format: ts|css, path: <file> }]
+ *
+ * Always safe: no source / no outputs → a clear no-op message, exit 0. A bad
+ * DTCG file or a write failure → exit 1 with the reason (it IS a build step).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const UI = require('../utils/ui');
+const TokensGenerator = require('../utils/tokens-generator');
+
+const CONFIG_FILE = 'baldart.config.yml';
+
+function loadConfig(cwd) {
+  const full = path.join(cwd, CONFIG_FILE);
+  try { return yaml.load(fs.readFileSync(full, 'utf8')) || {}; }
+  catch (_) { return null; }
+}
+
+async function tokensBuild(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const json = !!opts.json;
+  const config = loadConfig(cwd);
+
+  const emit = (obj, exit = 0) => {
+    if (json) process.stdout.write(JSON.stringify(obj) + '\n');
+    return exit;
+  };
+
+  if (!config) {
+    if (!json) UI.warning(`No (or malformed) ${CONFIG_FILE} — run \`npx baldart configure\` first.`);
+    return emit({ schema: 'baldart.tokens-build/1', ok: false, reason: 'no-config' }, 1);
+  }
+
+  const source = config.paths && config.paths.design_tokens;
+  const outputs = (config.design_tokens && config.design_tokens.outputs) || [];
+
+  if (!source) {
+    if (!json) UI.info('No `paths.design_tokens` set — DTCG token SSOT not adopted on this project. Nothing to build.');
+    return emit({ schema: 'baldart.tokens-build/1', ok: true, skipped: 'no-source' });
+  }
+
+  const gen = new TokensGenerator(cwd);
+  if (!gen.detect(source)) {
+    if (!json) UI.warning(`design tokens source not found at \`${source}\`. Create it (e.g. via /design-system-init) then re-run.`);
+    return emit({ schema: 'baldart.tokens-build/1', ok: false, reason: 'source-missing', source }, 1);
+  }
+  if (!outputs.length) {
+    if (!json) UI.warning('`design_tokens.outputs` is empty — nothing to generate. Add at least one { format, path }.');
+    return emit({ schema: 'baldart.tokens-build/1', ok: true, skipped: 'no-outputs', source });
+  }
+
+  const res = gen.build({ source, outputs });
+  if (!res.ok) {
+    if (!json) UI.error(`Token build failed: ${res.error}`);
+    return emit({ schema: 'baldart.tokens-build/1', ok: false, reason: res.error, source }, 1);
+  }
+
+  if (!json) {
+    UI.success(`Tokens built from ${source} (${res.tokenCount} tokens):`);
+    for (const p of res.written) UI.info(`  ✓ ${p}`);
+  }
+  return emit({ schema: 'baldart.tokens-build/1', ok: true, source, written: res.written, tokenCount: res.tokenCount });
+}
+
+module.exports = { build: tokensBuild };

package/src/commands/update.js

@@ -1320,6 +1320,12 @@ async function update(options = {}, unknownArgs = []) {
             const missingI18n = Object.keys(tpl.i18n || {})
               .filter((k) => !(k in (cur2.i18n || {})))
               .map((k) => `i18n.${k}`);
+            // `design_tokens:` (since v4.65.0) — same nested-block contract.
+            // Its only key `outputs` is an ARRAY, so (per the v4.46.0 array
+            // lesson) we diff presence of the key, not deep value equality.
+            const missingDesignTokens = Object.keys(tpl.design_tokens || {})
+              .filter((k) => !(k in (cur2.design_tokens || {})))
+              .map((k) => `design_tokens.${k}`);
             const allMissing = [
               ...missingPaths,
               ...missingFeatures,
@@ -1329,6 +1335,7 @@ async function update(options = {}, unknownArgs = []) {
               ...missingToolchain,
               ...missingToolchainCmds,
               ...missingI18n,
+              ...missingDesignTokens,
             ];
             if (allMissing.length) {
               UI.newline();

package/src/utils/token-emitters/README.md

@@ -0,0 +1,36 @@
+# token-emitters
+
+Per-format emitters for the DTCG token generator (`../tokens-generator.js`).
+The DTCG `.tokens.json` (`paths.design_tokens` in `baldart.config.yml`) is the
+design-token SSOT; each emitter turns the resolved token set into ONE
+stack-native artifact. Same REGISTRY pattern as `lsp-adapters/`,
+`routine-adapters/`, `tool-adapters/`, `toolchain-adapters/`.
+
+## Adding a format
+
+1. Create `<format>.js` exporting `module.exports = function emit({ resolved, nested, marker }) { return '<file contents>'; }`.
+   - `resolved`: `Map<dotId, { type, value }>` — fully ref-resolved leaf tokens, source order.
+   - `nested`: nested plain object of resolved **values** (DTCG tree minus `$type`/`$value`).
+   - `marker`: the generated-file banner line for your format (already comment-wrapped).
+2. Register it in `index.js`'s `EMITTERS` map.
+3. If the comment syntax differs from `//` and `/* */`, extend `markerFor()` in `index.js`.
+
+That's it — `tokens-generator.js`, `baldart tokens build`, and `doctor` iterate
+the registry; nothing else changes.
+
+## Invariants
+
+- **Deterministic, diff-stable output**: emit in source order, no timestamps, no
+  randomness — so `isStale()` (on-disk vs fresh render byte-compare) is reliable.
+- **Always emit the `marker`** as the first line — it is how humans and the
+  `framework-edit-gate` know the file is generated and must not be hand-edited.
+- **Pure**: emitters never touch the filesystem; the generator writes.
+- **Zero dependency**: no Style Dictionary, no npm — keep it portable (the build
+  path must run identically under Codex).
+
+## Shipped formats
+
+| format | output |
+|--------|--------|
+| `ts`   | `export const tokens = {…} as const;` + `export type Tokens` |
+| `css`  | `:root { --<dot-id-as-dashes>: <value>; }` |

package/src/utils/token-emitters/css.js

@@ -0,0 +1,18 @@
+// CSS emitter: DTCG → `:root { --<dot-id-as-dashes>: <value>; }`.
+//
+// Token id `color.action.primary` → `--color-action-primary`. Emits resolved
+// values (refs collapsed) in source order so the output is diff-stable.
+
+function cssVarName(dotId) {
+  return `--${dotId.replace(/\./g, '-')}`;
+}
+
+module.exports = function emitCss({ resolved, marker }) {
+  const lines = [];
+  for (const [id, tok] of resolved) {
+    lines.push(`  ${cssVarName(id)}: ${tok.value};`);
+  }
+  return `${marker}\n:root {\n${lines.join('\n')}\n}\n`;
+};
+
+module.exports.cssVarName = cssVarName;

package/src/utils/token-emitters/index.js

@@ -0,0 +1,47 @@
+// Token emitter registry (since v4.65.0).
+//
+// DTCG (`.tokens.json`) is the design-token SSOT; each emitter turns the
+// resolved token set into ONE stack-native artifact (a TS object, a CSS
+// custom-property sheet, …). This is the same REGISTRY pattern as
+// `lsp-adapters/`, `routine-adapters/`, `tool-adapters/`, `toolchain-adapters/`:
+// every other layer iterates this map, so adding a format = drop a file +
+// register it here. Zero npm dependency (no Style Dictionary) — see
+// `framework/docs/COMPONENT-MANIFEST-LAYER.md`.
+//
+// An emitter exports a single function:
+//   emit({ resolved, nested, marker }) -> string   (the file contents)
+// where:
+//   resolved : Map<dotId, { type, value }>  fully ref-resolved leaf tokens
+//   nested   : nested plain object of resolved VALUES (DTCG tree minus $type/$value)
+//   marker   : the "baldart-generated" banner line for this format
+
+const ts = require('./ts');
+const css = require('./css');
+
+const EMITTERS = { ts, css };
+
+/** Stable, format-appropriate generated-file banner. */
+function markerFor(format) {
+  const text = 'baldart-generated from .tokens.json — do not edit (run `baldart tokens build`)';
+  if (format === 'css') return `/* ${text} */`;
+  return `// ${text}`; // ts / js / any C-style
+}
+
+/**
+ * Emit one output. Returns { ok, format, content } or { ok:false, error }.
+ * Pure — does not touch the filesystem (the caller writes).
+ */
+function emit(format, { resolved, nested }) {
+  const fn = EMITTERS[format];
+  if (typeof fn !== 'function') {
+    return { ok: false, error: `unknown token output format: "${format}" (known: ${Object.keys(EMITTERS).join(', ')})` };
+  }
+  const marker = markerFor(format);
+  try {
+    return { ok: true, format, content: fn({ resolved, nested, marker }) };
+  } catch (e) {
+    return { ok: false, error: `emitter "${format}" failed: ${e.message}` };
+  }
+}
+
+module.exports = { emit, markerFor, knownFormats: () => Object.keys(EMITTERS) };

package/src/utils/token-emitters/ts.js

@@ -0,0 +1,32 @@
+// TS emitter: DTCG → a typed `export const tokens = {...} as const;` object.
+//
+// Emits the nested tree of RESOLVED values (refs already collapsed), mirroring
+// the DTCG group structure minus the $type/$value wrappers. Deterministic key
+// order (insertion order of the source) so the output is diff-stable.
+
+function literal(value) {
+  // Tokens resolve to strings (colors, dimensions, durations) or numbers.
+  if (typeof value === 'number') return String(value);
+  return JSON.stringify(String(value));
+}
+
+function render(node, indent) {
+  const pad = '  '.repeat(indent);
+  const padInner = '  '.repeat(indent + 1);
+  const keys = Object.keys(node);
+  const lines = keys.map((k) => {
+    const v = node[k];
+    // A safe JS identifier key can be bare; otherwise quote it (e.g. "2").
+    const key = /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(k) ? k : JSON.stringify(k);
+    if (v && typeof v === 'object') {
+      return `${padInner}${key}: ${render(v, indent + 1)},`;
+    }
+    return `${padInner}${key}: ${literal(v)},`;
+  });
+  return `{\n${lines.join('\n')}\n${pad}}`;
+}
+
+module.exports = function emitTs({ nested, marker }) {
+  const body = render(nested, 0);
+  return `${marker}\nexport const tokens = ${body} as const;\n\nexport type Tokens = typeof tokens;\n`;
+};

package/src/utils/tokens-generator.js

@@ -0,0 +1,165 @@
+// Tokens generator — thin orchestrator over the DTCG SSOT (since v4.65.0).
+//
+// DTCG (`.tokens.json`, W3C Design Tokens Community Group: `$type`/`$value`,
+// `{ref}` aliases) is the design-token source of truth. This class reads it,
+// resolves aliases, and fans out to the per-format emitters in
+// `token-emitters/` to write the stack-native artifacts (tokens.ts, CSS vars).
+// Zero npm dependency — DTCG parsing is plain JSON traversal. Mirrors the thin-
+// wrapper shape of `graphify-installer.js` (detect / isStale / build).
+//
+// Authoritative design: framework/docs/COMPONENT-MANIFEST-LAYER.md.
+
+const fs = require('fs');
+const path = require('path');
+const emitters = require('./token-emitters');
+
+class TokensGenerator {
+  constructor(cwd = process.cwd()) { this.cwd = cwd; }
+
+  /** True when the DTCG source file exists. */
+  detect(source) {
+    if (!source) return false;
+    try { return fs.statSync(path.join(this.cwd, source)).isFile(); }
+    catch (_) { return false; }
+  }
+
+  /** Read + JSON.parse the DTCG source. Throws a clear error on bad input. */
+  load(source) {
+    const abs = path.join(this.cwd, source);
+    let raw;
+    try { raw = fs.readFileSync(abs, 'utf8'); }
+    catch (e) { throw new Error(`cannot read design tokens at ${source}: ${e.message}`); }
+    try { return JSON.parse(raw); }
+    catch (e) { throw new Error(`${source} is not valid JSON: ${e.message}`); }
+  }
+
+  /**
+   * Flatten the DTCG tree to leaf tokens. A node is a token when it carries
+   * `$value`. `$type` is inherited from the nearest ancestor that declares it.
+   * Returns Map<dotId, { type, raw }> in source order.
+   */
+  flatten(tree) {
+    const out = new Map();
+    const walk = (node, prefix, inheritedType) => {
+      if (!node || typeof node !== 'object') return;
+      const type = Object.prototype.hasOwnProperty.call(node, '$type') ? node.$type : inheritedType;
+      if (Object.prototype.hasOwnProperty.call(node, '$value')) {
+        out.set(prefix, { type, raw: node.$value });
+        return;
+      }
+      for (const key of Object.keys(node)) {
+        if (key.startsWith('$')) continue; // $type / $description / $extensions
+        walk(node[key], prefix ? `${prefix}.${key}` : key, type);
+      }
+    };
+    walk(tree, '', undefined);
+    return out;
+  }
+
+  /**
+   * Resolve `{a.b.c}` aliases to concrete values (chains + cycle guard).
+   * Returns Map<dotId, { type, value }> in the same order as `flat`.
+   */
+  resolve(flat) {
+    const resolved = new Map();
+    const resolveOne = (id, seen) => {
+      if (resolved.has(id)) return resolved.get(id);
+      const tok = flat.get(id);
+      if (!tok) throw new Error(`token reference {${id}} does not resolve to a known token`);
+      let value = tok.raw;
+      if (typeof value === 'string') {
+        const m = value.match(/^\{([^}]+)\}$/);
+        if (m) {
+          const ref = m[1];
+          if (seen.has(ref)) throw new Error(`cyclic token reference: ${[...seen, ref].join(' → ')}`);
+          const target = resolveOne(ref, new Set([...seen, id]));
+          value = target.value;
+        }
+      }
+      const entry = { type: tok.type, value };
+      resolved.set(id, entry);
+      return entry;
+    };
+    for (const id of flat.keys()) resolveOne(id, new Set());
+    return resolved;
+  }
+
+  /** Build the nested object of resolved VALUES (DTCG tree minus $wrappers). */
+  nest(resolved) {
+    const root = {};
+    for (const [id, tok] of resolved) {
+      const parts = id.split('.');
+      let cur = root;
+      for (let i = 0; i < parts.length - 1; i++) {
+        cur[parts[i]] = cur[parts[i]] || {};
+        cur = cur[parts[i]];
+      }
+      cur[parts[parts.length - 1]] = tok.value;
+    }
+    return root;
+  }
+
+  /**
+   * Produce { outputs: [{ format, path, content }], resolved } WITHOUT writing.
+   * Used by both build() and isStale().
+   */
+  render({ source, outputs }) {
+    const tree = this.load(source);
+    const flat = this.flatten(tree);
+    if (flat.size === 0) throw new Error(`${source} contains no DTCG tokens ($value leaves)`);
+    const resolved = this.resolve(flat);
+    const nested = this.nest(resolved);
+    const rendered = [];
+    for (const o of outputs || []) {
+      const r = emitters.emit(o.format, { resolved, nested });
+      if (!r.ok) throw new Error(r.error);
+      rendered.push({ format: o.format, path: o.path, content: r.content });
+    }
+    return { outputs: rendered, resolved };
+  }
+
+  /**
+   * Build: render + write every output. Returns { ok, written:[paths] } or
+   * { ok:false, error }.
+   */
+  build({ source, outputs }) {
+    let r;
+    try { r = this.render({ source, outputs }); }
+    catch (e) { return { ok: false, error: e.message }; }
+    const written = [];
+    for (const o of r.outputs) {
+      const abs = path.join(this.cwd, o.path);
+      try {
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, o.content, 'utf8');
+        written.push(o.path);
+      } catch (e) {
+        return { ok: false, error: `failed writing ${o.path}: ${e.message}`, written };
+      }
+    }
+    return { ok: true, written, tokenCount: r.resolved.size };
+  }
+
+  /**
+   * isStale: true when any output on disk differs from a fresh render (i.e. a
+   * hand-edit to a generated file, or the source changed without a rebuild).
+   * Returns { stale, reasons:[{path, reason}] } or { stale:false } / error.
+   */
+  isStale({ source, outputs }) {
+    if (!this.detect(source)) return { stale: false, sourceMissing: true };
+    let r;
+    try { r = this.render({ source, outputs }); }
+    catch (e) { return { stale: true, error: e.message, reasons: [] }; }
+    const reasons = [];
+    for (const o of r.outputs) {
+      const abs = path.join(this.cwd, o.path);
+      let onDisk;
+      try { onDisk = fs.readFileSync(abs, 'utf8'); }
+      catch (_) { reasons.push({ path: o.path, reason: 'missing' }); continue; }
+      if (onDisk !== o.content) reasons.push({ path: o.path, reason: 'out-of-date' });
+    }
+    return { stale: reasons.length > 0, reasons };
+  }
+}
+
+module.exports = TokensGenerator;