sideby 0.0.0-stage → 0.2.1

package/dist/src/types.d.ts

@@ -0,0 +1,285 @@
+export type ShareMode = 'link' | 'copy' | 'link-or-copy' | 'link-or-local' | 'local' | 'local-if-api' | 'info' | 'json-key';
+export interface SharedItemDef {
+    /** Path inside the Account directory, for example `skills` or `.claude.json`. */
+    path: string;
+    mode: ShareMode;
+    /** Main-side source relative to HOME, when it does not live in the Main Account directory (`.claude.json`). */
+    mainPath?: string;
+    /** For `json-key`: the top-level key mirrored from the main file. */
+    key?: string;
+    /** The Host refuses to start when this path is a symlink (Grok sandbox). */
+    noSymlink?: boolean;
+    /** Holds credentials: must be a regular file with mode 600. Contents are never read. */
+    credential?: boolean;
+    /** Host message quoted when the item breaks a Host rule. */
+    hostMessage?: string;
+}
+export interface FamilyLayout {
+    /** Main Account directory relative to HOME, for example `.claude` or `.pi/agent`. */
+    main: string;
+    /** Other Accounts relative to HOME, with `<name>` in the first path segment: `.claude-<name>`, `.pi-<name>/agent`. */
+    account: string;
+}
+export type LoginState = 'logged-in' | 'logged-out' | 'unknown';
+/**
+ * A Family's mark for the Panel: one SVG path in a 24x24 view box, drawn inline. sideby checks it when the
+ * Plugin registers; an invalid logo is dropped with a plugin error and the Panel shows the Family's initials.
+ */
+export interface FamilyLogo {
+    /** SVG path data: only commands, numbers, spaces, commas, dots, `+` and `-`. At most 20000 characters. */
+    path: string;
+    /** Hex brand color such as `#D97757`. Without one the mark uses the text color, so it works in light and dark mode. */
+    color?: string;
+    /** Name of the mark for tooltips; defaults to the Family title. */
+    title?: string;
+    fillRule?: 'nonzero' | 'evenodd';
+}
+export interface FamilyDef {
+    id: string;
+    title: string;
+    /** Mark shown on the Panel's cards, lists and the Tool select; without one the Panel shows the id's initials. */
+    logo?: FamilyLogo;
+    /** Host executable looked up on PATH. */
+    bin: string;
+    installUrl: string;
+    /** Environment variable that selects the Account directory. Not set for the Main Account. */
+    selectVar: string;
+    layout: FamilyLayout;
+    /**
+     * Entries that prove a directory is this Family's Account (besides a Secret File or an empty directory).
+     * Defaults to the Shared Item paths; set it when a shared name is generic, like Claude's `plugins`.
+     */
+    markers?: string[];
+    /**
+     * Whether a Secret File makes an Account an API Account (default true). pi keeps `proxy.env` in every
+     * Account for provider keys, so for pi it is loaded at Launch but says nothing about the login.
+     */
+    secretFileMeansApi?: boolean;
+    /** Cleared before every Launch, for every Account. */
+    hijackVars: string[];
+    /** Variables written, commented out, into a new API Account's Secret File. */
+    apiVars: string[];
+    sharedItems: SharedItemDef[];
+    /** Arguments for the Host's sign-in command, or null when sign-in happens inside the Host. */
+    login: {
+        args: string[] | null;
+        hint: string;
+    };
+    /** Arguments sideby adds before the Account's and the user's arguments. */
+    defaultArgs?(account: Account, userArgs: readonly string[]): string[];
+    loginState?(account: Account): Promise<LoginState>;
+    model?(account: Account): Promise<string | undefined>;
+    /**
+     * Who the Account is signed in as, from the Host's own login file: identity fields such as the email and the
+     * organization only, never a token or any other credential value (ADR-0003). Return undefined when unknown; an
+     * error is treated the same way and never shown as a problem.
+     */
+    identity?(account: Account): Promise<AccountIdentity | undefined>;
+    readQuota?(account: Account, ctx: ReadContext): Promise<QuotaResult>;
+    readUsage?(account: Account, ctx: ReadContext): Promise<UsageResult>;
+    /** One-time, reversible change that lets the Host report Quota (Claude: status line wrapper). */
+    quotaSetup?: QuotaSetup;
+    /**
+     * The session these Host arguments resume by id (UUID-shaped), or undefined when they start a new session or
+     * pick one another way. With `sessionWrittenAt` it lets `sideby resume` find the Account (ADR-0007).
+     */
+    resumedSession?(args: readonly string[]): string | undefined;
+    /** When the Account holds the session, the last write time of its file in ms; otherwise undefined. */
+    sessionWrittenAt?(account: Account, sessionId: string): Promise<number | undefined>;
+}
+/** Identity fields of a signed-in Account. */
+export interface AccountIdentity {
+    email?: string;
+    /** Organization or team, when it is not just the personal default. */
+    org?: string;
+}
+export interface QuotaSetupPlan {
+    /** `enabled`: already on; `ready`: apply would make `diff`; `blocked`: cannot apply, see `message`. */
+    status: 'enabled' | 'ready' | 'blocked';
+    /** File the change touches. */
+    file: string;
+    /** Unified diff of the change, empty when nothing would change. */
+    diff: string;
+    message: string;
+}
+export interface QuotaSetup {
+    /** One sentence shown before the user confirms. */
+    summary: string;
+    plan(ctx: ReadContext): Promise<QuotaSetupPlan>;
+    /** Re-plans and applies only when the plan is `ready`. */
+    apply(ctx: ReadContext): Promise<QuotaSetupPlan>;
+    /** Restores the original bytes only if the file is still exactly what `apply` wrote. */
+    teardown(ctx: ReadContext): Promise<{
+        ok: boolean;
+        message: string;
+        diff?: string;
+    }>;
+}
+export interface Account {
+    family: string;
+    /** `main` for the Main Account. */
+    name: string;
+    /** `<family>:<name>` */
+    ref: string;
+    dir: string;
+    isMain: boolean;
+    kind: 'subscription' | 'api';
+    /** Path of the Secret File for API Accounts. */
+    secretFile?: string;
+}
+export interface ReadContext {
+    home: string;
+    now: Date;
+    /** sideby state directory (quota caches live here). */
+    stateDir: string;
+    /** sideby's own environment (PATH lookups); never the Host's. */
+    env: Env;
+}
+export interface QuotaWindow {
+    /** `5h`, `7d`, or `<n>m` for unknown window lengths. */
+    label: string;
+    windowMinutes: number;
+    usedPercent: number;
+    /** ISO timestamp. */
+    resetsAt: string;
+}
+export type QuotaUnavailableReason = 'not-enabled' | 'no-session' | 'unrecognized' | 'no-source' | 'api-account';
+export type QuotaResult = {
+    status: 'ok';
+    windows: QuotaWindow[];
+    observedAt: string;
+    source: string;
+    plan?: string;
+} | {
+    status: 'unavailable';
+    reason: QuotaUnavailableReason;
+    detail?: string;
+};
+export interface TokenTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+}
+export type UsageResult = ({
+    status: 'ok';
+    days: number;
+    sessions: number;
+    /**
+     * Tokens per local calendar day (`YYYY-MM-DD`), `days` entries ending today, oldest first, days without
+     * records as 0. It can sum to less than `totalTokens`, which also covers the part of the oldest day
+     * inside the rolling window.
+     */
+    daily?: {
+        date: string;
+        totalTokens: number;
+    }[];
+    /** ISO time of the newest record the reader saw, not later than now. */
+    lastActivityAt?: string;
+} & TokenTotals) | {
+    status: 'unavailable';
+    reason: 'no-source' | 'no-session' | 'unrecognized';
+    detail?: string;
+};
+export type FindingLevel = 'ok' | 'warn' | 'fail';
+export interface FixResult {
+    ok: boolean;
+    message: string;
+}
+export interface Finding {
+    level: FindingLevel;
+    /** Account ref the Finding is about. */
+    account: string;
+    /** Shared Item path or check name. */
+    item: string;
+    /** Stable machine code such as `link.real-file`. */
+    code: string;
+    message: string;
+    /** What the user should do; never contains credential values. */
+    hint?: string;
+    /** `core` or the Plugin name. */
+    source: string;
+    fixable: boolean;
+    /** Present when `fixable`; not serialized. */
+    fix?: () => Promise<FixResult>;
+}
+/** What a `doctor.check` hook returns; sideby fills `account` and `source`. */
+export type CheckResult = Omit<Finding, 'account' | 'source' | 'fixable'> & {
+    fixable?: boolean;
+};
+export type Env = Record<string, string | undefined>;
+export interface LaunchContext {
+    account: Account;
+    family: FamilyDef;
+    /** Environment the Host will receive; mutate to change it. */
+    env: Env;
+    /** Arguments the Host will receive; mutate to change them. */
+    args: string[];
+    config: Record<string, unknown>;
+    /** `run` or `login`. */
+    command: 'run' | 'login';
+}
+export interface CreateBeforeContext {
+    family: FamilyDef;
+    /** Name of the Account about to be created, already checked against the name rules. */
+    name: string;
+    /** Whether it will be an API Account (`sideby new --api`, or "API key account" in the Panel). */
+    api: boolean;
+    /** The Family's existing Accounts, the Main Account included. */
+    accounts: Account[];
+    config: Record<string, unknown>;
+}
+export interface CreatedContext {
+    account: Account;
+    family: FamilyDef;
+    config: Record<string, unknown>;
+    log(message: string): void;
+}
+export interface DoctorContext {
+    account: Account;
+    family: FamilyDef;
+    config: Record<string, unknown>;
+}
+export interface HookFilter {
+    family?: string;
+}
+export interface HookEvents {
+    'launch.before': {
+        ctx: LaunchContext;
+        result: void;
+    };
+    'account.create.before': {
+        ctx: CreateBeforeContext;
+        result: void;
+    };
+    'account.created': {
+        ctx: CreatedContext;
+        result: void;
+    };
+    'doctor.check': {
+        ctx: DoctorContext;
+        result: CheckResult[] | undefined;
+    };
+}
+export type HookEvent = keyof HookEvents;
+export type HookHandler<E extends HookEvent> = (ctx: HookEvents[E]['ctx']) => HookEvents[E]['result'] | Promise<HookEvents[E]['result']>;
+export interface PluginFs {
+    /** Atomic write via a temp file in the same directory; `mode` defaults to 0o600. */
+    writeFileAtomic(path: string, data: string | Uint8Array, mode?: number): Promise<void>;
+}
+export interface PluginApi {
+    family(def: FamilyDef): void;
+    on<E extends HookEvent>(event: E, handler: HookHandler<E>): void;
+    on<E extends HookEvent>(event: E, filter: HookFilter, handler: HookHandler<E>): void;
+    /**
+     * Returns an error that, when thrown from `launch.before` or `account.create.before`, stops the Launch or the
+     * new Account with this message. Say what to do instead: the CLI and the Panel show it as is.
+     */
+    abort(message: string): Error;
+    fs: PluginFs;
+}
+export interface Plugin {
+    name: string;
+    register(api: PluginApi): void | Promise<void>;
+}

