toolroll 0.5.0

package/dist/grant.js

@@ -0,0 +1,238 @@
+/**
+ * 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 { run } from "./exec.js";
+export const MUTATION_CLASSES = [
+    "create",
+    "transition",
+    "edge",
+    "hold",
+    "close",
+    "comment",
+];
+/** Granted unless asked otherwise; `close` is the deliberate omission. */
+export const DEFAULT_MUTATIONS = ["create", "transition", "edge", "hold"];
+/**
+ * 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 function permits(grant, request) {
+    if (grant === null) {
+        return {
+            ok: false,
+            reason: "no-grant",
+            message: `${request.repo} is not enrolled for ${request.backend} — \`toolroll enroll\` grants write access`,
+        };
+    }
+    // The grant has to be *this* grant. Callers look one up and pass it in, and
+    // a caller that looks up the wrong one — or reuses a handle across
+    // repositories in a loop — would otherwise have repo A's permission applied
+    // to repo B. Re-checking here costs a string compare and removes a class of
+    // confused-deputy bug that no amount of care at the call site can rule out.
+    if (grant.repo !== request.repo || grant.backend !== request.backend) {
+        return {
+            ok: false,
+            reason: "no-grant",
+            message: `that grant is for ${grant.backend} in ${grant.repo}, not ${request.backend} in ${request.repo}`,
+        };
+    }
+    if (!grant.mutations.includes(request.mutation)) {
+        return {
+            ok: false,
+            reason: "mutation",
+            message: `the grant on ${request.repo} does not allow \`${request.mutation}\` (it allows ${grant.mutations.join(", ")})`,
+        };
+    }
+    if (grant.selector === "ours" && request.origin === "theirs") {
+        return {
+            ok: false,
+            reason: "selector",
+            message: `the grant on ${request.repo} covers only tasks Toolroll created or was given`,
+        };
+    }
+    // A path outside the declared set is the case this is really for: a grant
+    // over `.beads/` must not become a licence to edit the working tree.
+    if (request.path !== undefined && !grant.paths.some(allowed => within(request.path, allowed))) {
+        return {
+            ok: false,
+            reason: "path",
+            message: `${request.path} is outside the grant on ${request.repo} (${grant.paths.join(", ")})`,
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Whether `path` is the granted scope or sits inside it.
+ *
+ * Segment-aware, so `.beads-backup` is not inside `.beads`, and `..` is
+ * resolved before comparing — without that, `.beads/../src/index.ts` starts
+ * with `.beads/` and a grant over a tracker's data directory becomes a licence
+ * to rewrite the working tree.
+ *
+ * This is a lexical check and says so. A symlink inside the granted directory
+ * still points wherever it points, and no amount of string handling will catch
+ * that; the boundary for it is the worktree the runner is confined to, which
+ * is M1's problem and not this function's.
+ */
+function within(path, allowed) {
+    const target = resolveSegments(path);
+    const scope = resolveSegments(allowed);
+    if (target === null || scope === null)
+        return false;
+    return target === scope || target.startsWith(`${scope}/`);
+}
+/** null when the path climbs above its own root, which is never inside anything. */
+function resolveSegments(path) {
+    const out = [];
+    for (const segment of normalise(path).split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment !== "..") {
+            out.push(segment);
+            continue;
+        }
+        if (out.length === 0)
+            return null;
+        out.pop();
+    }
+    return out.join("/");
+}
+function normalise(path) {
+    return path.replace(/\\/g, "/").replace(/\/+$/, "");
+}
+/**
+ * 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 async function proposeGrant(options) {
+    const { repo, backend, paths, mutations = DEFAULT_MUTATIONS, selector = "ours", credentialScope = null, grantedBy = "operator", now, runner = run, } = options;
+    return {
+        repo,
+        backend,
+        paths: [...paths],
+        mutations: [...mutations],
+        selector,
+        credentialScope,
+        observedByGit: await observedByGit(repo, paths, runner),
+        grantedAt: now.toISOString(),
+        grantedBy,
+    };
+}
+/**
+ * True when at least one granted path is not ignored by git.
+ *
+ * `git check-ignore` exits 0 when a path *is* ignored and 1 when it is not, so
+ * the interesting answer is the failure. Anything else — no git, an unreadable
+ * repository — is reported as observed, because claiming writes are invisible
+ * when we could not establish it is the wrong way to be wrong.
+ *
+ * Each path is asked about twice, bare and with a trailing slash, and that is
+ * not belt-and-braces. A `.gitignore` rule written `.beads/` matches only
+ * directories, and git cannot tell that a path *is* a directory when it does
+ * not exist yet — which is precisely the state at enrolment, before the
+ * tracker has been initialised. Asked bare, git says "not ignored" and the
+ * grant would tell somebody their writes are about to show up in every commit
+ * when they are not.
+ */
+async function observedByGit(repo, paths, runner) {
+    const local = paths.filter(path => !isRemoteRef(path));
+    if (local.length === 0)
+        return false;
+    for (const path of local) {
+        const asked = [path, `${normalise(path)}/`];
+        const ignored = await Promise.all(asked.map(async (candidate) => {
+            const result = await runner("git", ["--no-optional-locks", "check-ignore", "-q", candidate], {
+                cwd: repo,
+            });
+            return result.code === 0;
+        }));
+        if (!ignored.some(Boolean))
+            return true;
+    }
+    return false;
+}
+/** `owner/name` is a GitHub tracker, not a file in the working tree. */
+function isRemoteRef(path) {
+    return /^[^/\\]+\/[^/\\]+$/.test(path) && !path.startsWith(".");
+}
+/**
+ * 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 function describeGrant(grant) {
+    return [
+        `  repository   ${grant.repo}`,
+        `  backend      ${grant.backend}`,
+        `  may touch    ${grant.paths.join(", ")}`,
+        `  may do       ${grant.mutations.join(", ")}`,
+        `  on tasks     ${grant.selector === "ours" ? "only those Toolroll created or was given" : "every task in the tracker"}`,
+        `  credentials  ${grant.credentialScope ?? "none of its own — it uses the ones already on this machine"}`,
+        `  visibility   ${describeVisibility(grant)}`,
+    ];
+}
+/**
+ * Who will see these writes.
+ *
+ * Careful about what git can actually tell us. `check-ignore` answers whether
+ * a path would show up in `git status` — it does not decide what lands in
+ * history, since nothing lands there until somebody commits. Saying "these
+ * will be in your history" would be a claim this program is in no position to
+ * make; saying they will turn up in `git status`, staged by whoever commits
+ * next, is exactly true and is the thing an operator needs to know.
+ *
+ * A remote tracker is a different question entirely: nothing about git governs
+ * it, and the writes are visible to everyone with access the moment they land.
+ */
+function describeVisibility(grant) {
+    const remote = grant.paths.every(isRemoteRef);
+    if (remote)
+        return "these writes are visible to anyone with access to the tracker, immediately";
+    return grant.observedByGit
+        ? "these writes turn up in `git status` — whoever commits next will pick them up"
+        : "git ignores these paths, so they stay out of `git status` and out of commits";
+}
+/** What is not granted, which is the half people forget to read. */
+export function describeWithheld(grant) {
+    const withheld = MUTATION_CLASSES.filter(one => !grant.mutations.includes(one));
+    if (withheld.length === 0)
+        return [];
+    return [`  will not     ${withheld.join(", ")} — widening takes another \`enroll\``];
+}

