@undefineds.co/xpod 0.4.20 → 0.4.27

package/dist/cli/agent-fs/args.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * Conservative ripgrep argv classifier.
+ *
+ * Only argument combinations whose semantics the HTTP search backend can
+ * reproduce exactly are taken over. Everything else (regex patterns, stdin,
+ * ignore-file handling, context flags, unsupported output modes) is reported as
+ * `fallback` so the caller can exec the pre-resolved native binary unchanged.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRgArgs = parseRgArgs;
+const BOOLEAN_SHORT = new Set(['F', 'i', 'n', 'l', 'c']);
+function fallback(reason) {
+    return { kind: 'fallback', reason };
+}
+function parseLongOption(arg, options, takeNext) {
+    const equalsIndex = arg.indexOf('=');
+    const name = equalsIndex === -1 ? arg.slice(2) : arg.slice(2, equalsIndex);
+    const inlineValue = equalsIndex === -1 ? undefined : arg.slice(equalsIndex + 1);
+    const takesValue = name === 'sort' || name === 'color' || name === 'regexp';
+    if (!takesValue && inlineValue !== undefined) {
+        // `--hidden=true` is not equivalent to `--hidden`; let native decide.
+        return `--${name} does not take an inline value`;
+    }
+    switch (name) {
+        case 'files':
+            options.files = true;
+            return undefined;
+        case 'fixed-strings':
+            options.fixedStrings = true;
+            return undefined;
+        case 'no-ignore':
+            options.noIgnore = true;
+            return undefined;
+        case 'hidden':
+            options.hidden = true;
+            return undefined;
+        case 'ignore-case':
+            return 'case-insensitive matching is not differential-proven; use the native binary';
+        case 'line-number':
+            options.lineNumber = true;
+            return undefined;
+        case 'no-line-number':
+            options.lineNumber = false;
+            return undefined;
+        case 'files-with-matches':
+            options.filesWithMatches = true;
+            return undefined;
+        case 'count':
+            options.count = true;
+            return undefined;
+        case 'no-heading':
+            options.noHeading = true;
+            return undefined;
+        case 'heading':
+            return 'heading output is not reproduced';
+        case 'sort': {
+            const value = inlineValue ?? takeNext();
+            if (value !== 'path') {
+                return `--sort ${value ?? ''} is not supported (only "path")`;
+            }
+            options.sort = 'path';
+            return undefined;
+        }
+        case 'color': {
+            const value = inlineValue ?? takeNext();
+            if (value === 'never') {
+                options.color = 'never';
+                return undefined;
+            }
+            if (value === 'auto') {
+                options.color = 'auto';
+                return undefined;
+            }
+            if (value === 'always' || value === 'ansi') {
+                return `--color ${value} output is not reproduced; pass --color=never`;
+            }
+            return `--color ${value ?? ''} is not supported (only "never"/"auto")`;
+        }
+        case 'regexp': {
+            const value = inlineValue ?? takeNext();
+            if (value === undefined) {
+                return '--regexp requires a value';
+            }
+            options.patterns.push(value);
+            return undefined;
+        }
+        case 'no-filename':
+            return '--no-filename changes the output prefix contract';
+        case 'with-filename':
+            return undefined;
+        case 'no-messages':
+        case 'stats':
+        case 'json':
+        case 'vimgrep':
+        case 'null':
+        case 'null-data':
+            return `--${name} output is not supported`;
+        default:
+            return `unsupported option --${name}`;
+    }
+}
+function parseShortCluster(arg, options, takeNext) {
+    const cluster = arg.slice(1);
+    for (let index = 0; index < cluster.length; index += 1) {
+        const char = cluster[index];
+        if (char === 'e') {
+            const inline = cluster.slice(index + 1);
+            const value = inline.length > 0 ? inline : takeNext();
+            if (value === undefined) {
+                return '-e requires a value';
+            }
+            options.patterns.push(value);
+            return undefined;
+        }
+        if (!BOOLEAN_SHORT.has(char)) {
+            return `unsupported short option -${char}`;
+        }
+        switch (char) {
+            case 'F':
+                options.fixedStrings = true;
+                break;
+            case 'i':
+                return 'case-insensitive matching is not differential-proven; use the native binary';
+            case 'n':
+                options.lineNumber = true;
+                break;
+            case 'l':
+                options.filesWithMatches = true;
+                break;
+            case 'c':
+                options.count = true;
+                break;
+            default:
+                break;
+        }
+    }
+    return undefined;
+}
+function parseRgArgs(argv) {
+    const options = {
+        files: false,
+        fixedStrings: false,
+        noIgnore: false,
+        hidden: false,
+        ignoreCase: false,
+        filesWithMatches: false,
+        count: false,
+        noHeading: false,
+        color: 'auto',
+        patterns: [],
+        paths: [],
+        endOfOptions: false,
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (options.endOfOptions) {
+            if (options.files) {
+                options.paths.push(arg);
+            }
+            else if (options.patterns.length === 0) {
+                options.patterns.push(arg);
+            }
+            else {
+                options.paths.push(arg);
+            }
+            continue;
+        }
+        if (arg === '--') {
+            options.endOfOptions = true;
+            continue;
+        }
+        if (arg.startsWith('--')) {
+            const error = parseLongOption(arg, options, () => argv[++index]);
+            if (error) {
+                return fallback(error);
+            }
+            continue;
+        }
+        if (arg.startsWith('-') && arg.length > 1) {
+            const error = parseShortCluster(arg, options, () => argv[++index]);
+            if (error) {
+                return fallback(error);
+            }
+            continue;
+        }
+        if (options.files) {
+            options.paths.push(arg);
+        }
+        else if (options.patterns.length === 0) {
+            options.patterns.push(arg);
+        }
+        else {
+            options.paths.push(arg);
+        }
+    }
+    if (options.paths.length > 1) {
+        return fallback('multiple paths are not merged by the managed backend');
+    }
+    if (!options.noIgnore) {
+        return fallback('ignore-file semantics require the native binary; pass --no-ignore to opt in');
+    }
+    if (options.sort !== 'path') {
+        return fallback('pass --sort path to guarantee deterministic managed ordering');
+    }
+    const pathArg = options.paths[0];
+    if (options.files) {
+        if (options.patterns.length > 0) {
+            return fallback('--files does not take a pattern');
+        }
+        return {
+            kind: 'managed',
+            invocation: {
+                kind: 'files',
+                hidden: options.hidden,
+                sort: 'path',
+                ...(pathArg ? { pathArg } : {}),
+            },
+        };
+    }
+    if (!options.fixedStrings) {
+        return fallback('only fixed-string (-F) searches are taken over in this batch');
+    }
+    if (options.patterns.length !== 1) {
+        return fallback('exactly one fixed-string pattern is required');
+    }
+    const pattern = options.patterns[0];
+    if (pattern.length === 0) {
+        return fallback('empty patterns are handled by the native binary');
+    }
+    if (pattern.includes('\n') || pattern.includes('\r')) {
+        return fallback('multi-line patterns are handled by the native binary');
+    }
+    if (options.filesWithMatches && options.count) {
+        return fallback('-l and -c cannot be combined');
+    }
+    return {
+        kind: 'managed',
+        invocation: {
+            kind: 'search',
+            query: options.patterns[0],
+            hidden: options.hidden,
+            sort: 'path',
+            ignoreCase: options.ignoreCase,
+            ...(options.lineNumber === undefined ? {} : { lineNumber: options.lineNumber }),
+            filesWithMatches: options.filesWithMatches,
+            count: options.count,
+            noHeading: options.noHeading,
+            color: options.color,
+            ...(pathArg ? { pathArg } : {}),
+        },
+    };
+}
+//# sourceMappingURL=args.js.map

