project-tiny-context-harness 0.8.16 → 0.11.0

package/dist/lib/context-register/context-register-render.js

@@ -0,0 +1,21 @@
+export function renderContextRegisterText(result) {
+    const lines = [
+        `Context register ${result.applied ? "committed" : "dry-run"}`,
+        `Path: ${result.path}`,
+        `Role: ${result.role}`,
+        `Read policy: ${result.read_policy}`,
+        `Manifest: ${result.manifest.before_sha256} -> ${result.manifest.after_sha256} (${signed(result.manifest.bytes_delta)} bytes)`,
+        `Default footprint: ${result.default_footprint.before.path_count}/${result.default_footprint.before.bytes} -> ${result.default_footprint.after.path_count}/${result.default_footprint.after.bytes}`,
+        `Transaction: ${result.transaction.id} (${result.transaction.state})`,
+        "",
+        result.manifest.diff.trimEnd(),
+    ];
+    for (const diagnostic of result.diagnostics)
+        lines.push(`warning: ${diagnostic}`);
+    if (!result.applied)
+        lines.push("", "No files changed. Re-run with --apply to commit this exact plan after a fresh CAS check.");
+    return `${lines.join("\n")}\n`;
+}
+function signed(value) {
+    return value >= 0 ? `+${value}` : String(value);
+}

package/dist/lib/context-register/context-register-support.d.ts

@@ -0,0 +1,6 @@
+import type { CatalogFile, ContextCatalog } from "../context-catalog/catalog-types.js";
+import type { NormalizedRegisterInput } from "./context-register-input.js";
+export declare function assertRegistrationTarget(catalog: ContextCatalog, contextPath: string): CatalogFile;
+export declare function assertStagedRegistration(catalog: ContextCatalog, input: NormalizedRegisterInput): void;
+export declare function readContextContent(repository: string, file: CatalogFile): Promise<string>;
+export declare function renderAppendDiff(file: string, block: string): string;

package/dist/lib/context-register/context-register-support.js

@@ -0,0 +1,46 @@
+import { readFile } from "node:fs/promises";
+import { portableContextPathCaseKey } from "../context-catalog/catalog-paths.js";
+import { decodeMutationUtf8, mutationCatalogFailure, mutationIoFailure, mutationMessage, } from "../context-mutation/mutation-command-support.js";
+import { assertProtectedRepositoryFile } from "../repository-path-safety.js";
+export function assertRegistrationTarget(catalog, contextPath) {
+    const folded = portableContextPathCaseKey(contextPath);
+    const registered = catalog.registered_contexts.find((entry) => portableContextPathCaseKey(entry.path) === folded);
+    if (registered)
+        mutationCatalogFailure(`Context is already registered as ${registered.path}`);
+    const file = catalog.unregistered_context_files.find((entry) => portableContextPathCaseKey(entry.path) === folded);
+    if (!file)
+        mutationIoFailure(`context register requires an existing unregistered file: ${contextPath}`);
+    if (file.path !== contextPath)
+        mutationIoFailure(`context register path case does not match existing file: ${file.path}`);
+    return file;
+}
+export function assertStagedRegistration(catalog, input) {
+    const matches = catalog.registered_contexts.filter((entry) => entry.source === "context" && entry.path === input.path);
+    if (matches.length !== 1)
+        mutationCatalogFailure("staged registration is not unique");
+    if (matches[0].role !== input.role ||
+        matches[0].read_policy !== input.read_policy)
+        mutationCatalogFailure("staged registration metadata does not match the request");
+}
+export async function readContextContent(repository, file) {
+    try {
+        const absolute = await assertProtectedRepositoryFile(repository, file.absolute_path, "context_register_source");
+        return decodeMutationUtf8(await readFile(absolute), file.path);
+    }
+    catch (error) {
+        mutationIoFailure(`unable to read Context registration source: ${mutationMessage(error)}`, error);
+    }
+}
+export function renderAppendDiff(file, block) {
+    return [
+        `--- ${file}`,
+        `+++ ${file}`,
+        "@@ append context @@",
+        ...block
+            .replace(/\r\n/gu, "\n")
+            .trimEnd()
+            .split("\n")
+            .map((line) => `+${line}`),
+        "",
+    ].join("\n");
+}

