@hegemonart/get-design-done 1.53.0 → 1.55.0

package/sdk/cli/index.ts

@@ -22,6 +22,7 @@ import { queryCommand } from './commands/query.ts';
 import { auditCommand } from './commands/audit.ts';
 import { initCommand } from './commands/init.ts';
 import { buildCommand } from './commands/build.ts';
+import { dashboardCommand } from './commands/dashboard.ts';
 
 // ---------------------------------------------------------------------------
 // Top-level USAGE.
@@ -36,6 +37,7 @@ Commands:
   audit            Probe connections + dry-run verify.
   init             Bootstrap a new project.
   build skills     Compile per-harness skill bundles from source/skills/.
+  dashboard        Open the GDD dashboard (TUI; --web for the browser graph).
 
 Use 'gdd-sdk <command> -h' for command-specific flags.
 
@@ -60,6 +62,7 @@ export interface DispatcherDeps {
     readonly audit?: typeof auditCommand;
     readonly init?: typeof initCommand;
     readonly build?: typeof buildCommand;
+    readonly dashboard?: typeof dashboardCommand;
   };
 }
 
@@ -85,6 +88,7 @@ export async function dispatch(
     audit: deps.commands?.audit ?? auditCommand,
     init: deps.commands?.init ?? initCommand,
     build: deps.commands?.build ?? buildCommand,
+    dashboard: deps.commands?.dashboard ?? dashboardCommand,
   };
 
   // Bare invocation or top-level help → USAGE.
