kracked-core 1.4.0 → 1.5.1

package/README.md

@@ -134,6 +134,42 @@ Then it tracks the work:
 
 **A story cannot move to `done` without evidence.** Not "the tests pass" — what did you actually verify, and what did you *not*? Green tests are not a working feature. This one rule catches more bugs than any other part of the system.
 
+## Terminal commands
+
+```bash
+npx kracked-core init        # set up memory in this project
+npx kracked-core status      # what's installed, and is it current?
+npx kracked-core update      # refresh skills + loaders, keep your memory
+npx kracked-core uninstall   # remove it (asks before deleting anything)
+```
+
+## Am I on the latest version?
+
+```bash
+npx kracked-core@latest status
+```
+
+Shows the version that installed your files, the latest on npm, and tells you plainly whether
+you need to update:
+
+```
+This project ~/code/my-app
+  installed version: 1.4.0
+  .agents/skills: 5/5 skills
+
+Global memory ~/.kracked
+  4/4 files present
+  lessons learned: 12
+
+Version
+  running now:   1.5.0
+  latest on npm: 1.5.0
+
+  Up to date.
+```
+
+> The `@latest` matters — plain `npx kracked-core` can serve a cached older copy.
+
 ## Updating
 
 When a new version ships:

package/bin/kracked-core.mjs

@@ -3,12 +3,14 @@
 import { runInit } from '../src/wizard.mjs';
 import { runUninstall } from '../src/uninstall.mjs';
 import { runUpdate } from '../src/update.mjs';
