kracked-core 1.0.0 → 1.4.0

package/README.md

@@ -49,16 +49,24 @@ 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
 
-Three commands. That's the whole thing.
+Five commands. Three of them are the whole daily loop.
 
 ```
 /kracked-boot    Start of session — agent loads its memory and tells you where you left off
 /kracked-sdd     Build something — idea → spec → docs → build → review
 /kracked-wrap    End of session — agent writes down what it learned
+
+/kracked-identity  Change your agent's name, tone, or how you like to work
+/kracked-explain   "What is all this?" — walks you through what got installed
 ```
 
 > **`/kracked-wrap` is not optional.** Boot without wrap is a memory system that just forgets more slowly. The wrap is where memory actually gets written.
@@ -79,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
@@ -120,6 +134,30 @@ 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.
 
+## 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,51 @@
 #!/usr/bin/env node
 
 import { runInit } from '../src/wizard.mjs';
+import { runUninstall } from '../src/uninstall.mjs';
+import { runUpdate } from '../src/update.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 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 === '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.0.0",
+  "version": "1.4.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');
@@ -15,6 +39,39 @@ export function globalMemoryDir() {
   return path.join(os.homedir(), '.kracked');
 }
 
+/**
+ * Find agent setups already governing this directory, so we never silently
+ * overwrite someone's existing system. A CLAUDE.md/AGENTS.md that kracked-core
+ * didn't write is another system's loader — installing over it would replace
+ * that agent's identity, which is exactly the failure this check prevents.
+ *
+ * Returns [{ file, path, scope, ours }] — `ours` marks files kracked-core
+ * itself wrote (safe to refresh), everything else is someone else's.
+ */
+export function detectExistingAgentSetup(projectDir) {
+  const found = [];
+
+  const inspect = (filePath, label, scope) => {
+    if (!fs.existsSync(filePath)) return;
+    let body = '';
+    try {
+      body = fs.readFileSync(filePath, 'utf8');
+    } catch {
+      return; // unreadable is not our problem to solve here
+    }
+    // Our own loaders always reference kracked-core by name.
+    const ours = /kracked-core|kracked\.md|\.kracked\//.test(body);
+    found.push({ file: label, path: filePath, scope, ours });
+  };
+
+  inspect(path.join(projectDir, 'CLAUDE.md'), 'CLAUDE.md', 'project');
+  inspect(path.join(projectDir, 'AGENTS.md'), 'AGENTS.md', 'project');
+  inspect(path.join(projectDir, '.agents', 'rules', 'kracked.md'), '.agents/rules/kracked.md', 'project');
+  inspect(path.join(os.homedir(), '.claude', 'CLAUDE.md'), '~/.claude/CLAUDE.md', 'global');
+
+  return found;
+}
+
 /**
  * Is the target dir an existing codebase, empty, or new (doesn't exist yet)?
  * Returns one of: "new" (doesn't exist), "empty" (exists, no entries),
@@ -66,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 = [
@@ -94,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

@@ -0,0 +1,339 @@
+// Keyboard-driven prompts: arrow-key single select and spacebar checkboxes.
+// Zero dependencies — raw TTY keypress handling, so the installer never fails
+// in a classroom because of a missing package.
+
+import { stdin, stdout } from 'node:process';
+
+const ESC = '';
+const KEY = {
+  up: `${ESC}[A`,
+  down: `${ESC}[B`,
+  ctrlC: '',
+  ctrlD: '',
+  enter: '\r',
+  newline: '\n',
+  space: ' ',
+};
+
+const c = {
+  dim: (s) => `${s}`,
+  cyan: (s) => `${s}`,
+  green: (s) => `${s}`,
+  bold: (s) => `${s}`,
+};
+
+/** Hide/show the cursor so the redrawing menu doesn't flicker a caret around. */
+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.removeListener('data', handler);
+      // Resume early-capture so keys typed between prompts aren't lost.
+      stdin.on('data', bufferEarlyKeys);
+      setCursor(true);
+    };
+
+    /** 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');
+        process.exit(130);
+      }
+
+      let result;
+      try {
+        result = onKey(key);
+      } catch (err) {
+        cleanup();
+        reject(err);
+        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;
+        }
+      }
+    }
+
+    stdin.on('data', handler);
+  });
+}
+
+/**
+ * Arrow-key single select. `choices` is [{ label, value, hint }].
+ * Returns the chosen `value`.
+ */
+export async function select(question, choices, defaultIndex = 0) {
+  let index = defaultIndex;
+  let drawn = 0;
+
+  const render = () => {
+    clearLines(drawn);
+    let out = `${c.bold('?')} ${question}  ${c.dim('↑↓ to move, Enter to pick')}\n`;
+    for (let i = 0; i < choices.length; i++) {
+      const active = i === index;
+      const pointer = active ? c.cyan('❯') : ' ';
+      const label = active ? c.cyan(choices[i].label) : choices[i].label;
+      const hint = choices[i].hint ? `  ${c.dim(choices[i].hint)}` : '';
+      out += `${pointer} ${label}${hint}\n`;
+    }
+    stdout.write(out);
+    drawn = choices.length + 1;
+  };
+
+  setCursor(false);
+  render();
+
+  const value = await readKeys((key) => {
+    if (key === KEY.up) {
+      index = (index - 1 + choices.length) % choices.length;
+      render();
+    } else if (key === KEY.down) {
+      index = (index + 1) % choices.length;
+      render();
+    } else if (key === KEY.enter || key === KEY.newline) {
+      return { done: true, value: choices[index].value };
+    }
+    return null;
+  });
+
+  // Collapse the menu to a single answered line.
+  clearLines(drawn);
+  const chosen = choices.find((ch) => ch.value === value);
+  stdout.write(`${c.green('✔')} ${question}  ${c.cyan(chosen.label)}\n`);
+  return value;
+}
+
+/**
+ * Spacebar checkbox multi-select. `choices` is [{ label, value, hint, checked }].
+ * Returns an array of checked `value`s. Enter with nothing checked is refused,
+ * since every multi-select in this wizard needs at least one answer.
+ */
+export async function checkbox(question, choices) {
+  let index = 0;
+  let drawn = 0;
+  const state = choices.map((ch) => Boolean(ch.checked));
+  let warning = '';
+
+  const render = () => {
+    clearLines(drawn);
+    let out = `${c.bold('?')} ${question}  ${c.dim('↑↓ move, space to toggle, Enter to confirm')}\n`;
+    for (let i = 0; i < choices.length; i++) {
+      const active = i === index;
+      const pointer = active ? c.cyan('❯') : ' ';
+      const box = state[i] ? c.green('◉') : '◯';
+      const label = active ? c.cyan(choices[i].label) : choices[i].label;
+      const hint = choices[i].hint ? `  ${c.dim(choices[i].hint)}` : '';
+      out += `${pointer} ${box} ${label}${hint}\n`;
+    }
+    if (warning) out += `${c.dim(warning)}\n`;
+    stdout.write(out);
+    drawn = choices.length + 1 + (warning ? 1 : 0);
+  };
+
+  setCursor(false);
+  render();
+
+  const values = await readKeys((key) => {
+    if (key === KEY.up) {
+      index = (index - 1 + choices.length) % choices.length;
+      warning = '';
+      render();
+    } else if (key === KEY.down) {
+      index = (index + 1) % choices.length;
+      warning = '';
+      render();
+    } else if (key === KEY.space) {
+      state[index] = !state[index];
+      warning = '';
+      render();
+    } else if (key === KEY.enter || key === KEY.newline) {
+      const picked = choices.filter((_, i) => state[i]).map((ch) => ch.value);
+      if (picked.length === 0) {
+        warning = '  Pick at least one (space to toggle).';
+        render();
+        return null;
+      }
+      return { done: true, value: picked };
+    }
+    return null;
+  });
+
+  clearLines(drawn);
+  const labels = choices.filter((_, i) => state[i]).map((ch) => ch.label).join(', ');
+  stdout.write(`${c.green('✔')} ${question}  ${c.cyan(labels)}\n`);
+  return values;
+}
+
+/**
+ * Free-text input with a default. Implemented on the same raw-mode reader as
+ * the menus: readline and raw mode cannot share stdin — if both are listening,
+ * keystrokes go to the wrong reader and the wizard hangs. One owner, always.
+ */
+export async function input(question, defaultValue = '') {
+  let buffer = '';
+  const hint = defaultValue ? c.dim(` [${defaultValue}]`) : '';
+
+  const render = () => {
+    stdout.write(`\r${ESC}[0K${c.bold('?')} ${question}${hint} ${buffer}`);
+  };
+
+  setCursor(true);
+  render();
+
+  const value = await readKeys((key) => {
+    if (key === KEY.enter || key === KEY.newline) {
+      return { done: true, value: buffer.trim() || defaultValue };
+    }
+    // Backspace (DEL or BS)
+    if (key === '' || key === '\b') {
+      buffer = buffer.slice(0, -1);
+      render();
+      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();
+    return null;
+  });
+
+  stdout.write(`\r${ESC}[0K${c.green('✔')} ${question}  ${c.cyan(value)}\n`);
+  return value;
+}
+
+/** Yes/no as an arrow menu, so every prompt in the wizard behaves the same way. */
+export async function confirm(question, defaultYes = true) {
+  return select(
+    question,
+    [
+      { label: 'Yes', value: true },
+      { label: 'No', value: false },
+    ],
+    defaultYes ? 0 : 1
+  );
+}