@zigrivers/scaffold 3.28.0 → 3.29.0

package/dist/knowledge-freshness/gates/changed-files.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Resolve the list of changed knowledge-entry .md files for a gate run.
+ *
+ * Argument semantics:
+ *   - If `args` has entries, treat them as file paths (relative or absolute)
+ *     and use them directly. Operators pass explicit files when iterating
+ *     locally; the workflow passes them when GitHub's "changed files" API
+ *     surface is more convenient than re-running `git diff`.
+ *   - Otherwise fall back to `git diff --name-only origin/main...HEAD`,
+ *     filtering to `content/knowledge/**\/*.md` so callers can run the CLI
+ *     on a feature branch without flag plumbing.
+ *
+ * Returns absolute paths so callers can `fs.readFileSync` directly.
+ */
+export interface ResolveOptions {
+    /**
+     * Read the file list from a JSON file (must be an array of strings). Used
+     * by the CI workflow to avoid shell-interpolating PR-controlled filenames
+     * (round-2 F-001) — a PR could add a content/knowledge path containing
+     * shell metacharacters that would `$()`-execute inside the workflow's
+     * bash. Reading from a JSON file lets us validate each entry on the Node
+     * side without ever touching bash.
+     */
+    filesFrom?: string;
+}
+export declare function resolveTargetFiles(args: string[], cwd: string, opts?: ResolveOptions): string[];
+/**
+ * Read the operator opt-out list for link-checking from
+ * `.scaffold/observability.yaml` under `knowledge_freshness.link_check.skip`.
+ * Empty list when the file or key is missing — the default is "no opt-outs"
+ * per the task spec ("no opt-outs" if no list exists).
+ */
+export declare function loadLinkCheckSkip(projectRoot: string): string[];
+/**
+ * Produce a unified diff for a SPECIFIC set of files.
+ *
+ * Round-2 F-003: this used to diff `origin/main...HEAD`, which produced an
+ * empty diff in both deployment shapes:
+ *   - PR gate workflow: HEAD of the base checkout IS origin/main (since the
+ *     PR head's content/knowledge/ is OVERLAID, not merged). So
+ *     `origin/main...HEAD` returns nothing even when the overlay added
+ *     thousands of lines.
+ *   - Cron inline gates: audit-apply edits on disk WITHOUT committing,
+ *     so HEAD is still main and the diff is empty.
+ *
+ * Diffing the working tree (no commit ranges, just `git diff -- <files>`)
+ * captures both uncommitted edits AND overlaid files. That's the right
+ * shape for every gate-execution context we use.
+ *
+ * Returns an empty string when there are no changes.
+ */
+export declare function gitDiffForFiles(cwd: string, files: string[]): string;
+//# sourceMappingURL=changed-files.d.ts.map

package/dist/knowledge-freshness/gates/changed-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changed-files.d.ts","sourceRoot":"","sources":["../../../src/knowledge-freshness/gates/changed-files.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAoBD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,MAAM,EAAE,CAyCnG;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAiB/D;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAcpE"}

package/dist/knowledge-freshness/gates/changed-files.js