package/dist/src/types.js

@@ -0,0 +1,3 @@
+// Public contract shared by sideby core, built-in Families and third-party Plugins.
+// Plugins may only `import type` from this module (ADR-0002); values reach them through PluginApi.
+export {};

package/dist/testing/demo.d.ts

@@ -0,0 +1,8 @@
+import type { BuiltinPlugin } from '../src/plugins/loader.ts';
+import type { FamilyDef, Plugin, SharedItemDef } from '../src/types.ts';
+export declare const DEMO_ITEMS: SharedItemDef[];
+export declare function demoFamily(overrides?: Partial<FamilyDef>): FamilyDef;
+export declare function demoPlugin(def?: FamilyDef, extra?: Plugin['register']): Plugin;
+export declare function asBuiltin(plugin: Plugin, defaultEnabled?: boolean): BuiltinPlugin;
+/** Populates a Main Account with one source for every demo Shared Item. */
+export declare function seedDemoMain(write: (rel: string, data: string, mode?: number) => Promise<string>): Promise<void>;

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,118 @@
+// 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')
+// Handlers first: tests signal the Host as soon as the start record appears.
+for (const s of ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']) process.on(s, () => { rec({ signal: s }); process.exit(${opts.sleep ? 100 : 0}) })
+rec({ argv: process.argv.slice(2), env: process.env, pid: process.pid })
+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.2.1",
+  "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"
+}