@nexrall/code-core 1.4.71 → 1.4.73

package/dist/agent/nestedInstructions.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Caps: discovered files ride the system prompt on EVERY request of the session, so a
+ * pathological (or hostile, from a cloned repo) subdirectory file must not be able to
+ * crowd out the real project brief. Truncation is visible; the same pattern as the
+ * MCP-instructions caps.
+ */
+export declare const NESTED_INSTRUCTIONS_PER_FILE = 4000;
+export declare const NESTED_INSTRUCTIONS_TOTAL = 12000;
+/**
+ * The InstructionsLoaded `load_reason` a file is announced with — CC's own vocabulary.
+ * `session_start`: loaded up front (root unconditional rules). `nested_traversal`: a
+ * directory the agent worked in carries the file. `path_glob_match`: a `paths:`-scoped
+ * rule matched a touched path.
+ */
+export type InstructionLoadReason = 'nested_traversal' | 'path_glob_match' | 'session_start';
+/** One discovered instruction file, as loaded. */
+export interface NestedInstruction {
+    /** Absolute path of the instruction file. */
+    filePath: string;
+    /** Project-relative path, `/`-separated (e.g. `src/foo/nexrall.md`) — the label the prompt shows. */
+    relPath: string;
+    /** Instruction text (frontmatter stripped for rules). Trimmed. Replaced in place by refresh(). */
+    content: string;
+    /** Subdirectory brief (`nexrall.md`) or rule file (`.nexrall/rules/*.md`) — the prompt label. */
+    kind: 'brief' | 'rule';
+    /** Why this file entered context — what the InstructionsLoaded hook reports. */
+    loadReason: InstructionLoadReason;
+}
+/**
+ * Compile one `paths:` glob to an anchored RegExp over project-relative POSIX paths,
+ * or null when the pattern is empty / fails to compile (callers treat null as
+ * non-matching). Compiled once per pattern string, cached for the process.
+ */
+export declare function pathGlobToRegExp(pattern: string): RegExp | null;
+/**
+ * Read the `paths:` (alias `globs:`) frontmatter of a rule file. Returns null when
+ * there is no frontmatter, the key is absent, or it lists nothing — all of which mean
+ * UNCONDITIONAL. Accepts the three shapes CC's docs and real files use: a block list
+ * (`paths:\n  - glob`), a comma-separated string, and a flow list (`["a", "b"]`).
+ * Only top-level keys count — an indented `paths:` inside a nested map is that map's
+ * field, the same isolation util/frontmatter applies.
+ */
+export declare function extractPathGlobs(raw: string): string[] | null;
+/**
+ * Discovers `nexrall.md` briefs and `.nexrall/rules` files as the agent works (see the
+ * section comment above). Stateful across calls by design — the loaded set IS the
+ * feature (and the callback dedupe), so the host that owns a session keeps ONE
+ * instance and passes it to every run.
+ */
+export declare class NestedInstructionScanner {
+    private readonly workDir;
+    private readonly loaded;
+    private readonly ignored;
+    /** dir → the real on-disk path of its brief (casing resolved once, on the first hit). */
+    private readonly resolved;
+    /** rule file → parsed metadata: globs (null = unconditional) + frontmatter-stripped body. */
+    private readonly ruleMeta;
+    /** Root unconditional rules load once per session state; refresh() re-arms. */
+    private rootInitialized;
+    constructor(workDir: string);
+    /**
+     * Load the root's unconditional rules and return them — the HOST calls this at
+     * session start so they are announced with `session_start` alongside the brief and
+     * memory. A host that skips it still gets the rules from the first `list()`; it
+     * just has no announcement to make.
+     */
+    initialRules(): NestedInstruction[];
+    /**
+     * Scan the tool input of one call for filesystem paths and return the instruction
+     * files this call loaded (usually none). A failed tool call still scans: intent
+     * marks the area even when the file itself was missing.
+     */
+    scanInput(input: Record<string, unknown>): NestedInstruction[];
+    /** Scan the ancestor chain of one touched path; returns the files newly loaded by this call. */
+    scanPath(touched: string): NestedInstruction[];
+    /** Everything loaded so far, parent-first — what the prompt renders. */
+    list(): NestedInstruction[];
+    /**
+     * Re-read every loaded file from disk; files that no longer exist are dropped.
+     * The `/reload` escape hatch for content edits — returns how many entries changed
+     * or vanished, so a caller can report it (0 = nothing to say). Root rules are
+     * re-listed, so an unconditional rule file created since the session started (or
+     * one whose frontmatter lost its `paths:`) joins here; new path-scoped files load
+     * on their next matching touch.
+     */
+    refresh(): number;
+    /** Root unconditional rules: root listing once per session state, `session_start`. */
+    private ensureRootRules;
+    /** Root path-scoped rules matching this touch ('path_glob_match'). */
+    private scanRootRulesFor;
+    /**
+     * Rules a directory carries (`<dir>/.nexrall/rules`): unconditional ones load with
+     * the touch (`nested_traversal` — the same timing as that directory's brief);
+     * path-scoped ones load when this touch matches (`path_glob_match`).
+     */
+    private scanRulesDir;
+    /**
+     * Load one rule file if it should be — dedupe, parse, scope decision. `fallbackReason`
+     * is the reason an UNCONDITIONAL rule loads with; `relTouched` (null = no touch yet)
+     * is what path-scoped globs are tested against. Returns the new entry or null.
+     */
+    private loadRule;
+    /** Parsed metadata for a rule file, cached until refresh(). */
+    private ruleMetaOf;
+    /**
+     * The instruction file a directory carries, or null. A directory WITHOUT one is
+     * re-checked on every touch (see the header), so a file created after the first scan
+     * is still found; a directory WITH one is resolved once — the ledger keeps its
+     * content, and deletion is `refresh()`'s business.
+     */
+    private checkDir;
+}
+/**
+ * Render the discovered-instructions block, or null when there is nothing to inject —
+ * callers join the result with the project brief, and a null must not leave an empty
+ * section behind. Parent-first order makes a deeper file (the more specific one) read
+ * as the refinement of its ancestors, which is also how Claude Code orders nested
+ * CLAUDE.md context. Rules carry their own label so a file like `.nexrall/rules/x.md`
+ * is not mistaken for a subdirectory brief.
+ */
+export declare function formatNestedInstructions(files: NestedInstruction[]): string | null;
+//# sourceMappingURL=nestedInstructions.d.ts.map

