@shardflux/cli 0.24.0 → 0.24.1

package/dist/move.js

@@ -15,6 +15,7 @@
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { existsSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { dirname, relative, resolve } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { ShardfluxApiError } from '@shardflux/sdk';
@@ -31,13 +32,12 @@ import { conversationTerminal } from "./conversation-terminal.js";
 import { openInChoices } from "./t3-mode.js";
 import { openClaudeDesktopSession, remoteControlUrl } from "./agent-target-commands.js";
 import { openUrl } from "./browser.js";
-import { SYNC_CHUNK_BYTES } from "./project-sync-transfer.js";
 import { completeRecords, continuedAfter, findLocalSession, homeRelativeTranscript, listLocalSessions, readTranscript, recordCwd, rewriteSessionPaths, sessionState } from "./local-sessions.js";
 import { installDivergenceNotice, movedKey, movedSession, movedSessions, rememberMoved } from "./moved-sessions.js";
 import { captureWorktreeMigration, inspectWorktreeMigration, migrationScope, preserveWorktreeMigration, referencedWorktrees, rewriteWorktreeTranscript } from "./move-worktrees.js";
 import { interruptLocalTurn, MOVE_CONTINUATION, stopsLocalTurn } from "./move-interrupt.js";
 import { seedPhase } from "./seed-phases.js";
-const VM_HOME = '/home/user';
+import { homeSpelling, placeSessionFiles, sessionFiles, VM_HOME, writeChunks } from "./move-files.js";
 const SPACE = '/shardflux/project';
 /** A transcript above this moves with the repository's history bound. */
 const TRANSCRIPT_LIMIT = 256 << 20;
@@ -86,14 +86,6 @@ export async function waitForTurnEnd(ctx, s, env, pollMs = 1000) {
         await delay(pollMs, undefined, { signal: ctx.signal });
     }
 }
-async function writeChunks(cell, path, bytes) {
-    if (!bytes.length) {
-        await cell.files.write(path, '', { mode: '0600' });
-        return;
-    }
-    for (let at = 0; at < bytes.length; at += SYNC_CHUNK_BYTES)
-        await cell.files.write(path, bytes.subarray(at, at + SYNC_CHUNK_BYTES), { mode: '0600', append: at > 0 });
-}
 /**
  * The session's transcript in the conversation's VM: at its native path (where the harness resumes it) and, when the
  * project space is mounted, as the conversation's durable copy with the same checkpoint metadata the guest writes
@@ -252,6 +244,13 @@ export async function moveSession(ctx, values) {
         if (elsewhere.length && !ctx.json)
             ctx.io.stderr.write(`This session also worked in ${elsewhere.length === 1 ? 'another worktree' : `${elsewhere.length} other worktrees`} of this repository (${elsewhere.join(', ')}); ${elsewhere.length === 1 ? 'it stays' : 'they stay'} on this computer. shard move --preserve-all-worktrees copies every worktree.\n`);
     }
+    // Files it used outside the project (an @-mentioned ~/Downloads/handoff.md) go along at the same paths (0.25.0+).
+    const home = env.HOME || homedir();
+    const files = sessionFiles(bytes, s.harness, home, [folder, ...(plan?.trees.map(t => t.source) ?? []), ...elsewhere]);
+    if (!ctx.json && files.files.length)
+        ctx.io.stderr.write(`Bringing ${files.files.length === 1 ? 'a file' : `${files.files.length} files`} it used outside the project: ${files.files.map(f => homeSpelling(home, f.path)).join(', ')}\n`);
+    if (!ctx.json && files.left.length)
+        ctx.io.stderr.write(`Staying on this computer (past the move’s 64 files, 64 MiB): ${files.left.map(p => homeSpelling(home, p)).join(', ')}\n`);
     const sha256 = createHash('sha256').update(bytes).digest('hex');
     if (!ctx.json)
         ctx.io.stderr.write(`Moving ${s.harness === 'claude' ? 'Claude Code' : 'Codex'} session “${s.title}” to the cloud…\n`);
@@ -270,6 +269,7 @@ export async function moveSession(ctx, values) {
             // The workspace's cell handle is shared with the seed that follows: it stays open.
             beforeSeed: async (ws, c) => {
                 placed = await placeTranscript(ws.cell(), c, s, bytes, folder, ctx.signal, values['preserve-all-worktrees'] === true && plan ? plan : undefined);
+                await placeSessionFiles(ws.cell(), files, home, ctx.signal);
             },
         });
     }
@@ -303,7 +303,8 @@ export async function moveSession(ctx, values) {
     if (!attach) {
         const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
         await conversationTerminal(quiet, ws, c, place, { ...terminalValues, detach: true });
-        out(ctx, `Moved to the cloud as ${c.key}: the same session, with its history. Open it: shard agents open ${c.key}\n`, { moved, conversation: c, workspace: ws.data, ...(placed ? { transcript: placed } : {}), ...(preserved ? { preserved } : {}), ...(elsewhere.length ? { other_worktrees: elsewhere } : {}) });
+        out(ctx, `Moved to the cloud as ${c.key}: the same session, with its history. Open it: shard agents open ${c.key}\n`, { moved, conversation: c, workspace: ws.data, ...(placed ? { transcript: placed } : {}), ...(preserved ? { preserved } : {}), ...(elsewhere.length ? { other_worktrees: elsewhere } : {}),
+            ...(files.files.length ? { files: files.files.map(f => f.path) } : {}), ...(files.left.length ? { files_left: files.left } : {}) });
         return 0;
     }
     const where = openInChoices(ctx, project.slug)[s.harness];

package/dist/onboarding.d.ts

@@ -22,6 +22,7 @@ type CredentialRow = {
     app: string;
     status?: string;
     scope?: string;
+    fingerprint?: string | null;
     access?: {
         verdict: 'usable' | 'refused' | 'unknown';
         checked_at: string;
@@ -75,8 +76,11 @@ export interface T3SignInRow {
 export declare function t3Connection(ctx: Ctx, signedIn: boolean, appDirs?: string[], platform?: NodeJS.Platform, startSignIn?: boolean, scope?: Values): Promise<Connection | null>;
 /** Claude: the account login is ready and Claude itself accepts it right now. */
 export declare function claudeConnection(row: CredentialRow | undefined): Omit<Connection, 'id' | 'picked' | 'found'>;
