@litfamily/litmuse 0.0.0-stage → 0.1.0

package/lib/bundle.mjs

@@ -0,0 +1,128 @@
+import { createHash } from 'node:crypto';
+import {
+  readFileSync, readdirSync, lstatSync, existsSync, mkdirSync, copyFileSync, writeFileSync, renameSync, rmSync,
+} from 'node:fs';
+import { join, dirname, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertSafeWritePath } from './guard.mjs';
+
+export const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+export const PLUGIN_DIR = join(PACKAGE_ROOT, 'plugin');
+export const OWNER_FILE = '.litmuse-owner.json';
+
+export function readManifest(dir = PLUGIN_DIR) {
+  return JSON.parse(readFileSync(join(dir, '.muse-plugin', 'plugin.json'), 'utf8'));
+}
+
+export function packageVersion() {
+  return JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version;
+}
+
+// Minimal frontmatter reader: `key: value` lines, with JSON-style double-quoted values unquoted.
+export function parseFrontmatter(text) {
+  const m = /^---\n([\s\S]*?)\n---\n/.exec(text);
+  const out = {};
+  if (!m) return out;
+  for (const line of m[1].split('\n')) {
+    const i = line.indexOf(':');
+    if (i < 1) continue;
+    const key = line.slice(0, i).trim();
+    let value = line.slice(i + 1).trim();
+    if (value.startsWith('"')) {
+      try { value = JSON.parse(value); } catch { /* keep raw */ }
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+export function agentNames(dir = PLUGIN_DIR) {
+  const agents = join(dir, 'agents');
+  return existsSync(agents) ? readdirSync(agents).filter((f) => f.endsWith('.md')).map((f) => f.slice(0, -3)).sort() : [];
+}
+
+function listFiles(dir, base = dir, acc = []) {
+  for (const name of readdirSync(dir).sort()) {
+    const p = join(dir, name);
+    const st = lstatSync(p);
+    if (st.isSymbolicLink()) acc.push({ rel: relative(base, p), symlink: true });
+    else if (st.isDirectory()) listFiles(p, base, acc);
+    else acc.push({ rel: relative(base, p), symlink: false });
+  }
+  return acc;
+}
+
+const sha256 = (file) => createHash('sha256').update(readFileSync(file)).digest('hex');
+
+export function bundleHashes(dir = PLUGIN_DIR) {
+  const files = {};
+  for (const f of listFiles(dir)) {
+    if (f.rel === OWNER_FILE || f.symlink) continue;
+    files[f.rel] = sha256(join(dir, f.rel));
+  }
+  return files;
+}
+
+// Classifies the staging directory: absent, owned (ours and untouched), symlinked, foreign or modified.
+export function stageState(p) {
+  for (const candidate of [p.data, p.stage]) {
+    if (existsSync(candidate) || isDanglingLink(candidate)) {
+      if (lstatSync(candidate).isSymbolicLink()) return { state: 'symlinked', detail: `${candidate} is a symbolic link` };
+    }
+  }
+  if (!existsSync(p.stage)) return { state: 'absent' };
+  if (!lstatSync(p.stage).isDirectory()) return { state: 'foreign', detail: `${p.stage} is not a directory` };
+  const files = listFiles(p.stage);
+  if (files.length === 0) return { state: 'absent' };
+  const link = files.find((f) => f.symlink);
+  if (link) return { state: 'symlinked', detail: `${join(p.stage, link.rel)} is a symbolic link` };
+  const ownerPath = join(p.stage, OWNER_FILE);
+  if (!existsSync(ownerPath)) return { state: 'foreign', detail: `${p.stage} holds files LitMuse did not write` };
+  let owner;
+  try {
+    owner = JSON.parse(readFileSync(ownerPath, 'utf8'));
+  } catch {
+    return { state: 'foreign', detail: `${ownerPath} is unreadable` };
+  }
+  if (owner.product !== 'litmuse' || typeof owner.files !== 'object') return { state: 'foreign', detail: `${ownerPath} belongs to another product` };
+  const now = bundleHashes(p.stage);
+  const changed = [...new Set([...Object.keys(owner.files), ...Object.keys(now)])].filter((rel) => owner.files[rel] !== now[rel]);
+  if (changed.length) return { state: 'modified', detail: `changed since install: ${changed.slice(0, 5).join(', ')}${changed.length > 5 ? ', ...' : ''}`, version: owner.version };
+  return { state: 'owned', version: owner.version };
+}
+
+function isDanglingLink(p) {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+// Copies the packaged plugin into the staging directory through a temporary sibling and a rename.
+export function stageBundle(p, source = PLUGIN_DIR) {
+  assertSafeWritePath(p.stage);
+  for (const dir of [p.data, p.stage]) {
+    if (existsSync(dir) && lstatSync(dir).isSymbolicLink()) throw new Error(`refused: ${dir} is a symbolic link`);
+  }
+  mkdirSync(p.data, { recursive: true });
+  const tmp = `${p.stage}.tmp-${process.pid}`;
+  rmSync(tmp, { recursive: true, force: true });
+  for (const f of listFiles(source)) {
+    if (f.symlink) continue;
+    const to = join(tmp, f.rel);
+    mkdirSync(dirname(to), { recursive: true });
+    copyFileSync(join(source, f.rel), to);
+  }
+  const files = bundleHashes(tmp);
+  writeFileSync(join(tmp, OWNER_FILE), `${JSON.stringify({ product: 'litmuse', version: readManifest(source).version, files }, null, 2)}\n`);
+  if (existsSync(p.stage)) {
+    const old = `${p.stage}.old-${process.pid}`;
+    renameSync(p.stage, old);
+    renameSync(tmp, p.stage);
+    rmSync(old, { recursive: true, force: true });
+  } else {
+    renameSync(tmp, p.stage);
+  }
+  return Object.keys(files).length;
+}

package/lib/doctor.mjs

@@ -0,0 +1,156 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { findOnPath } from '../plugin/lib/host-process.mjs';
+import { hostPython } from '../plugin/lib/office-runtime.mjs';
+import { paths } from './paths.mjs';
+import { muse, museVersion, installedPlugin } from './muse.mjs';
+import { stageState, packageVersion, PLUGIN_DIR } from './bundle.mjs';
+import { approvalStates } from './approvals.mjs';
+import { checkUpdate } from './update-check.mjs';
+import { runtimeModules, callRuntime } from './runtime.mjs';
+
+const CATALOG_CAP = 32 * 1024;
+
+// Built from the skill folders, independently of the manifest that Muse reads, so a skill missing from the
+// manifest shows up as missing in Muse.
+export function expectedSkillIds(dir = PLUGIN_DIR) {
+  const root = join(dir, 'skills');
+  return readdirSync(root).filter((d) => existsSync(join(root, d, 'SKILL.md'))).sort().map((d) => `plugin:litmuse:${d}`);
+}
+
+// Host binaries the engines and skills call; a missing one is reported, never installed. Python and Node packages
+// come from the pinned engine runtimes below instead. A spec is found when every `all` program is on PATH, or an
+// `any` program is, or one of `files` exists, or its `env` variable is set. PATH is searched without a shell so the
+// same specs work with PATHEXT on Windows.
+export const RUNTIMES = [
+  { label: 'python3', python: true, fix: 'install Python 3.10 to 3.14 (python.org or your package manager); a newer python3 alone has no wheels for the pinned engines', skills: 'lit-docx, lit-pptx, lit-scientific-visualization, autoresearch' },
+  { label: 'Poppler (pdftoppm, pdftotext)', all: ['pdftoppm', 'pdftotext'], fix: 'brew install poppler (or your package manager\'s poppler-utils)', skills: 'lit-docx, lit-pptx' },
+  { label: 'LibreOffice (soffice)', any: ['soffice'], files: ['/Applications/LibreOffice.app/Contents/MacOS/soffice', 'C:\\Program Files\\LibreOffice\\program\\soffice.exe'], fix: 'install LibreOffice so documents can be rendered for checking', skills: 'lit-docx, lit-pptx' },
+  { label: 'pandoc', all: ['pandoc'], fix: 'brew install pandoc (or your package manager)', skills: 'lit-docx' },
+  { label: 'xelatex (optional)', all: ['xelatex'], fix: 'install a TeX distribution only if you want publisher-styled PDF', skills: 'lit-docx' },
+  { label: 'Chrome or Chromium', env: 'CHROME_PATH', files: ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe', 'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe'], any: ['google-chrome', 'chromium', 'chromium-browser'], fix: 'install Google Chrome or Chromium, or set CHROME_PATH', skills: 'frontend-ui-ux, visual-qa, browser-drive, lit-diagram-drawer, lit-typographic-motion' },
+  { label: 'ffmpeg', all: ['ffmpeg'], fix: 'brew install ffmpeg (or your package manager)', skills: 'lit-typographic-motion' },
+  { label: 'libwebp (img2webp, dwebp)', all: ['img2webp', 'dwebp'], fix: 'brew install webp (or your package manager\'s webp tools); gifski also works for covers', skills: 'lit-typographic-motion' },
+  { label: 'ast-grep', any: ['ast-grep', 'sg'], fix: 'npm i -g @ast-grep/cli', skills: 'structural-search' },
+];
+
+export function runtimeFound(spec, { env = process.env, platform = process.platform, exists } = {}) {
+  const look = (name) => findOnPath(name, { env, platform, ...(exists ? { exists } : {}) });
+  if (spec.python) {
+    return hostPython(env).ok;
+  }
+  if (spec.all) return spec.all.every((name) => look(name));
+  const fileExists = exists ?? existsSync;
+  return Boolean((spec.env && env[spec.env]) || (spec.files ?? []).some((file) => fileExists(file)) || (spec.any ?? []).some((name) => look(name)));
+}
+
+function engineRows(env) {
+  return runtimeModules().map((m) => {
+    const r = callRuntime(m, 'status', env);
+    const fix = `npx @litfamily/litmuse runtime install ${m.name}`;
+    if (r.error) return { status: 'INFO', label: `engine ${m.name}`, detail: `status check failed: ${r.error}`, fix };
+    if (r.ready) return { status: 'INFO', label: `engine ${m.name}`, detail: `ready${r.cache ? ` (${r.cache})` : ''}` };
+    // A pre-warm engine (motion) never installs from a session, so its fix is the terminal command, not a first use.
+    const when = r.prewarm ? 'run the fix from a terminal before first use' : 'the first use installs it';
+    return { status: 'INFO', label: `engine ${m.name}`, detail: `not installed yet${r.missing?.length ? `: ${r.missing.join(', ')}` : ''}; ${when}`, fix };
+  });
+}
+
+function runtimeRows(env) {
+  return [...RUNTIMES.map((r) => (runtimeFound(r, { env })
+    ? { status: 'INFO', label: `runtime ${r.label}`, detail: 'found' }
+    : { status: 'INFO', label: `runtime ${r.label}`, detail: `missing (used by ${r.skills})`, fix: r.fix })), ...engineRows(env)];
+}
+
+function baseName(skill) {
+  return String(skill.name ?? skill.id ?? '').replace(/^plugin:[^:]+:/, '').replace(/^bundled:/, '');
+}
+
+export async function doctor({ env = process.env, flags = {}, print = console.log }) {
+  const p = paths(env);
+  const rows = [];
+  const add = (status, label, detail, fix) => rows.push({ status, label, detail, ...(fix ? { fix } : {}) });
+
+  add('PASS', 'node', process.versions.node);
+  const mv = museVersion(env);
+  if (!mv) add('FAIL', 'muse', 'not found on PATH', 'install Muse Code: https://dev.meta.ai/docs/muse-code');
+  else add('PASS', 'muse', mv);
+
+  const st = stageState(p);
+  if (st.state === 'owned') add('PASS', 'bundle', `${p.stage} (LitMuse ${st.version}, unmodified)`);
+  else if (st.state === 'absent') add('FAIL', 'bundle', 'not installed', 'npx @litfamily/litmuse install');
+  else if (st.state === 'modified') add('FAIL', 'bundle', `modified: ${st.detail}`, `keep edits: mv "${p.stage}" "${p.stage}.saved"; or discard: npx @litfamily/litmuse uninstall --discard-modified; then install`);
+  else add('FAIL', 'bundle', `${st.state}: ${st.detail}`, `move it aside: mv "${p.stage}" "${p.stage}.saved"; then npx @litfamily/litmuse install`);
+
+  const plugin = mv ? installedPlugin(env) : null;
+  if (mv && !plugin) add('FAIL', 'plugin', 'LitMuse is not installed in Muse', 'npx @litfamily/litmuse install');
+  if (plugin) {
+    if (plugin.enabled === false) add('FAIL', 'plugin', 'installed but disabled', 'muse plugins enable litmuse');
+    else if (plugin.version && plugin.version !== packageVersion()) add('WARN', 'plugin', `Muse has LitMuse ${plugin.version}; this package is ${packageVersion()}`, 'npx @litfamily/litmuse install');
+    else add('PASS', 'plugin', `litmuse ${plugin.version ?? ''} installed and enabled`.trim());
+
+    for (const s of approvalStates(muse(env, ['plugins', 'inspect', 'litmuse', '--json']).json)) {
+      if (s.status === 'trusted_enabled') add('PASS', s.label, 'approved');
+      else if (s.status === 'review_needed') add('APPROVAL NEEDED', s.label, `run: muse plugins approve ${s.id}`, `muse plugins approve ${s.id}`);
+      else add('FAIL', s.label, `${s.status}${s.diagnostic ? `: ${JSON.stringify(s.diagnostic)}` : ''}`, `muse plugins approve ${s.id}`);
+    }
+
+    const list = muse(env, ['skills', 'list', '--json']).json?.skills ?? [];
+    const expected = expectedSkillIds();
+    const present = new Map(list.map((s) => [s.id, s]));
+    const missing = expected.filter((id) => present.get(id)?.activation !== 'on');
+    if (missing.length) add('FAIL', 'skills', `${expected.length - missing.length}/${expected.length} enrolled; missing or off: ${missing.join(', ')}`, 'npx @litfamily/litmuse install');
+    else add('PASS', 'skills', `${expected.length}/${expected.length} enrolled`);
+
+    const bytes = (s) => s.context_cost?.startup_bytes ?? 0;
+    const ours = list.filter((s) => String(s.id).startsWith('plugin:litmuse:')).reduce((n, s) => n + bytes(s), 0);
+    const whole = list.filter((s) => s.activation === 'on').reduce((n, s) => n + bytes(s), 0);
+    add('INFO', 'catalog', `LitMuse descriptions ${ours} B for ${expected.length} skills; whole catalog ${whole} B of ${CATALOG_CAP} B`);
+    if (whole > CATALOG_CAP) {
+      add('WARN', 'catalog', 'over the 32 KB cap: Muse keeps bundled descriptions, fills plugin descriptions in id order while they fit, and shortens the rest to id and path, so some LitMuse descriptions may be shortened; lit routes still load every LitMuse skill by id');
+    }
+
+    const ourIds = new Set(expected.map((id) => id.replace('plugin:litmuse:', '')));
+    for (const s of list) {
+      if (s.scope !== 'user' && s.scope !== 'project') continue;
+      if (ourIds.has(baseName(s))) add('WARN', 'overlap', `personal skill ${baseName(s)} (${s.path}) shares a name with a LitMuse skill; LitMuse routes load plugin:litmuse:${baseName(s)}`);
+      if (/\.claude\/plugins\//.test(String(s.path)) || /litclaude/i.test(`${s.id} ${s.path}`)) {
+        add('WARN', 'overlap', `${s.path} comes from another tool's plugin folder; LitMuse steers lit routes to its own skills`);
+      }
+    }
+  }
+
+  if (existsSync(p.foreignRules)) {
+    add('INFO', 'foreign rules', '~/.claude/CLAUDE.md is loaded by Muse as personal rules (Muse setting "Personal rules fallback"); LitMuse leaves it on and steers lit routes through its SessionStart context');
+  }
+
+  if (!flags.skipRuntimes && env.LITMUSE_SKIP_RUNTIMES !== '1') rows.push(...runtimeRows(env));
+
+  if (!flags.offline) {
+    const u = await checkUpdate(env);
+    if (u.latest) add('INFO', 'update', u.latest === packageVersion() ? `latest ${u.latest}` : `npm has ${u.latest}; run npx @litfamily/litmuse@latest install`);
+    else if (u.error) add('INFO', 'update', `not checked (${u.error})`);
+    else if (!u.skipped) add('INFO', 'update', 'no published version yet');
+  }
+
+  const fails = rows.filter((r) => r.status === 'FAIL').length;
+  const needed = rows.filter((r) => r.status === 'APPROVAL NEEDED').length;
+  const warns = rows.filter((r) => r.status === 'WARN').length;
+  const summary = fails
+    ? `LitMuse doctor: FAIL (${fails} failing check${fails === 1 ? '' : 's'}${needed ? `, ${needed} approvals needed` : ''})`
+    : needed
+      ? `LitMuse: installed, ${needed} approvals needed. Run the commands above or \`npx @litfamily/litmuse install --approve\`.`
+      : `LitMuse doctor: PASS${warns ? ` (${warns} warning${warns === 1 ? '' : 's'})` : ''}`;
+
+  if (flags.json) {
+    print(JSON.stringify({ rows, summary: { text: summary, fails, approvalsNeeded: needed, warnings: warns } }, null, 2));
+  } else {
+    for (const r of rows) {
+      const sep = r.status === 'APPROVAL NEEDED' ? ' — ' : ': ';
+      print(`${r.status} ${r.label}${sep}${r.detail}${r.fix && r.status === 'INFO' ? ` (fix: ${r.fix})` : ''}`);
+    }
+    print('');
+    print(summary);
+  }
+  return fails || needed ? 1 : 0;
+}

package/lib/guard.mjs

@@ -0,0 +1,11 @@
+import { sep } from 'node:path';
+
+const FOREIGN_DIRS = new Set(['.claude', '.codex']);
+
+// LitMuse writes only to its own data directory; another tool's home is never a destination.
+export function assertSafeWritePath(target) {
+  const parts = String(target).split(/[\\/]/).filter(Boolean);
+  const hit = parts.find((p) => FOREIGN_DIRS.has(p));
+  if (hit) throw new Error(`refused: LitMuse never writes under ${hit}${sep} (${target})`);
+  return target;
+}

package/lib/install.mjs

@@ -0,0 +1,168 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+import { paths } from './paths.mjs';
+import { preflightDestinations, writeFileAtomic, copyFileAtomic } from './safe-write.mjs';
+import { muse, museVersion, installedPlugin } from './muse.mjs';
+import { stageState, stageBundle, packageVersion } from './bundle.mjs';
+import { expectedApprovals, approvalStates } from './approvals.mjs';
+
+function remedy(state, detail, p) {
+  const saved = `${p.stage}.saved-${new Date().toISOString().slice(0, 10)}`;
+  if (state === 'symlinked') {
+    const link = detail.split(' is a symbolic link')[0];
+    return `Remove the link itself (the files it points to stay): rm "${link}" — then run install again.`;
+  }
+  if (state === 'foreign') return `LitMuse only replaces a bundle it wrote. Move that path aside: mv "${p.stage}" "${saved}" — then run install again.`;
+  return `The installed bundle was edited after install. Keep your edits with: mv "${p.stage}" "${saved}" — or discard them with: npx @litfamily/litmuse uninstall --discard-modified. Then run install again.`;
+}
+
+function stamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+// Copies the Muse files that install and approval will rewrite. The credential file is never read or copied.
+function backupHostFiles(p) {
+  const saved = [];
+  const at = stamp();
+  for (const file of [p.museSettings, p.museInstalled]) {
+    if (!existsSync(file)) continue;
+    saved.push(copyFileAtomic(file, join(p.backups, `${basename(file)}.${at}.bak`)));
+  }
+  return saved;
+}
+
+function samePath(a, b) {
+  const real = (x) => {
+    try { return realpathSync(x); } catch { return resolve(x); }
+  };
+  return real(a) === real(b);
+}
+
+export async function install({ env = process.env, flags = {}, interactive = false, ask, print = console.log }) {
+  const p = paths(env);
+  const version = packageVersion();
+  const scope = flags.scope || 'user';
+  print(`LitMuse ${version} installer for Muse Code`);
+
+  const major = Number(process.versions.node.split('.')[0]);
+  if (major < 20) {
+    print(`FAIL Node.js ${process.versions.node} is too old; LitMuse needs Node.js 20 or newer.`);
+    return 1;
+  }
+  const mv = museVersion(env);
+  if (!mv) {
+    print('FAIL muse was not found on PATH. Install Muse Code first (https://dev.meta.ai/docs/muse-code), sign in once, then run this again.');
+    return 1;
+  }
+  print(`Host: ${mv}`);
+
+  const st = preflightDestinations(p) ?? stageState(p);
+  if (['symlinked', 'foreign', 'modified'].includes(st.state)) {
+    print(`FAIL destination ${st.state}: ${st.detail}`);
+    print(remedy(st.state, st.detail, p));
+    print('No files written.');
+    return 1;
+  }
+
+  const existing = installedPlugin(env);
+  const existingSource = existing?.source?.path;
+  if (existingSource && !samePath(existingSource, p.stage)) {
+    print(`FAIL Muse already has LitMuse ${existing.version ?? ''} installed from ${existingSource}.`.replace('  ', ' '));
+    print(`This installer manages the copy in ${p.stage}. Remove the other one first with: muse plugins remove litmuse (this also clears its approvals), then run install again.`);
+    print('No files written.');
+    return 1;
+  }
+  const installArgs = existing ? ['plugins', 'update', 'litmuse', '--json'] : ['plugins', 'install', p.stage, '--scope', scope, '--json'];
+  const approvals = expectedApprovals();
+
+  print('');
+  print('Plan');
+  print(`  bundle      ${p.stage}${st.state === 'owned' ? ` (replaces LitMuse ${st.version})` : ''}`);
+  print(`  backups     ${p.backups} (Muse settings.json and installed.json, when present)`);
+  print(`  receipt     ${p.receipt}`);
+  print(`  muse        muse ${installArgs.join(' ')}`);
+  print(`  approvals   up to ${approvals.length} capabilities may need your approval in Muse (hooks and agents):`);
+  for (const a of approvals) print(`    ${a.id}`);
+
+  if (flags.dryRun) {
+    print('');
+    print('Dry run: no files written and no Muse command that changes state was run.');
+    return 0;
+  }
+  if (!interactive && !flags.yes) {
+    print('');
+    print('No files written: this shell has no terminal. Rerun with --yes to install (add --approve to approve the capabilities above as well).');
+    return 0;
+  }
+
+  const written = [];
+  written.push(...backupHostFiles(p));
+  stageBundle(p);
+  written.push(p.stage);
+
+  const validation = muse(env, ['plugins', 'validate', p.stage, '--json']);
+  const diagnostics = validation.json?.diagnostics ?? [];
+  if (!validation.ok || validation.json?.valid !== true || diagnostics.length) {
+    print('FAIL muse plugins validate rejected the bundle:');
+    for (const d of diagnostics) print(`  ${d.code ?? 'diagnostic'}: ${d.message ?? JSON.stringify(d)}`);
+    if (!diagnostics.length) print(`  ${validation.stderr.trim() || validation.stdout.trim()}`);
+    print('Muse was left unchanged.');
+    return 1;
+  }
+
+  const result = muse(env, installArgs);
+  if (!result.ok) {
+    print(`FAIL ${result.command} exited ${result.status}:`);
+    print(`  ${(result.stderr || result.stdout).trim().split('\n').slice(0, 6).join('\n  ')}`);
+    return 1;
+  }
+  const cachePath = result.json?.installed?.cache_path;
+  written.push(p.museInstalled);
+  if (cachePath) written.push(cachePath);
+  print('');
+  print(existing
+    ? `Installed: LitMuse ${version} is updated in Muse from ${p.stage}. Skills and commands are active now.`
+    : `Installed: LitMuse ${version} is installed in Muse at ${scope} scope. Skills and commands are active now.`);
+
+  let states = approvalStates(muse(env, ['plugins', 'inspect', 'litmuse', '--json']).json);
+  const pending = states.filter((s) => s.status !== 'trusted_enabled');
+  if (pending.length) {
+    print('');
+    print(`Muse runs plugin hooks and agents only after you approve them (an update re-arms the agent approvals, and the hook approvals whenever hook code changed). ${pending.length} are waiting:`);
+    for (const s of pending) print(`  ${s.id}  (${s.what})`);
+    let approve = Boolean(flags.approve);
+    if (!approve && interactive && ask) {
+      approve = await ask(`Approve these ${pending.length} LitMuse capabilities now? [y/N] `);
+    }
+    if (approve) {
+      const failed = [];
+      for (const s of pending) {
+        const r = muse(env, ['plugins', 'approve', s.id, '--json']);
+        if (!r.ok) failed.push(`${s.id}: ${(r.stderr || r.stdout).trim().split(/\r?\n/)[0]}`);
+      }
+      written.push(`${p.museSettings} (runtime_capabilities for litmuse)`);
+      for (const f of failed) print(`  FAIL approve ${f}`);
+      states = approvalStates(muse(env, ['plugins', 'inspect', 'litmuse', '--json']).json);
+    } else {
+      print('');
+      print('Approval needed. Run these when you are ready (or rerun install with --approve):');
+      for (const s of pending) print(`  muse plugins approve ${s.id}`);
+    }
+  }
+
+  const left = states.filter((s) => s.status !== 'trusted_enabled').length;
+  writeFileAtomic(p.receipt, `${JSON.stringify({
+    product: 'litmuse', version, scope, installedAt: new Date().toISOString(), host: mv,
+    written, approvals: states.map((s) => ({ id: s.id, status: s.status })),
+  }, null, 2)}\n`);
+  written.push(p.receipt);
+
+  print('');
+  print('Written:');
+  for (const w of written) print(`  ${w}`);
+  print('');
+  print(left === 0
+    ? 'Status: Ready. Start Muse in a project and begin a prompt with `lit`. Check any time with `npx @litfamily/litmuse doctor`.'
+    : `Status: installed, approval needed for ${left} capabilities. Run the commands above, then \`npx @litfamily/litmuse doctor\`.`);
+  return 0;
+}

package/lib/models.mjs

@@ -0,0 +1,57 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { paths } from './paths.mjs';
+
+// Models and effort tiers come only from the catalog Muse caches from its provider, so a model
+// the host adds tomorrow shows up here with no LitMuse release.
+export function listModels(env = process.env) {
+  const dir = paths(env).museCatalogDir;
+  if (!existsSync(dir)) return [];
+  const seen = new Map();
+  for (const file of readdirSync(dir).filter((f) => f.endsWith('.json')).sort()) {
+    let catalog;
+    try {
+      catalog = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+    } catch {
+      continue;
+    }
+    for (const row of Array.isArray(catalog.rows) ? catalog.rows : []) {
+      if (row.visibility !== 'visible' || typeof row.model_id !== 'string' || seen.has(row.model_id)) continue;
+      seen.set(row.model_id, {
+        id: row.model_id,
+        label: row.display_label || row.model_id,
+        isDefault: Boolean(row.is_default),
+        released: row.release_date ?? null,
+        efforts: (row.reasoning_effort_variants ?? []).map((v) => v.tier).filter(Boolean),
+      });
+    }
+  }
+  return [...seen.values()];
+}
+
+export function suggestedEffort(model) {
+  return model.efforts.includes('medium') ? 'medium' : model.efforts[0] ?? null;
+}
+
+export function models({ env = process.env, flags = {}, print = console.log }) {
+  const list = listModels(env);
+  if (flags.json) {
+    print(JSON.stringify(list, null, 2));
+    return list.length ? 0 : 1;
+  }
+  if (!list.length) {
+    print(`No Muse model catalog found in ${paths(env).museCatalogDir}. Start Muse once (the TUI or \`muse exec\`) so it caches the catalog, then run this again.`);
+    return 1;
+  }
+  print('Models your Muse install offers (from its own catalog):');
+  for (const m of list) {
+    print(`  ${m.id}${m.isDefault ? ' (default)' : ''}  efforts: ${m.efforts.join(', ') || 'host default'}`);
+  }
+  print('');
+  print('Pick one per run:');
+  for (const m of list) {
+    const effort = suggestedEffort(m);
+    print(`  muse --model ${m.id}${effort ? ` --reasoning-effort ${effort}` : ''}`);
+  }
+  return 0;
+}

package/lib/muse.mjs

@@ -0,0 +1,37 @@
+import { spawnSync } from 'node:child_process';
+
+// Calls the Muse CLI with stdin closed, the equivalent of `< /dev/null`, so no command can wait on a prompt.
+export function muse(env, args, { timeoutMs = 120000 } = {}) {
+  const bin = env.LITMUSE_MUSE_BIN || 'muse';
+  const r = spawnSync(bin, args, { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: timeoutMs });
+  let json = null;
+  if (args.includes('--json') && r.stdout) {
+    try {
+      json = JSON.parse(r.stdout);
+    } catch {
+      json = null;
+    }
+  }
+  return {
+    ok: r.status === 0,
+    status: r.status,
+    stdout: r.stdout ?? '',
+    stderr: r.stderr ?? '',
+    json,
+    missing: r.error?.code === 'ENOENT',
+    command: ['muse', ...args].join(' '),
+  };
+}
+
+export function museVersion(env) {
+  const r = muse(env, ['--version'], { timeoutMs: 30000 });
+  return r.ok ? r.stdout.trim() : null;
+}
+
+export function installedPlugin(env) {
+  const r = muse(env, ['plugins', 'list', '--json']);
+  const list = r.json?.plugins ?? [];
+  if (!Array.isArray(list)) return null;
+  // Muse 1.4.10 wraps each entry as { record: {...}, warning, plugin }; accept a bare record too.
+  return list.map((p) => p.record ?? p).find((p) => p.id === 'litmuse') ?? null;
+}

package/lib/paths.mjs

@@ -0,0 +1,22 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// Every location LitMuse reads or writes, resolved from one environment so tests can sandbox HOME.
+export function paths(env = process.env) {
+  const home = env.HOME || homedir();
+  const dataHome = env.XDG_DATA_HOME || join(home, '.local', 'share');
+  const configHome = env.XDG_CONFIG_HOME || join(home, '.config');
+  const data = join(dataHome, 'litmuse');
+  return {
+    home,
+    data,
+    stage: join(data, 'bundle'),
+    backups: join(data, 'backups'),
+    receipt: join(data, 'receipt.json'),
+    updateCache: join(data, 'update-check.json'),
+    museSettings: join(configHome, 'muse', 'settings.json'),
+    museInstalled: join(dataHome, 'muse', 'plugins', 'installed.json'),
+    museCatalogDir: join(dataHome, 'muse', 'model-catalog'),
+    foreignRules: join(home, '.claude', 'CLAUDE.md'),
+  };
+}

package/lib/runtime.mjs

@@ -0,0 +1,73 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { PLUGIN_DIR } from './bundle.mjs';
+import { paths } from './paths.mjs';
+
+// Pinned engine runtimes (office, diagram, frontend, ...) each ship one `<name>-runtime.mjs` module in the plugin,
+// in `lib/` or in a skill's `scripts/`. The module installs only into the LitMuse cache and answers
+// `status --json` / `install --json` with {name, ready, cache, missing}.
+export function runtimeModules(dir = PLUGIN_DIR) {
+  const found = [];
+  const scan = (folder) => {
+    if (!existsSync(folder)) return;
+    for (const f of readdirSync(folder)) if (f.endsWith('-runtime.mjs')) found.push({ name: f.slice(0, -'-runtime.mjs'.length), file: join(folder, f) });
+  };
+  scan(join(dir, 'lib'));
+  const skills = join(dir, 'skills');
+  if (existsSync(skills)) for (const id of readdirSync(skills).sort()) scan(join(skills, id, 'scripts'));
+  return found.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function runtimeEnv(env) {
+  const p = paths(env);
+  return { ...env, XDG_DATA_HOME: env.XDG_DATA_HOME || join(p.home, '.local', 'share') };
+}
+
+export function callRuntime(mod, action, env, { timeoutMs = 30000 } = {}) {
+  const r = spawnSync(process.execPath, [mod.file, action, '--json'], { env: runtimeEnv(env), encoding: 'utf8', timeout: timeoutMs, stdio: ['ignore', 'pipe', 'pipe'] });
+  const out = String(r.stdout ?? '').trim();
+  let json = null;
+  for (const candidate of [out, out.slice(out.indexOf('{')), out.split('\n').filter(Boolean).pop() ?? '']) {
+    try {
+      json = JSON.parse(candidate);
+      break;
+    } catch { /* try the next shape; reported below when none parses */ }
+  }
+  if (r.status !== 0 || !json || typeof json.ready !== 'boolean') {
+    const last = String(r.stderr ?? '').trim().split(/\r?\n/).pop();
+    return { name: mod.name, ready: false, error: r.error ? `could not start: ${r.error.message}` : `exit ${r.status}: ${last || 'no status output'}` };
+  }
+  return { ...json, name: json.name ?? mod.name };
+}
+
+export async function runtime({ env = process.env, flags = {}, args = [], print = console.log }) {
+  const [action = 'status', want] = args;
+  const mods = runtimeModules();
+  if (!['status', 'install'].includes(action)) {
+    print('Usage: litmuse runtime status [name] | litmuse runtime install <name|all>');
+    return 2;
+  }
+  if (action === 'install' && !want) {
+    print(`Name a runtime to install (${mods.map((m) => m.name).join(', ') || 'none shipped'}) or all.`);
+    return 2;
+  }
+  const picked = want && want !== 'all' ? mods.filter((m) => m.name === want) : mods;
+  if (want && want !== 'all' && picked.length === 0) {
+    print(`Unknown runtime: ${want} (shipped: ${mods.map((m) => m.name).join(', ') || 'none'})`);
+    return 2;
+  }
+  if (action === 'install' && flags.dryRun) {
+    for (const m of picked) print(`would install runtime ${m.name} with ${relative(PLUGIN_DIR, m.file)} into ${join(paths(env).data, 'runtime', m.name)}`);
+    return 0;
+  }
+  const results = picked.map((m) => callRuntime(m, action, env, { timeoutMs: action === 'install' ? 900000 : 30000 }));
+  if (flags.json) print(JSON.stringify({ runtimes: results }, null, 2));
+  else {
+    for (const r of results) {
+      const state = r.error ? `error: ${r.error}` : r.ready ? 'ready' : `not ready${r.missing?.length ? ` (missing: ${r.missing.join(', ')})` : ''}`;
+      print(`${r.name}: ${state}${r.cache ? ` · ${r.cache}` : ''}`);
+    }
+  }
+  return results.every((r) => !r.error && (action === 'status' || r.ready)) ? 0 : 1;
+}