runlist 0.0.0 → 0.94.2

package/src/update.mjs

@@ -0,0 +1,338 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { green, dim, yellow } from './color.mjs';
+import { executableName, which } from './util.mjs';
+import { CLAUDE_MARKETPLACE, claudeMarketplaceRefusalHint, installOpencodePlugin, opencodeStatus } from './host-integration.mjs';
+import { codexStatus } from './codex-integration.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+
+const NPM_PKG = 'runlist';
+const DEFAULT_PLUGIN_ID = 'runlist@runlist';
+export const LEGACY_PLUGIN_ID = 'dotmd@dotmd';
+
+// Parse an x.y.z prefix; returns [major, minor, patch] or null.
+function parseVer(v) {
+  if (typeof v !== 'string') return null;
+  const m = v.trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+// -1 if a<b, 0 if equal, 1 if a>b, null if either is unparseable.
+export function compareVersions(a, b) {
+  const pa = parseVer(a), pb = parseVer(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  return 0;
+}
+
+// Read Claude Code's plugin install record to find the installed runlist plugin's
+// id + version. Network-free. `opts.home` is injectable for tests. Returns
+// { id, version } or null when nothing is installed / the file is absent.
+export function readInstalledPluginRecords(opts = {}) {
+  const home = opts.home || os.homedir();
+  const file = path.join(home, '.claude', 'plugins', 'installed_plugins.json');
+  try {
+    const j = JSON.parse(readFileSync(file, 'utf8'));
+    const plugins = j.plugins || {};
+    const id = opts.id
+      ? (plugins[opts.id] ? opts.id : null)
+      : plugins[DEFAULT_PLUGIN_ID]
+        ? DEFAULT_PLUGIN_ID
+        : plugins[LEGACY_PLUGIN_ID]
+          ? LEGACY_PLUGIN_ID
+          : Object.keys(plugins).find(k => /^(?:runlist|dotmd)@/.test(k));
+    if (!id) return null;
+    const entries = Array.isArray(plugins[id]) ? plugins[id] : [plugins[id]];
+    return { id, entries: entries.filter(Boolean) };
+  } catch {
+    return null;
+  }
+}
+
+// Claude Code's marketplace registry, keyed by marketplace name. A plugin id
+// is `<plugin>@<marketplace>`, and the plugin only loads while its marketplace
+// is registered here — an install record alone is not an installed plugin.
+export function readKnownMarketplaces(opts = {}) {
+  const home = opts.home || os.homedir();
+  const file = path.join(home, '.claude', 'plugins', 'known_marketplaces.json');
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+// `marketplaceRegistered: false` is the state `claude plugin list` shows as
+// "failed to load: Marketplace runlist not found": the install record survived,
+// the marketplace registration did not (a settings.json declaration that no
+// longer matches, a wiped registry). Reading only the install record called
+// that "installed", so `runlist install claude` skipped the one repair it owns
+// and `runlist update` ran a `plugin update` that could only fail.
+export function readInstalledPlugin(opts = {}) {
+  const records = readInstalledPluginRecords(opts);
+  if (!records) return null;
+  const marketplace = records.id.split('@')[1] || null;
+  const known = readKnownMarketplaces(opts);
+  return {
+    id: records.id,
+    entries: records.entries,
+    version: records.entries[0]?.version ?? null,
+    marketplace,
+    marketplaceRegistered: Boolean(marketplace && known[marketplace]),
+  };
+}
+
+export function pluginScopeLabel(entry) {
+  return `${entry.scope ?? 'unknown scope'}${entry.projectPath ? ` (${entry.projectPath})` : ''}`;
+}
+
+const scopeKey = entry => JSON.stringify([entry.scope, entry.projectPath ?? null]);
+
+// Scope comes from the install registry, not the updater's current directory.
+// Never turn a missing project or unsupported scope into a user-wide update.
+export function planPluginUpdates(plugin) {
+  if (!plugin) return [];
+  if (!plugin?.entries) return [{ kind: 'plugin', cmd: ['claude', 'plugin', 'update', plugin.id] }];
+  const steps = [];
+  const seen = new Set();
+  for (const entry of plugin.entries) {
+    const key = scopeKey(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const scoped = entry.scope === 'project' || entry.scope === 'local';
+    if (!['user', 'project', 'local'].includes(entry.scope) ||
+        (scoped && (typeof entry.projectPath !== 'string' || !path.isAbsolute(entry.projectPath)))) {
+      steps.push({ kind: 'refusal', reason: `cannot update ${plugin.id} at ${pluginScopeLabel(entry)}: ${scoped ? 'an absolute project path is required' : 'scope is not writable by the Claude CLI'}` });
+      continue;
+    }
+    steps.push({ kind: 'plugin', scope: entry.scope, ...(scoped ? { cwd: entry.projectPath } : {}),
+      cmd: ['claude', 'plugin', 'update', plugin.id, '--scope', entry.scope] });
+  }
+  return steps;
+}
+
+// A zero command exit is insufficient: retain every original registration and
+// verify the fresh registry rather than trusting the first installation.
+export function verifyPluginScopeUpdates(before, after, { expectedVersion, minimumVersion } = {}) {
+  if (!before?.entries?.length) return { ok: false, reason: `${before?.id ?? DEFAULT_PLUGIN_ID} plugin is not installed` };
+  const failures = [];
+  const versions = new Set();
+  const targets = new Map([...before.entries, ...(after?.id === before.id ? after.entries : [])].map(entry => [scopeKey(entry), entry]));
+  for (const entry of targets.values()) {
+    const current = after?.id === before.id ? after.entries.filter(item => scopeKey(item) === scopeKey(entry)) : [];
+    if (!current.length) {
+      failures.push(`${pluginScopeLabel(entry)} registration disappeared`);
+      continue;
+    }
+    for (const item of current) {
+      versions.add(item.version);
+      if (parseVer(item.version) === null || (expectedVersion && item.version !== expectedVersion) ||
+          (minimumVersion && compareVersions(item.version, minimumVersion) < 0)) {
+        failures.push(`${pluginScopeLabel(entry)} has ${item.version ?? 'unknown'}, expected ${expectedVersion ?? (minimumVersion ? `at least ${minimumVersion}` : 'a valid version')}`);
+      }
+    }
+  }
+  if (!failures.length && versions.size > 1) failures.push('installed scopes have different versions');
+  return failures.length ? { ok: false, reason: `${before.id}: ${[...new Set(failures)].join('; ')}` } : { ok: true };
+}
+
+// The steps that put a plugin whose marketplace registration is gone back on
+// its feet. Only the marketplace runlist publishes has a source runlist knows; a
+// plugin installed from some other marketplace names a source we cannot guess.
+export function planMarketplaceRepair(plugin, { hasClaude, verb }) {
+  const reason = `marketplace "${plugin.marketplace}" is not registered, so the installed plugin cannot load`;
+  if (plugin.marketplace !== 'runlist') {
+    return [{ kind: 'skip', reason: `${reason} — re-add that marketplace (runlist does not know its source), then rerun` }];
+  }
+  if (!hasClaude) {
+    return [{ kind: 'manual', reason, lines: [`/plugin marketplace add ${CLAUDE_MARKETPLACE}`, `/plugin ${verb} ${plugin.id}`] }];
+  }
+  return [
+    { kind: 'marketplace', reason: `${reason} — re-adding it first`, cmd: ['claude', 'plugin', 'marketplace', 'add', CLAUDE_MARKETPLACE] },
+    ...(verb === 'update' ? planPluginUpdates(plugin).map(step => ({ ...step, needs: 'marketplace' }))
+      : [{ kind: 'plugin', needs: 'marketplace', cmd: ['claude', 'plugin', verb, plugin.id] }]),
+  ];
+}
+
+// Decide which steps `runlist update` should run. Pure — no side effects — so the
+// orchestration is unit-testable. `opts` = { cliOnly, pluginOnly }; `ctx` =
+// { plugin: {id,version}|null, hasClaude, hasNpm }.
+export function planUpdate(opts, ctx) {
+  const steps = [];
+  if (!opts.pluginOnly) {
+    steps.push(ctx.hasNpm
+      ? { kind: 'cli', cmd: ['npm', 'i', '-g', `${NPM_PKG}@latest`] }
+      : { kind: 'skip', reason: 'npm not found on PATH — skipping CLI update' });
+  }
+  if (!opts.cliOnly) {
+    if (!ctx.plugin) {
+      steps.push({ kind: 'skip', reason: 'runlist plugin not installed — skipping plugin update' });
+    } else if (ctx.plugin.id === LEGACY_PLUGIN_ID) {
+      if (ctx.hasClaude) {
+        steps.push({ kind: 'marketplace', cmd: ['claude', 'plugin', 'marketplace', 'add', CLAUDE_MARKETPLACE] });
+        steps.push({ kind: 'plugin', needs: 'marketplace', cmd: ['claude', 'plugin', 'install', DEFAULT_PLUGIN_ID] });
+        steps.push({ kind: 'legacy', needs: 'plugin', cmd: ['claude', 'plugin', 'uninstall', LEGACY_PLUGIN_ID] });
+      } else {
+        steps.push({ kind: 'manual', reason: 'Claude CLI not found', lines: [
+          `/plugin marketplace add ${CLAUDE_MARKETPLACE}`,
+          `/plugin install ${DEFAULT_PLUGIN_ID}`,
+          `/plugin uninstall ${LEGACY_PLUGIN_ID}`,
+        ] });
+      }
+    } else if (ctx.plugin.marketplaceRegistered === false) {
+      steps.push(...planMarketplaceRepair(ctx.plugin, { hasClaude: ctx.hasClaude, verb: 'update' }));
+    } else if (!ctx.hasClaude) {
+      steps.push({ kind: 'skip', reason: `claude CLI not found — run \`/plugin update ${ctx.plugin.id}\` from a session instead` });
+    } else {
+      steps.push(...planPluginUpdates(ctx.plugin));
+    }
+    if (ctx.legacyPlugin && ctx.plugin?.id !== LEGACY_PLUGIN_ID) {
+      steps.push(ctx.hasClaude
+        ? { kind: 'legacy', needs: 'plugin', cmd: ['claude', 'plugin', 'uninstall', LEGACY_PLUGIN_ID] }
+        : { kind: 'manual', reason: 'Legacy Claude plugin also installed', lines: [`/plugin uninstall ${LEGACY_PLUGIN_ID}`] });
+    }
+    // The OpenCode integration is a file runlist wrote, so it goes stale silently
+    // the moment the CLI moves on. Refresh it here — but only if it is already
+    // installed. `update` keeps hosts in lockstep; it never adopts a new one,
+    // which stays the job of the explicit `runlist install`.
+    if (ctx.opencode?.exists && ctx.opencode.stale) {
+      steps.push({ kind: 'opencode', path: ctx.opencode.path });
+    } else if (ctx.opencode?.foreign) {
+      steps.push({ kind: 'skip', reason: `${ctx.opencode.path} was not written by runlist — leaving it alone` });
+    }
+    if (ctx.codex?.foreign) {
+      steps.push({ kind: 'skip', reason: `${ctx.codex.plugin} was not written by runlist — leaving it alone` });
+    } else if (ctx.codex?.exists && (ctx.codex.stale || (!opts.pluginOnly && ctx.hasNpm))) {
+      steps.push({ kind: 'codex', cmd: ['runlist', 'install', 'codex'] });
+    }
+  }
+  return steps;
+}
+
+export function runUpdate(argv, _config, opts = {}) {
+  const check = argv.includes('--check');
+  const cliOnly = argv.includes('--cli-only');
+  const pluginOnly = argv.includes('--plugin-only');
+  const plugin = readInstalledPlugin();
+  const legacyPlugin = readInstalledPluginRecords({ id: LEGACY_PLUGIN_ID });
+
+  if (check) {
+    process.stdout.write(`runlist CLI:    ${pkg.version}\n`);
+    if (plugin) {
+      if (plugin.id === LEGACY_PLUGIN_ID || (legacyPlugin && plugin.id !== LEGACY_PLUGIN_ID)) {
+        process.stdout.write(yellow(`  legacy Claude plugin ${LEGACY_PLUGIN_ID} is installed — run \`runlist update --plugin-only\` to migrate.\n`));
+      }
+      for (const entry of plugin.entries) {
+        const cmp = compareVersions(entry.version, pkg.version);
+        const tag = cmp === 0 ? green('in sync')
+          : cmp === null ? dim('(unknown)')
+          : cmp < 0 ? yellow('behind — run `runlist update`')
+          : yellow('ahead — CLI is behind');
+        process.stdout.write(`runlist plugin: ${entry.version ?? '?'} (${plugin.id}; ${pluginScopeLabel(entry)}) ${tag}\n`);
+      }
+      if (plugin.marketplaceRegistered === false) {
+        process.stdout.write(yellow(`  marketplace "${plugin.marketplace}" is not registered — the plugin fails to load; run \`runlist install claude\`\n`));
+      }
+    } else {
+      process.stdout.write(dim('runlist plugin: not installed — `runlist install claude`\n'));
+    }
+    const oc = opencodeStatus({ version: pkg.version });
+    if (!oc.exists) process.stdout.write(dim('runlist opencode: not installed\n'));
+    else if (oc.foreign) process.stdout.write(`runlist opencode: ${yellow('unmanaged file — not written by runlist')}\n`);
+    else process.stdout.write(`runlist opencode: ${oc.version} ${oc.stale ? yellow('behind — run `runlist update`') : green('in sync')}\n`);
+    const cx = codexStatus({ version: pkg.version });
+    if (!cx.exists) process.stdout.write(dim('runlist codex: not installed\n'));
+    else if (cx.foreign) process.stdout.write(`runlist codex: ${yellow('unmanaged plugin directory')}\n`);
+    else process.stdout.write(`runlist codex: ${cx.version} ${cx.stale ? yellow('behind — run `runlist update`') : green('in sync')}\n`);
+    return;
+  }
+
+  const opencode = opencodeStatus({ version: pkg.version });
+  const codex = codexStatus({ version: pkg.version });
+  const steps = planUpdate({ cliOnly, pluginOnly }, { plugin, legacyPlugin, opencode, codex, hasClaude: which('claude'), hasNpm: which('npm') });
+  if (opts.dryRun) {
+    for (const step of steps) {
+      if (step.kind === 'skip') process.stdout.write(dim(`[dry-run] skip: ${step.reason}\n`));
+      else if (step.kind === 'manual') for (const line of step.lines) process.stdout.write(dim(`[dry-run] Run from a session: ${line}\n`));
+      else if (step.kind === 'opencode') process.stdout.write(dim(`[dry-run] Would refresh: ${step.path}\n`));
+      else if (step.kind === 'refusal') process.stdout.write(yellow(`[dry-run] Refused: ${step.reason}\n`));
+      else process.stdout.write(dim(`[dry-run] Would run: ${step.cmd.join(' ')}${step.cwd ? ` (in ${step.cwd})` : ''}\n`));
+    }
+    return;
+  }
+  // The hosts are independent: a failed `claude plugin update` says nothing
+  // about the OpenCode file, so every step runs and the failures are reported
+  // together at the end. Stopping at the first one left OpenCode stale behind a
+  // Claude registry problem — silently, since the abort said nothing about the
+  // steps it never reached.
+  let ran = false;
+  const failures = [];
+  const failedKinds = new Set();
+  for (const s of steps) {
+    if (s.kind === 'refusal') {
+      failures.push(s);
+      failedKinds.add('plugin');
+      process.stdout.write(yellow(`${s.reason}\n`));
+      continue;
+    }
+    if (s.kind === 'skip') {
+      process.stdout.write(dim(`skip: ${s.reason}\n`));
+      continue;
+    }
+    if (s.kind === 'manual') {
+      process.stdout.write(`${yellow(s.reason)} — run these from a Claude Code session:\n`);
+      for (const line of s.lines) process.stdout.write(`  ${line}\n`);
+      continue;
+    }
+    if (s.needs && failedKinds.has(s.needs)) {
+      process.stdout.write(dim(`skip: ${s.cmd.join(' ')} — the ${s.needs} step it depends on failed\n`));
+      continue;
+    }
+    if (s.kind === 'opencode') {
+      const result = installOpencodePlugin({ version: pkg.version });
+      process.stdout.write(dim(`refreshed opencode integration → ${pkg.version}  ${result.path}\n`));
+      ran = true;
+      continue;
+    }
+    if (s.reason) process.stdout.write(dim(`${s.reason}\n`));
+    process.stdout.write(dim(`$ ${s.cmd.join(' ')}${s.cwd ? ` (in ${s.cwd})` : ''}\n`));
+    const r = spawnSync(executableName(s.cmd[0]), s.cmd.slice(1), {
+      stdio: 'inherit',
+      ...(s.cwd ? { cwd: s.cwd } : {}),
+      shell: process.platform === 'win32',
+    });
+    ran = true;
+    if (r.status !== 0) {
+      failedKinds.add(s.kind);
+      failures.push(s);
+      process.stdout.write(yellow(`(${s.cmd[0]} ${r.error ? `failed: ${r.error.message}` : `exited ${r.status ?? '?'}`})\n`));
+      if (s.kind === 'marketplace') for (const line of claudeMarketplaceRefusalHint(plugin?.marketplace)) process.stdout.write(yellow(`${line}\n`));
+    }
+  }
+  if (plugin?.id === DEFAULT_PLUGIN_ID && steps.some(step => step.kind === 'plugin') && !failedKinds.has('plugin') && !failedKinds.has('marketplace')) {
+    // npm may have replaced this package while this process was running.
+    const currentVersion = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version;
+    const verified = verifyPluginScopeUpdates(plugin, readInstalledPluginRecords({ id: plugin.id }), { minimumVersion: currentVersion });
+    if (!verified.ok) {
+      failures.push({ reason: verified.reason });
+      process.stdout.write(yellow(`${verified.reason}\n`));
+    }
+  }
+  if (failures.length) {
+    process.stdout.write(yellow(`\n${failures.length === 1 ? '1 step' : `${failures.length} steps`} failed: ${failures.map(s => s.cmd ? `${s.cmd.join(' ')}${s.cwd ? ` (in ${s.cwd})` : ''}` : s.reason).join('; ')}\n`));
+    if (ran && failures.length < steps.filter(s => s.kind !== 'skip' && s.kind !== 'manual').length) {
+      process.stdout.write(dim('the other steps completed; restart your Claude Code session (or /reload-plugins) to apply them.\n'));
+    }
+    process.exitCode = 1;
+    return;
+  }
+  if (ran) {
+    process.stdout.write(green('\n✓ restart your Claude Code session (or /reload-plugins) to apply.\n'));
+  }
+}

package/src/use.mjs

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, die, resolveDocPath, toRepoPath } from './util.mjs';
+import { consumePrompt, pendingPromptsOldestFirst, resolvePromptInput } from './prompts.mjs';
+import { startPlan } from './lifecycle.mjs';
+import { resolveDocArg } from './index.mjs';
+
+// Top-level `runlist use [file]` — the single "start engaging with this doc"
+// verb. Dispatches by the target doc's `type:` so agents don't have to know
+// the verb-per-type rule:
+//   - prompt → print body + archive (one-shot consume)
+//   - plan   → set status in-session + print the plan card
+//   - doc    → print body (read-only)
+// With no argument, consumes the oldest pending prompt.
+export async function runUse(argv, config, opts = {}) {
+  const positional = argv.find(a => !a.startsWith('-'));
+  // `--no-claim` reads and archives a prompt without starting the plan it links.
+  const noClaim = argv.includes('--no-claim');
+  const promptOpts = { ...opts, noClaim };
+
+  if (!positional) {
+    const queue = pendingPromptsOldestFirst(config);
+    if (queue.length === 0) die('No pending prompts. Pass a file to use a plan or doc.');
+    const head = queue[0];
+    if (!head.abs) die(`Could not resolve path: ${head.doc.path}`);
+    return consumePrompt(head.abs, config, promptOpts);
+  }
+
+  // Exact path first, then prompt slugs (they keep precedence on a slug
+  // collision — consuming a prompt is the more common intent), then the
+  // shared resolver for plan/doc slugs, which dies with did-you-mean on miss.
+  const cwdPath = path.resolve(process.cwd(), positional);
+  const filePath = resolveDocPath(positional, config)
+    ?? (existsSync(cwdPath) ? cwdPath : null)
+    ?? resolvePromptInput(positional, config, { dieOnMiss: false })
+    ?? resolveDocArg(positional, config);
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter } = extractFrontmatter(raw);
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  const type = asString(parsed.type);
+
+  if (type === 'prompt') {
+    return consumePrompt(filePath, config, promptOpts);
+  }
+  if (noClaim) die('--no-claim applies to prompts only; a plan opened with `use` is always claimed.');
+  if (type === 'plan') {
+    // Mark in-session (pure frontmatter) and print the plan card.
+    return startPlan([filePath, ...argv.filter(a => a !== positional)], config, opts);
+  }
+  // Anything else (doc, untyped, custom): print the body. The frontmatter
+  // already names everything an agent needs to know about lifecycle for that
+  // type, so the verb stays a no-op read for non-actionable types.
+  process.stdout.write(raw);
+  if (!raw.endsWith('\n')) process.stdout.write('\n');
+  process.stderr.write(`${toRepoPath(filePath, config.repoRoot)} (${type ?? 'untyped'})\n`);
+}