baldart 3.6.2

package/src/utils/hooks.js

@@ -0,0 +1,152 @@
+/**
+ * Consumer-side hook registration for `.claude/settings.json`.
+ *
+ * BALDART ships a Claude Code PreToolUse hook (`framework-edit-gate`) that
+ * intercepts Edit / Write / MultiEdit calls targeting files inside
+ * `.framework/` and blocks them with an informative reason if the new
+ * content contains project-specific tokens (Neo-Brutalism, merchant,
+ * Recharts, secrets, hardcoded paths, …).
+ *
+ * Registration is auto-handled by `baldart add` and re-checked by
+ * `baldart update` / `baldart doctor`. The user can remove the entry from
+ * `.claude/settings.json` if they want to disable it.
+ *
+ * Schema: the hook config under `hooks.PreToolUse[]` follows Claude Code's
+ * documented hook format. Each entry has a `matcher` (tool name regex) and
+ * an inner `hooks[]` array of `{ type: "command", command: <shell> }`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SETTINGS_FILE = path.join('.claude', 'settings.json');
+const HOOK_ID = 'baldart-framework-edit-gate';
+const HOOK_COMMAND = 'node .framework/framework/.claude/hooks/framework-edit-gate.js';
+const HOOK_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
+
+function readSettings(cwd = process.cwd()) {
+  const full = path.join(cwd, SETTINGS_FILE);
+  if (!fs.existsSync(full)) return { path: full, settings: null, malformed: false };
+  try {
+    const raw = fs.readFileSync(full, 'utf8');
+    if (!raw.trim()) return { path: full, settings: {}, malformed: false };
+    return { path: full, settings: JSON.parse(raw), malformed: false };
+  } catch (_) {
+    return { path: full, settings: null, malformed: true };
+  }
+}
+
+function writeSettings(settingsPath, settings) {
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Returns true iff the framework-edit-gate hook is already registered in
+ * `.claude/settings.json` (matching either by command string or by the
+ * HOOK_ID marker we plant in a sibling property).
+ */
+function isRegistered(cwd = process.cwd()) {
+  const { settings } = readSettings(cwd);
+  if (!settings || !settings.hooks || !Array.isArray(settings.hooks.PreToolUse)) return false;
+  for (const entry of settings.hooks.PreToolUse) {
+    if (!entry || !Array.isArray(entry.hooks)) continue;
+    for (const h of entry.hooks) {
+      if (!h) continue;
+      if (h.id === HOOK_ID) return true;
+      if (h.type === 'command' && typeof h.command === 'string') {
+        if (h.command.includes('framework-edit-gate.js')) return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Register the hook idempotently. Returns:
+ *   { status: 'created', path }     — settings.json created from scratch
+ *   { status: 'updated', path }     — existing settings.json merged
+ *   { status: 'already', path }     — hook was already registered, no-op
+ *   { status: 'malformed', path }   — existing settings.json is invalid JSON
+ */
+function register(cwd = process.cwd()) {
+  const { path: settingsPath, settings: existing, malformed } = readSettings(cwd);
+  if (malformed) return { status: 'malformed', path: settingsPath };
+
+  const settings = existing && typeof existing === 'object' ? { ...existing } : {};
+  settings.hooks = settings.hooks && typeof settings.hooks === 'object'
+    ? { ...settings.hooks }
+    : {};
+
+  const list = Array.isArray(settings.hooks.PreToolUse) ? [...settings.hooks.PreToolUse] : [];
+
+  // Already present?
+  for (const entry of list) {
+    if (!entry || !Array.isArray(entry.hooks)) continue;
+    for (const h of entry.hooks) {
+      if (!h) continue;
+      if (h.id === HOOK_ID) return { status: 'already', path: settingsPath };
+      if (h.type === 'command' && typeof h.command === 'string'
+          && h.command.includes('framework-edit-gate.js')) {
+        return { status: 'already', path: settingsPath };
+      }
+    }
+  }
+
+  list.push({
+    matcher: HOOK_MATCHER,
+    hooks: [{
+      id: HOOK_ID,
+      type: 'command',
+      command: HOOK_COMMAND,
+    }],
+  });
+
+  settings.hooks.PreToolUse = list;
+  writeSettings(settingsPath, settings);
+  return { status: existing ? 'updated' : 'created', path: settingsPath };
+}
+
+/**
+ * Remove the hook from settings.json. Used by tests and as an undo helper.
+ */
+function unregister(cwd = process.cwd()) {
+  const { path: settingsPath, settings, malformed } = readSettings(cwd);
+  if (malformed || !settings || !settings.hooks || !Array.isArray(settings.hooks.PreToolUse)) {
+    return { status: 'not-found', path: settingsPath };
+  }
+
+  const filtered = settings.hooks.PreToolUse
+    .map((entry) => {
+      if (!entry || !Array.isArray(entry.hooks)) return entry;
+      const innerKept = entry.hooks.filter((h) => {
+        if (!h) return true;
+        if (h.id === HOOK_ID) return false;
+        if (h.type === 'command' && typeof h.command === 'string'
+            && h.command.includes('framework-edit-gate.js')) return false;
+        return true;
+      });
+      if (innerKept.length === 0) return null;
+      return { ...entry, hooks: innerKept };
+    })
+    .filter(Boolean);
+
+  if (filtered.length === settings.hooks.PreToolUse.length) {
+    return { status: 'not-found', path: settingsPath };
+  }
+
+  const next = { ...settings, hooks: { ...settings.hooks, PreToolUse: filtered } };
+  if (next.hooks.PreToolUse.length === 0) delete next.hooks.PreToolUse;
+  if (Object.keys(next.hooks).length === 0) delete next.hooks;
+  writeSettings(settingsPath, next);
+  return { status: 'removed', path: settingsPath };
+}
+
+module.exports = {
+  isRegistered,
+  register,
+  unregister,
+  HOOK_ID,
+  HOOK_COMMAND,
+  SETTINGS_FILE,
+};

package/src/utils/routine-adapters/claude-code-cloud.js

@@ -0,0 +1,78 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Claude Code Cloud adapter.
+ *
+ * Generates a routine config file under `.claude/routines/<name>.json` that
+ * Claude Code Cloud can pick up via `/schedule` or the RemoteTrigger mechanism.
+ *
+ * The actual remote trigger creation is interactive (user must run `/schedule`
+ * inside Claude Code). The adapter writes the config and prints the exact
+ * command the user needs to run.
+ */
+class ClaudeCodeCloudAdapter {
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+  }
+
+  get name() { return 'claude-code-cloud'; }
+  get label() { return 'Claude Code Cloud (RemoteTrigger)'; }
+  get description() {
+    return 'Schedules the agent via Claude Code Cloud RemoteTrigger. Best when you already use Claude Code Cloud.';
+  }
+
+  configDir() {
+    return path.join(this.cwd, '.claude', 'routines');
+  }
+
+  configPath(name) {
+    return path.join(this.configDir(), `${name}.json`);
+  }
+
+  install(spec) {
+    if (!fs.existsSync(this.configDir())) {
+      fs.mkdirSync(this.configDir(), { recursive: true });
+    }
+    const config = {
+      $schema: 'baldart-routine-config-v1',
+      name: spec.name,
+      description: spec.description,
+      schedule: spec.schedule,
+      agent: spec.agent,
+      prompt: spec.prompt,
+      output: spec.output,
+      backend: this.name,
+      installed_at: new Date().toISOString()
+    };
+    fs.writeFileSync(this.configPath(spec.name), JSON.stringify(config, null, 2) + '\n');
+    return {
+      backend: this.name,
+      artifacts: [path.relative(this.cwd, this.configPath(spec.name))],
+      followup: [
+        `Open Claude Code in this repo and run:`,
+        `  /schedule create --config .claude/routines/${spec.name}.json`,
+        `(or invoke the agent once with /loop ${spec.schedule.cron} <command> to test the cadence)`
+      ]
+    };
+  }
+
+  uninstall(name) {
+    const p = this.configPath(name);
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+    return {
+      backend: this.name,
+      followup: [
+        `Open Claude Code and run:`,
+        `  /schedule delete ${name}`,
+        `to remove the remote trigger.`
+      ]
+    };
+  }
+
+  detect(name) {
+    return fs.existsSync(this.configPath(name));
+  }
+}
+
+module.exports = ClaudeCodeCloudAdapter;

package/src/utils/routine-adapters/cron.js

@@ -0,0 +1,138 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Local cron adapter.
+ *
+ * Generates `scripts/routines/<name>.sh` (a self-contained wrapper) and prints
+ * the exact crontab line the user must install. Does NOT touch the user's
+ * crontab directly — that would be too invasive.
+ *
+ * Requires the `claude` CLI to be available on the user's PATH.
+ */
+class CronAdapter {
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+  }
+
+  get name() { return 'cron'; }
+  get label() { return 'Local cron (shell wrapper + crontab line)'; }
+  get description() {
+    return 'Generates a shell wrapper. You add a single line to your crontab. Best for self-hosted runs.';
+  }
+
+  scriptDir() {
+    return path.join(this.cwd, 'scripts', 'routines');
+  }
+
+  scriptPath(name) {
+    return path.join(this.scriptDir(), `${name}.sh`);
+  }
+
+  install(spec) {
+    if (!fs.existsSync(this.scriptDir())) {
+      fs.mkdirSync(this.scriptDir(), { recursive: true });
+    }
+    const sh = this._renderShellWrapper(spec);
+    fs.writeFileSync(this.scriptPath(spec.name), sh);
+    fs.chmodSync(this.scriptPath(spec.name), 0o755);
+
+    const absPath = path.resolve(this.cwd, this.scriptPath(spec.name));
+    const crontabLine = `${spec.schedule.cron}  ${absPath} >> ${path.dirname(absPath)}/${spec.name}.log 2>&1`;
+
+    return {
+      backend: this.name,
+      artifacts: [path.relative(this.cwd, this.scriptPath(spec.name))],
+      followup: [
+        `Add this line to your crontab (\`crontab -e\`):`,
+        ``,
+        `  ${crontabLine}`,
+        ``,
+        `Make sure the \`claude\` CLI is on PATH for the cron user and that ANTHROPIC_API_KEY is exported in the script env (edit the wrapper to suit).`,
+        `Manual test: ${absPath}`
+      ],
+      crontab_line: crontabLine
+    };
+  }
+
+  uninstall(name) {
+    const p = this.scriptPath(name);
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+    return {
+      backend: this.name,
+      followup: [
+        `Remove the crontab line that referenced scripts/routines/${name}.sh.`,
+        `Run \`crontab -e\` and delete the matching entry.`
+      ]
+    };
+  }
+
+  detect(name) {
+    return fs.existsSync(this.scriptPath(name));
+  }
+
+  _renderShellWrapper(spec) {
+    const outputPath = (spec.output && spec.output.path) || `docs/reports/{{YYYYMMDD}}-${spec.name}.md`;
+    const commitEnabled = spec.output && spec.output.commit && spec.output.commit.enabled;
+    const commitPrefix = (spec.output && spec.output.commit && spec.output.commit.prefix) || `[${spec.name.toUpperCase()}]`;
+    const promptHeredoc = spec.prompt;
+    const repoRoot = '"$(cd "$(dirname "$0")/../.." && pwd)"';
+
+    return `#!/usr/bin/env bash
+# Generated by BALDART (v${require('../../../package.json').version}) — npx baldart routines
+# Routine: ${spec.name}
+# ${spec.description}
+#
+# Schedule: ${spec.schedule.cron}   (${spec.schedule.cadence_label || 'scheduled'} ${spec.schedule.timezone || 'UTC'})
+#
+# Add to crontab (\`crontab -e\`):
+#   ${spec.schedule.cron}  ${'$(pwd)'}/scripts/routines/${spec.name}.sh >> ${'$(pwd)'}/scripts/routines/${spec.name}.log 2>&1
+
+set -euo pipefail
+
+# Resolve repo root and move into it so relative paths in the prompt work.
+REPO_ROOT=${repoRoot}
+cd "$REPO_ROOT"
+
+# Required: \`claude\` CLI on PATH and ANTHROPIC_API_KEY set.
+if ! command -v claude >/dev/null 2>&1; then
+  echo "ERROR: claude CLI not found on PATH" >&2
+  exit 1
+fi
+: "\${ANTHROPIC_API_KEY:?ANTHROPIC_API_KEY must be set (export it from the cron env or your shell profile)}"
+
+DATE=$(date -u +%Y%m%d)
+OUT_PATH="${outputPath}"
+OUT_PATH="\${OUT_PATH//\\{\\{YYYYMMDD\\}\\}/$DATE}"
+mkdir -p "$(dirname "$OUT_PATH")"
+
+claude --print --output-format json --mode bypassPermissions \\
+  --agent ${spec.agent} \\
+  > /tmp/baldart-${spec.name}.json <<'PROMPT'
+${promptHeredoc}
+PROMPT
+
+# Persist the output if the agent did not already write to disk
+if [ ! -s "$OUT_PATH" ]; then
+  jq -r '.result // .' /tmp/baldart-${spec.name}.json > "$OUT_PATH" 2>/dev/null \\
+    || cp /tmp/baldart-${spec.name}.json "$OUT_PATH"
+fi
+${commitEnabled ? `
+# Auto-commit the report and any inline fixes
+if git diff --quiet && git diff --staged --quiet; then
+  echo "No changes to commit."
+else
+  git add -A
+  git commit -m "${commitPrefix} routine $(date -u +%Y-%m-%d)"
+  # Push only when on a branch with a configured upstream
+  if git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}' >/dev/null 2>&1; then
+    git push
+  fi
+fi
+` : ''}
+echo "OK: ${spec.name} finished at $(date -u)"
+`;
+  }
+}
+
+module.exports = CronAdapter;

package/src/utils/routine-adapters/github-actions.js

@@ -0,0 +1,141 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * GitHub Actions adapter.
+ *
+ * Generates `.github/workflows/baldart-<name>.yml` with a `schedule` trigger
+ * and a `workflow_dispatch` trigger for manual runs. The workflow checks out
+ * the repo, sets up Node, installs Claude Code, and invokes the agent via
+ * the headless Claude CLI.
+ *
+ * Requires the user to set the `ANTHROPIC_API_KEY` secret in the repo.
+ */
+class GitHubActionsAdapter {
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+  }
+
+  get name() { return 'github-actions'; }
+  get label() { return 'GitHub Actions'; }
+  get description() {
+    return 'Schedules via a workflow with cron + workflow_dispatch. Requires the ANTHROPIC_API_KEY secret.';
+  }
+
+  workflowDir() {
+    return path.join(this.cwd, '.github', 'workflows');
+  }
+
+  workflowPath(name) {
+    return path.join(this.workflowDir(), `baldart-${name}.yml`);
+  }
+
+  install(spec) {
+    if (!fs.existsSync(this.workflowDir())) {
+      fs.mkdirSync(this.workflowDir(), { recursive: true });
+    }
+    const yml = this._renderWorkflow(spec);
+    fs.writeFileSync(this.workflowPath(spec.name), yml);
+    return {
+      backend: this.name,
+      artifacts: [path.relative(this.cwd, this.workflowPath(spec.name))],
+      followup: [
+        `Set the repository secret ANTHROPIC_API_KEY in GitHub.`,
+        `Commit and push .github/workflows/baldart-${spec.name}.yml to enable the schedule.`,
+        `Manual test: gh workflow run baldart-${spec.name}.yml`
+      ]
+    };
+  }
+
+  uninstall(name) {
+    const p = this.workflowPath(name);
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+    return {
+      backend: this.name,
+      followup: [
+        `Commit the removal of .github/workflows/baldart-${name}.yml to disable the schedule.`
+      ]
+    };
+  }
+
+  detect(name) {
+    return fs.existsSync(this.workflowPath(name));
+  }
+
+  _renderWorkflow(spec) {
+    const cron = spec.schedule.cron;
+    const promptIndented = spec.prompt.split('\n').map(l => '            ' + l).join('\n');
+    const outputPath = (spec.output && spec.output.path) || `docs/reports/{{YYYYMMDD}}-${spec.name}.md`;
+    const commitEnabled = spec.output && spec.output.commit && spec.output.commit.enabled;
+    const commitPrefix = (spec.output && spec.output.commit && spec.output.commit.prefix) || `[${spec.name.toUpperCase()}]`;
+
+    return `# Generated by BALDART (v${require('../../../package.json').version}) — npx baldart routines
+# Routine: ${spec.name}
+# ${spec.description}
+
+name: BALDART ${spec.name}
+
+on:
+  schedule:
+    - cron: '${cron}'   # ${spec.schedule.cadence_label || 'scheduled'}
+  workflow_dispatch:    # manual trigger from the Actions tab
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Claude Code CLI
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Run ${spec.name}
+        env:
+          ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          DATE=$(date -u +%Y%m%d)
+          OUT_PATH="${outputPath}"
+          OUT_PATH="\${OUT_PATH//\\{\\{YYYYMMDD\\}\\}/$DATE}"
+          mkdir -p "$(dirname "$OUT_PATH")"
+
+          claude --print --output-format json --mode bypassPermissions \\
+            --agent ${spec.agent} \\
+            > /tmp/claude-output.json <<'PROMPT'
+${promptIndented}
+          PROMPT
+
+          # Persist the output if the agent did not already write to disk
+          if [ ! -s "$OUT_PATH" ]; then
+            jq -r '.result // .' /tmp/claude-output.json > "$OUT_PATH" || \\
+              cp /tmp/claude-output.json "$OUT_PATH"
+          fi
+${commitEnabled ? `
+      - name: Commit report
+        run: |
+          git config user.name "baldart-routine"
+          git config user.email "baldart-routine@users.noreply.github.com"
+          git add -A
+          if ! git diff --staged --quiet; then
+            git commit -m "${commitPrefix} \${{ github.workflow }} run \$(date -u +%Y-%m-%d)"
+            git push
+          else
+            echo "No changes to commit."
+          fi
+` : ''}`;
+  }
+}
+
+module.exports = GitHubActionsAdapter;

