toolfactory 0.2.1 → 0.2.4

package/src/prompt/standard.ts

@@ -0,0 +1,93 @@
+/**
+ * The codex-prompt-standard rubric, as data. The prose canon is
+ * `.agents/skills/codex-prompt-standard/SKILL.md` — it ships inside the OpenClaw plugin and
+ * syncs to every dev harness; this module is the same guidance shaped for `review-prompt` to
+ * evaluate against. `review.test.ts` pins every anchor below to the canon text so the two
+ * cannot drift apart silently.
+ */
+
+export interface PromptSection {
+  id: string;
+  title: string;
+  /** Substring of the canon SKILL.md this section is pinned to (drift guard). */
+  canonAnchor: string;
+  /** Any hit marks the section present in a draft or a reference prompt. */
+  anchors: RegExp[];
+  /** The next-iteration instruction when the section is missing. */
+  directive: string;
+}
+
+/** The anatomy a Codex-class prompt reliably contains, in order (canon §2). */
+export const ANATOMY: PromptSection[] = [
+  {
+    id: "identity",
+    title: "one-sentence identity",
+    canonAnchor: "One-sentence identity",
+    anchors: [/\byou are\b/i, /\bacting (?:for|on behalf of|as)\b/i],
+    directive:
+      "Open with one sentence of identity: who the model is, where it runs, how it is expected to behave.",
+  },
+  {
+    id: "capabilities",
+    title: "capability inventory",
+    canonAnchor: "Capability inventory",
+    anchors: [/\byou can\b/i, /\bcapabilit/i, /\b(?:available|your) tools?\b/i],
+    directive: "State the capability inventory: what the agent can receive and emit.",
+  },
+  {
+    id: "how-you-work",
+    title: '"How you work" sections',
+    canonAnchor: '"How you work" sections',
+    anchors: [/how you work/i, /\bpreceden/i, /\bpersisten/i, /\bautonom/i, /\btone\b/i],
+    directive:
+      'Add "how you work" sections: personality and tone, instruction precedence, the autonomy and persistence contract.',
+  },
+  {
+    id: "planning",
+    title: "planning guidance",
+    canonAnchor: "Planning guidance",
+    anchors: [/\bplan\b/i, /\bpersist until\b/i, /before (?:acting|starting|diving)/i],
+    directive:
+      "Add planning guidance with explicit high-quality vs low-quality examples for what a good plan is.",
+  },
+  {
+    id: "execution-criteria",
+    title: "execution criteria",
+    canonAnchor: "Execution criteria",
+    anchors: [/\bMUST\b/, /\bNEVER\b/, /scope creep/i, /no unrelated changes/i],
+    directive:
+      "Add execution criteria: hard MUST/NEVER lists, root-cause fixes, no scope creep, no unrelated changes.",
+  },
+  {
+    id: "validation",
+    title: "validation philosophy",
+    canonAnchor: "Validation philosophy",
+    anchors: [/\bverify\b/i, /\bvalidat/i, /before claiming done/i, /\bdone when\b/i],
+    directive:
+      "Add the validation philosophy: start specific, broaden as confidence grows, verify before claiming done.",
+  },
+  {
+    id: "final-message",
+    title: "final-message guidance",
+    canonAnchor: "Final-message guidance",
+    anchors: [/final message/i, /\boutput depth\b/i, /\bfinal reply\b/i],
+    directive:
+      "Add final-message guidance: output depth matches task size; skip formatting for trivial replies.",
+  },
+];
+
+export interface PromptConvention {
+  id: string;
+  /** Substring of the canon SKILL.md this convention is pinned to (drift guard). */
+  canonAnchor: string;
+}
+
+/** Convention anchors the canon must mention; the checks in review.ts implement them. */
+export const CONVENTIONS: PromptConvention[] = [
+  { id: "positive-imperatives", canonAnchor: "Positive imperatives" },
+  { id: "precedence", canonAnchor: "Explicit precedence" },
+  { id: "must-never-discipline", canonAnchor: "MUST/NEVER reserved" },
+  { id: "examples", canonAnchor: "Good-vs-bad examples" },
+  { id: "harness-adaptation", canonAnchor: "Adapt to the target harness" },
+  { id: "checkable-criteria", canonAnchor: "checkable criterion" },
+];

package/src/surfaces/openclaw-native.test.ts

