@shardflux/cli 0.24.0 → 0.24.1

package/dist/device-bridge.js

@@ -15,20 +15,16 @@ import { conversationClient } from "./conversation-commands.js";
 import { withTargetLock } from "./target-lock.js";
 import { checkConversationWorktree, rememberConversationWorktree } from "./conversation-worktree.js";
 import { yourComputer } from "./this-computer.js";
+import { canonicalDevicePath, deviceHome, displayPath, expandDevicePath, FOLDER_KINDS, isDevicePath, linkLocalProject, listDeviceDir } from "./device-folders.js";
 const LIMIT = 256 << 20, OUTPUT = (192 << 10) - 128;
 const inside = (root, target) => target === root || target.startsWith(root + sep);
+/**
+ * A request belongs to its conversation, not to a turn: it is answered while the conversation exists, between turns
+ * (done) and as a turn ends too (0.25.0+); only an archived (or deleted) conversation refuses it.
+ */
+const archived = (c) => c.state === 'archived';
 const safeId = (value) => { if (!/^[a-zA-Z0-9_-]{1,96}$/.test(value))
     throw new Error('Invalid device request identity'); return value; };
-function canonicalDevicePath(target) {
-    let ancestor = target;
-    while (!existsSync(ancestor)) {
-        const parent = dirname(ancestor);
-        if (parent === ancestor)
-            throw new UsageError('Device path is unavailable.');
-        ancestor = parent;
-    }
-    return resolve(realpathSync(ancestor), relative(ancestor, target));
-}
 /** Resolve existing ancestors even before the conversation worktree is created. */
 export function devicePath(root, requested = '.') {
     if (/[\0\r\n]/.test(requested))
@@ -60,6 +56,30 @@ export class DeviceGrants {
         const grant = this.read()[this.key(api, project)];
         return !outside && grant?.root === realpathSync(root) && Array.isArray(grant.kinds) && grant.kinds.includes(kind);
     }
+    /** A folder grant (0.25.0+): Always for `root` and everything inside it, for one kind of request. */
+    folderKey(api, root) { return JSON.stringify(['folder', api, root]); }
+    allowsFolder(api, target, kind) {
+        return Object.entries(this.read()).some(([key, grant]) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(key);
+            }
+            catch {
+                return false;
+            }
+            return Array.isArray(parsed) && parsed.length === 3 && parsed[0] === 'folder' && parsed[1] === api && typeof grant?.root === 'string' && parsed[2] === grant.root
+                && Array.isArray(grant.kinds) && grant.kinds.includes(kind) && inside(grant.root, target);
+        });
+    }
+    async saveFolder(api, root, kind) {
+        if (kind === 'exec')
+            throw new UsageError('Commands never run under a folder grant.');
+        await withTargetLock(join(dirname(this.file), 'device-grants-lock'), () => {
+            const all = this.read(), key = this.folderKey(api, root);
+            all[key] = { root, kinds: [...new Set([...(all[key]?.root === root ? all[key].kinds : []), kind])] };
+            writePrivateFile(dirname(this.file), this.file, JSON.stringify(all) + '\n');
+        });
+    }
     async save(api, project, root, kind) {
         await withTargetLock(join(dirname(this.file), 'device-grants-lock'), () => {
             const all = this.read(), key = this.key(api, project), canonical = realpathSync(root);
@@ -70,6 +90,10 @@ export class DeviceGrants {
 }
 export function deviceSummary(r, platform = process.platform) {
     const yours = yourComputer(platform);
+    if (r.kind === 'dir_list')
+        return `List ${r.dir?.path} on ${yours}: names, sizes and Git remotes, no file contents.`;
+    if (r.kind === 'project_link')
+        return `Make ${r.link?.path} a project and copy its files to the cloud${r.link?.brief ? ', then start a conversation there' : ''}.`;
     if (tryLocallyAction(r))
         return tryLocallyAction(r) === 'stop' ? 'Stop this conversation’s local sync and ports.' : 'Try this conversation in an isolated local worktree with two-way sync and localhost ports.';
     if (r.kind === 'exec')
@@ -88,6 +112,23 @@ export function deviceApproval(r, c, target, folder) {
         ...(r.port ? { local_port: r.port.local_port, remote_port: r.port.remote_port } : {}),
     };
 }
+/** A request on a folder anywhere on this device: the folder kinds, and file moves named by an absolute or ~/ path. */
+export function folderRequest(r) {
+    return FOLDER_KINDS.has(r.kind) || ((r.kind === 'files_pull' || r.kind === 'files_push') && !!r.files && isDevicePath(r.files.local_path_relative));
+}
+/** What a folder request's approval shows: the canonical path, the folder Always would cover, and what will happen. */
+export function folderApproval(r, c, target, folder, home, remote, platform = process.platform) {
+    const shown = displayPath(target, home), yours = yourComputer(platform);
+    const summary = r.kind === 'dir_list' ? `List ${shown} on ${yours}: names, sizes and Git remotes, no file contents.`
+        : r.kind === 'project_link' ? `Make ${shown} a project and copy its files to the cloud (uncommitted changes too; .gitignore respected)${r.link?.brief ? ', then start a conversation there' : ''}.`
+            : r.kind === 'files_pull' ? `Share with conversation: ${shown} → ${r.files?.remote_path}` : `Save on ${yours}: ${r.files?.remote_path} → ${shown}`;
+    return {
+        type: 'approval', request_id: r.id, project_id: r.project_id, conversation_id: c.id, summary, outside: true, scope: 'folder', folder,
+        kind: r.kind, local_path: target, project_name: basename(folder), conversation_title: c.title || conversationName(c),
+        ...(r.files ? { remote_path: r.files.remote_path } : {}), ...(r.dir ? { depth: r.dir.depth ?? 1 } : {}),
+        ...(r.kind === 'project_link' ? { repo_remote: remote ?? null, ...(r.link?.brief ? { brief: r.link.brief } : {}) } : {}),
+    };
+}
 export function tryLocallyAction(r) {
     if (r.kind === 'try_locally')
         return 'start';
@@ -171,6 +212,8 @@ export class DeviceExecutor {
         safeId(r.id);
         if (r.state !== 'pending' || r.device_id !== this.#deviceId)
             return;
+        if (folderRequest(r))
+            return this.#folder(r);
         const records = localConversations(ctx);
         const matching = Object.values(records).filter(record => record.project_id === r.project_id);
         const folders = new Set(matching.map(record => record.folder));
@@ -199,7 +242,7 @@ export class DeviceExecutor {
         if (devicePath(record.folder, join('.shard', 'worktrees', conversationName(c))).path !== planned.path || devicePath(planned.path, requested).path !== target.path)
             throw new Error('Device path changed during approval.');
         const current = await getConversation(ctx, r.conversation_id);
-        if (current.project_id !== c.project_id || current.branch !== c.branch || current.state === 'done' || current.state === 'archived')
+        if (current.project_id !== c.project_id || current.branch !== c.branch || archived(current))
             throw new Error('The conversation changed or ended during device approval.');
         c = current;
         await this.result(r, { state: 'approved' });
@@ -214,7 +257,7 @@ export class DeviceExecutor {
             if (root !== planned.path || devicePath(root, requested).path !== target.path)
                 throw new Error('Device path changed during preparation.');
             const prepared = await getConversation(ctx, c.id);
-            if (prepared.project_id !== c.project_id || prepared.workspace_id !== c.workspace_id || prepared.branch !== c.branch || prepared.state === 'done' || prepared.state === 'archived')
+            if (prepared.project_id !== c.project_id || prepared.workspace_id !== c.workspace_id || prepared.branch !== c.branch || archived(prepared))
                 throw new Error('The conversation changed or ended during device preparation.');
             const cell = ws.cell();
             let result;
@@ -270,6 +313,8 @@ export class DeviceExecutor {
                 result = { state: 'done', files_artifact: r.kind === 'files_pull' ? f.remote_path : relative(root, target.path) };
             }
             else {
+                if (r.kind !== 'port_forward' && r.kind !== 'port_reverse')
+                    throw new UsageError('Unknown device request kind.');
                 if (!r.port || ![r.port.local_port, r.port.remote_port].every(p => Number.isInteger(p) && p > 0 && p <= 65535))
                     throw new UsageError('Device ports must be 1–65535.');
                 const handle = await devicePort(ws, cell, r.kind, r.port, ctx.signal);
@@ -286,6 +331,129 @@ export class DeviceExecutor {
                 ws?.cell().close();
         }
     }
+    /**
+     * A folder anywhere on this device (device-folders.ts). Every outcome is answered, so a request is never asked twice:
+     * denied before it was approved, failed after.
+     */
+    async #folder(r) {
+        const ctx = this.#ctx, home = deviceHome(ctx), deny = (message) => this.result(r, { state: 'denied', stderr_b64: Buffer.from(message).toString('base64') });
+        let c;
+        try {
+            c = await getConversation(ctx, r.conversation_id);
+            if (c.project_id !== r.project_id)
+                throw new Error('Device request project changed.');
+        }
+        catch (e) {
+            if (ctx.signal.aborted)
+                return;
+            await deny(e instanceof Error ? e.message : String(e));
+            return;
+        }
+        if (archived(c)) {
+            await deny('The conversation has ended.');
+            return;
+        }
+        const requested = r.dir?.path ?? r.link?.path ?? r.files?.local_path_relative ?? '';
+        const resolveTarget = () => canonicalDevicePath(expandDevicePath(requested, home));
+        let target, folder, remote = null;
+        try {
+            target = resolveTarget();
+            folder = r.kind === 'files_pull' || r.kind === 'files_push' ? canonicalDevicePath(dirname(target)) : target;
+            if (r.kind === 'project_link') {
+                const { projectIdentity } = await import("./project-identity.js");
+                remote = projectIdentity(target).remote;
+            }
+        }
+        catch (e) {
+            await deny(e instanceof Error ? e.message : String(e));
+            return;
+        }
+        const grants = new DeviceGrants(ctx.store.dir);
+        let choice;
+        try {
+            choice = grants.allowsFolder(ctx.apiUrl, target, r.kind) ? 'once' : await this.#ask(folderApproval(r, c, target, folder, home, remote));
+        }
+        catch (e) {
+            if (ctx.signal.aborted)
+                return;
+            await deny(e instanceof Error ? e.message : String(e));
+            return;
+        }
+        if (ctx.signal.aborted)
+            return;
+        if (choice !== 'once' && choice !== 'always') {
+            await this.result(r, { state: 'denied' });
+            return;
+        }
+        if (choice === 'always')
+            await grants.saveFolder(ctx.apiUrl, folder, r.kind);
+        // Re-read after the approval, before claiming or touching data: a symlink swapped meanwhile is a different path.
+        let now;
+        try {
+            now = resolveTarget();
+        }
+        catch {
+            now = '';
+        }
+        if (now !== target) {
+            await deny('Device path changed during approval.');
+            return;
+        }
+        const current = await getConversation(ctx, r.conversation_id).catch(() => undefined);
+        if (!current || current.project_id !== c.project_id || archived(current)) {
+            await deny('The conversation changed or ended during device approval.');
+            return;
+        }
+        await this.result(r, { state: 'approved' });
+        await this.result(r, { state: 'running' });
+        let ws;
+        try {
+            let result;
+            if (r.kind === 'dir_list')
+                result = { state: 'done', dir: await listDeviceDir(target, r.dir ?? {}, ctx.signal) };
+            else if (r.kind === 'project_link')
+                result = { state: 'done', project: await linkLocalProject(ctx, target, { ...(r.link?.brief ? { brief: r.link.brief } : {}), harness: r.link?.harness ?? current.harness, projectId: current.project_id }) };
+            else {
+                const f = r.files;
+                if (!f.remote_path.startsWith('/') || /[\0\r\n]/.test(f.remote_path))
+                    throw new UsageError('Device transfer requires an absolute VM path.');
+                const max = f.max_bytes ?? LIMIT;
+                if (!Number.isSafeInteger(max) || max < 1 || max > LIMIT)
+                    throw new UsageError('Device transfer maximum is 256 MiB.');
+                ws = await conversationWorkspace({ ...ctx, signal: AbortSignal.any([ctx.signal, AbortSignal.timeout(30_000)]) }, current);
+                const cell = ws.cell();
+                if (r.kind === 'files_pull') {
+                    const info = await stat(target);
+                    if (!info.isFile() || info.size > max)
+                        throw new UsageError('Local transfer file exceeds the requested size or is not a file.');
+                    const bytes = await readFile(target);
+                    if (bytes.length > max)
+                        throw new UsageError('Local transfer file grew during reading.');
+                    await writeSyncBlob(cell, f.remote_path, bytes);
+                }
+                else {
+                    const info = await cell.files.stat(f.remote_path);
+                    if (info.type !== 'file' || info.size > max)
+                        throw new UsageError('VM transfer file exceeds the requested size or is not a file.');
+                    const bytes = await cell.files.read(f.remote_path, { length: max + 1 });
+                    if (bytes.length > max || bytes.length !== info.size)
+                        throw new UsageError('VM transfer file changed during reading.');
+                    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+                    if (await realpath(dirname(target)) !== folder)
+                        throw new Error('Transfer folder changed during the transfer.');
+                    await writeFile(target, bytes, { mode: 0o600, flag: 'wx' }); // An existing file needs a fresh explicit request, never a silent clobber.
+                }
+                result = { state: 'done', files_artifact: r.kind === 'files_pull' ? f.remote_path : target };
+            }
+            await this.result(r, result);
+        }
+        catch (e) {
+            await this.result(r, { state: 'failed', stderr_b64: Buffer.from(e instanceof Error ? e.message : String(e)).toString('base64') });
+        }
+        finally {
+            ws?.cell().close();
+        }
+    }
     async reap() {
         for (const [id, handle] of this.#handles) {
             const c = await getConversation(this.#ctx, handle.conversation);
@@ -435,3 +603,46 @@ export async function askConnectedAcp(dir, approval, signal) {
         } });
     });
 }
+/**
+ * The desktop app's approval hop (0.25.0+): while it runs it serves `<config dir>/device-approver.sock` (or, when that
+ * path is too long for a socket, `/tmp/sf-device-<uid>/<hash>-approver.sock`) and shows each approval as a Needs-you
+ * item. One line in (the DeviceApproval JSON), one line out (`{"choice":"once|always|deny"}`). No app, a socket that is
+ * not this user's own, or one that closes without an answer: null, and the next surface asks.
+ */
+export function approverSocket(dir) {
+    const path = join(dir, 'device-approver.sock');
+    if (Buffer.byteLength(path) < 100)
+        return path;
+    return join('/tmp', `sf-device-${process.getuid?.() ?? 'user'}`, `${createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 20)}-approver.sock`);
+}
+export async function askDeviceApprover(dir, approval, signal) {
+    const path = approverSocket(dir), uid = process.getuid?.();
+    try {
+        const socket = lstatSync(path), parent = lstatSync(dirname(path));
+        if (!socket.isSocket() || parent.isSymbolicLink() || !parent.isDirectory() || (parent.mode & 0o077) || (uid !== undefined && (socket.uid !== uid || parent.uid !== uid)))
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return new Promise((resolveChoice, reject) => {
+        const socket = createConnection(path);
+        let text = '';
+        const abort = () => { socket.destroy(); reject(signal.reason instanceof Error ? signal.reason : new Error('Device approval interrupted')); };
+        signal.addEventListener('abort', abort, { once: true });
+        socket.on('connect', () => socket.write(JSON.stringify(approval) + '\n'));
+        socket.on('data', bytes => { text += String(bytes); if (text.length > 1024)
+            socket.destroy(); });
+        socket.once('error', () => { signal.removeEventListener('abort', abort); resolveChoice(null); });
+        socket.once('close', () => {
+            signal.removeEventListener('abort', abort);
+            try {
+                const choice = JSON.parse(text.split('\n')[0]).choice;
+                resolveChoice(['once', 'always', 'deny'].includes(choice) ? choice : null);
+            }
+            catch {
+                resolveChoice(null);
+            }
+        });
+    });
+}

package/dist/device-folders.d.ts

@@ -0,0 +1,58 @@
+import type { Ctx, Handler } from './commands.js';
+export declare const FOLDER_KINDS: Set<string>;
+/** An absolute or `~/…` path: one the device resolves on its own, outside any conversation's folder. */
+export declare function isDevicePath(path: string): boolean;
+export declare function deviceHome(ctx: Pick<Ctx, 'io'>): string;
+export declare function expandDevicePath(path: string, home: string): string;
+/** Through every symlink of the part that exists; a path that does not exist yet keeps its missing tail. */
+export declare function canonicalDevicePath(target: string): string;
+/** `/Users/me/code` as `~/code`: how a person reads their own folders. */
+export declare function displayPath(path: string, home: string): string;
+export interface DirListing {
+    path: string;
+    entries: {
+        path: string;
+        kind: 'file' | 'dir' | 'symlink' | 'other';
+        size?: number;
+        git_remote?: string;
+    }[];
+    truncated: boolean;
+    git_remote?: string;
+}
+/** Names, kinds, sizes and Git remotes under `root`, breadth first, bounded in depth, count and bytes. */
+export declare function listDeviceDir(root: string, options?: {
+    depth?: number;
+    max_entries?: number;
+    include_hidden?: boolean;
+}, signal?: AbortSignal): Promise<DirListing>;
+export interface LinkedProject {
+    project_id: string;
+    repo_remote: string;
+    folder: string;
+    name: string;
+    conversation_id?: string;
+}
+type Starter = (ctx: Ctx, folder: string, harness: 'claude' | 'codex', brief: string) => Promise<{
+    id: string;
+    project_id: string;
+}>;
+/**
+ * A new chat in `folder`, started the way `shard agents new --path` starts one, in its own process: the folder's
+ * working tree (uncommitted files too, .gitignore respected) seeds it while its VM boots, and the brief is its first
+ * prompt. The brief goes in on standard input, never in a command line another user can read.
+ */
+export declare const startFromFolder: Starter;
+/**
+ * `folder` becomes one of your projects: the repository its Git origin names (else the folder itself), in your
+ * project on this API. It is selected for background preparation, so its files are in the cloud before the next chat,
+ * and kept as this device's live copy: what conversations started from it finish lands back in it. With `brief`, a
+ * conversation starts there at once. A folder without Git gets a repository, as a new chat from it does.
+ */
+export declare function linkLocalProject(ctx: Ctx, path: string, options?: {
+    brief?: string;
+    harness?: 'claude' | 'codex';
+    projectId?: string;
+}, start?: Starter): Promise<LinkedProject>;
+/** `shard projects link <path>` (0.25.0+): what the desktop app's "Add a folder…" runs, the same as a device's project_link. */
+export declare const PROJECT_LINK_HANDLERS: Record<string, Handler>;
+export {};

package/dist/device-folders.js

@@ -0,0 +1,228 @@
+/**
+ * Folders on this device that a conversation's agent asks about (0.25.0+): `dir_list` lists one (names, kinds, sizes
+ * and Git remotes; never file contents), `project_link` makes one a project of yours, seeded from here, and
+ * `files_pull`/`files_push` with an absolute or `~/` local path move a file to or from anywhere on this device.
+ *
+ * Nothing runs before this device approves it. The choices are Allow once and Always for this folder. Always covers
+ * that kind of request for that folder and everything inside it, resolved through symlinks, from any of your
+ * conversations on this API: a path outside every such folder asks again, and `exec` never uses a folder grant.
+ */
+import { execFile, spawn } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { lstat, readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { out, str } from "./commands.js";
+import { readInitialPrompt } from "./initial-prompt.js";
+import { UsageError } from "./errors.js";
+import { ensureProjectGit } from "./project-git.js";
+import { normalizeRemote, projectIdentity } from "./project-identity.js";
+import { selectProject } from "./project-preparation.js";
+export const FOLDER_KINDS = new Set(['dir_list', 'project_link']);
+/** An absolute or `~/…` path: one the device resolves on its own, outside any conversation's folder. */
+export function isDevicePath(path) { return isAbsolute(path) || path === '~' || path.startsWith('~/'); }
+export function deviceHome(ctx) { return ctx.io.env.HOME || homedir(); }
+export function expandDevicePath(path, home) {
+    if (/[\0\r\n]/.test(path))
+        throw new UsageError('Device path contains invalid characters.');
+    if (path === '~')
+        return resolve(home);
+    if (path.startsWith('~/'))
+        return resolve(home, path.slice(2));
+    if (!isAbsolute(path))
+        throw new UsageError('Device path must be absolute or start with ~/.');
+    return resolve(path);
+}
+/** Through every symlink of the part that exists; a path that does not exist yet keeps its missing tail. */
+export function canonicalDevicePath(target) {
+    let ancestor = target;
+    while (!existsSync(ancestor)) {
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            throw new UsageError('Device path is unavailable.');
+        ancestor = parent;
+    }
+    return resolve(realpathSync(ancestor), relative(ancestor, target));
+}
+/** `/Users/me/code` as `~/code`: how a person reads their own folders. */
+export function displayPath(path, home) {
+    const h = resolve(home);
+    return path === h ? '~' : path.startsWith(h + sep) ? `~/${path.slice(h.length + 1)}` : path;
+}
+/** Never descended into: their contents are noise to a person choosing a folder, and unbounded. */
+const OPAQUE = new Set(['.git', 'node_modules', '.shard']);
+/** The listing must fit the result body (1 MiB); paths and remotes over the API's 1024 characters are left out. */
+const LISTING_BYTES = 900 << 10, NAME_MAX = 1024, GIT_LOOKUPS = 200;
+function gitRemote(dir, signal) {
+    return new Promise(resolveRemote => {
+        execFile('git', ['-C', dir, 'remote', 'get-url', 'origin'], { timeout: 5000, signal, encoding: 'utf8', env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' } }, (error, stdout) => {
+            if (error || !stdout.trim()) {
+                resolveRemote(undefined);
+                return;
+            }
+            // normalizeRemote drops the transport's user and password: a listing never carries credentials.
+            try {
+                const remote = normalizeRemote(stdout.trim(), dir);
+                resolveRemote(remote.length <= NAME_MAX ? remote : undefined);
+            }
+            catch {
+                resolveRemote(undefined);
+            }
+        });
+    });
+}
+/** Names, kinds, sizes and Git remotes under `root`, breadth first, bounded in depth, count and bytes. */
+export async function listDeviceDir(root, options = {}, signal) {
+    const depth = Math.min(Math.max(options.depth ?? 1, 1), 3), max = Math.min(Math.max(options.max_entries ?? 500, 1), 2000);
+    if (!(await lstat(root)).isDirectory())
+        throw new UsageError('That path is not a folder.');
+    const entries = [], repos = [];
+    let truncated = false, bytes = 0, queue = [{ dir: root, rel: '', level: 1 }];
+    while (queue.length && !truncated) {
+        const next = [];
+        for (const { dir, rel, level } of queue) {
+            signal?.throwIfAborted();
+            let names;
+            try {
+                names = (await readdir(dir)).sort((a, b) => a.localeCompare(b));
+            }
+            catch {
+                continue;
+            } // an unreadable folder lists as itself
+            for (const name of names) {
+                if (!options.include_hidden && name.startsWith('.'))
+                    continue;
+                const path = rel ? `${rel}/${name}` : name, full = join(dir, name);
+                if (path.length > NAME_MAX) {
+                    truncated = true;
+                    continue;
+                }
+                let info;
+                try {
+                    info = await lstat(full);
+                }
+                catch {
+                    continue;
+                }
+                const kind = info.isSymbolicLink() ? 'symlink' : info.isDirectory() ? 'dir' : info.isFile() ? 'file' : 'other';
+                const entry = { path, kind, ...(kind === 'file' ? { size: info.size } : {}) };
+                bytes += JSON.stringify(entry).length + 80;
+                if (entries.length >= max || bytes > LISTING_BYTES) {
+                    truncated = true;
+                    break;
+                }
+                entries.push(entry);
+                if (kind !== 'dir')
+                    continue;
+                if (existsSync(join(full, '.git')) && repos.length < GIT_LOOKUPS)
+                    repos.push({ index: entries.length - 1, dir: full });
+                if (level < depth && !OPAQUE.has(name))
+                    next.push({ dir: full, rel: path, level: level + 1 });
+            }
+            if (truncated)
+                break;
+        }
+        queue = next;
+    }
+    // Git remotes are read eight at a time, each bounded: a folder of a hundred repositories lists in about a second.
+    const own = existsSync(join(root, '.git')) ? gitRemote(root, signal) : Promise.resolve(undefined);
+    for (let i = 0; i < repos.length; i += 8) {
+        await Promise.all(repos.slice(i, i + 8).map(async (repo) => { const remote = await gitRemote(repo.dir, signal); if (remote)
+            entries[repo.index].git_remote = remote; }));
+    }
+    const remote = await own;
+    return { path: root, entries, truncated, ...(remote ? { git_remote: remote } : {}) };
+}
+/**
+ * A new chat in `folder`, started the way `shard agents new --path` starts one, in its own process: the folder's
+ * working tree (uncommitted files too, .gitignore respected) seeds it while its VM boots, and the brief is its first
+ * prompt. The brief goes in on standard input, never in a command line another user can read.
+ */
+export const startFromFolder = (ctx, folder, harness, brief) => {
+    const node = ctx.runtime?.node ?? process.execPath, script = ctx.runtime?.script ?? process.argv[1];
+    if (!script)
+        return Promise.reject(new Error('The Shardflux CLI could not find itself to start the conversation.'));
+    return new Promise((resolveStart, reject) => {
+        const child = spawn(node, [script, 'agents', 'new', '--app', harness, '--path', folder, '--prompt-file', '-', '--json'], {
+            cwd: folder, stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, CI: '1' },
+        });
+        const out = [], err = [];
+        const stop = () => child.kill('SIGTERM');
+        const timer = setTimeout(stop, 300_000);
+        ctx.signal.addEventListener('abort', stop, { once: true });
+        child.stdout.on('data', (b) => { if (out.length < 256)
+            out.push(b); });
+        child.stderr.on('data', (b) => { if (err.length < 64)
+            err.push(b); });
+        child.once('error', error => { clearTimeout(timer); reject(error); });
+        child.once('close', code => {
+            clearTimeout(timer);
+            ctx.signal.removeEventListener('abort', stop);
+            const text = Buffer.concat(out).toString('utf8');
+            try {
+                if (code !== 0)
+                    throw new Error(lastLine(Buffer.concat(err).toString('utf8')) || `The conversation did not start (exit ${code}).`);
+                const started = JSON.parse(text.trim().split('\n').at(-1));
+                const id = started.conversation?.id ?? started.workspace?.labels?.shard_conversation;
+                if (!id)
+                    throw new Error('The conversation did not start.');
+                resolveStart({ id, project_id: started.conversation?.project_id ?? started.workspace?.project_id ?? '' });
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+        child.stdin.end(brief);
+    });
+};
+function lastLine(stderr) {
+    const text = stderr.trim();
+    try {
+        const doc = JSON.parse(text);
+        if (doc.error?.message)
+            return doc.error.message;
+    }
+    catch { /* plain text */ }
+    return text.split('\n').at(-1)?.slice(0, 2000) ?? '';
+}
+/**
+ * `folder` becomes one of your projects: the repository its Git origin names (else the folder itself), in your
+ * project on this API. It is selected for background preparation, so its files are in the cloud before the next chat,
+ * and kept as this device's live copy: what conversations started from it finish lands back in it. With `brief`, a
+ * conversation starts there at once. A folder without Git gets a repository, as a new chat from it does.
+ */
+export async function linkLocalProject(ctx, path, options = {}, start = startFromFolder) {
+    const { folder } = projectIdentity(path);
+    await ensureProjectGit(ctx, folder);
+    const identity = projectIdentity(folder);
+    selectProject(ctx, folder);
+    const profile = ctx.store.profile(ctx.apiUrl);
+    let projectId = profile.project_id ?? profile.api_key?.project_id ?? options.projectId, conversationId;
+    if (options.brief) {
+        const started = await start(ctx, folder, options.harness ?? 'claude', options.brief);
+        conversationId = started.id;
+        projectId = started.project_id || projectId;
+    }
+    // An API key from the environment (the desktop app's sign-in) names its project only to the API.
+    if (!projectId && ctx.io.env.SHARDFLUX_API_KEY?.trim())
+        projectId = (await ctx.cloud().me()).api_key?.project_id;
+    if (!projectId)
+        throw new UsageError('Choose your default project first: shard projects use <id|slug>.');
+    const name = [...(identity.remote ? identity.slug : basename(folder))].slice(0, 200).join('') || identity.slug;
+    return { project_id: projectId, repo_remote: identity.remote ?? `file://${folder}`, folder, name, ...(conversationId ? { conversation_id: conversationId } : {}) };
+}
+/** `shard projects link <path>` (0.25.0+): what the desktop app's "Add a folder…" runs, the same as a device's project_link. */
+export const PROJECT_LINK_HANDLERS = {
+    async 'projects link'(ctx, values, [path]) {
+        if (!path)
+            throw new UsageError('Choose a local folder: shard projects link <path>.');
+        const app = str(values.app);
+        if (app !== undefined && app !== 'claude' && app !== 'codex')
+            throw new UsageError('--app must be claude or codex.');
+        const brief = await readInitialPrompt(ctx, values);
+        const project = await linkLocalProject(ctx, expandDevicePath(isDevicePath(path) ? path : resolve(path), deviceHome(ctx)), { ...(brief ? { brief } : {}), ...(app ? { harness: app } : {}) });
+        out(ctx, `Linked ${displayPath(project.folder, deviceHome(ctx))} as ${project.name} (${project.repo_remote}); it is prepared in the background.\n${project.conversation_id ? `Started conversation ${project.conversation_id}.\n` : ''}`, { project });
+        return 0;
+    },
+};

package/dist/device-helper.d.ts

@@ -3,3 +3,9 @@ import type { Ctx } from './commands.js';
 export declare function runDeviceHelper(ctx: Ctx, options?: {
     service?: boolean;
 }): Promise<number>;
+/**
+ * The projects this device answers for besides its local conversations' (0.25.0+): the signed-in project (the API
+ * key's, or the default one), and with a person's own sign-in and no key, every project they can reach (at most 100).
+ * A home conversation, an Orchestrator master or a chat the desktop app started asks from these.
+ */
+export declare function deviceProjects(ctx: Ctx): Promise<string[]>;