-import { beginTypeAhead } from '../src/prompt.mjs';
+import { runStatus } from '../src/status.mjs';
+import { beginTypeAhead, endTypeAhead } from '../src/prompt.mjs';
 
 const USAGE = `kracked-core — memory & workflow installer for AI coding agents
 
 Usage:
   npx kracked-core init        Set up global + project memory
+  npx kracked-core status      Show what's installed and whether it's current
   npx kracked-core update      Refresh skills + loaders, keeping your memory
   npx kracked-core uninstall   Remove kracked-core files (asks before deleting)
 
@@ -29,6 +31,11 @@ async function main() {
     return;
   }
 
+  if (subcommand === 'status') {
+    await runStatus();
+    return;
+  }
+
   if (subcommand === 'update') {
     await runUpdate();
     return;
@@ -56,7 +63,16 @@ async function main() {
   process.exit(1);
 }
 
-main().catch((err) => {
-  process.stderr.write(`\nkracked-core failed: ${err.message}\n`);
-  process.exit(1);
-});
+main()
+  .catch((err) => {
+    process.stderr.write(`\nkracked-core failed: ${err.message}\n`);
+    process.exitCode = 1;
+  })
+  // A raw-mode TTY stdin stays an ACTIVE HANDLE even after removeListener +
+  // pause(), so Node's event loop never drains and the terminal never returns —
+  // the command looks stuck even when it succeeded. Releasing stdin is not
+  // enough on its own; exit explicitly once the work is done.
+  .finally(() => {
+    endTypeAhead();
+    process.stdout.write('', () => process.exit(process.exitCode ?? 0));
+  });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kracked-core",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Zero-dependency memory & workflow installer for AI coding agents — global identity, project memory, and skills that survive session restarts.",
   "type": "module",
   "bin": {

package/src/prompt.mjs

@@ -110,6 +110,26 @@ export function beginTypeAhead() {
   stdin.on('data', bufferEarlyKeys);
 }
 
+/**
+ * Release stdin so the process can exit.
+ *
+ * An open stdin listener keeps Node's event loop alive indefinitely, so any
+ * command that finishes WITHOUT going through a prompt's cleanup (an early
+ * return, an error path, a completed run) leaves the terminal hanging with no
+ * output and no prompt back. `process.exitCode` sets the code but does not
+ * exit. Every command path must end here.
+ */
+export function endTypeAhead() {
+  if (!stdin.isTTY) return;
+  stdin.removeListener('data', bufferEarlyKeys);
+  try {
+    if (stdin.isRaw) stdin.setRawMode(false);
+  } catch {
+    // Terminal already gone.
+  }
+  stdin.pause();
+}
+
 function bufferEarlyKeys(chunk) {
   pendingKeys.push(...splitKeys(chunk));
 }

package/src/scaffold.mjs

@@ -174,6 +174,27 @@ export async function writeProjectMemory({ projectDir, tokens, ask, report }) {
   }
 }
 
+/**
+ * Record which version wrote these files. Without this there is no way to
+ * answer "am I on the latest?" — you can see what npm serves, but not what
+ * you actually installed.
+ */
+export function writeVersionStamp({ projectDir, version, report }) {
+  const dest = path.join(projectDir, '.kracked', '.version');
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, `${version}\n`, 'utf8');
+  report({ path: dest, action: 'written' });
+}
+
+/** Read the version that last wrote this project's files, or null. */
+export function readVersionStamp(projectDir) {
+  try {
+    return fs.readFileSync(path.join(projectDir, '.kracked', '.version'), 'utf8').trim();
+  } catch {
+    return null; // pre-1.5.0 install, or not installed
+  }
+}
+
 /** Write AGENTS.md, CLAUDE.md (shim), and .agents/rules/kracked.md. */
 export async function writeLoaders({ projectDir, tokens, ask, report, editors }) {
   const agentsContent = applyTokens(readTemplate('loaders/AGENTS.md'), tokens);

package/src/status.mjs

@@ -0,0 +1,125 @@
+// `kracked-core status` — what's installed here, and is it current?
+//
+// Answers the question a version number alone can't: the npm registry tells you
+// what's available, package.json tells you what you just ran, but neither tells
+// you which version actually wrote the files in this project.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { stdout } from 'node:process';
+import { createRequire } from 'node:module';
+
+import { readVersionStamp, SKILL_NAMES } from './scaffold.mjs';
+
+const require = createRequire(import.meta.url);
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+
+function runningVersion() {
+  try {
+    return require('../package.json').version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/** Ask npm what the current published version is. Network-optional. */
+async function latestPublished() {
+  try {
+    const res = await fetch('https://registry.npmjs.org/kracked-core', {
+      signal: AbortSignal.timeout(4000),
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    return body['dist-tags']?.latest ?? null;
+  } catch {
+    return null; // offline, or npm unreachable — not an error worth failing on
+  }
+}
+
+/** Compare semver-ish strings. Returns -1, 0, or 1. */
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}
+
+export async function runStatus() {
+  const projectDir = process.cwd();
+  const globalDir = path.join(os.homedir(), '.kracked');
+  const running = runningVersion();
+
+  stdout.write(`${bold('kracked-core status')}\n\n`);
+
+  // --- This project ---
+  const installed = readVersionStamp(projectDir);
+  const hasProject = fs.existsSync(path.join(projectDir, '.kracked'));
+
+  stdout.write(`${bold('This project')} ${dim(projectDir)}\n`);
+  if (!hasProject) {
+    stdout.write('  not set up — run `npx kracked-core@latest init`\n');
+  } else {
+    stdout.write(`  installed version: ${installed || dim('unknown (installed before 1.5.0)')}\n`);
+
+    const skillDirs = ['.claude/skills', '.agents/skills'].filter((d) =>
+      fs.existsSync(path.join(projectDir, d))
+    );
+    for (const dir of skillDirs) {
+      const present = SKILL_NAMES.filter((s) =>
+        fs.existsSync(path.join(projectDir, dir, s, 'SKILL.md'))
+      ).length;
+      stdout.write(`  ${dir}: ${present}/${SKILL_NAMES.length} skills\n`);
+    }
+  }
+
+  // --- Global memory ---
+  stdout.write(`\n${bold('Global memory')} ${dim(globalDir)}\n`);
+  if (!fs.existsSync(globalDir)) {
+    stdout.write('  not set up\n');
+  } else {
+    const files = ['identity.md', 'preferences.md', 'lessons.md', 'projects.md'];
+    const present = files.filter((f) => fs.existsSync(path.join(globalDir, f)));
+    stdout.write(`  ${present.length}/${files.length} files present\n`);
+
+    // Lesson count is the signal that memory is actually accumulating.
+    try {
+      const lessons = fs.readFileSync(path.join(globalDir, 'lessons.md'), 'utf8');
+      const count = lessons.split('\n').filter((l) => /^- /.test(l)).length;
+      stdout.write(`  lessons learned: ${count}\n`);
+    } catch {
+      // No lessons file — already reflected in the count above.
+    }
+  }
+
+  // --- Version check ---
+  stdout.write(`\n${bold('Version')}\n`);
+  stdout.write(`  running now: ${running}\n`);
+
+  const latest = await latestPublished();
+  if (!latest) {
+    stdout.write(`  latest on npm: ${dim("couldn't check (offline?)")}\n`);
+    return;
+  }
+
+  stdout.write(`  latest on npm: ${latest}\n\n`);
+
+  const compareTo = installed || running;
+  const cmp = compareVersions(compareTo, latest);
+
+  if (cmp >= 0) {
+    stdout.write(`  ${green('Up to date.')}\n`);
+  } else {
+    stdout.write(
+      `  ${yellow(`Update available: ${compareTo} → ${latest}`)}\n` +
+      '  Run `npx kracked-core@latest update` to refresh skills and loaders.\n' +
+      '  Your memory is never touched by an update.\n'
+    );
+  }
+}

package/src/update.mjs

@@ -12,7 +12,7 @@ import { stdout } from 'node:process';
 import { createRequire } from 'node:module';
 
 import { select } from './prompt.mjs';
-import { writeLoaders, writeSkills, SKILL_NAMES } from './scaffold.mjs';
+import { writeLoaders, writeSkills, writeVersionStamp, SKILL_NAMES } from './scaffold.mjs';
 
 const require = createRequire(import.meta.url);
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
@@ -87,10 +87,18 @@ export async function runUpdate() {
   stdout.write(`${bold('kracked-core update')} ${dim(`v${version}`)}\n\n`);
 
   if (!fs.existsSync(path.join(projectDir, '.kracked'))) {
-    stdout.write(
-      `No kracked-core install found in ${projectDir}\n\n` +
-      'Run `npx kracked-core init` to set it up first.\n'
-    );
+    stdout.write(`No kracked-core install found in ${projectDir}\n\n`);
+
+    // Easy mistake: running this inside the package source rather than a
+    // project that uses it. Say so instead of just repeating the error.
+    if (fs.existsSync(path.join(projectDir, 'templates', 'loaders', 'AGENTS.md'))) {
+      stdout.write(
+        'This looks like the kracked-core package source, not a project that\n' +
+        'uses it. cd into your own project first, then run this again.\n'
+      );
+    } else {
+      stdout.write('Run `npx kracked-core@latest init` to set it up first.\n');
+    }
     process.exitCode = 1;
     return;
   }
@@ -144,6 +152,7 @@ export async function runUpdate() {
   stdout.write('\nUpdating...\n');
   await writeLoaders({ projectDir, tokens, ask: overwrite, report, editors });
   await writeSkills({ projectDir, tokens, editors, ask: overwrite, report });
+  writeVersionStamp({ projectDir, version, report });
 
   stdout.write(`\n  Refreshed ${created.length} file(s).\n`);
   stdout.write('\nRestart your editor so it picks up the updated skills.\n');

package/src/wizard.mjs

@@ -2,6 +2,7 @@
 // Follows the wizard flow in CONTRACT.md exactly — question order matters.
 
 import { stdin, stdout } from 'node:process';
+import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -22,6 +23,7 @@ import {
   writeProjectMemory,
   writeLoaders,
   writeSkills,
+  writeVersionStamp,
 } from './scaffold.mjs';
 
 /** Expand a leading ~ to the home directory. Leaves other paths untouched. */
@@ -34,6 +36,15 @@ function expandTilde(inputPath) {
   return inputPath;
 }
 
+/** The version of kracked-core doing the installing. */
+function pkgVersion() {
+  try {
+    return createRequire(import.meta.url)('../package.json').version;
+  } catch {
+    return 'unknown';
+  }
+}
+
 /** Format today's date as YYYY-MM-DD. */
 function isoDate() {
   return new Date().toISOString().slice(0, 10);
@@ -341,6 +352,7 @@ async function wizardFlow() {
     await writeProjectMemory({ projectDir, tokens, ask: conflictAsk, report: reporter });
     await writeLoaders({ projectDir, tokens, ask: conflictAsk, report: reporter, editors });
     await writeSkills({ projectDir, tokens, editors, ask: conflictAsk, report: reporter });
+    writeVersionStamp({ projectDir, version: pkgVersion(), report: reporter });
   }
 
   printSummary(created, agentName, setUpProject);