codehere 0.3.4 → 0.5.0-alpha.2

package/dist/presentation/cli/commands/init-command.js

@@ -2,15 +2,35 @@
  * Init Command — scaffold a `.codehere/` directory at the repo root.
  *
  * The user-side analog to `git init`: gives the project a small, conventional
- * shape codehere can read from when an agent runs here. Three files:
+ * shape codehere can read from when an agent runs here.
  *
+ * v0.3.2 surface (the original "three files"):
  *   .codehere/CONTEXT.md   — what this repo is, conventions, constraints
  *   .codehere/HANDOVER.md  — manual cross-session continuity (until F3 ships)
  *   .codehere/PROMPTS.md   — your library of recurring task prompts
  *
+ * v0.5 F3 surface — the four-layer memory tree per docs/design/f3_memory_spec.md:
+ *   .codehere/memory/working/      — current-session scratch (gitignored)
+ *   .codehere/memory/episodic/     — execution record (committable)
+ *   .codehere/memory/semantic/     — graduated lessons (committed)
+ *   .codehere/memory/personal/     — per-developer prefs (gitignored)
+ *   .codehere/memory/candidates/   — staged patterns awaiting graduate (gitignored)
+ *   .codehere/skills/              — task-shape library (committed)
+ *   .codehere/protocols/           — safety + tool config (committed)
+ *
+ * F3 Task 1 = scaffold these directories + minimal seed files. Migration of
+ * the existing CONTEXT.md/HANDOVER.md/PROMPTS.md INTO the new layout is Task 2
+ * (`codehere memory init`). Until then, both layouts coexist — the v0.4.1
+ * files stay where they are; the F3 layout is added alongside.
+ *
+ * HOME is overridable via `CODEHERE_HOME` for test isolation (so the test
+ * suite never writes to the real user's home).
+ *
  * Conventions:
  *   - CONTEXT.md and PROMPTS.md are committed (project config, shared)
  *   - HANDOVER.md is git-ignored by default (per-machine working state)
+ *   - F3 working/, personal/, candidates/ are git-ignored (per-machine state)
+ *   - F3 episodic/, semantic/, skills/, protocols/ are committable
  *
  * Targets the repo root (via findCodebaseRoot), not cwd, so `cd src && codehere init`
  * still scaffolds at the repo root, not inside src/.
@@ -19,8 +39,9 @@
  * Refuses to follow symlinks (lstat check) so a hostile/misplaced symlink at
  * `.codehere/CONTEXT.md` or `.gitignore` cannot redirect writes outside the repo.
  */
-import { existsSync, mkdirSync, writeFileSync, readFileSync, appendFileSync, lstatSync, statSync } from 'fs';
-import { join } from 'path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, appendFileSync, lstatSync, statSync, symlinkSync, readlinkSync, rmSync } from 'fs';
+import { homedir } from 'os';
+import { join, dirname } from 'path';
 import { colors, success, info, warning, error, newline } from '../../../ui.js';
 import { findCodebaseRoot } from '../../../domain/services/codebase-detector.js';
 const TEMPLATES = [
@@ -121,8 +142,116 @@ Things you've been burned by.]
 `,
     },
 ];
+/**
+ * F3 v0.5 seed files — coexist with the v0.4.1 TEMPLATES above.
+ *
+ * Bodies are deliberately minimal — these are scaffolds, not docs. The richer
+ * content lands when memory accumulates (episodic auto-fill from sessions,
+ * semantic graduate via `codehere memory graduate`, skills authored by hand).
+ *
+ * EXPORTED so `memory-command.ts` can recognize "this file is still the
+ * default seed (user hasn't edited)" and overwrite it during migration —
+ * without that check, an init run before memory init would block migration
+ * (target exists ≠ user-edited target exists).
+ */
+export const F3_TEMPLATES = [
+    {
+        filename: 'memory/working/session.md',
+        body: `# Working session
+
+> Per-machine, gitignored. What's in flight right now.
+>
+> codehere reads this on agent spawn. Keep it short.
+> When the session ends, optionally graduate useful patterns into
+> \`memory/semantic/lessons.jsonl\` via \`codehere memory graduate\`.
+
+## In flight
+
+- [ ]
+
+## Decisions made this session
+
+-
+
+## Files touched
+
+-
+`,
+    },
+    {
+        filename: 'memory/semantic/lessons.jsonl',
+        body: '',
+    },
+    {
+        filename: 'memory/personal/preferences.json',
+        body: '{}\n',
+    },
+    {
+        filename: 'skills/_index.md',
+        body: `# Skills
+
+> One folder per skill. Each \`<skill-name>/SKILL.md\` is a task-shape
+> template — the prompt formula plus example inputs/outputs.
+>
+> Migrating from the flat \`PROMPTS.md\`? Run \`codehere memory init\` (Task 2
+> in the F3 spec). Until then both formats coexist — agents read whichever
+> is present.
+`,
+    },
+    {
+        filename: 'skills/_manifest.jsonl',
+        body: '',
+    },
+    {
+        filename: 'protocols/permissions.md',
+        body: `# Permissions
+
+> Human-readable allow/deny policy. The codehere PreToolUse hook reads
+> \`hook_patterns.json\` next to this file for the machine-readable rules;
+> this Markdown is the rationale and exceptions.
+
+## Default policy
+
+[Allow: read, build, test. Confirm: write, network. Deny: secret access.]
+
+## Project-specific exceptions
+
+-
+`,
+    },
+    {
+        filename: 'protocols/hook_patterns.json',
+        body: `{
+  "version": "v0.5",
+  "patterns_builtin": [],
+  "patterns_project": [],
+  "_note": "Run 'codehere protocols export' to populate patterns_builtin[] from the trust-scorer pattern bank. Add project-specific patterns to patterns_project[] — those are preserved across re-exports. Do NOT hand-edit patterns_builtin[] — it's regenerated on each export."
+}
+`,
+    },
+];
+/**
+ * Subdirectories created blindly (regardless of seed files). These ensure
+ * the F3 memory tree is fully present even before the first auto-populated
+ * artifact lands (e.g. episodic/AGENT_LEARNINGS.jsonl is a Task-3 symlink,
+ * not seeded here).
+ */
+const F3_DIRECTORIES = [
+    'memory/working',
+    'memory/episodic',
+    'memory/semantic',
+    'memory/personal',
+    'memory/candidates',
+    'skills',
+    'protocols',
+];
 const GITIGNORE_MARKER = '# Added by codehere init';
