karajan-code 3.5.0 → 3.6.0

package/packages/ai-trash/src/index.js

@@ -0,0 +1,14 @@
+// @karajan/ai-trash — public entry (skeleton).
+// Real surface (snapshot, restore, list, manifest) lands in KJC-TSK-0388
+// commits 2-6 and KJC-TSK-0389 (git ops). For now we expose a single
+// `version` export so consumers / tests can confirm the package loads.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+
+export const version = pkg.version;
+export const name = pkg.name;

package/packages/ai-trash/src/install.js

@@ -0,0 +1,52 @@
+// Claude Code settings patcher (KJC-TSK-0390 commit 3). Idempotently
+// adds a PreToolUse hook entry that pipes Bash commands through
+// `kj-trash hook`. Preserves any unrelated keys and existing hooks so
+// the user's other settings are untouched.
+
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+export const HOOK_COMMAND = "kj-trash hook";
+const MATCHER = "Bash";
+
+async function readSettings(path) {
+  try {
+    return JSON.parse(await fs.readFile(path, "utf8"));
+  } catch (err) {
+    if (err.code === "ENOENT") return {};
+    throw err;
+  }
+}
+
+function hasHookCommand(matcherEntry, command) {
+  return (matcherEntry.hooks ?? []).some((h) => h.type === "command" && h.command === command);
+}
+
+export function patchSettings(settings, command = HOOK_COMMAND, matcher = MATCHER) {
+  const next = { ...settings };
+  next.hooks = { ...(next.hooks ?? {}) };
+  const preToolUse = Array.isArray(next.hooks.PreToolUse) ? next.hooks.PreToolUse.slice() : [];
+  let entry = preToolUse.find((e) => e.matcher === matcher);
+  let mutated = false;
+  if (!entry) {
+    entry = { matcher, hooks: [{ type: "command", command }] };
+    preToolUse.push(entry);
+    mutated = true;
+  } else if (!hasHookCommand(entry, command)) {
+    entry.hooks = [...(entry.hooks ?? []), { type: "command", command }];
+    mutated = true;
+  }
+  next.hooks.PreToolUse = preToolUse;
+  return { settings: next, mutated };
+}
+
+export async function installClaudeCodeHook({ path = DEFAULT_SETTINGS_PATH, command = HOOK_COMMAND } = {}) {
+  const settings = await readSettings(path);
+  const { settings: next, mutated } = patchSettings(settings, command);
+  if (!mutated) return { path, mutated: false };
+  await fs.mkdir(dirname(path), { recursive: true });
+  await fs.writeFile(path, JSON.stringify(next, null, 2) + "\n", { encoding: "utf8" });
+  return { path, mutated: true };
+}

package/packages/ai-trash/src/logger.js

