create-codemodekit 0.3.0 → 0.4.0

package/skills/build-codemodekit-plugin/SKILL.md

@@ -1,44 +0,0 @@
----
-name: build-codemodekit-plugin
-description: Scaffold, retrofit, or maintain CodeModeKit servers and portable Agent Plugins with companion runtime skills. Use when creating a Code Mode MCP wrapper from an MCP command, adding Agent Plugins 1.0 packaging, refreshing generated tool TypeScript, configuring tool policy, installing a plugin into Cursor, or diagnosing a generated CodeModeKit project.
----
-
-# Build a CodeModeKit Plugin
-
-Prefer CodeModeKit's generator and lifecycle commands over hand-writing manifests, bundles, or generated tool declarations.
-
-## Create a new project
-
-1. Identify a short source name and a shell-free MCP executable plus arguments.
-2. Run:
-
-   ```sh
-   npm create codemodekit@latest <directory> -- \
-     --mcp-name <source-name> \
-     --mcp-command '<executable> [args...]' \
-     --agent-plugin
-   ```
-
-3. Inspect `src/server.mjs`, `plugin.json`, `mcp.json`, and the generated runtime skill before changing defaults.
-4. Keep credentials outside committed files. Pass an env-file argument to the upstream executable when it supports one; do not embed secrets in `mcp.json`.
-5. Run `npm run plugin:sync` after credentials and the upstream MCP are available.
-6. Run `npm run plugin:build` to recreate the self-contained `dist/plugin` package.
-7. Test `npm start` through an MCP client and confirm both `run_typescript` and `search_tools` are advertised.
-
-Read [references/generator.md](references/generator.md) for flags and lifecycle commands.
-
-## Update an existing project
-
-Preserve the one-file server unless the integration genuinely needs more structure. Use `scaffoldAgentPlugin` for portable manifests and the companion skill, and use `syncAgentPluginSkill` with the project's `CodeMode` instance to refresh catalog-derived references. Never hand-edit `tools.d.ts`; it is generated output.
-
-Read [references/programmatic-api.md](references/programmatic-api.md) for the builder contracts and [references/plugin-layout.md](references/plugin-layout.md) for generated-file ownership.
-
-## Validate
-
-- Treat a failed dependency install or plugin build as a generator failure; do not report the project as ready.
-- Treat a failed catalog sync as recoverable when the upstream MCP merely needs credentials or connectivity. Keep the pending references and report the exact `npm run plugin:sync` follow-up.
-- Reject partial snapshots when any source is unavailable.
-- Keep `SKILL.md` procedural and compact. Put generated schemas, TypeScript declarations, result semantics, and examples in `references/`.
-- Tell runtime agents to search large declaration references for focused matches instead of loading an entire catalog into context.
-- Preserve `search_tools` as a live fallback for pending, stale, or dynamic catalogs.
-- Reinstall the Cursor copy after changing source, policy, metadata, or generated references.

package/skills/build-codemodekit-plugin/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Build CodeModeKit Plugin"
-  short_description: "Scaffold and maintain CodeModeKit Agent Plugins"
-  default_prompt: "Build or update a portable CodeModeKit Agent Plugin with a companion runtime skill."

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

@@ -1,42 +0,0 @@
-# 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

@@ -1,38 +0,0 @@
-# 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

@@ -1,48 +0,0 @@
-# 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.