@opengsd/gsd-core 1.7.0-rc.4 → 1.7.0-rc.6

package/scripts/validate-registry.cjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * scripts/validate-registry.cjs — CLI validator for the third-party
+ * discoverability catalogs (issue #2182):
+ *
+ *   - docs/registries/capabilities.json  ("GSD Community Capability Registry")
+ *   - docs/registries/eos.json           ("GSD EoS Registry", PR2 — optional
+ *     until that JSON file ships)
+ *
+ * Validates each source's JSON array against the closed schema in
+ * scripts/registry-schema.cjs (validateEntries). Human-readable errors go to
+ * stderr; `--json` additionally prints a structured verdict to stdout.
+ *
+ * Usage:
+ *   node scripts/validate-registry.cjs           # human-readable report
+ *   node scripts/validate-registry.cjs --json    # structured JSON verdict
+ *
+ * Exit codes:
+ *   0  every present source's entries are all valid
+ *   1  one or more entries failed validation (or a source's JSON is malformed)
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const { validateEntries } = require('./registry-schema.cjs');
+
+// Resolved relative to process.cwd() (not __dirname) so the CLI validates
+// whichever project it is invoked from — this is what lets tests drive it as
+// a subprocess against isolated temp-fixture directories via `cwd`.
+const SOURCES = [
+  { file: 'capabilities.json', type: 'capability' },
+  { file: 'eos.json', type: 'eos' },
+];
+
+/**
+ * Load + validate a single registry JSON file.
+ *
+ * @param {string} jsonPath  absolute path to the registry JSON file
+ * @param {'capability'|'eos'} type
+ * @returns {{ok: boolean, errors: Array<{index: number, id?: string, field: string, reason: string}>}}
+ */
+function validateFile(jsonPath, type) {
+  let raw;
+  try {
+    raw = fs.readFileSync(jsonPath, 'utf8');
+  } catch (err) {
+    return {
+      ok: false,
+      errors: [{ index: -1, field: '<file>', reason: `could not read ${jsonPath}: ${err.message}` }],
+    };
+  }
+
+  let entries;
+  try {
+    entries = JSON.parse(raw);
+  } catch (err) {
+    return {
+      ok: false,
+      errors: [{ index: -1, field: '<file>', reason: `JSON parse error in ${jsonPath}: ${err.message}` }],
+    };
+  }
+
+  if (!Array.isArray(entries)) {
+    return {
+      ok: false,
+      errors: [{ index: -1, field: '<file>', reason: `${jsonPath} must be a JSON array of entries` }],
+    };
+  }
+
+  return validateEntries(entries, { type });
+}
+
+function main() {
+  const jsonMode = process.argv.includes('--json');
+  const registriesDir = path.join(process.cwd(), 'docs', 'registries');
+
+  const results = [];
+  let anyFailed = false;
+
+  for (const { file, type } of SOURCES) {
+    const jsonPath = path.join(registriesDir, file);
+    // eos.json is optional until PR2 ships it — skip silently when absent.
+    if (type === 'eos' && !fs.existsSync(jsonPath)) continue;
+
+    const verdict = validateFile(jsonPath, type);
+    results.push({ file, type, ok: verdict.ok, errors: verdict.errors });
+    if (!verdict.ok) anyFailed = true;
+  }
+
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify({ ok: !anyFailed, results }, null, 2) + '\n');
+  } else if (anyFailed) {
+    process.stderr.write('\nERROR validate-registry: one or more entries failed validation\n');
+    for (const result of results) {
+      if (result.ok) continue;
+      process.stderr.write(`\n${result.file}:\n`);
+      for (const e of result.errors) {
+        const idPart = e.id ? ` (id: ${e.id})` : '';
+        process.stderr.write(`  entry[${e.index}]${idPart} field "${e.field}": ${e.reason}\n`);
+      }
+    }
+    process.stderr.write('\n');
+  } else {
+    process.stdout.write('ok validate-registry: all entries valid\n');
+  }
+
+  if (anyFailed) throw new ExitError(1, 'registry validation failed');
+  return 0;
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = { main, validateFile, SOURCES };

package/vscode/browser.js

@@ -0,0 +1,197 @@
+'use strict';
+
+/**
+ * GSD extension for VS Code — WEB (browser) entry, #2103.
+ *
+ * This is the `browser` entry point (vscode/package.json `"browser": "./browser.js"`),
+ * loaded by VS Code Web / vscode.dev in a webworker context. It has ZERO Node
+ * APIs: no `require('fs')`, `require('path')`, or `require('child_process')`,
+ * and no Node globals (`process`, `Buffer`, `__dirname`, `__filename`). This is
+ * a HARD constraint, not a style preference — a Web Extension host does not
+ * have Node's core modules available at all; requiring one throws immediately
+ * at load time and breaks activation.
+ *
+ * WHY THIS FILE DOES NOT REQUIRE `./host-binding.js` OR `./extension.js`
+ * (a deliberate deviation from "compose the seams via bindGsdToVscode" — see
+ * the #2103 dispatch-crux note below):
+ *
+ * `host-binding.js`'s `bindGsdToVscode` is NOT actually web-safe once its
+ * transitive dependencies are checked — three of its four required engine-lib
+ * modules pull in Node's `fs`/`os`/`path` at module-load time (eagerly, on
+ * every `require()`, regardless of which code path runs):
+ *   - gsd-core/bin/lib/state-io.cjs           → requires 'node:fs' directly.
+ *   - gsd-core/bin/lib/adapter-imperative.cjs → requires install-engine.cjs +
+ *                                                capability-loader.cjs (fs/os/path).
+ *   - gsd-core/bin/lib/model-adapter.cjs      → requires model-resolver.cjs →
+ *                                                config-loader.cjs (fs/os/path) +
+ *                                                configuration.cjs (fs/path).
+ * (gsd-core/bin/lib/hook-bus.cjs alone has no requires and is genuinely
+ * web-safe.) Requiring `host-binding.js` here would transitively pull in
+ * `node:fs` and throw at web-worker load time — the opposite of "zero Node
+ * APIs". See host-binding.js's own header comment for the full chain. Fixing
+ * those engine-lib modules to be fs-free is a separate, much larger
+ * engine-wide refactor (config/capability loading genuinely reads files from
+ * disk for every OTHER host) — out of scope here; flagged rather than routed
+ * around silently.
+ *
+ * So this file implements its OWN minimal, independently-verified-zero-Node-API
+ * composition directly against `vscode.lm` — no engine-lib requires at all.
+ *
+ * DISPATCH STORY ON WEB (per the #2103 dispatch-crux design): full GSD engine
+ * dispatch (the gsd-tools.cjs subprocess-shim `dispatchGsdCommand` used by the
+ * desktop `extension.js`) is fundamentally a Node `child_process.spawnSync`
+ * call — there is no web-worker equivalent. On web, GSD command dispatch is
+ * available through VS Code's NATIVE MCP client connecting to the GSD
+ * companion MCP server (gsd-core/bin/lib/mcp-server.cjs, `gsd-mcp-server`
+ * bin entry — a separate, already-existing surface; this file does NOT
+ * implement an MCP client itself, it only points the user at that story).
+ * The chat participant and Language Model Tools registered below are
+ * therefore intentionally limited on web: they register (so the surface is
+ * discoverable and `#runSubagent`-eligible per VS Code's chat engine) but
+ * their handlers return an honest "configure the GSD MCP server for full
+ * dispatch on web" message rather than silently failing or faking success.
+ */
+
+/**
+ * Tokenizes a raw chat/free-form prompt string. Kept local (not shared with
+ * extension.js) so this file has zero requires of any kind beyond `vscode`.
+ * @param {string} rawPrompt
+ * @returns {{family: string, subcommand: string|undefined, args: string[]}}
+ */
+function parseChatPrompt(rawPrompt) {
+  const tokens = String(rawPrompt || '').trim().split(/\s+/).filter(Boolean);
+  return {
+    family: tokens[0] || '--help',
+    subcommand: tokens[1],
+    args: tokens.slice(2),
+  };
+}
+
+/**
+ * The honest "web mode" message every web-surface handler returns instead of
+ * attempting Node-only engine dispatch.
+ * @param {string} family
+ */
+function webDispatchUnavailableMessage(family) {
+  return (
+    `GSD web mode: full engine dispatch for "${family}" is not available in the browser ` +
+    '(the VS Code Web/webworker host has no Node runtime, so the gsd-tools.cjs ' +
+    'subprocess dispatch used on desktop cannot run here). Configure the GSD MCP ' +
+    'server (gsd-mcp-server) as a VS Code MCP server for full command dispatch on web, ' +
+    'or use the desktop GSD Core extension.'
+  );
+}
+
+/**
+ * Registers the `@gsd` chat participant in web mode (#2103). Its handler is
+ * honest about the web dispatch limitation — see webDispatchUnavailableMessage.
+ * Exported separately so it is testable with a mock `vscode.chat`.
+ * @param {object} vscode
+ * @param {import('vscode').ExtensionContext} context
+ * @returns {object|null} the created participant, or null if vscode.chat is absent.
+ */
+function registerChatParticipant(vscode, context) {
+  if (!vscode || !vscode.chat || typeof vscode.chat.createChatParticipant !== 'function') {
+    return null;
+  }
+  const participant = vscode.chat.createChatParticipant('gsd', async (request, _chatContext, stream, _token) => {
+    const { family } = parseChatPrompt(request && request.prompt);
+    if (stream && typeof stream.markdown === 'function') {
+      stream.markdown(webDispatchUnavailableMessage(family));
+    }
+    return { metadata: { command: family, mode: 'web' } };
+  });
+  if (context && Array.isArray(context.subscriptions)) context.subscriptions.push(participant);
+  return participant;
+}
+
+/**
+ * The same representative LM tool NAMES as the desktop extension (must match
+ * package.json's contributes.languageModelTools[].name — underscored, the
+ * vscode.lm.registerTool registration name — so the manifest is identical
+ * across both entry points), but with web-mode invoke() handlers.
+ */
+const LM_TOOL_NAMES = ['gsd_progress', 'gsd_workstreams', 'gsd_plan_phase'];
+
+/**
+ * Registers web-mode LM tools via vscode.lm.registerTool (#2103). Each
+ * invoke() returns the honest web-dispatch-unavailable message — no engine-lib
+ * requires, no Node APIs.
+ * @param {object} vscode
+ * @param {import('vscode').ExtensionContext} context
+ * @returns {number} count of tools registered (0 if vscode.lm is absent — fail-soft).
+ */
+function registerLanguageModelTools(vscode, context) {
+  if (!vscode || !vscode.lm || typeof vscode.lm.registerTool !== 'function') return 0;
+  let count = 0;
+  for (const name of LM_TOOL_NAMES) {
+    const impl = {
+      async invoke(_options, _token) {
+        return new vscode.LanguageModelToolResult([
+          new vscode.LanguageModelTextPart(webDispatchUnavailableMessage(name)),
+        ]);
+      },
+    };
+    const disposable = vscode.lm.registerTool(name, impl);
+    if (context && Array.isArray(context.subscriptions)) context.subscriptions.push(disposable);
+    count++;
+  }
+  return count;
+}
+
+/**
+ * Detects `#runSubagent` feature availability (`chat.subagents.allowInvocationsFromSubagents`,
+ * VS Code 1.105+). Fail-soft: never throws. Identical detection logic to the
+ * desktop extension.js (duplicated, not shared, to keep this file at zero
+ * requires) — see extension.js's registerSubagentDispatch for the rationale
+ * that VS Code's chat engine itself surfaces registered participants/tools to
+ * `#runSubagent`, with no separate registration API.
+ * @param {object} vscode
+ * @returns {{available: boolean}}
+ */
+function detectSubagentSupport(vscode) {
+  let available = false;
+  try {
+    const cfg = vscode && vscode.workspace && typeof vscode.workspace.getConfiguration === 'function'
+      ? vscode.workspace.getConfiguration('chat.subagents')
+      : null;
+    available = !!(cfg && typeof cfg.get === 'function' && cfg.get('allowInvocationsFromSubagents') !== undefined);
+  } catch {
+    available = false;
+  }
+  return { available };
+}
+
+/**
+ * VS Code Web extension activation. Registers the chat participant + Language
+ * Model Tools in web mode. Does NOT register the `gsd.invoke` command with a
+ * real-dispatch handler (there is no Node dispatch on web) — the command is
+ * still contributed (contributes.commands in package.json is shared across
+ * desktop/web), so it is registered here too, but its handler returns the
+ * same honest web-mode message.
+ * @param {import('vscode').ExtensionContext} context
+ */
+function activate(context) {
+  const vscode = require('vscode');
+
+  const gsdCommand = vscode.commands.registerCommand('gsd.invoke', async (args) => {
+    const a = (args && typeof args === 'object') ? args : {};
+    const family = (typeof a.family === 'string' && a.family) ? a.family : '--help';
+    return JSON.stringify({ ok: false, stdout: '', stderr: webDispatchUnavailableMessage(family), code: null, timedOut: false });
+  });
+  context.subscriptions.push(gsdCommand);
+
+  registerChatParticipant(vscode, context);
+  registerLanguageModelTools(vscode, context);
+  detectSubagentSupport(vscode);
+}
+
+module.exports = {
+  activate,
+  parseChatPrompt,
+  webDispatchUnavailableMessage,
+  registerChatParticipant,
+  registerLanguageModelTools,
+  detectSubagentSupport,
+  LM_TOOL_NAMES,
+};