@shardflux/cli 0.13.4 → 0.13.6

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.13.6
+
+- `shard` makes the macOS menu bar app's executable runnable when it installs or starts the app, so a menu bar copied
+  from `@shardflux/menubar-darwin` 0.1.1 or 0.1.2 starts (and an existing copy of those is repaired).
+
+## 0.13.5
+
+- `shard update` brings this computer's Shardflux install up to date in one step: it checks shard (the `shardflux`
+  package or `@shardflux/cli`), its SDK, the macOS menu bar app and a globally installed `@shardflux/mcp` against the
+  latest versions, runs one install with the package manager that installed shard (npm in its own prefix, pnpm, bun
+  or Volta), checks the result with the new shard and restarts the menu bar on its new app. `--check` only reports;
+  `--json` for both. A prefix npm cannot write to fails with `update_permission_denied` and the exact command to run.
+- The menu bar's Update button runs `shard update`: each `shard` run on macOS records where it runs
+  (`install.json` in the config directory), and `shard update` records its outcome (`last-update.json`).
+- `shard` replaces a running menu bar app that is older than the one its npm package carries (after
+  `npm i -g shardflux`, the old app used to keep running).
+- The daily update notice and `shard version` say `Update: shard update`.
+- `shard agents list` shows each session's latest message (LAST MESSAGE); `--json` returns it as `last_message`.
+
 ## 0.13.4
 
 - Cloud Claude sign-in and reopening the machine editor preserve existing workspace labels while updating their own labels.
@@ -20,7 +39,7 @@
 - Git history above the first copy's 256 MiB limit fails with `repository_too_large` and its next step in the hint, not `internal_error`.
 - A `revision_mismatch` suggests `--expected-revision` only for the file commands that take it; elsewhere it says to run the same command again.
 - Config sync reports project entries keyed by paths on this computer (Codex `config.projects.*`) as one summary line.
-- The command center does not show a setup step that `.shardflux/setup.yaml` marks `required: false` as the setup failure while the template saves, and reads skipped steps (coding template 9+).
+- The command center does not show a setup step that `.shardflux/setup.yaml` marks `required: false` as the setup failure while the template saves, and reads skipped steps (coding template 10+).
 
 ## 0.13.2
 

package/README.md

@@ -346,12 +346,26 @@ and the session renewals of step-up and password changes).
 - **Never printed:** the session and the saved key appear only in the file. Output shows key ids; error
   output redacts anything shaped like a key or session token. `shard env` prints the key on purpose.
 
