spectater 0.0.0-stage → 0.2.0

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/changes.js

@@ -0,0 +1,82 @@
+import { execFile } from 'node:child_process';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+export function sourceChanges(state) {
+  if (!state.previousDocuments) return [];
+  const before = state.previousDocuments,
+    after = state.currentDocuments || {};
+  return [...new Set([...Object.keys(before), ...Object.keys(after)])]
+    .flatMap((id) => {
+      if (before[id]?.hash === after[id]?.hash) return [];
+      return [
+        {
+          id,
+          path: (after[id] || before[id]).path,
+          status: !before[id] ? 'added' : !after[id] ? 'removed' : 'changed',
+          beforeHash: before[id]?.hash,
+          afterHash: after[id]?.hash,
+        },
+      ];
+    })
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export async function compareSources(state, id, run = promisify(execFile)) {
+  const change = sourceChanges(state).find((item) => item.id === id);
+  if (!change) throw new Error('No source comparison for this document.');
+  const directory = await mkdtemp(path.join(os.tmpdir(), 'spectater-diff-'));
+  try {
+    for (const [name, hash] of [
+      ['before', change.beforeHash],
+      ['after', change.afterHash],
+    ]) {
+      await writeFile(path.join(directory, name), hash ? state.snapshots[hash].source : '', {
+        mode: 0o600,
+        flag: 'wx',
+      });
+    }
+    const env = Object.fromEntries(
+      Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')),
+    );
+    Object.assign(env, {
+      GIT_CONFIG_NOSYSTEM: '1',
+      GIT_CONFIG_GLOBAL: os.devNull,
+      GIT_ATTR_NOSYSTEM: '1',
+      LC_ALL: 'C',
+    });
+    let diff;
+    try {
+      ({ stdout: diff } = await run(
+        'git',
+        [
+          '--no-pager',
+          '-c',
+          `core.attributesFile=${os.devNull}`,
+          'diff',
+          '--no-index',
+          '--no-ext-diff',
+          '--no-textconv',
+          '--no-color',
+          '--text',
+          '--unified=3',
+          '--',
+          'before',
+          'after',
+        ],
+        { cwd: directory, env, timeout: 3000, maxBuffer: 256 * 1024 },
+      ));
+    } catch (error) {
+      if (error.code === 1 && typeof error.stdout === 'string') diff = error.stdout;
+      else
+        throw new Error(
+          'Comparison unavailable. Git must be installed; comparisons are limited to 3 seconds and 256 KiB of output. Reading and feedback remain available.',
+        );
+    }
+    return { ...change, diff };
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}

package/src/config.js

@@ -0,0 +1,44 @@
+import os from 'node:os';
+import path from 'node:path';
+import { readFileLimited } from './files.js';
+
+export const defaults = Object.freeze({ defaultView: 'rendered', openBrowser: true });
+function configPath(env = process.env) {
+  return (
+    env.SPECTATER_CONFIG ||
+    path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'spectater', 'config.json')
+  );
+}
+
+export async function loadConfig(explicit, env = process.env) {
+  const file = explicit || configPath(env);
+  let text;
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(await readFileLimited(file, 16384));
+  } catch (error) {
+    if (error.code === 'ENOENT' && !explicit && !env.SPECTATER_CONFIG) return { ...defaults };
+    throw new Error(`Cannot read SpecTater config: ${error.message}`);
+  }
+  try {
+    const config = JSON.parse(text);
+    if (!config || typeof config !== 'object' || Array.isArray(config))
+      throw new Error('Expected an object.');
+    for (const key of Object.keys(config))
+      if (!['defaultView', 'openBrowser', 'stateDirectory'].includes(key))
+        throw new Error(`Unknown setting: ${key}`);
+    if (config.defaultView !== undefined && !['rendered', 'source'].includes(config.defaultView))
+      throw new Error('defaultView must be rendered or source.');
+    if (config.openBrowser !== undefined && typeof config.openBrowser !== 'boolean')
+      throw new Error('openBrowser must be true or false.');
+    if (
+      config.stateDirectory !== undefined &&
+      (typeof config.stateDirectory !== 'string' || !path.isAbsolute(config.stateDirectory))
+    )
+      throw new Error('stateDirectory must be an absolute path.');
+    return { ...defaults, ...config };
+  } catch (error) {
+    throw new Error(
+      `Invalid SpecTater config: ${error.message} Fix it or remove the optional file to use defaults.`,
+    );
+  }
+}

package/src/discovery.js

