tux-review 0.1.0

package/skills/tux-live-stop-review.md

@@ -0,0 +1,46 @@
+---
+name: tux-live-stop-review
+description: Stop the live review proxy cleanly — check state first, report the session summary, preserve every feedback item.
+---
+
+# tux-live-stop-review
+
+End a live review session deliberately: check the proxy state, hand over
+a session summary, then stop. In proxy mode the application itself was
+never modified and keeps serving untouched after the proxy is gone; in
+spawn mode the spawned review application is shut down with the session
+(SPC section 41).
+
+## Resolve the CLI
+
+Choose one TUX CLI variant; both implement the same commands and canonical
+JSON output, so do not install both:
+
+1. **Node.js/npm** — use an existing `tux --version` on PATH, or run
+   `npx --yes --package=tux-review tux --version` and prefix commands with
+   `npx --yes --package=tux-review tux …`.
+2. **Python/PyPI** — install with `pipx install tux-review` (or
+   `python -m pip install tux-review` in the active virtual environment),
+   then use `tux --version`. For a one-off run, use
+   `pipx run tux-review tux --version`.
+
+All commands below use the neutral form `tux <domain> <action>`. Replace
+`tux` with the Node `npx … tux` prefix only when you chose the Node
+one-off variant.
+
+## Workflow
+
+1. Check the current state: `tux live status --format json` — reports
+   `running` with URL, session and feedback count, or `stopped`. Never
+   stop blind.
+2. Report the session summary before stopping: target URL, session name,
+   feedback count.
+3. Stop with `tux live stop-review --format json`. The output confirms
+   `stopped: true` with the pid; `stopped: false` with reason
+   `not running` means there was nothing to stop. In spawn mode the
+   spawned application process is stopped together with the proxy.
+4. Verify: `tux live status` now reports `stopped`, and the feedback
+   store still contains every item — stopping MUST NOT delete feedback
+   (SPC section 41).
+5. Report the final state: review stopped, feedback count preserved,
+   store path.

package/src/canonical.js

