create-codemodekit 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,32 @@
 # create-codemodekit
 
-Scaffold a runnable, one-file Code Mode MCP server from an upstream MCP command.
+Scaffold a runnable, one-file Code Mode MCP server from Local Tools, an upstream MCP command, or a remote MCP URL.
+
+## Build with a coding agent
+
+Install CodeModeKit's development skills, then ask your agent to build the server:
+
+```sh
+npx skills add stjbrown/codemodekit
+```
+
+The skills can also be installed separately with `--skill build-codemodekit-server` or `--skill author-codemode-skill`. The generator below installs both automatically, so this step is for existing projects or a skill-first workflow.
+
+## Interactive weather starter
+
+```sh
+npm create codemodekit@latest
+```
+
+The default creates an editable Open-Meteo weather project, companion skill, and portable Agent Plugin. The equivalent non-interactive command is:
+
+```sh
+npm create codemodekit@latest weather-code-mode -- --example weather
+```
+
+The generated server uses two Local Tools—`findLocation` and `getCurrentWeather`—to demonstrate multi-call composition inside one `run_typescript` execution. No API key is required for Open-Meteo's limited non-commercial endpoint. Use the generated `.env.example` for customer or self-hosted endpoints.
+
+## Wrap an MCP command
 
 ```sh
 npm create codemodekit@latest my-code-mode -- \
@@ -8,13 +34,27 @@ npm create codemodekit@latest my-code-mode -- \
   --mcp-command 'uvx my-mcp-server'
 
 cd my-code-mode
+npm run verify
 npm start
 ```
 
-The command is parsed directly into an executable and argument array. Shell operators, shell expansion, and leading environment assignments are rejected; no shell is invoked. Dependency installation is automatic unless `--no-install` is supplied. A project-level CodeModeKit authoring skill is installed at `.agents/skills/build-codemodekit-plugin` by default; use `--no-authoring-skill` to omit it.
+The command is parsed directly into an executable and argument array. Shell operators, shell expansion, and leading environment assignments are rejected; no shell is invoked. Dependency installation is automatic unless `--no-install` is supplied. The `build-codemodekit-server` and `author-codemode-skill` development skills are installed under `.agents/skills` by default; use `--no-authoring-skill` to omit both.
 
 Generated servers use `--policy allow-all` by default so the project runs immediately. Use `--policy deny-all` when you want the generated server to start closed while you define a narrower tool policy.
 
+Use `--mcp-url https://example.com/mcp` instead of `--mcp-command` for a Streamable HTTP source. Add `--mcp-bearer-env MCP_TOKEN` or repeat `--mcp-header-env Header-Name=ENV_NAME` to assemble authentication headers from the host environment without writing credential values to source, manifests, or plugin artifacts.
+
+Repeat a complete source group to combine MCPs in one generated catalog:
+
+```sh
+npm create codemodekit@latest work-code-mode -- \
+  --mcp-name github --mcp-command 'docker run -i --rm ghcr.io/github/github-mcp-server' \
+  --mcp-name tickets --mcp-url https://tickets.example.com/mcp \
+  --mcp-bearer-env TICKETS_TOKEN
+```
+
+Every scaffold includes `npm run verify`. It validates source discovery, the two-tool downstream surface, invalid calls, and sandbox isolation without calling provider tools. For a semantic live check, set `CODEMODEKIT_VERIFY_CODE_FILE` to a bounded TypeScript composition that returns `{ verified: true }`. The generated `.env.example` is documentation; export its variables with your preferred environment manager.
+
 ## Generate an Agent Plugin
 
 Add `--agent-plugin` to create a portable Agent Plugins 1.0 package around the Code Mode server:
@@ -26,7 +66,7 @@ npm create codemodekit@latest my-code-mode -- \
   --agent-plugin
 ```
 
-This adds root `plugin.json` and `mcp.json` files plus `skills/use-upstream-codemode/`. The companion skill teaches a runtime agent to compose calls through `run_typescript`; its `references/tools.d.ts` is generated from CodeModeKit's live normalized catalog. After installation, the generator also builds a self-contained `dist/plugin` artifact containing the server bundle, QuickJS WASM, manifests, and runtime skill.
+This adds root `plugin.json` and `mcp.json` files plus `skills/use-upstream-codemode/`. The generated companion skill is a mechanically correct runtime baseline. Catalog sync writes a complete `references/tools.d.ts`, one file per source, and bounded tool-prefix shards for large sources; `catalog-metadata.json` indexes the set. Use the installed `author-codemode-skill` to add domain triggers, real workflows, safety decisions, and type-correct compositions. After installation, the generator builds a self-contained `dist/plugin` artifact containing the server bundle, QuickJS WASM, manifests, and runtime skill.
 
 The generator attempts catalog sync after dependency installation. If the upstream MCP still needs credentials or connectivity, the project remains valid with pending references. Configure the source and run:
 
@@ -35,7 +75,7 @@ npm run plugin:sync
 npm run plugin:build
 ```
 
-Use `--no-sync` to skip the initial attempt intentionally. The artifact deliberately excludes `node_modules`, `.env`, source files, and the development-time authoring skill.
+Use `--no-sync` to skip the initial attempt intentionally. The artifact deliberately excludes `node_modules`, `.env`, source files, and both development-time authoring skills.
 
 ## Cursor lifecycle
 