+## Update
+
+`shard update` **(0.13.5+)** brings everything Shardflux installed on this computer up to date: shard itself
+(the `shardflux` package or `@shardflux/cli`), its SDK, the macOS menu bar app and a globally installed
+`@shardflux/mcp`. It runs one install of the latest versions with the package manager that installed shard (npm,
+pnpm, bun or Volta) and restarts the menu bar on its new app. The menu bar's **Update** button runs the same command.
+
+```sh
+shard update --check   # what is behind, without installing
+shard update
+```
+
+Projects that depend on `@shardflux/sdk` or the Python `shardflux` package keep the versions their lockfiles pin.
+
 ## Version check
 
 `shard` tells you when a newer version exists, on stderr after the command's output:
 
 ```text
-@shardflux/cli 0.5.0 is outdated: 0.6.0 is available. Update: npm i -g shardflux
+@shardflux/cli 0.13.5 is outdated: 0.14.0 is available. Update: shard update
 ```
 
 or that the API no longer supports it (`... is no longer supported by the Shardflux API (minimum

package/dist/agent-live.d.ts

@@ -8,6 +8,7 @@ interface GuestSession {
     since_unix_ms: number;
     title: string;
     remote_control_url: string;
+    last_message?: string;
 }
 /** Parses `sf-agent list` stdout; anything malformed yields no sessions rather than a wrong row. */
 export declare function guestSessions(stdout: string): GuestSession[];

package/dist/agent-live.js

@@ -61,7 +61,9 @@ export async function withLiveAgents(ctx, agents, filter, now = Date.now()) {
                 return [];
             return guestSessions(result.stdout).map(s => ({
                 id: `${w.id}:${s.session_id}`, workspace_id: w.id, workspace_key: w.workspace_key, app: s.app, state: s.state,
-                since: new Date(s.since_unix_ms).toISOString(), title: s.title, remote_control_url: s.remote_control_url, labels: w.labels,
+                since: new Date(s.since_unix_ms).toISOString(), title: s.title, remote_control_url: s.remote_control_url,
+                // A guest from before the latest message (coding templates before it) lists none.
+                last_message: typeof s.last_message === 'string' ? s.last_message : '', labels: w.labels,
             }));
         }
         catch (error) {

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.13.4";
+export declare const CLI_VERSION = "0.13.6";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.13.4';
+export const CLI_VERSION = '0.13.6';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -161,6 +161,19 @@ const KEY_COMMANDS = [
         options: {},
     },
     { path: ['whoami'], summary: 'Show the principal behind the project API key (SHARDFLUX_API_KEY, else the saved one)', positionals: [], options: {} },
+    {
+        path: ['update'],
+        summary: 'Update shard, the menu bar app and a global MCP server to their latest versions',
+        description: [
+            'Checks every local Shardflux piece against GET /v1/client-versions: shard (the shardflux package or @shardflux/cli),',
+            'its SDK, the macOS menu bar app and a globally installed @shardflux/mcp. When one is behind, runs one install of',
+            'the latest versions with the package manager that installed shard (npm, pnpm, bun or Volta), then restarts the',
+            'menu bar on its new app. --check only reports. Projects that depend on @shardflux/sdk or shardflux (Python) keep',
+            'their own versions.',
+        ].join('\n'),
+        positionals: [],
+        options: { check: { type: 'boolean', description: 'Report what is behind without installing anything.' } },
+    },
     {
         path: ['version'],
         summary: 'Print the CLI and SDK versions and whether a newer shard is available',
@@ -1540,7 +1553,7 @@ export const HELP_SECTIONS = [
     { title: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', 'auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
     { title: 'Workspaces (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'machine', 'template', 'agents', 'ssh-proxy', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
     { title: 'Templates (publish and archive use the session; the rest the API key)', groups: ['templates'] },
-    { title: 'Other', groups: ['menubar', 'feedback', 'version'] },
+    { title: 'Other', groups: ['menubar', 'update', 'feedback', 'version'] },
 ];
 export function topHelp() {
     const w = Math.max(...COMMANDS.map((c) => usageLine(c).length));

package/dist/commands.d.ts

@@ -64,6 +64,10 @@ export interface Ctx {
     input: Input;
     /** The package that runs the CLI (the version check's identity). */
     distribution: Distribution;
+    /** The Node.js binary and script of this process; null when run in-process (tests, embedders). */
+    runtime: import('./update.js').Runtime | null;
+    /** GET /v1/client-versions (unauthenticated): the latest version of every client. */
+    clientVersions(): Promise<unknown>;
     /** This machine's name (default API key name of `shard setup`). */
     hostname(): string;
 }

package/dist/commands.js

@@ -818,7 +818,9 @@ export const KEY_HANDLERS = {
         // A complete listing also shows sessions the projection has not picked up yet (agent-live.ts).
         if (!next && !str(values.cursor))
             rows.splice(0, rows.length, ...await withLiveAgents(ctx, rows, { ...(state ? { state } : {}), labels }));
-        out(ctx, rows.length ? table(['WORKSPACE', 'APP', 'STATE', 'TITLE'], rows.map(a => [a.workspace_key, a.app, a.state, a.title])) : 'No agent sessions.\n', { data: rows, next_cursor: next });
+        // LAST MESSAGE (0.13.4+): the session's latest message, from an API that reports it.
+        const message = (a) => !a.last_message ? '-' : a.last_message.length > 60 ? `${a.last_message.slice(0, 59)}…` : a.last_message;
+        out(ctx, rows.length ? table(['WORKSPACE', 'APP', 'STATE', 'TITLE', 'LAST MESSAGE'], rows.map(a => [a.workspace_key, a.app, a.state, a.title, message(a)])) : 'No agent sessions.\n', { data: rows, next_cursor: next });
         if (!ctx.json && next)
             ctx.io.stderr.write(`more: shard agents list --cursor ${next}\n`);
         return 0;
@@ -2374,9 +2376,9 @@ function updateLine(u, d) {
         case 'current':
             return `up to date${pkg}: latest ${u.latest ?? '-'}${when}\n`;
         case 'outdated':
-            return `update available${pkg}: ${u.latest} (you have ${u.current}). Update: ${u.upgrade_command ?? '-'}\n`;
+            return `update available${pkg}: ${u.latest} (you have ${u.current}). Update: shard update\n`;
         case 'unsupported':
-            return `no longer supported${pkg}: the API needs ${u.minimum_supported} or later (latest ${u.latest ?? '-'}). Update: ${u.upgrade_command ?? '-'}\n`;
+            return `no longer supported${pkg}: the API needs ${u.minimum_supported} or later (latest ${u.latest ?? '-'}). Update: shard update\n`;
         default:
             return `update status unknown${pkg}${when} (the API could not be asked, or has no release of ${u.package} yet)\n`;
     }

package/dist/handlers.js

@@ -11,5 +11,6 @@ import { TARGET_HANDLERS } from "./agent-target-commands.js";
 import { CENTER_HANDLERS } from "./command-center-actions.js";
 import { AGENT_GIT_HANDLERS } from "./agent-git-commands.js";
 import { MENUBAR_HANDLERS } from "./menubar.js";
+import { UPDATE_HANDLERS } from "./update.js";
 import { FILESYSTEM_HANDLERS } from "./filesystem-commands.js";
-export const HANDLERS = { ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS };
+export const HANDLERS = { ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };

package/dist/main.d.ts

@@ -1,4 +1,5 @@
 import type { Io } from './commands.js';
+import type { Runtime } from './update.js';
 import type { Distribution } from './update-check.js';
 /** A sleep that ends early when the signal aborts (so Ctrl-C never waits out a poll interval). */
 export declare function abortableSleep(signal: AbortSignal): (ms: number) => Promise<void>;
@@ -6,6 +7,8 @@ export interface RunOptions {
     signal?: AbortSignal;
     /** The package that runs the CLI, for the version check (default @shardflux/cli at CLI_VERSION). */
     distribution?: Distribution;
+    /** The Node.js binary and script of this `shard` process (main() sets them; `shard update` needs them). */
+    runtime?: Runtime;
 }
 export declare function run(argv: readonly string[], io: Io, opts?: RunOptions): Promise<number>;
 export interface MainOptions {

package/dist/main.js

@@ -17,6 +17,7 @@ import { CLI_VERSION, CENTER_COMMAND, PROJECT_COMMAND, commandHelp, parseCommand
 import { commandCenter } from "./command-center.js";
 import { housekeeping, startupHousekeeping } from "./agent-git-commands.js";
 import { CredentialStore, configDir } from "./credentials.js";
+import { recordInstall } from "./update.js";
 import { AuthConfigError, EXIT, ExecutionPendingError, InterruptedError, UsageError, describeError, exitCodeFor, ownHint, redact } from "./errors.js";
 import { errorText, feedbackCommand, json, time } from "./format.js";
 import { HANDLERS } from "./handlers.js";
@@ -528,6 +529,15 @@ export async function run(argv, io, opts = {}) {
             store,
             input: new Input(io.stdin, io.stderr),
             distribution,
+            runtime: opts.runtime ?? null,
+            async clientVersions() {
+                const res = await base(new URL('/v1/client-versions', `${apiUrl.replace(/\/+$/, '')}/`), {
+                    headers: { accept: 'application/json', 'user-agent': userAgent }, signal: AbortSignal.any([signal, AbortSignal.timeout(10_000)]),
+                });
+                if (!res.ok)
+                    throw new UsageError(`Could not read the latest versions from ${apiUrl} (HTTP ${res.status}).`);
+                return res.json();
+            },
             hostname: () => {
                 try {
                     return hostname();
@@ -616,7 +626,7 @@ export async function run(argv, io, opts = {}) {
             },
         };
         // The update check runs next to the command (not for `version`, which reports it itself).
-        if (!updateCheckDisabled(io.env) && !['version', 'ssh-proxy'].includes(parsed.command.path[0])) {
+        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy'].includes(parsed.command.path[0])) {
             try {
                 updates = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent });
                 updates.start();
@@ -684,7 +694,11 @@ export async function main(opts = {}) {
         controller.abort(new Error('interrupted'));
     });
     const flush = (stream) => new Promise((resolve) => stream.write('', () => resolve()));
-    const code = await run(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin, env: process.env }, { signal: controller.signal, ...(opts.distribution ? { distribution: opts.distribution } : {}) });
+    const runtime = { node: process.execPath, script: process.argv[1] ?? '' };
+    // The menu bar's update button runs this shard; it finds it here (macOS only, written when it changes).
+    if (process.platform === 'darwin' && runtime.script)
+        recordInstall(configDir(process.env), runtime, opts.distribution ?? CLI_DISTRIBUTION);
+    const code = await run(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin, env: process.env }, { signal: controller.signal, runtime, ...(opts.distribution ? { distribution: opts.distribution } : {}) });
     await Promise.all([flush(process.stdout), flush(process.stderr)]);
     process.exit(code);
 }

package/dist/menubar.d.ts

@@ -10,6 +10,11 @@ export interface MenubarStatus {
 type NativeStatus = Omit<MenubarStatus, 'installed' | 'version'>;
 export declare function compareBundleVersions(left: string, right: string): number;
 export declare function parseNativeStatus(text: string): NativeStatus;
+/**
+ * The app's executables keep their execute permission (0.13.6+). @shardflux/menubar-darwin 0.1.1 and 0.1.2 reached npm
+ * without it (pnpm's packer drops it), so an app copied from them could not run; this also repairs such an install.
+ */
+export declare function makeExecutable(app: string): void;
 /** Native tools use argument arrays, bounded deadlines, and the installed app's own process/login projection. */
 export declare class MenubarManager {
     #private;
@@ -21,6 +26,9 @@ export declare class MenubarManager {
         packageApp?: () => string;
         signal?: AbortSignal;
     });
+    get platform(): NodeJS.Platform;
+    /** The version of the app this CLI's npm package carries (what `start` installs). */
+    packagedVersion(): Promise<string>;
     status(): Promise<MenubarStatus>;
     stop(): Promise<MenubarStatus>;
     login(value: 'on' | 'off'): Promise<MenubarStatus>;

package/dist/menubar.js

@@ -1,5 +1,5 @@
 import { execFile } from 'node:child_process';
-import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, renameSync, rmSync } from 'node:fs';
+import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
@@ -30,6 +30,25 @@ export function parseNativeStatus(text) {
     }
     return row;
 }
+/**
+ * The app's executables keep their execute permission (0.13.6+). @shardflux/menubar-darwin 0.1.1 and 0.1.2 reached npm
+ * without it (pnpm's packer drops it), so an app copied from them could not run; this also repairs such an install.
+ */
+export function makeExecutable(app) {
+    const dir = join(app, 'Contents', 'MacOS');
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        const file = join(dir, name), stat = lstatSync(file);
+        if (stat.isFile() && (stat.mode & 0o111) !== 0o111)
+            chmodSync(file, 0o755);
+    }
+}
 /** Native tools use argument arrays, bounded deadlines, and the installed app's own process/login projection. */
 export class MenubarManager {
     app;
@@ -49,8 +68,11 @@ export class MenubarManager {
             }
         });
     }
+    get platform() { return this.#platform; }
     #requireMac() { if (this.#platform !== 'darwin')
         throw new UsageError('shard menubar requires macOS 14 or later.'); }
+    /** The version of the app this CLI's npm package carries (what `start` installs). */
+    async packagedVersion() { this.#requireMac(); return this.#version(this.#packageApp()); }
     async #version(app) {
         const file = join(app, 'Contents', 'Info.plist');
         const id = (await this.#run('/usr/bin/plutil', ['-extract', 'CFBundleIdentifier', 'raw', '-o', '-', file])).trim();
@@ -61,6 +83,7 @@ export class MenubarManager {
         return version;
     }
     async #control(action, ...args) {
+        makeExecutable(this.app);
         return parseNativeStatus(await this.#run(join(this.app, 'Contents', 'MacOS', 'ShardfluxMenuBar'), ['--control', action, ...args]));
     }
     async status() {
@@ -111,6 +134,7 @@ export class MenubarManager {
                     await this.stop();
                 if (current.installed)
                     renameSync(this.app, backup);
+                makeExecutable(staged);
                 try {
                     renameSync(staged, this.app);
                     committed = true;
@@ -158,7 +182,8 @@ export async function ensureMenubar(dir, apiUrl, manager = new MenubarManager(),
         return undefined;
     try {
         const status = await manager.status();
-        if (status.running)
+        // A running app stays unless this CLI carries a newer one (after `npm i -g shardflux`): then it is replaced.
+        if (status.running && !(status.version && compareBundleVersions(status.version, await manager.packagedVersion()) < 0))
             return undefined;
         const started = await manager.start(dir, apiUrl);
         if (!started.running)

package/dist/update-check.d.ts

@@ -59,6 +59,7 @@ export declare class UpdateCheck {
         checkedAt: string | null;
     } | null>;
 }
-/** The one-line notice for stderr, or null when there is nothing to say. */
+/** The one-line notice for stderr, or null when there is nothing to say. It names `shard update` (0.13.5+), which
+ *  updates with the package manager that installed shard, rather than the catalog's npm command. */
 export declare function noticeOf(s: ClientVersionStatus | undefined | null): string | null;
 export {};

package/dist/update-check.js

@@ -120,9 +120,10 @@ export class UpdateCheck {
         }
     }
 }
-/** The one-line notice for stderr, or null when there is nothing to say. */
+/** The one-line notice for stderr, or null when there is nothing to say. It names `shard update` (0.13.5+), which
+ *  updates with the package manager that installed shard, rather than the catalog's npm command. */
 export function noticeOf(s) {
     if (!s || (s.status !== 'outdated' && s.status !== 'unsupported') || !s.message)
         return null;
-    return `${s.message}\n`;
+    return `${s.message.replace(/ Update: .*$/, ' Update: shard update')}\n`;
 }

package/dist/update.d.ts

@@ -0,0 +1,61 @@
+import type { ClientVersionStatusKind } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
+import { MenubarManager } from './menubar.js';
+export declare const INSTALL_FILE = "install.json";
+export declare const LAST_UPDATE_FILE = "last-update.json";
+/** How this `shard` process runs: the Node.js binary and the script it was started with. */
+export interface Runtime {
+    node: string;
+    script: string;
+}
+export type Manager = 'npm' | 'pnpm' | 'bun' | 'volta' | 'npx' | 'unmanaged';
+export interface Install {
+    manager: Manager;
+    /** The installed package directory of the distribution, when found. */
+    packageDir: string | null;
+    /** The node_modules directory that holds it (the global root for a global install). */
+    root: string | null;
+    /** npm's global prefix (`<prefix>/lib/node_modules` is the root). */
+    prefix: string | null;
+}
+export interface Component {
+    package: string;
+    label: string;
+    current: string;
+    latest: string | null;
+    status: ClientVersionStatusKind;
+}
+/** Finds the package directory of `pkg` above `script` and how it was installed. */
+export declare function detectInstall(script: string, pkg: string, platform?: NodeJS.Platform): Install;
+/** The packages one install updates: the distribution, plus `@shardflux/mcp` when it is installed next to it. */
+export declare function installSpecs(install: Install, pkg: string): string[];
+/** The install command as argv (npm keeps the prefix it was installed in), or null when shard cannot run it. */
+export declare function installArgv(install: Install, specs: string[], npm?: string): string[] | null;
+/** The command a person types for the same update. */
+export declare function displayCommand(install: Install, specs: string[]): string;
+/** Every local piece and its status against the catalog. */
+export declare function components(ctx: Ctx, install: Install, catalog: unknown, menubar?: MenubarManager): Promise<Component[]>;
+/** One line per change: `shard 0.13.4 → 0.13.5 · menu bar 0.1.1 → 0.1.2`. */
+export declare function changesText(list: {
+    label: string;
+    from: string;
+    to: string | null;
+}[]): string;
+export interface Exec {
+    code: number;
+    output: string;
+}
+export type Runner = (argv: string[], env: Record<string, string | undefined>, signal: AbortSignal) => Promise<Exec>;
+/** Runs argv without a shell, keeping the last 64 KiB of output; never throws for a non-zero exit. */
+export declare const runProcess: Runner;
+export interface UpdateDeps {
+    run?: Runner;
+    menubar?: MenubarManager;
+}
+export declare function update(ctx: Ctx, values: Record<string, unknown>, deps?: UpdateDeps): Promise<number>;
+/** Records where `shard` runs, for the menu bar's update button. Written on macOS, only when it changed. */
+export declare function recordInstall(dir: string, runtime: Runtime, distribution: {
+    package: string;
+    version: string;
+}): void;
+export declare const UPDATE_HANDLERS: Record<string, Handler>;

package/dist/update.js

@@ -0,0 +1,298 @@
+/**
+ * `shard update` (0.13.5+): brings this computer's Shardflux install up to date in one step. It checks every local
+ * piece against GET /v1/client-versions — the package that runs `shard` (the `shardflux` bundle or `@shardflux/cli`),
+ * the CLI and SDK inside it, the macOS menu bar app and a globally installed `@shardflux/mcp` — then runs one install
+ * of the latest versions with the package manager that installed `shard`, checks the result with the new `shard`,
+ * and restarts the menu bar on its new app. `--check` only reports.
+ *
+ * The menu bar app runs the same command: it finds `shard` through install.json (written by each `shard` run on
+ * macOS) and shows the outcome from last-update.json, also when the update replaced the app that started it.
+ */
+import { spawn } from 'node:child_process';
+import { closeSync, existsSync, openSync, readFileSync, realpathSync, rmSync, writeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, sep } from 'node:path';
+import { clientVersionStatus, SDK_VERSION } from '@shardflux/sdk';
+import { CLI_VERSION } from "./args.js";
+import { AgentStateStore } from "./agent-state.js";
+import { writePrivateFile } from "./credentials.js";
+import { CodedError } from "./errors.js";
+import { json } from "./format.js";
+import { compareBundleVersions, MenubarManager } from "./menubar.js";
+export const INSTALL_FILE = 'install.json';
+export const LAST_UPDATE_FILE = 'last-update.json';
+const LOCK_FILE = 'update.lock';
+const MCP = '@shardflux/mcp';
+const MENUBAR = '@shardflux/menubar-darwin';
+/** Finds the package directory of `pkg` above `script` and how it was installed. */
+export function detectInstall(script, pkg, platform = process.platform) {
+    let real = script;
+    try {
+        real = realpathSync(script);
+    }
+    catch { /* a missing script keeps its path */ }
+    let packageDir = null;
+    for (let dir = dirname(real); dir !== dirname(dir); dir = dirname(dir)) {
+        try {
+            if (JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).name === pkg) {
+                packageDir = dir;
+                break;
+            }
+        }
+        catch { /* no package.json here */ }
+    }
+    const none = { manager: 'unmanaged', packageDir, root: null, prefix: null };
+    if (!packageDir)
+        return none;
+    const root = pkg.startsWith('@') ? dirname(dirname(packageDir)) : dirname(packageDir);
+    if (basename(root) !== 'node_modules')
+        return none;
+    const has = (part) => root.split(sep).join('/').includes(part);
+    if (has('/_npx/'))
+        return { manager: 'npx', packageDir, root, prefix: null };
+    if (has('/.volta/'))
+        return { manager: 'volta', packageDir, root, prefix: null };
+    if (has('/.bun/install/global/'))
+        return { manager: 'bun', packageDir, root, prefix: null };
+    if (has('/pnpm/global/') || has('/.pnpm/'))
+        return { manager: 'pnpm', packageDir, root, prefix: null };
+    if (basename(dirname(root)) === 'lib')
+        return { manager: 'npm', packageDir, root, prefix: dirname(dirname(root)) };
+    if (platform === 'win32' && basename(dirname(root)) === 'npm')
+        return { manager: 'npm', packageDir, root, prefix: dirname(root) };
+    return none;
+}
+function versionAt(dir) {
+    try {
+        const v = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version;
+        return typeof v === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The packages one install updates: the distribution, plus `@shardflux/mcp` when it is installed next to it. */
+export function installSpecs(install, pkg) {
+    const specs = [`${pkg}@latest`];
+    if (install.root && versionAt(join(install.root, MCP)))
+        specs.push(`${MCP}@latest`);
+    return specs;
+}
+/** The install command as argv (npm keeps the prefix it was installed in), or null when shard cannot run it. */
+export function installArgv(install, specs, npm = 'npm') {
+    switch (install.manager) {
+        case 'npm': return [npm, 'install', '--global', ...(install.prefix ? ['--prefix', install.prefix] : []), ...specs, '--no-fund', '--no-audit'];
+        case 'pnpm': return ['pnpm', 'add', '--global', ...specs];
+        case 'bun': return ['bun', 'add', '--global', ...specs];
+        case 'volta': return ['volta', 'install', ...specs];
+        default: return null;
+    }
+}
+/** The command a person types for the same update. */
+export function displayCommand(install, specs) {
+    switch (install.manager) {
+        case 'pnpm': return `pnpm add -g ${specs.join(' ')}`;
+        case 'bun': return `bun add -g ${specs.join(' ')}`;
+        case 'volta': return `volta install ${specs.join(' ')}`;
+        case 'npx': return `npx ${specs[0]}`;
+        default: return `npm install -g ${specs.join(' ')}`;
+    }
+}
+const LABELS = { shardflux: 'shardflux', '@shardflux/cli': 'shard', '@shardflux/sdk': 'SDK', [MENUBAR]: 'menu bar', [MCP]: 'MCP server' };
+/** Every local piece and its status against the catalog. */
+export async function components(ctx, install, catalog, menubar = menubarManager(ctx)) {
+    const local = [[ctx.distribution.package, ctx.distribution.version]];
+    if (ctx.distribution.package !== '@shardflux/cli')
+        local.push(['@shardflux/cli', CLI_VERSION]);
+    local.push(['@shardflux/sdk', SDK_VERSION]);
+    if (menubar.platform === 'darwin') {
+        const status = await menubar.status().catch(() => null);
+        if (status?.installed && status.version)
+            local.push([MENUBAR, status.version]);
+    }
+    if (install.root)
+        local.push([MCP, versionAt(join(install.root, MCP))]);
+    return local.filter((entry) => entry[1] !== null).map(([pkg, version]) => {
+        const s = clientVersionStatus(catalog, { package: pkg, version });
+        return { package: pkg, label: LABELS[pkg] ?? pkg, current: version, latest: s.latest, status: s.status };
+    });
+}
+const outdated = (c) => c.status === 'outdated' || c.status === 'unsupported';
+function menubarManager(ctx) {
+    return new MenubarManager({ home: ctx.io.env.HOME || homedir(), signal: ctx.signal });
+}
+/** One line per change: `shard 0.13.4 → 0.13.5 · menu bar 0.1.1 → 0.1.2`. */
+export function changesText(list) {
+    return list.map(c => `${c.label} ${c.from} → ${c.to ?? '?'}`).join(' · ');
+}
+/** Runs argv without a shell, keeping the last 64 KiB of output; never throws for a non-zero exit. */
+export const runProcess = (argv, env, signal) => new Promise((resolve, reject) => {
+    const child = spawn(argv[0], argv.slice(1), { env: env, stdio: ['ignore', 'pipe', 'pipe'], signal });
+    let output = '';
+    const keep = (chunk) => { output = (output + chunk.toString('utf8')).slice(-65536); };
+    child.stdout.on('data', keep);
+    child.stderr.on('data', keep);
+    child.on('error', reject);
+    child.on('close', code => resolve({ code: code ?? 1, output }));
+});
+function writeLastUpdate(dir, doc) {
+    try {
+        writePrivateFile(dir, join(dir, LAST_UPDATE_FILE), `${JSON.stringify({ version: 1, finished_at: new Date().toISOString(), ...doc }, null, 2)}\n`);
+    }
+    catch { /* the outcome is also printed; the menu bar then shows no result */ }
+}
+/** One update at a time per config directory; a lock left by a process that is gone is taken over. */
+function lock(dir) {
+    const file = join(dir, LOCK_FILE);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(file, 'wx', 0o600);
+            writeSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => rmSync(file, { force: true });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const pid = Number(readFileSync(file, 'utf8'));
+            let alive = false;
+            try {
+                if (Number.isInteger(pid) && pid > 0) {
+                    process.kill(pid, 0);
+                    alive = true;
+                }
+            }
+            catch { /* gone */ }
+            if (alive)
+                throw new CodedError('update_in_progress', 'A Shardflux update is already running.', 'wait for it to finish, then run shard update --check');
+            rmSync(file, { force: true });
+        }
+    }
+    throw new CodedError('update_in_progress', 'A Shardflux update is already running.', 'wait for it to finish, then run shard update --check');
+}
+/** npm next to the running Node.js (the same installation), else npm on PATH. */
+function npmFor(node) {
+    const sibling = join(dirname(node), process.platform === 'win32' ? 'npm.cmd' : 'npm');
+    return existsSync(sibling) ? sibling : 'npm';
+}
+export async function update(ctx, values, deps = {}) {
+    const run = deps.run ?? runProcess;
+    const menubar = deps.menubar ?? menubarManager(ctx);
+    const runtime = ctx.runtime;
+    const install = runtime ? detectInstall(runtime.script, ctx.distribution.package) : { manager: 'unmanaged', packageDir: null, root: null, prefix: null };
+    const catalog = await ctx.clientVersions();
+    const list = await components(ctx, install, catalog, menubar);
+    const specs = installSpecs(install, ctx.distribution.package);
+    const command = displayCommand(install, specs);
+    const pending = list.filter(outdated);
+    const view = { update_available: pending.length > 0, components: list, install: { manager: install.manager, command } };
+    const versions = list.map(c => `${c.label} ${c.current}`).join(' · ');
+    if (values.check === true) {
+        ctx.io.stdout.write(ctx.json ? json(view) : pending.length
+            ? `Update available: ${changesText(pending.map(c => ({ label: c.label, from: c.current, to: c.latest })))}\nRun: shard update\n`
+            : `Shardflux is up to date (${versions}).\n`);
+        return 0;
+    }
+    if (!pending.length) {
+        // The npm package may already carry a newer menu bar app than the one running.
+        const refreshed = await refreshMenubar(ctx, menubar);
+        ctx.io.stdout.write(ctx.json ? json({ ...view, updated: false, menubar: refreshed }) : `Shardflux is up to date (${versions}).\n`);
+        return 0;
+    }
+    const argv = installArgv(install, specs, runtime ? npmFor(runtime.node) : 'npm');
+    if (!argv || !runtime) {
+        const where = install.packageDir ?? runtime?.script ?? 'this process';
+        const message = install.manager === 'npx'
+            ? 'npx runs the latest version the next time you start it.'
+            : `shard update does not manage the install at ${where}.`;
+        writeLastUpdate(ctx.store.dir, { status: 'failed', changes: [], message, command });
+        throw new CodedError('update_unmanaged', message, `run: ${command}`);
+    }
+    const unlock = lock(ctx.store.dir);
+    try {
+        if (!ctx.json)
+            ctx.io.stderr.write(`Updating ${changesText(pending.map(c => ({ label: c.label, from: c.current, to: c.latest })))} with ${install.manager}…\n`);
+        const env = { ...process.env, ...ctx.io.env, PATH: [dirname(runtime.node), ctx.io.env.PATH ?? process.env.PATH ?? ''].join(process.platform === 'win32' ? ';' : ':') };
+        const result = await run(argv, env, ctx.signal);
+        if (result.code !== 0) {
+            const denied = /\bEACCES\b|\bEPERM\b/.test(result.output);
+            const fix = denied ? `sudo ${command}` : command;
+            const message = denied
+                ? `${install.manager} cannot write to ${install.prefix ?? install.root}.`
+                : `${install.manager} failed: ${result.output.trim().split('\n').slice(-3).join(' ').slice(0, 400)}`;
+            writeLastUpdate(ctx.store.dir, { status: 'failed', changes: [], message, command: fix });
+            throw new CodedError(denied ? 'update_permission_denied' : 'update_failed', message, `run: ${fix}`);
+        }
+        // The new shard reports what is installed now.
+        const after = await run([runtime.node, runtime.script, 'version', '--json'], { ...env, SHARDFLUX_NO_UPDATE_CHECK: '1' }, ctx.signal);
+        let now = {};
+        try {
+            now = JSON.parse(after.output.slice(after.output.indexOf('{')));
+        }
+        catch { /* reported as unknown below */ }
+        const installed = {
+            [ctx.distribution.package]: install.packageDir ? versionAt(install.packageDir) : null,
+            '@shardflux/cli': now.cli ?? null, '@shardflux/sdk': now.sdk ?? null,
+            [MCP]: install.root ? versionAt(join(install.root, MCP)) : null,
+        };
+        const restart = await refreshMenubar(ctx, menubar, runtime, run, env);
+        if (restart.version)
+            installed[MENUBAR] = restart.version;
+        const changes = list.filter(c => (installed[c.package] ?? c.current) !== c.current)
+            .map(c => ({ package: c.package, label: c.label, from: c.current, to: installed[c.package] ?? null }));
+        const message = changes.length ? `Updated ${changesText(changes)}` : 'Shardflux is up to date';
+        writeLastUpdate(ctx.store.dir, { status: 'ok', changes, message, command });
+        ctx.io.stdout.write(ctx.json ? json({ ...view, updated: true, changes, menubar: restart.status }) : `${message}.\n`);
+        return 0;
+    }
+    finally {
+        unlock();
+    }
+}
+/**
+ * Restarts the menu bar on the app its npm package carries now, when that is newer than the installed one and the
+ * person has not turned the menu bar off. With `runtime`, the freshly installed shard does it (this process still
+ * runs the code from before the update).
+ */
+async function refreshMenubar(ctx, menubar, runtime, run, env) {
+    if (menubar.platform !== 'darwin')
+        return { status: 'off' };
+    if (new AgentStateStore(ctx.store.dir).read().menubar_stopped === true)
+        return { status: 'off' };
+    const before = await menubar.status().catch(() => null);
+    if (!before?.installed)
+        return { status: 'off' };
+    if (runtime && run && env) {
+        const r = await run([runtime.node, runtime.script, '--api-url', ctx.apiUrl, 'menubar', 'start', '--json'], { ...env, SHARDFLUX_NO_UPDATE_CHECK: '1', SHARDFLUX_CONFIG_DIR: ctx.store.dir }, ctx.signal);
+        if (r.code !== 0)
+            return { status: 'failed' };
+    }
+    else {
+        const packaged = await menubar.packagedVersion().catch(() => null);
+        if (!packaged || !before.version || compareBundleVersions(before.version, packaged) >= 0)
+            return { status: 'current' };
+        await menubar.start(ctx.store.dir, ctx.apiUrl);
+    }
+    const after = await menubar.status().catch(() => null);
+    return after?.version && after.version !== before.version ? { status: 'restarted', version: after.version } : { status: 'current' };
+}
+/** Records where `shard` runs, for the menu bar's update button. Written on macOS, only when it changed. */
+export function recordInstall(dir, runtime, distribution) {
+    let script = runtime.script;
+    try {
+        script = realpathSync(script);
+    }
+    catch { /* keep the path */ }
+    const doc = { version: 1, node: runtime.node, script, package: distribution.package, package_version: distribution.version, cli_version: CLI_VERSION };
+    const text = `${JSON.stringify(doc, null, 2)}\n`;
+    try {
+        if (readFileSync(join(dir, INSTALL_FILE), 'utf8') === text)
+            return;
+    }
+    catch { /* first run */ }
+    try {
+        writePrivateFile(dir, join(dir, INSTALL_FILE), text);
+    }
+    catch { /* the menu bar then offers the terminal instead */ }
+}
+export const UPDATE_HANDLERS = { update: (ctx, values) => update(ctx, values) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.13.4",
+  "version": "0.13.6",
   "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.18.2"
+    "@shardflux/sdk": "^0.18.3"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -58,7 +58,7 @@
     "typescript-eslint": "8.70.1"
   },
   "optionalDependencies": {
-    "@shardflux/menubar-darwin": "^0.1.1"
+    "@shardflux/menubar-darwin": "^0.1.3"
   },
   "scripts": {
     "build": "node scripts/build.mjs",