@shardflux/cli 0.11.1 → 0.13.1

package/dist/agent-config-files.js

@@ -0,0 +1,203 @@
+import { readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+export const object = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+export const text = (v) => typeof v === 'string' ? v : undefined;
+export const absent = (e) => e.code === 'ENOENT';
+// These are code/config trees, never agent runtime state. Plugin cache is handled by its install records below.
+const excluded = new Set(['.git', '.in_use', 'node_modules', '__pycache__', '.DS_Store', '.credentials.json', 'auth.json',
+    'projects', 'transcripts', 'history.jsonl', 'logs', 'cache', 'caches', '.env']);
+const maxFileBytes = 16 * 1024 * 1024;
+export async function readOptional(file) {
+    try {
+        return await readFile(file);
+    }
+    catch (error) {
+        if (absent(error))
+            return undefined;
+        throw error;
+    }
+}
+export async function readObject(file) {
+    const bytes = await readOptional(file);
+    if (!bytes)
+        return undefined;
+    const parsed = JSON.parse(bytes.toString('utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new Error(`expected an object in ${file}`);
+    return parsed;
+}
+/** Dereference skill symlinks, including ones shared from another local directory, but never traverse a cycle. */
+export async function collectTree(source, dest, files, issues, parents = new Set()) {
+    let resolved;
+    try {
+        resolved = await realpath(source);
+    }
+    catch (error) {
+        if (absent(error)) {
+            issues.push({ item: dest, reason: 'source is missing or a broken symlink' });
+            return;
+        }
+        throw error;
+    }
+    if (parents.has(resolved)) {
+        issues.push({ item: dest, reason: 'symlink cycle' });
+        return;
+    }
+    const info = await stat(resolved);
+    if (info.isDirectory()) {
+        const next = new Set(parents).add(resolved);
+        for (const name of (await readdir(resolved)).sort()) {
+            if (excluded.has(name) || name.startsWith('.env.'))
+                continue;
+            await collectTree(join(resolved, name), `${dest}/${name}`, files, issues, next);
+        }
+    }
+    else if (info.isFile()) {
+        if (info.size > maxFileBytes) {
+            issues.push({ item: dest, reason: 'file exceeds the 16 MiB config sync limit' });
+            return;
+        }
+        const content = await readFile(resolved);
+        if (/^\.(?:claude\/(?:skills|commands)|codex\/(?:skills|prompts))\//.test(dest) &&
+            /(?:\b(?:sk-[a-zA-Z0-9_-]{10,}|gh[pousr]_[a-zA-Z0-9]{10,}|github_pat_[a-zA-Z0-9_]{10,}|sfk_[a-zA-Z0-9_]{10,})|\b(?:[A-Z_]*(?:API_KEY|ACCESS_TOKEN|SECRET|PASSWORD))\s*[=:]\s*["']?(?!\$|\s|["']?\$)[a-zA-Z0-9_-]{8,})/.test(content.toString('utf8'))) {
+            issues.push({ item: dest, reason: 'contains a credential literal in reusable tooling; use a bound environment secret' });
+            return;
+        }
+        files.set(dest, { content, mode: info.mode & 0o111 ? '0700' : '0600' });
+    }
+    else
+        issues.push({ item: dest, reason: 'not a regular file or directory' });
+}
+export async function collectUserFiles(home, issues) {
+    const files = new Map();
+    for (const path of ['.claude/settings.json', '.claude/CLAUDE.md', '.claude/skills', '.claude/commands',
+        '.claude/agents', '.claude/output-styles', '.codex/AGENTS.md', '.codex/prompts', '.codex/skills']) {
+        try {
+            await stat(join(home, path));
+        }
+        catch (error) {
+            if (absent(error))
+                continue;
+            throw error;
+        }
+        await collectTree(join(home, path), path, files, issues);
+    }
+    return files;
+}
+function under(path, root) { const rel = relative(root, path); return rel === '' || !rel.startsWith('../') && rel !== '..' && !rel.startsWith('/'); }
+export function macBinary(bytes) {
+    if (bytes.length < 4)
+        return false;
+    const magic = bytes.readUInt32BE(0);
+    // Java class files share FAT_MAGIC; a fat Mach-O has a small, nonzero architecture count.
+    if ([0xcafebabe, 0xcafebabf].includes(magic))
+        return bytes.length >= 8 && bytes.readUInt32BE(4) > 0 && bytes.readUInt32BE(4) <= 20;
+    return new Set([0xfeedface, 0xfeedfacf, 0xcefaedfe, 0xcffaedfe, 0xbebafeca, 0xbfbafeca]).has(magic);
+}
+/** Preserve v2 install metadata and user-scope records, and copy just the trees needed to load them on Linux. */
+export async function collectPlugins(home, remoteHome, files, issues) {
+    const skipped = new Set();
+    const root = join(home, '.claude/plugins');
+    const installed = await readObject(join(root, 'installed_plugins.json'));
+    if (installed) {
+        const plugins = {};
+        for (const [id, records] of Object.entries(object(installed.plugins))) {
+            const kept = [];
+            for (const raw of Array.isArray(records) ? records : [records]) {
+                const record = object(raw);
+                if (record.scope !== 'user') {
+                    issues.push({ item: `plugin:${id}`, reason: 'project/local scope travels with its repository' });
+                    continue;
+                }
+                const path = text(record.installPath);
+                if (!path || !under(resolve(path), join(root, 'cache'))) {
+                    issues.push({ item: `plugin:${id}`, reason: 'install path is outside the plugin cache' });
+                    continue;
+                }
+                const dest = relative(home, resolve(path));
+                const tree = new Map();
+                const before = issues.length;
+                await collectTree(path, dest, tree, issues);
+                if (issues.length !== before || [...tree.values()].some(f => macBinary(f.content))) {
+                    issues.push({ item: `plugin:${id}`, reason: issues.length !== before ? 'plugin tree is incomplete' : 'contains macOS native binaries; install a Linux version' });
+                    continue;
+                }
+                for (const [name, file] of tree)
+                    files.set(name, file);
+                kept.push({ ...record, installPath: `${remoteHome}/${dest}` });
+            }
+            if (kept.length)
+                plugins[id] = kept;
+            else
+                skipped.add(id);
+        }
+        files.set('.claude/plugins/installed_plugins.json', { content: Buffer.from(JSON.stringify({ ...installed, plugins }) + '\n'), mode: '0600' });
+    }
+    const known = await readObject(join(root, 'known_marketplaces.json'));
+    if (known) {
+        const portable = {};
+        for (const [id, raw] of Object.entries(known)) {
+            const entry = object(raw);
+            const location = text(entry.installLocation);
+            if (!location || !under(resolve(location), join(root, 'marketplaces'))) {
+                issues.push({ item: `marketplace:${id}`, reason: 'marketplace is outside the marketplace directory' });
+                continue;
+            }
+            const dest = relative(home, resolve(location));
+            const tree = new Map();
+            const before = issues.length;
+            await collectTree(location, dest, tree, issues);
+            if (issues.length !== before)
+                continue;
+            // Marketplace source can contain binary packages for other platforms; the installed version is checked above.
+            for (const [name, file] of tree)
+                if (!macBinary(file.content))
+                    files.set(name, file);
+            portable[id] = { ...entry, installLocation: `${remoteHome}/${dest}` };
+        }
+        files.set('.claude/plugins/known_marketplaces.json', { content: Buffer.from(JSON.stringify(portable) + '\n'), mode: '0600' });
+    }
+    return skipped;
+}
+/** Only rewrite paths to files we actually send. Missing laptop paths are never made to look portable. */
+export function rewritePaths(value, home, remoteHome, files, issues, item) {
+    if (typeof value === 'string') {
+        if (/^https?:\/\//.test(value))
+            return value;
+        const expanded = value.startsWith('~/') ? join(home, value.slice(2)) : value;
+        const whole = relative(home, expanded);
+        if (under(expanded, home) && (files.has(whole) || [...files.keys()].some(p => p.startsWith(whole + '/'))))
+            return `${remoteHome}/${whole}`;
+        const escapedHome = home.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const pattern = new RegExp(`(?:${escapedHome}/|~/|/Users/|/Applications/|/opt/homebrew/|/home/)[^\\s"'\\],;]+`, 'g');
+        let failed = false;
+        const result = value.replace(pattern, path => {
+            const local = path.startsWith('~/') ? join(home, path.slice(2)) : path;
+            const rel = relative(home, local);
+            if (under(local, home) && (files.has(rel) || [...files.keys()].some(p => p.startsWith(rel + '/'))))
+                return `${remoteHome}/${rel}`;
+            issues.push({ item, reason: 'references a local path outside the synced config' });
+            failed = true;
+            return path;
+        });
+        return failed ? undefined : result;
+    }
+    if (Array.isArray(value)) {
+        const mapped = value.map(v => rewritePaths(v, home, remoteHome, files, issues, item));
+        return mapped.some(v => v === undefined) ? undefined : mapped;
+    }
+    if (value && typeof value === 'object') {
+        const result = {};
+        for (const [key, v] of Object.entries(value)) {
+            if (key.startsWith('/') || key.startsWith('~/')) {
+                issues.push({ item: `${item}.${key}`, reason: 'local project path is not synced by agent config' });
+                continue;
+            }
+            const mapped = rewritePaths(v, home, remoteHome, files, issues, `${item}.${key}`);
+            if (mapped !== undefined)
+                result[key] = mapped;
+        }
+        return result;
+    }
+    return value;
+}

package/dist/agent-config-mcp.d.ts

@@ -0,0 +1,36 @@
+import type { ConfigFiles, ConfigIssue, ObjectValue } from './agent-config-files.js';
+export type McpStatus = {
+    app: 'claude' | 'codex';
+    name: string;
+    status: 'copied' | 'reachable while attached' | 'skipped';
+    reason?: string;
+};
+export type ConfigTunnel = {
+    remote_port: number;
+    target: string;
+};
+export type McpSecret = {
+    name: string;
+    value: string;
+    item: string;
+};
+export type McpContext = {
+    home: string;
+    remoteHome: string;
+    workspaceId: string;
+    files: ConfigFiles;
+    issues: ConfigIssue[];
+    namespace?: string;
+    env: Record<string, string | undefined>;
+    exists(command: string): Promise<boolean>;
+    bind(secret: McpSecret): Promise<boolean>;
+};
+export declare const digest: (value: string | Uint8Array) => string;
+export declare const credential: (key: string, value: string) => boolean;
+/** Commands are checked through exec; a successful laptop command lookup would say nothing about the VM. */
+export declare function classifyMcp(server: ObjectValue, exists: McpContext['exists']): Promise<{
+    status: McpStatus['status'];
+    reason?: string;
+    url?: URL;
+}>;
+export declare function prepareMcp(app: 'claude' | 'codex', input: ObjectValue, ctx: McpContext, statuses: McpStatus[], tunnels: ConfigTunnel[]): Promise<ObjectValue>;

package/dist/agent-config-mcp.js

@@ -0,0 +1,225 @@
+import { createHash } from 'node:crypto';
+import { object, rewritePaths, text } from "./agent-config-files.js";
+export const digest = (value) => createHash('sha256').update(value).digest('hex');
+export const credential = (key, value) => /(?:^|[_-])(?:api[_-]?key|key|token|secret|password|passwd|auth|authorization|credential|cookie)(?:$|[_-])/i.test(key) || /^(?:sk-|gh[pousr]_|github_pat_|sfk_|Bearer\s|eyJ[A-Za-z0-9_-]+\.)/.test(value);
+const envReference = /^\$\{([A-Z_][A-Z0-9_]*)(?::-([^}]*))?\}$/;
+/** Commands are checked through exec; a successful laptop command lookup would say nothing about the VM. */
+export async function classifyMcp(server, exists) {
+    if (server.enabled === false)
+        return { status: 'skipped', reason: 'disabled on the laptop' };
+    if (typeof server.url === 'string') {
+        let url;
+        try {
+            url = new URL(server.url);
+        }
+        catch {
+            return { status: 'skipped', reason: 'URL is invalid or contains unresolved environment references' };
+        }
+        if (!['http:', 'https:'].includes(url.protocol))
+            return { status: 'skipped', reason: 'transport is not HTTP or SSE' };
+        if (url.username || url.password || [...url.searchParams.keys()].some(k => credential(k, '')))
+            return { status: 'skipped', reason: 'URL contains credentials; use header/environment authentication' };
+        return { status: ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname) ? 'reachable while attached' : 'copied', url };
+    }
+    const command = text(server.command);
+    if (!command || server.type && server.type !== 'stdio')
+        return { status: 'skipped', reason: 'unsupported MCP transport' };
+    if (server.args !== undefined && (!Array.isArray(server.args) || server.args.some((arg) => typeof arg !== 'string')))
+        return { status: 'skipped', reason: 'stdio args must be strings' };
+    if (!(await exists(command)))
+        return { status: 'skipped', reason: 'stdio command is absent in the VM' };
+    return { status: 'copied' };
+}
+export async function prepareMcp(app, input, ctx, statuses, tunnels) {
+    const result = {};
+    for (const [name, raw] of Object.entries(input)) {
+        const item = `${app}:mcp:${ctx.namespace ? ctx.namespace + ':' : ''}${name}`;
+        const issueCount = ctx.issues.length;
+        const server = object(rewritePaths(raw, ctx.home, ctx.remoteHome, ctx.files, ctx.issues, item));
+        let classification = await classifyMcp(server, command => ctx.exists(command));
+        if (ctx.issues.length > issueCount)
+            classification = { status: 'skipped', reason: 'references laptop files that are not synced' };
+        if (classification.status === 'skipped') {
+            statuses.push({ app, name, ...classification });
+            continue;
+        }
+        const env = object(server.env);
+        const explicitEnv = new Set(Object.keys(env));
+        if (server.url && explicitEnv.size) {
+            statuses.push({ app, name, status: 'skipped', reason: 'HTTP transport cannot map stdio environment values' });
+            continue;
+        }
+        const exports = [];
+        let denied = false;
+        const route = async (key, value) => {
+            const secretName = `SF_MCP_${digest(`${ctx.workspaceId}:${item}:${key}`).slice(0, 24).toUpperCase()}`;
+            if (!(await ctx.bind({ name: secretName, value, item: `${item}:${key}` }))) {
+                denied = true;
+                return undefined;
+            }
+            return secretName;
+        };
+        for (const [key, rawValue] of Object.entries(env)) {
+            const value = text(rawValue);
+            if (value === undefined) {
+                denied = true;
+                continue;
+            }
+            const ref = envReference.exec(value);
+            if (ref && ['CLAUDE_PLUGIN_ROOT', 'CLAUDE_PLUGIN_DATA', 'CLAUDE_PROJECT_DIR'].includes(ref[1]))
+                continue;
+            const resolved = ref ? ctx.env[ref[1]] || ref[2] : value;
+            if (ref && resolved === undefined) {
+                denied = true;
+                continue;
+            }
+            if (credential(key, resolved) || ref) {
+                const secretName = await route(key, resolved);
+                delete env[key];
+                if (secretName)
+                    exports.push({ key, name: secretName });
+            }
+        }
+        // Codex forwards env_vars verbatim; bind laptop values too, rather than writing them into TOML.
+        if (app === 'codex' && Array.isArray(server.env_vars)) {
+            for (const key of server.env_vars) {
+                if (typeof key !== 'string' || !/^[A-Z_][A-Z0-9_]*$/.test(key)) {
+                    denied = true;
+                    continue;
+                }
+                if (explicitEnv.has(key))
+                    continue;
+                const value = ctx.env[key];
+                if (value === undefined) {
+                    denied = true;
+                    continue;
+                }
+                const secretName = await route(key, value);
+                if (secretName)
+                    exports.push({ key, name: secretName });
+            }
+            delete server.env_vars;
+        }
+        const headersKey = app === 'claude' ? 'headers' : 'http_headers';
+        const headers = object(server[headersKey]);
+        const envHeaders = object(server.env_http_headers);
+        for (const [key, rawValue] of Object.entries(headers)) {
+            const value = text(rawValue);
+            if (value === undefined) {
+                denied = true;
+                continue;
+            }
+            let unresolved = false;
+            const expanded = value.replace(/\$\{([A-Z_][A-Z0-9_]*)(?::-([^}]*))?\}/g, (_all, variable, fallback) => {
+                const replacement = ctx.env[variable] || fallback;
+                if (replacement === undefined) {
+                    unresolved = true;
+                    return '';
+                }
+                return replacement;
+            });
+            if (unresolved) {
+                denied = true;
+                continue;
+            }
+            if (credential(key, expanded) || expanded !== value) {
+                const secretName = await route(`header:${key}`, expanded);
+                delete headers[key];
+                if (secretName) {
+                    if (app === 'codex')
+                        envHeaders[key] = secretName;
+                    else
+                        headers[key] = '${' + secretName + '}';
+                }
+            }
+        }
+        if (app === 'codex') {
+            for (const [key, rawValue] of Object.entries(object(server.env_http_headers))) {
+                const variable = text(rawValue);
+                const value = variable ? ctx.env[variable] : undefined;
+                if (value === undefined) {
+                    denied = true;
+                    continue;
+                }
+                const secretName = await route(`header:${key}`, value);
+                if (secretName)
+                    envHeaders[key] = secretName;
+            }
+            if (typeof server.bearer_token_env_var === 'string') {
+                const value = ctx.env[server.bearer_token_env_var];
+                if (value === undefined)
+                    denied = true;
+                else
+                    server.bearer_token_env_var = await route('bearer', value);
+            }
+            if (Object.keys(envHeaders).length)
+                server.env_http_headers = envHeaders;
+        }
+        if (denied) {
+            statuses.push({ app, name, status: 'skipped', reason: 'secret consent declined/unavailable, or referenced environment value is missing' });
+            continue;
+        }
+        if (Object.keys(env).length)
+            server.env = env;
+        else
+            delete server.env;
+        if (Object.keys(headers).length)
+            server[headersKey] = headers;
+        else
+            delete server[headersKey];
+        // Known browser MCPs join the same profile only after the customer imports a session.
+        // The shell delegates the original command unchanged when no browser profile is enabled.
+        if (!server.url) {
+            const args = Array.isArray(server.args) ? server.args : [];
+            const command = text(server.command);
+            const names = [command, ...args].map(a => a.replaceAll(String.fromCharCode(92), '/'));
+            const hasPackage = (pkg) => names.some(a => a === pkg || a.startsWith(`${pkg}@`) || a.endsWith(`/${pkg}`) || a.includes(`/${pkg}/`));
+            const browser = hasPackage('@playwright/mcp') || hasPackage('playwright-mcp') ? 'playwright'
+                : hasPackage('chrome-devtools-mcp') ? 'chrome' : undefined;
+            if (browser && await ctx.exists('sf-guest-agent') && await ctx.exists('sh')) {
+                server.command = 'sh';
+                server.args = ['-c', `if [ -f "$HOME/.local/share/shardflux/browser/enabled" ]; then exec sf-guest-agent browser-profile mcp ${browser} "$@"; else exec "$@"; fi`, 'shard-browser-mcp', command, ...args];
+            }
+        }
+        if (exports.length) {
+            if (server.url) {
+                statuses.push({ app, name, status: 'skipped', reason: 'HTTP transport cannot map stdio environment values' });
+                continue;
+            }
+            if (!(await ctx.exists('sh'))) {
+                statuses.push({ app, name, status: 'skipped', reason: 'secret environment forwarding needs sh in the VM' });
+                continue;
+            }
+            if (exports.some(e => !/^[A-Z_][A-Z0-9_]*$/.test(e.key))) {
+                statuses.push({ app, name, status: 'skipped', reason: 'invalid environment variable name' });
+                continue;
+            }
+            const command = text(server.command);
+            const args = Array.isArray(server.args) ? server.args : [];
+            server.command = 'sh';
+            server.args = ['-c', exports.map(e => `export ${e.key}="$${e.name}";`).join(' ') + ' exec "$@"', 'shard-mcp', command, ...args];
+            if (app === 'codex')
+                server.env_vars = [...new Set(exports.map(e => e.name))];
+        }
+        if (classification.status === 'reachable while attached') {
+            const url = classification.url;
+            const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80));
+            const target = `${url.hostname}:${port}`;
+            let tunnel = tunnels.find(t => t.target === target);
+            if (!tunnel) {
+                let remote = 20000 + Number.parseInt(digest(target).slice(0, 8), 16) % 40000;
+                while (tunnels.some(t => t.remote_port === remote))
+                    remote = 20000 + (remote - 20000 + 1) % 40000;
+                tunnel = { remote_port: remote, target };
+                tunnels.push(tunnel);
+            }
+            if (url.hostname === '[::1]')
+                url.hostname = 'localhost';
+            url.port = String(tunnel.remote_port);
+            server.url = url.toString();
+        }
+        result[name] = server;
+        statuses.push({ app, name, status: classification.status });
+    }
+    return result;
+}

package/dist/agent-config-sync.d.ts

@@ -0,0 +1,58 @@
+import type { CellClient, Workspace } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
+import type { ConfigFiles, ConfigIssue } from './agent-config-files.js';
+import type { ConfigTunnel, McpStatus } from './agent-config-mcp.js';
+type ManifestFile = {
+    hash: string;
+    mode: string;
+    created: boolean;
+};
+type SecretRecord = {
+    id: string;
+    hash: string;
+    version: number;
+};
+export type ConfigManifest = {
+    v: 1;
+    workspace_id: string;
+    workspace_key: string;
+    api_url: string;
+    home: string;
+    synced_at: string | null;
+    sync_state: 'applying' | 'synced';
+    remote_hash?: string;
+    files: Record<string, ManifestFile>;
+    claude_mcp: string[];
+    secrets: Record<string, SecretRecord>;
+    claude_mcp_owned?: Record<string, {
+        hash: string;
+        created: boolean;
+    }>;
+    skipped: ConfigIssue[];
+    mcp: McpStatus[];
+    tunnels: ConfigTunnel[];
+};
+export type ConfigSyncResult = {
+    workspace_id: string;
+    workspace_key: string;
+    copied: string[];
+    removed: string[];
+    skipped: ConfigIssue[];
+    mcp: McpStatus[];
+    synced_at: string | null;
+};
+export declare function configManifests(ctx: Pick<Ctx, 'store'>): Record<string, ConfigManifest>;
+/** `like` must not inherit generated MCP secrets restricted to the source workspace. */
+export declare function agentConfigLikeSecrets(ctx: Ctx, reference: string): Promise<string[] | undefined>;
+export declare function applyConfigFiles(cell: CellClient, home: string, files: ConfigFiles, previous: Record<string, ManifestFile>, trustManifest: boolean, issues: ConfigIssue[], signal: AbortSignal, deleteMissing?: boolean, progress?: (path: string, file: ManifestFile | undefined) => void): Promise<{
+    files: Record<string, ManifestFile>;
+    copied: string[];
+    removed: string[];
+}>;
+export declare function syncAgentConfig(ctx: Ctx, ws: Workspace): Promise<ConfigSyncResult>;
+/** Tunnels are owned by the attachment, and close even if the terminal fails or the user detaches. */
+export declare function startAgentConfigTunnels(ctx: Ctx, ws: Workspace): Promise<{
+    stop(): Promise<void>;
+}>;
+export declare const AGENT_CONFIG_HANDLERS: Record<string, Handler>;
+export {};