toolroll 0.9.103 → 0.9.105

package/dist/gaps.d.ts

@@ -1,35 +0,0 @@
-/**
- * Gaps: what the machine lacks, ranked by what filling it would free (§6).
- *
- * One computation, shared — the CLI brief, `toolroll gaps`, and the web
- * console all show the same ranking because they call the same function.
- * A second copy would only learn to disagree with this one.
- */
-import { type Capability, type Store } from "./store.js";
-/** One thing the machine lacks, and what filling it would actually free. */
-export type Gap = {
-    key: string;
-    repo: string;
-    /** Why it is a gap, in the capability's own words. */
-    state: string;
-    /** Tasks this gap alone is holding back — fill it and they start. */
-    unblocks: string[];
-    /** Tasks waiting on this *and* something else — filling this is not enough. */
-    alsoBlocks: string[];
-    /** How to prove it filled. */
-    verify: string;
-    instructions: string;
-};
-/**
- * What is missing, ranked by how many tasks it unblocks — never
- * alphabetically (§6). The count is honest in the way that matters at 9am:
- * a task waiting on two gaps starts when *both* fill, so it counts toward
- * neither gap's `unblocks` and both gaps' `alsoBlocks`. A ranking that
- * counted it twice would send the operator to fill the wrong gap first.
- *
- * Derived, not stored: every field here is a join over capabilities and the
- * ready set, and a stored copy would only learn to disagree with them.
- */
-export declare function computeGaps(store: Store, repo: string, now: Date): Gap[];
-export declare function adviceFor(kind: string): string;
-export declare function describeCapability(capability: Capability, now: Date): string;

package/dist/gate-failure.d.ts

@@ -1,40 +0,0 @@
-/**
- * Why a machine gate failed, read from its sealed receipt, log and candidate
- * inventory — so the bounded repair loop does not spend a code-writing
- * attempt on a failure the change cannot have caused.
- *
- * Two classes are conservative enough to skip a repair draft:
- *  - the whole command timed out before any test failed, and
- *  - every failing test is a per-test timeout inside a file the candidate
- *    did not touch.
- * An ordinary assertion failure anywhere — including in an untouched file,
- * whose imports the change may have broken — stays repairable. When the
- * failing files cannot be read from the log with certainty, the failure
- * stays repairable too: never silence a real failure by parsing badly.
- */
-import type { VerifyCommandFacts } from "./proof.js";
-export type GateFailureClass = {
-    kind: "repairable";
-} | {
-    kind: "gate-timed-out";
-    timeoutMs: number | null;
-} | {
-    kind: "untouched-test-timeout";
-    files: string[];
-};
-export type FailingTest = {
-    file: string;
-    timedOut: boolean;
-};
-/** The failing tests a Vitest log names, or null when the log's own failed
- * count and its FAIL blocks disagree (or no count was printed at all). */
-export declare function failingTestsOf(log: string): FailingTest[] | null;
-export declare function classifyGateFailure(result: VerifyCommandFacts, log: string, changedPaths: readonly string[] | null, timeoutMs?: number | null): GateFailureClass;
-/** What happened, in one sentence, for every notice about this failure. */
-export declare function gateFailureSummary(failure: Exclude<GateFailureClass, {
-    kind: "repairable";
-}>): string;
-/** Plain words for the person who has to act. */
-export declare function describeGateFailure(failure: Exclude<GateFailureClass, {
-    kind: "repairable";
-}>, taskId: string): string;

package/dist/git-floor.d.ts

@@ -1,16 +0,0 @@
-export declare const GIT_FLOOR: {
-    readonly major: 2;
-    readonly minor: 41;
-};
-export declare const GIT_FLOOR_WORDS: string;
-/** The version `git --version` names ("git version 2.50.1 (Apple Git-155)" → 2.50.1), or null when it names none. */
-export declare function parseGitVersion(text: string): {
-    major: number;
-    minor: number;
-    words: string;
-} | null;
-/** Why `version` (`git --version`'s answer) is below the floor, in one sentence, or null when it isn't (or can't be read). */
-export declare function gitFloorWords(versionText: string): string | null;
-/** The installed git's floor problem, asked once per process with no system or global config; null when git is new
- * enough, or when no version could be read (a missing git is reported where it is used). */
-export declare function installedGitFloorProblem(): string | null;

package/dist/git-incident.d.ts