-const GITIGNORE_BLOCK = `\n${GITIGNORE_MARKER}\n.codehere/HANDOVER.md\n`;
+const GITIGNORE_LINES = [
+    '.codehere/HANDOVER.md',
+    '.codehere/memory/working/',
+    '.codehere/memory/personal/',
+    '.codehere/memory/candidates/',
+];
 /**
  * Resolve the directory to scaffold. Prefers git/package root over cwd so
  * `cd repo/src && codehere init` still lands at repo/.
@@ -133,6 +262,14 @@ function resolveTargetRoot() {
         return { root: info.rootPath, type: info.type };
     return { root: process.cwd(), type: 'directory' };
 }
+/**
+ * Resolve the user "home" for HOME-scoped state. Override-able via
+ * `CODEHERE_HOME` for test isolation (so test suites never write to the real
+ * user's home).
+ */
+function resolveHome() {
+    return process.env.CODEHERE_HOME || homedir();
+}
 /**
  * Reject a path that exists AND is a symlink. Refusing on symlinks (rather
  * than following) prevents an init run from clobbering files outside the
@@ -146,18 +283,151 @@ function isSymlink(path) {
         return false;
     }
 }
+/**
+ * Walk every intermediate ancestor BELOW codehereDir up to (but not
+ * including) the leaf, refusing if any segment is a symlink. The outer
+ * .codehere symlink check in executeInitCommand handles codehereDir itself;
+ * the leaf is checked separately by writeTemplate / the F3_DIRECTORIES loop.
+ *
+ * Without this, an attacker can plant
+ * `.codehere/memory` as a symlink to `/etc` BEFORE init runs, and the
+ * subsequent `mkdirSync({ recursive: true })` + `writeFileSync` would happily
+ * follow it — bypassing the leaf-level symlink check that only guards the
+ * final filename.
+ *
+ * Caught by codex Round 1 review of F3 Task 1: the original v0.3.2 init
+ * only had one level of nesting (.codehere/CONTEXT.md), so checking
+ * .codehere itself + the leaf was enough. Nested F3 paths
+ * (memory/working/session.md, protocols/permissions.md, ...) need every
+ * intermediate dir checked.
+ *
+ * Returns the offending segment if any is a symlink, or null if the path is
+ * safe to mkdir/write into.
+ */
+function findSymlinkAncestor(codehereDir, relativePath) {
+    // Split on both POSIX and Windows separators (codex Round 2 fix). Without
+    // this, on Windows where `sep === '\\'`, the slash-delimited literals our
+    // callers pass (e.g. 'memory/episodic/AGENT_LEARNINGS.jsonl') would yield a
+    // single-segment array, the loop would never iterate, and the entire
+    // ancestor-symlink defense would silently bypass. POSIX-only is the stated
+    // assumption, but defending the security check against the easy
+    // platform-separator footgun costs one regex.
+    const segments = relativePath.split(/[/\\]/);
+    // Defensive: reject any relative path containing .. — even though templates
+    // are hard-coded, this protects against future schema additions slipping a
+    // traversal through.
+    if (segments.some(seg => seg === '..' || seg === '')) {
+        return relativePath;
+    }
+    // Walk codehereDir, codehereDir/seg1, codehereDir/seg1/seg2, ... (excluding
+    // the final leaf — writeTemplate handles the leaf separately).
+    let current = codehereDir;
+    for (let i = 0; i < segments.length - 1; i++) {
+        current = join(current, segments[i]);
+        if (isSymlink(current))
+            return current;
+    }
+    return null;
+}
 function ensureGitignore(repoRoot) {
     const gitDir = join(repoRoot, '.git');
     if (!existsSync(gitDir))
-        return 'no-git';
+        return { result: 'no-git', addedLines: 0 };
     const gitignorePath = join(repoRoot, '.gitignore');
     if (isSymlink(gitignorePath))
-        return 'refused-symlink';
+        return { result: 'refused-symlink', addedLines: 0 };
     const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
-    if (existing.includes('.codehere/HANDOVER.md'))
-        return 'already-present';
-    appendFileSync(gitignorePath, GITIGNORE_BLOCK);
-    return 'added';
+    // De-duplicate: only append lines that aren't already present.
+    const missing = GITIGNORE_LINES.filter(line => !existing.includes(line));
+    if (missing.length === 0)
+        return { result: 'already-present', addedLines: 0 };
+    const block = (existing.length > 0 && !existing.endsWith('\n') ? '\n' : '') +
+        `\n${GITIGNORE_MARKER}\n` +
+        missing.join('\n') + '\n';
+    appendFileSync(gitignorePath, block);
+    return { result: 'updated', addedLines: missing.length };
+}
+/**
+ * F3 Task 3 — bridge `.codehere/memory/episodic/AGENT_LEARNINGS.jsonl`
+ * to the user-scoped `~/.codehere/sessions.jsonl` execution log via a
+ * symlink. Lets any spawned agent read the project's full execution
+ * history through a single conventional path under .codehere/.
+ *
+ * Behavior:
+ *   - source already a symlink pointing at the correct target → 'exists'
+ *   - source already a symlink pointing elsewhere → re-link → 're-linked'
+ *     (handles HOME-moved scenarios, fresh clone on a new machine, etc.)
+ *   - source is a real file → 'refused' (DO NOT clobber user data)
+ *   - target file missing → touch it (zero-byte; the real session log
+ *     accumulates from agent runs)
+ *   - else → create symlink → 'created'
+ *
+ * The symlink target is ABSOLUTE because the source lives inside the repo
+ * and the target lives in HOME — a relative path would be a long, fragile
+ * climb across many parent directories.
+ */
+export function ensureEpisodicSymlink(codehereDir, home) {
+    const sourcePath = join(codehereDir, 'memory/episodic/AGENT_LEARNINGS.jsonl');
+    const targetPath = join(home, '.codehere/sessions.jsonl');
+    // K2 Round 1 review fix — refuse if running as root. Otherwise this would
+    // touch ~/.codehere/sessions.jsonl as root, leaving a root-owned file the
+    // user's normal codehere invocation can't read or rotate.
+    if (typeof process.getuid === 'function' && process.getuid() === 0) {
+        return { result: 'root-skipped', sourcePath, targetPath };
+    }
+    // Codex Round 1 BLOCKER fix — same nested-symlink defense Task 1 applied
+    // to writeTemplate / F3_DIRECTORIES. Without this, an attacker plants
+    // `.codehere/memory` → `/etc` and `mkdirSync({recursive:true})` followed by
+    // `symlinkSync` would happily write outside the repo. Reuses the helper.
+    if (findSymlinkAncestor(codehereDir, 'memory/episodic/AGENT_LEARNINGS.jsonl') !== null) {
+        return { result: 'refused', sourcePath, targetPath };
+    }
+    try {
+        // 1. Refuse if source is a real file (would silently destroy user content).
+        if (existsSync(sourcePath) && !isSymlink(sourcePath)) {
+            return { result: 'refused', sourcePath, targetPath };
+        }
+        // 2. Already a symlink — check its target.
+        let wasReLinked = false;
+        if (isSymlink(sourcePath)) {
+            const current = readlinkSync(sourcePath);
+            if (current === targetPath) {
+                return { result: 'exists', sourcePath, targetPath };
+            }
+            // Wrong target — re-link. Track so we report 're-linked', not 'created'.
+            // (Codex Round 1 fix — the previous version returned 'created' here,
+            // making the documented 're-linked' outcome unreachable.)
+            rmSync(sourcePath);
+            wasReLinked = true;
+        }
+        // 3. Ensure target file exists (touch zero-byte if missing).
+        mkdirSync(dirname(targetPath), { recursive: true });
+        if (!existsSync(targetPath))
+            writeFileSync(targetPath, '');
+        // 4. Ensure source's parent dir exists (F3_DIRECTORIES creates this in
+        //    init, but memory-command may call us before/without that path).
+        mkdirSync(dirname(sourcePath), { recursive: true });
+        // 5. Create the symlink with an absolute target.
+        symlinkSync(targetPath, sourcePath);
+        return { result: wasReLinked ? 're-linked' : 'created', sourcePath, targetPath };
+    }
+    catch {
+        return { result: 'failed', sourcePath, targetPath };
+    }
+}
+function writeTemplate(codehereDir, tmpl, force) {
+    const target = join(codehereDir, tmpl.filename);
+    // Refuse if ANY ancestor under .codehere/ is a symlink (codex Round 1 fix).
+    if (findSymlinkAncestor(codehereDir, tmpl.filename) !== null)
+        return 'refused';
+    if (isSymlink(target))
+        return 'refused';
+    if (existsSync(target) && !force)
+        return 'skipped';
+    // Ensure parent dir for nested seeds. Safe now that ancestors are verified.
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, tmpl.body);
+    return 'created';
 }
 export function executeInitCommand(options = {}) {
     try {
@@ -186,21 +456,41 @@ export function executeInitCommand(options = {}) {
                 return;
             }
         }
+        // F3 layout: ensure all directories exist before writing any seeds.
+        // Per-segment symlink check on EACH directory's ancestors; if .codehere/memory
+        // (or skills, or protocols, etc.) is a symlink, refuse to mkdir into it.
+        const refusedDirs = [];
+        for (const dir of F3_DIRECTORIES) {
+            const offending = findSymlinkAncestor(codehereDir, dir);
+            const fullPath = join(codehereDir, dir);
+            if (offending !== null || isSymlink(fullPath)) {
+                refusedDirs.push(dir);
+                continue;
+            }
+            mkdirSync(fullPath, { recursive: true });
+        }
         const created = [];
         const skipped = [];
         const refused = [];
+        // v0.4.1 templates first (CONTEXT/HANDOVER/PROMPTS at the top level).
         for (const tmpl of TEMPLATES) {
-            const target = join(codehereDir, tmpl.filename);
-            if (isSymlink(target)) {
+            const outcome = writeTemplate(codehereDir, tmpl, !!options.force);
+            if (outcome === 'created')
+                created.push(tmpl.filename);
+            else if (outcome === 'skipped')
+                skipped.push(tmpl.filename);
+            else
                 refused.push(tmpl.filename);
-                continue;
-            }
-            if (existsSync(target) && !options.force) {
+        }
+        // F3 v0.5 seed files (memory layers + skills + protocols).
+        for (const tmpl of F3_TEMPLATES) {
+            const outcome = writeTemplate(codehereDir, tmpl, !!options.force);
+            if (outcome === 'created')
+                created.push(tmpl.filename);
+            else if (outcome === 'skipped')
                 skipped.push(tmpl.filename);
-                continue;
-            }
-            writeFileSync(target, tmpl.body);
-            created.push(tmpl.filename);
+            else
+                refused.push(tmpl.filename);
         }
         for (const f of created) {
             console.log(`  ${success(`created`)}  .codehere/${f}`);
@@ -211,15 +501,41 @@ export function executeInitCommand(options = {}) {
         for (const f of refused) {
             console.log(`  ${error(`refused`)} .codehere/${f}  ${colors.dim('(symlink — remove it first)')}`);
         }
+        for (const d of refusedDirs) {
+            console.log(`  ${error(`refused`)} .codehere/${d}/  ${colors.dim('(intermediate symlink — remove it first)')}`);
+        }
+        // F3 Task 3 — episodic AGENT_LEARNINGS.jsonl symlink to user's session log.
+        const home = resolveHome();
+        const episodic = ensureEpisodicSymlink(codehereDir, home);
+        switch (episodic.result) {
+            case 'created':
+                console.log(`  ${success('linked  ')} .codehere/memory/episodic/AGENT_LEARNINGS.jsonl → ${episodic.targetPath}`);
+                break;
+            case 're-linked':
+                console.log(`  ${success('re-linked')} .codehere/memory/episodic/AGENT_LEARNINGS.jsonl → ${episodic.targetPath}  ${colors.dim('(target updated)')}`);
+                break;
+            case 'exists':
+                // Quiet on the no-op case to avoid output noise on re-runs.
+                break;
+            case 'refused':
+                console.log(`  ${error('refused ')} .codehere/memory/episodic/AGENT_LEARNINGS.jsonl  ${colors.dim('(real file or symlinked ancestor present — remove it first to enable the symlink)')}`);
+                break;
+            case 'root-skipped':
+                console.log(`  ${warning('skipped ')} episodic symlink  ${colors.dim('(running as root — would create root-owned files in HOME; re-run as your normal user)')}`);
+                break;
+            case 'failed':
+                console.log(`  ${warning('skipped ')} episodic symlink  ${colors.dim('(could not write — HOME may be read-only)')}`);
+                break;
+        }
         if (!options.noGitignore) {
             const gitignoreResult = ensureGitignore(root);
             newline();
-            switch (gitignoreResult) {
-                case 'added':
-                    console.log(`  ${success('updated')} .gitignore  ${colors.dim('(.codehere/HANDOVER.md ignored — per-machine working state)')}`);
+            switch (gitignoreResult.result) {
+                case 'updated':
+                    console.log(`  ${success('updated')} .gitignore  ${colors.dim(`(+${gitignoreResult.addedLines} entr${gitignoreResult.addedLines === 1 ? 'y' : 'ies'} for HANDOVER + memory/working/, /personal/, /candidates/)`)}`);
                     break;
                 case 'already-present':
-                    console.log(`  ${info('exists ')} .gitignore  ${colors.dim('(HANDOVER.md already ignored)')}`);
+                    console.log(`  ${info('exists ')} .gitignore  ${colors.dim('(codehere entries already ignored)')}`);
                     break;
                 case 'no-git':
                     console.log(`  ${warning('skipped')} .gitignore  ${colors.dim('(no .git directory at root)')}`);
@@ -233,7 +549,9 @@ export function executeInitCommand(options = {}) {
         console.log(colors.bold('Next:'));
         console.log(`  1. Open ${colors.cyan('.codehere/CONTEXT.md')} and fill in what this repo is`);
         console.log(`  2. Run ${colors.cyan('codehere start')} and delegate your first task`);
-        console.log(`  3. Update ${colors.cyan('.codehere/HANDOVER.md')} at the end of the session`);
+        console.log(`  3. Track in-flight work in ${colors.cyan('.codehere/HANDOVER.md')} as you go`);
+        console.log(`  ${colors.dim('Inspect what gets injected at spawn:')} ${colors.cyan('codehere memory show injection')}`);
+        console.log(`  ${colors.dim('To adopt the F3 canonical layout (AGENTS.md / memory/working/session.md / skills/), run:')} ${colors.cyan('codehere memory init')}`);
         newline();
     }
     catch (e) {