sideby 0.0.0-stage → 0.1.0

package/dist/src/core/launch.js

@@ -0,0 +1,108 @@
+import { spawn } from 'node:child_process';
+import { access, constants } from 'node:fs/promises';
+import { constants as osConstants } from 'node:os';
+import { delimiter, join } from 'node:path';
+import { readSecretFile } from './secret-file.js';
+/** Finds an executable on PATH; returns null when the Host is not installed. */
+export async function which(bin, env) {
+    for (const dir of (env.PATH ?? '').split(delimiter)) {
+        if (!dir)
+            continue;
+        const p = join(dir, bin);
+        try {
+            await access(p, constants.X_OK);
+            return p;
+        }
+        catch {
+            // keep looking
+        }
+    }
+    return null;
+}
+/**
+ * Builds the Host's environment and arguments (spec §3.5):
+ * copy the current env, clear Hijack Variables, merge the Secret File, set the select variable,
+ * then let `launch.before` hooks adjust or abort. Never touches the caller's environment.
+ */
+export async function prepareLaunch(opts) {
+    const { account, family } = opts;
+    const env = { ...opts.baseEnv };
+    for (const v of family.hijackVars)
+        delete env[v];
+    delete env[family.selectVar];
+    if (account.secretFile)
+        Object.assign(env, await readSecretFile(account.secretFile, opts.baseEnv));
+    if (!account.isMain)
+        env[family.selectVar] = account.dir;
+    let args;
+    let notice;
+    if (opts.command === 'login') {
+        // Family arguments still apply: Codex must store a non-main login in the Account's own file.
+        const base = family.defaultArgs?.(account, []) ?? [];
+        if (family.login.args)
+            args = [...base, ...family.login.args];
+        else {
+            args = base;
+            notice = family.login.hint;
+        }
+    }
+    else {
+        args = [...(family.defaultArgs?.(account, opts.userArgs) ?? []), ...opts.accountArgs, ...opts.userArgs];
+    }
+    await opts.bus.run('launch.before', family.id, {
+        account,
+        family,
+        env,
+        args,
+        config: {},
+        command: opts.command,
+    });
+    return { account, family, bin: family.bin, args, env, ...(notice ? { notice } : {}) };
+}
+/**
+ * Runs the Host with the terminal attached and returns sideby's exit code (spec §3.5):
+ * the Host's own code, 128 + signal number when a signal ended it, 1 when it could not start.
+ * While the Host runs, sideby ignores SIGINT/SIGQUIT (the terminal delivers them to the whole foreground
+ * process group, so the Host receives them directly) and forwards SIGTERM/SIGHUP once. SIGTSTP keeps its
+ * default action so Ctrl-Z suspends sideby together with the Host and `fg` resumes both.
+ */
+export function runHost(p) {
+    return new Promise((resolve) => {
+        const child = spawn(p.bin, p.args, { stdio: 'inherit', env: p.env });
+        const ignore = () => { };
+        const forwarded = new Set();
+        const forward = (sig) => () => {
+            if (forwarded.has(sig) || child.exitCode !== null || child.signalCode !== null)
+                return;
+            forwarded.add(sig);
+            child.kill(sig);
+        };
+        const handlers = [
+            ['SIGINT', ignore],
+            ['SIGQUIT', ignore],
+            ['SIGTERM', forward('SIGTERM')],
+            ['SIGHUP', forward('SIGHUP')],
+        ];
+        for (const [s, h] of handlers)
+            process.on(s, h);
+        const cleanup = () => {
+            for (const [s, h] of handlers)
+                process.off(s, h);
+        };
+        child.once('error', (err) => {
+            cleanup();
+            const msg = err.code === 'ENOENT'
+                ? `${p.family.title} is not installed (\`${p.bin}\` not found on PATH); install it: ${p.family.installUrl}`
+                : `could not start ${p.bin}: ${err.message}`;
+            process.stderr.write(`sideby: ${msg}\n`);
+            resolve(1);
+        });
+        child.once('exit', (code, signal) => {
+            cleanup();
+            if (signal)
+                resolve(128 + (osConstants.signals[signal] ?? 0));
+            else
+                resolve(code ?? 1);
+        });
+    });
+}

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

