@sbains2/lifeos 0.1.3 → 0.2.1

package/README.md

@@ -46,14 +46,22 @@ See [../docs/TRUST.md](../docs/TRUST.md) for the full commitments.
 
 After the wizard prints `Done in Xm Ys.`, here's the path from "scaffold exists" to "council convenes on real artifacts":
 
-### 1. Wire your MCP servers (10-30 min the first time)
+### 1. Set env vars + restart Claude (~3-5 min the first time)
 
-Open `.lifeos/INSTALL_MCPS.md` in the scaffolded directory. For each MCP listed:
+As of v0.1.5, the wizard does the heavy lifting for you:
 
-- Read the install hint (most point to a Smithery search or specific GitHub repo)
-- Install the MCP via the recommended method (usually `npx` or `uvx` — no Docker for v0.1 picks)
-- Set the auth env var in your shell (`export GITHUB_PERSONAL_ACCESS_TOKEN=...`, etc. — see each MCP's docs)
-- Verify the MCP shows up in your Claude Code config (`~/.claude/settings.json` or your IDE's MCP settings)
+- **`.mcp.json` is already written** in your scaffold dir — Claude Code, Cursor, and Cline auto-detect this
+- **Claude Desktop config was offered for merge** (with backup) if you said yes
+- **Per-MCP setup status was already printed** at the end of the wizard — read it carefully
+
+What you still need to do, listed in the wizard's status report:
+
+- **For `needs_env` MCPs:** set the env var in your shell (`export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...`) — the wizard surfaced exactly which env vars + the URL to get each one. Add to your `~/.zshrc` or `~/.bashrc` for persistence.
+- **For `needs_oauth` MCPs:** Claude will trigger the OAuth flow on first invocation — usually opens a browser, you click Authorize, done.
+- **For `manual` MCPs:** read `.lifeos/INSTALL_MCPS.md` for install hints; these are MCPs without a single-command auto-install (e.g., Canvas, Discord, Apple Notes). One-time clone + build per repo.
+- **For `risk` MCPs (only LinkedIn at v0.1.5):** if you said "yes, include in auto-config" the entry was wired; if "no" the MCP is in your `lifeos.config.json` but skipped from `.mcp.json` — install manually.
+
+**Then restart Claude Desktop** (Cmd+Q, then reopen) so the new MCPs load. For Claude Code, restart your terminal or run `claude /mcp` to see the wired list.
 
 ### 2. Open the folder in Claude Code
 

package/bin/lifeos.js

@@ -1,41 +1,75 @@
 #!/usr/bin/env node
 import { run } from '../src/index.js';
+import { runDoctorCommand } from '../src/commands/doctor.js';
 
-// Parse argv: positional target dir + flags
-// Usage: lifeos [target-dir] [--minimal]
+// Parse argv: optional subcommand + positional target dir + flags
+// Usage:
+//   lifeos [target-dir] [--minimal]              # wizard (default)
+//   lifeos doctor [target-dir] [--json] [--quiet] [--strict]
 const args = process.argv.slice(2);
 const flags = new Set(args.filter((a) => a.startsWith('--')));
-const positional = args.filter((a) => !a.startsWith('--'));
+const positional = args.filter((a) => !a.startsWith('--') && !a.startsWith('-'));
 
-if (flags.has('--help') || flags.has('-h')) {
-  console.log(`lifeos — scaffold a personal LifeOS
+if (flags.has('--help') || flags.has('-h') || positional[0] === 'help') {
+  console.log(`lifeos — scaffold and verify a personal LifeOS
 
 Usage:
-  lifeos [target-dir] [options]
+  lifeos [target-dir] [options]                   # run the wizard
+  lifeos doctor [target-dir] [options]            # verify scaffold health
+  lifeos --help                                   # show this
 
-Options:
+Wizard options:
   --minimal     Skip optional substantive prompts (longer-arc focus,
                 quadrant/council/MCP confirmations). Uses template
                 defaults everywhere. Target install time: < 60 seconds.
-  --help, -h    Show this help
+
+Doctor options:
+  --fix         Apply deterministic fixes (mkdir folders, copy missing
+                council files, generate writing_style stub, generate
+                .env.example with help URLs). Never touches secrets or
+                shell rc. Re-runs doctor after to show before/after.
+  --json        Emit machine-readable JSON (for CI / scripting)
+  --quiet       Suppress ✓ lines, only show warnings and errors
+  --strict      Exit code 1 even on warnings (default: warnings are 0)
 
 Arguments:
-  target-dir    Directory to scaffold into (default: current working dir)
+  target-dir    Directory to scaffold into / verify (default: current working dir)
 
 Examples:
-  lifeos                       # scaffold into current dir, full wizard
-  lifeos ~/my-lifeos           # scaffold into ~/my-lifeos
-  lifeos ~/my-lifeos --minimal # speed-optimized install
+  lifeos                                          # scaffold into current dir, full wizard
+  lifeos ~/my-lifeos                              # scaffold into ~/my-lifeos
+  lifeos ~/my-lifeos --minimal                    # speed-optimized install
+  lifeos doctor                                   # verify current dir
+  lifeos doctor ~/my-lifeos                       # verify ~/my-lifeos
+  lifeos doctor --json | jq '.summary'            # programmatic check
 `);
   process.exit(0);
 }
 
-const targetDir = positional[0] ?? process.cwd();
-const options = {
-  minimal: flags.has('--minimal'),
-};
+// Subcommand dispatch
+const subcommand = ['doctor', 'brain', 'migrate'].includes(positional[0]) ? positional[0] : null;
+const remainingPositional = subcommand ? positional.slice(1) : positional;
+const targetDir = remainingPositional[0] ?? process.cwd();
+
+async function main() {
+  if (subcommand === 'doctor') {
+    const exitCode = await runDoctorCommand(targetDir, {
+      json: flags.has('--json'),
+      quiet: flags.has('--quiet'),
+      strict: flags.has('--strict'),
+      fix: flags.has('--fix'),
+    });
+    process.exit(exitCode);
+  }
+  if (subcommand === 'brain' || subcommand === 'migrate') {
+    console.error(`\nNot yet implemented: \`lifeos ${subcommand}\`. See docs/COMMANDS.md for the design.`);
+    process.exit(2);
+  }
+  // Default: run the wizard
+  await run(targetDir, { minimal: flags.has('--minimal') });
+}
 
-run(targetDir, options).catch((err) => {
+main().catch((err) => {
   // Inquirer throws ExitPromptError when user hits Ctrl+C — handle gracefully
   if (err?.name === 'ExitPromptError') {
     console.log('\nCancelled.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sbains2/lifeos",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Scaffold a personal LifeOS — life-quadrant folders, a council of AI agent voices, and curated MCP wiring. Generates a working lifeos.config.json + .claude/agents/council/ in 2-4 minutes (or <60s with --minimal). BETA — early seed release.",
   "type": "module",
   "bin": {

package/src/commands/doctor.js

@@ -0,0 +1,132 @@
+/**
+ * `lifeos doctor` subcommand orchestrator.
+ *
+ * Runs the doctor checks against a target directory, prints a per-check report,
+ * and exits with code 0 (all green or warnings only) or 1 (any error).
+ *
+ * Supports:
+ *   --json   — emit machine-readable JSON instead of formatted output
+ *   --quiet  — suppress ✓ lines, only show warnings + errors
+ *   --strict — exit code 1 even on warnings (default treats warnings as 0)
+ */
+
+import { runDoctor } from '../doctor.js';
+import { applyDoctorFixes } from '../remedy.js';
+import { c } from '../utils/colors.js';
+
+export async function runDoctorCommand(targetDir, options = {}) {
+  const { json = false, quiet = false, strict = false, fix = false } = options;
+
+  const result = runDoctor(targetDir);
+
+  if (json && !fix) {
+    console.log(JSON.stringify(result, null, 2));
+    if (result.summary.error > 0) return 1;
+    if (strict && result.summary.warn > 0) return 1;
+    return 0;
+  }
+
+  if (!fix) {
+    printHumanReport(result, { quiet });
+    if (result.summary.error > 0) return 1;
+    if (strict && result.summary.warn > 0) return 1;
+    return 0;
+  }
+
+  // --fix mode: print initial state, apply remedies, re-run doctor, print final state
+  console.log('');
+  console.log(c.bold('lifeos doctor --fix') + c.dim(' — initial state'));
+  console.log('');
+  printSummaryLine(result.summary);
+
+  const remedy = applyDoctorFixes(targetDir);
+  console.log('');
+  console.log(c.bold('Applying deterministic fixes...'));
+  if (remedy.applied.length === 0) {
+    console.log(c.dim(`  ${c.dot} nothing to auto-fix (issues remaining need user input — see suggestions below)`));
+  } else {
+    for (const fix of remedy.applied) {
+      console.log(`  ${c.check} ${fix.id}: ${fix.message}`);
+    }
+  }
+  if (remedy.skipped.length > 0) {
+    console.log(c.dim(`  Skipped (need manual action):`));
+    for (const s of remedy.skipped) {
+      console.log(c.dim(`    ${c.dot} ${s.id}: ${s.reason}`));
+    }
+  }
+
+  // Re-run doctor to show new state
+  console.log('');
+  console.log(c.bold('Re-running doctor...'));
+  console.log('');
+  const after = runDoctor(targetDir);
+  printHumanReport(after, { quiet });
+
+  if (json) {
+    console.log('');
+    console.log(c.dim('--json + --fix combined: emitting after-state JSON'));
+    console.log(JSON.stringify(after, null, 2));
+  }
+
+  if (after.summary.error > 0) return 1;
+  if (strict && after.summary.warn > 0) return 1;
+  return 0;
+}
+
+function printSummaryLine(summary) {
+  const { ok, warn, error } = summary;
+  const parts = [
+    `${c.ok(`${ok} ok`)}`,
+    warn > 0 ? c.warn(`${warn} warning${warn === 1 ? '' : 's'}`) : null,
+    error > 0 ? c.err(`${error} error${error === 1 ? '' : 's'}`) : null,
+  ].filter(Boolean);
+  console.log('  ' + parts.join(', '));
+}
+
+function printHumanReport(result, { quiet }) {
+  console.log('');
+  console.log(c.bold('lifeos doctor') + c.dim(' — checking your scaffold'));
+  console.log('');
+
+  for (const check of result.checks) {
+    if (quiet && check.status === 'ok') continue;
+    const icon =
+      check.status === 'ok'
+        ? c.ok('✓')
+        : check.status === 'warn'
+          ? c.warn('⚠')
+          : c.err('✗');
+    const label = check.status === 'ok' ? c.dim(check.name) : check.name;
+    console.log(`  ${icon} ${label}`);
+    if (check.message && check.status !== 'ok') {
+      // Wrap long messages
+      const lines = check.message.split('\n');
+      for (const line of lines) console.log(c.dim(`     ${line}`));
+    }
+    if (check.fix) {
+      const fixLines = check.fix.split('\n');
+      console.log(c.cyan(`     → fix: ${fixLines[0]}`));
+      for (let i = 1; i < fixLines.length; i++) {
+        console.log(c.cyan(`           ${fixLines[i].replace(/^\s+/, '')}`));
+      }
+    }
+  }
+
+  console.log('');
+  const { ok, warn, error } = result.summary;
+  const summaryParts = [
+    `${c.ok(`${ok} ok`)}`,
+    warn > 0 ? c.warn(`${warn} warning${warn === 1 ? '' : 's'}`) : null,
+    error > 0 ? c.err(`${error} error${error === 1 ? '' : 's'}`) : null,
+  ].filter(Boolean);
+  console.log(c.bold('Summary: ') + summaryParts.join(', '));
+  if (error === 0 && warn === 0) {
+    console.log(c.dim('Your scaffold looks healthy. Open it in Claude Code and convene the council.'));
+  } else if (error === 0) {
+    console.log(c.dim('Mostly good — warnings are non-blocking but worth addressing when you have a moment.'));
+  } else {
+    console.log(c.dim('Errors above will block convening. Apply the fixes shown.'));
+  }
+  console.log('');
+}

package/src/doctor.js

@@ -0,0 +1,329 @@
+/**
+ * `lifeos doctor` — verifies post-install health of a LifeOS scaffold.
+ *
+ * Loads the user's `lifeos.config.json` and runs 8 checks:
+ * 1. Config exists + parses
+ * 2. Schema version matches CLI's supported version
+ * 3. Schema cross-refs (reuses validate.js — same checks the wizard runs at write time)
+ * 4. Council files present at the paths config references
+ * 5. Quadrant folders exist for every active quadrant
+ * 6. Env vars set for every wired MCP that needs auth (read-only check —
+ *    never reads the value, only checks `process.env[name]` is truthy)
+ * 7. Writing-style file present (if `writing_style_path` is set)
+ * 8. Brain artifact populated (warning if `.lifeos/brain/` is empty)
+ *
+ * Plus a bonus check (added for v0.2.0):
+ * 9. MCP runtimes available (npx / uvx / docker — checks `which <runtime>` for
+ *    each unique runtime referenced by wired MCPs)
+ *
+ * Each check returns { id, name, status: 'ok'|'warn'|'error', message, fix? }.
+ * Caller decides how to render and what exit code to use.
+ */
+
+import { existsSync, readFileSync, accessSync, readdirSync, constants } from 'node:fs';
+import { join, dirname, isAbsolute } from 'node:path';
+import { execSync } from 'node:child_process';
+import { listCouncilFiles, loadRegistry } from './templates-loader.js';
+import { validate } from './validate.js';
+
+const SUPPORTED_VERSION = '0.2';
+
+/**
+ * Run all checks against a directory. Returns { checks: [], summary: {ok, warn, error} }.
+ */
+export function runDoctor(targetDir) {
+  const checks = [];
+
+  // Check 1: config exists + parses
+  const configPath = join(targetDir, 'lifeos.config.json');
+  let config = null;
+  if (!existsSync(configPath)) {
+    checks.push({
+      id: 'config_exists',
+      name: 'lifeos.config.json present',
+      status: 'error',
+      message: `File not found at ${configPath}`,
+      fix: `Run \`npx @sbains2/lifeos ${targetDir}\` to scaffold a fresh config.`,
+    });
+    return finalize(checks);
+  }
+
+  try {
+    config = JSON.parse(readFileSync(configPath, 'utf8'));
+    checks.push({
+      id: 'config_exists',
+      name: 'lifeos.config.json present + parses',
+      status: 'ok',
+      message: `Loaded config (schema v${config.version})`,
+    });
+  } catch (err) {
+    checks.push({
+      id: 'config_exists',
+      name: 'lifeos.config.json present + parses',
+      status: 'error',
+      message: `JSON parse failed: ${err.message}`,
+      fix: `Open ${configPath} in an editor and fix the JSON syntax.`,
+    });
+    return finalize(checks);
+  }
+
+  // Check 2: schema version
+  if (config.version !== SUPPORTED_VERSION) {
+    checks.push({
+      id: 'schema_version',
+      name: `Schema version matches (cli wants v${SUPPORTED_VERSION})`,
+      status: 'error',
+      message: `Config is at v${config.version}, but this CLI was built for v${SUPPORTED_VERSION}`,
+      fix: `Either upgrade your config (when \`lifeos migrate\` ships) or pin to a CLI version compatible with v${config.version}.`,
+    });
+  } else {
+    checks.push({
+      id: 'schema_version',
+      name: `Schema version matches (v${SUPPORTED_VERSION})`,
+      status: 'ok',
+    });
+  }
+
+  // Check 3: schema cross-refs (reuse validate.js)
+  const validateResult = validate(config, { targetDir });
+  if (validateResult.ok) {
+    checks.push({
+      id: 'schema_cross_refs',
+      name: 'Schema cross-refs resolve (council ↔ quadrants ↔ MCPs)',
+      status: 'ok',
+    });
+  } else {
+    checks.push({
+      id: 'schema_cross_refs',
+      name: 'Schema cross-refs resolve',
+      status: 'error',
+      message: validateResult.errors.join('; '),
+      fix: 'Re-run the wizard with `npx @sbains2/lifeos` to regenerate from a clean template, or fix the references manually in lifeos.config.json.',
+    });
+  }
+  for (const w of validateResult.warnings) {
+    checks.push({
+      id: 'schema_warning',
+      name: 'Schema warning',
+      status: 'warn',
+      message: w,
+    });
+  }
+
+  // Check 4: council files present
+  const councilFilesMissing = [];
+  for (const member of config.council ?? []) {
+    if (!member.system_prompt_path) continue;
+    const filename = member.system_prompt_path.split('/').pop();
+    const installedPath = join(targetDir, '.claude', 'agents', 'council', filename);
+    if (!existsSync(installedPath)) {
+      councilFilesMissing.push({ id: member.id, expected: installedPath });
+    }
+  }
+  if (councilFilesMissing.length === 0) {
+    checks.push({
+      id: 'council_files',
+      name: `Council files present (${(config.council ?? []).length} members)`,
+      status: 'ok',
+    });
+  } else {
+    checks.push({
+      id: 'council_files',
+      name: 'Council files present',
+      status: 'error',
+      message: `Missing files for: ${councilFilesMissing.map((c) => c.id).join(', ')}`,
+      fix: `Re-run \`npx @sbains2/lifeos ${targetDir}\` to copy the bundled council prompts.`,
+    });
+  }
+
+  // Check 5: quadrant folders exist (active only)
+  const missingFolders = [];
+  for (const q of config.quadrants ?? []) {
+    if (!q.active) continue;
+    const fullPath = isAbsolute(q.path) ? q.path : join(targetDir, q.path);
+    if (!existsSync(fullPath)) {
+      missingFolders.push({ id: q.id, expected: fullPath });
+    }
+  }
+  const activeQuadrantCount = (config.quadrants ?? []).filter((q) => q.active).length;
+  if (missingFolders.length === 0) {
+    checks.push({
+      id: 'quadrant_folders',
+      name: `Active quadrant folders exist (${activeQuadrantCount} active)`,
+      status: 'ok',
+    });
+  } else {
+    checks.push({
+      id: 'quadrant_folders',
+      name: 'Active quadrant folders exist',
+      status: 'warn',
+      message: `Missing: ${missingFolders.map((m) => m.id).join(', ')}`,
+      fix: `mkdir -p ${missingFolders.map((m) => m.expected).join(' ')}`,
+    });
+  }
+
+  // Check 6: env vars set for wired MCPs (read-only — never reads the value)
+  let registry = null;
+  try {
+    registry = loadRegistry();
+  } catch {
+    /* registry not loadable — skip env-var check */
+  }
+  const missingEnv = [];
+  if (registry) {
+    const byId = new Map(registry.servers.map((s) => [s.id, s]));
+    for (const m of config.mcp_servers ?? []) {
+      const entry = byId.get(m.id);
+      if (!entry?.auth?.env_var) continue;
+      const envName = entry.auth.env_var;
+      if (!process.env[envName]) {
+        missingEnv.push({ id: m.id, env_var: envName, help_url: entry.auth.help_url });
+      }
+    }
+  }
+  if (missingEnv.length === 0) {
+    const wiredAuthCount = (config.mcp_servers ?? []).filter((m) => {
+      const entry = registry?.servers.find((s) => s.id === m.id);
+      return entry?.auth?.env_var;
+    }).length;
+    checks.push({
+      id: 'env_vars',
+      name: `Auth env vars set (${wiredAuthCount} wired MCPs need credentials)`,
+      status: 'ok',
+    });
+  } else {
+    checks.push({
+      id: 'env_vars',
+      name: 'Auth env vars set for wired MCPs',
+      status: 'error',
+      message: missingEnv
+        .map((m) => `${m.id} needs ${m.env_var}${m.help_url ? ` (get one: ${m.help_url})` : ''}`)
+        .join('; '),
+      fix: `Set the missing env vars in your shell rc (~/.zshrc or ~/.bashrc), e.g.:\n     ${missingEnv
+        .map((m) => `export ${m.env_var}=...`)
+        .join('\n     ')}\n   Then reload your shell + restart Claude.`,
+    });
+  }
+
+  // Check 7: writing_style file present (if path set)
+  if (config.writing_style_path) {
+    const stylePath = isAbsolute(config.writing_style_path)
+      ? config.writing_style_path
+      : join(targetDir, config.writing_style_path);
+    if (existsSync(stylePath)) {
+      checks.push({
+        id: 'writing_style',
+        name: 'writing_style.md present',
+        status: 'ok',
+      });
+    } else {
+      checks.push({
+        id: 'writing_style',
+        name: 'writing_style.md present',
+        status: 'warn',
+        message: `Path set but file not found: ${stylePath}`,
+        fix: `Either create the file (with a sample of your writing) or remove writing_style_path from lifeos.config.json.`,
+      });
+    }
+  }
+
+  // Check 8: brain artifact populated (warning only)
+  const brainPath = join(targetDir, config.brain?.graphify?.output ?? '.lifeos/brain');
+  if (existsSync(brainPath)) {
+    let brainEmpty = true;
+    try {
+      brainEmpty = readdirSync(brainPath).length === 0;
+    } catch {
+      /* permissions issue, skip */
+    }
+    if (brainEmpty) {
+      checks.push({
+        id: 'brain',
+        name: 'Brain index populated',
+        status: 'warn',
+        message: `${brainPath} exists but is empty`,
+        fix: `Run \`npx @sbains2/lifeos brain\` to populate the brain (when that command ships in v0.2.x).`,
+      });
+    } else {
+      checks.push({
+        id: 'brain',
+        name: 'Brain index populated',
+        status: 'ok',
+      });
+    }
+  }
+
+  // Check 9: MCP runtimes available (npx / uvx / docker)
+  const wiredRuntimes = new Set();
+  if (registry) {
+    const byId = new Map(registry.servers.map((s) => [s.id, s]));
+    for (const m of config.mcp_servers ?? []) {
+      const entry = byId.get(m.id);
+      if (entry?.runtime && entry.runtime !== 'manual' && entry.runtime !== 'remote') {
+        wiredRuntimes.add(entry.runtime);
+      }
+    }
+  }
+  // Map our runtime enum to the actual binary to check
+  const runtimeBinaries = {
+    npx: 'npx',
+    uvx: 'uvx',
+    'pip-install': 'pip',
+    'git+pip': 'pip',
+    docker: 'docker',
+  };
+  const missingRuntimes = [];
+  for (const rt of wiredRuntimes) {
+    const binary = runtimeBinaries[rt] ?? rt;
+    try {
+      execSync(`command -v ${binary}`, { stdio: 'ignore' });
+    } catch {
+      missingRuntimes.push({ runtime: rt, binary });
+    }
+  }
+  if (wiredRuntimes.size === 0) {
+    // No runtime needed — all MCPs are manual / remote
+    checks.push({
+      id: 'runtimes',
+      name: 'MCP runtimes available',
+      status: 'ok',
+      message: 'No automated runtimes wired (all MCPs are manual or remote)',
+    });
+  } else if (missingRuntimes.length === 0) {
+    checks.push({
+      id: 'runtimes',
+      name: `MCP runtimes available (${[...wiredRuntimes].join(', ')})`,
+      status: 'ok',
+    });
+  } else {
+    const fixes = missingRuntimes
+      .map((m) => {
+        if (m.binary === 'npx') return 'Install Node.js 20+ from https://nodejs.org';
+        if (m.binary === 'uvx') return 'Install uv from https://docs.astral.sh/uv/getting-started/installation/';
+        if (m.binary === 'docker') return 'Install Docker Desktop from https://docker.com';
+        if (m.binary === 'pip') return 'Install Python 3.10+ + pip from https://python.org';
+        return `Install ${m.binary}`;
+      })
+      .join('; ');
+    checks.push({
+      id: 'runtimes',
+      name: 'MCP runtimes available',
+      status: 'warn',
+      message: `Missing: ${missingRuntimes.map((m) => m.binary).join(', ')} (needed for: ${missingRuntimes
+        .map((m) => m.runtime)
+        .join(', ')})`,
+      fix: fixes,
+    });
+  }
+
+  return finalize(checks);
+}
+
+function finalize(checks) {
+  const summary = {
+    ok: checks.filter((c) => c.status === 'ok').length,
+    warn: checks.filter((c) => c.status === 'warn').length,
+    error: checks.filter((c) => c.status === 'error').length,
+  };
+  return { checks, summary };
+}