@llblab/pi-kit 0.18.1 → 0.19.0

package/node_modules/@llblab/pi-state-flow/dist/lib/publication.js

@@ -1,437 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, parse, resolve, sep } from "node:path";
-/** Missing policy on an existing runtime preserves 0.4 synchronous behavior. */
-export function resolveRemotePublicationPolicy(value, options) {
-    if (value === undefined) {
-        return options.legacyRuntime
-            ? { mode: "transition", migratedLegacyDefault: true }
-            : { mode: "turn-end", migratedLegacyDefault: false };
-    }
-    if (value !== "off" && value !== "turn-end" && value !== "transition") {
-        throw new Error("State Flow remote publication mode must be off, turn-end, or transition");
-    }
-    return { mode: value, migratedLegacyDefault: false };
-}
-export function parseRemotePublicationPolicyDocument(value, options) {
-    if (value === undefined)
-        return resolveRemotePublicationPolicy(undefined, options);
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        throw new Error("Invalid remote publication policy document");
-    const document = value;
-    if (Object.keys(document).sort().join(",") !== "mode,version" || document.version !== 1) {
-        throw new Error("Invalid remote publication policy document");
-    }
-    return resolveRemotePublicationPolicy(document.mode, { legacyRuntime: false });
-}
-export function serializeRemotePublicationPolicyDocument(policy) {
-    return { version: 1, mode: policy.mode };
-}
-export function remotePublicationDestinationKey(destination) {
-    if (!destination.remote.trim() || destination.remote !== destination.remote.trim()
-        || !destination.ref.trim() || destination.ref !== destination.ref.trim()) {
-        throw new Error("Remote publication destination requires non-empty trimmed remote and ref");
-    }
-    return JSON.stringify([resolve(destination.gitCommonDir), destination.remote, destination.ref]);
-}
-function isCommit(value) {
-    return typeof value === "string" && /^[0-9a-f]{40,64}$/.test(value);
-}
-export function createPublicationQueue(destination, target) {
-    if (!isCommit(target))
-        throw new Error("Publication queue target must be an exact commit");
-    remotePublicationDestinationKey(destination);
-    return { version: 1, destination: structuredClone(destination), target, status: "pending", attempt: 0 };
-}
-export function coalescePublicationTarget(state, destination, target, isAncestor, observer) {
-    validatePublicationQueue(state);
-    if (!isCommit(target))
-        throw new Error("Publication queue target must be an exact commit");
-    if (remotePublicationDestinationKey(state.destination) !== remotePublicationDestinationKey(destination))
-        throw new Error("Publication queue destination changed");
-    if (target === state.target || isAncestor(target, state.target))
-        return structuredClone(state);
-    const previous = structuredClone(state);
-    if (!isAncestor(state.target, target)) {
-        // A reset or re-initialized journal rewrites the lineage. The queued commit can never
-        // fast-forward the remote again, so retarget the live lineage instead of wedging every
-        // later turn-end; the retired commit stays in the local Git object store.
-        observer?.onDivergedLineage?.(previous);
-        const { confirmed: _confirmed, error: _error, ...live } = previous;
-        return { ...live, target, status: "pending", attempt: 0 };
-    }
-    return { ...previous, target, status: "pending", attempt: 0, error: undefined };
-}
-export function parsePublicationQueue(content) {
-    let value;
-    try {
-        value = JSON.parse(content);
-    }
-    catch {
-        throw new Error("Invalid publication queue JSON");
-    }
-    validatePublicationQueue(value);
-    return structuredClone(value);
-}
-export function serializePublicationQueue(state) {
-    validatePublicationQueue(state);
-    return `${JSON.stringify(state)}\n`;
-}
-export function beginPublicationAttempt(state) {
-    validatePublicationQueue(state);
-    const { error: _error, ...current } = structuredClone(state);
-    return { ...current, status: "pushing", attempt: state.attempt + 1 };
-}
-export function failPublicationAttempt(state, error) {
-    validatePublicationQueue(state);
-    if (state.status !== "pushing" || !error.trim())
-        throw new Error("Only an active publication attempt can fail with a bounded error");
-    return { ...structuredClone(state), status: "failed", error: error.trim().slice(0, 1000) };
-}
-export function confirmPublicationTarget(state, pushed, isAncestor) {
-    validatePublicationQueue(state);
-    if (!isCommit(pushed))
-        throw new Error("Confirmed publication target must be an exact commit");
-    if (pushed === state.target)
-        return undefined;
-    if (!isAncestor(pushed, state.target))
-        throw new Error("Publication confirmation does not cover the queued lineage");
-    return { ...structuredClone(state), confirmed: pushed, status: "pending", error: undefined };
-}
-/** A recovered pushing state is unconfirmed and safely retryable after restart. */
-export function recoverPublicationQueue(state) {
-    validatePublicationQueue(state);
-    return state.status === "pushing"
-        ? { ...structuredClone(state), status: "pending", error: "previous publication attempt ended without confirmation" }
-        : structuredClone(state);
-}
-export function validatePublicationQueue(value) {
-    if (typeof value !== "object" || value === null || Array.isArray(value))
-        throw new Error("Invalid publication queue document");
-    const v = value;
-    if (v.version !== 1 || !isCommit(v.target) || !Number.isSafeInteger(v.attempt) || v.attempt < 0
-        || (v.status !== "pending" && v.status !== "pushing" && v.status !== "failed")
-        || typeof v.destination !== "object" || v.destination === null)
-        throw new Error("Invalid publication queue document");
-    remotePublicationDestinationKey(v.destination);
-    if (v.confirmed !== undefined && !isCommit(v.confirmed))
-        throw new Error("Invalid publication queue document");
-    if (v.error !== undefined && (typeof v.error !== "string" || !v.error.trim()))
-        throw new Error("Invalid publication queue document");
-    const allowed = new Set(["version", "destination", "target", "confirmed", "status", "attempt", "error"]);
-    if (Object.keys(v).some((key) => !allowed.has(key)))
-        throw new Error("Invalid publication queue document");
-}
-export function publicationQueuePath(destination) {
-    const key = remotePublicationDestinationKey(destination);
-    const name = createHash("sha256").update(key).digest("hex");
-    return resolve(destination.gitCommonDir, "state-flow-publication", `${name}.json`);
-}
-function assertNoSymlinkAncestors(path) {
-    const absolute = resolve(path);
-    const root = parse(absolute).root;
-    let current = root;
-    for (const segment of absolute.slice(root.length).split(sep).filter(Boolean)) {
-        current = resolve(current, segment);
-        const stat = lstatSync(current, { throwIfNoEntry: false });
-        if (!stat)
-            break;
-        if (stat.isSymbolicLink())
-            throw new Error("Publication queue path cannot traverse symlink ancestors");
-        if (!stat.isDirectory())
-            throw new Error("Publication queue ancestor must be a directory");
-    }
-}
-function readWorkerLease(path) {
-    assertNoSymlinkAncestors(dirname(path));
-    const stat = lstatSync(path, { throwIfNoEntry: false });
-    if (!stat)
-        return undefined;
-    if (!stat.isFile())
-        throw new Error("Publication worker lease path must be a regular file");
-    let descriptor;
-    try {
-        descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return undefined; // A live owner may have released it.
-        throw error;
-    }
-    try {
-        if (!fstatSync(descriptor).isFile())
-            throw new Error("Publication worker lease path must be a regular file");
-        const source = readFileSync(descriptor, "utf8");
-        let value;
-        try {
-            value = JSON.parse(source);
-        }
-        catch {
-            throw new Error("Publication worker lease is malformed");
-        }
-        if (typeof value !== "object" || value === null || Array.isArray(value))
-            throw new Error("Publication worker lease is malformed");
-        const record = value;
-        if (Object.keys(record).sort().join(",") !== "pid,startedAt,token,version" || record.version !== 1
-            || !Number.isSafeInteger(record.pid) || record.pid <= 0 || record.pid > 2147483647
-            || typeof record.token !== "string" || !record.token.trim() || record.token !== record.token.trim()
-            || typeof record.startedAt !== "string" || !Number.isFinite(Date.parse(record.startedAt))) {
-            throw new Error("Publication worker lease is malformed");
-        }
-        return record;
-    }
-    finally {
-        closeSync(descriptor);
-    }
-}
-function processAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        return error.code !== "ESRCH";
-    }
-}
-export function acquirePublicationWorkerLease(queuePath) {
-    const path = `${resolve(queuePath)}.worker.lock`;
-    assertNoSymlinkAncestors(dirname(path));
-    const token = randomUUID();
-    const document = `${JSON.stringify({ version: 1, pid: process.pid, token, startedAt: new Date().toISOString() })}\n`;
-    const create = () => {
-        try {
-            writeFileSync(path, document, { flag: "wx", mode: 0o600 });
-        }
-        catch (error) {
-            if (error.code === "EEXIST")
-                return undefined;
-            throw error;
-        }
-        return { path, token, release() {
-                let current;
-                try {
-                    current = readWorkerLease(path);
-                }
-                catch {
-                    return;
-                }
-                // A live owner cannot be reclaimed, so release need not wait for queue writers.
-                if (current?.pid === process.pid && current.token === token)
-                    rmSync(path, { force: true });
-            } };
-    };
-    const lease = create();
-    if (lease)
-        return lease;
-    const current = readWorkerLease(path);
-    if (!current)
-        return create();
-    if (processAlive(current.pid))
-        return undefined;
-    // Only reclamation needs the existing queue writer gate; exclusive creation protects fresh claims.
-    const gate = `${resolve(queuePath)}.lock`;
-    assertNoSymlinkAncestors(dirname(gate));
-    let descriptor;
-    try {
-        descriptor = openSync(gate, "wx", 0o600);
-    }
-    catch (error) {
-        if (error.code === "EEXIST")
-            return undefined;
-        throw error;
-    }
-    try {
-        const owner = readWorkerLease(path);
-        if (owner && processAlive(owner.pid))
-            return undefined;
-        if (owner)
-            rmSync(path, { force: true });
-        return create(); // A fresh claimant may win the gap; never remove its replacement.
-    }
-    finally {
-        closeSync(descriptor);
-        rmSync(gate, { force: true });
-    }
-}
-export function loadPublicationQueue(path) {
-    const target = resolve(path);
-    assertNoSymlinkAncestors(dirname(target));
-    const stat = lstatSync(target, { throwIfNoEntry: false });
-    if (!stat)
-        return undefined;
-    if (!stat.isFile())
-        throw new Error("Publication queue path must be a regular file");
-    return parsePublicationQueue(readFileSync(target, "utf8"));
-}
-export function removePublicationQueue(path, expected) {
-    const target = resolve(path);
-    assertNoSymlinkAncestors(dirname(target));
-    const lock = `${target}.lock`;
-    let lockFd;
-    try {
-        lockFd = openSync(lock, "wx", 0o600);
-        const current = loadPublicationQueue(target);
-        if (!current || serializePublicationQueue(current) !== serializePublicationQueue(expected)) {
-            throw new Error("Publication queue compare-and-swap conflict");
-        }
-        rmSync(target);
-    }
-    finally {
-        if (lockFd !== undefined) {
-            closeSync(lockFd);
-            rmSync(lock, { force: true });
-        }
-    }
-}
-export function savePublicationQueue(path, state, expected) {
-    const target = resolve(path);
-    assertNoSymlinkAncestors(dirname(target));
-    mkdirSync(dirname(target), { recursive: true });
-    const lock = `${target}.lock`;
-    let lockFd;
-    try {
-        lockFd = openSync(lock, "wx", 0o600);
-        const existing = lstatSync(target, { throwIfNoEntry: false });
-        if (existing && !existing.isFile())
-            throw new Error("Publication queue path must be a regular file");
-        const previous = existing ? parsePublicationQueue(readFileSync(target, "utf8")) : undefined;
-        if (expected !== undefined && (previous === undefined
-            || serializePublicationQueue(previous) !== serializePublicationQueue(expected))) {
-            throw new Error("Publication queue compare-and-swap conflict");
-        }
-        if (expected === undefined && previous !== undefined)
-            throw new Error("Publication queue compare-and-swap requires the current receipt");
-        const temporary = `${target}.tmp-${process.pid}-${Date.now()}`;
-        try {
-            writeFileSync(temporary, serializePublicationQueue(state), { flag: "wx", mode: 0o600 });
-            renameSync(temporary, target);
-        }
-        finally {
-            rmSync(temporary, { force: true });
-        }
-        return { ...(previous === undefined ? {} : { previous }), current: structuredClone(state) };
-    }
-    finally {
-        if (lockFd !== undefined) {
-            closeSync(lockFd);
-            rmSync(lock, { force: true });
-        }
-    }
-}
-/** Execute one immutable target attempt; persistence/CAS remains the caller's responsibility. */
-export async function runPublicationWorker(state, push, current, isAncestor) {
-    const attempted = beginPublicationAttempt(state);
-    try {
-        await push(Object.freeze(structuredClone(attempted)));
-        const next = confirmPublicationTarget(current(), attempted.target, isAncestor);
-        return { attempted, ...(next === undefined ? {} : { next }) };
-    }
-    catch (error) {
-        return {
-            attempted,
-            next: failPublicationAttempt(attempted, error instanceof Error ? error.message : String(error)),
-        };
-    }
-}
-/** Own durable queue coalescing, worker leases, retries, generation fencing, and bounded shutdown. */
-export class PublicationWorkerController {
-    active = new Map();
-    ports;
-    stopped = false;
-    shutdownPromise;
-    constructor(ports) {
-        this.ports = ports;
-    }
-    enqueue(target) {
-        const destination = this.ports.resolveDestination();
-        if (!destination)
-            return;
-        const path = publicationQueuePath(destination);
-        const previous = loadPublicationQueue(path);
-        const next = previous
-            ? coalescePublicationTarget(previous, destination, target, this.ports.isAncestor, {
-                onDivergedLineage: (dropped) => this.ports.onDiverged(dropped, target),
-            })
-            : createPublicationQueue(destination, target);
-        savePublicationQueue(path, next, previous);
-    }
-    launch() {
-        if (this.stopped)
-            return;
-        let destination;
-        try {
-            destination = this.ports.resolveDestination();
-        }
-        catch (error) {
-            if (error instanceof Error && /ENOENT/.test(error.message))
-                return;
-            throw error;
-        }
-        if (!destination)
-            return;
-        const path = publicationQueuePath(destination);
-        if (this.active.has(path))
-            return;
-        let queued;
-        let lease;
-        try {
-            queued = loadPublicationQueue(path);
-            if (!queued)
-                return;
-            lease = acquirePublicationWorkerLease(path);
-        }
-        catch {
-            return;
-        }
-        if (!lease)
-            return;
-        const controller = new AbortController();
-        const done = runPublicationWorker(queued, ({ target }) => this.ports.push(destination, target, controller.signal), () => loadPublicationQueue(path) ?? queued, this.ports.isAncestor).then((result) => {
-            if (this.stopped)
-                return;
-            const current = loadPublicationQueue(path);
-            if (!current)
-                return;
-            if (result.next === undefined) {
-                if (current.target === result.attempted.target)
-                    removePublicationQueue(path, current);
-                return;
-            }
-            if (current.target === result.attempted.target || result.next.target === current.target)
-                savePublicationQueue(path, result.next, current);
-        }).catch(() => {
-            // Queue/CAS truth remains durable; status and a later activation expose retry.
-        }).finally(() => {
-            this.active.delete(path);
-            try {
-                lease.release();
-                if (!this.stopped && loadPublicationQueue(path)?.status === "pending")
-                    this.launch();
-            }
-            catch {
-                // Failed lease cleanup or malformed persistence stays inert until retry or repair.
-            }
-        });
-        this.active.set(path, { controller, done });
-    }
-    shutdown(waitMs) {
-        this.stopped = true;
-        return this.shutdownPromise ??= (async () => {
-            const workers = [...this.active.values()];
-            for (const { controller } of workers)
-                controller.abort();
-            if (workers.length === 0)
-                return true;
-            let timeout;
-            try {
-                return await Promise.race([
-                    Promise.all(workers.map(({ done }) => done)).then(() => true),
-                    new Promise((resolve) => { timeout = setTimeout(() => resolve(false), waitMs); }),
-                ]);
-            }
-            finally {
-                clearTimeout(timeout);
-            }
-        })();
-    }
-}

