sideby 0.0.0-stage → 0.1.0

package/dist/testing/demo.js

@@ -0,0 +1,50 @@
+export const DEMO_ITEMS = [
+    { path: 'skills', mode: 'link' },
+    { path: 'rules.md', mode: 'link' },
+    { path: 'hooks', mode: 'copy', hostMessage: 'hooks must be a real directory' },
+    { path: 'theme.json', mode: 'link-or-copy' },
+    { path: 'trusted.toml', mode: 'link-or-local' },
+    { path: 'cli.json', mode: 'local' },
+    { path: 'config.toml', mode: 'local-if-api' },
+    { path: 'auth.json', mode: 'info', credential: true, noSymlink: true },
+    { path: '.demo.json', mode: 'json-key', key: 'servers', mainPath: '.demo.json', credential: true },
+];
+export function demoFamily(overrides = {}) {
+    return {
+        id: 'demo',
+        title: 'Demo',
+        bin: 'demo',
+        installUrl: 'https://example.invalid/demo',
+        selectVar: 'DEMO_HOME',
+        layout: { main: '.demo', account: '.demo-<name>' },
+        hijackVars: ['DEMO_API_KEY', 'DEMO_BASE_URL'],
+        apiVars: ['DEMO_BASE_URL', 'DEMO_API_KEY'],
+        sharedItems: DEMO_ITEMS,
+        login: { args: ['login'], hint: 'run demo login' },
+        ...overrides,
+    };
+}
+export function demoPlugin(def = demoFamily(), extra) {
+    return {
+        name: 'demo-family',
+        async register(api) {
+            api.family(def);
+            await extra?.(api);
+        },
+    };
+}
+export function asBuiltin(plugin, defaultEnabled = true) {
+    return { plugin, version: '0.0.0-test', description: 'test', defaultEnabled };
+}
+/** Populates a Main Account with one source for every demo Shared Item. */
+export async function seedDemoMain(write) {
+    await write('.demo/skills/a/SKILL.md', '# a\n');
+    await write('.demo/rules.md', 'rules\n');
+    await write('.demo/hooks/pre.sh', '#!/bin/sh\n', 0o755);
+    await write('.demo/theme.json', '{"dark":true}\n');
+    await write('.demo/trusted.toml', 'trusted = []\n');
+    await write('.demo/cli.json', '{"model":"x"}\n');
+    await write('.demo/config.toml', 'model = "main"\n');
+    await write('.demo/auth.json', '{"token":"fake-main"}\n', 0o600);
+    await write('.demo.json', '{"servers":{"a":{"cmd":"a"}},"user":"main"}\n', 0o600);
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,36 @@
+import type { Env } from '../src/types.ts';
+export interface FakeHome {
+    home: string;
+    /** Directory prepended to PATH; fake Host binaries live here. */
+    bin: string;
+    /** Environment for code under test: HOME, XDG dirs and PATH all point inside the fake HOME. */
+    env: Env;
+    path(...parts: string[]): string;
+    write(rel: string, data: string, mode?: number): Promise<string>;
+    mkdir(rel: string): Promise<string>;
+}
+/** Runs `fn` with a fresh fake HOME and removes it afterwards. */
+export declare function withFakeHome<T>(fn: (h: FakeHome) => Promise<T>): Promise<T>;
+export interface FakeHostOptions {
+    exitCode?: number;
+    /** Signal the fake Host sends itself after recording, for example `SIGTERM`. */
+    selfSignal?: string;
+    /** Seconds to sleep before exiting, so tests can signal it. */
+    sleep?: number;
+}
+/**
+ * Installs a fake Host executable named `name` that appends its argv, selected env and received signals
+ * to `<bin>/<name>.log` as JSON lines.
+ */
+export declare function fakeHost(h: FakeHome, name: string, opts?: FakeHostOptions): Promise<string>;
+export interface HostRecord {
+    argv: string[];
+    env: Record<string, string>;
+    pid: number;
+    signal?: string;
+}
+export declare function readHostLog(h: FakeHome, name: string): Promise<HostRecord[]>;
+/** Snapshot of every path under `root` with its type, symlink target or content hash, for write audits. */
+export declare function snapshot(root: string): Promise<Map<string, string>>;
+/** Lists keys whose snapshot value differs, appeared or disappeared. */
+export declare function diffSnapshots(before: Map<string, string>, after: Map<string, string>): string[];

package/dist/testing/index.js

@@ -0,0 +1,117 @@
+// Test helpers for sideby and its Plugins. Every test runs against a throwaway HOME and fake Host binaries,
+// so nothing a test does can reach the developer's real accounts.
+import { chmod, mkdir, mkdtemp, readdir, readFile, readlink, realpath, rm, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** Runs `fn` with a fresh fake HOME and removes it afterwards. */
+export async function withFakeHome(fn) {
+    const base = await realpath(await mkdtemp(join(tmpdir(), 'sideby-test-')));
+    const home = join(base, 'home');
+    const bin = join(base, 'bin');
+    await mkdir(home, { recursive: true });
+    await mkdir(bin, { recursive: true });
+    const realHome = homedir();
+    if (home === realHome || home.startsWith(`${realHome}/.`))
+        throw new Error('fake HOME resolved inside the real HOME');
+    const env = {
+        HOME: home,
+        XDG_CONFIG_HOME: join(home, '.config'),
+        XDG_STATE_HOME: join(home, '.local', 'state'),
+        PATH: `${bin}:/usr/bin:/bin`,
+        NO_COLOR: '1',
+    };
+    const h = {
+        home,
+        bin,
+        env,
+        path: (...parts) => join(home, ...parts),
+        async write(rel, data, mode = 0o644) {
+            const p = join(home, rel);
+            await mkdir(join(p, '..'), { recursive: true });
+            await writeFile(p, data, { mode });
+            await chmod(p, mode);
+            return p;
+        },
+        async mkdir(rel) {
+            const p = join(home, rel);
+            await mkdir(p, { recursive: true });
+            return p;
+        },
+    };
+    try {
+        return await fn(h);
+    }
+    finally {
+        await rm(base, { recursive: true, force: true });
+    }
+}
+/**
+ * Installs a fake Host executable named `name` that appends its argv, selected env and received signals
+ * to `<bin>/<name>.log` as JSON lines.
+ */
+export async function fakeHost(h, name, opts = {}) {
+    const log = join(h.bin, `${name}.log`);
+    const script = `#!/usr/bin/env node
+const fs = require('node:fs')
+const log = ${JSON.stringify(log)}
+const rec = (o) => fs.appendFileSync(log, JSON.stringify(o) + '\\n')
+rec({ argv: process.argv.slice(2), env: process.env, pid: process.pid })
+for (const s of ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']) process.on(s, () => { rec({ signal: s }); process.exit(${opts.sleep ? 100 : 0}) })
+const finish = () => {
+  ${opts.selfSignal ? `process.removeAllListeners(${JSON.stringify(opts.selfSignal)}); process.kill(process.pid, ${JSON.stringify(opts.selfSignal)})` : `process.exit(${opts.exitCode ?? 0})`}
+}
+${opts.sleep ? `setTimeout(finish, ${Math.round(opts.sleep * 1000)})` : 'finish()'}
+`;
+    const p = join(h.bin, name);
+    await writeFile(p, script.replace('#!/usr/bin/env node', `#!${process.execPath}`), { mode: 0o755 });
+    return p;
+}
+export async function readHostLog(h, name) {
+    try {
+        const raw = await readFile(join(h.bin, `${name}.log`), 'utf8');
+        return raw
+            .split('\n')
+            .filter(Boolean)
+            .map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}
+/** Snapshot of every path under `root` with its type, symlink target or content hash, for write audits. */
+export async function snapshot(root) {
+    const out = new Map();
+    const { createHash } = await import('node:crypto');
+    const { lstat } = await import('node:fs/promises');
+    async function walk(dir, rel) {
+        let entries;
+        try {
+            entries = await readdir(dir);
+        }
+        catch {
+            return;
+        }
+        for (const e of entries.sort()) {
+            const p = join(dir, e);
+            const r = rel ? `${rel}/${e}` : e;
+            const st = await lstat(p);
+            if (st.isSymbolicLink())
+                out.set(r, `link:${await readlink(p)}`);
+            else if (st.isDirectory()) {
+                out.set(r, `dir:${(st.mode & 0o777).toString(8)}`);
+                await walk(p, r);
+            }
+            else
+                out.set(r, `file:${(st.mode & 0o777).toString(8)}:${createHash('sha256')
+                    .update(await readFile(p))
+                    .digest('hex')}`);
+        }
+    }
+    await walk(root, '');
+    return out;
+}
+/** Lists keys whose snapshot value differs, appeared or disappeared. */
+export function diffSnapshots(before, after) {
+    const keys = new Set([...before.keys(), ...after.keys()]);
+    return [...keys].filter((k) => before.get(k) !== after.get(k)).sort();
+}

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "sideby",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Run every AI coding account side by side: Claude Code, Codex, Grok and pi, with one shared config and a quota panel.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "grok",
+    "pi",
+    "multi-account",
+    "ai-coding",
+    "cli",
+    "quota"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Adonis0123/sideby.git"
+  },
+  "homepage": "https://github.com/Adonis0123/sideby#readme",
+  "bugs": "https://github.com/Adonis0123/sideby/issues",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "bin": {
+    "sideby": "dist/src/cli/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "skills",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/src/cli/main.js && node scripts/write-build-id.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "node --test --test-concurrency=4 \"src/**/*.test.ts\" \"testing/**/*.test.ts\"",
+    "schemas": "node src/cli/schemas.ts",
+    "leak-check": "sh scripts/leak-check.sh",
+    "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm leak-check",
+    "version": "node scripts/sync-skill-version.ts && git add skills/sideby/SKILL.md"
+  },
+  "dependencies": {
+    "typebox": "^1.3.34"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@types/node": "^22.18.0",
+    "typescript": "^7.0.2"
+  },
+  "packageManager": "pnpm@10.15.0"
+}

package/schemas/alias.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/alias.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "ok",
+    "alias",
+    "status"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "ok": {
+      "type": "boolean",
+      "description": "False when a config `shellInitFile` was not rewritten."
+    },
+    "alias": {
+      "type": "string"
+    },
+    "status": {
+      "anyOf": [
+        {
+          "type": "string",
+          "const": "added"
+        },
+        {
+          "type": "string",
+          "const": "exists"
+        },
+        {
+          "type": "string",
+          "const": "removed"
+        },
+        {
+          "type": "string",
+          "const": "absent"
+        }
+      ]
+    },
+    "account": {
+      "type": "string"
+    },
+    "args": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Host arguments `sideby run <alias>` adds."
+    },
+    "shellInitFiles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "shell",
+          "path",
+          "ok"
+        ],
+        "properties": {
+          "shell": {
+            "anyOf": [
+              {
+                "type": "string",
+                "const": "zsh"
+              },
+              {
+                "type": "string",
+                "const": "bash"
+              }
+            ]
+          },
+          "path": {
+            "type": "string"
+          },
+          "ok": {
+            "type": "boolean"
+          },
+          "action": {
+            "anyOf": [
+              {
+                "type": "string",
+                "const": "written"
+              },
+              {
+                "type": "string",
+                "const": "unchanged"
+              }
+            ]
+          },
+          "message": {
+            "type": "string"
+          }
+        }
+      },
+      "description": "One entry per config `shellInitFile`, rewritten after the change."
+    }
+  },
+  "title": "sideby alias add|rm --json"
+}

