@hachej/boring-files 0.0.0-stage → 0.2.0

package/dist/text.js

@@ -0,0 +1,29 @@
+export function parseTextEdits(value) {
+    if (!Array.isArray(value) || !value.length)
+        throw new TypeError('At least one exact text edit is required');
+    const edits = value;
+    return edits.map(item => {
+        if (!item || typeof item !== 'object' || !('find' in item) || !('replace' in item) || typeof item.find !== 'string' || !item.find.length || typeof item.replace !== 'string'
+            || Object.keys(item).some(key => key !== 'find' && key !== 'replace'))
+            throw new TypeError('Each text edit requires nonempty find and string replace');
+        return { find: item.find, replace: item.replace };
+    });
+}
+/** Each edit sees the preceding edit's result; ambiguous or missing matches refuse the entire transformation. */
+export function applyTextEdits(text, input) {
+    if (typeof text !== 'string')
+        throw new TypeError('Expected text');
+    const edits = parseTextEdits(input);
+    let result = text;
+    for (const [editIndex, edit] of edits.entries()) {
+        const at = result.indexOf(edit.find);
+        if (at < 0)
+            return { kind: 'rejected', editIndex, reason: 'Exact text was not found' };
+        if (result.indexOf(edit.find, at + 1) >= 0)
+            return { kind: 'rejected', editIndex, reason: 'Exact text occurs more than once' };
+        result = result.slice(0, at) + edit.replace + result.slice(at + edit.find.length);
+    }
+    if (new TextDecoder('utf-8', { ignoreBOM: true }).decode(new TextEncoder().encode(result)) !== result)
+        return { kind: 'rejected', editIndex: edits.length - 1, reason: 'Result contains invalid Unicode' };
+    return { kind: 'applied', text: result };
+}

package/dist/workspace-catalog.d.ts

@@ -0,0 +1,17 @@
+import type { FileSystem } from '@earendil-works/pi-durable/env';
+import type { FileEntry, WorkspaceCatalog, SavedRevision } from './revision-contracts.js';
+export interface WorkspaceCatalogOptions {
+    /** Presentation defaults, never an access policy. False shows dependency/build/internal names and gitignored files. */
+    readonly defaults?: boolean;
+    /** Additional presentation filtering. Returning false prunes a directory and its descendants. */
+    readonly filter?: (entry: FileEntry) => boolean;
+    /** A traversal exceeding this bound fails explicitly; it never returns a silently incomplete page. */
+    readonly maxEntries?: number;
+}
+export declare function catalogPath(path: string, allowRoot?: boolean): string;
+export declare function createWorkspaceCatalog(options: {
+    readonly fs: FileSystem;
+    readonly config?: WorkspaceCatalogOptions;
+    readonly saves: (path: string) => readonly SavedRevision[];
+}): WorkspaceCatalog;
+//# sourceMappingURL=workspace-catalog.d.ts.map

package/dist/workspace-catalog.js

