clinkx 0.2.3 → 0.3.0

package/dist/context-builder/progress.js

@@ -0,0 +1,70 @@
+import { logger } from "../logger.js";
+import { sanitizeProgressMessage } from "./diagnostics.js";
+const STAGE_PROGRESS = Object.freeze({
+    validating: 5,
+    scanning: 20,
+    searching: 40,
+    selecting: 60,
+    curating: 72,
+    finalizing: 84,
+    writing: 94,
+    complete: 100,
+});
+const STAGE_ORDER = Object.freeze({
+    validating: 0,
+    scanning: 1,
+    searching: 2,
+    selecting: 3,
+    curating: 4,
+    finalizing: 5,
+    writing: 6,
+    complete: 7,
+});
+const STAGE_MESSAGES = Object.freeze({
+    validating: "context_builder validating",
+    scanning: "context_builder scanning",
+    searching: "context_builder searching",
+    selecting: "context_builder selecting",
+    curating: "context_builder curating",
+    finalizing: "context_builder finalizing",
+    writing: "context_builder writing",
+    complete: "context_builder complete",
+});
+export class ContextBuilderProgressReporter {
+    target;
+    highestEmitted = -1;
+    chain = Promise.resolve();
+    constructor(target) {
+        this.target = target;
+    }
+    emit(stage) {
+        const next = this.chain.then(() => this.emitNow(stage));
+        this.chain = next.catch(() => { });
+        return next;
+    }
+    async emitNow(stage) {
+        const order = STAGE_ORDER[stage];
+        if (order <= this.highestEmitted) {
+            return;
+        }
+        try {
+            await this.target.server.notification({
+                method: "notifications/progress",
+                params: {
+                    progressToken: this.target.token,
+                    progress: STAGE_PROGRESS[stage],
+                    total: 100,
+                    message: sanitizeProgressMessage(STAGE_MESSAGES[stage]),
+                },
+            });
+            this.highestEmitted = order;
+        }
+        catch (err) {
+            logger.warn({ err, stage }, "failed to send context_builder progress");
+        }
+    }
+}
+export function createContextBuilderProgressReporter(target) {
+    return target == null ? undefined : new ContextBuilderProgressReporter(target);
+}
+//# sourceMappingURL=progress.js.map

package/dist/context-builder/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../src/context-builder/progress.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAiB3D,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IACnC,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,EAAE;IACZ,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,QAAQ,EAAE,EAAE;IACZ,UAAU,EAAE,EAAE;IACd,OAAO,EAAE,EAAE;IACX,QAAQ,EAAE,GAAG;CACwC,CAAC,CAAC;AAEzD,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC;IAChC,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,CAAC;IACX,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,CAAC;IACZ,QAAQ,EAAE,CAAC;IACX,UAAU,EAAE,CAAC;IACb,OAAO,EAAE,CAAC;IACV,QAAQ,EAAE,CAAC;CAC0C,CAAC,CAAC;AAEzD,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IACnC,UAAU,EAAE,4BAA4B;IACxC,QAAQ,EAAE,0BAA0B;IACpC,SAAS,EAAE,2BAA2B;IACtC,SAAS,EAAE,2BAA2B;IACtC,QAAQ,EAAE,0BAA0B;IACpC,UAAU,EAAE,4BAA4B;IACxC,OAAO,EAAE,yBAAyB;IAClC,QAAQ,EAAE,0BAA0B;CACiB,CAAC,CAAC;AAEzD,MAAM,OAAO,8BAA8B;IAIZ;IAHrB,cAAc,GAAG,CAAC,CAAC,CAAC;IACpB,KAAK,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAEjD,YAA6B,MAAoC;QAApC,WAAM,GAAN,MAAM,CAA8B;IAAG,CAAC;IAErE,IAAI,CAAC,KAAkC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QACxD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,KAAkC;QACtD,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,KAAK,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACjC,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC;gBACpC,MAAM,EAAE,wBAAwB;gBAChC,MAAM,EAAE;oBACN,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK;oBAChC,QAAQ,EAAE,cAAc,CAAC,KAAK,CAAC;oBAC/B,KAAK,EAAE,GAAG;oBACV,OAAO,EAAE,uBAAuB,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;iBACxD;aACF,CAAC,CAAC;YACH,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,yCAAyC,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;CACF;AAED,MAAM,UAAU,oCAAoC,CAClD,MAAgD;IAEhD,OAAO,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,8BAA8B,CAAC,MAAM,CAAC,CAAC;AACjF,CAAC"}