@@ -1,65 +0,0 @@
-export type GitIncident = {
-    at: string;
-    checkout: string;
-    repository: string;
-    /** Folders of the repository found swapped, and where each now leads (null: its pointers changed instead). */
-    swapped: {
-        path: string;
-        leadsTo: string | null;
-    }[];
-    /** What changed: a folder swapped for a link, the checkout's pointers naming another git directory, or a folder on the
-     * way to its own moved. Absent on older records. */
-    cause?: "swapped" | "rebound" | "moved";
-    /** What the plane was doing, in a person's words ("tidying an old checkout"). Absent on older records. */
-    doing?: string;
-};
-type Listener = (incident: GitIncident) => void;
-/** Hear about every git incident (returns the unsubscribe). With none registered, incidents go to stderr. */
-export declare function onGitIncident(listener: Listener): () => void;
-/** Record and tell one incident. */
-export declare function gitIncident(input: {
-    checkout: string;
-    repository: string;
-    swapped: GitIncident["swapped"];
-    cause?: GitIncident["cause"];
-    doing?: string;
-    record: string;
-}): GitIncident;
-/** What noticeGitIncidents needs of the store: its durable outbox, and its own project records. */
-export type IncidentOutbox = {
-    enqueueNotification(notification: {
-        dedupeKey: string;
-        kind: string;
-        subject: string;
-        body: string;
-        pushClass?: "attention";
-        source?: {
-            project: string;
-        } | {
-            installation: true;
-        };
-    }, now: Date): boolean;
-    listProjects(): {
-        path: string;
-        name: string;
-    }[];
-};
-/**
- * Every git incident from now on raises an attention notification in `outbox` (the console and the background worker
- * register their store as they start; once per store): "Git incident in <project>: a folder of its repository changed
- * while Toolroll's git ran". Nothing the agent chose reaches the text (paths in an agent-written repository can carry
- * newlines and words of its own): the project is named only by the plane's own record of it (matched by real path,
- * else "a project"), and the person is pointed to the incident record file, where the paths are. Returns the
- * unsubscribe.
- */
-export declare function noticeGitIncidents(outbox: IncidentOutbox, now?: () => Date, record?: string): () => void;
-/** How long a checkout that had a git incident is left alone by tidying (worktree.ts inspect): a day. */
-export declare const INCIDENT_QUIET_MS: number;
-/**
- * Whether `checkout` had a git incident recorded since `since`: the last 256 KB of the record, read without following
- * a link. A record that can't be read says no (tidying then runs, and a real incident is still caught and told).
- */
-export declare function recentGitIncident(record: string, checkout: string, since: Date): boolean;
-/** How many distinct changes on one checkout reach a person in a day before the rest share one last notice. */
-export declare const INCIDENT_CHANGES_PER_DAY = 3;
-export {};

package/dist/git-views.d.ts

@@ -1,20 +0,0 @@
-/** The views folder under `home`. */
-export declare function gitViewsRoot(home: string): string;
-/**
- * The views folder under `home`, made if it isn't there (owner-only), and proven to be this user's own real folder all
- * the way from `home`: neither it nor `~/.toolroll` may be a link or anyone else's. Throws otherwise.
- */
-export declare function ensureGitViewsRoot(home: string): string;
-/**
- * One plane git command at a time on a checkout (Codex review of a0fa135d): each command's private GIT_DIR has its own
- * HEAD, so two at once would each take their own HEAD lock and the later carry-back would undo the earlier. The lock
- * is a file the plane makes exclusively in the fenced views folder, named by the checkout's real path, holding this
- * process's id; one whose process is gone is taken over. Waits up to `timeoutMs`; returns the release.
- */
-export declare function lockCheckout(home: string, checkout: string, timeoutMs?: number): Promise<() => void>;
-/**
- * Run `work` holding the checkout's lock (lockCheckout). Re-entrant along one call chain: a hardened git nested in
- * another on the same checkout (teardown's git run through the builder's hardened runner, a view within a view) runs
- * under the lock its caller already holds instead of waiting on itself.
- */
-export declare function withCheckoutLock<T>(home: string, checkout: string, work: () => Promise<T>, timeoutMs?: number): Promise<T>;

package/dist/git.d.ts