@@ -0,0 +1,28 @@
+/**
+ * Canonical JSON serialization.
+ *
+ * Canonical JSON is UTF-8, 2-space indented, `\n` line endings, keys in
+ * the fixed schema order (objects are built in that order by the
+ * constructors; free-form `ui_state` keys are sorted alphabetically) with
+ * a single trailing newline when written as a document. Both reference
+ * implementations (Node, Python) must emit byte-identical bytes.
+ *
+ * @module canonical
+ */
+
+/** Serialize a value as canonical JSON text (no trailing newline). */
+export function canonicalJson(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+/** Serialize a value as a compact single-line JSON text (no newline). */
+export function compactJson(value) {
+  return JSON.stringify(value);
+}
+
+/** Sort the keys of a free-form object alphabetically (one level). */
+export function sortedObject(obj) {
+  const out = {};
+  for (const k of Object.keys(obj).sort()) out[k] = obj[k];
+  return out;
+}

package/src/cli.js

@@ -0,0 +1,229 @@
+/**
+ * `tux` command-line interface (SPC sections 25, 74, 75).
+ *
+ * Grammar: `tux <domain> <action> [arguments] [options]`.
+ * Machine output: canonical JSON on stdout; diagnostics on stderr as
+ * `error: <message>` lines with canonical exit codes.
+ *
+ * @module cli
+ */
+import { CliError, EXIT } from './errors.js';
+import { loadConfig } from './config.js';
+import { opShow, opCreate, opUpdate, opDelete, opClear, opExport, opIncorporate, opValidate } from './feedback.js';
+import { opDesignInstall, opDesignCreate, opLiveCreate, opDesignStart, opDesignStatus, opDesignStop } from './design.js';
+import { opLiveInstall, opLiveStart, opLiveStatus, opLiveStop } from './live.js';
+
+export const VERSION = '0.1.0';
+
+const VALUE_FLAGS = new Set([
+  'config', 'format', 'type', 'text', 'route', 'page', 'component', 'component-instance', 'instance',
+  'tux-id', 'test-id', 'session', 'environment', 'origin', 'status', 'strategy', 'result', 'note', 'record',
+  'url', 'target-port', 'port', 'host', 'store', 'project-id', 'name', 'framework', 'dir', 'root', 'out',
+  'mode', 'target',
+]);
+const BOOL_FLAGS = new Set(['mine', 'all', 'force', 'strict', 'dry-run', 'no-interactive', 'foreground', 'help', 'version']);
+
+export function parseArgs(args) {
+  const flags = {};
+  const positional = [];
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    if (a === '--') {
+      positional.push(...args.slice(i + 1));
+      return { flags, positional, cmd: null };
+    }
+    if (a.startsWith('--')) {
+      const name = a.slice(2);
+      if (VALUE_FLAGS.has(name)) {
+        const v = args[i + 1];
+        if (v === undefined) throw new CliError(EXIT.usage, `option --${name} requires a value`);
+        flags[name] = v;
+        i += 2;
+        continue;
+      }
+      if (BOOL_FLAGS.has(name)) {
+        flags[name] = true;
+        i += 1;
+        continue;
+      }
+      throw new CliError(EXIT.usage, `unknown option: --${name}`);
+    }
+    positional.push(a);
+    i += 1;
+  }
+  return { flags, positional, cmd: null };
+}
+
+function optsFrom(cwd, config, configPath, flags) {
+  return {
+    cwd,
+    config,
+    configPath,
+    format: flags.format ?? null,
+  };
+}
+
+function requireFormat(flags, fallback) {
+  return flags.format ?? fallback;
+}
+
+export async function run(argv, context = {}) {
+  const cwd = context.cwd ?? process.cwd();
+  let parsed;
+  try {
+    parsed = parseArgs(argv);
+  } catch (e) {
+    if (e instanceof CliError) return fail(e);
+    throw e;
+  }
+  const { flags, positional } = parsed;
+
+  try {
+    if (flags.version) return { stdout: `tux ${VERSION}\n`, exit: EXIT.ok };
+    if (flags.help || positional.length === 0) return { stdout: help(), exit: EXIT.ok };
+
+    const domain = positional[0];
+    const action = positional[1];
+
+    if (domain === 'feedback') {
+      const { config, configPath } = loadConfig(cwd, flags);
+      const opts = optsFrom(cwd, config, configPath, flags);
+      opts.format = requireFormat(flags, opts.format);
+      switch (action) {
+        case 'show': {
+          const id = positional[2];
+          opts.format = flags.format ?? 'text';
+          return opShow(opts, id, {
+            status: flags.status, type: flags.type, mine: flags.mine ?? false,
+            route: flags.route, session: flags.session, origin: flags.origin,
+          });
+        }
+        case 'create':
+          return opCreate(opts, {
+            type: flags.type ?? 'issue',
+            text: flags.text,
+            route: flags.route,
+            page: flags.page,
+            component: flags.component,
+            instance: flags['component-instance'] ?? flags.instance,
+            tuxId: flags['tux-id'],
+            testId: flags['test-id'],
+            session: flags.session,
+            environment: flags.environment,
+            origin: flags.origin,
+          });
+        case 'update': {
+          const id = positional[2];
+          if (!id) throw new CliError(EXIT.usage, 'usage: tux feedback update <feedback-id>');
+          return opUpdate(opts, id, { text: flags.text, type: flags.type, status: flags.status });
+        }
+        case 'delete': {
+          const id = positional[2];
+          if (!id) throw new CliError(EXIT.usage, 'usage: tux feedback delete <feedback-id>');
+          opts.format = flags.format ?? 'text';
+          return opDelete(opts, id);
+        }
+        case 'clear':
+          opts.format = flags.format ?? 'text';
+          return opClear(opts, flags.all ? 'all' : flags.mine ? 'mine' : undefined, {
+            force: flags.force ?? false, route: flags.route, session: flags.session,
+          });
+        case 'export':
+          return opExport(opts, flags.format === 'jsonl' ? 'jsonl' : 'json');
+        case 'incorporate':
+          return opIncorporate(opts, flags.strategy, {
+            mine: flags.mine ?? false, route: flags.route, session: flags.session, origin: flags.origin,
+          });
+        case 'validate':
+          return opValidate(opts, {
+            record: flags.record ?? undefined,
+            result: flags.result,
+            note: flags.note,
+            strict: flags.strict ?? false,
+            origin: flags.origin,
+          });
+        default:
+          throw new CliError(EXIT.usage, `unknown action: ${action ?? '(missing)'} for domain ${domain}`);
+      }
+    }
+
+    if (domain === 'design' || domain === 'live') {
+      const { config, configPath } = loadConfig(cwd, flags);
+      const opts = optsFrom(cwd, config, configPath, flags);
+      const isDesign = domain === 'design';
+      opts.format = requireFormat(flags, 'json');
+      switch (action) {
+        case 'install':
+          return isDesign
+            ? opDesignInstall(opts, { framework: flags.framework, root: flags.root })
+            : opLiveInstall(opts);
+        case 'create':
+          return isDesign
+            ? opDesignCreate(opts, { framework: flags.framework, name: flags.name })
+            : opLiveCreate(opts, { framework: flags.framework, name: flags.name });
+        case 'start-review':
+          opts.format = flags.format ?? 'json';
+          if (isDesign) {
+            return await opDesignStart(opts, {
+              dir: flags.dir,
+              port: flags.port ? Number(flags.port) : undefined,
+              host: flags.host,
+              session: flags.session,
+              environment: flags.environment,
+              dryRun: flags['dry-run'] ?? false,
+              foreground: flags.foreground ?? false,
+            });
+          }
+          return await opLiveStart(opts, {
+            url: flags.url ?? null,
+            cmd: parsed.cmd && parsed.cmd.length ? parsed.cmd.join(' ') : (positional.length > 2 ? positional.slice(2).join(' ') : null),
+            targetPort: flags['target-port'] ? Number(flags['target-port']) : undefined,
+            port: flags.port ? Number(flags.port) : undefined,
+            host: flags.host,
+            session: flags.session,
+            environment: flags.environment,
+            dryRun: flags['dry-run'] ?? false,
+            foreground: flags.foreground ?? false,
+          });
+        case 'status': {
+          opts.format = flags.format ?? 'text';
+          return await opLiveStatus(opts);
+        }
+        case 'stop-review': {
+          opts.format = flags.format ?? 'text';
+          return opLiveStop(opts);
+        }
+        default:
+          throw new CliError(EXIT.usage, `unknown action: ${action ?? '(missing)'} for domain ${domain}`);
+      }
+    }
+
+    throw new CliError(EXIT.usage, `unknown command: ${domain}`);
+  } catch (e) {
+    if (e instanceof CliError) return fail(e);
+    return { stdout: '', stderr: `error: internal: ${e.message}\n`, exit: EXIT.general };
+  }
+}
+
+function fail(e) {
+  return { stdout: '', stderr: `error: ${e.message}\n`, exit: e.code };
+}
+
+function help() {
+  return [
+    'tux <domain> <action> [arguments] [options]',
+    '',
+    'domains:',
+    '  design    install | create | start-review | status | stop-review',
+    '  live      install | create | start-review | status | stop-review',
+    '  feedback  show | create | update | delete | clear | export | incorporate | validate',
+    '',
+    'options:',
+    '  --config <path>     project config (default: tux.config.json)',
+    '  --format json|text  output format',
+    '  --version           print version',
+    '  --help              this help',
+    '',
+  ].join('\n');
+}

