tux-review 0.1.0

package/src/feedback.js

@@ -0,0 +1,289 @@
+/**
+ * Feedback operations — the deterministic primitives behind
+ * `tux feedback <action>` (SPC sections 42–57).
+ *
+ * @module feedback
+ */
+import { CliError, EXIT } from './errors.js';
+import { canonicalJson, compactJson } from './canonical.js';
+import { nowMs, canonicalTimestamp, newId } from './ids.js';
+import { FEEDBACK_TYPES, FEEDBACK_STATUSES, makeFeedback, normalizedText, validateFeedback } from './schema.js';
+import {
+  loadStore, saveStore, storeExists, ensureSession,
+  countIncorporationBatches, saveIncorporationBatch,
+} from './store.js';
+import { resolveIdentity } from './config.js';
+
+/** Options shared by every action: {cwd, config, identity, format, time}. */
+function ctx(opts) {
+  return {
+    cwd: opts.cwd,
+    config: opts.config,
+    identity: opts.identity ?? resolveIdentity(opts.config),
+    format: opts.format ?? 'text',
+    now: opts.now ?? nowMs(),
+    timestamp: canonicalTimestamp(opts.now ?? nowMs()),
+  };
+}
+
+/**
+ * `tux feedback show [feedback-id]` (SPC section 42): with an ID, print
+ * the complete canonical item (always canonical JSON, filters ignored);
+ * without an ID, survey all items with composing filters.
+ */
+export function opShow(opts, id, filters = {}) {
+  const c = ctx(opts);
+  const store = loadStore(c.cwd, c.config);
+  if (id) {
+    const item = store.feedback.find((f) => f.id === id);
+    if (!item) throw new CliError(EXIT.notFound, `feedback not found: ${id}`);
+    return { stdout: canonicalJson(item) + '\n', exit: EXIT.ok };
+  }
+  let items = store.feedback;
+  if (filters.status) items = items.filter((f) => f.status === filters.status);
+  if (filters.type) items = items.filter((f) => f.feedback.type === filters.type);
+  if (filters.mine) items = items.filter((f) => f.author.user_id === c.identity.user_id);
+  if (filters.route) items = items.filter((f) => f.location?.route === filters.route);
+  if (filters.session) items = items.filter((f) => f.session_id === filters.session);
+  if (filters.origin) items = items.filter((f) => f.origin?.mode === filters.origin);
+  if (c.format === 'json') return { stdout: canonicalJson(items) + '\n', exit: EXIT.ok };
+  const lines = items.map((f) =>
+    [f.id, f.status, f.feedback.type, f.location?.route ?? '-', firstLine(f.feedback.text)].join('\t')
+  );
+  return { stdout: (lines.length ? lines.join('\n') + '\n' : ''), exit: EXIT.ok };
+}
+
+export function opCreate(opts, spec) {
+  const c = ctx(opts);
+  if (!FEEDBACK_TYPES.includes(spec.type)) {
+    throw new CliError(EXIT.usage, `invalid feedback type: ${spec.type} (expected ${FEEDBACK_TYPES.join(', ')})`);
+  }
+  if (!spec.text || spec.text.trim() === '') throw new CliError(EXIT.usage, '--text is required');
+  const store = loadStore(c.cwd, c.config);
+  const seq = store.feedback.length + 1;
+  const id = newId('fb', store.project_id, spec.session ?? 'default', seq, 'feedback', c.now);
+  const item = makeFeedback({
+    id,
+    project_id: store.project_id,
+    session_id: spec.session ?? 'default',
+    author: { user_id: c.identity.user_id, display_name: c.identity.display_name },
+    origin: spec.origin ?? 'design',
+    location: {
+      ...(spec.route ? { route: spec.route } : {}),
+      ...(spec.page ? { page: spec.page } : {}),
+      ...(spec.component ? { component: spec.component } : {}),
+      ...(spec.instance ? { component_instance: spec.instance } : {}),
+    },
+    target: {
+      ...(spec.tuxId ? { tux_id: spec.tuxId } : {}),
+      ...(spec.testId ? { test_id: spec.testId } : {}),
+    },
+    ui_state: spec.uiState ?? {},
+    type: spec.type,
+    text: spec.text,
+    created_at: c.timestamp,
+  });
+  const problems = validateFeedback(item);
+  if (problems.length) throw new CliError(EXIT.general, `created item invalid: ${problems.join('; ')}`);
+  store.feedback.push(item);
+  saveStore(c.cwd, c.config, store);
+  if (spec.session) ensureSession(c.cwd, c.config, spec.session, spec.environment ?? 'design', c.timestamp);
+  return { stdout: canonicalJson(item) + '\n', exit: EXIT.ok };
+}
+
+export function opUpdate(opts, id, patch) {
+  const c = ctx(opts);
+  const store = loadStore(c.cwd, c.config);
+  const item = store.feedback.find((f) => f.id === id);
+  if (!item) throw new CliError(EXIT.notFound, `feedback not found: ${id}`);
+  if (patch.status !== undefined && !FEEDBACK_STATUSES.includes(patch.status)) {
+    throw new CliError(EXIT.usage, `invalid status: ${patch.status} (expected ${FEEDBACK_STATUSES.join(', ')})`);
+  }
+  if (patch.type !== undefined && !FEEDBACK_TYPES.includes(patch.type)) {
+    throw new CliError(EXIT.usage, `invalid feedback type: ${patch.type} (expected ${FEEDBACK_TYPES.join(', ')})`);
+  }
+  if (patch.text !== undefined) item.feedback.text = patch.text;
+  if (patch.type !== undefined) item.feedback.type = patch.type;
+  if (patch.status !== undefined) item.status = patch.status;
+  if (patch.incorporation !== undefined) item.incorporation = patch.incorporation;
+  item.updated_at = c.timestamp;
+  saveStore(c.cwd, c.config, store);
+  return { stdout: canonicalJson(item) + '\n', exit: EXIT.ok };
+}
+
+export function opDelete(opts, id) {
+  const c = ctx(opts);
+  const store = loadStore(c.cwd, c.config);
+  const idx = store.feedback.findIndex((f) => f.id === id);
+  if (idx === -1) throw new CliError(EXIT.notFound, `feedback not found: ${id}`);
+  store.feedback.splice(idx, 1);
+  saveStore(c.cwd, c.config, store);
+  if (c.format === 'json') return { stdout: canonicalJson({ deleted: [id] }) + '\n', exit: EXIT.ok };
+  return { stdout: `deleted ${id}\n`, exit: EXIT.ok };
+}
+
+export function opClear(opts, scope, filters) {
+  const c = ctx(opts);
+  if (scope === 'all' && !filters.force) {
+    throw new CliError(EXIT.usage, '--all requires explicit confirmation (--force)');
+  }
+  if (!scope) throw new CliError(EXIT.usage, 'specify --mine or --all');
+  const store = loadStore(c.cwd, c.config);
+  const before = store.feedback.length;
+  store.feedback = store.feedback.filter((f) => {
+    if (scope === 'mine' && f.author.user_id !== c.identity.user_id) return true;
+    if (filters.route && f.location?.route !== filters.route) return true;
+    if (filters.session && f.session_id !== filters.session) return true;
+    return false;
+  });
+  const cleared = before - store.feedback.length;
+  saveStore(c.cwd, c.config, store);
+  if (c.format === 'json') return { stdout: canonicalJson({ cleared }) + '\n', exit: EXIT.ok };
+  return { stdout: `cleared ${cleared}\n`, exit: EXIT.ok };
+}
+
+export function opExport(opts, format) {
+  const c = ctx(opts);
+  const store = loadStore(c.cwd, c.config);
+  if (format === 'jsonl') {
+    const out = store.feedback.map((f) => compactJson(f)).join('\n');
+    return { stdout: (out ? out + '\n' : ''), exit: EXIT.ok };
+  }
+  return { stdout: canonicalJson(store.feedback) + '\n', exit: EXIT.ok };
+}
+
+export function storeIsEmpty(opts) {
+  return !storeExists(opts.cwd, opts.config);
+}
+
+/** Canonical target key for grouping (SPC section 50). */
+export function targetKey(item) {
+  return [
+    item.location?.route ?? '',
+    item.location?.page ?? '',
+    item.location?.component ?? '',
+    item.location?.component_instance ?? '',
+    item.target?.tux_id ?? '',
+    item.target?.test_id ?? '',
+  ].join('|');
+}
+
+export function opIncorporate(opts, strategy, filters) {
+  const c = ctx(opts);
+  const STRATEGIES = ['consolidate', 'requirements', 'tasks', 'direct', 'export-only'];
+  if (strategy === undefined) {
+    throw new CliError(EXIT.usage, `--strategy is required in non-interactive mode (one of ${STRATEGIES.join(', ')})`);
+  }
+  if (!STRATEGIES.includes(strategy)) {
+    throw new CliError(EXIT.usage, `invalid strategy: ${strategy} (expected ${STRATEGIES.join(', ')})`);
+  }
+  const store = loadStore(c.cwd, c.config);
+  let open = store.feedback.filter((f) => f.status === 'open');
+  if (filters.mine) open = open.filter((f) => f.author.user_id === c.identity.user_id);
+  if (filters.route) open = open.filter((f) => f.location?.route === filters.route);
+  if (filters.session) open = open.filter((f) => f.session_id === filters.session);
+  if (filters.origin) open = open.filter((f) => f.origin?.mode === filters.origin);
+
+  const groups = [];
+  const byKey = new Map();
+  for (const item of open) {
+    const key = targetKey(item);
+    if (!byKey.has(key)) {
+      const group = { key, items: [] };
+      byKey.set(key, group);
+      groups.push(group);
+    }
+    byKey.get(key).items.push(item);
+  }
+
+  const reportGroups = [];
+  const incorporated = [];
+  const conflicts = [];
+  for (const group of groups) {
+    const items = group.items;
+    const kinds = new Set(items.map((i) => i.feedback.type));
+    const isConflict = kinds.has('approval') && (kinds.has('change') || kinds.has('issue') || kinds.has('question'));
+    if (isConflict) {
+      reportGroups.push({ key: group.key, kind: 'conflict', requires_decision: true, feedback_ids: items.map((i) => i.id) });
+      for (const i of items) conflicts.push(i.id);
+      continue;
+    }
+    let kind = 'unique';
+    if (items.length > 1) {
+      const first = normalizedText(items[0].feedback.text);
+      kind = items.every((i) => normalizedText(i.feedback.text) === first) ? 'duplicate' : 'unique';
+    }
+    reportGroups.push({ key: group.key, kind, requires_decision: false, feedback_ids: items.map((i) => i.id) });
+    if (strategy !== 'export-only') {
+      for (const i of items) {
+        i.status = 'incorporated';
+        i.incorporation = { strategy, batch_id: null, recorded_at: c.timestamp };
+        incorporated.push(i.id);
+      }
+    }
+  }
+
+  const seq = countIncorporationBatches(c.cwd) + 1;
+  const batchId = newId('batch', store.project_id, 'default', seq, 'batch', c.now);
+  const report = {
+    schema_version: '1.0',
+    batch_id: batchId,
+    strategy,
+    created_at: c.timestamp,
+    groups: reportGroups,
+    incorporated,
+    conflicts,
+  };
+  if (strategy !== 'export-only') {
+    for (const item of store.feedback) {
+      if (item.incorporation?.batch_id === null && incorporated.includes(item.id)) {
+        item.incorporation.batch_id = batchId;
+      }
+    }
+    saveStore(c.cwd, c.config, store);
+    saveIncorporationBatch(c.cwd, report);
+  }
+  return { stdout: canonicalJson(report) + '\n', exit: EXIT.ok };
+}
+
+export function opValidate(opts, args) {
+  const c = ctx(opts);
+  if (args.record !== undefined) {
+    if (!['passed', 'failed'].includes(args.result)) {
+      throw new CliError(EXIT.usage, `invalid validation result: ${args.result} (expected passed, failed)`);
+    }
+    const store = loadStore(c.cwd, c.config);
+    const item = store.feedback.find((f) => f.id === args.record);
+    if (!item) throw new CliError(EXIT.notFound, `feedback not found: ${args.record}`);
+    item.validation = { result: args.result, checked_at: c.timestamp, ...(args.note ? { note: args.note } : {}) };
+    item.updated_at = c.timestamp;
+    saveStore(c.cwd, c.config, store);
+    return { stdout: canonicalJson(item) + '\n', exit: EXIT.ok };
+  }
+  const store = loadStore(c.cwd, c.config);
+  let items = store.feedback
+    .filter((f) => f.status === 'incorporated')
+    .filter((f) => !args.origin || f.origin?.mode === args.origin)
+    .map((f) => ({
+      id: f.id,
+      location_route: f.location?.route ?? null,
+      validation_result: f.validation?.result ?? 'unvalidated',
+    }));
+  const summary = {
+    total: items.length,
+    passed: items.filter((i) => i.validation_result === 'passed').length,
+    failed: items.filter((i) => i.validation_result === 'failed').length,
+    unvalidated: items.filter((i) => i.validation_result === 'unvalidated').length,
+  };
+  let exit = EXIT.ok;
+  if (args.strict && (summary.failed > 0 || summary.unvalidated > 0)) exit = EXIT.general;
+  if (c.format === 'json') {
+    return { stdout: canonicalJson({ schema_version: '1.0', summary, items }) + '\n', exit };
+  }
+  const lines = items.map((i) => [i.id, i.validation_result].join('\t'));
+  return { stdout: (lines.length ? lines.join('\n') + '\n' : '') + `total ${summary.total}, passed ${summary.passed}, failed ${summary.failed}, unvalidated ${summary.unvalidated}\n`, exit };
+}
+
+function firstLine(text) {
+  return String(text).split('\n')[0];
+}