@@ -53,4 +93,4 @@ Installation rebuilds first, copies the artifact beneath `~/.cursor/plugins/loca
 
 Use `--plugin-name`, `--skill-name`, `--plugin-description`, and `--plugin-license` with `--agent-plugin` to override the portable defaults.
 
-Programmatic consumers can call `scaffoldCodeModeMcp`, `scaffoldAgentPlugin`, `syncAgentPluginSkill`, `buildAgentPlugin`, `installProjectAuthoringSkill`, and the Cursor lifecycle functions directly.
+Programmatic consumers can call `scaffoldCodeModeMcp`, `scaffoldAgentPlugin`, `syncAgentPluginSkill`, `buildAgentPlugin`, `installProjectAuthoringSkills`, and the Cursor lifecycle functions directly. The singular `installProjectAuthoringSkill` remains available for compatibility.

package/dist/agent-plugin.d.ts

@@ -1,3 +1,5 @@
+import { type AgentPluginTypeScriptCatalog } from "./catalog-files.js";
+export type { AgentPluginTypeScriptCatalog, AgentPluginTypeScriptCatalogShard, AgentPluginTypeScriptCatalogSource, } from "./catalog-files.js";
 export interface AgentPluginCatalogSource {
     start(signal?: AbortSignal): Promise<AgentPluginStartupReport>;
     getTypeScriptCatalog(signal?: AbortSignal): Promise<AgentPluginTypeScriptCatalog>;
@@ -14,10 +16,6 @@ export interface AgentPluginSourceReport {
     readonly message?: string;
     readonly rejectedToolCount?: number;
 }
-export interface AgentPluginTypeScriptCatalog {
-    readonly catalogRevision: string;
-    readonly declarations: string;
-}
 export interface ScaffoldAgentPluginOptions {
     readonly root: string;
     readonly pluginName: string;
@@ -46,12 +44,14 @@ export interface SyncAgentPluginSkillResult {
     readonly skillDirectory: string;
     readonly catalogRevision: string;
     readonly declarations: string;
+    readonly declarationFiles: readonly string[];
     readonly metadata: string;
     readonly sources: readonly AgentPluginSourceReport[];
 }
 /**
- * Writes the portable Agent Plugins 1.0 wrapper and a compact companion skill.
- * Tool-specific declarations are populated later by syncAgentPluginSkill.
+ * Writes the portable Agent Plugins 1.0 wrapper and a mechanical runtime-skill
+ * baseline. Tool-specific declarations are populated by syncAgentPluginSkill;
+ * domain workflows remain agent- and developer-authored.
  */
 export declare function scaffoldAgentPlugin(options: ScaffoldAgentPluginOptions): Promise<ScaffoldAgentPluginResult>;
 /**
@@ -66,5 +66,4 @@ interface RenderCompanionSkillOptions {
     readonly serverName: string;
 }
 export declare function renderCompanionSkill(options: RenderCompanionSkillOptions): string;
-export {};
 //# sourceMappingURL=agent-plugin.d.ts.map

package/dist/agent-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-plugin.d.ts","sourceRoot":"","sources":["../src/agent-plugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-plugin.d.ts","sourceRoot":"","sources":["../src/agent-plugin.ts"],"names":[],"mappings":"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"}

package/dist/agent-plugin.js

@@ -1,11 +1,13 @@
-import { mkdir, rename, writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { catalogDeclarationFiles, commitCatalogSnapshot, } from "./catalog-files.js";
 const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
 const MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
 const PORTABLE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
 /**
- * Writes the portable Agent Plugins 1.0 wrapper and a compact companion skill.
- * Tool-specific declarations are populated later by syncAgentPluginSkill.
+ * Writes the portable Agent Plugins 1.0 wrapper and a mechanical runtime-skill
+ * baseline. Tool-specific declarations are populated by syncAgentPluginSkill;
+ * domain workflows remain agent- and developer-authored.
  */
 export async function scaffoldAgentPlugin(options) {
     const root = path.resolve(options.root);
@@ -51,9 +53,13 @@ export async function scaffoldAgentPlugin(options) {
         writeFile(path.join(referencesDirectory, "examples.md"), renderExamplesReference(), "utf8"),
         writeFile(path.join(referencesDirectory, "tools.d.ts"), renderPendingDeclarations(), "utf8"),
         writeJson(path.join(referencesDirectory, "catalog-metadata.json"), {
-            schemaVersion: 1,
+            schemaVersion: 2,
             status: "pending",
             serverName,
+            declarations: [
+                { path: "tools.d.ts", scope: "catalog", toolCount: 0 },
+            ],
+            generatedFiles: ["tools.d.ts"],
             message: "Run npm run plugin:sync after the upstream tool source is available.",
         }),
     ]);
@@ -87,11 +93,12 @@ export async function syncAgentPluginSkill(options) {
     const skillDirectory = path.join(root, "skills", skillName);
     const referencesDirectory = path.join(skillDirectory, "references");
     await mkdir(referencesDirectory, { recursive: true });
+    const declarationFiles = catalogDeclarationFiles(snapshot.catalog);
     const declarationsPath = path.join(referencesDirectory, "tools.d.ts");
     const metadataPath = path.join(referencesDirectory, "catalog-metadata.json");
-    const declarations = renderCatalogDeclarations(snapshot.catalog.catalogRevision, snapshot.catalog.declarations);
+    const totalToolCount = snapshot.startup.sources.reduce((total, source) => total + source.toolCount, 0);
     const metadata = {
-        schemaVersion: 1,
+        schemaVersion: 2,
         status: "ready",
         serverName,
         catalogRevision: snapshot.catalog.catalogRevision,
@@ -103,15 +110,24 @@ export async function syncAgentPluginSkill(options) {
                 ? {}
                 : { rejectedToolCount: source.rejectedToolCount }),
         })),
+        declarations: declarationFiles.map((file) => ({
+            path: file.path,
+            scope: file.scope,
+            toolCount: file.scope === "catalog" ? totalToolCount : file.toolCount,
+            ...(file.source === undefined ? {} : { source: file.source }),
+            ...(file.prefixes === undefined ? {} : { prefixes: file.prefixes }),
+        })),
+        generatedFiles: declarationFiles.map((file) => file.path),
     };
-    await Promise.all([
-        atomicWrite(declarationsPath, declarations),
-        atomicWrite(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`),
-    ]);
+    await commitCatalogSnapshot(referencesDirectory, new Map([
+        ...declarationFiles.map((file) => [file.path, file.contents]),
+        ["catalog-metadata.json", `${JSON.stringify(metadata, null, 2)}\n`],
+    ]));
     return {
         skillDirectory,
         catalogRevision: snapshot.catalog.catalogRevision,
         declarations: declarationsPath,
+        declarationFiles: declarationFiles.map((file) => path.join(referencesDirectory, file.path)),
         metadata: metadataPath,
         sources: snapshot.startup.sources,
     };
