vouchington-tooling 0.2.0 → 0.3.0

package/dist/retrospective-facts/index.d.mts

@@ -0,0 +1,3 @@
+import type { RetrospectiveFactsOptions } from './shared.mts';
+export type { CommandExecutor, CommandResult, RetrospectiveFactsOptions } from './shared.mts';
+export declare function runRetrospectiveFacts(options: RetrospectiveFactsOptions): Promise<string>;

package/dist/retrospective-facts/index.mjs

@@ -0,0 +1,26 @@
+import { shell } from './exec.mjs';
+import { foreignFacts } from './foreign.mjs';
+import { localFacts } from './local.mjs';
+export async function runRetrospectiveFacts(options) {
+    validate(options);
+    const execute = options.execute ?? shell;
+    return options.repo ? foreignFacts(options, execute) : localFacts(options, execute);
+}
+function validate(options) {
+    if (options.pr !== undefined && !/^\d+$/.test(options.pr))
+        throw new Error('--pr requires a number');
+    if (options.branch !== undefined && (!options.branch || options.branch.startsWith('-')))
+        throw new Error('--branch requires a name');
+    if (options.repo !== undefined && !/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(options.repo))
+        throw new Error('--repo requires an owner/name value');
+    if (options.pr && options.noPr)
+        throw new Error('--pr and --no-pr are mutually exclusive');
+    if (options.repo && options.branch)
+        throw new Error('--branch cannot be combined with --repo');
+    if (options.repo && options.noPr)
+        throw new Error('--no-pr cannot be combined with --repo');
+    if (options.repo && !options.pr)
+        throw new Error('--repo requires --pr (a foreign repo has no current PR for this local branch)');
+    if (!options.pr && !options.branch && !options.noPr)
+        throw new Error('pass --pr <number>, --branch <name>, or --no-pr');
+}

package/dist/retrospective-facts/local.d.mts

@@ -0,0 +1,2 @@
+import { type CommandExecutor, type RetrospectiveFactsOptions } from './shared.mts';
+export declare function localFacts(options: RetrospectiveFactsOptions, execute: CommandExecutor): Promise<string>;

package/dist/retrospective-facts/local.mjs