package/src/ids.js

@@ -0,0 +1,57 @@
+/**
+ * Deterministic identifiers and timestamps.
+ *
+ * IDs are ULIDs (Crockford base32, 26 chars): 48-bit millisecond timestamp
+ * plus 80-bit entropy. For cross-runtime byte-identical output the
+ * timestamp comes from `TUX_TIME_OVERRIDE` (ISO 8601; naive values are
+ * treated as UTC) and the entropy is the first 10 bytes of
+ * `SHA-256("<project_id>|<session_id>|<seq>|<kind>")` where `seq` is the
+ * 1-based next sequence number in the target store.
+ *
+ * @module ids
+ */
+import { createHash } from 'node:crypto';
+import { CliError } from './errors.js';
+
+const CROCKFORD = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+
+/** Resolve the effective "now" in epoch milliseconds. */
+export function nowMs() {
+  const override = process.env.TUX_TIME_OVERRIDE;
+  if (override === undefined) return Date.now();
+  let s = override.trim();
+  if (!/(?:[zZ]|[+-]\d{2}:?\d{2})$/.test(s)) s += 'Z';
+  const t = Date.parse(s);
+  if (Number.isNaN(t)) throw new CliError(3, `invalid TUX_TIME_OVERRIDE: ${override}`);
+  return t;
+}
+
+/** Canonical UTC timestamp with millisecond precision. */
+export function canonicalTimestamp(ms) {
+  return new Date(ms).toISOString();
+}
+
+/** 80-bit entropy bytes derived deterministically from context. */
+export function deterministicEntropy(projectId, sessionId, seq, kind) {
+  const material = `${projectId}|${sessionId}|${seq}|${kind}`;
+  return createHash('sha256').update(material, 'utf8').digest().subarray(0, 10);
+}
+
+/** Encode 16 bytes (6 time + 10 entropy) as a 26-char Crockford ULID. */
+export function ulid(timeMs, entropy) {
+  const buf = Buffer.alloc(16);
+  buf.writeUIntBE(Number(timeMs), 0, 6);
+  entropy.copy(buf, 6);
+  let n = BigInt('0x' + buf.toString('hex'));
+  let out = '';
+  for (let i = 0; i < 26; i++) {
+    out = CROCKFORD[Number(n % 32n)] + out;
+    n /= 32n;
+  }
+  return out;
+}
+
+/** Deterministic prefixed ID (`fb_…`, `batch_…`). */
+export function newId(prefix, projectId, sessionId, seq, kind, timeMs) {
+  return `${prefix}_${ulid(timeMs, deterministicEntropy(projectId, sessionId, seq, kind))}`;
+}

