@blokjs/capabilities 2.2.0

package/dist/contracts.d.ts

@@ -0,0 +1,184 @@
+import type { ArtifactVersionIdentity, CapabilityAuthority, EvidenceProvenanceIdentity, PolicyDecision, PolicyEvaluationResult, PolicyLayer, PolicyProvider, PolicyRequest, PrincipalIdentity, SessionIdentity, TurnIdentity, WorkflowIdentity } from "@blokjs/shared";
+export declare const WORKSPACE_FILESYSTEM_CONTRACT_VERSION: "1";
+export declare const WORKSPACE_FILESYSTEM_OPERATIONS: readonly ["metadata", "list", "read", "search", "write", "patch", "watch"];
+export type WorkspaceFilesystemOperation = (typeof WORKSPACE_FILESYSTEM_OPERATIONS)[number];
+export declare const WORKSPACE_FILESYSTEM_MAX_PATH_LENGTH = 4096;
+export declare const WORKSPACE_FILESYSTEM_MAX_QUERY_LENGTH = 8192;
+export declare const WORKSPACE_FILESYSTEM_MAX_READ_BYTES: number;
+export declare const WORKSPACE_FILESYSTEM_MAX_WRITE_BYTES: number;
+export declare const WORKSPACE_FILESYSTEM_MAX_LIST_FILES = 10000;
+export declare const WORKSPACE_FILESYSTEM_MAX_SEARCH_FILES = 2000;
+export declare const WORKSPACE_FILESYSTEM_MAX_SEARCH_MATCHES = 10000;
+export declare const WORKSPACE_FILESYSTEM_MAX_SEARCH_BYTES: number;
+export declare const WORKSPACE_FILESYSTEM_MAX_LINES = 100000;
+export declare const WORKSPACE_FILESYSTEM_MAX_WATCH_EVENTS = 1000;
+export declare const WORKSPACE_FILESYSTEM_MAX_DURATION_MS = 30000;
+export declare const WORKSPACE_FILESYSTEM_MAX_WATCH_DEBOUNCE_MS = 5000;
+export type WorkspaceRootInput = {
+    readonly id: string;
+    readonly path: string;
+};
+export type WorkspaceRoot = {
+    readonly id: string;
+    /** Canonical host path. It is never returned in operation results. */
+    readonly path: string;
+};
+export type WorkspaceFilesystemLimits = {
+    readonly maxReadBytes?: number;
+    readonly maxWriteBytes?: number;
+    readonly maxListFiles?: number;
+    readonly maxSearchFiles?: number;
+    readonly maxSearchMatches?: number;
+    readonly maxSearchBytes?: number;
+    readonly maxLines?: number;
+    readonly maxWatchEvents?: number;
+    readonly maxDurationMs?: number;
+};
+export type WorkspaceFilesystemPolicyRequest = PolicyRequest & {
+    readonly capability: "workspace-filesystem";
+    readonly operation: WorkspaceFilesystemOperation;
+    readonly workspaceId: string;
+    /** Workspace-relative, canonical path. Host paths are never sent to policy. */
+    readonly relativePath: string;
+};
+export type WorkspaceFilesystemPolicy = {
+    readonly provider: PolicyProvider;
+    readonly principal: PrincipalIdentity;
+    readonly session: SessionIdentity;
+    readonly turn: TurnIdentity;
+    readonly policyVersion: string;
+    readonly workflow: WorkflowIdentity;
+    readonly step: {
+        readonly id: string;
+        readonly index?: number;
+        readonly attempt?: number;
+    };
+    readonly layers: readonly PolicyLayer[];
+    readonly authority?: CapabilityAuthority;
+};
+export type WorkspaceFilesystemOptions = {
+    readonly roots: readonly WorkspaceRootInput[];
+    readonly limits?: WorkspaceFilesystemLimits;
+    readonly policy?: WorkspaceFilesystemPolicy;
+    readonly provenance?: EvidenceProvenanceIdentity;
+};
+export type WorkspacePathInput = {
+    readonly workspaceId: string;
+    /** Workspace-relative path. `/`, drive paths, UNC paths, and `..` are rejected. */
+    readonly path: string;
+    readonly signal?: AbortSignal;
+    readonly maxDurationMs?: number;
+};
+export type WorkspaceFileKind = "file" | "directory";
+export type WorkspaceArtifact = ArtifactVersionIdentity & {
+    readonly workspaceId: string;
+    readonly relativePath: string;
+    readonly sizeBytes: number;
+    readonly observedAt: string;
+    readonly provenance?: EvidenceProvenanceIdentity;
+};
+export type WorkspaceFileMetadata = {
+    readonly path: string;
+    readonly kind: WorkspaceFileKind;
+    readonly sizeBytes: number;
+    readonly modifiedAt: string;
+    readonly version?: string;
+    readonly mediaType?: string;
+    readonly artifact?: WorkspaceArtifact;
+};
+export type WorkspaceMetadataInput = WorkspacePathInput;
+export type WorkspaceListInput = WorkspacePathInput & {
+    readonly recursive?: boolean;
+    readonly maxFiles?: number;
+    readonly maxBytes?: number;
+};
+export type WorkspaceListResult = {
+    readonly workspaceId: string;
+    readonly path: string;
+    readonly entries: readonly WorkspaceFileMetadata[];
+    readonly bytesScanned: number;
+    readonly truncated: boolean;
+};
+export type WorkspaceReadEncoding = "utf8" | "base64" | "bytes";
+export type WorkspaceReadInput = WorkspacePathInput & {
+    readonly encoding?: WorkspaceReadEncoding;
+    readonly startLine?: number;
+    readonly endLine?: number;
+    readonly maxBytes?: number;
+    readonly maxLines?: number;
+};
+export type WorkspaceReadResult = {
+    readonly workspaceId: string;
+    readonly path: string;
+    readonly encoding: WorkspaceReadEncoding;
+    readonly bytes: Uint8Array;
+    readonly content: string | Uint8Array;
+    readonly sizeBytes: number;
+    readonly version: string;
+    readonly artifact: WorkspaceArtifact;
+};
+export type WorkspaceSearchInput = WorkspacePathInput & {
+    readonly query: string;
+    readonly regex?: boolean;
+    readonly caseSensitive?: boolean;
+    readonly maxFiles?: number;
+    readonly maxMatches?: number;
+    readonly maxBytes?: number;
+    readonly maxLines?: number;
+};
+export type WorkspaceSearchMatch = {
+    readonly path: string;
+    readonly line: number;
+    readonly column: number;
+    readonly text: string;
+    readonly artifact?: WorkspaceArtifact;
+};
+export type WorkspaceSearchResult = {
+    readonly workspaceId: string;
+    readonly root: string;
+    readonly matches: readonly WorkspaceSearchMatch[];
+    readonly filesScanned: number;
+    readonly bytesScanned: number;
+    readonly truncated: boolean;
+};
+export type WorkspaceWriteInput = WorkspacePathInput & {
+    readonly content: string | Uint8Array;
+    /** Required when replacing an existing file. */
+    readonly expectedVersion?: string;
+    readonly maxBytes?: number;
+};
+export type WorkspaceWriteResult = {
+    readonly workspaceId: string;
+    readonly path: string;
+    readonly created: boolean;
+    readonly bytesWritten: number;
+    readonly version: string;
+    readonly artifact: WorkspaceArtifact;
+};
+export type WorkspaceTextPatch = {
+    readonly start: number;
+    readonly end: number;
+    readonly replacement: string;
+};
+export type WorkspacePatchInput = WorkspacePathInput & {
+    readonly patches: readonly WorkspaceTextPatch[];
+    readonly expectedVersion: string;
+    readonly maxBytes?: number;
+};
+export type WorkspaceWatchInput = WorkspacePathInput & {
+    readonly recursive?: boolean;
+    readonly debounceMs?: number;
+    readonly maxEvents?: number;
+};
+export type WorkspaceWatchEvent = {
+    readonly type: "created" | "changed" | "deleted" | "renamed" | "overflow";
+    readonly workspaceId: string;
+    readonly path?: string;
+    readonly version?: string;
+    readonly artifact?: WorkspaceArtifact;
+    readonly requiresRescan: boolean;
+    readonly observedAt: string;
+};
+export type WorkspacePolicyDecision = PolicyEvaluationResult & {
+    readonly decision: PolicyDecision;
+};