@@ -0,0 +1,147 @@
+import ignore from 'ignore';
+import { identifier, locator } from './publication-input.js';
+import { RevisionError } from './revision-contracts.js';
+const hidden = new Set(['.git', '.boring', 'node_modules', 'dist', 'build', '.cache', '.next', 'coverage', '__pycache__']);
+const temporary = /^\.boring-[0-9a-f-]{36}\.tmp$/;
+const inside = (root, path) => path === root || path.startsWith(root === '/' ? '/' : `${root}/`);
+export function catalogPath(path, allowRoot = false) {
+    if (allowRoot && path === '')
+        return path;
+    return locator({ resource: { providerId: 'catalog', path }, view: { kind: 'published' } }).resource.path;
+}
+export function createWorkspaceCatalog(options) {
+    const { fs } = options, config = options.config ?? {};
+    const maximum = config.maxEntries ?? 100_000;
+    if (!Number.isSafeInteger(maximum) || maximum < 1)
+        throw new TypeError('Invalid catalog traversal bound');
+    const root = fs.cwd.replace(/\/$/, '') || '/';
+    const absolute = (path) => `${root === '/' ? '' : root}/${path}`;
+    const check = (access) => { if (access.signal?.aborted)
+        throw new RevisionError('aborted', 'File browsing was cancelled'); };
+    const context = (access) => ({ abortSignal: access.signal, value: () => undefined, toString: () => 'boring-catalog' });
+    async function contained(path, access) {
+        check(access);
+        const base = await fs.canonicalPath(root, context(access));
+        const resolved = await fs.canonicalPath(absolute(path), context(access));
+        check(access);
+        return base.ok && resolved.ok && inside(base.value, resolved.value);
+    }
+    async function rulesAt(path, directory, parents, access) {
+        if (config.defaults === false)
+            return parents;
+        const info = await fs.fileInfo(absolute(path), context(access));
+        if (!info.ok) {
+            if (info.error.code === 'not_found' || info.error.code === 'not_directory')
+                return parents;
+            throw new RevisionError('unavailable', 'Ignore rules could not be inspected');
+        }
+        if (info.value.kind !== 'file' || !await contained(path, access))
+            throw new RevisionError('denied', 'Ignore rules must be a file inside the workspace');
+        if (info.value.size > 1_048_576)
+            throw new RevisionError('unavailable', 'Ignore rules exceed the catalog limit');
+        const read = await fs.readBinaryFile(absolute(path), context(access));
+        check(access);
+        if (!read.ok)
+            throw new RevisionError('unavailable', 'Ignore rules could not be read');
+        return [...parents, { directory, matcher: ignore.default().add(new TextDecoder('utf-8', { fatal: true }).decode(read.value)) }];
+    }
+    function visible(entry, rules) {
+        const name = entry.path.slice(entry.path.lastIndexOf('/') + 1);
+        if (temporary.test(name))
+            return false;
+        if (config.defaults !== false) {
+            if (hidden.has(name))
+                return false;
+            let ignored = false;
+            for (const rule of rules) {
+                const relative = entry.path.slice(rule.directory ? rule.directory.length + 1 : 0) + (entry.kind === 'directory' ? '/' : '');
+                const result = rule.matcher.test(relative);
+                if (result.ignored)
+                    ignored = true;
+                else if (result.unignored)
+                    ignored = false;
+            }
+            if (ignored)
+                return false;
+        }
+        return config.filter?.(entry) !== false;
+    }
+    async function collect(directory, recursive, access) {
+        check(access);
+        if (!await contained(directory, access))
+            throw new RevisionError('denied', 'The directory is outside the workspace or unavailable');
+        const entries = [];
+        let scanned = 0;
+        async function walk(parent, rules) {
+            check(access);
+            const own = await rulesAt(parent ? `${parent}/.gitignore` : '.gitignore', parent, rules, access);
+            const listing = await fs.listDir(absolute(parent), context(access));
+            check(access);
+            if (!listing.ok)
+                throw new RevisionError('unavailable', 'The directory could not be listed');
+            for (const item of listing.value) {
+                check(access);
+                if (++scanned > maximum)
+                    throw new RevisionError('unavailable', 'The workspace exceeds the catalog traversal limit');
+                if (item.kind !== 'file' && item.kind !== 'directory')
+                    continue;
+                const path = catalogPath(parent ? `${parent}/${item.name}` : item.name);
+                const entry = { path, kind: item.kind, size: item.size };
+                if (!visible(entry, own))
+                    continue;
+                if (!await contained(path, access))
+                    throw new RevisionError('denied', 'A listed entry resolves outside the workspace');
+                entries.push(entry);
+                if (item.kind === 'directory' && (recursive || directory === path || directory.startsWith(`${path}/`)))
+                    await walk(path, own);
+            }
+        }
+        // Walk from the root so parent ignore rules and directory exclusions also apply to a direct nested-directory request.
+        let initial = [];
+        if (config.defaults !== false) {
+            for (const path of ['.git', '.git/info']) {
+                const info = await fs.fileInfo(absolute(path), context(access));
+                if (info.ok && info.value.kind === 'symlink')
+                    throw new RevisionError('denied', 'Repository ignore rules cannot use symbolic links');
+            }
+            initial = await rulesAt('.git/info/exclude', '', [], access);
+        }
+        await walk('', initial);
+        if (recursive)
+            return entries;
+        return entries.filter(entry => entry.path.slice(0, entry.path.lastIndexOf('/') + 1) === (directory ? `${directory}/` : ''));
+    }
+    function page(entries, key, cursor, limit) {
+        const count = limit ?? 100;
+        if (!Number.isSafeInteger(count) || count < 1 || count > 500)
+            throw new RevisionError('invalid', 'Page limit must be between 1 and 500');
+        let after = '';
+        if (cursor !== undefined) {
+            try {
+                const value = JSON.parse(decodeURIComponent(cursor));
+                if (!Array.isArray(value) || value.length !== 2 || value[0] !== key || typeof value[1] !== 'string')
+                    throw new Error();
+                after = catalogPath(value[1]);
+            }
+            catch {
+                throw new RevisionError('invalid', 'Invalid catalog cursor');
+            }
+        }
+        const sorted = entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0).filter(entry => entry.path > after);
+        const selected = sorted.slice(0, count), last = selected.at(-1);
+        return { entries: selected, ...(last && sorted.length > count ? { cursor: encodeURIComponent(JSON.stringify([key, last.path])) } : {}) };
+    }
+    return {
+        list: async (request, access) => {
+            const directory = catalogPath(request.directory ?? '', true);
+            return page(await collect(directory, false, access), `list:${directory}`, request.cursor, request.limit);
+        },
+        search: async (request, access) => {
+            if (typeof request.query !== 'string' || request.query.length > 1024)
+                throw new RevisionError('invalid', 'Invalid filename query');
+            const query = request.query.toLowerCase();
+            return page((await collect('', true, access)).filter(entry => entry.kind === 'file' && entry.path.toLowerCase().includes(query)), `search:${query}`, request.cursor, request.limit);
+        },
+        history: async (path, access) => { check(access); identifier(access.scopeId); return options.saves(catalogPath(path)); },
+    };
+}

