toolfactory 0.1.1

package/src/surfaces/skill.ts

@@ -0,0 +1,136 @@
+/**
+ * Agent Skills: one `skills/<N>/SKILL.md` per tool. toolfactory owns the frontmatter and
+ * the `<!-- tf:operations -->` block; the body is the author's prose and is never generated.
+ * The bundle formats (Agent Plugins, Claude, Codex, Cursor) fix `skills/` at the bundle root,
+ * while Copilot, Codex, Hermes and DSH read a project's skills only from `.agents/skills/`
+ * (and `npx skills add` reads both): a symbolic link there is the one directory that serves all.
+ */
+import { stringify as yaml } from "yaml";
+import {
+  type Capability,
+  isInstructionOnly,
+  type Operation,
+  type Project,
+  type Surface,
+  type Verdict,
+} from "../model.js";
+import { compact, has, skillVerdict } from "./shared.js";
+
+export const OPERATIONS_BEGIN = "<!-- tf:operations -->";
+export const OPERATIONS_END = "<!-- /tf:operations -->";
+
+export function skillPath(project: Project): string {
+  return `skills/${project.identity.name}/SKILL.md`;
+}
+
+/** The `.agents/` canon's view of the same skill, which `.agents/sync.py` fans out to every harness. */
+function skillLinkPath(project: Project): string {
+  return `.agents/skills/${project.identity.name}`;
+}
+
+function invocation(project: Project, operation: Operation): string {
+  const name = project.identity.name;
+  const lines: string[] = [];
+  if (has(project, "cli"))
+    lines.push(`\`${name} ${operation.name} --json '<arguments>'\` prints a JSON result.`);
+  if (has(project, "mcp") || has(project, "agent-plugins")) {
+    lines.push(
+      `MCP tool \`${operation.name}\` on server \`${name}\` returns the same result as \`structuredContent\`.`,
+    );
+  }
+  return lines.join(" ");
+}
+
+/** How an agent bridges each non-portable capability before calling the operation. */
+const GUIDANCE: Partial<Record<Capability, string>> = {
+  browser: "drive this host's own browser tools and pass what they return as arguments",
+  model: "do that reasoning yourself and pass the result as an argument",
+  "user-input": "ask the user for what it needs before calling it",
+};
+
+export function renderOperations(project: Project): string {
+  if (isInstructionOnly(project.tool)) return "";
+  const lines = ["", "## Operations", ""];
+  if (project.operations.length === 0) {
+    lines.push("_No operations yet: run `toolfactory introspect` after adding one to the kernel._");
+  }
+  for (const operation of project.operations) {
+    const verdict: Verdict = skillVerdict(operation);
+    if (verdict.kind === "excluded") continue;
+    const required = Object.keys(
+      (operation.inputSchema.properties as Record<string, unknown> | undefined) ?? {},
+    );
+    lines.push(`### ${operation.name}`, "");
+    if (operation.description) lines.push(operation.description, "");
+    if (required.length)
+      lines.push(`Arguments: ${required.map((k) => `\`${k}\``).join(", ")}.`, "");
+    const how = invocation(project, operation);
+    if (how) lines.push(how, "");
+    const needs = operation.requires.filter((capability) => GUIDANCE[capability]);
+    if (verdict.kind === "bridged" && needs.length) {
+      lines.push(
+        `This operation needs ${needs.join(", ")}: ${needs.map((capability) => GUIDANCE[capability]).join("; ")}.`,
+        "",
+      );
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export function frontmatter(project: Project): string {
+  const document = compact({
+    name: project.identity.name,
+    description: project.identity.description ?? `Use the ${project.identity.name} tool.`,
+    license: project.identity.license,
+  });
+  return `\n${yaml(document).trimEnd()}\n`;
+}
+
+export const surface: Surface = {
+  id: "skill",
+  plan(project) {
+    const path = skillPath(project);
+    const regions = [
+      { begin: "---", end: "---", content: frontmatter(project) },
+      { begin: OPERATIONS_BEGIN, end: OPERATIONS_END, content: renderOperations(project) },
+    ];
+    const template = [
+      "---",
+      "---",
+      "",
+      `# ${project.identity.name}`,
+      "",
+      "Explain here when an agent should reach for this tool and how to combine its operations.",
+      "",
+      OPERATIONS_BEGIN,
+      OPERATIONS_END,
+      "",
+    ].join("\n");
+    return [
+      { kind: "region", path, regions, template },
+      {
+        kind: "file",
+        path: skillLinkPath(project),
+        content: `../../skills/${project.identity.name}`,
+        symlink: true,
+      },
+    ];
+  },
+  validate(project) {
+    return [
+      {
+        label: "agentskills validate",
+        command: "uvx",
+        args: [
+          "--from",
+          "skills-ref",
+          "agentskills",
+          "validate",
+          `skills/${project.identity.name}`,
+        ],
+        cwd: project.root,
+      },
+    ];
+  },
+  verdict: skillVerdict,
+};

