@golden-frijoles/kit 0.0.0 → 0.2.0

package/dist/lib/gh-rest.mjs

@@ -0,0 +1,229 @@
+// gh-rest.mjs — REST-only GitHub API helpers, for environments where `gh`'s GraphQL proxying is
+// unavailable.
+//
+// Confirmed live (2026-07-02, ops-nightly's Claude Routine sandbox): `gh pr list --json`, `gh pr view
+// --json`, and `gh pr comment` all internally hit `https://api.github.com/graphql` — traced via
+// `GH_DEBUG=api`. `gh run list/rerun` and any `gh api <rest-path>` call always use REST v3 regardless,
+// and were unaffected. This module gives standup.mjs/weekly-recap.mjs/babysit-pr.mjs/build-order-sync.mjs
+// REST-only equivalents for the operations they need, so they no longer depend on GraphQL being reachable.
+//
+// Normalizes every REST response into the SAME shape + casing the codebase's existing pure decision
+// functions already expect (matching GraphQL's statusCheckRollup: UPPERCASE conclusion/state enums,
+// camelCase detailsUrl, mergeable as a MergeableState-style string) — so decideBabysitActions() and the
+// standup's failingOpen/conflictingOpen filters need NO changes, only the I/O layer feeding them does.
+//
+// Zero npm deps — Node >=20 (spawnSync). `gh api` takes GET query params and POST bodies as `-f key=value`
+// pairs (safe: passed as argv, never shell-interpolated) for short payloads, or JSON piped via
+// `--input -` for a comment/PR body that may be long or contain characters `-f` can't safely encode.
+
+import { spawnSync } from 'node:child_process';
+
+function ghApi(args, { input } = {}) {
+  const r = spawnSync('gh', ['api', ...args], {
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+    input,
+  });
+  if (r.status !== 0) return null;
+  try {
+    return JSON.parse(r.stdout || 'null');
+  } catch {
+    return null;
+  }
+}
+
+// ---- pure normalizers (exported for unit testing without gh/network I/O) ----
+
+// GitHub's REST `mergeable_state` (dirty|clean|unstable|has_hooks|unknown|…) → the same coarse
+// MERGEABLE/CONFLICTING/UNKNOWN vocabulary the codebase's `mergeable === 'CONFLICTING'` checks expect
+// (mirroring GraphQL's MergeableState enum, which only ever surfaced as one of those three in practice
+// here). `unknown` means GitHub hasn't finished computing it yet — the caller retries, this just reports
+// what it was handed.
+export function mapMergeableState(mergeableState, mergeableBool) {
+  if (mergeableState === 'dirty') return 'CONFLICTING';
+  if (mergeableState === 'clean' || mergeableState === 'unstable' || mergeableState === 'has_hooks') {
+    return 'MERGEABLE';
+  }
+  if (mergeableBool === false) return 'CONFLICTING';
+  if (mergeableBool === true) return 'MERGEABLE';
+  return 'UNKNOWN';
+}
+
+// Merges the legacy combined-status API + the modern check-runs API into ONE rollup list, normalized to
+// look like a GraphQL statusCheckRollup entry: a check-run item carries {name, status, conclusion,
+// detailsUrl} (status/conclusion uppercase, matching CheckStatusState/CheckConclusionState), a legacy
+// status item carries {context, state, detailsUrl} (state uppercase, matching StatusState) — exactly the
+// two shapes decideBabysitActions()/standup.mjs's failingOpen filter already branch on.
+export function buildStatusRollup({ combinedStatus, checkRuns }) {
+  const rollup = [];
+  for (const s of combinedStatus?.statuses || []) {
+    rollup.push({
+      context: s.context,
+      state: (s.state || '').toUpperCase(),
+      detailsUrl: s.target_url || null,
+    });
+  }
+  for (const c of checkRuns?.check_runs || []) {
+    rollup.push({
+      name: c.name,
+      status: (c.status || '').toUpperCase(),
+      conclusion: c.conclusion ? c.conclusion.toUpperCase() : null,
+      detailsUrl: c.details_url || null,
+    });
+  }
+  return rollup;
+}
+
+// REST pull-list item → the shape standup.mjs's gatherRepoPrs already builds `byNumber`/open/merged sets
+// from (state OPEN/MERGED/CLOSED matching GraphQL's PullRequestState enum casing).
+//
+// `headRefName` (the PR's source branch) was added 2026-07-26 for session-resume.mjs's stray-branch check
+// (README.md D3: "a non-main branch with no open PR") — it needs to correlate a repo's current local
+// branch against open PRs by branch NAME, which the list endpoint already returns as `head.ref` but no
+// existing consumer had asked for yet. Purely additive: every field standup.mjs/babysit-pr.mjs already
+// read is unchanged.
+export function normalizePullListItem(p) {
+  return {
+    number: p.number,
+    title: p.title,
+    state: p.state === 'open' ? 'OPEN' : p.merged_at ? 'MERGED' : 'CLOSED',
+    isDraft: !!p.draft,
+    mergedAt: p.merged_at,
+    createdAt: p.created_at,
+    updatedAt: p.updated_at,
+    url: p.html_url,
+    headSha: p.head?.sha || null,
+    headRefName: p.head?.ref || null,
+  };
+}
+
+// A GitHub Search API (`/search/issues`) item, scoped to `is:pr` → the {number, title, mergedAt, url}
+// shape weekly-recap.mjs already expects.
+export function normalizeSearchPrItem(it) {
+  return {
+    number: it.number,
+    title: it.title,
+    createdAt: it.created_at || null,
+    mergedAt: it.pull_request?.merged_at || null,
+    url: it.html_url,
+  };
+}
+
+// ---- I/O (thin wrappers over `gh api`) ----
+
+// GET /repos/{repo}/pulls?state=… — list PRs (title/state/draft/dates/url only; mergeable and check
+// status are NOT included by the list endpoint — see getPullMergeability/getStatusRollup for those).
+export function listPulls({ repo, state = 'all', perPage = 50 }) {
+  const data = ghApi([
+    `repos/${repo}/pulls`,
+    '--method',
+    'GET',
+    '-f',
+    `state=${state}`,
+    '-f',
+    `per_page=${perPage}`,
+    '-f',
+    'sort=updated',
+    '-f',
+    'direction=desc',
+  ]);
+  return data === null ? null : data.map(normalizePullListItem);
+}
+
+// search/issues — merged PRs with `merged_at >= sinceDate` (day-granular, same as the old GraphQL
+// `merged:>=` search qualifier), optionally scoped to a base branch. Paginates up to maxItems.
+export function searchMergedPrs({ repo, sinceDate, base, maxItems = 500 }) {
+  const items = [];
+  const perPage = 100;
+  for (let page = 1; items.length < maxItems; page += 1) {
+    const q = `repo:${repo} is:pr is:merged merged:>=${sinceDate}${base ? ` base:${base}` : ''}`;
+    const data = ghApi([
+      'search/issues',
+      '--method',
+      'GET',
+      '-f',
+      `q=${q}`,
+      '-f',
+      `per_page=${perPage}`,
+      '-f',
+      `page=${page}`,
+    ]);
+    if (data === null) return null;
+    const pageItems = data.items || [];
+    items.push(...pageItems);
+    if (pageItems.length < perPage) break;
+  }
+  return items.slice(0, maxItems).map(normalizeSearchPrItem);
+}
+
+// GET /repos/{repo}/pulls/{number} — raw response, with GitHub's own documented retry-on-"unknown"
+// pattern: `mergeable`/`mergeable_state` are computed ASYNCHRONOUSLY, so a just-fetched or just-updated
+// PR can report `mergeable_state: "unknown"` on the first try. One retry (2s default) resolves it in
+// practice (confirmed live); if it's still unknown after that, the caller gets 'unknown' back rather
+// than this function guessing.
+function fetchPullWithRetry({ repo, number, retries = 1, delayMs = 2000 }) {
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    const data = ghApi([`repos/${repo}/pulls/${number}`, '--method', 'GET']);
+    if (data === null) return null;
+    if (data.mergeable_state !== 'unknown' || attempt === retries) return data;
+    spawnSync('sleep', [String(delayMs / 1000)]);
+  }
+  return null; // unreachable — the loop always returns on its last iteration
+}
+
+// GET /repos/{repo}/pulls/{number} — just the mapped mergeable state (standup.mjs's use case).
+export function getPullMergeability({ repo, number, retries = 1, delayMs = 2000 }) {
+  const data = fetchPullWithRetry({ repo, number, retries, delayMs });
+  return data === null ? null : mapMergeableState(data.mergeable_state, data.mergeable);
+}
+
+// GET /repos/{repo}/pulls/{number} — the fuller shape babysit-pr.mjs needs in one call: state
+// (OPEN/CLOSED/MERGED, matching GraphQL's PullRequestState casing), headSha (for getStatusRollup), and
+// the mapped mergeable state.
+export function getPull({ repo, number, retries = 1, delayMs = 2000 }) {
+  const data = fetchPullWithRetry({ repo, number, retries, delayMs });
+  if (data === null) return null;
+  return {
+    number: data.number,
+    state: data.state === 'open' ? 'OPEN' : data.merged_at ? 'MERGED' : 'CLOSED',
+    url: data.html_url,
+    headSha: data.head?.sha || null,
+    mergeable: mapMergeableState(data.mergeable_state, data.mergeable),
+  };
+}
+
+// GET commits/{sha}/status + commits/{sha}/check-runs, merged via buildStatusRollup(). `per_page=100`
+// (GitHub's max) on check-runs — its default page size is 30, so an unpaginated call could silently miss
+// failures past page 1 on a commit with many parallel jobs.
+export function getStatusRollup({ repo, sha }) {
+  const combinedStatus = ghApi([`repos/${repo}/commits/${sha}/status`, '--method', 'GET']);
+  const checkRuns = ghApi([
+    `repos/${repo}/commits/${sha}/check-runs`,
+    '--method',
+    'GET',
+    '-f',
+    'per_page=100',
+  ]);
+  // Fail closed on EITHER source failing, not just both — a PARTIAL rollup (one source real, the other
+  // silently empty) is worse than no rollup at all, since it can misreport a genuine failure as "clean."
+  // Callers treat a null rollup as "unavailable" (degrading to no-signal), never as "confirmed clean."
+  if (combinedStatus === null || checkRuns === null) return null;
+  return buildStatusRollup({ combinedStatus, checkRuns });
+}
+
+// POST /repos/{repo}/issues/{number}/comments — works for both issues and PRs (a PR IS an issue for
+// this endpoint, same as `gh pr comment` used under the hood).
+export function postIssueComment({ repo, number, body }) {
+  const data = ghApi([`repos/${repo}/issues/${number}/comments`, '--method', 'POST', '--input', '-'], {
+    input: JSON.stringify({ body }),
+  });
+  return data ? { url: data.html_url } : null;
+}
+
+// POST /repos/{repo}/pulls
+export function createPullRequest({ repo, head, base, title, body }) {
+  const data = ghApi([`repos/${repo}/pulls`, '--method', 'POST', '--input', '-'], {
+    input: JSON.stringify({ head, base, title, body }),
+  });
+  return data ? { url: data.html_url, number: data.number } : null;
+}