package/dist/lib/context-register/context-register-types.d.ts

@@ -0,0 +1,46 @@
+import type { ContextRole } from "../context-catalog/catalog-portable-contract.js";
+import type { ContextFootprintState } from "../context-mutation/mutation-types.js";
+export interface ContextRegisterInput {
+    project_root: string;
+    context_path: string;
+    role: string;
+    read_policy?: string;
+    read_when?: string;
+    triggers?: string[];
+    default_children?: string[];
+    apply?: boolean;
+}
+export interface ContextRegisterResult {
+    schema_version: 1;
+    operation: "register";
+    applied: boolean;
+    path: string;
+    role: ContextRole;
+    read_policy: "default" | "on-demand";
+    manifest: {
+        path: "project_context/context.toml";
+        before_sha256: string;
+        after_sha256: string;
+        before_bytes: number;
+        after_bytes: number;
+        bytes_delta: number;
+        diff: string;
+    };
+    default_footprint: {
+        changed: boolean;
+        before: ContextFootprintState;
+        after: ContextFootprintState;
+        added: string[];
+        removed: string[];
+    };
+    catalog: {
+        before_identity: string;
+        after_identity: string;
+    };
+    diagnostics: string[];
+    transaction: {
+        id: string;
+        state: "dry-run" | "committed";
+        journal_present: false;
+    };
+}

package/dist/lib/context-register/context-register-types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/context-register/context-register.d.ts

@@ -0,0 +1,8 @@
+import type { ContextMutationPlan } from "../context-mutation/mutation-types.js";
+import type { ContextRegisterInput, ContextRegisterResult } from "./context-register-types.js";
+export declare function registerContext(input: ContextRegisterInput): Promise<ContextRegisterResult>;
+export interface PlannedContextRegistration {
+    plan: ContextMutationPlan;
+    result: ContextRegisterResult;
+}
+export declare function planContextRegistration(input: ContextRegisterInput): Promise<PlannedContextRegistration>;

package/dist/lib/context-register/context-register.js