package/src/surfaces/web.test.ts

@@ -0,0 +1,303 @@
+import { spawnSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { kernel, scaffold } from "../bindings/typescript.js";
+import { run } from "../commands.js";
+import { DRIFT_ENTRY } from "../hosts/web.js";
+import type { Operation, Project } from "../model.js";
+import { apply, deepMerge, replaceRegions } from "../project/apply.js";
+import { json } from "./shared.js";
+import { APP_BEGIN, APP_END, surface, WEB_DIR, WEB_SCAFFOLD } from "./web.js";
+
+const echo: Operation = {
+  name: "echo",
+  description: "Return the text you pass in.",
+  inputSchema: {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    type: "object",
+    properties: { text: { type: "string", description: "Text to echo back" } },
+    required: ["text"],
+  },
+  annotations: { readOnlyHint: true },
+  requires: [],
+};
+const shoot: Operation = {
+  name: "shoot",
+  description: "Take a screenshot of the current tab.",
+  inputSchema: { type: "object" },
+  requires: ["browser"],
+};
+
+function project(overrides: Partial<Project> = {}): Project {
+  return {
+    root: "/repo",
+    tool: {
+      schemaVersion: 1,
+      identity: "package.json",
+      binding: "typescript",
+      surfaces: ["web", "mcp", "cli"],
+      bundle: { runtime: "package" },
+      tests: { examples: {} },
+    },
+    identity: { name: "hello", version: "0.1.0", description: "Say hello" },
+    identityExtra: {},
+    operations: [echo, shoot],
+    toolfactoryVersion: "0.1.0",
+    ...overrides,
+  };
+}
+
+/** Every planned file as text, region files rendered fresh (as `apply()` writes them the first time). */
+function planned(from: Project = project()): Map<string, string> {
+  return new Map(
+    surface.plan(from).map((file) => {
+      if (file.kind === "file") return [file.path, file.content];
+      if (file.kind === "region")
+        return [file.path, replaceRegions(file.template, file) ?? file.template];
+      return [file.path, json(deepMerge({}, file.patch))];
+    }),
+  );
+}
+
+function opsJson(from: Project = project()): Record<string, unknown> {
+  return JSON.parse(planned(from).get(`${WEB_DIR}/src/ops.json`) ?? "");
+}
+
+describe("web", () => {
+  it("plans the vite + shadcn project and leaves src/components/ui to the shadcn CLI", () => {
+    expect([...planned().keys()]).toEqual([
+      "web/.oxlintrc.json",
+      "web/components.json",
+      "web/index.html",
+      "web/package.json",
+      "web/smoke.mjs",
+      "web/src/App.tsx",
+      "web/src/index.css",
+      "web/src/lib/utils.ts",
+      "web/src/main.tsx",
+      "web/src/ops.json",
+      "web/src/schema-form.tsx",
+      "web/tsconfig.app.json",
+      "web/tsconfig.json",
+      "web/tsconfig.node.json",
+      "web/vite.config.ts",
+    ]);
+  });
+
+  it("App.tsx is a region file: the operations page is generated, the pages array and shell are the author's and survive a rebuild", () => {
+    const target = project();
+    const file = surface
+      .plan(target)
+      .find((candidate) => candidate.path === `${WEB_DIR}/src/App.tsx`);
+    if (file?.kind !== "region") throw new Error("web/src/App.tsx is no longer a region file");
+    expect(file.regions).toHaveLength(1);
+    expect(file.regions[0].begin).toBe(APP_BEGIN);
+    expect(file.regions[0].end).toBe(APP_END);
+    expect(file.regions[0].content).toContain("export function OperationsPage()");
+    expect(file.template).toContain(
+      "export const pages: { id: string; title: string; element: ReactNode }[]",
+    );
+    expect(file.template).toContain(
+      '{ id: "operations", title: "Operations", element: <OperationsPage /> }',
+    );
+    expect(file.template).toContain("export default function App()");
+
+    // Round-trip through the real writer: scaffold, let the author add a page below the
+    // marker (as vutoolkit adds its d3 degree-planner graph), then run a second `toolfactory
+    // build` (a changed operation set, same as a real `introspect` picking up new tools) and
+    // check the added page is still there.
+    const root = mkdtempSync(join(tmpdir(), "toolfactory-web-app-"));
+    apply(root, surface.plan(target), "0.1.0");
+    const appPath = join(root, WEB_DIR, "src/App.tsx");
+    const authored = readFileSync(appPath, "utf8").replace(
+      '{ id: "operations", title: "Operations", element: <OperationsPage /> },',
+      '{ id: "operations", title: "Operations", element: <OperationsPage /> },\n  { id: "planner", title: "Degree planner", element: <div>planner</div> },',
+    );
+    writeFileSync(appPath, authored);
+
+    const rebuilt = project({ operations: [echo] });
+    apply(root, surface.plan(rebuilt), "0.1.0");
+    const after = readFileSync(appPath, "utf8");
+    expect(after).toContain(
+      '{ id: "planner", title: "Degree planner", element: <div>planner</div> },',
+    );
+    expect(after).toContain("export function OperationsPage()");
+  });
+
+  it("web/package.json is a merge file, so an author-added dependency (e.g. `npm --prefix web install d3` for a page) survives a rebuild", () => {
+    const target = project();
+    const file = surface
+      .plan(target)
+      .find((candidate) => candidate.path === `${WEB_DIR}/package.json`);
+    if (file?.kind !== "merge") throw new Error("web/package.json is no longer a merge file");
+
+    const root = mkdtempSync(join(tmpdir(), "toolfactory-web-pkg-"));
+    apply(root, surface.plan(target), "0.1.0");
+    const pkgPath = join(root, WEB_DIR, "package.json");
+    const authored = JSON.parse(readFileSync(pkgPath, "utf8"));
+    authored.dependencies.d3 = "^7.9.0";
+    writeFileSync(pkgPath, json(authored));
+
+    apply(root, surface.plan(project({ operations: [echo] })), "0.1.0");
+    const after = JSON.parse(readFileSync(pkgPath, "utf8"));
+    expect(after.dependencies.d3).toBe("^7.9.0");
+    expect(after.dependencies.react).toBe(WEB_SCAFFOLD.packageJson.dependencies.react);
+  });
+
+  it("snapshots the operations this surface carries and says why the others are missing", () => {
+    const data = opsJson();
+    expect(data.tool).toEqual({ name: "hello", version: "0.1.0", description: "Say hello" });
+    expect(data.mcpProtocolVersion).toBe("2026-07-28");
+    // Relative to the document: one build serves under `/`, under a plugin prefix, and on Pages.
+    expect(data.defaultEndpoint).toBe("mcp");
+
+    const operations = data.operations as {
+      name: string;
+      inputSchema: unknown;
+      annotations?: unknown;
+    }[];
+    expect(operations.map((operation) => operation.name)).toEqual(["echo"]);
+    expect(operations[0]?.inputSchema).toEqual(echo.inputSchema);
+    // `smoke.mjs` runs the first read-only operation for real, so the hints have to travel.
+    expect(operations[0]?.annotations).toEqual({ readOnlyHint: true });
+    expect(data.excluded).toEqual([{ name: "shoot", reason: "excluded:mcp-no-host-capabilities" }]);
+    expect(surface.verdict?.(shoot, project())).toEqual({
+      kind: "excluded",
+      reason: "excluded:mcp-no-host-capabilities",
+    });
+  });
+
+  it("src/ops.json is an output file: a lossy duplicate rebuilt by `npm run build`, not tracked (D8)", () => {
+    const file = surface
+      .plan(project())
+      .find((candidate) => candidate.path === `${WEB_DIR}/src/ops.json`);
+    if (file?.kind !== "file") throw new Error("web/src/ops.json is no longer a plain file");
+    expect(file.output).toBe(true);
+  });
+
+  it("the page and the smoke both talk to the kernel that served them: relative endpoint, bearer from the fragment, one listener", () => {
+    const files = planned();
+    const app = files.get(`${WEB_DIR}/src/App.tsx`) ?? "";
+    expect(app).toContain("new URL(DATA.defaultEndpoint, document.baseURI).href");
+    expect(app).toContain("window.location.hash");
+    expect(app).toContain("Authorization: `Bearer ${TOKEN}`");
+    // The Secrets panel is the developer's `.env`, and it is the kernel's `/env` that answers.
+    expect(app).toContain('new URL("env", document.baseURI).href');
+    expect(app).toContain("toolfactory secrets check");
+    expect(app).toContain('type="password"');
+
+    // The smoke drives the real kernel over --http instead of a static server of its own.
+    const smoke = files.get(`${WEB_DIR}/smoke.mjs`) ?? "";
+    expect(smoke).toContain('const KERNEL = ["node","--import","tsx","src/toolfactory/mcp.ts"]');
+    expect(smoke).toContain('"--http", "0"');
+    expect(smoke).toContain("HELLO_MCP_TOKEN");
+    expect(smoke).toContain("candidate.annotations?.readOnlyHint");
+    expect(smoke).not.toContain("createServer");
+  });
+
+  it("builds with a relative base, so one build is served the same at /, under a plugin prefix and on Pages", () => {
+    const content = planned().get(`${WEB_DIR}/vite.config.ts`) ?? "";
+    expect(content).toContain('base: process.env.PAGES_BASE ?? "./"');
+  });
+
+  it("previews the CLI only when the cli surface is also selected", () => {
+    expect(opsJson().cliAvailable).toBe(true);
+    const without = project({ tool: { ...project().tool, surfaces: ["web", "mcp"] } });
+    expect(opsJson(without).cliAvailable).toBe(false);
+  });
+
+  it("emits the pinned scaffold verbatim, so the drift check speaks for plan()", () => {
+    const files = planned();
+    expect(files.get("web/src/index.css")).toBe(WEB_SCAFFOLD.indexCss);
+    expect(files.get("web/src/lib/utils.ts")).toBe(WEB_SCAFFOLD.utils);
+    for (const [path, content] of Object.entries(WEB_SCAFFOLD.vite)) {
+      // The two tsconfigs gain the `@/*` alias; the rest travel unchanged.
+      const emitted = files.get(`web/${path}`) ?? "";
+      if (path === "tsconfig.json" || path === "tsconfig.app.json") {
+        expect(emitted).toContain('"@/*": ["./src/*"]');
+      } else if (path !== "vite.config.ts") {
+        expect(emitted).toBe(content);
+      }
+    }
+    expect(JSON.parse(files.get("web/components.json") ?? "")).toEqual(WEB_SCAFFOLD.componentsJson);
+
+    const packageJson = JSON.parse(files.get("web/package.json") ?? "");
+    expect(packageJson.dependencies).toEqual(WEB_SCAFFOLD.packageJson.dependencies);
+    expect(packageJson.devDependencies).toMatchObject(WEB_SCAFFOLD.packageJson.devDependencies);
+    expect(packageJson.devDependencies.playwright).toBe(WEB_SCAFFOLD.playwright);
+
+    // Every component the page imports is one `validate()` asks the shadcn CLI for.
+    const sources = `${files.get("web/src/App.tsx")}${files.get("web/src/schema-form.tsx")}`;
+    const imported = [...sources.matchAll(/@\/components\/ui\/([a-z-]+)/g)].map(
+      (match) => match[1],
+    );
+    expect(imported.length).toBeGreaterThan(0);
+    expect(WEB_SCAFFOLD.components).toEqual(expect.arrayContaining(imported));
+  });
+});
+
+/**
+ * The whole validator chain, run the way `toolfactory validate --surface web` runs it. Needs
+ * npm (every step installs from the registry) and a Playwright browser download for the smoke,
+ * so it self-skips where neither the author nor CI has one.
+ */
+function browserAvailable(): boolean {
+  const browsers = process.env.PLAYWRIGHT_BROWSERS_PATH ?? join(homedir(), ".cache/ms-playwright");
+  return existsSync(browsers) && spawnSync("npm", ["--version"]).status === 0;
+}
+
+describe.skipIf(!browserAvailable())("validated the way an author runs it", () => {
+  it("installs, adds the components, proves the scaffold, builds and smokes the page", () => {
+    const root = mkdtempSync(join(tmpdir(), "toolfactory-web-"));
+    const fixture = project({ root });
+    for (const [path, content] of planned(fixture)) {
+      mkdirSync(dirname(join(root, path)), { recursive: true });
+      writeFileSync(join(root, path), content);
+    }
+    // What `loadProject` needs, so the drift script can re-plan from the same project.
+    mkdirSync(join(root, "dev.toolfactory"), { recursive: true });
+    writeFileSync(join(root, "dev.toolfactory/tool.json"), json(fixture.tool));
+    writeFileSync(
+      join(root, "dev.toolfactory/ops.json"),
+      json({
+        tools: [echo, shoot].map(({ requires, ...tool }) => ({
+          ...tool,
+          _meta: { "dev.toolfactory": { requires } },
+        })),
+      }),
+    );
+    // The smoke drives the real kernel, so the fixture is a real project: the binding's kernel
+    // and scaffold, and this checkout's `node_modules` (the SDK, zod and tsx the kernel imports).
+    for (const file of [...kernel(fixture), ...scaffold(fixture)]) {
+      if (file.kind !== "file") continue;
+      mkdirSync(dirname(join(root, file.path)), { recursive: true });
+      writeFileSync(join(root, file.path), file.content);
+    }
+    symlinkSync(join(process.cwd(), "node_modules"), join(root, "node_modules"));
+
+    for (const command of surface.validate?.(fixture) ?? []) {
+      // Vitest runs this file from source, so the drift entry is still TypeScript: give node
+      // the loader from this checkout, where `tsx` is installed.
+      const outcome = run(
+        command.args.includes(DRIFT_ENTRY)
+          ? { ...command, args: ["--import", "tsx", DRIFT_ENTRY, root], cwd: process.cwd() }
+          : command,
+      );
+      expect(outcome.ok, `${outcome.label}: ${outcome.output}`).toBe(true);
+      if (outcome.label.includes("smoke")) {
+        expect(outcome.output).toContain("PASS cli preview");
+        // The whole point of driving the kernel: the page's own call came back from it.
+        expect(outcome.output).toContain('PASS echo round-tripped: {\n  "text": "smoke"\n}');
+      }
+    }
+  }, 900_000);
+});