package/src/index.js

@@ -0,0 +1,17 @@
+/**
+ * TUX — TUX UIX review system (Node reference implementation).
+ *
+ * Public library surface alongside the `tux` CLI.
+ *
+ * @module index
+ */
+export { canonicalJson, compactJson, sortedObject } from './canonical.js';
+export { nowMs, canonicalTimestamp, ulid, deterministicEntropy, newId } from './ids.js';
+export { SCHEMA_VERSION, FEEDBACK_TYPES, FEEDBACK_STATUSES, validateFeedback, makeFeedback, normalizedText } from './schema.js';
+export { loadConfig, resolveIdentity } from './config.js';
+export { loadStore, saveStore } from './store.js';
+export { opShow, opCreate, opUpdate, opDelete, opClear, opExport, opIncorporate, opValidate } from './feedback.js';
+export { opDesignInstall, opDesignCreate, opLiveCreate, opDesignStart, opDesignStatus, opDesignStop } from './design.js';
+export { opLiveInstall, opLiveStart, opLiveStatus, opLiveStop } from './live.js';
+export { run, parseArgs, VERSION } from './cli.js';
+export { startServer, inject } from './server.js';

package/src/live.js

@@ -0,0 +1,261 @@
+/**
+ * `tux live <action>` — install, create, start-review, status, stop-review (SPC sections 32–41).
+ * Also hosts the shared server lifecycle used by `tux design start-review`.
+ *
+ * @module live
+ */
+import { existsSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { platform } from 'node:os';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { CliError, EXIT } from './errors.js';
+import { canonicalJson } from './canonical.js';
+import { canonicalTimestamp } from './ids.js';
+import { loadStore } from './store.js';
+
+const SERVER_STATE_FILE = '.tux/server.json';
+
+async function health(url) {
+  try {
+    const r = await fetch(joinUrl(url, '/api/tux/health'), { signal: AbortSignal.timeout(2000) });
+    if (!r.ok) return false;
+    await r.json();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function joinUrl(base, path) {
+  return base.replace(/\/+$/, '') + path;
+}
+
+export function opLiveInstall(opts) {
+  const cwd = opts.cwd;
+  const pkgPath = join(cwd, 'package.json');
+  const hasPkg = existsSync(pkgPath);
+  const hasIndex = existsSync(join(cwd, 'index.html'));
+  if (!hasPkg && !hasIndex) {
+    throw new CliError(EXIT.config, 'unsupported setup: no package.json or index.html found in the current directory');
+  }
+  let pkg = {};
+  if (hasPkg) {
+    try {
+      pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    } catch {
+      throw new CliError(EXIT.config, 'invalid JSON in package.json');
+    }
+  }
+  const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+  let framework = 'vanilla';
+  if (deps.next) framework = 'next';
+  else if (deps['@angular/core']) framework = 'angular';
+  else if (deps.vue) framework = 'vue';
+  else if (deps.react) framework = 'react';
+  const devCommand = pkg.scripts?.dev ?? null;
+  let devPort = 3000;
+  if (devCommand) {
+    const m = devCommand.match(/--port[= ](\d+)/);
+    if (m) devPort = Number(m[1]);
+  }
+  const report = {
+    action: 'install',
+    kind: 'live',
+    strategy: 'proxy',
+    runtime: hasPkg ? 'node' : 'static',
+    framework,
+    dev_command: devCommand,
+    dev_port: hasPkg ? devPort : null,
+    next: ['tux live start-review --url http://localhost:' + (hasPkg ? devPort : 8123)],
+  };
+  if (opts.format === 'text') {
+    const lines = [
+      `installed live review (strategy ${report.strategy}, framework ${framework})`,
+      `next: ${report.next.join(' | ')}`,
+    ];
+    return { stdout: lines.join('\n') + '\n', exit: EXIT.ok };
+  }
+  return { stdout: canonicalJson(report) + '\n', exit: EXIT.ok };
+}
+
+/**
+ * Shared server start for `tux live start-review` and `tux design start-review`.
+ * spec: {mode, host, port, session, environment, url, target|null, root|null, dryRun, foreground, plan}
+ */
+export async function startServer(opts, spec) {
+  if (spec.dryRun) {
+    return { stdout: canonicalJson(spec.plan) + '\n', exit: EXIT.ok };
+  }
+  mkdirSync(join(opts.cwd, '.tux'), { recursive: true });
+  let appPid = null;
+  if (spec.cmd) {
+    appPid = spawnDetached(spec.cmd, opts.cwd);
+    const deadline = Date.now() + 30000;
+    const targetUp = await waitUntil(() => health(spec.target), deadline);
+    if (!targetUp) {
+      killTree(appPid);
+      throw new CliError(EXIT.server, `target application did not become reachable at ${spec.target}`);
+    }
+  }
+  if (spec.foreground) {
+    const { startServer: startInProcess } = await import('./server.js');
+    const server = startInProcess({
+      mode: spec.mode, host: spec.host, port: spec.port,
+      root: spec.root ?? null, target: spec.target ?? null,
+      cwd: opts.cwd, session: spec.session, environment: spec.environment, config: opts.config,
+    });
+    await new Promise((resolvePromise) => server.listen(spec.port, spec.host, resolvePromise));
+    const state = serverState(spec, opts, process.pid);
+    writeState(opts.cwd, state);
+    return { stdout: '', exit: EXIT.ok, keepAlive: server };
+  }
+  const serveMain = fileURLToPath(new URL('./serve-main.js', import.meta.url));
+  const args = [serveMain, '--mode', spec.mode, '--host', String(spec.host), '--port', String(spec.port),
+    '--session', spec.session, '--environment', spec.environment,
+    '--store', opts.config.review.store, '--project-id', opts.config.project_id, '--cwd', opts.cwd];
+  if (spec.root) args.push('--root', spec.root);
+  if (spec.target) args.push('--target', spec.target);
+  const child = spawn(process.execPath, args, { detached: true, stdio: 'ignore', env: process.env });
+  child.unref();
+  const deadline = Date.now() + 15000;
+  const ok = await waitUntil(() => health(spec.url), deadline);
+  if (!ok) {
+    killTree(child.pid);
+    throw new CliError(EXIT.server, `server did not become healthy at ${spec.url}`);
+  }
+  const state = serverState(spec, opts, child.pid);
+  writeState(opts.cwd, state);
+  if (opts.format === 'text') {
+    return { stdout: `server running at ${spec.url} (pid ${state.pid})\n`, exit: EXIT.ok };
+  }
+  return { stdout: canonicalJson(state) + '\n', exit: EXIT.ok };
+}
+
+function serverState(spec, opts, pid) {
+  return {
+    pid,
+    ...(spec.appPid ? { app_pid: spec.appPid } : {}),
+    mode: spec.mode,
+    url: spec.url,
+    ...(spec.target ? { target_url: spec.target } : {}),
+    ...(spec.root ? { root: spec.root } : {}),
+    host: spec.host,
+    port: spec.port,
+    session_id: spec.session,
+    environment: spec.environment,
+    project_id: opts.config.project_id,
+    store: opts.config.review.store,
+    started_at: canonicalTimestamp(Date.now()),
+  };
+}
+
+function writeState(cwd, state) {
+  writeFileSync(join(cwd, SERVER_STATE_FILE), canonicalJson(state) + '\n', 'utf8');
+}
+
+export async function opLiveStart(opts, spec) {
+  const { config } = opts;
+  const host = spec.host ?? config.review.host;
+  const port = spec.port ?? config.review.port;
+  const session = spec.session ?? 'default';
+  const environment = spec.environment ?? 'live';
+  const mode = 'live';
+  const target = spec.url ?? `http://127.0.0.1:${spec.targetPort ?? 3000}`;
+  const url = `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${port}`;
+  const plan = {
+    action: 'start',
+    kind: 'live',
+    mode: spec.cmd ? 'spawn' : 'proxy',
+    target,
+    host,
+    port,
+    session_id: session,
+    environment,
+    url,
+    ...(spec.cmd ? { command: spec.cmd } : {}),
+  };
+  return startServer(opts, {
+    ...spec, mode, host, port, session, environment, target, url,
+    root: null, plan,
+  });
+}
+
+export async function opLiveStatus(opts) {
+  const statePath = join(opts.cwd, SERVER_STATE_FILE);
+  const stopped = { state: 'stopped' };
+  if (!existsSync(statePath)) {
+    if (opts.format === 'json') return { stdout: canonicalJson(stopped) + '\n', exit: EXIT.ok };
+    return { stdout: 'stopped\n', exit: EXIT.ok };
+  }
+  const state = JSON.parse(readFileSync(statePath, 'utf8'));
+  if (!(await health(state.url))) {
+    if (opts.format === 'json') return { stdout: canonicalJson(stopped) + '\n', exit: EXIT.ok };
+    return { stdout: 'stopped\n', exit: EXIT.ok };
+  }
+  const store = loadStore(opts.cwd, opts.config);
+  const result = { state: 'running', ...state, feedback_count: store.feedback.length };
+  if (opts.format === 'json') return { stdout: canonicalJson(result) + '\n', exit: EXIT.ok };
+  const lines = [
+    'state: running',
+    `url: ${state.url}`,
+    `session: ${state.session_id}`,
+    `feedback: ${store.feedback.length}`,
+  ];
+  return { stdout: lines.join('\n') + '\n', exit: EXIT.ok };
+}
+
+export function opLiveStop(opts) {
+  const statePath = join(opts.cwd, SERVER_STATE_FILE);
+  if (!existsSync(statePath)) {
+    if (opts.format === 'json') return { stdout: canonicalJson({ stopped: false, reason: 'not running' }) + '\n', exit: EXIT.ok };
+    return { stdout: 'not running\n', exit: EXIT.ok };
+  }
+  const state = JSON.parse(readFileSync(statePath, 'utf8'));
+  killTree(state.pid);
+  if (state.app_pid) killTree(state.app_pid);
+  rmSync(statePath);
+  if (opts.format === 'json') return { stdout: canonicalJson({ stopped: true, pid: state.pid }) + '\n', exit: EXIT.ok };
+  return { stdout: `stopped (pid ${state.pid})\n`, exit: EXIT.ok };
+}
+
+function spawnDetached(cmd, cwd) {
+  const isWin = platform() === 'win32';
+  const child = isWin
+    ? spawn('cmd.exe', ['/d', '/s', '/c', cmd], { detached: true, stdio: 'ignore', cwd })
+    : spawn('/bin/sh', ['-c', cmd], { detached: true, stdio: 'ignore', cwd });
+  child.unref();
+  return child.pid;
+}
+
+function killTree(pid) {
+  if (pid === null || pid === undefined) return;
+  try {
+    if (platform() === 'win32') {
+      spawn('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
+    } else {
+      try {
+        process.kill(-pid, 'SIGTERM');
+      } catch {
+        process.kill(pid, 'SIGTERM');
+      }
+    }
+  } catch {
+    /* already gone */
+  }
+}
+
+function waitUntil(fn, deadlineMs) {
+  return new Promise((resolvePromise) => {
+    const tick = async () => {
+      try {
+        if (await fn()) return resolvePromise(true);
+      } catch {
+        /* keep waiting */
+      }
+      if (Date.now() > deadlineMs) return resolvePromise(false);
+      setTimeout(tick, 250);
+    };
+    tick();
+  });
+}