package/dist/lib/golden-onboarding.mjs

@@ -0,0 +1,179 @@
+// golden-onboarding.mjs — the Golden Frijoles onboarding surface, named ONCE.
+//
+// ── Why this is a module and not a sentence in three READMEs ───────────────────────────────────
+// golden-flags-by-default S1.4's acceptance is that the text the agent prints, the install page's
+// CLI block and `gf init`'s own next-step line are **one surface**: "the three must say the same
+// thing". Two hand-written copies of `npx @golden-frijoles/cli init` agree right up until one of
+// them is edited, and the one that drifts is always the one nobody runs.
+//
+// So every command a consuming project is ever told to type comes from here, and
+// `scripts/check-onboarding-parity.mjs` (in dobby-foundation, not shipped) asserts the shipped
+// READMEs and AGENTS.md still contain these exact strings.
+//
+// ── The cross-repo half, stated honestly ──────────────────────────────────────────────────────
+// The other two surfaces live in the Golden Frijoles product repo — its `/install` page reads
+// `apps/web/lib/cli-install.ts`, and `gf init` prints from `packages/cli/src/commands/init.ts`.
+// This file cannot import either: they are a different repo, and a template that npm-installs a
+// product's web app to read a string would be absurd. The weld there is the same discipline in the
+// other direction (`cli-install.test.ts` reads `packages/cli/package.json` off disk). Here the
+// values are TRANSCRIBED, each with the file it was transcribed from, and re-checked by hand at
+// every CLI release — `ENV_KEYS` below is the pair that matters, and `preflight.mjs` FAILS LOUDLY
+// if the CLI writes different names, so a drift is caught by running the tool rather than by
+// reading it.
+//
+// ── The env var names are D6 of the CLI epic, and D3 of this one ──────────────────────────────
+// `gf init` writes exactly three names, and deliberately does NOT write `flag_sync` or an ingest
+// key: a verb whose job is "let this app READ its flags" must not put wider credentials on disk as
+// a side effect. `flag_sync` is an operator/deploy credential and belongs in CI secrets — minted on
+// purpose with `gf keys create --type flag_sync`. Never both in one place.
+//
+// Zero deps — Node 18+.
+
+/** The published packages. Transcribed from golden-beans `apps/web/lib/cli-install.ts`. */
+export const CLI_PACKAGE = '@golden-frijoles/cli';
+export const SDK_PACKAGE = '@golden-frijoles/sdk';
+
+/** The binary `npm i -g` puts on PATH. */
+export const CLI_BIN = 'gf';
+
+/**
+ * The minimum CLI this template's contract is written against.
+ *
+ * It is the version that shipped the write path — `flags create --kill-switch --all-envs`, the verb
+ * every kill-switch story in this operating system now names. A project on an older `gf` can read
+ * flags and cannot complete a kill-switch story, which is a failure worth naming at preflight
+ * rather than discovering halfway through one.
+ */
+export const MIN_CLI_VERSION = '0.1.0';
+
+/**
+ * The env var names `gf init` writes and the app reads. ONE definition, on purpose (CLI epic D6):
+ * the file and its reader are generated together in `gf init`, and this is that pair's address on
+ * the template side. `preflight.mjs` and `apps/example-app/flags.mjs` both read it from here.
+ */
+export const ENV_KEYS = {
+  url: 'GOLDEN_FRIJOLES_URL',
+  flagRead: 'GOLDEN_FRIJOLES_FLAG_READ_KEY',
+  environment: 'GOLDEN_FRIJOLES_ENVIRONMENT',
+};
+
+/** The file `gf init` writes, and refuses to write if it cannot get it into `.gitignore`. */
+export const ENV_FILE = '.env.local';
+
+/** The route a `flag_read` key is exercised against — the one that actually serves it. */
+export const SNAPSHOT_PATH = 'api/v1/flags/snapshot';
+
+/** The default deployment, matching the CLI's own `DEFAULT_API_URL`. */
+export const DEFAULT_API_URL = 'https://goldenfrijoles.com';
+
+/**
+ * The ONE command. `npx` first because the promise is "a machine that has never seen it" — a reader
+ * who wants the global install finds it one line below, and a reader who only wants to try it will
+ * not go looking for the shorter form.
+ */
+export const CLI_NPX_INIT = `npx ${CLI_PACKAGE} init`;
+export const CLI_NPX_LOGIN = `npx ${CLI_PACKAGE} login`;
+export const CLI_GLOBAL_INSTALL = `npm i -g ${CLI_PACKAGE}`;
+
+/**
+ * The kill-switch story as the commands that complete it — **including the activation step**.
+ *
+ * D4 of this epic: definitions are catalog-as-code, activations are not. `flags create` does both
+ * in one verb (it creates the definition AND activates it in every environment named), which is
+ * exactly why the distinction has to be written down somewhere a planner reads: `flags sync`, the
+ * catalog-as-code verb, does NOT activate, and a project that syncs its definitions from source
+ * control and never activates them serves compile defaults through the fallback chain while its
+ * console reads "Never turned on here".
+ */
+export const KILL_SWITCH_STORY = [
+  `${CLI_BIN} flags create <domain>.<feature>_enabled --kill-switch --all-envs`,
+  `${CLI_BIN} flags get <domain>.<feature>_enabled    # ← the ACTIVATION check: PRODUCTION must not read "—"`,
+  `${CLI_BIN} flags kill <domain>.<feature>_enabled --env production`,
+];
+
+/**
+ * How to read the activation check's answer, in the CLI's OWN vocabulary.
+ *
+ * ⚠️ **This line shipped wrong once, and the way it was wrong is worth keeping.** It said
+ * `gf flags ls --env production` and told the reader to look for the words *"never turned on"*. Two
+ * separate errors: `gf flags ls` accepts only `--project` and prints all three environments as
+ * columns, so `--env` is a hard usage error that exits 1 before it ever reaches auth; and *"never
+ * turned on here"* is the **web console's** wording, while the CLI's `describeServing` prints `—`.
+ * A reader following it literally would have run a command that cannot run, looking for a string
+ * the tool never prints.
+ *
+ * It survived because it was verified the way prose gets verified — the string was present in every
+ * surface, and `check-onboarding-parity.mjs` was about to weld it into five files. **Presence is not
+ * execution.** A command a doc tells someone to run is checked by running it.
+ */
+export const SERVING_LEGEND = [
+  '—                    never activated here. The consumer is serving its call-site default.',
+  'off (nothing served) activated, then deactivated. Also the call-site default.',
+  '<value>  v<n>        activated, and this is what a context with no attributes actually gets.',
+];
+
+/**
+ * The block an agent prints when a project has no linked Golden Frijoles project.
+ *
+ * Returned as an array of lines rather than one string so a caller can indent it, prefix it or push
+ * it into an existing report without re-wrapping. `preflight.mjs` prints it verbatim on a hard
+ * failure; the READMEs carry it as a fenced block; `check-onboarding-parity.mjs` asserts they match.
+ */
+export function onboardingLines() {
+  return [
+    'This project has no Golden Frijoles project linked, so it cannot create a kill-switch.',
+    'Two commands fix that — the second writes .env.local and prints the snippet that reads it:',
+    '',
+    `  ${CLI_NPX_LOGIN}`,
+    `  ${CLI_NPX_INIT}`,
+    '',
+    `(${CLI_GLOBAL_INSTALL} puts \`${CLI_BIN}\` on your PATH. Every command takes --json.)`,
+  ];
+}
+
+/**
+ * Compare two dotted versions. Returns <0, 0 or >0 — `null` when either is unparseable, because
+ * "we could not tell" and "it is older" lead to different actions and must not collapse.
+ *
+ * Deliberately not semver-complete: prerelease tags are compared as "has one = older than the same
+ * numbers without one", which is the only prerelease rule this check needs and the only one it can
+ * get right without a dependency in a repo that has none.
+ */
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(String(v).trim());
+    return m ? { nums: [Number(m[1]), Number(m[2]), Number(m[3])], pre: m[4] ?? null } : null;
+  };
+  const left = parse(a);
+  const right = parse(b);
+  if (!left || !right) return null;
+  for (let i = 0; i < 3; i += 1) {
+    if (left.nums[i] !== right.nums[i]) return left.nums[i] - right.nums[i];
+  }
+  if (left.pre === right.pre) return 0;
+  if (left.pre === null) return 1;
+  if (right.pre === null) return -1;
+  return left.pre < right.pre ? -1 : 1;
+}
+
+/**
+ * The value of `name` in a dotenv file, or null.
+ *
+ * ⚠️ **The LAST assignment wins.** `dotenv` assigns in file order, so a later line overrides an
+ * earlier one — and a reader that returns the FIRST will confidently report on a value the running
+ * app does not use. Two duplicate lines is not exotic: it is what a hand-edit plus a re-run of
+ * `gf init` produces. Same rule, same reason, as the CLI's own `readEnvValue`.
+ *
+ * No interpolation, deliberately: this reads a file to decide whether a credential is present, and
+ * expanding `$VAR` would make that answer depend on the environment doing the reading.
+ */
+export function readEnvValue(contents, name) {
+  let found = null;
+  for (const line of String(contents).split('\n')) {
+    const match = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=\\s*(.*)$`).exec(line);
+    if (!match) continue;
+    const raw = match[1].trim().replace(/^(['"])(.*)\1$/, '$2');
+    found = raw === '' ? null : raw;
+  }
+  return found;
+}