@@ -139,12 +155,14 @@ description: ${JSON.stringify(description)}
 
 # Use ${serverName} Code Mode
 
+This generated baseline covers Code Mode mechanics and the live tool catalog. Maintainers should tailor its trigger description, workflows, safety decisions, and examples to the integration's real users before distribution.
+
 Use \`run_typescript\` as the primary interface to the tools wrapped by this server.
 
-1. Locate the relevant declarations in [references/tools.d.ts](references/tools.d.ts) before authoring calls. Search large files by capability, source, or tool name and read only focused matches.
+1. Read [references/catalog-metadata.json](references/catalog-metadata.json) as the declaration-file index. Open the narrowest listed prefix or source shard that covers the request; use [references/tools.d.ts](references/tools.d.ts) only for cross-source work or when no narrower shard applies.
 2. Put related calls, result extraction, filtering, and reshaping into one \`run_typescript\` execution.
-3. Return only the bounded value needed to answer the user.
-4. Use \`search_tools\` when the generated catalog is pending or stale, does not contain the needed capability, or the client cannot search a large declaration reference efficiently.
+3. Return only the bounded value needed to answer the user. Project requested fields, omit empty metadata, cap collections, and summarize large result sets instead of returning raw upstream payloads.
+4. Use \`search_tools\` when the generated catalog is pending or stale, does not contain the needed capability, or the available client cannot search declaration files efficiently.
 5. Treat tool errors as data you can catch and handle; do not bypass tool policy or sandbox limits.
 
 Read [references/runtime.md](references/runtime.md) for execution rules, [references/result-contract.md](references/result-contract.md) for MCP result extraction, and [references/examples.md](references/examples.md) for composition patterns.
@@ -160,9 +178,9 @@ The server exposes a small Code Mode surface:
 
 The sandbox exposes \`tools\` and a limited set of safe JavaScript globals. It does not expose Node.js modules, filesystem APIs, process APIs, network APIs, dynamic imports, or arbitrary package imports.
 
-Prefer one execution that calls, combines, and reduces upstream results. Use \`Promise.all\` only for independent operations. Keep the final return value small; do not return raw payloads when a projection or summary is sufficient.
+Prefer one execution that calls, combines, and reduces upstream results. Use \`Promise.all\` only for independent operations. Project requested fields, remove null or empty metadata, cap collections to the smallest useful number of rows, and return counts or summaries for larger sets. Do not return raw upstream payloads.
 
-The generated declaration snapshot is authoritative for its recorded catalog revision. If a call is missing or fails with \`TOOL_NOT_FOUND\`, use \`search_tools\` to inspect the live catalog and then refresh the snapshot with \`npm run plugin:sync\` when maintaining the plugin.
+The generated declaration snapshot is authoritative for its recorded catalog revision. \`catalog-metadata.json\` indexes the complete catalog, per-source files, and bounded tool-prefix shards. Start with the narrowest applicable shard so unrelated declarations stay out of context. If a call is missing or fails with \`TOOL_NOT_FOUND\`, use \`search_tools\` to inspect the live catalog and then refresh the snapshot with \`npm run plugin:sync\` when maintaining the plugin.
 `;
 }
 function renderResultContractReference() {
@@ -190,7 +208,7 @@ Tool failures throw a catchable \`ToolCallError\` with \`code\`, \`phase\`, and
 function renderExamplesReference() {
     return `# Composition examples
 
-Replace the source, tool, and input names with declarations from \`tools.d.ts\`.
+Replace the source, tool, and input names with declarations from the narrowest file indexed by \`catalog-metadata.json\`.
 
 ## Extract structured data
 
@@ -238,12 +256,6 @@ function renderPendingDeclarations() {
 // Run: npm run plugin:sync
 `;
 }