@@ -0,0 +1,128 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+/** Reject any path that escapes content/knowledge/, contains shell metas, or isn't a .md file. */
+function validateGatePath(rel) {
+    if (!rel.startsWith('content/knowledge/')) {
+        throw new Error(`refusing gate path outside content/knowledge/: ${JSON.stringify(rel)}`);
+    }
+    if (!rel.endsWith('.md')) {
+        throw new Error(`refusing non-markdown gate path: ${JSON.stringify(rel)}`);
+    }
+    if (rel.includes('..')) {
+        throw new Error(`refusing gate path containing "..": ${JSON.stringify(rel)}`);
+    }
+    // Belt-and-braces: even though we never interpolate these paths into a
+    // shell, reject the metacharacters a future regression might.
+    if (/[\s;|&`$<>"'\\(){}*?]/.test(rel)) {
+        throw new Error(`refusing gate path with shell metacharacters: ${JSON.stringify(rel)}`);
+    }
+}
+export function resolveTargetFiles(args, cwd, opts = {}) {
+    if (opts.filesFrom) {
+        const raw = fs.readFileSync(path.resolve(cwd, opts.filesFrom), 'utf8');
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (e) {
+            throw new Error(`--files-from JSON parse error: ${e.message}`);
+        }
+        if (!Array.isArray(parsed))
+            throw new Error('--files-from must be a JSON array of strings');
+        const out = [];
+        for (const p of parsed) {
+            if (typeof p !== 'string')
+                throw new Error('--files-from entries must be strings');
+            validateGatePath(p);
+            out.push(path.resolve(cwd, p));
+        }
+        return out;
+    }
+    if (args.length > 0) {
+        // Even explicit args go through the validator — the CLI is called from
+        // workflows too, and we want one validation chokepoint.
+        for (const a of args) {
+            const rel = path.isAbsolute(a) ? path.relative(cwd, a) : a;
+            validateGatePath(rel);
+        }
+        return args.map((p) => path.resolve(cwd, p));
+    }
+    // Round-8 F-001: mirror the CI workflow's --diff-filter=d so a locally-
+    // deleted knowledge entry doesn't appear in the file list and crash
+    // downstream gates with ENOENT.
+    const out = spawnSync('git', ['diff', '--name-only', '--diff-filter=d', 'origin/main...HEAD'], {
+        cwd, encoding: 'utf8',
+    });
+    if (out.status !== 0) {
+        throw new Error(`git diff failed (exit ${out.status}): ${out.stderr || '<no stderr>'}\n` +
+            'If you are running this gate locally without an origin/main, pass file paths explicitly.');
+    }
+    return out.stdout
+        .split('\n')
+        .map((s) => s.trim())
+        .filter((s) => s.startsWith('content/knowledge/') && s.endsWith('.md'))
+        .map((p) => path.resolve(cwd, p));
+}
+/**
+ * Read the operator opt-out list for link-checking from
+ * `.scaffold/observability.yaml` under `knowledge_freshness.link_check.skip`.
+ * Empty list when the file or key is missing — the default is "no opt-outs"
+ * per the task spec ("no opt-outs" if no list exists).
+ */
+export function loadLinkCheckSkip(projectRoot) {
+    const yamlPath = path.join(projectRoot, '.scaffold', 'observability.yaml');
+    if (!fs.existsSync(yamlPath))
+        return [];
+    try {
+        const parsed = yaml.load(fs.readFileSync(yamlPath, 'utf8'), { schema: yaml.JSON_SCHEMA });
+        if (!parsed || typeof parsed !== 'object')
+            return [];
+        const kf = parsed['knowledge_freshness'];
+        if (!kf || typeof kf !== 'object')
+            return [];
+        const lc = kf['link_check'];
+        if (!lc || typeof lc !== 'object')
+            return [];
+        const skip = lc['skip'];
+        if (!Array.isArray(skip))
+            return [];
+        return skip.filter((s) => typeof s === 'string' && s.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+// F-007: the former `readPrBody` helper was removed. Anti-over-rewrite no
+// longer reads the PR body — the override is now a maintainer-applied label
+// passed explicitly via `--pr-labels` from the workflow (see F-005).
+/**
+ * Produce a unified diff for a SPECIFIC set of files.
+ *
+ * Round-2 F-003: this used to diff `origin/main...HEAD`, which produced an
+ * empty diff in both deployment shapes:
+ *   - PR gate workflow: HEAD of the base checkout IS origin/main (since the
+ *     PR head's content/knowledge/ is OVERLAID, not merged). So
+ *     `origin/main...HEAD` returns nothing even when the overlay added
+ *     thousands of lines.
+ *   - Cron inline gates: audit-apply edits on disk WITHOUT committing,
+ *     so HEAD is still main and the diff is empty.
+ *
+ * Diffing the working tree (no commit ranges, just `git diff -- <files>`)
+ * captures both uncommitted edits AND overlaid files. That's the right
+ * shape for every gate-execution context we use.
+ *
+ * Returns an empty string when there are no changes.
+ */
+export function gitDiffForFiles(cwd, files) {
+    if (files.length === 0)
+        return '';
+    const relFiles = files.map((f) => path.relative(cwd, f));
+    const out = spawnSync('git', ['diff', '--no-color', '--', ...relFiles], { cwd, encoding: 'utf8' });
+    if (out.status !== 0) {
+        throw new Error(`git diff failed (exit ${out.status}): ${out.stderr || '<no stderr>'}`);
+    }
+    return out.stdout;
+}
+//# sourceMappingURL=changed-files.js.map

package/dist/knowledge-freshness/gates/changed-files.js.map

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

package/dist/knowledge-freshness/gates/deep-guidance-check.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Deep-Guidance-preserved gate (spec §A.5).
+ *
+ * The assembly engine matches `^## Deep Guidance\s*$` to extract per-entry
+ * deep guidance for injection into pipeline prompts. If a refresh PR replaces
+ * the heading with `## Guidance` or `### Deep Guidance` the engine silently
+ * skips the section. This gate refuses to merge any PR that drops the exact
+ * heading from a changed entry.
+ *
+ * The check is positive (must contain the literal heading), not regex-fuzzy
+ * — we explicitly want to fail variants like `# Deep Guidance`,
+ * `## deep guidance`, or trailing punctuation.
+ */
+export interface DeepGuidanceFinding {
+    file: string;
+    ok: boolean;
+    reason?: string;
+}
+export declare function checkDeepGuidance(inputs: Array<{
+    file: string;
+    content: string;
+}>): DeepGuidanceFinding[];
+//# sourceMappingURL=deep-guidance-check.d.ts.map

package/dist/knowledge-freshness/gates/deep-guidance-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-guidance-check.d.ts","sourceRoot":"","sources":["../../../src/knowledge-freshness/gates/deep-guidance-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,mBAAmB,EAAE,CAWzG"}

package/dist/knowledge-freshness/gates/deep-guidance-check.js

@@ -0,0 +1,27 @@
+/**
+ * Deep-Guidance-preserved gate (spec §A.5).
+ *
+ * The assembly engine matches `^## Deep Guidance\s*$` to extract per-entry
+ * deep guidance for injection into pipeline prompts. If a refresh PR replaces
+ * the heading with `## Guidance` or `### Deep Guidance` the engine silently
+ * skips the section. This gate refuses to merge any PR that drops the exact
+ * heading from a changed entry.
+ *
+ * The check is positive (must contain the literal heading), not regex-fuzzy
+ * — we explicitly want to fail variants like `# Deep Guidance`,
+ * `## deep guidance`, or trailing punctuation.
+ */
+const DEEP_GUIDANCE_RE = /^## Deep Guidance\s*$/m;
+export function checkDeepGuidance(inputs) {
+    return inputs.map(({ file, content }) => {
+        if (DEEP_GUIDANCE_RE.test(content)) {
+            return { file, ok: true };
+        }
+        return {
+            file,
+            ok: false,
+            reason: 'missing literal `## Deep Guidance` heading (assembly engine depends on this exact form)',
+        };
+    });
+}
+//# sourceMappingURL=deep-guidance-check.js.map

package/dist/knowledge-freshness/gates/deep-guidance-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-guidance-check.js","sourceRoot":"","sources":["../../../src/knowledge-freshness/gates/deep-guidance-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,gBAAgB,GAAG,wBAAwB,CAAA;AAQjD,MAAM,UAAU,iBAAiB,CAAC,MAAgD;IAChF,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;QACtC,IAAI,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YACnC,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;QAC3B,CAAC;QACD,OAAO;YACL,IAAI;YACJ,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,yFAAyF;SAClG,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/knowledge-freshness/gates/deep-guidance-check.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=deep-guidance-check.test.d.ts.map

package/dist/knowledge-freshness/gates/deep-guidance-check.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-guidance-check.test.d.ts","sourceRoot":"","sources":["../../../src/knowledge-freshness/gates/deep-guidance-check.test.ts"],"names":[],"mappings":""}

package/dist/knowledge-freshness/gates/deep-guidance-check.test.js

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest';
+import { checkDeepGuidance } from './deep-guidance-check.js';
+describe('checkDeepGuidance', () => {
+    it('passes entries that contain the literal heading', () => {
+        const content = '---\nname: x\n---\n## Deep Guidance\nstuff';
+        expect(checkDeepGuidance([{ file: 'a.md', content }])[0].ok).toBe(true);
+    });
+    it('fails when the heading is missing entirely', () => {
+        const content = '---\nname: x\n---\n## Guidance\nstuff';
+        const r = checkDeepGuidance([{ file: 'a.md', content }])[0];
+        expect(r.ok).toBe(false);
+        expect(r.reason).toMatch(/Deep Guidance/);
+    });
+    it('fails on case-different variants', () => {
+        const content = '---\nname: x\n---\n## deep guidance\n';
+        expect(checkDeepGuidance([{ file: 'a.md', content }])[0].ok).toBe(false);
+    });
+    it('fails when the heading is demoted to ###', () => {
+        const content = '---\nname: x\n---\n### Deep Guidance\n';
+        expect(checkDeepGuidance([{ file: 'a.md', content }])[0].ok).toBe(false);
+    });
+});
+//# sourceMappingURL=deep-guidance-check.test.js.map

package/dist/knowledge-freshness/gates/deep-guidance-check.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-guidance-check.test.js","sourceRoot":"","sources":["../../../src/knowledge-freshness/gates/deep-guidance-check.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAE5D,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,OAAO,GAAG,4CAA4C,CAAA;QAC5D,MAAM,CAAC,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,OAAO,GAAG,uCAAuC,CAAA;QACvD,MAAM,CAAC,GAAG,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC3D,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACxB,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,CAAA;IAC3C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,OAAO,GAAG,uCAAuC,CAAA;QACvD,MAAM,CAAC,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC1E,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,OAAO,GAAG,wCAAwC,CAAA;QACxD,MAAM,CAAC,iBAAiB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC1E,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/knowledge-freshness/gates/link-check.d.ts

@@ -0,0 +1,55 @@
+import { type Resolver } from '../source-url-validator.js';
+/**
+ * Link-check gate: verifies every `sources[*].url` declared in changed
+ * knowledge entries resolves to a 2xx (after following 3xx). HEAD is tried
+ * first; if the server returns 405/501 or any non-2xx that's still <500, we
+ * fall back to a GET with `Range: bytes=0-0` so the body cap from
+ * `fetchAndHash` doesn't apply here either.
+ *
+ * SSRF: every hop is re-validated using the same `assertSafeSourceUrlWithDns`
+ * + pinning-agent pattern as `source-hash.ts::fetchAndHash`. This is the only
+ * other code path that issues outbound HTTP from this package — keeping the
+ * guards identical means a fix to one applies to both.
+ */
+export type FetchImpl = (input: string, init?: Record<string, unknown>) => Promise<Response>;
+export interface LinkCheckOptions {
+    resolver?: Resolver;
+    timeoutMs?: number;
+    fetchImpl?: FetchImpl;
+    /**
+     * Hosts (or exact URLs) to skip entirely. Drawn from
+     * `.scaffold/observability.yaml` `knowledge_freshness.link_check.skip:` when
+     * present. Matching is by exact-URL or by hostname suffix.
+     */
+    skip?: string[];
+}
+export interface LinkCheckResult {
+    url: string;
+    ok: boolean;
+    status: number | null;
+    reason?: string;
+    /** True when the URL matched the operator opt-out list and was not fetched. */
+    skipped?: boolean;
+}
+/**
+ * HEAD-check one URL (with GET-Range fallback). Returns a structured result
+ * rather than throwing so the caller can aggregate per-URL outcomes for the
+ * CI annotation output. SSRF / DNS-rebinding errors surface as `ok: false`
+ * with `status: null` and the validator's message in `reason`.
+ */
+export declare function checkOneUrl(url: string, opts?: LinkCheckOptions): Promise<LinkCheckResult>;
+/**
+ * Check every URL across a set of entries. Returns one result per (url, file)
+ * pair so the CLI can attribute failures to specific files in the PR.
+ */
+export interface AggregateLinkCheckResult {
+    ok: boolean;
+    results: Array<LinkCheckResult & {
+        file: string;
+    }>;
+}
+export declare function checkUrlsForEntries(entries: Array<{
+    file: string;
+    sourceUrls: string[];
+}>, opts?: LinkCheckOptions): Promise<AggregateLinkCheckResult>;
+//# sourceMappingURL=link-check.d.ts.map

package/dist/knowledge-freshness/gates/link-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-check.d.ts","sourceRoot":"","sources":["../../../src/knowledge-freshness/gates/link-check.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,4BAA4B,CAAA;AAEnC;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;AAK5F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAyBD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,eAAe,CAAC,CAwF1B;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,EAAE,KAAK,CAAC,eAAe,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACnD;AAED,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,EACtD,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,wBAAwB,CAAC,CAWnC"}

package/dist/knowledge-freshness/gates/link-check.js

@@ -0,0 +1,161 @@
+import net from 'node:net';
+import { fetch as undiciFetch, Agent } from 'undici';
+import { assertSafeSourceUrlWithDns, defaultResolver, } from '../source-url-validator.js';
+const MAX_REDIRECT_HOPS = 5;
+const DEFAULT_TIMEOUT_MS = 15_000;
+function pinningAgent(pinnedIp) {
+    const family = net.isIP(pinnedIp) === 6 ? 6 : 4;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const lookup = (_hostname, opts, callback) => {
+        if (opts && opts.all === true)
+            callback(null, [{ address: pinnedIp, family }]);
+        else
+            callback(null, pinnedIp, family);
+    };
+    return new Agent({ connect: { lookup } });
+}
+function urlMatchesSkip(url, skip) {
+    if (!skip.length)
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    for (const entry of skip) {
+        if (!entry)
+            continue;
+        if (entry === url)
+            return true;
+        // Hostname or hostname-suffix match — same pattern as the allowlist loader.
+        if (parsed.hostname === entry || parsed.hostname.endsWith('.' + entry))
+            return true;
+    }
+    return false;
+}
+/**
+ * HEAD-check one URL (with GET-Range fallback). Returns a structured result
+ * rather than throwing so the caller can aggregate per-URL outcomes for the
+ * CI annotation output. SSRF / DNS-rebinding errors surface as `ok: false`
+ * with `status: null` and the validator's message in `reason`.
+ */
+export async function checkOneUrl(url, opts = {}) {
+    const skip = opts.skip ?? [];
+    if (urlMatchesSkip(url, skip)) {
+        return { url, ok: true, status: null, skipped: true };
+    }
+    const resolver = opts.resolver ?? defaultResolver;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const doFetch = opts.fetchImpl ?? undiciFetch;
+    let current = url;
+    let lastStatus = null;
+    for (let hop = 0; hop <= MAX_REDIRECT_HOPS; hop++) {
+        let validated;
+        try {
+            validated = await assertSafeSourceUrlWithDns(current, resolver);
+        }
+        catch (e) {
+            return { url, ok: false, status: null, reason: e instanceof Error ? e.message : String(e) };
+        }
+        let host = validated.url.hostname;
+        if (host.startsWith('[') && host.endsWith(']'))
+            host = host.slice(1, -1);
+        const pinnedIp = validated.ips[0];
+        const dispatcher = net.isIP(host) === 0 && pinnedIp ? pinningAgent(pinnedIp) : undefined;
+        // Try HEAD first; if the server returns a status that suggests HEAD isn't
+        // supported (405 / 501) OR any non-2xx that's not a redirect, fall back
+        // to a tiny GET (Range: bytes=0-0) before declaring failure.
+        let headRes;
+        try {
+            try {
+                headRes = await doFetch(current, {
+                    method: 'HEAD',
+                    redirect: 'manual',
+                    signal: AbortSignal.timeout(timeoutMs),
+                    ...(dispatcher ? { dispatcher } : {}),
+                });
+            }
+            catch (e) {
+                // Some servers reset the connection on HEAD. Try GET-Range below.
+                const msg = e instanceof Error ? e.message : String(e);
+                if (/abort|timeout/i.test(msg)) {
+                    return { url, ok: false, status: null, reason: msg };
+                }
+                // Fall through to GET-Range fallback.
+                headRes = undefined;
+            }
+            const headStatus = headRes?.status ?? 0;
+            const shouldFallback = !headRes || headStatus === 405 || headStatus === 501 ||
+                (headStatus >= 400 && headStatus < 500);
+            let res;
+            if (shouldFallback) {
+                try {
+                    await headRes?.body?.cancel();
+                }
+                catch { /* noop */ }
+                res = await doFetch(current, {
+                    method: 'GET',
+                    headers: { Range: 'bytes=0-0' },
+                    redirect: 'manual',
+                    signal: AbortSignal.timeout(timeoutMs),
+                    ...(dispatcher ? { dispatcher } : {}),
+                });
+            }
+            else {
+                res = headRes;
+            }
+            lastStatus = res.status;
+            // 2xx including 206 Partial Content from the Range request → success.
+            if (res.status >= 200 && res.status < 300) {
+                try {
+                    await res.body?.cancel();
+                }
+                catch { /* noop */ }
+                return { url, ok: true, status: res.status };
+            }
+            // 3xx → re-validate the redirect target and try again.
+            if (res.status >= 300 && res.status < 400) {
+                const location = res.headers.get('location');
+                try {
+                    await res.body?.cancel();
+                }
+                catch { /* noop */ }
+                if (!location) {
+                    return { url, ok: false, status: res.status, reason: `${res.status} with no Location header` };
+                }
+                current = new URL(location, current).toString();
+                continue;
+            }
+            // 4xx / 5xx → fail.
+            try {
+                await res.body?.cancel();
+            }
+            catch { /* noop */ }
+            return { url, ok: false, status: res.status, reason: `HTTP ${res.status}` };
+        }
+        catch (e) {
+            return { url, ok: false, status: lastStatus, reason: e instanceof Error ? e.message : String(e) };
+        }
+        finally {
+            if (dispatcher)
+                await dispatcher.close();
+        }
+    }
+    return { url, ok: false, status: lastStatus, reason: `exceeded ${MAX_REDIRECT_HOPS} redirects` };
+}
+export async function checkUrlsForEntries(entries, opts = {}) {
+    const out = [];
+    let ok = true;
+    for (const e of entries) {
+        for (const url of e.sourceUrls) {
+            const r = await checkOneUrl(url, opts);
+            out.push({ ...r, file: e.file });
+            if (!r.ok)
+                ok = false;
+        }
+    }
+    return { ok, results: out };
+}
+//# sourceMappingURL=link-check.js.map

package/dist/knowledge-freshness/gates/link-check.js.map

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

package/dist/knowledge-freshness/gates/link-check.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=link-check.test.d.ts.map

package/dist/knowledge-freshness/gates/link-check.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-check.test.d.ts","sourceRoot":"","sources":["../../../src/knowledge-freshness/gates/link-check.test.ts"],"names":[],"mappings":""}

package/dist/knowledge-freshness/gates/link-check.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi } from 'vitest';
+import { checkOneUrl, checkUrlsForEntries } from './link-check.js';
+const allowResolver = async () => ['93.184.216.34'];
+describe('checkOneUrl', () => {
+    it('returns ok for a 200 HEAD', async () => {
+        const fetchImpl = vi.fn(async () => new Response(null, { status: 200 }));
+        const r = await checkOneUrl('https://example.com/a', { resolver: allowResolver, fetchImpl });
+        expect(r.ok).toBe(true);
+        expect(r.status).toBe(200);
+    });
+    it('falls back to GET-Range when HEAD returns 405', async () => {
+        const calls = [];
+        const fetchImpl = vi.fn(async (_url, init) => {
+            calls.push({ method: String(init.method) });
+            if (init.method === 'HEAD')
+                return new Response(null, { status: 405 });
+            return new Response('partial', { status: 206 });
+        });
+        const r = await checkOneUrl('https://example.com/a', { resolver: allowResolver, fetchImpl });
+        expect(r.ok).toBe(true);
+        expect(r.status).toBe(206);
+        expect(calls.map((c) => c.method)).toEqual(['HEAD', 'GET']);
+    });
+    it('fails on 404', async () => {
+        const fetchImpl = vi.fn(async () => {
+            // HEAD returns 404 → falls back to GET, which also returns 404.
+            return new Response(null, { status: 404 });
+        });
+        const r = await checkOneUrl('https://example.com/missing', { resolver: allowResolver, fetchImpl });
+        expect(r.ok).toBe(false);
+        expect(r.status).toBe(404);
+    });
+    it('follows a 301 redirect', async () => {
+        let hop = 0;
+        const fetchImpl = vi.fn(async () => {
+            hop++;
+            if (hop === 1)
+                return new Response(null, { status: 301, headers: { Location: 'https://example.com/b' } });
+            return new Response(null, { status: 200 });
+        });
+        const r = await checkOneUrl('https://example.com/a', { resolver: allowResolver, fetchImpl });
+        expect(r.ok).toBe(true);
+        expect(r.status).toBe(200);
+    });
+    it('honors the operator skip list', async () => {
+        const fetchImpl = vi.fn();
+        const r = await checkOneUrl('https://flaky.example.com/x', {
+            resolver: allowResolver, fetchImpl, skip: ['flaky.example.com'],
+        });
+        expect(r.skipped).toBe(true);
+        expect(r.ok).toBe(true);
+        expect(fetchImpl).not.toHaveBeenCalled();
+    });
+    it('rejects SSRF targets via the validator', async () => {
+        const fetchImpl = vi.fn();
+        const r = await checkOneUrl('http://localhost/x', { resolver: allowResolver, fetchImpl });
+        expect(r.ok).toBe(false);
+        expect(r.reason).toMatch(/localhost|SSRF|blocked/i);
+        expect(fetchImpl).not.toHaveBeenCalled();
+    });
+});
+describe('checkUrlsForEntries', () => {
+    it('aggregates ok=false when any URL fails', async () => {
+        const fetchImpl = vi.fn(async (url) => {
+            if (url.endsWith('/bad'))
+                return new Response(null, { status: 404 });
+            return new Response(null, { status: 200 });
+        });
+        const out = await checkUrlsForEntries([
+            { file: 'a.md', sourceUrls: ['https://example.com/good', 'https://example.com/bad'] },
+        ], { resolver: allowResolver, fetchImpl });
+        expect(out.ok).toBe(false);
+        expect(out.results.find((r) => r.url.endsWith('/bad'))?.ok).toBe(false);
+    });
+});
+//# sourceMappingURL=link-check.test.js.map

package/dist/knowledge-freshness/gates/link-check.test.js.map

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