toolfactory 0.1.1

package/dist/hosts/github.js

@@ -0,0 +1,247 @@
+/**
+ * Everything toolfactory does to a GitHub repository: creating and pushing it (`init --repo`),
+ * and preparing the T4 live tier — an environment with required reviewers and the secrets inside
+ * it, the two things GitHub only exposes over its API. All of it through the official `gh` CLI
+ * (§8 C1: own no client), never a hand-rolled HTTP call, and all of it optional: a project with
+ * no GitHub at all never reaches this file.
+ *
+ * Secret values are read from the local `.env`, piped to `gh` on stdin, and never written to a
+ * command line, a log line, or the returned result.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseEnv } from "node:util";
+import { envName, has, liveCredentials, npmName } from "../surfaces/shared.js";
+/** The GitHub environment the generated `live` job deploys to. */
+export const LIVE_ENVIRONMENT = "live-tests";
+/** `owner/repo` from a GitHub URL or `git@` remote. */
+export function githubSlug(repository) {
+    const match = repository?.match(/github\.com[/:]([^/]+)\/([^/#?]+?)(?:\.git)?(?:[/#?]|$)/);
+    return match ? `${match[1]}/${match[2]}` : undefined;
+}
+function gh(args, stdin, cwd) {
+    return execFileSync("gh", args, {
+        cwd,
+        encoding: "utf8",
+        input: stdin,
+        stdio: ["pipe", "pipe", "inherit"],
+    }).trim();
+}
+/** npm trust's direct-publish permission flags landed in npm 11.15.0. */
+function supportsNpmTrust() {
+    const result = spawnSync("npm", ["--version"], { encoding: "utf8", timeout: 10_000 });
+    const version = result.status === 0 ? result.stdout.trim() : "unavailable";
+    const [major = 0, minor = 0] = version.split(".").map(Number);
+    return { ok: major > 11 || (major === 11 && minor >= 15), version };
+}
+export function bootstrapRepo(project, options = {}) {
+    const repository = options.repository ?? githubSlug(project.identity.repository);
+    if (!repository) {
+        throw new Error("bootstrap-repo needs a GitHub repository URL in the identity file to know which repo to prepare.");
+    }
+    const { reviewers = [], dryRun = false, releaseSecrets = [] } = options;
+    // npm setup below reports its actual result, replacing the generic status instructions.
+    const manual = (options.manual ?? []).filter((step) => !step.startsWith("npm:"));
+    const envFile = options.envFile ?? join(project.root, ".env");
+    const values = existsSync(envFile) ? parseEnv(readFileSync(envFile, "utf8")) : {};
+    const keys = liveCredentials(project);
+    const commands = [];
+    const written = [];
+    const missing = [];
+    // The live tier's own environment, and only when the project has a live tier: a `tool.json`
+    // config key that is both required and sensitive is the whole trigger (§6 T4).
+    if (keys.length) {
+        const ids = reviewers.map((login) => {
+            const args = ["api", `users/${login}`, "--jq", ".id"];
+            commands.push(`gh ${args.join(" ")}`);
+            return dryRun ? `<id of ${login}>` : gh(args);
+        });
+        const body = JSON.stringify(reviewers.length
+            ? { reviewers: ids.map((id) => ({ type: "User", id: Number(id) || id })) }
+            : {});
+        const environmentArgs = [
+            "api",
+            "--method",
+            "PUT",
+            `repos/${repository}/environments/${LIVE_ENVIRONMENT}`,
+            "--input",
+            "-",
+        ];
+        commands.push(`gh ${environmentArgs.join(" ")} <<< '${body}'`);
+        if (!dryRun)
+            gh(environmentArgs, body);
+    }
+    // Two scopes, one loop: a config key is the live job's, a registry token is the release's, and
+    // one `gh secret set -f .env` could not tell them apart. The value goes in on stdin either way,
+    // so it never reaches argv (`ps`), a log line, or this result.
+    const scoped = [
+        ...keys.map((key) => [envName(key), ["--env", LIVE_ENVIRONMENT]]),
+        ...[...new Set(releaseSecrets)].map((name) => [name, []]),
+    ];
+    for (const [name, scope] of scoped) {
+        if (!dryRun && !values[name]) {
+            missing.push(name);
+            continue;
+        }
+        const args = ["secret", "set", name, ...scope, "--repo", repository];
+        commands.push(`gh ${args.join(" ")}  # value from ${envFile}, on stdin`);
+        if (!dryRun)
+            gh(args, values[name]);
+        written.push(name);
+    }
+    // Pages: a workflow's own token cannot enable it (`GITHUB_TOKEN` has no `administration` key at
+    // all), but a local `gh` session is a repository admin, which is exactly the bar. Idempotent:
+    // 404 from the read means "not enabled yet", anything else means it already is.
+    if (has(project, "web")) {
+        const read = ["api", `repos/${repository}/pages`];
+        const create = [
+            "api",
+            "--method",
+            "POST",
+            `repos/${repository}/pages`,
+            "-f",
+            "build_type=workflow",
+        ];
+        commands.push(`gh ${read.join(" ")} || gh ${create.join(" ")}`);
+        if (!dryRun && !try_(() => gh(read)))
+            try_(() => gh(create));
+    }
+    // npm trusted publishing, so the release can use OIDC — but only once the package exists.
+    // npm trust requires an interactive, logged-in 2FA session; granular bypass-2FA tokens are
+    // explicitly unsupported, so never smuggle NPM_TOKEN into this command.
+    if (releaseSecrets.includes("NPM_TOKEN")) {
+        const pkg = npmName(project);
+        const trustArgs = [
+            "trust",
+            "github",
+            pkg,
+            "--file",
+            "release.yml",
+            "--repo",
+            repository,
+            "--allow-publish",
+            "-y",
+        ];
+        const trust = `npm ${trustArgs.join(" ")}`;
+        const confirmArgs = [
+            "variable",
+            "set",
+            "NPM_TRUSTED_PUBLISHER",
+            "-b",
+            "true",
+            "--repo",
+            repository,
+        ];
+        const confirm = `gh ${confirmArgs.join(" ")}`;
+        const manualTrust = `npm: \`${trust}\` requires npm@11.15+, a package that already exists, and a logged-in 2FA session; granular access tokens with bypass 2FA are unsupported. Run it from that session, then \`${confirm}\`. Until it succeeds, NPM_TOKEN is the release fallback.`;
+        const published = !dryRun &&
+            spawnSync("npm", ["view", pkg, "version"], { stdio: "ignore", timeout: 60_000 }).status === 0;
+        if (!published) {
+            manual.push(`npm: the first publish uses NPM_TOKEN because \`npm trust\` requires the package to exist. Afterwards ${manualTrust.slice("npm: ".length)}`);
+        }
+        else {
+            const npm = supportsNpmTrust();
+            if (!npm.ok) {
+                manual.push(`npm: did not run \`${trust}\` because npm ${npm.version} lacks npm@11.15+'s --allow-publish permission. Install npm@^11.15 in the logged-in 2FA session, then ${manualTrust.slice("npm: ".length)}`);
+            }
+            else if (!process.stdin.isTTY || !process.stdout.isTTY) {
+                manual.push(`npm: run bootstrap-repo from an interactive terminal for npm's 2FA challenge. ${manualTrust.slice("npm: ".length)}`);
+            }
+            else {
+                commands.push(trust);
+                const result = spawnSync("npm", trustArgs, { stdio: "inherit", timeout: 120_000 });
+                if (result.status !== 0) {
+                    manual.push(`npm: \`${trust}\` exited ${result.status}. ${manualTrust.slice("npm: ".length)}`);
+                }
+                else {
+                    commands.push(confirm);
+                    try {
+                        gh(confirmArgs);
+                    }
+                    catch {
+                        manual.push(`npm: trusted publishing was configured, but \`${confirm}\` did not succeed. Run it before relying on OIDC; NPM_TOKEN remains the release fallback until then.`);
+                    }
+                }
+            }
+        }
+    }
+    return {
+        repository,
+        environment: LIVE_ENVIRONMENT,
+        reviewers,
+        secrets: written,
+        missing,
+        commands,
+        manual,
+        dryRun,
+    };
+}
+/** `gh` exits non-zero for "not found" as readily as for a real failure; both mean "keep going". */
+function try_(call) {
+    try {
+        call();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * One GitHub topic per selected surface, so a repository `init` creates is discoverable as what
+ * it actually ships. Surfaces that only package the same tool (`cli`, `npm`, `pypi`, `web`,
+ * `clawhub`, `workflows`) name no ecosystem and get none.
+ */
+export const SURFACE_TOPICS = {
+    skill: "agent-skill",
+    "agent-plugins": "agent-plugins",
+    claude: "claude-plugin",
+    codex: "codex-plugin",
+    cursor: "cursor-plugin",
+    mcp: "mcp-server",
+    "mcp-registry": "mcp-registry",
+    "openclaw-native": "openclaw-plugin",
+    "hermes-native": "hermes-plugin",
+    dsh: "dsh-plugin",
+};
+/** `gh <args>`, copy-pasteable: only arguments that need quoting get it. */
+function render(args) {
+    return `gh ${args.map((arg) => (/[\s"'$]/.test(arg) ? JSON.stringify(arg) : arg)).join(" ")}`;
+}
+/**
+ * Create the repository from the checkout and push it: `gh repo create --source --remote --push`,
+ * private unless asked otherwise, then one `gh repo edit --add-topic` for the selected surfaces.
+ * `gh` is the only GitHub client (§8 C1); nothing here talks to the API directly.
+ */
+export function createRepo(project, options) {
+    const { slug, dryRun = false } = options;
+    if (!/^[^/\s]+\/[^/\s]+$/.test(slug)) {
+        throw new Error(`repo takes owner/name, not ${JSON.stringify(slug)}.`);
+    }
+    const visibility = options.public ? "public" : "private";
+    const topics = [
+        ...new Set(project.tool.surfaces
+            .flatMap((surface) => SURFACE_TOPICS[surface] ?? [])
+            .concat("toolfactory")),
+    ];
+    const commands = [];
+    const create = [
+        "repo",
+        "create",
+        slug,
+        `--${visibility}`,
+        ...(project.identity.description ? ["--description", project.identity.description] : []),
+        "--source",
+        ".",
+        "--remote",
+        "origin",
+        "--push",
+    ];
+    const edit = ["repo", "edit", slug, "--add-topic", topics.join(",")];
+    for (const args of [create, edit]) {
+        commands.push(render(args));
+        if (!dryRun)
+            gh(args, undefined, project.root);
+    }
+    return { repository: slug, visibility, topics, commands, dryRun };
+}

package/dist/hosts/openclaw.d.ts

@@ -0,0 +1,4 @@
+import type { Project } from "../model.js";
+export declare const DRIFT_ENTRY: string;
+/** Human-readable drift lines; empty means the generator still mirrors upstream. */
+export declare function scaffoldDrift(project: Project): string[];

package/dist/hosts/openclaw.js

@@ -0,0 +1,94 @@
+/**
+ * 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 { 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) {
+    const openclaw = project.tool.openclaw;
+    const paths = new Set();
+    for (const section of ["dependencies", "peerDependencies", "devDependencies"]) {
+        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, ours, path, skip) {
+    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;
+    return Object.entries(scaffold).flatMap(([key, value]) => path === "" && PER_TOOL_KEYS.has(key) ? [] : missing(value, right[key], `${path}.${key}`, skip));
+}
+function planned(files, path) {
+    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) {
+    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) => 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/dist/hosts/template.d.ts

@@ -0,0 +1,15 @@
+export declare const DRIFT_ENTRY: string;
+export declare 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 declare const VENDORED_PATHS: string[];
+/** Human-readable drift lines; empty means the vendored copy is still the template's own bytes. */
+export declare function scaffoldDrift(source?: string): string[];
+/** Re-vendor: read every projected file out of a checkout and rewrite the constants module. */
+export declare function vendor(source?: string): {
+    commit: string;
+    path: string;
+};

package/dist/hosts/template.js

@@ -0,0 +1,142 @@
+/**
+ * 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) {
+    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) {
+    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, path) {
+    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 = TEMPLATE_URL) {
+    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, commit) {
+    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 = TEMPLATE_URL) {
+    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/dist/hosts/web.d.ts

@@ -0,0 +1,4 @@
+import type { Project } from "../model.js";
+export declare const DRIFT_ENTRY: string;
+/** Human-readable drift lines; empty means the generators still write what WEB_SCAFFOLD says. */
+export declare function scaffoldDrift(project: Project): string[];

package/dist/hosts/web.js

@@ -0,0 +1,89 @@
+/**
+ * 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 { 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, path) {
+    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) {
+    return JSON.parse(text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, ""));
+}
+function differs(label, upstream, pinned) {
+    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) {
+    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) => 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) => readFileSync(join(probe, path), "utf8");
+        const drift = Object.keys(WEB_SCAFFOLD.vite).flatMap((path) => scaffold(path) === WEB_SCAFFOLD.vite[path]
+            ? []
+            : [`${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"));
+        return [
+            ...drift,
+            ...["scripts", "dependencies", "devDependencies"].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/dist/identity/name.d.ts

@@ -0,0 +1,20 @@
+export declare function assertValidName(name: string): void;
+/** The total projection of the canonical name N onto every wire-visible identifier. */
+export declare const projectName: {
+    npm: (name: string, scope?: string) => string;
+    pypi: (name: string) => string;
+    pythonPackage: (name: string) => string;
+    /** Human-facing name for manifests: words from the hyphens and dots, capitalised. */
+    display: (name: string) => string;
+    cursor: (name: string) => string;
+    /** Gemini CLI extension name: the directory name rule, the same shape as Cursor's. */
+    gemini: (name: string) => string;
+    openclawPackage: (name: string) => string;
+    mcpRegistry: (name: string, owner: string) => string;
+    hermesToolset: (name: string) => string;
+    dshPackage: (name: string) => string;
+    /** DSH `serverName`: `[A-Za-z0-9_-]{1,32}`, validated at boot, and wire-visible as `mcp__<it>__<tool>`. */
+    dshServer: (name: string) => string;
+};
+/** `owner` from a GitHub repository URL, for the MCP Registry namespace. */
+export declare function githubOwner(repository: string | undefined): string | undefined;

package/dist/identity/name.js

@@ -0,0 +1,33 @@
+import { NAME_PATTERN } from "../model.js";
+export function assertValidName(name) {
+    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, scope) => scope ? `@${scope.replace(/^@/, "")}/${name}` : name,
+    pypi: (name) => name.replace(/\./g, "-"),
+    pythonPackage: (name) => name.replace(/[.-]/g, "_").replace(/^(?=\d)/, "_"),
+    /** Human-facing name for manifests: words from the hyphens and dots, capitalised. */
+    display: (name) => name
+        .split(/[-.]/)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" "),
+    cursor: (name) => name.replace(/\./g, "-"),
+    /** Gemini CLI extension name: the directory name rule, the same shape as Cursor's. */
+    gemini: (name) => name.replace(/\./g, "-"),
+    openclawPackage: (name) => `openclaw-plugin-${name}`,
+    mcpRegistry: (name, owner) => `io.github.${owner}/${name}`,
+    hermesToolset: (name) => name.replace(/[.-]/g, "_"),
+    dshPackage: (name) => `${name}-dsh`,
+    /** DSH `serverName`: `[A-Za-z0-9_-]{1,32}`, validated at boot, and wire-visible as `mcp__<it>__<tool>`. */
+    dshServer: (name) => name.replace(/\./g, "-").slice(0, 32),
+};
+/** `owner` from a GitHub repository URL, for the MCP Registry namespace. */
+export function githubOwner(repository) {
+    if (!repository)
+        return undefined;
+    const match = repository.match(/github\.com[/:]([^/]+)\/[^/#?]+/);
+    return match?.[1];
+}

package/dist/identity/name.test.d.ts

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