@jini-ai/vibecoding 0.6.10 → 0.6.11

package/dist/node/project.js

@@ -0,0 +1,367 @@
+import { createEditHistory } from '../core/history.js';
+import { FsFilePathError } from '@jini-ai/platform/fs';
+import { ProjectError } from '../core/project.js';
+import { assertCandidatePaths, createProjectPaths, projectLimits } from './paths.js';
+import { createProjectStore, prepareDirectories, revisionToken } from './store.js';
+const POINTER = 'revision';
+function fail(code, message) {
+    throw new ProjectError({ code, message });
+}
+function sameRevision(left, right) {
+    return left.generation === right.generation && left.revisionId === right.revisionId;
+}
+/** Materialize a single immutable candidate in memory before invoking a whole-project validator.
+ * @complexity O(tree bytes + changes + path segments) time/space, all bounded by project limits.
+ */
+function changeFiles({ files: base, changes, paths, limits }) {
+    if (changes.length > limits.maxChanges)
+        fail('LIMIT', 'too many changes in one turn');
+    const files = new Map(base), seen = new Set();
+    for (const change of changes) {
+        const path = paths.check({ relativePath: change.op === 'create' ? change.relativePath : change.id });
+        if (seen.has(path))
+            fail('INVALID_CHANGE', `multiple operations for ${path}`);
+        seen.add(path);
+        changeFile({ files, change, path, limits });
+    }
+    assertCandidatePaths({ paths: [...files.keys()] });
+    assertTreeLimits({ files, limits });
+    return files;
+}
+function changeFile({ files, change, path, limits }) {
+    if (change.op === 'create') {
+        if (files.has(path))
+            fail('INVALID_CHANGE', `file already exists: ${path}`);
+    }
+    else if (!files.has(path))
+        fail('INVALID_CHANGE', `file not listed: ${path}`);
+    if (change.op === 'delete') {
+        files.delete(path);
+        return;
+    }
+    if (change.content.length > limits.maxFileBytes)
+        fail('LIMIT', `file exceeds byte limit: ${path}`);
+    const bytes = new TextEncoder().encode(change.content);
+    if (bytes.byteLength > limits.maxFileBytes)
+        fail('LIMIT', `file exceeds byte limit: ${path}`);
+    files.set(path, bytes);
+}
+function assertTreeLimits({ files, limits }) {
+    if (files.size > limits.maxFiles)
+        fail('LIMIT', 'candidate exceeds file count');
+    let total = 0;
+    for (const bytes of files.values())
+        total += bytes.byteLength;
+    if (total > limits.maxTreeBytes)
+        fail('LIMIT', 'candidate exceeds tree byte limit');
+}
+function candidateView({ files }) {
+    return Object.freeze({
+        paths: Object.freeze([...files.keys()].sort()),
+        async readBytes({ relativePath }, _options = {}) {
+            const bytes = files.get(relativePath);
+            if (!bytes)
+                fail('INVALID_PATH', `file not in candidate: ${relativePath}`);
+            return Uint8Array.from(bytes);
+        },
+    });
+}
+/** Bound host diagnostics before retaining or sending them back to a model. */
+function diagnosticsFor(input = []) {
+    return input.slice(0, 100).map(item => ({ code: item.code.slice(0, 100), message: item.message.slice(0, 2000),
+        ...(item.relativePath === undefined ? {} : { relativePath: item.relativePath.slice(0, 200) }) }));
+}
+/** Timeout/cancellation races the validator, even when an adapter ignores its AbortSignal.
+ * @complexity O(candidate bytes) only in the adapter; this wrapper uses O(1) resources.
+ */
+async function validateCandidate({ validator, candidate, signal, timeoutMs }) {
+    if (signal?.aborted)
+        fail('CANCELLED', 'turn cancelled');
+    if (!validator)
+        return [];
+    const controller = new AbortController();
+    const cancel = () => controller.abort(new ProjectError({ code: 'CANCELLED', message: 'turn cancelled' }));
+    signal?.addEventListener('abort', cancel, { once: true });
+    const timer = setTimeout(() => controller.abort(new ProjectError({ code: 'VALIDATION', message: 'validation timed out' })), timeoutMs);
+    let onAbort = () => { };
+    const aborted = new Promise((_resolve, reject) => {
+        onAbort = () => reject(controller.signal.reason);
+        controller.signal.addEventListener('abort', onAbort, { once: true });
+    });
+    try {
+        const result = await Promise.race([validator.validate({ candidate, signal: controller.signal }), aborted]);
+        if (result.ok)
+            return [];
+        const diagnostics = diagnosticsFor(result.diagnostics);
+        return diagnostics.length ? diagnostics : [{ code: 'VALIDATION', message: 'candidate refused by validator' }];
+    }
+    catch (cause) {
+        if (cause instanceof ProjectError)
+            throw cause;
+        throw new ProjectError({ code: 'VALIDATION', message: 'project validator failed', cause });
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', cancel);
+        controller.signal.removeEventListener('abort', onAbort);
+    }
+}
+/** Open real local files with process-crash roll-forward and session-local pointer history.
+ * @throws ProjectError for conflicts, unsafe paths, corruption, limits or I/O failure.
+ * @complexity O(files + bytes) opening/capture; each turn is bounded by configured tree limits.
+ */
+export async function openFileTreeProject(input, options = {}) {
+    const limits = projectLimits(options);
+    const historyLimit = options.historyLimit ?? 50;
+    if (!Number.isSafeInteger(historyLimit) || historyLimit <= 0)
+        throw new TypeError('historyLimit must be positive');
+    try {
+        const directories = await prepareDirectories(input);
+        const paths = createProjectPaths({ root: directories.root, policy: input.policy, limits });
+        const store = createProjectStore({ ...directories, paths, limits });
+        const project = assembleProject({ store, paths, limits, historyLimit, validator: input.validator });
+        await project.capture();
+        return project;
+    }
+    catch (cause) {
+        if (cause instanceof ProjectError || cause instanceof TypeError)
+            throw cause;
+        throw new ProjectError({ code: 'STORAGE', message: 'could not open local project', cause });
+    }
+}
+/** One process-local queue plus the shared file lock covers all mutation paths.
+ * Validation releases the shared lock, then checks generation AND working-tree drift again.
+ */
+function assembleProject({ store, paths, limits, historyLimit, validator }) {
+    let current = null, closed = false;
+    let selectingCapture;
+    let queue = Promise.resolve();
+    const pointer = {
+        listParts: async () => [{ id: POINTER }],
+        readPart: async () => selected().revision,
+        replacePart: async ({ id, content }) => {
+            if (id !== POINTER)
+                fail('INVALID_CHANGE', 'private revision pointer only');
+            if (!selectingCapture)
+                await store.preflight({ current, revisionId: content });
+            current = await store.select({ current: selected(), revisionId: content, captured: selectingCapture });
+        },
+        validate: async () => ({ ok: true }),
+        snapshot: async () => ({ id: selected().revision, parts: { [POINTER]: selected().revision } }),
+        restore: async () => { fail('INVALID_CHANGE', 'use project.restore'); },
+    };
+    const rawHistory = createEditHistory({ target: pointer }, { limit: historyLimit });
+    function selected() {
+        if (!current)
+            fail('CORRUPT', 'project has no current revision');
+        return current;
+    }
+    function serial(work) {
+        const next = queue.then(async () => {
+            if (closed)
+                fail('CLOSED', 'project is closed');
+            return work();
+        });
+        queue = next.catch(() => { });
+        return next;
+    }
+    /** Never replay a local stack over a different writer's generation, even after A→B→A. */
+    async function synchronize() {
+        const disk = await store.recover();
+        if (current && (!disk || !sameRevision(revisionToken({ current }), revisionToken({ current: disk })))) {
+            current = disk;
+            rawHistory.clear();
+            fail('CONFLICT', 'project generation changed; local history cleared');
+        }
+        current = disk;
+    }
+    async function locked(work) {
+        try {
+            return await store.locked(async () => { await synchronize(); return work(); });
+        }
+        catch (cause) {
+            // Only synchronize() clears history: another writer's generation makes the stacks unsound.
+            // A stale caller token or a file written mid-scan leaves this handle's stacks coherent.
+            if (cause instanceof ProjectError)
+                throw cause;
+            if (cause instanceof FsFilePathError)
+                throw new ProjectError({ code: 'INVALID_PATH', message: cause.message, cause });
+            throw new ProjectError({ code: 'STORAGE', message: 'project storage operation failed', cause });
+        }
+    }
+    /** The pointer write is the only and last write inside history's recording callback. */
+    async function record({ revisionId, captured, label }) {
+        if (!captured)
+            await store.preflight({ current, revisionId });
+        selectingCapture = captured;
+        try {
+            await rawHistory.transaction({ work: recording => recording.replacePart({ id: POINTER, content: revisionId }) }, label === undefined ? {} : { label });
+        }
+        finally {
+            selectingCapture = undefined;
+        }
+    }
+    async function collect() {
+        const revisions = new Set([selected().revision]);
+        for (const entry of rawHistory.retainedEntries()) {
+            for (const change of entry.changes) {
+                revisions.add(change.before);
+                revisions.add(change.after);
+            }
+        }
+        await store.collect({ revisions });
+    }
+    /** Drift becomes a normal revision without overwriting what npm/editor/user just wrote. */
+    async function captureLocked() {
+        const { files, observed } = await store.scan({ current });
+        const revisionId = await store.prepare({ files });
+        const previous = current?.revision;
+        if (!current)
+            current = await store.select({ current: null, revisionId, captured: observed });
+        else if (current.revision !== revisionId)
+            await record({ revisionId, captured: observed, label: 'Capture external changes' });
+        else
+            current = await store.observe({ current, observed });
+        if (previous !== revisionId)
+            await collect();
+        return files;
+    }
+    /** The caller's view is stale (e.g. drift captured as its own entry); history stays intact. */
+    function checkExpected(expected) {
+        if (sameRevision(expected, revisionToken({ current: selected() })))
+            return;
+        fail('CONFLICT', 'expected revision is stale; capture/refresh and retry');
+    }
+    async function applyTurn(input, options = {}) {
+        return serial(async () => {
+            const files = await locked(async () => {
+                const base = await captureLocked();
+                checkExpected(input.expectedRevision);
+                return changeFiles({ files: base, changes: input.changes, paths, limits });
+            });
+            const diagnostics = await validateCandidate({ validator, candidate: candidateView({ files }), signal: options.signal, timeoutMs: limits.validationTimeoutMs });
+            return locked(async () => {
+                // Validation can run arbitrary host code; do not silently erase edits made while it ran.
+                await captureLocked();
+                checkExpected(input.expectedRevision);
+                if (options.signal?.aborted)
+                    fail('CANCELLED', 'turn cancelled');
+                if (diagnostics.length)
+                    return { status: 'rejected', revision: revisionToken({ current: selected() }), diagnostics };
+                return commitFiles({ files, label: options.label });
+            });
+        });
+    }
+    async function commitFiles({ files, label }) {
+        const revisionId = await store.prepare({ files });
+        if (revisionId === selected().revision)
+            return { status: 'unchanged', revision: revisionToken({ current: selected() }), diagnostics: [] };
+        await record({ revisionId, ...(label === undefined ? {} : { label }) });
+        await collect();
+        return { status: 'committed', revision: revisionToken({ current: selected() }), diagnostics: [] };
+    }
+    async function replay(side) {
+        return serial(() => locked(async () => {
+            await captureLocked();
+            const entry = await rawHistory[side]();
+            await collect();
+            return entry;
+        }));
+    }
+    async function restoreRevision({ revisionId, label }) {
+        return serial(() => locked(async () => {
+            await captureLocked();
+            await retainedManifest({ store, revisionId });
+            if (selected().revision !== revisionId)
+                await record({ revisionId, ...(label === undefined ? {} : { label }) });
+            await collect();
+            return revisionToken({ current: selected() });
+        }));
+    }
+    async function textSnapshot() {
+        return serial(() => locked(async () => {
+            const files = await captureLocked();
+            const parts = Object.create(null);
+            for (const [path, bytes] of files)
+                parts[path] = decodeText({ bytes });
+            return { id: selected().revision, parts };
+        }));
+    }
+    async function restoreText({ snapshot }) {
+        // Snapshot IDs name retained manifests. Replaying them preserves binary files and deletions.
+        const before = rawHistory.entries().at(-1);
+        await restoreRevision({ revisionId: snapshot.id, label: `restore ${snapshot.id}` });
+        const after = rawHistory.entries().at(-1);
+        return before === after ? null : after ?? null;
+    }
+    const history = {
+        transaction: async () => fail('INVALID_CHANGE', 'use project.applyTurn for atomic transactions'),
+        canUndo: rawHistory.canUndo, canRedo: rawHistory.canRedo,
+        undo: () => replay('undo'), redo: () => replay('redo'), restore: restoreText,
+        entries: rawHistory.entries, retainedEntries: rawHistory.retainedEntries, clear: rawHistory.clear,
+    };
+    const target = {
+        listParts: () => serial(() => locked(async () => [...(await captureLocked()).keys()].sort().map(id => ({ id })))),
+        readPart: ({ id }) => serial(() => locked(async () => {
+            paths.check({ relativePath: id });
+            const manifest = await store.manifest({ revisionId: selected().revision });
+            if (!manifest.files.some(file => file.path === id))
+                fail('INVALID_CHANGE', `file not listed: ${id}`);
+            return decodeText({ bytes: await store.readWorkingFile({ relativePath: id }) });
+        })),
+        replacePart: async (edit) => {
+            const outcomes = await applyEdits({ edits: [edit] });
+            const outcome = outcomes[0];
+            if (outcome.status === 'failed')
+                throw outcome.error;
+            if (outcome.status === 'rejected')
+                fail('VALIDATION', outcome.reason);
+        },
+        validate: async () => ({ ok: true }), // replacePart owns whole-candidate validation, including direct calls.
+        snapshot: textSnapshot, restore: async (input) => { await restoreText(input); },
+    };
+    async function applyEdits({ edits }, options = {}) {
+        const expectedRevision = await project.capture();
+        const changes = edits.map(edit => ({ op: 'replace', ...edit }));
+        try {
+            const result = await applyTurn({ expectedRevision, changes }, options);
+            if (result.status !== 'rejected')
+                return edits.map(({ id }) => ({ status: 'applied', id }));
+            const reason = result.diagnostics.map(diagnostic => diagnostic.message).join('\n');
+            return edits.map(({ id }) => ({ status: 'rejected', id, reason }));
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            return edits.map(({ id }) => ({ status: 'failed', id, error: failure }));
+        }
+    }
+    const project = {
+        target, history, applyTurn, applyEdits,
+        getRevision: () => serial(() => locked(async () => revisionToken({ current: selected() }))),
+        capture: () => serial(() => locked(async () => { await captureLocked(); await collect(); return revisionToken({ current: selected() }); })),
+        snapshot: () => serial(() => locked(async () => { await captureLocked(); return { revisionId: selected().revision }; })),
+        restore: ({ snapshot }, options = {}) => restoreRevision({ revisionId: snapshot.revisionId, ...options }),
+        close: () => serial(() => locked(async () => { rawHistory.clear(); await collect(); closed = true; })),
+    };
+    return project;
+}
+/** Keep a leading BOM in the text so a read-modify-replace round trip preserves the file's bytes. */
+function decodeText({ bytes }) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch (cause) {
+        throw new ProjectError({ code: 'INVALID_CHANGE', message: 'binary asset cannot be read as UTF-8 text; use a candidate byte read', cause });
+    }
+}
+async function retainedManifest({ store, revisionId }) {
+    try {
+        await store.manifest({ revisionId });
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT')
+            fail('SNAPSHOT_EXPIRED', 'snapshot revision is no longer retained');
+        throw cause;
+    }
+}
+//# sourceMappingURL=project.js.map