@@ -0,0 +1,144 @@
+import { rawBlock } from './exec.mjs';
+import { apiFiles, count, dirs, format, objectField, readJson, stringField, topDirs, } from './format.mjs';
+import { PR_JSON_FIELDS, } from './shared.mjs';
+export async function localFacts(options, execute) {
+    const calls = [];
+    const run = async (command, args) => {
+        const result = await execute(command, args);
+        calls.push({ command, args, result });
+        return result;
+    };
+    const mainSpec = 'main:refs/remotes/origin/main';
+    const branchSpec = options.branch
+        ? `${options.branch}:refs/remotes/origin/${options.branch}`
+        : undefined;
+    const fetch = await run('git', ['fetch', 'origin', mainSpec]);
+    const branchFetch = branchSpec ? await run('git', ['fetch', 'origin', branchSpec]) : undefined;
+    const originMain = fetch.ok ||
+        (await run('git', ['rev-parse', '--verify', '--quiet', 'refs/remotes/origin/main'])).ok;
+    const branchResult = await run('git', ['branch', '--show-current']);
+    const localBranch = text(branchResult) || 'unavailable';
+    const selector = options.noPr ? undefined : (options.pr ?? options.branch);
+    const ghArgs = selector ? ['pr', 'view', selector, '--json', PR_JSON_FIELDS] : undefined;
+    const gh = ghArgs ? await run('gh', ghArgs) : undefined;
+    const data = gh?.ok ? readJson(gh.stdout) : undefined;
+    const state = options.noPr
+        ? 'none'
+        : stringField(data, 'state', gh?.ok ? 'unavailable' : gh ? 'gh failed' : 'unavailable');
+    const head = stringField(data, 'headRefName');
+    const branch = options.branch ??
+        (options.pr && head !== 'unavailable' ? head : options.noPr ? localBranch : 'unavailable');
+    const rangeName = options.branch ?? (options.noPr ? localBranch : undefined);
+    const localRange = options.noPr && options.branch === undefined && localBranch === 'unavailable'
+        ? 'HEAD'
+        : rangeName;
+    const resolved = localRange
+        ? await resolveNamedRef(localRange, run, localRange === options.branch && branchFetch?.ok === true)
+        : unresolvedRange();
+    const range = resolved.range;
+    const commitsResult = !data && range && originMain
+        ? await run('git', ['rev-list', '--count', `origin/main..${range}`])
+        : undefined;
+    const diffResult = !data && range && originMain
+        ? await run('git', ['diff', '--name-only', `origin/main...${range}`])
+        : undefined;
+    const scoped = Boolean(options.branch &&
+        (localBranch !== options.branch || (head !== 'unavailable' && head !== options.branch))) || Boolean(options.pr && !options.branch && (head === 'unavailable' || head !== localBranch));
+    const scope = options.branch ?? `#${options.pr}`;
+    const status = scoped
+        ? undefined
+        : await run('git', ['status', '--porcelain', '--untracked-files=normal']);
+    const reflog = scoped || branch === 'unavailable'
+        ? undefined
+        : await run('git', ['reflog', 'show', `origin/${branch}`]);
+    const merge = objectField(data, 'mergeCommit', 'oid');
+    const merged = await mergeFact(data, state, merge, resolved.range, originMain, options, run);
+    const filesText = diffResult?.ok ? text(diffResult) : undefined;
+    const raw = options.raw
+        ? `\n=== Raw Command Output ===\n${calls.map((call) => rawBlock(call.command, call.args, call.result)).join('')}`
+        : '';
+    return format({
+        fetch: `git fetch origin ${mainSpec}${branchSpec ? `; git fetch origin ${branchSpec}` : ''}`,
+        fetchStatus: fetch.ok ? 'ok' : 'failed',
+        fetchNote: `${fetch.ok
+            ? 'origin/main refreshed'
+            : originMain
+                ? 'using existing local origin/main ref after failed fetch'
+                : 'origin/main unavailable after failed fetch'}${resolved.refreshed ? `; origin/${localRange} refreshed` : ''}`,
+        branch,
+        pr: options.noPr ? 'none' : stringField(data, 'number'),
+        state,
+        mergedAt: stringField(data, 'mergedAt'),
+        mergeCommit: merge,
+        merged,
+        commits: data ? 'unavailable' : commitsResult?.ok ? text(commitsResult) : 'unavailable',
+        prCommits: data ? count(data, 'commits') : undefined,
+        files: data
+            ? apiFiles(data)
+            : filesText === undefined
+                ? 'unavailable'
+                : String(lines(filesText).length),
+        dirs: data ? dirs(data) : filesText === undefined ? 'unavailable' : topDirs(filesText),
+        changeSource: data ? 'api' : 'local',
+        remote: reflog === undefined
+            ? undefined
+            : reflog.ok
+                ? String(lines(text(reflog)).length)
+                : 'unavailable',
+        pushes: reflog === undefined
+            ? undefined
+            : reflog.ok
+                ? String(lines(text(reflog)).filter((line) => line.includes('update by push')).length)
+                : 'unavailable',
+        ...(scoped ? { scoped: scope } : {}),
+        working: status === undefined
+            ? undefined
+            : status.ok
+                ? String(lines(text(status)).length)
+                : 'unavailable',
+    }, raw);
+}
+function text(result) {
+    return result.stdout.trim();
+}
+function lines(value) {
+    return value.split('\n').filter(Boolean);
+}
+async function resolveNamedRef(name, run, fetched = false) {
+    if (name === 'HEAD')
+        return { range: name, refreshed: false };
+    if ((await run('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${name}`])).ok)
+        return { range: name, refreshed: false };
+    const fetch = fetched
+        ? { ok: true, stdout: '', stderr: '' }
+        : await run('git', ['fetch', 'origin', `${name}:refs/remotes/origin/${name}`]);
+    if (!fetch.ok)
+        return { range: undefined, refreshed: false };
+    if ((await run('git', ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${name}`])).ok)
+        return { range: `origin/${name}`, refreshed: true };
+    return { range: undefined, refreshed: false };
+}
+function unresolvedRange() {
+    return { range: undefined, refreshed: false };
+}
+async function mergeFact(data, state, merge, range, originMain, options, run) {
+    if (merge && originMain) {
+        const inOrigin = await run('git', ['merge-base', '--is-ancestor', merge, 'origin/main']);
+        if (!inOrigin.ok)
+            return inOrigin.exitCode === 1 ? `no (origin/main lacks ${merge})` : 'unavailable';
+        const inLocalMain = await run('git', ['merge-base', '--is-ancestor', merge, 'main']);
+        if (!inLocalMain.ok && inLocalMain.exitCode === 1)
+            options.onWarning?.(`Warning: local main lacks PR merge commit ${merge}, but origin/main contains it.`);
+        return `yes (origin/main contains ${merge})`;
+    }
+    if (data && (state === 'OPEN' || state === 'CLOSED'))
+        return 'unmerged at time of retro';
+    if (!data && range && originMain) {
+        const rangeInOrigin = await run('git', ['merge-base', '--is-ancestor', range, 'origin/main']);
+        if (rangeInOrigin.ok)
+            return `yes (origin/main contains ${range})`;
+        if (rangeInOrigin.exitCode === 1)
+            return `no (origin/main lacks ${range})`;
+    }
+    return 'unavailable';
+}

package/dist/retrospective-facts/shared.d.mts

@@ -0,0 +1,17 @@
+export declare const PR_JSON_FIELDS = "number,state,mergedAt,mergeCommit,changedFiles,files,commits,headRefName,baseRefName";
+export type CommandResult = {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode?: number | null;
+};
+export type CommandExecutor = (command: string, args: string[]) => Promise<CommandResult>;
+export type RetrospectiveFactsOptions = {
+    pr?: string;
+    branch?: string;
+    noPr?: boolean;
+    repo?: string;
+    raw?: boolean;
+    execute?: CommandExecutor;
+    onWarning?: (message: string) => void;
+};

package/dist/retrospective-facts/shared.mjs

@@ -0,0 +1 @@
+export const PR_JSON_FIELDS = 'number,state,mergedAt,mergeCommit,changedFiles,files,commits,headRefName,baseRefName';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -46,6 +46,16 @@
       "import": "./dist/retrospective-transcript/index.mjs",
       "default": "./dist/retrospective-transcript/index.mjs"
     },
+    "./retrospective-facts": {
+      "types": "./dist/retrospective-facts/index.d.mts",
+      "import": "./dist/retrospective-facts/index.mjs",
+      "default": "./dist/retrospective-facts/index.mjs"
+    },
+    "./agent-blackboard": {
+      "types": "./dist/agent-blackboard/index.d.mts",
+      "import": "./dist/agent-blackboard/index.mjs",
+      "default": "./dist/agent-blackboard/index.mjs"
+    },
     "./session-friction": {
       "types": "./dist/session-friction/index.d.mts",
       "import": "./dist/session-friction/index.mjs",
@@ -239,7 +249,16 @@
     "yaml": "2.9.0"
   },
   "devDependencies": {
-    "@types/picomatch": "^4.0.3"
+    "@types/picomatch": "^4.0.3",
+    "agent-blackboard": "^0.3.1"
+  },
+  "peerDependencies": {
+    "agent-blackboard": "^0.3.1"
+  },
+  "peerDependenciesMeta": {
+    "agent-blackboard": {
+      "optional": true
+    }
   },
   "optionalDependencies": {
     "@libpg-query/parser": "^18.0.0"

package/scripts/gha/harness-admission-lane.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "${#}" -ne 1 ]; then
+  echo "usage: harness-admission-lane.sh <lanes>" >&2
+  exit 2
+fi
+
+if [ -z "${GITHUB_OUTPUT:-}" ]; then
+  echo 'GITHUB_OUTPUT must be set' >&2
+  exit 2
+fi
+
+LANES="$1"
+if ! [[ "$LANES" =~ ^[1-9][0-9]*$ ]]; then
+  echo "::error::admission lane count must be a positive integer, got: '$LANES'"
+  exit 1
+fi
+
+RUN_ID="${GITHUB_RUN_ID:-}"
+if ! [[ "$RUN_ID" =~ ^[0-9]+$ ]]; then
+  echo "::error::GITHUB_RUN_ID must be a non-negative integer, got: '${RUN_ID}'"
+  exit 1
+fi
+
+echo "lane=$(( RUN_ID % LANES ))" >> "$GITHUB_OUTPUT"

package/scripts/gha/harness-assert-gates.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "$#" -eq 0 ]; then
+  echo "usage: harness-assert-gates.sh <gate>..." >&2
+  exit 2
+fi
+
+for gate in "$@"; do
+  if ! [[ "$gate" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
+    echo "::error::invalid gate name: '$gate'"
+    exit 1
+  fi
+done
+
+for gate in "$@"; do
+  value="${!gate:-}"
+  if [ "$value" = "true" ]; then
+    echo "::error::$gate must be disabled but is enabled"
+    exit 1
+  fi
+done
+
+exit 0