graphlin 0.1.0

package/scripts/build-packages.mjs

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+import { cp, mkdir, readFile, readdir, lstat, writeFile, rm, rename, chmod } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { publicPackageFiles, validatePackage } from './validate-packages.mjs';
+
+const SOURCE = fileURLToPath(new URL('../', import.meta.url));
+const SOURCE_DIRECTORIES = ['.claude-plugin', '.codex-plugin', 'skills', 'scripts', 'runtime', 'schemas', 'adapters'];
+
+async function assertDestination(destination, { directory = false } = {}) {
+  const absolute = path.resolve(destination), root = path.parse(absolute).root;
+  const components = absolute.slice(root.length).split(path.sep).filter(Boolean);
+  let current = root;
+  for (let i = 0; i < components.length; i++) {
+    current = path.join(current, components[i]);
+    let info;
+    try { info = await lstat(current); }
+    catch (error) { if (error.code === 'ENOENT') return; throw error; }
+    if (info.isSymbolicLink()) throw new Error('package_destination_symlink_rejected');
+    if ((i < components.length - 1 || directory) && !info.isDirectory()) {
+      throw new Error('invalid_package_destination');
+    }
+  }
+}
+async function destinationDirectory(directory) {
+  await assertDestination(directory, { directory: true });
+  await mkdir(directory, { recursive: true });
+  await assertDestination(directory, { directory: true });
+}
+async function publishFile(filename, contents) {
+  await assertDestination(filename);
+  const temporary = path.join(path.dirname(filename), `.${path.basename(filename)}-${randomUUID()}.tmp`);
+  try {
+    // The exclusive temporary write cannot truncate a linked destination.
+    // Rename replaces a directory entry and never follows the final symlink.
+    await writeFile(temporary, contents, { flag: 'wx', mode: 0o644 });
+    await assertDestination(filename);
+    await rename(temporary, filename);
+  } finally { await rm(temporary, { force: true }); }
+}
+
+async function assertSourceTree(directory) {
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const name = path.join(directory, entry.name);
+    if (entry.isSymbolicLink()) throw new Error('package_symlink_rejected');
+    if (entry.isDirectory()) await assertSourceTree(name);
+  }
+}
+async function copy(source, destination) {
+  const info = await lstat(source);
+  if (info.isSymbolicLink()) throw new Error('package_symlink_rejected');
+  if (info.isDirectory()) await assertSourceTree(source);
+  await mkdir(path.dirname(destination), { recursive: true });
+  await cp(source, destination, { recursive: true, dereference: false });
+}
+export async function buildPackages({ outputDir = path.join(SOURCE, 'dist'), sourceDir = SOURCE } = {}) {
+  const source = path.resolve(sourceDir), output = path.resolve(outputDir);
+  if (output === source || source.startsWith(`${output}${path.sep}`)) throw new Error('unsafe_output_directory');
+  if (SOURCE_DIRECTORIES.some(file => output === path.join(source, file) || output.startsWith(`${path.join(source, file)}${path.sep}`))) {
+    throw new Error('unsafe_output_directory');
+  }
+  // Preflight every output before replacing even the first generated profile.
+  // Parent links are rejected too, including links above outputDir.
+  await assertDestination(output, { directory: true });
+  for (const profile of ['portable', 'claude', 'codex']) {
+    const target = path.join(output, profile, 'graphlin');
+    await assertDestination(target, { directory: true });
+    await assertDestination(path.join(target, '.graphlin-package'));
+  }
+  const kiro = path.join(output, 'kiro');
+  await assertDestination(kiro, { directory: true });
+  await assertDestination(path.join(kiro, 'profile.json'));
+  await assertDestination(path.join(kiro, 'README.md'));
+  const marketplaceDirectory = path.join(output, 'codex', '.agents', 'plugins');
+  const marketplaceFile = path.join(marketplaceDirectory, 'marketplace.json');
+  await assertDestination(marketplaceDirectory, { directory: true });
+  await assertDestination(marketplaceFile);
+  const files = await publicPackageFiles(source);
+  for (const directory of SOURCE_DIRECTORIES) {
+    const filename = path.join(source, directory), info = await lstat(filename);
+    if (info.isSymbolicLink()) throw new Error('package_symlink_rejected');
+    await assertSourceTree(filename);
+  }
+  await validatePackage(source);
+  await destinationDirectory(output);
+  const built = [];
+  for (const profile of ['portable', 'claude', 'codex']) {
+    const parent = path.join(output, profile), target = path.join(parent, 'graphlin');
+    await destinationDirectory(parent);
+    const temporary = path.join(parent, `.graphlin-${randomUUID()}`);
+    await mkdir(temporary);
+    try {
+      const profileFiles = files.filter(file => profile === 'claude' || file !== '.claude-plugin/plugin.json');
+      for (const file of profileFiles) await copy(path.join(source, file), path.join(temporary, file));
+      const metadata = JSON.parse(await readFile(path.join(temporary, 'package.json'), 'utf8'));
+      metadata.files = metadata.files.filter(file => profileFiles.includes(file.slice(2)));
+      // Generated plugins are runnable distributions. Checkout-only testing,
+      // evaluation, packaging, and release commands would point to absent files.
+      metadata.scripts = Object.fromEntries(['start', 'demo', 'doctor', 'validate', 'prepack']
+        .filter(name => metadata.scripts[name]).map(name => [name, metadata.scripts[name]]));
+      await writeFile(path.join(temporary, 'package.json'), `${JSON.stringify(metadata, null, 2)}\n`);
+      if (profile === 'codex') {
+        await writeFile(path.join(temporary, '.mcp.json'), `${JSON.stringify({
+          mcpServers: { graphlin: { type: 'stdio', command: 'node', args: ['${PLUGIN_ROOT}/scripts/control.mjs'] } },
+        }, null, 2)}\n`);
+      }
+      if (profile === 'portable') {
+        const manifest = JSON.parse(await readFile(path.join(temporary, 'plugin.json'), 'utf8'));
+        delete manifest.extensions;
+        await writeFile(path.join(temporary, 'plugin.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+      }
+      for (const file of ['collect.sh', 'graphlin.mjs', 'control.mjs']) {
+        await chmod(path.join(temporary, 'scripts', file), 0o755);
+      }
+      await writeFile(path.join(temporary, 'PACKAGE-NOTES.md'),
+        `# Graphlin ${profile} package\n\nNode.js 22.14+; macOS/Linux. Self-contained source bundle; no dependency install.\n` +
+        'Run scripts/graphlin.mjs --help for local controls. This package does not install itself.\n' +
+        'Hook activation/trust has not been certified. Kiro is inactive and experimental.\n' +
+        'See adapters/README.md and skills/graphlin/SKILL.md for privacy and coverage.\n');
+      await validatePackage(temporary);
+      await assertDestination(target, { directory: true });
+      await assertDestination(path.join(target, '.graphlin-package'));
+      const exists = await lstat(target).catch(() => null);
+      if (exists) {
+        if (exists.isSymbolicLink() || (await readFile(path.join(target, '.graphlin-package'), 'utf8').catch(() => '')) !== profile) {
+          throw new Error('unmanaged_output_directory');
+        }
+        await rm(target, { recursive: true, force: true });
+      }
+      await writeFile(path.join(temporary, '.graphlin-package'), profile);
+      await assertDestination(target, { directory: true });
+      await rename(temporary, target);
+      built.push({ profile, directory: target });
+    } finally { await rm(temporary, { recursive: true, force: true }); }
+  }
+  await destinationDirectory(kiro);
+  await publishFile(path.join(kiro, 'profile.json'), await readFile(path.join(source, 'adapters/kiro/profile.json')));
+  await publishFile(path.join(kiro, 'README.md'), '# Kiro: inactive experimental profile\n\nNo active hooks or installable plugin are generated. See profile.json.\n');
+  await destinationDirectory(marketplaceDirectory);
+  await publishFile(marketplaceFile, `${JSON.stringify({
+    name: 'graphlin-local',
+    interface: { displayName: 'Graphlin local' },
+    plugins: [{
+      name: 'graphlin',
+      source: { source: 'local', path: './graphlin' },
+      policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' },
+      category: 'Productivity',
+    }],
+  }, null, 2)}\n`);
+  return built;
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const args = process.argv.slice(2);
+    if (args.length && (args.length !== 2 || !['--out', '--output'].includes(args[0]))) throw new Error('invalid_arguments');
+    const result = await buildPackages(args.length ? { outputDir: args[1] } : {});
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } catch { process.stderr.write('Graphlin package generation failed.\n'); process.exitCode = 1; }
+}

package/scripts/collect.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+# Keep import/runtime/launcher errors out of the host conversation as well.
+exec 2>/dev/null
+base=$(CDPATH= cd -- "$(dirname -- "$0")" 2>/dev/null && pwd) || exit 0
+entry="$base/collector.mjs"
+[ -r "$entry" ] || exit 0
+runtime=${GRAPHLIN_NODE:-node}
+command -v "$runtime" >/dev/null 2>&1 || exit 0
+exec 3<&0
+"$runtime" "$entry" "${1:-claude}" <&3 >/dev/null 2>&1 &
+collector_pid=$!
+# The watchdog also bounds a broken executable before the JS deadline starts.
+(
+  sleep 1
+  kill -TERM "$collector_pid" 2>/dev/null || exit 0
+  sleep 0.2
+  kill -KILL "$collector_pid" 2>/dev/null
+) >/dev/null 2>&1 &
+watchdog_pid=$!
+wait "$collector_pid" 2>/dev/null
+kill -KILL "$watchdog_pid" 2>/dev/null
+wait "$watchdog_pid" 2>/dev/null
+exit 0

package/scripts/collector.mjs

@@ -0,0 +1,11 @@
+// This entry point has no output, no persistence, no daemon startup, and no
+// remote transport. An outer guarded launcher also covers import/runtime errors.
+import { collect, readHook } from '../runtime/collector/index.mjs';
+const deadline = setTimeout(() => process.exit(0), 350);
+try {
+  if (Number(process.versions.node.split('.')[0]) >= 22) {
+    const payload = await readHook();
+    if (payload) await collect(payload, { host: process.argv[2] || 'claude' });
+  }
+} catch { /* Passive hooks always fail open. */ }
+finally { clearTimeout(deadline); process.exit(0); }

package/scripts/control.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { startDaemon, stopDaemon, daemonStatus, doctor, publicError } from '../runtime/daemon/manager.mjs';
+
+const METHODS = { start: input => startDaemon({ ...input, background: true }),
+  stop: stopDaemon, status: daemonStatus, doctor };
+const SCHEMA = { type: 'object', properties: { projectRoot: { type: 'string', minLength: 1, maxLength: 4096 } },
+  required: ['projectRoot'], additionalProperties: false };
+const TOOLS = Object.keys(METHODS).map(name => ({
+  name,
+  description: {
+    start: 'Start or reopen Graphlin for an explicit project and return a one-use viewer URL. Reuses saved project consent and credentials; metadata only without consent. Omit policy fields to reuse the current policy. MCP launch runs in the background; use the CLI for foreground operation.',
+    stop: 'Stop the Graphlin daemon for this canonical project.',
+    status: 'Get safe daemon status; does not activate hooks or call a remote service.',
+    doctor: 'Check local configuration, credential presence, host versions, daemon health, and observed hook delivery. Returns next steps; never sends a remote request or exposes a key.',
+  }[name],
+  inputSchema: name === 'start' ? { ...SCHEMA, properties: { ...SCHEMA.properties,
+    allowSource: { type: 'boolean' }, persistEvidence: { type: 'boolean' },
+    displayEvidence: { type: 'boolean' } } } : SCHEMA,
+  annotations: { readOnlyHint: name === 'status' || name === 'doctor',
+    destructiveHint: false, openWorldHint: name === 'start' },
+}));
+let initialized = false;
+const send = message => new Promise((resolve, reject) => {
+  process.stdout.write(`${JSON.stringify(message)}\n`, error => error ? reject(error) : resolve());
+});
+const error = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
+async function handle(line) {
+  let message;
+  try { message = JSON.parse(line); } catch { await error(null, -32700, 'Parse error'); return; }
+  if (!message || message.jsonrpc !== '2.0' || typeof message.method !== 'string' ||
+      (message.id !== undefined && typeof message.id !== 'string' && typeof message.id !== 'number')) {
+    await error(null, -32600, 'Invalid request'); return;
+  }
+  if (message.id === undefined) return; // All notifications are deliberately silent.
+  const result = value => send({ jsonrpc: '2.0', id: message.id, result: value });
+  if (message.method === 'initialize') {
+    if (initialized) return error(message.id, -32600, 'Already initialized');
+    initialized = true;
+    const supported = ['2024-11-05', '2025-03-26', '2025-06-18'];
+    return result({ protocolVersion: supported.includes(message.params?.protocolVersion) ? message.params.protocolVersion : '2025-06-18',
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: 'graphlin', version: '0.1.0' },
+      instructions: 'Controls only. Passive host hooks provide observations when separately activated. No drawing calls after each action.' });
+  }
+  if (message.method === 'ping') return result({});
+  if (!initialized) return error(message.id, -32002, 'Initialize first');
+  if (message.method === 'tools/list') return result({ tools: TOOLS });
+  if (message.method !== 'tools/call') return error(message.id, -32601, 'Method not found');
+  const name = message.params?.name, input = message.params?.arguments;
+  if (!Object.hasOwn(METHODS, name ?? '') || !input || Array.isArray(input) || typeof input !== 'object') {
+    return error(message.id, -32602, 'Invalid tool arguments');
+  }
+  const allowed = new Set(name === 'start' ? ['projectRoot', 'allowSource', 'persistEvidence', 'displayEvidence'] : ['projectRoot']);
+  if (typeof input.projectRoot !== 'string' || !input.projectRoot || input.projectRoot.length > 4096 ||
+      Object.keys(input).some(key => !allowed.has(key)) ||
+      Object.entries(input).some(([key, value]) => key !== 'projectRoot' && typeof value !== 'boolean')) {
+    return error(message.id, -32602, 'Invalid tool arguments');
+  }
+  try {
+    const value = await METHODS[name](input);
+    await result({ content: [{ type: 'text', text: JSON.stringify(value) }], isError: false });
+  } catch (failure) {
+    await result({ content: [{ type: 'text', text: JSON.stringify({ error: publicError(failure) }) }], isError: true });
+  }
+}
+let buffer = '', discarding = false;
+process.stdin.setEncoding('utf8');
+for await (const chunk of process.stdin) {
+  buffer += chunk.toString('utf8');
+  let newline;
+  while ((newline = buffer.indexOf('\n')) !== -1) {
+    const line = buffer.slice(0, newline); buffer = buffer.slice(newline + 1);
+    if (discarding) { discarding = false; continue; }
+    if (Buffer.byteLength(line) > 64 * 1024) await error(null, -32600, 'Request too large');
+    else if (line.trim()) await handle(line).catch(() => error(null, -32603, 'Internal error'));
+  }
+  if (Buffer.byteLength(buffer) > 64 * 1024) {
+    buffer = ''; discarding = true; await error(null, -32600, 'Request too large');
+  }
+}

package/scripts/daemon.mjs

@@ -0,0 +1,28 @@
+import { startServer } from '../runtime/daemon/server.mjs';
+import { parseArguments } from './arguments.mjs';
+
+process.umask(0o077);
+let server;
+try {
+  const options = parseArguments(process.argv.slice(2), { worker: true });
+  const policy = { transmitSource: options.allowSource, persistEvidence: options.persistEvidence,
+    displayEvidence: options.displayEvidence };
+  let decisionService;
+  if (options.mode === 'demo') {
+    const { demoDecisionService } = await import('../runtime/daemon/demo.mjs');
+    decisionService = demoDecisionService();
+  }
+  server = await startServer({ ...options, policy, decisionService });
+  for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => {
+    void server.close().then(() => process.exit(0), () => process.exit(1));
+  });
+  if (options.mode === 'demo') {
+    const { replayDemo } = await import('../runtime/daemon/demo.mjs');
+    await replayDemo(server.pipeline, options.projectRoot);
+  }
+  const stopped = await server.whenClosed;
+  if (!stopped.ok) process.exitCode = 1;
+} catch {
+  await server?.close().catch(() => {});
+  process.exitCode = 1;
+}

