ai-runtime-kit 0.5.0

package/src/templates.js

@@ -0,0 +1,96 @@
+'use strict';
+
+// Project-side templates instantiated by `init` into .ai/project/.
+
+function projectStateMd() {
+  return `# Project Runtime State
+
+This file holds the current instance values for runtime metadata
+whose definitions live in \`.ai/runtime/\`. Reading this file plus
+the corresponding runtime file is equivalent to reading the
+single-file version.
+
+## Mode
+
+FEATURE_DEVELOPMENT
+
+### Runtime Intent
+
+Current focus:
+
+- (fill me in: what this project is currently optimizing for)
+
+## Health
+
+GREEN
+
+### Health Drivers
+
+Reasons:
+
+- (fill me in: what is currently true that justifies GREEN)
+
+### Recovery Goals
+
+(fill me in: what would degrade health, and how to recover)
+
+## Priorities
+
+Current runtime health:
+
+- GREEN
+
+Current priority focus:
+
+- (fill me in)
+`;
+}
+
+function projectTaskStatusMd() {
+  return `# Task Status — Active Sets
+
+Active task lifecycle state for this project. Lifecycle schema is
+defined in \`.ai/runtime/tasks/TASK_STATUS.md\`.
+
+---
+
+## Active Task Sets
+
+(empty — populate as task sets are opened)
+`;
+}
+
+function agentEntryClaudeMd() {
+  return `# CLAUDE.md
+
+This repository uses an \`.ai/\` runtime managed by
+[ai-runtime-kit](https://github.com/kaelen2026/ai-runtime-kit).
+
+## Agent entry point
+
+Before doing engineering work in this repo, read the runtime bootstrap:
+
+\`\`\`
+.ai/runtime/BOOTSTRAP.md
+\`\`\`
+
+That file defines the read sequence (INDEX → CAPABILITIES → RUNTIME_MODE
+→ SAFETY → PRIORITIES → workflows). Project-instance state — current
+mode, health, priorities — lives at \`.ai/project/STATE.md\`.
+
+## Loading order
+
+1. This file (\`CLAUDE.md\`), auto-loaded by Claude Code from cwd.
+2. \`.ai/runtime/BOOTSTRAP.md\` — explicitly read on task start.
+3. \`.ai/project/STATE.md\` — current instance state.
+4. Task-relevant runtime and project files per BOOTSTRAP's read sequence.
+
+## Editing this file
+
+This file is **project-owned**. \`ai-runtime-kit upgrade\` never
+touches it. Add repo-specific notes (stack, conventions, gotchas)
+below — they will be preserved across kit upgrades.
+`;
+}
+
+module.exports = { projectStateMd, projectTaskStatusMd, agentEntryClaudeMd };

package/src/upgrade.js

