toolfactory 0.1.1 → 0.2.0

package/src/surfaces/readme.ts

@@ -14,6 +14,9 @@
  * `cursor.com/en/install-mcp`), both computed from the exact same `{command, args, env}` launch
  * the plain-text line renders — a badge can never point somewhere the text line does not.
  */
+
+import { nativeInstallLines } from "../distribution/native.js";
+import { systemInstallLines } from "../distribution/system.js";
 import { githubSlug } from "../hosts/github.js";
 import { projectName } from "../identity/name.js";
 import type { Project, Surface } from "../model.js";
@@ -22,6 +25,7 @@ import { HOST_DIR as DSH_HOST_DIR, dshTarball } from "./dsh.js";
 import { pluginDir as hermesPluginDir } from "./hermes-native.js";
 import { HOST_DIR as OPENCLAW_HOST_DIR } from "./openclaw-native.js";
 import { envName, has, npmName, pypiName, requiredConfig } from "./shared.js";
+import { vsixName } from "./vscode-extension.js";
 
 export const README_PATH = "README.md";
 export const INSTALL_BEGIN = "<!-- tf:install -->";
@@ -83,6 +87,12 @@ function installLines(project: Project): string[] {
   const { identity } = project;
   const slug = githubSlug(identity.repository);
   const lines: string[] = [];
+  lines.push(...nativeInstallLines(project).map((line) => `- **Native package** — ${line}`));
+  lines.push(...systemInstallLines(project).map((line) => `- **System package** — ${line}`));
+  if (has(project, "vscode-extension"))
+    lines.push(
+      `- **VS Code extension** — download \`${vsixName(project)}\` from the release, then \`code --install-extension ${vsixName(project)}\``,
+    );
   if (has(project, "skill") && slug) {
     lines.push(`- **Agent Skill** — \`npx skills add ${slug}\``);
   }
@@ -142,8 +152,8 @@ function installLines(project: Project): string[] {
   }
   if (has(project, "browser-extension")) {
     // Three channels, in the order a reader needs them: build-and-load from a checkout, the
-    // release assets (only Mozilla's signed xpi is a real self-hosted install — Chrome drops
-    // side-loaded unpacked extensions), the store listings. Pairing is the last step of each.
+    // release assets (the signed Firefox XPI depends on configured signing credentials), and
+    // store listings. Pairing is the last step of each.
     const zips = (["chrome", "firefox", "edge"] as const).map(
       (browser) => `\`${zipName(project, browser)}\``,
     );
@@ -152,9 +162,8 @@ function installLines(project: Project): string[] {
         `- **Browser extension** — from a checkout: \`npm --prefix ${BROWSER_HOST_DIR} install && npm --prefix ${BROWSER_HOST_DIR} exec --no -- wxt build\`,`,
         `  then \`chrome://extensions\` → developer mode → Load unpacked → \`${BROWSER_HOST_DIR}/.output/chrome-mv3\``,
         `  (Firefox: \`npm --prefix ${BROWSER_HOST_DIR} exec --no -- web-ext run\`). Each GitHub Release attaches the`,
-        `  store uploads ${zips.join(", ")}, and the Mozilla-signed \`.xpi\`,`,
-        "  which is the only download-and-install channel now that Chrome no longer keeps side-loaded unpacked",
-        "  extensions; the Chrome Web Store, Firefox Add-ons and Edge Add-ons listings appear once the release's",
+        `  store uploads ${zips.join(", ")}. When Firefox signing credentials are configured, it also attaches a`,
+        "  Mozilla-signed `.xpi`; the Chrome Web Store, Firefox Add-ons and Edge Add-ons listings appear once the release's",
         `  submit step has each store's credentials. Then pair it: \`${mcpCommand(project)} --http --pair\``,
         "  prints the `<url>#<token>` the extension's options page accepts.",
       ].join("\n"),
@@ -169,7 +178,13 @@ function installLines(project: Project): string[] {
       "  returns the URL.",
     );
   }
-  if (has(project, "npm")) lines.push(`- **npm package** — \`npm install ${npmName(project)}\``);
+  if (has(project, "npm")) {
+    const pythonBridge =
+      project.tool.binding === "python"
+        ? `; requires \`uv\`, and \`${identity.name}\` delegates to \`uvx --from ${pypiName(project)}==${identity.version} ${identity.name}\``
+        : "";
+    lines.push(`- **npm package** — \`npm install ${npmName(project)}\`${pythonBridge}`);
+  }
   if (has(project, "pypi")) lines.push(`- **PyPI package** — \`uv add ${pypiName(project)}\``);
   return lines;
 }