@@ -0,0 +1,23 @@
+import type { Env } from '../types.ts';
+export declare const LOGIN_PATH_TIMEOUT_MS = 5000;
+export interface LoginPathOptions {
+    /** Shell to ask; defaults to `$SHELL`, then the account's shell, then `/bin/sh`. */
+    shell?: string;
+    timeoutMs?: number;
+}
+export interface LoginPathResult {
+    path: string;
+    /** `login-shell` when the shell answered, `fallback` when its answer was unusable and `path` is the current one. */
+    source: 'login-shell' | 'fallback';
+    /** Why the fallback was used. */
+    reason?: string;
+}
+/** Joins PATH lists, first occurrence wins, dropping empty and relative entries. */
+export declare function mergePaths(...lists: (string | undefined)[]): string;
+/** Reads the PATH between the markers; rc files may print anything before or after them. */
+export declare function parseMarkedPath(stdout: string): string | undefined;
+/**
+ * Asks the login shell (`$SHELL -ilc`) for its PATH and merges it in front of `env.PATH`.
+ * Never throws: on a timeout, a missing shell or unreadable output it returns the current PATH.
+ */
+export declare function loginShellPath(env: Env, opts?: LoginPathOptions): Promise<LoginPathResult>;

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

@@ -0,0 +1,96 @@
+// PATH as the user's login shell sets it. An app started from Finder, a dock or launchd gets a minimal PATH, so
+// Hosts installed under ~/.local/bin, ~/.grok/bin or a version manager would look "not installed".
+import { spawn } from 'node:child_process';
+import { userInfo } from 'node:os';
+import { delimiter, isAbsolute } from 'node:path';
+const BEGIN = '__SIDEBY_PATH_BEGIN__';
+const END = '__SIDEBY_PATH_END__';
+export const LOGIN_PATH_TIMEOUT_MS = 5000;
+/** Joins PATH lists, first occurrence wins, dropping empty and relative entries. */
+export function mergePaths(...lists) {
+    const seen = new Set();
+    for (const list of lists)
+        for (const dir of (list ?? '').split(delimiter))
+            if (dir && isAbsolute(dir) && !seen.has(dir))
+                seen.add(dir);
+    return [...seen].join(delimiter);
+}
+/** Reads the PATH between the markers; rc files may print anything before or after them. */
+export function parseMarkedPath(stdout) {
+    const end = stdout.lastIndexOf(END);
+    if (end === -1)
+        return undefined;
+    const begin = stdout.lastIndexOf(BEGIN, end);
+    if (begin === -1)
+        return undefined;
+    const value = stdout.slice(begin + BEGIN.length, end).trim();
+    if (!value || /[\r\n]/.test(value))
+        return undefined;
+    const dirs = value.split(delimiter).filter((d) => d && isAbsolute(d));
+    return dirs.length ? dirs.join(delimiter) : undefined;
+}
+function defaultShell(env) {
+    if (env.SHELL && isAbsolute(env.SHELL))
+        return env.SHELL;
+    try {
+        const s = userInfo().shell;
+        if (s && isAbsolute(s))
+            return s;
+    }
+    catch { }
+    return '/bin/sh';
+}
+/**
+ * Asks the login shell (`$SHELL -ilc`) for its PATH and merges it in front of `env.PATH`.
+ * Never throws: on a timeout, a missing shell or unreadable output it returns the current PATH.
+ */
+export function loginShellPath(env, opts = {}) {
+    const current = env.PATH ?? '';
+    const shell = opts.shell ?? defaultShell(env);
+    const timeoutMs = opts.timeoutMs ?? LOGIN_PATH_TIMEOUT_MS;
+    // `printenv` prints the exported PATH the same way in sh, bash, zsh and fish (where $PATH is a list).
+    const script = `echo ${BEGIN}; printenv PATH; echo ${END}`;
+    return new Promise((resolve) => {
+        let done = false;
+        let out = '';
+        const finish = (reason) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            // A shell that printed its PATH but hangs on exit (an rc file started something) still counts.
+            const found = parseMarkedPath(out);
+            if (found)
+                resolve({ path: mergePaths(found, current), source: 'login-shell' });
+            else
+                resolve({ path: current, source: 'fallback', reason: reason ?? 'no PATH in the shell output' });
+        };
+        let child;
+        try {
+            child = spawn(shell, ['-ilc', script], {
+                env: env,
+                stdio: ['ignore', 'pipe', 'ignore'],
+                // Own process group, so a timeout also stops whatever the rc files started.
+                detached: true,
+            });
+        }
+        catch (err) {
+            resolve({ path: current, source: 'fallback', reason: err instanceof Error ? err.message : String(err) });
+            return;
+        }
+        const timer = setTimeout(() => {
+            try {
+                if (child.pid)
+                    process.kill(-child.pid, 'SIGKILL');
+            }
+            catch { }
+            finish(`${shell} did not answer within ${timeoutMs} ms`);
+        }, timeoutMs);
+        child.stdout?.on('data', (d) => {
+            if (out.length < 1_000_000)
+                out += d;
+        });
+        child.once('error', (err) => finish(err.message));
+        child.once('close', () => finish());
+    });
+}

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

