@litfamily/litmuse 0.0.0-stage → 0.1.0

package/lib/safe-write.mjs

@@ -0,0 +1,72 @@
+import { lstatSync, realpathSync, writeFileSync, renameSync, copyFileSync, mkdirSync, rmSync } from 'node:fs';
+import { dirname, basename, join } from 'node:path';
+import { assertSafeWritePath } from './guard.mjs';
+
+function lstatOrNull(p) {
+  try {
+    return lstatSync(p);
+  } catch {
+    return null;
+  }
+}
+
+// The nearest existing ancestor, resolved through links, so the guard judges where bytes really land.
+function realExistingAncestor(p) {
+  let cur = p;
+  while (!lstatOrNull(cur) && dirname(cur) !== cur) cur = dirname(cur);
+  return realpathSync(cur);
+}
+
+// Checks every LitMuse destination before the first write: links and wrong file types stop the install.
+export function preflightDestinations(p) {
+  const checks = [
+    [p.data, 'directory'], [p.stage, 'directory'], [p.backups, 'directory'],
+    [p.receipt, 'file'], [p.updateCache, 'file'],
+  ];
+  for (const [target, kind] of checks) {
+    const st = lstatOrNull(target);
+    if (!st) continue;
+    if (st.isSymbolicLink()) return { state: 'symlinked', detail: `${target} is a symbolic link` };
+    if (kind === 'file' && !st.isFile()) return { state: 'foreign', detail: `${target} is not a regular file` };
+    if (kind === 'directory' && !st.isDirectory()) return { state: 'foreign', detail: `${target} is not a directory` };
+  }
+  assertSafeWritePath(realExistingAncestor(p.data));
+  return null;
+}
+
+function assertWritableTarget(target) {
+  const parent = dirname(target);
+  const pst = lstatOrNull(parent);
+  if (pst && (pst.isSymbolicLink() || !pst.isDirectory())) throw new Error(`refused: ${parent} is not a real directory`);
+  const st = lstatOrNull(target);
+  if (st && !st.isFile()) throw new Error(`refused: ${target} is a link or not a regular file`);
+  assertSafeWritePath(target);
+  assertSafeWritePath(realExistingAncestor(parent));
+}
+
+// Writes through a temp file in the same directory and a rename, which replaces the entry instead of following it.
+export function writeFileAtomic(target, content) {
+  assertWritableTarget(target);
+  mkdirSync(dirname(target), { recursive: true });
+  const tmp = join(dirname(target), `.${basename(target)}.tmp-${process.pid}`);
+  try {
+    writeFileSync(tmp, content, { flag: 'wx' });
+    renameSync(tmp, target);
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+  return target;
+}
+
+export function copyFileAtomic(source, target) {
+  assertWritableTarget(target);
+  mkdirSync(dirname(target), { recursive: true });
+  const tmp = join(dirname(target), `.${basename(target)}.tmp-${process.pid}`);
+  try {
+    copyFileSync(source, tmp);
+    renameSync(tmp, target);
+  } finally {
+    rmSync(tmp, { force: true });
+  }
+  return target;
+}

package/lib/stage-card.mjs

@@ -0,0 +1,102 @@
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { latestFile, readStage, stageFile, workspaceHash } from '../plugin/hooks/lib/stage.mjs';
+
+export function fmtDuration(ms) {
+  const s = Math.max(0, Math.floor(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${String(s % 60).padStart(2, '0')}s`;
+  return `${Math.floor(m / 60)}h ${String(m % 60).padStart(2, '0')}m`;
+}
+
+// Plan rows are `- [ ] N. text` / `- [x] N. text`, read live from the plan file.
+export function planProgress(cwd, planFile) {
+  try {
+    let file = planFile;
+    if (!file) {
+      const dir = join(cwd, 'plans');
+      if (!existsSync(dir)) return null;
+      let best = null;
+      for (const name of readdirSync(dir).filter((f) => f.endsWith('.md'))) {
+        const m = statSync(join(dir, name)).mtimeMs;
+        if (/^- \[[ xX]\] \d+\./m.test(readFileSync(join(dir, name), 'utf8')) && (!best || m > best.m)) best = { name, m };
+      }
+      if (!best) return null;
+      file = `plans/${best.name}`;
+    }
+    const rows = [...readFileSync(join(cwd, file), 'utf8').matchAll(/^- \[([ xX])\] (\d+)\.\s*(.*)$/gm)];
+    if (!rows.length) return null;
+    const open = rows.find((r) => r[1] === ' ');
+    return {
+      file, total: rows.length, done: rows.filter((r) => r[1] !== ' ').length,
+      next: open ? { row: Number(open[2]), text: open[3].slice(0, 120) } : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function activeGoal(cwd) {
+  try {
+    const dir = join(cwd, '.litmuse', 'goals');
+    let best = null;
+    for (const name of readdirSync(dir).filter((f) => f.endsWith('.json'))) {
+      try {
+        const g = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+        const m = statSync(join(dir, name)).mtimeMs;
+        if (g && g.status === 'active' && (!best || m > best.m)) best = { g, m };
+      } catch { /* skip unreadable goal */ }
+    }
+    if (!best) return null;
+    const criteria = Array.isArray(best.g.criteria) ? best.g.criteria : [];
+    return {
+      slug: best.g.slug ?? null, objective: String(best.g.objective ?? '').slice(0, 200),
+      met: criteria.filter((c) => c.status === 'pass').length, total: criteria.length,
+      open: criteria.filter((c) => c.status !== 'pass').map((c) => ({ id: c.id, text: String(c.text ?? '').slice(0, 120) })),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function loadStage({ cwd, session, env = process.env }) {
+  if (session) return readStage(stageFile(cwd, session, env));
+  const ptr = readStage(latestFile(env));
+  const entry = ptr && ptr[workspaceHash(cwd)];
+  return entry && entry.session ? readStage(stageFile(cwd, entry.session, env)) : null;
+}
+
+export function buildCard({ cwd, session, env = process.env, now = Date.now() }) {
+  const rec = loadStage({ cwd, session, env });
+  const goal = activeGoal(cwd);
+  if (!rec) return { active: false, route: null, goal, plan: planProgress(cwd, null), lanes: [], now };
+  const lanes = (rec.lanes ?? []).map((l) => ({
+    id: l.id, type: l.type, status: l.status,
+    elapsedMs: (l.endedAt ?? now) - l.startedAt,
+  }));
+  return {
+    active: Boolean(rec.route), route: rec.route ?? null, keyword: rec.keyword ?? null, kind: rec.kind ?? null,
+    session: rec.session ?? null, activeMs: rec.route && rec.activatedAt ? now - rec.activatedAt : null,
+    plan: planProgress(cwd, rec.plan ?? null), lanes, goal, updated: rec.updated ?? null, now,
+  };
+}
+
+export function renderCard(card) {
+  const out = [];
+  out.push(card.active
+    ? `LIT · ${card.route}${card.activeMs !== null ? ` · active ${fmtDuration(card.activeMs)}` : ''}${card.kind && card.kind !== 'ignite' ? ` (${card.kind})` : ''}`
+    : 'LIT · no active route in this workspace');
+  if (card.plan) {
+    out.push(`plan ${card.plan.done}/${card.plan.total} · ${card.plan.file}${card.plan.next ? ` · next ${card.plan.next.row}. ${card.plan.next.text}` : ' · all rows ticked'}`);
+  }
+  const running = card.lanes.filter((l) => l.status === 'running');
+  const finished = card.lanes.filter((l) => l.status !== 'running');
+  if (running.length) out.push(`lanes running: ${running.map((l) => `${l.type} ${fmtDuration(l.elapsedMs)}`).join(', ')}`);
+  if (finished.length) out.push(`lanes finished: ${finished.map((l) => `${l.type} ${l.status} ${fmtDuration(l.elapsedMs)}`).join(', ')}`);
+  if (card.goal) {
+    out.push(`goal: ${card.goal.objective} (${card.goal.met}/${card.goal.total} criteria met)`);
+    for (const c of card.goal.open.slice(0, 5)) out.push(`  open ${c.id}: ${c.text}`);
+  }
+  return out.join('\n');
+}

package/lib/style.mjs

@@ -0,0 +1,41 @@
+import { readFileSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+import { paths } from './paths.mjs';
+import { writeFileAtomic } from './safe-write.mjs';
+
+export const STYLES = ['eli5', 'asd-ste100'];
+
+const stylePath = (env) => join(paths(env).data, 'style.json');
+
+// The chosen style name, or null when none is set or the file is unreadable, a link, or names an unknown style.
+export function readStyle(env = process.env) {
+  try {
+    const file = stylePath(env);
+    if (lstatSync(file).isSymbolicLink()) return null;
+    const { style } = JSON.parse(readFileSync(file, 'utf8'));
+    return STYLES.includes(style) ? style : null;
+  } catch {
+    return null;
+  }
+}
+
+// `litmuse style eli5|asd-ste100|off|status`; returns the exit code.
+export function styleCommand(args, env = process.env, print = console.log) {
+  const [word] = args;
+  if (!word || word === 'status') {
+    print(`LitMuse output style: ${readStyle(env) ?? 'off'}`);
+    return 0;
+  }
+  if (word !== 'off' && !STYLES.includes(word)) {
+    print(`Unknown style "${word}". Use one of: ${STYLES.join(', ')}, off, status.`);
+    return 1;
+  }
+  try {
+    writeFileAtomic(stylePath(env), `${JSON.stringify({ style: word === 'off' ? null : word, updatedAt: new Date().toISOString() })}\n`);
+  } catch (e) {
+    print(`LitMuse could not save the style: ${e.message}`);
+    return 1;
+  }
+  print(word === 'off' ? 'LitMuse output style: off. It applies from the next session start.' : `LitMuse output style: ${word}. It applies from the next session start.`);
+  return 0;
+}

package/lib/uninstall.mjs

@@ -0,0 +1,42 @@
+import { rmSync } from 'node:fs';
+import { paths } from './paths.mjs';
+import { muse, installedPlugin } from './muse.mjs';
+import { stageState } from './bundle.mjs';
+import { assertSafeWritePath } from './guard.mjs';
+
+export async function uninstall({ env = process.env, flags = {}, interactive = false, print = console.log }) {
+  const p = paths(env);
+  const plugin = installedPlugin(env);
+  const st = stageState(p);
+  print('LitMuse uninstall');
+  print(`  muse plugin   ${plugin ? 'muse plugins remove litmuse (also clears its approvals)' : 'not installed in Muse'}`);
+  const discard = st.state === 'modified' && flags.discardModified;
+  const bundleLine = st.state === 'owned' || discard
+    ? `remove ${p.stage}${discard ? ` (discarding edits: ${st.detail})` : ''}`
+    : st.state === 'absent' ? 'absent' : `keep ${p.stage} (${st.state}: ${st.detail})`;
+  print(`  bundle        ${bundleLine}`);
+  if (st.state === 'modified' && !discard) print('  hint          add --discard-modified to remove the edited bundle too');
+  print(`  kept          ${p.backups} and ${p.receipt}`);
+  if (flags.dryRun) {
+    print('Dry run: nothing removed.');
+    return 0;
+  }
+  if (!interactive && !flags.yes) {
+    print('Nothing removed: this shell has no terminal. Rerun with --yes.');
+    return 0;
+  }
+  if (plugin) {
+    const r = muse(env, ['plugins', 'remove', 'litmuse', '--json']);
+    if (!r.ok) {
+      print(`FAIL ${r.command}: ${(r.stderr || r.stdout).trim().split(/\r?\n/)[0]}`);
+      return 1;
+    }
+    print('Removed the LitMuse plugin from Muse.');
+  }
+  if (st.state === 'owned' || discard) {
+    rmSync(assertSafeWritePath(p.stage), { recursive: true, force: true });
+    print(`Removed ${p.stage}.`);
+  }
+  print('Project files LitMuse sessions wrote (plans/, .litmuse/) stay in each project.');
+  return 0;
+}

package/lib/update-check.mjs

@@ -0,0 +1,30 @@
+import { paths } from './paths.mjs';
+import { writeFileAtomic } from './safe-write.mjs';
+
+const REGISTRY = 'https://registry.npmjs.org/@litfamily%2flitmuse/latest';
+
+// Asks npm for the latest published version and caches the answer for the SessionStart hook.
+export async function checkUpdate(env = process.env) {
+  if (env.LITMUSE_NO_UPDATE_CHECK === '1') return { skipped: true };
+  let latest = null;
+  let error = null;
+  try {
+    const res = await fetch(REGISTRY, { signal: AbortSignal.timeout(3000) });
+    if (res.ok) latest = (await res.json()).version ?? null;
+    else if (res.status !== 404) error = `registry answered ${res.status}`;
+  } catch (e) {
+    error = e.name === 'TimeoutError' ? 'registry timed out' : 'registry unreachable';
+  }
+  if (!error) writeCache(env, { latest });
+  return { latest, error };
+}
+
+// The cache is a convenience for the SessionStart hook; a link or odd file in its place is left alone.
+export function writeCache(env, { latest }) {
+  try {
+    writeFileAtomic(paths(env).updateCache, `${JSON.stringify({ latest, checkedAt: Date.now() })}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@litfamily/litmuse",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Installer for LitMuse: skills, hooks and agents that help Meta's Muse Code plan, build, check and hand off work.",
+  "keywords": [
+    "muse",
+    "muse-code",
+    "coding-agent",
+    "agent-skills",
+    "hooks",
+    "planning",
+    "code-review",
+    "research",
+    "context-handoff",
+    "korean"
+  ],
+  "type": "module",
+  "bin": {
+    "litmuse": "bin/litmuse.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check:version": "node scripts/check-version.mjs",
+    "scan:legacy-tokens": "node scripts/scan-legacy-tokens.mjs",
+    "qa:muse": "node scripts/qa-muse-surface.mjs",
+    "qa:muse-live": "node scripts/qa-muse-live.mjs",
+    "sync:digests": "node scripts/sync-hook-digests.mjs",
+    "check:digests": "node scripts/sync-hook-digests.mjs --check",
+    "qa:cover-recipes": "node scripts/qa-cover-recipes.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "plugin",
+    "docs/hud-preset.md",
+    "docs/assets/cover-motion.webp",
+    "docs/assets/cover-motion-still.webp",
+    "README.md",
+    "README_ko-KR.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wjgoarxiv/litmuse.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wjgoarxiv/litmuse/issues"
+  },
+  "homepage": "https://github.com/wjgoarxiv/litmuse#readme",
+  "license": "MIT",
+  "author": "LitMuse contributors"
+}