milagre 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Milagre contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# Milagre CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run agents on a computer without opening a desktop UI. Requires Node.js 24+, Git, and at least one installed, signed-in agent CLI (Claude Code or Codex).
+
+Start the server with npm:
+
+```sh
+npx milagre serve
+```
+
+Or install the command globally:
+
+```sh
+npm install --global milagre
+milagre serve
+```
+
+`milagre help` lists the commands. Use `milagre help serve` or `milagre serve --help` for a command's flags and examples. Help uses color in interactive terminals and plain text when piped; `NO_COLOR` disables color.
+
+`serve` runs in the foreground and uses `~/.milagre/server` for its persistent profile. It prints a private pairing link and, in an interactive terminal, a phone QR code. In another desktop's Settings > Devices > Add computer, paste the link. Approve the computer from another terminal on the server:
+
+```sh
+milagre devices pending
+milagre devices allow KEY
+```
+
+Phones scan the QR with Milagre's pairing screen. The existing encrypted relay connects devices across networks; no public daemon port is needed. Pairing links expire after 10 minutes. Previously paired devices reconnect after a server restart. Run `milagre pair` to open another pairing window. Keep links private: they grant access to your agents.
+
+```sh
+milagre serve --project /absolute/path/to/project
+milagre status
+milagre devices list
+milagre devices deny KEY
+milagre devices remove KEY
+milagre request project:open '["/absolute/path/to/project"]'
+milagre stop
+```
+
+Use `MILAGRE_DATA_DIR` or an absolute `--data-dir` to select another profile. Use that same profile for every command. The CLI profile is separate from the desktop profile; do not open the same Projects in two hosts at once. The server runs with your account's permissions and uses the agent credentials on that computer.
+
+Ctrl+C and SIGTERM save and stop the server. Use `milagre serve --no-pair` for unattended restarts without printing links or opening a new pairing window. It retains access for devices already paired. `--no-qr` prints links without QR codes. No startup service is installed automatically; run the foreground command through your service manager for an always-on computer.
+
+From the repository, `npm run cli -- serve` runs the same command. `npm run package:cli` produces the installable tarball in `release/cli/`; it bundles the private Milagre packages, without Electron. npm installs registry dependencies and sets up native dependencies for the computer where you install it. You can also install that tarball with `npm install --global ./milagre-0.1.1.tgz`.