@@ -0,0 +1,13 @@
+import type { Env } from '../types.ts';
+export interface Paths {
+    home: string;
+    configDir: string;
+    stateDir: string;
+    configFile: string;
+    userPluginsDir: string;
+}
+export declare function resolvePaths(env?: Env): Paths;
+/** Expands a leading `~` or `~/`; returns undefined for relative paths so callers can reject them. */
+export declare function expandUserPath(p: string, home: string): string | undefined;
+/** Replaces the HOME prefix with `~` for user-facing output. */
+export declare function tildify(p: string, home: string): string;

package/dist/src/core/paths.js

@@ -0,0 +1,32 @@
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+export function resolvePaths(env = process.env) {
+    const home = env.HOME || homedir();
+    const configBase = absOr(env.XDG_CONFIG_HOME, join(home, '.config'));
+    const stateBase = absOr(env.XDG_STATE_HOME, join(home, '.local', 'state'));
+    const configDir = join(configBase, 'sideby');
+    return {
+        home,
+        configDir,
+        stateDir: join(stateBase, 'sideby'),
+        configFile: join(configDir, 'config.json'),
+        userPluginsDir: join(configDir, 'plugins'),
+    };
+}
+/** Expands a leading `~` or `~/`; returns undefined for relative paths so callers can reject them. */
+export function expandUserPath(p, home) {
+    if (p === '~')
+        return home;
+    if (p.startsWith('~/'))
+        return join(home, p.slice(2));
+    return isAbsolute(p) ? p : undefined;
+}
+/** Replaces the HOME prefix with `~` for user-facing output. */
+export function tildify(p, home) {
+    if (p === home)
+        return '~';
+    return p.startsWith(`${home}/`) ? `~${p.slice(home.length)}` : p;
+}
+function absOr(value, fallback) {
+    return value && isAbsolute(value) ? value : fallback;
+}

package/dist/src/core/quota-levels.d.ts

@@ -0,0 +1,19 @@
+import type { QuotaResult } from '../types.ts';
+/**
+ * How full a Quota window must be before the CLI and the Panel warn about it, and the Usage window both
+ * report. One rule for both surfaces: the Panel interpolates these numbers into its inline script.
+ */
+export declare const QUOTA_FAIL_PERCENT = 85;
+export declare const QUOTA_WARN_PERCENT = 60;
+/** Days of Usage every Family reports. */
+export declare const USAGE_DAYS = 7;
+export type QuotaLevel = 'ok' | 'warn' | 'fail';
+export declare function quotaLevel(usedPercent: number): QuotaLevel;
+/** True once a window's reset time has passed; an unreadable time never counts as reset. */
+export declare function windowReset(resetsAt: string, now: Date): boolean;
+/**
+ * Quota Pressure: the used percent of the fullest window that has not reset yet (0 when all have reset),
+ * or null when the Account has no Quota. The Panel keeps its own copy (`quotaPressure` in page-logic.ts,
+ * -1 for null) because page-logic helpers must be self-contained; a test keeps the two equal.
+ */
+export declare function quotaPressure(quota: QuotaResult | undefined, now: Date): number | null;

package/dist/src/core/quota-levels.js

