@hachej/boring-files 0.0.0-stage → 0.2.1

package/dist/sqlite.js

@@ -0,0 +1,50 @@
+import { applySqliteSettings, resolveSqliteSettings } from './sqlite-settings.js';
+export * from './sqlite-settings.js';
+/**
+ * A `node:sqlite` database with `settings` applied (partial settings are filled from `sqliteSettings.localDisk`: WAL, full sync,
+ * 5 s busy timeout). For Pi's own durable storage on the same settings, hand it to Pi's public adapter:
+ * `SqliteStorage.open(new NodeSqliteDatabase(openNodeDatabase(file, sqliteSettings.networkFilesystem)))`. Throws
+ * `SqliteLockedError` when another connection holds the file under `lockingMode: 'exclusive'`. Loaded without a static import so
+ * other runtimes can bundle this module.
+ */
+export function openNodeDatabase(filename, settings = {}) {
+    const resolved = resolveSqliteSettings(settings);
+    const sqlite = globalThis.process?.getBuiltinModule?.('node:sqlite');
+    if (!sqlite)
+        throw new Error('A filename needs Node.js with node:sqlite; pass a connection on other runtimes');
+    const db = new sqlite.DatabaseSync(filename);
+    try {
+        applySqliteSettings({ exec: sql => { db.exec(sql); }, get: sql => db.prepare(sql).get() }, resolved, filename);
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+    return db;
+}
+/** A `node:sqlite` file as a connection (`openNodeDatabase` with the same settings), `BEGIN IMMEDIATE` for writes. */
+export function openNodeConnection(filename, settings = {}) {
+    const db = openNodeDatabase(filename, settings);
+    return {
+        exec: sql => { db.exec(sql); },
+        run: (sql, ...params) => { db.prepare(sql).run(...params); },
+        get: (sql, ...params) => db.prepare(sql).get(...params),
+        all: (sql, ...params) => db.prepare(sql).all(...params),
+        // A transaction opened inside another one joins it: the outer one commits or rolls back everything.
+        transaction: (mode, work) => {
+            if (db.isTransaction)
+                return work();
+            db.exec(mode === 'write' ? 'BEGIN IMMEDIATE' : 'BEGIN');
+            try {
+                const result = work();
+                db.exec('COMMIT');
+                return result;
+            }
+            catch (error) {
+                db.exec('ROLLBACK');
+                throw error;
+            }
+        },
+        close: () => { db.close(); },
+    };
+}

package/dist/text.d.ts

@@ -0,0 +1,16 @@
+export interface TextEdit {
+    readonly find: string;
+    readonly replace: string;
+}
+export type TextEditResult = {
+    readonly kind: 'applied';
+    readonly text: string;
+} | {
+    readonly kind: 'rejected';
+    readonly editIndex: number;
+    readonly reason: string;
+};
+export declare function parseTextEdits(value: unknown): readonly TextEdit[];
+/** Each edit sees the preceding edit's result; ambiguous or missing matches refuse the entire transformation. */
+export declare function applyTextEdits(text: string, input: readonly TextEdit[]): TextEditResult;
+//# sourceMappingURL=text.d.ts.map

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,108 @@
+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 { ChangeFeedRequest, WorkspaceCatalog, WorkspaceChangeEvent } from './revision-contracts.js';
+export type { ChangeFeedRequest, WorkspaceChangeEvent } from './revision-contracts.js';
+export type { WorkspaceCatalogOptions } from './workspace-catalog.js';
+import type { HistorySource, 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 (or, from a watcher, when the path is a directory). */
+    readonly revision: string | null;
+    /** `publish`: a conditional write. `agent`: `record` (a Pi `write` or `edit`). `poll`: found by hashing. `watch`: the file system reported it. */
+    readonly source: 'publish' | 'agent' | 'poll' | 'watch';
+}
+/** What `record` is told about an agent write (ruling 2: observed, never receipted). */
+export interface AgentWrite {
+    readonly path: string;
+    /** The file before the write, when it existed: its revision and the bytes of that revision (kept in history as the replaced version). */
+    readonly before?: {
+        readonly revision: string;
+        readonly bytes: Uint8Array;
+    } | null | undefined;
+    /** The revision the write produced, as the caller observed it right after. */
+    readonly after: string;
+    readonly source: 'agent';
+    /** The Pi conversation that wrote it, carried on the change event. */
+    readonly conversationId?: string | undefined;
+}
+/** 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;
+    /**
+     * Record a write the agent already made through the native tools (Pi `write`/`edit`, called by the file guard right after the
+     * tool succeeded): the file's history gains the written revision (source `agent`, and the replaced one when `before` carries its
+     * bytes) and the change feed an `agent` event. It writes history rows only: no publish, no receipt, no operation or intent rows,
+     * so agent writes are observed, not published. It does not enter `queue` (the guard already runs inside it), so it is safe to call from queued work.
+     * When the bytes there no longer have the `after` revision (a shell wrote in between), only the change event is recorded.
+     */
+    readonly record: (write: AgentWrite, access: ResourceAccess) => Promise<void>;
+    /**
+     * The change feed: every write this provider makes or records, every change `poll` finds and, while someone is listening, every
+     * change the file system's `watch` reports (the SQLite file system reports its own connection's writes at once). Ordered by
+     * `seq` and replayable from `since` within a bounded window; a gap yields a `resnapshot` event. The iterator ends when
+     * `request.signal` or `access.signal` aborts, or the provider closes. Events are invalidation hints: read the bytes again.
+     *
+     * After the last listener leaves, the watcher stays open for `watchLingerMs` and then closes. Changes made while no watcher was
+     * open are unknown, so the first listener afterwards makes the feed append a `resnapshot`: a client that reconnects after a
+     * longer absence reloads everything once, and one that stays connected is never affected.
+     */
+    readonly changes: (request: ChangeFeedRequest, access: ResourceAccess) => AsyncIterable<WorkspaceChangeEvent>;
+    /** The seq of the newest change event (the cursor of "now" for `changes({ since })`). */
+    readonly changeHead: () => number;
+    /** Names this provider's lifetime; a cursor from another one (`ChangeFeedRequest.incarnation`) is answered with a `resnapshot`. */
+    readonly changeIncarnation: string;
+    /** Ends every change stream, closes the file watcher and drops the change listeners. Idempotent; the provider still reads and publishes. */
+    readonly close: () => void;
+    /** Aborts when the provider closes, so a change stream nobody is reading still ends and releases its lease. */
+    readonly lifetime: AbortSignal;
+    /** 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;
+        readonly source: HistorySource;
+    }[];
+    /** 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.
+     * Without `paths`, every file of the workspace (except `.git` and `node_modules`): the first such call takes the baseline and
+     * reports nothing; later calls also report new and removed files. A host whose file system cannot `watch` calls it at the end of
+     * each agent turn (after `bash`), so the change feed still sees 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;
+    /** How many change events the feed retains for replay (default 1024). An older cursor gets a `resnapshot`. */
+    readonly changeBuffer?: number;
+    /** How long the watcher stays open after the last change-feed listener leaves, in milliseconds (default 30 000). */
+    readonly watchLingerMs?: number;
+}
+/** 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