toolfactory 0.1.1

package/src/hosts/openclaw.ts

@@ -0,0 +1,110 @@
+/**
+ * The I/O half of the OpenClaw surface: §8 C2, "mirror scaffolds by execution, not
+ * transcription". Runs the real `openclaw plugins init --type tool` into a temp directory and
+ * checks that everything it writes still agrees with what `plan()` emits, so an upstream default
+ * change is inherited on the next toolfactory release instead of silently rotting in a constant.
+ *
+ * Runnable as a script (`node dist/hosts/openclaw.js <root>`) because that is how the surface's
+ * `validate()` step reaches it: one Command like every other validator.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { argv, exit, stderr, stdout } from "node:process";
+import { fileURLToPath } from "node:url";
+import type { PlannedFile, Project } from "../model.js";
+import { loadProject } from "../project/load.js";
+import { HOST_DIR, surface } from "../surfaces/openclaw-native.js";
+
+export const DRIFT_ENTRY = fileURLToPath(import.meta.url);
+
+/** Per-tool values: the scaffold writes its own, and the projection is expected to differ. */
+const PER_TOOL_KEYS = new Set(["name", "version", "description"]);
+
+/**
+ * Keys `tool.json` deliberately overrides (`openclaw.pluginApi` and the extra dependency maps):
+ * the scaffold's value is not law where the author has replaced it on purpose.
+ */
+function overridden(project: Project): Set<string> {
+  const openclaw = project.tool.openclaw;
+  const paths = new Set<string>();
+  for (const section of ["dependencies", "peerDependencies", "devDependencies"] as const) {
+    for (const key of Object.keys(openclaw?.[section] ?? {})) paths.add(`.${section}.${key}`);
+  }
+  if (openclaw?.pluginApi) {
+    paths.add(".peerDependencies.openclaw");
+    paths.add(".openclaw.compat.pluginApi");
+  }
+  return paths;
+}
+
+/**
+ * Every scaffold key must survive into the projection with the same value; extra keys are the
+ * generator's own additions (the core dependency, the projected tools, the inspector fixture)
+ * and are allowed, as are the keys `tool.json` overrides on purpose.
+ */
+function missing(scaffold: unknown, ours: unknown, path: string, skip: Set<string>): string[] {
+  if (skip.has(path)) return [];
+  if (scaffold === null || typeof scaffold !== "object" || Array.isArray(scaffold)) {
+    return JSON.stringify(scaffold) === JSON.stringify(ours)
+      ? []
+      : [`${path}: upstream ${JSON.stringify(scaffold)}, generated ${JSON.stringify(ours)}`];
+  }
+  if (ours === null || typeof ours !== "object" || Array.isArray(ours)) {
+    return [`${path}: upstream object, generated ${JSON.stringify(ours)}`];
+  }
+  const right = ours as Record<string, unknown>;
+  return Object.entries(scaffold as Record<string, unknown>).flatMap(([key, value]) =>
+    path === "" && PER_TOOL_KEYS.has(key) ? [] : missing(value, right[key], `${path}.${key}`, skip),
+  );
+}
+
+function planned(files: PlannedFile[], path: string): string {
+  const file = files.find((candidate) => candidate.path === `${HOST_DIR}/${path}`);
+  if (file?.kind !== "file") throw new Error(`the openclaw surface no longer plans ${path}`);
+  return file.content;
+}
+
+/** Human-readable drift lines; empty means the generator still mirrors upstream. */
+export function scaffoldDrift(project: Project): string[] {
+  const files = surface.plan(project);
+  const directory = mkdtempSync(join(tmpdir(), "toolfactory-openclaw-"));
+  // Prefer the openclaw the plugin pins as a devDependency over whatever is on PATH.
+  const pinned = join(project.root, HOST_DIR, "node_modules/.bin/openclaw");
+  try {
+    execFileSync(
+      existsSync(pinned) ? pinned : "openclaw",
+      ["plugins", "init", "tf-probe", "--type", "tool", "--directory", join(directory, "probe")],
+      { stdio: "pipe" },
+    );
+    const scaffold = (path: string) => readFileSync(join(directory, "probe", path), "utf8");
+    const skip = overridden(project);
+    const drift = [
+      ...["package.json", "tsconfig.json"].flatMap((path) =>
+        missing(JSON.parse(scaffold(path)), JSON.parse(planned(files, path)), "", skip).map(
+          (line) => `${path}${line}`,
+        ),
+      ),
+      ...(scaffold("vitest.config.ts") === planned(files, "vitest.config.ts")
+        ? []
+        : ["vitest.config.ts: upstream template changed"]),
+    ];
+    return drift;
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+}
+
+if (argv[1] === DRIFT_ENTRY) {
+  const drift = scaffoldDrift(loadProject(argv[2] ?? "."));
+  if (drift.length) {
+    stderr.write(
+      `openclaw scaffold drifted upstream; update src/surfaces/openclaw-native.ts:\n${drift
+        .map((line) => `  ${line}`)
+        .join("\n")}\n`,
+    );
+    exit(1);
+  }
+  stdout.write("openclaw plugins init still matches src/surfaces/openclaw-native.ts\n");
+}

package/src/hosts/template.ts

@@ -0,0 +1,149 @@
+/**
+ * The I/O half of the `agents` surface: §8 C2, "mirror scaffolds by execution, not
+ * transcription", applied to a repository instead of a generator. The agent-config machinery
+ * every generated project carries — `.agents/sync.py`, the hook carriers, the agent-config
+ * workflow — is one shared contract owned by github.com/GoatInAHat/template, and a copy of a
+ * moving contract rots silently. So the bytes are vendored into `src/surfaces/agents.template.ts`
+ * by this module's `--write` mode, and the copy is proved by cloning the real repository and
+ * diffing it file by file.
+ *
+ * Runnable as a script (`node dist/hosts/template.js [<url or checkout>] [--write]`) because that
+ * is how the surface's `validate()` step reaches it: one Command like every other validator.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { argv, exit, stderr, stdout } from "node:process";
+import { fileURLToPath } from "node:url";
+import { TEMPLATE_COMMIT, TEMPLATE_FILES } from "../surfaces/agents.template.js";
+
+export const DRIFT_ENTRY = fileURLToPath(import.meta.url);
+export const TEMPLATE_URL = "https://github.com/GoatInAHat/template";
+
+/**
+ * The template files toolfactory projects into every generated repository. The two it does not
+ * vendor are the two it writes itself: `.agents/mcp/servers.json` (a merge file, so a teammate's
+ * absorbed server survives a rebuild) and `AGENTS.md` (a region file with the tool's own prose).
+ */
+export const VENDORED_PATHS = [
+  ".agents/README.md",
+  ".agents/setup",
+  ".agents/skills/.gitkeep",
+  ".agents/sync.py",
+  ".claude/settings.json",
+  ".cursor/environment.json",
+  ".devcontainer/Dockerfile",
+  ".devcontainer/devcontainer.json",
+  ".gitattributes",
+  ".github/workflows/agent-config.yml",
+  ".github/workflows/copilot-setup-steps.yml",
+  ".gitignore",
+];
+
+/** Where `--write` puts the vendored bytes; a source-tree path, since re-vendoring is a dev step. */
+const VENDORED_MODULE = join(dirname(DRIFT_ENTRY), "..", "surfaces", "agents.template.ts");
+
+function head(root: string): string {
+  return execFileSync("git", ["-C", root, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+}
+
+/** A local checkout is used where it is; anything else is cloned shallow into a temp directory. */
+function checkout(source: string): { root: string; commit: string; dispose: () => void } {
+  const local = (() => {
+    try {
+      return statSync(source).isDirectory();
+    } catch {
+      return false;
+    }
+  })();
+  if (local) return { root: source, commit: head(source), dispose: () => {} };
+  const directory = mkdtempSync(join(tmpdir(), "toolfactory-template-"));
+  execFileSync("git", ["clone", "--depth", "1", source, directory], { stdio: "pipe" });
+  return {
+    root: directory,
+    commit: head(directory),
+    dispose: () => rmSync(directory, { recursive: true, force: true }),
+  };
+}
+
+function read(root: string, path: string): string | undefined {
+  try {
+    return readFileSync(join(root, path), "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+/** Human-readable drift lines; empty means the vendored copy is still the template's own bytes. */
+export function scaffoldDrift(source: string = TEMPLATE_URL): string[] {
+  const at = checkout(source);
+  try {
+    return VENDORED_PATHS.flatMap((path) => {
+      const upstream = read(at.root, path);
+      if (upstream === undefined) return [`${path}: no longer in the template`];
+      if (TEMPLATE_FILES[path] === undefined) return [`${path}: not vendored`];
+      return upstream === TEMPLATE_FILES[path] ? [] : [`${path}: the template moved`];
+    });
+  } finally {
+    at.dispose();
+  }
+}
+
+function moduleSource(files: Record<string, string>, commit: string): string {
+  return [
+    "/**",
+    ` * Vendored from ${TEMPLATE_URL} at ${commit}.`,
+    " *",
+    " * Do not edit: written by `pnpm vendor:template`, proved by `src/hosts/template.ts`'s",
+    " * scaffoldDrift, which the `agents` surface's validate() runs against the real repository.",
+    " */",
+    `export const TEMPLATE_COMMIT = ${JSON.stringify(commit)};`,
+    "",
+    "export const TEMPLATE_FILES: Record<string, string> = {",
+    ...VENDORED_PATHS.map((path) => `  ${JSON.stringify(path)}: ${JSON.stringify(files[path])},`),
+    "};",
+    "",
+  ].join("\n");
+}
+
+/** Re-vendor: read every projected file out of a checkout and rewrite the constants module. */
+export function vendor(source: string = TEMPLATE_URL): { commit: string; path: string } {
+  const at = checkout(source);
+  try {
+    const files = Object.fromEntries(
+      VENDORED_PATHS.map((path) => {
+        const content = read(at.root, path);
+        if (content === undefined) throw new Error(`${path} is not in ${source}`);
+        return [path, content];
+      }),
+    );
+    writeFileSync(VENDORED_MODULE, moduleSource(files, at.commit));
+    return { commit: at.commit, path: VENDORED_MODULE };
+  } finally {
+    at.dispose();
+  }
+}
+
+if (argv[1] === DRIFT_ENTRY) {
+  const args = argv.slice(2);
+  const write = args.includes("--write");
+  const source = args.find((argument) => !argument.startsWith("--")) ?? TEMPLATE_URL;
+  if (write) {
+    const { commit, path } = vendor(source);
+    stdout.write(`vendored ${VENDORED_PATHS.length} template files at ${commit} into ${path}\n`);
+  } else {
+    const drift = scaffoldDrift(source);
+    if (drift.length) {
+      stderr.write(
+        `the agent-config template drifted; re-run \`pnpm vendor:template\`:\n${drift
+          .map((line) => `  ${line}`)
+          .join("\n")}\n`,
+      );
+      exit(1);
+    }
+    stdout.write(
+      `the template still matches src/surfaces/agents.template.ts (vendored at ${TEMPLATE_COMMIT})\n`,
+    );
+  }
+}

package/src/hosts/web.ts

@@ -0,0 +1,111 @@
+/**
+ * The I/O half of the web surface: §8 C2, "mirror scaffolds by execution, not transcription".
+ * Runs the real generators — `npm create vite`, the Tailwind and alias steps from
+ * ui.shadcn.com/docs/installation/vite, `shadcn init` and `shadcn add` — into a temp directory,
+ * seeding it with the very files `plan()` emits, then checks that everything they write still
+ * agrees with WEB_SCAFFOLD, so an upstream default change is inherited on the next toolfactory
+ * release instead of silently rotting in a constant.
+ *
+ * Runnable as a script (`node dist/hosts/web.js <root>`) because that is how the surface's
+ * `validate()` step reaches it: one Command like every other validator.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { argv, exit, stderr, stdout } from "node:process";
+import { fileURLToPath } from "node:url";
+import type { PlannedFile, Project } from "../model.js";
+import { loadProject } from "../project/load.js";
+import { surface, TAILWIND_CSS, WEB_DIR, WEB_SCAFFOLD } from "../surfaces/web.js";
+
+export const DRIFT_ENTRY = fileURLToPath(import.meta.url);
+
+/** The scaffold's own config, which the generators read before writing anything else. */
+const SEEDED = ["vite.config.ts", "tsconfig.json", "tsconfig.app.json"];
+
+function planned(files: PlannedFile[], path: string): string {
+  const file = files.find((candidate) => candidate.path === `${WEB_DIR}/${path}`);
+  if (file?.kind !== "file") throw new Error(`the web surface no longer plans ${path}`);
+  return file.content;
+}
+
+/** JSON with the comments a tsconfig is allowed to carry. */
+function parse(text: string): unknown {
+  return JSON.parse(text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, ""));
+}
+
+function differs(label: string, upstream: unknown, pinned: unknown): string[] {
+  return JSON.stringify(upstream) === JSON.stringify(pinned)
+    ? []
+    : [`${label}: upstream and WEB_SCAFFOLD no longer agree`];
+}
+
+/** Human-readable drift lines; empty means the generators still write what WEB_SCAFFOLD says. */
+export function scaffoldDrift(project: Project): string[] {
+  const files = surface.plan(project);
+  const directory = mkdtempSync(join(tmpdir(), "toolfactory-web-"));
+  const probe = join(directory, WEB_DIR);
+  // Prefer the shadcn the page pins as a dependency over whatever is on PATH.
+  const pinned = join(project.root, WEB_DIR, "node_modules/.bin/shadcn");
+  const shadcn = (args: string[]) =>
+    existsSync(pinned)
+      ? execFileSync(pinned, [...args, "--cwd", probe], { stdio: "pipe" })
+      : execFileSync("npx", ["--yes", "shadcn@latest", ...args, "--cwd", probe], { stdio: "pipe" });
+  try {
+    execFileSync(
+      "npm",
+      ["create", "vite@latest", WEB_DIR, "--", "--template", WEB_SCAFFOLD.viteTemplate],
+      { cwd: directory, stdio: "pipe" },
+    );
+    const scaffold = (path: string) => readFileSync(join(probe, path), "utf8");
+    const drift = Object.keys(WEB_SCAFFOLD.vite).flatMap((path) =>
+      scaffold(path) === WEB_SCAFFOLD.vite[path as keyof typeof WEB_SCAFFOLD.vite]
+        ? []
+        : [`${path}: \`npm create vite\` no longer writes what WEB_SCAFFOLD.vite pins`],
+    );
+
+    // The documentation's Tailwind and alias steps, as the generated project carries them.
+    writeFileSync(join(probe, "src/index.css"), TAILWIND_CSS);
+    for (const path of SEEDED) writeFileSync(join(probe, path), planned(files, path));
+    execFileSync("npm", ["--prefix", probe, "install", "tailwindcss", "@tailwindcss/vite"], {
+      stdio: "pipe",
+    });
+    shadcn(["init", "--yes", "--base", WEB_SCAFFOLD.base, "--preset", WEB_SCAFFOLD.preset]);
+    shadcn(["add", "--yes", ...WEB_SCAFFOLD.components]);
+
+    const packageJson = JSON.parse(scaffold("package.json")) as Record<string, unknown>;
+    return [
+      ...drift,
+      ...(["scripts", "dependencies", "devDependencies"] as const).flatMap((key) =>
+        differs(`package.json ${key}`, packageJson[key], WEB_SCAFFOLD.packageJson[key]),
+      ),
+      ...differs(
+        "components.json",
+        parse(scaffold("components.json")),
+        WEB_SCAFFOLD.componentsJson,
+      ),
+      ...(scaffold("src/index.css") === WEB_SCAFFOLD.indexCss
+        ? []
+        : ["src/index.css: `shadcn init` no longer writes what WEB_SCAFFOLD.indexCss pins"]),
+      ...(scaffold("src/lib/utils.ts") === WEB_SCAFFOLD.utils
+        ? []
+        : ["src/lib/utils.ts: `shadcn init` no longer writes what WEB_SCAFFOLD.utils pins"]),
+    ];
+  } finally {
+    rmSync(directory, { recursive: true, force: true });
+  }
+}
+
+if (argv[1] === DRIFT_ENTRY) {
+  const drift = scaffoldDrift(loadProject(argv[2] ?? "."));
+  if (drift.length) {
+    stderr.write(
+      `web scaffold drifted upstream; update WEB_SCAFFOLD in src/surfaces/web.ts:\n${drift
+        .map((line) => `  ${line}`)
+        .join("\n")}\n`,
+    );
+    exit(1);
+  }
+  stdout.write("the vite + shadcn scaffold still matches src/surfaces/web.ts\n");
+}

package/src/identity/name.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { assertValidName, githubOwner, projectName } from "./name.js";
+
+describe("projectName", () => {
+  it("projects the canonical name N onto every wire-visible identifier", () => {
+    expect(projectName.npm("hello")).toBe("hello");
+    expect(projectName.npm("hello", "acme")).toBe("@acme/hello");
+    expect(projectName.npm("hello", "@acme")).toBe("@acme/hello");
+    expect(projectName.pypi("hello.tool")).toBe("hello-tool");
+    expect(projectName.pythonPackage("hello.tool-kit")).toBe("hello_tool_kit");
+    expect(projectName.cursor("hello.tool")).toBe("hello-tool");
+    expect(projectName.openclawPackage("hello")).toBe("openclaw-plugin-hello");
+    expect(projectName.mcpRegistry("hello", "acme")).toBe("io.github.acme/hello");
+    expect(projectName.hermesToolset("hello.tool-kit")).toBe("hello_tool_kit");
+  });
+});
+
+describe("githubOwner", () => {
+  it("reads the owner out of a github repository URL", () => {
+    expect(githubOwner("https://github.com/acme/hello")).toBe("acme");
+    expect(githubOwner("git@github.com:acme/hello.git")).toBe("acme");
+    expect(githubOwner(undefined)).toBeUndefined();
+    expect(githubOwner("https://example.com/acme/hello")).toBeUndefined();
+  });
+});
+
+describe("assertValidName", () => {
+  it("accepts a lowercase, hyphen/dot-separated name", () => {
+    expect(() => assertValidName("hello-tool.kit")).not.toThrow();
+  });
+
+  it("rejects a double hyphen", () => {
+    expect(() => assertValidName("Bad--Name")).toThrow(/Invalid tool name/);
+  });
+
+  it("rejects a leading hyphen", () => {
+    expect(() => assertValidName("-abc")).toThrow(/Invalid tool name/);
+  });
+
+  it("rejects uppercase", () => {
+    expect(() => assertValidName("ABC")).toThrow(/Invalid tool name/);
+  });
+});

package/src/identity/name.ts

@@ -0,0 +1,39 @@
+import { NAME_PATTERN } from "../model.js";
+
+export function assertValidName(name: string): void {
+  if (!NAME_PATTERN.test(name) || name.length > 64) {
+    throw new Error(
+      `Invalid tool name ${JSON.stringify(name)}: must match Agent Plugins ${NAME_PATTERN} and be at most 64 characters.`,
+    );
+  }
+}
+
+/** The total projection of the canonical name N onto every wire-visible identifier. */
+export const projectName = {
+  npm: (name: string, scope?: string): string =>
+    scope ? `@${scope.replace(/^@/, "")}/${name}` : name,
+  pypi: (name: string): string => name.replace(/\./g, "-"),
+  pythonPackage: (name: string): string => name.replace(/[.-]/g, "_").replace(/^(?=\d)/, "_"),
+  /** Human-facing name for manifests: words from the hyphens and dots, capitalised. */
+  display: (name: string): string =>
+    name
+      .split(/[-.]/)
+      .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+      .join(" "),
+  cursor: (name: string): string => name.replace(/\./g, "-"),
+  /** Gemini CLI extension name: the directory name rule, the same shape as Cursor's. */
+  gemini: (name: string): string => name.replace(/\./g, "-"),
+  openclawPackage: (name: string): string => `openclaw-plugin-${name}`,
+  mcpRegistry: (name: string, owner: string): string => `io.github.${owner}/${name}`,
+  hermesToolset: (name: string): string => name.replace(/[.-]/g, "_"),
+  dshPackage: (name: string): string => `${name}-dsh`,
+  /** DSH `serverName`: `[A-Za-z0-9_-]{1,32}`, validated at boot, and wire-visible as `mcp__<it>__<tool>`. */
+  dshServer: (name: string): string => name.replace(/\./g, "-").slice(0, 32),
+};
+
+/** `owner` from a GitHub repository URL, for the MCP Registry namespace. */
+export function githubOwner(repository: string | undefined): string | undefined {
+  if (!repository) return undefined;
+  const match = repository.match(/github\.com[/:]([^/]+)\/[^/#?]+/);
+  return match?.[1];
+}

package/src/identity/read.test.ts

@@ -0,0 +1,92 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { readIdentityFile } from "./read.js";
+
+let dir: string;
+
+function file(name: string, content: string): string {
+  const path = join(dir, name);
+  writeFileSync(path, content);
+  return path;
+}
+
+describe("readIdentityFile", () => {
+  afterEach(() => {
+    dir = "";
+  });
+
+  it("reads plugin.json, preserving unknown top-level keys as extra", () => {
+    dir = mkdtempSync(join(tmpdir(), "tf-identity-"));
+    const path = file(
+      "plugin.json",
+      JSON.stringify({
+        name: "hello",
+        version: "0.1.0",
+        description: "Say hello.",
+        author: { name: "Ada", email: "ada@example.com" },
+        license: "MIT",
+        extensions: { toolfactory: {} },
+      }),
+    );
+    const result = readIdentityFile(path);
+    expect(result.format).toBe("json");
+    expect(result.identity).toMatchObject({
+      name: "hello",
+      version: "0.1.0",
+      description: "Say hello.",
+      author: { name: "Ada", email: "ada@example.com" },
+      license: "MIT",
+    });
+    expect(result.extra).toEqual({ extensions: { toolfactory: {} } });
+  });
+
+  it("reads package.json, stripping the npm scope off a scoped name", () => {
+    dir = mkdtempSync(join(tmpdir(), "tf-identity-"));
+    const path = file("package.json", JSON.stringify({ name: "@acme/hello", version: "0.2.0" }));
+    const result = readIdentityFile(path);
+    expect(result.identity.name).toBe("hello");
+    expect(result.identity.version).toBe("0.2.0");
+  });
+
+  it("reads pyproject.toml", () => {
+    dir = mkdtempSync(join(tmpdir(), "tf-identity-"));
+    const path = file(
+      "pyproject.toml",
+      [
+        "[project]",
+        'name = "hello-py"',
+        'version = "0.3.0"',
+        'description = "Say hello."',
+        'authors = [{ name = "Ada", email = "ada@example.com" }]',
+        "",
+        "[project.urls]",
+        'Repository = "https://github.com/acme/hello-py"',
+        "",
+      ].join("\n"),
+    );
+    const result = readIdentityFile(path);
+    expect(result.format).toBe("toml");
+    expect(result.identity).toMatchObject({
+      name: "hello-py",
+      version: "0.3.0",
+      description: "Say hello.",
+      author: { name: "Ada", email: "ada@example.com" },
+      repository: "https://github.com/acme/hello-py",
+    });
+  });
+
+  it("reads openclaw.plugin.json off the `id` field", () => {
+    dir = mkdtempSync(join(tmpdir(), "tf-identity-"));
+    const path = file(
+      "openclaw.plugin.json",
+      JSON.stringify({ id: "hello", version: "0.1.0", commands: ["run"] }),
+    );
+    const result = readIdentityFile(path);
+    expect(result.identity.name).toBe("hello");
+    expect(result.identity.version).toBe("0.1.0");
+    // Unknown keys other than the generic identity set round-trip as extra.
+    expect(result.extra).toEqual({ commands: ["run"] });
+  });
+});

package/src/identity/read.ts

@@ -0,0 +1,119 @@
+/**
+ * Identity readers. These are shallow structural reads that pull the eight identity
+ * fields out of a file the ecosystem defines and keep every other top-level key as an
+ * opaque bag, so a rewrite never deletes what toolfactory does not understand.
+ */
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { parse as parseYaml } from "yaml";
+import type { Author, Identity } from "../model.js";
+import { assertValidName } from "./name.js";
+
+export interface IdentityFile {
+  identity: Identity;
+  extra: Record<string, unknown>;
+  /** Object → text serializer matching the source format, used when projecting back. */
+  format: "json" | "toml" | "yaml";
+}
+
+const IDENTITY_KEYS = [
+  "name",
+  "version",
+  "description",
+  "author",
+  "homepage",
+  "repository",
+  "license",
+  "keywords",
+];
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function asAuthor(value: unknown): Author | undefined {
+  if (typeof value === "string") {
+    const match = value.match(/^([^<(]+?)\s*(?:<([^>]+)>)?\s*(?:\(([^)]+)\))?\s*$/);
+    return match ? { name: match[1]?.trim(), email: match[2], url: match[3] } : { name: value };
+  }
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    return {
+      name: asString(record.name),
+      email: asString(record.email),
+      url: asString(record.url),
+    };
+  }
+  return undefined;
+}
+
+function asRepository(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") return asString((value as Record<string, unknown>).url);
+  return undefined;
+}
+
+function split(record: Record<string, unknown>, keys: string[]): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(record).filter(([key]) => !keys.includes(key)));
+}
+
+function fromGeneric(record: Record<string, unknown>, nameKey = "name"): IdentityFile {
+  const rawName = asString(record[nameKey]) ?? "";
+  const name = rawName.replace(/^@[^/]+\//, "");
+  assertValidName(name);
+  const identity: Identity = {
+    name,
+    version: asString(record.version),
+    description: asString(record.description),
+    author: asAuthor(record.author),
+    homepage: asString(record.homepage),
+    repository: asRepository(record.repository),
+    license: asString(record.license),
+    keywords: Array.isArray(record.keywords)
+      ? record.keywords.filter((k): k is string => typeof k === "string")
+      : undefined,
+  };
+  const owned = [...IDENTITY_KEYS.filter((key) => key !== "name"), nameKey];
+  return { identity, extra: split(record, owned), format: "json" };
+}
+
+function fromPyproject(text: string): IdentityFile {
+  const document = parseToml(text) as Record<string, unknown>;
+  const project = (document.project ?? {}) as Record<string, unknown>;
+  const urls = (project.urls ?? {}) as Record<string, unknown>;
+  const authors = Array.isArray(project.authors)
+    ? (project.authors as Record<string, unknown>[])
+    : [];
+  const name = asString(project.name) ?? "";
+  assertValidName(name);
+  const license = project.license;
+  const identity: Identity = {
+    name,
+    version: asString(project.version),
+    description: asString(project.description),
+    author: authors[0] ? asAuthor(authors[0]) : undefined,
+    homepage: asString(urls.Homepage ?? urls.homepage),
+    repository: asString(urls.Repository ?? urls.repository ?? urls.Source),
+    license:
+      typeof license === "string"
+        ? license
+        : asString((license as Record<string, unknown> | undefined)?.text),
+    keywords: Array.isArray(project.keywords) ? (project.keywords as string[]) : undefined,
+  };
+  return { identity, extra: document, format: "toml" };
+}
+
+/** Read the identity file named by `tool.json.identity`. */
+export function readIdentityFile(path: string): IdentityFile {
+  const text = readFileSync(path, "utf8");
+  const file = basename(path);
+  if (file === "pyproject.toml") return fromPyproject(text);
+  if (file === "plugin.yaml" || file === "plugin.yml") {
+    const document = (parseYaml(text) ?? {}) as Record<string, unknown>;
+    return { ...fromGeneric(document), format: "yaml" };
+  }
+  const document = JSON.parse(text) as Record<string, unknown>;
+  if (file === "openclaw.plugin.json") return fromGeneric(document, "id");
+  return fromGeneric(document);
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export * as commands from "./commands.js";
+export * from "./model.js";
+export { loadProject, TOOLFACTORY_VERSION } from "./project/load.js";
+export { buildPlan } from "./project/plan.js";
+export { computeCoverage } from "./report/coverage.js";
+export {
+  assertSurfaceRequirements,
+  getSurface,
+  registerSurface,
+  selectedSurfaces,
+} from "./surfaces/registry.js";