toolfactory 0.1.2 → 0.2.0

package/dist/surfaces/mcp-registry.test.js

@@ -52,12 +52,30 @@ describe("mcp-registry Dockerfile", () => {
         expect(npmBuilt.Dockerfile).not.toContain("corepack enable");
         const py = files(project({ tool: { ...project().tool, binding: "python" } }));
         expect(py.Dockerfile).toContain('ENTRYPOINT ["python","-m","hello.toolfactory.mcp"]');
+        expect(py.Dockerfile).toContain("COPY . .\nRUN uv sync --no-dev");
+        expect(py.Dockerfile).not.toContain("COPY pyproject.toml ./");
+        expect(py.Dockerfile).toContain('for path in README README.md README.rst LICENSE LICENSE.md LICENSE.txt NOTICE NOTICE.md NOTICE.txt; do if [ -f "$path" ]; then cp "$path" /app/runtime/; fi; done');
+        expect(py.Dockerfile).toContain("COPY --from=build /app/runtime/ ./");
+        expect(py.Dockerfile).not.toContain("COPY --from=build /app .");
         const pythonWeb = files(project({
             tool: { ...project().tool, binding: "python", surfaces: ["mcp-registry", "web"] },
         }));
         expect(pythonWeb.Dockerfile).toContain("FROM node:24-alpine AS web");
         expect(pythonWeb.Dockerfile).toContain("COPY --from=web /app/web/dist ./src/hello/web");
     });