@@ -0,0 +1,155 @@
+import { appendContextManifestBlock, } from "../context-mutation/manifest-lossless-patch.js";
+import { captureMutationFileState, mutationFileStateFromBytes, mutationTemporaryPath, } from "../context-mutation/mutation-cas.js";
+import { executeContextMutationPlan } from "../context-mutation/mutation-commit.js";
+import { assertMutationCatalogValid, assertNoUnfinishedContextMutation, decodeMutationUtf8, loadMutationCatalog, mutationCatalogFailure, mutationIoFailure, mutationMessage, mutationStateBytes, sameMutationArray, } from "../context-mutation/mutation-command-support.js";
+import { contextCatalogIdentity, contextFootprintState, stagedFileOverrides, } from "../context-mutation/mutation-staged-fs.js";
+import { canonicalValueJson, sha256Hex } from "../strict-codec.js";
+import { CliCommandError } from "../cli-exit.js";
+import { validateContextRegistrationContent } from "../validators.js";
+import { normalizeContextRegisterInput } from "./context-register-input.js";
+import { assertRegistrationTarget, assertStagedRegistration, readContextContent, renderAppendDiff, } from "./context-register-support.js";
+const MANIFEST_PATH = "project_context/context.toml";
+export async function registerContext(input) {
+    const planned = await planContextRegistration(input);
+    if (!input.apply)
+        return planned.result;
+    try {
+        await executeContextMutationPlan(input.project_root, planned.plan);
+    }
+    catch (error) {
+        if (error instanceof CliCommandError)
+            throw error;
+        mutationIoFailure(`context register transaction stopped: ${mutationMessage(error)}; inspect recovery with ty-context context transaction status`, error);
+    }
+    return {
+        ...planned.result,
+        applied: true,
+        transaction: {
+            ...planned.result.transaction,
+            state: "committed",
+        },
+    };
+}
+export async function planContextRegistration(input) {
+    const normalized = normalizeContextRegisterInput(input);
+    await assertNoUnfinishedContextMutation(input.project_root);
+    const beforeCatalog = await loadMutationCatalog(input.project_root);
+    assertMutationCatalogValid(beforeCatalog, "context register requires a valid Catalog");
+    const registrationFile = assertRegistrationTarget(beforeCatalog, normalized.path);
+    const manifestBefore = await captureMutationFileState(input.project_root, MANIFEST_PATH);
+    if (!manifestBefore.exists || manifestBefore.mode === null)
+        mutationCatalogFailure("project_context/context.toml is missing");
+    const manifestText = decodeMutationUtf8(mutationStateBytes(manifestBefore), MANIFEST_PATH);
+    if (manifestText !== beforeCatalog.manifest_content)
+        mutationIoFailure("Context Catalog changed while planning register");
+    const contextContent = await readContextContent(input.project_root, registrationFile);
+    const recoveryErrors = validateContextRegistrationContent(input.project_root, normalized.path, contextContent, normalized.role, normalized.read_policy);
+    if (recoveryErrors.length)
+        mutationCatalogFailure(`Context is not recoverable for registration: ${recoveryErrors.join("; ")}`);
+    const manifestPatchInput = {
+        path: normalized.path,
+        role: normalized.role,
+        read_policy: normalized.read_policy,
+        read_when: normalized.read_when,
+        triggers: normalized.triggers,
+        default_children: normalized.default_children,
+    };
+    let patch;
+    try {
+        patch = appendContextManifestBlock(manifestText, manifestPatchInput);
+    }
+    catch (error) {
+        mutationCatalogFailure(`Manifest cannot be patched losslessly: ${mutationMessage(error)}`, error);
+    }
+    const afterBytes = Buffer.from(patch.content, "utf8");
+    const overrides = stagedFileOverrides([[MANIFEST_PATH, afterBytes]]);
+    const afterCatalog = await loadMutationCatalog(input.project_root, overrides);
+    assertMutationCatalogValid(afterCatalog, "staged Context registration is invalid");
+    assertStagedRegistration(afterCatalog, normalized);
+    const beforeFootprint = contextFootprintState(beforeCatalog);
+    const afterFootprint = contextFootprintState(afterCatalog);
+    const afterState = mutationFileStateFromBytes(afterBytes, manifestBefore.mode);
+    const operationData = {
+        kind: "register",
+        context_path: normalized.path,
+        role: normalized.role,
+        read_policy: normalized.read_policy,
+        expected_default_paths: afterFootprint.paths,
+        expected_default_bytes: afterFootprint.bytes,
+    };
+    const catalogBeforeIdentity = contextCatalogIdentity(beforeCatalog);
+    const catalogAfterIdentity = contextCatalogIdentity(afterCatalog);
+    const transactionId = sha256Hex(canonicalValueJson({
+        operation: "register",
+        catalog_before_identity: catalogBeforeIdentity,
+        catalog_after_identity: catalogAfterIdentity,
+        file: {
+            path: MANIFEST_PATH,
+            before_sha256: manifestBefore.sha256,
+            after_sha256: afterState.sha256,
+            mode: manifestBefore.mode,
+        },
+        operation_data: operationData,
+    }));
+    const plan = {
+        transaction_id: transactionId,
+        operation: "register",
+        catalog_before_identity: catalogBeforeIdentity,
+        catalog_after_identity: catalogAfterIdentity,
+        directories: [],
+        files: [
+            {
+                path: MANIFEST_PATH,
+                physical_path: MANIFEST_PATH,
+                before: manifestBefore,
+                after: afterState,
+                commit_order: 0,
+                temporary_path: mutationTemporaryPath(MANIFEST_PATH, transactionId, 0),
+                temporary_state: null,
+                published_before: null,
+                published_after: null,
+            },
+        ],
+        operation_data: operationData,
+    };
+    return {
+        plan,
+        result: {
+            schema_version: 1,
+            operation: "register",
+            applied: false,
+            path: normalized.path,
+            role: normalized.role,
+            read_policy: normalized.read_policy,
+            manifest: {
+                path: MANIFEST_PATH,
+                before_sha256: manifestBefore.sha256,
+                after_sha256: afterState.sha256,
+                before_bytes: mutationStateBytes(manifestBefore).length,
+                after_bytes: afterBytes.length,
+                bytes_delta: afterBytes.length - mutationStateBytes(manifestBefore).length,
+                diff: renderAppendDiff(MANIFEST_PATH, patch.inserted_block),
+            },
+            default_footprint: {
+                changed: beforeFootprint.bytes !== afterFootprint.bytes ||
+                    !sameMutationArray(beforeFootprint.paths, afterFootprint.paths),
+                before: beforeFootprint,
+                after: afterFootprint,
+                added: afterFootprint.paths.filter((file) => !beforeFootprint.paths.includes(file)),
+                removed: beforeFootprint.paths.filter((file) => !afterFootprint.paths.includes(file)),
+            },
+            catalog: {
+                before_identity: catalogBeforeIdentity,
+                after_identity: catalogAfterIdentity,
+            },
+            diagnostics: afterCatalog.diagnostics
+                .filter((entry) => entry.severity === "warning")
+                .map((entry) => entry.message),
+            transaction: {
+                id: transactionId,
+                state: "dry-run",
+                journal_present: false,
+            },
+        },
+    };
+}