package/src/surfaces/registry.ts

@@ -1,3 +1,5 @@
+import { nativePackageSurfaces } from "../distribution/native.js";
+import { systemPackageSurfaces } from "../distribution/system.js";
 import type { Surface, SurfaceId } from "../model.js";
 import { surface as agentPlugins } from "./agent-plugins.js";
 import { surface as agents } from "./agents.js";
@@ -17,10 +19,13 @@ import { surface as openclawNative } from "./openclaw-native.js";
 import { surface as pypi } from "./pypi.js";
 import { surface as readme } from "./readme.js";
 import { surface as skill } from "./skill.js";
+import { surface as vscodeExtension } from "./vscode-extension.js";
 import { surface as web } from "./web.js";
 import { surface as workflows } from "./workflows.js";
 
 const registry: Partial<Record<SurfaceId, Surface>> = {
+  ...Object.fromEntries(nativePackageSurfaces.map((surface) => [surface.id, surface])),
+  ...Object.fromEntries(systemPackageSurfaces.map((surface) => [surface.id, surface])),
   "agent-plugins": agentPlugins,
   agents,
   "browser-extension": { ...browserExtension, requires: ["mcp"] },
@@ -38,9 +43,9 @@ const registry: Partial<Record<SurfaceId, Surface>> = {
   cli,
   mcp,
   "mcp-registry": mcpRegistry,
-  // The bundle root is the npm tarball with its production dependencies installed into it, and
-  // its one row launches the kernel MCP server: without either surface there is nothing to pack.
-  mcpb: { ...mcpb, requires: ["mcp", "npm"] },
+  // TypeScript bundles stage their npm tarball; Python `uv` bundles stage the PyPI project's
+  // source. The projector enforces that binding-specific distribution dependency.
+  mcpb: { ...mcpb, requires: ["mcp"] },
   npm,
   skill,
   "hermes-native": hermesNative,
@@ -48,6 +53,7 @@ const registry: Partial<Record<SurfaceId, Surface>> = {
   pypi,
   readme,
   web: { ...web, requires: ["mcp"] },
+  "vscode-extension": { ...vscodeExtension, requires: ["mcp", "cli"] },
   workflows,
 };
 

package/src/surfaces/vscode-extension.test.ts

@@ -0,0 +1,89 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, expect, it } from "vitest";
+import { type Project, ToolConfigSchema } from "../model.js";
+import { apply, check } from "../project/apply.js";
+import { packageSteps, registries } from "../project/gate.js";
+import { surface } from "./vscode-extension.js";
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function fixture(): Project {
+  const root = mkdtempSync(join(tmpdir(), "tf-vscode-"));
+  roots.push(root);
+  return {
+    root,
+    tool: ToolConfigSchema.parse({
+      schemaVersion: 1,
+      identity: "plugin.json",
+      binding: "typescript",
+      surfaces: ["mcp", "cli", "npm", "vscode-extension"],
+      vscode: { publisher: "octo" },
+    }),
+    identity: { name: "hello.tool", version: "1.0.0", repository: "https://github.com/octo/hello" },
+    identityExtra: {},
+    operations: [
+      { name: "echo", inputSchema: { type: "object" }, requires: [] },
+      { name: "native", inputSchema: { type: "object" }, requires: ["model"] },
+    ],
+    toolfactoryVersion: "0.1.2",
+  };
+}
+
+it("keeps native contributions, activation, build settings and command details across operation changes", () => {
+  const project = fixture();
+  apply(project.root, surface.plan(project), "0.1.2");
+  const path = join(project.root, "hosts/vscode/package.json");
+  const pkg = JSON.parse(readFileSync(path, "utf8"));
+  pkg.contributes.commands[0].icon = "$(beaker)";
+  pkg.contributes.commands.push({ command: "hello.tool.custom", title: "Custom native command" });
+  pkg.contributes.views = { explorer: [{ id: "native-view", name: "Native view" }] };
+  pkg.scripts.custom = "node custom.js";
+  writeFileSync(path, JSON.stringify(pkg));
+  const entry = join(project.root, "hosts/vscode/src/extension.ts");
+  writeFileSync(entry, `${readFileSync(entry, "utf8")}\nexport const authored = true;\n`);
+  expect(check(project.root, surface.plan(project), "0.1.2")).toEqual([]);
+  const echo = project.operations[0];
+  if (!echo) throw new Error("fixture must contain echo");
+  echo.title = "New title";
+  apply(project.root, surface.plan(project), "0.1.2");
+  const rebuilt = JSON.parse(readFileSync(path, "utf8"));
+  expect(rebuilt.contributes.commands).toContainEqual({
+    command: "hello-tool.echo",
+    title: "New title",
+    category: "Hello Tool",
+    icon: "$(beaker)",
+  });
+  expect(rebuilt.contributes.commands).toContainEqual({
+    command: "hello.tool.custom",
+    title: "Custom native command",
+  });
+  expect(rebuilt.contributes.commands).not.toContainEqual(
+    expect.objectContaining({ command: "hello-tool.native" }),
+  );
+  expect(rebuilt.contributes.views).toEqual(pkg.contributes.views);
+  expect(rebuilt.scripts.custom).toBe("node custom.js");
+  expect(readFileSync(entry, "utf8")).toContain("export const authored = true;");
+  expect(check(project.root, surface.plan(project), "0.1.2")).toEqual([]);
+});
+
+it("packages a VSIX independently of registry credentials and permits each registry to be deselected", () => {
+  const project = fixture();
+  expect(packageSteps(project).some((step) => step.run.includes("hello-tool-1.0.0.vsix"))).toBe(
+    true,
+  );
+  expect(registries(project).map((row) => row.id)).toEqual(
+    expect.arrayContaining(["vscode-marketplace", "open-vsx"]),
+  );
+  project.tool.vscode = { publisher: "octo", marketplace: false, openvsx: true };
+  expect(registries(project).map((row) => row.id)).not.toContain("vscode-marketplace");
+  project.tool.binding = "python";
+  expect(() => surface.plan(project)).toThrow("requires pypi");
+  project.tool.surfaces = ["mcp", "cli", "pypi", "vscode-extension"];
+  const runtime = surface.plan(project).find((file) => file.path.endsWith("/generated.ts"));
+  expect(runtime?.kind === "file" && runtime.content).toContain('"command":"uvx"');
+});

package/src/surfaces/vscode-extension.ts

@@ -0,0 +1,345 @@
+/** A native VS Code extension. The author owns activation and all native contributions. */
+import { execArgv } from "node:process";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { githubOwner, projectName } from "../identity/name.js";
+import { isPortable, type Project, type Surface } from "../model.js";
+import {
+  configProperties,
+  dataDirEnvName,
+  envName,
+  has,
+  isSensitive,
+  npmName,
+  pypiName,
+  rootEnvName,
+} from "./shared.js";
+import {
+  ESBUILD,
+  ESLINT,
+  GITIGNORE,
+  IGNORE,
+  LAUNCH,
+  TASKS,
+  VSCODE_SCAFFOLD,
+} from "./vscode-scaffold.js";
+
+export const HOST_DIR = "hosts/vscode";
+export const vscodeConfigSchema = z.object({
+  publisher: z
+    .string()
+    .regex(/^[a-zA-Z0-9][a-zA-Z0-9-]*$/)
+    .optional()
+    .describe(
+      "Your registered Visual Studio Marketplace/Open VSX publisher; repository owner is the local packaging default.",
+    ),
+  marketplace: z.boolean().default(true),
+  openvsx: z.boolean().default(true),
+});
+export const VSCE_VERSION = "3.9.2";
+export const OVSX_VERSION = "1.1.1";
+
+export function extensionName(project: Project): string {
+  return project.identity.name.replaceAll(".", "-");
+}
+
+export function publisher(project: Project): string {
+  return (
+    project.tool.vscode?.publisher ??
+    githubOwner(project.identity.repository) ??
+    extensionName(project)
+  );
+}
+
+export function vsixName(project: Project): string {
+  return `${extensionName(project)}-${project.identity.version ?? "0.0.0"}.vsix`;
+}
+
+function operations(project: Project) {
+  return project.operations.filter(isPortable);
+}
+
+function runtime(project: Project): string {
+  const name = extensionName(project);
+  const python = project.tool.binding === "python";
+  const packageName = python ? pypiName(project) : npmName(project);
+  const version = project.identity.version ?? "0.0.0";
+  const defaults = python
+    ? { command: "uvx", args: ["--from", `${packageName}==${version}`, project.identity.name] }
+    : { command: "npx", args: ["--yes", `${packageName}@${version}`] };
+  const config = Object.entries(configProperties(project)).map(([key, property]) => ({
+    key,
+    env: envName(key),
+    secret: isSensitive(property),
+  }));
+  return `// Generated by toolfactory. Native extension code belongs in extension.ts.
+import { mkdir } from 'node:fs/promises';
+import { Client } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
+import * as vscode from 'vscode';
+
+const namespace = ${JSON.stringify(name)};
+const defaults = ${JSON.stringify(defaults)};
+const config: Array<{key: string; env: string; secret: boolean}> = ${JSON.stringify(config)};
+const operations: Array<{name: string; title: string}> = ${JSON.stringify(operations(project).map((op) => ({ name: op.name, title: op.title ?? op.name })))};
+
+function launch(context: vscode.ExtensionContext) {
+  const settings = vscode.workspace.getConfiguration(namespace);
+  const root = vscode.Uri.joinPath(context.extensionUri, '../..').fsPath;
+  const development = context.extensionMode !== vscode.ExtensionMode.Production;
+  const local = ${python ? `{ command: 'uv', args: ['run', '--quiet', '--directory', root, 'python', '-m', '${projectName.pythonPackage(project.identity.name)}.toolfactory.cli'] }` : `{ command: 'node', args: ['--import', 'tsx', root + '/src/toolfactory/cli.ts'] }`};
+  const selected = development ? local : defaults;
+  const command = settings.get<string>('runtime.command');
+  return {
+    command: command || selected.command,
+    args: command ? settings.get<string[]>('runtime.args', []) : selected.args,
+    cwd: development ? root : undefined,
+  };
+}
+
+async function environment(context: vscode.ExtensionContext): Promise<Record<string, string>> {
+  const settings = vscode.workspace.getConfiguration(namespace);
+  const env: Record<string, string> = {};
+  for (const property of config) {
+    const value = (property.secret ? await context.secrets.get(property.env) : settings.get('config.' + property.key)) ?? process.env[property.env];
+    if (value !== undefined) env[property.env] = typeof value === 'string' ? value : JSON.stringify(value);
+  }
+  await mkdir(context.globalStorageUri.fsPath, { recursive: true });
+  env[${JSON.stringify(dataDirEnvName(project))}] = context.globalStorageUri.fsPath;
+  const folder = vscode.workspace.workspaceFolders?.find(folder => folder.uri.scheme === 'file');
+  if (folder) env[${JSON.stringify(rootEnvName(project))}] = folder.uri.fsPath;
+  return env;
+}
+
+export function registerGenerated(context: vscode.ExtensionContext): void {
+  const changes = new vscode.EventEmitter<void>();
+  context.subscriptions.push(changes,
+    vscode.workspace.onDidChangeConfiguration(event => { if (event.affectsConfiguration(namespace)) changes.fire(); }),
+    context.secrets.onDidChange(() => changes.fire()),
+    vscode.lm.registerMcpServerDefinitionProvider(namespace, {
+      onDidChangeMcpServerDefinitions: changes.event,
+      provideMcpServerDefinitions() {
+        const selected = launch(context);
+        const server = new vscode.McpStdioServerDefinition(
+          ${JSON.stringify(projectName.display(project.identity.name))}, selected.command,
+          [...selected.args, 'mcp'], {}, ${JSON.stringify(version)},
+        );
+        server.cwd = selected.cwd ? vscode.Uri.file(selected.cwd) : undefined;
+        return [server];
+      },
+      async resolveMcpServerDefinition(server) {
+        if (!vscode.workspace.isTrusted) throw new Error('Trust this workspace before starting the tool runtime.');
+        if (server instanceof vscode.McpStdioServerDefinition) server.env = { ...server.env, ...await environment(context) };
+        return server;
+      },
+    }),
+  );
+  ${
+    config.some((property) => property.secret)
+      ? `context.subscriptions.push(vscode.commands.registerCommand(namespace + '.configureSecrets', async () => {
+    const chosen = await vscode.window.showQuickPick(config.filter(property => property.secret).map(property => property.env), { title: 'Configure credentials' });
+    if (!chosen) return;
+    const value = await vscode.window.showInputBox({ title: chosen, password: true, prompt: 'Stored in VS Code SecretStorage. Leave empty to remove.' });
+    if (value === undefined) return;
+    if (value) await context.secrets.store(chosen, value); else await context.secrets.delete(chosen);
+  }));`
+      : ""
+  }
+  for (const operation of operations) {
+    context.subscriptions.push(vscode.commands.registerCommand(namespace + '.' + operation.name, async (args?: Record<string, unknown>) => {
+      if (!vscode.workspace.isTrusted) throw new Error('Trust this workspace before running tools.');
+      const interactive = args === undefined;
+      if (interactive) {
+        const input = await vscode.window.showInputBox({ title: operation.title, prompt: 'Operation arguments (JSON object)', value: '{}',
+          validateInput(value) { try { const parsed = JSON.parse(value); return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? undefined : 'Enter a JSON object'; } catch { return 'Enter a JSON object'; } },
+        });
+        if (input === undefined) return;
+        args = JSON.parse(input) as Record<string, unknown>;
+      }
+      const selected = launch(context);
+      const client = new Client({ name: namespace + '-vscode', version: ${JSON.stringify(version)} });
+      try {
+        await client.connect(new StdioClientTransport({ command: selected.command, args: [...selected.args, 'mcp'],
+          cwd: selected.cwd, env: await environment(context),
+        }));
+        const response = await client.callTool({ name: operation.name, arguments: args });
+        if (response.isError) throw new Error(JSON.stringify(response.content));
+        const result = response.structuredContent ?? response.content;
+        if (interactive) await vscode.window.showTextDocument(await vscode.workspace.openTextDocument({ language: 'json', content: JSON.stringify(result, null, 2) }));
+        return result;
+      } finally {
+        await client.close();
+      }
+    }));
+  }
+}
+`;
+}
+
+function packagePatch(project: Project): Record<string, unknown> {
+  const name = extensionName(project);
+  const properties = Object.fromEntries(
+    Object.entries(configProperties(project))
+      .filter(([, property]) => !isSensitive(property))
+      .map(([key, property]) => {
+        const { "x-toolfactory": _metadata, ...schema } = property;
+        return [`${name}.config.${key}`, schema];
+      }),
+  );
+  const commands = operations(project).map((op) => ({
+    command: `${name}.${op.name}`,
+    title: op.title ?? op.name,
+    category: projectName.display(project.identity.name),
+  }));
+  if (Object.values(configProperties(project)).some(isSensitive))
+    commands.push({
+      command: `${name}.configureSecrets`,
+      title: "Configure credentials",
+      category: projectName.display(project.identity.name),
+    });
+  return {
+    name,
+    version: project.identity.version ?? "0.0.0",
+    displayName: projectName.display(project.identity.name),
+    description: project.identity.description ?? `${project.identity.name} tools for VS Code`,
+    publisher: publisher(project),
+    license: project.identity.license ?? "UNLICENSED",
+    ...(project.identity.repository
+      ? { repository: { type: "git", url: project.identity.repository } }
+      : {}),
+    engines: VSCODE_SCAFFOLD.engines,
+    main: "./dist/extension.js",
+    capabilities: { untrustedWorkspaces: { supported: false } },
+    contributes: {
+      commands,
+      mcpServerDefinitionProviders: [
+        { id: name, label: projectName.display(project.identity.name) },
+      ],
+      configuration: {
+        title: projectName.display(project.identity.name),
+        properties: {
+          ...properties,
+          [`${name}.runtime.command`]: {
+            type: "string",
+            scope: "machine",
+            description: "Override the tool runtime executable.",
+          },
+          [`${name}.runtime.args`]: {
+            type: "array",
+            items: { type: "string" },
+            scope: "machine",
+            description: "Arguments for runtime.command, before the mcp subcommand.",
+          },
+        },
+      },
+    },
+    scripts: { ...VSCODE_SCAFFOLD.scripts, vsix: "vsce package --out extension.vsix" },
+    dependencies: { "@modelcontextprotocol/client": "^2.0.0" },
+    devDependencies: { ...VSCODE_SCAFFOLD.devDependencies, "@vscode/vsce": `^${VSCE_VERSION}` },
+    overrides: VSCODE_SCAFFOLD.overrides,
+  };
+}
+
+export const surface: Surface = {
+  id: "vscode-extension",
+  plan(project) {
+    const registry = project.tool.binding === "python" ? "pypi" : "npm";
+    if (!has(project, registry))
+      throw new Error(`vscode-extension requires ${registry} for its installed runtime.`);
+    const entry = `import * as vscode from 'vscode';\nimport { registerGenerated } from './generated';\n`;
+    const probe = operations(project).find((op) => project.tool.tests.examples[op.name]);
+    return [
+      {
+        kind: "merge",
+        path: `${HOST_DIR}/package.json`,
+        format: "json",
+        patch: packagePatch(project),
+        keyedArrays: {
+          "contributes.commands": "command",
+          "contributes.mcpServerDefinitionProviders": "id",
+        },
+      },
+      { kind: "file", path: `${HOST_DIR}/src/generated.ts`, content: runtime(project) },
+      {
+        kind: "region",
+        path: `${HOST_DIR}/src/extension.ts`,
+        regions: [{ begin: "// tf:imports", end: "// /tf:imports", content: `\n${entry}` }],
+        template: `// tf:imports\n// /tf:imports\n\n// This is your extension entry. Use the complete VS Code API here.\nexport function activate(context: vscode.ExtensionContext) {\n  registerGenerated(context);\n}\n\nexport function deactivate() {}\n`,
+      },
+      {
+        kind: "merge",
+        path: `${HOST_DIR}/tsconfig.json`,
+        format: "json",
+        patch: {
+          compilerOptions: {
+            module: "Node16",
+            target: "ES2022",
+            lib: ["ES2022"],
+            types: ["node", "mocha"],
+            sourceMap: true,
+            rootDir: "src",
+            strict: true,
+          },
+        },
+      },
+      ...[
+        ["esbuild.js", ESBUILD],
+        ["eslint.config.mjs", ESLINT],
+        [".vscode/launch.json", LAUNCH],
+        [".vscode/tasks.json", TASKS],
+        [".vscodeignore", IGNORE],
+        [".gitignore", GITIGNORE],
+      ].map(([path, content]) => ({
+        kind: "region" as const,
+        path: `${HOST_DIR}/${path}`,
+        regions: [
+          {
+            begin: path?.endsWith("ignore") ? "# tf:scaffold" : "// tf:scaffold",
+            end: path?.endsWith("ignore") ? "# /tf:scaffold" : "// /tf:scaffold",
+            content: "\n",
+          },
+        ],
+        template: `${path?.endsWith("ignore") ? "# tf:scaffold\n# /tf:scaffold" : "// tf:scaffold\n// /tf:scaffold"}\n${content}`,
+      })),
+      {
+        kind: "file",
+        path: `${HOST_DIR}/.vscode-test.mjs`,
+        content: `import { defineConfig } from '@vscode/test-cli';\nexport default defineConfig({ files: 'out/test/**/*.test.js', launchArgs: ['--disable-workspace-trust', '--skip-welcome', '--skip-release-notes', '--no-sandbox'] });\n`,
+      },
+      {
+        kind: "file",
+        path: `${HOST_DIR}/src/test/generated.test.ts`,
+        content: `import * as assert from 'node:assert/strict';\nimport * as vscode from 'vscode';\nsuite('Generated extension', () => {\n  test('activates and registers the operations', async () => {\n    const extension = vscode.extensions.getExtension(${JSON.stringify(`${publisher(project)}.${extensionName(project)}`)});\n    assert.ok(extension);\n    await extension.activate();\n    const commands = await vscode.commands.getCommands(true);\n    for (const command of ${JSON.stringify(operations(project).map((op) => `${extensionName(project)}.${op.name}`))}) assert.ok(commands.includes(command), command);\n    ${probe ? `await vscode.commands.executeCommand(${JSON.stringify(`${extensionName(project)}.${probe.name}`)}, ${JSON.stringify(project.tool.tests.examples[probe.name])});` : ""}\n  });\n});\n`,
+      },
+      {
+        kind: "file",
+        path: `${HOST_DIR}/README.md`,
+        content: `# ${projectName.display(project.identity.name)} for VS Code\n\n${project.identity.description ?? ""}\n\nInstall the VSIX with \`code --install-extension ${vsixName(project)}\`. The extension provides an MCP server and commands for each portable operation. ${registry === "npm" ? "Node.js/npm" : "uv"} must be on PATH; installed extensions use the matching published ${registry} version.\n\nDevelop with \`npm install\`, then open this directory in VS Code and press F5. Development and tests use the checkout's kernel. \`npm test\` runs a real Extension Development Host; \`npm run vsix\` creates the installable package.\n\nEdit \`src/extension.ts\` outside its import markers and add native files freely. Use all VS Code APIs: language-model tools, chat participants, views, webviews, commands, editors and language services. Add native contribution points and additional commands directly to \`package.json\`; generated command/provider entries are maintained by identity, preserving your entries. Build scripts, debugger settings and ignore rules are editable scaffold files. Use \`adopt\` only when replacing a generated integration itself.\n\nConfiguration is in VS Code Settings; credentials use SecretStorage through the Configure credentials command when declared. The runtime command/arguments can be overridden in machine settings.\n\nPublishers must be registered separately with Visual Studio Marketplace and Open VSX. Releases attach a VSIX even when no publishing credentials are configured.\n`,
+      },
+    ];
+  },
+  validate(project) {
+    const cwd = `${project.root}/${HOST_DIR}`;
+    const drift = fileURLToPath(new URL("../hosts/vscode.js", import.meta.url));
+    return [
+      {
+        label: "VS Code upstream scaffold",
+        command: "node",
+        args: [...execArgv, drift, project.root],
+      },
+      { label: "VS Code dependencies", command: "npm", args: ["install"], cwd },
+      { label: "VS Code VSIX", command: "npm", args: ["run", "vsix"], cwd },
+      {
+        label: "VS Code Extension Development Host",
+        command: process.platform === "linux" ? "xvfb-run" : "npm",
+        args: process.platform === "linux" ? ["-a", "npm", "test"] : ["test"],
+        cwd,
+      },
+    ];
+  },
+  verdict(operation) {
+    return isPortable(operation)
+      ? { kind: "bridged", reason: "bridged:vscode-mcp" }
+      : { kind: "excluded", reason: "excluded:implement-in-hosts" };
+  },
+};

package/src/surfaces/vscode-scaffold.ts

@@ -0,0 +1,55 @@
+/** Captured by running generator-code@1.12.0 (TypeScript/esbuild); hosts/vscode.ts verifies it. */
+
+export const VSCODE_GENERATOR = "1.12.0";
+export const GITIGNORE = "out\ndist\nnode_modules\n.vscode-test/\n*.vsix\n";
+
+export const VSCODE_SCAFFOLD = {
+  engines: {
+    vscode: "^1.136.0",
+  },
+  scripts: {
+    "vscode:prepublish": "npm run package",
+    compile: "npm run check-types && npm run lint && node esbuild.js",
+    watch: "npm-run-all -p watch:*",
+    "watch:esbuild": "node esbuild.js --watch",
+    "watch:tsc": "tsc --noEmit --watch --project tsconfig.json",
+    package: "npm run check-types && npm run lint && node esbuild.js --production",
+    "compile-tests": "tsc -p . --outDir out",
+    "watch-tests": "tsc -p . -w --outDir out",
+    pretest: "npm run compile-tests && npm run compile && npm run lint",
+    "check-types": "tsc --noEmit",
+    lint: "eslint src",
+    test: "vscode-test",
+  },
+  devDependencies: {
+    "@types/vscode": "^1.136.0",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "24.x",
+    "typescript-eslint": "^8.61.1",
+    eslint: "^10.5.0",
+    esbuild: "^0.28.1",
+    "npm-run-all": "^4.1.5",
+    typescript: "^6.0.3",
+    "@vscode/test-cli": "^0.0.15",
+    "@vscode/test-electron": "^3.0.0",
+  },
+  overrides: {
+    diff: "^8.0.4",
+    "serialize-javascript": "^7.0.6",
+  },
+} as const;
+
+export const ESBUILD =
+  "const esbuild = require(\"esbuild\");\n\nconst production = process.argv.includes('--production');\nconst watch = process.argv.includes('--watch');\n\n/**\n * @type {import('esbuild').Plugin}\n */\nconst esbuildProblemMatcherPlugin = {\n\tname: 'esbuild-problem-matcher',\n\n\tsetup(build) {\n\t\tbuild.onStart(() => {\n\t\t\tconsole.log('[watch] build started');\n\t\t});\n\t\tbuild.onEnd((result) => {\n\t\t\tresult.errors.forEach(({ text, location }) => {\n\t\t\t\tconsole.error(`\u2718 [ERROR] ${text}`);\n\t\t\t\tconsole.error(`    ${location.file}:${location.line}:${location.column}:`);\n\t\t\t});\n\t\t\tconsole.log('[watch] build finished');\n\t\t});\n\t},\n};\n\nasync function main() {\n\tconst ctx = await esbuild.context({\n\t\tentryPoints: [\n\t\t\t'src/extension.ts'\n\t\t],\n\t\tbundle: true,\n\t\tformat: 'cjs',\n\t\tminify: production,\n\t\tsourcemap: !production,\n\t\tsourcesContent: false,\n\t\tplatform: 'node',\n\t\toutfile: 'dist/extension.js',\n\t\texternal: ['vscode'],\n\t\tlogLevel: 'silent',\n\t\tplugins: [\n\t\t\t/* add to the end of plugins array */\n\t\t\tesbuildProblemMatcherPlugin,\n\t\t],\n\t});\n\tif (watch) {\n\t\tawait ctx.watch();\n\t} else {\n\t\tawait ctx.rebuild();\n\t\tawait ctx.dispose();\n\t}\n}\n\nmain().catch(e => {\n\tconsole.error(e);\n\tprocess.exit(1);\n});\n";
+
+export const ESLINT =
+  'import typescriptEslint from "typescript-eslint";\n\nexport default [{\n    files: ["**/*.ts"],\n}, {\n    plugins: {\n        "@typescript-eslint": typescriptEslint.plugin,\n    },\n\n    languageOptions: {\n        parser: typescriptEslint.parser,\n        ecmaVersion: 2022,\n        sourceType: "module",\n    },\n\n    rules: {\n        "@typescript-eslint/naming-convention": ["warn", {\n            selector: "import",\n            format: ["camelCase", "PascalCase"],\n        }],\n\n        curly: "warn",\n        eqeqeq: "warn",\n        "no-throw-literal": "warn",\n        semi: "warn",\n    },\n}];';
+
+export const IGNORE =
+  ".vscode/**\n.vscode-test/**\nout/**\nnode_modules/**\nsrc/**\n.gitignore\n.yarnrc\nesbuild.js\nvsc-extension-quickstart.md\n**/tsconfig.json\n**/eslint.config.mjs\n**/*.map\n**/*.ts\n**/.vscode-test.*\n";
+
+export const LAUNCH =
+  '// A launch configuration that compiles the extension and then opens it inside a new window\n// Use IntelliSense to learn about possible attributes.\n// Hover to view descriptions of existing attributes.\n// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387\n{\n\t"version": "0.2.0",\n\t"configurations": [\n\t\t{\n\t\t\t"name": "Run Extension",\n\t\t\t"type": "extensionHost",\n\t\t\t"request": "launch",\n\t\t\t"args": [\n\t\t\t\t"--extensionDevelopmentPath=${workspaceFolder}"\n\t\t\t],\n\t\t\t"outFiles": [\n\t\t\t\t"${workspaceFolder}/dist/**/*.js"\n\t\t\t],\n\t\t\t"preLaunchTask": "${defaultBuildTask}"\n\t\t}\n\t]\n}\n';
+
+export const TASKS =
+  '// See https://go.microsoft.com/fwlink/?LinkId=733558\n// for the documentation about the tasks.json format\n{\n\t"version": "2.0.0",\n\t"tasks": [\n\t\t{\n            "label": "watch",\n            "dependsOn": [\n                "npm: watch:tsc",\n                "npm: watch:esbuild"\n            ],\n            "presentation": {\n                "reveal": "never"\n            },\n            "group": {\n                "kind": "build",\n                "isDefault": true\n            }\n        },\n        {\n            "type": "npm",\n            "script": "watch:esbuild",\n            "group": "build",\n            "problemMatcher": "$esbuild-watch",\n            "isBackground": true,\n            "label": "npm: watch:esbuild",\n            "presentation": {\n                "group": "watch",\n                "reveal": "never"\n            }\n        },\n\t\t{\n            "type": "npm",\n            "script": "watch:tsc",\n            "group": "build",\n            "problemMatcher": "$tsc-watch",\n            "isBackground": true,\n            "label": "npm: watch:tsc",\n            "presentation": {\n                "group": "watch",\n                "reveal": "never"\n            }\n        },\n\t\t{\n\t\t\t"type": "npm",\n\t\t\t"script": "watch-tests",\n\t\t\t"problemMatcher": "$tsc-watch",\n\t\t\t"isBackground": true,\n\t\t\t"presentation": {\n\t\t\t\t"reveal": "never",\n\t\t\t\t"group": "watchers"\n\t\t\t},\n\t\t\t"group": "build"\n\t\t},\n\t\t{\n\t\t\t"label": "tasks: watch-tests",\n\t\t\t"dependsOn": [\n\t\t\t\t"npm: watch",\n\t\t\t\t"npm: watch-tests"\n\t\t\t],\n\t\t\t"problemMatcher": []\n\t\t}\n\t]\n}\n';