@nanonets/graft 0.15.0 → 0.18.0

package/dist/brain/attach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../src/brain/attach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0CAA0C;AAC1C,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAAE,EAClB,KAAK,EAAE,SAAS,EAAE,EAClB,KAAK,EAAE,OAAO,GAAG,IAAI,GACpB,WAAW,EAAE,CA+Bf;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,EAAE,CAS5D"}

package/dist/brain/attach.js

@@ -0,0 +1,63 @@
+/** Most rules to attach to one answer. */
+export const MAX_ATTACHED_RULES = 6;
+/**
+ * The rules governing the symbols in `pointers`, resolved against `graph`.
+ *
+ * Scoped to the answer, not the repo: attaching every rule a brain holds would
+ * turn a token-saving pack into a token-spending one, and `ask` prints the
+ * saving it claims. Capped for the same reason.
+ */
+export function rulesForPointers(pointers, rules, graph) {
+    if (!rules.length || !graph)
+        return [];
+    // node id → its current pointer and body hash. One pass over the graph; the
+    // caller does this once per ask, not once per hit.
+    const byId = new Map();
+    for (const n of graph.nodes) {
+        byId.set(n.id, { pointer: `${n.path}:${n.span}`, hash: n.body_hash });
+    }
+    const wanted = new Set(pointers);
+    const out = [];
+    const seen = new Set();
+    for (const r of rules) {
+        const node = byId.get(r.symbol);
+        if (!node || !wanted.has(node.pointer))
+            continue;
+        // The same rule can be mined against two symbols in one answer; show it once.
+        if (seen.has(r.rule))
+            continue;
+        seen.add(r.rule);
+        out.push({
+            rule: r.rule,
+            pointer: node.pointer,
+            // No recorded fingerprint means the rule was mined before hashing existed
+            // (or against a symbol graft could not hash). Unknown is not stale: a
+            // false "the code moved" is worse than saying nothing about freshness.
+            stale: r.fingerprint !== '' && r.fingerprint !== node.hash,
+            sourceUrl: r.sourceUrl,
+        });
+        if (out.length === MAX_ATTACHED_RULES)
+            break;
+    }
+    return out;
+}
+/**
+ * Render the rules block appended to an `ask` pack.
+ *
+ * Deliberately terse. This rides along on every answer, so it has to earn its
+ * tokens: one line per rule, the pointer it governs, and a link only when there
+ * is one. The `[graft]` prefix is avoided — `sumSavingsFooters` scans for
+ * `[graft] tokens saved ≈` and nothing here should look like a savings line.
+ */
+export function formatRules(applied) {
+    if (!applied.length)
+        return [];
+    const lines = ['', 'rules that govern these symbols'];
+    for (const a of applied) {
+        const flag = a.stale ? ' (STALE — the code changed since this was decided)' : '';
+        lines.push(`- ${a.rule}${flag}`);
+        lines.push(`  ${a.pointer}${a.sourceUrl ? ` · ${a.sourceUrl}` : ''}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=attach.js.map

package/dist/brain/attach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.js","sourceRoot":"","sources":["../../src/brain/attach.ts"],"names":[],"mappings":"AA0BA,0CAA0C;AAC1C,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAkB,EAClB,KAAkB,EAClB,KAAqB;IAErB,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IAEvC,4EAA4E;IAC5E,mDAAmD;IACnD,MAAM,IAAI,GAAG,IAAI,GAAG,EAA6C,CAAC;IAClE,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;QAC5B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IACjC,MAAM,GAAG,GAAkB,EAAE,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,SAAS;QACjD,8EAA8E;QAC9E,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,SAAS;QAC/B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACjB,GAAG,CAAC,IAAI,CAAC;YACP,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,0EAA0E;YAC1E,sEAAsE;YACtE,uEAAuE;YACvE,KAAK,EAAE,CAAC,CAAC,WAAW,KAAK,EAAE,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,CAAC,IAAI;YAC1D,SAAS,EAAE,CAAC,CAAC,SAAS;SACvB,CAAC,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,KAAK,kBAAkB;YAAE,MAAM;IAC/C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAAsB;IAChD,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,CAAC,EAAE,EAAE,iCAAiC,CAAC,CAAC;IACtD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,oDAAoD,CAAC,CAAC,CAAC,EAAE,CAAC;QACjF,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,IAAI,EAAE,CAAC,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/brain/connect.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The one command a user runs to attach a brain: parse the handoff value,
+ * store the link, pull the rules, write them into the agent files.
+ */
+import { type BrainLink, type BrainRule } from './link.js';
+import { type BrainWrite } from './wire.js';
+/**
+ * Parse the `--brain` value.
+ *
+ * The onboarding page hands over one string so there is one thing to copy. Two
+ * accepted shapes:
+ *
+ *   `<brainId>:<token>`  — the normal case, both halves in one paste
+ *   `<brainId>`          — with the token in `GRAFT_BRAIN_TOKEN`, for CI, where
+ *                          a secret must not appear in a command line
+ *
+ * A bare token with no brain id is rejected rather than guessed: pointing the
+ * wrong brain at a repo would write another team's rules into it.
+ */
+export declare function parseBrainArg(value: string): BrainLink | {
+    error: string;
+};
+/** What connecting a brain did, for the caller to print. */
+export interface ConnectResult {
+    linked: boolean;
+    ruleCount: number;
+    writes: BrainWrite[];
+    /** Set when the rules could not be fetched; the link is still stored. */
+    warning?: string;
+}
+/**
+ * Store the link, pull the rules once, and write them into the agent files.
+ *
+ * The link is stored even when the pull fails. That is deliberate: a token
+ * typed correctly against a brain that is momentarily unreachable should not
+ * have to be pasted again — `graft brain pull` retries, and `ask` degrades to
+ * the code-only answer meanwhile.
+ */
+export declare function connectBrain(repo: string, link: BrainLink, opts?: {
+    home: string;
+    ids?: string[];
+    fetchImpl?: typeof fetch;
+}): Promise<ConnectResult>;
+/**
+ * Re-pull the rules for an already-linked repo and rewrite the agent files.
+ * Returns null when the repo has no brain linked.
+ */
+export declare function pullBrain(repo: string, opts: {
+    home: string;
+    ids?: string[];
+    fetchImpl?: typeof fetch;
+}): Promise<ConnectResult | null>;
+/** The linked brain and its cached rule set, for `graft brain status`. */
+export declare function brainStatus(repo: string): {
+    link: BrainLink | null;
+    rules: BrainRule[];
+    fetchedAt: number | null;
+};
+//# sourceMappingURL=connect.d.ts.map

package/dist/brain/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/brain/connect.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAML,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAGhE;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAkB1E;AAED,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,EACf,IAAI,GAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAiB,GAC9E,OAAO,CAAC,aAAa,CAAC,CAexB;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAE,GAC/D,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAI/B;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG;IACzC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAIA"}

package/dist/brain/connect.js

@@ -0,0 +1,80 @@
+/**
+ * The one command a user runs to attach a brain: parse the handoff value,
+ * store the link, pull the rules, write them into the agent files.
+ */
+import { readLink, writeLink, fetchRules, writeRulesCache, readRulesCache, } from './link.js';
+import { writeBrainSections } from './wire.js';
+import { basename } from 'node:path';
+/**
+ * Parse the `--brain` value.
+ *
+ * The onboarding page hands over one string so there is one thing to copy. Two
+ * accepted shapes:
+ *
+ *   `<brainId>:<token>`  — the normal case, both halves in one paste
+ *   `<brainId>`          — with the token in `GRAFT_BRAIN_TOKEN`, for CI, where
+ *                          a secret must not appear in a command line
+ *
+ * A bare token with no brain id is rejected rather than guessed: pointing the
+ * wrong brain at a repo would write another team's rules into it.
+ */
+export function parseBrainArg(value) {
+    const raw = value.trim();
+    if (!raw)
+        return { error: 'empty --brain value' };
+    const cut = raw.indexOf(':');
+    if (cut > 0) {
+        const brainId = raw.slice(0, cut).trim();
+        const token = raw.slice(cut + 1).trim();
+        if (!brainId || !token)
+            return { error: 'expected --brain <brainId>:<token>' };
+        return { brainId, token };
+    }
+    const envToken = process.env.GRAFT_BRAIN_TOKEN;
+    if (!envToken) {
+        return {
+            error: 'expected --brain <brainId>:<token>, or a bare brain id with the token in GRAFT_BRAIN_TOKEN',
+        };
+    }
+    return { brainId: raw, token: envToken };
+}
+/**
+ * Store the link, pull the rules once, and write them into the agent files.
+ *
+ * The link is stored even when the pull fails. That is deliberate: a token
+ * typed correctly against a brain that is momentarily unreachable should not
+ * have to be pasted again — `graft brain pull` retries, and `ask` degrades to
+ * the code-only answer meanwhile.
+ */
+export async function connectBrain(repo, link, opts = { home: '' }) {
+    writeLink(repo, link);
+    const rules = await fetchRules(link, opts.fetchImpl ?? fetch);
+    if (rules === null) {
+        return {
+            linked: true,
+            ruleCount: 0,
+            writes: [],
+            warning: 'could not reach the brain to pull its rules — the link is saved; run `graft brain pull` to retry',
+        };
+    }
+    writeRulesCache(repo, { brainId: link.brainId, fetchedAt: Date.now(), rules });
+    const writes = writeBrainSections(repo, opts.home, rules, basename(repo), opts.ids);
+    return { linked: true, ruleCount: rules.length, writes };
+}
+/**
+ * Re-pull the rules for an already-linked repo and rewrite the agent files.
+ * Returns null when the repo has no brain linked.
+ */
+export async function pullBrain(repo, opts) {
+    const link = readLink(repo);
+    if (!link)
+        return null;
+    return connectBrain(repo, link, opts);
+}
+/** The linked brain and its cached rule set, for `graft brain status`. */
+export function brainStatus(repo) {
+    const link = readLink(repo);
+    const cache = readRulesCache(repo);
+    return { link, rules: cache?.rules ?? [], fetchedAt: cache?.fetchedAt ?? null };
+}
+//# sourceMappingURL=connect.js.map

package/dist/brain/connect.js.map

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

package/dist/brain/link.d.ts

@@ -0,0 +1,82 @@
+/** How long a cached rule set is served before upkeep refreshes it. */
+export declare const RULES_TTL_MS: number;
+/**
+ * The TTL used while the cache holds NO rules.
+ *
+ * A brain is connected during onboarding while it is still being mined, so the
+ * first pull legitimately returns nothing. Six hours of that is the difference
+ * between the feature working and the user concluding it does not: they wired
+ * graft up, got an empty rulebook, and nothing would go back for the real one
+ * until tomorrow. Two minutes costs one cheap request per session until the
+ * rules land, and then the normal TTL takes over.
+ */
+export declare const EMPTY_RULES_TTL_MS: number;
+/** One rule from the brain, anchored to a symbol in this repo. */
+export interface BrainRule {
+    ruleId: string;
+    /** A graft node id: `<path>#<QualifiedName>`. */
+    symbol: string;
+    /** The symbol's body hash when the rule was mined; '' when unrecorded. */
+    fingerprint: string;
+    rule: string;
+    /** Deep link to the commit or pull request that established it. */
+    sourceUrl?: string;
+}
+/** The cached rule set, as stored under the repo's graft cache. */
+export interface RulesCache {
+    brainId: string;
+    fetchedAt: number;
+    rules: BrainRule[];
+    /** When a refresh was last ATTEMPTED, successful or not. Separate from
+     * `fetchedAt`, which records when rules last actually arrived: without the
+     * distinction, a brain that is still building would be re-checked on every
+     * single command, because its `fetchedAt` never advances. */
+    checkedAt?: number;
+}
+/** The persisted brain link. */
+export interface BrainLink {
+    brainId: string;
+    /** Workspace API key (`nn...`). Stored in the git-ignored `.graft/`. */
+    token: string;
+    /** Set only when the user pointed graft at a non-default host. */
+    baseUrl?: string;
+}
+/**
+ * The link for repo `dir`, or null when it has none.
+ *
+ * `GRAFT_BRAIN_TOKEN` / `GRAFT_BRAIN_ID` override the stored pair, so CI can
+ * attach a brain without writing to the checkout.
+ */
+export declare function readLink(dir: string): BrainLink | null;
+/** Persist the link for repo `dir`, merging into any existing build config. */
+export declare function writeLink(dir: string, link: BrainLink): void;
+/** Forget the link for repo `dir`. Leaves the cached rules for `uninstall` to remove. */
+export declare function clearLink(dir: string): void;
+/** Where the rule cache lives: beside the graph, since it is derived data. */
+export declare function rulesCachePath(dir: string): string;
+export declare function readRulesCache(dir: string): RulesCache | null;
+export declare function writeRulesCache(dir: string, cache: RulesCache): void;
+/**
+ * Whether a cached set is old enough to refetch.
+ *
+ * Keyed off the last ATTEMPT, not the last success, and with a much shorter
+ * window while the cache is empty — see EMPTY_RULES_TTL_MS for why that case
+ * is the one that matters.
+ */
+export declare function cacheIsStale(cache: RulesCache | null, now?: number): boolean;
+/** Record that a refresh was attempted, without claiming rules arrived. */
+export declare function markRulesChecked(dir: string, now?: number): void;
+/**
+ * The base URL for a link, honouring the env override first so a misconfigured
+ * stored value can always be corrected without editing a file.
+ */
+export declare function baseUrlFor(link: BrainLink): string;
+/**
+ * Fetch the brain's symbol-anchored rules.
+ *
+ * Returns null on any failure — an unreachable brain, a revoked token, a
+ * malformed body. Never throws: `ask` degrades to the code-only answer it gave
+ * before a brain was attached, which is the whole reason the cache exists.
+ */
+export declare function fetchRules(link: BrainLink, fetchImpl?: typeof fetch): Promise<BrainRule[] | null>;
+//# sourceMappingURL=link.d.ts.map

package/dist/brain/link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/brain/link.ts"],"names":[],"mappings":"AAoBA,uEAAuE;AACvE,eAAO,MAAM,YAAY,QAAqB,CAAC;AAE/C;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAAgB,CAAC;AAEhD,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;;iEAG6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,gCAAgC;AAChC,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAStD;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,CAE5D;AAED,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAE7D;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAEpE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,EAAE,GAAG,SAAa,GAAG,OAAO,CAIhF;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,IAAI,CAIpE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAElD;AAeD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,EACf,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CA4B7B"}

package/dist/brain/link.js

@@ -0,0 +1,136 @@
+/**
+ * The link between a repo's graft graph and a Trail brain.
+ *
+ * A brain holds the rules mined out of this repository's history — what the
+ * team decided and why, which the code graph cannot see. Graft holds the code
+ * and can say which symbols an answer touches. This module is the join: the
+ * token identifying the brain, and the rules cached beside it so `ask` never
+ * waits on the network.
+ *
+ * The link lives in the per-repo, git-ignored `.graft/config.json`, next to the
+ * other persisted build choices. Not in `~/.graft/`: a brain belongs to one
+ * repository, and two checkouts of different repos on one machine must not
+ * share one.
+ */
+import { readBuildConfig, patchBuildConfig, cacheDir, readJson, writeJsonAtomic } from '../util/state.js';
+import { join } from 'node:path';
+/** Default API host. Overridden by GRAFT_BRAIN_URL, for staging and self-hosted. */
+const DEFAULT_BRAIN_BASE_URL = 'https://agents.nanonets.com';
+/** How long a cached rule set is served before upkeep refreshes it. */
+export const RULES_TTL_MS = 6 * 60 * 60 * 1000; // 6 hours
+/**
+ * The TTL used while the cache holds NO rules.
+ *
+ * A brain is connected during onboarding while it is still being mined, so the
+ * first pull legitimately returns nothing. Six hours of that is the difference
+ * between the feature working and the user concluding it does not: they wired
+ * graft up, got an empty rulebook, and nothing would go back for the real one
+ * until tomorrow. Two minutes costs one cheap request per session until the
+ * rules land, and then the normal TTL takes over.
+ */
+export const EMPTY_RULES_TTL_MS = 2 * 60 * 1000;
+/**
+ * The link for repo `dir`, or null when it has none.
+ *
+ * `GRAFT_BRAIN_TOKEN` / `GRAFT_BRAIN_ID` override the stored pair, so CI can
+ * attach a brain without writing to the checkout.
+ */
+export function readLink(dir) {
+    const envToken = process.env.GRAFT_BRAIN_TOKEN;
+    const envBrain = process.env.GRAFT_BRAIN_ID;
+    if (envToken && envBrain) {
+        return { brainId: envBrain, token: envToken, baseUrl: process.env.GRAFT_BRAIN_URL };
+    }
+    const stored = readBuildConfig(dir)?.brain;
+    if (!stored?.brainId || !stored?.token)
+        return null;
+    return stored;
+}
+/** Persist the link for repo `dir`, merging into any existing build config. */
+export function writeLink(dir, link) {
+    patchBuildConfig(dir, { brain: link });
+}
+/** Forget the link for repo `dir`. Leaves the cached rules for `uninstall` to remove. */
+export function clearLink(dir) {
+    patchBuildConfig(dir, { brain: undefined });
+}
+/** Where the rule cache lives: beside the graph, since it is derived data. */
+export function rulesCachePath(dir) {
+    return join(cacheDir(dir), 'brain-rules.json');
+}
+export function readRulesCache(dir) {
+    return readJson(rulesCachePath(dir));
+}
+export function writeRulesCache(dir, cache) {
+    writeJsonAtomic(rulesCachePath(dir), cache, true);
+}
+/**
+ * Whether a cached set is old enough to refetch.
+ *
+ * Keyed off the last ATTEMPT, not the last success, and with a much shorter
+ * window while the cache is empty — see EMPTY_RULES_TTL_MS for why that case
+ * is the one that matters.
+ */
+export function cacheIsStale(cache, now = Date.now()) {
+    if (!cache)
+        return true;
+    const ttl = cache.rules.length === 0 ? EMPTY_RULES_TTL_MS : RULES_TTL_MS;
+    return now - (cache.checkedAt ?? cache.fetchedAt) > ttl;
+}
+/** Record that a refresh was attempted, without claiming rules arrived. */
+export function markRulesChecked(dir, now = Date.now()) {
+    const cache = readRulesCache(dir);
+    if (!cache)
+        return;
+    writeRulesCache(dir, { ...cache, checkedAt: now });
+}
+/**
+ * The base URL for a link, honouring the env override first so a misconfigured
+ * stored value can always be corrected without editing a file.
+ */
+export function baseUrlFor(link) {
+    return (process.env.GRAFT_BRAIN_URL || link.baseUrl || DEFAULT_BRAIN_BASE_URL).replace(/\/+$/, '');
+}
+/** Timeout for one rules fetch. Short: `ask` must never block on this. */
+const FETCH_TIMEOUT_MS = 5000;
+/**
+ * Fetch the brain's symbol-anchored rules.
+ *
+ * Returns null on any failure — an unreachable brain, a revoked token, a
+ * malformed body. Never throws: `ask` degrades to the code-only answer it gave
+ * before a brain was attached, which is the whole reason the cache exists.
+ */
+export async function fetchRules(link, fetchImpl = fetch) {
+    // The PUBLIC, token-authenticated route: graft runs on a laptop with no
+    // session, and the token it holds is scoped to this one brain rather than the
+    // workspace. The protected route is for the app itself.
+    const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/rules/anchors`;
+    try {
+        const res = await fetchImpl(url, {
+            headers: { authorization: `Bearer ${link.token}`, accept: 'application/json' },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!Array.isArray(body.anchors))
+            return null;
+        const out = [];
+        for (const a of body.anchors) {
+            if (!a?.symbol || !a?.rule)
+                continue;
+            out.push({
+                ruleId: String(a.rule_id ?? ''),
+                symbol: a.symbol,
+                fingerprint: String(a.fingerprint ?? ''),
+                rule: a.rule,
+                sourceUrl: a.source_url || undefined,
+            });
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=link.js.map

package/dist/brain/link.js.map

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

package/dist/brain/push.d.ts

@@ -0,0 +1,72 @@
+import { type RepoDigest } from "../app/history.js";
+import type { GraphV1 } from "../graph/types.js";
+import { type BrainLink } from "./link.js";
+/** What a local ingest read, for the caller to print. */
+export interface PushResult {
+    jobId: string;
+    repo: string;
+    commits: number;
+    threads: number;
+    symbols: number;
+    sources: number;
+    /** Set when discussion could not be read; the ingest still went ahead. */
+    warning?: string;
+}
+/**
+ * owner/name for this checkout, from its origin remote.
+ *
+ * Only GitHub, because the discussion reader and the forge links are
+ * GitHub-shaped; another forge would need its own reader, not a looser regex
+ * here that produces links to nowhere.
+ */
+export declare function repoSlugFromGit(root: string): {
+    owner: string;
+    name: string;
+} | null;
+/**
+ * A GitHub token from wherever the user already keeps one.
+ *
+ * `gh auth token` first, because anyone who works with private repositories on
+ * the command line has it and it needs no setup at all. The env vars are the
+ * CI path. Absent, the ingest still runs on commits alone — pull-request
+ * discussion is the richest source, not a required one.
+ */
+export declare function githubToken(): string | null;
+/** What the brain is waiting for, when it is waiting for something. */
+export interface ExpectedRepo {
+    slug: string;
+    status: string;
+    brainName: string;
+}
+/**
+ * The repository this brain expects, or null when it expects none.
+ *
+ * The website records it when the user chooses the local route, so this is how
+ * the CLI knows whether the directory it is standing in is the one they asked
+ * for. Mining the wrong repo into a brain is silent and very hard to notice
+ * afterwards — the rules simply describe someone else's codebase — so the round
+ * trip is worth it.
+ *
+ * Null on any failure, which keeps an older brain (or an unreachable one)
+ * working exactly as it did before this check existed.
+ */
+export declare function fetchExpectedRepo(link: BrainLink, fetchImpl?: typeof fetch): Promise<ExpectedRepo | null>;
+/** Whether two repo slugs name the same repository. GitHub is case-insensitive. */
+export declare function sameRepo(a: string, b: string): boolean;
+/** Build the digest for the checkout at `root`. Reads nothing but text. */
+export declare function buildLocalDigest(root: string, graph: GraphV1 | null, opts?: {
+    autoApprove?: boolean;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    digest: RepoDigest;
+    warning?: string;
+} | {
+    error: string;
+}>;
+/** Send a digest to the brain and return the job to poll. */
+export declare function pushDigest(link: BrainLink, digest: RepoDigest, fetchImpl?: typeof fetch): Promise<{
+    jobId: string;
+} | {
+    error: string;
+}>;
+//# sourceMappingURL=push.d.ts.map

package/dist/brain/push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.d.ts","sourceRoot":"","sources":["../../src/brain/push.ts"],"names":[],"mappings":"AAiBA,OAAO,EAKL,KAAK,UAAU,EAChB,MAAM,mBAAmB,CAAC;AAY3B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAEvD,yDAAyD;AACzD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAYD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAMpF;AAQD;;;;;;;GAOG;AACH,wBAAgB,WAAW,IAAI,MAAM,GAAG,IAAI,CAM3C;AAgBD,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAatH;AAED,mFAAmF;AACnF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,2EAA2E;AAC3E,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GAAG,IAAI,EACrB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAO,GAC7D,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAoDvE;AAED,6DAA6D;AAC7D,wBAAsB,UAAU,CAC9B,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,UAAU,EAClB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBhD"}