@sabaiway/agent-workflow-kit 1.17.0 → 1.19.0

package/tools/surface.mjs

@@ -0,0 +1,75 @@
+// surface.mjs — capability detection for the kit's OWN stdout (the direct CLI). Plan §4.5.
+//
+// Resolves how `node tools/family-registry.mjs` should render: the requested format, the effective
+// render mode (json | plain | ansi), whether to emit color, the terminal width, and whether to fall
+// back to ASCII glyphs. This governs ONLY the kit's direct-CLI output — the agent-mediated
+// `/agent-workflow-kit status` surface always consumes `--json` and localizes itself.
+//
+// Pure + fully injectable (argv / env / isTTY / columns / platform are inputs), no side effects on
+// import, Node >= 18. Tested in isolation against the §4.5 table.
+
+export const FORMATS = Object.freeze(['auto', 'plain', 'ansi', 'json']);
+export const FORMAT_ENV = 'AGENT_WORKFLOW_FORMAT';
+export const MIN_WIDTH = 40; // below this, force plain ASCII (a box can't lay out under ~40 cols)
+export const DEFAULT_WIDTH = 80;
+const FORMAT_FLAG = '--format=';
+
+// Resolve the requested format. A FLAG (--json or --format=X) beats the AGENT_WORKFLOW_FORMAT env;
+// among flags the LAST on argv wins (deterministic, standard last-wins). `--json` is exact sugar for
+// `--format=json`. A bare `--format` (no value), an empty value, or an unknown value → a LOUD reject
+// (never a silent fallback — Hard Constraint). Absent everywhere → 'auto'.
+export const resolveFormat = (argv = [], env = {}) => {
+  let fromFlag = null;
+  for (const a of argv) {
+    if (a === '--json') fromFlag = 'json';
+    else if (a === '--format') throw new Error(`[agent-workflow-kit] --format needs a value: --format=<${FORMATS.join('|')}>`);
+    else if (a.startsWith(FORMAT_FLAG)) fromFlag = a.slice(FORMAT_FLAG.length);
+  }
+  const requested = fromFlag ?? env[FORMAT_ENV] ?? 'auto';
+  if (!FORMATS.includes(requested)) {
+    throw new Error(`[agent-workflow-kit] invalid format "${requested}" — expected one of ${FORMATS.join(', ')}`);
+  }
+  return requested;
+};
+
+// Terminal width: stdout.columns (>0) wins, else $COLUMNS (>0), else the 80-col default. A garbage /
+// zero / undefined value falls through to the next source — never NaN.
+export const resolveWidth = ({ columns, env = {} } = {}) => {
+  const fromStdout = Number(columns);
+  if (Number.isFinite(fromStdout) && fromStdout > 0) return fromStdout;
+  const fromEnv = Number(env.COLUMNS);
+  if (Number.isFinite(fromEnv) && fromEnv > 0) return fromEnv;
+  return DEFAULT_WIDTH;
+};
+
+// Color is ORTHOGONAL to the render mode (the ansi renderer applies it; plain ignores it). Precedence:
+// CLICOLOR_FORCE / FORCE_COLOR present → on (unless explicitly '0'/'false'); else NO_COLOR present
+// (incl. empty value) → off; else follow isTTY. FORCE beats NO_COLOR.
+export const resolveColor = ({ env = {}, isTTY = false } = {}) => {
+  if ('CLICOLOR_FORCE' in env || 'FORCE_COLOR' in env) {
+    const v = 'CLICOLOR_FORCE' in env ? env.CLICOLOR_FORCE : env.FORCE_COLOR;
+    return !(v === '0' || String(v).toLowerCase() === 'false');
+  }
+  if ('NO_COLOR' in env) return false; // any value, incl. empty, disables (the NO_COLOR spec)
+  return Boolean(isTTY);
+};
+
+const isUtf8Env = (env = {}) => /utf-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || '');
+
+// The full resolved surface. mode: 'json' (machine envelope) | 'plain' | 'ansi'. For a non-json
+// format: an explicit plain/ansi is honored; 'auto' detects a tier (plain when NOT a TTY, or TERM=dumb,
+// or any CI env; else ansi). A width below MIN_WIDTH FORCES plain. ascii glyphs when narrow, or on a
+// Windows TTY without a UTF-8 locale (shallow — deeper Windows/UTF-8 depth is deferred, Plan §9).
+export const detectSurface = ({ argv = [], env = {}, isTTY = false, columns, platform = 'linux' } = {}) => {
+  const format = resolveFormat(argv, env);
+  const width = resolveWidth({ columns, env });
+  if (format === 'json') return { format, mode: 'json', width, color: false, ascii: false };
+
+  const autoTier = !isTTY || env.TERM === 'dumb' || 'CI' in env ? 'plain' : 'ansi';
+  const requestedMode = format === 'auto' ? autoTier : format; // 'plain' | 'ansi'
+  const narrow = width < MIN_WIDTH;
+  const mode = narrow ? 'plain' : requestedMode; // the width floor wins over an ansi request
+  const ascii = narrow || (platform === 'win32' && !isUtf8Env(env));
+  const color = resolveColor({ env, isTTY }); // orthogonal — the ansi renderer gates on mode + color
+  return { format, mode, width, color, ascii };
+};

