team 0.0.1 → 0.1.1

package/dist/args.d.ts

@@ -0,0 +1,7 @@
+export type Args = {
+    values: Record<string, string>;
+    flags: Set<string>;
+    rest: string[];
+    error?: string;
+};
+export declare function readArgs(argv: string[], valued: string[], flags: string[]): Args;

package/dist/args.js

@@ -0,0 +1,22 @@
+export function readArgs(argv, valued, flags) {
+    const args = { values: {}, flags: new Set(), rest: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            args.rest.push(arg);
+            continue;
+        }
+        const [name, inline] = arg.slice(2).split(/=(.*)/s);
+        if (flags.includes(name) && inline === undefined)
+            args.flags.add(name);
+        else if (valued.includes(name)) {
+            const value = inline ?? argv[++i];
+            if (value === undefined || value === '')
+                return { ...args, error: `--${name} needs a value` };
+            args.values[name] = value;
+        }
+        else
+            return { ...args, error: `unknown option --${name}` };
+    }
+    return args;
+}

package/dist/budgets/checks.d.ts

@@ -0,0 +1,35 @@
+import type { TeamFile } from '../file/types.ts';
+export type ApprovedCheck = {
+    command: string;
+    path: string;
+    hash: string;
+};
+/** The accounts `budgets` names a check for. Callers hand in the section in force (RFC 0003 § 5). */
+export declare function checkCommands(budgets: TeamFile['budgets']): {
+    account: string;
+    command: string;
+}[];
+/** The file a command names, and its sha256. Null when it cannot be resolved. */
+export declare function resolveCheck(command: string, root: string, pathEnv: string): {
+    path: string;
+    hash: string;
+} | null;
+export declare function resolveChecks(team: TeamFile, root: string, pathEnv: string): {
+    ok: true;
+    checks: Record<string, ApprovedCheck>;
+} | {
+    ok: false;
+    account: string;
+    command: string;
+};
+export type CheckReading = {
+    account: string;
+    state: 'approved' | 'unknown';
+};
+/**
+ * Whether each account's check may be run. The stored absolute path is hashed
+ * again; PATH is not consulted. A missing or changed file reads unknown.
+ */
+export declare function checkReadings(budgets: TeamFile['budgets'], approved: Record<string, ApprovedCheck> | undefined): CheckReading[];
+/** Lines for a resolved command whose path or hash is not the approved one. */
+export declare function checkDrift(approved: Record<string, ApprovedCheck> | undefined, current: Record<string, ApprovedCheck>): string[];

package/dist/budgets/checks.js

