kracked-core 1.0.0 → 1.4.0

package/src/scaffold.mjs

@@ -9,7 +9,18 @@ import { fileURLToPath } from 'node:url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_ROOT = path.join(__dirname, '..', 'templates');
 
-const SKILL_NAMES = ['kracked-boot', 'kracked-sdd', 'kracked-wrap', 'kracked-explain'];
+// 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',
+  'kracked-explain',
+  'kracked-identity',
+];
 
 /** Read a template file, throwing a clear error if Track A hasn't shipped it yet. */
 function readTemplate(relPath) {
@@ -89,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 });
 
@@ -142,38 +155,66 @@ 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',
+  ];
 
-  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' });
+  for (const rel of sddDocs) {
+    const destPath = path.join(krackedDir, rel);
+    const content = applyTokens(readTemplate(`project/${rel}`), tokens);
+    await writeFileWithConflictCheck(destPath, content, ask, report);
   }
 }
 
 /** 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
+    );
+  }
 }
 
 /**
- * Write the 4 skills to BOTH .claude/skills/<name>/SKILL.md and
+ * Write every skill to BOTH .claude/skills/<name>/SKILL.md and
  * .agents/skills/<name>/SKILL.md — but only for the harnesses selected.
  * `editors` is an array that may contain 'antigravity' and/or 'claude'.
  */
@@ -190,3 +231,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' });
+}

package/src/uninstall.mjs