package/dist/context-builder/receipt.d.ts

@@ -0,0 +1,89 @@
+export declare const CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION = 1;
+export declare const CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION = 2;
+export declare const CONTEXT_BUILDER_SCHEMA_VERSION = 1;
+export declare const CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS: readonly ["manifest_json", "bundle_md", "tree_json", "search_jsonl", "slices_jsonl", "codemap_jsonl", "summary_json"];
+export type ContextBuilderArtifactKey = (typeof CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS)[number];
+export declare const CONTEXT_BUILDER_ATTACHABLE_ARTIFACT_KEYS: readonly ["bundle_md", "manifest_json"];
+export declare const CONTEXT_BUILDER_RECEIPT_TOP_LEVEL_KEYS: readonly ["schema_version", "run_id", "status", "artifact_dir", "artifacts", "attachable_file_paths", "recommended_clink", "metrics", "warnings", "omissions"];
+export type ContextBuilderStatus = "succeeded" | "partial";
+export type ContextBuilderReceiptSchemaVersion = typeof CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION | typeof CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION;
+export type ContextBuilderDelegateReceiptMetadata = {
+    enabled: true;
+    status: "succeeded" | "partial" | "failed";
+    failure_policy: "fallback" | "fail";
+    fallback_used: boolean;
+    curator: {
+        cli_name: string;
+        role: string;
+    };
+    finalizer: {
+        cli_name: string;
+        role: string;
+        min_score: number;
+    };
+    finalizer_score?: number;
+    selected_count: number;
+    warning_count: number;
+    omission_count: number;
+    failure_reason?: string;
+};
+export declare const CONTEXT_BUILDER_DELEGATE_METADATA_KEYS: readonly ["enabled", "status", "failure_policy", "fallback_used", "curator", "finalizer", "finalizer_score", "selected_count", "warning_count", "omission_count", "failure_reason"];
+export declare const CONTEXT_BUILDER_DELEGATE_PROVIDER_METADATA_KEYS: readonly ["cli_name", "role"];
+export declare const CONTEXT_BUILDER_DELEGATE_FINALIZER_METADATA_KEYS: readonly ["cli_name", "role", "min_score"];
+export type ContextBuilderMetrics = {
+    files_seen: number;
+    files_considered: number;
+    files_selected: number;
+    files_omitted: number;
+    scan_cap_hit: boolean;
+    search_cap_hit: boolean;
+    discovery_byte_cap_hit: boolean;
+    discovery_candidate_cap_hit: boolean;
+    candidate_cap_hit: boolean;
+    bytes_read: number;
+    bytes_written: number;
+    estimated_tokens: number;
+    truncated: boolean;
+};
+export type ContextBuilderReceipt = {
+    schema_version: ContextBuilderReceiptSchemaVersion;
+    run_id: string;
+    status: ContextBuilderStatus;
+    artifact_dir: string;
+    artifacts: Record<ContextBuilderArtifactKey, string>;
+    attachable_file_paths: string[];
+    recommended_clink: {
+        absolute_file_paths: string[];
+    };
+    metrics: ContextBuilderMetrics;
+    warnings: unknown[];
+    omissions: unknown[];
+} & ({
+    schema_version: typeof CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION;
+    delegate?: never;
+} | {
+    schema_version: typeof CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION;
+    delegate: ContextBuilderDelegateReceiptMetadata;
+});
+export type ContextBuilderReceiptTextResponse = {
+    content: [
+        {
+            type: "text";
+            text: string;
+        }
+    ];
+};
+export declare function createContextBuilderReceipt(input: {
+    run_id: string;
+    status: ContextBuilderStatus;
+    artifact_dir: string;
+    artifacts: Record<ContextBuilderArtifactKey, string>;
+    metrics: ContextBuilderMetrics;
+    warnings?: unknown[];
+    omissions?: unknown[];
+    delegate?: ContextBuilderDelegateReceiptMetadata;
+}): ContextBuilderReceipt;
+export declare function serializeContextBuilderReceipt(receipt: ContextBuilderReceipt): string;
+export declare function createContextBuilderReceiptTextResponse(receipt: ContextBuilderReceipt): ContextBuilderReceiptTextResponse;
+export declare function cloneContextBuilderDelegateReceiptMetadata(delegate: ContextBuilderDelegateReceiptMetadata): ContextBuilderDelegateReceiptMetadata;
+export declare function isContextBuilderDelegateReceiptMetadata(value: unknown): value is ContextBuilderDelegateReceiptMetadata;