-/** Codex: this computer's Codex login is copied and the account's Codex remote device (one executor) is connected. */
-export declare function codexConnection(local: boolean, synced: boolean, connector: CodexConnectorView | null, health: CodexHealth): Omit<Connection, 'id' | 'picked' | 'found'>;
+/**
+ * Codex: this computer's Codex login is copied and the account's Codex remote device (one executor) is connected.
+ * `renewed`: this computer has a Codex login other than the one in the cloud (a new sign-in not copied yet).
+ */
+export declare function codexConnection(local: boolean, synced: boolean, connector: CodexConnectorView | null, health: CodexHealth, renewed?: boolean): Omit<Connection, 'id' | 'picked' | 'found'>;
 /**
  * The onboarding report, for an agent setting itself up from chat and for the menu bar app. It verifies every
  * connection live: the Shardflux account, Claude (Claude itself accepts the login) and Codex (the login is copied and

package/dist/onboarding.js

@@ -7,9 +7,9 @@ import { AgentStateStore } from "./agent-state.js";
 import { describeError } from "./errors.js";
 import { t3PhoneLink } from "./t3-phone.js";
 import { t3NeedsProject, t3SignInProject } from "./account-scope.js";
-import { readAgentCredentials, syncAgentCredentials } from "./agent-credentials.js";
+import { credentialFingerprint, readAgentCredentials, syncAgentCredentials } from "./agent-credentials.js";
 import { getConversation } from "./conversations.js";
-import { codexHealth, readCodexConnector, restartCodexConnector } from "./codex-cloud.js";
+import { CODEX_SIGN_IN_LINE, codexHealth, readCodexConnector, restartCodexConnector } from "./codex-cloud.js";
 import { applicationDirs } from "./agent-targets.js";
 import { configureT3Provider } from "./t3-provider.js";
 import { t3Install } from "./t3-mode.js";
@@ -198,8 +198,11 @@ export function claudeConnection(row) {
         return { state: 'action', fact: 'Claude no longer accepts this sign-in.', action: { ...signIn, title: 'Sign in to Claude again' } };
     return { state: 'verified', fact: 'Signed in. Works in every conversation, on web and phone.' };
 }
-/** Codex: this computer's Codex login is copied and the account's Codex remote device (one executor) is connected. */
-export function codexConnection(local, synced, connector, health) {
+/**
+ * Codex: this computer's Codex login is copied and the account's Codex remote device (one executor) is connected.
+ * `renewed`: this computer has a Codex login other than the one in the cloud (a new sign-in not copied yet).
+ */
+export function codexConnection(local, synced, connector, health, renewed = false) {
     const enable = { title: 'Connect Codex', command: shard(['agents', 'codex', 'enable']) };
     if (!synced) {
         return local ? { state: 'action', fact: 'Available on web and phone once connected.', action: enable }
@@ -215,6 +218,11 @@ export function codexConnection(local, synced, connector, health) {
         case 'failed': return { state: 'action', fact: 'Codex’s remote device didn’t start.', action: retry };
         case 'stuck': return { state: 'action', fact: 'Codex’s remote device is taking too long to start.', action: retry };
         case 'attention': return { state: 'action', fact: connector?.last_error ? `Codex needs attention: ${connector.last_error}` : 'Codex needs attention.', action: retry };
+        // Codex Cloud refused the copied ChatGPT login (0.25.0+): sign in to Codex again here, then copy that sign-in, which
+        // starts the device again by itself. Never Retry: a restart cannot fix a sign-in.
+        case 'sign_in': return renewed
+            ? { state: 'action', fact: 'Your new Codex sign-in is ready to copy to the cloud.', action: { title: 'Copy sign-in', command: shard(['agents', 'credentials', 'sync']) } }
+            : { state: 'action', fact: CODEX_SIGN_IN_LINE, action: { title: 'Sign in to Codex again', command: ['codex', 'login'] } };
     }
 }
 /**
@@ -237,7 +245,10 @@ export async function onboardingReport(ctx, values, platform = process.platform)
     let connector = null;
     let health = 'missing';
     const home = ctx.io.env.HOME ?? ctx.io.env.USERPROFILE;
-    const localCodex = home ? (await readAgentCredentials({ home, redact: value => ctx.addSecret(value) })).some(v => v.app === 'codex') : false;
+    const localLogin = home ? (await readAgentCredentials({ home, redact: value => ctx.addSecret(value) })).find(v => v.app === 'codex') : undefined;
+    const localCodex = localLogin !== undefined;
+    /** Whether this computer's Codex login differs from the copy in the cloud. */
+    const renewed = (rows) => localLogin !== undefined && rows.find(row => row.app === 'codex')?.fingerprint !== credentialFingerprint(localLogin.files);
     try {
         ctx.apiKey();
         const principal = await ctx.cloud().me();
@@ -284,6 +295,13 @@ export async function onboardingReport(ctx, values, platform = process.platform)
                     read = { connector: await ctx.cloud().codex.enable({ signal: ctx.signal }), workspaceState: null };
                     health = codexHealth(read.connector, null);
                 }
+                else if (connect && synced && health === 'sign_in' && renewed(credentials) && home) {
+                    // A new Codex sign-in on this computer: copy it, and the device starts again with it (never a restart).
+                    await syncAgentCredentials(ctx.cloud(), { home, redact: value => ctx.addSecret(value) });
+                    credentials = await listCredentials();
+                    read = { connector: await ctx.cloud().codex.enable({ signal: ctx.signal }), workspaceState: null };
+                    health = codexHealth(read.connector, null);
+                }
                 else if (connect && synced && values['retry-codex'] === true && (health === 'failed' || health === 'stuck' || health === 'attention')) {
                     read = { connector: await restartCodexConnector(ctx), workspaceState: null };
                     health = codexHealth(read.connector, null);
@@ -304,7 +322,7 @@ export async function onboardingReport(ctx, values, platform = process.platform)
         ...(!connected ? signIn : codexError instanceof ShardfluxApiError && codexError.reason === 'codex_chatgpt_login_required'
             ? { state: 'action', fact: codexError.message, action: { title: 'Sign in with ChatGPT', command: ['codex', 'login'] } }
             : (credentialError ?? codexError) !== undefined ? failure(credentialError ?? codexError)
-                : codexConnection(localCodex, credentials.some(row => row.app === 'codex'), connector, health)) };
+                : codexConnection(localCodex, credentials.some(row => row.app === 'codex'), connector, health, renewed(credentials))) };
     const t3 = await t3Connection(ctx, connected || ctx.sessionSource() !== null, undefined, undefined, values['t3-connect'] === true, values);
     const connections = [account, claude, codex, ...(t3 ? [t3] : [])];
     // The cloud machine (0.20.2+), the same row `shard machine setup --status` reports: whether what is installed carries