package/node_modules/@llblab/pi-state-flow/lib/discovery.ts

@@ -1,133 +0,0 @@
-import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
-import { hashArtifactSource, type ArtifactSourceIdentity } from "./artifact.ts";
-
-/** Opaque source metadata discovered without decoding or retaining Markdown bodies. */
-export interface ArtifactSourceCandidate extends ArtifactSourceIdentity {
-	/** Raw byte count used as a conservative maintenance token-budget ceiling. */
-	bytes: number;
-}
-
-export interface GlobalMarkdownDiscoveryResult {
-	sources: ArtifactSourceCandidate[];
-	removed: string[];
-	unavailable?: string;
-}
-
-export function getKnowledgeRoot(agentDir = getAgentDir()): string {
-	return resolve(agentDir, "knowledge");
-}
-
-function errorCode(error: unknown): string | undefined {
-	return error instanceof Error && "code" in error
-		? (error as NodeJS.ErrnoException).code
-		: undefined;
-}
-
-function isMissing(error: unknown): boolean {
-	return errorCode(error) === "ENOENT";
-}
-
-function isInside(root: string, path: string): boolean {
-	const child = relative(root, path);
-	return child === "" || (!isAbsolute(child) && child !== ".." && !child.startsWith(`..${sep}`));
-}
-
-function canonicalExistingPath(path: string): string | undefined {
-	try {
-		return realpathSync.native(path);
-	} catch (error) {
-		if (isMissing(error)) return undefined;
-		throw error;
-	}
-}
-
-function readRegularFile(path: string): Buffer | undefined {
-	let descriptor: number | undefined;
-	try {
-		descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
-		if (!fstatSync(descriptor).isFile()) return undefined;
-		return readFileSync(descriptor);
-	} catch (error) {
-		if (isMissing(error) || errorCode(error) === "ELOOP") return undefined;
-		throw error;
-	} finally {
-		if (descriptor !== undefined) closeSync(descriptor);
-	}
-}
-
-/** Discover regular `*.md` files beneath a Knowledge root without following directory or file symlinks. */
-export function discoverGlobalMarkdownSources(knowledgeRoot = getKnowledgeRoot()): ArtifactSourceCandidate[] {
-	const configuredRoot = resolve(knowledgeRoot);
-	const root = canonicalExistingPath(configuredRoot);
-	if (root === undefined) return [];
-	if (!statSync(root).isDirectory()) throw new Error(`Knowledge root is not a directory: ${configuredRoot}`);
-
-	const sources: ArtifactSourceCandidate[] = [];
-	const visit = (directory: string): void => {
-		const entries = readdirSync(directory, { withFileTypes: true })
-			.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
-		for (const entry of entries) {
-			const candidate = join(directory, entry.name);
-			let metadata;
-			try {
-				metadata = lstatSync(candidate);
-			} catch (error) {
-				if (isMissing(error)) continue;
-				throw error;
-			}
-			if (metadata.isSymbolicLink()) continue;
-
-			const canonical = canonicalExistingPath(candidate);
-			if (canonical === undefined || !isInside(root, canonical)) continue;
-			if (metadata.isDirectory()) {
-				visit(canonical);
-				continue;
-			}
-			if (!metadata.isFile() || !entry.name.endsWith(".md")) continue;
-
-			const body = readRegularFile(canonical);
-			if (body === undefined) continue;
-			sources.push({ path: canonical, hash: hashArtifactSource(body), bytes: body.byteLength });
-		}
-	};
-
-	visit(root);
-	return sources.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
-}
-
-/** Prove absence inside the current source root without following excluded symlink components. */
-function missingOwnedMarkdown(root: string, path: string): boolean {
-	if (!isAbsolute(path) || path !== resolve(path) || path === root || !isInside(root, path) || !path.endsWith(".md")) return false;
-	let candidate = root;
-	for (const segment of relative(root, path).split(sep)) {
-		candidate = join(candidate, segment);
-		const metadata = lstatSync(candidate, { throwIfNoEntry: false });
-		if (metadata === undefined) return true;
-		if (metadata.isSymbolicLink() || !metadata.isDirectory()) return false;
-	}
-	return false;
-}
-
-/** Source-owner discovery; retained paths let restart/status re-observe removals until publication. */
-export class GlobalMarkdownDiscovery {
-	readonly knowledgeRoot: string;
-	#knownPaths = new Set<string>();
-
-	constructor(knowledgeRoot = getKnowledgeRoot()) {
-		this.knowledgeRoot = resolve(knowledgeRoot);
-	}
-
-	refresh(retainedPaths: Iterable<string> = this.#knownPaths): GlobalMarkdownDiscoveryResult {
-		const root = canonicalExistingPath(this.knowledgeRoot);
-		if (root === undefined) return { sources: [], removed: [], unavailable: `Knowledge root is unavailable: ${this.knowledgeRoot}` };
-		const sources = discoverGlobalMarkdownSources(root);
-		const currentPaths = new Set(sources.map((source) => source.path));
-		const removed = [...new Set(retainedPaths)]
-			.filter((path) => !currentPaths.has(path) && missingOwnedMarkdown(root, path))
-			.sort();
-		this.#knownPaths = currentPaths;
-		return { sources, removed };
-	}
-}