@shardflux/cli 0.19.1 → 0.22.0

package/dist/t3-mode.js

@@ -35,8 +35,11 @@ import { T3_THREAD_SCRIPT } from "./t3-thread-script.js";
 import { t3InstallScript } from "./t3-runtime.js";
 import { uploadInitialImages } from "./initial-prompt.js";
 export const T3_BUNDLE_ID = 'com.t3tools.t3code';
-/** Where each app's new conversations can open: Claude in a terminal, Claude Desktop, claude.ai or T3; Codex in the Codex app or T3. */
-export const OPEN_IN_TARGETS = { claude: ['terminal', 'claude-desktop', 'web', 't3'], codex: ['codex-app', 't3'] };
+/**
+ * Where each app's new conversations can open: Claude in a terminal app, Claude Desktop, claude.ai or T3; Codex in the
+ * Codex app, a terminal app (0.21.1+ on macOS) or T3. `agents targets --json` reports them as `open_in_targets`.
+ */
+export const OPEN_IN_TARGETS = { claude: ['terminal', 'claude-desktop', 'web', 't3'], codex: ['codex-app', 'terminal', 't3'] };
 export const openInTargets = (app, platform = process.platform) => platform === 'linux' && app === 'codex' ? ['terminal', 't3'] : OPEN_IN_TARGETS[app];
 /** T3 0.0.45's built-in defaults (DEFAULT_MODEL_BY_PROVIDER), used only when T3 in the VM has not described its models yet. */
 const T3_DEFAULT_MODEL = { claude: 'claude-fable-5-1', codex: 'gpt-6-astra' };
@@ -173,10 +176,22 @@ export function openInChoices(ctx, project, known = {}) {
     return { claude: choices.claude.target, codex: choices.codex.target };
 }
 const available = (target, status, clients) => target === 't3' ? status.installed : target === 'claude-desktop' ? clients.includes('claude-desktop') : true;