package/dist/lib/context-router/context-route-budget.d.ts

@@ -0,0 +1,15 @@
+export declare const CONTEXT_ROUTE_SCHEMA_VERSION = 1;
+export declare const CONTEXT_ROUTE_BUDGETS: Readonly<{
+    readonly task_utf8_bytes: number;
+    readonly automatic_terms: 32;
+    readonly explicit_terms: 32;
+    readonly automatic_term_min_code_points: 2;
+    readonly explicit_term_min_code_points: 1;
+    readonly term_max_code_points: 128;
+    readonly candidate_files: 4096;
+    readonly per_file_scan_bytes: number;
+    readonly aggregate_scan_bytes: number;
+    readonly output_matches: 200;
+    readonly per_file_output_matches: 20;
+}>;
+export type ContextRouteBudgetName = keyof typeof CONTEXT_ROUTE_BUDGETS;

package/dist/lib/context-router/context-route-budget.js

@@ -0,0 +1,14 @@
+export const CONTEXT_ROUTE_SCHEMA_VERSION = 1;
+export const CONTEXT_ROUTE_BUDGETS = Object.freeze({
+    task_utf8_bytes: 8 * 1024,
+    automatic_terms: 32,
+    explicit_terms: 32,
+    automatic_term_min_code_points: 2,
+    explicit_term_min_code_points: 1,
+    term_max_code_points: 128,
+    candidate_files: 4096,
+    per_file_scan_bytes: 1024 * 1024,
+    aggregate_scan_bytes: 32 * 1024 * 1024,
+    output_matches: 200,
+    per_file_output_matches: 20,
+});

package/dist/lib/context-router/context-route-candidates.d.ts

