sideby 0.16.0 → 0.17.0

package/dist/src/core/probe.js

@@ -0,0 +1,127 @@
+import { spawn } from 'node:child_process';
+import { HookBus } from '../plugins/bus.js';
+import { UserError } from './errors.js';
+import { prepareLaunch } from './launch.js';
+import { readSecretFile } from './secret-file.js';
+/** How long `sideby try` waits for the Host (spec §3.28). The spawner enforces it. */
+export const PROBE_TIMEOUT_MS = 60_000;
+/** Combined stdout and stderr kept after redaction, in bytes. */
+export const PROBE_OUTPUT_MAX_BYTES = 2048;
+/**
+ * Runs the Family's probe the way Launch would start the Host: `prepareLaunch`'s environment and
+ * arguments (with `probe.args` as the user's arguments), the caller's temp directory as cwd, stdin ignored, and a 60s
+ * timeout the spawner enforces. Returns the exit code and the redacted output.
+ * Throws a UserError when the Family has no probe; the message says this tool cannot be tried
+ * and to start the account with `sideby run` instead.
+ */
+export async function runProbe(account, deps) {
+    const probe = deps.family.probe;
+    if (!probe)
+        throw new UserError(`This tool cannot be tried. Start ${account.ref} with \`sideby run ${account.ref}\` and send one short message instead.`, { code: 'no-probe' });
+    const prepared = deps.launch ??
+        (await prepareLaunch({
+            account,
+            family: deps.family,
+            baseEnv: deps.baseEnv,
+            accountArgs: deps.accountArgs ?? [],
+            userArgs: probe.args,
+            command: 'run',
+            bus: deps.bus ?? new HookBus(),
+            ...(deps.label ? { label: deps.label } : {}),
+        }));
+    const secrets = account.secretFile
+        ? Object.values(await readSecretFile(account.secretFile, deps.baseEnv))
+        : [];
+    const spawned = await deps.spawn({
+        bin: prepared.bin,
+        // Family defaults, config arguments and `launch.before` changes, as `sideby run` passes them.
+        args: prepared.args,
+        env: prepared.env,
+        cwd: deps.cwd,
+        timeoutMs: deps.timeoutMs ?? PROBE_TIMEOUT_MS,
+        stdin: 'ignore',
+    });
+    const output = clip(redactSecrets(spawned.stdout + spawned.stderr, secrets), PROBE_OUTPUT_MAX_BYTES);
+    return {
+        ok: spawned.exitCode === 0 && !spawned.timedOut,
+        exitCode: spawned.exitCode,
+        output,
+        timedOut: spawned.timedOut,
+    };
+}
+/** Output kept per stream before redaction, in characters. */
+const SPAWN_KEEP = 65536;
+/**
+ * The real spawner for {@link ProbeDeps.spawn}. The Host leads its own process group, so the timeout stops it and
+ * any child it started; the result comes at once, even while a child still holds the output pipes open.
+ */
+export function spawnProbe(request) {
+    return new Promise((resolve) => {
+        const child = spawn(request.bin, [...request.args], {
+            cwd: request.cwd,
+            env: request.env,
+            stdio: [request.stdin, 'pipe', 'pipe'],
+            detached: true,
+        });
+        let stdout = '', stderr = '', timedOut = false, done = false;
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, 'SIGKILL');
+            }
+            catch {
+                child.kill('SIGKILL');
+            }
+            child.stdout.destroy();
+            child.stderr.destroy();
+            // It may have exited already while a child of its own kept the pipes open.
+            if (child.exitCode !== null || child.signalCode !== null)
+                finish({ exitCode: null, stdout, stderr, timedOut });
+        }, request.timeoutMs);
+        child.stdout.on('data', (d) => {
+            if (stdout.length < SPAWN_KEEP)
+                stdout += d.toString();
+        });
+        child.stderr.on('data', (d) => {
+            if (stderr.length < SPAWN_KEEP)
+                stderr += d.toString();
+        });
+        child.on('error', () => finish({
+            exitCode: 1,
+            stdout: '',
+            stderr: 'Could not start the Host; check its installation and run `sideby try` again.',
+            timedOut: false,
+        }));
+        child.on('exit', () => {
+            if (timedOut)
+                finish({ exitCode: null, stdout, stderr, timedOut });
+        });
+        child.on('close', (exitCode) => finish({ exitCode, stdout, stderr, timedOut }));
+    });
+}
+/** Replaces each secret of length 4 or more. Longer values go first so one cannot hide inside another. */
+export function redactSecrets(text, values) {
+    const needles = [...new Set(values.filter((v) => v.length >= 4))].sort((a, b) => b.length - a.length);
+    let out = text;
+    for (const needle of needles)
+        out = out.split(needle).join('***');
+    return out;
+}
+/** The first `max` bytes, never cutting a UTF-8 code point in half. */
+function clip(text, max) {
+    const buf = Buffer.from(text, 'utf8');
+    if (buf.length <= max)
+        return text;
+    let n = max;
+    while (n > 0 && (buf[n] & 0xc0) === 0x80)
+        n--;
+    return buf.subarray(0, n).toString('utf8');
+}

