@sbains2/lifeos 0.2.0 → 0.2.1

package/bin/lifeos.js

@@ -24,6 +24,10 @@ Wizard options:
                 defaults everywhere. Target install time: < 60 seconds.
 
 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)
@@ -53,6 +57,7 @@ async function main() {
       json: flags.has('--json'),
       quiet: flags.has('--quiet'),
       strict: flags.has('--strict'),
+      fix: flags.has('--fix'),
     });
     process.exit(exitCode);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sbains2/lifeos",
-  "version": "0.2.0",
+  "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

@@ -11,25 +11,79 @@
  */
 
 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 } = options;
+  const { json = false, quiet = false, strict = false, fix = false } = options;
 
   const result = runDoctor(targetDir);
 
-  if (json) {
+  if (json && !fix) {
     console.log(JSON.stringify(result, null, 2));
-  } else {
+    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));
   }
 
-  // Exit code: 1 if any error; 1 if any warning AND strict mode; else 0
-  if (result.summary.error > 0) return 1;
-  if (strict && result.summary.warn > 0) return 1;
+  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'));

package/src/index.js

@@ -26,7 +26,7 @@ export async function run(targetDir, options = {}) {
   const { minimal = false } = options;
 
   console.log('');
-  console.log(c.bold('lifeos') + c.dim(' v0.2.0 — scaffold a personal LifeOS'));
+  console.log(c.bold('lifeos') + c.dim(' v0.2.1 — 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)'));

package/src/remedy.js

@@ -0,0 +1,288 @@
+/**
+ * `lifeos doctor --fix` — deterministic remediation for an unhealthy scaffold.
+ *
+ * Trust posture:
+ * - NEVER touches user secrets (tokens, OAuth credentials)
+ * - NEVER edits the user's shell rc (~/.zshrc, ~/.bashrc)
+ * - NEVER overwrites existing files without backup
+ * - ONLY applies fixes for checks where the right action is unambiguous and
+ *   doesn't require user input
+ *
+ * What it can fix automatically:
+ * - Missing quadrant folders → mkdir -p (with placeholder README)
+ * - Missing council files → copy from bundled templates
+ * - Missing writing_style.md (when path is set in config) → create stub
+ * - Missing .env.example for required auth env vars → generate with help-URL
+ *   comments per env var. User sources it as .env.local after filling in
+ *   values.
+ *
+ * What it CANNOT fix automatically (must be user-driven):
+ * - Missing env var values (we'd need the secret)
+ * - Schema version mismatch (needs `lifeos migrate` — not yet implemented)
+ * - Empty brain index (needs `lifeos brain` — not yet implemented)
+ * - Missing MCP runtimes (npx / docker / uvx — user must install)
+ *
+ * Each fix returns { id, applied: boolean, action: string, message: string }.
+ * Caller decides how to render.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, copyFileSync, readFileSync } from 'node:fs';
+import { join, dirname, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadRegistry } from './templates-loader.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_COUNCIL = join(__dirname, '..', 'templates', 'council');
+
+/**
+ * Apply all deterministic fixes to a scaffold. Reads the same lifeos.config.json
+ * doctor reads. Returns { applied: [], skipped: [], summary }.
+ */
+export function applyDoctorFixes(targetDir, options = {}) {
+  const { allowWritingStyleStub = true, allowEnvExample = true } = options;
+
+  const configPath = join(targetDir, 'lifeos.config.json');
+  if (!existsSync(configPath)) {
+    return {
+      applied: [],
+      skipped: [{ id: 'config', reason: 'lifeos.config.json not found — nothing to remediate' }],
+      summary: { applied: 0, skipped: 1 },
+    };
+  }
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    return {
+      applied: [],
+      skipped: [{ id: 'config', reason: `JSON parse failed: ${err.message} — fix manually first` }],
+      summary: { applied: 0, skipped: 1 },
+    };
+  }
+
+  const applied = [];
+  const skipped = [];
+
+  // Fix 1: missing quadrant folders
+  for (const q of config.quadrants ?? []) {
+    if (!q.active) continue;
+    const fullPath = isAbsolute(q.path) ? q.path : join(targetDir, q.path);
+    if (existsSync(fullPath)) continue;
+    try {
+      mkdirSync(fullPath, { recursive: true });
+      const readme = join(fullPath, 'README.md');
+      if (!existsSync(readme)) {
+        writeFileSync(readme, quadrantReadme(q), 'utf8');
+      }
+      applied.push({
+        id: `quadrant_folder:${q.id}`,
+        action: `mkdir`,
+        message: `Created ${q.path}/ + placeholder README`,
+      });
+    } catch (err) {
+      skipped.push({ id: `quadrant_folder:${q.id}`, reason: `mkdir failed: ${err.message}` });
+    }
+  }
+
+  // Fix 2: missing council files
+  const councilDir = join(targetDir, '.claude', 'agents', 'council');
+  for (const member of config.council ?? []) {
+    if (!member.system_prompt_path) continue;
+    const filename = member.system_prompt_path.split('/').pop();
+    const installedPath = join(councilDir, filename);
+    if (existsSync(installedPath)) continue;
+    const templatePath = join(TEMPLATES_COUNCIL, filename);
+    if (!existsSync(templatePath)) {
+      skipped.push({
+        id: `council_file:${member.id}`,
+        reason: `bundled template missing for ${filename} — file may be custom; not auto-fixable`,
+      });
+      continue;
+    }
+    try {
+      mkdirSync(councilDir, { recursive: true });
+      copyFileSync(templatePath, installedPath);
+      applied.push({
+        id: `council_file:${member.id}`,
+        action: 'copy',
+        message: `Copied ${filename} from bundled templates`,
+      });
+    } catch (err) {
+      skipped.push({ id: `council_file:${member.id}`, reason: `copy failed: ${err.message}` });
+    }
+  }
+
+  // Fix 3: writing_style.md stub if path is set + file missing
+  if (allowWritingStyleStub && config.writing_style_path) {
+    const stylePath = isAbsolute(config.writing_style_path)
+      ? config.writing_style_path
+      : join(targetDir, config.writing_style_path);
+    if (!existsSync(stylePath)) {
+      try {
+        mkdirSync(dirname(stylePath), { recursive: true });
+        writeFileSync(stylePath, writingStyleStub(), 'utf8');
+        applied.push({
+          id: 'writing_style',
+          action: 'stub',
+          message: `Wrote stub at ${config.writing_style_path} — replace with a real sample of your writing`,
+        });
+      } catch (err) {
+        skipped.push({ id: 'writing_style', reason: `write failed: ${err.message}` });
+      }
+    }
+  }
+
+  // Fix 4: .env.example for required env vars
+  if (allowEnvExample) {
+    let registry = null;
+    try {
+      registry = loadRegistry();
+    } catch {
+      /* skip env example if registry unavailable */
+    }
+    if (registry) {
+      const envEntries = collectEnvEntries(config, registry);
+      if (envEntries.length > 0) {
+        const envExamplePath = join(targetDir, '.env.example');
+        const wasExisting = existsSync(envExamplePath);
+        try {
+          // Don't overwrite if user already customized — just notify
+          if (wasExisting) {
+            skipped.push({
+              id: 'env_example',
+              reason: `.env.example already exists — not overwriting (review and merge manually if needed)`,
+            });
+          } else {
+            writeFileSync(envExamplePath, envExampleContent(envEntries), 'utf8');
+            applied.push({
+              id: 'env_example',
+              action: 'generate',
+              message: `Wrote .env.example with ${envEntries.length} env var stub(s) + help URLs. Copy to .env.local, fill in values, then \`source .env.local\` before launching Claude.`,
+            });
+          }
+        } catch (err) {
+          skipped.push({ id: 'env_example', reason: `write failed: ${err.message}` });
+        }
+      }
+    }
+  }
+
+  return {
+    applied,
+    skipped,
+    summary: { applied: applied.length, skipped: skipped.length },
+  };
+}
+
+/**
+ * Collect env var entries needed by wired MCPs.
+ * Returns [{ env_var, mcp_id, mcp_name, help_url, scope_hint }].
+ */
+function collectEnvEntries(config, registry) {
+  const byId = new Map(registry.servers.map((s) => [s.id, s]));
+  const entries = [];
+  const seen = new Set();
+  for (const m of config.mcp_servers ?? []) {
+    const entry = byId.get(m.id);
+    if (!entry?.auth?.env_var) continue;
+    if (seen.has(entry.auth.env_var)) continue;
+    seen.add(entry.auth.env_var);
+    entries.push({
+      env_var: entry.auth.env_var,
+      mcp_id: entry.id,
+      mcp_name: entry.name,
+      help_url: entry.auth.help_url,
+      scope_hint: entry.auth.scope_hint,
+    });
+  }
+  return entries;
+}
+
+function envExampleContent(entries) {
+  const lines = [
+    '# LifeOS — wired MCP environment variables',
+    '#',
+    '# Generated by `lifeos doctor --fix`. To use:',
+    '#   1. Copy this file to .env.local in the same directory',
+    '#   2. Fill in each value from the help URLs below',
+    '#   3. Source it before launching Claude Code:',
+    '#        source .env.local',
+    '#      or add a permanent `set -a; source .env.local; set +a` to your shell rc.',
+    '#',
+    '# Trust note: .env.local should be gitignored (LifeOS scaffold .gitignore covers this).',
+    '# LifeOS itself never reads any value in this file — it\'s yours, in your shell.',
+    '',
+  ];
+
+  for (const e of entries) {
+    lines.push(`# ${e.mcp_name}`);
+    if (e.help_url) lines.push(`# Get one: ${e.help_url}`);
+    if (e.scope_hint) {
+      const wrapped = wrapText(`# Scope: ${e.scope_hint}`, 100);
+      lines.push(...wrapped);
+    }
+    lines.push(`export ${e.env_var}=`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function wrapText(text, maxWidth) {
+  const lines = [];
+  const prefix = text.startsWith('#') ? '# ' : '';
+  const content = text.startsWith('#') ? text.slice(2) : text;
+  const words = content.split(/\s+/);
+  let current = '';
+  for (const word of words) {
+    if (current.length + word.length + 1 > maxWidth - prefix.length) {
+      if (current) lines.push(prefix + current);
+      current = word;
+    } else {
+      current = current ? `${current} ${word}` : word;
+    }
+  }
+  if (current) lines.push(prefix + current);
+  return lines;
+}
+
+function quadrantReadme(q) {
+  return `# ${q.name}
+
+${q.description ?? ''}
+
+This folder is the home of your **${q.id}** quadrant. The LifeOS council members assigned to it will read files here as context when convened.
+
+## Council members assigned
+
+${(q.council_member_ids ?? []).map((id) => `- \`${id}\``).join('\n') || '_none_'}
+
+## MCP servers wired
+
+${(q.mcp_server_ids ?? []).map((id) => `- \`${id}\``).join('\n') || '_none_'}
+
+## Priority
+
+\`${q.priority}\` — change in \`lifeos.config.json\` to adjust how much airtime this quadrant gets in cross-quadrant convenings.
+`;
+}
+
+function writingStyleStub() {
+  return `# Writing style
+
+> This file anchors your voice for council members that produce written output (Writing Critic, Editor, etc.).
+> Replace this placeholder with a real sample of your writing — an email, an essay paragraph, a Slack message you're proud of.
+> The council reads this verbatim and tries to match the register. Be specific.
+
+## Style notes
+
+- _Tone:_ [e.g., formal-analytical, conversational, direct, hedged]
+- _Sentence length preference:_ [e.g., short and punchy / long and layered]
+- _Vocabulary preferences:_ [e.g., academic, plain-spoken, jargon-heavy]
+- _Avoid:_ [e.g., overly casual contractions, filler phrases, marketing-speak]
+
+## Sample (replace this entire section with your own)
+
+[Paste 200-500 words of your own writing here. Anything you wrote and stand behind.]
+`;
+}