@@ -0,0 +1,15 @@
+import type { CatalogFile, CatalogRegisteredContext, ContextCatalog } from "../context-catalog/catalog-types.js";
+import type { ContextRouteBudgetExceeded, ContextRouteCandidate, ContextRouteDefaultEntry, ContextRouteGroup, ContextRouteReason, ContextRouteResult } from "./context-route-types.js";
+export interface MutableCandidate extends Omit<ContextRouteCandidate, "cumulative_bytes"> {
+    group_set: Set<ContextRouteGroup>;
+    reason_keys: Set<string>;
+}
+export declare function addReason(candidates: Map<string, MutableCandidate>, catalog: ContextCatalog, filesByPath: Map<string, CatalogFile>, registeredByPath: Map<string, CatalogRegisteredContext>, contextPath: string, reason: ContextRouteReason, group?: ContextRouteGroup, matchedPath?: string): MutableCandidate;
+export declare function projectCandidates(values: MutableCandidate[]): ContextRouteCandidate[];
+export declare function defaultEntries(catalog: ContextCatalog): ContextRouteDefaultEntry[];
+export declare function emptyResult(input: {
+    catalog: ContextCatalog;
+    caseSensitive: boolean;
+    defaultContext: ContextRouteDefaultEntry[];
+    exceeded: ContextRouteBudgetExceeded[];
+}): ContextRouteResult;

package/dist/lib/context-router/context-route-candidates.js

@@ -0,0 +1,112 @@
+import { compareUtf8Paths } from "../context-catalog/catalog-paths.js";
+import { CONTEXT_LEGACY_READ_POLICY_SET } from "../context-catalog/catalog-portable-contract.js";
+import { CONTEXT_ROUTE_SCHEMA_VERSION } from "./context-route-budget.js";
+import { compareRouteReasons, sortRouteGroups, stableRouteBudgetExceeded, } from "./context-route-order.js";
+export function addReason(candidates, catalog, filesByPath, registeredByPath, contextPath, reason, group, matchedPath) {
+    const registered = registeredByPath.get(contextPath);
+    const file = filesByPath.get(contextPath);
+    const current = candidates.get(contextPath) ??
+        createCandidate(catalog, registered, file, contextPath);
+    if (group)
+        current.group_set.add(group);
+    if (matchedPath && !current.matched_paths.includes(matchedPath))
+        current.matched_paths.push(matchedPath);
+    const reasonKey = `${reason.kind}\0${reason.input}\0${reason.detail}`;
+    if (!current.reason_keys.has(reasonKey)) {
+        current.reason_keys.add(reasonKey);
+        current.reasons.push(reason);
+    }
+    candidates.set(contextPath, current);
+    return current;
+}
+export function projectCandidates(values) {
+    const result = [...values].sort((left, right) => compareUtf8Paths(left.path, right.path));
+    let cumulative = 0;
+    return result.map(({ group_set, reason_keys: _reasonKeys, ...entry }) => {
+        cumulative += entry.bytes;
+        return {
+            ...entry,
+            groups: sortRouteGroups(group_set),
+            reasons: [...entry.reasons].sort(compareRouteReasons),
+            matched_paths: [...entry.matched_paths].sort(compareUtf8Paths),
+            cumulative_bytes: cumulative,
+        };
+    });
+}
+export function defaultEntries(catalog) {
+    const files = new Map(catalog.context_files.map((entry) => [entry.path, entry]));
+    const values = [...catalog.default_footprint.entries()].sort(([left], [right]) => compareUtf8Paths(left, right));
+    let cumulative = 0;
+    return values.map(([contextPath, reasons]) => {
+        const bytes = contextPath === catalog.manifest_path
+            ? Buffer.byteLength(catalog.manifest_content ?? "", "utf8")
+            : (files.get(contextPath)?.bytes ?? 0);
+        cumulative += bytes;
+        return {
+            path: contextPath,
+            reasons: [...reasons].sort(compareUtf8Paths),
+            bytes,
+            cumulative_bytes: cumulative,
+        };
+    });
+}
+export function emptyResult(input) {
+    return {
+        schema_version: CONTEXT_ROUTE_SCHEMA_VERSION,
+        complete: false,
+        catalog_valid: false,
+        experimental: true,
+        authority: false,
+        workflow_search_replaced: false,
+        matching: {
+            literal: true,
+            unicode_normalization: "NFC",
+            case_sensitive: input.caseSensitive,
+        },
+        scan: {
+            files_considered: input.catalog.context_files.length,
+            files_scanned: 0,
+            bytes_scanned: 0,
+            budget_exceeded: input.exceeded.length > 0,
+            exceeded: stableRouteBudgetExceeded(input.exceeded),
+        },
+        output_truncated: false,
+        default_context: input.defaultContext,
+        candidates: [],
+        unregistered_matches: [],
+        ambiguous: [],
+        unresolved: [],
+        diagnostics: input.catalog.diagnostics,
+    };
+}
+function createCandidate(catalog, registered, file, contextPath) {
+    const groups = classificationGroups(catalog, registered, contextPath);
+    const unregistered = catalog.unregistered_context_files.some((entry) => entry.path === contextPath);
+    return {
+        path: contextPath,
+        registration: unregistered ? "unregistered" : "registered",
+        role: registered?.role ?? null,
+        read_policy: registered?.read_policy ?? null,
+        groups,
+        group_set: new Set(groups),
+        reasons: [],
+        reason_keys: new Set(),
+        matched_terms: [],
+        matched_paths: [],
+        matches: [],
+        bytes: file?.bytes ?? 0,
+    };
+}
+function classificationGroups(catalog, registered, contextPath) {
+    if (catalog.unregistered_context_files.some((entry) => entry.path === contextPath))
+        return ["unregistered"];
+    const groups = [];
+    if (catalog.default_footprint.has(contextPath))
+        groups.push("default_registered");
+    if (registered?.read_policy &&
+        CONTEXT_LEGACY_READ_POLICY_SET.has(registered.read_policy))
+        groups.push("legacy_registered");
+    else if (!catalog.default_footprint.has(contextPath))
+        groups.push("on_demand_registered");
+    return groups;
+}