+    it("ships an author-extensible Docker ignore region without excluding source metadata", () => {
+        const ignore = surface.plan(project()).find((file) => file.path === ".dockerignore");
+        if (ignore?.kind !== "region")
+            throw new Error("expected a Docker ignore region");
+        expect(ignore.template).toContain("# tf:dockerignore\n# /tf:dockerignore");
+        expect(ignore.regions[0]?.content).toContain(".git/");
+        expect(ignore.regions[0]?.content).toContain(".env.*");
+        expect(ignore.regions[0]?.content).toContain("!.env.example");
+        expect(ignore.regions[0]?.content).toContain("**/node_modules/");
+        expect(ignore.regions[0]?.content).toContain("**/.venv/");
+        expect(ignore.regions[0]?.content).not.toContain("README");
+        expect(ignore.regions[0]?.content).not.toContain("web/");
+    });
 });
 describe("mcp-registry server.json oci package", () => {
     it("adds an oci entry with a lowercased ghcr.io identifier, unconditionally", () => {

package/dist/surfaces/openclaw-native.js

@@ -216,7 +216,7 @@ function packageJson(project, operations, kase) {
         : undefined;
     const extra = project.tool.openclaw;
     const e2e = kase ? { "test:e2e": OPENCLAW_ADDITIONS.e2eScript } : undefined;
-    return json(compact({
+    return compact({
         name: projectName.openclawPackage(project.identity.name),
         version: project.identity.version ?? "0.0.0",
         description: pluginDescription(project),
@@ -239,7 +239,7 @@ function packageJson(project, operations, kase) {
         pluginInspector: expectedRegistrations(project, operations).length
             ? pluginInspector(project, operations)
             : undefined,
-    }));
+    });
 }
 /**
  * `openclaw plugins build` regenerates this file; emitting it keeps `--check` green from a clean
@@ -256,7 +256,7 @@ function pluginManifest(project, operations) {
         registration.contract,
         registration.ids,
     ]);
-    return json(compact({
+    return compact({
         id: project.identity.name,
         name: displayName(project.identity.name),
         description: pluginDescription(project),
@@ -268,7 +268,7 @@ function pluginManifest(project, operations) {
             tools: operations.map((operation) => operation.name),
             ...Object.fromEntries(declared),
         },
-    }));
+    });
 }
 function executeBody(project, operation) {
     if (project.tool.binding === "typescript") {
@@ -819,9 +819,10 @@ export const surface = {
         const kase = e2eCase(project, operations);
         return [
             {
-                kind: "file",
+                kind: "merge",
                 path: `${HOST_DIR}/package.json`,
-                content: packageJson(project, operations, kase),
+                format: "json",
+                patch: packageJson(project, operations, kase),
             },
             {
                 kind: "file",
@@ -841,9 +842,10 @@ export const surface = {
                 content: OPENCLAW_SCAFFOLD.vitestConfig,
             },
             {
-                kind: "file",
+                kind: "merge",
                 path: `${HOST_DIR}/openclaw.plugin.json`,
-                content: pluginManifest(project, operations),
+                format: "json",
+                patch: pluginManifest(project, operations),
             },
             {
                 kind: "region",

package/dist/surfaces/openclaw-native.test.js

@@ -1,6 +1,10 @@
 import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { scaffoldDrift } from "../hosts/openclaw.js";
+import { apply } from "../project/apply.js";
 import { computeCoverage, renderCoverageMarkdown } from "../report/coverage.js";
 import { HOST_DIR, OPENCLAW_ADDITIONS, OPENCLAW_SCAFFOLD, surface } from "./openclaw-native.js";
 const echo = {
@@ -74,6 +78,32 @@ function emitted(target) {
     ]));
 }
 describe("openclaw-native", () => {
+    it("keeps hand-authored package and manifest extensions through regeneration", () => {
+        const root = mkdtempSync(join(tmpdir(), "toolfactory-openclaw-"));
+        const target = { ...project(), root };
+        apply(root, surface.plan(target), "0.1.0");
+        const packagePath = join(root, HOST_DIR, "package.json");
+        const manifestPath = join(root, HOST_DIR, "openclaw.plugin.json");
+        writeFileSync(packagePath, JSON.stringify({
+            ...JSON.parse(readFileSync(packagePath, "utf8")),
+            scripts: { custom: "node custom.mjs" },
+            exports: { "./native": "./src/native.ts" },
+        }));
+        writeFileSync(manifestPath, JSON.stringify({
+            ...JSON.parse(readFileSync(manifestPath, "utf8")),
+            contracts: { customProviders: ["native"] },
+            nativeField: true,
+        }));
+        apply(root, surface.plan(target), "0.1.0");
+        expect(JSON.parse(readFileSync(packagePath, "utf8"))).toMatchObject({
+            scripts: { custom: "node custom.mjs" },
+            exports: { "./native": "./src/native.ts" },
+        });
+        expect(JSON.parse(readFileSync(manifestPath, "utf8"))).toMatchObject({
+            contracts: { customProviders: ["native"] },
+            nativeField: true,
+        });
+    });
     it("projects only the operations OpenClaw can run and pins the scaffold in one place", () => {
         const files = emitted(project());
         const manifest = JSON.parse(files[`${HOST_DIR}/openclaw.plugin.json`] ?? "{}");

package/dist/surfaces/readme.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Surface "readme": the `<!-- tf:install -->` region of `README.md`, always generated (like
+ * `workflows` and `agents`; never in `tool.json.surfaces`). One install line per selected
+ * distribution surface, in the exact shape that surface's own installer accepts, so the
+ * humans-and-agents-facing half of distribution cannot drift from the artifacts. The prose
+ * around the region — what the tool is, how to use it — is the author's, forever.
+ *
+ * Every line works from a plain checkout; the ones that need a GitHub repository (`npx skills
+ * add`, the Agent Skill badge, the marketplace and Hermes clone URLs) appear only once the
+ * identity file carries one, so a tool built without GitHub still gets an accurate section.
+ *
+ * When `mcp` is selected alongside a package registry, the MCP line also carries the two
+ * first-party one-click badges (VS Code's `vscode.dev/redirect/mcp/install`, Cursor's
+ * `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 type { Project, Surface } from "../model.js";
 export declare const README_PATH = "README.md";
 export declare const INSTALL_BEGIN = "<!-- tf:install -->";

package/dist/surfaces/readme.js

@@ -14,6 +14,8 @@
  * `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 { HOST_DIR as BROWSER_HOST_DIR, zipName } from "./browser-extension.js";
@@ -21,6 +23,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 -->";
 export const INSTALL_END = "<!-- /tf:install -->";
@@ -70,6 +73,10 @@ function installLines(project) {
     const { identity } = project;
     const slug = githubSlug(identity.repository);
     const lines = [];
+    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}\``);
     }

package/dist/surfaces/registry.js

@@ -1,3 +1,5 @@
+import { nativePackageSurfaces } from "../distribution/native.js";
+import { systemPackageSurfaces } from "../distribution/system.js";
 import { surface as agentPlugins } from "./agent-plugins.js";
 import { surface as agents } from "./agents.js";
 import { surface as browserExtension } from "./browser-extension.js";
@@ -16,9 +18,12 @@ 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 = {
+    ...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"] },
@@ -46,6 +51,7 @@ const registry = {
     pypi,
     readme,
     web: { ...web, requires: ["mcp"] },
+    "vscode-extension": { ...vscodeExtension, requires: ["mcp", "cli"] },
     workflows,
 };
 export function registerSurface(surface) {

package/dist/surfaces/vscode-extension.d.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { type Project, type Surface } from "../model.js";
+export declare const HOST_DIR = "hosts/vscode";
+export declare const vscodeConfigSchema: z.ZodObject<{
+    publisher: z.ZodOptional<z.ZodString>;
+    marketplace: z.ZodDefault<z.ZodBoolean>;
+    openvsx: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const VSCE_VERSION = "3.9.2";
+export declare const OVSX_VERSION = "1.1.1";
+export declare function extensionName(project: Project): string;
+export declare function publisher(project: Project): string;
+export declare function vsixName(project: Project): string;
+export declare const surface: Surface;

package/dist/surfaces/vscode-extension.js

@@ -0,0 +1,312 @@
+/** 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 } 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) {
+    return project.identity.name.replaceAll(".", "-");
+}
+export function publisher(project) {
+    return (project.tool.vscode?.publisher ??
+        githubOwner(project.identity.repository) ??
+        extensionName(project));
+}
+export function vsixName(project) {
+    return `${extensionName(project)}-${project.identity.version ?? "0.0.0"}.vsix`;
+}
+function operations(project) {
+    return project.operations.filter(isPortable);
+}
+function runtime(project) {
+    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) {
+    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 = {
+    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",
+                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/dist/surfaces/vscode-extension.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/surfaces/vscode-extension.test.js

@@ -0,0 +1,81 @@
+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 { 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 = [];
+afterEach(() => {
+    for (const root of roots.splice(0))
+        rmSync(root, { recursive: true, force: true });
+});
+function fixture() {
+    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"');
+});