kracked-core 1.5.0 → 1.6.1

package/README.md

@@ -47,7 +47,11 @@ It's plain markdown files. You can read them, edit them, commit them to git, and
 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.
+The wizard asks a few questions — name your agent, new or existing project, which editor you use —
+and writes the files. Pressing Enter through it gives you a working setup.
+
+**Existing codebase?** It scans your repo and drafts the memory from what it finds.
+**Starting fresh?** It asks what you're building and what stack, so your agent knows from day one.
 
 **Full support** (memory + all five commands):
 **Antigravity** · **Claude Code** · **Kilo Code** (VS Code) · **Roo Code** (VS Code)

package/bin/kracked-core.mjs

@@ -4,7 +4,7 @@ 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';
+import { beginTypeAhead, endTypeAhead } from '../src/prompt.mjs';
 
 const USAGE = `kracked-core — memory & workflow installer for AI coding agents
 
@@ -63,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.5.0",
+  "version": "1.6.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

@@ -80,6 +80,19 @@ async function writeFileWithConflictCheck(destPath, content, ask, report) {
  * 'skip' | 'overwrite' | 'alongside'.
  * `report(entry)` is called once per file, for the wizard's final summary.
  */
+/**
+ * Drop the illustrative example entries from a freshly-written memory file.
+ * They exist to show the format, but left in place they sit alongside the
+ * user's real lessons forever and make the index untrustworthy.
+ */
+function stripExamples(content) {
+  return content
+    .split('\n')
+    .filter((line) => !/^[-|]\s*\[?(YYYY-MM-DD|\d{4}-\d{2}-\d{2})\]?\s*(todo-app|my-blog|<project>)/.test(line))
+    .filter((line) => !/^\|\s*(todo-app|my-blog)\s*\|/.test(line))
+    .join('\n');
+}
+
 export async function writeGlobalMemory({ tokens, ask, report }) {
   const globalDir = path.join(os.homedir(), '.kracked');
   // projects.md is excluded here — it's a running registry appended to by
@@ -88,7 +101,7 @@ export async function writeGlobalMemory({ tokens, ask, report }) {
 
   for (const file of files) {
     const destPath = path.join(globalDir, file);
-    const content = applyTokens(readTemplate(`global/${file}`), tokens);
+    const content = stripExamples(applyTokens(readTemplate(`global/${file}`), tokens));
     await writeFileWithConflictCheck(destPath, content, ask, report);
   }
 }
@@ -124,10 +137,13 @@ export function registerProject({ tokens }) {
   const lines = content.split('\n');
   const isDivider = (l) => /^\|[\s|:-]+\|?\s*$/.test(l);
 
-  // Find the table's divider row (|---|---|), then insert after the last data
-  // row that follows it. Anchoring on the divider matters: without it, a table
-  // whose only row is the header inserts ABOVE the divider and breaks the table.
-  const dividerIdx = lines.findIndex(isDivider);
+  // Anchor on the Registry heading first — a table-looking line elsewhere in the
+  // doc (an example, a fenced snippet) would otherwise capture the insert and
+  // produce a second, malformed table.
+  const registryIdx = lines.findIndex((l) => /^##\s+Registry\s*$/i.test(l));
+  const searchFrom = registryIdx >= 0 ? registryIdx : 0;
+  const rel = lines.slice(searchFrom).findIndex(isDivider);
+  const dividerIdx = rel >= 0 ? searchFrom + rel : -1;
 
   if (dividerIdx >= 0) {
     let insertAt = dividerIdx;

package/src/update.mjs

@@ -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;
   }

package/src/wizard.mjs

@@ -196,6 +196,7 @@ async function wizardFlow() {
   let projectMode = null; // 'new' | 'existing'
   let stackLine = 'unknown — not auto-detected';
   let projectSummary = null;
+  let projectPitch = '';
 
   if (setUpProject) {
     const pathAnswer = await input('Project directory?', '.');
@@ -250,6 +251,24 @@ async function wizardFlow() {
       classification === 'existing' ? 0 : 1
     );
 
+    if (projectMode === 'new') {
+      // Nothing to scan, so ask instead — otherwise the agent boots knowing
+      // nothing about what's being built, which is the problem this package
+      // exists to solve. Both skippable with Enter.
+      stdout.write('\n  Two quick questions so your agent knows what it\'s working on.\n');
+      stdout.write(`  ${c_dim('Press Enter to skip either one.')}\n\n`);
+
+      projectPitch = sanitizeScanned(
+        await input('What are you building? (one line)', ''),
+        200
+      );
+      const statedStack = sanitizeScanned(
+        await input('What stack? (e.g. Next.js + Supabase)', ''),
+        80
+      );
+      if (statedStack) stackLine = statedStack;
+    }
+
     if (projectMode === 'existing') {
       if (!fs.existsSync(projectDir)) {
         stdout.write(`\n  ${projectDir} doesn't exist yet — nothing to scan. Treating as new.\n`);
@@ -333,6 +352,9 @@ async function wizardFlow() {
     DATE: isoDate(),
     STACK: stackLine,
     RUN_COMMANDS: runCommandsBlock(projectSummary),
+    PITCH: projectPitch
+      ? projectPitch
+      : '_(Add a sentence or two here on what this project actually does.)_',
   };
 
   stdout.write('\nWriting files...\n');

package/templates/global/projects.md

@@ -4,13 +4,7 @@ Registry of every project {{USER_NAME}} is working on. Each row points to the pr
 `.kracked/` folder, where the real detail (stack, conventions, session state) lives. This file
 only tracks what exists and where — never project-specific truth.
 
-## Format
-
-```
-| Project | Path | Stack | Status |
-```
-
-- **Status** is one of: `active`, `paused`, `done`.
+**Status** is one of: `active`, `paused`, `done`.
 
 ## Registry
 

package/templates/project/project.md

@@ -11,7 +11,7 @@ here.
 - **Stack:** {{STACK}}
 - **Created:** {{DATE}}
 
-_(Add a sentence or two here on what this project actually does, once there's something to say.)_
+{{PITCH}}
 
 ## Conventions