@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/store/branches.d.ts

@@ -0,0 +1,164 @@
+/**
+ * The checkouts and the branches, as the framework reads and acts on them (#1774). The framework
+ * keeps no checkout and imports no branches package: a project's checkouts come from whichever of
+ * its packages declares that it provides them — `"framework": { "branches": "<command>" }` in the
+ * package's own package.json — and the framework reads and moves them by running that command.
+ * Swap the package for another that answers the same command line and prints the same shapes,
+ * and nothing here changes. No package declares it: the project has no checkouts, so no run with
+ * one, no branch to hand off, nothing to remove.
+ *
+ * The command line a provider answers, each printing one JSON document and exiting 0 (a refusal
+ * exits 1 with its reason on stderr):
+ *   `<command> list [--sizes]`                          every checkout, as an array of {@link Checkout}
+ *   `<command> show [--from <commit>] <branch>...`      what each branch holds and where it stands, as an array of {@link BranchState}, in the order asked;
+ *                                                       measured from `<commit>`, where the branches started, in place of the default branch;
+ *                                                       a full commit id in place of a branch is read as a branch that ends there
+ *   `<command> merge <b>`                               merge the branch into the default branch, on this machine, then delete it
+ *   `<command> push --branch <b>`                       push the branch to the remote; a branch only the remote has is answered as it is
+ *   `<command> remove <id> [--from <commit>] [--discard]`  reclaim a run's checkout once its branch holds everything, pushing nothing, its branch measured from the commit it started from; `--discard` drops uncommitted work
+ * `list` and `show` read this machine, no network: the framework polls. `show` answers the branch's
+ * git facts only; its pull request is the git host provider's (`git-host.ts`), as every pull request is.
+ *
+ * That is the whole contract: git, and nothing beyond it (#1820). The framework reads checkouts to
+ * find the runs that have one, and a branch's state for what it composes: the run page's handoff,
+ * the Human Queue's unpushed rows. Opening a pull request is the push here, then the git host
+ * provider's `open`. What a checkout is, where it lives, how a branch is pushed is the package's.
+ *
+ * The shapes, owned here: {@link Checkout}, {@link BranchState}.
+ */
+/** A run's checkout: where it works, as a provider lists it. */
+export interface Checkout {
+    /** The run's id. */
+    id: string;
+    /** The checkout's directory, absolute. */
+    path: string;
+    /** The branch it is on; absent for a checkout on none, or one git no longer knows. */
+    branch?: string;
+    /** The name the agent gave its work, as the provider answers it; absent while the run has not named it. Drawn where a branch would be drawn as a name. */
+    name?: string;
+    /** Its size on disk, when sizes were asked for. */
+    sizeBytes?: number;
+}
+/** One commit a branch holds beyond its base. */
+export interface BranchCommit {
+    sha: string;
+    subject: string;
+}
+/** One file a branch changed against its base. */
+export interface BranchFile {
+    path: string;
+    insertions: number;
+    deletions: number;
+    /** A binary file, where line counts mean nothing. */
+    binary: boolean;
+}
+/** What a branch holds and where it stands, as a provider answers `show`: git facts, no pull request. */
+export interface BranchState {
+    branch: string;
+    /** The name the agent gave its work, as the provider answers it; absent while the run has not named it. */
+    name?: string;
+    /** The branch exists on this machine. Gone: every list below is empty, and only the remote can say more. */
+    exists: boolean;
+    /** What it is measured against: the commit asked with `--from`, else the project's default branch, when one was found. */
+    base?: string;
+    /** The branch's own commits beyond the base, newest first. */
+    commits: BranchCommit[];
+    /** What it changed since it left the base. */
+    files: BranchFile[];
+    /** The project has a remote to push to. */
+    hasRemote: boolean;
+    /** The remote has the branch at this same tip. */
+    pushed: boolean;
+    /** The base already contains it. */
+    merged: boolean;
+    /** The uncommitted paths in the checkout that is on this branch; absent when no checkout is. */
+    pendingFiles?: string[];
+}
+/** What pushing a branch did: `pushed` is false when only the remote had it, so there was nothing here to push. */
+export type PushOutcome = {
+    ok: true;
+    pushed: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * What merging a branch into the project's default branch did: `into` names that branch, `commit`
+ * is the merged branch's last commit and `from` the commit its work began at, and `deleted` says
+ * the branch went once its work was in.
+ */
+export type MergeOutcome = {
+    ok: true;
+    into: string;
+    commit: string;
+    from: string;
+    deleted: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/** What reclaiming a checkout did: done, with the branches that went with it when any did, or the provider's reason it stayed. */
+export type RemoveOutcome = {
+    ok: true;
+    branchesDeleted?: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/** A project's checkouts and branches: what a provider answers, read and moved by the framework. */
+export interface BranchesSource {
+    /**
+     * Every checkout; `[]` when none can be read. `fresh` asks past a list read within the window:
+     * the caller is looking for a checkout that may have just appeared. A list read less than
+     * {@link FRESH_MS} ago still answers, so a caller asking every second for a run that has no
+     * checkout is not a process every second.
+     */
+    list(opts?: {
+        sizes?: boolean;
+        fresh?: boolean;
+    }): Promise<Checkout[]>;
+    /**
+     * Each branch's state, in the order asked; a branch the provider did not answer for is missing.
+     * `[]` when nothing can be read. `from` is the commit the branches started from, which their
+     * commits and files are then measured from. A full commit id in place of a branch reads what a
+     * branch that ended there held.
+     */
+    show(branches: readonly string[], from?: string): Promise<BranchState[]>;
+    /** Push a branch to the remote: the checkout on it under its clean rule, else the branch itself. */
+    push(branch: string): Promise<PushOutcome>;
+    /** Merge a branch into the project's default branch, on this machine, then delete it; a merge that conflicts changes nothing. */
+    merge(branch: string): Promise<MergeOutcome>;
+    /**
+     * Reclaim a run's checkout, or why it stayed. `from` is the commit the run's branch started
+     * from, when that is not the default branch: what tells a branch with nothing of its own.
+     * `discard` drops its uncommitted work instead of refusing over it.
+     */
+    remove(id: string, opts?: {
+        discard?: boolean;
+        from?: string;
+    }): Promise<RemoveOutcome>;
+}
+/** The checkouts of the project at `root`, or `undefined` when none of its packages provides them. */
+export type BranchesFor = (root: string) => Promise<BranchesSource | undefined>;
+/** A {@link BranchesFor} that also forgets what it read of one project, for when a module or a run just wrote there. */
+export type BranchesReader = BranchesFor & {
+    changed(root: string): void;
+};
+/** The rows read back from a provider's `list`: the objects with an id and a path, everything else as printed; anything else is no checkout. */
+export declare function parseCheckouts(output: unknown): Checkout[];
+/** The states read back from a provider's `show`: the objects with a branch and the three verdicts, lists cleaned; anything else is no state. */
+export declare function parseBranchStates(output: unknown): BranchState[];
+/**
+ * The production {@link BranchesReader}: the project's provider, looked up by its package.json,
+ * one source per project kept while the same command provides — so the cache holds across the
+ * many reads of one poll, and a project that installs, swaps or drops its provider is read the new
+ * way within {@link CACHE_MS}. `changed(root)` forgets that project's reads, so the next read runs
+ * the command again: a run just started there, or a module's command just ran, and a checkout may
+ * have come or gone.
+ */
+export declare function providedBranches(now?: () => number): BranchesReader;
+/** The framework's one reader of the checkouts, shared by every caller so they share its cache. */
+export declare const projectBranches: BranchesReader;
+/** A {@link BranchesFor} for a project with no provider: no checkouts. */
+export declare const noBranches: BranchesFor;
+//# sourceMappingURL=branches.d.ts.map

package/dist/store/branches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branches.d.ts","sourceRoot":"","sources":["../../src/store/branches.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,gEAAgE;AAChE,MAAM,WAAW,QAAQ;IACvB,oBAAoB;IACpB,EAAE,EAAE,MAAM,CAAA;IACV,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAA;IACZ,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,0JAA0J;IAC1J,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,yGAAyG;AACzG,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,2GAA2G;IAC3G,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,4GAA4G;IAC5G,MAAM,EAAE,OAAO,CAAA;IACf,0HAA0H;IAC1H,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,8CAA8C;IAC9C,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,2CAA2C;IAC3C,SAAS,EAAE,OAAO,CAAA;IAClB,kDAAkD;IAClD,MAAM,EAAE,OAAO,CAAA;IACf,oCAAoC;IACpC,MAAM,EAAE,OAAO,CAAA;IACf,gGAAgG;IAChG,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CACxB;AAED,mHAAmH;AACnH,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtF;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpI,kIAAkI;AAClI,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnG,oGAAoG;AACpG,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;IACtE;;;;;OAKG;IACH,IAAI,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAA;IACxE,oGAAoG;IACpG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC1C,iIAAiI;IACjI,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAC5C;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;CACxF;AAED,sGAAsG;AACtG,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAA;AAE/E,wHAAwH;AACxH,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG;IAAE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAA;AAQ1E,gJAAgJ;AAChJ,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,EAAE,CAiB1D;AAED,iJAAiJ;AACjJ,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,EAAE,CAqBhE;AAiGD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,MAAiB,GAAG,cAAc,CAa7E;AAED,mGAAmG;AACnG,eAAO,MAAM,eAAe,EAAE,cAAmC,CAAA;AAEjE,0EAA0E;AAC1E,eAAO,MAAM,UAAU,EAAE,WAAmC,CAAA"}

package/dist/store/branches.js

@@ -0,0 +1,187 @@
+import { runPackageCommand } from '@openagt/agent-data';
+import { providedCommand } from '../built-in.js';
+import { isRunId } from './runs.js';
+/** How long a read is reused: the dashboard polls several reads of every project's checkouts every few seconds, and each is a process. */
+const CACHE_MS = 5_000;
+/** How recent a list read still answers a `fresh` ask: younger than this, the checkout the caller looks for was not there a moment ago either. */
+const FRESH_MS = 1_000;
+/** The rows read back from a provider's `list`: the objects with an id and a path, everything else as printed; anything else is no checkout. */
+export function parseCheckouts(output) {
+    if (!Array.isArray(output))
+        return [];
+    const rows = [];
+    for (const value of output) {
+        if (!value || typeof value !== 'object')
+            continue;
+        const row = value;
+        const id = row['agentId'] ?? row['id'];
+        if (typeof id !== 'string' || !isRunId(id) || typeof row['path'] !== 'string' || row['path'] === '')
+            continue;
+        rows.push({
+            id,
+            path: row['path'],
+            ...(typeof row['branch'] === 'string' && row['branch'] !== '' ? { branch: row['branch'] } : {}),
+            ...(typeof row['name'] === 'string' && row['name'] !== '' ? { name: row['name'] } : {}),
+            ...(typeof row['sizeBytes'] === 'number' ? { sizeBytes: row['sizeBytes'] } : {}),
+        });
+    }
+    return rows;
+}
+/** The states read back from a provider's `show`: the objects with a branch and the three verdicts, lists cleaned; anything else is no state. */
+export function parseBranchStates(output) {
+    if (!Array.isArray(output))
+        return [];
+    const states = [];
+    for (const value of output) {
+        if (!value || typeof value !== 'object')
+            continue;
+        const row = value;
+        if (typeof row['branch'] !== 'string' || row['branch'] === '' || typeof row['exists'] !== 'boolean' || typeof row['pushed'] !== 'boolean' || typeof row['merged'] !== 'boolean')
+            continue;
+        states.push({
+            branch: row['branch'],
+            ...(typeof row['name'] === 'string' && row['name'] !== '' ? { name: row['name'] } : {}),
+            exists: row['exists'],
+            ...(typeof row['base'] === 'string' && row['base'] !== '' ? { base: row['base'] } : {}),
+            commits: commitsOf(row['commits']),
+            files: filesOf(row['files']),
+            hasRemote: row['hasRemote'] === true,
+            pushed: row['pushed'],
+            merged: row['merged'],
+            ...(Array.isArray(row['pendingFiles']) ? { pendingFiles: row['pendingFiles'].filter((path) => typeof path === 'string') } : {}),
+        });
+    }
+    return states;
+}
+function commitsOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap(entry => {
+        const commit = entry;
+        return commit && typeof commit['sha'] === 'string' && commit['sha'] !== '' ? [{ sha: commit['sha'], subject: typeof commit['subject'] === 'string' ? commit['subject'] : '' }] : [];
+    });
+}
+function filesOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap(entry => {
+        const file = entry;
+        if (!file || typeof file['path'] !== 'string' || file['path'] === '')
+            return [];
+        return [
+            {
+                path: file['path'],
+                insertions: typeof file['insertions'] === 'number' ? file['insertions'] : 0,
+                deletions: typeof file['deletions'] === 'number' ? file['deletions'] : 0,
+                binary: file['binary'] === true,
+            },
+        ];
+    });
+}
+/** The branches source over one provider command: each read one run of the command, cached per {@link CACHE_MS}; each write drops the reads. */
+function commandBranches(root, command, now) {
+    const listed = new Map();
+    const shown = new Map();
+    const drop = () => {
+        listed.clear();
+        shown.clear();
+    };
+    return {
+        drop,
+        list(opts = {}) {
+            // Concurrent reads share one process; a read that failed is not kept.
+            const key = opts.sizes ? 'sizes' : 'plain';
+            const known = listed.get(key);
+            if (known && now() - known.at < (opts.fresh ? FRESH_MS : CACHE_MS))
+                return known.rows;
+            const read = { at: now(), rows: Promise.resolve([]) };
+            read.rows = runPackageCommand(root, command, ['list', ...(opts.sizes ? ['--sizes'] : [])]).then(result => {
+                if (!result.ok || !Array.isArray(result.output)) {
+                    if (listed.get(key) === read)
+                        listed.delete(key);
+                    return [];
+                }
+                return parseCheckouts(result.output);
+            });
+            listed.set(key, read);
+            return read.rows;
+        },
+        show(branches, from) {
+            const asked = branches.filter(branch => branch !== '');
+            if (asked.length === 0)
+                return Promise.resolve([]);
+            const key = [from ?? '', ...asked].join('\0');
+            const known = shown.get(key);
+            if (known && now() - known.at < CACHE_MS)
+                return known.states;
+            const read = { at: now(), states: Promise.resolve([]) };
+            read.states = runPackageCommand(root, command, ['show', ...(from ? ['--from', from] : []), ...asked]).then(result => {
+                if (!result.ok || !Array.isArray(result.output)) {
+                    if (shown.get(key) === read)
+                        shown.delete(key);
+                    return [];
+                }
+                return parseBranchStates(result.output);
+            });
+            shown.set(key, read);
+            return read.states;
+        },
+        async push(branch) {
+            const result = await runPackageCommand(root, command, ['push', '--branch', branch]);
+            drop();
+            if (!result.ok)
+                return { ok: false, error: result.error };
+            const pushed = result.output && typeof result.output === 'object' ? result.output['pushed'] : undefined;
+            return { ok: true, pushed: pushed !== false };
+        },
+        async merge(branch) {
+            const result = await runPackageCommand(root, command, ['merge', branch]);
+            drop();
+            if (!result.ok)
+                return { ok: false, error: result.error };
+            const out = (result.output && typeof result.output === 'object' ? result.output : {});
+            const { into, commit, from } = out;
+            if (typeof into !== 'string' || typeof commit !== 'string' || typeof from !== 'string')
+                return { ok: false, error: 'the branches provider answered no merge' };
+            return { ok: true, into, commit, from, deleted: out['deleted'] === true };
+        },
+        async remove(id, opts = {}) {
+            if (!isRunId(id))
+                return { ok: false, error: `not a run id: ${id}` };
+            const result = await runPackageCommand(root, command, ['remove', id, ...(opts.discard ? ['--discard'] : opts.from ? ['--from', opts.from] : [])]);
+            drop();
+            if (!result.ok)
+                return { ok: false, error: result.error };
+            const gone = result.output && typeof result.output === 'object' ? result.output['branchesDeleted'] : undefined;
+            const branchesDeleted = Array.isArray(gone) ? gone.filter((branch) => typeof branch === 'string') : [];
+            return branchesDeleted.length ? { ok: true, branchesDeleted } : { ok: true };
+        },
+    };
+}
+/**
+ * The production {@link BranchesReader}: the project's provider, looked up by its package.json,
+ * one source per project kept while the same command provides — so the cache holds across the
+ * many reads of one poll, and a project that installs, swaps or drops its provider is read the new
+ * way within {@link CACHE_MS}. `changed(root)` forgets that project's reads, so the next read runs
+ * the command again: a run just started there, or a module's command just ran, and a checkout may
+ * have come or gone.
+ */
+export function providedBranches(now = Date.now) {
+    const sources = new Map();
+    const reader = async (root) => {
+        let known = sources.get(root);
+        if (!known || now() - known.at >= CACHE_MS) {
+            const command = await providedCommand(root, 'branches').catch(() => undefined);
+            const same = known?.command && command && known.command.bin === command.bin;
+            known = { at: now(), ...(command ? { command, source: same ? known.source : commandBranches(root, command, now) } : {}) };
+            sources.set(root, known);
+        }
+        return known.source;
+    };
+    return Object.assign(reader, { changed: (root) => sources.get(root)?.source?.drop() });
+}
+/** The framework's one reader of the checkouts, shared by every caller so they share its cache. */
+export const projectBranches = providedBranches();
+/** A {@link BranchesFor} for a project with no provider: no checkouts. */
+export const noBranches = async () => undefined;
+//# sourceMappingURL=branches.js.map

package/dist/store/branches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branches.js","sourceRoot":"","sources":["../../src/store/branches.ts"],"names":[],"mappings":"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"}

package/dist/store/forge.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The project's forge, as the framework reads and acts on it (#1820): the pull requests of the
+ * project, opening one, landing one, and the project's page there. The framework names no forge
+ * and runs no forge tool: a project's forge comes from whichever of its packages declares that it
+ * provides it — `"framework": { "forge": "<command>" }` in the package's own package.json — and
+ * the framework asks by running that command. Swap the package for another that answers the same
+ * command line and prints the same shapes, and nothing here changes. No package declares it: the
+ * project has no forge, so no pull requests, and a finished run's last step is the push.
+ *
+ * The command line a provider answers, each printing one JSON document and exiting 0 (a refusal
+ * exits 1 with its reason on stderr):
+ *   `<command> requests [--branch <b>] [--state open|merged|all] [--since <iso>]`
+ *                                                       the project's pull requests, newest first, as an array of {@link ForgeRequest}
+ *   `<command> open --branch <b> --title <t> [--body <text>] [--draft]`
+ *                                                       open the branch's pull request; an open one is answered as it is (`existing`)
+ *   `<command> merge <number>`                          land the pull request: armed to merge on green, or merged at once
+ *   `<command> home`                                    the project's page on the forge, and the forge's name
+ * The branch `open` is asked for must already be on the remote: pushing is the branches
+ * provider's step, and the framework runs it first.
+ *
+ * The shapes, owned here: {@link ForgeRequest}, {@link ForgeHome}.
+ */
+/** A pull request, as a provider lists it. */
+export interface ForgeRequest {
+    number: number;
+    url: string;
+    state: 'open' | 'merged' | 'closed';
+    title: string;
+    draft: boolean;
+    /** The branch the request is from. */
+    branch: string;
+    /** The commit the request's head is at. */
+    head: string;
+    /** ISO creation time. */
+    createdAt: string;
+    /** ISO merge time, for a merged request. */
+    mergedAt?: string;
+}
+/** The project's page on the forge, and what the forge is called: what a link is drawn from. */
+export interface ForgeHome {
+    url: string;
+    name: string;
+}
+/** What asking for requests answered: the list, or why there is none: "none" and "could not tell" are different answers. */
+export type RequestsOutcome = {
+    ok: true;
+    requests: ForgeRequest[];
+} | {
+    ok: false;
+    error: string;
+};
+/** What opening a pull request left: the request, and whether it was open already. */
+export type OpenOutcome = {
+    ok: true;
+    request: {
+        number: number;
+        url: string;
+    };
+    existing: boolean;
+} | {
+    ok: false;
+    error: string;
+};
+/** What landing a pull request did: armed to merge on green, merged at once, or the provider watching its checks. */
+export type MergeOutcome = {
+    ok: true;
+    outcome: 'auto-armed' | 'merged' | 'watching';
+} | {
+    ok: false;
+    error: string;
+};
+/** A project's forge: what a provider answers, read and moved by the framework. */
+export interface ForgeSource {
+    /** The project's pull requests, newest first: all, or one branch's, or by state, or since a time. */
+    requests(opts?: {
+        branch?: string;
+        state?: 'open' | 'merged' | 'all';
+        since?: string;
+    }): Promise<RequestsOutcome>;
+    /** Open a branch's pull request, or answer the open one. */
+    open(branch: string, opts: {
+        title: string;
+        body?: string;
+        draft?: boolean;
+    }): Promise<OpenOutcome>;
+    /** Land a pull request. */
+    merge(number: number): Promise<MergeOutcome>;
+    /** The project's page on the forge; `undefined` when the provider cannot tell (no remote there). */
+    home(): Promise<ForgeHome | undefined>;
+}
+/** The forge of the project at `root`, or `undefined` when none of its packages provides one. */
+export type ForgeFor = (root: string) => Promise<ForgeSource | undefined>;
+/** A {@link ForgeFor} that also forgets what it knows of one project. */
+export type ForgeReader = ForgeFor & {
+    changed(root: string): void;
+};
+/** The rows read back from a provider's `requests`: the objects with the facts a request needs; anything else is no request. */
+export declare function parseRequests(output: unknown): ForgeRequest[];
+/**
+ * The production {@link ForgeReader}: the project's provider, looked up by its package.json, one
+ * source per project kept while the same command provides, so a project that installs, swaps or
+ * drops its forge is read the new way within {@link CACHE_MS}. `changed(root)` forgets the
+ * project, so the next ask looks its provider up again.
+ */
+export declare function providedForge(now?: () => number): ForgeReader;
+/** The framework's one reader of the forge, shared by every caller. */
+export declare const projectForge: ForgeReader;
+/** A {@link ForgeFor} for a project with no forge package. */
+export declare const noForge: ForgeFor;
+//# sourceMappingURL=forge.d.ts.map

package/dist/store/forge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forge.d.ts","sourceRoot":"","sources":["../../src/store/forge.ts"],"names":[],"mappings":"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"}

package/dist/store/forge.js

@@ -0,0 +1,97 @@
+import { readProvidedCommand, runPackageCommand } from '@gemstack/agent-data';
+/** How long a provider lookup is reused: the dashboard asks for the forge on every handoff read. */
+const CACHE_MS = 5_000;
+/** The rows read back from a provider's `requests`: the objects with the facts a request needs; anything else is no request. */
+export function parseRequests(output) {
+    if (!Array.isArray(output))
+        return [];
+    const requests = [];
+    for (const value of output) {
+        if (!value || typeof value !== 'object')
+            continue;
+        const row = value;
+        const state = row['state'];
+        if (typeof row['number'] !== 'number' || typeof row['url'] !== 'string' || (state !== 'open' && state !== 'merged' && state !== 'closed'))
+            continue;
+        requests.push({
+            number: row['number'],
+            url: row['url'],
+            state,
+            title: typeof row['title'] === 'string' ? row['title'] : '',
+            draft: row['draft'] === true,
+            branch: typeof row['branch'] === 'string' ? row['branch'] : '',
+            head: typeof row['head'] === 'string' ? row['head'] : '',
+            createdAt: typeof row['createdAt'] === 'string' ? row['createdAt'] : '',
+            ...(typeof row['mergedAt'] === 'string' ? { mergedAt: row['mergedAt'] } : {}),
+        });
+    }
+    return requests;
+}
+/** A pull request read back from an `open` answer, or undefined. */
+function requestOf(output) {
+    const request = output && typeof output === 'object' ? output['request'] : undefined;
+    return request && typeof request === 'object' && typeof request['number'] === 'number' && typeof request['url'] === 'string' ? { number: request['number'], url: request['url'] } : undefined;
+}
+/** The forge source over one provider command: each call one run of the command. */
+function commandForge(root, command) {
+    return {
+        async requests(opts = {}) {
+            const args = ['requests', ...(opts.branch ? ['--branch', opts.branch] : []), ...(opts.state ? ['--state', opts.state] : []), ...(opts.since ? ['--since', opts.since] : [])];
+            const result = await runPackageCommand(root, command, args);
+            if (!result.ok)
+                return { ok: false, error: result.error };
+            return { ok: true, requests: parseRequests(result.output) };
+        },
+        async open(branch, opts) {
+            const args = ['open', '--branch', branch, '--title', opts.title, ...(opts.body !== undefined ? ['--body', opts.body] : []), ...(opts.draft ? ['--draft'] : [])];
+            const result = await runPackageCommand(root, command, args);
+            if (!result.ok)
+                return { ok: false, error: result.error };
+            const request = requestOf(result.output);
+            if (!request)
+                return { ok: false, error: `${command.name} opened no pull request` };
+            return { ok: true, request, existing: result.output['existing'] === true };
+        },
+        async merge(number) {
+            const result = await runPackageCommand(root, command, ['merge', String(number)]);
+            if (!result.ok)
+                return { ok: false, error: result.error };
+            const outcome = result.output && typeof result.output === 'object' ? result.output['outcome'] : undefined;
+            if (outcome === 'auto-armed' || outcome === 'merged' || outcome === 'watching')
+                return { ok: true, outcome };
+            return { ok: false, error: `${command.name} did not merge` };
+        },
+        async home() {
+            const result = await runPackageCommand(root, command, ['home']);
+            if (!result.ok || !result.output || typeof result.output !== 'object')
+                return undefined;
+            const home = result.output;
+            return typeof home['url'] === 'string' && typeof home['name'] === 'string' ? { url: home['url'], name: home['name'] } : undefined;
+        },
+    };
+}
+/**
+ * The production {@link ForgeReader}: the project's provider, looked up by its package.json, one
+ * source per project kept while the same command provides, so a project that installs, swaps or
+ * drops its forge is read the new way within {@link CACHE_MS}. `changed(root)` forgets the
+ * project, so the next ask looks its provider up again.
+ */
+export function providedForge(now = Date.now) {
+    const sources = new Map();
+    const reader = async (root) => {
+        let known = sources.get(root);
+        if (!known || now() - known.at >= CACHE_MS) {
+            const command = await readProvidedCommand(root, 'forge').catch(() => undefined);
+            const same = known?.command && command && known.command.bin === command.bin;
+            known = { at: now(), ...(command ? { command, source: same ? known.source : commandForge(root, command) } : {}) };
+            sources.set(root, known);
+        }
+        return known.source;
+    };
+    return Object.assign(reader, { changed: (root) => sources.delete(root) });
+}
+/** The framework's one reader of the forge, shared by every caller. */
+export const projectForge = providedForge();
+/** A {@link ForgeFor} for a project with no forge package. */
+export const noForge = async () => undefined;
+//# sourceMappingURL=forge.js.map

package/dist/store/forge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forge.js","sourceRoot":"","sources":["../../src/store/forge.ts"],"names":[],"mappings":"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"}