package/dist/src/core/same-login.d.ts

@@ -1,18 +1,23 @@
 import type { Account, AccountIdentity, QuotaResult } from '../types.ts';
+/** Families whose Accounts can be a Same Login (ADR-0016, ADR-0028). */
+export declare const SAME_LOGIN_FAMILIES: ReadonlySet<string>;
 /**
- * Families whose Identity tells one Quota apart. Codex is left out: its Identity is an email only, and one email can
- * belong to several ChatGPT workspaces, each with its own Quota (ADR-0016).
+ * Families whose Identity alone does not tell one Quota apart, so two Accounts also need equal Login Keys. Codex: one
+ * email can belong to several ChatGPT workspaces, each with its own Quota (ADR-0028).
  */
-export declare const SAME_LOGIN_FAMILIES: ReadonlySet<string>;
+export declare const LOGIN_KEY_FAMILIES: ReadonlySet<string>;
 export interface LoginMember {
     ref: string;
     family: string;
     kind: Account['kind'];
     identity?: AccountIdentity;
+    /** The opaque Login Key (ADR-0028), only for comparing here; never put into an output. */
+    loginKey?: string;
 }
 /**
  * Whether two Accounts are the same login: same Family (one that groups), both subscriptions, the same email, and the
- * same organization (both have one and it is equal, or neither has one). Without an email nothing groups.
+ * same organization (both have one and it is equal, or neither has one). Without an email nothing groups. In a Family
+ * of `LOGIN_KEY_FAMILIES` both must also have a Login Key, and the keys must be equal.
  */
 export declare function isSameLogin(a: LoginMember, b: LoginMember): boolean;
 /** Ref → the other refs of its Same Login, in the order given; Accounts without one are left out. */

package/dist/src/core/same-login.js

@@ -1,12 +1,15 @@
+/** Families whose Accounts can be a Same Login (ADR-0016, ADR-0028). */
+export const SAME_LOGIN_FAMILIES = new Set(['claude', 'codex']);
 /**
- * Families whose Identity tells one Quota apart. Codex is left out: its Identity is an email only, and one email can
- * belong to several ChatGPT workspaces, each with its own Quota (ADR-0016).
+ * Families whose Identity alone does not tell one Quota apart, so two Accounts also need equal Login Keys. Codex: one
+ * email can belong to several ChatGPT workspaces, each with its own Quota (ADR-0028).
  */