package/src/utils/routine-adapters/index.js

@@ -0,0 +1,21 @@
+const ClaudeCodeCloudAdapter = require('./claude-code-cloud');
+const GitHubActionsAdapter = require('./github-actions');
+const CronAdapter = require('./cron');
+
+const REGISTRY = {
+  'claude-code-cloud': ClaudeCodeCloudAdapter,
+  'github-actions':     GitHubActionsAdapter,
+  'cron':               CronAdapter
+};
+
+function listAdapters() {
+  return Object.keys(REGISTRY);
+}
+
+function getAdapter(name, cwd) {
+  const Cls = REGISTRY[name];
+  if (!Cls) throw new Error(`Unknown adapter: ${name}. Available: ${listAdapters().join(', ')}`);
+  return new Cls(cwd);
+}
+
+module.exports = { listAdapters, getAdapter, REGISTRY };

package/src/utils/routines.js

@@ -0,0 +1,166 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const FRAMEWORK_DIR = '.framework';
+const ROUTINES_SUBPATH = path.join('framework', 'routines');
+const LOCK_DIR = '.baldart';
+const LOCK_FILE = 'routines.lock.json';
+
+class Routines {
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+  }
+
+  // -------- Catalog reading ------------------------------------------------
+
+  routinesDir() {
+    return path.join(this.cwd, FRAMEWORK_DIR, ROUTINES_SUBPATH);
+  }
+
+  catalogPath() {
+    return path.join(this.routinesDir(), 'index.yml');
+  }
+
+  /** Read the routines catalog (index.yml). Returns {version, routines: []} or null. */
+  readCatalog() {
+    const p = this.catalogPath();
+    if (!fs.existsSync(p)) return null;
+    try {
+      return yaml.load(fs.readFileSync(p, 'utf8'));
+    } catch (err) {
+      throw new Error(`Failed to parse ${p}: ${err.message}`);
+    }
+  }
+
+  /** Read a single routine spec by name. Throws if missing or malformed. */
+  readSpec(name) {
+    const catalog = this.readCatalog();
+    if (!catalog) throw new Error('Routines catalog not found. Is BALDART installed?');
+    const entry = (catalog.routines || []).find(r => r.name === name);
+    if (!entry) throw new Error(`Unknown routine: ${name}`);
+    const specPath = path.join(this.routinesDir(), entry.file);
+    if (!fs.existsSync(specPath)) {
+      throw new Error(`Routine spec missing on disk: ${specPath}`);
+    }
+    const spec = yaml.load(fs.readFileSync(specPath, 'utf8'));
+    spec._catalogEntry = entry;
+    spec._specPath = specPath;
+    return spec;
+  }
+
+  /** Return the full list of available routines (catalog entries enriched with spec). */
+  list() {
+    const catalog = this.readCatalog();
+    if (!catalog) return [];
+    return (catalog.routines || []).map(entry => {
+      try {
+        return this.readSpec(entry.name);
+      } catch (err) {
+        return Object.assign({}, entry, { _error: err.message });
+      }
+    });
+  }
+
+  // -------- Lock file ------------------------------------------------------
+
+  lockDir() {
+    return path.join(this.cwd, LOCK_DIR);
+  }
+
+  lockPath() {
+    return path.join(this.lockDir(), LOCK_FILE);
+  }
+
+  readLock() {
+    const p = this.lockPath();
+    if (!fs.existsSync(p)) return { version: 1, routines: {} };
+    try {
+      return JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch (err) {
+      throw new Error(`Failed to parse ${p}: ${err.message}`);
+    }
+  }
+
+  writeLock(lock) {
+    if (!fs.existsSync(this.lockDir())) {
+      fs.mkdirSync(this.lockDir(), { recursive: true });
+    }
+    fs.writeFileSync(this.lockPath(), JSON.stringify(lock, null, 2) + '\n');
+  }
+
+  /** Update the lock entry for a routine. Status is "installed" | "skipped" | "disabled". */
+  setLockEntry(name, entry) {
+    const lock = this.readLock();
+    lock.routines = lock.routines || {};
+    lock.routines[name] = Object.assign({}, lock.routines[name] || {}, entry, {
+      updated_at: new Date().toISOString()
+    });
+    this.writeLock(lock);
+  }
+
+  removeLockEntry(name) {
+    const lock = this.readLock();
+    if (lock.routines && lock.routines[name]) {
+      delete lock.routines[name];
+      this.writeLock(lock);
+    }
+  }
+
+  // -------- Status computation --------------------------------------------
+
+  /**
+   * Compute status for every routine in the catalog.
+   * Returns array of { spec, lockEntry, status, requiredArtifacts: {present, missing} }
+   */
+  computeStatus() {
+    const lock = this.readLock();
+    return this.list().map(spec => {
+      if (spec._error) {
+        return { spec, lockEntry: null, status: 'error', error: spec._error };
+      }
+      const lockEntry = (lock.routines || {})[spec.name] || null;
+      const required = (spec.required_artifacts || []).map(p => {
+        const full = path.join(this.cwd, p);
+        return { path: p, exists: fs.existsSync(full) };
+      });
+      const missingRequired = required.filter(r => !r.exists);
+      const isOptional = !!spec.optional;
+
+      let status;
+      if (lockEntry && lockEntry.status === 'installed') {
+        status = 'installed';
+      } else if (lockEntry && lockEntry.status === 'skipped') {
+        status = 'skipped';
+      } else if (lockEntry && lockEntry.status === 'disabled') {
+        status = 'disabled';
+      } else if (missingRequired.length > 0 && isOptional) {
+        status = 'unavailable';
+      } else if (missingRequired.length > 0) {
+        status = 'blocked';
+      } else {
+        status = 'available';
+      }
+
+      return {
+        spec,
+        lockEntry,
+        status,
+        requiredArtifacts: { present: required.filter(r => r.exists), missing: missingRequired },
+        optional: isOptional
+      };
+    });
+  }
+
+  // -------- New routines since last seen ----------------------------------
+
+  /**
+   * Returns routines that exist in the catalog but have no lock entry — i.e.
+   * routines the user has never been prompted about. Used by add.js/update.js.
+   */
+  newRoutines() {
+    return this.computeStatus().filter(r => r.status === 'available' && !r.lockEntry);
+  }
+}
+
+module.exports = Routines;