package/schemas/app-install.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/app-install.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "platform",
+    "path",
+    "files",
+    "mode",
+    "node",
+    "entry",
+    "updated",
+    "hints"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "platform": {
+      "anyOf": [
+        {
+          "type": "string",
+          "const": "darwin"
+        },
+        {
+          "type": "string",
+          "const": "linux"
+        }
+      ]
+    },
+    "path": {
+      "type": "string"
+    },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "mode": {
+      "anyOf": [
+        {
+          "type": "string",
+          "const": "panel"
+        },
+        {
+          "type": "string",
+          "const": "url"
+        }
+      ]
+    },
+    "url": {
+      "type": "string"
+    },
+    "node": {
+      "type": "string"
+    },
+    "entry": {
+      "type": "string"
+    },
+    "updated": {
+      "type": "boolean"
+    },
+    "hints": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "title": "sideby app install --json"
+}

package/schemas/app-uninstall.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/app-uninstall.json",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "platform",
+    "removed",
+    "skipped"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "platform": {
+      "anyOf": [
+        {
+          "type": "string",
+          "const": "darwin"
+        },
+        {
+          "type": "string",
+          "const": "linux"
+        }
+      ]
+    },
+    "removed": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "skipped": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "path",
+          "reason"
+        ],
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "reason": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "title": "sideby app uninstall --json"
+}