package/dist/cli/agent-fs/auth-proxy.d.ts

@@ -0,0 +1,27 @@
+export interface AuthProxyOptions {
+    /** Real Pod container root, e.g. https://pod.example/alice/ */
+    podRoot: string;
+    /** Fixed capability for tests/helper IPC; a random 32-byte one is generated otherwise. */
+    capability?: string;
+    /** Called after an authenticated local shutdown response has been sent. */
+    onShutdown?: () => void;
+}
+export interface AuthProxy {
+    /** Pure loopback origin (no capability in the URL). */
+    origin: string;
+    /** Per-mount capability; callers must send it as `x-xpod-agentfs-capability`. */
+    capability: string;
+    podRoot: string;
+    close: () => Promise<void>;
+}
+/**
+ * Device-side loopback proxy bound to a single Pod root and a single per-mount
+ * capability.
+ *
+ * The origin is a pure loopback origin; the capability is a 32-byte random
+ * secret delivered to the helper through its private environment/IPC. Requests
+ * without the capability are refused before any Pod request. Forwarding always
+ * goes through the CLI's authoritative `authFetch`; the helper never owns
+ * credentials.
+ */
+export declare function startAuthProxy(options: AuthProxyOptions): Promise<AuthProxy>;

package/dist/cli/agent-fs/auth-proxy.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startAuthProxy = startAuthProxy;
+const node_http_1 = require("node:http");
+const node_crypto_1 = require("node:crypto");
+const node_stream_1 = require("node:stream");
+const promises_1 = require("node:stream/promises");
+const auth_context_1 = require("../lib/auth-context");
+const HOP_BY_HOP = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+const CAPABILITY_HEADER = 'x-xpod-agentfs-capability';
+const MAX_REDIRECTS = 3;
+function canonicalTarget(raw, realRoot, transportOrigin) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return undefined;
+    }
+    // The target must be a URL on the real Pod origin that canonicalizes to the
+    // bound Pod root (Alice). A loopback URL is rewritten if it points at the
+    // same Pod path.
+    if ((parsed.origin === realRoot.origin || parsed.origin === transportOrigin) && parsed.pathname.startsWith(realRoot.pathname)) {
+        return `${realRoot.origin}${parsed.pathname}${parsed.search}`;
+    }
+    return undefined;
+}
+function rewriteSidecarTargets(search, realRoot, transportOrigin) {
+    const params = new URLSearchParams(search);
+    for (const key of ['root', 'url']) {
+        const value = params.get(key);
+        if (!value) {
+            continue;
+        }
+        const canonical = canonicalTarget(value, realRoot, transportOrigin);
+        if (!canonical) {
+            return { error: `sidecar parameter "${key}" points outside the proxied Pod root` };
+        }
+        params.set(key, canonical);
+    }
+    return { search: `?${params.toString()}` };
+}
+/**
+ * Device-side loopback proxy bound to a single Pod root and a single per-mount
+ * capability.
+ *
+ * The origin is a pure loopback origin; the capability is a 32-byte random
+ * secret delivered to the helper through its private environment/IPC. Requests
+ * without the capability are refused before any Pod request. Forwarding always
+ * goes through the CLI's authoritative `authFetch`; the helper never owns
+ * credentials.
+ */
+async function startAuthProxy(options) {
+    const realRoot = new URL(options.podRoot.endsWith('/') ? options.podRoot : `${options.podRoot}/`);
+    const podPath = realRoot.pathname;
+    const capability = options.capability ?? (0, node_crypto_1.randomBytes)(32).toString('hex');
+    const server = (0, node_http_1.createServer)((request, response) => {
+        void (async () => {
+            const incoming = new URL(request.url ?? '/', 'http://127.0.0.1');
+            // 1. Capability gate: header only, never the URL.
+            const headerCap = request.headers[CAPABILITY_HEADER];
+            if (typeof headerCap !== 'string' || headerCap !== capability) {
+                response.writeHead(401, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'missing per-mount capability' }));
+                return;
+            }
+            if (incoming.pathname === '/-/agentfs-proxy/shutdown' && options.onShutdown) {
+                if (request.method !== 'POST') {
+                    response.writeHead(405, { allow: 'POST' });
+                    response.end();
+                    return;
+                }
+                response.once('finish', options.onShutdown);
+                response.writeHead(204);
+                response.end();
+                return;
+            }
+            // 2. Map path: resources live under the Pod path; the sidecar is at root.
+            let forwardPath;
+            let forwardSearch = incoming.search;
+            if (incoming.pathname.startsWith(podPath)) {
+                forwardPath = incoming.pathname;
+            }
+            else if (incoming.pathname.startsWith('/-/agent-directory/')) {
+                forwardPath = incoming.pathname;
+                const transport = server.address();
+                const rewritten = rewriteSidecarTargets(incoming.search, realRoot, `http://127.0.0.1:${transport.port}`);
+                if ('error' in rewritten) {
+                    response.writeHead(403, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: rewritten.error }));
+                    return;
+                }
+                forwardSearch = rewritten.search;
+            }
+            else {
+                response.writeHead(403, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: 'path outside the proxied Pod root' }));
+                return;
+            }
+            const headers = {};
+            for (const [key, value] of Object.entries(request.headers)) {
+                const lower = key.toLowerCase();
+                if (lower === 'host' || lower === 'authorization' || lower === CAPABILITY_HEADER || HOP_BY_HOP.has(lower)) {
+                    continue;
+                }
+                if (typeof value === 'string') {
+                    headers[key] = value;
+                }
+                else if (Array.isArray(value)) {
+                    headers[key] = value.join(', ');
+                }
+            }
+            const safeMethod = request.method === 'GET' || request.method === 'HEAD';
+            const hasBody = !safeMethod;
+            // Bun can transparently retry a disconnected pooled request, including
+            // streaming mutations. A lost receipt belongs to journal recovery, never
+            // to the transport's retry path. Fresh, closing connections avoid it.
+            if (hasBody) {
+                headers.connection = 'close';
+            }
+            const init = {
+                method: request.method,
+                headers,
+                redirect: 'manual',
+                ...(hasBody ? { keepalive: false } : {}),
+                ...(hasBody ? { body: node_stream_1.Readable.toWeb(request), duplex: 'half' } : {}),
+            };
+            const fetchOnce = async (url, forceRefresh) => (0, auth_context_1.authFetch)(await (0, auth_context_1.requireAuthContext)({ forceRefresh }), url, init);
+            try {
+                let currentUrl = `${realRoot.origin}${forwardPath}${forwardSearch}`;
+                let upstream = await fetchOnce(currentUrl, false);
+                // A mutating body stream cannot be replayed; return the retryable 401
+                // instead of silently reusing a consumed stream (which would 502).
+                if (upstream.status === 401 && safeMethod) {
+                    upstream = await fetchOnce(currentUrl, true);
+                }
+                // Manual redirects: verify every hop stays inside this Pod before following.
+                let hops = 0;
+                while (upstream.status >= 300 && upstream.status < 400 && safeMethod && hops < MAX_REDIRECTS) {
+                    const location = upstream.headers.get('location');
+                    if (!location) {
+                        break;
+                    }
+                    const resolved = new URL(location, currentUrl);
+                    if (resolved.origin !== realRoot.origin || !resolved.pathname.startsWith(podPath)) {
+                        response.writeHead(403, { 'content-type': 'application/json' });
+                        response.end(JSON.stringify({ error: 'redirect outside the Pod root' }));
+                        return;
+                    }
+                    currentUrl = resolved.href;
+                    upstream = await fetchOnce(currentUrl, false);
+                    hops += 1;
+                }
+                if (upstream.status >= 300 && upstream.status < 400) {
+                    response.writeHead(502, { 'content-type': 'application/json' });
+                    response.end(JSON.stringify({ error: 'unhandled Pod redirect' }));
+                    return;
+                }
+                const responseHeaders = {};
+                upstream.headers.forEach((value, key) => {
+                    const lower = key.toLowerCase();
+                    if (HOP_BY_HOP.has(lower) || lower === 'content-encoding' || lower === 'content-length') {
+                        return;
+                    }
+                    responseHeaders[key] = value;
+                });
+                const upstreamLength = upstream.headers.get('content-length');
+                if (upstreamLength) {
+                    responseHeaders['content-length'] = upstreamLength;
+                }
+                response.writeHead(upstream.status, responseHeaders);
+                if (request.method === 'HEAD' || !upstream.body) {
+                    response.end();
+                    return;
+                }
+                await (0, promises_1.pipeline)(node_stream_1.Readable.fromWeb(upstream.body), response);
+            }
+            catch (error) {
+                if (response.headersSent || response.destroyed) {
+                    response.destroy(error instanceof Error ? error : new Error(String(error)));
+                    return;
+                }
+                response.writeHead(502, { 'content-type': 'application/json' });
+                response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+            }
+        })();
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+    const address = server.address();
+    return {
+        origin: `http://127.0.0.1:${address.port}`,
+        capability,
+        podRoot: options.podRoot,
+        close: async () => {
+            await new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve())));
+        },
+    };
+}
+//# sourceMappingURL=auth-proxy.js.map

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

