@vextlabs/theron-cli 0.1.0 → 0.2.0

package/dist/project_memory.js

@@ -0,0 +1,158 @@
+// project_memory — auto-load a per-project instructions file and inject
+// it into every chat turn as system context. Theron's analogue to Claude
+// Code's CLAUDE.md.
+//
+// Why this exists: a CLI that edits your repo should know the repo's
+// rules (build command, code style, "never touch migrations/", the
+// canonical model count) WITHOUT you re-typing them every session. Claude
+// Code reads CLAUDE.md at the project root + a parent-dir cascade; this
+// gives Theron the same superpower.
+//
+// Resolution (mirrors cap_config.ts's two-tier overlay + the verifiers'
+// findTsconfig walk-up):
+//   1. Global   — ~/.theron/THERON.md (your cross-project house style).
+//   2. Ancestors — walk UP from cwd (max 8 levels), and at each dir take
+//      the first of THERON.md / CLAUDE.md / AGENTS.md that exists. We stop
+//      at the FIRST ancestor that has a memory file so a sub-package's
+//      THERON.md wins over the monorepo root's (closest-wins, same spirit
+//      as project-local caps.json overriding the global one).
+//
+// THERON.md is preferred, then CLAUDE.md, then AGENTS.md — so a repo that
+// already has a CLAUDE.md (most do) gets picked up with zero setup, and a
+// Theron user can add a THERON.md to override it just for Theron.
+//
+// The loaded text rides into the request as a leading note (see repl.ts /
+// api.ts `projectContext`). This is a pure client-side feature: no server
+// change is required — worst case the server ignores the field and the
+// note still travels in the messages array as plain context.
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+/** Filenames we recognize as a project-memory file, in priority order.
+ *  THERON.md is ours; CLAUDE.md / AGENTS.md are the de-facto conventions
+ *  most repos already carry, so we read them too for zero-setup pickup. */
+export const MEMORY_FILENAMES = ["THERON.md", "CLAUDE.md", "AGENTS.md"];
+/** Hard cap on injected memory size. A runaway CLAUDE.md (some are huge)
+ *  shouldn't blow the context window or the request body. We keep the
+ *  head — the top of these files is almost always the important rules —
+ *  and mark the truncation so the model knows it didn't see all of it. */
+const MAX_MEMORY_BYTES = 32 * 1024;
+/** How far up the directory tree we walk looking for a memory file.
+ *  Matches findTsconfig's depth so behavior is consistent across the CLI. */
+const MAX_WALK_DEPTH = 8;
+const EMPTY = { content: "", sources: [], truncated: false };
+/** Read a UTF-8 file, returning null on any error (missing / unreadable /
+ *  not a regular file). Never throws — a bad memory file must not break
+ *  the REPL. */
+function readMemorySafe(filePath) {
+    try {
+        const st = fs.statSync(filePath);
+        if (!st.isFile())
+            return null;
+        return fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Truncate to MAX_MEMORY_BYTES on a UTF-8 boundary, keeping the head. */
+function clampBytes(text) {
+    const buf = Buffer.from(text, "utf8");
+    if (buf.length <= MAX_MEMORY_BYTES)
+        return { text, truncated: false };
+    // Slice on a byte boundary then drop a possibly-broken trailing
+    // multibyte char by re-decoding loosely.
+    const head = buf.subarray(0, MAX_MEMORY_BYTES).toString("utf8");
+    return { text: head, truncated: true };
+}
+/**
+ * Find the nearest project-memory file by walking up from `startDir`.
+ * At each ancestor, the first existing filename in MEMORY_FILENAMES wins.
+ * Returns the absolute path, or null if none found within MAX_WALK_DEPTH.
+ *
+ * Closest ancestor wins (a package's THERON.md beats the repo root's), so
+ * a monorepo can give each package its own rules.
+ */
+export function findProjectMemoryFile(startDir) {
+    let dir = path.resolve(startDir);
+    for (let i = 0; i < MAX_WALK_DEPTH; i++) {
+        for (const name of MEMORY_FILENAMES) {
+            const candidate = path.join(dir, name);
+            try {
+                if (fs.statSync(candidate).isFile())
+                    return candidate;
+            }
+            catch {
+                // not here — keep looking
+            }
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // hit filesystem root
+        dir = parent;
+    }
+    return null;
+}
+/** Resolve the path to the global memory file, or null when HOME is unset. */
+function globalMemoryPath() {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+    return home ? path.join(home, ".theron", "THERON.md") : null;
+}
+/**
+ * Load project memory for a given working directory.
+ *
+ * Layering (later sources are appended after earlier ones, so the
+ * project file — being more specific — has the model's freshest
+ * attention): global house style first, then the nearest project file.
+ *
+ * Always returns a value; on any failure it degrades to EMPTY so the
+ * REPL keeps working with no memory injected.
+ */
+export function loadProjectMemory(cwd = process.cwd()) {
+    const sources = [];
+    const chunks = [];
+    let truncatedAny = false;
+    const add = (label, filePath) => {
+        const raw = readMemorySafe(filePath);
+        if (raw === null)
+            return;
+        const trimmed = raw.trim();
+        if (!trimmed)
+            return; // empty/whitespace file — nothing to inject
+        const { text, truncated } = clampBytes(trimmed);
+        if (truncated)
+            truncatedAny = true;
+        sources.push(filePath);
+        chunks.push(`--- ${label}: ${filePath}${truncated ? " (truncated)" : ""} ---\n${text}`);
+    };
+    const gp = globalMemoryPath();
+    if (gp)
+        add("global memory", gp);
+    const projectFile = findProjectMemoryFile(cwd);
+    // Don't double-load if the project file IS the global file (e.g. you're
+    // sitting in ~/.theron).
+    if (projectFile && projectFile !== gp)
+        add("project memory", projectFile);
+    if (chunks.length === 0)
+        return EMPTY;
+    return {
+        content: chunks.join("\n\n"),
+        sources,
+        truncated: truncatedAny,
+    };
+}
+/**
+ * Wrap loaded memory in a clear system-context header for injection. The
+ * header tells the model exactly what this block is and that it's
+ * authoritative project guidance, not user chat. Returns "" when there's
+ * nothing to inject so callers can cheaply skip.
+ */
+export function formatProjectMemoryForRequest(mem) {
+    if (!mem.content)
+        return "";
+    return ("Project context (auto-loaded from a THERON.md / CLAUDE.md / AGENTS.md " +
+        "file — treat as authoritative instructions for this repository, " +
+        "the same weight as a system prompt):\n\n" +
+        mem.content);
+}
+//# sourceMappingURL=project_memory.js.map

package/dist/project_memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project_memory.js","sourceRoot":"","sources":["../src/project_memory.ts"],"names":[],"mappings":"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"}

package/dist/repl.d.ts

@@ -1,4 +1,3 @@
-import { renderMarkdown } from "./render.js";
 interface ReplOptions {
     apiUrl: string;
     apiKey: string | undefined;
@@ -8,6 +7,20 @@ interface ReplOptions {
     oneShot?: string;
     /** Domain profile slug. Defaults to "code". */
     profile?: string;
+    /** Start in plan mode — read-only tools, plan instruction, hard write deny. */
+    planMode?: boolean;
+    /** Headless mode: suppress interactive chrome; for json, buffer the
+     *  answer and emit one JSON object at the end. Implies oneShot. */
+    headless?: boolean;
+    /** Output format for headless mode. */
+    outputFormat?: "text" | "json";
+    /** Resume the most-recent session for this cwd before the loop. */
+    continueSession?: boolean;
+    /** Resume a session (with resumeId, that one; else a picker). */
+    resumeSession?: boolean;
+    resumeId?: string;
+    /** Pretty-render the assistant's markdown at end of turn. */
+    renderMode?: boolean;
 }
 export declare function runRepl(opts: ReplOptions): Promise<number>;
-export { renderMarkdown };
+export {};