package/dist/agent/nestedInstructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nestedInstructions.d.ts","sourceRoot":"","sources":["../../src/agent/nestedInstructions.ts"],"names":[],"mappings":"AAgDA;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAC;AACjD,eAAO,MAAM,yBAAyB,QAAQ,CAAC;AAY/C;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,kBAAkB,GAAG,iBAAiB,GAAG,eAAe,CAAC;AAE7F,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,qGAAqG;IACrG,OAAO,EAAE,MAAM,CAAC;IAChB,kGAAkG;IAClG,OAAO,EAAE,MAAM,CAAC;IAChB,iGAAiG;IACjG,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,gFAAgF;IAChF,UAAU,EAAE,qBAAqB,CAAC;CACnC;AAwJD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAa/D;AAmBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAuB7D;AA2DD;;;;;GAKG;AACH,qBAAa,wBAAwB;IAUvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IATpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,yFAAyF;IACzF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqE;IAC9F,+EAA+E;IAC/E,OAAO,CAAC,eAAe,CAAS;gBAEH,OAAO,EAAE,MAAM;IAE5C;;;;;OAKG;IACH,YAAY,IAAI,iBAAiB,EAAE;IAInC;;;;OAIG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,EAAE;IAU9D,gGAAgG;IAChG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,EAAE;IAiD9C,wEAAwE;IACxE,IAAI,IAAI,iBAAiB,EAAE;IAK3B;;;;;;;OAOG;IACH,OAAO,IAAI,MAAM;IAwBjB,sFAAsF;IACtF,OAAO,CAAC,eAAe;IAWvB,sEAAsE;IACtE,OAAO,CAAC,gBAAgB;IAYxB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IASpB;;;;OAIG;IACH,OAAO,CAAC,QAAQ;IAwBhB,+DAA+D;IAC/D,OAAO,CAAC,UAAU;IAkBlB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;CAkBjB;AAqBD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,MAAM,GAAG,IAAI,CAqBlF"}