package/dist/lib/context-router/context-route-order.d.ts

@@ -0,0 +1,6 @@
+import type { ContextRouteAmbiguity, ContextRouteBudgetExceeded, ContextRouteGroup, ContextRouteReason, ContextRouteUnresolved } from "./context-route-types.js";
+export declare function compareRouteReasons(left: ContextRouteReason, right: ContextRouteReason): number;
+export declare function sortRouteGroups(groups: Iterable<ContextRouteGroup>): ContextRouteGroup[];
+export declare function stableRouteBudgetExceeded(values: readonly ContextRouteBudgetExceeded[]): ContextRouteBudgetExceeded[];
+export declare function compareRouteAmbiguities(left: ContextRouteAmbiguity, right: ContextRouteAmbiguity): number;
+export declare function compareRouteUnresolved(left: ContextRouteUnresolved, right: ContextRouteUnresolved): number;

package/dist/lib/context-router/context-route-order.js

@@ -0,0 +1,53 @@
+import { compareUtf8Paths, normalizeContextPath, } from "../context-catalog/catalog-paths.js";
+export function compareRouteReasons(left, right) {
+    return (compareUtf8Paths(left.kind, right.kind) ||
+        compareUtf8Paths(left.input, right.input) ||
+        compareUtf8Paths(left.detail, right.detail));
+}
+export function sortRouteGroups(groups) {
+    return [...groups].sort(compareUtf8Paths);
+}
+export function stableRouteBudgetExceeded(values) {
+    const merged = new Map();
+    for (const entry of values) {
+        const normalized = {
+            ...entry,
+            ...(entry.path ? { path: normalizeContextPath(entry.path) } : {}),
+        };
+        const key = `${normalized.budget}\0${normalized.path ?? ""}`;
+        const current = merged.get(key);
+        merged.set(key, current
+            ? {
+                ...normalized,
+                limit: Math.min(current.limit, normalized.limit),
+                observed: Math.max(current.observed, normalized.observed),
+            }
+            : normalized);
+    }
+    return [...merged.values()].sort((left, right) => compareUtf8Paths(left.budget, right.budget) ||
+        compareUtf8Paths(left.path ?? "", right.path ?? "") ||
+        left.limit - right.limit ||
+        left.observed - right.observed);
+}
+export function compareRouteAmbiguities(left, right) {
+    return (compareUtf8Paths(left.kind, right.kind) ||
+        compareUtf8Paths(left.input, right.input) ||
+        compareAreaCandidateLists(left.candidates, right.candidates) ||
+        compareUtf8Paths(left.reason, right.reason));
+}
+export function compareRouteUnresolved(left, right) {
+    return (compareUtf8Paths(left.kind, right.kind) ||
+        compareUtf8Paths(left.input, right.input) ||
+        compareUtf8Paths(left.reason, right.reason));
+}
+function compareAreaCandidateLists(left, right) {
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        const comparison = compareUtf8Paths(left[index].root, right[index].root) ||
+            compareUtf8Paths(left[index].id, right[index].id) ||
+            compareUtf8Paths(left[index].context, right[index].context);
+        if (comparison !== 0)
+            return comparison;
+    }
+    return left.length - right.length;
+}

