codehere 0.3.0-rc.9 → 0.3.2

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

@@ -0,0 +1,245 @@
+/**
+ * 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:
+ *
+ *   .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
+ *
+ * Conventions:
+ *   - CONTEXT.md and PROMPTS.md are committed (project config, shared)
+ *   - HANDOVER.md is git-ignored by default (per-machine working state)
+ *
+ * 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 } from 'fs';
+import { join } 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."
+`,
+    },
+];
+const GITIGNORE_MARKER = '# Added by codehere init';
+const GITIGNORE_BLOCK = `\n${GITIGNORE_MARKER}\n.codehere/HANDOVER.md\n`;
+/**
+ * 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' };
+}
+/**
+ * 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;
+    }
+}
+function ensureGitignore(repoRoot) {
+    const gitDir = join(repoRoot, '.git');
+    if (!existsSync(gitDir))
+        return 'no-git';
+    const gitignorePath = join(repoRoot, '.gitignore');
+    if (isSymlink(gitignorePath))
+        return 'refused-symlink';
+    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
+    if (existing.includes('.codehere/HANDOVER.md'))
+        return 'already-present';
+    appendFileSync(gitignorePath, GITIGNORE_BLOCK);
+    return 'added';
+}
+export function executeInitCommand(options = {}) {
+    try {
+        const { root, type } = resolveTargetRoot();
+        const codehereDir = join(root, '.codehere');
+        newline();
+        console.log(colors.bold('codehere init'));
+        console.log(colors.dim(`  scaffolding .codehere/ at ${type} root: ${root}`));
+        newline();
+        // Refuse if .codehere itself is a symlink — would redirect every subsequent write.
+        if (existsSync(codehereDir) && isSymlink(codehereDir)) {
+            console.log(`  ${error('refused')} .codehere is a symlink — refusing to follow. Remove it first.`);
+            newline();
+            process.exitCode = 1;
+            return;
+        }
+        if (!existsSync(codehereDir)) {
+            mkdirSync(codehereDir, { recursive: true });
+        }
+        else {
+            const codehereStat = statSync(codehereDir);
+            if (!codehereStat.isDirectory()) {
+                console.log(`  ${error('refused')} .codehere exists but is not a directory.`);
+                newline();
+                process.exitCode = 1;
+                return;
+            }
+        }
+        const created = [];
+        const skipped = [];
+        const refused = [];
+        for (const tmpl of TEMPLATES) {
+            const target = join(codehereDir, tmpl.filename);
+            if (isSymlink(target)) {
+                refused.push(tmpl.filename);
+                continue;
+            }
+            if (existsSync(target) && !options.force) {
+                skipped.push(tmpl.filename);
+                continue;
+            }
+            writeFileSync(target, tmpl.body);
+            created.push(tmpl.filename);
+        }
+        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)')}`);
+        }
+        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)')}`);
+                    break;
+                case 'already-present':
+                    console.log(`  ${info('exists ')} .gitignore  ${colors.dim('(HANDOVER.md 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. Update ${colors.cyan('.codehere/HANDOVER.md')} at the end of the session`);
+        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

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

@@ -237,14 +237,61 @@ function generateSimpleReport(report, target) {
     lines.push('Generated by codehere — know what your AI agent did before your tech lead asks.');
     return lines.join('\n');
 }
+/**
+ * Write report to the requested path. If the path is unwritable (EROFS,
+ * EACCES, EPERM, ENOENT on a parent dir we can't create), fall back to
+ * stdout so the user still gets the report instead of a stack trace.
+ *
+ * Returns true if the file was written, false if we fell back to stdout.
+ *
+ * Provoked by rc.25 UAT: `codehere report --simple` from `/` crashed with
+ * `EROFS: read-only file system, open 'codehere-audit.md'`. A user running
+ * the command from any unwritable cwd should still get their report.
+ */
+function writeReportWithFallback(targetPath, content, label) {
+    try {
+        writeFileSync(targetPath, content);
+        console.log(success(`${label} written to ${targetPath}`));
+        return true;
+    }
+    catch (e) {
+        const code = e.code ?? '';
+        if (['EROFS', 'EACCES', 'EPERM', 'ENOENT'].includes(code)) {
+            console.error(error(`Could not write to ${targetPath} (${code}). Printing to stdout instead — pass --out <path> to a writable location.`));
+            process.stdout.write(content + '\n');
+            return false;
+        }
+        throw e;
+    }
+}
 export async function executeReportCommand(target, options = {}) {
     const cwd = process.cwd();
     const resolved = target ? (isAbsolute(target) ? target : join(cwd, target)) : cwd;
-    // Default: write to a file so the user gets a shareable artifact instead of
-    // raw markdown sprayed at the terminal. --stdout opts into the old behavior
-    // for piping; --out overrides the default path.
-    const defaultOutName = options.json ? 'codehere-audit.json' : 'codehere-audit.md';
-    const effectiveOut = options.stdout ? undefined : (options.out ?? defaultOutName);
+    // rc.18: explicit mutex on combinations Codex flagged as silently
+    // ambiguous. Two pairs:
+    //   format    {--json, --simple} — pick at most one output format
+    //   dest      {--stdout, --out}   — pick at most one destination
+    // Previously the second flag silently lost; now we error so users know.
+    if (options.json && options.simple) {
+        console.error(error('--json and --simple cannot be used together. Pick one output format.'));
+        process.exit(2);
+    }
+    if (options.stdout && options.out) {
+        console.error(error('--stdout and --out cannot be used together. Pick one destination.'));
+        process.exit(2);
+    }
+    // Default routing rules (after mutex check):
+    //   --json            → stdout (pipeable to jq, every CLI convention).
+    //   --simple / md     → file (user expects a shareable artifact, not a wall of markdown).
+    //   --out <path>      → wins over the default (explicit beats default).
+    //   --stdout          → forces stdout for non-json formats.
+    // Rationale: rc.15 — `report --json` writing to disk silently broke pipelines
+    // (`codehere report --json | jq` produced empty stdout). Stdout for machine-
+    // readable formats matches `kubectl get -o json`, `docker inspect`, etc.
+    const defaultOut = options.json
+        ? undefined // stdout
+        : 'codehere-audit.md';
+    const effectiveOut = options.stdout ? undefined : (options.out ?? defaultOut);
     if (!existsSync(resolved)) {
         console.error(error(`Not found: ${resolved}`));
         process.exit(1);
@@ -297,8 +344,7 @@ export async function executeReportCommand(target, options = {}) {
     if (options.json) {
         const output = JSON.stringify(report, null, 2);
         if (effectiveOut) {
-            writeFileSync(effectiveOut, output);
-            console.log(success(`Report written to ${effectiveOut}`));
+            writeReportWithFallback(effectiveOut, output, 'Report');
         }
         else {
             console.log(output);
@@ -309,8 +355,7 @@ export async function executeReportCommand(target, options = {}) {
     if (options.simple) {
         const simple = generateSimpleReport(report, resolved);
         if (effectiveOut) {
-            writeFileSync(effectiveOut, simple);
-            console.log(success(`Plain-English report written to ${effectiveOut}`));
+            writeReportWithFallback(effectiveOut, simple, 'Plain-English report');
         }
         else {
             process.stdout.write(simple + '\n');
@@ -320,9 +365,9 @@ export async function executeReportCommand(target, options = {}) {
     // Markdown output
     const markdown = generateMarkdown(report, resolved, cwd);
     if (effectiveOut) {
-        writeFileSync(effectiveOut, markdown);
+        if (!writeReportWithFallback(effectiveOut, markdown, 'Report'))
+            return;
         newline();
-        console.log(success(`Report written to ${effectiveOut}`));
         console.log(colors.dim(`  ${paths.length} files · score ${overallScore}/100 · grade ${grade}`));
         if (criticalCount > 0) {
             console.log(colors.red(`  ${criticalCount} critical issue${criticalCount !== 1 ? 's' : ''} — check the report`));

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

@@ -148,9 +148,14 @@ function renderSessionDrillDown(sessionId, entries) {
         console.log(`  ${icon}  ${time}  ${tool}  ${colors.dim(reason)}`);
     }
     newline();
-    // Verdict
-    if (blocked.length > 2 && sorted.length > 20) {
-        console.log(colors.red('  ⚠ High block rate in a long session — possible prompt injection in multi-agent chain.'));
+    // Verdict — rc.17: tighten "injection" claim to actual high block ratio
+    // (UX_OBSERVATIONS.md P1; long attended sessions shouldn't get accused).
+    if (blocked.length > 2 && sorted.length > 20 && blocked.length / sorted.length > 0.05) {
+        const pct = ((blocked.length / sorted.length) * 100).toFixed(0);
+        console.log(colors.red(`  ⚠ ${pct}% block rate (${blocked.length}/${sorted.length}) — review for injection patterns.`));
+    }
+    else if (blocked.length > 0 && sorted.length > 20) {
+        console.log(colors.yellow(`  ${blocked.length} blocked / ${sorted.length} total — long session, review if unattended.`));
     }
     else if (blocked.length > 0) {
         console.log(colors.yellow(`  ${blocked.length} blocked call${blocked.length !== 1 ? 's' : ''} — review the blocked entries above.`));
@@ -413,6 +418,13 @@ export async function executeStatusCommand(options = {}) {
     const cwd = process.cwd();
     const version = getVersion();
     const entries = readAuditLog();
+    // Validate --since up front — applies to ALL modes, not just --export.
+    // (rc.15 fix: previously the validation ran only inside the --export branch,
+    // so `codehere status --since bogus` silently succeeded with exit 0.)
+    if (options.since && parseDurationToHours(options.since) == null) {
+        console.error(`Invalid --since value: "${options.since}". Use e.g. 24h, 7d, 4w.`);
+        process.exit(1);
+    }
     // Session drill-down mode
     if (options.session) {
         renderSessionDrillDown(options.session, entries);
@@ -421,10 +433,6 @@ export async function executeStatusCommand(options = {}) {
     // Audit export mode — dump raw events for archival/compliance/sharing
     if (options.export) {
         const sinceHours = options.since ? parseDurationToHours(options.since) : null;
-        if (options.since && sinceHours == null) {
-            console.error(`Invalid --since value: "${options.since}". Use e.g. 24h, 7d, 4w.`);
-            process.exit(1);
-        }
         try {
             exportAudit(entries, options.export, sinceHours);
         }
@@ -480,9 +488,17 @@ export async function executeStatusCommand(options = {}) {
                 }));
                 result.taskCount = tasks.length;
             }
-            catch {
+            catch (e) {
+                // rc.25: JSON consumers reading only stdout were still being fed a
+                // lie ([] tasks, 0 count) on real failure (Codex final review:
+                // "degraded behavior being presented as success"). Now we surface a
+                // structured taskLoadError + status:'degraded' so automation can
+                // distinguish "no tasks" from "load failed."
+                console.error('[status --tasks --json] task repository failed to load:', e);
                 result.tasks = [];
                 result.taskCount = 0;
+                result.taskLoadError = e instanceof Error ? e.message : String(e);
+                result.status = 'degraded';
             }
         }
         console.log(JSON.stringify(result, null, 2));
@@ -630,8 +646,14 @@ export async function executeStatusCommand(options = {}) {
                 }
             }
         }
-        catch {
-            console.log(colors.dim('No tasks found. Run "codehere start" to open the task intake, or "codehere task <prompt>" from the CLI.'));
+        catch (e) {
+            // rc.25: don't print "No tasks found" — that's a lie when load failed
+            // (Codex final review: "degraded behavior presented as success"). Show
+            // a clear error line; stderr already has the cause for the operator.
+            console.error('[status] task repository failed to load:', e);
+            const msg = e instanceof Error ? e.message : String(e);
+            console.log(colors.red(`  ✗ Could not load task repository: ${msg}`));
+            console.log(colors.dim('  See logs above for details. Try `codehere start` to (re)init the task intake.'));
         }
     }
     // Quick trust scan (opt-in)