@shardflux/cli 0.11.0 → 0.13.0

package/dist/agent-repository.js

@@ -0,0 +1,182 @@
+import { randomUUID } from 'node:crypto';
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { AgentStateStore } from "./agent-state.js";
+import { projectIdentity } from "./project-identity.js";
+import { localManifest, projectGit } from "./project-sync-manifest.js";
+import { applyRemoteSyncBatch, readLocalSyncFile, writeSyncBlob } from "./project-sync-transfer.js";
+export function projectWorkspacePath(project) {
+    if (!/^[a-z0-9][a-z0-9._-]{0,95}$/.test(project.slug))
+        throw new Error('invalid sync project slug');
+    return `/home/user/${project.slug}`;
+}
+/** New workspaces label this path explicitly; custom remote paths remain available to Git callers. */
+export function workspaceRepositoryPath(ws) {
+    return ws.labels.repo_path || projectWorkspacePath({ slug: ws.labels.shard_project || ws.key.split('/')[0] });
+}
+export function needsGitSeed(ctx, ws) {
+    const seed = new AgentStateStore(ctx.store.dir).read().git_seeding?.[ws.id];
+    return seed !== undefined && seed.api_url === ctx.apiUrl;
+}
+/** One history seed for C5 and C11. Bundles use the bounded files path, without a Git helper or second connection. */
+export async function seedAgentRepository(ctx, ws, folder, options = {}) {
+    const project = projectIdentity(folder);
+    // A cloud-only `like` launch must never seed an unrelated laptop repository.
+    if (ws.labels.repo_remote && ws.labels.repo_remote !== project.remote)
+        return;
+    const root = options.root ?? workspaceRepositoryPath(ws);
+    const retry = needsGitSeed(ctx, ws);
+    const state = new AgentStateStore(ctx.store.dir);
+    state.update(doc => { const seeds = (doc.git_seeding ?? {}); seeds[ws.id] = { api_url: ctx.apiUrl, folder: project.folder }; doc.git_seeding = seeds; });
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    await cell.files.mkdir(root, { parents: true });
+    await initializeProjectGit(cell, project.folder, root, ctx.signal, options.populate, retry, message => { ctx.io.stderr.write(`${message}\n`); });
+    state.update(doc => { const seeds = (doc.git_seeding ?? {}); delete seeds[ws.id]; doc.git_seeding = seeds; });
+}
+async function initializeProjectGit(cell, folder, root, signal, populate = false, retry = false, report = () => undefined) {
+    let top;
+    try {
+        top = (await projectGit(folder, ['rev-parse', '--show-toplevel'], signal)).trim();
+    }
+    catch (error) {
+        if (signal?.aborted || error.code !== 128)
+            throw error;
+        if (populate)
+            await seedProjectFiles(cell, folder, root, '', new Set(), true, signal, report);
+        return;
+    }
+    if (top !== folder)
+        throw new Error('project sync requires the Git repository root; run shard there');
+    const existing = await cell.exec.run(['git', '-C', root, 'rev-parse', '--verify', 'HEAD'], { timeoutMs: 5000, signal });
+    if (existing.exitCode !== 0 && existing.exitCode !== 128)
+        throw new Error('could not check workspace Git history');
+    if (existing.exitCode === 128 || retry) {
+        const importHistory = existing.exitCode === 128;
+        let head = '', branch = '';
+        try {
+            head = (await projectGit(folder, ['rev-parse', '--verify', 'HEAD'], signal)).trim();
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+        }
+        try {
+            branch = (await projectGit(folder, ['symbolic-ref', '-q', 'HEAD'], signal)).trim();
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+        }
+        if (head && importHistory) {
+            const dir = await mkdtemp(join(tmpdir(), 'shard-sync-git-'));
+            const local = join(dir, 'history.bundle'), remote = `/tmp/shard-sync-${randomUUID()}.bundle`;
+            try {
+                await projectGit(folder, ['bundle', 'create', local, '--all'], signal);
+                if ((await stat(local)).size > 256 << 20)
+                    throw new Error('Git history bundle exceeds the 256 MiB sync limit');
+                await writeSyncBlob(cell, remote, await readFile(local));
+                const script = 'set -eu; git init -q "$1"; git -C "$1" -c core.hooksPath=/dev/null fetch -q --update-head-ok "$2" HEAD:refs/shard-sync/initial "+refs/heads/*:refs/heads/*" "+refs/tags/*:refs/tags/*"; if [ -n "$4" ]; then git -C "$1" symbolic-ref HEAD "$4"; else git -C "$1" update-ref --no-deref HEAD "$3"; fi; git -C "$1" update-ref HEAD "$3"; git -C "$1" read-tree HEAD; git -C "$1" update-ref -d refs/shard-sync/initial';
+                const result = await cell.exec.run(['sh', '-c', script, 'shard-sync', root, remote, head, branch], { timeoutMs: 60_000, maxOutputBytes: 4096, signal });
+                if (result.exitCode !== 0)
+                    throw new Error(`initial Git bundle failed: ${result.stderr.trim()}`);
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true });
+                await cell.files.remove(remote).catch(() => undefined);
+            }
+        }
+        else if (importHistory) {
+            const result = await cell.exec.run(['git', 'init', '-q', ...(branch.startsWith('refs/heads/') ? ['--initial-branch', branch.slice(11)] : []), root], { timeoutMs: 5000, signal });
+            if (result.exitCode !== 0)
+                throw new Error(`initial Git repository failed: ${result.stderr.trim()}`);
+        }
+        for (const key of ['user.name', 'user.email']) {
+            let value = '';
+            try {
+                value = (await projectGit(folder, ['config', '--get', key], signal)).trim();
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    throw error;
+            }
+            if (value) {
+                const result = await cell.exec.run(['git', '-C', root, 'config', key, value], { timeoutMs: 5000, signal });
+                if (result.exitCode !== 0)
+                    throw new Error(`could not copy Git ${key}`);
+            }
+        }
+        const origin = projectIdentity(folder).remote;
+        if (origin && !origin.startsWith('file:')) {
+            const result = await cell.exec.run(['git', '-C', root, 'config', 'remote.origin.url', origin], { timeoutMs: 5000, signal });
+            if (result.exitCode !== 0)
+                throw new Error('could not copy Git origin');
+        }
+        // Ignore files must exist before the first remote scan; otherwise a
+        // template's dependency outputs would look like agent-created source.
+        // For unborn repos, intent-to-add preserves tracked ignored paths too.
+        const tracked = new Set((await projectGit(folder, ['ls-files', '-z', '--cached'], signal)).split('\0'));
+        await seedProjectFiles(cell, folder, root, head, tracked, populate, signal, report);
+    }
+    // Git's info/exclude and laptop-wide excludes are selection metadata, copied
+    // into a dedicated Git exclude file without syncing credentials or .git data.
+    const readOptional = async (path) => {
+        try {
+            return await readFile(path, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return '';
+            throw error;
+        }
+    };
+    const info = (await projectGit(folder, ['rev-parse', '--git-path', 'info/exclude'], signal)).trim();
+    let global = '';
+    try {
+        global = (await projectGit(folder, ['config', '--path', '--get', 'core.excludesFile'], signal)).trim();
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
+    }
+    const excludes = await readOptional(resolve(folder, info)) + '\n' + await readOptional(global ? resolve(folder, global) : join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'git', 'ignore'));
+    await cell.files.write(`${root}/.git/shard-sync-excludes`, excludes, { mode: '0600' });
+    const result = await cell.exec.run(['git', '-C', root, 'config', 'core.excludesFile', `${root}/.git/shard-sync-excludes`], { timeoutMs: 5000, signal });
+    if (result.exitCode !== 0)
+        throw new Error('could not apply project Git exclude rules');
+}
+async function seedProjectFiles(cell, folder, root, head, tracked, populate, signal, report) {
+    const raw = await localManifest(folder, signal);
+    for (const skip of raw.skipped)
+        report(`Project seed skipped ${skip.path}: ${skip.reason}`);
+    const seed = raw.entries.filter((entry) => populate || entry.path.split('/').at(-1) === '.gitignore' || (!head && tracked.has(entry.path)));
+    for (let offset = 0; offset < seed.length; offset += 32) {
+        const entries = seed.slice(offset, offset + 32);
+        const probe = await cell.exec.run(['python3', '-c', 'import os,sys,json;root=sys.argv[1];print(json.dumps([p for p in json.loads(sys.argv[2]) if not os.path.lexists(root+"/"+p)]))', root, JSON.stringify(entries.map((entry) => entry.path))], { timeoutMs: 5000, signal });
+        if (probe.exitCode !== 0)
+            throw new Error('could not inspect initial project ignore files');
+        const missing = new Set(JSON.parse(probe.stdout));
+        let seeds = new Map(), bytes = 0;
+        for (const entry of entries)
+            if (missing.has(entry.path)) {
+                if (bytes + entry.size > 8 << 20 && seeds.size) {
+                    await applyRemoteSyncBatch(cell, root, seeds, {}, signal);
+                    seeds = new Map();
+                    bytes = 0;
+                }
+                const file = await readLocalSyncFile(folder, entry);
+                seeds.set(entry.path, file);
+                bytes += file.data.length;
+            }
+        if (seeds.size)
+            await applyRemoteSyncBatch(cell, root, seeds, {}, signal);
+        if (!head) {
+            const add = entries.filter((entry) => tracked.has(entry.path)).map((entry) => entry.path);
+            if (add.length) {
+                const result = await cell.exec.run(['git', '-C', root, '-c', 'core.hooksPath=/dev/null', 'add', '-N', '-f', '--', ...add], { timeoutMs: 5000, signal });
+                if (result.exitCode !== 0)
+                    throw new Error(`initial tracked project files failed: ${result.stderr.trim()}`);
+            }
+        }
+    }
+}

