graphlin 0.1.3 → 0.2.1

package/scripts/build-packages.mjs

@@ -7,6 +7,7 @@ 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'];
+const PROTECTED_DIRECTORIES = [...SOURCE_DIRECTORIES, 'docs', 'node_modules'];
 
 async function assertDestination(destination, { directory = false } = {}) {
   const absolute = path.resolve(destination), root = path.parse(absolute).root;
@@ -57,7 +58,7 @@ async function copy(source, destination) {
 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}`))) {
+  if (PROTECTED_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.
@@ -92,6 +93,9 @@ export async function buildPackages({ outputDir = path.join(SOURCE, 'dist'), sou
     await mkdir(temporary);
     try {
       const profileFiles = files.filter(file => profile === 'claude' || file !== '.claude-plugin/plugin.json');
+      // publicPackageFiles includes every reviewed file of the full pinned
+      // parser under Graphlin's own node_modules. Never resolve a hoisted or
+      // inspected-project dependency, and never copy an arbitrary dependency tree.
       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)));
@@ -114,7 +118,7 @@ export async function buildPackages({ outputDir = path.join(SOURCE, 'dist'), sou
         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` +
+        `# Graphlin ${profile} package\n\nNode.js 22.14+; macOS/Linux. Self-contained runtime and parser 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');

package/scripts/control.mjs

@@ -39,7 +39,7 @@ async function handle(line) {
     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.3' },
+      serverInfo: { name: 'graphlin', version: '0.2.1' },
       instructions: 'Controls only. Passive host hooks provide observations when separately activated. No drawing calls after each action.' });
   }
   if (message.method === 'ping') return result({});

package/scripts/daemon.mjs

@@ -5,7 +5,8 @@ process.umask(0o077);
 let server;
 try {
   const options = parseArguments(process.argv.slice(2), { worker: true });
-  const policy = { transmitSource: options.allowSource, persistEvidence: options.persistEvidence,
+  const policy = { readSource: options.localSource || options.allowSource,
+    transmitSource: options.allowSource, persistEvidence: options.persistEvidence,
     displayEvidence: options.displayEvidence };
   let decisionService;
   if (options.mode === 'demo') {

package/scripts/extensions.mjs

@@ -0,0 +1,44 @@
+import path from 'node:path';
+import { projectPaths, defaultDataDir } from '../runtime/daemon/paths.mjs';
+import { createExtensionRegistry, extensionError } from '../runtime/extensions/index.mjs';
+
+/** Parent CLI dispatches its already-parsed extension arguments here. This
+ * module neither parses global CLI options nor starts/stops the daemon. */
+export async function runExtensions(args, {
+  projectRoot, dataDir = defaultDataDir(), signal, transport, output = process.stdout,
+  registry: suppliedRegistry,
+} = {}) {
+  if (!Array.isArray(args) || args.some(value => typeof value !== 'string')) throw extensionError('invalid_extension_arguments');
+  const [command = 'list', source, ...rest] = args;
+  if (!['list', 'add', 'update', 'remove', 'doctor', 'dev'].includes(command) || rest.length ||
+    (['add', 'update', 'remove', 'dev'].includes(command) ? !source : source !== undefined)) {
+    throw extensionError('usage_extensions_list_add_update_remove_doctor_dev');
+  }
+  let registry = suppliedRegistry;
+  if (!registry) {
+    const paths = await projectPaths(projectRoot ?? process.cwd(), dataDir);
+    registry = await createExtensionRegistry({ dataDir: paths.dataDir, projectId: paths.projectId, transport });
+  }
+  const resolveSource = value => value.startsWith('.') || path.isAbsolute(value)
+    ? path.resolve(projectRoot ?? process.cwd(), value) : value;
+  let result;
+  if (command === 'list') result = await registry.list();
+  if (command === 'doctor') result = await registry.doctor();
+  if (command === 'remove') result = await registry.remove(source);
+  if (command === 'add' || command === 'update') result = await registry.install(resolveSource(source), { signal });
+  if (command === 'dev') {
+    if (!(source.startsWith('.') || path.isAbsolute(source))) throw extensionError('development_directory_required');
+    result = await registry.dev(resolveSource(source), { signal });
+  }
+  if (output) {
+    if (Array.isArray(result)) output.write(result.length ? result.map(row =>
+      `${row.id} ${row.version} ${row.digest.slice(0, 12)}${row.development ? ' development' : ''} ${row.grant ? 'granted' : 'approval required'}`
+    ).join('\n') + '\n' : 'No visualizer extensions installed.\n');
+    else if (command === 'doctor') output.write(`${result.ok ? 'Extension checks passed.' : 'Extension checks failed.'}\n${
+      result.results.map(row => `${row.id ?? 'catalogue'}: ${row.code}`).join('\n')}${result.results.length ? '\n' : ''}`);
+    else output.write(command === 'remove' ? `Removed ${result.id} and its grants.\n` :
+      `Installed ${result.id} ${result.version}${result.development ? ' (development snapshot)' : ''}. ${
+        result.grant ? 'Existing digest approval retained.' : 'Project approval is required before data delivery.'}\n`);
+  }
+  return result;
+}

package/scripts/graphlin.mjs

@@ -4,11 +4,12 @@ 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';
+import { runExtensions } from './extensions.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]
+  init [--host claude|codex|both] [--allow-source|--local-source|--no-source] [--replace-key]
+  start --project PATH [--allow-source|--local-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
@@ -17,10 +18,16 @@ const HELP = `Graphlin — local architecture and activity viewer (Node.js 22.14
   demo [--data-dir PATH] [--background]
   export --project PATH
   logs --project PATH [--file PATH]
+  extensions list                    List installed visualizers and approvals
+  extensions add PACKAGE@VERSION     Install without running package scripts
+  extensions dev ./DIRECTORY         Install a local development snapshot
+  extensions update PACKAGE@VERSION  Replace an installed visualizer
+  extensions remove ID
+  extensions doctor
 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.
+--host and one source mode; remote 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.
@@ -31,6 +38,10 @@ 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.
+--local-source parses supported source on this machine, without remote decisions.
+Metadata mode inventories paths without opening source files. Visualizers require
+project approval in the viewer before receiving data; custom renderers run in a
+sandboxed frame. Install or mount does not run decision profiles.
 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.
@@ -47,6 +58,15 @@ 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 if (args[0] === 'extensions') {
+    const globalArgs = [], extensionArgs = [];
+    for (let index = 1; index < args.length; index++) {
+      if (['--project', '--data-dir'].includes(args[index])) globalArgs.push(args[index], args[++index]);
+      else extensionArgs.push(args[index]);
+    }
+    const { projectRoot, dataDir } = parseArguments(['status', ...globalArgs]);
+    await runExtensions(extensionArgs, { projectRoot, dataDir });
+  }
   else {
     const options = parseArguments(args);
     const print = result => process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/scripts/onboarding.mjs

@@ -313,13 +313,19 @@ export async function initOnboarding(options, dependencies = {}) {
   write(`Project: ${JSON.stringify(paths.projectRoot)}\n`);
   if (upgrading) write('Updating every recorded Graphlin host to keep the installed version consistent.\n');
   let allowSource = options.allowSource ?? (resuming ? saved.policy?.allowSource : undefined);
+  let localSource = options.localSource === true ||
+    (resuming && options.allowSource === undefined && saved.policy?.localSource === true);
   if (allowSource === undefined) {
-    write('Source mode sends locally filtered source excerpts, user prompts, and public agent messages to TypeSafe. Metadata mode sends none of these and needs no key.\n');
-    allowSource = await choose('For this project, choose source or metadata: ', ['source', 'metadata'], prompt) === 'source';
+    write('Source mode sends locally filtered source excerpts and public messages to the decision provider (Jev by default). Local mode parses code on this machine without sending it. Metadata mode reads no source content. Local and metadata need no key.\n');
+    const mode = await choose('For this project, choose source, local, or metadata: ', ['source', 'local', 'metadata'], prompt);
+    allowSource = mode === 'source';
+    localSource = mode === 'local';
   }
   const policy = { ...defaults, ...saved.policy, allowSource,
     persistEvidence: options.persistEvidence ?? saved.policy?.persistEvidence ?? false,
     displayEvidence: options.displayEvidence ?? saved.policy?.displayEvidence ?? true };
+  if (localSource && !allowSource) policy.localSource = true;
+  else delete policy.localSource;
   // Explicit setup plus source consent authorizes saving the supplied key so
   // later launches do not depend on this terminal's environment.
   let apiKey = allowSource && env.TYPESAFE_API_KEY ? env.TYPESAFE_API_KEY : undefined;
@@ -399,7 +405,8 @@ export async function uninstallOnboarding(options, dependencies = {}) {
     await record();
     write(`Graphlin removed from ${host}.\n`);
   }
-  await saveSettings(paths, { policy: { ...defaults, ...saved.policy, allowSource: false, persistEvidence: false } });
+  await saveSettings(paths, { policy: { ...defaults, ...saved.policy, allowSource: false,
+    ...(saved.policy?.localSource ? { localSource: false } : {}), persistEvidence: false } });
   write('Source and evidence-persistence consent reset for this project. A running viewer keeps its current policy until stopped; use graphlin stop.\n');
   return { removed, ...(cancelledPending.length ? { cancelledPending } : {}), retainedData: true };
 }

package/scripts/validate-packages.mjs

@@ -4,6 +4,51 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import assert from 'node:assert/strict';
 
+const PARSER_NAME = '@vscode/tree-sitter-wasm';
+const PARSER_VERSION = '0.3.1';
+// The complete published 0.3.1 package, not a pruned grammar subset. Keep this
+// explicit: arbitrary new files under node_modules must never enter a release.
+const PARSER_FILES = [
+  'LICENSE', 'README.md', 'SECURITY.md', 'cgmanifest.json', 'package.json',
+  'wasm/tree-sitter.js', 'wasm/tree-sitter.wasm', 'wasm/web-tree-sitter.d.ts',
+  ...['bash', 'c-sharp', 'cpp', 'css', 'go', 'ini', 'java', 'javascript', 'php',
+    'powershell', 'python', 'regex', 'ruby', 'rust', 'tsx', 'typescript']
+    .map(language => `wasm/tree-sitter-${language}.wasm`),
+];
+const SDK_EXPORTS = {
+  './extensions/sdk': {
+    types: './runtime/extensions/sdk.d.ts',
+    import: './runtime/extensions/sdk.mjs',
+    default: './runtime/extensions/sdk.mjs',
+  },
+  './extensions/scene': './runtime/extensions/scene.mjs',
+};
+
+async function assertRegularFile(root, file) {
+  let current = root;
+  for (const component of file.split('/')) {
+    current = path.join(current, component);
+    assert.equal((await lstat(current)).isSymbolicLink(), false, 'package_symlink_rejected');
+  }
+  assert.ok((await lstat(current)).isFile(), 'package_file_must_be_regular');
+}
+
+export async function bundledPackageFiles(root, metadata) {
+  metadata ??= JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+  assert.deepEqual(metadata.bundledDependencies, [PARSER_NAME], 'parser_bundle_required');
+  assert.equal(metadata.dependencies?.[PARSER_NAME], PARSER_VERSION, 'parser_dependency_must_be_pinned');
+  const base = `node_modules/${PARSER_NAME}`;
+  await assertRegularFile(root, `${base}/package.json`);
+  const parser = JSON.parse(await readFile(path.join(root, base, 'package.json'), 'utf8'));
+  assert.equal(parser.name, PARSER_NAME, 'unexpected_parser_package');
+  assert.equal(parser.version, PARSER_VERSION, 'unexpected_parser_version');
+  assert.equal(parser.license, 'MIT', 'unexpected_parser_license');
+  assert.deepEqual(Object.keys(parser.dependencies ?? {}), [], 'unexpected_parser_dependencies');
+  const files = PARSER_FILES.map(file => `${base}/${file}`);
+  for (const file of files) await assertRegularFile(root, file);
+  return files;
+}
+
 // Dependency-free checks for this package's deliberately small manifest profile.
 // This is not a replacement for a host's schema validation or activation/trust.
 export async function publicPackageFiles(root) {
@@ -22,21 +67,22 @@ export async function publicPackageFiles(root) {
     assert.ok(typeof file === 'string' && file.length > 0 && !file.includes('\\') &&
       !path.posix.isAbsolute(file) && !/[*?[\]{}!\u0000-\u001f]/.test(file) &&
       file.split('/').every(part => part && part !== '.' && part !== '..'), 'invalid_package_file');
-    assert.ok(/^(?:package\.json|LICENSE|README\.md|plugin\.json|mcp\.json|\.mcp\.json|\.claude-plugin\/plugin\.json|\.codex-plugin\/plugin\.json|adapters\/(?:README\.md|(?:claude|codex|kiro)\/(?:hooks|profile)\.json)|skills\/graphlin\/SKILL\.md|runtime\/(?:[a-z0-9-]+\/)*[a-z0-9-]+\.(?:mjs|js|css|html)|schemas\/[a-z0-9-]+\.schema\.json|scripts\/(?:arguments|build-packages|collector|control|daemon|graphlin|onboarding|validate-packages)\.mjs|scripts\/collect\.sh)$/.test(file),
+    assert.ok(/^(?:package\.json|LICENSE|README\.md|plugin\.json|mcp\.json|\.mcp\.json|\.claude-plugin\/plugin\.json|\.codex-plugin\/plugin\.json|adapters\/(?:README\.md|(?:claude|codex|kiro)\/(?:hooks|profile)\.json)|skills\/graphlin\/SKILL\.md|runtime\/(?:[a-z0-9-]+\/)*[a-z0-9-]+\.(?:mjs|js|css|html|d\.ts)|docs\/(?:decision-service|extension-authoring|model-api|visualizer-views|usage)\.md|schemas\/[a-z0-9-]+\.schema\.json|scripts\/(?:arguments|build-packages|collector|control|daemon|extensions|graphlin|onboarding|validate-packages)\.mjs|scripts\/collect\.sh)$/.test(file),
     'unexpected_public_package_file');
-    let current = root;
-    for (const component of file.split('/')) {
-      current = path.join(current, component);
-      assert.equal((await lstat(current)).isSymbolicLink(), false, 'package_symlink_rejected');
-    }
-    assert.ok((await lstat(current)).isFile(), 'package_file_must_be_regular');
+    await assertRegularFile(root, file);
   }
-  return files;
+  return [...files, ...await bundledPackageFiles(root, metadata)];
 }
 
 export async function validatePackage(root) {
   const json = async name => JSON.parse(await readFile(path.join(root, name), 'utf8'));
   const metadata = await json('package.json');
+  await bundledPackageFiles(root, metadata);
+  assert.deepEqual(metadata.exports, SDK_EXPORTS, 'invalid_sdk_exports');
+  for (const file of ['runtime/extensions/sdk.mjs', 'runtime/extensions/sdk.d.ts', 'runtime/extensions/scene.mjs']) {
+    assert.ok(metadata.files.includes(`./${file}`), 'sdk_export_must_be_packaged');
+    await assertRegularFile(root, file);
+  }
   const manifest = await json('plugin.json'), portable = await json('mcp.json');
   assert.equal(manifest.$schema, 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json');
   assert.equal(manifest.name, 'graphlin');