@blokjs/capabilities 2.2.0

package/README.md

@@ -0,0 +1,24 @@
+# `@blokjs/capabilities`
+
+Trusted, bounded adapters for effectful operations used by the Blok harness.
+
+`WorkspaceFilesystemCapability` is the H3-01 filesystem boundary. It accepts
+only registered, canonical workspace roots and workspace-relative paths. It
+does not expose host paths, follows no symlinks, rejects hard-linked regular
+files and special files, and returns stable, bounded results. Reads, searches,
+writes, patches, and watches carry separate `fs.workspace.*` capabilities and
+filesystem/read, filesystem/write, or filesystem/streaming effects in the
+shared v1 capability-manifest vocabulary.
+
+Agent-originated callers should provide the H0-03 policy provider and complete
+policy context through `WorkspaceFilesystemOptions.policy`. A policy provider
+does not grant filesystem authority by itself: the requested operation must
+remain in the existing `CapabilityAuthority`, and only an `allow` decision for
+the configured policy version proceeds.
+
+Writes require an expected content version when replacing a file. Replacement
+is performed with a same-directory temporary file and atomic rename; a changed
+version or a target appearing during a create is rejected.
+
+This package deliberately does not implement Git, process execution, shell
+commands, graph indexing, or a desktop-specific host protocol.

package/dist/WorkspaceFilesystemCapability.d.ts

@@ -0,0 +1,35 @@
+import { type CapabilityAuthority, type CapabilityManifestV1 } from "@blokjs/shared";
+import type { WorkspaceFileMetadata, WorkspaceFilesystemLimits, WorkspaceFilesystemOperation, WorkspaceFilesystemOptions, WorkspaceListInput, WorkspaceListResult, WorkspaceMetadataInput, WorkspacePatchInput, WorkspaceReadInput, WorkspaceReadResult, WorkspaceRoot, WorkspaceSearchInput, WorkspaceSearchResult, WorkspaceWatchEvent, WorkspaceWatchInput, WorkspaceWriteInput, WorkspaceWriteResult } from "./contracts.js";
+export declare function workspaceFilesystemManifest(operation: WorkspaceFilesystemOperation, limits?: WorkspaceFilesystemLimits): CapabilityManifestV1;
+export declare function workspaceFilesystemAuthority(operation: WorkspaceFilesystemOperation, workspaceId?: string): CapabilityAuthority;
+export declare function workspaceRelativePath(value: string): string;
+export declare class WorkspaceFilesystemCapability {
+    readonly roots: readonly WorkspaceRoot[];
+    readonly limits: Required<WorkspaceFilesystemLimits>;
+    private readonly rootById;
+    private readonly options;
+    constructor(options: WorkspaceFilesystemOptions);
+    metadata(input: WorkspaceMetadataInput): Promise<WorkspaceFileMetadata>;
+    list(input: WorkspaceListInput): Promise<WorkspaceListResult>;
+    read(input: WorkspaceReadInput): Promise<WorkspaceReadResult>;
+    search(input: WorkspaceSearchInput): Promise<WorkspaceSearchResult>;
+    write(input: WorkspaceWriteInput): Promise<WorkspaceWriteResult>;
+    patch(input: WorkspacePatchInput): Promise<WorkspaceWriteResult>;
+    watch(input: WorkspaceWatchInput): AsyncIterable<WorkspaceWatchEvent>;
+    private run;
+    private duration;
+    private resolveInput;
+    private resolveTarget;
+    private pathFromAbsolute;
+    private authorize;
+    private scopeAllows;
+    private secureStat;
+    private readSecure;
+    private metadataInternal;
+    private statVersion;
+    private makeArtifact;
+    private selectLines;
+    private writeInternal;
+    private directoriesForWatch;
+    private watchEvent;
+}