package/dist/project-git.d.ts

@@ -1,3 +1,9 @@
 import type { Ctx } from './commands.js';
-/** Prepare only the selected project root. Never stage files or initialize a nested repository. */
+/**
+ * Prepare only the selected project root; never a nested repository. A folder without Git becomes a repository whose
+ * first commit is its files (.gitignore respected; large untracked media stay untracked, as a twin snapshot leaves
+ * them): a conversation then starts from the same commit as the folder and its work fast-forwards back, as in a
+ * repository the person made (0.25.0+; before, an empty first commit left every file to a snapshot, and landings
+ * conflicted). A repository of the person's own keeps its staged and untracked files as they are.
+ */
 export declare function ensureProjectGit(ctx: Ctx, folder: string): Promise<void>;

package/dist/project-git.js

@@ -1,8 +1,16 @@
+import { createHash } from 'node:crypto';
 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. */
+import { largeUntrackedMedia, outsideSpecs } from "./large-media.js";
+/**
+ * Prepare only the selected project root; never a nested repository. A folder without Git becomes a repository whose
+ * first commit is its files (.gitignore respected; large untracked media stay untracked, as a twin snapshot leaves
+ * them): a conversation then starts from the same commit as the folder and its work fast-forwards back, as in a
+ * repository the person made (0.25.0+; before, an empty first commit left every file to a snapshot, and landings
+ * conflicted). A repository of the person's own keeps its staged and untracked files as they are.
+ */
 export async function ensureProjectGit(ctx, folder) {
     const git = gitRunner(folder, { ...process.env, ...ctx.io.env, LC_ALL: 'C' }, ctx.signal, false);
     let initialized = false;
@@ -37,7 +45,12 @@ export async function ensureProjectGit(ctx, folder) {
             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'];
+    let commit = ['-c', 'core.hooksPath=/dev/null', 'commit', '--allow-empty', '--only', '-m', 'Initial commit'];
+    if (initialized) {
+        const media = await largeUntrackedMedia(folder, ctx.store.dir, `init-${createHash('sha256').update(folder).digest('hex').slice(0, 16)}`, ctx.signal);
+        await git(['add', '-A', '--', '.', ...outsideSpecs(media)]);
+        commit = ['-c', 'core.hooksPath=/dev/null', 'commit', '--allow-empty', '-m', 'Initial commit'];
+    }
     try {
         await git(commit);
     }
@@ -47,6 +60,6 @@ export async function ensureProjectGit(ctx, folder) {
         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`
+        ? `Initialized a git repository in ${folder} with its files as the first commit (shard tracks your project with git).\n`
         : `Created an initial empty commit in ${folder}.\n`);
 }

package/dist/project-preparation.d.ts

@@ -38,6 +38,13 @@ export interface SetupStatus {
     }[];
 }
 export declare function setupFailure(status: SetupStatus): CodedError;
+/**
+ * A setup that failed only because the project has no build or test command (the guest's `.:checks` step, unresolved
+ * at detection) has nothing left to prepare: its files are in the cache and every other step succeeded. That is a
+ * clean ready, never an error that waits for an edit (0.25.0+; before, a plain folder from `projects link` stayed
+ * flagged).
+ */
+export declare function nothingToCheck(status: SetupStatus): boolean;
 /** New content past this, or a dependency change, makes a quiet project worth preparing again. */
 export declare const PREPARE_AGAIN_BYTES: number;
 /** Quiet this long after the last edit before preparing again. */

package/dist/project-preparation.js

@@ -40,6 +40,18 @@ export function setupFailure(status) {
     const fix = `${first}${step ? `, or set run for ${step.name} under steps in .shardflux/setup.yaml` : ''}; the project is prepared again after the change`;
     return new SetupFailed('project_setup_failed', message, fix, step ? { step: step.name, ...(step.error?.code ? { error_code: step.error.code } : {}) } : undefined);
 }
+/**
+ * A setup that failed only because the project has no build or test command (the guest's `.:checks` step, unresolved
+ * at detection) has nothing left to prepare: its files are in the cache and every other step succeeded. That is a
+ * clean ready, never an error that waits for an edit (0.25.0+; before, a plain folder from `projects link` stayed
+ * flagged).
+ */
+export function nothingToCheck(status) {
+    const failed = status.tasks?.filter(t => t.state === 'failed') ?? [];
+    return status.state === 'failed' && failed.length > 0
+        && failed.every(t => t.error?.code === 'setup_detection_unresolved' && /(^|:)checks$/.test(t.name))
+        && (status.tasks ?? []).every(t => t.state === 'failed' ? failed.includes(t) : ['succeeded', 'skipped'].includes(t.state));
+}
 /** New content past this, or a dependency change, makes a quiet project worth preparing again. */
 export const PREPARE_AGAIN_BYTES = 8 << 20;
 /** Quiet this long after the last edit before preparing again. */
@@ -158,6 +170,8 @@ export async function prepareSelectedProject(ctx, selected) {
                     if (status.exitCode !== 0)
                         throw new Error(`Project setup status failed: ${status.stderr.trim()}`);
                     const state = JSON.parse(status.stdout);
+                    if (nothingToCheck(state))
+                        break;
                     if (state.state === 'failed')
                         throw setupFailure(state);
                     if (Date.now() > deadline)

package/dist/project-template-setup.js

@@ -23,20 +23,41 @@ export function dependencyHash(folder) {
             throw error;
     }
     const files = [];
-    const walk = (relative, devcontainer) => {
-        for (const name of readdirSync(join(folder, relative)).sort()) {
-            const path = relative ? `${relative}/${name}` : name;
-            const st = lstatSync(join(folder, path));
-            const inside = devcontainer || name === '.devcontainer';
-            if (st.isDirectory()) {
-                if (!skippedDirs.has(name))
-                    walk(path, inside);
+    const wanted = (path, name, inside) => name !== '.env' && !name.startsWith('.env.') && (inside || path.startsWith('.github/workflows/') || dependencyName(name));
+    if (selected) {
+        // Git's list is the whole input: walking the folder visited every ignored and untracked tree too (a folder of
+        // agent worktrees held 1.2 million entries and cost 29 s of every start).
+        for (const path of selected) {
+            const parts = path.split('/'), name = parts.at(-1);
+            if (!name || parts.slice(0, -1).some(dir => skippedDirs.has(dir)) || !wanted(path, name, parts.includes('.devcontainer')))
+                continue;
+            let st;
+            try {
+                st = lstatSync(join(folder, path));
             }
-            else if ((st.isFile() || st.isSymbolicLink()) && (!selected || selected.has(path)) && name !== '.env' && !name.startsWith('.env.') && (inside || path.startsWith('.github/workflows/') || dependencyName(name)))
+            catch {
+                continue;
+            }
+            if (st.isFile() || st.isSymbolicLink())
                 files.push(path);
         }
-    };
-    walk('', false);
+    }
+    else {
+        const walk = (relative, devcontainer) => {
+            for (const name of readdirSync(join(folder, relative)).sort()) {
+                const path = relative ? `${relative}/${name}` : name;
+                const st = lstatSync(join(folder, path));
+                const inside = devcontainer || name === '.devcontainer';
+                if (st.isDirectory()) {
+                    if (!skippedDirs.has(name))
+                        walk(path, inside);
+                }
+                else if ((st.isFile() || st.isSymbolicLink()) && wanted(path, name, inside))
+                    files.push(path);
+            }
+        };
+        walk('', false);
+    }
     const hash = createHash('sha256').update('shardflux-deps-v2\0');
     for (const path of files.sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)))) {
         const st = lstatSync(join(folder, path));

package/dist/router-commands.d.ts

@@ -0,0 +1,22 @@
+import type { RouterResult, Shardflux, ShardfluxAccount } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
+/** The API's bound on one input or question (characters). */
+export declare const BOARD_TEXT_MAX = 4000;
+interface BoardClient {
+    client: Shardflux | ShardfluxAccount;
+    /** The signed-in session: the organization's whole board. */
+    session: boolean;
+}
+/** SHARDFLUX_API_KEY in the environment wins; else the signed-in session; else the saved key (its error names both). */
+export declare function boardClient(ctx: Ctx): BoardClient;
+/**
+ * The readable form of a RouterResult: the kind and where it goes, then each part (a split's parts numbered, with
+ * their titles).
+ *
+ *   2 tasks in site
+ *     1. Fix the landing page hero image
+ *        fix the hero image on the landing page
+ */
+export declare function routeText(r: RouterResult, names: ReadonlyMap<string, string>): string;
+export declare const ROUTER_HANDLERS: Record<string, Handler>;
+export {};

package/dist/router-commands.js

@@ -0,0 +1,179 @@
+/**
+ * `shard route` and `shard ask` (0.25.0+): the board's input bar from a terminal, through @shardflux/sdk's
+ * `router.route()` and `questions.stream()` / `questions.ask()`. The signed-in session reads every project of an
+ * organization; SHARDFLUX_API_KEY in the environment (or a saved key without a session) reads that key's project.
+ */
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { UUID } from "./args.js";
+import { findOrg, resolveOrg, resolveProject } from "./account-scope.js";
+import { out, str } from "./commands.js";
+import { EXIT, UsageError } from "./errors.js";
+/** The API's bound on one input or question (characters). */
+export const BOARD_TEXT_MAX = 4000;
+const TASK_ID = /^[A-Za-z0-9_-]{1,64}$/;
+/** SHARDFLUX_API_KEY in the environment wins; else the signed-in session; else the saved key (its error names both). */
+export function boardClient(ctx) {
+    if (!ctx.io.env.SHARDFLUX_API_KEY?.trim() && ctx.sessionSource() !== null)
+        return { client: ctx.account(), session: true };
+    return { client: ctx.cloud(), session: false };
+}
+/** --org / --project as ids (slugs resolved with the session); with neither, the saved default organization. */
+async function scopeOf(ctx, values, b) {
+    const org = str(values.org), project = str(values.project);
+    if (!b.session) {
+        for (const [flag, v] of [['--org', org], ['--project', project]]) {
+            if (v !== undefined && !UUID.test(v))
+                throw new UsageError(`${flag} must be an id (UUID) with a project API key`, 'or sign in (shard auth login) to name it by slug');
+        }
+        return { scope: { ...(org === undefined ? {} : { organizationId: org }), ...(project === undefined ? {} : { projectId: project }) }, defaulted: false };
+    }
+    const account = b.client;
+    const scope = {};
+    if (org !== undefined)
+        scope.organizationId = UUID.test(org) ? org : (await findOrg(account, org)).id;
+    if (project !== undefined)
+        scope.projectId = UUID.test(project) ? project : (await resolveProject(ctx, account, values)).id;
+    if (org !== undefined || project !== undefined)
+        return { scope, defaulted: false };
+    const saved = ctx.store.profile(ctx.apiUrl).organization_id;
+    return { scope: saved ? { organizationId: saved } : {}, defaulted: true };
+}
+/**
+ * Runs `call` in the board's scope. With the session and no --org/--project: the saved default organization, else the
+ * only one; when the person is in several and none is saved (422), or the saved one is gone (404), the error lists
+ * theirs and names the fix (resolveOrg), and an organization that resolves is used.
+ */
+async function inScope(ctx, values, call) {
+    const b = boardClient(ctx);
+    const { scope, defaulted } = await scopeOf(ctx, values, b);
+    try {
+        return await call(b.client, scope);
+    }
+    catch (err) {
+        if (!b.session || !defaulted || !(err instanceof ShardfluxApiError))
+            throw err;
+        const several = err.status === 422 && scope.organizationId === undefined && /organization/i.test(err.message);
+        const gone = err.status === 404 && scope.organizationId !== undefined;
+        if (!several && !gone)
+            throw err;
+        const org = await resolveOrg(ctx, b.client, {});
+        if (org.id === scope.organizationId)
+            throw err;
+        return call(b.client, { organizationId: org.id });
+    }
+}
+function textOf(words, what, command) {
+    const text = words.join(' ').trim();
+    if (!text)
+        throw new UsageError(`missing <${what}> for "shard ${command}"`);
+    if (text.length > BOARD_TEXT_MAX)
+        throw new UsageError(`the ${what} is ${text.length} characters; the limit is ${BOARD_TEXT_MAX}`);
+    return text;
+}
+function taskOf(values) {
+    const task = str(values.task);
+    if (task !== undefined && !TASK_ID.test(task))
+        throw new UsageError('--task must be a task id (task_…)');
+    return task;
+}
+/** Project names for the readable form (GET /v1/projects/{id}); an id that cannot be read prints as itself. */
+async function projectNames(client, parts, signal) {
+    const ids = [...new Set(parts.filter((p) => !p.home && p.project_id).map((p) => p.project_id))];
+    const names = await Promise.all(ids.map((id) => client.request('GET', `/v1/projects/${encodeURIComponent(id)}`, { signal }).then((p) => p.name, () => id)));
+    return new Map(ids.map((id, i) => [id, names[i]]));
+}
+/**
+ * The readable form of a RouterResult: the kind and where it goes, then each part (a split's parts numbered, with
+ * their titles).
+ *
+ *   2 tasks in site
+ *     1. Fix the landing page hero image
+ *        fix the hero image on the landing page
+ */
+export function routeText(r, names) {
+    const where = (p) => (p.home ? 'on your home' : p.project_id ? `in ${names.get(p.project_id) ?? p.project_id}` : '');
+    const parts = r.parts;
+    const same = parts.every((p) => where(p) === where(parts[0]));
+    let head = r.kind === 'task' && parts.length > 1 ? `${parts.length} tasks` : r.kind;
+    if (r.task_ref)
+        head += r.kind === 'steer' ? ` ${r.task_ref}` : ` about ${r.task_ref}`;
+    if (same && where(parts[0]))
+        head += ` ${where(parts[0])}`;
+    const notes = [r.forced === 'question' ? 'asked as a question' : '', r.uncertain ? 'project uncertain' : ''].filter(Boolean);
+    if (notes.length)
+        head += ` (${notes.join(', ')})`;
+    const lines = [head];
+    if (parts.length === 1) {
+        const p = parts[0];
+        if (p.title)
+            lines.push(`  ${p.title}`);
+        lines.push(`  ${p.text}${same ? '' : ` (${where(p)})`}`);
+    }
+    else {
+        parts.forEach((p, i) => {
+            lines.push(`  ${i + 1}. ${p.title ?? p.text}${same ? '' : ` (${where(p)})`}`);
+            if (p.title)
+                lines.push(`     ${p.text}`);
+        });
+    }
+    return `${lines.join('\n')}\n`;
+}
+const interrupted = (ctx, err) => {
+    if (ctx.signal.aborted)
+        return EXIT.interrupted;
+    throw err;
+};
+export const ROUTER_HANDLERS = {
+    async route(ctx, values, words) {
+        const text = textOf(words, 'text', 'route');
+        const selectedTaskId = taskOf(values);
+        try {
+            const { result, client } = await inScope(ctx, values, async (client, scope) => ({
+                client,
+                result: await client.router.route({ text, ...(selectedTaskId === undefined ? {} : { selectedTaskId }), ...scope, signal: ctx.signal }),
+            }));
+            if (ctx.json) {
+                out(ctx, '', result);
+                return EXIT.ok;
+            }
+            ctx.io.stdout.write(routeText(result, await projectNames(client, result.parts, ctx.signal)));
+            return EXIT.ok;
+        }
+        catch (err) {
+            return interrupted(ctx, err);
+        }
+    },
+    async ask(ctx, values, words) {
+        const text = textOf(words, 'question', 'ask');
+        const taskId = taskOf(values);
+        const params = { text, ...(taskId === undefined ? {} : { taskId }), signal: ctx.signal };
+        try {
+            if (ctx.json) {
+                out(ctx, '', await inScope(ctx, values, (client, scope) => client.questions.ask({ ...params, ...scope })));
+                return EXIT.ok;
+            }
+            // Standard output carries the answer as it is written; the place in line (while it waits) goes to stderr.
+            await inScope(ctx, values, async (client, scope) => {
+                let written = '';
+                for await (const e of client.questions.stream({ ...params, ...scope })) {
+                    if (e.type === 'queued')
+                        ctx.io.stderr.write(`Queued: position ${e.position}, about ${Math.max(1, Math.round(e.expectedWaitMs / 1000))} s\n`);
+                    else if (e.type === 'delta') {
+                        ctx.io.stdout.write(e.text);
+                        written += e.text;
+                    }
+                    else {
+                        if (!written)
+                            ctx.io.stdout.write((written = e.answer.text));
+                        if (!written.endsWith('\n'))
+                            ctx.io.stdout.write('\n');
+                    }
+                }
+            });
+            return EXIT.ok;
+        }
+        catch (err) {
+            return interrupted(ctx, err);
+        }
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "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",
@@ -48,7 +48,7 @@
     "snappyjs": "0.7.0",
     "ws": "8.22.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.27.2"
+    "@shardflux/sdk": "^0.27.3"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",