package/dist/graph.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Which work graph is already here.
+ *
+ * Chosen by looking, not by asking — an operator who already keeps their work
+ * in beads should not be made to declare that to a tool standing in the same
+ * directory. But **detection is not authorization.** Finding a populated
+ * tracker says it exists; it says nothing about whether its owner wants Night
+ * Orders scheduling, closing, or restructuring what is in it. Nothing here
+ * writes, enrolls, or grants anything.
+ *
+ * **Nothing is ever installed.** No package manager, no package runner, no
+ * initializer — `bd init` stages files, edits agent integrations, and can make
+ * a commit, so it is the operator's to run. This module runs read commands
+ * against binaries that are already on PATH, and prints what it cannot do.
+ *
+ * Data and runtime are detected independently, and that separation is the
+ * point. A populated tracker with no working runtime is real work that this
+ * machine cannot currently dispatch, and saying so at 9am is the whole job —
+ * the alternative is finding out inside a dead loop at 3am.
+ *
+ * Where a fact is not established it is `unverified`, and unverified fails
+ * closed. A backend whose dependency edges we cannot confirm is shown and may
+ * even be recommended, but it is not dispatchable, because §4's rule is that
+ * scheduling edges are never emulated: a private graph other tools cannot see
+ * is shadow data.
+ */
+import { type ExecResult, type RunOptions } from "./exec.js";
+export type BackendKind = "beads" | "backlog-md" | "github-issues";
+/**
+ * Whether the backend carries dependency edges of its own.
+ *
+ * `unverified` is not a soft `native`. It means nobody has confirmed it, and a
+ * scheduler must treat it as absent rather than assume in its own favour.
+ */
+export type Deps = "native" | "unverified" | "none";
+export type Runtime = {
+    state: "ok";
+    version: string | null;
+} | {
+    state: "missing";
+    binary: string;
+} | {
+    state: "outdated";
+    version: string;
+    needs: string;
+} | {
+    state: "unreadable";
+    reason: string;
+};
+/**
+ * What was counted, and which question it answers. A ready count and an open
+ * count are different numbers, and labelling one as the other would misreport
+ * how much work is actually dispatchable.
+ */
+export type Count = {
+    of: "ready" | "open";
+    value: number;
+};
+export type Detection = {
+    kind: BackendKind;
+    label: string;
+    /** Repositories whose data was found on disk, or which have issues. */
+    repos: string[];
+    /** null when nothing could be counted — absence of a number, not zero. */
+    count: Count | null;
+    deps: Deps;
+    runtime: Runtime;
+    /** Whether work here could actually be scheduled tonight. */
+    dispatchable: boolean;
+    /** What could not be read, in words. Never silently dropped. */
+    problems: string[];
+};
+/**
+ * The ladder from §3. `ambiguous` is a deliberate outcome and not a failure:
+ * several populated trackers mean the operator has to say which one, because
+ * task count is not write authority and the biggest tracker may be the
+ * abandoned one.
+ */
+export type Choice = {
+    action: "recommend";
+    kind: BackendKind;
+    dispatchable: boolean;
+    why: string;
+} | {
+    action: "ambiguous";
+    kinds: BackendKind[];
+    why: string;
+} | {
+    action: "built-in";
+    why: string;
+};
+export type ChooseOptions = {
+    /** A backend the operator already enrolled. Outranks anything detected. */
+    enrolled?: BackendKind;
+};
+/**
+ * What the operator would run to set a backend up, and what it would do to
+ * their repository.
+ *
+ * This is text, and stays text. `bd init` creates or updates `AGENTS.md` and
+ * installs Claude and Codex integrations unless told not to — which is a
+ * substantial thing to do to somebody's repository, and not ours to do on
+ * their behalf. A tool that refuses to run `bd init` for you and then quietly
+ * ran it from inside a helpful setup prompt would have spent the only
+ * credibility it had.
+ *
+ * There is deliberately no prompt. A wizard would cost the zero-config opening
+ * this tool is built around, and half the intended audience is an agent or a
+ * scheduled run, where anything that blocks on an answer simply hangs.
+ *
+ * Commands are quoted from each tool's own documentation rather than inferred.
+ * Backlog.md is detected but not offered here, because its install path has
+ * not been verified — and printing a command that has not been checked is how
+ * an operator ends up running the wrong thing on our say-so.
+ */
+export type SetupOption = {
+    kind: BackendKind | "built-in";
+    label: string;
+    /** null when there is nothing to install. */
+    install: string | null;
+    /** null when there is nothing to initialize. */
+    init: string | null;
+    /** What it changes in the repository. Never omitted where there is one. */
+    sideEffects: string | null;
+    note: string | null;
+};
+export declare function setupOptions(): SetupOption[];
+export type Runner = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
+export type DetectOptions = {
+    runner?: Runner;
+    /** Injected so the pure half of detection needs no fixture tree. */
+    exists?: (path: string) => boolean;
+};
+/** Reading a tracker is local work; only the GitHub one crosses the network. */
+export declare const LOCAL_TIMEOUT_MS = 10000;
+export declare const NETWORK_TIMEOUT_MS = 20000;
+/**
+ * Dependency fields on GitHub Issues need a newer `gh` than the REST route
+ * does. The version gate is therefore about *native edges*, not about whether
+ * issues can be read at all — an older gh still counts them, it just cannot be
+ * trusted to schedule from them.
+ */
+export declare const GH_DEPS_MIN_VERSION = "2.94.0";
+export declare const LABELS: Record<BackendKind, string>;
+export declare function detectGraphs(repos: readonly string[], options?: DetectOptions): Promise<Detection[]>;
+/** null when no version-shaped token is present — unknown, not zero. */
+export declare function parseVersion(text: string): string | null;
+/** Negative, zero, or positive, like every other comparator. */
+export declare function compareVersions(left: string, right: string): number;
+/**
+ * The ladder from §3, as a pure function so the policy can be read and tested
+ * without a filesystem.
+ *
+ * The rung that does the most work is the third: several populated repo-local
+ * trackers mean Toolroll stays in discovery until a person says which one.
+ * Picking the largest would be inventing authority out of a row count.
+ *
+ * GitHub Issues is never chosen automatically. It has native edges, but a
+ * populated issue tracker is evidence people file issues, not evidence anyone
+ * wants an unattended agent closing them — the design requires existing
+ * dependency use *and* a confirmed write scope, and neither is established by
+ * looking.
+ */
+export declare function chooseBackend(detections: readonly Detection[], options?: ChooseOptions): Choice;