package/schemas/config.json

@@ -0,0 +1,166 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sideby/config.json",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "accounts": {
+      "type": "object",
+      "patternProperties": {
+        "^.*$": {
+          "type": "object",
+          "properties": {
+            "args": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "description": "Per-Account settings keyed by `<family>:<name>`."
+    },
+    "aliases": {
+      "type": "object",
+      "patternProperties": {
+        "^[A-Za-z_][A-Za-z0-9_-]*$": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "object",
+              "required": [
+                "account"
+              ],
+              "properties": {
+                "account": {
+                  "type": "string",
+                  "pattern": "^[^:]+:.+$",
+                  "description": "The Account ref, `<family>:<name>`."
+                },
+                "args": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Host arguments `sideby run <alias>` adds after the Account `args`, before the user’s."
+                }
+              },
+              "additionalProperties": false
+            }
+          ]
+        }
+      },
+      "description": "Short shell function names created by `sideby shell-init`, mapped to an Account ref or to `{ account, args }`."
+    },
+    "ignore": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Account refs that are not Accounts."
+    },
+    "pluginDirs": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Absolute or `~/` paths of Plugin directories."
+    },
+    "plugins": {
+      "type": "object",
+      "patternProperties": {
+        "^.*$": {
+          "type": "object",
+          "patternProperties": {
+            "^.*$": {}
+          }
+        }
+      },
+      "description": "Per-Plugin settings; `enabled: false` turns a Plugin off."
+    },
+    "extraSharedItems": {
+      "type": "object",
+      "patternProperties": {
+        "^.*$": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "path",
+              "mode"
+            ],
+            "properties": {
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$)).+$"
+              },
+              "mode": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "const": "link"
+                  },
+                  {
+                    "type": "string",
+                    "const": "copy"
+                  },
+                  {
+                    "type": "string",
+                    "const": "link-or-copy"
+                  },
+                  {
+                    "type": "string",
+                    "const": "link-or-local"
+                  },
+                  {
+                    "type": "string",
+                    "const": "local"
+                  },
+                  {
+                    "type": "string",
+                    "const": "local-if-api"
+                  },
+                  {
+                    "type": "string",
+                    "const": "info"
+                  }
+                ]
+              },
+              "noSymlink": {
+                "type": "boolean"
+              },
+              "credential": {
+                "type": "boolean"
+              }
+            },
+            "additionalProperties": false
+          }
+        }
+      }
+    },
+    "shellInitFile": {
+      "type": "object",
+      "properties": {
+        "zsh": {
+          "type": "string",
+          "minLength": 1
+        },
+        "bash": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false,
+      "description": "Absolute or `~/` paths of files sideby rewrites with the `sideby shell-init <shell>` output whenever it adds an Account or an alias; source the file from your shell rc."
+    }
+  },
+  "additionalProperties": false,
+  "title": "sideby config"
+}