package/src/config.js

@@ -0,0 +1,72 @@
+/**
+ * Project configuration (`tux.config.json`) with canonical precedence:
+ * CLI → environment → config file → defaults (SPC section 76).
+ *
+ * @module config
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { CliError } from './errors.js';
+
+export const CONFIG_FILE = 'tux.config.json';
+
+export function defaultConfig(cwd) {
+  return {
+    project_id: basename(cwd),
+    design: { root: 'requirements', framework: 'vanilla' },
+    review: { enabled: true, store: '.tux/feedback.json', host: '127.0.0.1', port: 4173 },
+    identity: { provider: 'local', user_id: 'anonymous', display_name: 'Anonymous', admins: [] },
+  };
+}
+
+/**
+ * @param {string} cwd project working directory
+ * @param {{config?: string}} cliOpts CLI options (`--config`)
+ * @returns {{config: object, configPath: string|null, cwd: string}}
+ */
+export function loadConfig(cwd, cliOpts = {}) {
+  const config = defaultConfig(cwd);
+  let configPath = cliOpts.config ?? process.env.TUX_CONFIG ?? null;
+  if (configPath === null && existsSync(join(cwd, CONFIG_FILE))) configPath = join(cwd, CONFIG_FILE);
+  if (configPath !== null) {
+    if (!existsSync(configPath)) throw new CliError(3, `config file not found: ${configPath}`);
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(configPath, 'utf8'));
+    } catch (e) {
+      throw new CliError(3, `invalid config JSON in ${configPath}: ${e.message}`);
+    }
+    mergeConfig(config, parsed);
+  }
+  const env = process.env;
+  if (env.TUX_PROJECT_ID !== undefined) config.project_id = env.TUX_PROJECT_ID;
+  if (env.TUX_STORE !== undefined) config.review.store = env.TUX_STORE;
+  if (env.TUX_HOST !== undefined) config.review.host = env.TUX_HOST;
+  if (env.TUX_PORT !== undefined) config.review.port = Number(env.TUX_PORT);
+  if (env.TUX_USER_ID !== undefined) config.identity.user_id = env.TUX_USER_ID;
+  if (env.TUX_DISPLAY_NAME !== undefined) config.identity.display_name = env.TUX_DISPLAY_NAME;
+  return { config, configPath, cwd };
+}
+
+function mergeConfig(target, patch) {
+  for (const [key, value] of Object.entries(patch ?? {})) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value) && typeof target[key] === 'object') {
+      mergeConfig(target[key], value);
+    } else {
+      target[key] = value;
+    }
+  }
+}
+
+/** Resolve the effective reviewer identity. */
+export function resolveIdentity(config) {
+  return {
+    user_id: config.identity.user_id || 'anonymous',
+    display_name: config.identity.display_name || 'Anonymous',
+    admins: config.identity.admins ?? [],
+  };
+}
+
+export function isAdmin(config, userId) {
+  return resolveIdentity(config).admins.includes(userId);
+}

