kracked-core 1.1.0 → 1.5.0

package/README.md

@@ -49,7 +49,12 @@ npx kracked-core init
 
 The wizard asks a few questions — name your agent, is this a new or existing project, which editor you use — and writes the files. Hold Enter through it and you'll get a sane setup.
 
-**Works with:** Antigravity · Claude Code · Cursor · Windsurf · anything that reads `AGENTS.md`
+**Full support** (memory + all five commands):
+**Antigravity** · **Claude Code** · **Kilo Code** (VS Code) · **Roo Code** (VS Code)
+
+**Memory only:** Cursor, Windsurf, and anything else that reads `AGENTS.md` — your agent loads its
+memory, but the `/kracked-*` commands aren't installed, because those editors use a different
+skill format. You can still run the flow by asking in plain language.
 
 ## Use
 
@@ -82,7 +87,13 @@ your-project/.kracked/   PROJECT — this codebase only
   project.md             stack, conventions, how to run it
   session.md             where we are right now
   decisions.md           why things are the way they are
-  sdd/tracker.md         story status + evidence
+  sdd/
+    tracker.md           story status + evidence
+    specs/               what to build and why
+    epics/               groups of related stories
+    stories/             one shippable slice each
+    architecture/        how it's built (large work only)
+      decisions/         ADRs, numbered, never renumbered
 ```
 
 ### The boundary rule
@@ -123,6 +134,66 @@ 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:
+
+```bash
+npx kracked-core@latest update
+```
+
+Refreshes the skills and loaders. **Your memory is never touched** — identity, preferences,
+lessons, and everything under `.kracked/` stay exactly as they are. It keeps your agent's name too.
+
+Restart your editor afterwards so it picks up the new skills.
+
+## Uninstalling
+
+```bash
+npx kracked-core uninstall
+```
+
+Shows what it will remove and asks before deleting — project files and global memory are separate
+questions. It never touches a `CLAUDE.md` or `AGENTS.md` another tool wrote.
+
+Full guide, including manual removal and how to keep your docs: [docs/UNINSTALL.md](https://github.com/Krackeddevs-Org/kracked-core/blob/main/docs/UNINSTALL.md)
+
 ## FAQ
 
 **Does this send my code anywhere?**

package/bin/kracked-core.mjs

@@ -1,24 +1,58 @@
 #!/usr/bin/env node
 
 import { runInit } from '../src/wizard.mjs';
+import { runUninstall } from '../src/uninstall.mjs';
+import { runUpdate } from '../src/update.mjs';
+import { runStatus } from '../src/status.mjs';
+import { beginTypeAhead } 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 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)
 
 Options:
-  -h, --help                 Show this help
+  -h, --help                    Show this help
+  -v, --version                 Show the installed version
 `;
 
 async function main() {
   const [, , subcommand] = process.argv;
 
+  // Capture keystrokes from the very first millisecond — a student holding
+  // Enter starts before Node has finished booting.
+  if (['init', 'update', 'uninstall'].includes(subcommand)) beginTypeAhead();
+
   if (subcommand === 'init') {
     await runInit();
     return;
   }
 
+  if (subcommand === 'status') {
+    await runStatus();
+    return;
+  }
+
+  if (subcommand === 'update') {
+    await runUpdate();
+    return;
+  }
+
+  if (subcommand === 'uninstall') {
+    await runUninstall();
+    return;
+  }
+
+  if (subcommand === '--version' || subcommand === '-v') {
+    const { createRequire } = await import('node:module');
+    const pkg = createRequire(import.meta.url)('../package.json');
+    process.stdout.write(`${pkg.version}\n`);
+    return;
+  }
+
   if (subcommand === '--help' || subcommand === '-h' || !subcommand) {
     process.stdout.write(USAGE);
     process.exit(subcommand ? 0 : 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kracked-core",
-  "version": "1.1.0",
+  "version": "1.5.0",
   "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/detect.mjs

@@ -5,6 +5,30 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 
+/**
+ * Scrub a value read from an untrusted repo before it can reach a template.
+ *
+ * Everything scanned from a project (package.json name, script names) gets
+ * interpolated into AGENTS.md and ~/.kracked/projects.md — files an AI agent
+ * READS AS INSTRUCTIONS on every boot. A crafted `name` containing newlines and
+ * a markdown heading can therefore inject text that reads as package-authored
+ * instruction, and via the global registry it persists into every OTHER project
+ * the user opens. Sanitize here, at the boundary, so no caller can forget.
+ */
+export function sanitizeScanned(value, maxLength = 64) {
+  if (typeof value !== 'string') return '';
+  return value
+    .replace(/[\r\n\t]+/g, ' ')          // no line breaks — kills injected blocks
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\u0000-\u001f\u007f]/g, '') // strip remaining control chars
+    .replace(/[|`<>]/g, '')              // markdown table + code + html structure
+    .replace(/^[\s#>*\-=+]+/, '')        // no leading heading/quote/list markers
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, maxLength)
+    .trim();
+}
+
 /** Does ~/.kracked/ already exist? */
 export function globalMemoryExists() {
   const dir = path.join(os.homedir(), '.kracked');
@@ -99,9 +123,17 @@ export function scanExistingProject(targetDir) {
   if (fs.existsSync(pkgPath)) {
     try {
       const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-      if (pkg.name) summary.name = pkg.name;
+
+      // Everything below comes from an untrusted repo and ends up inside files
+      // the agent reads as instructions — sanitize before it goes anywhere.
+      const cleanName = sanitizeScanned(pkg.name);
+      if (cleanName) summary.name = cleanName;
+
       if (pkg.scripts && typeof pkg.scripts === 'object') {
-        summary.scripts = pkg.scripts;
+        // Keep only plausible script names; a hostile key is dropped, not rendered.
+        for (const key of Object.keys(pkg.scripts)) {
+          if (/^[a-zA-Z0-9:_-]{1,40}$/.test(key)) summary.scripts[key] = true;
+        }
       }
       const deps = { ...pkg.dependencies, ...pkg.devDependencies };
       const frameworkHints = [
@@ -127,13 +159,3 @@ export function stackSummaryLine(summary) {
   return parts.length ? parts.join(' ') : 'unknown — not auto-detected';
 }
 
-/** Which harnesses already have a footprint in this project dir? */
-export function detectHarnesses(targetDir) {
-  return {
-    claudeCode: fs.existsSync(path.join(targetDir, '.claude')) ||
-      fs.existsSync(path.join(targetDir, 'CLAUDE.md')),
-    antigravity: fs.existsSync(path.join(targetDir, '.agents')) ||
-      fs.existsSync(path.join(targetDir, 'AGENTS.md')),
-    cursor: fs.existsSync(path.join(targetDir, '.cursor')),
-  };
-}

package/src/prompt.mjs

@@ -27,32 +27,112 @@ function setCursor(visible) {
   stdout.write(visible ? `${ESC}[?25h` : `${ESC}[?25l`);
 }
 
+// A throw anywhere outside the keypress handler would otherwise exit with the
+// terminal still in raw mode and the cursor hidden — leaving the user's shell
+// with invisible, unechoed input. One idempotent restore covers every exit path,
+// including process.exit().
+let restoreRegistered = false;
+function registerTerminalRestore() {
+  if (restoreRegistered) return;
+  restoreRegistered = true;
+  process.on('exit', () => {
+    try {
+      if (stdin.isTTY && stdin.isRaw) stdin.setRawMode(false);
+      stdout.write(`${ESC}[?25h`);
+    } catch {
+      // Nothing useful to do while the process is already exiting.
+    }
+  });
+}
+
 /** Move up n lines and clear from there down — used to redraw the menu in place. */
 function clearLines(n) {
   if (n > 0) stdout.write(`${ESC}[${n}A`);
   stdout.write(`${ESC}[0J`);
 }
 
+/**
+ * Split one stdin chunk into individual keys.
+ *
+ * stdin delivers DATA, not keystrokes: holding Enter (key auto-repeat), typing
+ * fast, pasting, or running over SSH/tmux routinely packs several keys into one
+ * chunk. Comparing a whole chunk against '\r' then matches nothing, so the key
+ * is silently dropped and the prompt hangs — the worst kind of failure, because
+ * there is no error to see. Escape sequences (arrows) must stay intact as one
+ * key; everything else is per-character.
+ */
+function splitKeys(chunk) {
+  const keys = [];
+  let i = 0;
+
+  while (i < chunk.length) {
+    if (chunk[i] === ESC) {
+      // CSI sequence: ESC [ ... final-byte (@ through ~). Arrows are ESC[A..D.
+      const match = /^\x1b\[[0-9;?]*[ -/]*[@-~]/.exec(chunk.slice(i));
+      if (match) {
+        keys.push(match[0]);
+        i += match[0].length;
+        continue;
+      }
+      // ESC alone, or an unrecognised sequence — take just the ESC.
+      keys.push(chunk[i]);
+      i += 1;
+      continue;
+    }
+    keys.push(chunk[i]);
+    i += 1;
+  }
+
+  return keys;
+}
+
 /**
  * Read single keypresses until `onKey` signals completion.
  * onKey(key) returns { done: true, value } to finish, or falsy to keep listening.
  */
+// Keys that arrive between prompts — while one question has resolved and the
+// next hasn't attached its listener yet — would otherwise be dropped on the
+// floor. Holding Enter produces exactly that. Buffer them and replay into the
+// next prompt so no keystroke is ever silently lost.
+const pendingKeys = [];
+
+/**
+ * Start capturing keystrokes immediately, before the first prompt renders.
+ * Node takes a moment to boot and draw; anything typed in that window is
+ * otherwise lost. Call once at CLI start.
+ */
+export function beginTypeAhead() {
+  if (!stdin.isTTY) return;
+  registerTerminalRestore();
+  stdin.setRawMode(true);
+  stdin.resume();
+  stdin.setEncoding('utf8');
+  stdin.on('data', bufferEarlyKeys);
+}
+
+function bufferEarlyKeys(chunk) {
+  pendingKeys.push(...splitKeys(chunk));
+}
+
 function readKeys(onKey) {
   return new Promise((resolve, reject) => {
+    registerTerminalRestore();
     const wasRaw = stdin.isRaw;
     stdin.setRawMode(true);
     stdin.resume();
     stdin.setEncoding('utf8');
+    stdin.removeListener('data', bufferEarlyKeys);
 
     const cleanup = () => {
       stdin.setRawMode(wasRaw ?? false);
-      stdin.pause();
       stdin.removeListener('data', handler);
+      // Resume early-capture so keys typed between prompts aren't lost.
+      stdin.on('data', bufferEarlyKeys);
       setCursor(true);
     };
 
-    function handler(key) {
-      // Ctrl+C / Ctrl+D must always escape, whatever the prompt is doing.
+    /** Feed one key to onKey. Returns true when the prompt is finished. */
+    const dispatch = (key) => {
       if (key === KEY.ctrlC || key === KEY.ctrlD) {
         cleanup();
         stdout.write('\n\nCancelled — nothing was written.\n');
@@ -65,12 +145,32 @@ function readKeys(onKey) {
       } catch (err) {
         cleanup();
         reject(err);
-        return;
+        return true;
       }
 
       if (result && result.done) {
         cleanup();
         resolve(result.value);
+        return true;
+      }
+      return false;
+    };
+
+    // Replay anything typed ahead of this prompt before listening for more.
+    while (pendingKeys.length) {
+      if (dispatch(pendingKeys.shift())) return;
+    }
+
+    function handler(chunk) {
+      // One chunk can carry several keys. Dispatch them one at a time; once a
+      // key completes this prompt, park the rest for the next one rather than
+      // discarding them.
+      const keys = splitKeys(chunk);
+      for (let i = 0; i < keys.length; i++) {
+        if (dispatch(keys[i])) {
+          pendingKeys.push(...keys.slice(i + 1));
+          return;
+        }
       }
     }
 
@@ -210,8 +310,12 @@ export async function input(question, defaultValue = '') {
       render();
       return null;
     }
-    // Ignore escape sequences (arrows etc.) and other control chars.
-    if (key.startsWith(ESC) || key < ' ') return null;
+    // Ignore escape sequences (arrows etc.) and any control character. Compare
+    // the code point, not the string — `key < ' '` on a multi-char value tests
+    // lexicographic order, not "is this a control char".
+    if (key.startsWith(ESC)) return null;
+    const code = key.codePointAt(0);
+    if (code < 0x20 || code === 0x7f) return null;
 
     buffer += key;
     render();

package/src/scaffold.mjs

@@ -9,7 +9,12 @@ import { fileURLToPath } from 'node:url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_ROOT = path.join(__dirname, '..', 'templates');
 
-const SKILL_NAMES = [
+// Written into every loader kracked-core generates. `uninstall` requires this
+// exact string before deleting a shared-name file (AGENTS.md / CLAUDE.md), so
+// another tool's loader is never removed. Never change it without a migration.
+export const OWNED_MARKER = '<!-- kracked-core:owned -->';
+
+export const SKILL_NAMES = [
   'kracked-boot',
   'kracked-sdd',
   'kracked-wrap',
@@ -95,8 +100,10 @@ export async function writeGlobalMemory({ tokens, ask, report }) {
 export function registerProject({ tokens }) {
   const globalDir = path.join(os.homedir(), '.kracked');
   const projectsPath = path.join(globalDir, 'projects.md');
+  // Escape pipes — a path or name containing `|` would add phantom columns.
+  const cell = (v) => String(v ?? '').replace(/\|/g, '\\|');
   const stack = tokens.STACK && tokens.STACK.trim() ? tokens.STACK : '—';
-  const row = `| ${tokens.PROJECT_NAME} | ${tokens.PROJECT_PATH} | ${stack} | active |`;
+  const row = `| ${cell(tokens.PROJECT_NAME)} | ${cell(tokens.PROJECT_PATH)} | ${cell(stack)} | active |`;
 
   fs.mkdirSync(globalDir, { recursive: true });
 
@@ -148,34 +155,83 @@ export async function writeProjectMemory({ projectDir, tokens, ask, report }) {
     await writeFileWithConflictCheck(destPath, content, ask, report);
   }
 
-  // sdd/tracker.md + sdd/specs/.gitkeep
-  const trackerDest = path.join(krackedDir, 'sdd', 'tracker.md');
-  const trackerContent = applyTokens(readTemplate('project/sdd/tracker.md'), tokens);
-  await writeFileWithConflictCheck(trackerDest, trackerContent, ask, report);
+  // SDD docs: tracker + the artifact folders, each with a template that
+  // explains what belongs there. An empty folder teaches nothing.
+  const sddDocs = [
+    'sdd/tracker.md',
+    'sdd/README.md',
+    'sdd/specs/_TEMPLATE.md',
+    'sdd/epics/_TEMPLATE.md',
+    'sdd/stories/_TEMPLATE.md',
+    'sdd/architecture/_TEMPLATE.md',
+    'sdd/architecture/decisions/_TEMPLATE.md',
+  ];
+
+  for (const rel of sddDocs) {
+    const destPath = path.join(krackedDir, rel);
+    const content = applyTokens(readTemplate(`project/${rel}`), tokens);
+    await writeFileWithConflictCheck(destPath, content, 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' });
+}
 
-  const gitkeepDest = path.join(krackedDir, 'sdd', 'specs', '.gitkeep');
-  if (!fs.existsSync(gitkeepDest)) {
-    fs.mkdirSync(path.dirname(gitkeepDest), { recursive: true });
-    fs.writeFileSync(gitkeepDest, '', 'utf8');
-    report({ path: gitkeepDest, 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 }) {
+export async function writeLoaders({ projectDir, tokens, ask, report, editors }) {
   const agentsContent = applyTokens(readTemplate('loaders/AGENTS.md'), tokens);
   await writeFileWithConflictCheck(path.join(projectDir, 'AGENTS.md'), agentsContent, ask, report);
 
   const claudeContent = applyTokens(readTemplate('loaders/CLAUDE.md'), tokens);
   await writeFileWithConflictCheck(path.join(projectDir, 'CLAUDE.md'), claudeContent, ask, report);
 
-  const krackedRulesContent = applyTokens(readTemplate('loaders/antigravity-rules.md'), tokens);
-  await writeFileWithConflictCheck(
-    path.join(projectDir, '.agents', 'rules', 'kracked.md'),
-    krackedRulesContent,
-    ask,
-    report
-  );
+  // Roo reads .roo/rules/ only — it does NOT read .agents/rules/, so without
+  // this mirror the pointer is invisible to Roo.
+  if (editors && editors.includes('roo')) {
+    const rooRules = applyTokens(readTemplate('loaders/antigravity-rules.md'), tokens);
+    await writeFileWithConflictCheck(
+      path.join(projectDir, '.roo', 'rules', 'kracked.md'),
+      rooRules,
+      ask,
+      report
+    );
+  }
+
+  // Kilo only loads a rules file if it's declared in kilo.jsonc's `instructions`
+  // array. Merge into an existing config rather than clobbering the user's.
+  if (editors && editors.includes('kilo')) {
+    await writeKiloConfig({ projectDir, report });
+  }
+
+  // Only write the Antigravity pointer when Antigravity is actually in use —
+  // `update` was creating .agents/ in Claude-only projects.
+  if (!editors || editors.includes('antigravity')) {
+    const krackedRulesContent = applyTokens(readTemplate('loaders/antigravity-rules.md'), tokens);
+    await writeFileWithConflictCheck(
+      path.join(projectDir, '.agents', 'rules', 'kracked.md'),
+      krackedRulesContent,
+      ask,
+      report
+    );
+  }
 }
 
 /**
@@ -196,3 +252,41 @@ export async function writeSkills({ projectDir, tokens, editors, ask, report })
     }
   }
 }
+
+/**
+ * Add our rules file to kilo.jsonc's `instructions` array. Kilo does not
+ * auto-load `.kilo/rules/` — a file is only read if it's listed here, so
+ * without this the pointer is silently ignored.
+ * Merges into an existing config; never overwrites the user's settings.
+ */
+async function writeKiloConfig({ projectDir, report }) {
+  const configPath = path.join(projectDir, 'kilo.jsonc');
+  const entry = '.agents/rules/kracked.md';
+
+  if (fs.existsSync(configPath)) {
+    const body = fs.readFileSync(configPath, 'utf8');
+    if (body.includes(entry)) {
+      report({ path: configPath, action: 'already configured' });
+      return;
+    }
+    // Append to the existing instructions array if there is one, else add it.
+    let updated;
+    if (/"instructions"\s*:\s*\[/.test(body)) {
+      updated = body.replace(/("instructions"\s*:\s*\[)/, `$1\n    "${entry}",`);
+    } else {
+      updated = body.replace(/^\s*\{/, `{\n  "instructions": ["${entry}"],`);
+    }
+    fs.writeFileSync(configPath, updated, 'utf8');
+    report({ path: configPath, action: 'updated (added instructions entry)' });
+    return;
+  }
+
+  const fresh = `{
+  // Kilo reads AGENTS.md automatically. This entry additionally loads the
+  // kracked-core rules pointer. Add your own settings alongside it.
+  "instructions": ["${entry}"]
+}
+`;
+  fs.writeFileSync(configPath, fresh, 'utf8');
+  report({ path: configPath, action: 'written' });
+}