@@ -0,0 +1,179 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parseArgs } = require('node:util');
+
+const { copyKitRuntimeTo, removeDir } = require('./snapshot');
+const {
+  KIT_VERSION,
+  readProjectKitVersion,
+  writeProjectKitVersion,
+  compareSemver,
+} = require('./version');
+const { computeRuntimeDiff, printDiffSummary, printPerFileDiff } = require('./diff');
+const { gitStatusPorcelain, isGitRepo } = require('./git');
+const { confirm } = require('./prompt');
+
+async function run(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      options: {
+        cwd: { type: 'string' },
+        yes: { type: 'boolean', short: 'y', default: false },
+        'no-diff': { type: 'boolean', default: false },
+        pager: { type: 'string' },
+        'allow-dirty': { type: 'boolean', default: false },
+        'allow-downgrade': { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+      allowPositionals: false,
+    });
+  } catch (e) {
+    console.error(`upgrade: ${e.message}`);
+    console.error('Try: ai-runtime-kit upgrade --help');
+    process.exit(1);
+  }
+
+  if (parsed.values.help) {
+    printHelp();
+    return;
+  }
+
+  const cwd = path.resolve(parsed.values.cwd ?? process.cwd());
+  const runtimeDir = path.join(cwd, '.ai', 'runtime');
+
+  if (!fs.existsSync(runtimeDir)) {
+    console.error(`upgrade: ${runtimeDir} does not exist.`);
+    console.error('Run `ai-runtime-kit init` first.');
+    process.exit(1);
+  }
+
+  const installedVersion = readProjectKitVersion(cwd);
+  if (!installedVersion) {
+    console.error('upgrade: .ai/runtime/KIT_VERSION not found.');
+    console.error('Either re-run init in --migrate mode or write KIT_VERSION manually.');
+    process.exit(1);
+  }
+
+  const cmp = compareSemver(KIT_VERSION, installedVersion);
+  if (cmp === 0) {
+    console.log(`Already on kit ${KIT_VERSION}. No upgrade needed.`);
+    return;
+  }
+  if (cmp < 0) {
+    if (!parsed.values['allow-downgrade']) {
+      console.error(`upgrade: refusing downgrade — installed ${installedVersion} > kit ${KIT_VERSION}.`);
+      console.error('Pass --allow-downgrade to override.');
+      process.exit(1);
+    }
+    console.warn(`Warning: downgrading from ${installedVersion} to ${KIT_VERSION}.`);
+  }
+
+  // Git dirty check
+  if (!parsed.values['allow-dirty']) {
+    if (isGitRepo(cwd)) {
+      const status = gitStatusPorcelain('.ai/runtime', cwd);
+      if (!status.ok) {
+        console.error(`upgrade: git status check failed: ${status.error}`);
+        console.error('Pass --allow-dirty to skip the git check.');
+        process.exit(1);
+      }
+      if (status.lines.length) {
+        console.error('upgrade: .ai/runtime/ has uncommitted changes:');
+        for (const line of status.lines) console.error(`  ${line}`);
+        console.error('Commit or stash them, or pass --allow-dirty.');
+        process.exit(1);
+      }
+    } else {
+      console.warn(`upgrade: ${cwd} is not a git repository — skipping dirty check.`);
+    }
+  }
+
+  // Compute and print diff
+  const diff = computeRuntimeDiff(runtimeDir);
+  console.log(`Upgrading kit ${installedVersion} → ${KIT_VERSION}`);
+  console.log('');
+  printDiffSummary(diff);
+
+  if (
+    diff.added.length === 0 &&
+    diff.removed.length === 0 &&
+    diff.replaced.length === 0
+  ) {
+    console.log('No file-level changes. Updating KIT_VERSION only.');
+    writeProjectKitVersion(cwd, KIT_VERSION);
+    return;
+  }
+
+  if (!parsed.values['no-diff']) {
+    const pagerCmd = parsed.values.pager ?? process.env.AI_RUNTIME_KIT_PAGER;
+    if (pagerCmd && process.stdout.isTTY) {
+      const { spawn } = require('node:child_process');
+      const [bin, ...pagerArgs] = pagerCmd.split(/\s+/);
+      const child = spawn(bin, pagerArgs, {
+        stdio: ['pipe', 'inherit', 'inherit'],
+      });
+      printPerFileDiff(diff, runtimeDir, child.stdin);
+      child.stdin.end();
+      await new Promise((resolve, reject) => {
+        child.on('close', resolve);
+        child.on('error', reject);
+      });
+    } else {
+      printPerFileDiff(diff, runtimeDir);
+    }
+  }
+
+  // Confirm
+  let ok;
+  if (parsed.values.yes) {
+    ok = true;
+    console.log('--yes passed; proceeding without prompt.');
+  } else {
+    ok = await confirm('Apply this upgrade?', { defaultYes: false });
+  }
+
+  if (!ok) {
+    console.log('Aborted. No changes made.');
+    process.exit(2);
+  }
+
+  removeDir(runtimeDir);
+  copyKitRuntimeTo(runtimeDir);
+  writeProjectKitVersion(cwd, KIT_VERSION);
+  console.log(`Done. Kit upgraded to ${KIT_VERSION}.`);
+  console.log('Changes are unstaged; review with `git diff .ai/runtime/` and commit when ready.');
+}
+
+function printHelp() {
+  console.log(`ai-runtime-kit upgrade [options]
+
+Replace .ai/runtime/ with the kit's current canonical snapshot.
+
+Process:
+  1. Verify .ai/runtime/KIT_VERSION exists.
+  2. Verify .ai/runtime/ has no uncommitted git changes.
+  3. Show file-level ADD / REPLACE / DELETE summary + per-file diff.
+  4. Prompt: Apply this upgrade? (y/N).
+  5. On y: rm -rf .ai/runtime/, lay down new snapshot, update KIT_VERSION.
+
+Never touches .ai/project/.
+
+Options:
+  --cwd <dir>          Target directory (default: process.cwd())
+  --yes, -y            Skip the y/N prompt (apply immediately)
+  --no-diff            Skip the per-file diff preview (still shows summary)
+  --pager <cmd>        Pipe per-file diff through this pager (e.g.
+                       \`--pager 'less -R'\`). Also honored via env
+                       AI_RUNTIME_KIT_PAGER. Only applied when stdout
+                       is a TTY.
+  --allow-dirty        Skip the git dirty check
+  --allow-downgrade    Permit installing an older kit version
+  -h, --help           Show this help.`);
+}
+
+module.exports = { run, printHelp };

package/src/version.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const KIT_PKG = require('../package.json');
+
+const KIT_VERSION = KIT_PKG.version;
+
+function kitVersionFilePath(projectRoot) {
+  return path.join(projectRoot, '.ai', 'runtime', 'KIT_VERSION');
+}
+
+function readProjectKitVersion(projectRoot) {
+  const f = kitVersionFilePath(projectRoot);
+  if (!fs.existsSync(f)) return null;
+  return fs.readFileSync(f, 'utf8').trim();
+}
+
+function writeProjectKitVersion(projectRoot, version) {
+  fs.writeFileSync(kitVersionFilePath(projectRoot), `${version}\n`);
+}
+
+// Returns 1 / 0 / -1 if a is newer / equal / older than b. Pre-release tags
+// ignored (we don't need full semver here — v0.x and v1.x suffice).
+function compareSemver(a, b) {
+  const norm = (s) => s.replace(/^v/, '').split('-')[0].split('.').map(Number);
+  const [aMaj, aMin, aPat] = norm(a);
+  const [bMaj, bMin, bPat] = norm(b);
+  if (aMaj !== bMaj) return aMaj > bMaj ? 1 : -1;
+  if (aMin !== bMin) return aMin > bMin ? 1 : -1;
+  if (aPat !== bPat) return aPat > bPat ? 1 : -1;
+  return 0;
+}
+
+module.exports = {
+  KIT_VERSION,
+  kitVersionFilePath,
+  readProjectKitVersion,
+  writeProjectKitVersion,
+  compareSemver,
+};