-export const SAME_LOGIN_FAMILIES = new Set(['claude']);
+export const LOGIN_KEY_FAMILIES = new Set(['codex']);
 const norm = (s) => s?.trim().toLowerCase();
 /**
  * Whether two Accounts are the same login: same Family (one that groups), both subscriptions, the same email, and the
- * same organization (both have one and it is equal, or neither has one). Without an email nothing groups.
+ * same organization (both have one and it is equal, or neither has one). Without an email nothing groups. In a Family
+ * of `LOGIN_KEY_FAMILIES` both must also have a Login Key, and the keys must be equal.
  */
 export function isSameLogin(a, b) {
     if (a.ref === b.ref || a.family !== b.family || !SAME_LOGIN_FAMILIES.has(a.family))
@@ -16,6 +19,8 @@ export function isSameLogin(a, b) {
     const ea = norm(a.identity?.email);
     if (!ea || ea !== norm(b.identity?.email))
         return false;
+    if (LOGIN_KEY_FAMILIES.has(a.family) && (!a.loginKey || a.loginKey !== b.loginKey))
+        return false;
     return norm(a.identity?.org) === norm(b.identity?.org);
 }
 /** Ref → the other refs of its Same Login, in the order given; Accounts without one are left out. */

package/dist/src/core/secret-file.d.ts

@@ -1,3 +1,4 @@
+import type { FamilyDef } from '../types.ts';
 import { UserError } from './errors.ts';
 export declare class SecretFileError extends UserError {
 }
@@ -28,3 +29,28 @@ export declare function inspectSecretFile(file: string): Promise<SecretFileState
 /** Reads a Secret File after inspectSecretFile accepts it. */
 export declare function readSecretFile(file: string, env?: Readonly<Record<string, string | undefined>>): Promise<Record<string, string>>;
 export declare function secretFileTemplate(vars: readonly string[], familyTitle: string): string;
+/** Variable names `sideby key` accepts, such as `ANTHROPIC_AUTH_TOKEN`. */
+export declare const SECRET_VAR_NAME: RegExp;
+export interface SetSecretResult {
+    /** Path whose bytes were written. When `file` is a symlink, this is its real target. */
+    path: string;
+    /** True when `file` was a symlink. The link itself is unchanged. */
+    viaLink: boolean;
+    name: string;
+    /** `replaced` keeps the assignment's line; `appended` adds one at the end. */
+    action: 'replaced' | 'appended';
+}
+/**
+ * The Secret File variable `sideby key` writes when the user does not pass `--var`.
+ * Uses `family.secretVar` when the Family sets one, otherwise the first `apiVars` entry
+ * that ends in `_KEY` or `_TOKEN`. Throws when the Family has neither, and says to pass `--var`.
+ */
+export declare function secretVarFor(family: Pick<FamilyDef, 'title' | 'apiVars' | 'secretVar'>): string;
+/**
+ * Writes one assignment into a Secret File. The line that assigns `name` is replaced and stays
+ * where it was; every other line is kept byte for byte. When `name` is absent, a line is appended.
+ * The write is atomic and the file ends at mode 600. A symlink is left in place and the bytes go
+ * to its real target, which `path` reports. `name` must match {@link SECRET_VAR_NAME}. A value
+ * that contains a newline is rejected. The value is never included in an error or in the result.
+ */
+export declare function setSecret(file: string, name: string, value: string): Promise<SetSecretResult>;

package/dist/src/core/secret-file.js

@@ -1,5 +1,6 @@
-import { lstat, readFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { UserError } from './errors.js';
+import { lstatOrNull, realpathOrNull, writeFileAtomic } from './fs-safe.js';
 export class SecretFileError extends UserError {
 }
 const LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/;
@@ -82,13 +83,9 @@ export function parseSecretFile(text, file, env = {}) {
  * with mode 600. Only the file's type and mode are inspected, never its contents.
  */
 export async function inspectSecretFile(file) {
-    let st;
-    try {
-        st = await lstat(file);
-    }
-    catch {
+    const st = await lstatOrNull(file);
+    if (!st)
         return { kind: 'missing' };
-    }
     if (!st.isFile())
         return { kind: 'not-file' };
     const mode = st.mode & 0o777;
@@ -114,3 +111,125 @@ export function secretFileTemplate(vars, familyTitle) {
     ];
     return lines.join('\n');
 }
+/** Variable names `sideby key` accepts, such as `ANTHROPIC_AUTH_TOKEN`. */
+export const SECRET_VAR_NAME = /^[A-Z][A-Z0-9_]*$/;
+const KEY_VAR = /(?:_KEY|_TOKEN)$/;
+const ASSIGN = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+/**
+ * The Secret File variable `sideby key` writes when the user does not pass `--var`.
+ * Uses `family.secretVar` when the Family sets one, otherwise the first `apiVars` entry
+ * that ends in `_KEY` or `_TOKEN`. Throws when the Family has neither, and says to pass `--var`.
+ */
+export function secretVarFor(family) {
+    const name = family.secretVar ?? family.apiVars.find((v) => SECRET_VAR_NAME.test(v) && KEY_VAR.test(v));
+    if (!name || !SECRET_VAR_NAME.test(name))
+        throw new SecretFileError(`${family.title} has no default key variable. Run \`sideby key <account> --var <NAME>\` with the variable that tool's documentation names.`);
+    return name;
+}
+/**
+ * Writes one assignment into a Secret File. The line that assigns `name` is replaced and stays
+ * where it was; every other line is kept byte for byte. When `name` is absent, a line is appended.
+ * The write is atomic and the file ends at mode 600. A symlink is left in place and the bytes go
+ * to its real target, which `path` reports. `name` must match {@link SECRET_VAR_NAME}. A value
+ * that contains a newline is rejected. The value is never included in an error or in the result.
+ */
+export async function setSecret(file, name, value) {
+    if (!SECRET_VAR_NAME.test(name))
+        throw new SecretFileError(`variable name must match [A-Z][A-Z0-9_]* (for example ANTHROPIC_AUTH_TOKEN). Run \`sideby key <account> --var <NAME>\`.`);
+    if (value.includes('\n') || value.includes('\r'))
+        throw new SecretFileError(`${name} must be a single line. Run \`sideby key <account>\` and enter one line, or fill the key in the Panel.`);
+    const formatted = `${name}=${formatSecretValue(value)}`;
+    const located = await locateSecretFile(file);
+    let previous = '';
+    if (located.existed) {
+        try {
+            previous = await readFile(located.path, 'utf8');
+        }
+        catch (err) {
+            throw writeFailed(located.path, err);
+        }
+    }
+    const next = assignLine(previous, name, formatted);
+    try {
+        await writeFileAtomic(located.path, next.text, 0o600);
+    }
+    catch (err) {
+        throw writeFailed(located.path, err);
+    }
+    return { path: located.path, viaLink: located.viaLink, name, action: next.action };
+}
+/** Where the bytes go. A symlink is not followed by the writer; the caller passes the real target. */
+async function locateSecretFile(file) {
+    const st = await lstatOrNull(file);
+    if (!st)
+        return { path: file, viaLink: false, existed: false };
+    if (st.isSymbolicLink()) {
+        const real = await realpathOrNull(file);
+        if (!real)
+            throw new SecretFileError(`${file} is a broken link. Point it at a proxy.env file, or replace the link with a file, then run \`sideby key\` again.`);
+        const target = await lstatOrNull(real);
+        if (!target?.isFile())
+            throw new SecretFileError(`${file} points at ${real}, which is not a file. Point the link at a proxy.env file, then run \`sideby key\` again.`);
+        return { path: real, viaLink: true, existed: true };
+    }
+    if (st.isDirectory())
+        throw new SecretFileError(`${file} is a directory. \`sideby key\` writes the proxy.env file; move that directory aside, then run \`sideby key\` again.`);
+    if (!st.isFile())
+        throw new SecretFileError(`${file} is not a regular file. Replace it with a proxy.env file, then run \`sideby key\` again.`);
+    return { path: file, viaLink: false, existed: true };
+}
+function assignLine(text, name, formatted) {
+    const lines = splitKeepEnds(text);
+    let replaced = false;
+    const rebuilt = lines
+        .map((line) => {
+        if (assignmentName(line.body) !== name)
+            return line.body + line.eol;
+        replaced = true;
+        return formatted + line.eol;
+    })
+        .join('');
+    if (replaced)
+        return { text: rebuilt, action: 'replaced' };
+    const sep = text.length > 0 && !text.endsWith('\n') ? '\n' : '';
+    return { text: `${text}${sep}${formatted}\n`, action: 'appended' };
+}
+function assignmentName(body) {
+    const trimmed = body.trim();
+    if (!trimmed || trimmed.startsWith('#'))
+        return null;
+    return ASSIGN.exec(body)?.[1] ?? null;
+}
+/** A value `parseSecretFile` reads back unchanged. Single quotes stay literal; nothing is executed. */
+function formatSecretValue(value) {
+    if (/^[A-Za-z0-9_./:@%+-]*$/.test(value))
+        return value;
+    if (!value.includes("'"))
+        return `'${value}'`;
+    const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\$/g, '\\$');
+    return `"${escaped}"`;
+}
+function splitKeepEnds(text) {
+    if (text === '')
+        return [];
+    const out = [];
+    const re = /\r\n|\n/g;
+    let last = 0;
+    for (let m = re.exec(text); m; m = re.exec(text)) {
+        out.push({ body: text.slice(last, m.index), eol: m[0] });
+        last = m.index + m[0].length;
+    }
+    if (last < text.length)
+        out.push({ body: text.slice(last), eol: '' });
+    return out;
+}
+function writeFailed(file, err) {
+    if (err instanceof SecretFileError)
+        return err;
+    const code = err.code;
+    if (code === 'ENOENT')
+        return new SecretFileError(`${file} cannot be written because a parent directory is missing. Create the account with \`sideby new <family> <name> --api\`, then run \`sideby key\` again.`);
+    if (code === 'EACCES' || code === 'EPERM')
+        return new SecretFileError(`${file} cannot be written (permission denied). Make the account directory yours, then run \`sideby key\` again.`);
+    return new SecretFileError(`${file} could not be written. Check that the account directory is a real folder you can write to, then run \`sideby key\` again.`);
+}

package/dist/src/core/terminal.d.ts

@@ -0,0 +1,93 @@
+import { access, stat } from 'node:fs/promises';
+import type { Env } from '../types.ts';
+import type { DesktopDeps } from './desktop-app.ts';
+export type TerminalId = 'terminal' | 'iterm2' | 'ghostty' | 'orca' | 'wezterm' | 'kitty' | 'alacritty' | 'custom';
+export interface TerminalDef {
+    id: TerminalId;
+    name: string;
+    bundleId: string | null;
+    app: string | null;
+    termPrograms: readonly string[];
+    marker?: string;
+    binary?: string;
+}
+/** Supported macOS terminals; custom templates have no app bundle or environment marker. */
+export declare const TERMINALS: readonly TerminalDef[];
+export interface InstalledTerminal {
+    id: TerminalId;
+    appPath?: string;
+    executable?: string;
+}
+export interface TerminalDeps {
+    home: string;
+    env: Env;
+    platform?: NodeJS.Platform;
+    appDirs?: readonly string[];
+    fs?: {
+        stat: typeof stat;
+        access: typeof access;
+    };
+}
+/** Finds bundles and command line launchers without opening apps or reading user files. */
+export declare function installedTerminals(deps: TerminalDeps): Promise<InstalledTerminal[]>;
+/** Chooses an installed preference, then the launching environment, then macOS Terminal. */
+export declare function guessTerminal(opts: {
+    preferred?: string;
+    env: Env;
+    installed: readonly InstalledTerminal[];
+}): {
+    id: TerminalId;
+    source: 'config' | 'env' | 'default';
+};
+/** What the terminal runs: this Node and this sideby's CLI entry, so neither PATH nor the login shell matters. */
+export interface AskLauncher {
+    node: string;
+    entry: string;
+}
+/** This process's Node and the real path of the CLI entry next to this module (`main.ts` from source, `main.js` from dist). */
+export declare function askLauncher(): AskLauncher;
+/** Why the terminal cannot run this launcher, or null when it can. */
+export declare function launcherProblem(launcher: AskLauncher, stateDir?: string): {
+    ok: false;
+    reason: 'npx-cache' | 'unsafe-path';
+    detail: string;
+} | null;
+/**
+ * Builds the only shell command accepted by the AI Task terminal launcher: the quoted Node and CLI entry, or
+ * `sideby` by name when `launcher` is null (a command for the user to paste where sideby is on PATH). It carries the
+ * state folder the task was written to, so a terminal whose environment differs from the Panel's still finds it.
+ */
+export declare function askRunCommand(taskId: string, stateDir: string, launcher?: AskLauncher | null): string;
+export interface TerminalLaunchOptions {
+    cwd: string;
+    command: string;
+    custom?: string;
+    appPath?: string;
+    executable?: string;
+}
+export interface TerminalCommand {
+    file: string;
+    args: string[];
+}
+/**
+ * Splits a custom terminal template into argv, throwing unless it names a program first and has both `{cmd}` and
+ * `{cwd}` in its arguments.
+ */
+export declare function validateCustomTemplate(template: string): [string, ...string[]];
+/** Builds argv only. The caller supplies discovered bundle/binary paths when available. */
+export declare function launchArgs(id: TerminalId, opts: TerminalLaunchOptions): TerminalCommand;
+export type TerminalOpenResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'unsupported-platform';
+} | {
+    ok: false;
+    reason: 'not-installed' | 'automation-denied' | 'failed' | 'npx-cache' | 'unsafe-path';
+    detail: string;
+};
+/** Opens through the injected Desktop exec boundary, returning safe, actionable failures only. */
+export declare function openTerminal(id: TerminalId, opts: TerminalLaunchOptions & {
+    platform?: NodeJS.Platform;
+    installed: readonly InstalledTerminal[];
+}, exec: DesktopDeps['exec']): Promise<TerminalOpenResult>;