@@ -1,54 +0,0 @@
-/**
- * Parsers for git plumbing output.
- *
- * Pure functions over strings — no child_process, no fs. Shelling out lives in
- * the caller, so the part most worth testing needs no fixture repo. This is also
- * why discovery can claim to be read-only: nothing here can reach a repository.
- */
-export type Worktree = {
-    path: string;
-    head: string;
-    /** null when in detached HEAD — which is how treehouse leases worktrees. */
-    branch: string | null;
-    detached: boolean;
-    bare: boolean;
-    locked: boolean;
-    prunable: boolean;
-};
-export type TrackingState = {
-    ahead: number;
-    behind: number;
-    /** Upstream existed and was deleted — the merged-and-cleaned-up case. */
-    gone: boolean;
-};
-export type Branch = {
-    name: string;
-    track: TrackingState;
-    /** Opaque ISO-8601 from git, passed through untouched. Never reformatted here. */
-    committedAt: string;
-};
-/**
- * Parse `git worktree list --porcelain`.
- *
- * Records are separated by blank lines; each is a sequence of `key value` lines
- * where `detached`, `bare`, `locked` and `prunable` are bare flags that may carry
- * a trailing reason we deliberately discard.
- */
-export declare function parseWorktrees(porcelain: string): Worktree[];
-/**
- * Parse the `%(upstream:track)` field: `""`, `"[gone]"`, `"[ahead 2]"`,
- * `"[behind 5]"`, or `"[ahead 2, behind 5]"`.
- *
- * Unrecognized input yields a zeroed state rather than throwing — a tracking
- * field we cannot read must never take down discovery of the repo around it.
- */
-export declare function parseTrack(field: string): TrackingState;
-/**
- * Parse tab-separated `git for-each-ref` output:
- *
- *   %(refname:short)\t%(upstream:track)\t%(committerdate:iso8601-strict)
- *
- * Tabs rather than spaces because a ref name may not contain a tab, but the
- * tracking field always does.
- */
-export declare function parseBranches(output: string): Branch[];

package/dist/github-import.d.ts