package/dist/context-builder/receipt.js

@@ -0,0 +1,169 @@
+export const CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION = 1;
+export const CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION = 2;
+export const CONTEXT_BUILDER_SCHEMA_VERSION = CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION;
+export const CONTEXT_BUILDER_NO_DELEGATE_ARTIFACT_KEYS = [
+    "manifest_json",
+    "bundle_md",
+    "tree_json",
+    "search_jsonl",
+    "slices_jsonl",
+    "codemap_jsonl",
+    "summary_json",
+];
+export const CONTEXT_BUILDER_ATTACHABLE_ARTIFACT_KEYS = [
+    "bundle_md",
+    "manifest_json",
+];
+export const CONTEXT_BUILDER_RECEIPT_TOP_LEVEL_KEYS = [
+    "schema_version",
+    "run_id",
+    "status",
+    "artifact_dir",
+    "artifacts",
+    "attachable_file_paths",
+    "recommended_clink",
+    "metrics",
+    "warnings",
+    "omissions",
+];
+export const CONTEXT_BUILDER_DELEGATE_METADATA_KEYS = [
+    "enabled",
+    "status",
+    "failure_policy",
+    "fallback_used",
+    "curator",
+    "finalizer",
+    "finalizer_score",
+    "selected_count",
+    "warning_count",
+    "omission_count",
+    "failure_reason",
+];
+export const CONTEXT_BUILDER_DELEGATE_PROVIDER_METADATA_KEYS = [
+    "cli_name",
+    "role",
+];
+export const CONTEXT_BUILDER_DELEGATE_FINALIZER_METADATA_KEYS = [
+    "cli_name",
+    "role",
+    "min_score",
+];
+export function createContextBuilderReceipt(input) {
+    const artifacts = { ...input.artifacts };
+    const attachableFilePaths = CONTEXT_BUILDER_ATTACHABLE_ARTIFACT_KEYS.map((key) => artifacts[key]);
+    const baseReceipt = {
+        run_id: input.run_id,
+        status: input.status,
+        artifact_dir: input.artifact_dir,
+        artifacts,
+        attachable_file_paths: [...attachableFilePaths],
+        recommended_clink: {
+            absolute_file_paths: [...attachableFilePaths],
+        },
+        metrics: { ...input.metrics },
+        warnings: [...(input.warnings ?? [])],
+        omissions: [...(input.omissions ?? [])],
+    };
+    if (input.delegate != null) {
+        return {
+            schema_version: CONTEXT_BUILDER_DELEGATE_SCHEMA_VERSION,
+            ...baseReceipt,
+            delegate: cloneContextBuilderDelegateReceiptMetadata(input.delegate),
+        };
+    }
+    return {
+        schema_version: CONTEXT_BUILDER_NO_DELEGATE_SCHEMA_VERSION,
+        ...baseReceipt,
+    };
+}
+export function serializeContextBuilderReceipt(receipt) {
+    return JSON.stringify(receipt);
+}
+export function createContextBuilderReceiptTextResponse(receipt) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: serializeContextBuilderReceipt(receipt),
+            },
+        ],
+    };
+}
+export function cloneContextBuilderDelegateReceiptMetadata(delegate) {
+    return {
+        enabled: delegate.enabled,
+        status: delegate.status,
+        failure_policy: delegate.failure_policy,
+        fallback_used: delegate.fallback_used,
+        curator: { ...delegate.curator },
+        finalizer: { ...delegate.finalizer },
+        ...(delegate.finalizer_score == null
+            ? {}
+            : { finalizer_score: delegate.finalizer_score }),
+        selected_count: delegate.selected_count,
+        warning_count: delegate.warning_count,
+        omission_count: delegate.omission_count,
+        ...(delegate.failure_reason == null
+            ? {}
+            : { failure_reason: delegate.failure_reason }),
+    };
+}
+export function isContextBuilderDelegateReceiptMetadata(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, CONTEXT_BUILDER_DELEGATE_METADATA_KEYS)) {
+        return false;
+    }
+    if (value.enabled !== true
+        || !isDelegateMetadataStatus(value.status)
+        || !isDelegateMetadataFailurePolicy(value.failure_policy)
+        || typeof value.fallback_used !== "boolean"
+        || !isDelegateProviderMetadata(value.curator)
+        || !isDelegateFinalizerMetadata(value.finalizer)
+        || !isNonNegativeInteger(value.selected_count)
+        || !isNonNegativeInteger(value.warning_count)
+        || !isNonNegativeInteger(value.omission_count)) {
+        return false;
+    }
+    if (value.finalizer_score !== undefined
+        && !isFiniteNumber(value.finalizer_score)) {
+        return false;
+    }
+    return (value.failure_reason === undefined
+        || typeof value.failure_reason === "string");
+}
+function isDelegateProviderMetadata(value) {
+    return (isRecord(value)
+        && hasOnlyKeys(value, CONTEXT_BUILDER_DELEGATE_PROVIDER_METADATA_KEYS)
+        && typeof value.cli_name === "string"
+        && value.cli_name.length > 0
+        && typeof value.role === "string"
+        && value.role.length > 0);
+}
+function isDelegateFinalizerMetadata(value) {
+    return (isRecord(value)
+        && hasOnlyKeys(value, CONTEXT_BUILDER_DELEGATE_FINALIZER_METADATA_KEYS)
+        && typeof value.cli_name === "string"
+        && value.cli_name.length > 0
+        && typeof value.role === "string"
+        && value.role.length > 0
+        && isFiniteNumber(value.min_score));
+}
+function isDelegateMetadataStatus(value) {
+    return value === "succeeded" || value === "partial" || value === "failed";
+}
+function isDelegateMetadataFailurePolicy(value) {
+    return value === "fallback" || value === "fail";
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasOnlyKeys(value, allowedKeys) {
+    const allowed = new Set(allowedKeys);
+    return Object.keys(value).every((key) => allowed.has(key));
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+//# sourceMappingURL=receipt.js.map

package/dist/context-builder/receipt.js.map

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

package/dist/context-builder/run-id.d.ts

@@ -0,0 +1,7 @@
+export type RunIdGeneratorOptions = {
+    now?: () => Date;
+    randomHex?: () => string;
+};
+export declare function validateCallerRunId(runId: string): string;
+export declare function generateContextBuilderRunId(options?: RunIdGeneratorOptions): string;
+export declare function isGeneratedContextBuilderRunId(runId: string): boolean;

package/dist/context-builder/run-id.js

@@ -0,0 +1,31 @@
+import { randomBytes } from "node:crypto";
+import { InvalidParamsError } from "../errors.js";
+const CALLER_RUN_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const GENERATED_RUN_ID_PATTERN = /^ctx_\d{8}T\d{6}Z_[0-9a-f]{8,12}$/;
+export function validateCallerRunId(runId) {
+    if (!CALLER_RUN_ID_PATTERN.test(runId)) {
+        throw new InvalidParamsError("context_builder run_id must match [A-Za-z0-9_-]{1,64}");
+    }
+    return runId;
+}
+export function generateContextBuilderRunId(options = {}) {
+    const now = options.now?.() ?? new Date();
+    const timestamp = now.toISOString().replace(/[-:]/g, "").slice(0, 15);
+    const suffix = normalizeGeneratedHex(options.randomHex?.() ?? randomBytes(6).toString("hex"));
+    const runId = `ctx_${timestamp}Z_${suffix}`;
+    if (!GENERATED_RUN_ID_PATTERN.test(runId)) {
+        throw new Error(`Generated context_builder run_id is invalid: ${runId}`);
+    }
+    return runId;
+}
+export function isGeneratedContextBuilderRunId(runId) {
+    return GENERATED_RUN_ID_PATTERN.test(runId);
+}
+function normalizeGeneratedHex(input) {
+    const hex = input.toLowerCase();
+    if (!/^[0-9a-f]{8,12}$/.test(hex)) {
+        throw new Error("context_builder generated run_id suffix must be 8-12 hex");
+    }
+    return hex;
+}
+//# sourceMappingURL=run-id.js.map

package/dist/context-builder/run-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-id.js","sourceRoot":"","sources":["../../src/context-builder/run-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AACtD,MAAM,wBAAwB,GAAG,mCAAmC,CAAC;AAOrE,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,kBAAkB,CAC1B,uDAAuD,CACxD,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,2BAA2B,CACzC,UAAiC,EAAE;IAEnC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC;IAC1C,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACtE,MAAM,MAAM,GAAG,qBAAqB,CAClC,OAAO,CAAC,SAAS,EAAE,EAAE,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CACxD,CAAC;IACF,MAAM,KAAK,GAAG,OAAO,SAAS,KAAK,MAAM,EAAE,CAAC;IAE5C,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,gDAAgD,KAAK,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,KAAa;IAC1D,OAAO,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAa;IAC1C,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAEhC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC9E,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}