copillm 0.1.1 → 0.1.4

package/README.md

@@ -14,7 +14,15 @@ A local proxy that exposes OpenAI- and Anthropic-compatible HTTP endpoints backe
 
 ## Installation
 
-`copillm` is distributed on npm and can be invoked directly with `npx`. A global install is not required.
+`copillm` is distributed on [npm](https://www.npmjs.com/package/copillm). Install it globally for the most convenient usage:
+
+```bash
+npm install -g copillm
+
+copillm --help
+```
+
+Alternatively, you can invoke it directly with `npx` without a global install:
 
 ```bash
 npx copillm --help
@@ -24,12 +32,12 @@ npx copillm --help
 
 ```bash
 # Authenticate once via the GitHub device flow.
-npx copillm login
+copillm login
 
 # Launch an agent. copillm starts the local daemon, installs the agent if
 # necessary, and configures the required environment variables.
-npx copillm claude
-npx copillm codex
+copillm claude
+copillm codex
 ```
 
 Arguments after the agent name are forwarded to the underlying CLI:

package/dist/agentconfig/load.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { parse as parseToml, TomlError } from "smol-toml";
 import { ZodError } from "zod";
 import { getCopillmHome } from "../config/home.js";
-import { AgentTomlSchema, UNSET_SENTINEL } from "./schema.js";
+import { AgentTomlSchema } from "./schema.js";
 export class AgentConfigError extends Error {
     constructor(message) {
         super(message);
@@ -97,16 +97,13 @@ function mergeAndResolve(input) {
     const instructions = instructionsBody !== null && instructionsBody.trim().length > 0
         ? { body: instructionsBody }
         : null;
-    // Merge mcp.servers map; later layers replace earlier same-named entries;
-    // `inherit = "@unset"` removes an inherited entry.
+    // Merge mcp.servers map; later layers replace earlier same-named entries.
+    // Defaults are always-on: a profile may override a default by name but
+    // cannot remove it.
     const servers = {};
     for (const layer of layers) {
         const layerServers = layer.mcp?.servers ?? {};
         for (const [name, value] of Object.entries(layerServers)) {
-            if ("inherit" in value && value.inherit === UNSET_SENTINEL) {
-                delete servers[name];
-                continue;
-            }
             servers[name] = expandEnv(value);
         }
     }

package/dist/agentconfig/render.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import fs from "node:fs";
 import { stringify as stringifyToml } from "smol-toml";
 import { AgentConfigError } from "./load.js";
+import { getCopillmHome } from "../config/home.js";
 import { HASH_COMMENT, HTML_COMMENT, upsertManagedBlock } from "./markerBlock.js";
 // ─── Codex ────────────────────────────────────────────────────────────────
 export function renderCodex(input) {
@@ -79,93 +80,54 @@ const TOML_IDENT = /^[A-Za-z0-9_-]+$/;
 function isValidTomlIdent(name) {
     return TOML_IDENT.test(name);
 }
+// ─── Claude Code ──────────────────────────────────────────────────────────
+/**
+ * copillm writes Claude's MCP config to ~/.copillm/claude/mcp.json (a
+ * copillm-owned location) and injects `--mcp-config <path>` into the launch
+ * argv. This is purely additive: Claude continues to read its own project
+ * (./.mcp.json) and user (~/.claude.json) scopes, and copillm never touches
+ * cwd. Instructions fan-out is not supported for Claude — put project
+ * guidance in your own CLAUDE.md and global guidance in ~/.claude/CLAUDE.md.
+ */
 export function renderClaude(input) {
     const writes = [];
     const notes = [];
-    // 1. .mcp.json (project scope) — preserve user entries.
-    const mcpJsonPath = path.join(input.cwd, ".mcp.json");
-    const claudeMcp = renderClaudeMcp(mcpJsonPath, input.resolved.mcpServers);
-    if (claudeMcp) {
-        writes.push({
-            path: mcpJsonPath,
-            content: claudeMcp,
-            mode: 0o600,
-            description: "Claude Code .mcp.json"
-        });
-    }
-    // 2. CLAUDE.md instruction block.
-    if (input.resolved.instructions) {
-        const claudeMdPath = path.join(input.cwd, "CLAUDE.md");
-        const existing = fs.existsSync(claudeMdPath) ? fs.readFileSync(claudeMdPath, "utf8") : "";
-        const next = upsertManagedBlock(existing, input.resolved.instructions.body, HTML_COMMENT);
-        if (next !== existing) {
+    const cliArgs = [];
+    const claudeDir = path.join(getCopillmHome(), "claude");
+    const mcpJsonPath = path.join(claudeDir, "mcp.json");
+    const serverCount = Object.keys(input.resolved.mcpServers).length;
+    if (serverCount > 0) {
+        const content = renderClaudeMcp(input.resolved.mcpServers);
+        const existing = fs.existsSync(mcpJsonPath) ? fs.readFileSync(mcpJsonPath, "utf8") : null;
+        if (existing !== content) {
             writes.push({
-                path: claudeMdPath,
-                content: next,
+                path: mcpJsonPath,
+                content,
                 mode: 0o600,
-                description: "CLAUDE.md instructions block"
+                description: "Claude Code mcp.json (copillm-managed)"
             });
         }
+        cliArgs.push("--mcp-config", mcpJsonPath);
     }
-    return { writes, envOverlay: {}, cliArgs: [], notes };
-}
-function renderClaudeMcp(mcpJsonPath, servers) {
-    let existing = {};
-    if (fs.existsSync(mcpJsonPath)) {
-        try {
-            existing = JSON.parse(fs.readFileSync(mcpJsonPath, "utf8"));
-            if (typeof existing !== "object" || existing === null) {
-                throw new Error("not an object");
-            }
-        }
-        catch (error) {
-            throw new AgentConfigError(`Failed to parse ${mcpJsonPath}: ${error.message}. ` +
-                `Fix or remove the file and re-run.`);
-        }
-    }
-    const managed = new Set(existing._copillmManaged ?? []);
-    const userOwned = new Set(Object.keys(existing.mcpServers ?? {}).filter((n) => !managed.has(n)));
-    // Detect conflicts: a copillm-managed name collides with a user-owned name.
-    const newNames = Object.keys(servers);
-    for (const name of newNames) {
-        if (userOwned.has(name)) {
-            throw new AgentConfigError(`MCP server name "${name}" already exists in ${mcpJsonPath} and is owned by the user ` +
-                `(not previously managed by copillm). Rename one side, or move the user's entry ` +
-                `into agent.toml so copillm can manage it.`);
-        }
+    else if (fs.existsSync(mcpJsonPath)) {
+        // Profile no longer declares any servers — clear the stale file so we
+        // don't keep referencing dead config on the next launch.
+        fs.rmSync(mcpJsonPath, { force: true });
+        notes.push(`Removed stale ${mcpJsonPath} (no MCP servers in active profile).`);
     }