@@ -0,0 +1,34 @@
+/**
+ * How full a Quota window must be before the CLI and the Panel warn about it, and the Usage window both
+ * report. One rule for both surfaces: the Panel interpolates these numbers into its inline script.
+ */
+export const QUOTA_FAIL_PERCENT = 85;
+export const QUOTA_WARN_PERCENT = 60;
+/** Days of Usage every Family reports. */
+export const USAGE_DAYS = 7;
+export function quotaLevel(usedPercent) {
+    if (usedPercent >= QUOTA_FAIL_PERCENT)
+        return 'fail';
+    if (usedPercent >= QUOTA_WARN_PERCENT)
+        return 'warn';
+    return 'ok';
+}
+/** True once a window's reset time has passed; an unreadable time never counts as reset. */
+export function windowReset(resetsAt, now) {
+    const t = Date.parse(resetsAt);
+    return Number.isFinite(t) && t <= now.getTime();
+}
+/**
+ * Quota Pressure: the used percent of the fullest window that has not reset yet (0 when all have reset),
+ * or null when the Account has no Quota. The Panel keeps its own copy (`quotaPressure` in page-logic.ts,
+ * -1 for null) because page-logic helpers must be self-contained; a test keeps the two equal.
+ */
+export function quotaPressure(quota, now) {
+    if (quota?.status !== 'ok' || quota.windows.length === 0)
+        return null;
+    let max = 0;
+    for (const w of quota.windows)
+        if (!windowReset(w.resetsAt, now))
+            max = Math.max(max, Math.min(100, Number(w.usedPercent) || 0));
+    return max;
+}

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

