toolfactory 0.1.1

package/dist/project/history.js

@@ -0,0 +1,41 @@
+/**
+ * Git is the release ledger (§7). Nothing records "what this project published at v0.1.0" except
+ * the commit that tag points at, so the previous selection is read straight out of it: no state
+ * file, no per-registry ledger, and nothing to keep in sync.
+ *
+ * Every function here is best-effort and never throws: a checkout with no tags, no git at all, or
+ * a tag predating `dev.toolfactory/tool.json` simply has nothing to compare against, and
+ * `unpublish` then has nothing to do.
+ */
+import { spawnSync } from "node:child_process";
+import { ToolConfigSchema } from "../model.js";
+import { TOOL_PATH } from "./load.js";
+function git(root, args) {
+    const result = spawnSync("git", args, { cwd: root, encoding: "utf8", timeout: 30_000 });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}
+/**
+ * The tag released before `ref`: `git describe --tags --abbrev=0 <ref>^`. The `^` is what makes it
+ * *previous* — on the release runner `ref` is the tag being cut, and on a working tree it is the
+ * last release behind HEAD. Undefined at the first tag, which is exactly "nothing was dropped".
+ */
+export function previousTag(root, ref = "HEAD") {
+    return git(root, ["describe", "--tags", "--abbrev=0", `${ref}^`]) || undefined;
+}
+/** `dev.toolfactory/tool.json` as of a ref, or undefined when the ref has none / it does not parse. */
+export function toolAtRef(root, ref) {
+    const text = git(root, ["show", `${ref}:${TOOL_PATH}`]);
+    if (!text)
+        return undefined;
+    try {
+        const parsed = ToolConfigSchema.safeParse(JSON.parse(text));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The surfaces a ref selected that the current selection no longer does, in the ref's own order. */
+export function droppedSurfaces(previous, current) {
+    return previous.filter((surface) => !current.includes(surface));
+}

package/dist/project/load.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { type Operation, type Project } from "../model.js";
+export declare const TOOL_PATH = "dev.toolfactory/tool.json";
+export declare const OPS_PATH = "dev.toolfactory/ops.json";
+export declare const TOOLFACTORY_VERSION: string;
+/** `ops.json`: the `tools/list` result, verbatim, sorted by name. */
+export declare const OpsSchema: z.ZodObject<{
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+export type Ops = z.infer<typeof OpsSchema>;
+export declare function toOperation(tool: Ops["tools"][number]): Operation;
+export declare function readOps(root: string): Operation[];
+export declare function loadProject(rootInput?: string): Project;

package/dist/project/load.js

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+import { readIdentityFile } from "../identity/read.js";
+import { CAPABILITIES, isInstructionOnly, PACKAGE_MANAGERS, ToolConfigSchema, } from "../model.js";
+import { TOOLFACTORY_DIR } from "./lock.js";
+export const TOOL_PATH = `${TOOLFACTORY_DIR}/tool.json`;
+export const OPS_PATH = `${TOOLFACTORY_DIR}/ops.json`;
+const require = createRequire(import.meta.url);
+export const TOOLFACTORY_VERSION = require("../../package.json").version;
+/** `ops.json`: the `tools/list` result, verbatim, sorted by name. */
+export const OpsSchema = z.object({
+    tools: z.array(z
+        .object({
+        name: z.string(),
+        title: z.string().optional(),
+        description: z.string().optional(),
+        inputSchema: z.record(z.string(), z.unknown()),
+        outputSchema: z.record(z.string(), z.unknown()).optional(),
+        annotations: z.record(z.string(), z.unknown()).optional(),
+        _meta: z.record(z.string(), z.unknown()).optional(),
+    })
+        .passthrough()),
+});
+export function toOperation(tool) {
+    const meta = (tool._meta?.["dev.toolfactory"] ?? {});
+    const declared = Array.isArray(meta.requires) ? meta.requires : [];
+    const requires = declared.filter((c) => CAPABILITIES.includes(String(c)));
+    const unknown = declared.filter((c) => !CAPABILITIES.includes(String(c)));
+    if (unknown.length) {
+        throw new Error(`Operation ${tool.name} declares unknown capabilities ${JSON.stringify(unknown)}; allowed: ${CAPABILITIES.join(", ")}`);
+    }
+    return {
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
+        annotations: tool.annotations,
+        requires,
+    };
+}
+export function readOps(root) {
+    const path = join(root, OPS_PATH);
+    if (!existsSync(path))
+        return [];
+    return OpsSchema.parse(JSON.parse(readFileSync(path, "utf8"))).tools.map(toOperation);
+}
+/** The package manager the root package.json declares (`packageManager: "pnpm@10.0.0"`), if any. */
+function readPackageManager(root) {
+    const path = join(root, "package.json");
+    if (!existsSync(path))
+        return undefined;
+    const declared = JSON.parse(readFileSync(path, "utf8"))
+        .packageManager;
+    if (!declared)
+        return undefined;
+    const name = declared.split("@")[0] ?? "";
+    if (!PACKAGE_MANAGERS.includes(name)) {
+        throw new Error(`package.json packageManager "${declared}" is not supported; toolfactory generates workflows for ${PACKAGE_MANAGERS.join(", ")}.`);
+    }
+    return name;
+}
+export function loadProject(rootInput = ".") {
+    const root = resolve(rootInput);
+    const toolPath = join(root, TOOL_PATH);
+    if (!existsSync(toolPath)) {
+        throw new Error(`${TOOL_PATH} not found in ${root}; run \`toolfactory init\` first.`);
+    }
+    const tool = ToolConfigSchema.parse(JSON.parse(readFileSync(toolPath, "utf8")));
+    const identityFile = readIdentityFile(join(root, tool.identity));
+    return {
+        root,
+        tool,
+        identity: identityFile.identity,
+        identityExtra: identityFile.extra,
+        operations: isInstructionOnly(tool) ? [] : readOps(root),
+        toolfactoryVersion: TOOLFACTORY_VERSION,
+        packageManager: readPackageManager(root),
+    };
+}

package/dist/project/lock.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export declare const TOOLFACTORY_DIR = "dev.toolfactory";
+export declare const LOCK_PATH = "dev.toolfactory/lock.json";
+/** A region's marker pair, without its content: what the lock records, and the inverse it enables. */
+export declare const MarkersSchema: z.ZodObject<{
+    begin: z.ZodString;
+    end: z.ZodString;
+}, z.core.$strip>;
+export type Markers = z.infer<typeof MarkersSchema>;
+export declare const LockSchema: z.ZodObject<{
+    toolfactoryVersion: z.ZodString;
+    files: z.ZodRecord<z.ZodString, z.ZodObject<{
+        sha256: z.ZodString;
+        state: z.ZodEnum<{
+            generated: "generated";
+            manual: "manual";
+        }>;
+        keys: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        regions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            begin: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Lock = z.infer<typeof LockSchema>;
+export declare function sha256(content: string): string;
+export declare function readLock(root: string): Lock | undefined;
+export declare function serializeLock(lock: Lock): string;

package/dist/project/lock.js

@@ -0,0 +1,42 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+export const TOOLFACTORY_DIR = "dev.toolfactory";
+export const LOCK_PATH = `${TOOLFACTORY_DIR}/lock.json`;
+/** A region's marker pair, without its content: what the lock records, and the inverse it enables. */
+export const MarkersSchema = z.object({ begin: z.string(), end: z.string() });
+export const LockSchema = z.object({
+    toolfactoryVersion: z.string(),
+    files: z.record(z.string(), z.object({
+        sha256: z.string(),
+        state: z.enum(["generated", "manual"]),
+        /**
+         * A merge file's inverse: the dotted key paths its patch wrote. Keys the current patch no
+         * longer carries are removed from the document before merging, so dropping a key from a
+         * patch — or deselecting the surface that added it — uninstalls it instead of stranding it.
+         */
+        keys: z.array(z.string()).optional(),
+        /**
+         * A region file's inverse, exactly as `keys` is a merge file's: the marker pairs its
+         * projector wrote. Regions the current plan no longer writes are emptied before the current
+         * ones are replaced, so dropping a region from a projector — or deselecting the surface that
+         * added it — uninstalls its content instead of stranding it, and a region file that leaves
+         * the plan loses its regions, not its existence.
+         */
+        regions: z.array(MarkersSchema).optional(),
+    })),
+});
+export function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+export function readLock(root) {
+    const path = join(root, LOCK_PATH);
+    if (!existsSync(path))
+        return undefined;
+    return LockSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+export function serializeLock(lock) {
+    const files = Object.fromEntries(Object.entries(lock.files).sort(([a], [b]) => a.localeCompare(b)));
+    return `${JSON.stringify({ toolfactoryVersion: lock.toolfactoryVersion, files }, null, 2)}\n`;
+}

package/dist/project/plan.d.ts

@@ -0,0 +1,5 @@
+import type { PlannedFile, Project, Surface } from "../model.js";
+export declare const COVERAGE_PATH = "dev.toolfactory/coverage.json";
+export declare const TOOL_SCHEMA_PATH = "dev.toolfactory/tool.schema.json";
+export declare function toolJsonSchema(): Record<string, unknown>;
+export declare function buildPlan(project: Project, surfaces?: Surface[]): PlannedFile[];

package/dist/project/plan.js

@@ -0,0 +1,96 @@
+/**
+ * Assemble the full plan for a project: every selected surface's files, deduplicated by
+ * path (identical content from two surfaces is fine; conflicting content is a bug), plus
+ * the derived coverage files and the published schema for tool.json.
+ */
+import { z } from "zod";
+import { getBinding } from "../bindings/index.js";
+import { isInstructionOnly, ToolConfigSchema } from "../model.js";
+import { computeCoverage, renderCoverageMarkdown } from "../report/coverage.js";
+import { assertSurfaceRequirements, getSurface, selectedSurfaces } from "../surfaces/registry.js";
+import { json } from "../surfaces/shared.js";
+import { managedContent } from "./apply.js";
+import { readLock, TOOLFACTORY_DIR } from "./lock.js";
+export const COVERAGE_PATH = `${TOOLFACTORY_DIR}/coverage.json`;
+export const TOOL_SCHEMA_PATH = `${TOOLFACTORY_DIR}/tool.schema.json`;
+export function toolJsonSchema() {
+    return z.toJSONSchema(ToolConfigSchema, { io: "input" });
+}
+/**
+ * Two projectors may own different regions of one author-owned file (`readme`'s install block and
+ * `pypi`'s mcp-name marker both live in README.md), so the plan carries their union and the
+ * template grows the marker pairs it is missing. Only the same marker holding different content is
+ * a conflict.
+ */
+function mergeRegions(base, extra) {
+    const regions = [...base.regions];
+    for (const region of extra.regions) {
+        const owner = regions.find((planned) => planned.begin === region.begin);
+        if (!owner)
+            regions.push(region);
+        else if (owner.content !== region.content) {
+            throw new Error(`Two surfaces plan different content for ${base.path} ${region.begin}.`);
+        }
+    }
+    const missing = regions.filter((region) => !base.template.includes(region.begin));
+    if (missing.length === 0)
+        return { ...base, regions };
+    const appended = missing.map((region) => `${region.begin}\n${region.end}`).join("\n");
+    return { ...base, regions, template: `${base.template}\n${appended}\n` };
+}
+function dedupe(files) {
+    const byPath = new Map();
+    for (const file of files) {
+        const existing = byPath.get(file.path);
+        if (!existing) {
+            byPath.set(file.path, file);
+        }
+        else if (existing.kind === "region" && file.kind === "region") {
+            byPath.set(file.path, mergeRegions(existing, file));
+        }
+        else if (managedContent(existing) !== managedContent(file)) {
+            throw new Error(`Two surfaces plan different content for ${file.path}.`);
+        }
+    }
+    return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+export function buildPlan(project, surfaces = selectedSurfaces(project.tool.surfaces)) {
+    // Always the declared selection, never the argument: `eject` plans one surface out of a valid one.
+    assertSurfaceRequirements(project.tool.surfaces);
+    // Workflows are always generated: ci.yml for every project, release.yml when a registry is selected.
+    // COVERAGE.md is always generated too: a one-surface table is still the record of what is excluded.
+    const withWorkflows = surfaces.some((s) => s.id === "workflows")
+        ? surfaces
+        : [...surfaces, getSurface("workflows")];
+    // AGENTS.md is always generated too, so an agent developing the tool has it from the first build.
+    const withAgents = withWorkflows.some((s) => s.id === "agents")
+        ? withWorkflows
+        : [...withWorkflows, getSurface("agents")];
+    // README.md's install region is always generated too: the one place a human or an agent
+    // reads to install what this repo ships.
+    const withReadme = withAgents.some((s) => s.id === "readme")
+        ? withAgents
+        : [...withAgents, getSurface("readme")];
+    const files = withReadme.flatMap((surface) => surface.plan(project));
+    // Instruction-only plugins are consumed as skill prose by Codex and have no executable payload.
+    if (!isInstructionOnly(project.tool)) {
+        files.push(...getBinding(project.tool.binding).kernel(project));
+        files.push(...getBinding(project.tool.binding).liveTest(project));
+    }
+    files.push({ kind: "file", path: TOOL_SCHEMA_PATH, content: json(toolJsonSchema()) });
+    const coverage = computeCoverage(project, surfaces);
+    // The machine-readable half of the coverage report is a build output; COVERAGE.md is the
+    // tracked one, so a repo cannot silently drift to majority-manual (§2.2 S5).
+    files.push({ kind: "file", path: COVERAGE_PATH, content: json(coverage), output: true });
+    const lock = readLock(project.root);
+    const manual = Object.entries(lock?.files ?? {})
+        .filter(([, entry]) => entry.state === "manual")
+        .map(([path]) => path);
+    const total = Object.keys(lock?.files ?? {}).length || files.length;
+    files.push({
+        kind: "file",
+        path: "COVERAGE.md",
+        content: renderCoverageMarkdown(coverage, manual, total),
+    });
+    return dedupe(files);
+}

package/dist/report/coverage.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Coverage: one verdict per (operation × selected surface). Degradation is omission plus
+ * an explanation, never a stub that fails at call time.
+ */
+import { type Operation, type Project, type Surface, type SurfaceId, type ToolConfig, type Verdict } from "../model.js";
+export interface CoverageRow {
+    operation: string;
+    verdicts: Record<string, Verdict>;
+}
+/** One host registration a plugin contributes beyond its operations (`openclaw.registers`). */
+export type Registration = NonNullable<NonNullable<ToolConfig["openclaw"]>["registers"]>[number];
+export interface Coverage {
+    surfaces: SurfaceId[];
+    rows: CoverageRow[];
+    /** What a plugin contributes besides operations; the whole story when there are none. */
+    contributions?: Registration[];
+}
+export declare function defaultVerdict(operation: Operation): Verdict;
+export declare function computeCoverage(project: Project, surfaces: Surface[]): Coverage;
+/** Operations that reach a surface (anything but `excluded`). */
+export declare function includedOperations(project: Project, surface: Surface): Operation[];
+export declare function renderCoverageMarkdown(coverage: Coverage, manualFiles: string[], totalFiles: number): string;

package/dist/report/coverage.js

@@ -0,0 +1,72 @@
+/**
+ * Coverage: one verdict per (operation × selected surface). Degradation is omission plus
+ * an explanation, never a stub that fails at call time.
+ */
+import { isPortable, } from "../model.js";
+export function defaultVerdict(operation) {
+    return isPortable(operation)
+        ? { kind: "native" }
+        : {
+            kind: "excluded",
+            reason: `excluded:requires-${operation.requires.filter((c) => !["net", "fs", "shell", "secret"].includes(c)).join("+")}`,
+        };
+}
+export function computeCoverage(project, surfaces) {
+    const rows = project.operations.map((operation) => ({
+        operation: operation.name,
+        verdicts: Object.fromEntries(surfaces.map((surface) => [
+            surface.id,
+            surface.verdict ? surface.verdict(operation, project) : defaultVerdict(operation),
+        ])),
+    }));
+    const contributions = project.tool.openclaw?.registers;
+    return {
+        surfaces: surfaces.map((s) => s.id),
+        rows,
+        ...(contributions?.length ? { contributions } : {}),
+    };
+}
+/** Operations that reach a surface (anything but `excluded`). */
+export function includedOperations(project, surface) {
+    return project.operations.filter((operation) => {
+        const verdict = surface.verdict
+            ? surface.verdict(operation, project)
+            : defaultVerdict(operation);
+        return verdict.kind !== "excluded";
+    });
+}
+export function renderCoverageMarkdown(coverage, manualFiles, totalFiles) {
+    const header = `| operation | ${coverage.surfaces.join(" | ")} |`;
+    const divider = `|---|${coverage.surfaces.map(() => "---").join("|")}|`;
+    const cell = (verdict) => verdict.reason ? `${verdict.kind} (${verdict.reason.replace(/^[a-z]+:/, "")})` : verdict.kind;
+    const rows = coverage.rows.map((row) => `| \`${row.operation}\` | ${coverage.surfaces.map((s) => cell(row.verdicts[s] ?? { kind: "excluded" })).join(" | ")} |`);
+    // A plugin with no operations has nothing to tabulate; what it contributes is its registrations.
+    const table = coverage.rows.length
+        ? [header, divider, ...rows]
+        : [
+            "No operation reaches a surface.",
+            ...(coverage.contributions?.length
+                ? [
+                    "",
+                    "This tool is a host plugin: what it contributes is what it registers with the host.",
+                    "",
+                    ...coverage.contributions.map((contribution) => `- \`${contribution.api}\` → \`${contribution.contract}\`: ${contribution.ids
+                        .map((id) => `\`${id}\``)
+                        .join(", ")}`),
+                ]
+                : []),
+        ];
+    const manual = manualFiles.length === 0
+        ? "All generated files are managed by toolfactory."
+        : `${manualFiles.length} of ${totalFiles} managed files adopted as manual (${Math.round((100 * manualFiles.length) / Math.max(totalFiles, 1))}%): ${manualFiles.map((f) => `\`${f}\``).join(", ")}.`;
+    return [
+        "# Coverage",
+        "",
+        "Generated by `toolfactory build`. Verdicts per operation and surface: `native` (the surface runs it as-is), `bridged` (through a named bridge), `degraded` (present with a limit), `excluded` (omitted, with the reason).",
+        "",
+        ...table,
+        "",
+        manual,
+        "",
+    ].join("\n");
+}

package/dist/report/coverage.test.d.ts

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

package/dist/report/coverage.test.js

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { surface as codex } from "../surfaces/codex.js";
+import { mcp } from "../surfaces/kernel.js";
+import { surface as skill } from "../surfaces/skill.js";
+import { computeCoverage, defaultVerdict, includedOperations, renderCoverageMarkdown, } from "./coverage.js";
+const echo = {
+    name: "echo",
+    inputSchema: { type: "object", properties: {} },
+    requires: ["fs"],
+};
+const screenshot = {
+    name: "screenshot",
+    inputSchema: { type: "object", properties: {} },
+    requires: ["browser"],
+};
+const notify = {
+    name: "notify",
+    inputSchema: { type: "object", properties: {} },
+    requires: ["channel"],
+};
+function project() {
+    return {
+        root: "/repo",
+        tool: {
+            schemaVersion: 1,
+            identity: "package.json",
+            binding: "typescript",
+            surfaces: ["skill", "mcp", "codex"],
+            bundle: { runtime: "package" },
+            tests: { examples: {} },
+        },
+        identity: { name: "hello", version: "1.0.0" },
+        identityExtra: {},
+        operations: [echo, screenshot, notify],
+        toolfactoryVersion: "0.1.0",
+    };
+}
+describe("defaultVerdict", () => {
+    it("is native for a portable operation and excluded, reasoned, otherwise", () => {
+        expect(defaultVerdict(echo)).toEqual({ kind: "native" });
+        expect(defaultVerdict(screenshot)).toEqual({
+            kind: "excluded",
+            reason: "excluded:requires-browser",
+        });
+    });
+});
+describe("computeCoverage across skill, mcp, codex", () => {
+    const coverage = computeCoverage(project(), [skill, mcp, codex]);
+    const verdicts = Object.fromEntries(coverage.rows.map((row) => [row.operation, row.verdicts]));
+    it("a portable operation is bridged on skill, native on mcp, degraded (loader-unverified) on codex", () => {
+        expect(verdicts.echo.skill).toEqual({ kind: "bridged", reason: "bridged:agent-mediated" });
+        expect(verdicts.echo.mcp).toEqual({ kind: "native" });
+        expect(verdicts.echo.codex).toEqual({ kind: "degraded", reason: "degraded:loader-unverified" });
+    });
+    it("a browser operation is bridged on skill, excluded (no host capabilities) on mcp and codex", () => {
+        expect(verdicts.screenshot.skill).toEqual({
+            kind: "bridged",
+            reason: "bridged:agent-mediated",
+        });
+        expect(verdicts.screenshot.mcp).toEqual({
+            kind: "excluded",
+            reason: "excluded:mcp-no-host-capabilities",
+        });
+        expect(verdicts.screenshot.codex).toEqual({
+            kind: "excluded",
+            reason: "excluded:mcp-no-host-capabilities",
+        });
+    });
+    it("a channel operation is excluded everywhere, with skill naming the missing channel bridge", () => {
+        expect(verdicts.notify.skill).toEqual({
+            kind: "excluded",
+            reason: "excluded:no-channel-bridge",
+        });
+        expect(verdicts.notify.mcp).toEqual({
+            kind: "excluded",
+            reason: "excluded:mcp-no-host-capabilities",
+        });
+        expect(verdicts.notify.codex).toEqual({
+            kind: "excluded",
+            reason: "excluded:mcp-no-host-capabilities",
+        });
+    });
+    it("includedOperations drops exactly what its surface excludes", () => {
+        expect(includedOperations(project(), skill).map((o) => o.name)).toEqual(["echo", "screenshot"]);
+        expect(includedOperations(project(), mcp).map((o) => o.name)).toEqual(["echo"]);
+    });
+    it("renderCoverageMarkdown puts every surface as a column and every verdict's reason in the cell", () => {
+        const markdown = renderCoverageMarkdown(coverage, [], 3);
+        expect(markdown).toContain("| operation | skill | mcp | codex |");
+        expect(markdown).toContain("bridged (agent-mediated)");
+        expect(markdown).toContain("All generated files are managed by toolfactory.");
+    });
+});

package/dist/surfaces/agent-plugins.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Agent Plugins 1.0.0 bundle: `plugin.json` is the authored identity file (never written
+ * here), `mcp.json` points at the kernel, `skills/` comes from the skill surface.
+ * Validation is Ajv against the cached official schemas; the spec forbids fetching at load.
+ */
+import type { Project, Surface } from "../model.js";
+export declare const MCP_SCHEMA_ID = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+export declare const PLUGIN_SCHEMA_ID = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+export declare function assertBundleIdentity(project: Project): void;
+export declare const surface: Surface;

package/dist/surfaces/agent-plugins.js

@@ -0,0 +1,36 @@
+import { json, kernelLaunch, mcpVerdict } from "./shared.js";
+export const MCP_SCHEMA_ID = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+export const PLUGIN_SCHEMA_ID = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+export function assertBundleIdentity(project) {
+    if (project.tool.identity !== "plugin.json") {
+        throw new Error(`Surface "agent-plugins" requires plugin.json as the identity file (tool.json.identity is "${project.tool.identity}").`);
+    }
+}
+export const surface = {
+    id: "agent-plugins",
+    plan(project) {
+        assertBundleIdentity(project);
+        const launch = kernelLaunch(project, "${PLUGIN_ROOT}");
+        return [
+            {
+                kind: "file",
+                path: "mcp.json",
+                content: json({
+                    $schema: MCP_SCHEMA_ID,
+                    mcpServers: { [project.identity.name]: { type: "stdio", ...launch } },
+                }),
+            },
+        ];
+    },
+    validate(project) {
+        return [
+            {
+                label: "agent-plugins schema",
+                command: "toolfactory",
+                args: ["validate", "--surface", "agent-plugins"],
+                cwd: project.root,
+            },
+        ];
+    },
+    verdict: mcpVerdict,
+};

package/dist/surfaces/agents.d.ts

@@ -0,0 +1,35 @@
+import { type Project, type Surface } from "../model.js";
+export declare const AGENTS_PATH = "AGENTS.md";
+export declare const AGENTS_BEGIN = "<!-- tf:agents -->";
+export declare const AGENTS_END = "<!-- /tf:agents -->";
+export declare const SETUP_PATH = ".agents/setup";
+export declare const SETUP_BEGIN = "# tf:setup";
+export declare const SETUP_END = "# /tf:setup";
+export declare const IGNORE_PATH = ".gitignore";
+export declare const IGNORE_BEGIN = "# tf:ignore";
+export declare const IGNORE_END = "# /tf:ignore";
+export declare const SERVERS_PATH = ".agents/mcp/servers.json";
+/**
+ * What it takes for a harness to see a newly registered MCP server, a new skill or an edited
+ * `AGENTS.md`. One table: the generated Reload section renders it, and `init` prints the single
+ * `line` of whichever harness it is running inside (`reloadLine`). Reload is the one part of
+ * registration a repository cannot automate, so the honest replacement for "restart your agent"
+ * is one accurate sentence per harness, generated from here.
+ */
+export interface Reload {
+    harness: string;
+    /** Environment variables whose presence means this process is inside that harness. */
+    env: string[];
+    /** What a new MCP server registration needs before the session can call it. */
+    mcp: string;
+    /** What a new or edited skill, or an edited `AGENTS.md`, needs. */
+    instructions: string;
+    /** The line `init` prints when it detects this harness; harnesses with no marker have none. */
+    line?: string;
+}
+export declare const RELOAD: Reload[];
+export declare const RELOAD_FALLBACK = "Your harness reads `AGENTS.md` and `.agents/skills/` directly; for MCP config, restart it or use its own reload command \u2014 the Reload table in `AGENTS.md` names one per harness.";
+/** The one reload line that matches the harness this process is running inside. */
+export declare function reloadLine(environment: NodeJS.ProcessEnv): string;
+export declare function agentsContent(project: Project): string;
+export declare const surface: Surface;