@hegemonart/get-design-done 1.46.0 → 1.47.0

package/scripts/lib/live/session-store.cjs

@@ -0,0 +1,364 @@
+'use strict';
+/**
+ * scripts/lib/live/session-store.cjs — Phase 47 (Live Mode) session persistence.
+ *
+ * The substrate behind `/gdd:live`: the user picks a DOM element on a dev
+ * server, the agent generates N design variants, the user accepts/discards, and
+ * the session survives a crash / `--resume`. This module owns the per-session
+ * record on disk at:
+ *
+ *   <projectRoot>/.design/live-sessions/<session-id>.json
+ *
+ * Each record is a single JSON document conforming to
+ * reference/schemas/live-session.schema.json — `{schema_version, session_id,
+ * started_at, ended_at|null, status, url?, dev_server?, events:[...]}` — where
+ * `events` is an append-only log of `{kind:'pick'|'generate'|'accept'|'discard',
+ * at, ...}` entries.
+ *
+ * Design constraints (mirrors scripts/lib/pin/store.cjs + ds-arms store):
+ *   - Pure, dependency-free CommonJS. Only `fs` + `path`. No network.
+ *   - NO top-level Date.now()/Math.random()/new Date(). Time + id are injected
+ *     (`now` / `id` / `sessionId`) so every behaviour is deterministic and
+ *     hermetically testable. The clock is only ever read from caller input.
+ *   - Atomic writes: contents go to `<dest>.tmp` then fs.renameSync into place,
+ *     so an interrupted write never leaves a half-written session (and never a
+ *     stray `.tmp`).
+ *   - Every entry point takes an explicit `projectRoot`; all paths are built
+ *     with path.join so the module is cross-platform.
+ *
+ * Ships in the npm package (scripts/lib/ is in package.json `files`), so it must
+ * stay runtime-safe — no dev-only requires.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_VERSION = '47.0';
+
+/** Statuses an active session can hold. */
+const STATUS_IN_PROGRESS = 'in_progress';
+const STATUS_COMPLETED = 'completed';
+const STATUS_ABANDONED = 'abandoned';
+
+/** Event kinds recognised in the append-only log. */
+const EVENT_KINDS = Object.freeze(['pick', 'generate', 'accept', 'discard']);
+
+/** Directory (relative to projectRoot) that holds every session record. */
+const SESSIONS_SUBDIR = path.join('.design', 'live-sessions');
+
+/**
+ * Absolute path to the live-sessions directory for a project.
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+function sessionsDir(projectRoot) {
+  if (!projectRoot) throw new TypeError('session-store: projectRoot is required');
+  return path.join(projectRoot, SESSIONS_SUBDIR);
+}
+
+/**
+ * Absolute path to a single session record.
+ * @param {string} projectRoot
+ * @param {string} sessionId
+ * @returns {string}
+ */
+function sessionPath(projectRoot, sessionId) {
+  if (!sessionId) throw new TypeError('session-store: sessionId is required');
+  // Guard against path traversal in the id — a session id is a flat token, never
+  // a path. We reject any separator or `..` rather than silently joining it.
+  const id = String(sessionId);
+  if (id.includes('/') || id.includes('\\') || id === '.' || id === '..') {
+    throw new Error(`session-store: invalid sessionId "${id}" (must not contain path separators)`);
+  }
+  return path.join(sessionsDir(projectRoot), `${id}.json`);
+}
+
+/** Atomic write: write to `<dest>.tmp` then rename into place. */
+function atomicWriteJson(dest, value) {
+  const dir = path.dirname(dest);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${dest}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  try {
+    fs.renameSync(tmp, dest);
+  } catch (e) {
+    // Never leave a stray .tmp behind on a failed rename.
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw e;
+  }
+}
+
+/**
+ * Derive a stable session id WITHOUT touching a global clock or RNG. The id is
+ * built purely from caller-supplied inputs so it is deterministic in tests.
+ *
+ * Preference order:
+ *   1. explicit `id` (the injectable)
+ *   2. a slug of `now` (the injected timestamp) — e.g. "2026-06-03T01:02:03Z"
+ *      becomes "session-2026-06-03t01-02-03z"
+ *
+ * @param {{ id?: string, now?: string }} args
+ * @returns {string}
+ */
+function deriveSessionId(args = {}) {
+  if (args.id != null && String(args.id).length) return String(args.id);
+  if (args.now != null && String(args.now).length) {
+    const slug = String(args.now)
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '');
+    if (slug.length) return `session-${slug}`;
+  }
+  throw new TypeError(
+    'session-store.newSession: provide an explicit sessionId, or inject `id`/`now` to derive one ' +
+      '(no internal clock/RNG by design)',
+  );
+}
+
+/**
+ * Create a new session record on disk.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} [args.sessionId]      explicit id; if omitted, derived from `id`/`now`
+ * @param {string} [args.id]             injectable id source (used when sessionId omitted)
+ * @param {string} [args.now]            ISO timestamp for started_at + id derivation
+ * @param {string} [args.url]            the page the element was picked from
+ * @param {string|object} [args.devServer] dev-server descriptor (url/port/command)
+ * @returns {{ sessionId: string, path: string, session: object }}
+ */
+function newSession(args = {}) {
+  const { projectRoot } = args;
+  if (!projectRoot) throw new TypeError('newSession: projectRoot is required');
+
+  const sessionId = args.sessionId != null && String(args.sessionId).length
+    ? String(args.sessionId)
+    : deriveSessionId({ id: args.id, now: args.now });
+
+  const startedAt = args.now != null && String(args.now).length ? String(args.now) : null;
+  if (!startedAt) {
+    throw new TypeError(
+      'newSession: `now` (ISO timestamp) is required for started_at (no internal clock by design)',
+    );
+  }
+
+  const session = {
+    schema_version: SCHEMA_VERSION,
+    session_id: sessionId,
+    status: STATUS_IN_PROGRESS,
+    started_at: startedAt,
+    ended_at: null,
+    events: [],
+  };
+  if (args.url != null) session.url = String(args.url);
+  if (args.devServer != null) session.dev_server = args.devServer;
+
+  const dest = sessionPath(projectRoot, sessionId);
+  atomicWriteJson(dest, session);
+  return { sessionId, path: dest, session };
+}
+
+/**
+ * Load a session record, or null if it does not exist / is unparseable.
+ * @param {{ projectRoot: string, sessionId: string }} args
+ * @returns {object|null}
+ */
+function loadSession(args = {}) {
+  const { projectRoot, sessionId } = args;
+  if (!projectRoot) throw new TypeError('loadSession: projectRoot is required');
+  if (!sessionId) throw new TypeError('loadSession: sessionId is required');
+  const file = sessionPath(projectRoot, sessionId);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const data = JSON.parse(raw);
+    if (!Array.isArray(data.events)) data.events = [];
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Append an event to a session's `events` log and atomically rewrite the record.
+ *
+ * The event MUST carry a recognised `kind` and an `at` timestamp — the `at`
+ * comes from the caller (no internal clock). Any extra payload fields (e.g.
+ * a `generate` event's variant list, a `pick` event's selector + implicated
+ * files) are preserved verbatim.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.sessionId
+ * @param {object} args.event   { kind, at, ... }
+ * @returns {{ sessionId: string, path: string, session: object, eventIndex: number }}
+ */
+function appendEvent(args = {}) {
+  const { projectRoot, sessionId, event } = args;
+  if (!projectRoot) throw new TypeError('appendEvent: projectRoot is required');
+  if (!sessionId) throw new TypeError('appendEvent: sessionId is required');
+  if (!event || typeof event !== 'object') throw new TypeError('appendEvent: event object is required');
+  if (!EVENT_KINDS.includes(event.kind)) {
+    throw new Error(
+      `appendEvent: unknown event.kind "${event.kind}" (expected one of ${EVENT_KINDS.join(', ')})`,
+    );
+  }
+  if (event.at == null || !String(event.at).length) {
+    throw new TypeError('appendEvent: event.at (ISO timestamp) is required (no internal clock by design)');
+  }
+
+  const session = loadSession({ projectRoot, sessionId });
+  if (!session) {
+    throw new Error(`appendEvent: no session "${sessionId}" under ${sessionsDir(projectRoot)}`);
+  }
+  // Normalise the stored event so `kind`/`at` lead, then spread the rest.
+  const stored = { kind: event.kind, at: String(event.at) };
+  for (const [k, v] of Object.entries(event)) {
+    if (k === 'kind' || k === 'at') continue;
+    stored[k] = v;
+  }
+  session.events.push(stored);
+
+  const dest = sessionPath(projectRoot, sessionId);
+  atomicWriteJson(dest, session);
+  return { sessionId, path: dest, session, eventIndex: session.events.length - 1 };
+}
+
+/** The last event in a session, or null if none. */
+function lastEventOf(session) {
+  if (!session || !Array.isArray(session.events) || session.events.length === 0) return null;
+  return session.events[session.events.length - 1];
+}
+
+/**
+ * List every session for a project, newest activity first, for resume offers.
+ *
+ * Each entry: `{ sessionId, status, started_at, lastEvent }`. Unparseable /
+ * non-session files are skipped. Returns [] when the directory is absent.
+ *
+ * @param {string} projectRoot
+ * @returns {Array<{ sessionId: string, status: string, started_at: string|null, lastEvent: object|null }>}
+ */
+function listSessions(projectRoot) {
+  if (!projectRoot) throw new TypeError('listSessions: projectRoot is required');
+  const dir = sessionsDir(projectRoot);
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    if (!e.name.endsWith('.json')) continue;
+    if (e.name.endsWith('.tmp')) continue;
+    const sessionId = e.name.slice(0, -'.json'.length);
+    const session = loadSession({ projectRoot, sessionId });
+    if (!session || session.session_id == null) continue;
+    out.push({
+      sessionId: session.session_id,
+      status: session.status || null,
+      started_at: session.started_at || null,
+      lastEvent: lastEventOf(session),
+    });
+  }
+  // Stable order: most recently started first; ties broken by id for determinism.
+  out.sort((a, b) => {
+    const sa = a.started_at || '';
+    const sb = b.started_at || '';
+    if (sa === sb) return a.sessionId.localeCompare(b.sessionId);
+    return sa < sb ? 1 : -1;
+  });
+  return out;
+}
+
+/**
+ * Resume information for a single session, so the skill can offer
+ * "continue from <last_event>" vs "start fresh".
+ *
+ * @param {{ projectRoot: string, sessionId: string }} args
+ * @returns {{ canResume: boolean, lastEvent: object|null, summary: string }}
+ */
+function resumeInfo(args = {}) {
+  const { projectRoot, sessionId } = args;
+  if (!projectRoot) throw new TypeError('resumeInfo: projectRoot is required');
+  if (!sessionId) throw new TypeError('resumeInfo: sessionId is required');
+
+  const session = loadSession({ projectRoot, sessionId });
+  if (!session) {
+    return { canResume: false, lastEvent: null, summary: `no session "${sessionId}"` };
+  }
+  const last = lastEventOf(session);
+  const eventCount = Array.isArray(session.events) ? session.events.length : 0;
+  // Only in-progress sessions can be resumed; completed/abandoned ones are done.
+  const canResume = session.status === STATUS_IN_PROGRESS;
+
+  let summary;
+  if (!canResume) {
+    summary = `session "${sessionId}" is ${session.status} — start fresh`;
+  } else if (last) {
+    summary = `continue from "${last.kind}" (${eventCount} event${eventCount === 1 ? '' : 's'} recorded)`;
+  } else {
+    summary = `session "${sessionId}" started but has no events yet — continue or start fresh`;
+  }
+  return { canResume, lastEvent: last, summary };
+}
+
+/**
+ * Close a session: set `ended_at` and a terminal status.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.sessionId
+ * @param {('completed'|'abandoned')} args.status
+ * @param {string} args.now   ISO timestamp for ended_at (no internal clock)
+ * @returns {{ sessionId: string, path: string, session: object }}
+ */
+function endSession(args = {}) {
+  const { projectRoot, sessionId } = args;
+  if (!projectRoot) throw new TypeError('endSession: projectRoot is required');
+  if (!sessionId) throw new TypeError('endSession: sessionId is required');
+  const status = args.status || STATUS_COMPLETED;
+  if (status !== STATUS_COMPLETED && status !== STATUS_ABANDONED) {
+    throw new Error(`endSession: status must be "${STATUS_COMPLETED}" or "${STATUS_ABANDONED}", got "${status}"`);
+  }
+  if (args.now == null || !String(args.now).length) {
+    throw new TypeError('endSession: `now` (ISO timestamp) is required for ended_at (no internal clock by design)');
+  }
+
+  const session = loadSession({ projectRoot, sessionId });
+  if (!session) {
+    throw new Error(`endSession: no session "${sessionId}" under ${sessionsDir(projectRoot)}`);
+  }
+  session.status = status;
+  session.ended_at = String(args.now);
+
+  const dest = sessionPath(projectRoot, sessionId);
+  atomicWriteJson(dest, session);
+  return { sessionId, path: dest, session };
+}
+
+module.exports = {
+  newSession,
+  appendEvent,
+  loadSession,
+  listSessions,
+  resumeInfo,
+  endSession,
+  // exported for callers + tests
+  sessionsDir,
+  sessionPath,
+  deriveSessionId,
+  lastEventOf,
+  SCHEMA_VERSION,
+  SESSIONS_SUBDIR,
+  EVENT_KINDS,
+  STATUS_IN_PROGRESS,
+  STATUS_COMPLETED,
+  STATUS_ABANDONED,
+};