@@ -0,0 +1,30 @@
+import { UserError } from './errors.ts';
+export declare class SecretFileError extends UserError {
+}
+/** Non-secret locations a Secret File may reference from the environment, such as `$HOME/bin/notify`. */
+export declare const SECRET_FILE_ENV_REFS: readonly ['HOME', 'USER', 'LOGNAME', 'TMPDIR', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_STATE_HOME', 'XDG_CACHE_HOME'];
+/**
+ * Parses the dotenv subset sideby supports: KEY=VALUE, optional `export `, quotes and comments.
+ * `$NAME` and `${NAME}` in unquoted or double-quoted values expand to a key defined earlier in the
+ * same file, else to one of SECRET_FILE_ENV_REFS from `env`; no other variable is read and nothing is
+ * executed. Errors name the line, never its content.
+ */
+export declare function parseSecretFile(text: string, file: string, env?: Readonly<Record<string, string | undefined>>): Record<string, string>;
+export type SecretFileState = {
+    kind: 'ok';
+} | {
+    kind: 'missing';
+} | {
+    kind: 'not-file';
+} | {
+    kind: 'mode';
+    mode: number;
+};
+/**
+ * The one Secret File rule, used by Launch and by Doctor: the Account's own regular file (never a link)
+ * with mode 600. Only the file's type and mode are inspected, never its contents.
+ */
+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;

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

@@ -0,0 +1,116 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { UserError } from './errors.js';
+export class SecretFileError extends UserError {
+}
+const LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/;
+/** Non-secret locations a Secret File may reference from the environment, such as `$HOME/bin/notify`. */
+export const SECRET_FILE_ENV_REFS = [
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'TMPDIR',
+    'XDG_CONFIG_HOME',
+    'XDG_DATA_HOME',
+    'XDG_STATE_HOME',
+    'XDG_CACHE_HOME',
+];
+const REF = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)|\$\{/g;
+/**
+ * Parses the dotenv subset sideby supports: KEY=VALUE, optional `export `, quotes and comments.
+ * `$NAME` and `${NAME}` in unquoted or double-quoted values expand to a key defined earlier in the
+ * same file, else to one of SECRET_FILE_ENV_REFS from `env`; no other variable is read and nothing is
+ * executed. Errors name the line, never its content.
+ */
+export function parseSecretFile(text, file, env = {}) {
+    const out = {};
+    const lines = text.split(/\r?\n/);
+    const expand = (s, line) => s.replace(REF, (whole, braced, bare) => {
+        const name = braced ?? bare;
+        if (!name)
+            throw new SecretFileError(`${file}:${line}: unterminated \${`);
+        if (Object.hasOwn(out, name))
+            return out[name];
+        const fromEnv = SECRET_FILE_ENV_REFS.includes(name) ? env[name] : undefined;
+        if (fromEnv !== undefined)
+            return fromEnv;
+        throw new SecretFileError(`${file}:${line}: ${whole} is not defined earlier in this file; from the environment only ${SECRET_FILE_ENV_REFS.join(', ')} are read`);
+    });
+    lines.forEach((raw, i) => {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            return;
+        const m = LINE.exec(raw);
+        if (!m)
+            throw new SecretFileError(`${file}:${i + 1}: expected KEY=VALUE`);
+        const key = m[1];
+        let value = m[2];
+        const q = value[0];
+        if (q === '"' || q === "'") {
+            let end = -1;
+            for (let j = 1; j < value.length; j++) {
+                if (q === '"' && value[j] === '\\')
+                    j++;
+                else if (value[j] === q) {
+                    end = j;
+                    break;
+                }
+            }
+            if (end === -1)
+                throw new SecretFileError(`${file}:${i + 1}: unterminated quote`);
+            const rest = value.slice(end + 1).trim();
+            if (rest && !rest.startsWith('#'))
+                throw new SecretFileError(`${file}:${i + 1}: text after closing quote`);
+            value = value.slice(1, end);
+            if (q === '"')
+                // Escapes and references in one pass, so an escaped `\$` stays a literal dollar sign.
+                value = value.replace(/\\(n|"|\\|\$)|\$[^$\\]*/g, (part, c) => c === undefined ? expand(part, i + 1) : c === 'n' ? '\n' : c);
+        }
+        else {
+            const hash = value.search(/\s#/);
+            if (hash !== -1)
+                value = value.slice(0, hash).trimEnd();
+            if (/\$\(|`/.test(value))
+                throw new SecretFileError(`${file}:${i + 1}: command substitution is not supported; write the value itself`);
+            value = expand(value, i + 1);
+        }
+        out[key] = value;
+    });
+    return out;
+}
+/**
+ * The one Secret File rule, used by Launch and by Doctor: the Account's own regular file (never a link)
+ * 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 {
+        return { kind: 'missing' };
+    }
+    if (!st.isFile())
+        return { kind: 'not-file' };
+    const mode = st.mode & 0o777;
+    return mode === 0o600 ? { kind: 'ok' } : { kind: 'mode', mode };
+}
+/** Reads a Secret File after inspectSecretFile accepts it. */
+export async function readSecretFile(file, env = {}) {
+    const state = await inspectSecretFile(file);
+    if (state.kind === 'missing')
+        throw new SecretFileError(`${file} is missing`);
+    if (state.kind === 'not-file')
+        throw new SecretFileError(`${file} must be a regular file, not a link or directory`);
+    if (state.kind === 'mode')
+        throw new SecretFileError(`${file} has mode ${state.mode.toString(8)}; run \`chmod 600 ${file}\` so only you can read it`);
+    return parseSecretFile(await readFile(file, 'utf8'), file, env);
+}
+export function secretFileTemplate(vars, familyTitle) {
+    const lines = [
+        `# ${familyTitle} API account. sideby loads these variables only into this account's process.`,
+        '# Uncomment and fill in. Keep this file private (mode 600).',
+        ...vars.map((v) => `# ${v}=`),
+        '',
+    ];
+    return lines.join('\n');
+}

package/dist/src/core/share-mode-names.d.ts

@@ -0,0 +1 @@
+export declare const SHARE_MODES: readonly ["link", "copy", "link-or-copy", "link-or-local", "local", "local-if-api", "info", "json-key"];

package/dist/src/core/share-mode-names.js

@@ -0,0 +1,10 @@
+export const SHARE_MODES = [
+    'link',
+    'copy',
+    'link-or-copy',
+    'link-or-local',
+    'local',
+    'local-if-api',
+    'info',
+    'json-key',
+];

package/dist/src/core/share-modes.d.ts

@@ -0,0 +1,24 @@
+import type { Account, CheckResult, SharedItemDef } from '../types.ts';
+export interface ItemContext {
+    account: Account;
+    item: SharedItemDef;
+    /** Resolved main-side path. */
+    mainPath: string;
+    /** Path inside the Account directory. */
+    accountPath: string;
+    /** The Account directory; every repair must stay inside it. */
+    accountDir: string;
+    /** Allows `json-key` to remove entries the Account has but the main file does not. */
+    force: boolean;
+}
+/** `counted` is false for `info` items, which never count toward the shared total. */
+export interface ItemCheck {
+    counted: boolean;
+    results: CheckResult[];
+}
+export declare function credentialModeFinding(item: string, path: string, mode: number): CheckResult;
+export declare function checkItem(ctx: ItemContext): Promise<ItemCheck>;
+export declare function itemPaths(home: string, mainDir: string, accountDir: string, item: SharedItemDef): {
+    mainPath: string;
+    accountPath: string;
+};