@@ -0,0 +1,18 @@
+import type { ManagedRoot } from './roots';
+export interface InstallRgWrapperOptions {
+    dir: string;
+    roots: ManagedRoot[];
+    nativeRg?: string;
+    /** Override the launcher command (executable + entry script). */
+    launcher?: string[];
+    sessionDir?: string;
+}
+export interface InstallRgWrapperResult {
+    dir: string;
+    wrapperPath: string;
+    nativeRg: string;
+    launcher: string[];
+}
+export declare function shellQuote(value: string): string;
+export declare function installRgWrapper(options: InstallRgWrapperOptions): InstallRgWrapperResult;
+export declare function renderEnvExports(result: InstallRgWrapperResult): string[];

package/dist/cli/agent-fs/install.js

@@ -0,0 +1,54 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shellQuote = shellQuote;
+exports.installRgWrapper = installRgWrapper;
+exports.renderEnvExports = renderEnvExports;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const native_1 = require("./native");
+const launcher_1 = require("../lib/launcher");
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function resolveLauncher(override) {
+    if (override && override.length > 0) {
+        return override;
+    }
+    return (0, launcher_1.cliLauncher)();
+}
+function installRgWrapper(options) {
+    const dir = node_path_1.default.resolve(options.dir);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const nativeRg = options.nativeRg ?? (0, native_1.resolveNativeBinary)('rg', process.env, [dir]);
+    if (!nativeRg) {
+        throw new Error('Could not resolve a native rg binary. Pass --native-rg or install ripgrep.');
+    }
+    const launcher = resolveLauncher(options.launcher);
+    const rootsJson = JSON.stringify(options.roots);
+    const wrapperPath = node_path_1.default.join(dir, 'rg');
+    const script = [
+        '#!/bin/sh',
+        '# Generated by `xpod agent-fs install`. Session-scoped rg wrapper.',
+        'XPOD_AGENT_FS_WRAPPER_DIR="$(cd "$(dirname "$0")" && pwd)"',
+        'export XPOD_AGENT_FS_WRAPPER_DIR',
+        `export XPOD_AGENT_FS_NATIVE_RG=${shellQuote(nativeRg)}`,
+        `export XPOD_AGENT_FS_ROOTS=${shellQuote(rootsJson)}`,
+        ...(options.sessionDir ? [`export XPOD_AGENTFS_SESSION=${shellQuote(node_path_1.default.resolve(options.sessionDir))}`] : []),
+        `exec ${launcher.map(shellQuote).join(' ')} agent-fs rg "$@"`,
+        '',
+    ].join('\n');
+    (0, node_fs_1.writeFileSync)(wrapperPath, script, 'utf8');
+    (0, node_fs_1.chmodSync)(wrapperPath, 0o755);
+    return { dir, wrapperPath, nativeRg, launcher };
+}
+function renderEnvExports(result) {
+    return [
+        `export XPOD_AGENT_FS_WRAPPER_DIR=${shellQuote(result.dir)}`,
+        `export XPOD_AGENT_FS_NATIVE_RG=${shellQuote(result.nativeRg)}`,
+        `export PATH=${shellQuote(result.dir)}:"$PATH"`,
+    ];
+}
+//# sourceMappingURL=install.js.map

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