package/dist/lib/context-router/context-route-paths.d.ts

@@ -0,0 +1,16 @@
+import type { CatalogFile, ContextCatalog } from "../context-catalog/catalog-types.js";
+import type { ContextRouteAmbiguity, ContextRouteAreaCandidate, ContextRouteUnresolved } from "./context-route-types.js";
+export interface ContextRoutePathMatch {
+    input: string;
+    normalized_path: string;
+    area: ContextRouteAreaCandidate;
+}
+export interface ContextRoutePathResult {
+    matches: ContextRoutePathMatch[];
+    ambiguous: ContextRouteAmbiguity[];
+    unresolved: ContextRouteUnresolved[];
+}
+export declare function matchContextAreas(catalog: ContextCatalog, inputs: string[]): ContextRoutePathResult;
+export declare function resolveManualIncludes(catalog: ContextCatalog, inputs: string[]): Promise<CatalogFile[]>;
+export declare function normalizeRepositoryInput(value: string, flag: string): string;
+export declare function normalizeRepositoryInputs(values: readonly string[], flag: string): string[];

package/dist/lib/context-router/context-route-paths.js

@@ -0,0 +1,109 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+import { CLI_EXIT_CODES, CliCommandError } from "../cli-exit.js";
+import { compareUtf8Paths, isPathWithin, normalizeContextPath, resolveProjectPath, } from "../context-catalog/catalog-paths.js";
+import { compareRouteAmbiguities, compareRouteUnresolved, } from "./context-route-order.js";
+export function matchContextAreas(catalog, inputs) {
+    const matches = [];
+    const ambiguous = [];
+    const unresolved = [];
+    for (const normalized of normalizeRepositoryInputs(inputs, "--path")) {
+        const candidates = catalog.areas
+            .map((area) => ({
+            id: area.id.normalize("NFC"),
+            root: normalizeAreaRoot(area.root),
+            context: normalizeContextPath(area.context),
+        }))
+            .filter((area) => areaContains(area.root, normalized));
+        if (candidates.length === 0) {
+            unresolved.push({
+                kind: "path",
+                input: normalized,
+                reason: "no Area root contains the repository-relative path",
+            });
+            continue;
+        }
+        const maximum = Math.max(...candidates.map(areaScore));
+        const deepest = candidates
+            .filter((area) => areaScore(area) === maximum)
+            .sort((left, right) => compareUtf8Paths(`${left.root}\0${left.id}\0${left.context}`, `${right.root}\0${right.id}\0${right.context}`));
+        if (deepest.length > 1) {
+            ambiguous.push({
+                kind: "area_path",
+                input: normalized,
+                candidates: deepest,
+                reason: "multiple Area roots tie at the deepest matching root",
+            });
+            continue;
+        }
+        matches.push({
+            input: normalized,
+            normalized_path: normalized,
+            area: deepest[0],
+        });
+    }
+    return {
+        matches: matches.sort(comparePathMatches),
+        ambiguous: ambiguous.sort(compareRouteAmbiguities),
+        unresolved: unresolved.sort(compareRouteUnresolved),
+    };
+}
+export async function resolveManualIncludes(catalog, inputs) {
+    const files = new Map(catalog.context_files.map((file) => [file.path, file]));
+    const contextRoot = resolveProjectPath(catalog.project_root, "project_context");
+    const realContextRoot = await realpath(contextRoot);
+    const result = new Map();
+    for (const normalized of normalizeRepositoryInputs(inputs, "--include")) {
+        if (!normalized.startsWith("project_context/") ||
+            !normalized.endsWith(".md"))
+            throw new CliCommandError(CLI_EXIT_CODES.io, `route include must name an existing Markdown file under project_context/: ${normalized}`);
+        const file = files.get(normalized);
+        if (!file)
+            throw new CliCommandError(CLI_EXIT_CODES.io, `route include is missing or is not an eligible Context file: ${normalized}`);
+        const metadata = await lstat(file.absolute_path);
+        if (!metadata.isFile() || metadata.isSymbolicLink())
+            throw new CliCommandError(CLI_EXIT_CODES.io, `route include must be a regular no-follow file: ${normalized}`);
+        const identity = await realpath(file.absolute_path);
+        if (!isPathWithin(realContextRoot, identity))
+            throw new CliCommandError(CLI_EXIT_CODES.io, `route include resolves outside project_context/: ${normalized}`);
+        result.set(normalized, file);
+    }
+    return [...result.values()].sort((left, right) => compareUtf8Paths(left.path, right.path));
+}
+export function normalizeRepositoryInput(value, flag) {
+    const normalized = normalizeContextPath(value.trim());
+    if (!normalized)
+        throw new CliCommandError(CLI_EXIT_CODES.arguments, `route ${flag} requires a non-empty repository-relative path`);
+    if (path.posix.isAbsolute(normalized) ||
+        path.win32.isAbsolute(normalized) ||
+        normalized.split("/").includes("..") ||
+        /^[A-Za-z]:/u.test(normalized))
+        throw new CliCommandError(CLI_EXIT_CODES.io, `route ${flag} path must stay repository-relative: ${value}`);
+    return normalized;
+}
+export function normalizeRepositoryInputs(values, flag) {
+    return [
+        ...new Set(values.map((value) => normalizeRepositoryInput(value, flag))),
+    ].sort(compareUtf8Paths);
+}
+function normalizeAreaRoot(value) {
+    const normalized = normalizeContextPath(value.trim());
+    return normalized === "" || normalized === "."
+        ? "."
+        : normalized.replace(/\/$/u, "");
+}
+function comparePathMatches(left, right) {
+    return (compareUtf8Paths(left.normalized_path, right.normalized_path) ||
+        compareUtf8Paths(left.area.root, right.area.root) ||
+        compareUtf8Paths(left.area.id, right.area.id) ||
+        compareUtf8Paths(left.area.context, right.area.context));
+}
+function areaContains(root, candidate) {
+    return root === "." || candidate === root || candidate.startsWith(`${root}/`);
+}
+function areaScore(area) {
+    if (area.root === ".")
+        return 0;
+    const depth = area.root.split("/").length;
+    return depth * 1_000_000 + Buffer.byteLength(area.root, "utf8");
+}

package/dist/lib/context-router/context-route-render.d.ts

@@ -0,0 +1,2 @@
+import type { ContextRouteResult } from "./context-route-types.js";
+export declare function renderContextRouteText(result: ContextRouteResult, explain: boolean): string;