create-codemodekit 0.2.0 → 0.3.0

package/skills/build-codemodekit-plugin/references/generator.md

@@ -0,0 +1,42 @@
+# Generator reference
+
+## Minimal server
+
+```sh
+npm create codemodekit@latest my-code-mode -- \
+  --mcp-name upstream \
+  --mcp-command 'uvx upstream-mcp'
+```
+
+Dependency installation is automatic. Use `--no-install` only when installation must happen later. The generator also installs this development-time skill at `.agents/skills/build-codemodekit-plugin`; use `--no-authoring-skill` to omit it.
+
+## Agent Plugin
+
+Add `--agent-plugin` to generate the portable manifests, companion Agent Skill, catalog references, and self-contained `dist/plugin` artifact. After installation, the generator attempts a live catalog sync. Use `--no-sync` to leave the references pending intentionally.
+
+The generated package includes:
+
+```json
+{
+  "scripts": {
+    "start": "node src/server.mjs",
+    "plugin:sync": "node src/server.mjs --sync-plugin",
+    "plugin:build": "codemodekit-plugin build",
+    "plugin:install:cursor": "codemodekit-plugin install cursor",
+    "plugin:status:cursor": "codemodekit-plugin status cursor",
+    "plugin:uninstall:cursor": "codemodekit-plugin uninstall cursor"
+  }
+}
+```
+
+`plugin:install:cursor` rebuilds the artifact, copies it into Cursor's local plugin directory, and resolves concrete Node and server paths for Cursor. Reload Cursor after install. Re-run the command after source or catalog changes.
+
+## Tool policy
+
+`--policy allow-all` is the runnable default. It allows every tool advertised by configured sources, subject to restrictions enforced by the upstream server itself.
+
+Use `--policy deny-all` when the generated server must begin closed. Replace the policy in `src/server.mjs` with an explicit application policy before expecting tool calls to succeed.
+
+## Command parsing
+
+`--mcp-command` is parsed into one executable and an argument array without a shell. Quotes and backslash escaping are supported. Pipes, redirects, command substitution, and leading environment assignments are rejected.

package/skills/build-codemodekit-plugin/references/plugin-layout.md

@@ -0,0 +1,38 @@
+# Generated plugin layout
+
+```text
+my-code-mode/
+├── .agents/skills/build-codemodekit-plugin/
+├── dist/plugin/
+│   ├── emscripten-module.wasm
+│   ├── mcp.json
+│   ├── plugin.json
+│   ├── server.mjs
+│   └── skills/
+├── package.json
+├── plugin.json
+├── mcp.json
+├── src/
+│   └── server.mjs
+└── skills/
+    └── use-upstream-codemode/
+        ├── SKILL.md
+        └── references/
+            ├── catalog-metadata.json
+            ├── examples.md
+            ├── result-contract.md
+            ├── runtime.md
+            └── tools.d.ts
+```
+
+## Ownership
+
+- The developer owns `src/server.mjs`, tool policy, provider configuration, and plugin metadata.
+- CodeModeKit owns generated `tools.d.ts`, `catalog-metadata.json`, and `dist/plugin`.
+- The generated runtime `SKILL.md` contains stable procedure and should stay small.
+- `runtime.md`, `result-contract.md`, and `examples.md` are scaffolded reference templates and may be tailored when an integration needs additional guidance.
+- `.agents/skills/build-codemodekit-plugin` is development-time authoring guidance and is intentionally excluded from the portable plugin artifact.
+
+`mcp.json` exposes the bundled Code Mode server to an Agent Plugins client. The upstream MCP remains configured inside `src/server.mjs`; it is not exposed as a second direct server that would bypass Code Mode policy and sandboxing.
+
+The portable `dist/plugin/mcp.json` uses `${PLUGIN_ROOT}` as required by Agent Plugins. Cursor installation produces a separate concrete copy because Cursor currently needs absolute executable and server paths for local plugins.

package/skills/build-codemodekit-plugin/references/programmatic-api.md

@@ -0,0 +1,48 @@
+# Programmatic API
+
+Import the builders from `create-codemodekit`.
+
+## Scaffold the full project
+
+```ts
+import { parseMcpCommand, scaffoldCodeModeMcp } from "create-codemodekit";
+
+const result = await scaffoldCodeModeMcp({
+  targetDirectory: "my-code-mode",
+  mcpName: "upstream",
+  mcpCommand: parseMcpCommand("uvx upstream-mcp"),
+  agentPlugin: true,
+});
+```
+
+Installation and the project authoring skill default to enabled. Pass `install: false` or `authoringSkill: false` only when intentionally deferring those steps.
+
+`agentPlugin` also accepts configuration:
+
+```ts
+agentPlugin: {
+  pluginName: "my-code-mode",
+  skillName: "use-my-code-mode",
+  description: "Use the upstream service through Code Mode.",
+  license: "Apache-2.0",
+  sync: true,
+}
+```
+
+## Scaffold only plugin components
+
+Use `scaffoldAgentPlugin` when a project already owns its server entrypoint. It writes `plugin.json`, `mcp.json`, the companion `SKILL.md`, and pending references.
+
+Use `buildAgentPlugin` to create the dependency-free `dist/plugin` artifact. Use `installCursorPlugin`, `getCursorPluginStatus`, and `uninstallCursorPlugin` for Cursor's concrete local copy.
+
+Use `installProjectAuthoringSkill` to add the bundled development-time skill to an existing project at `.agents/skills/build-codemodekit-plugin`.
+
+## Refresh references
+
+Call `syncAgentPluginSkill` with a started or startable CodeModeKit `CodeMode` instance. The function reads the revisioned TypeScript catalog, rejects degraded or unstable snapshots, and atomically replaces `references/tools.d.ts` and `references/catalog-metadata.json`.
+
+Close the Code Mode application in a `finally` block after syncing.
+
+## Observe execution
+
+The high- and low-level constructors accept an `observer` callback. Use it for metrics, tracing, and audit correlation. Events contain IDs, source/tool names, byte counts, durations, outcomes, and stable error codes; they intentionally exclude authored code, arguments, results, logs, and diagnostic messages. Keep payload logging as a separate, explicit host decision.