package/scripts/graphlin.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { startDaemon, runForeground, stopDaemon, daemonStatus, doctor, exportDaemon, diagnosticLogs, publicError } from '../runtime/daemon/manager.mjs';
+import { parseArguments } from './arguments.mjs';
+import { initOnboarding, uninstallOnboarding, needsOnboarding, openViewer, agentInstructions } from './onboarding.mjs';
+import { readSettings } from '../runtime/daemon/settings.mjs';
+import { projectPaths } from '../runtime/daemon/paths.mjs';
+
+const HELP = `Graphlin — local architecture and activity viewer (Node.js 22.14+, macOS/Linux).
+  graphlin                           Guided setup if needed, then foreground start
+  init [--host claude|codex|both] [--allow-source|--no-source] [--replace-key]
+  start --project PATH [--allow-source|--no-source] [--persist-evidence] [--no-display-evidence] [--background] [--no-open]
+  open --project PATH                Open/reopen the viewer; start detached if needed
+  uninstall [--host claude|codex|both]
+  stop --project PATH
+  status --project PATH
+  doctor --project PATH
+  demo [--data-dir PATH] [--background]
+  export --project PATH
+  logs --project PATH [--file PATH]
+All commands accept --project PATH and --data-dir PATH (or GRAPHLIN_DATA_DIR).
+init installs for your user account using the host CLIs; it saves project consent
+and offers a masked key prompt only in a terminal. Non-interactive init requires
+--host and --allow-source or --no-source; source also needs a saved/environment key.
+init --replace-key replaces a saved key at the masked prompt; it requires a terminal.
+uninstall removes only Graphlin host plugins for all projects, retaining keys,
+history, packages and marketplace registrations; it resets current project consent.
+Start and demo stay in this terminal by default; Ctrl+C gracefully stops the
+joined instance. --background explicitly detaches. Repeated starts for the same
+canonical project/data directory reuse its port and issue a fresh one-use URL.
+Omitted policy flags reuse current/saved consent. Without consent: metadata only.
+--no-source explicitly opts out; --allow-source permits sanitized source/public
+intent to TypeSafe using TYPESAFE_API_KEY or the privately saved key. Approved evidence
+is displayed by default; excerpts are persisted only with --persist-evidence.
+Credentials, environment files, excluded paths, binary and oversized files are
+filtered locally. Replay history is bounded to 7 days; an expired stopped-daemon
+snapshot is deleted on the next startup. Current snapshots are private and bounded.
+Policy changes require stop/start. Hooks never install themselves. Interactive
+starts open a browser automatically; --no-open suppresses this.
+Demo uses local fixture answers and makes no remote requests.
+Diagnostics retain bounded metadata in a private 300-record/512 KiB ring and two
+1 MiB JSONL files. Source, prompts, and credentials are never logged. Safe paths
+and labels require source permission and their display/persistence settings.
+logs also works stopped, with paths and labels hidden; --file matches retained
+artifact identity, including files since deleted.
+`;
+
+try {
+  const args = process.argv.slice(2);
+  if (args.includes('--help') || args[0] === 'help') process.stdout.write(HELP);
+  else {
+    const options = parseArguments(args);
+    const print = result => process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    let result;
+    if (['start', 'demo', 'open', 'init', 'uninstall'].includes(options.command)) {
+      const controller = new AbortController();
+      const interrupt = () => controller.abort();
+      for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, interrupt);
+      try {
+        if (options.command === 'init') result = await initOnboarding({ ...options, signal: controller.signal });
+        else if (options.command === 'uninstall') result = await uninstallOnboarding({ ...options, signal: controller.signal });
+        else {
+          if (options.guided && await needsOnboarding(options)) {
+            const setup = await initOnboarding({ ...options, signal: controller.signal });
+            Object.assign(options, setup.policy);
+          }
+          if (options.command === 'demo') {
+            const { createDemoProject } = await import('../runtime/daemon/demo.mjs');
+            options.projectRoot = await createDemoProject(options.dataDir);
+            options.mode = 'demo'; options.allowSource = true;
+          }
+          let browser = Promise.resolve();
+          let instructions;
+          if (interactive && options.command !== 'demo') {
+            const paths = await projectPaths(options.projectRoot, options.dataDir);
+            const saved = await readSettings(paths);
+            instructions = agentInstructions({ ...paths, hosts: saved.installation?.hosts?.length ? saved.installation.hosts : undefined });
+          }
+          const ready = value => {
+            print(options.command === 'demo' ? { ...value, projectRoot: options.projectRoot } : value);
+            if (instructions) process.stderr.write(instructions);
+            if (options.openBrowser !== false && (interactive || options.command === 'open')) {
+              browser = openViewer(value.url, { signal: controller.signal }).catch(() => {
+                process.stderr.write('Could not open a browser automatically. Open the printed one-use URL; run graphlin open for a fresh URL if it expires.\n');
+              });
+            }
+          };
+          if (options.background || options.command === 'open') ready(await startDaemon({ ...options, background: true }));
+          else await runForeground({ ...options, signal: controller.signal }, ready);
+          await browser;
+        }
+      } finally {
+        for (const signal of ['SIGINT', 'SIGTERM']) process.removeListener(signal, interrupt);
+      }
+    } else if (options.command === 'stop') result = await stopDaemon(options);
+    else if (options.command === 'status') result = await daemonStatus(options);
+    else if (options.command === 'doctor') result = await doctor(options);
+    else if (options.command === 'export') result = await exportDaemon(options);
+    else if (options.command === 'logs') result = await diagnosticLogs(options);
+    else throw new Error('unknown_command');
+    if (result !== undefined) print(result);
+  }
+} catch (error) {
+  const argumentErrors = new Set(['duplicate_argument', 'invalid_argument', 'invalid_port', 'conflicting_arguments',
+    'unknown_argument', 'invalid_host', 'unknown_command']);
+  const message = error?.onboarding ? error.message : argumentErrors.has(error?.message) ? error.message : publicError(error);
+  const nextStep = message === 'policy_restart_required'
+    ? 'Stop the current viewer with Ctrl+C or graphlin stop, then run Graphlin again to apply the saved settings.'
+    : 'Run with --help for usage.';
+  process.stderr.write(`Graphlin: ${message}. ${nextStep}\n`);
+  process.exitCode = error?.code === 'cancelled' ? 130 : 1;
+}