@tyroneross/navgator 0.2.1 → 0.9.0

package/dist/enrich/cache.js

@@ -0,0 +1,97 @@
+/**
+ * Self-contained enrichment cache for NavGator.
+ *
+ * Lives entirely inside NavGator — NO dependency on api-registry's registry.db
+ * or any external plugin. Backed by a dependency-free JSON file in NavGator's
+ * own shared home (`~/.navgator/enrichment-cache.json`), so resolved versions
+ * are reused across every repo on the machine (serves "persistent … across any
+ * type of app") and a scan never re-fetches what another scan already learned.
+ *
+ * The structural enrich pass (enrichFromCache) reads this synchronously and
+ * offline. Only the freshness path (refreshExternal / the external-resolver
+ * agent) writes to it, after hitting the network.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+/** NavGator's own cache location — independent of project storage mode. */
+export function enrichmentCachePath() {
+    return join(process.env['NAVGATOR_HOME'] || join(homedir(), '.navgator'), 'enrichment-cache.json');
+}
+/** Map a component type to the ecosystem its versions resolve from. */
+export function ecosystemFor(type) {
+    switch (type) {
+        case 'npm':
+            return 'npm';
+        case 'pip':
+            return 'pypi';
+        case 'cargo':
+            return 'cargo';
+        case 'go':
+            return 'go';
+        case 'spm':
+            return 'github'; // SPM/CocoaPods resolve via GitHub releases
+        default:
+            return 'manual'; // service / llm / infra — curated, matched by name
+    }
+}
+/** Deterministic cache key: ecosystem-scoped, lowercased package/service name. */
+export function cacheKey(type, name) {
+    return `${ecosystemFor(type)}:${name.trim().toLowerCase()}`;
+}
+/** Load the cache (sync, offline). Returns an empty cache if absent/corrupt. */
+export function loadCache() {
+    const path = enrichmentCachePath();
+    if (!existsSync(path))
+        return { version: 1, records: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (parsed?.version === 1 && parsed.records)
+            return parsed;
+    }
+    catch {
+        /* corrupt cache → start fresh; never block a scan */
+    }
+    return { version: 1, records: {} };
+}
+/** Persist the cache atomically-ish (write temp + rename). */
+export function saveCache(cache) {
+    const path = enrichmentCachePath();
+    mkdirSync(join(path, '..'), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(cache, null, 2), 'utf8');
+    writeFileSync(path, JSON.stringify(cache, null, 2), 'utf8');
+    try {
+        // best-effort cleanup of temp
+        if (existsSync(tmp))
+            writeFileSync(tmp, '', 'utf8');
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Upsert a resolved record by ecosystem+name. */
+export function upsertRecord(cache, type, name, rec) {
+    cache.records[cacheKey(type, name)] = rec;
+}
+/**
+ * Build the offline `lookup` the resolver needs, closed over a loaded cache.
+ * Matches a component to its cached record by ecosystem+name, with a fallback
+ * to canonical-service match for name-only nodes (service/llm/infra).
+ */
+export function makeLookup(cache) {
+    // Secondary index: canonical_service → record, for non-package nodes.
+    const byService = new Map();
+    for (const rec of Object.values(cache.records)) {
+        if (rec.canonical_service)
+            byService.set(rec.canonical_service.toLowerCase(), rec);
+    }
+    return (c) => {
+        const direct = cache.records[cacheKey(c.type, c.name)];
+        if (direct)
+            return direct;
+        const svc = byService.get(c.name.trim().toLowerCase());
+        return svc ?? null;
+    };
+}
+//# sourceMappingURL=cache.js.map

package/dist/enrich/cache.js.map

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

package/dist/enrich/external-enrichment.types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * External enrichment schema — the "live boundary" layer for NavGator.
+ *
+ * NavGator's scanners already DETECT external boundary nodes (`service`, `npm`,
+ * `spm`, `llm`, `infra`, `config`). What they don't do is RESOLVE them: a bare
+ * `npm:openai` node has no canonical identity, current/latest version, release
+ * date, authoritative docs, or freshness signal.
+ *
+ * This module defines the enrichment block that the external-resolver populates
+ * onto those nodes. It is the integration-layer twin of the database-profile
+ * fold (research plugin), which enriches `database` nodes with live schema/rows.
+ * Both folds answer the same question for opposite boundaries: "is this node a
+ * monitored, versioned, dated fact, or just a name?"
+ *
+ * Design rules:
+ *  - Enrichment is ADDITIVE and OPTIONAL. A component with no `external` block
+ *    behaves exactly as before. Removing this module degrades gracefully.
+ *  - Two update axes (see external-resolver.ts):
+ *      1. structural  — runs inside scan(), offline, from the registry cache.
+ *      2. freshness   — runs on the 7-day contract, online, file-change-free.
+ *  - No secrets ever land here. Enrichment is identity + version + docs only.
+ */
+/** Which package/release ecosystem a version was resolved against. */
+export type EnrichmentRegistry = 'npm' | 'pypi' | 'github' | 'cargo' | 'go' | 'manual';
+/**
+ * Freshness of NavGator's KNOWLEDGE of this node — distinct from
+ * ComponentStatus, which describes the dependency itself.
+ *  - current  : last checked within the freshness window (default 7d).
+ *  - drifting  : window elapsed; a re-check is due but not yet run.
+ *  - stale     : re-checked and a newer version exists (mirrors status:'outdated').
+ *  - unresolved: detected but never successfully resolved (offline / unknown service).
+ */
+export type Freshness = 'current' | 'drifting' | 'stale' | 'unresolved';
+/**
+ * The enrichment block hung off ArchitectureComponent.external.
+ * Populated by the external-resolver; consumed by `schema`, `summary`,
+ * `review`, and agent-output update-available messaging.
+ */
+export interface ExternalEnrichment {
+    /**
+     * Canonical service identity from the api-registry registry (e.g. the npm
+     * nodes `@anthropic-ai/sdk` and `openai` both resolve to llm-provider
+     * services). Null when the node could not be matched to a known service.
+     */
+    canonical_service?: string;
+    /** Ecosystem the version facts below were resolved from. */
+    registry: EnrichmentRegistry;
+    /** Package identifiers per ecosystem, e.g. { npm: "openai", pypi: "openai" }. */
+    package_ids: Partial<Record<EnrichmentRegistry, string>>;
+    /** Latest version available upstream at last check (e.g. "4.52.0"). */
+    latest_version?: string;
+    /** ISO-8601 release date of latest_version, when the registry exposes it. */
+    latest_released_at?: string;
+    /** Context7 library id for doc routing, when known (e.g. "/openai/openai-node"). */
+    context7_id?: string;
+    /** Authoritative docs URL — overrides the scanner's guessed documentation_url. */
+    docs_url?: string;
+    /** Freshness of this enrichment (see Freshness). */
+    freshness: Freshness;
+    /** Epoch ms of the last successful upstream check. 0 = never checked. */
+    last_checked: number;
+    /**
+     * Freshness window in ms used for this node (default 7d). Per-node override
+     * lets volatile providers (LLM SDKs) re-check more often than stable infra.
+     */
+    freshness_window_ms: number;
+    /** True when this service is in the user's ~/.api-registry/owned.json scope. */
+    author_owned?: boolean;
+    /** Where the resolution came from, for auditability. */
+    resolved_via: 'cache' | 'network';
+}
+/**
+ * Additive extension to the existing ComponentHealth block. The resolver writes
+ * these alongside the fields NavGator already declares (update_available,
+ * update_type) so existing agent-output messaging lights up for free.
+ *
+ * Merge these keys into the ComponentHealth interface in types.ts (see
+ * docs/external-enrichment-fold.md §"Schema delta").
+ */
+export interface ExternalHealthExtension {
+    /** Version NavGator believes is installed (echo of component.version). */
+    installed_version?: string;
+    /** Registry the health check ran against. */
+    health_source?: EnrichmentRegistry;
+}
+/** Default 7-day freshness window, matching api-registry's contract. */
+export declare const DEFAULT_FRESHNESS_WINDOW_MS: number;
+/** Component types that are external boundary nodes eligible for enrichment. */
+export declare const ENRICHABLE_TYPES: readonly ["npm", "pip", "spm", "cargo", "go", "gem", "composer", "service", "llm", "infra"];
+export type EnrichableType = (typeof ENRICHABLE_TYPES)[number];
+//# sourceMappingURL=external-enrichment.types.d.ts.map

package/dist/enrich/external-enrichment.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-enrichment.types.d.ts","sourceRoot":"","sources":["../../src/enrich/external-enrichment.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,sEAAsE;AACtE,MAAM,MAAM,kBAAkB,GAC1B,KAAK,GACL,MAAM,GACN,QAAQ,GACR,OAAO,GACP,IAAI,GACJ,QAAQ,CAAC;AAEb;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,CAAC;AAExE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,4DAA4D;IAC5D,QAAQ,EAAE,kBAAkB,CAAC;IAE7B,iFAAiF;IACjF,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,CAAC;IAEzD,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,oDAAoD;IACpD,SAAS,EAAE,SAAS,CAAC;IAErB,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAE5B,gFAAgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,wDAAwD;IACxD,YAAY,EAAE,OAAO,GAAG,SAAS,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED,wEAAwE;AACxE,eAAO,MAAM,2BAA2B,QAA0B,CAAC;AAEnE,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,6FAWnB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/enrich/external-enrichment.types.js

@@ -0,0 +1,38 @@
+/**
+ * External enrichment schema — the "live boundary" layer for NavGator.
+ *
+ * NavGator's scanners already DETECT external boundary nodes (`service`, `npm`,
+ * `spm`, `llm`, `infra`, `config`). What they don't do is RESOLVE them: a bare
+ * `npm:openai` node has no canonical identity, current/latest version, release
+ * date, authoritative docs, or freshness signal.
+ *
+ * This module defines the enrichment block that the external-resolver populates
+ * onto those nodes. It is the integration-layer twin of the database-profile
+ * fold (research plugin), which enriches `database` nodes with live schema/rows.
+ * Both folds answer the same question for opposite boundaries: "is this node a
+ * monitored, versioned, dated fact, or just a name?"
+ *
+ * Design rules:
+ *  - Enrichment is ADDITIVE and OPTIONAL. A component with no `external` block
+ *    behaves exactly as before. Removing this module degrades gracefully.
+ *  - Two update axes (see external-resolver.ts):
+ *      1. structural  — runs inside scan(), offline, from the registry cache.
+ *      2. freshness   — runs on the 7-day contract, online, file-change-free.
+ *  - No secrets ever land here. Enrichment is identity + version + docs only.
+ */
+/** Default 7-day freshness window, matching api-registry's contract. */
+export const DEFAULT_FRESHNESS_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+/** Component types that are external boundary nodes eligible for enrichment. */
+export const ENRICHABLE_TYPES = [
+    'npm',
+    'pip',
+    'spm',
+    'cargo',
+    'go',
+    'gem',
+    'composer',
+    'service',
+    'llm',
+    'infra',
+];
+//# sourceMappingURL=external-enrichment.types.js.map

package/dist/enrich/external-enrichment.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-enrichment.types.js","sourceRoot":"","sources":["../../src/enrich/external-enrichment.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAsFH,wEAAwE;AACxE,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEnE,gFAAgF;AAChF,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,KAAK;IACL,KAAK;IACL,KAAK;IACL,OAAO;IACP,IAAI;IACJ,KAAK;IACL,UAAU;IACV,SAAS;IACT,KAAK;IACL,OAAO;CACC,CAAC"}

package/dist/enrich/external-resolver.d.ts

@@ -0,0 +1,95 @@
+/**
+ * External resolver — the populator that turns NavGator's opaque boundary nodes
+ * into live, versioned, dated, doc-linked facts.
+ *
+ * It has TWO entry points, one per self-update axis:
+ *
+ *   1. enrichFromCache()   — STRUCTURAL axis. Pure-local, offline, fast.
+ *      Hook: src/scanner.ts, in scan(), just before "Store final state"
+ *      (~line 1546). Runs every scan over the final deduped component set,
+ *      stamping cached identity/version/docs. Never touches the network, so it
+ *      never slows a scan.
+ *
+ *   2. refreshFreshness()  — FRESHNESS axis. Network, time-triggered.
+ *      Hook: src/scanner.ts autoRefreshIfStale() (~line 2070), plus the
+ *      SessionStart staleness sweep. Re-checks upstream versions for nodes whose
+ *      freshness window has elapsed — EVEN WHEN NO FILE CHANGED. This is the
+ *      axis that makes the map "self-updating on the world changing," not just
+ *      on the repo changing. Delegate the actual fetch to the external-resolver
+ *      AGENT (agents/external-resolver.md) so network work runs isolated.
+ *
+ * Everything here is SELF-CONTAINED inside NavGator: the cache is NavGator's own
+ * JSON store (src/enrich/cache.ts → ~/.navgator/enrichment-cache.json) and the
+ * fetchers are vendored (src/enrich/fetchers.ts). No api-registry / external
+ * plugin dependency. See docs/external-enrichment-fold.md.
+ */
+import type { ArchitectureComponent } from '../types.js';
+import { type ExternalEnrichment, type Freshness } from './external-enrichment.types.js';
+import { type EnrichmentCacheFile } from './cache.js';
+/** A cache row from the api-registry registry, keyed by canonical service. */
+export interface RegistryRecord {
+    canonical_service: string;
+    registry: ExternalEnrichment['registry'];
+    package_ids: ExternalEnrichment['package_ids'];
+    latest_version?: string;
+    latest_released_at?: string;
+    context7_id?: string;
+    docs_url?: string;
+    last_checked: number;
+    author_owned?: boolean;
+}
+/** Narrow a component to an enrichable boundary node. */
+export declare function isEnrichable(c: ArchitectureComponent): boolean;
+/**
+ * Deterministic freshness from timestamps + version comparison. No network.
+ * Exported so it can be unit-tested in isolation (the one piece of real logic).
+ */
+export declare function computeFreshness(now: number, enrichment: Pick<ExternalEnrichment, 'last_checked' | 'freshness_window_ms' | 'latest_version'>, installedVersion?: string): Freshness;
+/**
+ * STRUCTURAL axis. Stamp every enrichable node from the registry cache.
+ * Mutates components in place; returns the count enriched. Offline + sync-fast.
+ *
+ * @param lookup  resolve a component to a cached registry record (or null).
+ *                Injected so this module never imports the SQLite layer directly.
+ */
+export declare function enrichFromCache(components: ArchitectureComponent[], lookup: (c: ArchitectureComponent) => RegistryRecord | null, now: number): number;
+/**
+ * FRESHNESS axis. Returns the nodes whose enrichment is overdue and need an
+ * upstream re-check. The orchestrator hands this list to the external-resolver
+ * AGENT, which fetches latest versions and writes back into the registry cache;
+ * the next enrichFromCache() pass then re-stamps the graph. Kept as a SELECTOR
+ * (no network here) so the engine stays deterministic and offline-safe.
+ */
+export declare function selectStaleForRefresh(components: ArchitectureComponent[], now: number): ArchitectureComponent[];
+/** Report from a freshness refresh pass. */
+export interface RefreshReport {
+    checked: number;
+    resolved: number;
+    unresolved: number;
+    cache_updated: number;
+    drift: Array<{
+        name: string;
+        type: string;
+        installed?: string;
+        latest?: string;
+        bump: 'patch' | 'minor' | 'major';
+    }>;
+}
+/**
+ * FRESHNESS axis (network). Self-contained: vendored fetchers + NavGator's own
+ * JSON cache. Resolves overdue/unresolved boundary nodes upstream, upserts the
+ * cache, and persists it. Returns a drift report. Called by the external-
+ * resolver agent or a `navgator refresh-external` command — NOT by scan().
+ *
+ * For spm/cargo/go nodes the upstream ref is owner/repo (from repository_url);
+ * pass a resolver to derive it, else those nodes stay unresolved.
+ */
+export declare function refreshExternal(components: ArchitectureComponent[], cache: EnrichmentCacheFile, now: number, opts?: {
+    force?: boolean;
+    githubRefOf?: (c: ArchitectureComponent) => string | null;
+}): Promise<RefreshReport>;
+/** Best-effort owner/repo from a repository URL. */
+export declare function deriveOwnerRepo(repoUrl?: string): string | null;
+/** semver-ish bump classification; falls back to 'minor' when unparseable. */
+export declare function classifyBump(from: string | undefined, to: string): 'patch' | 'minor' | 'major';
+//# sourceMappingURL=external-resolver.d.ts.map

package/dist/enrich/external-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-resolver.d.ts","sourceRoot":"","sources":["../../src/enrich/external-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,SAAS,EAIf,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,KAAK,mBAAmB,EAIzB,MAAM,YAAY,CAAC;AAGpB,8EAA8E;AAC9E,MAAM,WAAW,cAAc;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAC;IACzC,WAAW,EAAE,kBAAkB,CAAC,aAAa,CAAC,CAAC;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAE9D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,IAAI,CACd,kBAAkB,EAClB,cAAc,GAAG,qBAAqB,GAAG,gBAAgB,CAC1D,EACD,gBAAgB,CAAC,EAAE,MAAM,GACxB,SAAS,CAUX;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,qBAAqB,EAAE,EACnC,MAAM,EAAE,CAAC,CAAC,EAAE,qBAAqB,KAAK,cAAc,GAAG,IAAI,EAC3D,GAAG,EAAE,MAAM,GACV,MAAM,CA0CR;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,qBAAqB,EAAE,EACnC,GAAG,EAAE,MAAM,GACV,qBAAqB,EAAE,CAMzB;AAED,4CAA4C;AAC5C,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;KACnC,CAAC,CAAC;CACJ;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,qBAAqB,EAAE,EACnC,KAAK,EAAE,mBAAmB,EAC1B,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,qBAAqB,KAAK,MAAM,GAAG,IAAI,CAAA;CAAO,GACxF,OAAO,CAAC,aAAa,CAAC,CA2DxB;AAED,oDAAoD;AACpD,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI/D;AAaD,8EAA8E;AAC9E,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,EAAE,EAAE,MAAM,GACT,OAAO,GAAG,OAAO,GAAG,OAAO,CAO7B"}

package/dist/enrich/external-resolver.js

@@ -0,0 +1,222 @@
+/**
+ * External resolver — the populator that turns NavGator's opaque boundary nodes
+ * into live, versioned, dated, doc-linked facts.
+ *
+ * It has TWO entry points, one per self-update axis:
+ *
+ *   1. enrichFromCache()   — STRUCTURAL axis. Pure-local, offline, fast.
+ *      Hook: src/scanner.ts, in scan(), just before "Store final state"
+ *      (~line 1546). Runs every scan over the final deduped component set,
+ *      stamping cached identity/version/docs. Never touches the network, so it
+ *      never slows a scan.
+ *
+ *   2. refreshFreshness()  — FRESHNESS axis. Network, time-triggered.
+ *      Hook: src/scanner.ts autoRefreshIfStale() (~line 2070), plus the
+ *      SessionStart staleness sweep. Re-checks upstream versions for nodes whose
+ *      freshness window has elapsed — EVEN WHEN NO FILE CHANGED. This is the
+ *      axis that makes the map "self-updating on the world changing," not just
+ *      on the repo changing. Delegate the actual fetch to the external-resolver
+ *      AGENT (agents/external-resolver.md) so network work runs isolated.
+ *
+ * Everything here is SELF-CONTAINED inside NavGator: the cache is NavGator's own
+ * JSON store (src/enrich/cache.ts → ~/.navgator/enrichment-cache.json) and the
+ * fetchers are vendored (src/enrich/fetchers.ts). No api-registry / external
+ * plugin dependency. See docs/external-enrichment-fold.md.
+ */
+import { DEFAULT_FRESHNESS_WINDOW_MS, ENRICHABLE_TYPES, } from './external-enrichment.types.js';
+import { ecosystemFor, upsertRecord, saveCache, } from './cache.js';
+import { fetchLatest } from './fetchers.js';
+/** Narrow a component to an enrichable boundary node. */
+export function isEnrichable(c) {
+    return ENRICHABLE_TYPES.includes(c.type);
+}
+/**
+ * Deterministic freshness from timestamps + version comparison. No network.
+ * Exported so it can be unit-tested in isolation (the one piece of real logic).
+ */
+export function computeFreshness(now, enrichment, installedVersion) {
+    if (!enrichment.last_checked)
+        return 'unresolved';
+    const elapsed = now - enrichment.last_checked;
+    const overdue = elapsed > enrichment.freshness_window_ms;
+    const newerExists = !!installedVersion &&
+        !!enrichment.latest_version &&
+        installedVersion !== enrichment.latest_version;
+    if (newerExists)
+        return 'stale';
+    return overdue ? 'drifting' : 'current';
+}
+/**
+ * STRUCTURAL axis. Stamp every enrichable node from the registry cache.
+ * Mutates components in place; returns the count enriched. Offline + sync-fast.
+ *
+ * @param lookup  resolve a component to a cached registry record (or null).
+ *                Injected so this module never imports the SQLite layer directly.
+ */
+export function enrichFromCache(components, lookup, now) {
+    let enriched = 0;
+    for (const c of components) {
+        if (!isEnrichable(c))
+            continue;
+        const rec = lookup(c);
+        if (!rec) {
+            // Detected but unknown to the registry — mark unresolved so the freshness
+            // sweep / agent knows to attempt a network resolve later.
+            c.external = unresolvedEnrichment(c.type);
+            continue;
+        }
+        const enrichment = {
+            canonical_service: rec.canonical_service,
+            registry: rec.registry,
+            package_ids: rec.package_ids,
+            latest_version: rec.latest_version,
+            latest_released_at: rec.latest_released_at,
+            context7_id: rec.context7_id,
+            docs_url: rec.docs_url,
+            last_checked: rec.last_checked,
+            freshness_window_ms: DEFAULT_FRESHNESS_WINDOW_MS,
+            author_owned: rec.author_owned,
+            resolved_via: 'cache',
+            freshness: 'unresolved', // set below
+        };
+        enrichment.freshness = computeFreshness(now, enrichment, c.version);
+        c.external = enrichment;
+        // Light up the health fields NavGator ALREADY consumes in agent-output.ts.
+        if (enrichment.freshness === 'stale' && rec.latest_version) {
+            c.status = c.status === 'active' ? 'outdated' : c.status;
+            c.health = {
+                ...(c.health ?? { last_audit: now }),
+                last_audit: now,
+                update_available: rec.latest_version,
+                update_type: classifyBump(c.version, rec.latest_version),
+            };
+        }
+        if (rec.docs_url)
+            c.documentation_url = rec.docs_url;
+        enriched++;
+    }
+    return enriched;
+}
+/**
+ * FRESHNESS axis. Returns the nodes whose enrichment is overdue and need an
+ * upstream re-check. The orchestrator hands this list to the external-resolver
+ * AGENT, which fetches latest versions and writes back into the registry cache;
+ * the next enrichFromCache() pass then re-stamps the graph. Kept as a SELECTOR
+ * (no network here) so the engine stays deterministic and offline-safe.
+ */
+export function selectStaleForRefresh(components, now) {
+    return components.filter((c) => {
+        if (!isEnrichable(c) || !c.external)
+            return isEnrichable(c); // never-resolved → refresh
+        const f = computeFreshness(now, c.external, c.version);
+        return f === 'drifting' || f === 'unresolved';
+    });
+}
+/**
+ * FRESHNESS axis (network). Self-contained: vendored fetchers + NavGator's own
+ * JSON cache. Resolves overdue/unresolved boundary nodes upstream, upserts the
+ * cache, and persists it. Returns a drift report. Called by the external-
+ * resolver agent or a `navgator refresh-external` command — NOT by scan().
+ *
+ * For spm/cargo/go nodes the upstream ref is owner/repo (from repository_url);
+ * pass a resolver to derive it, else those nodes stay unresolved.
+ */
+export async function refreshExternal(components, cache, now, opts = {}) {
+    const report = {
+        checked: 0,
+        resolved: 0,
+        unresolved: 0,
+        cache_updated: 0,
+        drift: [],
+    };
+    const targets = opts.force
+        ? components.filter(isEnrichable)
+        : selectStaleForRefresh(components, now);
+    for (const c of targets) {
+        report.checked++;
+        const eco = ecosystemFor(c.type);
+        let ref = c.name;
+        let registry = null;
+        if (eco === 'npm')
+            registry = 'npm';
+        else if (eco === 'pypi')
+            registry = 'pypi';
+        else if (eco === 'github') {
+            registry = 'github';
+            ref = opts.githubRefOf?.(c) ?? deriveOwnerRepo(c.repository_url);
+        }
+        else {
+            // service/llm/infra/manual — no auto-source; leave to curated cache.
+            report.unresolved++;
+            continue;
+        }
+        if (!registry || !ref) {
+            report.unresolved++;
+            continue;
+        }
+        const latest = await fetchLatest(registry, ref);
+        if (!latest?.version) {
+            report.unresolved++;
+            continue;
+        }
+        report.resolved++;
+        upsertRecord(cache, c.type, c.name, {
+            canonical_service: c.name,
+            registry: eco,
+            package_ids: { [eco]: c.name },
+            latest_version: latest.version,
+            latest_released_at: latest.released_at,
+            docs_url: latest.docs_url,
+            last_checked: now,
+        });
+        report.cache_updated++;
+        if (c.version && c.version !== latest.version) {
+            report.drift.push({
+                name: c.name,
+                type: c.type,
+                installed: c.version,
+                latest: latest.version,
+                bump: classifyBump(c.version, latest.version),
+            });
+        }
+    }
+    if (report.cache_updated > 0)
+        saveCache(cache);
+    return report;
+}
+/** Best-effort owner/repo from a repository URL. */
+export function deriveOwnerRepo(repoUrl) {
+    if (!repoUrl)
+        return null;
+    const m = repoUrl.match(/github\.com[/:]([^/]+\/[^/.]+)/i);
+    return m ? m[1] : null;
+}
+function unresolvedEnrichment(_type) {
+    return {
+        registry: 'manual',
+        package_ids: {},
+        freshness: 'unresolved',
+        last_checked: 0,
+        freshness_window_ms: DEFAULT_FRESHNESS_WINDOW_MS,
+        resolved_via: 'cache',
+    };
+}
+/** semver-ish bump classification; falls back to 'minor' when unparseable. */
+export function classifyBump(from, to) {
+    const a = parseSemver(from);
+    const b = parseSemver(to);
+    if (!a || !b)
+        return 'minor';
+    if (b[0] > a[0])
+        return 'major';
+    if (b[1] > a[1])
+        return 'minor';
+    return 'patch';
+}
+function parseSemver(v) {
+    if (!v)
+        return null;
+    const m = v.replace(/^[^\d]*/, '').match(/^(\d+)\.(\d+)\.(\d+)/);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+//# sourceMappingURL=external-resolver.js.map

package/dist/enrich/external-resolver.js.map

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

package/dist/enrich/fetchers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Vendored, dependency-free upstream version fetchers for NavGator.
+ *
+ * Self-contained: uses the global `fetch` (Node ≥18) — no axios, no api-registry
+ * import. These are the ONLY network calls in the enrichment fold, and they run
+ * exclusively on the freshness path (refreshExternal / the external-resolver
+ * agent), never inside scan(). The engine stays offline and deterministic.
+ *
+ * Equivalent to api-registry/src/http.ts's fetchers, re-implemented here so
+ * NavGator carries no cross-plugin dependency.
+ */
+export interface LatestVersion {
+    version?: string;
+    released_at?: string;
+    docs_url?: string;
+    repo_url?: string;
+}
+/** npm: latest dist-tag + publish time. */
+export declare function fetchNpmLatest(pkg: string): Promise<LatestVersion | null>;
+/** PyPI: latest version + release date. */
+export declare function fetchPypiLatest(pkg: string): Promise<LatestVersion | null>;
+/**
+ * GitHub Releases: latest tag + publish date for `owner/repo`.
+ * Used for spm/cargo/go nodes that expose versions via tags, not a registry.
+ * Honors GITHUB_TOKEN when present to avoid the 60/hr unauthenticated limit.
+ */
+export declare function fetchGitHubLatest(ownerRepo: string): Promise<LatestVersion | null>;
+/** Dispatch by ecosystem. `ref` is a package name, or owner/repo for github. */
+export declare function fetchLatest(registry: 'npm' | 'pypi' | 'github', ref: string): Promise<LatestVersion | null>;
+//# sourceMappingURL=fetchers.d.ts.map

package/dist/enrich/fetchers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchers.d.ts","sourceRoot":"","sources":["../../src/enrich/fetchers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAkBD,2CAA2C;AAC3C,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAiB/E;AAED,2CAA2C;AAC3C,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAmBhF;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAexF;AAED,gFAAgF;AAChF,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,EACnC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAW/B"}