package/scripts/lib/manifest/skills.json

@@ -198,6 +198,14 @@
       "tools": "Read, Bash",
       "registered_in_phase": "46"
     },
+    {
+      "name": "live",
+      "description": "Live in-browser design mode. The user picks a DOM element on a running dev server (via the Claude Preview MCP), the agent generates N design variants in one batch, they hot-swap in place through HMR or preview_eval using a data-gdd-variant marker, the user accepts or discards, and the whole pick-generate-accept loop persists to .design/live-sessions so it survives a crash or resume. Use when the user wants to iterate on the look of a live component against a real running server, asks to try variants on a page, or runs the live command with a url; falls back to a screenshot-only degraded mode on harnesses without MCP support.",
+      "argument_hint": "[--variants N] [--resume <session-id>] [url]",
+      "tools": "Read, Write, Edit, Bash, Glob, Grep, Task",
+      "user_invocable": true,
+      "registered_in_phase": "47"
+    },
     {
       "name": "locale",
       "description": "Inspects or sets the GDD CLI locale for this project. With no argument, reports the resolved locale (config.locale > env LANG > en), the fallback chain, and per-locale coverage (which message tables are complete vs placeholder). With a <code> (en/ru/uk/de/fr/zh/ja), sets .design/config.json#locale after previewing the change. Localizes --help, common error messages, and skill prompt headers via scripts/lib/i18n/; missing keys fall back to English, so a partial locale never breaks the CLI. Use to switch GDD's own output language.",

package/skills/live/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: gdd-live
+description: "Live in-browser design mode. The user picks a DOM element on a running dev server (via the Claude Preview MCP), the agent generates N design variants in one batch, they hot-swap in place through HMR or preview_eval using a data-gdd-variant marker, the user accepts or discards, and the whole pick-generate-accept loop persists to .design/live-sessions so it survives a crash or resume. Use when the user wants to iterate on the look of a live component against a real running server, asks to try variants on a page, or runs the live command with a url; falls back to a screenshot-only degraded mode on harnesses without MCP support."
+argument-hint: "[--variants N] [--resume <session-id>] [url]"
+tools: Read, Write, Edit, Bash, Glob, Grep, Task
+user-invocable: true
+---
+
+# gdd-live - Live In-Browser Design Mode
+
+Pick a DOM element on a running dev server, generate competing design variants, hot-swap them in place, and accept the winner as a real source edit. Every step persists to `.design/live-sessions/<id>.json` so the session survives a crash or a later resume.
+
+The browser-side runtime, the harness-mode gate, the session store, the events feed, the post-check, the scope guard, and the bandit feed are all separate modules under `scripts/lib/live/`. This skill describes the loop and names the module that owns each step; it does not import them.
+
+For the full surface (the Preview MCP tools, the six `live_*` events, the session file, the bandit feed, degraded mode, the scope guard), see `../../reference/live-mode-integration.md`. For the SKILL.md structural contract, see `../../reference/skill-authoring-contract.md`.
+
+---
+
+## Arguments
+
+- `[url]` - the page to drive. Optional. When omitted, detect the dev server and use its root.
+- `--variants N` - how many variants to generate per pick. Default 3.
+- `--resume <session-id>` - reattach to an in-progress session in `.design/live-sessions/`.
+
+---
+
+## BOOT
+
+1. Probe the Preview MCP per `../../connections/preview.md`: `ToolSearch({ query: "Claude_Preview" })`, then `mcp__Claude_Preview__preview_list`. Empty ToolSearch means the MCP is not loaded.
+2. Resolve the harness live mode. The capability signal is `capability_matrix.mcp_support` in `scripts/lib/manifest/harnesses.json`, projected by `scripts/lib/live/harness-mode.cjs` (`liveModeFor(harnessId)`). A `puppeteer` result means full live mode; a `degraded` result means screenshot-only.
+3. If `mcp_support` is false for this harness, or Preview is unavailable, enter DEGRADED mode and say so plainly: variants are generated and captured as static screenshots, with no in-page hot-swap. Skip the INJECT and PICK steps; generate against the file the user names instead.
+4. Detect the dev server. Look for Vite, Next, Bun, or a static server (check `package.json` scripts plus a `preview_list` entry). Record the server descriptor on the session.
+5. Open or create the session via `scripts/lib/live/session-store.cjs` (`.design/live-sessions/<id>.json`). On `--resume`, load the named session (see RESUME).
+
+---
+
+## INJECT
+
+Inject the browser runtime once. Read `RUNTIME_JS` from `scripts/lib/live/runtime.cjs` and evaluate it in the page with `mcp__Claude_Preview__preview_eval`. The runtime is an idempotent IIFE bound to `window.__gddLive`, so a re-inject after navigation rebinds the same singleton rather than stacking listeners. It installs the pick handler and the variant-swap helpers, and stamps the live variant on the element via the `data-gdd-variant` attribute.
+
+---
+
+## PICK
+
+1. Arm the picker (`window.__gddLive.pick()`), then guide the user to click the target element. Use `preview_click` and `preview_inspect` to confirm the element and read its computed styles and bounding box.
+2. Read the pick report back. Its fields are documented in `pickReportShape` (selector, tagName, classList, boundingRect, computedStyle subset, current variant). The selector strategy prefers id, then a data-testid, then a tag plus class plus nth-of-type path.
+3. Emit a `live_pick` event through `scripts/lib/live/events.cjs` and append a `pick` entry to the session.
+
+---
+
+## GENERATE (one batch)
+
+1. Load the relevant Phase 45 canonical reference index FIRST, so variants are grounded in real guidance: the domain index that matches the picked element (for example `../../reference/spatial.md` for layout, `../../reference/interaction.md` for components and a11y, `../../reference/color.md` for color, `../../reference/typography.md` for type, `../../reference/motion.md` for animation).
+2. Generate all N variants in ONE batch (default 3), each a distinct, hypothesis-tagged design direction for the picked element. Do not generate them one at a time.
+3. For each variant: write the change atomically to the implicated source file, then make it live. With HMR running, the file write is enough; otherwise apply the variant in place with `window.__gddLive.swapVariant({ n, style, html })`, which sets `data-gdd-variant="n"` and applies the variant's style or markup.
+
+---
+
+## POST-CHECK
+
+Run the post-check on each variant via `scripts/lib/live/postcheck.cjs`, which invokes `gdd-detect`. Show the findings inline next to each variant. A variant that trips a finding is flagged, NOT auto-rejected: the user still decides. Append a `live_postcheck` event per variant.
+
+---
+
+## ACCEPT / DISCARD
+
+- ACCEPT one variant: apply the chosen variant as the canonical source edit, and revert the others in the page (`window.__gddLive.revert()` on each non-chosen element). Emit a `live_accept` event and feed the outcome to the design-variants bandit via `scripts/lib/live/bandit-feed.cjs` (a dev-time signal). Append an `accept` entry.
+- DISCARD: revert every variant in the page back to its captured original and leave the source untouched. Emit a `live_discard` event and append a `discard` entry.
+
+Either way, persist the result through `scripts/lib/live/session-store.cjs` before continuing.
+
+---
+
+## PERSIST
+
+Every step (boot, pick, generate, post-check, accept, discard) is written to the session file through `scripts/lib/live/session-store.cjs` as it happens. The on-disk event log uses the `pick`, `generate`, `accept`, `discard` kinds; the telemetry stream uses the six `live_*` event types. Writes are atomic, so an interrupted step never leaves a half-written session.
+
+---
+
+## RESUME
+
+With `--resume <session-id>`, load the named session from `.design/live-sessions/`. Only an `in_progress` session is resumable. Offer the user two choices: continue from the last recorded event (report what that was, for example "last pick was the primary button"), or start fresh (open a new session and leave the old one intact). Never silently replay completed events.
+
+---
+
+## SCOPE GUARD
+
+Never write outside the source files implicated by the picked element. Run every proposed write through `scripts/lib/live/scope-guard.cjs`, which maps the picked selector to its owning source files and rejects edits that fall outside them. If a variant would need a change beyond that scope (a shared token, a parent layout, a new dependency), stop and surface it to the user rather than widening the blast radius.
+
+## Constraints
+
+- Do NOT edit files outside the picked element's implicated sources (enforced by the scope guard).
+- Do NOT generate variants one at a time; generate the full batch, then swap.
+- Do NOT auto-reject a variant on a post-check finding; flag it and let the user decide.
+- In DEGRADED mode, state up front that hot-swap is unavailable and fall back to screenshots.
+- Persist before every user-facing prompt so a crash never loses accepted work.
+
+## LIVE COMPLETE