@@ -133,6 +133,7 @@ describe("openclaw-native", () => {
     expect(files[`${HOST_DIR}/README.md`]).toContain("`shoot` — requires browser");
 
     const pkg = JSON.parse(files[`${HOST_DIR}/package.json`] ?? "{}");
+    expect(pkg.devDependencies).toMatchObject(OPENCLAW_SCAFFOLD.devDependencies);
     expect(pkg.openclaw).toEqual({
       extensions: ["./dist/index.js"],
       compat: { pluginApi: OPENCLAW_SCAFFOLD.pluginApi },
@@ -212,6 +213,10 @@ describe("openclaw-native", () => {
 
   it("drives manifest, inspector and test from one `registers` declaration", () => {
     const target = voice();
+    target.tool.openclaw = {
+      ...target.tool.openclaw,
+      devDependencies: { openclaw: "2026.9.2", "@types/ws": "^8.18.0" },
+    };
     const files = emitted(target);
     const manifest = JSON.parse(files[`${HOST_DIR}/openclaw.plugin.json`] ?? "{}");
     expect(manifest.contracts).toEqual({ tools: [], realtimeVoiceProviders: ["codex"] });
@@ -223,6 +228,11 @@ describe("openclaw-native", () => {
     });
     // The author's extra dependency merges after the scaffold's; the core is not imported at all.
     expect(pkg.dependencies).toEqual({ ...OPENCLAW_SCAFFOLD.dependencies, ws: "^8.18.0" });
+    expect(pkg.devDependencies).toEqual({
+      ...OPENCLAW_SCAFFOLD.devDependencies,
+      openclaw: "2026.9.2",
+      "@types/ws": "^8.18.0",
+    });
     expect(pkg.peerDependencies.openclaw).toBe(">=2026.8.2");
     expect(pkg.openclaw.compat.pluginApi).toBe(">=2026.8.2");
 
@@ -312,7 +322,7 @@ function hasOpenclaw(): boolean {
 }
 
 describe.skipIf(!hasOpenclaw())("openclaw scaffold", () => {
-  it("still matches `openclaw plugins init --type tool`", () => {
+  it("still matches `openclaw plugins init --type tool`", { timeout: 60_000 }, () => {
     expect(scaffoldDrift(project())).toEqual([]);
     // A declared `pluginApi` is an intentional override, not drift.
     expect(scaffoldDrift(voice())).toEqual([]);

package/src/surfaces/openclaw-native.ts

@@ -35,7 +35,7 @@ import {
 /** Transcribed from `openclaw plugins init --type tool`; `validate()` proves them still current. */
 export const OPENCLAW_SCAFFOLD = {
   /** The OpenClaw release the scaffold was taken from (`package.json openclaw.build`). */
-  openclawVersion: "2026.9.2",
+  openclawVersion: "2026.9.4",
   /** `peerDependencies.openclaw` and `openclaw.compat.pluginApi`. */
   pluginApi: ">=2026.5.17",
   private: true,
@@ -86,6 +86,17 @@ export default defineConfig({
  * survive into the projection but allows extra ones: upstream stays the source of truth for
  * everything it does write.
  */
+/**
+ * The version `openclaw plugins init` stamps into its scaffold is the CLI's own version, so
+ * the generated manifest carries the openclaw this project actually pins (author override via
+ * `openclaw.devDependencies.openclaw`), and the scaffold default only when the project rides
+ * `latest`. hosts/openclaw.ts runs the same pin in its drift probe, so the upstream/generated
+ * comparison is identical in every environment.
+ */
+export function openclawVersion(project: Project): string {
+  return project.tool.openclaw?.devDependencies?.openclaw ?? OPENCLAW_SCAFFOLD.openclawVersion;
+}
+
 export const OPENCLAW_ADDITIONS = {
   /** Without it `tsc` emits a `dist/` from source that failed type-checking. */
   compilerOptions: { noEmitOnError: true },
@@ -123,6 +134,11 @@ export function registrations(project: Project): Registration[] {
   return project.tool.openclaw?.registers ?? [];
 }
 
+/** Whether the plugin ships `.agents/skills/` directories (`openclaw.skills` in tool.json). */
+export function shipsSkills(project: Project): boolean {
+  return (project.tool.openclaw?.skills?.length ?? 0) > 0;
+}
+
 /**
  * The gateway route and the Control UI tab the plugin adds when the tool also has a `web`
  * surface. Only for the in-process binding: the route hands requests to the core package's own
@@ -257,7 +273,7 @@ function packageJson(
     type: "module",
     private: OPENCLAW_SCAFFOLD.private,
     scripts: { ...OPENCLAW_SCAFFOLD.scripts, ...e2e },
-    files: OPENCLAW_SCAFFOLD.files,
+    files: shipsSkills(project) ? [...OPENCLAW_SCAFFOLD.files, "skills"] : OPENCLAW_SCAFFOLD.files,
     peerDependencies: { openclaw: pluginApi(project), ...extra?.peerDependencies },
     dependencies: { ...OPENCLAW_SCAFFOLD.dependencies, ...core, ...extra?.dependencies },
     devDependencies: {
@@ -268,7 +284,7 @@ function packageJson(
     openclaw: {
       extensions: [OPENCLAW_SCAFFOLD.entry],
       compat: { pluginApi: pluginApi(project) },
-      build: { openclawVersion: OPENCLAW_SCAFFOLD.openclawVersion },
+      build: { openclawVersion: openclawVersion(project) },
     },
     pluginInspector: expectedRegistrations(project, operations).length
       ? pluginInspector(project, operations)
@@ -299,6 +315,7 @@ function pluginManifest(project: Project, operations: Operation[]): Record<strin
     configSchema: configSchema(project),
     uiHints: sensitive.length ? Object.fromEntries(sensitive) : undefined,
     activation: activation(project),
+    skills: shipsSkills(project) ? ["./skills"] : undefined,
     contracts: {
       tools: operations.map((operation) => operation.name),
       ...Object.fromEntries(declared),
@@ -955,6 +972,13 @@ export const surface: Surface = {
         path: `${HOST_DIR}/vitest.config.ts`,
         content: OPENCLAW_SCAFFOLD.vitestConfig,
       },
+      ...(project.skills ?? []).flatMap((skill) =>
+        skill.files.map((file) => ({
+          kind: "file" as const,
+          path: `${HOST_DIR}/skills/${skill.name}/${file.path}`,
+          content: file.content,
+        })),
+      ),
       {
         kind: "merge",
         path: `${HOST_DIR}/openclaw.plugin.json`,

package/src/surfaces/web.test.ts

@@ -192,7 +192,7 @@ describe("web", () => {
     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("toolfactory secrets-usage check");
     expect(app).toContain('type="password"');
 
     // The smoke drives the real kernel over --http instead of a static server of its own.

package/src/surfaces/web.ts

@@ -153,8 +153,8 @@ export default defineConfig({
       "@fontsource-variable/geist": "^5.3.0",
       "@tailwindcss/vite": "^4.3.3",
       "class-variance-authority": "^0.7.1",
-      cn: "^0.2.6",
-      "lucide-react": "^1.43.0",
+      cn: "^0.3.0",
+      "lucide-react": "^1.46.0",
       react: "^19.2.8",
       "react-dom": "^19.2.8",
       shadcn: "^4.21.0",
@@ -164,11 +164,11 @@ export default defineConfig({
     devDependencies: {
       "@types/node": "^24.13.3",
       "@types/react": "^19.2.18",
-      "@types/react-dom": "^19.2.4",
-      "@vitejs/plugin-react": "^6.1.0",
-      oxlint: "^1.79.0",
+      "@types/react-dom": "^19.2.7",
+      "@vitejs/plugin-react": "^6.1.1",
+      oxlint: "^1.81.0",
       typescript: "~6.0.2",
-      vite: "^8.2.2",
+      vite: "^8.3.0",
     },
   },
   componentsJson: {
@@ -637,7 +637,7 @@ function SecretsPanel() {
         <CardTitle>Secrets</CardTitle>
         <CardDescription>
           Written to this checkout's gitignored <code>.env</code>, which the live tests and
-          <code> toolfactory bootstrap-repo</code> read. Run <code>toolfactory secrets check</code>{" "}
+          <code> toolfactory bootstrap-repo</code> read. Run <code>toolfactory secrets-usage check</code>{" "}
           to ask each registry whether it accepts them.
         </CardDescription>
       </CardHeader>

package/src/surfaces/workflows.ts

@@ -625,7 +625,7 @@ function releaseDocument(
     "`gh workflow run release.yml -f tag=vX.Y.Z` — never `gh run rerun`, which replays the",
     "original run's secret snapshot. `release` first retracts every registry a surface dropped",
     "since the previous tag published to (git is the ledger; `toolfactory unpublish`), and",
-    "`toolfactory secrets status` / `bootstrap-repo` cover the one-time steps that are left.",
+    "`toolfactory secrets-usage status` / `bootstrap-repo` cover the one-time steps that are left.",
   ];
   if (clawhubSelected) {
     jobs["publish-clawhub"] = compact({
@@ -904,7 +904,7 @@ function envExample(project: Project): string {
     lines.push(
       "",
       "# Release credentials (repository secrets; `toolfactory bootstrap-repo` pushes them from .env,",
-      "# `toolfactory secrets status` explains each). Leave one empty to skip that registry.",
+      "# `toolfactory secrets-usage status` explains each). Leave one empty to skip that registry.",
     );
     for (const row of release) {
       lines.push("", `# ${row.id}: ${row.url}`, ...row.secrets.map((name) => `${name}=`));

package/src/toolfactory/cli.ts

@@ -13,7 +13,7 @@ const operations = [...authored, web];
 const program = new Command()
   .name("toolfactory")
   .description("Build an agent tool once; ship it as Agent Skills, MCP servers, Agent Plugins / Claude / Codex / Cursor bundles, OpenClaw and Hermes plugins, CLIs, and packages, with the tests and releases to match.")
-  .version("0.2.1");
+  .version("0.2.4");
 
 for (const op of operations) {
   if (!serves(op, "cli")) continue;

package/src/toolfactory/mcp.ts

@@ -33,7 +33,7 @@ const introspecting = Boolean(process.env.TOOLFACTORY_INTROSPECT);
 
 /** Builds one server instance with every servable operation registered; called once for stdio, once per HTTP request. */
 function createServer(): McpServer {
-  const server = new McpServer({ name: "toolfactory", version: "0.2.1" });
+  const server = new McpServer({ name: "toolfactory", version: "0.2.4" });
   for (const op of operations) {
     if (!introspecting && !serves(op, "mcp")) continue;
     server.registerTool(