@@ -0,0 +1,35 @@
+/** Fixed AgentFS upstream revision the prototype helper must be built against. */
+export declare const AGENTFS_UPSTREAM: {
+    readonly repository: "https://github.com/tursodatabase/agentfs";
+    readonly commit: "0a014ebd4918615baff589ed17486e557e7c6a23";
+    readonly sdkCrate: "sdk/rust";
+    readonly cliCrate: "cli";
+};
+export interface MountPrerequisites {
+    platform: string;
+    helperPath?: string;
+    helperPresent: boolean;
+    /** Prerequisite-shell binary used for diagnostics only; never a mount. */
+    checkBinaryPath?: string;
+    fuseAvailable: boolean;
+    nfsMountAvailable: boolean;
+    upstream: typeof AGENTFS_UPSTREAM;
+    blockers: string[];
+}
+/** The real mount helper. Absent until the AgentFS-linked build exists. */
+export declare function resolveHelperPath(repoRoot: string, env?: NodeJS.ProcessEnv): string | undefined;
+/** Diagnostic-only prerequisite shell; deliberately a different binary name. */
+export declare function resolveCheckBinaryPath(repoRoot: string): string | undefined;
+export type MountBackendKind = 'nfs' | 'fuse';
+export declare function defaultBackend(platform?: string): MountBackendKind;
+export declare function describePrerequisites(repoRoot: string, env?: NodeJS.ProcessEnv, backend?: MountBackendKind): MountPrerequisites;
+export declare class MountUnavailableError extends Error {
+    readonly prerequisites: MountPrerequisites;
+    constructor(prerequisites: MountPrerequisites);
+}
+/**
+ * Fails loudly instead of pretending a mount exists. A "successful mount"
+ * claim requires an actual OS mount performed by the helper; if the helper or
+ * kernel driver is missing, this prototype must not fabricate it.
+ */
+export declare function assertMountable(prerequisites: MountPrerequisites): void;