-/** `--open-in claude=t3,codex=t3`: validated against what is installed, then saved in agents.json. */
+/**
+ * `--open-in claude=t3,codex=t3`: validated against what is installed, then saved in agents.json. A bare target
+ * (`--open-in terminal`, 0.20.1+) is the choice of every app that opens there (terminal: Claude and Codex).
+ */
 export function saveOpenIn(ctx, spec, status, clients) {
     const choices = {};
-    for (const part of spec.split(',').map(s => s.trim()).filter(Boolean)) {
+    const apps = ['claude', 'codex'];
+    const parts = spec.split(',').map(s => s.trim()).filter(Boolean).flatMap(part => {
+        if (part.includes('='))
+            return [part];
+        const fits = apps.filter(app => openInTargets(app).includes(part));
+        if (!fits.length)
+            throw new UsageError(`--open-in: a target is one of ${[...new Set(apps.flatMap(app => openInTargets(app)))].join(', ')}, or app=target pairs such as claude=t3,codex=t3.`);
+        return fits.map(app => `${app}=${part}`);
+    });
+    for (const part of parts) {
         const [app, target, extra] = part.split('=').map(s => s.trim());
         if (app !== 'claude' && app !== 'codex' || !target || extra !== undefined)
             throw new UsageError('--open-in takes app=target pairs, e.g. claude=t3,codex=t3.');

package/dist/t3-phone.d.ts

@@ -12,6 +12,8 @@ export interface T3PhoneLink {
 }
 /**
  * Links a workspace for the T3 app on the phone (0.17.0+). An API key links with its creator's sign-in; starting that
- * sign-in takes the person's own session, so the sign-in comes from `shard`'s session when the key has none yet.
+ * sign-in takes the person's own session, so the sign-in comes from `shard`'s session when the key has none yet. That
+ * sign-in is for the workspace's organization: `projectId` (the workspace's project) scopes it, which a person in more
+ * than one organization needs (0.20.2+; without it the API answers 422 project_id is required).
  */
-export declare function t3PhoneLink(ctx: Ctx, workspaceId: string): Promise<T3PhoneLink>;
+export declare function t3PhoneLink(ctx: Ctx, workspaceId: string, projectId?: string): Promise<T3PhoneLink>;

package/dist/t3-phone.js

@@ -1,8 +1,11 @@
+import { t3NeedsProject } from "./account-scope.js";
 /**
  * Links a workspace for the T3 app on the phone (0.17.0+). An API key links with its creator's sign-in; starting that
- * sign-in takes the person's own session, so the sign-in comes from `shard`'s session when the key has none yet.
+ * sign-in takes the person's own session, so the sign-in comes from `shard`'s session when the key has none yet. That
+ * sign-in is for the workspace's organization: `projectId` (the workspace's project) scopes it, which a person in more
+ * than one organization needs (0.20.2+; without it the API answers 422 project_id is required).
  */
-export async function t3PhoneLink(ctx, workspaceId) {
+export async function t3PhoneLink(ctx, workspaceId, projectId) {
     const link = await ctx.cloud().t3.link(workspaceId);
     if (link.status !== 'needs_sign_in')
         return { link };
@@ -10,6 +13,11 @@ export async function t3PhoneLink(ctx, workspaceId) {
         return { link, signIn: link.sign_in };
     if (ctx.store.profile(ctx.apiUrl).session?.state !== 'active')
         return { link, needsLogin: true };
-    const flow = await ctx.account().t3.signIn();
-    return { link, signIn: flow };
+    try {
+        const flow = await ctx.account().t3.signIn(projectId ? { projectId } : {});
+        return { link, signIn: flow };
+    }
+    catch (error) {
+        throw t3NeedsProject(error) ?? error;
+    }
 }

package/dist/terminal-apps.d.ts

@@ -0,0 +1,157 @@
+import type { Ctx, Io } from './commands.js';
+export declare const TERMINAL_IDS: readonly ["ghostty", "iterm", "terminal", "wezterm", "kitty", "alacritty", "warp"];
+export type TerminalId = typeof TERMINAL_IDS[number];
+export type TerminalMode = 'tab' | 'window';
+export interface TerminalChoice {
+    id: TerminalId;
+    mode: TerminalMode;
+}
+type Env = Record<string, string | undefined>;
+export declare const terminalName: (id: TerminalId) => string;
+/** The terminals this platform can open conversations in (iTerm2 is macOS only). */
+export declare const platformTerminals: (platform?: NodeJS.Platform) => TerminalId[];
+export declare const tabSupported: (id: TerminalId, platform?: NodeJS.Platform) => boolean;
+/** One terminal on this computer: its app bundle (macOS) or program (Linux), whether it runs now and opens tabs. */
+export interface TerminalInfo {
+    id: TerminalId;
+    name: string;
+    installed: boolean;
+    running: boolean;
+    tab_supported: boolean;
+    path: string | null;
+}
+/** Native lookups and launches; tests replace them (no osascript, no terminal ever starts in a test). */
+export declare const terminalNative: {
+    /** A short program's result; `code` is null when it did not start or ran out of time. */
+    run(command: string, args: string[], opts: {
+        env: Env;
+        input?: string;
+        timeoutMs?: number;
+        cwd?: string;
+    }): Promise<{
+        code: number | null;
+        stdout: string;
+        stderr: string;
+    }>;
+    /** Starts a program that outlives shard (a new terminal window): true once it started. */
+    start(command: string, args: string[], opts: {
+        env: Env;
+        cwd?: string;
+    }): Promise<boolean>;
+    /** Running processes: executable paths on macOS, program names on Linux (one `ps`). */
+    processes(env: Env): string[];
+    /** App bundles with these bundle ids anywhere Spotlight knows (macOS), one query. */
+    spotlight(bundles: readonly string[], env: Env): string[];
+    /** CFBundleShortVersionString of an app bundle. */
+    appVersion(path: string): string | null;
+    writeFile(file: string, text: string): void;
+};
+/**
+ * The terminals this platform can use, installed or not. macOS: app bundles in the app folders (applicationDirs, and
+ * the system's Utilities folder) and, with `spotlight`, anywhere Spotlight finds their bundle ids; Terminal.app is part
+ * of macOS. SHARDFLUX_APPLICATIONS_DIRS (tests) replaces every folder and turns Spotlight off. Linux: programs on PATH;
+ * `terminal` is the default terminal ($TERMINAL, x-terminal-emulator, gnome-terminal).
+ */
+export declare function detectTerminals(env: Env, platform?: NodeJS.Platform, opts?: {
+    spotlight?: boolean;
+}): TerminalInfo[];
+/** The terminal a command runs in: TERM_PROGRAM, the terminals' own variables, then the app that started it. */
+export declare function currentTerminal(env: Env): TerminalId | null;
+/** The choice saved with `agents targets --terminal`, or null (auto). */
+export declare function storedTerminal(dir: string): TerminalChoice | null;
+/**
+ * `--terminal <app>[:tab|:window]` checked against this computer: null for `auto` (clears the choice). A terminal that
+ * opens only windows takes `<app>` or `<app>:window`; without a mode, a tab where the app opens tabs.
+ */
+export declare function parseTerminalChoice(spec: string, terminals: readonly TerminalInfo[], platform?: NodeJS.Platform): TerminalChoice | null;
+export declare function saveTerminalChoice(dir: string, choice: TerminalChoice | null): void;
+/** Where a terminal conversation opens now: the saved choice while installed, else the terminal this runs in, else a
+ * running terminal, else Terminal.app (macOS) or the default terminal (Linux). null when the computer has none. */
+export declare function effectiveTerminal(stored: TerminalChoice | null, terminals: readonly TerminalInfo[], env: Env): (TerminalChoice & {
+    saved: boolean;
+}) | null;
+/** The terminal part of `agents targets --json` (0.20.1+). */
+export declare function terminalReport(dir: string, env: Env, terminals: readonly TerminalInfo[]): {
+    terminal_app: TerminalChoice | null;
+    terminal: {
+        name: string;
+        id: TerminalId;
+        mode: TerminalMode;
+        saved: boolean;
+    } | null;
+    current_terminal: "terminal" | "ghostty" | "iterm" | "wezterm" | "kitty" | "alacritty" | "warp" | null;
+    terminals: {
+        id: "terminal" | "ghostty" | "iterm" | "wezterm" | "kitty" | "alacritty" | "warp";
+        name: string;
+        installed: boolean;
+        running: boolean;
+        tab_supported: boolean;
+        path: string | null;
+    }[];
+};
+/** A shell word, quoted only when it needs it (the line shows in the person's terminal). */
+export declare const shellWord: (s: string) => string;
+/** The command as typed: with this computer's config folder when it is not the default (an app's own, a test's). */
+export declare function commandLine(argv: readonly string[], env: Env): string;
+/** What a shell in a new tab types: into the project folder, then the command. */
+export declare const typedLine: (argv: readonly string[], cwd: string, env: Env) => string;
+/** A new window's own command (Linux, Alacritty): it keeps the window open on an error so the person can read it. */
+export declare function windowCommand(argv: readonly string[], cwd: string, env: Env): string[];
+/** An AppleScript string literal. */
+export declare const appleString: (s: string) => string;
+/**
+ * The AppleScript that opens `command` in `cwd` in a new shell of Ghostty, iTerm2 or Terminal.app. A tab goes in the
+ * front window; with no window, or `window`, a new window. An app this script starts uses the window it opens with.
+ */
+export declare function appleScript(id: 'ghostty' | 'iterm' | 'terminal', mode: TerminalMode, command: string, cwd: string): string;
+/** Warp's tab config for one conversation (`warp://tab_config/shardflux`). */
+export declare function warpTabConfig(argv: readonly string[], cwd: string, env: Env): string;
+export declare function warpTabConfigFile(env: Env, platform?: NodeJS.Platform): string;
+/** kitty's remote-control socket: KITTY_LISTEN_ON, else `listen_on` in kitty.conf (kitty adds -<pid> to a unix path). */
+export declare function kittySocket(env: Env, platform?: NodeJS.Platform): string | null;
+export declare function compareVersions(a: string, b: string): number;
+/** `opened`: where it opened (`fallback_from` and `reason` when not in the chosen app); else why nothing opened. */
+export interface TerminalOpen {
+    opened: boolean;
+    app: TerminalId | null;
+    mode: TerminalMode | null;
+    command: string[];
+    fallback_from?: TerminalId;
+    reason?: string;
+}
+/**
+ * Opens `argv` in the person's terminal app, in `cwd`: the chosen app (effectiveTerminal) as a tab, or a window with
+ * `window`; when it fails, the other running terminals, then Terminal.app or the Linux default terminal.
+ */
+export declare function openInTerminal(dir: string, env: Env, argv: readonly string[], opts: {
+    cwd: string;
+    window?: boolean;
+    platform?: NodeJS.Platform;
+}): Promise<TerminalOpen>;
+/** "Opened in Ghostty (new tab)." and, when it fell back, the reason on its own line. */
+export declare function openedText(result: TerminalOpen): {
+    line: string;
+    note?: string;
+};
+/** The runnable command that opens a conversation: this shard (an app's own Node.js and script) when it is not the
+ * `shard` on PATH, with its API. */
+export declare function shardArgv(runtime: {
+    node: string;
+    script: string;
+} | null, apiUrl: string, words: readonly string[], env: Env): string[];
+/** A terminal a person types into: not a pipe, and not a coding agent's shell (a PTY nobody types into, 0.17.1+). */
+export declare const attachable: (io: Pick<Io, "stdin" | "stdout" | "env">) => boolean;
+/**
+ * The local folder a conversation or agent belongs to, where its terminal tab starts: the conversation's record, the
+ * Git agent's repository, else the current folder (the home folder for an app, whose folder is /).
+ */
+export declare function referenceFolder(dir: string, apiUrl: string, ref: string, env: Env): string;
+/** `--json`: `{target: 'terminal', opened, app, mode, command, fallback_from?, reason?}`; text: where it opened, the
+ * reason it fell back on stderr, and with nothing opened the runnable command. */
+export declare function reportTerminalOpen(ctx: Pick<Ctx, 'io' | 'json'>, result: TerminalOpen, extra?: Record<string, unknown>): void;
+/** Opens `shard <words>` (a conversation's attach) in the person's terminal app, in `cwd`. */
+export declare function openShardInTerminal(ctx: Pick<Ctx, 'runtime' | 'apiUrl' | 'io' | 'store'>, words: readonly string[], opts: {
+    cwd: string;
+    window?: boolean;
+}): Promise<TerminalOpen>;
+export {};