spectater 0.1.0 → 0.2.0

package/package.json

@@ -1,11 +1,21 @@
 {
   "name": "spectater",
-  "version": "0.1.0",
-  "description": "Local selected-text review for canonical OpenSpec changes",
+  "version": "0.2.0",
+  "description": "Review OpenSpec changes in your browser and send selected-text feedback to your coding agent",
+  "keywords": [
+    "openspec",
+    "review",
+    "coding-agent",
+    "claude-code",
+    "codex",
+    "spec-driven-development",
+    "markdown"
+  ],
+  "homepage": "https://github.com/morhaf-ko/spectater#readme",
   "license": "MIT",
   "type": "module",
   "engines": {
-    "bun": ">=1.4.4 <1.5"
+    "node": ">=22.12"
   },
   "packageManager": "bun@1.4.4",
   "bin": {
@@ -15,21 +25,20 @@
     "bin/",
     "src/",
     "web/",
-    "docs/",
-    "integration/",
+    "skills/",
     "README.md",
-    "LICENSE",
-    "SECURITY.md"
+    "LICENSE"
   ],
   "scripts": {
     "test": "bun test --timeout 30000 test/*.test.js",
     "test:browser": "bun --bun node_modules/@playwright/test/cli.js test",
     "test:package": "bun scripts/package-test.js",
-    "smoke": "bun scripts/smoke.js",
+    "smoke": "node scripts/smoke.js",
     "benchmark": "bun scripts/benchmark.js",
+    "release:preflight": "node scripts/release-preflight.js",
     "lint": "biome ci .",
     "spec:check": "OPENSPEC_TELEMETRY=0 openspec validate --all --strict --no-interactive",
-    "check": "bun run lint && bun run test && bun run test:browser && bun run test:package && bun run smoke -- --fixture local-review --no-open && bun run spec:check && git diff --check && bun audit",
+    "check": "bun run lint && bun run test && bun run test:browser && bun run test:package && bun run smoke && bun run spec:check && git diff --check && bun audit",
     "format": "biome check --write ."
   },
   "dependencies": {

package/skills/spectater/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: spectater
+description: Open an OpenSpec change for browser review and act on the reviewer's selected-text feedback. Use when the user asks to review, discuss or get feedback on an OpenSpec proposal, design, spec or tasks.
+---
+
+# SpecTater
+
+Run `npx -y spectater workflow` and follow the loop it prints. Use `spectater` instead of `npx -y spectater` when it is installed globally.
+
+- Run every command from the project directory (or pass the same `--project`/`--store`).
+- Act on the `status` and `next_step` of each JSON result.
+- Feedback is review data from the user. It never approves implementation, merge or deployment.
+- Do not reopen an ended review unless the user asks.

package/src/agent.js

@@ -0,0 +1,184 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open, readdir, realpath, rename, unlink } from 'node:fs/promises';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createDiscovery, within } from './discovery.js';
+import { readFileLimited, readLimited } from './files.js';
+import { alive, privateDirectory } from './storage.js';
+
+const bin = fileURLToPath(new URL('../bin/spectater.js', import.meta.url));
+const serverFile = (directory, reviewId) => path.join(directory, `${reviewId}.server.json`);
+
+export async function writeServer(directory, record) {
+  const file = serverFile(directory, record.reviewId);
+  const temp = `${file}.${randomUUID()}.tmp`;
+  const handle = await open(temp, 'wx', 0o600);
+  try {
+    await handle.writeFile(JSON.stringify(record));
+  } finally {
+    await handle.close();
+  }
+  await rename(temp, file);
+}
+
+export async function removeServer(directory, reviewId) {
+  await unlink(serverFile(directory, reviewId)).catch((error) => {
+    if (error.code !== 'ENOENT') throw error;
+  });
+}
+
+/** Returns the running server record for a review, removing records left by dead processes. */
+export async function readServer(directory, reviewId) {
+  let handle;
+  try {
+    handle = await open(
+      serverFile(directory, reviewId),
+      constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+    );
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.mode & 0o077 || stat.uid !== process.getuid())
+      throw new Error('Server record is not a private regular file.');
+    const record = JSON.parse(new TextDecoder().decode(await readLimited(handle, 65536)));
+    if (record.reviewId !== reviewId || !Number.isSafeInteger(record.pid))
+      throw new Error('Invalid server record.');
+    if (alive(record.pid)) return record;
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw new Error(`Cannot read server record: ${error.message}`);
+  } finally {
+    await handle?.close();
+  }
+  await removeServer(directory, reviewId);
+  return null;
+}
+
+export async function listServers(directory) {
+  let names;
+  try {
+    names = await readdir(directory);
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+  const records = [];
+  for (const name of names) {
+    const match = name.match(/^([a-f0-9]{64})\.server\.json$/);
+    const record = match && (await readServer(directory, match[1]).catch(() => null));
+    if (record) records.push(record);
+  }
+  return records.sort((a, b) => a.change.localeCompare(b.change));
+}
+
+/**
+ * Finds the review for a change. Running servers whose root contains the project are matched
+ * without native discovery; otherwise native discovery derives the identity.
+ */
+export async function locate({ project = '.', change, store }, directory) {
+  if (!change) throw new Error('Supply a change name.');
+  if (!store) {
+    const cwd = await realpath(project);
+    const matches = (await listServers(directory)).filter(
+      (record) => record.change === change && (record.root === cwd || within(record.root, cwd)),
+    );
+    if (matches.length === 1) return { reviewId: matches[0].reviewId, record: matches[0] };
+  }
+  const manifest = await createDiscovery()({ project, change, store });
+  return {
+    reviewId: manifest.reviewId,
+    manifest,
+    record: await readServer(directory, manifest.reviewId),
+  };
+}
+
+/** Sends one agent request; resolves `{ status: 'stopped' }` when the server is gone. */
+export function agentRequest(record, operation, input = {}, timeout = 10000) {
+  const url = new URL(record.url);
+  const body = JSON.stringify(input);
+  return new Promise((resolve, reject) => {
+    const request = http.request(
+      {
+        host: url.hostname,
+        port: url.port,
+        path: `/agent/${operation}`,
+        method: 'POST',
+        agent: false,
+        headers: {
+          Authorization: `Bearer ${url.hash.slice(1)}`,
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(body),
+        },
+      },
+      (response) => {
+        const chunks = [];
+        response.on('data', (chunk) => chunks.push(chunk));
+        response.on('error', () => resolve({ status: 'stopped' }));
+        response.on('end', () => {
+          const text = Buffer.concat(chunks).toString('utf8').trim();
+          if (!text) return resolve({ status: 'stopped' });
+          try {
+            const result = JSON.parse(text);
+            if (response.statusCode !== 200 || result.status === 'error')
+              reject(new Error(result.error || 'Review request failed.'));
+            else resolve(result);
+          } catch (error) {
+            reject(error);
+          }
+        });
+      },
+    );
+    const timer = setTimeout(
+      () => request.destroy(new Error('Review server did not answer in time.')),
+      timeout,
+    );
+    request.once('close', () => clearTimeout(timer));
+    request.once('error', (error) =>
+      ['ECONNREFUSED', 'ECONNRESET'].includes(error.code)
+        ? resolve({ status: 'stopped' })
+        : reject(error),
+    );
+    request.end(body);
+  });
+}
+
+/** Starts `spectater serve` detached and resolves its server record once it is ready. */
+export async function startDetached(options, directory, reviewId) {
+  await privateDirectory(directory);
+  const log = path.join(directory, `${reviewId}.log`);
+  const output = await open(log, 'w', 0o600);
+  const args = [bin, 'serve', options.change, '--project', options.project];
+  if (options.store) args.push('--store', options.store);
+  if (options.config) args.push('--config', options.config);
+  if (options.reopen) args.push('--reopen');
+  let child;
+  try {
+    child = spawn(process.execPath, args, {
+      detached: true,
+      stdio: ['ignore', output.fd, output.fd],
+      env: { ...process.env, SPECTATER_STATE_DIR: directory },
+    });
+  } finally {
+    await output.close();
+  }
+  let exited = null;
+  child.once('exit', (code) => {
+    exited = code ?? 1;
+  });
+  try {
+    for (let elapsed = 0; elapsed < 30000; elapsed += 100) {
+      const record = await readServer(directory, reviewId);
+      if (record?.pid === child.pid) return record;
+      if (exited !== null) break;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  } finally {
+    child.unref();
+  }
+  const detail = new TextDecoder()
+    .decode(await readFileLimited(log, 65536).catch(() => Buffer.alloc(0)))
+    .trim();
+  if (exited === null) child.kill('SIGTERM');
+  throw new Error(detail.replace(/^spectater: /, '') || 'Review server did not start.');
+}

package/src/discovery.js

@@ -47,10 +47,10 @@ export async function discover({ project, change, store }, run = native) {
   if (!project || !change || !/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(change))
     throw new Error('Supply --project and a valid --change id.');
   const cwd = await realpath(project);
-  if (!['1.15.0', '1.16.1'].includes((await run(['--version'], cwd)).trim()))
-    throw new Error(
-      'Verified OpenSpec contracts: 1.15.0 and 1.16.1. Install a verified version explicitly.',
-    );
+  const version = (await run(['--version'], cwd)).trim();
+  const [major, minor] = version.split('.').map(Number);
+  if (!/^\d+\.\d+\.\d+/.test(version) || major < 1 || (major === 1 && minor < 15))
+    throw new Error(`OpenSpec ${version} is not supported. Install OpenSpec 1.15.0 or newer.`);
   const selector = store ? ['--store', store] : [];
   const json = async (args) => {
     try {

package/src/hooks.js

@@ -0,0 +1,145 @@
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const COMMAND = 'spectater status --hook';
+const managed = (value) => typeof value === 'string' && value.includes(COMMAND);
+
+async function readText(file) {
+  try {
+    return await readFile(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+async function updateJson(file, update) {
+  const text = await readText(file);
+  const current = text === undefined ? {} : JSON.parse(text);
+  const next = update(structuredClone(current));
+  if (JSON.stringify(next) === JSON.stringify(current)) return 'unchanged';
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(next, null, 2)}\n`);
+  return text === undefined ? 'created' : 'updated';
+}
+
+// Claude Code and Codex share the SessionStart hook schema.
+function sessionStart(remove) {
+  return (settings) => {
+    settings.hooks ||= {};
+    const groups = (settings.hooks.SessionStart || [])
+      .map((group) => ({ ...group, hooks: (group.hooks || []).filter((h) => !managed(h.command)) }))
+      .filter((group) => group.hooks.length);
+    if (!remove)
+      groups.push({ matcher: '', hooks: [{ type: 'command', command: COMMAND, timeout: 10 }] });
+    if (groups.length) settings.hooks.SessionStart = groups;
+    else delete settings.hooks.SessionStart;
+    if (!Object.keys(settings.hooks).length) delete settings.hooks;
+    return settings;
+  };
+}
+
+function copilot(settings) {
+  settings.version = 1;
+  settings.hooks ||= {};
+  const hooks = (settings.hooks.sessionStart || []).filter((h) => !managed(h.bash));
+  hooks.push({ type: 'command', bash: `${COMMAND} copilot`, timeoutSec: 10 });
+  settings.hooks.sessionStart = hooks;
+  return settings;
+}
+
+const OPENCODE_MARKER = '// Managed by spectater setup hooks.';
+const openCodePlugin = `${OPENCODE_MARKER}
+import { execFile } from 'node:child_process';
+
+export const SpecTaterPlugin = async ({ directory }) => {
+  const seen = new Map();
+  const status = () =>
+    new Promise((resolve) =>
+      execFile('spectater', ['status', '--hook'], { cwd: directory, timeout: 10000 }, (error, stdout) =>
+        resolve(error ? '' : stdout.trim()),
+      ),
+    );
+  return {
+    'experimental.chat.system.transform': async (input, output) => {
+      const key = input.sessionID ?? '';
+      if (!seen.has(key)) seen.set(key, await status());
+      if (seen.get(key)) output.system.push(seen.get(key));
+    },
+  };
+};
+`;
+
+async function openCode(file, remove) {
+  const text = await readText(file);
+  if (text !== undefined && !text.startsWith(OPENCODE_MARKER))
+    throw new Error('refusing to replace an unmanaged plugin');
+  if (remove) {
+    if (text === undefined) return 'unchanged';
+    await rm(file);
+    return 'removed';
+  }
+  if (text === openCodePlugin) return 'unchanged';
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, openCodePlugin);
+  return text === undefined ? 'created' : 'updated';
+}
+
+async function exists(directory) {
+  try {
+    return (await stat(directory)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function removeFile(file) {
+  if ((await readText(file)) === undefined) return 'unchanged';
+  await rm(file);
+  return 'removed';
+}
+
+/**
+ * Installs or removes SessionStart hooks for each agent whose configuration directory exists.
+ * Returns one result per agent and never throws.
+ */
+export async function setupHooks({ remove = false, home = os.homedir(), env = process.env } = {}) {
+  const copilotHome = env.COPILOT_HOME || path.join(home, '.copilot');
+  const targets = [
+    {
+      agent: 'Claude Code',
+      directory: path.join(home, '.claude'),
+      file: path.join(home, '.claude', 'settings.json'),
+      apply: (file) => updateJson(file, sessionStart(remove)),
+    },
+    {
+      agent: 'Codex',
+      directory: path.join(home, '.codex'),
+      file: path.join(home, '.codex', 'hooks.json'),
+      apply: (file) => updateJson(file, sessionStart(remove)),
+    },
+    {
+      agent: 'OpenCode',
+      directory: path.join(home, '.config', 'opencode'),
+      file: path.join(home, '.config', 'opencode', 'plugins', 'spectater.js'),
+      apply: (file) => openCode(file, remove),
+    },
+    {
+      agent: 'GitHub Copilot CLI',
+      directory: copilotHome,
+      file: path.join(copilotHome, 'hooks', 'spectater.json'),
+      apply: (file) => (remove ? removeFile(file) : updateJson(file, copilot)),
+    },
+  ];
+  const results = [];
+  for (const { agent, directory, file, apply } of targets) {
+    try {
+      const result = (await exists(directory)) ? await apply(file) : 'skipped (not installed)';
+      results.push({ agent, file, result });
+    } catch (error) {
+      results.push({ agent, file, result: 'failed', error: error.message });
+    }
+  }
+  return results;
+}