package/node_modules/@milagre/core/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@milagre/core",
+  "version": "0.1.0",
+  "private": true,
+  "type": "commonjs",
+  "main": "src/runtime.cjs",
+  "exports": {
+    ".": {
+      "types": "./src/runtime.d.cts",
+      "default": "./src/runtime.cjs"
+    },
+    "./*": "./src/*.cjs",
+    "./editors": {
+      "types": "./src/editors.d.cts",
+      "default": "./src/editors.cjs"
+    },
+    "./keep-awake": {
+      "types": "./src/keep-awake.d.cts",
+      "default": "./src/keep-awake.cjs"
+    },
+    "./agents/environment": {
+      "types": "./src/agents/environment.d.cts",
+      "default": "./src/agents/environment.cjs"
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}

package/node_modules/@milagre/core/src/account-mcp.cjs

@@ -0,0 +1,119 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { randomUUID } = require("node:crypto");
+
+// An added Claude or Codex Account runs from its own config folder, but the MCP servers the user set up
+// belong to the connected CLI account: Claude keeps them in .claude.json, which an Account never copies,
+// and Codex copied config.toml once, when the Account was added. Each time an Account's environment is
+// built, the connected account's servers are merged into the Account's config. A server of the same name
+// takes the connected account's definition; a server only the Account has stays.
+
+function writeIfChanged(file, before, after) {
+  if (after === before) return;
+  const temp = `${file}.${randomUUID()}.tmp`;
+  fs.writeFileSync(temp, after, { mode: 0o600 });
+  fs.renameSync(temp, file);
+}
+
+function readText(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+const isObject = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+
+// The names copied last time, beside the target config, so a server removed from the source can be removed again
+// without touching servers the account added itself.
+const recordFile = (targetFile) => path.join(path.dirname(targetFile), "milagre-inherited-mcp.json");
+function readRecorded(targetFile) {
+  try {
+    const names = JSON.parse(fs.readFileSync(recordFile(targetFile), "utf8")).names;
+    return new Set(Array.isArray(names) ? names : []);
+  } catch {
+    return new Set();
+  }
+}
+function writeRecorded(targetFile, names) {
+  const file = recordFile(targetFile);
+  writeIfChanged(file, readText(file), `${JSON.stringify({ names: [...names].toSorted() })}\n`);
+}
+
+// User servers sit at the top level of .claude.json, local ones under projects[path]. The Account's file
+// is written by Claude Code at sign-in; before that there is nothing to merge into.
+function inheritClaudeMcp(sourceFile, targetFile) {
+  const sourceText = readText(sourceFile);
+  const targetText = readText(targetFile);
+  if (sourceText === null || targetText === null) return;
+  const source = JSON.parse(sourceText);
+  const target = JSON.parse(targetText);
+  if (!isObject(source) || !isObject(target)) return;
+  const sourceNames = new Set(isObject(source.mcpServers) ? Object.keys(source.mcpServers) : []);
+  if (isObject(target.mcpServers)) for (const name of readRecorded(targetFile)) if (!sourceNames.has(name)) delete target.mcpServers[name];
+  if (isObject(source.mcpServers) && Object.keys(source.mcpServers).length)
+    target.mcpServers = { ...(isObject(target.mcpServers) ? target.mcpServers : {}), ...source.mcpServers };
+  for (const [project, settings] of Object.entries(isObject(source.projects) ? source.projects : {})) {
+    if (!isObject(settings?.mcpServers) || !Object.keys(settings.mcpServers).length) continue;
+    if (!isObject(target.projects)) target.projects = {};
+    const current = isObject(target.projects[project]) ? target.projects[project] : {};
+    target.projects[project] = { ...current, mcpServers: { ...(isObject(current.mcpServers) ? current.mcpServers : {}), ...settings.mcpServers } };
+  }
+  const next = JSON.stringify(target, null, 2);
+  // Unchanged servers leave the file alone, whatever formatting Claude Code wrote it with.
+  if (JSON.stringify(JSON.parse(targetText), null, 2) !== next) writeIfChanged(targetFile, targetText, next);
+  writeRecorded(targetFile, sourceNames);
+}
+
+// The server a TOML table header belongs to: [mcp_servers.pencil] and [mcp_servers.pencil.env] are both
+// "pencil". Anything else, [mcp_servers] alone included, belongs to no server.
+const SERVER_HEADER = /^\s*\[\s*mcp_servers\s*\.\s*("(?:[^"\\]|\\.)*"|'[^']*'|[A-Za-z0-9_-]+)\s*(?:\.[^\]]*)?\]\s*(?:#.*)?$/;
+const HEADER = /^\s*\[/;
+
+// The text before the first table, then each table with the lines up to the next header.
+function tomlSections(text) {
+  const lines = text.split("\n");
+  const sections = [];
+  let current = { server: null, lines: [] };
+  for (const line of lines) {
+    if (HEADER.test(line)) {
+      sections.push(current);
+      const name = SERVER_HEADER.exec(line)?.[1];
+      current = { server: name ? name.replace(/^["']|["']$/g, "") : null, lines: [] };
+    }
+    current.lines.push(line);
+  }
+  sections.push(current);
+  return sections;
+}
+
+function inheritCodexMcp(sourceFile, targetFile) {
+  const sourceText = readText(sourceFile);
+  const targetText = readText(targetFile);
+  if (sourceText === null || targetText === null) return;
+  const inherited = tomlSections(sourceText).filter((section) => section.server);
+  const names = new Set(inherited.map((section) => section.server));
+  // A server copied last time that the source no longer has goes, sub-tables included.
+  const removed = new Set([...readRecorded(targetFile)].filter((name) => !names.has(name)));
+  if (!inherited.length && !removed.size) return;
+  const kept = tomlSections(targetText).filter((section) => !names.has(section.server) && !removed.has(section.server));
+  const body = kept
+    .map((section) => section.lines.join("\n"))
+    .join("\n")
+    .replace(/\n*$/, "\n");
+  const added = inherited.map((section) => section.lines.join("\n").replace(/\n*$/, "\n")).join("\n");
+  writeIfChanged(targetFile, targetText, inherited.length ? `${body}\n${added}` : body);
+  writeRecorded(targetFile, names);
+}
+
+function inheritMcp(provider, { sourceDir, targetDir, home, configDirSet }) {
+  if (provider === "claude") {
+    // Without CLAUDE_CONFIG_DIR, Claude Code keeps .claude.json in the home folder, not in ~/.claude.
+    const sourceFile = configDirSet ? path.join(sourceDir, ".claude.json") : path.join(home, ".claude.json");
+    inheritClaudeMcp(sourceFile, path.join(targetDir, ".claude.json"));
+  } else if (provider === "codex") inheritCodexMcp(path.join(sourceDir, "config.toml"), path.join(targetDir, "config.toml"));
+}
+
+module.exports = { inheritMcp, inheritClaudeMcp, inheritCodexMcp };

package/node_modules/@milagre/core/src/account-routing.cjs

@@ -0,0 +1,40 @@
+const os = require("node:os");
+const { createCliStatus, cliWhenLoggedIn } = require("./agents/status.cjs");
+const { createModelCache } = require("./agents/models.cjs");
+const { PROVIDERS } = require("@milagre/shared/providers");
+
+/** Services capture account IDs, never a mutable currently viewed Project. */
+function createAccountRouting({ accounts, cli: baseCli, clientVersion, statusFactory = createCliStatus, modelsFactory = createModelCache }) {
+  const cache = new Map();
+  function selection(scope) {
+    return Object.fromEntries(PROVIDERS.map((provider) => [provider, accounts.selected(provider, scope)]));
+  }
+  async function forAccount(provider, accountId) {
+    const status = await baseCli(provider);
+    try {
+      return { ...status, accountId, env: accounts.environment(provider, accountId) };
+    } catch {
+      return { ...status, accountId, problem: "Assigned account not found. Choose another account in Project Accounts.", env: undefined };
+    }
+  }
+  const cli = (provider, scope) => forAccount(provider, accounts.selected(provider, scope));
+  function services(scope, ids = selection(scope)) {
+    const key = JSON.stringify(ids);
+    if (!cache.has(key)) {
+      const pinnedCli = (provider) => forAccount(provider, ids[provider]);
+      const options = { cli: pinnedCli, cwd: os.homedir(), clientVersion };
+      const status = statusFactory(options);
+      const models = modelsFactory({ ...options, cli: cliWhenLoggedIn(pinnedCli, status) });
+      cache.set(key, { status, models });
+    }
+    return cache.get(key);
+  }
+  function invalidate(provider) {
+    for (const entry of cache.values()) {
+      entry.status.invalidate?.(provider);
+      entry.models.invalidate?.(provider);
+    }
+  }
+  return { cli, forAccount, services, selection, invalidate };
+}
+module.exports = { createAccountRouting };