@undefineds.co/xpod 0.4.19 → 0.4.25

package/dist/cli/agent-fs/pod-lower.js

@@ -0,0 +1,398 @@
+"use strict";
+/**
+ * PodHttpLowerFileSystem - dependency-free model of the operations an AgentFS
+ * Pod lower filesystem must perform over the existing authenticated Pod HTTP
+ * surface.
+ *
+ * It is deliberately transport-level (not a simulated mount): a native helper
+ * would call the same HTTP operations. Key contracts:
+ * - Directory enumeration is metadata only and never fetches file bodies.
+ * - Reads use HTTP Range and only transfer the requested slice when the server
+ *   supports it; a 200 response is sliced but reported as `rangeIgnored`.
+ * - Writes are conditional: create uses `If-None-Match: *`, overwrite/delete use
+ *   `If-Match: <version>`; 412 becomes a conflict, never an unconditional write.
+ * - No persistent body cache: only version tokens are memoized, and they can be
+ *   invalidated on external change. Dirty/pending local operations are kept
+ *   until they are explicitly committed or discarded.
+ * - The Pod remains the content authority; SQLite delta (here: pending ops) is
+ *   only client-side state waiting to be written back.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PodHttpLowerFileSystem = exports.PodLowerNotFoundError = exports.PodLowerConflictError = exports.PodLowerHttpError = void 0;
+class PodLowerHttpError extends Error {
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'PodLowerHttpError';
+    }
+}
+exports.PodLowerHttpError = PodLowerHttpError;
+class PodLowerConflictError extends PodLowerHttpError {
+    constructor(message = 'Pod resource version conflict') {
+        super(412, message);
+        this.name = 'PodLowerConflictError';
+    }
+}
+exports.PodLowerConflictError = PodLowerConflictError;
+class PodLowerNotFoundError extends PodLowerHttpError {
+    constructor(message = 'Pod resource not found') {
+        super(404, message);
+        this.name = 'PodLowerNotFoundError';
+    }
+}
+exports.PodLowerNotFoundError = PodLowerNotFoundError;
+function normalizeRelativePath(input) {
+    const trimmed = input.replace(/^\/+/, '');
+    if (trimmed.length === 0) {
+        return '';
+    }
+    const segments = trimmed.split('/');
+    if (segments.some((segment) => segment.length === 0 || segment === '.' || segment === '..')) {
+        throw new Error(`Invalid Pod relative path: ${input}`);
+    }
+    return segments.join('/');
+}
+function encodeRelativePath(relative) {
+    if (relative.length === 0) {
+        return '';
+    }
+    return relative.split('/').map((segment) => encodeURIComponent(segment)).join('/');
+}
+function inferContentType(filePath) {
+    const lower = filePath.toLowerCase();
+    if (lower.endsWith('.txt') || lower.endsWith('.md'))
+        return 'text/plain';
+    if (lower.endsWith('.json'))
+        return 'application/json';
+    if (lower.endsWith('.ttl'))
+        return 'text/turtle';
+    if (lower.endsWith('.jsonld'))
+        return 'application/ld+json';
+    return 'application/octet-stream';
+}
+class PodHttpLowerFileSystem {
+    constructor(options) {
+        this.versionCache = new Map();
+        this.pending = new Map();
+        this.stats = {
+            requestCount: 0,
+            readRequests: 0,
+            bodiesReadBytes: 0,
+            writeRequests: 0,
+            bytesWritten: 0,
+        };
+        this.baseUrl = options.baseUrl.endsWith('/') ? options.baseUrl : `${options.baseUrl}/`;
+        this.request = options.request;
+        this.client = options.client;
+    }
+    resourceUrl(relativePath) {
+        const normalized = normalizeRelativePath(relativePath);
+        return new URL(encodeRelativePath(normalized), this.baseUrl).href;
+    }
+    /** Metadata-only listing. Never fetches file bodies. */
+    async readdir(relativePath) {
+        const normalized = normalizeRelativePath(relativePath);
+        const prefix = normalized.length === 0 ? '' : `${normalized}/`;
+        const listing = await this.client.listAll({ root: this.baseUrl, ...(prefix ? { pathPrefix: prefix } : {}) });
+        const children = new Map();
+        for (const entry of listing.entries) {
+            const remainder = entry.path.startsWith(prefix) ? entry.path.slice(prefix.length) : entry.path;
+            const segments = remainder.split('/').filter((segment) => segment.length > 0);
+            if (segments.length !== 1) {
+                continue;
+            }
+            const name = entry.type === 'container' ? `${segments[0]}/` : segments[0];
+            children.set(name, entry);
+        }
+        // Merge the client-side delta into the view. The Pod stays authoritative:
+        // this only changes what the workspace view reports, not the server.
+        for (const operation of this.pending.values()) {
+            const remainder = operation.path.startsWith(prefix) ? operation.path.slice(prefix.length) : operation.path;
+            const segments = remainder.split('/').filter((segment) => segment.length > 0);
+            if (segments.length !== 1) {
+                continue;
+            }
+            if (operation.op === 'delete') {
+                children.delete(operation.path);
+            }
+            else if (operation.op === 'write' && operation.create) {
+                children.set(operation.path, {
+                    path: operation.path,
+                    url: this.resourceUrl(operation.path),
+                    type: 'file',
+                    size: Buffer.from(operation.dataBase64, 'base64').length,
+                    ...(operation.contentType ? { contentType: operation.contentType } : {}),
+                });
+            }
+        }
+        return [...children.values()].map((entry) => this.toStat(entry)).sort((left, right) => (left.path < right.path ? -1 : 1));
+    }
+    /**
+     * Overlay view of the directory that includes the client-side delta. This is
+     * deliberately separate from `readdir`: `readdir` is the transport view of
+     * the Pod, while callers that render the working workspace use the overlay.
+     */
+    async overlayReaddir(relativePath) {
+        const normalized = normalizeRelativePath(relativePath);
+        const prefix = normalized.length === 0 ? '' : `${normalized}/`;
+        const entries = new Map((await this.readdir(relativePath)).map((entry) => [entry.path, entry]));
+        for (const operation of this.pending.values()) {
+            const remainder = operation.path.startsWith(prefix) ? operation.path.slice(prefix.length) : operation.path;
+            const segments = remainder.split('/').filter((segment) => segment.length > 0);
+            if (segments.length !== 1) {
+                continue;
+            }
+            if (operation.op === 'delete') {
+                entries.delete(operation.path);
+            }
+            else if (operation.op === 'write' && operation.create) {
+                entries.set(operation.path, {
+                    path: operation.path,
+                    type: 'file',
+                    size: Buffer.from(operation.dataBase64, 'base64').length,
+                    ...(operation.contentType ? { contentType: operation.contentType } : {}),
+                    ...(operation.baseVersion ? { version: operation.baseVersion } : {}),
+                });
+            }
+        }
+        return [...entries.values()].sort((left, right) => (left.path < right.path ? -1 : 1));
+    }
+    /** HEAD-style metadata lookup. Does not read the body. */
+    async stat(relativePath) {
+        const normalized = normalizeRelativePath(relativePath);
+        const url = this.resourceUrl(normalized);
+        const response = await this.send(url, { method: 'HEAD' });
+        if (response.status === 404) {
+            return undefined;
+        }
+        if (!response.ok) {
+            throw new PodLowerHttpError(response.status, `HEAD ${url} failed: ${response.status}`);
+        }
+        const stats = {
+            path: normalized,
+            type: 'file',
+            ...(response.headers.get('content-length') ? { size: Number(response.headers.get('content-length')) } : {}),
+            ...(response.headers.get('content-type') ? { contentType: response.headers.get('content-type') } : {}),
+            ...(response.headers.get('etag') ? { version: response.headers.get('etag') } : {}),
+            ...(response.headers.get('last-modified') ? { lastModified: response.headers.get('last-modified') } : {}),
+        };
+        this.versionCache.set(normalized, stats.version);
+        return stats;
+    }
+    /** Reads only the requested byte slice, using HTTP Range. */
+    async read(relativePath, offset = 0, length) {
+        const normalized = normalizeRelativePath(relativePath);
+        const url = this.resourceUrl(normalized);
+        const headers = {};
+        if (offset > 0 || length !== undefined) {
+            const end = length === undefined ? '' : offset + length - 1;
+            headers.Range = `bytes=${offset}-${end}`;
+        }
+        const response = await this.send(url, { method: 'GET', headers }, true);
+        if (response.status === 404) {
+            throw new PodLowerNotFoundError(`GET ${url} not found`);
+        }
+        if (response.status === 416) {
+            // Only a read at/after the resource total is a normal EOF; a 416 that
+            // claims the requested offset is inside the resource is a real error.
+            const total = /bytes\s+\*\/(\d+)/.exec(response.headers.get('content-range') ?? '');
+            const totalSize = total ? Number(total[1]) : undefined;
+            if (totalSize !== undefined && offset >= totalSize) {
+                return { data: Buffer.alloc(0), rangeIgnored: false };
+            }
+            throw new PodLowerHttpError(416, `range not satisfiable for ${normalized} at offset ${offset}`);
+        }
+        if (!response.ok) {
+            throw new PodLowerHttpError(response.status, `GET ${url} failed: ${response.status}`);
+        }
+        const buffer = Buffer.from(await response.arrayBuffer());
+        if (response.status === 206) {
+            const contentRange = response.headers.get('content-range') ?? '';
+            const match = /^bytes\s+(\d+)-/.exec(contentRange);
+            if (!match || Number(match[1]) !== offset) {
+                throw new PodLowerHttpError(502, `Range response for ${normalized} did not start at the requested offset (${offset}): ${contentRange}`);
+            }
+        }
+        const rangeIgnored = response.status === 200 && Object.keys(headers).length > 0;
+        const slice = rangeIgnored ? buffer.subarray(offset, length === undefined ? undefined : offset + length) : buffer;
+        return { data: Buffer.from(slice), rangeIgnored };
+    }
+    /** Conditional create: fails with a conflict when the target already exists. */
+    async create(relativePath, data, contentType) {
+        const normalized = normalizeRelativePath(relativePath);
+        const url = this.resourceUrl(normalized);
+        const response = await this.send(url, {
+            method: 'PUT',
+            headers: {
+                'Content-Type': contentType ?? inferContentType(normalized),
+                'If-None-Match': '*',
+            },
+            body: data,
+        }, true, data.length);
+        if (response.status === 412 || response.status === 409) {
+            throw new PodLowerConflictError(`Create conflict for ${normalized}`);
+        }
+        if (!response.ok) {
+            throw new PodLowerHttpError(response.status, `PUT ${url} failed: ${response.status}`);
+        }
+        this.invalidate(normalized);
+        const version = response.headers.get('etag') ?? undefined;
+        this.versionCache.set(normalized, version);
+        return { path: normalized, type: 'file', size: data.length, ...(contentType ? { contentType } : {}), ...(version ? { version } : {}) };
+    }
+    /** Conditional overwrite: requires the caller's version baseline. */
+    async write(relativePath, data, baseVersion, contentType) {
+        const normalized = normalizeRelativePath(relativePath);
+        const url = this.resourceUrl(normalized);
+        const response = await this.send(url, {
+            method: 'PUT',
+            headers: {
+                'Content-Type': contentType ?? inferContentType(normalized),
+                'If-Match': baseVersion,
+            },
+            body: data,
+        }, true, data.length);
+        if (response.status === 412) {
+            throw new PodLowerConflictError(`Stale version for ${normalized}`);
+        }
+        if (!response.ok) {
+            throw new PodLowerHttpError(response.status, `PUT ${url} failed: ${response.status}`);
+        }
+        this.invalidate(normalized);
+        const version = response.headers.get('etag') ?? undefined;
+        this.versionCache.set(normalized, version);
+        return { path: normalized, type: 'file', size: data.length, ...(contentType ? { contentType } : {}), ...(version ? { version } : {}) };
+    }
+    /**
+     * Conditional delete. A delete without a version baseline would be an
+     * unconditional write, so it is refused instead of sent.
+     */
+    async remove(relativePath, baseVersion) {
+        const normalized = normalizeRelativePath(relativePath);
+        if (!baseVersion) {
+            throw new PodLowerConflictError(`refusing unconditional delete of ${normalized}: no version baseline`);
+        }
+        const url = this.resourceUrl(normalized);
+        const headers = { 'If-Match': baseVersion };
+        const response = await this.send(url, { method: 'DELETE', headers }, true);
+        if (response.status === 412) {
+            throw new PodLowerConflictError(`Stale version for ${normalized}`);
+        }
+        if (response.status === 404) {
+            throw new PodLowerNotFoundError(`DELETE ${url} not found`);
+        }
+        if (!response.ok) {
+            throw new PodLowerHttpError(response.status, `DELETE ${url} failed: ${response.status}`);
+        }
+        this.invalidate(normalized);
+    }
+    /**
+     * Pod HTTP has no atomic rename. The prototype performs a conditional
+     * create-then-conditional-delete and explicitly documents the non-atomic
+     * window; it never falls back to an unconditional overwrite.
+     */
+    async rename(from, to, baseVersion) {
+        const source = normalizeRelativePath(from);
+        const target = normalizeRelativePath(to);
+        const sourceStat = await this.stat(source);
+        if (!sourceStat) {
+            throw new PodLowerNotFoundError(`rename source ${source} not found`);
+        }
+        const content = await this.read(source);
+        // Editor atomic-save replaces an existing target: overwrite it conditionally
+        // when it exists, otherwise create it. Never an unconditional overwrite.
+        const targetStat = await this.stat(target);
+        if (targetStat) {
+            if (!targetStat.version) {
+                throw new PodLowerConflictError(`refusing unconditional overwrite of ${target}: no ETag`);
+            }
+            await this.write(target, content.data, targetStat.version, sourceStat.contentType);
+        }
+        else {
+            await this.create(target, content.data, sourceStat.contentType);
+        }
+        await this.remove(source, baseVersion ?? sourceStat.version);
+        this.invalidate(target);
+    }
+    /** Pending (dirty) operations are not evicted by cache management. */
+    enqueue(operation) {
+        this.pending.set(operation.id, operation);
+    }
+    listPending() {
+        return [...this.pending.values()];
+    }
+    /** Applies pending operations to the Pod; failures keep the op for retry. */
+    async commit() {
+        let applied = 0;
+        const conflicts = [];
+        for (const operation of [...this.pending.values()]) {
+            try {
+                if (operation.op === 'write') {
+                    const data = Buffer.from(operation.dataBase64, 'base64');
+                    if (operation.create || operation.baseVersion === undefined) {
+                        await this.create(operation.path, data, operation.contentType);
+                    }
+                    else {
+                        await this.write(operation.path, data, operation.baseVersion, operation.contentType);
+                    }
+                }
+                else {
+                    await this.remove(operation.path, operation.baseVersion);
+                }
+                this.pending.delete(operation.id);
+                applied += 1;
+            }
+            catch (error) {
+                if (error instanceof PodLowerConflictError) {
+                    conflicts.push(operation.path);
+                    continue;
+                }
+                throw error;
+            }
+        }
+        return { applied, conflicts };
+    }
+    /**
+     * Drops a cached version token so the next access revalidates against the
+     * Pod. No body is cached, so an external modification can never be served
+     * from a stale local body copy.
+     */
+    invalidate(relativePath) {
+        this.versionCache.delete(relativePath);
+    }
+    getTransferStats() {
+        return { ...this.stats };
+    }
+    toStat(entry) {
+        return {
+            path: entry.path,
+            type: entry.type,
+            ...(entry.size !== undefined ? { size: entry.size } : {}),
+            ...(entry.contentType ? { contentType: entry.contentType } : {}),
+            ...(entry.version ? { version: entry.version } : {}),
+        };
+    }
+    async send(url, init, bodyRead = false, bodyLength = 0) {
+        this.stats.requestCount += 1;
+        if (init.method === 'GET') {
+            this.stats.readRequests += 1;
+        }
+        if (init.method === 'PUT' || init.method === 'DELETE') {
+            this.stats.writeRequests += 1;
+        }
+        if (bodyRead) {
+            this.stats.bodiesReadBytes += bodyLength;
+        }
+        const response = await this.request(url, init);
+        if (bodyRead && init.method === 'GET') {
+            const contentLength = Number(response.headers.get('content-length') ?? 0);
+            this.stats.bodiesReadBytes += Number.isFinite(contentLength) ? contentLength : 0;
+        }
+        if (bodyRead && (init.method === 'PUT' || init.method === 'DELETE')) {
+            this.stats.bytesWritten += bodyLength;
+        }
+        return response;
+    }
+}
+exports.PodHttpLowerFileSystem = PodHttpLowerFileSystem;
+//# sourceMappingURL=pod-lower.js.map