-    // Strip previously-managed entries from the user's file before adding ours.
-    const nextServers = {};
-    for (const [name, value] of Object.entries(existing.mcpServers ?? {})) {
-        if (!managed.has(name))
-            nextServers[name] = value;
+    if (input.resolved.instructions) {
+        notes.push("Claude: instructions fan-out is unsupported (Claude has no out-of-tree " +
+            "instructions hook). Move guidance to ~/.claude/CLAUDE.md or your " +
+            "project's CLAUDE.md manually.");
     }
+    return { writes, envOverlay: {}, cliArgs, notes };
+}
+function renderClaudeMcp(servers) {
+    const out = {};
     for (const [name, server] of Object.entries(servers)) {
-        nextServers[name] = serverToClaudeShape(server);
-    }
-    const nextFile = { ...existing };
-    if (Object.keys(nextServers).length > 0) {
-        nextFile.mcpServers = nextServers;
-    }
-    else {
-        delete nextFile.mcpServers;
-    }
-    if (newNames.length > 0) {
-        nextFile._copillmManaged = newNames;
-    }
-    else {
-        delete nextFile._copillmManaged;
-    }
-    const serialized = `${JSON.stringify(nextFile, null, 2)}\n`;
-    // Avoid pointless writes when state is unchanged.
-    if (fs.existsSync(mcpJsonPath) && fs.readFileSync(mcpJsonPath, "utf8") === serialized) {
-        return null;
-    }
-    // If we'd produce an empty file (no servers, no other keys), skip writing.
-    if (Object.keys(nextFile).length === 0 && !fs.existsSync(mcpJsonPath)) {
-        return null;
+        out[name] = serverToClaudeShape(server);
     }
-    return serialized;
+    return `${JSON.stringify({ mcpServers: out }, null, 2)}\n`;
 }
 function serverToClaudeShape(server) {
     if (server.transport === "stdio") {

package/dist/agentconfig/schema.js

@@ -3,12 +3,15 @@ import { z } from "zod";
  * Schema for `~/.copillm/agent.toml` (global) and `<cwd>/.copillm/agent.toml`
  * (project overlay). See plans/unified-booping-mango.md for design rationale.
  *
- * Sections under `[defaults.*]` apply to every profile; profiles override by
- * deep-merge. v1 only wires `instructions` and `mcp` into fan-out — the other
+ * Sections under `[defaults.*]` always apply, regardless of which profile is
+ * active. A profile may override a default by re-declaring an entry with the
+ * same key (e.g. `[profiles.work.mcp.servers.<name>]` replaces the same-named
+ * `[defaults.mcp.servers.<name>]`). There is no way to *remove* a default from
+ * a profile — defaults are intentionally always-on. v1 only wires
+ * `instructions` and `mcp` into fan-out — the other
  * sections (`skills`, `agents`, `hooks`, `permissions`) are reserved-but-
  * permissive so users can start populating them without future TOML breaking.
  */
-export const UNSET_SENTINEL = "@unset";
 const StringRecord = z.record(z.string());
 const McpStdioSchema = z
     .object({
@@ -28,12 +31,7 @@ const McpHttpSchema = z
     scope: z.enum(["project", "user"]).optional()
 })
     .strict();
-const McpInheritUnset = z
-    .object({
-    inherit: z.literal(UNSET_SENTINEL)
-})
-    .strict();
-export const McpServerSchema = z.union([McpStdioSchema, McpHttpSchema, McpInheritUnset]);
+export const McpServerSchema = z.union([McpStdioSchema, McpHttpSchema]);
 const InstructionsSchema = z
     .object({
     body: z.string()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copillm",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Local Copilot proxy CLI (OpenAI/Anthropic-compatible)",
   "license": "MIT",
   "type": "module",