@shardflux/cli 0.14.0 → 0.14.2

package/dist/device-bridge.js

@@ -18,11 +18,7 @@ const LIMIT = 256 << 20, OUTPUT = (192 << 10) - 128;
 const inside = (root, target) => target === root || target.startsWith(root + sep);
 const safeId = (value) => { if (!/^[a-zA-Z0-9_-]{1,96}$/.test(value))
     throw new Error('Invalid device request identity'); return value; };
-/** Resolve every existing ancestor, including symlinks. Missing leaf files do not hide an outside parent. */
-export function devicePath(root, requested = '.') {
-    if (/[\0\r\n]/.test(requested))
-        throw new UsageError('Device path contains invalid characters.');
-    const base = realpathSync(root), target = isAbsolute(requested) ? resolve(requested) : resolve(base, requested);
+function canonicalDevicePath(target) {
     let ancestor = target;
     while (!existsSync(ancestor)) {
         const parent = dirname(ancestor);
@@ -30,7 +26,14 @@ export function devicePath(root, requested = '.') {
             throw new UsageError('Device path is unavailable.');
         ancestor = parent;
     }
-    const canonical = resolve(realpathSync(ancestor), relative(ancestor, target));
+    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))
+        throw new UsageError('Device path contains invalid characters.');
+    const base = canonicalDevicePath(resolve(root)), target = isAbsolute(requested) ? resolve(requested) : resolve(base, requested);
+    const canonical = canonicalDevicePath(target);
     return { path: canonical, outside: !inside(base, canonical) };
 }
 export class DeviceGrants {
@@ -162,12 +165,13 @@ export class DeviceExecutor {
         const record = records[r.conversation_id] ?? (folders.size === 1 ? matching[0] : undefined);
         if (!record || record.project_id !== r.project_id)
             return; // No inferred local path for unknown projects.
-        let c = await getConversation(ctx, r.conversation_id), ws = await conversationWorkspace(ctx, c);
+        let c = await getConversation(ctx, r.conversation_id);
         if (c.project_id !== r.project_id)
             throw new Error('Device request project changed.');
-        const root = await ensureConversationWorktree(ctx, c, record.folder, ws);
+        const planned = devicePath(record.folder, join('.shard', 'worktrees', conversationName(c)));
         const requested = r.exec?.cwd_relative ?? r.files?.local_path_relative ?? '.';
-        const target = devicePath(root, requested), grants = new DeviceGrants(ctx.store.dir);
+        const target = devicePath(planned.path, requested), grants = new DeviceGrants(ctx.store.dir);
+        target.outside ||= planned.outside;
         const choice = grants.allows(ctx.apiUrl, r.project_id, record.folder, r.kind, target.outside) ? 'once' : await this.#ask({ type: 'approval', request_id: r.id, project_id: r.project_id, conversation_id: c.id, summary: deviceSummary(r), outside: target.outside });
         if (choice === 'deny') {
             await this.result(r, { state: 'denied' });
@@ -180,20 +184,27 @@ export class DeviceExecutor {
         if (choice === 'always')
             await grants.save(ctx.apiUrl, r.project_id, record.folder, r.kind);
         // Re-read after the approval, before claiming or touching data.
-        if (devicePath(root, requested).path !== target.path)
+        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')
             throw new Error('The conversation changed or ended during device approval.');
-        if (current.workspace_id !== c.workspace_id) {
-            ws.cell().close();
-            ws = await conversationWorkspace(ctx, current);
-        }
         c = current;
         await this.result(r, { state: 'approved' });
         await this.result(r, { state: 'running' });
-        const cell = ws.cell();
+        let ws;
         try {
+            // Approval is independent of VM/Git availability. Bound setup and report its
+            // failure through the existing running -> failed transition.
+            const preparation = { ...ctx, signal: AbortSignal.any([ctx.signal, AbortSignal.timeout(30_000)]) };
+            ws = await conversationWorkspace(preparation, c);
+            const root = await ensureConversationWorktree(preparation, c, record.folder, ws);
+            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')
+                throw new Error('The conversation changed or ended during device preparation.');
+            const cell = ws.cell();
             let result;
             if (r.kind === 'try_locally' || tryLocallyAction(r)) {
                 const action = tryLocallyAction(r);
@@ -260,7 +271,7 @@ export class DeviceExecutor {
         }
         finally {
             if (!this.#handles.has(r.id))
-                cell.close();
+                ws?.cell().close();
         }
     }
     async reap() {

package/dist/errors.d.ts

@@ -28,6 +28,13 @@ declare class HintedError extends Error {
 export declare class UsageError extends HintedError {
     name: string;
 }
+/** Keep Git exit statuses for optional probes while reporting actionable CLI errors. */
+export declare class GitError extends HintedError {
+    name: string;
+    readonly code: string | number | undefined;
+    readonly stderr: string;
+    constructor(folder: string, cause: unknown);
+}
 /**
  * A refusal `shard` detects itself, with a stable code, its facts in `details` and the next step as `hint` (exit 1),
  * e.g. `repository_too_large` (0.13.3+) for Git history over the initial sync limit.

package/dist/errors.js

@@ -36,6 +36,22 @@ class HintedError extends Error {
 export class UsageError extends HintedError {
     name = 'UsageError';
 }
+/** Keep Git exit statuses for optional probes while reporting actionable CLI errors. */
+export class GitError extends HintedError {
+    name = 'GitError';
+    code;
+    stderr;
+    constructor(folder, cause) {
+        const failure = cause;
+        const detail = failure.stderr?.trim() || failure.message || 'Git command failed';
+        super(`Git failed in ${folder}: ${detail}\n${failure.code === 'ENOENT' ? 'Install Git and make sure git is on PATH, then run shard again.' : 'Resolve this Git error, then run shard again.'}`, failure.code === 'ENOENT'
+            ? 'Install Git and make sure git is on PATH, then run shard again.'
+            : `Check Git permissions, configuration and repository state with git -C ${JSON.stringify(folder)} status, resolve the error above, then run shard again.`);
+        this.code = failure.code;
+        this.stderr = failure.stderr ?? '';
+        this.cause = cause;
+    }
+}
 /**
  * A refusal `shard` detects itself, with a stable code, its facts in `details` and the next step as `hint` (exit 1),
  * e.g. `repository_too_large` (0.13.3+) for Git history over the initial sync limit.
@@ -199,6 +215,8 @@ export function describeError(err) {
         return { code: 'timeout', message: err.message, last_state: err.session.state, details: { session_id: err.session.session_id } };
     if (err instanceof UsageError)
         return { code: 'usage', message: err.message };
+    if (err instanceof GitError)
+        return { code: 'git_error', message: err.message, retryable: false };
     if (err instanceof CodedError)
         return { code: err.code, message: err.message, retryable: false, ...(err.details ? { details: err.details } : {}) };
     if (err instanceof CheckoutTimeoutError) {

package/dist/git-remote-bin.js

@@ -22,7 +22,9 @@ try {
         if (!ws)
             throw new Error(`workspace ${remote.key} does not exist`);
         cell = ws.cell({ agentLabel: 'git-remote-shard', transitionTimeoutMs: 120_000 });
-        return cell.exec;
+        const capability = await cell.exec.run(['/usr/local/bin/sf-agent', 'git-bridge-info'], { timeoutMs: 10_000, maxOutputBytes: 4096, signal: controller.signal });
+        const platformGitBridge = capability.exitCode === 0 && JSON.parse(capability.stdout).version === 1;
+        return { ...cell.exec, platformGitBridge };
     }, controller.signal);
 }
 catch (error) {

package/dist/git-remote.d.ts

@@ -7,7 +7,9 @@ export interface ShardRemote {
 /** Keys have two segments (K9). Everything after the agent is an absolute guest path. */
 export declare function parseShardRemote(url: string): ShardRemote;
 export declare function shardRemote(key: string, path: string): string;
-export type GitExec = Pick<CellClient['exec'], 'start' | 'input' | 'output' | 'cancel'>;
+export type GitExec = Pick<CellClient['exec'], 'start' | 'input' | 'output' | 'cancel'> & {
+    platformGitBridge?: boolean;
+};
 /** No text decoding of the pack stream; offsets are acknowledged bytes, including partial stdin writes. */
 export declare function bridgeGit(exec: GitExec, service: string, path: string, input: AsyncIterable<Uint8Array>, stdout: Writable, stderr: Writable, signal: AbortSignal): Promise<number>;
 /** Git's `connect` capability switches from newline commands to a full-duplex smart protocol. */

package/dist/git-remote.js

@@ -28,7 +28,8 @@ export async function bridgeGit(exec, service, path, input, stdout, stderr, sign
         throw new UsageError('unsupported Git service');
     const controller = new AbortController();
     const combined = AbortSignal.any([signal, controller.signal]);
-    const session = await exec.start({ argv: [service, path], stdin_open: true, timeout_ms: 600_000 }, combined);
+    const argv = exec.platformGitBridge ? ['/usr/local/bin/sf-agent', 'git-bridge', '--service', service, '--path', path] : [service, path];
+    const session = await exec.start({ argv, stdin_open: true, timeout_ms: 600_000 }, combined);
     let ended = false, offset = 0;
     const send = async () => {
         for await (const chunk of input) {

package/dist/project-git.d.ts

@@ -0,0 +1,3 @@
+import type { Ctx } from './commands.js';
+/** Prepare only the selected project root. Never stage files or initialize a nested repository. */
+export declare function ensureProjectGit(ctx: Ctx, folder: string): Promise<void>;

package/dist/project-git.js

@@ -0,0 +1,52 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { gitRunner } from "./agent-git.js";
+import { GitError } from "./errors.js";
+/** Prepare only the selected project root. Never stage files or initialize a nested repository. */
+export async function ensureProjectGit(ctx, folder) {
+    const git = gitRunner(folder, { ...process.env, ...ctx.io.env, LC_ALL: 'C' }, ctx.signal, false);
+    let initialized = false;
+    try {
+        const top = await git(['rev-parse', '--show-toplevel']);
+        if (realpathSync(top) !== realpathSync(folder))
+            return;
+    }
+    catch (error) {
+        if (!(error instanceof GitError) || error.code !== 128 || !error.stderr.includes('not a git repository'))
+            throw error;
+        if (existsSync(join(folder, '.git')))
+            throw error;
+        await git(['init', '-b', 'main']);
+        initialized = true;
+    }
+    try {
+        await git(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}']);
+        return;
+    }
+    catch (error) {
+        if (!(error instanceof GitError) || error.code !== 1)
+            throw error;
+        // An absent branch is unborn; a broken existing ref is a Git failure, not permission to replace it.
+        const branch = await git(['symbolic-ref', 'HEAD']);
+        const absent = await git(['show-ref', '--verify', '--quiet', branch]).then(() => false, (refError) => {
+            if (!(refError instanceof GitError) || refError.code !== 1)
+                throw refError;
+            return true;
+        });
+        if (!absent)
+            throw error;
+    }
+    // --only with no paths makes an empty commit even when the user already has staged files.
+    const commit = ['-c', 'core.hooksPath=/dev/null', 'commit', '--allow-empty', '--only', '-m', 'Initial commit'];
+    try {
+        await git(commit);
+    }
+    catch (error) {
+        if (!(error instanceof GitError) || !/Author identity unknown|Committer identity unknown|unable to auto-detect email address|empty ident name|no (?:name|email) was given/.test(error.stderr))
+            throw error;
+        await git(['-c', 'user.name=Shardflux', '-c', 'user.email=noreply@shardflux.dev', ...commit]);
+    }
+    ctx.io.stderr.write(initialized
+        ? `Initialized a git repository in ${folder} (shard tracks your project with git).\n`
+        : `Created an initial empty commit in ${folder}.\n`);
+}

package/dist/project-sync-manifest.js

@@ -3,6 +3,7 @@ import { execFile } from 'node:child_process';
 import { constants } from 'node:fs';
 import { lstat, open, readdir, readlink, realpath } from 'node:fs/promises';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { GitError } from "./errors.js";
 export const MAX_SYNC_FILE_BYTES = 64 * 1024 * 1024;
 export const MAX_SYNC_ENTRIES = 20_000;
 export function validSyncPath(path) {
@@ -46,13 +47,19 @@ export function parseManifest(manifest) {
 }
 export async function projectGit(folder, args, signal, input = '') {
     return new Promise((resolve, reject) => {
-        const child = execFile('git', ['-C', folder, '-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false', '-c', 'core.hooksPath=/dev/null', ...args], { encoding: 'utf8', timeout: 30_000, maxBuffer: 4 << 20, signal, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' } }, (error, stdout) => {
-            if (error) {
-                const failure = Object.assign(new Error(error.message, { cause: error }), { code: error.code, stdout });
-                reject(failure);
-            }
-            else
+        const child = execFile('git', ['-C', folder, '-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false', '-c', 'core.hooksPath=/dev/null', ...args], { encoding: 'utf8', timeout: 30_000, maxBuffer: 4 << 20, signal, env: { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' } }, (error, stdout, stderr) => {
+            if (!error) {
                 resolve(stdout);
+                return;
+            }
+            if (signal?.aborted) {
+                const abortError = error;
+                reject(abortError);
+                return;
+            }
+            const failure = new GitError(folder, Object.assign(error, { stderr }));
+            Object.assign(failure, { stdout });
+            reject(failure);
         });
         child.stdin?.on('error', () => undefined); // Early Git refusal is reported by the callback.
         child.stdin?.end(input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -47,7 +47,7 @@
     "smol-toml": "1.9.0",
     "snappyjs": "0.7.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.19.0"
+    "@shardflux/sdk": "^0.19.1"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",