package/dist/node/store.d.ts

@@ -0,0 +1,102 @@
+import { type ProjectLimits, type RevisionToken } from '../core/project.js';
+import { type ProjectPaths } from './paths.js';
+export interface ManifestFile {
+    readonly path: string;
+    readonly hash: string;
+    readonly size: number;
+}
+export interface Manifest {
+    readonly version: 1;
+    readonly files: readonly ManifestFile[];
+}
+interface Fingerprint {
+    readonly size: number;
+    readonly mtimeMs: number;
+    readonly ctimeMs: number;
+}
+export interface Current {
+    readonly version: 1;
+    readonly root: string;
+    readonly revision: string;
+    readonly generation: number;
+    readonly pending: {
+        readonly from: string | null;
+    } | null;
+    readonly observed: Readonly<Record<string, Fingerprint>>;
+}
+export type StoreCheckpoint = 'objects' | 'manifest' | 'journal' | 'delete' | 'write' | 'prune' | 'clear';
+export interface StoreInput {
+    root: string;
+    stateDir: string;
+    paths: ProjectPaths;
+    limits: ProjectLimits;
+}
+export interface StoreOptions {
+    /** Internal deterministic process-crash seam; never needed by the public factory. */
+    checkpoint?: (input: {
+        step: StoreCheckpoint;
+    }) => void | Promise<void>;
+}
+/** Immutable object/revision IDs are SHA-256 of their exact bytes. */
+export declare function digest({ bytes }: {
+    bytes: Uint8Array | string;
+}, _options?: {}): string;
+/** Host state is physically separate from the watched/served tree, in both directions.
+ * @throws ProjectError INVALID_PATH when either canonical directory contains the other.
+ * @complexity O(path length) plus constant directory I/O.
+ */
+export declare function prepareDirectories({ root, stateDir }: {
+    root: string;
+    stateDir: string;
+}, _options?: {}): Promise<{
+    root: string;
+    stateDir: string;
+}>;
+/** Content-addressed persistence and idempotent roll-forward. Call mutations inside locked().
+ * @complexity O(bytes + files log files + files × depth²) for capture; memory bounded by maxTreeBytes.
+ */
+export declare function createProjectStore({ root, stateDir, paths, limits }: StoreInput, options?: StoreOptions): {
+    readCurrent: () => Promise<Current | null>;
+    manifest: ({ revisionId }: {
+        revisionId: string;
+    }) => Promise<Manifest>;
+    object: ({ file }: {
+        file: ManifestFile;
+    }) => Promise<Uint8Array>;
+    prepare: ({ files }: {
+        files: ReadonlyMap<string, Uint8Array>;
+    }) => Promise<string>;
+    scan: ({ current }: {
+        current: Current | null;
+    }) => Promise<{
+        files: Map<string, Uint8Array>;
+        observed: Record<string, Fingerprint>;
+    }>;
+    select: ({ current, revisionId, captured }: {
+        current: Current | null;
+        revisionId: string;
+        captured?: Readonly<Record<string, Fingerprint>> | undefined;
+    }) => Promise<Current>;
+    collect: ({ revisions }: {
+        revisions: ReadonlySet<string>;
+    }) => Promise<void>;
+    preflight: ({ current, revisionId }: {
+        current: Current | null;
+        revisionId: string;
+    }) => Promise<void>;
+    observe: ({ current, observed }: {
+        current: Current;
+        observed: Current["observed"];
+    }) => Promise<Current>;
+    readWorkingFile: ({ relativePath }: {
+        relativePath: string;
+    }) => Promise<Uint8Array>;
+    locked: <T>(run: () => Promise<T>) => Promise<T>;
+    recover: () => Promise<Current | null>;
+};
+export declare function revisionToken({ current }: {
+    current: Current;
+}, _options?: {}): RevisionToken;
+export type ProjectStore = ReturnType<typeof createProjectStore>;
+export {};
+//# sourceMappingURL=store.d.ts.map