@nurix/nustack 0.23.21 → 0.23.22

package/dist/lib/context/hook.js

@@ -0,0 +1,287 @@
+import { createHash } from "node:crypto";
+import { closeSync, openSync, readdirSync, rmSync, statSync } from "node:fs";
+import path from "node:path";
+import { isGateOff } from "../gate/settings.js";
+import { relativeToRoot, resolveProjectRoot } from "../graph/projectRoot.js";
+import { contextMarkersDir } from "../local_store/paths.js";
+import { mkdirSecure } from "../secure_file.js";
+import { composePack, CONTEXT_EXIT_OK } from "./compose.js";
+import { buildEditCard, objectsWrittenIn } from "./editCard.js";
+import { GRAPH_UNAVAILABLE_REASON, openGraphForHook, readCheckoutHead } from "./graph.js";
+import { appendOffered, readOffered, recallHandlerFor } from "./recall.js";
+import { docsRootOf, readRegister } from "./register.js";
+import { extractTerms, resolveObjects, resolvePaths } from "./resolve.js";
+export const CONTEXT_HOOK_DEADLINE_MS = 1_500;
+export const CONTEXT_SESSION_ID_PATTERN = /^[A-Za-z0-9-]{1,128}$/;
+export const CONTEXT_MARKER_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+export const CONTEXT_EDIT_TOOLS = ["Edit", "Write", "MultiEdit"];
+class ContextHookInputError extends Error {
+    code = "HOOK_INPUT_INVALID";
+}
+const TTY_NOTICE = "nustack context: hook entry point; reads Claude Code's hook JSON on stdin\n";
+async function readStdin(stdin) {
+    const chunks = [];
+    for await (const chunk of stdin)
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+function parsePayload(text) {
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        throw new ContextHookInputError("stdin is not JSON");
+    }
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload))
+        throw new ContextHookInputError("stdin is not a JSON object");
+    return payload;
+}
+function stringOf(payload, key) {
+    const value = payload[key];
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+function sha1(text) {
+    return createHash("sha1").update(text).digest("hex");
+}
+function claimMarker(sessionDir, name) {
+    try {
+        closeSync(openSync(path.join(sessionDir, name), "wx", 0o600));
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+}
+function markerExists(sessionDir, name) {
+    try {
+        statSync(path.join(sessionDir, name));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function sessionDirOf(sessionId) {
+    const root = contextMarkersDir();
+    await mkdirSecure(root);
+    const dir = path.join(root, sessionId);
+    await mkdirSecure(dir);
+    return dir;
+}
+async function onPrompt(root, sessionId, payload) {
+    const prompt = stringOf(payload, "prompt");
+    if (prompt === undefined)
+        return null;
+    const register = readRegister(root);
+    if (register === null)
+        return null;
+    const terms = extractTerms(prompt);
+    const cwd = stringOf(payload, "cwd") ?? root;
+    if (resolveObjects(register.objects, prompt, terms.identifiers, []).length === 0 && resolvePaths(root, cwd, terms.paths).resolved.length === 0) {
+        return null;
+    }
+    const markersDir = path.join(contextMarkersDir(), sessionId);
+    const graph = await openGraphForHook(root);
+    try {
+        const pack = composePack({
+            root,
+            cwd,
+            register,
+            text: prompt,
+            paths: [],
+            graph: graph.view,
+            graphReason: graph.reason,
+            docsRoot: docsRootOf(root),
+            checkoutHead: readCheckoutHead(root),
+        });
+        if (pack.exitCode !== CONTEXT_EXIT_OK)
+            return null;
+        const markers = [...pack.objects.map((name) => `pack-${name}`), ...pack.resolvedPaths.map((entry) => `pack-path-${sha1(entry)}`)];
+        if (markers.every((name) => markerExists(markersDir, name)))
+            return null;
+        const sessionDir = await sessionDirOf(sessionId);
+        const claimed = markers.filter((name) => claimMarker(sessionDir, name));
+        if (claimed.length === 0)
+            return null;
+        appendOffered(sessionDir, pack.offeredPaths);
+        return pack.rendered.text;
+    }
+    finally {
+        graph.view?.close();
+    }
+}
+function isFailedToolCall(payload) {
+    const response = payload.tool_response;
+    if (response === null || typeof response !== "object")
+        return false;
+    const fields = response;
+    return fields.success === false || fields.is_error === true || (typeof fields.error === "string" && fields.error !== "");
+}
+async function writeRecallRow(sessionId, relPath, payload, env, stderr) {
+    if (isGateOff(env))
+        return;
+    const sessionDir = path.join(contextMarkersDir(), sessionId);
+    const offered = readOffered(sessionDir);
+    if (offered === null)
+        return;
+    try {
+        const routing = await import("../local_store/routing.js");
+        const handler = recallHandlerFor(relPath, offered, routing.LABEL_ROW_HANDLERS);
+        if (handler === null)
+            return;
+        if (!claimMarker(sessionDir, `edit-${sha1(relPath)}`))
+            return;
+        const { openLocalStore } = await import("../local_store/database.js");
+        const store = await openLocalStore();
+        try {
+            routing.insertLabelRow(store, {
+                id: `lr_${createHash("sha1").update(`${sessionId}:${relPath}:${Date.now()}:${Math.random()}`).digest("hex").slice(0, 24)}`,
+                session_id: sessionId,
+                agent_type: stringOf(payload, "agent_type") ?? "main",
+                path: relPath,
+                estimated_tokens: 0,
+                returned_tokens: 0,
+                handler,
+                check_result: null,
+                bypass_used: 0,
+                latency_ms: 0,
+                tokens_kept_out: 0,
+                created_at: Date.now(),
+            });
+        }
+        finally {
+            store.close();
+        }
+    }
+    catch (error) {
+        stderr.write(`nustack context: recall row: ${messageOf(error)}\n`);
+    }
+}
+async function onEdit(root, sessionId, payload, env, stderr) {
+    const toolName = stringOf(payload, "tool_name");
+    if (toolName === undefined || !CONTEXT_EDIT_TOOLS.includes(toolName))
+        return null;
+    if (isFailedToolCall(payload))
+        return null;
+    const toolInput = payload.tool_input;
+    const filePath = toolInput !== null && typeof toolInput === "object" ? toolInput.file_path : undefined;
+    if (typeof filePath !== "string" || filePath === "")
+        return null;
+    const relPath = relativeToRoot(root, filePath, stringOf(payload, "cwd") ?? root);
+    if (relPath === null)
+        return null;
+    const register = readRegister(root);
+    let text = null;
+    if (register !== null) {
+        const written = objectsWrittenIn(root, register, relPath);
+        if (written.length > 0) {
+            const sessionDir = await sessionDirOf(sessionId);
+            const claimed = written.filter((object) => claimMarker(sessionDir, `card-${object.name}`));
+            if (claimed.length > 0) {
+                const graph = await openGraphForHook(root);
+                try {
+                    text = claimed.map((object) => buildEditCard(root, object, relPath, graph.view, graph.reason ?? GRAPH_UNAVAILABLE_REASON).text).join("\n\n");
+                }
+                finally {
+                    graph.view?.close();
+                }
+            }
+        }
+    }
+    await writeRecallRow(sessionId, relPath, payload, env, stderr);
+    return text;
+}
+function onSessionStart(sessionId, payload, now) {
+    const source = stringOf(payload, "source");
+    const root = contextMarkersDir();
+    if (source === "compact") {
+        rmSync(path.join(root, sessionId), { recursive: true, force: true });
+        return;
+    }
+    if (source !== "startup")
+        return;
+    let names;
+    try {
+        names = readdirSync(root);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!CONTEXT_SESSION_ID_PATTERN.test(name))
+            continue;
+        const folder = path.join(root, name);
+        try {
+            const stats = statSync(folder);
+            if (stats.isDirectory() && now - stats.mtimeMs > CONTEXT_MARKER_MAX_AGE_MS)
+                rmSync(folder, { recursive: true, force: true });
+        }
+        catch {
+        }
+    }
+}
+export async function handleContextEvent(payload, env, stderr = process.stderr) {
+    const event = stringOf(payload, "hook_event_name");
+    const sessionId = stringOf(payload, "session_id");
+    if (event === undefined || sessionId === undefined)
+        throw new ContextHookInputError("hook_event_name or session_id is missing");
+    if (!CONTEXT_SESSION_ID_PATTERN.test(sessionId))
+        throw new ContextHookInputError("session_id is not a plain identifier");
+    if (event === "SessionStart") {
+        onSessionStart(sessionId, payload, Date.now());
+        return null;
+    }
+    const root = resolveProjectRoot(env.CLAUDE_PROJECT_DIR, stringOf(payload, "cwd"));
+    if (root === null)
+        return null;
+    let text = null;
+    if (event === "UserPromptSubmit")
+        text = await onPrompt(root, sessionId, payload);
+    else if (event === "PostToolUse")
+        text = await onEdit(root, sessionId, payload, env, stderr);
+    return text === null ? null : { event, text };
+}
+function codeOf(error) {
+    const code = error?.code;
+    if (typeof code === "string" && code !== "")
+        return code;
+    if (error instanceof Error)
+        return error.constructor.name || error.name;
+    return "Error";
+}
+function messageOf(error) {
+    const text = error instanceof Error ? error.message : String(error);
+    return text.replace(/\s+/g, " ").trim();
+}
+export async function runContextHook(io = { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr, env: process.env }, deps = {}) {
+    process.exitCode = 0;
+    if (io.stdin.isTTY) {
+        io.stderr.write(TTY_NOTICE);
+        return "done";
+    }
+    const handle = deps.handle ?? ((payload, env) => handleContextEvent(payload, env, io.stderr));
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("deadline"), deps.deadlineMs ?? CONTEXT_HOOK_DEADLINE_MS);
+    });
+    const work = (async () => handle(parsePayload(await readStdin(io.stdin)), io.env))();
+    work.catch(() => undefined);
+    try {
+        const outcome = await Promise.race([work, deadline]);
+        if (outcome === "deadline")
+            return "deadline";
+        if (outcome !== null) {
+            io.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: outcome.event, additionalContext: outcome.text } })}\n`);
+        }
+    }
+    catch (error) {
+        io.stderr.write(`nustack context: ${codeOf(error)}: ${messageOf(error)}\n`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return "done";
+}

package/dist/lib/context/recall.js

@@ -0,0 +1,26 @@
+import { appendFileSync, readFileSync } from "node:fs";
+import path from "node:path";
+export const CONTEXT_RECALL_HANDLERS = ["pack_hit", "pack_miss"];
+export const CONTEXT_OFFERED_FILE = "offered";
+export function appendOffered(sessionDir, paths) {
+    const listed = new Set(readOffered(sessionDir) ?? []);
+    const fresh = [...new Set(paths)].filter((entry) => entry !== "" && !listed.has(entry));
+    if (fresh.length === 0)
+        return;
+    appendFileSync(path.join(sessionDir, CONTEXT_OFFERED_FILE), `${fresh.join("\n")}\n`, { mode: 0o600 });
+}
+export function readOffered(sessionDir) {
+    try {
+        return readFileSync(path.join(sessionDir, CONTEXT_OFFERED_FILE), "utf8")
+            .split("\n")
+            .filter((entry) => entry !== "");
+    }
+    catch {
+        return null;
+    }
+}
+export function recallHandlerFor(relPath, offered, handlers) {
+    if (!CONTEXT_RECALL_HANDLERS.every((handler) => handlers.includes(handler)))
+        return null;
+    return offered.includes(relPath) ? "pack_hit" : "pack_miss";
+}

package/dist/lib/context/register.js

@@ -0,0 +1,211 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+export const REGISTER_SUBDIR = path.join("dna", "objects");
+const OBJECT_KEY = /^([a-z0-9][a-z0-9-]*):\s*$/;
+const FIELD = /^ {2}([a-z-]+):(?:\s+(.*))?$/;
+const CLAIM_ITEM = /^ {4}- (.+)$/;
+const SCALAR_FIELDS = new Set(["kind", "plane", "projects", "one-line"]);
+const SEQUENCE_FIELDS = new Set(["aliases", "tables"]);
+export function docsRootOf(root) {
+    try {
+        const parsed = JSON.parse(readFileSync(path.join(root, ".nustack", "workspace.json"), "utf8"));
+        if (typeof parsed.docsRoot === "string" && parsed.docsRoot.trim() !== "")
+            return parsed.docsRoot.trim();
+    }
+    catch {
+    }
+    return "docs";
+}
+class GrammarError extends Error {
+}
+function stripComment(value) {
+    let quote = null;
+    for (let index = 0; index < value.length; index++) {
+        const char = value[index];
+        if (quote !== null) {
+            if (char === "\\" && quote === '"')
+                index++;
+            else if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (char === '"' || char === "'")
+            quote = char;
+        else if (char === "#" && (index === 0 || /\s/.test(value[index - 1] ?? "")))
+            return value.slice(0, index).trimEnd();
+    }
+    return value.trimEnd();
+}
+export function parseScalar(raw) {
+    const value = raw.trim();
+    if (value.startsWith('"')) {
+        if (value.length < 2 || !value.endsWith('"'))
+            throw new GrammarError("unterminated double-quoted scalar");
+        return value.slice(1, -1).replace(/\\(["\\])/g, "$1");
+    }
+    if (value.startsWith("'")) {
+        if (value.length < 2 || !value.endsWith("'"))
+            throw new GrammarError("unterminated single-quoted scalar");
+        return value.slice(1, -1).replace(/''/g, "'");
+    }
+    if (value === "")
+        throw new GrammarError("empty scalar");
+    if (/^[[\]{}&*!|>%@`]/.test(value))
+        throw new GrammarError(`unsupported scalar "${value}"`);
+    return value;
+}
+export function parseFlowSequence(raw) {
+    const value = raw.trim();
+    if (!value.startsWith("[") || !value.endsWith("]"))
+        throw new GrammarError("expected a flow sequence [ … ]");
+    const body = value.slice(1, -1);
+    if (body.trim() === "")
+        return [];
+    const items = [];
+    let current = "";
+    let quote = null;
+    for (let index = 0; index < body.length; index++) {
+        const char = body[index] ?? "";
+        if (quote !== null) {
+            current += char;
+            if (char === "\\" && quote === '"') {
+                current += body[index + 1] ?? "";
+                index++;
+            }
+            else if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            current += char;
+        }
+        else if (char === ",") {
+            items.push(parseScalar(current));
+            current = "";
+        }
+        else if (char === "[" || char === "]" || char === "{" || char === "}") {
+            throw new GrammarError("nested collection in a flow sequence");
+        }
+        else
+            current += char;
+    }
+    if (quote !== null)
+        throw new GrammarError("unterminated quote in a flow sequence");
+    items.push(parseScalar(current));
+    return items;
+}
+function parseClaim(raw) {
+    const value = stripComment(raw);
+    const unchecked = /^unchecked:\s+(.*)$/.exec(value);
+    if (unchecked !== null)
+        return { type: "unchecked", text: parseScalar(unchecked[1] ?? "") };
+    return { type: "predicate", text: parseScalar(value) };
+}
+function emptyObject(name, file, line) {
+    return { name, file, line, aliases: [], kind: null, plane: null, scope: [], tables: [], projects: null, oneLine: null, claims: [] };
+}
+export function parseRegisterText(text, file) {
+    const objects = [];
+    const refusals = [];
+    let current = null;
+    let isRefused = false;
+    let seen = new Set();
+    let isInClaims = false;
+    const lines = text.split(/\r?\n/);
+    const finish = () => {
+        if (current !== null && !isRefused)
+            objects.push(current);
+        current = null;
+    };
+    lines.forEach((line, index) => {
+        const lineNumber = index + 1;
+        if (line.trim() === "" || /^\s*#/.test(line))
+            return;
+        const top = OBJECT_KEY.exec(line);
+        if (top !== null) {
+            finish();
+            current = emptyObject(top[1] ?? "", file, lineNumber);
+            isRefused = false;
+            isInClaims = false;
+            seen = new Set();
+            return;
+        }
+        if (current === null) {
+            refusals.push({ name: null, file, line: lineNumber, reason: "a line outside any object" });
+            return;
+        }
+        if (isRefused)
+            return;
+        const object = current;
+        try {
+            const claim = CLAIM_ITEM.exec(line);
+            if (claim !== null) {
+                if (!isInClaims)
+                    throw new GrammarError("a list item outside claims");
+                object.claims.push(parseClaim(claim[1] ?? ""));
+                return;
+            }
+            const field = FIELD.exec(line);
+            if (field === null)
+                throw new GrammarError("a line outside the register grammar");
+            const key = field[1] ?? "";
+            const value = stripComment(field[2] ?? "");
+            if (seen.has(key))
+                throw new GrammarError(`duplicate key ${key}`);
+            seen.add(key);
+            isInClaims = false;
+            if (key === "claims") {
+                if (value !== "")
+                    throw new GrammarError("claims must be a block sequence");
+                isInClaims = true;
+            }
+            else if (SEQUENCE_FIELDS.has(key)) {
+                const items = parseFlowSequence(value);
+                if (key === "aliases")
+                    object.aliases = items;
+                else
+                    object.tables = items;
+            }
+            else if (key === "scope") {
+                object.scope = value.startsWith("[") ? parseFlowSequence(value) : [parseScalar(value)];
+            }
+            else if (SCALAR_FIELDS.has(key)) {
+                const scalar = parseScalar(value);
+                if (key === "kind")
+                    object.kind = scalar;
+                else if (key === "plane")
+                    object.plane = scalar;
+                else if (key === "projects")
+                    object.projects = scalar;
+                else
+                    object.oneLine = scalar;
+            }
+            else
+                throw new GrammarError(`unknown key ${key}`);
+        }
+        catch (error) {
+            if (!(error instanceof GrammarError))
+                throw error;
+            isRefused = true;
+            refusals.push({ name: object.name, file, line: lineNumber, reason: error.message });
+        }
+    });
+    finish();
+    return { objects, refusals };
+}
+export function readRegister(root, docsRoot = docsRootOf(root)) {
+    const dir = path.join(docsRoot, REGISTER_SUBDIR);
+    const absolute = path.join(root, dir);
+    if (!existsSync(absolute))
+        return null;
+    const register = { dir: dir.split(path.sep).join("/"), objects: [], refusals: [] };
+    const files = readdirSync(absolute).filter((name) => name.endsWith(".yaml")).sort();
+    for (const name of files) {
+        const file = `${register.dir}/${name}`;
+        const parsed = parseRegisterText(readFileSync(path.join(absolute, name), "utf8"), file);
+        register.objects.push(...parsed.objects);
+        register.refusals.push(...parsed.refusals);
+    }
+    return register;
+}

package/dist/lib/context/render.js

@@ -0,0 +1,103 @@
+import { tokensOfLength } from "../gate/estimate.js";
+export const CONTEXT_PACK_MAX_TOKENS = 2_500;
+export const EDIT_CARD_MAX_TOKENS = 600;
+const ANCHOR_ROWS_KEPT = 2;
+const DOCS_KEPT = 3;
+export const SECTION_NAMES = ["RESOLVED", "CARDS", "RELATIONS", "ANCHORS", "DOCS", "OBLIGATIONS", "HOLES"];
+export function emptySections() {
+    return { RESOLVED: [], CARDS: [], RELATIONS: [], ANCHORS: [], DOCS: [], OBLIGATIONS: [], HOLES: [] };
+}
+export function renderLine(line) {
+    return line.label === "NOT KNOWN" ? `  NOT KNOWN — ${line.text}` : `  [${line.label}] ${line.text}`;
+}
+function renderSections(sections, empty, dropped) {
+    const out = [];
+    for (const name of SECTION_NAMES) {
+        out.push(name);
+        const lines = sections[name];
+        if (lines.length === 0)
+            out.push(`  (empty${empty[name] !== undefined ? ` — ${empty[name]}` : ""})`);
+        else
+            out.push(...lines.map(renderLine));
+    }
+    if (dropped.length > 0)
+        out.push(`DROPPED: ${dropped.join("; ")}`);
+    return out.join("\n");
+}
+function copySections(sections) {
+    const copy = emptySections();
+    for (const name of SECTION_NAMES)
+        copy[name] = [...sections[name]];
+    return copy;
+}
+export function renderPack(input, empty = {}, maxTokens = CONTEXT_PACK_MAX_TOKENS) {
+    const sections = copySections(input);
+    const dropped = [];
+    const measure = () => {
+        const text = renderSections(sections, empty, dropped);
+        return { text, sections, dropped, tokens: tokensOfLength(text.length) };
+    };
+    const cardNames = [...new Set(sections.CARDS.map((line) => line.group).filter((group) => group !== undefined))];
+    const steps = [
+        () => {
+            if (sections.RELATIONS.length === 0)
+                return null;
+            sections.RELATIONS = [];
+            return "RELATIONS";
+        },
+        () => {
+            const kept = sections.ANCHORS.filter((line) => (line.rank ?? 0) < ANCHOR_ROWS_KEPT);
+            if (kept.length === sections.ANCHORS.length)
+                return null;
+            sections.ANCHORS = kept;
+            return `ANCHORS past ${ANCHOR_ROWS_KEPT} per path`;
+        },
+        () => {
+            if (sections.DOCS.length <= DOCS_KEPT)
+                return null;
+            sections.DOCS = sections.DOCS.slice(0, DOCS_KEPT);
+            return `DOCS past ${DOCS_KEPT}`;
+        },
+        () => dropCard(sections, cardNames[2]),
+        () => dropCard(sections, cardNames[1]),
+    ];
+    let rendered = measure();
+    for (const step of steps) {
+        if (rendered.tokens <= maxTokens)
+            break;
+        const part = step();
+        if (part !== null) {
+            dropped.push(part);
+            rendered = measure();
+        }
+    }
+    return rendered;
+}
+function dropCard(sections, name) {
+    if (name === undefined)
+        return null;
+    sections.CARDS = sections.CARDS.filter((line) => line.group !== name);
+    sections.HOLES = sections.HOLES.filter((line) => line.group !== name);
+    return `card ${name}`;
+}
+export function renderCard(heading, lines, maxTokens = EDIT_CARD_MAX_TOKENS) {
+    let kept = [...lines];
+    const dropped = [];
+    const text = () => [heading, ...kept.map(renderLine), ...(dropped.length > 0 ? [`DROPPED: ${dropped.join("; ")}`] : [])].join("\n");
+    for (const role of ["writer", "claim"]) {
+        const ofRole = kept.filter((line) => line.role === role);
+        let removed = 0;
+        while (tokensOfLength(text().length) > maxTokens && removed < ofRole.length) {
+            const last = ofRole[ofRole.length - 1 - removed];
+            kept = kept.filter((line) => line !== last);
+            removed++;
+            const label = `${role}s past ${ofRole.length - removed}`;
+            const index = dropped.findIndex((entry) => entry.startsWith(`${role}s past`));
+            if (index === -1)
+                dropped.push(label);
+            else
+                dropped[index] = label;
+        }
+    }
+    return { text: text(), dropped };
+}