sideby 0.6.0 → 0.8.0

package/README.md

@@ -76,7 +76,8 @@ The agent checks Node and your Host CLIs, installs sideby and the skill, creates
 | Let a running task move to the next account by itself when quota runs low (off by default; see the risk) | `sideby handoff enable` (or the panel) | [Auto Handoff](docs/guide/usage.md#auto-handoff) |
 | Short commands such as `ccw` | `sideby alias add ccw claude:work` | [Shell functions](docs/guide/configuration.md#shell-functions) |
 | Reopen a session from Orca and the like in the account that holds it | `"resumeRouting": true` in config | [Resuming from other tools](docs/guide/configuration.md#resuming-from-other-tools) |
-| Open the panel from the Dock or app menu | `sideby app install` | [Desktop app](docs/guide/panel.md#desktop-app) |
+| Open Claude Desktop or the Codex app as one account, several side by side (macOS) | `sideby desktop claude:work` (or the panel) | [Desktop apps](docs/guide/usage.md#desktop-apps) |
+| Open the panel from the Dock or app menu | `sideby app install` | [Panel app](docs/guide/panel.md#panel-app) |
 | Show the panel inside your own local page | `createPanelHandler()` | [Embed the panel](docs/guide/panel.md#embed-the-panel) |
 | Add a Host or a pre-launch check | a local plugin | [Plugins](docs/guide/plugins.md) |
 
@@ -114,7 +115,7 @@ Usage questions and ideas go in [Discussions](https://github.com/Adonis0123/side
 - [Using sideby](docs/guide/usage.md): accounts, API accounts, Doctor, quota, Handoff, Host notes
 - [Commands](docs/guide/commands.md): every command, exit codes and `--json`
 - [Configuration](docs/guide/configuration.md): `config.json`, aliases, shell functions
-- [Panel](docs/guide/panel.md): the panel, desktop app and embedding
+- [Panel](docs/guide/panel.md): the panel, panel app and embedding
 - [Plugins](docs/guide/plugins.md): write your own Family or launch hook
 - [FAQ](docs/guide/faq.md): terms of service, data locations, alternatives, uninstall
 - [Changelog](https://github.com/Adonis0123/sideby/releases)

package/dist/build.json

@@ -1 +1 @@
-{"id":"20261014T070544-66900c"}
+{"id":"20261014T102906-2ab079"}

package/dist/src/cli/commands.d.ts

@@ -57,6 +57,8 @@ export declare function cmdPlugins(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdShellInit(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdUi(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdApp(a: ParsedArgs, io: Io): Promise<number>;
+/** `sideby desktop <account>`: the Family's Desktop App as that Account (spec §3.20). */
+export declare function cmdDesktop(a: ParsedArgs, io: Io): Promise<number>;
 export declare function cmdAlias(a: ParsedArgs, io: Io): Promise<number>;
 /** `sideby families [family]`: each Family's layout, sign-in and Shared Items, from its FamilyDef (spec §3.16). */
 export declare function cmdFamilies(a: ParsedArgs, io: Io): Promise<number>;

package/dist/src/cli/commands.js

@@ -1,6 +1,7 @@
 import { fileURLToPath } from 'node:url';
 import { aliasesByAccount } from '../core/accounts.js';
 import { aliasRefs } from '../core/config.js';
+import { openDesktopApp, withDesktopApps } from '../core/desktop-app.js';
 import { UserError } from '../core/errors.js';
 import { requestHandoff } from '../core/handoff-chain.js';
 import { explain, readyDecision, runWithHandoff } from '../core/handoff-run.js';
@@ -53,7 +54,8 @@ function tilde(text, home) {
 export async function cmdList(a, io) {
     const rt = await createRuntime();
     const accounts = await rt.accounts();
-    const statuses = await Promise.all(accounts.map((x) => rt.status(x)));
+    const statuses = await withDesktopApps(rt, accounts, Promise.all(accounts.map((x) => rt.status(x))));
+    const hasDesktop = statuses.some((s) => s.desktopApp);
     const families = await rt.familyInfo();
     if (a.flags.has('json')) {
         json(io, { families, accounts: statuses, pluginErrors: [...rt.pluginErrors] });
@@ -69,8 +71,10 @@ export async function cmdList(a, io) {
             io.out(`Run ${installed.map((f) => f.bin).join(' or ')} once, then \`sideby new <family> <name>\`.`);
     }
     else {
+        // `= main`: the other Accounts of its Same Login, which share its Quota (spec §3.21).
+        const sameMark = (refs) => refs?.length ? ` ${c.dim(`= ${refs.map((r) => r.slice(r.indexOf(':') + 1)).join(', ')}`)}` : '';
         const rows = statuses.map((s) => [
-            c.bold(s.ref),
+            `${c.bold(s.ref)}${sameMark(s.sameLogin)}`,
             s.isMain ? 'main' : s.kind === 'api' ? c.cyan('api') : 'sub',
             s.login === 'logged-in'
                 ? c.green('✓')
@@ -82,8 +86,11 @@ export async function cmdList(a, io) {
             s.identity?.email ?? c.dim('—'),
             s.model ?? c.dim('—'),
             s.hostInstalled ? tildify(s.dir, home) : `${tildify(s.dir, home)} ${c.yellow('(host not installed)')}`,
+            ...(hasDesktop ? [s.desktopApp?.running ? c.green('open') : c.dim('—')] : []),
         ]);
-        io.out(table(rows, ['ACCOUNT', 'TYPE', 'LOGIN', 'EMAIL', 'MODEL', 'DIR']));
+        io.out(table(rows, ['ACCOUNT', 'TYPE', 'LOGIN', 'EMAIL', 'MODEL', 'DIR', ...(hasDesktop ? ['DESKTOP'] : [])]));
+        if (statuses.some((s) => s.sameLogin?.length))
+            io.out(c.dim('\n= <account>: signed in as the same login as that account, so they share one quota.'));
         io.out(c.dim('\nsideby run <account>  ·  sideby new <family> <name>  ·  sideby quota  ·  sideby ui'));
     }
     for (const s of statuses)
@@ -213,6 +220,8 @@ export async function cmdNext(a, io) {
     }
     const now = rt.readContext().now;
     const note = (e) => {
+        if (e.sameLoginAs)
+            return `same login as ${e.sameLoginAs}, which shares its quota; skipped`;
         if (e.state === 'ready')
             return `fullest window ${Math.round(e.pressure ?? 0)}%`;
         if (e.state === 'unknown')
@@ -236,11 +245,13 @@ export async function cmdNext(a, io) {
         const why = plan.earliestReset
             ? `every ${family} account is at its limit; ${plan.earliestReset.ref} is back at ${clock(plan.earliestReset.at, now)}`
             : `no ${family} account can be used now`;
+        const same = plan.accounts.filter((e) => e.sameLoginAs).map((e) => e.ref);
+        const sameNote = same.length ? `; ${same.join(', ')} share the quota of ${plan.from}` : '';
         const next = [
             ...(out.length ? [`sign in with \`${out.join('` or `')}\``] : []),
             ...(apiLeft ? ['add --include-api to use an API account'] : []),
         ];
-        io.err(c.yellow(`\n${why}${next.length ? `; ${next.join(', or ')}` : ''}.`));
+        io.err(c.yellow(`\n${why}${sameNote}${next.length ? `; ${next.join(', or ')}` : ''}.`));
         return 1;
     }
     const picked = plan.accounts.find((e) => e.ref === plan.pick);
@@ -527,7 +538,11 @@ export async function cmdQuota(a, io) {
         return 0;
     }
     const now = new Date();
-    io.out(table(rows.map((r) => [c.bold(r.ref), quotaText(r.quota, now), usageText(r.usage)]), ['ACCOUNT', 'QUOTA', `USAGE (${USAGE_DAYS}d)`]));
+    io.out(table(rows.map((r) => [
+        c.bold(r.ref),
+        `${quotaText(r.quota, now)}${r.quota.status === 'ok' && r.quota.from ? c.dim(` read from ${r.quota.from} (same login)`) : ''}`,
+        usageText(r.usage),
+    ]), ['ACCOUNT', 'QUOTA', `USAGE (${USAGE_DAYS}d)`]));
     for (const r of rows)
         if (r.quota.status === 'unavailable' && r.quota.detail)
             io.out(c.dim(`${r.ref}: ${r.quota.detail}`));
@@ -897,6 +912,30 @@ export async function cmdApp(a, io) {
     }
     return r.skipped.length ? 1 : 0;
 }
+/** `sideby desktop <account>`: the Family's Desktop App as that Account (spec §3.20). */
+export async function cmdDesktop(a, io) {
+    const [ref, ...extra] = a.positionals;
+    if (!ref || extra.length || a.rest.length)
+        throw new UsageError('usage: sideby desktop <account>');
+    const rt = await createRuntime();
+    const r = await openDesktopApp(rt, ref);
+    if (a.flags.has('json')) {
+        json(io, r);
+        return 0;
+    }
+    const home = rt.paths.home;
+    if (r.action === 'started')
+        io.out(`${c.green('✓')} opened ${r.app} as ${c.bold(r.ref)}`);
+    else if (r.action === 'focused')
+        io.out(`${c.green('✓')} ${r.app} is already open as ${c.bold(r.ref)}; brought it to the front`);
+    if (r.appData)
+        io.out(c.dim(`  its data: ${tildify(r.appData, home)}`));
+    for (const f of r.linked)
+        io.out(c.dim(`  linked ${f} to the main account's`));
+    for (const n of r.notices)
+        io.err(c.cyan(n));
+    return 0;
+}
 export async function cmdAlias(a, io) {
     const [sub, alias, target, ...more] = a.positionals;
     const usage = 'usage: sideby alias add <short-command> <account> [-- host args]  |  sideby alias rm <short-command>';

package/dist/src/cli/json-schemas.js

@@ -36,7 +36,13 @@ const AccountStatus = Type.Intersect([
         identity: Type.Optional(Type.Object({ email: Type.Optional(Str), org: Type.Optional(Str) }, {
             description: "Who the account is signed in as, from the host's login file: identity fields only, never a token (ADR-0003).",
         })),
+        sameLogin: Type.Optional(Type.Array(Str, {
+            description: 'The other accounts signed in as the same login (same family, email and organization), which share one quota (spec §3.21). Absent when there are none.',
+        })),
         problems: Type.Optional(Type.Array(Str)),
+        desktopApp: Type.Optional(Type.Object({ app: Str, installed: Type.Boolean(), running: Type.Boolean() }, {
+            description: "The family's desktop app for this account (macOS, subscription accounts of claude and codex): whether it is installed and whether this account's own window runs now. Open it with `sideby desktop <account>`.",
+        })),
     }),
 ]);
 const FamilyInfo = Type.Object({
@@ -103,6 +109,9 @@ const Quota = Type.Union([
         observedAt: Str,
         source: Str,
         plan: Type.Optional(Str),
+        from: Type.Optional(Type.String({
+            description: 'The account this reading was taken from, when it is another account of the same login (spec §3.21); observedAt is its time.',
+        })),
     }),
     Type.Object({ status: Type.Literal('unavailable'), reason: Str, detail: Type.Optional(Str) }),
 ]);
@@ -260,6 +269,9 @@ export const OUTPUT_SCHEMAS = {
     next: Type.Object({
         schemaVersion: Version,
         family: Str,
+        from: Type.Optional(Type.String({
+            description: 'The account `sideby next` runs in (SIDEBY_ACCOUNT, set by sideby for the sessions it starts), when it belongs to this family.',
+        })),
         pick: Type.Union([Str, Type.Null()], {
             description: 'The recommended account; null when none can be used now (exit code 1).',
         }),
@@ -280,6 +292,12 @@ export const OUTPUT_SCHEMAS = {
             }),
             resetsAt: Type.Optional(Type.String({ description: 'For full: when its last full window resets.' })),
             observedAt: Type.Optional(Type.String({ description: "When the account's quota was recorded (its last session)." })),
+            quotaFrom: Type.Optional(Type.String({
+                description: 'The account the quota was read from, when it is another account of the same login.',
+            })),
+            sameLoginAs: Type.Optional(Type.String({
+                description: 'The current account (`from`), when this one is signed in as the same login: it shares that quota and is never picked.',
+            })),
         }), { description: 'Every account of the family, best first.' }),
         hasQuota: Type.Boolean({
             description: 'False when no account has quota data: the pick is then a guess, and `sideby next` does not start it (exit 1).',
@@ -395,6 +413,25 @@ export const OUTPUT_SCHEMAS = {
         removed: Type.Array(Str),
         skipped: Type.Array(Type.Object({ path: Str, reason: Str })),
     }, { title: 'sideby app uninstall --json' }),
+    desktop: Type.Object({
+        schemaVersion: Version,
+        ref: Str,
+        family: Str,
+        app: Type.String({ description: 'The desktop app, for example `Claude Desktop`.' }),
+        appPath: Str,
+        action: Type.Union([Type.Literal('started'), Type.Literal('focused'), Type.Literal('already-running')], {
+            description: '`started`: a new window for this account; `focused`: its running window was brought to the front; `already-running`: it runs but could not be brought to the front.',
+        }),
+        appData: Type.Optional(Type.String({
+            description: "This account's app data folder; absent for the main account, which uses the app's default.",
+        })),
+        createdAppData: Type.Boolean(),
+        linked: Type.Array(Str, {
+            description: "Files linked into a new app data folder from the main account's (claude_desktop_config.json).",
+        }),
+        command: Type.Optional(Type.Array(Str, { description: 'The `open` command sideby ran.' })),
+        notices: Type.Array(Str),
+    }, { title: 'sideby desktop --json' }),
     error: Type.Object({
         schemaVersion: Version,
         error: Type.String({ description: 'What went wrong and what to do next.' }),

package/dist/src/cli/main.js

@@ -45,6 +45,8 @@ Usage:
   sideby ui [--port n] [--no-open]    open the local panel
   sideby ui --background              same, without a terminal: keeps running after this command exits
   sideby ui --stop                    stop the background panel
+  sideby desktop <account>            open the desktop app (Claude Desktop, the Codex app) as this
+                                      account, next to the others (macOS)
   sideby app install [--url <url>]    add a sideby app that opens the panel (macOS, Linux)
   sideby app uninstall                remove that app
   sideby shell-init zsh|bash          print shell functions, e.g. eval "$(sideby shell-init zsh)"
@@ -53,8 +55,9 @@ Usage:
   sideby plugins                      list loaded plugins and load errors
 
 Options:
-  --json        machine-readable output (list, new, next, alias, doctor, quota, tune, handoff, families, plugins, app)
-  -h, --help    show this help; \`sideby <command> --help\` for new, alias, login, doctor, families
+  --json        machine-readable output (list, new, next, alias, doctor, quota, tune, handoff, families, plugins, app,
+                desktop)
+  -h, --help    show this help; \`sideby <command> --help\` for new, alias, login, doctor, families, desktop
   -v, --version show the version
 
 An <account> is <family>:<name> (claude:work) or just <name> when it is unique.
@@ -125,6 +128,24 @@ Examples:
   sideby doctor --json
   sideby doctor claude:008 --fix
 Exit: 0 when nothing fails (warnings allowed); 1 when a check fails.`,
+    desktop: `sideby desktop <account> [--json]
+
+Open the host's desktop app as one account: Claude Desktop for claude accounts, the Codex app (ChatGPT.app) for codex
+accounts. Each account gets its own window, side by side with the others; macOS only for now.
+
+The main account opens the app as usual. Any other subscription account opens a new window with that account's
+directory (CLAUDE_CONFIG_DIR, CODEX_HOME) and its own app data folder,
+~/Library/Application Support/sideby/<family>/<name>/. When that account's window is already open, sideby brings it
+to the front instead of starting another one. API accounts are refused: the apps sign in with a subscription only.
+
+sideby never copies or changes the app, and never closes a window. The first time, sign in inside Claude Desktop;
+close other Claude Desktop windows while you do, because the sign-in may come back to one of them.
+
+Examples:
+  sideby desktop claude:work
+  sideby desktop cc008 --json
+Exit: 0 opened or brought to the front; 1 not macOS, no desktop app for that host, API account, app not installed,
+or the app did not open; 2 malformed command line.`,
     families: `sideby families [family] [--json]
 
 For each host (built in or from a plugin): where its accounts live, the variable that selects one, how to sign
@@ -163,6 +184,7 @@ const COMMANDS = {
     },
     ui: { flags: ['no-open', 'background', 'stop', 'serve-detached'], valued: ['port'] },
     app: { flags: ['json'], valued: ['url'] },
+    desktop: { flags: ['json'] },
     'shell-init': { flags: ['write'] },
     plugins: { flags: ['json'] },
     families: { flags: ['json'] },
@@ -266,6 +288,8 @@ export async function main(argv) {
                 return await cmds.cmdUi(parsed, io);
             case 'app':
                 return await cmds.cmdApp(parsed, io);
+            case 'desktop':
+                return await cmds.cmdDesktop(parsed, io);
             case 'shell-init':
                 return await cmds.cmdShellInit(parsed, io);
             case 'plugins':

package/dist/src/core/desktop-app.d.ts

@@ -0,0 +1,96 @@
+import { type DesktopAppDef } from '../families/desktop.ts';
+import type { LoadedPlugin } from '../plugins/loader.ts';
+import type { Runtime } from '../runtime.ts';
+import type { Account, CheckResult, Env } from '../types.ts';
+export interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** What opening a Desktop App needs from the machine; tests replace all of it. */
+export interface DesktopDeps {
+    platform: NodeJS.Platform;
+    /** Folders searched for the app, in order (normally /Applications and ~/Applications). */
+    appDirs: readonly string[];
+    /** Runs a program and resolves with its exit code and output; never rejects. */
+    exec(cmd: string, args: readonly string[], env?: Env): Promise<ExecResult>;
+}
+/**
+ * Internal: makes every Desktop App call made with this Runtime use `deps` instead of the machine. Only
+ * `createRuntime` calls it, from its `desktop` option, which is the one way to replace the machine (tests).
+ */
+export declare function bindDesktopDeps(rt: Runtime, deps: Partial<DesktopDeps>): void;
+/** The Desktop App of a Family, only when a built-in Plugin provides that Family (a plugin may not claim one). */
+export declare function desktopAppOf(plugins: readonly LoadedPlugin[], familyId: string): DesktopAppDef | undefined;
+/** Where a non-main Account's App Data lives: `~/Library/Application Support/sideby/<family>/<name>`. */
+export declare function appDataDir(home: string, account: Pick<Account, 'family' | 'name'>): string;
+export interface FoundApp {
+    path: string;
+    /** `Contents/MacOS/<executable>`: the app's main process runs this. */
+    executable: string;
+}
+/**
+ * Finds the app by bundle id: the usual names in the app folders first, then (with `spotlight`) Spotlight. Listing
+ * Accounts leaves Spotlight out to stay fast; opening one asks it too.
+ */
+export declare function findApp(def: DesktopAppDef, deps: DesktopDeps, opts?: {
+    spotlight?: boolean;
+}): Promise<FoundApp | null>;
+export interface Proc {
+    pid: number;
+    command: string;
+}
+/** The running instance of this Account: the one with its App Data, or for the Main Account the one without any. */
+export declare function instanceOf(app: FoundApp, appData: string | null, procs: readonly Proc[]): Proc | undefined;
+export interface DesktopOpenResult {
+    ref: string;
+    family: string;
+    /** The app as messages name it, for example `Claude Desktop`. */
+    app: string;
+    appPath: string;
+    /** `started`: a new instance; `focused`: the running one is in front; `already-running`: it runs but stayed behind. */
+    action: 'started' | 'focused' | 'already-running';
+    /** The Account's App Data; absent for the Main Account, which uses the app's default. */
+    appData?: string;
+    /** True when this call created the App Data folder. */
+    createdAppData: boolean;
+    /** Files linked into a new App Data from the Main Account's default one. */
+    linked: string[];
+    /** The `open` arguments, when sideby started the app. */
+    command?: string[];
+    /** What the user should know: sign in first, close other windows while signing in. */
+    notices: string[];
+}
+/**
+ * Opens the Account's Desktop App, or brings its running instance to the front. Never starts a second instance of the
+ * same Account, never ends a process, never touches the app bundle or the Host account directory.
+ */
+export declare function openDesktopApp(rt: Runtime, ref: string): Promise<DesktopOpenResult>;
+export interface DesktopAppStatus {
+    /** The app as messages name it. */
+    app: string;
+    installed: boolean;
+    /** That Account's own instance runs now. */
+    running: boolean;
+}
+/**
+ * Desktop App state per Account ref for `sideby list` and the Panel: only on macOS, only Subscription Accounts of a
+ * Family that has one. One process listing for all of them; never throws.
+ */
+export declare function desktopStatuses(rt: Runtime, accounts: readonly Account[]): Promise<Map<string, DesktopAppStatus>>;
+/**
+ * Adds `desktopApp` to each status whose Account has one, for `sideby list` and the Panel. The process listing runs
+ * while `statuses` is still being built; the order of the statuses is kept.
+ */
+export declare function withDesktopApps<T extends {
+    ref: string;
+}>(rt: Runtime, accounts: readonly Account[], statuses: Promise<readonly T[]>): Promise<(T & {
+    desktopApp?: DesktopAppStatus;
+})[]>;
+/**
+ * Doctor's extra checks for an Account's App Data (spec §3.20): the Desktop App's shared files under `link` rules,
+ * only when that Account's App Data folder exists, never for the Main Account (it uses the app's default) or an API
+ * Account. Results are named `app-data/<path>` and are not counted in `shared`. The App Data is the repair boundary:
+ * a fix may only add a missing link inside it, never replace a real file.
+ */
+export declare function checkAppData(plugins: readonly LoadedPlugin[], home: string, account: Account): Promise<CheckResult[]>;