package/tools/view-model.mjs

@@ -0,0 +1,89 @@
+// view-model.mjs — transform the no-leak `--json` envelope (buildEnvelope output) into a render-ready
+// ViewModel for the direct-CLI renderers. Plan §4.2 / §4.5: surface → VIEW-MODEL → renderers.
+//
+// One data source: the renderers never touch the raw surveys, only this VM, which is built from the
+// ENVELOPE — so the renderers inherit the envelope's no-leak guarantee (internal manifestState / stamp
+// filenames never reach them). This module resolves public tokens → English phrases (presentation.mjs)
+// and computes the headline counts; the renderers do layout + glyphs only.
+//
+// Pure, no side effects, Node >= 18.
+
+import { STATE_PHRASING, VISIBILITY_PHRASING } from './presentation.mjs';
+
+const memberVm = (m) => {
+  const refresh = m.refresh ?? { behind: false, recommend: null };
+  return {
+    display: m.display,
+    version: m.version ?? null,
+    state: m.state,
+    // 'installed' → null (the renderer shows the version instead); every other public token → a phrase.
+    statePhrase: m.state in STATE_PHRASING ? STATE_PHRASING[m.state] : m.state,
+    notes: m.notes ?? [], // the verbatim caveats — printed as ↳ sub-lines (INV-3: no dedupe)
+    behind: Boolean(refresh.behind), // used ONLY for the headline count on the direct CLI (INV-3)
+    recommend: refresh.recommend ?? null,
+  };
+};
+
+const bridgeVm = (b) => ({
+  display: b.display,
+  readiness: b.readiness,
+  // preserve the three-state wrapper status (present | missing | unknown) — the renderer maps to a glyph.
+  wrappers: (b.wrappers ?? []).map((w) => ({ cmd: w.cmd, state: w.state })),
+});
+
+const visibilityVm = (v) => {
+  if (!v) return null;
+  if (v.error) return { error: v.error };
+  return { phrase: v.state in VISIBILITY_PHRASING ? VISIBILITY_PHRASING[v.state] : v.state };
+};
+
+const recipesVm = (r) => {
+  if (!r) return null;
+  if (r.error) return { error: r.error };
+  const pairs = [];
+  for (const [activity, slots] of Object.entries(r.activities ?? {})) {
+    for (const [slot, v] of Object.entries(slots)) pairs.push({ key: `${activity}.${slot}`, recipe: v.recipe });
+  }
+  return { pairs, detectError: r.detectError ?? null };
+};
+
+const attributionVm = (a) => {
+  if (!a) return null;
+  if (a.error) return { error: a.error };
+  // A local OVERRIDE only when local actually set the key (non-null) AND it differs from project — a
+  // null local means the key is absent there, so the project value stands (that is not an override).
+  const override = a.local != null && a.local !== a.project;
+  return { effective: a.effective ?? null, override };
+};
+
+const velocityVm = (v) => {
+  if (!v) return null;
+  if (v.error) return { error: v.error };
+  return { defaultMode: v.defaultMode ?? null, allow: { project: v.allowEntries?.project ?? 0, local: v.allowEntries?.local ?? 0 } };
+};
+
+const settingsVm = (s) =>
+  s ? { recipes: recipesVm(s.recipes), attribution: attributionVm(s.attribution), velocity: velocityVm(s.velocity) } : null;
+
+const projectVm = (p) =>
+  p
+    ? {
+        dir: p.dir,
+        deployed: p.deployed,
+        docsAi: p.docsAi,
+        deployStamps: (p.deployStamps ?? []).map((st) => ({ display: st.display, version: st.version ?? null })),
+        visibility: visibilityVm(p.visibility),
+        settings: settingsVm(p.settings),
+      }
+    : null;
+
+export const toViewModel = (envelope = {}) => {
+  const members = (envelope.installed ?? []).map(memberVm);
+  return {
+    deploymentHead: envelope.deploymentHead ?? null,
+    members,
+    headline: { total: members.length, behind: members.filter((m) => m.behind).length },
+    bridges: envelope.bridges ? envelope.bridges.map(bridgeVm) : null,
+    project: projectVm(envelope.project),
+  };
+};