package/dist/contracts.js

@@ -0,0 +1,22 @@
+export const WORKSPACE_FILESYSTEM_CONTRACT_VERSION = "1";
+export const WORKSPACE_FILESYSTEM_OPERATIONS = [
+    "metadata",
+    "list",
+    "read",
+    "search",
+    "write",
+    "patch",
+    "watch",
+];
+export const WORKSPACE_FILESYSTEM_MAX_PATH_LENGTH = 4096;
+export const WORKSPACE_FILESYSTEM_MAX_QUERY_LENGTH = 8192;
+export const WORKSPACE_FILESYSTEM_MAX_READ_BYTES = 8 * 1024 * 1024;
+export const WORKSPACE_FILESYSTEM_MAX_WRITE_BYTES = 8 * 1024 * 1024;
+export const WORKSPACE_FILESYSTEM_MAX_LIST_FILES = 10_000;
+export const WORKSPACE_FILESYSTEM_MAX_SEARCH_FILES = 2_000;
+export const WORKSPACE_FILESYSTEM_MAX_SEARCH_MATCHES = 10_000;
+export const WORKSPACE_FILESYSTEM_MAX_SEARCH_BYTES = 32 * 1024 * 1024;
+export const WORKSPACE_FILESYSTEM_MAX_LINES = 100_000;
+export const WORKSPACE_FILESYSTEM_MAX_WATCH_EVENTS = 1_000;
+export const WORKSPACE_FILESYSTEM_MAX_DURATION_MS = 30_000;
+export const WORKSPACE_FILESYSTEM_MAX_WATCH_DEBOUNCE_MS = 5_000;

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+export declare const WORKSPACE_FILESYSTEM_ERROR_CODES: readonly ["WORKSPACE_FS_INVALID_ROOT", "WORKSPACE_FS_INVALID_PATH", "WORKSPACE_FS_PATH_ESCAPE", "WORKSPACE_FS_SYMLINK_DISALLOWED", "WORKSPACE_FS_HARDLINK_DISALLOWED", "WORKSPACE_FS_SPECIAL_FILE_DISALLOWED", "WORKSPACE_FS_NOT_FOUND", "WORKSPACE_FS_PERMISSION_DENIED", "WORKSPACE_FS_INVALID_TARGET", "WORKSPACE_FS_BINARY_FILE", "WORKSPACE_FS_INVALID_ENCODING", "WORKSPACE_FS_QUERY_INVALID", "WORKSPACE_FS_SIZE_LIMIT", "WORKSPACE_FS_FILE_LIMIT", "WORKSPACE_FS_MATCH_LIMIT", "WORKSPACE_FS_LINE_LIMIT", "WORKSPACE_FS_TIME_LIMIT", "WORKSPACE_FS_CANCELLED", "WORKSPACE_FS_VERSION_REQUIRED", "WORKSPACE_FS_VERSION_CONFLICT", "WORKSPACE_FS_PATCH_INVALID", "WORKSPACE_FS_WATCH_OVERFLOW", "WORKSPACE_FS_POLICY_DENIED", "WORKSPACE_FS_POLICY_INVALID", "WORKSPACE_FS_ATOMIC_REPLACE_UNSUPPORTED"];
+export type WorkspaceFilesystemErrorCode = (typeof WORKSPACE_FILESYSTEM_ERROR_CODES)[number];
+export declare class WorkspaceFilesystemError extends Error {
+    readonly code: WorkspaceFilesystemErrorCode;
+    readonly operation?: string;
+    readonly relativePath?: string;
+    constructor(code: WorkspaceFilesystemErrorCode, message?: string, details?: {
+        operation?: string;
+        relativePath?: string;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,39 @@
+export const WORKSPACE_FILESYSTEM_ERROR_CODES = [
+    "WORKSPACE_FS_INVALID_ROOT",
+    "WORKSPACE_FS_INVALID_PATH",
+    "WORKSPACE_FS_PATH_ESCAPE",
+    "WORKSPACE_FS_SYMLINK_DISALLOWED",
+    "WORKSPACE_FS_HARDLINK_DISALLOWED",
+    "WORKSPACE_FS_SPECIAL_FILE_DISALLOWED",
+    "WORKSPACE_FS_NOT_FOUND",
+    "WORKSPACE_FS_PERMISSION_DENIED",
+    "WORKSPACE_FS_INVALID_TARGET",
+    "WORKSPACE_FS_BINARY_FILE",
+    "WORKSPACE_FS_INVALID_ENCODING",
+    "WORKSPACE_FS_QUERY_INVALID",
+    "WORKSPACE_FS_SIZE_LIMIT",
+    "WORKSPACE_FS_FILE_LIMIT",
+    "WORKSPACE_FS_MATCH_LIMIT",
+    "WORKSPACE_FS_LINE_LIMIT",
+    "WORKSPACE_FS_TIME_LIMIT",
+    "WORKSPACE_FS_CANCELLED",
+    "WORKSPACE_FS_VERSION_REQUIRED",
+    "WORKSPACE_FS_VERSION_CONFLICT",
+    "WORKSPACE_FS_PATCH_INVALID",
+    "WORKSPACE_FS_WATCH_OVERFLOW",
+    "WORKSPACE_FS_POLICY_DENIED",
+    "WORKSPACE_FS_POLICY_INVALID",
+    "WORKSPACE_FS_ATOMIC_REPLACE_UNSUPPORTED",
+];
+export class WorkspaceFilesystemError extends Error {
+    code;
+    operation;
+    relativePath;
+    constructor(code, message, details) {
+        super(message ?? code);
+        this.name = "WorkspaceFilesystemError";
+        this.code = code;
+        this.operation = details?.operation;
+        this.relativePath = details?.relativePath;
+    }
+}

package/dist/graph/BoundedGraphIndexer.d.ts

@@ -0,0 +1,44 @@
+import { type GraphIndexResponse, type GraphProvider } from "@blokjs/shared";
+export interface GraphIndexerEvent {
+    readonly type: "enqueued" | "started" | "completed" | "failed" | "cancelled";
+    readonly key: string;
+    readonly queued: number;
+    readonly active: number;
+    readonly error?: string;
+}
+export interface GraphIndexJobHandle {
+    readonly key: string;
+    readonly promise: Promise<GraphIndexResponse>;
+    cancel(): void;
+}
+export interface GraphIndexerEnqueueOptions {
+    readonly signal?: AbortSignal;
+}
+export interface BoundedGraphIndexerOptions {
+    readonly maxQueueSize?: number;
+    readonly maxConcurrent?: number;
+    readonly maxFilesPerJob?: number;
+    readonly maxBytesPerJob?: number;
+    readonly onEvent?: (event: GraphIndexerEvent) => void;
+}
+/** A bounded, cancellable and content-deduplicating index work queue. */
+export declare class BoundedGraphIndexer {
+    private readonly provider;
+    private readonly maxQueueSize;
+    private readonly maxConcurrent;
+    private readonly maxFilesPerJob;
+    private readonly maxBytesPerJob;
+    private readonly onEvent?;
+    private readonly jobs;
+    private readonly queue;
+    private active;
+    constructor(provider: GraphProvider, options?: BoundedGraphIndexerOptions);
+    get queued(): number;
+    get running(): number;
+    enqueue(input: unknown, options?: GraphIndexerEnqueueOptions): GraphIndexJobHandle;
+    close(): void;
+    private cancel;
+    private emit;
+    private pump;
+    private run;
+}

package/dist/graph/BoundedGraphIndexer.js

@@ -0,0 +1,157 @@
+import { GRAPH_MAX_FILES_PER_INDEX, GRAPH_MAX_INDEX_BYTES, parseGraphIndexRequest, } from "@blokjs/shared";
+import { GraphProviderError } from "./GraphProviderError.js";
+function identityKey(request) {
+    const files = [...request.files]
+        .sort((left, right) => left.path.localeCompare(right.path))
+        .map((file) => `${file.path}:${file.contentHash}`);
+    return JSON.stringify({
+        repository: request.scope.repository,
+        worktree: request.scope.worktree,
+        commit: request.scope.commit,
+        files,
+    });
+}
+function requestBytes(request) {
+    return new TextEncoder().encode(JSON.stringify(request)).byteLength;
+}
+/** A bounded, cancellable and content-deduplicating index work queue. */
+export class BoundedGraphIndexer {
+    provider;
+    maxQueueSize;
+    maxConcurrent;
+    maxFilesPerJob;
+    maxBytesPerJob;
+    onEvent;
+    jobs = new Map();
+    queue = [];
+    active = 0;
+    constructor(provider, options = {}) {
+        this.provider = provider;
+        this.maxQueueSize = options.maxQueueSize ?? 64;
+        this.maxConcurrent = options.maxConcurrent ?? 2;
+        this.maxFilesPerJob = options.maxFilesPerJob ?? GRAPH_MAX_FILES_PER_INDEX;
+        this.maxBytesPerJob = options.maxBytesPerJob ?? GRAPH_MAX_INDEX_BYTES;
+        this.onEvent = options.onEvent;
+        if (!Number.isSafeInteger(this.maxQueueSize) || this.maxQueueSize <= 0)
+            throw new Error("maxQueueSize must be positive");
+        if (!Number.isSafeInteger(this.maxConcurrent) || this.maxConcurrent <= 0)
+            throw new Error("maxConcurrent must be positive");
+    }
+    get queued() {
+        return this.queue.length;
+    }
+    get running() {
+        return this.active;
+    }
+    enqueue(input, options = {}) {
+        if (options.signal?.aborted)
+            throw GraphProviderError.cancelled();
+        let request;
+        try {
+            request = parseGraphIndexRequest(input);
+        }
+        catch (error) {
+            throw new GraphProviderError("invalid-query", "GRAPH_INVALID_INDEX_REQUEST", error instanceof Error ? error.message : "Invalid graph index request", { guidance: "narrow-query" });
+        }
+        if (request.files.length > this.maxFilesPerJob) {
+            throw new GraphProviderError("limit-exceeded", "GRAPH_INDEX_FILE_LIMIT", "Index request exceeds the configured file limit", {
+                guidance: "narrow-query",
+            });
+        }
+        if (requestBytes(request) > this.maxBytesPerJob) {
+            throw new GraphProviderError("limit-exceeded", "GRAPH_INDEX_BYTE_LIMIT", "Index request exceeds the configured byte limit", {
+                guidance: "narrow-query",
+            });
+        }
+        const key = identityKey(request);
+        const existing = this.jobs.get(key);
+        if (existing)
+            return { key, promise: existing.promise, cancel: () => this.cancel(existing) };
+        if (this.jobs.size >= this.maxQueueSize) {
+            throw new GraphProviderError("limit-exceeded", "GRAPH_INDEX_QUEUE_FULL", "Graph index queue is full", {
+                retryable: true,
+                guidance: "retry",
+            });
+        }
+        let resolve;
+        let reject;
+        const promise = new Promise((resolvePromise, rejectPromise) => {
+            resolve = resolvePromise;
+            reject = rejectPromise;
+        });
+        const job = { key, request, controller: new AbortController(), promise, resolve, reject, started: false };
+        this.jobs.set(key, job);
+        this.queue.push(job);
+        if (options.signal) {
+            if (options.signal.aborted) {
+                this.cancel(job);
+            }
+            else {
+                options.signal.addEventListener("abort", () => this.cancel(job), { once: true });
+            }
+        }
+        this.emit({ type: "enqueued", key });
+        this.pump();
+        return { key, promise, cancel: () => this.cancel(job) };
+    }
+    close() {
+        for (const job of this.jobs.values())
+            this.cancel(job);
+    }
+    cancel(job) {
+        if (job.controller.signal.aborted)
+            return;
+        job.controller.abort();
+        if (job.started)
+            return;
+        const index = this.queue.indexOf(job);
+        if (index >= 0)
+            this.queue.splice(index, 1);
+        this.jobs.delete(job.key);
+        job.reject(GraphProviderError.cancelled());
+        this.emit({ type: "cancelled", key: job.key });
+        this.pump();
+    }
+    emit(event) {
+        this.onEvent?.({ ...event, queued: this.queue.length, active: this.active });
+    }
+    pump() {
+        while (this.active < this.maxConcurrent && this.queue.length > 0) {
+            const job = this.queue.shift();
+            if (!job)
+                return;
+            if (job.controller.signal.aborted) {
+                this.jobs.delete(job.key);
+                job.reject(GraphProviderError.cancelled());
+                continue;
+            }
+            job.started = true;
+            this.active += 1;
+            this.emit({ type: "started", key: job.key });
+            void this.run(job);
+        }
+    }
+    async run(job) {
+        try {
+            const result = await this.provider.index(job.request, { signal: job.controller.signal });
+            if (job.controller.signal.aborted)
+                throw GraphProviderError.cancelled();
+            job.resolve(result);
+            this.emit({ type: "completed", key: job.key });
+        }
+        catch (error) {
+            const failure = job.controller.signal.aborted ? GraphProviderError.cancelled() : error;
+            job.reject(failure);
+            this.emit({
+                type: failure instanceof GraphProviderError && failure.category === "cancelled" ? "cancelled" : "failed",
+                key: job.key,
+                error: String(failure),
+            });
+        }
+        finally {
+            this.active -= 1;
+            this.jobs.delete(job.key);
+            this.pump();
+        }
+    }
+}

package/dist/graph/FakeGraphProvider.d.ts

@@ -0,0 +1,35 @@
+import { type GraphFreshnessRequest, type GraphImpactRequest, type GraphIndexFile, type GraphIndexRequest, type GraphIndexResponse, type GraphLocation, type GraphProvider, type GraphQueryOptions, type GraphQueryResponse, type GraphRelation, type GraphRelationRequest, type GraphScope, type GraphSearchHit, type GraphSearchRequest, type GraphSymbol, type GraphSymbolRequest } from "@blokjs/shared";
+type FakeOperation = "search" | "symbol" | "relations" | "impact" | "freshness" | "index";
+export interface FakeGraphProviderOptions {
+    readonly scope?: GraphScope;
+    readonly files?: readonly GraphIndexFile[];
+    readonly supportedOperations?: readonly FakeOperation[];
+    readonly now?: () => string;
+}
+/** Deterministic in-memory provider used for contract tests and local adapters. */
+export declare class FakeGraphProvider implements GraphProvider {
+    readonly id = "fake";
+    readonly version = "fake-1";
+    private readonly symbols;
+    private readonly relationsById;
+    private readonly indexedHashes;
+    private readonly supported;
+    private readonly now;
+    private indexedScope?;
+    private indexedAt?;
+    private indexVersion;
+    constructor(options?: FakeGraphProviderOptions);
+    seed(scope: GraphScope, files: readonly GraphIndexFile[]): void;
+    search(input: GraphSearchRequest, options?: GraphQueryOptions): Promise<GraphQueryResponse<GraphSearchHit>>;
+    findSymbol(input: GraphSymbolRequest, options?: GraphQueryOptions): Promise<GraphQueryResponse<GraphSymbol>>;
+    relations(input: GraphRelationRequest, options?: GraphQueryOptions): Promise<GraphQueryResponse<GraphRelation>>;
+    impact(input: GraphImpactRequest, options?: GraphQueryOptions): Promise<GraphQueryResponse<GraphSymbol>>;
+    freshness(input: GraphFreshnessRequest, options?: GraphQueryOptions): Promise<GraphQueryResponse<GraphLocation>>;
+    index(input: GraphIndexRequest, options?: GraphQueryOptions): Promise<GraphIndexResponse>;
+    private applyIndex;
+    private score;
+    private parse;
+    private unsupported;
+    private scopeMetadata;
+}
+export {};