@crouton-kit/tsym 0.1.0 → 0.2.0

package/dist/store/seed.js

@@ -0,0 +1,185 @@
+import { randomUUID } from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+import { cpSync, existsSync, lstatSync, readdirSync, realpathSync, renameSync, rmSync } from 'node:fs';
+import { connect } from 'node:net';
+import path from 'node:path';
+import { pathsForRoot } from '../server/lifecycle.js';
+import { NdjsonReader, WIRE_VERSION, writeFrame } from '../server/wire.js';
+import { readMetadata, sameFormat, writeMetadata } from './meta.js';
+/** Finds compatible sibling stores and installs one only after a complete copy validates. */
+export async function seedFromSibling(root, paths, expected, identity) {
+    const started = performance.now();
+    // A process that died mid-copy on a previous start leaves this behind; it is never valid to keep across a start.
+    rmSync(seedPath(paths), { recursive: true, force: true });
+    for (const candidate of siblings(root, paths, expected, identity)) {
+        try {
+            const copied = copyWhileLocked(candidate, paths) || await copyFromOwner(candidate, paths);
+            if (!copied)
+                continue;
+            const copiedMetadata = readMetadata(seedPath(paths));
+            if (copiedMetadata === null || copiedMetadata.root !== candidate.root || !sameFormat(copiedMetadata, identity))
+                throw new Error('copied metadata did not match the selected sibling');
+            writeMetadata(seedPath(paths), { ...copiedMetadata, root });
+            rmSync(paths.store, { recursive: true, force: true });
+            renameSync(seedPath(paths), paths.store);
+            return { root: candidate.root, bytes: directoryBytes(paths.store), durationMs: performance.now() - started };
+        }
+        catch {
+            rmSync(seedPath(paths), { recursive: true, force: true });
+        }
+    }
+    return undefined;
+}
+/** Copies a resident's store after the owner checkpointed it. The owner excludes its process-local marker. */
+export function copyStore(source, destination) {
+    if (existsSync(destination))
+        throw new Error(`Seed destination already exists: ${destination}.`);
+    cpSync(source, destination, { recursive: true, filter: (entry) => path.basename(entry) !== '.tsym-owner' });
+    return directoryBytes(destination);
+}
+/** Returns the wire refusal reason, keeping the owner’s destination safety contract testable. */
+export function refuseSeed(dest, cacheBase, bootstrapped, busy) {
+    if (!bootstrapped)
+        return 'The resident has not bootstrapped a store.';
+    if (busy)
+        return 'The resident is writing its store.';
+    if (typeof dest !== 'string' || !inside(cacheBase, dest) || existsSync(dest))
+        return 'The seed destination must be a new directory inside the tsym cache.';
+    return undefined;
+}
+function siblings(root, paths, expected, identity) {
+    const candidates = [];
+    const base = path.dirname(paths.state);
+    for (const entry of readdirSync(base, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const store = path.join(base, entry.name, 'store');
+        let metadata;
+        try {
+            metadata = readMetadata(store);
+        }
+        catch {
+            continue;
+        }
+        if (metadata === null || metadata.root === root || !sameFormat(metadata, identity))
+            continue;
+        if (fileDifference(metadata.files, expected.files) !== 0)
+            continue;
+        candidates.push({ root: metadata.root, store, metadata });
+    }
+    return candidates;
+}
+function copyWhileLocked(candidate, paths) {
+    let lock;
+    try {
+        lock = new DatabaseSync(pathsForRoot(candidate.root).lock);
+        lock.exec('BEGIN EXCLUSIVE');
+        copyStore(candidate.store, seedPath(paths));
+        return true;
+    }
+    catch (error) {
+        if (!isBusy(error))
+            throw error;
+        return false;
+    }
+    finally {
+        try {
+            lock?.close();
+        }
+        catch { }
+    }
+}
+async function copyFromOwner(candidate, paths) {
+    const destination = seedPath(paths);
+    const sourcePaths = pathsForRoot(candidate.root);
+    try {
+        const response = await requestSeed(sourcePaths.port, candidate.root, destination);
+        return response.root === candidate.root && response.store === destination;
+    }
+    catch {
+        return false;
+    }
+}
+function requestSeed(port, root, dest) {
+    return new Promise((resolve, reject) => {
+        const socket = connect(port);
+        const reader = new NdjsonReader();
+        const requestId = randomUUID();
+        const timer = setTimeout(() => fail(new Error('seed request timed out')), 30_000);
+        let settled = false;
+        const finish = (value) => { if (!settled) {
+            settled = true;
+            clearTimeout(timer);
+            socket.end();
+            resolve(value);
+        } };
+        const fail = (error) => { if (!settled) {
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            reject(error);
+        } };
+        socket.on('connect', () => writeFrame(socket, { version: WIRE_VERSION, requestId, root, operation: 'seed', seed: { dest } }));
+        socket.on('data', (chunk) => {
+            for (const value of reader.push(chunk)) {
+                const frame = value;
+                if (frame.type !== 'response' || frame.requestId !== requestId)
+                    continue;
+                const answer = frame.completion.answer;
+                const data = answer?.data;
+                const node = Array.isArray(data) ? data[0] : data;
+                if (node?.element === 'seed' && typeof node.attributes?.root === 'string' && typeof node.attributes.store === 'string')
+                    finish({ root: node.attributes.root, store: node.attributes.store });
+                else
+                    fail(new Error('seed request was refused'));
+            }
+        });
+        socket.on('error', fail);
+        socket.on('close', () => { if (!settled)
+            fail(new Error('seed owner closed without responding')); });
+    });
+}
+function seedPath(paths) { return path.join(paths.state, 'store.seed'); }
+function fileDifference(left, right) {
+    const files = new Set([...Object.keys(left), ...Object.keys(right)]);
+    let differing = 0;
+    for (const file of files)
+        if (left[file] !== right[file])
+            differing++;
+    return differing;
+}
+function directoryBytes(directory) {
+    let bytes = 0;
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            bytes += directoryBytes(file);
+        else if (entry.isFile())
+            bytes += lstatSync(file).size;
+    }
+    return bytes;
+}
+function isBusy(error) { return error.code === 'ERR_SQLITE_ERROR' && error.errcode === 5 || String(error).includes('database is locked'); }
+function inside(parent, child) {
+    try {
+        const physicalParent = realpathSync(parent);
+        const physicalChild = physicalPath(child);
+        const relative = path.relative(physicalParent, physicalChild);
+        return relative !== '' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+    }
+    catch {
+        return false;
+    }
+}
+function physicalPath(target) {
+    const missing = [];
+    let existing = path.resolve(target);
+    while (!existsSync(existing)) {
+        const parent = path.dirname(existing);
+        if (parent === existing)
+            throw new Error(`No existing ancestor for ${target}.`);
+        missing.unshift(path.basename(existing));
+        existing = parent;
+    }
+    return path.join(realpathSync(existing), ...missing);
+}