package/dist/agent-state.d.ts

@@ -0,0 +1,16 @@
+type State = Record<string, unknown> & {
+    projects?: Record<string, {
+        app?: string;
+    }>;
+};
+/** Keep other lanes' sync manifests and project settings when remembering the app choice. */
+export declare class AgentStateStore {
+    readonly file: string;
+    readonly dir: string;
+    constructor(dir: string);
+    read(): State;
+    app(project: string, fallback?: 'claude' | 'codex'): 'claude' | 'codex';
+    update(change: (state: State) => void): void;
+    save(project: string, app: 'claude' | 'codex'): void;
+}
+export {};

package/dist/agent-state.js

@@ -0,0 +1,63 @@
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensurePrivateDir, writePrivateFile } from "./credentials.js";
+import { UsageError } from "./errors.js";
+/** Keep other lanes' sync manifests and project settings when remembering the app choice. */
+export class AgentStateStore {
+    file;
+    dir;
+    constructor(dir) { this.dir = dir; this.file = join(dir, 'agents.json'); }
+    read() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.file, 'utf8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw new Error('expected an object');
+            return parsed;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return {};
+            throw new UsageError(`cannot read ${this.file}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    app(project, fallback = 'claude') {
+        const app = this.read().projects?.[project]?.app;
+        return app === 'claude' || app === 'codex' ? app : fallback;
+    }
+    update(change) {
+        ensurePrivateDir(this.dir);
+        const lock = `${this.file}.lock`;
+        try {
+            writeFileSync(lock, String(process.pid), { flag: 'wx', mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            try {
+                process.kill(Number(readFileSync(lock, 'utf8')), 0);
+            }
+            catch (probe) {
+                if (probe.code === 'ESRCH') {
+                    rmSync(lock);
+                    return this.update(change);
+                }
+            }
+            throw new UsageError('another shard process is updating agent state; run the command again');
+        }
+        try {
+            const state = this.read();
+            change(state);
+            writePrivateFile(this.dir, this.file, JSON.stringify(state) + '\n');
+        }
+        finally {
+            rmSync(lock, { force: true });
+        }
+    }
+    save(project, app) {
+        this.update(doc => {
+            doc.projects ??= {};
+            doc.projects[project] = { ...doc.projects[project], app };
+            delete doc.terminal_sessions;
+        });
+    }
+}

package/dist/agent-target-commands.d.ts

@@ -0,0 +1,10 @@
+import { Duplex } from 'node:stream';
+import type { CellClient, Workspace } from '@shardflux/sdk';
+import type { Ctx, Handler, Io } from './commands.js';
+import { AgentTargets } from './agent-targets.js';
+/** Optimistic file replacement preserves keys installed by other devices connecting at the same time. */
+export declare function installDeviceKey(cell: CellClient, key: string, signal?: AbortSignal): Promise<void>;
+/** Host trust is established over the authenticated files API, before sending any SSH protocol bytes. */
+export declare function prepareSsh(ws: Workspace, ctx: Ctx, targets: AgentTargets, host: string): Promise<CellClient>;
+export declare function proxyStream(io: Io): Duplex;
+export declare const TARGET_HANDLERS: Record<string, Handler>;

package/dist/agent-target-commands.js

@@ -0,0 +1,171 @@
+import { agentReachability } from "./agent-reachability.js";
+import { ensureCloudClaude } from "./claude-cloud-login.js";
+import { spawn } from 'node:child_process';
+import { Readable, Duplex } from 'node:stream';
+import { ShardfluxApiError, WorkspaceTunnels } from '@shardflux/sdk';
+import { out, resolveWorkspace } from "./commands.js";
+import { AgentTargets, installedTargets } from "./agent-targets.js";
+import { projectIdentity } from "./project-identity.js";
+import { projectWorkspacePath } from "./agent-repository.js";
+import { UsageError } from "./errors.js";
+import { openUrl } from "./browser.js";
+const missing = (e) => e instanceof ShardfluxApiError && e.status === 404;
+const keyOf = (ref) => ref.includes('/') ? ref : `${projectIdentity('./').slug}/${ref}`;
+/** Optimistic file replacement preserves keys installed by other devices connecting at the same time. */
+export async function installDeviceKey(cell, key, signal) {
+    const path = '/home/user/.ssh/authorized_keys';
+    await cell.files.mkdir('/home/user/.ssh', { mode: '0700', parents: true });
+    for (let attempt = 0; attempt < 4; attempt++) {
+        let text = '', revision = 'absent';
+        try {
+            const read = await cell.files.readWithInfo(path);
+            if (!read.revision || read.data.byteLength > 1024 * 1024)
+                throw new Error('authorized_keys must have a revision and be at most 1 MiB');
+            text = new TextDecoder('utf-8', { fatal: true }).decode(read.data);
+            revision = read.revision;
+        }
+        catch (e) {
+            if (!missing(e))
+                throw e;
+        }
+        const publicPart = key.split(' ').slice(0, 2).join(' ');
+        if (text.split('\n').some(line => line.trim().split(/\s+/).slice(0, 2).join(' ') === publicPart))
+            return;
+        try {
+            await cell.files.patch({ path, content: text + (text && !text.endsWith('\n') ? '\n' : '') + key + '\n', expectedRevision: revision, mode: '0600' }, { signal });
+            return;
+        }
+        catch (e) {
+            if (!(e instanceof ShardfluxApiError && e.status === 409 && e.details?.reason === 'revision_mismatch'))
+                throw e;
+        }
+    }
+    throw new Error('authorized_keys kept changing; retry the SSH connection');
+}
+/** Host trust is established over the authenticated files API, before sending any SSH protocol bytes. */
+export async function prepareSsh(ws, ctx, targets, host) {
+    if (!ws.ready)
+        await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    const hostKey = await cell.files.readText('/etc/ssh/ssh_host_ed25519_key.pub', { length: 4096 });
+    targets.pin(host, hostKey);
+    await installDeviceKey(cell, targets.deviceKey(), ctx.signal);
+    return cell;
+}
+async function openApp(target, env) {
+    const child = spawn('open', ['-b', target === 'claude-desktop' ? 'com.anthropic.claudefordesktop' : 'com.openai.codex'], { env, stdio: 'ignore' });
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('app launcher timed out')); }, 10_000);
+        child.once('error', e => { clearTimeout(timer); reject(e); });
+        child.once('exit', code => { clearTimeout(timer); if (code === 0)
+            resolve();
+        else
+            reject(new Error(`app launcher exited ${code}`)); });
+    });
+}
+export function proxyStream(io) {
+    const stdout = io.stdout;
+    const source = Readable.from(io.stdin, { objectMode: false });
+    let blocked = false;
+    const pump = () => {
+        while (!blocked && !stream.destroyed) {
+            const bytes = source.read();
+            if (bytes === null)
+                return;
+            blocked = !stream.push(bytes);
+        }
+    };
+    const stream = new Duplex({
+        allowHalfOpen: true,
+        read() { blocked = false; pump(); },
+        write(bytes, _encoding, done) {
+            try {
+                if (stdout.write(bytes))
+                    done();
+                else if (stdout.once)
+                    stdout.once('drain', done);
+                else
+                    done(new Error('stdout cannot signal backpressure'));
+            }
+            catch (e) {
+                done(e);
+            }
+        },
+        destroy(error, done) { source.destroy(); done(error); },
+    });
+    source.on('readable', pump);
+    source.once('end', () => stream.push(null));
+    source.once('error', (error) => stream.destroy(error));
+    return stream;
+}
+const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
+    if (target !== 'web' && !installedTargets(ctx.io.env).targets.includes(target))
+        throw new UsageError(`${target} is not installed on this machine`);
+    let ws = await resolveWorkspace(ctx, keyOf(ref));
+    if (values.reachable !== undefined)
+        ws = await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
+    if (target !== 'codex-app')
+        await ensureCloudClaude(ctx, ws);
+    if (target === 'web') {
+        let cursor;
+        let url;
+        do {
+            const page = await ctx.cloud().agents.list({ limit: 200, ...(cursor ? { cursor } : {}) });
+            url = page.data.find(a => a.workspace_id === ws.id && a.app === 'claude' && a.state !== 'exited' && a.remote_control_url)?.remote_control_url;
+            cursor = page.nextCursor ?? undefined;
+        } while (!url && cursor && !ctx.signal.aborted);
+        if (!url)
+            throw new UsageError(`${ws.key} has no active Remote Control URL; start Claude with Remote Control first`);
+        const parsed = new URL(url);
+        if (parsed.protocol !== 'https:' || parsed.hostname !== 'claude.ai' || !parsed.pathname.startsWith('/code/') || parsed.username || parsed.password)
+            throw new Error('agent returned an invalid Claude Remote Control URL');
+        if (!ctx.json && !openUrl(url, ctx.io.env))
+            throw new Error(`could not open ${url}`);
+        out(ctx, `${url}\n`, { target, workspace: ws.data, url });
+        return 0;
+    }
+    const targets = new AgentTargets(ctx.io.env, ctx.store.dir);
+    const entry = targets.configure(ws.key, ctx.apiUrl, [target]).find(e => e.workspace === ws.key);
+    const instructions = target === 'claude-desktop'
+        ? `Restart Claude Desktop to load the connection, then choose Shardflux · ${entry.project} · ${entry.agent} in Code's environment dropdown and open ${projectWorkspacePath({ slug: entry.project })}.`
+        : `Restart Codex to import ${entry.host} and its remote project. If it has already been imported, enable ${entry.host} in Settings → Connections → SSH.`;
+    if (!ctx.json)
+        await openApp(target, ctx.io.env);
+    out(ctx, `${instructions}\n`, { target, workspace: ws.data, host: entry.host, instructions });
+    return 0;
+};
+export const TARGET_HANDLERS = {
+    'agents targets'(ctx, values, [ref]) {
+        const detected = installedTargets(ctx.io.env);
+        const targets = new AgentTargets(ctx.io.env, ctx.store.dir);
+        const entries = ref || values.remove === true
+            ? targets.configure(ref ? keyOf(ref) : undefined, ctx.apiUrl, detected.targets.filter((t) => t === 'claude-desktop' || t === 'codex-app'), values.remove === true)
+            : [];
+        out(ctx, `${detected.clients.join(', ') || 'No installed agent clients'}\nOpen targets: ${detected.targets.join(', ')}\n${entries.map(e => e.host).join('\n')}${entries.length ? '\n' : ''}`, { ...detected, entries });
+        return Promise.resolve(0);
+    },
+    'agents open claude-desktop': openTarget('claude-desktop'),
+    'agents open codex-app': openTarget('codex-app'),
+    'agents open web': openTarget('web'),
+    async 'ssh-proxy'(ctx, _values, [host]) {
+        if (ctx.json || !host)
+            throw new UsageError('ssh-proxy requires a managed host and binary standard IO');
+        const targets = new AgentTargets(ctx.io.env, ctx.store.dir), entry = targets.entry(host, ctx.apiUrl);
+        const ws = await resolveWorkspace(ctx, entry.workspace);
+        const cell = await prepareSsh(ws, ctx, targets, host);
+        const stream = proxyStream(ctx.io);
+        try {
+            const tunnel = await new WorkspaceTunnels(() => cell, () => ws.grantedTools).forward({ remotePort: 22, stream, signal: ctx.signal });
+            try {
+                await tunnel.closed;
+            }
+            finally {
+                await tunnel.close();
+            }
+        }
+        finally {
+            stream.destroy();
+        }
+        return 0;
+    },
+};

package/dist/agent-targets.d.ts

@@ -0,0 +1,33 @@
+export type DesktopTarget = 'claude-desktop' | 'codex-app';
+export interface TargetEntry {
+    host: string;
+    workspace: string;
+    api_url: string;
+    project: string;
+    agent: string;
+    targets: DesktopTarget[];
+}
+export declare function targetIdentity(key: string): Pick<TargetEntry, 'host' | 'workspace' | 'project' | 'agent'>;
+/** Replace only a marked block, retaining every byte outside it. Put Includes before user Host blocks. */
+export declare function managedBlock(text: string, body: string): string;
+export declare function installedTargets(env: Record<string, string | undefined>, platform?: NodeJS.Platform): {
+    targets: string[];
+    clients: string[];
+};
+/** All paths are supplied by the invocation; tests use a temporary HOME, never the owner's app stores. */
+export declare class AgentTargets {
+    #private;
+    readonly home: string;
+    readonly dir: string;
+    readonly identityFile: string;
+    readonly knownHosts: string;
+    readonly sshFile: string;
+    readonly claudeFile: string;
+    readonly codexFile: string;
+    readonly manifestFile: string;
+    constructor(env: Record<string, string | undefined>, dir: string);
+    entry(host: string, apiUrl: string): TargetEntry;
+    deviceKey(): string;
+    pin(host: string, publicKey: string): void;
+    configure(key: string | undefined, apiUrl: string, targets: DesktopTarget[], remove?: boolean): TargetEntry[];
+}