codehere 1.0.1 → 1.0.2

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

@@ -1,590 +0,0 @@
-/**
- * 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.
- *
- * 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/.
- *
- * Idempotent: re-running detects existing files and skips them unless --force.
- * 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, 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 = [
-    {
-        filename: 'CONTEXT.md',
-        body: `# Project Context
-
-> codehere reads this when an agent runs in this directory.
-> Keep it short. Keep it true. The agent will follow what's written here.
-
-## What this is
-
-[One-paragraph description of what this repo does and who uses it.]
-
-## Conventions
-
-[How this codebase is organized — entry points, file naming, framework version.
-Anything an agent would otherwise have to discover by grep.]
-
-## Style
-
-[Tone for generated code. Test framework. Lint rules. Imports style.
-Prefer X. Avoid Y.]
-
-## Constraints
-
-[Don't do X. Always do Y. Files that are off-limits.
-Things you've been burned by.]
-
-## Useful commands
-
-\`\`\`
-[build, test, lint, dev server — the agent will run these]
-\`\`\`
-`,
-    },
-    {
-        filename: 'HANDOVER.md',
-        body: `# Handover
-
-> Update at the end of each working session.
-> codehere has no project memory across sessions yet (F3 ships in v0.5).
-> This file is the manual handover so the next session — or the next agent —
-> can pick up without you re-explaining.
-
-## Last session
-
-- **Date:**
-- **What got done:**
-- **What's in progress:**
-- **What to pick up next:**
-- **Open questions:**
-
-## Decisions worth remembering
-
-[Decisions made this session that future sessions should respect.]
-
-## Files touched recently
-
-[List the files you've been working on. The agent can prioritize them.]
-`,
-    },
-    {
-        filename: 'PROMPTS.md',
-        body: `# Prompts
-
-> Your library of recurring task prompts.
-> Copy + adapt + delegate via \`codehere task\` or the web UI.
->
-> The codehere prompt formula: **Context + End State + Constraints**.
-> Stack-specific details (test framework, language, file conventions) belong
-> in CONTEXT.md, not duplicated in every prompt here.
-
-## Implement a change
-
-> "Read .codehere/CONTEXT.md. [Describe the change in user-visible terms · what
-> behavior is added, removed, or changed.] Match existing conventions. Don't
-> touch unrelated files. Don't add new dependencies."
-
-## Add tests
-
-> "Read .codehere/CONTEXT.md. Add tests for [FILE / behavior]. Cover happy
-> path, edge cases, and error paths. Match the existing test style and
-> framework. Don't lower the strictness of any existing test."
-
-## Refactor safely
-
-> "Read .codehere/CONTEXT.md. Refactor [FILE / module] to [GOAL]. Keep the
-> public API stable. All existing tests must still pass. Don't introduce
-> new dependencies. Show the diff before applying."
-
-## Review changes
-
-> "Read .codehere/CONTEXT.md. Review the changes in [PR / branch / file] for:
-> security issues, missing tests, breaking changes, style violations, and
-> alignment with the constraints in CONTEXT.md. Output a short markdown
-> report; don't change any code."
-`,
-    },
-];
-/**
- * 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_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/.
- */
-function resolveTargetRoot() {
-    const info = findCodebaseRoot();
-    if (info)
-        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
- * repo if a hostile or misplaced symlink already exists at the target.
- */
-function isSymlink(path) {
-    try {
-        return lstatSync(path).isSymbolicLink();
-    }
-    catch {
-        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 { result: 'no-git', addedLines: 0 };
-    const gitignorePath = join(repoRoot, '.gitignore');
-    if (isSymlink(gitignorePath))
-        return { result: 'refused-symlink', addedLines: 0 };
-    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
-    // 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 scaffoldProjectAt(root, options = {}) {
-    const codehereDir = join(root, '.codehere');
-    const empty = { created: [], skipped: [], refused: [], refusedDirs: [] };
-    const noEpisodic = { result: 'failed', sourcePath: '', targetPath: '' };
-    // Refuse if .codehere itself is a symlink — would redirect every subsequent write.
-    if (existsSync(codehereDir) && isSymlink(codehereDir)) {
-        return {
-            ok: false,
-            reason: 'codehere-dir-is-symlink',
-            ...empty,
-            episodic: noEpisodic,
-            gitignore: { result: 'skipped' },
-        };
-    }
-    if (!existsSync(codehereDir)) {
-        mkdirSync(codehereDir, { recursive: true });
-    }
-    else if (!statSync(codehereDir).isDirectory()) {
-        return {
-            ok: false,
-            reason: 'codehere-not-a-directory',
-            ...empty,
-            episodic: noEpisodic,
-            gitignore: { result: 'skipped' },
-        };
-    }
-    // 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 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);
-    }
-    // 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);
-        else
-            refused.push(tmpl.filename);
-    }
-    // F3 Task 3 — episodic AGENT_LEARNINGS.jsonl symlink to user's session log.
-    const episodic = ensureEpisodicSymlink(codehereDir, resolveHome());
-    const gitignore = options.noGitignore ? { result: 'skipped' } : ensureGitignore(root);
-    return { ok: true, created, skipped, refused, refusedDirs, episodic, gitignore };
-}
-export function executeInitCommand(options = {}) {
-    try {
-        const { root, type } = resolveTargetRoot();
-        newline();
-        console.log(colors.bold('codehere init'));
-        console.log(colors.dim(`  scaffolding .codehere/ at ${type} root: ${root}`));
-        newline();
-        const r = scaffoldProjectAt(root, options);
-        if (!r.ok) {
-            if (r.reason === 'codehere-dir-is-symlink') {
-                console.log(`  ${error('refused')} .codehere is a symlink · refusing to follow. Remove it first.`);
-            }
-            else {
-                console.log(`  ${error('refused')} .codehere exists but is not a directory.`);
-            }
-            newline();
-            process.exitCode = 1;
-            return;
-        }
-        const { created, skipped, refused, refusedDirs } = r;
-        for (const f of created) {
-            console.log(`  ${success(`created`)}  .codehere/${f}`);
-        }
-        for (const f of skipped) {
-            console.log(`  ${info(`exists `)} .codehere/${f}  ${colors.dim('(use --force to overwrite)')}`);
-        }
-        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 episodic = r.episodic;
-        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 = r.gitignore;
-            newline();
-            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('(codehere entries already ignored)')}`);
-                    break;
-                case 'no-git':
-                    console.log(`  ${warning('skipped')} .gitignore  ${colors.dim('(no .git directory at root)')}`);
-                    break;
-                case 'refused-symlink':
-                    console.log(`  ${error('refused')} .gitignore is a symlink · left untouched.`);
-                    break;
-            }
-        }
-        newline();
-        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. Track in-flight work in ${colors.cyan('.codehere/HANDOVER.md')} as you go`);
-        // Power-user / advanced layout entry points moved to docs/advanced/ per the
-        // "one canonical entry" rule (May 2 CUT pass). Used to print two extra
-        // dim lines pointing at `codehere memory show injection` and the F3
-        // canonical layout migration — both confused new users in real-task
-        // dogfood. Power users find them in docs/MEMORY.md.
-        newline();
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        console.error(`\n  ${error('failed')} codehere init · ${msg}\n`);
-        process.exitCode = 1;
-    }
-}
-//# sourceMappingURL=init-command.js.map