@sbains2/lifeos 0.1.3 → 0.2.0

package/src/index.js

@@ -1,7 +1,8 @@
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
+import { homedir } from 'node:os';
 import { confirm } from '@inquirer/prompts';
-import { loadPersonaTemplate } from './templates-loader.js';
+import { loadPersonaTemplate, loadRegistry } from './templates-loader.js';
 import { askPersona } from './wizard/persona.js';
 import { askProfile } from './wizard/profile.js';
 import { askFoci } from './wizard/foci.js';
@@ -10,6 +11,14 @@ import { askCouncil } from './wizard/council.js';
 import { askMcps } from './wizard/mcps.js';
 import { validateAndGenerate } from './wizard/generate.js';
 import { cleanupQuadrantMcpRefs } from './cleanup.js';
+import {
+  writeProjectMcpJson,
+  detectClaudeDesktop,
+  mergeIntoClaudeDesktop,
+  generateMcpStatus,
+  groupMcpStatus,
+  CLAUDE_DESKTOP_CONFIG_PATH,
+} from './mcp-config.js';
 import { startTimer, elapsed } from './utils/timer.js';
 import { c } from './utils/colors.js';
 
@@ -17,7 +26,7 @@ export async function run(targetDir, options = {}) {
   const { minimal = false } = options;
 
   console.log('');
-  console.log(c.bold('lifeos') + c.dim(' v0.1.3 — scaffold a personal LifeOS'));
+  console.log(c.bold('lifeos') + c.dim(' v0.2.0 — scaffold a personal LifeOS'));
   console.log(c.dim(`Target directory: ${targetDir}`));
   if (minimal) {
     console.log(c.dim('Mode: --minimal (speed-optimized; using template defaults for quadrants, council, MCPs)'));
@@ -74,8 +83,6 @@ export async function run(targetDir, options = {}) {
 
   // Auto-cleanup: if the user unchecked any MCP at Step 6 that a quadrant
   // still references, remove the dangling reference so validation passes.
-  // (Reported as a bug 2026-05-01 — friend tester unchecked zotero and the
-  // research quadrant still referenced it, blocking the entire install.)
   const { cleaned: cleanedQuadrants, removed: cleanupReport } = cleanupQuadrantMcpRefs(quadrants, mcps);
   if (cleanupReport.length > 0) {
     console.log('');
@@ -85,6 +92,32 @@ export async function run(targetDir, options = {}) {
     }
   }
 
+  // Risk-advisory check: if any wired MCP is `use-at-your-own-risk`, surface the
+  // warning and ask whether to include it in auto-config (.mcp.json + Claude Desktop).
+  // The MCP stays in lifeos.config.json regardless — this only controls auto-install.
+  const registry = (() => {
+    try { return loadRegistry(); } catch { return { servers: [] }; }
+  })();
+  const registryById = new Map(registry.servers.map((s) => [s.id, s]));
+  const riskyPicked = mcps.filter((m) => registryById.get(m.id)?.status === 'use-at-your-own-risk');
+  let includeRisky = false;
+  if (riskyPicked.length > 0 && !minimal) {
+    console.log('');
+    console.log(c.warn('Some MCPs you picked are marked use-at-your-own-risk:'));
+    for (const m of riskyPicked) {
+      const entry = registryById.get(m.id);
+      console.log(`  ${c.warn('!')} ${c.bold(m.id)}: ${entry.risk_advisory ?? '(see registry)'}`);
+    }
+    includeRisky = await confirm({
+      message: 'Include these in auto-config? (No = MCP stays in lifeos.config.json but skipped from .mcp.json — install manually)',
+      default: false,
+    });
+  } else if (riskyPicked.length > 0 && minimal) {
+    // --minimal: include by default to avoid blocking, but log
+    includeRisky = true;
+    console.log(c.dim(`  (--minimal: including ${riskyPicked.length} use-at-your-own-risk MCP(s) without prompt — see lifeos.config.json risk_advisory)`));
+  }
+
   // Assemble final config
   const config = {
     $schema: template.$schema,
@@ -106,7 +139,6 @@ export async function run(targetDir, options = {}) {
       ...template.brain,
       graphify: {
         ...template.brain.graphify,
-        // Reduce graphify paths to active quadrants only
         paths: cleanedQuadrants.filter((q) => q.active).map((q) => q.path),
       },
     },
@@ -115,17 +147,114 @@ export async function run(targetDir, options = {}) {
 
   // Step 7 — validate + scaffold
   const result = await validateAndGenerate(config, { targetDir, minimal });
+  if (!result.ok) {
+    console.log(c.dim(`Aborted after ${elapsed(start)}.`));
+    return;
+  }
 
+  // Post-scaffold: auto-config MCPs
+  // (1) Always write project-local .mcp.json — low-risk, scoped to the user's repo
   console.log('');
-  if (result.ok) {
-    console.log(c.bold(c.ok('Done')) + ` in ${elapsed(start)}.`);
-    console.log('');
-    console.log(c.bold('Next:'));
-    console.log(`  ${c.arrow} Wire your MCP servers (see .lifeos/INSTALL_MCPS.md)`);
-    console.log(`  ${c.arrow} Open this folder in Claude Code and try convening the council on a real artifact`);
-    console.log(`  ${c.arrow} Edit lifeos.config.json to tune council priorities, add quadrants, or change foci`);
-    console.log('');
+  console.log(c.bold('Wiring MCP servers...'));
+  const mcpJsonResult = writeProjectMcpJson(targetDir, mcps, registry, { includeRisky });
+  console.log(`  ${c.check} wrote ${relative(homedir(), mcpJsonResult.path).replace(/^/, '~/')} (${mcpJsonResult.added} entries)`);
+  if (mcpJsonResult.skipped.length > 0) {
+    for (const s of mcpJsonResult.skipped) {
+      console.log(c.dim(`    ${c.dot} skipped ${s.id}: ${s.reason}`));
+    }
+  }
+
+  // (2) Detect Claude Desktop config; offer to merge
+  let desktopMergeResult = null;
+  if (detectClaudeDesktop()) {
+    if (!minimal) {
+      console.log('');
+      console.log(c.dim(`Detected Claude Desktop config at ${CLAUDE_DESKTOP_CONFIG_PATH.replace(homedir(), '~')}`));
+      const doMerge = await confirm({
+        message: 'Also merge wired MCPs into Claude Desktop config? (backup taken first; existing entries by name preserved)',
+        default: true,
+      });
+      if (doMerge) {
+        try {
+          desktopMergeResult = mergeIntoClaudeDesktop(mcps, registry, { includeRisky });
+          console.log(`  ${c.check} merged into Claude Desktop config`);
+          console.log(c.dim(`    backup: ${desktopMergeResult.backupPath.replace(homedir(), '~')}`));
+          if (desktopMergeResult.addedIds.length > 0) {
+            console.log(c.dim(`    added: ${desktopMergeResult.addedIds.join(', ')}`));
+          }
+          if (desktopMergeResult.skippedIds.length > 0) {
+            console.log(c.dim(`    skipped (already in your config): ${desktopMergeResult.skippedIds.join(', ')}`));
+          }
+        } catch (err) {
+          console.log(c.err(`  ${c.cross} merge failed: ${err.message}`));
+          console.log(c.dim(`    .mcp.json was still written — Claude Code / Cursor will pick that up`));
+        }
+      } else {
+        console.log(c.dim(`  ${c.dot} skipped Claude Desktop merge — only .mcp.json written`));
+      }
+    } else {
+      console.log(c.dim(`  ${c.dot} (--minimal: skipping Claude Desktop merge prompt — only .mcp.json written)`));
+    }
   } else {
-    console.log(c.dim(`Aborted after ${elapsed(start)}.`));
+    console.log(c.dim(`  ${c.dot} Claude Desktop config not found — only .mcp.json written`));
   }
+
+  // (3) Per-MCP status report
+  const mcpStatus = generateMcpStatus(mcps, registry);
+  const groups = groupMcpStatus(mcpStatus);
+  console.log('');
+  console.log(c.bold(`MCP setup status (${mcps.length} wired):`));
+  if (groups.ready.length > 0) {
+    console.log(`  ${c.ok('✓ ready')} (${groups.ready.length}): ${groups.ready.map((r) => r.id).join(', ')}`);
+    console.log(c.dim(`     these work as soon as Claude restarts`));
+  }
+  if (groups.needs_oauth.length > 0) {
+    console.log(`  ${c.warn('⚠ OAuth on first use')} (${groups.needs_oauth.length}):`);
+    for (const r of groups.needs_oauth) {
+      console.log(`     ${c.bold(r.id)}`);
+      for (const line of r.lines) console.log(c.dim(`       ${line}`));
+    }
+  }
+  if (groups.needs_env.length > 0) {
+    console.log(`  ${c.warn('⚠ needs env var')} (${groups.needs_env.length}):`);
+    for (const r of groups.needs_env) {
+      console.log(`     ${c.bold(r.id)}`);
+      for (const line of r.lines) console.log(c.dim(`       ${line}`));
+    }
+  }
+  if (groups.manual.length > 0) {
+    console.log(`  ${c.warn('⚠ manual install required')} (${groups.manual.length}):`);
+    for (const r of groups.manual) {
+      console.log(`     ${c.bold(r.id)}`);
+      for (const line of r.lines) console.log(c.dim(`       ${line}`));
+    }
+  }
+  if (groups.risk.length > 0) {
+    console.log(`  ${c.err('⚠ use-at-your-own-risk')} (${groups.risk.length}):`);
+    for (const r of groups.risk) {
+      console.log(`     ${c.bold(r.id)}`);
+      for (const line of r.lines) console.log(c.dim(`       ${line}`));
+    }
+  }
+  if (groups.unknown.length > 0) {
+    console.log(`  ${c.dim('? unknown (not in registry)')} (${groups.unknown.length}): ${groups.unknown.map((r) => r.id).join(', ')}`);
+  }
+
+  // Final summary
+  console.log('');
+  console.log(c.bold(c.ok('Done')) + ` in ${elapsed(start)}.`);
+  console.log('');
+  console.log(c.bold('Next:'));
+  if (groups.needs_env.length > 0) {
+    console.log(`  ${c.arrow} Set the env vars listed above (in your shell rc — ~/.zshrc or ~/.bashrc), then reload your shell`);
+  }
+  if (desktopMergeResult || groups.ready.length > 0 || groups.needs_oauth.length > 0) {
+    console.log(`  ${c.arrow} Restart Claude Desktop (Cmd+Q, then reopen) so the new MCPs load`);
+  }
+  console.log(`  ${c.arrow} Open ${targetDir} in Claude Code and try convening the council on a real artifact`);
+  console.log(`  ${c.arrow} Edit lifeos.config.json to tune council priorities, add quadrants, or change foci`);
+  if (groups.manual.length > 0 || groups.risk.length > 0) {
+    console.log(`  ${c.arrow} For manual / risky MCPs: see .lifeos/INSTALL_MCPS.md for the full hint per server`);
+  }
+  console.log('');
 }

package/src/mcp-config.js

@@ -0,0 +1,231 @@
+/**
+ * MCP auto-configuration: write .mcp.json into the LifeOS scaffold and
+ * optionally merge into the user's Claude Desktop config.
+ *
+ * Trust posture:
+ * - The local .mcp.json is always written (project-scoped, low-risk).
+ * - The Claude Desktop config is only touched after explicit user confirmation,
+ *   always backed up first, and we MERGE — never overwrite existing entries by name.
+ * - Auth tokens are referenced by env-var name only. The CLI never reads token
+ *   values from anywhere or writes them to the config.
+ */
+
+import { writeFileSync, readFileSync, existsSync, copyFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+export const CLAUDE_DESKTOP_CONFIG_PATH = join(
+  homedir(),
+  'Library',
+  'Application Support',
+  'Claude',
+  'claude_desktop_config.json'
+);
+
+/**
+ * Build the `mcpServers` block for a list of wired MCPs.
+ * - Looks each MCP up in the registry.
+ * - Skips entries with `runtime: "manual"` or no `install_command`.
+ * - Skips entries with status `use-at-your-own-risk` UNLESS explicitly opted in
+ *   (caller passes { includeRisky: true }) — these need explicit user confirmation.
+ *
+ * Returns { servers, skipped: [{id, reason}] }.
+ */
+export function buildMcpServersBlock(wiredMcps, registry, options = {}) {
+  const { includeRisky = false } = options;
+  const byId = new Map((registry?.servers ?? []).map((s) => [s.id, s]));
+  const servers = {};
+  const skipped = [];
+
+  for (const m of wiredMcps ?? []) {
+    const entry = byId.get(m.id);
+    if (!entry) {
+      skipped.push({ id: m.id, reason: 'not in registry' });
+      continue;
+    }
+    if (!entry.install_command || entry.runtime === 'manual') {
+      skipped.push({ id: m.id, reason: 'manual install (see install_hint)' });
+      continue;
+    }
+    if (entry.status === 'use-at-your-own-risk' && !includeRisky) {
+      skipped.push({ id: m.id, reason: 'use-at-your-own-risk — opt in explicitly' });
+      continue;
+    }
+
+    const [command, ...args] = entry.install_command;
+    const def = { command, args };
+    if (entry.auth?.env_var) {
+      // Reference by name only — value comes from user's shell env at runtime
+      def.env = { [entry.auth.env_var]: `\${${entry.auth.env_var}}` };
+    }
+    servers[m.id] = def;
+  }
+
+  return { servers, skipped };
+}
+
+/**
+ * Write `<targetDir>/.mcp.json` with the wired MCPs.
+ * If the file already exists, MERGE — preserve any user-added entries.
+ * Returns { path, added: number, skipped: [] }.
+ */
+export function writeProjectMcpJson(targetDir, wiredMcps, registry, options = {}) {
+  const { servers, skipped } = buildMcpServersBlock(wiredMcps, registry, options);
+  const path = join(targetDir, '.mcp.json');
+
+  let existing = { mcpServers: {} };
+  if (existsSync(path)) {
+    try {
+      existing = JSON.parse(readFileSync(path, 'utf8'));
+    } catch {
+      // Malformed existing file — skip merge, write fresh (preserve via backup below)
+      const backupPath = `${path}.malformed-backup`;
+      copyFileSync(path, backupPath);
+      existing = { mcpServers: {} };
+    }
+  }
+
+  const existingServers = existing.mcpServers ?? {};
+  const merged = {
+    ...existing,
+    mcpServers: {
+      ...existingServers,
+      // New entries take precedence over old ones with same id only if user explicitly
+      // chose them in the wizard. We assume that's intentional (re-run wizard = update).
+      ...servers,
+    },
+  };
+
+  writeFileSync(path, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+  return { path, added: Object.keys(servers).length, skipped };
+}
+
+/**
+ * Returns true if Claude Desktop is installed (config file exists).
+ * Read-only — does not modify anything.
+ */
+export function detectClaudeDesktop(configPath = CLAUDE_DESKTOP_CONFIG_PATH) {
+  return existsSync(configPath);
+}
+
+/**
+ * Backup + merge our MCPs into the Claude Desktop config.
+ * Always writes a backup at `<configPath>.lifeos-backup.<timestamp>` before any change.
+ * NEVER overwrites existing mcpServers entries by name — preserves user customization.
+ *
+ * Returns { backupPath, addedIds: [], skippedIds: [] (because already present in user config) }.
+ * Throws if config file doesn't exist or can't be parsed.
+ */
+export function mergeIntoClaudeDesktop(wiredMcps, registry, options = {}) {
+  const { configPath = CLAUDE_DESKTOP_CONFIG_PATH } = options;
+  if (!existsSync(configPath)) {
+    throw new Error(`Claude Desktop config not found at ${configPath}`);
+  }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = `${configPath}.lifeos-backup.${timestamp}`;
+  copyFileSync(configPath, backupPath);
+
+  let existing;
+  try {
+    existing = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    throw new Error(
+      `Could not parse Claude Desktop config (${err.message}). ` +
+        `Original preserved at ${backupPath} — fix the JSON manually before retrying.`
+    );
+  }
+
+  const { servers } = buildMcpServersBlock(wiredMcps, registry, options);
+  const existingServers = existing.mcpServers ?? {};
+  const existingIds = new Set(Object.keys(existingServers));
+
+  const addedIds = [];
+  const skippedIds = [];
+  const newServers = {};
+  for (const [id, def] of Object.entries(servers)) {
+    if (existingIds.has(id)) {
+      skippedIds.push(id);
+    } else {
+      newServers[id] = def;
+      addedIds.push(id);
+    }
+  }
+
+  const merged = {
+    ...existing,
+    mcpServers: { ...existingServers, ...newServers },
+  };
+
+  writeFileSync(configPath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+  return { backupPath, addedIds, skippedIds };
+}
+
+/**
+ * Generate a per-MCP status report. Returns an array of objects suitable for
+ * display in the wizard's final summary. Each entry: { id, status, lines: [] }
+ *
+ * Statuses:
+ * - "ready"      — install_command + no auth needed
+ * - "needs_env"  — install_command exists; user must set an env var
+ * - "needs_oauth"— install_command exists; user must complete OAuth on first run
+ * - "manual"     — no install_command (manual install required)
+ * - "risk"       — use-at-your-own-risk; surface advisory prominently
+ * - "unknown"    — not in registry (only happens if user added an ad-hoc MCP)
+ */
+export function generateMcpStatus(wiredMcps, registry) {
+  const byId = new Map((registry?.servers ?? []).map((s) => [s.id, s]));
+  const report = [];
+
+  for (const m of wiredMcps ?? []) {
+    const entry = byId.get(m.id);
+    if (!entry) {
+      report.push({ id: m.id, status: 'unknown', lines: ['not in registry'] });
+      continue;
+    }
+
+    const lines = [];
+    let status;
+
+    if (entry.status === 'use-at-your-own-risk') {
+      status = 'risk';
+      lines.push(`⚠ ${entry.risk_advisory?.split('.')[0] ?? 'use at your own risk'}`);
+      if (entry.repo_url) lines.push(`   repo: ${entry.repo_url}`);
+    } else if (!entry.install_command || entry.runtime === 'manual') {
+      status = 'manual';
+      lines.push(`manual install required`);
+      if (entry.repo_url) lines.push(`   repo: ${entry.repo_url}`);
+      if (entry.install_hint) lines.push(`   ${entry.install_hint.split('.')[0]}`);
+    } else if (entry.auth?.method === 'oauth') {
+      status = 'needs_oauth';
+      lines.push(`OAuth on first use (Claude will prompt)`);
+      if (entry.auth.help_url) lines.push(`   setup help: ${entry.auth.help_url}`);
+      if (entry.auth.scope_hint) lines.push(`   ${entry.auth.scope_hint.split('.')[0]}`);
+    } else if (entry.auth?.method === 'api_key' && entry.auth?.env_var) {
+      status = 'needs_env';
+      lines.push(`needs ${entry.auth.env_var}`);
+      if (entry.auth.help_url) lines.push(`   get one: ${entry.auth.help_url}`);
+      if (entry.auth.scope_hint) lines.push(`   scope: ${entry.auth.scope_hint.split('.')[0]}`);
+    } else {
+      status = 'ready';
+      lines.push(`ready (${entry.runtime})`);
+    }
+
+    report.push({ id: m.id, status, lines });
+  }
+
+  return report;
+}
+
+/**
+ * Group a status report by status for printing.
+ * Returns { ready: [], needs_env: [], needs_oauth: [], manual: [], risk: [], unknown: [] }.
+ */
+export function groupMcpStatus(report) {
+  const groups = { ready: [], needs_oauth: [], needs_env: [], manual: [], risk: [], unknown: [] };
+  for (const entry of report) {
+    if (groups[entry.status]) groups[entry.status].push(entry);
+    else groups.unknown.push(entry);
+  }
+  return groups;
+}

package/templates/SCHEMA.md

@@ -91,13 +91,44 @@ Roster of council voices. Each member is defined once globally and referenced by
 
 ### `mcp_servers`
 
-Wired MCP servers — id-only references, with optional per-server overrides. The CLI's onboarding wizard suggests these from `templates/mcps/registry.json` based on the user's app stack.
+Wired MCP servers — id-only references in the user's `lifeos.config.json`, with optional per-server overrides. The CLI's onboarding wizard suggests these from `templates/mcps/registry.json` based on the user's app stack.
+
+In the user's config:
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
 | `id` | string | yes | Slug; must match a registry entry |
 | `config_overrides` | object | no | Per-server config (e.g., scopes, allowed folders, send_permission) |
 
+In the registry (`templates/mcps/registry.json`), each entry carries the metadata needed to install + auth:
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `id` | string | yes | Slug |
+| `name` | string | yes | Display name |
+| `category` | string | yes | Grouping (productivity, communication, engineering, etc.) |
+| `description` | string | yes | One-sentence description |
+| `status` | enum | yes | `reference` / `vendor-published` / `community` / `beta-unverified` / `use-at-your-own-risk` |
+| `repo_url` | string | no | Verified GitHub URL (null if beta-unverified) |
+| `runtime` | enum | yes | `npx` / `uvx` / `pip-install` / `git+pip` / `docker` / `remote` / `manual` |
+| `install_command` | string[] | no | Argv-style command to install/run the MCP. `null` if `manual` runtime |
+| `auth.method` | enum | yes | `oauth` / `api_key` / `none` |
+| `auth.env_var` | string | no | Name of the env var holding the credential |
+| `auth.help_url` | string | no | Where the user obtains credentials (e.g., `https://github.com/settings/tokens`) |
+| `auth.scope_hint` | string | no | Recommended scopes/permissions |
+| `risk_advisory` | string | no | Free-text warning surfaced for `use-at-your-own-risk` entries |
+| `useful_for_personas` | string[] | yes | Which persona templates suggest this MCP |
+| `last_verified` | string | yes | YYYY-MM-DD when registry entry was last verified against upstream |
+| `install_hint` | string | yes | Free-text fallback / additional context for the install path |
+
+#### Status enum reference
+
+- `reference` — Maintained by the MCP steering group. Most stable.
+- `vendor-published` — Published by the vendor whose product it integrates with (e.g. Stripe, Notion, Microsoft for Playwright). Generally vendor-supported.
+- `community` — Community-built, actively maintained as of `last_verified`. Multiple options often exist.
+- `beta-unverified` — We have not researched a current canonical implementation. Install path needs your own due diligence.
+- `use-at-your-own-risk` — Functions but carries significant risk. Currently only used for MCPs that violate the upstream service's ToS or carry account-ban risk (e.g., LinkedIn unofficial-API MCPs). Always read `risk_advisory` before installing.
+
 Server install details (package, runtime, auth method) live in the registry, not the config file. This keeps configs small and lets registry updates propagate without users regenerating their files.
 
 ### `agent_runtime`