@nurix/nustack 0.23.20 → 0.23.22

package/dist/lib/context/resolve.js

@@ -0,0 +1,104 @@
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+export const CONTEXT_MAX_OBJECTS = 3;
+const SOURCE_EXTENSION = /\.(ts|tsx|js|jsx|mjs|cjs|json|md|mdx|sql|py|rs|go|yaml|yml|toml|css|html|sh)$/i;
+export function isIdentifierShaped(token) {
+    if (!/^[A-Za-z_][A-Za-z0-9_-]*[A-Za-z0-9]$/.test(token))
+        return false;
+    if (/[a-z][A-Z]/.test(token))
+        return true;
+    if (/[A-Za-z0-9]_[A-Za-z0-9]/.test(token))
+        return true;
+    if (/[a-z0-9]-[a-z0-9]/i.test(token))
+        return true;
+    return /^[A-Z][A-Z0-9_]+$/.test(token) && token.length >= 2;
+}
+function isPathShaped(token) {
+    return (token.includes("/") && /[A-Za-z]/.test(token)) || SOURCE_EXTENSION.test(token);
+}
+export function extractTerms(text) {
+    const paths = [];
+    const identifiers = [];
+    const add = (list, term) => {
+        if (term !== "" && !list.includes(term))
+            list.push(term);
+    };
+    const classify = (raw, isBackticked) => {
+        const token = raw.replace(/^[("'[{<]+|[)"'\]}>,;:!?.]+$/g, "").replace(/'s$/, "");
+        if (token === "")
+            return;
+        if (isPathShaped(token))
+            add(paths, token.replace(/^\.\//, ""));
+        else if (isIdentifierShaped(token))
+            add(identifiers, token);
+        else if (isBackticked && /^[A-Za-z_][A-Za-z0-9_]*$/.test(token))
+            add(identifiers, token);
+    };
+    for (const match of text.matchAll(/`([^`]+)`/g)) {
+        const span = (match[1] ?? "").trim();
+        if (/\s/.test(span))
+            span.split(/\s+/).forEach((part) => classify(part, true));
+        else
+            classify(span, true);
+    }
+    for (const token of text.replace(/`[^`]*`/g, " ").split(/\s+/))
+        classify(token, false);
+    return { paths, identifiers };
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function mentions(text, phrase) {
+    const body = escapeRegExp(phrase.trim()).replace(/\s+/g, "\\s+");
+    if (body === "")
+        return false;
+    return new RegExp(`(?:^|[^A-Za-z0-9_-])${body}(?:e?s)?(?=$|[^A-Za-z0-9_-])`, "i").test(text);
+}
+export function resolvePaths(root, cwd, candidates) {
+    const resolved = [];
+    const missing = [];
+    for (const candidate of candidates) {
+        const fromRoot = path.resolve(root, candidate);
+        const absolute = existsSync(fromRoot) ? fromRoot : path.resolve(cwd, candidate);
+        const relative = path.relative(root, absolute).split(path.sep).join("/");
+        if (!existsSync(absolute) || relative.startsWith("..") || path.isAbsolute(relative)) {
+            missing.push(candidate);
+            continue;
+        }
+        if (relative === "" || resolved.some((entry) => entry.path === relative))
+            continue;
+        resolved.push({ path: relative, isFile: statSync(absolute).isFile() });
+    }
+    return { resolved, missing };
+}
+export function resolveObjects(objects, text, identifiers, pathSites) {
+    const lowered = new Set(identifiers.map((term) => term.toLowerCase()));
+    const ranked = [];
+    objects.forEach((object, order) => {
+        const via = [];
+        for (const site of pathSites) {
+            if (object.tables.includes(site.table)) {
+                const entry = `path ${site.path} (writes ${site.table} at line ${site.line})`;
+                if (!via.some((existing) => existing.startsWith(`path ${site.path} `)))
+                    via.push(entry);
+            }
+        }
+        for (const table of object.tables) {
+            if (lowered.has(table.toLowerCase()) || mentions(text, table))
+                via.push(`table ${table}`);
+        }
+        if (mentions(text, object.name))
+            via.push(`name "${object.name}"`);
+        for (const alias of object.aliases) {
+            if (alias.toLowerCase() !== object.name.toLowerCase() && mentions(text, alias))
+                via.push(`alias "${alias}"`);
+        }
+        if (via.length > 0)
+            ranked.push({ object, via, order });
+    });
+    ranked.sort((left, right) => right.via.length - left.via.length || left.order - right.order);
+    return ranked.slice(0, CONTEXT_MAX_OBJECTS).map(({ object, via }) => ({ object, via }));
+}
+export function isRegisterTerm(objects, term) {
+    return objects.some((object) => [object.name, ...object.aliases, ...object.tables].some((name) => mentions(term, name) && mentions(name, term)));
+}

package/dist/lib/context/writers.js

@@ -0,0 +1,58 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+export const WRITE_SITE_CANDIDATE_FILES = 20;
+export function camelCaseOf(table) {
+    return table.replace(/[_-]+([a-z0-9])/g, (_match, letter) => letter.toUpperCase());
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+export function tableSymbols(table, graph) {
+    const camel = camelCaseOf(table);
+    const candidates = camel === table ? [table] : [camel, table];
+    if (graph === null)
+        return [camel];
+    const confirmed = candidates.find((symbol) => graph.isDefined(symbol) || graph.importers(symbol, 1).length > 0);
+    return confirmed === undefined ? [] : [confirmed];
+}
+export function writePatterns(table, symbols) {
+    const patterns = symbols.map((symbol) => new RegExp(`\\.(insert|update|delete)\\(\\s*(?:\\w+\\.)?${escapeRegExp(symbol)}\\b`));
+    patterns.push(new RegExp(`(INSERT\\s+INTO|UPDATE|DELETE\\s+FROM)\\s+["'\`]?${escapeRegExp(table)}\\b`));
+    return patterns;
+}
+function verbOf(match) {
+    const lowered = match.toLowerCase();
+    if (lowered.includes("insert"))
+        return "insert";
+    if (lowered.includes("delete"))
+        return "delete";
+    return "update";
+}
+export function scanWriteSites(root, files, table, symbols) {
+    const patterns = writePatterns(table, symbols);
+    const sites = [];
+    for (const file of [...new Set(files)]) {
+        let text;
+        try {
+            text = readFileSync(path.join(root, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        text.split("\n").forEach((line, index) => {
+            for (const pattern of patterns) {
+                const match = pattern.exec(line);
+                if (match !== null) {
+                    sites.push({ path: file, line: index + 1, verb: verbOf(match[1] ?? ""), table });
+                    break;
+                }
+            }
+        });
+    }
+    return sites;
+}
+export function findWriteSites(root, table, graph, scrutinised = []) {
+    const symbols = tableSymbols(table, graph);
+    const candidates = graph === null || symbols.length === 0 ? [] : graph.importers(symbols[0] ?? table, WRITE_SITE_CANDIDATE_FILES);
+    return scanWriteSites(root, [...candidates, ...scrutinised], table, graph === null ? [camelCaseOf(table)] : symbols);
+}

package/dist/lib/gate/readGate.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { performance } from "node:perf_hooks";
 import { assessBashRead, classifyBashRead } from "./bashRead.js";
 import { assessFullRead, readLeadingLines, regularFileSize, tokensOfLength } from "./estimate.js";
+import { assessRedirect, redirectHandler } from "./redirect.js";
 import { GATE_MIN_THRESHOLD_TOKENS, isGateOff, resolveThreshold } from "./settings.js";
 export class GateInputError extends Error {
     code = "HOOK_INPUT_INVALID";
@@ -26,7 +27,7 @@ function realPathOf(file) {
         return file;
     }
 }
-export async function gateReadCall(call, env = process.env) {
+export async function gateReadCall(call, env = process.env, deps = {}) {
     if (isGateOff(env))
         return PASS;
     const filePath = call.toolInput.file_path;
@@ -35,8 +36,12 @@ export async function gateReadCall(call, env = process.env) {
     if (call.toolInput.offset != null || call.toolInput.limit != null)
         return PASS;
     const resolved = resolvePath(call.cwd, filePath);
+    const redirect = await assessRedirect(resolved, call.cwd, env, deps);
     const assessment = assessFullRead(resolved, () => resolveThreshold(env).thresholdTokens, GATE_MIN_THRESHOLD_TOKENS);
-    return answerAssessment(call, resolved, assessment, "read");
+    if (assessment.decision === "gate" || !redirect.isRedirect)
+        return answerAssessment(call, resolved, assessment, "read");
+    const { LABEL_ROW_HANDLERS } = await import("../local_store/routing.js");
+    return answerLargeRead(call, resolved, redirect.estimatedTokens, "read", redirectHandler(LABEL_ROW_HANDLERS));
 }
 export async function gateBashCall(call, env = process.env) {
     if (isGateOff(env))
@@ -56,7 +61,7 @@ async function answerAssessment(call, resolved, assessment, tool) {
         return PASS;
     return answerLargeRead(call, resolved, assessment.estimatedTokens, tool);
 }
-async function answerLargeRead(call, resolved, estimatedTokens, tool) {
+async function answerLargeRead(call, resolved, estimatedTokens, tool, deniedHandler = "outline") {
     const [{ openLocalStore, withTransaction }, routing, outline] = await Promise.all([
         import("../local_store/database.js"),
         import("../local_store/routing.js"),
@@ -84,7 +89,7 @@ async function answerLargeRead(call, resolved, estimatedTokens, tool) {
                 path: realPath,
                 estimated_tokens: estimatedTokens,
                 returned_tokens: returnedTokens,
-                handler: isInserted ? "outline" : "bypass",
+                handler: isInserted ? deniedHandler : "bypass",
                 check_result: null,
                 bypass_used: isInserted ? 0 : 1,
                 latency_ms: Math.max(0, Math.round(performance.now() - call.startedAt)),

package/dist/lib/gate/redirect.js

@@ -0,0 +1,61 @@
+import { statSync } from "node:fs";
+import path from "node:path";
+import { relativeToRoot, resolveProjectRoot } from "../graph/projectRoot.js";
+import { estimateReadTokens, isSkippedExtension, readLeadingLines, READ_DEFAULT_LINE_LIMIT, regularFileSize } from "./estimate.js";
+export const REDIRECT_MIN_LINES = 350;
+export const REDIRECT_RULE_PATH = path.join(".claude", "rules", "large-read-redirect.md");
+export const NUSTACK_READ_REDIRECT_ENV = "NUSTACK_READ_REDIRECT";
+export function isRedirectOn(root, env = process.env) {
+    const override = env[NUSTACK_READ_REDIRECT_ENV];
+    if (override === "on" || override === "off")
+        return { isOn: override === "on", source: "env" };
+    if (root === null)
+        return { isOn: false, source: "absent" };
+    try {
+        return statSync(path.join(root, REDIRECT_RULE_PATH)).isFile() ? { isOn: true, source: "rule" } : { isOn: false, source: "absent" };
+    }
+    catch {
+        return { isOn: false, source: "absent" };
+    }
+}
+export function redirectHandler(handlers) {
+    return handlers.includes("redirect") ? "redirect" : "outline";
+}
+const NO_REDIRECT = { isRedirect: false };
+async function defaultLoader() {
+    const { loadCodegraph } = await import("../graph/library.js");
+    return loadCodegraph();
+}
+export async function assessRedirect(file, cwd, env = process.env, deps = {}) {
+    try {
+        const size = regularFileSize(file);
+        if (size === null || size < REDIRECT_MIN_LINES + 1 || isSkippedExtension(file))
+            return NO_REDIRECT;
+        const root = resolveProjectRoot(env.CLAUDE_PROJECT_DIR, cwd);
+        if (root === null || !isRedirectOn(root, env).isOn)
+            return NO_REDIRECT;
+        const head = readLeadingLines(file, REDIRECT_MIN_LINES + 1);
+        if (head.isBinary || head.lines <= REDIRECT_MIN_LINES)
+            return NO_REDIRECT;
+        const relPath = relativeToRoot(root, file, cwd);
+        if (relPath === null)
+            return NO_REDIRECT;
+        const library = await (deps.loadLibrary ?? defaultLoader)();
+        if (typeof library.openReadOnly !== "function" || typeof library.indexedFile !== "function")
+            return NO_REDIRECT;
+        const db = library.openReadOnly(root);
+        if (db === null)
+            return NO_REDIRECT;
+        try {
+            if (library.indexedFile(db, relPath) === null)
+                return NO_REDIRECT;
+        }
+        finally {
+            db.close();
+        }
+        return { isRedirect: true, estimatedTokens: estimateReadTokens(readLeadingLines(file, READ_DEFAULT_LINE_LIMIT)) };
+    }
+    catch {
+        return NO_REDIRECT;
+    }
+}

package/dist/lib/graph/projectRoot.js

@@ -0,0 +1,39 @@
+import { existsSync, realpathSync } from "node:fs";
+import path from "node:path";
+function startOf(projectDir, cwd) {
+    if (projectDir !== undefined && projectDir.trim() !== "")
+        return projectDir;
+    if (cwd !== undefined && cwd.trim() !== "")
+        return cwd;
+    return process.cwd();
+}
+export function resolveProjectRoot(projectDir, cwd) {
+    let current;
+    try {
+        current = realpathSync(startOf(projectDir, cwd));
+    }
+    catch {
+        return null;
+    }
+    for (;;) {
+        if (existsSync(path.join(current, ".git")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+export function relativeToRoot(root, file, base = root) {
+    let real;
+    try {
+        real = realpathSync(path.isAbsolute(file) ? file : path.resolve(base, file));
+    }
+    catch {
+        return null;
+    }
+    const relative = path.relative(root, real);
+    if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative))
+        return null;
+    return relative.split(path.sep).join("/");
+}

package/dist/lib/local_store/paths.js

@@ -19,6 +19,9 @@ export function desktopSettingsPath() {
 export function cacheDir() {
     return path.join(nustackHomeDir(), "cache");
 }
+export function contextMarkersDir() {
+    return path.join(cacheDir(), "context");
+}
 export function sessionEventsDir() {
     return path.join(nustackHomeDir(), "session-events");
 }

package/dist/program.js

@@ -8,6 +8,7 @@ import { runSync } from "./commands/sync.js";
 import { runDescribe } from "./commands/describe.js";
 import { runValidate } from "./commands/validate.js";
 import { runGraph } from "./commands/graph.js";
+import { runContext } from "./commands/context.js";
 import { runLogscope } from "./commands/logscope.js";
 import { runDoctor } from "./commands/doctor.js";
 import { runTokenCreate, runTokenList, runTokenRevoke } from "./commands/token.js";
@@ -116,6 +117,16 @@ program
     .allowUnknownOption()
     .allowExcessArguments()
     .action(async (_fn, _args, options) => runGraph(process.argv, options));
+program
+    .command("context [text...]")
+    .description("Resolve task text, paths or a diff to register objects and print the context pack")
+    .option("--path <p>", "a path the task touches (repeatable)", (value, previous = []) => [...previous, value])
+    .option("--diff <fileOrDash>", "a unified diff whose files the task touches; - reads stdin")
+    .option("--json", "emit the versioned machine envelope")
+    .option("--no-refresh", "answer from the code-graph index as it stands, however old")
+    .option("--budget <tokens>", "the pack's token cap (default 2500)")
+    .option("--hook", "Claude Code hook entry for UserPromptSubmit, PostToolUse and SessionStart (reads stdin)")
+    .action(async (text, options) => runContext(text, options));
 program
     .command("logscope [fn] [args...]")
     .description("Log tracking: ask this machine's log corpus a question, or `index` / `corpora` / `allow` / `prune`")
@@ -253,11 +264,14 @@ registerRecordsCommands(program.command("records").description("Emit, send and l
 registerRecordAliases(program, () => program.opts());
 const LOCAL_ONLY_COMMANDS = ["census", "check"];
 const UNDRAINED_GROUPS = ["records", "gate", "session", "read", "lane", ...RECORD_ALIAS_GROUPS];
+const HOOK_PATH_COMMANDS = ["context"];
 program.hook("preAction", async (_program, action) => {
     if (program.opts().nonInteractive)
         process.env[NON_INTERACTIVE_VARIABLE] = "1";
     if (action.parent === program && LOCAL_ONLY_COMMANDS.includes(action.name()))
         return;
+    if (action.parent === program && HOOK_PATH_COMMANDS.includes(action.name()))
+        return;
     const group = action.parent?.name() ?? "";
     if (!UNDRAINED_GROUPS.includes(group))
         await startDrainIfDue(program.opts());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nurix/nustack",
-  "version": "0.23.20",
+  "version": "0.23.22",
   "description": "The nustack CLI — bootstrap NuStack services into a repo via the NuStack discovery plane.",
   "type": "module",
   "private": false,
@@ -34,10 +34,10 @@
     "@types/node": "^22.19.20",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
+    "@nurix/contracts": "2.0.2",
     "@nurix/harness": "0.0.0",
     "@nurix/nustack.studio": "0.0.0",
-    "@nurix/nustack.ui": "0.0.0",
-    "@nurix/contracts": "2.0.2"
+    "@nurix/nustack.ui": "0.0.0"
   },
   "publishConfig": {
     "access": "public"