@@ -0,0 +1,77 @@
+// A `check` command is resolved and hashed at approval. The hash is of the named
+// file only. team never reads what that file imports, and never logs its bytes.
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+/** The accounts `budgets` names a check for. Callers hand in the section in force (RFC 0003 § 5). */
+export function checkCommands(budgets) {
+    return Object.entries(budgets.accounts)
+        .filter((entry) => entry[1].check !== null)
+        .map(([account, accountBudget]) => ({ account, command: accountBudget.check }));
+}
+/** The file a command names, and its sha256. Null when it cannot be resolved. */
+export function resolveCheck(command, root, pathEnv) {
+    const path = command.includes('/')
+        ? (isAbsolute(command) ? command : resolve(root, command))
+        : pathEnv.split(':').filter((dir) => dir && isAbsolute(dir)).map((dir) => join(dir, command)).find((file) => executable(file)) ?? '';
+    if (!path || !executable(path))
+        return null;
+    return { path, hash: createHash('sha256').update(readFileSync(path)).digest('hex') };
+}
+export function resolveChecks(team, root, pathEnv) {
+    const checks = {};
+    for (const { account, command } of checkCommands(team.budgets)) {
+        const found = resolveCheck(command, root, pathEnv);
+        if (!found)
+            return { ok: false, account, command };
+        checks[account] = { command, path: found.path, hash: found.hash };
+    }
+    return { ok: true, checks };
+}
+/**
+ * Whether each account's check may be run. The stored absolute path is hashed
+ * again; PATH is not consulted. A missing or changed file reads unknown.
+ */
+export function checkReadings(budgets, approved) {
+    return checkCommands(budgets).map(({ account }) => {
+        const known = approved?.[account];
+        if (!known || hashOf(known.path) !== known.hash)
+            return { account, state: 'unknown' };
+        return { account, state: 'approved' };
+    });
+}
+/** Lines for a resolved command whose path or hash is not the approved one. */
+export function checkDrift(approved, current) {
+    const lines = [];
+    const previous = approved ?? {};
+    for (const [account, check] of Object.entries(current)) {
+        const known = previous[account];
+        if (!known || known.command !== check.command || known.path !== check.path || known.hash !== check.hash) {
+            lines.push(`the check for ${account} changed`);
+        }
+    }
+    for (const account of Object.keys(previous)) {
+        if (!current[account])
+            lines.push(`the check for ${account} changed`);
+    }
+    return lines;
+}
+function hashOf(file) {
+    try {
+        if (!statSync(file).isFile())
+            return null;
+        return createHash('sha256').update(readFileSync(file)).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+function executable(file) {
+    try {
+        const stat = statSync(file);
+        return stat.isFile() && (stat.mode & 0o111) !== 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/budgets/gate.d.ts

@@ -0,0 +1,24 @@
+import type { Seat, TeamFile } from '../file/types.ts';
+import { type Seen, type SpendReading } from './readings.ts';
+export type LaunchDecision = {
+    kind: 'clear';
+} | {
+    kind: 'unknown';
+    account: string;
+    text: string;
+} | {
+    kind: 'refuse';
+    why: string;
+};
+/**
+ * The seat's account is its vendor. There is no separate account field on a seat. `budgets` is
+ * the section in force: an unapproved edit to a reserve refuses no one until it is approved,
+ * and an account only the unapproved edit names is not an account at all. `spend` holds the
+ * stored spend check readings; a subscription account never looks at them.
+ */
+export declare function seatBudget(budgets: TeamFile['budgets'], readings: readonly Seen[], seat: Seat, now: number, spend?: readonly SpendReading[]): LaunchDecision;
+/**
+ * Accounts whose counted figures leave room: a subscription with every counted window outside
+ * its reserve, a spend account with a fresh reading above its floor.
+ */
+export declare function accountsWithRoom(budgets: TeamFile['budgets'], readings: readonly Seen[], now: number, spend?: readonly SpendReading[]): string[];

package/dist/budgets/gate.js

@@ -0,0 +1,127 @@
+import { verdict } from "./readings.js";
+const RANK = { session: 0, daily: 1, weekly: 2 };
+/**
+ * The seat's account is its vendor. There is no separate account field on a seat. `budgets` is
+ * the section in force: an unapproved edit to a reserve refuses no one until it is approved,
+ * and an account only the unapproved edit names is not an account at all. `spend` holds the
+ * stored spend check readings; a subscription account never looks at them.
+ */
+export function seatBudget(budgets, readings, seat, now, spend = []) {
+    const name = seat.vendor;
+    const account = budgets.accounts[name];
+    if (!account)
+        return { kind: 'clear' };
+    if (account.kind === 'spend') {
+        const floor = account.floor;
+        const reading = spend.find((item) => item.account === name);
+        // § 5's freshness rule for a check reading, applied to the floor: a reading with no floor to
+        // measure against, one read longer ago than `stale_after`, and one in another currency than
+        // the floor's are the same answer — unknown, said, never a refusal.
+        if (!floor || !reading || reading.currency !== floor.currency || now - reading.at >= budgets.staleAfter * 1000) {
+            return { kind: 'unknown', account: name, text: `${name} is unknown` };
+        }
+        if (reading.amount > floor.amount)
+            return { kind: 'clear' };
+        const room = accountsWithRoom(budgets, readings, now, spend).filter((accountName) => accountName !== name);
+        return {
+            kind: 'refuse',
+            why: `${name} spend ${money(reading.amount)} ${reading.currency}, at or below its ${money(floor.amount)} ${floor.currency} floor, read ${age(now - reading.at)} ago; accounts with room: ${room.length ? room.join(', ') : 'none'}`,
+        };
+    }
+    const staleAfterMs = budgets.staleAfter * 1000;
+    const mine = readings.filter((item) => item.account === name);
+    let unknown = mine.length === 0;
+    let unconfirmed = false;
+    let counted = false;
+    let worst = null;
+    for (const group of windowsOf(mine)) {
+        const result = verdict(group, now, staleAfterMs, account.reserve);
+        if (result.kind === 'unknown') {
+            unknown = true;
+            continue;
+        }
+        // A first sight is unconfirmed. It never refuses.
+        if (result.kind === 'unconfirmed') {
+            unconfirmed = true;
+            continue;
+        }
+        counted = true;
+        const inside = account.reserve !== null && result.reading.left <= account.reserve;
+        if (!inside && result.kind !== 'refusing')
+            continue;
+        if (!worst
+            || result.reading.left < worst.left
+            || (result.reading.left === worst.left && RANK[result.reading.window] < RANK[worst.window])) {
+            worst = result.reading;
+        }
+    }
+    if (worst && account.reserve !== null) {
+        const room = accountsWithRoom(budgets, readings, now).filter((accountName) => accountName !== name);
+        return {
+            kind: 'refuse',
+            why: `${name} ${worst.window} left ${worst.left}%, inside its ${account.reserve}% reserve, changed ${age(now - worst.changedAt)} ago; accounts with room: ${room.length ? room.join(', ') : 'none'}`,
+        };
+    }
+    if (unknown)
+        return { kind: 'unknown', account: name, text: `${name} is unknown` };
+    if (unconfirmed && !counted)
+        return { kind: 'unknown', account: name, text: `${name}: first sight only, not yet counted` };
+    return { kind: 'clear' };
+}
+/**
+ * Accounts whose counted figures leave room: a subscription with every counted window outside
+ * its reserve, a spend account with a fresh reading above its floor.
+ */
+export function accountsWithRoom(budgets, readings, now, spend = []) {
+    const staleAfterMs = budgets.staleAfter * 1000;
+    const names = [];
+    for (const [name, account] of Object.entries(budgets.accounts)) {
+        if (account.kind === 'spend') {
+            const floor = account.floor;
+            const reading = spend.find((item) => item.account === name);
+            if (floor && reading && reading.currency === floor.currency && now - reading.at < staleAfterMs && reading.amount > floor.amount) {
+                names.push(name);
+            }
+            continue;
+        }
+        if (account.reserve === null)
+            continue;
+        const groups = windowsOf(readings.filter((item) => item.account === name));
+        let counted = 0;
+        let inside = false;
+        for (const group of groups) {
+            const result = verdict(group, now, staleAfterMs, account.reserve);
+            if (result.kind === 'unknown' || result.kind === 'unconfirmed')
+                continue;
+            counted += 1;
+            if (result.kind === 'refusing' || result.reading.left <= account.reserve)
+                inside = true;
+        }
+        if (counted > 0 && !inside)
+            names.push(name);
+    }
+    return names.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+function windowsOf(list) {
+    const groups = new Map();
+    for (const reading of list) {
+        const group = groups.get(reading.window) ?? [];
+        group.push(reading);
+        groups.set(reading.window, group);
+    }
+    return [...groups.values()];
+}
+function age(ms) {
+    const minutes = Math.max(0, Math.floor(ms / 60_000));
+    const hours = Math.floor(minutes / 60);
+    const rest = minutes % 60;
+    if (hours && rest)
+        return `${hours}h${rest}m`;
+    if (hours)
+        return `${hours}h`;
+    return `${minutes}m`;
+}
+/** A money figure in a refusal: the cents are shown even when the file wrote none. */
+function money(amount) {
+    return amount.toFixed(2);
+}

package/dist/budgets/readings.d.ts

@@ -0,0 +1,69 @@
+import type { QuotaFigure, WindowName } from '../profiles/quota.ts';
+export type Seen = {
+    account: string;
+    window: WindowName;
+    left: number;
+    used: number;
+    changedAt: number;
+    resetsAt: number | null;
+    seat: string;
+    confirmed: boolean;
+};
+export type StoredReading = {
+    account: string;
+    window: WindowName;
+    left: number;
+    used: number;
+    changedAt: string;
+    resetsAt: string | null;
+    seat: string;
+    confirmed: boolean;
+};
+export type Verdict = {
+    kind: 'fresh' | 'unconfirmed' | 'stale' | 'refusing';
+    reading: Seen;
+} | {
+    kind: 'unknown';
+};
+/** A spend check reading (RFC 0003 § 5): the money the account still holds. */
+export type SpendReading = {
+    account: string;
+    amount: number;
+    currency: string;
+    /** When the check ran: a spend line carries no time of its own (§ 5). */
+    at: number;
+};
+export type StoredSpend = {
+    account: string;
+    amount: number;
+    currency: string;
+    at: string;
+};
+/** Fold one seat's figure into the readings kept for this pass. */
+export declare function observe(list: readonly Seen[], figure: QuotaFigure, seat: string, now: number): Seen[];
+/**
+ * The reading that counts. A figure from before a known reset is dropped.
+ * Among confirmed live readings, the newest change wins. A first sight counts
+ * only when no confirmed reading is still live. Staleness is measured from
+ * `changedAt`. A stale reading inside the reserve refuses until its reset;
+ * with no reset time it is unknown.
+ */
+export declare function verdict(list: readonly Seen[], now: number, staleAfterMs: number, reserve: number | null): Verdict;
+/** Readings whose reset has passed are left out. One with no reset time is kept. */
+export declare function remember(list: readonly Seen[], now: number): Record<string, StoredReading>;
+export declare function recall(stored: Record<string, StoredReading> | undefined): Seen[];
+/** Write the readings that still count. The state file is the per-project cache. */
+export declare function saveReadings(dir: string, session: string, list: readonly Seen[], now?: number): void;
+export declare function loadReadings(dir: string, session: string): Seen[];
+/**
+ * Write the spend readings a pass's checks read, merging by account: an account whose check did
+ * not run this pass keeps the reading the state already holds. Nothing read, nothing written.
+ */
+export declare function saveSpendReadings(dir: string, session: string, list: readonly SpendReading[]): void;
+export declare function loadSpendReadings(dir: string, session: string): SpendReading[];
+export declare function storeSpend(reading: SpendReading): StoredSpend;
+export declare function recallSpend(stored: Record<string, StoredSpend> | undefined): SpendReading[];
+export declare function store(reading: Seen): StoredReading;
+export declare function revive(stored: StoredReading): Seen;
+/** When a duration such as `114h4m` ends, counted from a time. Null for no or an odd duration. */
+export declare function resetsFrom(duration: string | null, now: number): number | null;

package/dist/budgets/readings.js

@@ -0,0 +1,156 @@
+import { emptySession, readState, updateState } from "../state.js";
+/** Fold one seat's figure into the readings kept for this pass. */
+export function observe(list, figure, seat, now) {
+    const next = list.slice();
+    const at = next.findIndex((item) => item.account === figure.account && item.window === figure.window && item.seat === seat);
+    const previous = at < 0 ? null : next[at] ?? null;
+    const same = previous !== null && previous.left === figure.left && previous.used === figure.used;
+    const agreed = next.some((item) => item !== previous
+        && item.account === figure.account
+        && item.window === figure.window
+        && item.left === figure.left
+        && item.used === figure.used
+        && (item.resetsAt === null || item.resetsAt > now));
+    const reading = {
+        account: figure.account,
+        window: figure.window,
+        left: figure.left,
+        used: figure.used,
+        changedAt: same && previous ? previous.changedAt : now,
+        resetsAt: same && previous && previous.resetsAt !== null ? previous.resetsAt : resetsFrom(figure.resets, now),
+        seat,
+        confirmed: previous === null ? agreed : same ? previous.confirmed || agreed : true,
+    };
+    if (at < 0)
+        next.push(reading);
+    else
+        next[at] = reading;
+    return next;
+}
+/**
+ * The reading that counts. A figure from before a known reset is dropped.
+ * Among confirmed live readings, the newest change wins. A first sight counts
+ * only when no confirmed reading is still live. Staleness is measured from
+ * `changedAt`. A stale reading inside the reserve refuses until its reset;
+ * with no reset time it is unknown.
+ */
+export function verdict(list, now, staleAfterMs, reserve) {
+    const live = list.filter((item) => item.resetsAt === null || item.resetsAt > now);
+    const confirmed = live.filter((item) => item.confirmed);
+    const ranked = confirmed.length > 0 ? confirmed : live;
+    if (ranked.length === 0)
+        return { kind: 'unknown' };
+    const newest = Math.max(...ranked.map((item) => item.changedAt));
+    const tied = ranked.filter((item) => item.changedAt === newest);
+    const reading = tied.find((item) => item.confirmed) ?? tied[0];
+    if (!reading)
+        return { kind: 'unknown' };
+    if (!reading.confirmed)
+        return { kind: 'unconfirmed', reading };
+    if (now - reading.changedAt < staleAfterMs)
+        return { kind: 'fresh', reading };
+    const inside = reserve !== null && reading.left <= reserve;
+    if (inside && reading.resetsAt !== null)
+        return { kind: 'refusing', reading };
+    if (reading.resetsAt === null)
+        return { kind: 'unknown' };
+    return { kind: 'stale', reading };
+}
+/** Readings whose reset has passed are left out. One with no reset time is kept. */
+export function remember(list, now) {
+    const out = {};
+    for (const reading of list) {
+        if (reading.resetsAt !== null && reading.resetsAt <= now)
+            continue;
+        out[`${reading.account}/${reading.window}/${reading.seat}`] = store(reading);
+    }
+    return out;
+}
+export function recall(stored) {
+    if (!stored)
+        return [];
+    return Object.values(stored).map(revive);
+}
+/** Write the readings that still count. The state file is the per-project cache. */
+export function saveReadings(dir, session, list, now = Date.now()) {
+    updateState(dir, (state) => {
+        const current = state.sessions[session] ?? emptySession();
+        current.budgets = remember(list, now);
+        state.sessions[session] = current;
+    });
+}
+export function loadReadings(dir, session) {
+    return recall(readState(dir).sessions[session]?.budgets);
+}
+/**
+ * Write the spend readings a pass's checks read, merging by account: an account whose check did
+ * not run this pass keeps the reading the state already holds. Nothing read, nothing written.
+ */
+export function saveSpendReadings(dir, session, list) {
+    if (!list.length)
+        return;
+    updateState(dir, (state) => {
+        const current = state.sessions[session] ?? emptySession();
+        const spend = current.spend ?? {};
+        for (const reading of list)
+            spend[reading.account] = storeSpend(reading);
+        current.spend = spend;
+        state.sessions[session] = current;
+    });
+}
+export function loadSpendReadings(dir, session) {
+    return recallSpend(readState(dir).sessions[session]?.spend);
+}
+export function storeSpend(reading) {
+    return {
+        account: reading.account,
+        amount: reading.amount,
+        currency: reading.currency,
+        at: new Date(reading.at).toISOString(),
+    };
+}
+export function recallSpend(stored) {
+    if (!stored)
+        return [];
+    return Object.values(stored).map((one) => ({
+        account: one.account,
+        amount: one.amount,
+        currency: one.currency,
+        at: Date.parse(one.at),
+    }));
+}
+export function store(reading) {
+    return {
+        account: reading.account,
+        window: reading.window,
+        left: reading.left,
+        used: reading.used,
+        changedAt: new Date(reading.changedAt).toISOString(),
+        resetsAt: reading.resetsAt === null ? null : new Date(reading.resetsAt).toISOString(),
+        seat: reading.seat,
+        confirmed: reading.confirmed,
+    };
+}
+export function revive(stored) {
+    return {
+        account: stored.account,
+        window: stored.window,
+        left: stored.left,
+        used: stored.used,
+        changedAt: Date.parse(stored.changedAt),
+        resetsAt: stored.resetsAt === null ? null : Date.parse(stored.resetsAt),
+        seat: stored.seat,
+        confirmed: stored.confirmed,
+    };
+}
+/** When a duration such as `114h4m` ends, counted from a time. Null for no or an odd duration. */
+export function resetsFrom(duration, now) {
+    if (duration === null)
+        return null;
+    const match = /^(?:([0-9]+)h)?(?:([0-9]+)m)?$/.exec(duration);
+    if (!match || (match[1] === undefined && match[2] === undefined))
+        return null;
+    const hours = Number(match[1] ?? 0);
+    const minutes = Number(match[2] ?? 0);
+    return now + (hours * 60 + minutes) * 60 * 1000;
+}

package/dist/budgets/run.d.ts

@@ -0,0 +1,66 @@
+import type { BudgetAccount, TeamFile } from '../file/types.ts';
+import type { WindowName } from '../profiles/quota.ts';
+import { type ApprovedCheck } from './checks.ts';
+/** One window of a subscription check reading. */
+export type CheckWindow = {
+    window: WindowName;
+    left: number;
+    used: number;
+    /** The source's own measurement time: `at` when the line carries one, else the run's. */
+    at: number;
+    /** Anchored at the reading's own time, not at the run's. */
+    resetsAt: number | null;
+};
+export type CheckReading = {
+    kind: 'subscription';
+    windows: CheckWindow[];
+} | {
+    kind: 'spend';
+    amount: number;
+    currency: string;
+    at: number;
+};
+/** What one account's check reads this pass, or why it has no reading. */
+export type CheckOutcome = {
+    account: string;
+    state: 'read';
+    reading: CheckReading;
+} | {
+    account: string;
+    state: 'unreadable' | 'unapproved';
+};
+/**
+ * A subscription output against § 5. Any line off the contract, a figure over
+ * 100, or a window twice reads unknown — the whole output, not just the line.
+ * `at`, when printed, is the line's own time; a time later than the run is the run's.
+ */
+export declare function parseSubscription(text: string, now: number): CheckReading | null;
+/** A spend output against § 5: exactly one line, and in the floor's currency. */
+export declare function parseSpend(text: string, currency: string, now: number): CheckReading | null;
+/** One output against its account's contract. Null reads unknown for that account. */
+export declare function parseOutput(account: BudgetAccount, text: string, now: number): CheckReading | null;
+/**
+ * Runs one approved command and returns its output, or null: § 5 gives it an
+ * empty environment with PATH and HOME, a timeout, and exit 0; stderr is dropped.
+ * The timeout kills (SIGKILL: a command that traps TERM would otherwise run on,
+ * and `spawnSync` blocks the whole watch loop while it does). The command's bytes
+ * are the owner's, so they are returned to the parser only.
+ */
+export declare function runCommand(path: string, timeoutMs?: number): string | null;
+/** One account's reading this pass: null when the command fails, times out, or breaks its contract. */
+export declare function readCheck(account: BudgetAccount, path: string, now: number, timeoutMs?: number): CheckReading | null;
+export type CheckRunner = (account: BudgetAccount, path: string, now: number) => CheckReading | null;
+/**
+ * What each checked account reads this pass: its reading, or that it has none
+ * and why. `budgets` is the section in force: an account an unapproved edit
+ * took out is not checked, and one it changed reads under the approved entry.
+ * An account whose check is changed, missing or unapproved is not run at all
+ * (§ 5, #45). The path handed to `run` is the approved one, hashed again
+ * against the approval: the file's command is never run directly.
+ */
+export declare function checkOutcomes(budgets: TeamFile['budgets'], approved: Record<string, ApprovedCheck> | undefined, run: CheckRunner, now: number): CheckOutcome[];
+/**
+ * What every checked account reads this pass, with the approval of this machine. The accounts are
+ * the ones the budgets in force name, never the file's unapproved edit of them.
+ */
+export declare function runChecks(team: TeamFile, root: string, now: number, home?: string, run?: CheckRunner): CheckOutcome[];