@@ -117,6 +121,8 @@ export async function dispatch(
       return await commands.init(parsed, { stdout, stderr });
     case 'build':
       return await commands.build(parsed, { stdout, stderr });
+    case 'dashboard':
+      return await commands.dashboard(parsed, { stdout, stderr });
     default:
       stderr.write(
         `gdd-sdk: unknown subcommand "${parsed.subcommand}"\n${USAGE}`,
@@ -132,6 +138,7 @@ const KNOWN_SUBCOMMANDS: ReadonlySet<string> = new Set([
   'audit',
   'init',
   'build',
+  'dashboard',
 ]);
 
 // ---------------------------------------------------------------------------

package/sdk/dashboard/data/_pkg-root.cjs

@@ -0,0 +1,92 @@
+'use strict';
+/**
+ * sdk/dashboard/data/_pkg-root.cjs — Phase 55 (GDD Dashboard, dep-free).
+ *
+ * Package-root walk-up for sibling resolution (the Phase 53/54 lesson): never
+ * resolve a cross-tree sibling via a fixed `__dirname`-relative `../../..`
+ * jump, because that breaks the moment a file is copied/moved or the layout
+ * shifts. Instead, walk UP from this file's directory until we find the GDD
+ * package.json (identified by `name === 'get-design-done'`), and resolve all
+ * in-repo siblings relative to that root.
+ *
+ * Even though these dashboard `.cjs` files are NOT esbuild-bundled (R8 — the
+ * bin trampoline runs them directly so the Phase 53 __dirname-rewrite trap
+ * does not apply), keeping the walk-up makes the data plane robust to future
+ * bundling or relocation. Pure + dependency-free; memoized per process.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** Memoized resolved package root (computed once per process). */
+let _cachedRoot = null;
+
+/**
+ * Walk up from `startDir` looking for the GDD package root. The GDD root is
+ * the first ancestor whose package.json declares `name: "get-design-done"`;
+ * if no such marker is found (e.g. running from an unusual layout), fall back
+ * to the FIRST ancestor that has any package.json, then to `startDir`.
+ *
+ * @param {string} startDir
+ * @returns {string} absolute package-root directory
+ */
+function findPackageRoot(startDir) {
+  let dir = path.resolve(startDir);
+  let firstWithPkg = null;
+  // Bound the climb defensively (deep trees / odd mounts).
+  for (let i = 0; i < 12; i++) {
+    const pkgPath = path.join(dir, 'package.json');
+    let pkg = null;
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    } catch {
+      pkg = null;
+    }
+    if (pkg) {
+      if (firstWithPkg === null) firstWithPkg = dir;
+      if (pkg.name === 'get-design-done') return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return firstWithPkg || path.resolve(startDir);
+}
+
+/**
+ * Resolved GDD package root, memoized. Computed by walking up from THIS file's
+ * directory (`__dirname`) — which is correct regardless of the caller's cwd.
+ * @returns {string}
+ */
+function packageRoot() {
+  if (_cachedRoot === null) _cachedRoot = findPackageRoot(__dirname);
+  return _cachedRoot;
+}
+
+/**
+ * Absolute path to an in-repo file given its repo-relative path.
+ * @param {string} relPath e.g. 'scripts/lib/install/runtime-homes.cjs'
+ * @returns {string}
+ */
+function resolveFromPackageRoot(relPath) {
+  return path.join(packageRoot(), relPath);
+}
+
+/**
+ * require() an in-repo sibling .cjs module by its repo-relative path, resolved
+ * via the package-root walk-up. Use ONLY for .cjs siblings — .ts libs must be
+ * loaded via dynamic import(pathToFileURL) (a .cjs cannot static-require a .ts).
+ *
+ * @param {string} relPath e.g. 'scripts/lib/design-context-query.cjs'
+ * @returns {*} the required module
+ */
+function requireFromPackageRoot(relPath) {
+  return require(resolveFromPackageRoot(relPath));
+}
+
+module.exports = {
+  findPackageRoot,
+  packageRoot,
+  resolveFromPackageRoot,
+  requireFromPackageRoot,
+};

package/sdk/dashboard/data/cost-aggregator.cjs

@@ -0,0 +1,187 @@
+'use strict';
+/**
+ * sdk/dashboard/data/cost-aggregator.cjs — Phase 55 (GDD Dashboard, dep-free).
+ *
+ * Pure roll-up of cost events into per-runtime / cumulative / per-cycle
+ * buckets, plus a tolerant JSONL reader for `.design/telemetry/costs.jsonl`.
+ *
+ * Cost rows on disk have evolved across phases (Phase 10.1 -> 26 -> 27 -> 33.6),
+ * so this aggregator is deliberately field-shape tolerant:
+ *
+ *   - cost field:    `est_cost_usd` (the on-disk tier-resolver/budget-enforcer
+ *                    shape) OR `cost_usd` (the newer event-payload shape).
+ *   - runtime key:   `runtime` (Phase 27+) -> else `tier` -> else `agent`
+ *                    -> else "unknown". Grouping is best-effort: the dashboard
+ *                    just needs a stable label per row.
+ *   - cycle key:     `cycle` -> else "unknown".
+ *   - tokens:        `tokens_in` / `tokens_out`, coerced via Number(... || 0).
+ *
+ * NEVER throws. Pure (no FS) except `readCosts()`, which reads one file and
+ * tolerates malformed lines (skips them silently, like the event-stream reader).
+ *
+ * Public API:
+ *   aggregateCosts(costEvents) -> { byRuntime, cumulative, byCycle }
+ *   readCosts({ root?, path? }) -> cost row array (tolerant; [] when absent)
+ *
+ * Determinism: no Date.now()/Math.random(); output ordering follows input
+ * ordering of first-seen keys (object insertion order).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_COSTS_PATH = '.design/telemetry/costs.jsonl';
+
+/**
+ * Coerce a possibly-missing numeric field to a finite number (0 on garbage).
+ * @param {unknown} v
+ * @returns {number}
+ */
+function num(v) {
+  const n = Number(v);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/**
+ * Read the per-runtime label for a cost row. Prefers the explicit `runtime`
+ * tag (Phase 27+), then `tier`, then `agent`, then a literal "unknown".
+ * @param {Record<string, unknown>} row
+ * @returns {string}
+ */
+function runtimeKeyOf(row) {
+  if (row && typeof row.runtime === 'string' && row.runtime.length) return row.runtime;
+  if (row && typeof row.tier === 'string' && row.tier.length) return row.tier;
+  if (row && typeof row.agent === 'string' && row.agent.length) return row.agent;
+  return 'unknown';
+}
+
+/**
+ * Read the USD cost for a row, tolerant of both on-disk shapes.
+ * @param {Record<string, unknown>} row
+ * @returns {number}
+ */
+function costUsdOf(row) {
+  if (!row) return 0;
+  if (typeof row.est_cost_usd !== 'undefined') return num(row.est_cost_usd);
+  if (typeof row.cost_usd !== 'undefined') return num(row.cost_usd);
+  if (typeof row.usd !== 'undefined') return num(row.usd);
+  return 0;
+}
+
+/**
+ * Read the cycle label for a row.
+ * @param {Record<string, unknown>} row
+ * @returns {string}
+ */
+function cycleKeyOf(row) {
+  if (row && typeof row.cycle === 'string' && row.cycle.length) return row.cycle;
+  if (row && typeof row.cycle === 'number') return String(row.cycle);
+  return 'unknown';
+}
+
+/** Fresh zeroed accumulator bucket. */
+function emptyBucket() {
+  return { tokens_in: 0, tokens_out: 0, est_cost_usd: 0 };
+}
+
+/**
+ * Add one row's measures into an accumulator bucket (mutates `bucket`).
+ * @param {{tokens_in:number,tokens_out:number,est_cost_usd:number}} bucket
+ * @param {Record<string, unknown>} row
+ */
+function addInto(bucket, row) {
+  bucket.tokens_in += num(row.tokens_in);
+  bucket.tokens_out += num(row.tokens_out);
+  bucket.est_cost_usd += costUsdOf(row);
+}
+
+/**
+ * Aggregate an array (or any iterable) of cost rows into per-runtime,
+ * cumulative, and per-cycle roll-ups. Pure — never throws, never reads FS.
+ *
+ * Non-array / nullish input degrades to empty buckets.
+ *
+ * @param {Iterable<Record<string, unknown>> | null | undefined} costEvents
+ * @returns {{
+ *   byRuntime: Record<string, {tokens_in:number,tokens_out:number,est_cost_usd:number}>,
+ *   cumulative: {tokens_in:number,tokens_out:number,est_cost_usd:number},
+ *   byCycle: Record<string, {tokens_in:number,tokens_out:number,est_cost_usd:number}>,
+ * }}
+ */
+function aggregateCosts(costEvents) {
+  /** @type {Record<string, ReturnType<typeof emptyBucket>>} */
+  const byRuntime = {};
+  /** @type {Record<string, ReturnType<typeof emptyBucket>>} */
+  const byCycle = {};
+  const cumulative = emptyBucket();
+
+  if (!costEvents || typeof costEvents[Symbol.iterator] !== 'function') {
+    return { byRuntime, cumulative, byCycle };
+  }
+
+  for (const row of costEvents) {
+    if (!row || typeof row !== 'object') continue;
+    const rt = runtimeKeyOf(row);
+    const cy = cycleKeyOf(row);
+    if (!byRuntime[rt]) byRuntime[rt] = emptyBucket();
+    if (!byCycle[cy]) byCycle[cy] = emptyBucket();
+    addInto(byRuntime[rt], row);
+    addInto(byCycle[cy], row);
+    addInto(cumulative, row);
+  }
+
+  return { byRuntime, cumulative, byCycle };
+}
+
+/**
+ * Resolve the costs.jsonl path: explicit `path` wins (absolute or relative to
+ * cwd); else `<root>/.design/telemetry/costs.jsonl`; else cwd-relative default.
+ * @param {{root?: string, path?: string}} [opts]
+ * @returns {string}
+ */
+function costsPathFor(opts = {}) {
+  if (opts.path) {
+    return path.isAbsolute(opts.path) ? opts.path : path.resolve(process.cwd(), opts.path);
+  }
+  const root = opts.root || process.cwd();
+  return path.join(root, DEFAULT_COSTS_PATH);
+}
+
+/**
+ * Read + parse `.design/telemetry/costs.jsonl` into a cost-row array.
+ *
+ * Tolerant: a missing file returns []; malformed JSON lines are skipped
+ * silently (the writer guarantees well-formed output, so a bad line is a
+ * corruption signal that must not crash a read-only dashboard). NEVER throws.
+ *
+ * @param {{root?: string, path?: string}} [opts]
+ * @returns {Array<Record<string, unknown>>}
+ */
+function readCosts(opts = {}) {
+  const file = costsPathFor(opts);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return []; // absent / unreadable -> graceful empty
+  }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed && typeof parsed === 'object') out.push(parsed);
+    } catch {
+      // tolerate a malformed line — skip it, keep reading
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  aggregateCosts,
+  readCosts,
+  costsPathFor,
+  DEFAULT_COSTS_PATH,
+};

package/sdk/dashboard/data/discovery.cjs

@@ -0,0 +1,297 @@
+'use strict';
+/**
+ * sdk/dashboard/data/discovery.cjs — Phase 55 (GDD Dashboard, dep-free).
+ *
+ * Best-effort, graceful-absent discovery of the three "where is GDD running"
+ * surfaces the dashboard renders:
+ *
+ *   - discoverRuntimes()            -> the 14 installable runtimes + whether
+ *                                      each one's global config dir is present
+ *                                      on this machine (Phase 24/28.7 set).
+ *   - discoverWorktrees({root?})    -> linked git worktrees via
+ *                                      `git worktree list --porcelain`.
+ *   - discoverSessions({root?})     -> session manifests under
+ *                                      `<root>/.design/sessions/*.json`
+ *                                      (Phase 55 R4: not yet persisted by the
+ *                                      pipeline -> degrades to []).
+ *   - recordSession({id, harness})  -> OPTIONAL additive writer that atomically
+ *                                      drops `<root>/.design/sessions/<id>.json`
+ *                                      so cross-harness visibility can grow over
+ *                                      time (tmp + rename, same-dir, Windows-safe).
+ *
+ * Everything is graceful-absent and NEVER throws: no git -> [] worktrees; no
+ * sessions dir -> [] sessions; an unknown runtime in the catalog is skipped
+ * rather than thrown. Sibling resolution (runtime-homes) is required via a
+ * package-root walk-up so this file survives being copied around the tree
+ * (the Phase 53/54 __dirname lesson).
+ *
+ * Determinism: the runtime catalog order is fixed; worktree order follows git's
+ * porcelain output order; session order follows readdir then a stable id sort.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { requireFromPackageRoot } = require('./_pkg-root.cjs');
+
+// runtime-homes is a sibling .cjs lib; resolve it via package-root walk-up so a
+// fixed __dirname-relative jump never breaks if this file moves (Phase 53/54).
+const runtimeHomes = requireFromPackageRoot('scripts/lib/install/runtime-homes.cjs');
+
+/**
+ * The 14 GDD runtimes locked by Phase 24 D-02 (and resolved by
+ * runtime-homes.cjs). `cline` is rules-based and has no skills dir
+ * (getGlobalSkillsBase('cline') === null) — surfaced as skillsBase: null.
+ */
+const RUNTIMES = Object.freeze([
+  'claude',
+  'opencode',
+  'gemini',
+  'kilo',
+  'codex',
+  'copilot',
+  'cursor',
+  'windsurf',
+  'antigravity',
+  'augment',
+  'trae',
+  'qwen',
+  'codebuddy',
+  'cline',
+]);
+
+/** True iff `p` exists and is a directory. Never throws. */
+function dirExists(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Discover the installable runtimes and whether each is present locally.
+ *
+ * "present" = the runtime's global config dir exists on disk. We do NOT read
+ * any file inside it (pure presence probe), and a resolver RangeError on an
+ * unexpected id is swallowed (the entry is still emitted with present:false).
+ *
+ * @returns {Array<{runtime:string, configDir:string|null, skillsBase:string|null, present:boolean}>}
+ */
+function discoverRuntimes() {
+  const out = [];
+  for (const runtime of RUNTIMES) {
+    let configDir = null;
+    let skillsBase = null;
+    let present = false;
+    try {
+      configDir = runtimeHomes.getGlobalConfigDir(runtime);
+    } catch {
+      configDir = null;
+    }
+    try {
+      skillsBase = runtimeHomes.getGlobalSkillsBase(runtime); // null for cline
+    } catch {
+      skillsBase = null;
+    }
+    if (configDir) present = dirExists(configDir);
+    out.push({ runtime, configDir, skillsBase, present });
+  }
+  return out;
+}
+
+/**
+ * Default git runner: synchronous `git <args>` in `cwd`, trimmed stdout or null
+ * on ANY failure (git missing, non-zero, not a repo). Matches the
+ * worktree-resolve.cjs injectable-exec contract: `(cmd, args) => string`.
+ *
+ * @param {string} cmd  literal 'git'
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {string|null}
+ */
+function defaultGitExec(cmd, args, cwd) {
+  try {
+    const res = spawnSync(cmd, args, { cwd, encoding: 'utf8', windowsHide: true });
+    if (!res || res.status !== 0 || typeof res.stdout !== 'string') return null;
+    return res.stdout;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse `git worktree list --porcelain` output into structured records.
+ *
+ * Porcelain format is blank-line-separated stanzas; each stanza has lines like:
+ *   worktree /abs/path
+ *   HEAD <sha>
+ *   branch refs/heads/<name>      (or `detached` / `bare`)
+ *   locked [reason]               (optional)
+ *
+ * Tolerant: unknown keys are ignored; a stanza without a `worktree` line is
+ * dropped. Pure string parsing — never throws.
+ *
+ * @param {string} porcelain
+ * @returns {Array<{path:string, head:string|null, branch:string|null, detached:boolean, bare:boolean, locked:boolean}>}
+ */
+function parseWorktreePorcelain(porcelain) {
+  const out = [];
+  if (typeof porcelain !== 'string' || porcelain.trim() === '') return out;
+  // Stanzas separated by one or more blank lines.
+  const stanzas = porcelain.replace(/\r\n/g, '\n').split(/\n\s*\n/);
+  for (const stanza of stanzas) {
+    const rec = { path: null, head: null, branch: null, detached: false, bare: false, locked: false };
+    for (const lineRaw of stanza.split('\n')) {
+      const line = lineRaw.trim();
+      if (line === '') continue;
+      if (line.startsWith('worktree ')) rec.path = line.slice('worktree '.length).trim();
+      else if (line.startsWith('HEAD ')) rec.head = line.slice('HEAD '.length).trim();
+      else if (line.startsWith('branch ')) {
+        const ref = line.slice('branch '.length).trim();
+        rec.branch = ref.replace(/^refs\/heads\//, '');
+      } else if (line === 'detached') rec.detached = true;
+      else if (line === 'bare') rec.bare = true;
+      else if (line === 'locked' || line.startsWith('locked ')) rec.locked = true;
+    }
+    if (rec.path) out.push(rec);
+  }
+  return out;
+}
+
+/**
+ * Discover linked git worktrees for the repo containing `root`.
+ *
+ * `exec` is injectable (matching worktree-resolve.cjs): `(cmd, args) => string`.
+ * Returns [] when git is unavailable / `root` is not a repo. NEVER throws.
+ *
+ * @param {{root?: string, exec?: (cmd:string, args:string[]) => string}} [opts]
+ * @returns {Array<{path:string, head:string|null, branch:string|null, detached:boolean, bare:boolean, locked:boolean}>}
+ */
+function discoverWorktrees(opts = {}) {
+  const root = opts.root || process.cwd();
+  const run = typeof opts.exec === 'function'
+    ? (args) => {
+        try {
+          const o = opts.exec('git', args);
+          return typeof o === 'string' ? o : null;
+        } catch {
+          return null;
+        }
+      }
+    : (args) => defaultGitExec('git', args, root);
+
+  const porcelain = run(['worktree', 'list', '--porcelain']);
+  if (porcelain == null) return [];
+  return parseWorktreePorcelain(porcelain);
+}
+
+/**
+ * Resolve the sessions directory: `<root>/.design/sessions`.
+ * @param {{root?: string}} [opts]
+ * @returns {string}
+ */
+function sessionsDirFor(opts = {}) {
+  const root = opts.root || process.cwd();
+  return path.join(root, '.design', 'sessions');
+}
+
+/**
+ * Discover persisted session manifests under `<root>/.design/sessions/*.json`.
+ *
+ * Phase 55 R4: the pipeline does not yet persist session manifests, so this
+ * degrades to [] in practice. When present, each `<id>.json` is read + parsed
+ * (malformed/unreadable files skipped). Results are sorted by id for
+ * determinism. NEVER throws.
+ *
+ * @param {{root?: string}} [opts]
+ * @returns {Array<Record<string, unknown>>}
+ */
+function discoverSessions(opts = {}) {
+  const dir = sessionsDirFor(opts);
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return []; // no sessions dir -> graceful empty
+  }
+  const out = [];
+  for (const ent of entries) {
+    if (!ent.isFile() || !ent.name.endsWith('.json')) continue;
+    try {
+      const body = fs.readFileSync(path.join(dir, ent.name), 'utf8');
+      const parsed = JSON.parse(body);
+      if (parsed && typeof parsed === 'object') out.push(parsed);
+    } catch {
+      // skip malformed/unreadable manifest
+    }
+  }
+  out.sort((a, b) => String(a && a.id).localeCompare(String(b && b.id)));
+  return out;
+}
+
+/**
+ * OPTIONAL additive writer (Phase 55 R4 / D5): atomically persist a session
+ * manifest at `<root>/.design/sessions/<id>.json` so future runs / other
+ * harnesses can discover it. Uses tmp + same-dir rename (Windows-safe atomic
+ * write idiom, mirrors scripts/lib/graph/atomic-write.mjs).
+ *
+ * Stamps `updated_at` (ISO) so the manifest carries freshness — this is the one
+ * intentional non-deterministic field (a write side-effect, not part of any
+ * deterministic render contract). `id` is required.
+ *
+ * Returns the written file path. NEVER throws on a sanitizable input; throws
+ * only on a missing/empty id (a programmer error the caller must fix).
+ *
+ * @param {{id: string, harness?: string, root?: string, [k:string]: unknown}} input
+ * @returns {string} absolute path of the written manifest
+ */
+function recordSession(input) {
+  if (!input || typeof input.id !== 'string' || input.id.length === 0) {
+    throw new TypeError('recordSession: id is required');
+  }
+  // Sanitize id into a safe filename (no path separators / traversal).
+  const safeId = input.id.replace(/[^A-Za-z0-9._-]/g, '_');
+  const dir = sessionsDirFor({ root: input.root });
+  const target = path.join(dir, `${safeId}.json`);
+
+  const manifest = { id: input.id };
+  if (typeof input.harness === 'string') manifest.harness = input.harness;
+  // Preserve opaque extras (anything except control keys).
+  for (const key of Object.keys(input)) {
+    if (key === 'root' || key === 'id' || key === 'harness') continue;
+    manifest[key] = input[key];
+  }
+  manifest.updated_at = new Date().toISOString();
+
+  const base = path.basename(target);
+  const tmp = path.join(
+    dir,
+    `.${base}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`,
+  );
+  fs.mkdirSync(dir, { recursive: true });
+  const body = JSON.stringify(manifest, null, 2) + '\n';
+  try {
+    fs.writeFileSync(tmp, body, 'utf8');
+    fs.renameSync(tmp, target);
+  } catch (err) {
+    try {
+      if (fs.existsSync(tmp)) fs.unlinkSync(tmp);
+    } catch {
+      /* best-effort cleanup; original error takes precedence */
+    }
+    throw err;
+  }
+  return target;
+}
+
+module.exports = {
+  discoverRuntimes,
+  discoverWorktrees,
+  discoverSessions,
+  recordSession,
+  parseWorktreePorcelain,
+  sessionsDirFor,
+  RUNTIMES,
+};