package/src/design.js

@@ -0,0 +1,140 @@
+/**
+ * `tux design <action>` — install, create, start-review, status, stop-review (SPC sections 28–38).
+ * `tux live create` (SPC section 32) shares the create primitive with `"kind": "live"`.
+ *
+ * @module design
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { CliError, EXIT } from './errors.js';
+import { canonicalJson } from './canonical.js';
+import { CONFIG_FILE, defaultConfig } from './config.js';
+import { SUPPORTED_FRAMEWORKS, designTemplate } from './templates.js';
+import { startServer, opLiveStatus, opLiveStop } from './live.js';
+
+function textReport(lines) {
+  return { stdout: lines.join('\n') + '\n', exit: EXIT.ok };
+}
+
+function relPath(cwd, p) {
+  const rel = relative(cwd, p);
+  if (rel === '') return '.';
+  return rel.startsWith('..') ? p : rel;
+}
+
+export function opDesignInstall(opts, spec) {
+  const cwd = opts.cwd;
+  const framework = spec.framework ?? opts.config.design.framework ?? 'vanilla';
+  if (!SUPPORTED_FRAMEWORKS.includes(framework)) {
+    throw new CliError(EXIT.usage, `unsupported framework: ${framework} (expected ${SUPPORTED_FRAMEWORKS.join(', ')})`);
+  }
+  const configPath = opts.configPath ?? join(cwd, CONFIG_FILE);
+  let config;
+  if (existsSync(configPath)) {
+    config = JSON.parse(readFileSync(configPath, 'utf8'));
+  } else {
+    config = defaultConfig(cwd);
+  }
+  config.design = config.design ?? {};
+  config.design.framework = framework;
+  if (spec.root) config.design.root = spec.root;
+  const root = config.design.root ?? 'requirements';
+  writeFileSync(configPath, canonicalJson(config) + '\n', 'utf8');
+  const report = {
+    action: 'install',
+    kind: 'design',
+    framework,
+    root,
+    config: opts.configPath ? relPath(cwd, opts.configPath) : CONFIG_FILE,
+    next: [`tux design create --framework ${framework}`, 'tux design start-review'],
+  };
+  if (opts.format === 'text') {
+    return textReport([
+      `installed design review (framework ${framework})`,
+      `config: ${report.config}`,
+      `next: ${report.next.join(' | ')}`,
+    ]);
+  }
+  return { stdout: canonicalJson(report) + '\n', exit: EXIT.ok };
+}
+
+const DEV_PORT = { vanilla: 4173, react: 5173, vue: 5173, angular: 4200 };
+
+/**
+ * Create the runnable design scaffold (`tux design create`) or the identical
+ * live-app scaffold (`tux live create`, `"kind": "live"`).
+ */
+export function opDesignCreate(opts, spec) {
+  const kind = spec.kind ?? 'design';
+  const cwd = opts.cwd;
+  const framework = spec.framework;
+  if (!framework) throw new CliError(EXIT.usage, '--framework is required');
+  if (!SUPPORTED_FRAMEWORKS.includes(framework)) {
+    throw new CliError(EXIT.usage, `unsupported framework: ${framework} (expected ${SUPPORTED_FRAMEWORKS.join(', ')})`);
+  }
+  if (!spec.name || !/^[a-z0-9][a-z0-9-]*$/.test(spec.name)) {
+    throw new CliError(EXIT.usage, '--name must be a lowercase slug (letters, digits, dashes)');
+  }
+  const root = opts.config.design.root ?? 'requirements';
+  const designDir = resolve(cwd, root, spec.name, 'design');
+  if (existsSync(designDir)) {
+    throw new CliError(EXIT.conflict, `design directory already exists: ${root}/${spec.name}/design`);
+  }
+  const files = designTemplate(framework);
+  for (const [rel, content] of Object.entries(files)) {
+    const p = join(designDir, rel);
+    mkdirSync(join(p, '..'), { recursive: true });
+    writeFileSync(p, content, 'utf8');
+  }
+  const domain = kind === 'live' ? 'live' : 'design';
+  const next = kind === 'live'
+    ? ['tux live install', `tux live start-review --url http://localhost:${DEV_PORT[framework]}`]
+    : ['tux design start-review', 'review in the browser'];
+  const report = {
+    action: 'create',
+    kind,
+    framework,
+    name: spec.name,
+    root: `${root}/${spec.name}/design`,
+    next,
+  };
+  if (opts.format === 'text') {
+    return textReport([
+      `created ${report.root} (framework ${framework}, kind ${kind})`,
+      `next: ${report.next.join(' | ')}`,
+    ]);
+  }
+  return { stdout: canonicalJson(report) + '\n', exit: EXIT.ok };
+}
+
+export function opLiveCreate(opts, spec) {
+  return opDesignCreate(opts, { ...spec, kind: 'live' });
+}
+
+export async function opDesignStart(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 ?? 'design';
+  const root = resolve(opts.cwd, spec.dir ?? config.design.root);
+  const url = `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${port}`;
+  const plan = {
+    action: 'start',
+    kind: 'design',
+    mode: 'design',
+    root: relPath(opts.cwd, root),
+    host,
+    port,
+    session_id: session,
+    environment,
+    url,
+  };
+  return startServer(opts, {
+    mode: 'design', host, port, session, environment, url,
+    root: relPath(opts.cwd, root), target: null,
+    dryRun: spec.dryRun ?? false, foreground: spec.foreground ?? false, plan,
+  });
+}
+
+export { opLiveStatus as opDesignStatus, opLiveStop as opDesignStop };

package/src/errors.js

@@ -0,0 +1,28 @@
+/**
+ * CLI error carrying a canonical exit code (SPC section 75).
+ *
+ * @module errors
+ */
+
+export const EXIT = {
+  ok: 0,
+  general: 1,
+  usage: 2,
+  config: 3,
+  server: 4,
+  authorization: 5,
+  notFound: 6,
+  conflict: 7,
+};
+
+/** Error with a canonical exit code; message printed as `error: …` on stderr. */
+export class CliError extends Error {
+  /**
+   * @param {number} code canonical exit code
+   * @param {string} message diagnostic message (no locale, no paths of the host)
+   */
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}