@@ -0,0 +1,60 @@
+// Append-only JSONL audit log for the trash store. Events are written one
+// JSON object per line so the file can be `tail -f`-d and parsed
+// line-by-line without holding the whole log in memory.
+
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { lockdownFile } from "./permissions.js";
+
+const HOME = homedir();
+
+function redactPath(p) {
+  if (typeof p !== "string" || !p) return p;
+  if (p === HOME) return "~";
+  if (p.startsWith(`${HOME}/`)) return `~/${p.slice(HOME.length + 1)}`;
+  return p;
+}
+
+function redactPayload(payload) {
+  if (!payload || typeof payload !== "object") return payload;
+  const out = {};
+  for (const [k, v] of Object.entries(payload)) {
+    if (typeof v === "string" && (k.includes("Path") || k === "cwd")) {
+      out[k] = redactPath(v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+export async function appendLogEntry(rootDir, event, payload = {}) {
+  if (!event) throw new Error("ai-trash: log event required");
+  const file = join(rootDir, "log.jsonl");
+  const line =
+    JSON.stringify({
+      ts: new Date().toISOString(),
+      event,
+      ...redactPayload(payload),
+    }) + "\n";
+  await fs.mkdir(rootDir, { recursive: true });
+  await fs.appendFile(file, line, { encoding: "utf8", mode: 0o600 });
+  await lockdownFile(file);
+}
+
+export async function readLog(rootDir) {
+  const file = join(rootDir, "log.jsonl");
+  try {
+    const raw = await fs.readFile(file, "utf8");
+    return raw
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l));
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+export { redactPath };

package/packages/ai-trash/src/manifest.js

@@ -0,0 +1,91 @@
+import { promises as fs } from "node:fs";
+import { dirname, join } from "node:path";
+import { ulid } from "./ulid.js";
+
+export const SCHEMA_VERSION = 1;
+
+export async function loadManifest(rootDir) {
+  const file = join(rootDir, "manifest.json");
+  try {
+    const raw = await fs.readFile(file, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed?.schemaVersion !== SCHEMA_VERSION) {
+      throw new Error(`ai-trash: unsupported manifest schemaVersion ${parsed?.schemaVersion}`);
+    }
+    if (!Array.isArray(parsed.entries)) parsed.entries = [];
+    return parsed;
+  } catch (err) {
+    if (err.code === "ENOENT") return { schemaVersion: SCHEMA_VERSION, entries: [] };
+    throw err;
+  }
+}
+
+export async function saveManifest(rootDir, manifest) {
+  const file = join(rootDir, "manifest.json");
+  await fs.mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(manifest, null, 2), {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  await fs.rename(tmp, file);
+}
+
+export function addEntry(manifest, partial) {
+  if (!partial?.sourcePath) throw new Error("ai-trash: sourcePath required");
+  if (typeof partial.sizeBytes !== "number" || partial.sizeBytes < 0) {
+    throw new Error("ai-trash: sizeBytes must be a non-negative number");
+  }
+  const now = Date.now();
+  const entry = {
+    id: ulid(now),
+    createdAt: now,
+    sourcePath: partial.sourcePath,
+    snapshotPath: partial.snapshotPath ?? null,
+    sizeBytes: partial.sizeBytes,
+    command: partial.command ?? null,
+    origin: partial.origin ?? "unknown",
+  };
+  manifest.entries.push(entry);
+  return entry;
+}
+
+export function listEntries(manifest) {
+  return [...manifest.entries].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function removeEntry(manifest, id) {
+  const idx = manifest.entries.findIndex((e) => e.id === id);
+  if (idx < 0) return null;
+  return manifest.entries.splice(idx, 1)[0];
+}
+
+export function expireBefore(manifest, cutoffMs) {
+  const expired = [];
+  manifest.entries = manifest.entries.filter((e) => {
+    if (e.createdAt < cutoffMs) {
+      expired.push(e);
+      return false;
+    }
+    return true;
+  });
+  return expired;
+}
+
+export function enforceLruQuota(manifest, maxBytes) {
+  if (typeof maxBytes !== "number" || maxBytes < 0) {
+    throw new Error("ai-trash: maxBytes must be a non-negative number");
+  }
+  const sorted = listEntries(manifest);
+  const total = sorted.reduce((sum, e) => sum + e.sizeBytes, 0);
+  const evicted = [];
+  let running = total;
+  for (const entry of sorted) {
+    if (running <= maxBytes) break;
+    evicted.push(entry);
+    running -= entry.sizeBytes;
+  }
+  const evictedIds = new Set(evicted.map((e) => e.id));
+  manifest.entries = manifest.entries.filter((e) => !evictedIds.has(e.id));
+  return evicted;
+}

package/packages/ai-trash/src/permissions.js

@@ -0,0 +1,26 @@
+import { promises as fs } from "node:fs";
+
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+
+export async function ensureSecureDir(path) {
+  await fs.mkdir(path, { recursive: true, mode: DIR_MODE });
+  await fs.chmod(path, DIR_MODE);
+}
+
+export async function lockdownFile(path) {
+  await fs.chmod(path, FILE_MODE);
+}
+
+export async function assertOwnedByCurrentUser(path) {
+  if (process.platform === "win32") return;
+  const stats = await fs.stat(path);
+  if (typeof process.getuid !== "function") return;
+  if (stats.uid !== process.getuid()) {
+    throw new Error(
+      `ai-trash: ${path} is owned by uid ${stats.uid}, expected ${process.getuid()}`
+    );
+  }
+}
+
+export { DIR_MODE, FILE_MODE };

package/packages/ai-trash/src/snapshot.js

@@ -0,0 +1,66 @@
+import { promises as fs } from "node:fs";
+import { basename, join } from "node:path";
+import { ulid } from "./ulid.js";
+import { ensureSecureDir, lockdownFile } from "./permissions.js";
+import { appendLogEntry } from "./logger.js";
+
+async function statOrNull(path) {
+  try {
+    return await fs.lstat(path);
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+export async function snapshotFile(rootDir, sourcePath, options = {}) {
+  const stat = await statOrNull(sourcePath);
+  if (!stat) throw new Error(`ai-trash: source not found: ${sourcePath}`);
+  if (stat.isDirectory()) {
+    throw new Error("ai-trash: directory snapshots not implemented in MVP");
+  }
+  const id = ulid();
+  const storeDir = join(rootDir, "store", id);
+  await ensureSecureDir(storeDir);
+  const snapshotPath = join(storeDir, basename(sourcePath));
+  await fs.copyFile(sourcePath, snapshotPath);
+  await lockdownFile(snapshotPath);
+  const entry = {
+    id,
+    createdAt: Date.now(),
+    sourcePath,
+    snapshotPath,
+    sizeBytes: stat.size,
+    command: options.command ?? null,
+    origin: options.origin ?? "unknown",
+  };
+  await appendLogEntry(rootDir, "snapshot.create", {
+    id,
+    sourcePath,
+    snapshotPath,
+    sizeBytes: stat.size,
+  });
+  return entry;
+}
+
+export async function restoreSnapshot(rootDir, entry, targetPath) {
+  const target = targetPath ?? entry.sourcePath;
+  const exists = await statOrNull(target);
+  if (exists) throw new Error(`ai-trash: refusing to overwrite ${target}`);
+  await fs.mkdir(join(target, ".."), { recursive: true });
+  await fs.copyFile(entry.snapshotPath, target);
+  await appendLogEntry(rootDir, "snapshot.restore", {
+    id: entry.id,
+    snapshotPath: entry.snapshotPath,
+    targetPath: target,
+  });
+  return target;
+}
+
+export async function purgeSnapshot(rootDir, entry) {
+  await fs.rm(join(rootDir, "store", entry.id), { recursive: true, force: true });
+  await appendLogEntry(rootDir, "snapshot.purge", {
+    id: entry.id,
+    sizeBytes: entry.sizeBytes,
+  });
+}

package/packages/ai-trash/src/ulid.js

@@ -0,0 +1,66 @@
+// Tiny ULID generator (Crockford base32, 26 chars, monotonic within ms).
+// We keep this self-contained to avoid pulling a runtime dep into the
+// safety-net package — fewer transitive deps = fewer supply-chain surfaces
+// that an attacker could pivot through to reach the trash store.
+
+import { randomBytes } from "node:crypto";
+
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+let lastMs = 0;
+let lastRandom = new Uint8Array(10);
+
+function encodeTime(ms) {
+  let out = "";
+  for (let i = 9; i >= 0; i--) {
+    out = ENCODING[ms % 32] + out;
+    ms = Math.floor(ms / 32);
+  }
+  return out;
+}
+
+function encodeRandom(bytes) {
+  let out = "";
+  for (let i = 0; i < 16; i++) {
+    const byteIndex = Math.floor((i * 5) / 8);
+    const bitOffset = (i * 5) % 8;
+    const hi = bytes[byteIndex] ?? 0;
+    const lo = bytes[byteIndex + 1] ?? 0;
+    const value = ((hi << 8) | lo) >> (11 - bitOffset);
+    out += ENCODING[value & 31];
+  }
+  return out;
+}
+
+function bumpRandom(buf) {
+  for (let i = buf.length - 1; i >= 0; i--) {
+    if (buf[i] === 0xff) {
+      buf[i] = 0;
+      continue;
+    }
+    buf[i] += 1;
+    return buf;
+  }
+  throw new Error("ulid: random overflow within the same millisecond");
+}
+
+export function ulid(nowMs = Date.now()) {
+  if (nowMs === lastMs) {
+    lastRandom = bumpRandom(lastRandom);
+  } else {
+    lastMs = nowMs;
+    lastRandom = new Uint8Array(randomBytes(10));
+  }
+  return encodeTime(nowMs) + encodeRandom(lastRandom);
+}
+
+export function decodeTimeFromUlid(id) {
+  const slice = id.slice(0, 10);
+  let ms = 0;
+  for (const ch of slice) {
+    const v = ENCODING.indexOf(ch);
+    if (v < 0) throw new Error(`ulid: invalid char ${ch}`);
+    ms = ms * 32 + v;
+  }
+  return ms;
+}

package/scripts/verify-pack.mjs

@@ -18,7 +18,7 @@
  * this from prepublishOnly does not recurse.
  */
 
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -101,6 +101,19 @@ try {
   }
   console.log("verify-pack: sqlite-vec + @karajan/core resolve ✓");
 
+  // 4. kj-trash (ai-trash safety binary) must ship + link onto PATH and boot
+  // without a module-resolution crash. It was silently absent from the tarball
+  // until KJC-BUG-0089 — every npm user got "kj-trash not found".
+  const trashBin = path.join(tmpDir, "node_modules", ".bin", "kj-trash");
+  if (!fs.existsSync(trashBin)) fail(`kj-trash binary missing after install: ${trashBin}`);
+  const trash = spawnSync(trashBin, ["--help"], { encoding: "utf8", env: childEnv });
+  // The CLI exits 2 on --help (usage); only a real crash (module not found, or
+  // an unexpected non-0/2 exit) is a failure.
+  if (![0, 2].includes(trash.status) || /ERR_MODULE_NOT_FOUND|Cannot find/.test(trash.stderr || "")) {
+    fail("`kj-trash --help` crashed on a clean install", trash.stderr || `exit ${trash.status}`);
+  }
+  console.log("verify-pack: kj-trash ships + boots ✓");
+
   console.log(`\n✓ verify-pack: karajan-code@${expectedVersion} installs clean and runs.`);
 } finally {
   if (tgzPath && fs.existsSync(tgzPath)) fs.rmSync(tgzPath, { force: true });

package/src/checks/ai-trash.js

@@ -23,7 +23,7 @@ function createAiTrashCheck() {
         ok: false,
         severity: "warn",
         detail: "kj-trash not found — destructive ops unprotected",
-        fix: "Reinstall karajan-code (kj-trash ships with the workspace) and run `kj-trash install --claude-code`",
+        fix: "Install karajan-code globally (npm i -g karajan-code) so kj-trash is on PATH, then run `kj-trash install --claude-code`",
       };
     },
   };

package/src/cli/register-meta.js

@@ -406,6 +406,10 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--no-config", "Skip lint/format/commit config files (hooks only)")
     .option("--no-ci", "Skip CI quality workflows")
     .option("--no-guidelines", "Skip AI-agent guideline files (AGENTS.md/CLAUDE.md)")
+    .option("--only <dirs...>", "Harden only these language roots (e.g. frontend backend)")
+    .option("--exclude <globs...>", "Skip language roots matching these globs (e.g. wrappers)")
+    .option("--report", "Read-only: show what kj would add/improve, change nothing")
+    .option("--interactive", "Adopt the kj standard piece by piece (default keeps yours)")
     .option("--dry-run", "Show what would change without writing")
     .option("--json", "Emit machine-readable JSON")
     .action(async (flags) => {
@@ -415,6 +419,10 @@ export function registerMeta(program, { pkgVersion }) {
           config: flags.config !== false,
           ci: flags.ci !== false,
           guidelines: flags.guidelines !== false,
+          only: flags.only ?? [],
+          exclude: flags.exclude ?? [],
+          report: Boolean(flags.report),
+          interactive: Boolean(flags.interactive),
           dryRun: Boolean(flags.dryRun),
           json: Boolean(flags.json),
           logger,

package/src/cli.js

@@ -41,6 +41,21 @@ program
   .allowUnknownOption(true)
   .allowExcessArguments(true);
 
+// KJC-TSK-0571: the command list is long (30+). Orient a newcomer to the few
+// commands they actually need; the rest are advanced/internal.
+program.addHelpText(
+  "after",
+  `
+Getting started (the basics — start here):
+  kj init             Set up Karajan in this project (run once)
+  kj run "<task>"     Build or fix something end-to-end (coder + review)
+  kj plan "<task>"    Break a task into user stories first, then run them
+  kj doctor           Check your environment is ready
+  kj harden           Add quality git hooks + CI to any repo
+
+Everything else is advanced or internal — you rarely call it directly.`
+);
+
 registerPipeline(program, { pkgVersion: PKG_VERSION });
 registerPlan(program, { pkgVersion: PKG_VERSION });
 registerRolesSkills(program, { pkgVersion: PKG_VERSION });
@@ -116,7 +131,6 @@ program.action(async (_opts, command) => {
 try {
   await migrateKjToKarajan();
 } catch (err) {
-  // eslint-disable-next-line no-console
   console.warn(`\x1b[33m[warn]\x1b[0m home migration skipped: ${err.message}`);
 }
 

package/src/commands/harden.js

@@ -9,6 +9,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { compareHarden, formatAdvisoryReport } from "../harden/advisory.js";
+import { interactiveHarden } from "../harden/interactive.js";
+import { createWizard, isTTY } from "../utils/wizard.js";
 import { installConfigsForRoots } from "../harden/config-engine.js";
 import { installGuidelines } from "../harden/guidelines-engine.js";
 import { commandsForLanguage } from "../harden/hook-commands.js";
@@ -23,6 +26,21 @@ const JS_TEST_CMD = {
   mocha: "npx mocha",
 };
 
+/**
+ * Per-repo harden scope, persisted in package.json `kj.harden` so a repo with
+ * sub-tools (e.g. a python wrapper) excludes them once instead of on every
+ * invocation (KJC-TSK-0564). CLI flags are merged on top.
+ */
+function readHardenConfig(projectDir) {
+  const pkgPath = join(projectDir, "package.json");
+  if (!existsSync(pkgPath)) return {};
+  try {
+    return JSON.parse(readFileSync(pkgPath, "utf8")).kj?.harden ?? {};
+  } catch {
+    return {};
+  }
+}
+
 /**
  * Resolve the hook's lint/format/test commands for the primary language.
  * Non-JS stacks use their native toolchain (go/ruff/…); JS/TS is built from
@@ -60,9 +78,46 @@ export async function hardenCommand({
   guidelines = true,
   dryRun = false,
   json = false,
+  report = false,
+  interactive = false,
+  only = [],
+  exclude = [],
   logger = console,
 } = {}) {
-  const roots = detectStackRoots(projectDir);
+  const repoCfg = readHardenConfig(projectDir);
+  const onlyDirs = [...(repoCfg.only ?? []), ...only];
+  const excludeDirs = [...(repoCfg.exclude ?? []), ...exclude];
+
+  // --report is read-only: compare against the kj standard and print/emit the
+  // advisory (Advisory B, KJC-TSK-0566), honouring the same scope as an install
+  // so it never proposes a root that `kj harden` would skip. Writes nothing.
+  if (report) {
+    const result = compareHarden({ projectDir, profile, only: onlyDirs, exclude: excludeDirs });
+    if (json) logger.info?.(JSON.stringify(result));
+    else for (const line of formatAdvisoryReport(result)) logger.info?.(line);
+    return { ok: true, report: true, ...result };
+  }
+
+  // --interactive: adopt the kj standard piece by piece, default-safe (keep the
+  // user's own). Only meaningful with a TTY — without one (CI, --json) we fall
+  // through to the normal seed-if-absent install so nothing breaks (KJC-TSK-0567).
+  if (interactive && isTTY() && !json) {
+    const wizard = createWizard();
+    try {
+      return await interactiveHarden({
+        projectDir,
+        profile,
+        only: onlyDirs,
+        exclude: excludeDirs,
+        ask: (prompt, def) => wizard.confirm(prompt, def),
+        logger,
+      });
+    } finally {
+      wizard.close();
+    }
+  }
+
+  const roots = detectStackRoots(projectDir, { only: onlyDirs, exclude: excludeDirs });
   const cmds = await resolveCmds(projectDir, roots[0]?.language ?? null);
   let result;
   try {
@@ -102,6 +157,6 @@ export async function hardenCommand({
   for (const c of out.configs) logger.info?.(`  • ${c.file}: ${c.action}`);
   for (const w of out.workflows) logger.info?.(`  • ${w.file}: ${w.action}`);
   for (const g of out.guidelines) logger.info?.(`  • ${g.file}: ${g.action}`);
-  if (!dryRun) logger.info?.("core.hooksPath set. Verify later with `kj check` (H-E).");
+  if (!dryRun) logger.info?.("core.hooksPath set. Verify later with `kj check`.");
   return out;
 }