@@ -0,0 +1,158 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { readLimited } from './files.js';
+
+export const hash = (value) => createHash('sha256').update(value).digest('hex');
+export function within(root, file) {
+  const relative = path.relative(root, file);
+  return (
+    relative !== '' &&
+    !relative.startsWith(`..${path.sep}`) &&
+    relative !== '..' &&
+    !path.isAbsolute(relative)
+  );
+}
+
+export async function native(args, cwd) {
+  try {
+    const { stdout } = await promisify(execFile)('openspec', args, {
+      cwd,
+      timeout: 15000,
+      maxBuffer: 4 * 1024 * 1024,
+      env: { ...process.env, OPENSPEC_TELEMETRY: '0' },
+    });
+    return stdout;
+  } catch (error) {
+    throw new Error(
+      `OpenSpec failed: ${error.stderr?.trim() || error.stdout?.trim() || error.message}`,
+    );
+  }
+}
+
+export function createDiscovery() {
+  let version;
+  return (options) =>
+    discover(options, async (args, cwd) => {
+      if (args[0] !== '--version') return native(args, cwd);
+      version ??= await native(args, cwd);
+      return version;
+    });
+}
+
+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);
+  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 {
+      return JSON.parse(await run([...args, ...selector, '--json'], cwd));
+    } catch (error) {
+      throw new Error(`OpenSpec JSON/discovery error: ${error.message}`);
+    }
+  };
+  const context = await json(['context']);
+  if (
+    !context.root?.path ||
+    !['nearest', 'declared', 'store', 'global_default'].includes(context.root.source)
+  )
+    throw new Error('Unsupported OpenSpec root contract.');
+  if (context.root.source === 'global_default' && !store)
+    throw new Error('Global default refused. Select an explicit --store id.');
+  const root = await realpath(context.root.path);
+  const list = await json(['list']);
+  if (!Array.isArray(list.changes) || !list.changes.some((item) => item.name === change))
+    throw new Error(`Change not found: ${change}`);
+  const status = await json(['status', '--change', change]);
+  if (
+    status.changeName !== change ||
+    typeof status.schemaName !== 'string' ||
+    !Array.isArray(status.artifacts) ||
+    !status.artifactPaths ||
+    !status.changeRoot ||
+    !status.root?.path
+  )
+    throw new Error('Unsupported OpenSpec status contract.');
+  if (
+    (await realpath(status.root.path)) !== root ||
+    !list.root?.path ||
+    (await realpath(list.root.path)) !== root
+  )
+    throw new Error('OpenSpec root changed during discovery.');
+  const changeRoot = await realpath(status.changeRoot);
+  if (!within(root, changeRoot)) throw new Error('Change escapes the selected OpenSpec root.');
+  const documents = [];
+  for (const artifact of status.artifacts) {
+    const outputs = status.artifactPaths[artifact.id]?.existingOutputPaths;
+    if (
+      typeof artifact.id !== 'string' ||
+      typeof artifact.status !== 'string' ||
+      !Array.isArray(outputs)
+    )
+      throw new Error('Unsupported OpenSpec artifact contract.');
+    for (const file of outputs) {
+      if (typeof file !== 'string' || !path.isAbsolute(file) || !within(changeRoot, file))
+        throw new Error('Artifact escapes the selected change.');
+      const canonical = await realpath(file);
+      if (!within(changeRoot, canonical))
+        throw new Error('Artifact symlink escapes the selected change.');
+      const relative = path.relative(changeRoot, file).split(path.sep).join('/');
+      if (!documents.some((item) => item.path === relative))
+        documents.push({
+          id: hash(relative).slice(0, 24),
+          path: relative,
+          file,
+          canonical,
+          supported: /\.md$/i.test(file),
+          artifact: artifact.id,
+        });
+    }
+  }
+  if (documents.length > 128) throw new Error('Review exceeds 128 artifacts.');
+  return {
+    root,
+    changeRoot,
+    change,
+    schemaName: status.schemaName,
+    source: context.root.source,
+    reviewId: hash(JSON.stringify([root, changeRoot])),
+    artifacts: status.artifacts,
+    documents,
+  };
+}
+
+export async function readDocument(review, document) {
+  if (
+    (await realpath(review.root)) !== review.root ||
+    (await realpath(review.changeRoot)) !== review.changeRoot
+  )
+    throw new Error('Planning identity changed. Reopen explicitly.');
+  const canonical = await realpath(document.file);
+  if (canonical !== document.canonical || !within(review.changeRoot, canonical))
+    throw new Error('Document identity changed or escaped the change.');
+  if (!(await lstat(canonical)).isFile()) throw new Error('Artifact is not a regular file.');
+  const handle = await open(
+    canonical,
+    constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+  );
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size > 1024 * 1024)
+      throw new Error('Artifact must be a regular file smaller than 1 MiB.');
+    const bytes = await readLimited(handle, 1024 * 1024);
+    if (bytes.length > 1024 * 1024 || (await realpath(document.file)) !== canonical)
+      throw new Error('Document changed during read.');
+    const source = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    return { path: document.path, hash: hash(bytes), source };
+  } finally {
+    await handle.close();
+  }
+}

package/src/files.js

@@ -0,0 +1,25 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+
+export async function readLimited(handle, limit) {
+  const chunks = [];
+  let length = 0;
+  while (true) {
+    const chunk = Buffer.allocUnsafe(Math.min(65536, limit + 1 - length));
+    const { bytesRead } = await handle.read(chunk);
+    if (!bytesRead) return Buffer.concat(chunks, length);
+    length += bytesRead;
+    if (length > limit) throw new Error(`File exceeds ${limit} bytes.`);
+    chunks.push(chunk.subarray(0, bytesRead));
+  }
+}
+
+export async function readFileLimited(file, limit) {
+  const handle = await open(file, constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    if (!(await handle.stat()).isFile()) throw new Error('Expected a regular file.');
+    return await readLimited(handle, limit);
+  } finally {
+    await handle.close();
+  }
+}

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;
+}