package/dist/store/store.d.ts

@@ -24,10 +24,12 @@ export declare class Store {
     private boundedConnection;
     private closed;
     private readonly boundedQueryTimeoutMs;
+    private writing;
     constructor(storePath: string, options?: StoreOptions);
     execute(statement: string, parameters?: Record<string, LbugValue>): StoreRow[];
     /** Executes a read query on a separate connection whose 30-second engine timeout never affects writes. */
     executeBounded(statement: string, parameters?: Record<string, LbugValue>): StoreRow[];
+    get busy(): boolean;
     transaction<T>(work: () => T): T;
     checkpoint(): void;
     close(): void;

package/dist/store/store.js

@@ -38,6 +38,7 @@ export class Store {
     boundedConnection;
     closed = false;
     boundedQueryTimeoutMs;
+    writing = false;
     constructor(storePath, options = {}) {
         this.path = path.resolve(storePath);
         this.boundedQueryTimeoutMs = options.boundedQueryTimeoutMs ?? DEFAULT_BOUNDED_QUERY_TIMEOUT_MS;
@@ -92,9 +93,13 @@ export class Store {
             throw new StoreReadOnlyError();
         return collect(connection.executeSync(prepared, parameters));
     }
+    get busy() { return this.writing; }
     transaction(work) {
-        this.execute('BEGIN TRANSACTION');
+        if (this.writing)
+            throw new Error('Store transaction is already in progress.');
+        this.writing = true;
         try {
+            this.execute('BEGIN TRANSACTION');
             const value = work();
             this.execute('COMMIT');
             return value;
@@ -106,6 +111,9 @@ export class Store {
             catch { }
             throw error;
         }
+        finally {
+            this.writing = false;
+        }
     }
     checkpoint() {
         this.execute('CHECKPOINT');
@@ -171,7 +179,8 @@ function collect(result) {
     const rows = [];
     for (const item of results) {
         try {
-            rows.push(...item.getAllSync());
+            for (const row of item.getAllSync())
+                rows.push(row);
         }
         finally {
             item.close();

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@crouton-kit/tsym",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Symbol-level reading of a TypeScript codebase for agents.",
   "type": "module",
   "license": "MIT",
   "bin": {
-    "tsym": "./bin/tsym.js"
+    "tsym": "bin/tsym.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",