package/dist/cli/agent-fs/rg-entry.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Entry point used by the generated `rg` wrapper script. It either serves the
+ * invocation from the Pod HTTP directory backend or execs the pre-resolved
+ * native ripgrep binary with the original argv.
+ */
+export declare function runRgWrapperMain(argv: string[]): Promise<void>;

package/dist/cli/agent-fs/rg-entry.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRgWrapperMain = runRgWrapperMain;
+const AgentDirectoryClient_1 = require("../../agent-directory/client/AgentDirectoryClient");
+const auth_context_1 = require("../lib/auth-context");
+const args_1 = require("./args");
+const native_1 = require("./native");
+const roots_1 = require("./roots");
+const runner_1 = require("./runner");
+const session_view_1 = require("./session-view");
+function writeError(message) {
+    process.stderr.write(`xpod-rg: ${message}\n`);
+}
+/**
+ * Entry point used by the generated `rg` wrapper script. It either serves the
+ * invocation from the Pod HTTP directory backend or execs the pre-resolved
+ * native ripgrep binary with the original argv.
+ */
+async function runRgWrapperMain(argv) {
+    const wrapperDir = process.env.XPOD_AGENT_FS_WRAPPER_DIR;
+    const nativeRg = (0, native_1.resolveNativeBinary)('rg', process.env, wrapperDir ? [wrapperDir] : []);
+    if (!nativeRg) {
+        writeError('could not resolve the native rg binary; set XPOD_AGENT_FS_NATIVE_RG');
+        process.exitCode = 2;
+        return;
+    }
+    const fallbackToNative = async () => {
+        try {
+            process.exitCode = await (0, native_1.execNativeBinary)(nativeRg, argv, process.cwd());
+        }
+        catch (error) {
+            writeError(error instanceof Error ? error.message : String(error));
+            process.exitCode = 2;
+        }
+    };
+    const parsed = (0, args_1.parseRgArgs)(argv);
+    if (parsed.kind === 'fallback') {
+        await fallbackToNative();
+        return;
+    }
+    const invocation = parsed.invocation;
+    if (process.stdout.isTTY &&
+        invocation.kind === 'search' &&
+        (invocation.lineNumber === undefined || !invocation.noHeading || invocation.color !== 'never')) {
+        // Interactive ripgrep adds line numbers/headings/color by default; only an
+        // explicit non-interactive-equivalent invocation can be reproduced.
+        await fallbackToNative();
+        return;
+    }
+    // ripgrep reads stdin when no path is given; the managed backend cannot.
+    if (invocation.kind === 'search' && invocation.pathArg === undefined && process.stdin?.isTTY !== true) {
+        await fallbackToNative();
+        return;
+    }
+    const roots = (0, roots_1.loadManagedRoots)();
+    if (roots.length === 0) {
+        await fallbackToNative();
+        return;
+    }
+    const target = (0, roots_1.resolveManagedTarget)(process.cwd(), invocation.pathArg, roots);
+    if (!target) {
+        await fallbackToNative();
+        return;
+    }
+    // A remote index cannot represent unpublished edits. Use the native tool on
+    // the actual merged mount whenever this session has a delta. Do not maintain
+    // a separate TypeScript overlay or silently search stale remote content.
+    let sessionBefore;
+    try {
+        sessionBefore = (0, session_view_1.observeSession)((0, session_view_1.defaultSessionDir)());
+        if (sessionBefore.podRoot === target.root.podRoot && sessionBefore.pending > 0) {
+            await fallbackToNative();
+            return;
+        }
+    }
+    catch (error) {
+        writeError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 2;
+        return;
+    }
+    // Production uses the CLI's single authenticated request entry point
+    // (`authFetch`) so any token type/refresh handled there is preserved. The
+    // access-token override exists only for isolated wrapper tests.
+    let client;
+    const tokenOverride = process.env.XPOD_AGENT_FS_ACCESS_TOKEN;
+    if (tokenOverride) {
+        client = new AgentDirectoryClient_1.AgentDirectoryClient({ baseUrl: target.root.podRoot, accessToken: tokenOverride });
+    }
+    else {
+        try {
+            const context = await (0, auth_context_1.requireAuthContext)({});
+            client = new AgentDirectoryClient_1.AgentDirectoryClient({
+                baseUrl: target.root.podRoot,
+                request: (url, init) => (0, auth_context_1.authFetch)(context, url, init),
+            });
+        }
+        catch (error) {
+            writeError(error instanceof Error ? error.message : String(error));
+            process.exitCode = 2;
+            return;
+        }
+    }
+    try {
+        const result = await (0, runner_1.runManagedInvocation)(invocation, {
+            client,
+            cwd: process.cwd(),
+            roots,
+            stdoutIsTty: process.stdout.isTTY === true,
+        });
+        const sessionAfter = (0, session_view_1.observeSession)((0, session_view_1.defaultSessionDir)());
+        if (sessionAfter.podRoot === target.root.podRoot && sessionAfter.version !== sessionBefore.version) {
+            await fallbackToNative();
+            return;
+        }
+        if (result.stdout) {
+            process.stdout.write(result.stdout);
+        }
+        if (result.stderr) {
+            process.stderr.write(result.stderr);
+        }
+        process.exitCode = result.exitCode;
+    }
+    catch (error) {
+        if (error instanceof runner_1.ManagedTargetUnresolvedError) {
+            await fallbackToNative();
+            return;
+        }
+        writeError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 2;
+    }
+}
+//# sourceMappingURL=rg-entry.js.map

package/dist/cli/agent-fs/roots.d.ts

@@ -0,0 +1,18 @@
+export interface ManagedRoot {
+    localPath: string;
+    podRoot: string;
+}
+export interface ManagedTarget {
+    root: ManagedRoot;
+    /** Pod-root-relative path (POSIX, trailing slash for directories). */
+    relFromRoot: string;
+    /** cwd-relative-to-Pod-root path (POSIX, trailing slash). */
+    relCwd: string;
+}
+export declare function normalizePodRoot(value: string): string | undefined;
+export declare function parseManagedRoots(raw: unknown): ManagedRoot[];
+export declare function loadManagedRoots(env?: NodeJS.ProcessEnv): ManagedRoot[];
+export declare function resolveManagedTarget(cwd: string, pathArg: string | undefined, roots: ManagedRoot[]): ManagedTarget | undefined;
+export declare function displayPrefixFor(pathArg: string | undefined): string;
+export declare function stripPrefix(entryPath: string, prefix: string): string;
+export declare function hasHiddenSegment(relativePath: string): boolean;