package/dist/workspace-identity.d.ts

@@ -0,0 +1,8 @@
+/** The host's identity of the workspace (the same shape as `WorkspaceIdentity` in `@hachej/boring-execution`). Pi's environment `id` is only a namespace. */
+export interface WorkspaceKey {
+    readonly providerId: string;
+    readonly instanceId: string;
+    readonly incarnation: string;
+    readonly viewId: string;
+}
+//# sourceMappingURL=workspace-identity.d.ts.map

package/dist/workspace-identity.js

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

package/dist/workspace.d.ts

@@ -0,0 +1,55 @@
+import type { FileSystem } from '@earendil-works/pi-durable/env';
+import type { PublicationLookupResult, PublicationResult, ReadResult, ResourceAccess, ResourceProvider } from './contracts.js';
+import type { WorkspaceCatalogOptions } from './workspace-catalog.js';
+import type { WorkspaceCatalog } from './revision-contracts.js';
+export type { WorkspaceCatalogOptions } from './workspace-catalog.js';
+import type { WorkspaceJournal } from './journal.js';
+import type { WorkspaceKey } from './workspace-identity.js';
+export type { WorkspaceKey } from './workspace-identity.js';
+export interface WorkspaceChange {
+    readonly path: string;
+    /** `null` when the file is absent. */
+    readonly revision: string | null;
+    readonly source: 'provider' | 'poll';
+}
+/** Runs one piece of work at a time, in order. A failed piece does not stop the ones behind it. */
+export interface WorkspaceQueue {
+    readonly run: <Value>(work: () => Promise<Value>) => Promise<Value>;
+}
+export interface WorkspaceResourceProvider extends ResourceProvider {
+    readonly identity: WorkspaceKey;
+    readonly catalog: WorkspaceCatalog;
+    readonly publication: {
+        readonly publish: (request: Parameters<NonNullable<ResourceProvider['publication']>['publish']>[0], access: ResourceAccess) => Promise<PublicationResult>;
+    };
+    readonly reconciliation: {
+        readonly lookup: (operationId: string, access: ResourceAccess) => Promise<PublicationLookupResult>;
+    };
+    /** The workspace's mutation queue. Native tool calls that must not interleave with a conditional write run through it. */
+    readonly queue: WorkspaceQueue;
+    /** Revisions still retained for a file, newest first. */
+    readonly history: (path: string) => string[];
+    /** The same revisions with the time each was saved (milliseconds since the epoch; 0 when unknown), newest first. */
+    readonly saves: (path: string) => {
+        readonly revision: string;
+        readonly savedAt: number;
+    }[];
+    /** Read the file as it is now and retain that revision in its history (what `present` shows). Serialised with writes. */
+    readonly keep: (path: string, access: ResourceAccess) => Promise<ReadResult>;
+    /** Provider writes and polled detections. The listener must not throw. */
+    readonly onChange: (listener: (change: WorkspaceChange) => void) => () => void;
+    /** Hash each path now and report those that differ from the last revision this provider wrote or polled. Finds shell writes. */
+    readonly poll: (paths: readonly string[], signal?: AbortSignal) => Promise<WorkspaceChange[]>;
+}
+export interface WorkspaceProviderOptions {
+    readonly identity: WorkspaceKey;
+    readonly fs: FileSystem;
+    readonly journal: WorkspaceJournal;
+    readonly catalog?: WorkspaceCatalogOptions;
+}
+/** The Git blob id of `bytes` (`sha1("blob <length>\0" + bytes)`), computed without Git. */
+export declare function blobRevision(bytes: Uint8Array): Promise<string>;
+/** Whether a path is one of the provider's temporary files (a lister hides them). */
+export declare const isTemporary: (path: string) => boolean;
+export declare function createWorkspaceProvider(options: WorkspaceProviderOptions): WorkspaceResourceProvider;
+//# sourceMappingURL=workspace.d.ts.map