@passioncode-ai/passioncode 0.1.45 → 0.1.46

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.46 - 2026-10-12
+
+### Added
+
+- **`update` registers the Fabric Dashboards MCP server for every agent that is present**
+  (`fabric-dashboards`, stdio, the app bundle's `bin/fabric-dashboards-mcp`): Claude Code
+  through `claude mcp add --scope user`, Codex CLI as a `["mcp_servers"."fabric-dashboards"]`
+  table appended to `~/.codex/config.toml`, Gemini CLI and Kimi Code in the `mcpServers` of
+  `~/.gemini/settings.json` and `$KIMI_CODE_HOME/mcp.json`. A machine without the app skips
+  the step; an entry that already points at the same command is left alone, and one that
+  points elsewhere, or is declared in a form the launcher does not edit, is reported and
+  kept. Each registration is journalled before the file changes and removed again by
+  `restore` and `uninstall` only while it is still exactly what the launcher wrote
+  ([ADR-0003](docs/adr/0003-fabric-dashboards-mcp-registration.md)).
+
 ## 0.1.45 - 2026-10-12
 
 ### Changed

package/README.md

@@ -55,6 +55,12 @@ out of it, even when they implement Fabric protocols.
   `~/.passioncode/quarantine/` — `npx @passioncode-ai/passioncode@latest restore` puts them back.
 - Each version is an immutable release under `~/.passioncode/releases/<version>`; an update
   keeps the release it replaced for rollback and removes older ones.
+- When the Fabric Dashboards app is installed, `update` also registers its MCP server
+  (`fabric-dashboards`) for every agent that is present — Claude Code (through
+  `claude mcp add --scope user`), Codex CLI (`~/.codex/config.toml`), Gemini CLI
+  (`~/.gemini/settings.json`) and Kimi Code (`~/.kimi-code/mcp.json`). An entry that
+  already points at the same command is left alone; one that points elsewhere is reported
+  and kept. `restore` and `uninstall` remove what the launcher added.
 
 ## Staying current
 

package/SECURITY.md

@@ -11,7 +11,12 @@ that replaces it is verified. For a member's old single-member marketplace
 (`legacyMarketplaces` in `family.json`), once that plugin is verified and nothing else
 installed comes from it, it also moves the `extraKnownMarketplaces` entry out of
 `~/.claude/settings.json` (a copy of the file is kept in the quarantine) and runs
-`claude plugin marketplace remove <name>`. Displaced files are moved rather than
+`claude plugin marketplace remove <name>`. When the Fabric Dashboards app is installed it
+also registers a `fabric-dashboards` MCP entry for every agent that is present: through
+`claude mcp add --scope user` for Claude Code (it never writes `~/.claude.json` itself),
+and in `~/.codex/config.toml`, `~/.gemini/settings.json` and `~/.kimi-code/mcp.json`,
+copying each existing file into the quarantine first; an entry that already exists is
+left alone and reported. Displaced files are moved rather than
 deleted: a recovery record is written before the move in
 `~/.passioncode/quarantine/<run>/moved.json`. `restore` processes the latest batch,
 checkpoints completed entries and refuses to overwrite a conflicting user replacement.

package/lib/launcher.js

@@ -2,8 +2,9 @@
 /**
  * The PassionCode.ai launcher: installs the vendored payload as one release,
  * gives Claude Code the plugins through a local marketplace, gives every other
- * agent the same skills through the ~/.agents/skills hub, and removes what
- * would shadow them — reversibly. Every step is recorded; nothing is deleted.
+ * agent the same skills through the ~/.agents/skills hub, registers the Fabric
+ * Dashboards MCP server for every agent that is present, and removes what would
+ * shadow them — reversibly. Every step is recorded; nothing is deleted.
  *
  * One channel per agent: Claude Code reads plugins, so nothing is written to
  * ~/.claude/skills (a plain copy there shadows the plugin and serves its frozen
@@ -47,6 +48,12 @@ function writeJson(file, value) {
   fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n');
   fs.renameSync(tmp, file);
 }
+function writeText(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, text);
+  fs.renameSync(tmp, file);
+}
 function lstat(p) { try { return fs.lstatSync(p); } catch (_) { return null; } }
 function linkTarget(p) { try { return fs.readlinkSync(p); } catch (_) { return null; } }
 function pointsTo(at, target) { const link = linkTarget(at); return link !== null && path.resolve(path.dirname(at), link) === target; }
@@ -187,6 +194,103 @@ function marketplaceAddArg(source) {
   return source.url || source.repo || source.path || null;
 }
 
+const MCP_NAME = 'fabric-dashboards';
+const MCP_COMMAND = () => process.env.PASSIONCODE_FABRIC_DASHBOARDS_MCP
+  || '/Applications/Fabric Dashboards.app/Contents/Resources/bin/fabric-dashboards-mcp';
+
+/**
+ * The agents besides Claude Code the Fabric Dashboards MCP server is registered for, and
+ * the file each keeps its MCP configuration in. An agent is present when its directory
+ * is; a missing file under a present agent is created. Claude Code is registered through
+ * its own CLI instead: every running session rewrites ~/.claude.json, so a second writer
+ * there would lose one side's change.
+ */
+function mcpFileTargets(home) {
+  const kimiHome = process.env.KIMI_CODE_HOME || path.join(home, '.kimi-code');
+  return [
+    { agent: 'Codex CLI', dir: path.join(home, '.codex'), file: path.join(home, '.codex', 'config.toml'), kind: 'toml' },
+    { agent: 'Gemini CLI', dir: path.join(home, '.gemini'), file: path.join(home, '.gemini', 'settings.json'), kind: 'json' },
+    { agent: 'Kimi Code', dir: kimiHome, file: path.join(kimiHome, 'mcp.json'), kind: 'json' },
+  ];
+}
+
+/** The line range of the `["mcp_servers"."<name>"]` table in a TOML text, or null. */
+function tomlTableRange(text, name) {
+  const lines = text.split('\n');
+  const header = new RegExp(`^\\s*\\[\\s*["']?mcp_servers["']?\\s*\\.\\s*["']?${name}["']?\\s*\\]\\s*(?:#.*)?$`);
+  for (let i = 0; i < lines.length; i++) {
+    if (!header.test(lines[i])) continue;
+    let end = lines.length;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (/^\s*\[/.test(lines[j])) { end = j; break; }
+    }
+    return { start: i, end, lines };
+  }
+  return null;
+}
+
+/**
+ * Any other way a TOML text can already define the server — a sub-table such as
+ * `[mcp_servers.<name>.env]` or an inline `<name> = { … }` under `[mcp_servers]`.
+ * Appending a table then would declare the key twice and Codex would refuse the file.
+ */
+function tomlMentions(text, name) {
+  return new RegExp(`^\\s*\\[\\s*["']?mcp_servers["']?\\s*\\.\\s*["']?${name}["']?\\s*\\.`, 'm').test(text)
+    || new RegExp(`^\\s*["']?${name}["']?\\s*=`, 'm').test(text);
+}
+
+/** The `command` of a TOML table range: the string, null when absent, undefined when unreadable. */
+function tomlTableCommand(range) {
+  for (let i = range.start + 1; i < range.end; i++) {
+    const m = /^\s*command\s*=\s*("(?:[^"\\]|\\.)*")\s*(?:#.*)?$/.exec(range.lines[i]);
+    if (m) { try { return JSON.parse(m[1]); } catch (_) { return undefined; } }
+  }
+  return null;
+}
+
+function mcpTomlTable(command) {
+  return `["mcp_servers"."${MCP_NAME}"]\ncommand = ${JSON.stringify(command)}\nargs = []\n`;
+}
+
+/** Two MCP entries are the same when their JSON lines up at every depth, key order aside. */
+function sameEntry(a, b) {
+  const canon = (v) => (v && typeof v === 'object' && !Array.isArray(v)
+    ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, canon(v[k])]))
+    : Array.isArray(v) ? v.map(canon) : v);
+  return JSON.stringify(canon(a)) === JSON.stringify(canon(b));
+}
+
+/**
+ * Remove an MCP entry the launcher added, only while it is still exactly that entry.
+ * Returns a note, or null when the entry is already gone. Never deletes the file.
+ */
+function removeMcpRegistration(record, claude) {
+  const kept = (why) => `${record.file}: ${record.name} for ${record.agent} ${why}; kept`;
+  const removed = `${record.name} for ${record.agent} removed from ${record.file}`;
+  if (record.file.endsWith('.toml')) {
+    let text;
+    try { text = fs.readFileSync(record.file, 'utf8'); } catch (_) { return null; }
+    const range = tomlTableRange(text, record.name);
+    if (!range) return null;
+    if (tomlTableCommand(range) !== record.entry.command) return kept('was changed');
+    writeText(record.file, range.lines.slice(0, range.start).concat(range.lines.slice(range.end)).join('\n'));
+    return removed;
+  }
+  let cfg;
+  try { cfg = readSettings(record.file); } catch (error) { return kept(`could not be read (${error.message})`); }
+  const servers = cfg.doc.mcpServers;
+  if (!servers || !Object.prototype.hasOwnProperty.call(servers, record.name)) return null;
+  if (!sameEntry(servers[record.name], record.entry)) return kept('was changed');
+  if (record.via === 'claude') {
+    if (!claude.available()) return kept('is registered with Claude Code, whose CLI was not found');
+    const r = claude.run(['mcp', 'remove', '--scope', 'user', record.name]);
+    return r.code === 0 ? removed : kept(`could not be removed (${r.out || 'claude mcp remove failed'})`);
+  }
+  delete servers[record.name];
+  writeJson(record.file, cfg.doc);
+  return removed;
+}
+
 function payloadManifest(dir = PAYLOAD()) {
   const m = readJson(path.join(dir, 'manifest.json'), null);
   if (!m || !Array.isArray(m.members)) throw new Error(`No payload in ${dir}: the package is incomplete (run scripts/vendor.mjs).`);
@@ -391,7 +495,93 @@ function update({ home, dryRun = false, claude = claudeRunner(), log = () => {}
     }
   }
 
-  // 5. The launcher's own releases: keep this one and the one it replaced, remove the rest.
+  // 5. The Fabric Dashboards MCP server, for every agent that is present. Entries a
+  //    person or another tool set are never rewritten: a matching entry is left, a
+  //    different one is reported. What the launcher adds is journalled before it is
+  //    written, so restore and uninstall can take it out again.
+  const registered = [];
+  const mcpCommand = MCP_COMMAND();
+  const mcpBackup = (file, agent) => {
+    if (!lstat(file)) return null;
+    fs.mkdirSync(quarantineDir, { recursive: true });
+    const backup = path.join(quarantineDir, `${path.basename(file)}.before-mcp-${agent.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`);
+    fs.copyFileSync(file, backup);
+    return backup;
+  };
+  const register = (record, write) => step('mcp', `register ${MCP_NAME} for ${record.agent} in ${record.file}`, () => {
+    recordMove(record);
+    write();
+    registered.push({ agent: record.agent, file: record.file, name: record.name, entry: record.entry, ...(record.via ? { via: record.via } : {}) });
+  });
+  const existingNote = (agent, existing) => existing === mcpCommand
+    ? { kind: 'mcp', detail: `${agent} already runs ${MCP_NAME} from ${mcpCommand}`, outcome: 'skipped' }
+    : { kind: 'mcp', detail: `${agent} has its own ${MCP_NAME} entry (${existing || 'not a stdio server'}); it was kept`, outcome: 'skipped' };
+  if (!lstat(mcpCommand)) {
+    steps.push({ kind: 'mcp', detail: `no Fabric Dashboards MCP at ${mcpCommand}; nothing was registered`, outcome: 'skipped' });
+  } else {
+    const claudeJson = path.join(p.home, '.claude.json');
+    if (!hasClaude) {
+      steps.push({ kind: 'mcp', detail: `Claude Code CLI not found; ${MCP_NAME} was not registered for it`, outcome: 'skipped' });
+    } else {
+      let servers = null;
+      try { servers = readSettings(claudeJson).doc.mcpServers || {}; } catch (error) {
+        steps.push({ kind: 'mcp', detail: `keep ${claudeJson}: it could not be read`, outcome: 'failed', error: error.message });
+      }
+      const existing = servers && servers[MCP_NAME];
+      if (existing) steps.push(existingNote('Claude Code', typeof existing === 'object' ? existing.command || existing.url : null));
+      else if (servers) {
+        const entry = { type: 'stdio', command: mcpCommand, args: [], env: {} };
+        register({ kind: 'mcp', via: 'claude', agent: 'Claude Code', file: claudeJson, name: MCP_NAME, entry, backup: null }, () => {
+          const r = claude.run(['mcp', 'add', '--scope', 'user', MCP_NAME, '--', mcpCommand], { cwd: p.state });
+          if (r.code !== 0) throw new Error(r.out || 'claude mcp add failed');
+          const now = readSettings(claudeJson).doc.mcpServers || {};
+          if (!now[MCP_NAME] || now[MCP_NAME].command !== mcpCommand) throw new Error(`Claude Code did not register ${MCP_NAME} in ${claudeJson}`);
+          // What the CLI wrote is what restore and uninstall compare against.
+          entry.type = now[MCP_NAME].type; entry.args = now[MCP_NAME].args; entry.env = now[MCP_NAME].env;
+        });
+      }
+    }
+    for (const target of mcpFileTargets(p.home)) {
+      if (!isDirectory(target.dir)) {
+        steps.push({ kind: 'mcp', detail: `${target.agent} not found; ${MCP_NAME} was not registered for it`, outcome: 'skipped' });
+        continue;
+      }
+      if (target.kind === 'json') {
+        let cfg;
+        try { cfg = readSettings(target.file); } catch (error) {
+          steps.push({ kind: 'mcp', detail: `keep ${target.file}: it could not be read`, outcome: 'failed', error: error.message });
+          continue;
+        }
+        const existing = (cfg.doc.mcpServers || {})[MCP_NAME];
+        if (existing) { steps.push(existingNote(target.agent, typeof existing === 'object' ? existing.command || existing.url : null)); continue; }
+        const entry = { command: mcpCommand, args: [], env: {} };
+        register({ kind: 'mcp', agent: target.agent, file: target.file, name: MCP_NAME, entry, backup: mcpBackup(target.file, target.agent) }, () => {
+          cfg.doc.mcpServers = { ...(cfg.doc.mcpServers || {}), [MCP_NAME]: entry };
+          writeJson(target.file, cfg.doc);
+        });
+      } else {
+        let text = '';
+        try { text = fs.readFileSync(target.file, 'utf8'); } catch (error) {
+          if (error.code !== 'ENOENT') {
+            steps.push({ kind: 'mcp', detail: `keep ${target.file}: it could not be read`, outcome: 'failed', error: error.message });
+            continue;
+          }
+        }
+        const range = tomlTableRange(text, MCP_NAME);
+        if (range) { const c = tomlTableCommand(range); steps.push(existingNote(target.agent, c == null ? null : c)); continue; }
+        if (tomlMentions(text, MCP_NAME)) {
+          steps.push({ kind: 'mcp', detail: `${target.agent} declares ${MCP_NAME} in ${target.file} in a form the launcher does not edit; it was kept`, outcome: 'skipped' });
+          continue;
+        }
+        const entry = { command: mcpCommand, args: [] };
+        register({ kind: 'mcp', agent: target.agent, file: target.file, name: MCP_NAME, entry, backup: mcpBackup(target.file, target.agent) }, () => {
+          writeText(target.file, text ? `${text.endsWith('\n') ? text : `${text}\n`}\n${mcpTomlTable(mcpCommand)}` : mcpTomlTable(mcpCommand));
+        });
+      }
+    }
+  }
+
+  // 6. The launcher's own releases: keep this one and the one it replaced, remove the rest.
   //    They are its own output, reinstallable from npm — not the person's files, which are
   //    only ever moved to the quarantine.
   const stale = staleReleases(p, version, state.installed || null);
@@ -410,6 +600,9 @@ function update({ home, dryRun = false, claude = claudeRunner(), log = () => {}
     fresh.members = manifest.members.map((m) => ({ name: m.name, version: m.version, ref: m.ref, commit: m.commit }));
     fresh.quarantines = [...new Set([...(fresh.quarantines || []), ...(moved.length ? [quarantineDir] : [])])];
     if (state.legacyRemoved) fresh.legacyRemoved = state.legacyRemoved;
+    if (registered.length) {
+      fresh.mcpRegistrations = [...(fresh.mcpRegistrations || []).filter((r) => !registered.some((n) => n.file === r.file && n.name === r.name)), ...registered];
+    }
     delete fresh.updatingSince;
     writeJson(p.stateFile, fresh);
   }
@@ -430,6 +623,15 @@ function restore({ home, which, claude = claudeRunner() } = {}) {
       if (entry.restoredAt) continue;
       if (entry.kind === 'marketplace') {
         restored.push(restoreMarketplace(p, entry, claude));
+      } else if (entry.kind === 'mcp') {
+        const note = removeMcpRegistration(entry, claude);
+        if (note) restored.push(note);
+        const state = readState(p.stateFile);
+        if (state.mcpRegistrations) {
+          state.mcpRegistrations = state.mcpRegistrations.filter((r) => !(r.file === entry.file && r.name === entry.name));
+          if (!state.mcpRegistrations.length) delete state.mcpRegistrations;
+          writeJson(p.stateFile, state);
+        }
       } else if (lstat(entry.to)) {
         if (lstat(entry.from)) {
           // Old journals did not record the replacement. Only recognise a link
@@ -561,6 +763,13 @@ function uninstall({ home, claude = claudeRunner() } = {}) {
     fs.unlinkSync(p.current);
   }
   const state = readState(p.stateFile);
+  // The MCP registrations this launcher added — only while they are still exactly what
+  // it wrote; an entry a person changed since stays.
+  for (const record of state.mcpRegistrations || []) {
+    const note = removeMcpRegistration(record, claude);
+    if (note) removed.push(note);
+  }
+  delete state.mcpRegistrations;
   state.installed = null;
   state.members = [];
   state.config = { ...(state.config || {}), auto: false };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/passioncode",
-  "version": "0.1.45",
+  "version": "0.1.46",
   "description": "The PassionCode.ai agent skill set \u2014 Fabric Agent Adapter, Observatory Log and the organisation's working rules \u2014 for Claude Code and every other agent on the machine, updated as one set.",
   "bin": {
     "passioncode": "bin/passioncode.js"

package/payload/.claude-plugin/marketplace.json

@@ -35,7 +35,7 @@
       "name": "passioncode",
       "displayName": "PassionCode.ai",
       "source": "./plugins/passioncode",
-      "version": "0.1.45",
+      "version": "0.1.46",
       "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
       "author": {
         "name": "PassionCode.ai",

package/payload/manifest.json

@@ -1,6 +1,6 @@
 {
   "family": "passioncode",
-  "version": "0.1.45",
+  "version": "0.1.46",
   "release": true,
   "members": [
     {
@@ -61,16 +61,16 @@
       "name": "passioncode",
       "displayName": "PassionCode.ai",
       "repo": "passioncode-ai/passioncode",
-      "ref": "v0.1.45",
+      "ref": "v0.1.46",
       "commit": null,
-      "version": "0.1.45",
+      "version": "0.1.46",
       "via": "this repository",
       "skills": [
         "working-in-passioncode"
       ],
       "legacyPluginIds": [],
       "legacyMarketplaces": [],
-      "contentHash": "sha256:9cca65f79d5971661e6593ae604ab184e1aef8de06c60fbc05b00240cabd84ac",
+      "contentHash": "sha256:eceb409d950b38814a892a29ffe028c41a3000c3323af46458ec345f1faa37f3",
       "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
       "author": {
         "name": "PassionCode.ai",

package/payload/plugins/passioncode/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "passioncode",
   "displayName": "PassionCode.ai",
-  "version": "0.1.45",
+  "version": "0.1.46",
   "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check at session start that keeps the PassionCode.ai skill set current.",
   "author": {
     "name": "PassionCode.ai",