sideby 0.0.0-stage → 0.1.0

package/dist/src/core/share-modes.js

@@ -0,0 +1,405 @@
+import { chmod, mkdir, readFile, symlink, unlink } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { assertInside, fileHash, isEmptyDir, linksTo, lstatOrNull, permBits, realpathOrNull, replaceWithCopy, sameContent, statOrNull, writeIfUnchanged, } from './fs-safe.js';
+function kindOf(st) {
+    if (!st)
+        return 'missing';
+    if (st.isSymbolicLink())
+        return 'link';
+    if (st.isFile())
+        return 'file';
+    if (st.isDirectory())
+        return 'dir';
+    return 'other';
+}
+async function classify(ctx) {
+    const st = await lstatOrNull(ctx.accountPath);
+    const k = kindOf(st);
+    if (k !== 'link')
+        return { kind: k, st };
+    return { kind: (await linksTo(ctx.accountPath, ctx.mainPath)) ? 'link-ok' : 'link-other', st };
+}
+const ok = (item) => ({ level: 'ok', item, code: 'ok', message: 'ok' });
+function hostNote(item) {
+    return item.hostMessage ? ` (host says: "${item.hostMessage}")` : '';
+}
+async function makeLink(ctx) {
+    await mkdir(dirname(ctx.accountPath), { recursive: true });
+    await symlink(ctx.mainPath, ctx.accountPath);
+    return { ok: true, message: `linked ${ctx.item.path}` };
+}
+async function makeCopy(ctx) {
+    await mkdir(dirname(ctx.accountPath), { recursive: true });
+    await replaceWithCopy(ctx.mainPath, ctx.accountPath);
+    return { ok: true, message: `copied ${ctx.item.path} from the main account` };
+}
+/** Replaces a symlink that points at the main item with a real copy; refuses any other link. */
+async function linkToCopy(ctx) {
+    if (!(await linksTo(ctx.accountPath, ctx.mainPath)))
+        return { ok: false, message: `${ctx.item.path} no longer points at the main account; left unchanged` };
+    await unlink(ctx.accountPath);
+    return makeCopy(ctx);
+}
+function realConflict(ctx, what) {
+    const p = ctx.accountPath;
+    return {
+        level: 'fail',
+        item: ctx.item.path,
+        code: 'link.real-file',
+        message: `${ctx.item.path} is a real ${what}; expected a link to the main account`,
+        hint: `sideby never replaces it. Keep it with: mv "${p}" "${p}.local" && ln -s "${ctx.mainPath}" "${p}"`,
+    };
+}
+/** Whether this item may legitimately be a link in this Account. */
+function acceptsLink(ctx) {
+    const { item } = ctx;
+    if (item.noSymlink)
+        return false;
+    if (item.mode === 'local-if-api')
+        return ctx.account.kind !== 'api';
+    return item.mode === 'link' || item.mode === 'link-or-copy' || item.mode === 'link-or-local';
+}
+/** A link that does not resolve to the main item: dangling is a failure, a deliberate other target a warning. */
+async function wrongLink(ctx) {
+    const target = await realpathOrNull(ctx.accountPath);
+    if (target && !acceptsLink(ctx))
+        return {
+            level: 'fail',
+            item: ctx.item.path,
+            code: 'symlink-forbidden',
+            message: `${ctx.item.path} must not be a link (it points to ${target})${hostNote(ctx.item)}`,
+            hint: `sideby never re-points or replaces links it did not create. Replace it yourself: rm "${ctx.accountPath}" && cp -R "${ctx.mainPath}" "${ctx.accountPath}"`,
+        };
+    if (target)
+        return {
+            level: 'warn',
+            item: ctx.item.path,
+            code: 'link.other-target',
+            message: `${ctx.item.path} links to ${target} instead of the main account's ${ctx.item.path}`,
+            hint: 'fine if intended; sideby never re-points links',
+        };
+    return {
+        level: 'fail',
+        item: ctx.item.path,
+        code: 'link.dangling',
+        message: `${ctx.item.path} is a dangling link`,
+        hint: `sideby never re-points links. Inspect it with: ls -l "${ctx.accountPath}"`,
+    };
+}
+function missingFix(ctx, useCopy) {
+    return {
+        level: 'fail',
+        item: ctx.item.path,
+        code: 'missing',
+        message: `${ctx.item.path} is missing`,
+        hint: 'run `sideby doctor --fix`',
+        fixable: true,
+        fix: () => (useCopy ? makeCopy(ctx) : makeLink(ctx)),
+    };
+}
+async function compareCopy(ctx, mainSt, kind) {
+    const item = ctx.item.path;
+    const mainKind = mainSt.isDirectory() ? 'dir' : 'file';
+    if (kind !== mainKind)
+        return {
+            level: 'fail',
+            item,
+            code: 'copy.type-mismatch',
+            message: `${item} is a ${kind} but the main account has a ${mainKind}`,
+            hint: 'sideby does not change the type of an existing item; move it aside and run `sideby doctor --fix`',
+        };
+    if (await sameContent(ctx.accountPath, ctx.mainPath))
+        return ok(item);
+    if (mainKind === 'dir' && (await isEmptyDir(ctx.mainPath)))
+        return {
+            level: 'warn',
+            item,
+            code: 'copy.main-empty',
+            message: `${item} differs, but the main account's copy is empty; not mirroring an empty directory`,
+        };
+    return {
+        level: 'fail',
+        item,
+        code: 'copy.stale',
+        message: `${item} is an outdated copy of the main account`,
+        hint: 'run `sideby doctor --fix`',
+        fixable: true,
+        fix: () => makeCopy(ctx),
+    };
+}
+async function checkCopyLike(ctx, mainSt, allowLink) {
+    const { kind } = await classify(ctx);
+    const item = ctx.item.path;
+    switch (kind) {
+        case 'link-ok':
+            if (allowLink)
+                return ok(item);
+            return {
+                level: 'fail',
+                item,
+                code: 'symlink-forbidden',
+                message: `${item} must be a real copy, not a link${hostNote(ctx.item)}`,
+                hint: 'run `sideby doctor --fix` to replace the link with a copy',
+                fixable: true,
+                fix: () => linkToCopy(ctx),
+            };
+        case 'link-other':
+            return await wrongLink(ctx);
+        case 'missing':
+            return missingFix(ctx, !allowLink);
+        case 'file':
+        case 'dir':
+            return compareCopy(ctx, mainSt, kind);
+        default:
+            return {
+                level: 'fail',
+                item,
+                code: 'unsupported-type',
+                message: `${item} is not a file, directory or link`,
+            };
+    }
+}
+async function checkJsonKey(ctx) {
+    const item = `${ctx.item.path}#${ctx.item.key}`;
+    const key = ctx.item.key;
+    const accSt = await lstatOrNull(ctx.accountPath);
+    if (accSt?.isSymbolicLink())
+        return {
+            level: 'fail',
+            item,
+            code: 'json-key.symlink',
+            message: `${ctx.item.path} is a symlink; sharing it would mix logins between accounts`,
+            hint: `replace it with the account's own file; sideby will not write through it even with --force`,
+        };
+    let mainVal;
+    let mainText;
+    try {
+        mainText = await readFile(ctx.mainPath, 'utf8');
+    }
+    catch {
+        return { level: 'ok', item, code: 'ok', message: 'main file absent; nothing to share' };
+    }
+    try {
+        mainVal = JSON.parse(mainText)[key];
+    }
+    catch {
+        return {
+            level: 'warn',
+            item,
+            code: 'json-key.main-unreadable',
+            message: `cannot read ${key} from the main file`,
+        };
+    }
+    if (mainVal === undefined)
+        return { level: 'ok', item, code: 'ok', message: `main file has no ${key}` };
+    if (!isPlainObject(mainVal))
+        return { level: 'fail', item, code: 'json-key.main-not-object', message: `main ${key} is not an object` };
+    const beforeHash = await fileHash(ctx.accountPath);
+    let acc = {};
+    if (beforeHash !== null) {
+        try {
+            const parsed = JSON.parse(await readFile(ctx.accountPath, 'utf8'));
+            if (!isPlainObject(parsed))
+                throw new Error('not an object');
+            acc = parsed;
+        }
+        catch {
+            return {
+                level: 'fail',
+                item,
+                code: 'json-key.not-object',
+                message: `${ctx.item.path} is not a JSON object; sideby will not rewrite it`,
+            };
+        }
+    }
+    const accVal = key in acc ? acc[key] : {};
+    if (!isPlainObject(accVal))
+        return {
+            level: 'fail',
+            item,
+            code: 'json-key.not-object',
+            message: `${key} in ${ctx.item.path} is not an object`,
+        };
+    if (canonical(accVal) === canonical(mainVal))
+        return ok(item);
+    const removed = Object.keys(accVal).filter((k) => !(k in mainVal));
+    const added = Object.keys(mainVal).filter((k) => !(k in accVal));
+    const detail = [
+        added.length ? `adds ${added.join(', ')}` : '',
+        removed.length ? `removes ${removed.join(', ')}` : '',
+    ]
+        .filter(Boolean)
+        .join('; ');
+    const write = async () => {
+        const next = `${JSON.stringify({ ...acc, [key]: mainVal }, null, 2)}\n`;
+        const done = await writeIfUnchanged(ctx.accountPath, beforeHash, next, 0o600);
+        return done
+            ? { ok: true, message: `synced ${key} (${detail || 'values changed'})` }
+            : { ok: false, message: `${ctx.item.path} changed while syncing; run doctor again` };
+    };
+    if (removed.length && !ctx.force)
+        return {
+            level: 'fail',
+            item,
+            code: 'json-key.would-remove',
+            message: `${key} differs from the main account and syncing would remove: ${removed.join(', ')}`,
+            hint: 'add them to the main account first, or run `sideby doctor --fix --force` to remove them',
+        };
+    return {
+        level: 'fail',
+        item,
+        code: 'json-key.drift',
+        message: `${key} differs from the main account (${detail || 'values changed'})`,
+        hint: 'run `sideby doctor --fix`',
+        fixable: true,
+        fix: write,
+    };
+}
+async function checkCredentialMode(ctx) {
+    const st = await lstatOrNull(ctx.accountPath);
+    if (!st?.isFile() || permBits(st) === 0o600)
+        return null;
+    return credentialModeFinding(ctx.item.path, ctx.accountPath, permBits(st));
+}
+export function credentialModeFinding(item, path, mode) {
+    return {
+        level: 'fail',
+        item,
+        code: 'credential.mode',
+        message: `${item} has mode ${mode.toString(8)}; credentials must be 600`,
+        hint: 'run `sideby doctor --fix`',
+        fixable: true,
+        fix: async () => {
+            await chmod(path, 0o600);
+            return { ok: true, message: `set ${item} to 600` };
+        },
+    };
+}
+export async function checkItem(ctx) {
+    const { item } = ctx;
+    const out = [];
+    if (isAbsolute(item.path) || item.path.split(/[\\/]/).includes('..'))
+        return {
+            counted: false,
+            results: [
+                {
+                    level: 'fail',
+                    item: item.path,
+                    code: 'path.invalid',
+                    message: `shared item path ${item.path} must be relative and stay inside the account directory`,
+                    hint: 'fix the path in the sideby config or the plugin that defines it',
+                },
+            ],
+        };
+    // Every repair re-checks, at the moment it runs, that it writes inside this Account only.
+    const guard = (r) => {
+        const fix = r.fix;
+        if (!fix)
+            return r;
+        return {
+            ...r,
+            fix: async () => {
+                await assertInside(ctx.accountDir, ctx.accountPath);
+                return fix();
+            },
+        };
+    };
+    const done = async (r, counted = true) => {
+        out.push(guard(r));
+        if (item.credential) {
+            const c = await checkCredentialMode(ctx);
+            if (c)
+                out.push(guard(c));
+        }
+        return { counted, results: out };
+    };
+    if (item.mode === 'info') {
+        const st = await lstatOrNull(ctx.accountPath);
+        if (item.noSymlink && st?.isSymbolicLink())
+            return done({
+                level: 'fail',
+                item: item.path,
+                code: 'symlink-forbidden',
+                message: `${item.path} must not be a link${hostNote(item)}`,
+                hint: `sideby does not copy credentials. Replace the link with the account's own file, e.g. log in again with \`sideby login ${ctx.account.ref}\``,
+            }, false);
+        return done(ok(item.path), false);
+    }
+    if (item.mode === 'json-key')
+        return done(await checkJsonKey(ctx));
+    // The main account has nothing to share here yet: not counted, but the Account's own entry must still
+    // respect Host rules (a dangling link, or a link where the Host refuses links, is still a problem).
+    const mainSt = await statOrNull(ctx.mainPath);
+    if (!mainSt) {
+        const st = await lstatOrNull(ctx.accountPath);
+        if (st?.isSymbolicLink() && (!(await realpathOrNull(ctx.accountPath)) || !acceptsLink(ctx)))
+            return done(await wrongLink(ctx), false);
+        return done(ok(item.path), false);
+    }
+    const isApi = ctx.account.kind === 'api';
+    const { kind } = await classify(ctx);
+    switch (item.mode) {
+        case 'link':
+            if (kind === 'link-ok')
+                return done(ok(item.path));
+            if (kind === 'missing')
+                return done(missingFix(ctx, false));
+            if (kind === 'link-other')
+                return done(await wrongLink(ctx));
+            return done(realConflict(ctx, kind === 'dir' ? 'directory' : 'file'));
+        case 'copy':
+            return done(await checkCopyLike(ctx, mainSt, false));
+        case 'link-or-copy':
+            return done(await checkCopyLike(ctx, mainSt, !item.noSymlink));
+        case 'link-or-local':
+            if (kind === 'link-ok' || kind === 'file' || kind === 'dir')
+                return done(ok(item.path));
+            if (kind === 'missing')
+                return done(missingFix(ctx, false));
+            return done(await wrongLink(ctx));
+        case 'local':
+            if (kind === 'file' || kind === 'dir')
+                return done(ok(item.path));
+            if (kind === 'missing')
+                return done(missingFix(ctx, true));
+            return done({
+                level: 'fail',
+                item: item.path,
+                code: 'local.is-link',
+                message: `${item.path} must be the account's own file, not a link${hostNote(item)}`,
+                hint: `sideby never replaces links here. Replace it yourself: rm "${ctx.accountPath}" && cp -R "${ctx.mainPath}" "${ctx.accountPath}"`,
+            });
+        case 'local-if-api':
+            if (!isApi)
+                return done(await checkCopyLike(ctx, mainSt, !item.noSymlink));
+            if (kind === 'file')
+                return done(ok(item.path));
+            if (kind === 'missing')
+                return done({
+                    level: 'fail',
+                    item: item.path,
+                    code: 'api.needs-own',
+                    message: `${item.path} is missing; an API account needs its own copy`,
+                    hint: `cp "${ctx.mainPath}" "${ctx.accountPath}" and edit it for this account's endpoint`,
+                });
+            return done({
+                level: 'fail',
+                item: item.path,
+                code: 'api.needs-own',
+                message: `${item.path} must be this API account's own file (found ${kind === 'link-ok' || kind === 'link-other' ? 'a link' : `a ${kind}`})`,
+                hint: 'an API account changes its endpoint here, so sharing it would change the main account too',
+            });
+    }
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function canonical(v) {
+    return JSON.stringify(v, (_k, val) => isPlainObject(val) ? Object.fromEntries(Object.entries(val).sort(([a], [b]) => a.localeCompare(b))) : val);
+}
+export function itemPaths(home, mainDir, accountDir, item) {
+    return {
+        mainPath: item.mainPath ? join(home, item.mainPath) : join(mainDir, item.path),
+        accountPath: join(accountDir, item.path),
+    };
+}

package/dist/src/core/shell-init.d.ts

@@ -0,0 +1,25 @@
+import type { Account } from '../types.ts';
+export declare const SHELLS: readonly ['zsh', 'bash'];
+export type Shell = (typeof SHELLS)[number];
+/** First line of every generated script; an existing file without it is never overwritten. */
+export declare const SHELL_INIT_HEADER = "# sideby shell-init: one function per account, plus aliases from the sideby config";
+/**
+ * The script for one shell, ending in a newline: exactly what `sideby shell-init <shell>` prints. zsh and bash
+ * read the same function syntax, so the shell only names the file it goes to.
+ */
+export declare function shellInitScript(accounts: readonly Account[], aliases: Readonly<Record<string, unknown>> | undefined): string;
+export interface ShellInitWrite {
+    shell: Shell;
+    /** The configured path, as written in the config (`~/…` kept). */
+    path: string;
+    ok: boolean;
+    /** `written`, or `unchanged` when the file already had this content. */
+    action?: 'written' | 'unchanged';
+    message?: string;
+}
+/**
+ * Writes `content` to the configured file atomically (temp file in the same directory, then rename), keeping its
+ * mode (0644 for a new file). Refuses a relative path and an existing file that sideby did not generate, so a
+ * mistyped `shellInitFile` can never replace a shell rc file.
+ */
+export declare function writeShellInitFile(shell: Shell, configured: string, home: string, content: string): Promise<ShellInitWrite>;

package/dist/src/core/shell-init.js

@@ -0,0 +1,61 @@
+// The shell functions `sideby shell-init` prints, and the optional files (config `shellInitFile`) sideby keeps
+// in sync with them whenever it adds an Account or an alias.
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { aliasProblem } from './config.js';
+import { realpathOrNull, statOrNull, writeFileAtomic } from './fs-safe.js';
+import { expandUserPath } from './paths.js';
+export const SHELLS = ['zsh', 'bash'];
+/** First line of every generated script; an existing file without it is never overwritten. */
+export const SHELL_INIT_HEADER = '# sideby shell-init: one function per account, plus aliases from the sideby config';
+const quote = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+/**
+ * The script for one shell, ending in a newline: exactly what `sideby shell-init <shell>` prints. zsh and bash
+ * read the same function syntax, so the shell only names the file it goes to.
+ */
+export function shellInitScript(accounts, aliases) {
+    const lines = [SHELL_INIT_HEADER];
+    for (const acc of accounts)
+        lines.push(`sideby-${acc.family}-${acc.name}() { command sideby run ${quote(acc.ref)} -- "$@"; }`);
+    // An alias function runs the alias itself, so `sideby run` reads its Account and arguments from the config.
+    for (const alias of Object.keys(aliases ?? {}))
+        if (!aliasProblem(alias))
+            lines.push(`${alias}() { command sideby run ${quote(alias)} -- "$@"; }`);
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Writes `content` to the configured file atomically (temp file in the same directory, then rename), keeping its
+ * mode (0644 for a new file). Refuses a relative path and an existing file that sideby did not generate, so a
+ * mistyped `shellInitFile` can never replace a shell rc file.
+ */
+export async function writeShellInitFile(shell, configured, home, content) {
+    const base = { shell, path: configured };
+    const expanded = expandUserPath(configured, home);
+    if (!expanded)
+        return { ...base, ok: false, message: `shellInitFile.${shell} must be an absolute or ~/ path` };
+    try {
+        // Follow a link (a dotfiles manager may link the file) and replace the real file.
+        const target = (await realpathOrNull(expanded)) ?? expanded;
+        const st = await statOrNull(target);
+        if (st && !st.isFile())
+            return { ...base, ok: false, message: `${configured} is not a regular file` };
+        if (st) {
+            const current = await readFile(target, 'utf8');
+            if (current === content)
+                return { ...base, ok: true, action: 'unchanged' };
+            if (current.trim() && !current.startsWith(SHELL_INIT_HEADER))
+                return {
+                    ...base,
+                    ok: false,
+                    message: `${configured} was not written by sideby shell-init; move it aside or point shellInitFile.${shell} at another file`,
+                };
+        }
+        else
+            await mkdir(dirname(target), { recursive: true });
+        await writeFileAtomic(target, content, st ? st.mode & 0o777 : 0o644);
+        return { ...base, ok: true, action: 'written' };
+    }
+    catch (err) {
+        return { ...base, ok: false, message: `cannot write ${configured}: ${err.message}` };
+    }
+}

package/dist/src/core/skill-check.d.ts

@@ -0,0 +1,11 @@
+import type { FamilyDef, Finding } from '../types.ts';
+export declare const SKILL_INSTALL = "npx skills add Adonis0123/sideby -g";
+/** `metadata.version` from a SKILL.md frontmatter, or null when there is none. */
+export declare function skillVersionOf(text: string): string | null;
+/**
+ * Checks, for each given Family, the sideby skill its Host reads: `<main>/skills/sideby`, and for Codex also
+ * `~/.agents/skills/sideby` (where `npx skills add -g` installs and Codex reads user skills). A file is read
+ * once per Family, so the result for one Family never depends on which others are checked with it. Findings
+ * are general and belong to that Family's Main Account.
+ */
+export declare function checkInstalledSkills(home: string, families: readonly FamilyDef[], version: string): Promise<Finding[]>;

package/dist/src/core/skill-check.js

@@ -0,0 +1,57 @@
+// Doctor's look at an installed sideby Agent Skill (spec §3.11). Read-only: a skill written for another
+// sideby version teaches commands this CLI may not have, so a version mismatch is a warning with the
+// reinstall command. Not installed is not a problem.
+import { readFile, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { mainDirOf } from './accounts.js';
+import { tildify } from './paths.js';
+export const SKILL_INSTALL = 'npx skills add Adonis0123/sideby -g';
+/** `metadata.version` from a SKILL.md frontmatter, or null when there is none. */
+export function skillVersionOf(text) {
+    const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1];
+    const meta = front && /^metadata:[ \t]*\r?\n((?:[ \t]+.*(?:\r?\n|$))*)/m.exec(front)?.[1];
+    return (meta && /^[ \t]+version:[ \t]*['"]?([^'"\s]+)/m.exec(meta)?.[1]) || null;
+}
+/**
+ * Checks, for each given Family, the sideby skill its Host reads: `<main>/skills/sideby`, and for Codex also
+ * `~/.agents/skills/sideby` (where `npx skills add -g` installs and Codex reads user skills). A file is read
+ * once per Family, so the result for one Family never depends on which others are checked with it. Findings
+ * are general and belong to that Family's Main Account.
+ */
+export async function checkInstalledSkills(home, families, version) {
+    const places = families.flatMap((f) => [
+        { family: f, path: join(mainDirOf(f, home), 'skills', 'sideby', 'SKILL.md') },
+        ...(f.id === 'codex' ? [{ family: f, path: join(home, '.agents', 'skills', 'sideby', 'SKILL.md') }] : []),
+    ]);
+    const seen = new Set();
+    const out = [];
+    for (const { family, path } of places) {
+        let real;
+        let text;
+        try {
+            real = await realpath(path);
+            if (seen.has(`${family.id}\0${real}`))
+                continue;
+            text = await readFile(real, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        seen.add(`${family.id}\0${real}`);
+        const found = skillVersionOf(text);
+        if (found === version)
+            continue;
+        const where = tildify(path, home);
+        out.push({
+            level: 'warn',
+            account: `${family.id}:main`,
+            item: where,
+            code: 'skill.outdated',
+            message: `the sideby skill at ${where} is ${found ? `for sideby ${found}` : 'from before skills had a version'}; this sideby is ${version}`,
+            hint: `update it with \`${SKILL_INSTALL}\`, so agents learn this version's commands`,
+            source: 'core',
+            fixable: false,
+        });
+    }
+    return out;
+}

package/dist/src/core/usage-days.d.ts

@@ -0,0 +1,15 @@
+export interface DailyTokens {
+    /** Local calendar date, `YYYY-MM-DD`. */
+    date: string;
+    totalTokens: number;
+}
+/** Local calendar date of a time, `YYYY-MM-DD`. */
+export declare function localDate(at: number | Date): string;
+/**
+ * `days` buckets ending with the local day of `now`. `add` drops times outside those days, so the buckets can
+ * sum to less than a reader's rolling-window total (the oldest partial day falls outside them).
+ */
+export declare function dailyBuckets(now: Date, days?: number): {
+    daily: DailyTokens[];
+    add(at: number, tokens: number): void;
+};

package/dist/src/core/usage-days.js

@@ -0,0 +1,33 @@
+// Per-day Usage buckets shared by the built-in readers: local calendar dates, oldest first, zero-filled.
+import { USAGE_DAYS } from './quota-levels.js';
+const pad = (n) => String(n).padStart(2, '0');
+/** Local calendar date of a time, `YYYY-MM-DD`. */
+export function localDate(at) {
+    const d = at instanceof Date ? at : new Date(at);
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+/**
+ * `days` buckets ending with the local day of `now`. `add` drops times outside those days, so the buckets can
+ * sum to less than a reader's rolling-window total (the oldest partial day falls outside them).
+ */
+export function dailyBuckets(now, days = USAGE_DAYS) {
+    const daily = [];
+    const index = new Map();
+    for (let i = days - 1; i >= 0; i--) {
+        // Built from calendar parts, so a daylight-saving day of 23 or 25 hours still yields one entry per date.
+        const date = localDate(new Date(now.getFullYear(), now.getMonth(), now.getDate() - i));
+        const bucket = { date, totalTokens: 0 };
+        daily.push(bucket);
+        index.set(date, bucket);
+    }
+    return {
+        daily,
+        add(at, tokens) {
+            if (!Number.isFinite(at) || tokens <= 0)
+                return;
+            const bucket = index.get(localDate(at));
+            if (bucket)
+                bucket.totalTokens += tokens;
+        },
+    };
+}

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

@@ -0,0 +1,9 @@
+/** The sideby package version, read once from package.json (two levels up from src/, three from dist/src/). */
+export declare function packageVersion(): string;
+/**
+ * Identity of the code that is running: the version plus the id `pnpm build` writes to `dist/build.json`, so a
+ * rebuilt or reinstalled package differs even when its version does not. Long-running Panels compare it to
+ * notice new code. From source there is no build file (`<version>+source`). `SIDEBY_BUILD_ID` overrides the
+ * id for tests.
+ */
+export declare function buildId(env?: NodeJS.ProcessEnv): string;

package/dist/src/core/version.js

@@ -0,0 +1,46 @@
+import { readFileSync } from 'node:fs';
+let cached;
+/** The sideby package version, read once from package.json (two levels up from src/, three from dist/src/). */
+export function packageVersion() {
+    if (cached)
+        return cached;
+    for (const rel of ['../../package.json', '../../../package.json']) {
+        try {
+            const pkg = JSON.parse(readFileSync(new URL(rel, import.meta.url), 'utf8'));
+            if (pkg.name === 'sideby' && pkg.version) {
+                cached = pkg.version;
+                return cached;
+            }
+        }
+        catch {
+            // try the next layout
+        }
+    }
+    cached = '0.0.0';
+    return cached;
+}
+let cachedBuild;
+/**
+ * Identity of the code that is running: the version plus the id `pnpm build` writes to `dist/build.json`, so a
+ * rebuilt or reinstalled package differs even when its version does not. Long-running Panels compare it to
+ * notice new code. From source there is no build file (`<version>+source`). `SIDEBY_BUILD_ID` overrides the
+ * id for tests.
+ */
+export function buildId(env = process.env) {
+    if (env.SIDEBY_BUILD_ID)
+        return `${packageVersion()}+${env.SIDEBY_BUILD_ID}`;
+    if (cachedBuild)
+        return cachedBuild;
+    let id = 'source';
+    try {
+        // dist/src/core/version.js → dist/build.json; from src/ the file does not exist.
+        const data = JSON.parse(readFileSync(new URL('../../build.json', import.meta.url), 'utf8'));
+        if (typeof data.id === 'string' && data.id)
+            id = data.id;
+    }
+    catch {
+        // running from source
+    }
+    cachedBuild = `${packageVersion()}+${id}`;
+    return cachedBuild;
+}