@sbains2/lifeos 0.1.3 → 0.2.1

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.]
+`;
+}

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`