@@ -1,62 +0,0 @@
-import type { Store } from "./store.js";
-export type GithubRef = {
-    owner: string;
-    repo: string;
-    kind: "issue" | "pull";
-    number: number;
-    url: string;
-};
-export type GithubItem = GithubRef & {
-    title: string;
-    body: string;
-    author: string | null;
-    head: string | null;
-};
-export type ImportRefusal = {
-    ok: false;
-    reason: "bad-url" | "foreign-host" | "unregistered" | "unreadable" | "identity" | "fork" | "head-moved" | "not-filed";
-    message: string;
-};
-/** A pasted link, strictly: https, exactly github.com, an issue or a pull request. */
-export declare function parseGithubRef(text: string): GithubRef | ImportRefusal;
-/** `owner/repo` from a remote the project recorded, only in GitHub's exact forms. */
-export declare function githubRepoOf(remote: string | null): string | null;
-/** The environment gh gets: this allowlist, nothing else from the caller. */
-export declare function importEnv(base?: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv;
-/** gh from the system's own folders, as its real file: PATH is never asked, so a planted `gh` is never run. */
-export declare function pinnedGh(): string;
-export type GhExec = (file: string, args: readonly string[], options: {
-    cwd: string;
-    env: NodeJS.ProcessEnv;
-    timeoutMs: number;
-}) => Promise<{
-    code: number;
-    stdout: string;
-    stderr: string;
-}>;
-export type ImportDeps = {
-    exec?: GhExec;
-    gh?: string;
-};
-/** Read the item, and prove it is the one the project's identity says. */
-export declare function readGithubItem(store: Store, input: {
-    url: string;
-    repo: string;
-}, deps?: ImportDeps): Promise<{
-    ok: true;
-    item: GithubItem;
-    gh: string;
-} | ImportRefusal>;
-/** The plan's words: what to do, then the outside text as a quotation, cut with a link when it's long. */
-export declare function importedGoal(item: GithubItem): string;
-/** File it, with its provenance, in one transaction. `shownHead`: the commit the person saw, for a pull request. */
-export declare function fileGithubItem(store: Store, input: {
-    url: string;
-    repo: string;
-    actor: string;
-    shownHead?: string | null;
-}, now: Date, deps?: ImportDeps): Promise<{
-    ok: true;
-    taskId: string;
-    item: GithubItem;
-} | ImportRefusal>;

package/dist/github-jobs.d.ts

@@ -1,25 +0,0 @@
-/**
- * GitHub's own job records, read by the plane's gh (release-adapters.ts for a release's checks, nightly-github.ts for
- * GitHub's nightly): what each step of a finished job did. Step numbers and outcomes are the runner's records; nothing
- * the tested code prints is read.
- */
-/** One job's step outcomes as GitHub's Actions API reports them. */
-export type JobRecord = {
-    id: number;
-    status: string;
-    conclusion: string | null;
-    steps: {
-        number: number;
-        name: string;
-        status: string;
-        conclusion: string | null;
-    }[];
-};
-/**
- * Whether a finished, unsuccessful job ended before any of the workflow's own steps ran: every step after GitHub's own
- * first one ("Set up job", always number 1) never ran (no conclusion, or skipped) — leaving out only GitHub's own
- * closing "Complete job" when it is the last step. Step numbers and outcomes are the runner's records; nothing the
- * candidate prints is read. A job with no steps never reached one. Anything else (a step that ran, even the checkout)
- * is not confirmed infrastructure.
- */
-export declare function failedBeforeTests(job: JobRecord): boolean;

package/dist/google-mail.d.ts

@@ -1,59 +0,0 @@
-export declare const GOOGLE_AUTH = "https://accounts.google.com/o/oauth2/v2/auth";
-export declare const GOOGLE_TOKEN = "https://oauth2.googleapis.com/token";
-/** Full mail access is what IMAP and SMTP sign-in needs; "email" says which address it is. */
-export declare const GOOGLE_SCOPE = "https://mail.google.com/ openid email";
-export declare const GOOGLE_CALLBACK = "/settings/google/callback";
-export type GoogleMail = {
-    clientId: string;
-    clientSecret: string;
-    refreshToken: string | null;
-    address: string | null;
-};
-/** The saved client and connection; null when there's none. A keychain that refuses throws (SecretStoreError). */
-export declare function readGoogleMail(dir: string | null): GoogleMail | null;
-/** Connected: a refresh token and the address it belongs to. */
-export declare function googleConnected(dir: string | null): {
-    address: string;
-} | null;
-/** Save the OAuth client from Settings; an empty secret keeps the saved one. A new client forgets the old connection. */
-export declare function saveGoogleClient(dir: string, input: {
-    clientId: unknown;
-    clientSecret: unknown;
-}): {
-    ok: true;
-} | {
-    ok: false;
-    message: string;
-};
-export type GoogleVisit = {
-    state: string;
-    verifier: string;
-    redirectUri: string;
-    by: string;
-    expires: number;
-};
-/** Where to send the person to consent, and what to remember to check their return against. */
-export declare function googleConsent(client: GoogleMail, redirectUri: string, by: string, now?: number): {
-    url: string;
-    visit: GoogleVisit;
-};
-/** The one-time code from Google's redirect, exchanged for a refresh token and saved. */
-export declare function finishGoogleConsent(dir: string, visit: GoogleVisit, code: string, fetcher: typeof fetch): Promise<{
-    ok: true;
-    address: string;
-} | {
-    ok: false;
-    message: string;
-}>;
-/** A fresh access token for IMAP and SMTP (kept in memory until a minute before it ends). */
-export declare function googleAccessToken(dir: string | null, fetcher: typeof fetch, now?: number): Promise<{
-    ok: true;
-    token: string;
-    address: string;
-} | {
-    ok: false;
-    said: string;
-    permanent: boolean;
-}>;
-/** Disconnect: Google forgets the grant (best effort), and the file goes. */
-export declare function disconnectGoogle(dir: string, fetcher: typeof fetch): Promise<void>;

package/dist/grant.d.ts

@@ -1,136 +0,0 @@
-/**
- * Permission to write to somebody else's tracker.
- *
- * Everything up to here reads. This is the line, and it is drawn deliberately
- * wide of where it needs to be: discovery indexes everything it can see, and
- * Toolroll drives only what has been handed over, one repository and one
- * backend at a time, by a person, in an act that shows its own consequences
- * first.
- *
- * The grant is not a boolean. A yes/no flag would answer "may I write here"
- * and leave every interesting question — write *what*, to *which* tasks, with
- * *whose* credentials, visible to *whom* — to whatever the agent decided at
- * 3am. So the record carries all of them, and the check is against the whole
- * thing.
- *
- * Two defaults are load-bearing.
- *
- * **Only tasks we created or were given.** An operator enrolling a repository
- * with four hundred open issues is not volunteering all four hundred to an
- * unattended agent, and reading enrollment that way is how a tool ends up
- * closing somebody's backlog overnight.
- *
- * **Closing is not included.** Creating a task is additive and reversible;
- * transitioning one we own is ours to do; closing work somebody else filed is
- * neither, so it is off unless explicitly granted. Widening takes another
- * human action, which is the design's rule and not a nicety.
- *
- * Absence of a grant is denial. There is no implicit, inherited, or default
- * permission anywhere in this module — an unknown repository is refused for
- * the same reason an unknown lease is: silence is not consent.
- */
-import { type ExecResult, type RunOptions } from "./exec.js";
-/**
- * What a write actually does, split by how much it can hurt.
- *
- * `close` is separate from `transition` because "mark the task I am working on
- * as done" and "close the issue somebody filed in March" are the same verb to
- * a database and completely different acts to a person.
- */
-export type MutationClass = "create" | "transition" | "edge" | "hold" | "close" | "comment";
-export declare const MUTATION_CLASSES: readonly MutationClass[];
-/** Granted unless asked otherwise; `close` is the deliberate omission. */
-export declare const DEFAULT_MUTATIONS: readonly MutationClass[];
-/**
- * Which tasks the grant covers. `ours` means the ones Toolroll created or
- * was explicitly given — the design's default, and the one that keeps an
- * enrolment from becoming an amnesty over an entire backlog.
- */
-export type TaskSelector = "ours" | "all";
-export type BackendGrant = {
-    repo: string;
-    backend: string;
-    /** Exact paths, or `owner/name` for a GitHub tracker. Never a wildcard. */
-    paths: string[];
-    mutations: MutationClass[];
-    selector: TaskSelector;
-    /** Named, never held: the value lives on the runner. */
-    credentialScope: string | null;
-    /** Whether these writes will show up in `git status` and in history. */
-    observedByGit: boolean;
-    grantedAt: string;
-    grantedBy: string;
-    /** External dispatch (v20): a SEPARATE authority from tracker writes —
-     * "this plane will BUILD what this tracker nominates, under scopes
-     * approved here". Never in any default; its own explicit yes. */
-    dispatch?: boolean;
-    /** The one exact owner/name this dispatch grant binds. Required when
-     * dispatch is true (enforced in saveGrant). */
-    remoteRepo?: string | null;
-    /** This plane's identity for the tracker-side marker — detection of a
-     * second plane, never a distributed lease. Minted at grant creation. */
-    planeId?: string | null;
-    /** Fail-closed dispatch block: set by marker verification and sync
-     * failures; null = clear. Admission refuses while set. */
-    dispatchBlocked?: "pending-marker" | "unreachable" | "foreign" | "missing" | "multiple-or-malformed" | null;
-    dispatchBlockedAt?: string | null;
-    dispatchBlockedDetail?: string | null;
-};
-/** Where a task came from, which is what `selector` discriminates on. */
-export type TaskOrigin = "ours" | "theirs";
-export type WriteRequest = {
-    repo: string;
-    backend: string;
-    mutation: MutationClass;
-    origin: TaskOrigin;
-    /** The file or repository being written, when the backend has one. */
-    path?: string;
-};
-export type Verdict = {
-    ok: true;
-} | {
-    ok: false;
-    reason: DenialReason;
-    message: string;
-};
-/** Stable tokens: an agent branches on these, a person reads the message. */
-export type DenialReason = "no-grant" | "mutation" | "selector" | "path";
-/**
- * Whether this write is inside the grant.
- *
- * Written as a pure function over the whole grant so the policy can be read in
- * one place and tested without a database, a repository, or a network — the
- * three things that make a permission check hard to trust.
- */
-export declare function permits(grant: BackendGrant | null, request: WriteRequest): Verdict;
-export type Runner = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
-export type ProposeOptions = {
-    repo: string;
-    backend: string;
-    paths: string[];
-    mutations?: readonly MutationClass[];
-    selector?: TaskSelector;
-    credentialScope?: string | null;
-    grantedBy?: string;
-    now: Date;
-    runner?: Runner;
-};
-/**
- * Build the grant that would be created, including the one fact an operator
- * cannot easily check for themselves: whether these writes will be visible.
- *
- * A backend that stores its data in a tracked directory means every task
- * transition shows up in `git status` and eventually in history — which is
- * either exactly what somebody wants, or a nasty surprise on their next
- * commit. It is asked of git rather than assumed, because the answer differs
- * per repository and the guess would be wrong half the time.
- */
-export declare function proposeGrant(options: ProposeOptions): Promise<BackendGrant>;
-/**
- * The grant, in the words an operator needs before agreeing to it — what may
- * be touched, what may be done, to which tasks, and whether anyone else will
- * see it happen.
- */
-export declare function describeGrant(grant: BackendGrant): string[];
-/** What is not granted, which is the half people forget to read. */
-export declare function describeWithheld(grant: BackendGrant): string[];