-function renderCatalogDeclarations(revision, declarations) {
-    return `// Generated by CodeModeKit from catalog revision ${revision}.
-// Refresh with: npm run plugin:sync
-
-${declarations.trim()}\n`;
-}
 async function stableCatalogSnapshot(codeMode, signal) {
     for (let attempt = 0; attempt < 3; attempt += 1) {
         const startup = await codeMode.start(signal);
@@ -257,11 +269,6 @@ async function stableCatalogSnapshot(codeMode, signal) {
 async function writeJson(file, value) {
     await writeFile(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
-async function atomicWrite(file, contents) {
-    const temporary = `${file}.${String(process.pid)}.tmp`;
-    await writeFile(temporary, contents, "utf8");
-    await rename(temporary, file);
-}
 function validatePortableName(value, label) {
     const name = required(value, label);
     if (name.length > 64 || !PORTABLE_NAME.test(name)) {

package/dist/agent-plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-plugin.js","sourceRoot":"","sources":["../src/agent-plugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-plugin.js","sourceRoot":"","sources":["../src/agent-plugin.ts"],"names":[],"mappings":"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"}

package/dist/authoring-skill.d.ts

@@ -1,7 +1,14 @@
+import { type InstallCodeModeKitSkillsResult } from "@codemodekit/skills";
 export interface InstallProjectAuthoringSkillOptions {
     readonly root: string;
     readonly overwrite?: boolean;
 }
-/** Installs CodeModeKit's development-time skill into the universal project path. */
+/** Installs both CodeModeKit development skills into the universal project path. */
+export declare function installProjectAuthoringSkills(options: InstallProjectAuthoringSkillOptions): Promise<InstallCodeModeKitSkillsResult>;
+/**
+ * Installs the original server-building role for compatibility. New generators
+ * install both roles through installProjectAuthoringSkills.
+ */
 export declare function installProjectAuthoringSkill(options: InstallProjectAuthoringSkillOptions): Promise<string>;
+export type { InstallCodeModeKitSkillsResult } from "@codemodekit/skills";
 //# sourceMappingURL=authoring-skill.d.ts.map

package/dist/authoring-skill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authoring-skill.d.ts","sourceRoot":"","sources":["../src/authoring-skill.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,qFAAqF;AACrF,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,mCAAmC,GAC3C,OAAO,CAAC,MAAM,CAAC,CAuBjB"}
+{"version":3,"file":"authoring-skill.d.ts","sourceRoot":"","sources":["../src/authoring-skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,8BAA8B,EACpC,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,oFAAoF;AACpF,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,mCAAmC,GAC3C,OAAO,CAAC,8BAA8B,CAAC,CAEzC;AAED;;;GAGG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,mCAAmC,GAC3C,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,YAAY,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/authoring-skill.js

@@ -1,42 +1,21 @@
-import { cp, lstat, mkdir, rename, rm } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-const AUTHORING_SKILL_NAME = "build-codemodekit-plugin";
-const BUNDLED_SKILL_DIRECTORY = fileURLToPath(new URL(`../skills/${AUTHORING_SKILL_NAME}`, import.meta.url));
-/** Installs CodeModeKit's development-time skill into the universal project path. */
-export async function installProjectAuthoringSkill(options) {
-    const root = path.resolve(options.root);
-    const skillsRoot = path.join(root, ".agents", "skills");
-    const destination = path.join(skillsRoot, AUTHORING_SKILL_NAME);
-    const staging = path.join(skillsRoot, `.${AUTHORING_SKILL_NAME}.${String(process.pid)}.${String(Date.now())}.tmp`);
-    if ((await pathExists(destination)) && options.overwrite !== true) {
-        throw new Error(`Authoring skill already exists: ${destination}`);
-    }
-    await mkdir(skillsRoot, { recursive: true });
-    await rm(staging, { recursive: true, force: true });
-    await cp(BUNDLED_SKILL_DIRECTORY, staging, { recursive: true });
-    try {
-        await rm(destination, { recursive: true, force: true });
-        await rename(staging, destination);
-    }
-    catch (error) {
-        await rm(staging, { recursive: true, force: true });
-        throw error;
-    }
-    return destination;
+import { installCodeModeKitSkills, } from "@codemodekit/skills";
+/** Installs both CodeModeKit development skills into the universal project path. */
+export function installProjectAuthoringSkills(options) {
+    return installCodeModeKitSkills(options);
 }
-async function pathExists(file) {
-    try {
-        await lstat(file);
-        return true;
-    }
-    catch (error) {
-        if (error instanceof Error &&
-            "code" in error &&
-            error.code === "ENOENT") {
-            return false;
-        }
-        throw error;
+/**
+ * Installs the original server-building role for compatibility. New generators
+ * install both roles through installProjectAuthoringSkills.
+ */
+export async function installProjectAuthoringSkill(options) {
+    const result = await installCodeModeKitSkills({
+        ...options,
+        skills: ["build-codemodekit-server"],
+    });
+    const directory = result.directories["build-codemodekit-server"];
+    if (directory === undefined) {
+        throw new Error("The CodeModeKit server-building skill was not installed");
     }
+    return directory;
 }
 //# sourceMappingURL=authoring-skill.js.map

package/dist/authoring-skill.js.map

@@ -1 +1 @@
-{"version":3,"file":"authoring-skill.js","sourceRoot":"","sources":["../src/authoring-skill.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AACxD,MAAM,uBAAuB,GAAG,aAAa,CAC3C,IAAI,GAAG,CAAC,aAAa,oBAAoB,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAC9D,CAAC;AAOF,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,OAA4C;IAE5C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IACxD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,oBAAoB,CAAC,CAAC;IAChE,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CACvB,UAAU,EACV,IAAI,oBAAoB,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAC5E,CAAC;IACF,IAAI,CAAC,MAAM,UAAU,CAAC,WAAW,CAAC,CAAC,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;QAClE,MAAM,IAAI,KAAK,CAAC,mCAAmC,WAAW,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,EAAE,CAAC,uBAAuB,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,MAAM,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IACE,KAAK,YAAY,KAAK;YACtB,MAAM,IAAI,KAAK;YACd,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAClD,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"authoring-skill.js","sourceRoot":"","sources":["../src/authoring-skill.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,GAEzB,MAAM,qBAAqB,CAAC;AAO7B,oFAAoF;AACpF,MAAM,UAAU,6BAA6B,CAC3C,OAA4C;IAE5C,OAAO,wBAAwB,CAAC,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,OAA4C;IAE5C,MAAM,MAAM,GAAG,MAAM,wBAAwB,CAAC;QAC5C,GAAG,OAAO;QACV,MAAM,EAAE,CAAC,0BAA0B,CAAC;KACrC,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,0BAA0B,CAAC,CAAC;IACjE,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/catalog-files.d.ts

@@ -0,0 +1,28 @@
+export interface AgentPluginTypeScriptCatalog {
+    readonly catalogRevision: string;
+    readonly declarations: string;
+    readonly sources?: readonly AgentPluginTypeScriptCatalogSource[];
+}
+export interface AgentPluginTypeScriptCatalogSource {
+    readonly source: string;
+    readonly toolCount: number;
+    readonly declarations: string;
+    readonly shards: readonly AgentPluginTypeScriptCatalogShard[];
+}
+export interface AgentPluginTypeScriptCatalogShard {
+    readonly key: string;
+    readonly prefixes: readonly string[];
+    readonly toolCount: number;
+    readonly declarations: string;
+}
+export interface CatalogDeclarationFile {
+    readonly path: string;
+    readonly scope: "catalog" | "source" | "prefix";
+    readonly source?: string;
+    readonly prefixes?: readonly string[];
+    readonly toolCount: number;
+    readonly contents: string;
+}
+export declare function catalogDeclarationFiles(catalog: AgentPluginTypeScriptCatalog): readonly CatalogDeclarationFile[];
+export declare function commitCatalogSnapshot(referencesDirectory: string, files: ReadonlyMap<string, string>): Promise<void>;
+//# sourceMappingURL=catalog-files.d.ts.map

package/dist/catalog-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-files.d.ts","sourceRoot":"","sources":["../src/catalog-files.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,kCAAkC,EAAE,CAAC;CAClE;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,SAAS,iCAAiC,EAAE,CAAC;CAC/D;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,4BAA4B,GACpC,SAAS,sBAAsB,EAAE,CA0DnC;AAED,wBAAsB,qBAAqB,CACzC,mBAAmB,EAAE,MAAM,EAC3B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,OAAO,CAAC,IAAI,CAAC,CAoEf"}

package/dist/catalog-files.js

@@ -0,0 +1,193 @@
+import { createHash, randomUUID } from "node:crypto";
+import { access, mkdir, readdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import path from "node:path";
+export function catalogDeclarationFiles(catalog) {
+    const files = [
+        {
+            path: "tools.d.ts",
+            scope: "catalog",
+            toolCount: catalog.sources?.reduce((total, source) => total + source.toolCount, 0) ?? 0,
+            contents: renderCatalogDeclarations(catalog.catalogRevision, catalog.declarations),
+        },
+    ];
+    const usedPaths = new Map([["tools.d.ts", "catalog"]]);
+    const sourceSegments = collisionSafeSegments((catalog.sources ?? []).map((source) => source.source));
+    for (const source of catalog.sources ?? []) {
+        const sourceSegment = sourceSegments.get(source.source) ?? safeFilenameSegment(source.source);
+        files.push({
+            path: allocateDeclarationPath([sourceSegment], `source:${source.source}`, usedPaths),
+            scope: "source",
+            source: source.source,
+            toolCount: source.toolCount,
+            contents: renderCatalogDeclarations(catalog.catalogRevision, source.declarations),
+        });
+        for (const shard of source.shards) {
+            const identity = `prefix:${source.source}:${shard.key}:` + shard.prefixes.join("\u0000");
+            files.push({
+                path: allocateDeclarationPath([sourceSegment, safeFilenameSegment(shard.key)], identity, usedPaths),
+                scope: "prefix",
+                source: source.source,
+                prefixes: shard.prefixes,
+                toolCount: shard.toolCount,
+                contents: renderCatalogDeclarations(catalog.catalogRevision, shard.declarations),
+            });
+        }
+    }
+    return files;
+}
+export async function commitCatalogSnapshot(referencesDirectory, files) {
+    const transaction = path.join(referencesDirectory, `.codemodekit-sync-${String(process.pid)}-${randomUUID()}`);
+    const incoming = path.join(transaction, "incoming");
+    const backup = path.join(transaction, "backup");
+    const incomingNames = [...files.keys()];
+    for (const name of incomingNames) {
+        validateGeneratedFilename(name);
+    }
+    await Promise.all([
+        mkdir(incoming, { recursive: true }),
+        mkdir(backup, { recursive: true }),
+    ]);
+    try {
+        await Promise.all([...files].map(([name, contents]) => writeFile(path.join(incoming, name), contents, "utf8")));
+        const existingNames = await ownedCatalogFiles(referencesDirectory);
+        const backedUp = [];
+        const committed = [];
+        try {
+            for (const name of existingNames) {
+                if (await fileExists(path.join(referencesDirectory, name))) {
+                    await rename(path.join(referencesDirectory, name), path.join(backup, name));
+                    backedUp.push(name);
+                }
+            }
+            const commitOrder = incomingNames
+                .filter((name) => name !== "catalog-metadata.json")
+                .concat(incomingNames.includes("catalog-metadata.json")
+                ? ["catalog-metadata.json"]
+                : []);
+            for (const name of commitOrder) {
+                await rename(path.join(incoming, name), path.join(referencesDirectory, name));
+                committed.push(name);
+            }
+        }
+        catch (error) {
+            await Promise.allSettled(committed.map((name) => rm(path.join(referencesDirectory, name), { force: true })));
+            for (const name of backedUp) {
+                await rename(path.join(backup, name), path.join(referencesDirectory, name));
+            }
+            throw error;
+        }
+    }
+    finally {
+        await rm(transaction, { recursive: true, force: true });
+    }
+}
+function collisionSafeSegments(values) {
+    const byBase = new Map();
+    for (const value of values) {
+        const base = safeFilenameSegment(value);
+        byBase.set(base, [...(byBase.get(base) ?? []), value]);
+    }
+    const result = new Map();
+    for (const [base, collisions] of byBase) {
+        for (const value of collisions) {
+            result.set(value, collisions.length === 1 ? base : `${base}-${shortHash(value)}`);
+        }
+    }
+    return result;
+}
+function allocateDeclarationPath(segments, identity, used) {
+    const base = `tools.${segments.join(".")}.d.ts`;
+    const existing = used.get(base);
+    if (existing === undefined || existing === identity) {
+        used.set(base, identity);
+        return base;
+    }
+    const stem = `tools.${segments.join(".")}-${shortHash(identity)}`;
+    let attempt = 1;
+    while (true) {
+        const candidate = `${stem}${attempt === 1 ? "" : `-${String(attempt)}`}.d.ts`;
+        const collision = used.get(candidate);
+        if (collision === undefined || collision === identity) {
+            used.set(candidate, identity);
+            return candidate;
+        }
+        attempt += 1;
+    }
+}
+function safeFilenameSegment(value) {
+    const normalized = value
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/gu, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, "-")
+        .replace(/-+/gu, "-")
+        .replace(/^-|-$/gu, "");
+    if (normalized === "") {
+        return `item-${shortHash(value)}`;
+    }
+    if (normalized.length <= 48) {
+        return normalized;
+    }
+    return `${normalized.slice(0, 39).replace(/-$/u, "")}-${shortHash(value)}`;
+}
+function shortHash(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 8);
+}
+function renderCatalogDeclarations(revision, declarations) {
+    return `// Generated by CodeModeKit from catalog revision ${revision}.
+// Refresh with: npm run plugin:sync
+
+${declarations.trim()}\n`;
+}
+async function ownedCatalogFiles(referencesDirectory) {
+    const owned = new Set(["tools.d.ts", "catalog-metadata.json"]);
+    const metadataPath = path.join(referencesDirectory, "catalog-metadata.json");
+    try {
+        const metadata = JSON.parse(await readFile(metadataPath, "utf8"));
+        if (Array.isArray(metadata.generatedFiles)) {
+            for (const name of metadata.generatedFiles) {
+                if (typeof name === "string" && isGeneratedFilename(name)) {
+                    owned.add(name);
+                }
+            }
+        }
+    }
+    catch {
+        // Legacy metadata is recovered by inspecting generated declaration headers.
+    }
+    try {
+        const entries = await readdir(referencesDirectory, { withFileTypes: true });
+        await Promise.all(entries.map(async (entry) => {
+            if (!entry.isFile() || !isGeneratedFilename(entry.name))
+                return;
+            const contents = await readFile(path.join(referencesDirectory, entry.name), "utf8");
+            if (contents.startsWith("// Generated by CodeModeKit") ||
+                contents.startsWith("// CodeModeKit catalog snapshot pending")) {
+                owned.add(entry.name);
+            }
+        }));
+    }
+    catch {
+        // The caller creates this directory; absence means there is no prior snapshot.
+    }
+    return [...owned].sort();
+}
+function validateGeneratedFilename(name) {
+    if (!isGeneratedFilename(name) && name !== "catalog-metadata.json") {
+        throw new TypeError(`Invalid generated catalog filename: ${name}`);
+    }
+}
+function isGeneratedFilename(name) {
+    return (path.basename(name) === name &&
+        /^tools(?:\.[a-z0-9-]+)*\.d\.ts$/u.test(name));
+}
+async function fileExists(file) {
+    try {
+        await access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=catalog-files.js.map