@@ -0,0 +1,214 @@
+// `kracked-core uninstall` — remove what the installer wrote.
+//
+// Deleting a user's memory is unrecoverable, so this is deliberately cautious:
+// it shows exactly what it will remove, asks per layer, defaults to No on the
+// global layer, and never deletes a file it didn't recognise as its own.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { stdout } from 'node:process';
+
+import { select, confirm } from './prompt.mjs';
+import { OWNED_MARKER, SKILL_NAMES } from './scaffold.mjs';
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+
+/**
+ * Files/dirs the installer writes into a project.
+ *
+ * CRITICAL: when the "project" IS the home directory, `<project>/.kracked` and
+ * `~/.kracked` are the same folder — so listing it as a project target would
+ * delete the user's entire global memory behind the mild "Remove these project
+ * files?" prompt, never reaching the two-step global confirmation below.
+ * Global memory is only ever removable via the global layer.
+ */
+function projectTargets(projectDir) {
+  const globalDir = path.resolve(path.join(os.homedir(), '.kracked'));
+
+  const targets = [
+    { path: path.join(projectDir, '.kracked'), label: '.kracked/', kind: 'dir' },
+    { path: path.join(projectDir, 'AGENTS.md'), label: 'AGENTS.md', kind: 'file' },
+    { path: path.join(projectDir, 'CLAUDE.md'), label: 'CLAUDE.md', kind: 'file' },
+    {
+      path: path.join(projectDir, '.agents', 'rules', 'kracked.md'),
+      label: '.agents/rules/kracked.md',
+      kind: 'file',
+    },
+  ];
+
+  // Roo's rules mirror. kilo.jsonc is deliberately NOT listed — it may hold the
+  // user's own settings, so removing it wholesale would destroy their config.
+  targets.push({
+    path: path.join(projectDir, '.roo', 'rules', 'kracked.md'),
+    label: '.roo/rules/kracked.md',
+    kind: 'file',
+  });
+
+  // "Write alongside" during init creates these; nothing else knew about them,
+  // so they were orphaned forever.
+  for (const base of ['AGENTS.md', 'CLAUDE.md']) {
+    targets.push({
+      path: path.join(projectDir, `${base}.kracked-new`),
+      label: `${base}.kracked-new`,
+      kind: 'file',
+    });
+  }
+
+  for (const skill of SKILL_NAMES) {
+    targets.push({
+      path: path.join(projectDir, '.claude', 'skills', skill),
+      label: `.claude/skills/${skill}/`,
+      kind: 'dir',
+    });
+    targets.push({
+      path: path.join(projectDir, '.agents', 'skills', skill),
+      label: `.agents/skills/${skill}/`,
+      kind: 'dir',
+    });
+  }
+
+  return targets.filter((t) => {
+    if (!fs.existsSync(t.path)) return false;
+    // Never let a project target resolve onto global memory.
+    if (path.resolve(t.path) === globalDir) return false;
+    return true;
+  });
+}
+
+/**
+ * Only the two SHARED loader filenames can belong to another system —
+ * AGENTS.md and CLAUDE.md are conventions other tools use too, so their
+ * contents decide ownership. Everything else lives at a kracked-core-specific
+ * path (.kracked/, kracked.md, skills/kracked-*) and is ours by definition.
+ */
+function isOurs(filePath) {
+  const base = path.basename(filePath);
+  if (base !== 'AGENTS.md' && base !== 'CLAUDE.md') return true;
+
+  try {
+    // Require the sentinel the installer writes. Anything else — including a
+    // file that merely MENTIONS kracked-core, or another tool using the shared
+    // `@AGENTS.md` import convention — is someone else's and must survive.
+    // Fail closed: an orphaned file is recoverable, a deleted one is not.
+    const body = fs.readFileSync(filePath, 'utf8');
+    if (body.includes(OWNED_MARKER)) return true;
+
+    // Pre-sentinel installs (<=1.2.0) have no marker. Recognise their exact
+    // generated shape so an upgrade path doesn't orphan loaders forever.
+    // Deliberately narrow: a bare `@AGENTS.md` (a shared convention other tools
+    // use) is NOT enough on its own.
+    const legacyClaude = /^@AGENTS\.md\s*\n[\s\S]*canonical instructions live in `AGENTS\.md`/.test(body);
+    const legacyAgents = /^# AGENTS\.md — [\s\S]*This is the canonical loader[\s\S]*kracked-boot/.test(body);
+    return legacyClaude || legacyAgents;
+  } catch {
+    return false; // unreadable — leave it alone rather than risk deleting someone else's
+  }
+}
+
+function remove(target) {
+  if (target.kind === 'dir') {
+    fs.rmSync(target.path, { recursive: true, force: true });
+  } else {
+    fs.rmSync(target.path, { force: true });
+  }
+}
+
+/** Drop now-empty .claude/.agents shells so uninstall leaves no litter. */
+function pruneEmptyParents(projectDir) {
+  const candidates = [
+    path.join(projectDir, '.claude', 'skills'),
+    path.join(projectDir, '.claude'),
+    path.join(projectDir, '.agents', 'rules'),
+    path.join(projectDir, '.roo', 'rules'),
+    path.join(projectDir, '.roo'),
+    path.join(projectDir, '.agents', 'skills'),
+    path.join(projectDir, '.agents'),
+  ];
+  for (const dir of candidates) {
+    try {
+      if (fs.existsSync(dir) && fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
+    } catch {
+      // Non-empty or not ours to remove — leaving it is the safe outcome.
+    }
+  }
+}
+
+export async function runUninstall() {
+  if (!process.stdin.isTTY) {
+    process.stderr.write(
+      'kracked-core uninstall needs an interactive terminal.\n' +
+      'Run it directly in a terminal, or delete the files manually — see\n' +
+      'https://github.com/Krackeddevs-Org/kracked-core/blob/main/docs/UNINSTALL.md\n'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const projectDir = process.cwd();
+  const globalDir = path.join(os.homedir(), '.kracked');
+
+  stdout.write(`${bold('kracked-core uninstall')}\n\n`);
+
+  // ---- Project layer ----
+  const found = projectTargets(projectDir);
+
+  if (found.length === 0) {
+    stdout.write(`No kracked-core files found in ${projectDir}\n`);
+  } else {
+    // Loaders another system owns must never be deleted.
+    const foreign = found.filter((t) => t.kind === 'file' && !isOurs(t.path));
+    const ours = found.filter((t) => !foreign.includes(t));
+
+    stdout.write(`Found in ${dim(projectDir)}:\n`);
+    for (const t of ours) stdout.write(`  ${t.label}\n`);
+    if (foreign.length) {
+      stdout.write('\n  Not ours — will NOT be touched:\n');
+      for (const t of foreign) stdout.write(`    ${t.label} ${dim('(another system wrote this)')}\n`);
+    }
+    stdout.write('\n');
+
+    const choice = await select('Remove these project files?', [
+      { label: 'No, keep everything', value: 'no' },
+      { label: 'Yes, remove them', value: 'yes', hint: 'this cannot be undone' },
+    ], 0);
+
+    if (choice === 'yes') {
+      for (const t of ours) remove(t);
+      pruneEmptyParents(projectDir);
+      stdout.write(`\n  Removed ${ours.length} item(s) from this project.\n`);
+    } else {
+      stdout.write('\n  Kept project files.\n');
+    }
+  }
+
+  // ---- Global layer ----
+  stdout.write('\n');
+  if (!fs.existsSync(globalDir)) {
+    stdout.write(`No global memory at ${globalDir}\n`);
+  } else {
+    stdout.write(`${bold('Global memory')} — ${dim(globalDir)}\n`);
+    stdout.write(
+      '  This holds your agent\'s identity, your preferences, and every lesson it has\n' +
+      '  learned across ALL projects. Removing it cannot be undone, and it is not\n' +
+      '  recreated by reinstalling — the content is yours, not the package\'s.\n\n'
+    );
+
+    const wipe = await confirm('Remove global memory too?', false);
+    if (wipe) {
+      // Deleting months of accumulated lessons deserves a second, explicit yes.
+      const sure = await confirm('Are you sure? Your lessons and preferences will be gone.', false);
+      if (sure) {
+        fs.rmSync(globalDir, { recursive: true, force: true });
+        stdout.write('\n  Removed global memory.\n');
+      } else {
+        stdout.write('\n  Kept global memory.\n');
+      }
+    } else {
+      stdout.write('\n  Kept global memory.\n');
+    }
+  }
+
+  stdout.write('\nDone.\n');
+}

package/src/update.mjs

@@ -0,0 +1,150 @@
+// `kracked-core update` — refresh the package-owned files without touching
+// anything the user has written.
+//
+// The distinction that makes this safe: SKILLS and LOADERS are package files
+// (we wrote them, we can replace them). MEMORY is the user's (identity,
+// preferences, lessons, project docs) — never overwritten here, ever.
+
+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 { select } from './prompt.mjs';
+import { writeLoaders, writeSkills, 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`;
+
+function installedVersion() {
+  try {
+    return require('../package.json').version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/** Which harnesses this project already uses, so update doesn't add new ones. */
+function detectInstalledHarnesses(projectDir) {
+  const editors = [];
+  if (fs.existsSync(path.join(projectDir, '.claude', 'skills'))) editors.push('claude');
+  if (fs.existsSync(path.join(projectDir, '.agents', 'skills'))) editors.push('antigravity');
+  // A CLAUDE.md with no skills dir still means Claude Code is in play.
+  if (!editors.includes('claude') && fs.existsSync(path.join(projectDir, 'CLAUDE.md'))) {
+    editors.push('claude');
+  }
+  return editors;
+}
+
+/** Read the agent + user name back out of an installed AGENTS.md. */
+function recoverTokens(projectDir) {
+  const agentsPath = path.join(projectDir, 'AGENTS.md');
+  const tokens = { AGENT_NAME: 'KC', USER_NAME: os.userInfo().username || 'you' };
+
+  try {
+    const body = fs.readFileSync(agentsPath, 'utf8');
+    const agent = body.match(/You are \*\*([^*]+)\*\*/);
+    if (agent) tokens.AGENT_NAME = agent[1].trim();
+    const user = body.match(/how ([^\s]+) likes to work/);
+    if (user) tokens.USER_NAME = user[1].trim();
+  } catch {
+    // No AGENTS.md to read — fall back to defaults above.
+  }
+
+  return tokens;
+}
+
+/** Which skills exist here but aren't in this version — i.e. new ones to add. */
+function missingSkills(projectDir, editors) {
+  const missing = [];
+  for (const skill of SKILL_NAMES) {
+    const inClaude = editors.includes('claude')
+      && fs.existsSync(path.join(projectDir, '.claude', 'skills', skill, 'SKILL.md'));
+    const inAgents = editors.includes('antigravity')
+      && fs.existsSync(path.join(projectDir, '.agents', 'skills', skill, 'SKILL.md'));
+    const expected = (editors.includes('claude') ? 1 : 0) + (editors.includes('antigravity') ? 1 : 0);
+    const present = (inClaude ? 1 : 0) + (inAgents ? 1 : 0);
+    if (present < expected) missing.push(skill);
+  }
+  return missing;
+}
+
+export async function runUpdate() {
+  if (!process.stdin.isTTY) {
+    process.stderr.write(
+      'kracked-core update needs an interactive terminal.\n' +
+      'Run it directly in a terminal, not piped or in a script.\n'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const projectDir = process.cwd();
+  const version = installedVersion();
+
+  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'
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const editors = detectInstalledHarnesses(projectDir);
+  if (editors.length === 0) {
+    stdout.write('Found .kracked/ but no editor files. Run `npx kracked-core init` instead.\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  const tokens = {
+    ...recoverTokens(projectDir),
+    PROJECT_NAME: path.basename(projectDir),
+    PROJECT_PATH: projectDir,
+    DATE: new Date().toISOString().slice(0, 10),
+    STACK: '',
+    RUN_COMMANDS: '',
+  };
+
+  const newSkills = missingSkills(projectDir, editors);
+
+  stdout.write(`Agent:   ${tokens.AGENT_NAME}\n`);
+  stdout.write(`Editors: ${editors.join(', ')}\n`);
+  if (newSkills.length) {
+    stdout.write(`New in this version: ${newSkills.join(', ')}\n`);
+  }
+
+  stdout.write(`\n${bold('Will be refreshed')} ${dim('(package files — safe to replace)')}\n`);
+  stdout.write('  the 5 skills, AGENTS.md, CLAUDE.md, .agents/rules/kracked.md\n');
+  stdout.write(`\n${bold('Will NOT be touched')} ${dim('(yours)')}\n`);
+  stdout.write('  ~/.kracked/  — identity, preferences, lessons\n');
+  stdout.write('  .kracked/    — project memory, specs, epics, stories, architecture\n\n');
+
+  const choice = await select('Refresh package files to this version?', [
+    { label: 'Yes, update', value: 'yes' },
+    { label: 'No, cancel', value: 'no' },
+  ], 0);
+
+  if (choice === 'no') {
+    stdout.write('\nCancelled — nothing changed.\n');
+    return;
+  }
+
+  // Package files are ours, so overwrite silently rather than prompting per
+  // file. User memory is never in this set.
+  const created = [];
+  const report = (entry) => created.push(entry);
+  const overwrite = async () => 'overwrite';
+
+  stdout.write('\nUpdating...\n');
+  await writeLoaders({ projectDir, tokens, ask: overwrite, report, editors });
+  await writeSkills({ projectDir, tokens, editors, ask: overwrite, report });
+
+  stdout.write(`\n  Refreshed ${created.length} file(s).\n`);
+  stdout.write('\nRestart your editor so it picks up the updated skills.\n');
+}