repo_readiness.ts

Whether each configured repo sits where the registry puts it, read from the entries repos status --json reports: the facts gitops_publish --wetrun gates on, the ones gitops_sync refuses or warns on, and the at-rest block the read-only diagnostics print.

Pure — a report's facts in, problems and their messages out; no git calls. The facts are decided on the Rust side (at_rest, fetch_error, a checkout's busy, needs_human); this reads them, never re-derives them.

Three readings:

  • at rest (repo_readiness_at_rest) — the primary checkout on the branch the entry follows, clean (untracked files count), no operation in progress, and that branch in sync with its origin upstream as of the local remote-tracking refs. What the diagnostics report.
  • ready to publish (repo_readiness_for_publish) — at rest, except that the followed branch may be ahead of origin (origin's tip is then an ancestor, so the plan misses nothing and the release push is still a fast-forward), and also fetched without error (so the relation is origin's current word), no other live Claude Code session in the primary checkout (the executor commits there), and nothing the entry leaves to a person (needs_human).
  • ready to generate (repo_readiness_for_gen) — what gitops_sync needs before it writes the dashboard's site data: the primary checkout on its branch, clean, and idle, since the site pairs each repo's local tree with origin's CI. The followed branch's relation to origin and a failed fetch only warn.
view source

Declarations
#

13 declarations

check_gen_readiness
#

repo_readiness.ts view source

(options: { report: { version: 18; workspace: string; registry: string; fetched: boolean; sessions: { kind: "available"; unscoped: { pid: number; cwd: string; worktree: string | null; process_cwd: string | null; source: "session_file" | "roster_worker"; }[]; } | { ...; }; entries: { ...; }[]; unregistered: ({ ...; } | ... 4 more ... | { ...; })[] | null; }; keys: readonly string[]; allow_dirty?: boolean | undefined; now?: number | undefined; } & RepoReadinessFormatOptions): Result<...> import {check_gen_readiness} from '@fuzdev/fuz_repos/repo_readiness.js';

Checks a repos status --json report on the repos gitops_sync generates the site data from (repo_readiness_for_gen).

options

type { report: { version: 18; workspace: string; registry: string; fetched: boolean; sessions: { kind: "available"; unscoped: { pid: number; cwd: string; worktree: string | null; process_cwd: string | null; source: "session_file" | "roster_worker"; }[]; } | { ...; }; entries: { ...; }[]; unregistered: ({ ...; } | ... 4 m... & RepoReadinessFormatOptions

returns

Result

warnings, a line per problem that doesn't refuse; and on failure also a message naming each refused repo, what's wrong, and the fix, and its lines

check_publish_readiness
#

repo_readiness.ts view source

(options: { report: { version: 18; workspace: string; registry: string; fetched: boolean; sessions: { kind: "available"; unscoped: { pid: number; cwd: string; worktree: string | null; process_cwd: string | null; source: "session_file" | "roster_worker"; }[]; } | { ...; }; entries: { ...; }[]; unregistered: ({ ...; } | ... 4 more ... | { ...; })[] | null; }; keys: readonly string[]; } & RepoReadinessFormatOptions): Result<...> import {check_publish_readiness} from '@fuzdev/fuz_repos/repo_readiness.js';

Checks a repos status --fetch --json report on the repos a real publish reads and writes: every key's entry ready (repo_readiness_for_publish), the report fetched, and busy detection available, since a live session it can't vouch for may be working in any checkout.

options

type { report: { version: 18; workspace: string; registry: string; fetched: boolean; sessions: { kind: "available"; unscoped: { pid: number; cwd: string; worktree: string | null; process_cwd: string | null; source: "session_file" | "roster_worker"; }[]; } | { ...; }; entries: { ...; }[]; unregistered: ({ ...; } | ... 4 m... & RepoReadinessFormatOptions

returns

Result

ahead, the ready repos whose followed branch is ahead of origin; and on failure a message naming each repo, what's wrong, and the fix, its lines, and every not-ready repo

format_readiness_ahead
#

repo_readiness.ts view source

(ahead: ReadinessAhead, publishes: boolean, options?: RepoReadinessFormatOptions): string import {format_readiness_ahead} from '@fuzdev/fuz_repos/repo_readiness.js';

Says what happens to a ready repo's commits ahead of origin: its release push carries them when it publishes, else they stay unpushed.

ahead

the repo, its branch, and how many commits it's ahead

type ReadinessAhead

publishes

whether the plan publishes it

type boolean

options

the repos invocation the message names

type RepoReadinessFormatOptions
default {}

returns

string

the line to log

format_readiness_block
#

repo_readiness.ts view source

(not_ready: readonly RepoReadiness[], now: number): string[] import {format_readiness_block} from '@fuzdev/fuz_repos/repo_readiness.js';

Formats the diagnostics' readiness block: a header and a line per problem, saying what each repo not at rest is doing instead — or no lines when every repo is at rest. Not a failure: the diagnostics read repos as they sit.

not_ready

type readonly RepoReadiness[]

now

the current time in unix seconds, for how long ago each repo was fetched

type number

returns

string[]

the block's lines, unindented header first

format_repo_readiness_problem
#

repo_readiness.ts view source

(key: string, problem: RepoReadinessProblem, options?: RepoReadinessFormatOptions): { what: string; fix: string; } import {format_repo_readiness_problem} from '@fuzdev/fuz_repos/repo_readiness.js';

What a readiness problem says is wrong with the repo keyed key, and the fix, when there is one to name.

key

the repo's registry key

type string

problem

one of the repo's readiness problems

type RepoReadinessProblem

options

the repos invocation fixes name

type RepoReadinessFormatOptions
default {}

returns

{ what: string; fix: string; }

what's wrong, and the fix

ReadinessAhead
#

repo_readiness.ts view source

ReadinessAhead import type {ReadinessAhead} from '@fuzdev/fuz_repos/repo_readiness.js';

A ready repo whose followed branch is ahead of origin: commits a publish pushes.

key

type string

branch

type string

commits

type number

repo_readiness_at_rest
#

repo_readiness.ts view source

(entry: { key: string; kind: "repo" | "reference"; dir: string; url: string; writable: boolean; archived: boolean; visibility: "public" | "private" | null; ci: boolean; branch: string | null; pinned: boolean; ... 13 more ...; visibility_check: { ...; } | ... 2 more ... | null; }): RepoReadinessProblem[] import {repo_readiness_at_rest} from '@fuzdev/fuz_repos/repo_readiness.js';

The ways an entry's primary checkout isn't at rest where the registry puts it, from its at_rest facts: empty when it is.

entry

the entry as repos status --json reported it

type ReposEntryStatus

returns

RepoReadinessProblem[]

the problems, in a fixed order: unprobed alone, else branch, dirt, operation, then the followed branch's relation

repo_readiness_for_gen
#

repo_readiness.ts view source

(entry: { key: string; kind: "repo" | "reference"; dir: string; url: string; writable: boolean; archived: boolean; visibility: "public" | "private" | null; ci: boolean; branch: string | null; pinned: boolean; ... 13 more ...; visibility_check: { ...; } | ... 2 more ... | null; }, options?: { ...; }): { ...; } import {repo_readiness_for_gen} from '@fuzdev/fuz_repos/repo_readiness.js';

An entry's problems for gitops_sync, split by what they do to the run: refused stops it, warned is logged. Off its branch, dirty, or mid-operation refuses, since the site would show that working tree's modules beside origin's CI — unless allow_dirty, which reads the repo as it sits and warns instead. A checkout that can't be read, or an entry following no branch (only a reference follows none, and the config refuses references), always refuses. The followed branch not in sync with origin (behind, say: CI is origin's tip, the modules the local tree) and a failed fetch (the last fetch's view stands) warn. Busy sessions and needs_human reasons don't matter: generating writes nothing in the repo.

entry

the entry as repos status --json reported it

type ReposEntryStatus

options

type { allow_dirty?: boolean | undefined; }
default {}

returns

{ refused: RepoReadinessProblem[]; warned: RepoReadinessProblem[]; }

the problems that refuse, and those that warn

repo_readiness_for_publish
#

repo_readiness.ts view source

(entry: { key: string; kind: "repo" | "reference"; dir: string; url: string; writable: boolean; archived: boolean; visibility: "public" | "private" | null; ci: boolean; branch: string | null; pinned: boolean; ... 13 more ...; visibility_check: { ...; } | ... 2 more ... | null; }): RepoReadinessProblem[] import {repo_readiness_for_publish} from '@fuzdev/fuz_repos/repo_readiness.js';

The ways an entry isn't ready for gitops_publish --wetrun: not at rest (repo_readiness_at_rest) other than its followed branch being ahead of origin, its fetch failed, another live session works in its primary checkout, or it has a needs_human reason. Ahead is ready: origin's tip is an ancestor of the branch, so the plan misses nothing and gro publish's push stays a fast-forward, pushing those commits with the release (see format_readiness_ahead). A reason restating an at-rest problem (the primary's operation or detached HEAD) is left out, and a default_branch_* reason stands in for the followed-branch problem it explains.

entry

the entry as repos status --fetch --json reported it

type ReposEntryStatus

returns

RepoReadinessProblem[]

the problems; empty when the entry is ready

RepoReadiness
#

RepoReadinessFormatOptions
#

repo_readiness.ts view source

RepoReadinessFormatOptions import type {RepoReadinessFormatOptions} from '@fuzdev/fuz_repos/repo_readiness.js';

Options for the messages naming what's wrong and the fix.

repos_command?

The repos invocation fixes name; repos --registry <path> when the run passed one.

type string

RepoReadinessProblem
#

repo_readiness.ts view source

RepoReadinessProblem

type { kind: "unprobed"; detail: string; } | { kind: "no_branch"; } | { kind: "off_branch"; branch: string; head: { kind: "branch"; name: string; } | { kind: "detached"; commit: string; }; } | { kind: "dirty"; uncommitted: { staged: number; unstaged: number; untracked: number; conflicted: number; }; } | { kind: "in_progress"; op: "rebase" | "merge" | "cherry_pick" | "revert" | "bisect" | "sequencer" | "am" | null; } | { kind: "followed"; branch: string; relation: { kind: "in_sync"; } | { kind: "ahead"; commits: number; } | { kind: "behind"; commits: number; } | { kind: "diverged"; ahead: number; behind: number; } | { kind: "shallow"; } | { kind: "gone"; } | { kind: "unmapped"; } | { kind: "untracked"; } | null; } | { kind: "fetch_failed"; failure: { kind: "ref_gone"; refname: string; fix: { kind: "unset_refspec"; pattern: string; } | { kind: "set_branches"; branch: string | null; } | { kind: "by_hand"; }; } | { kind: "unreachable"; cause: "dns" | "connection" | "host_key" | "auth"; message: string; } | { kind: "repo_not_found"; message: string; } | { kind: "timed_out"; after_secs: number; } | { kind: "failed"; message: string; } | { kind: "refspec_outside_origin"; refspec: string; } | { kind: "origin_refs_shared"; remote: string; refspec: string; } | { kind: "legacy_remotes_unreadable"; path: string; }; } | { kind: "busy"; sessions: { pid: number; cwd: string; worktree: string | null; process_cwd: string | null; source: "session_file" | "roster_worker"; }[]; } | { kind: "needs_human"; reason: { kind: "not_a_repo"; detail: string; } | { kind: "operation_in_progress"; checkout: string; op: "rebase" | "merge" | "cherry_pick" | "revert" | "bisect" | "sequencer" | "am"; } | ... 12 more ... | { ...; }; }

import type {RepoReadinessProblem} from '@fuzdev/fuz_repos/repo_readiness.js';

One way a repo isn't where the registry puts it, or isn't ready to publish.

repos_not_at_rest
#

repo_readiness.ts view source

(entries: readonly { key: string; kind: "repo" | "reference"; dir: string; url: string; writable: boolean; archived: boolean; visibility: "public" | "private" | null; ci: boolean; branch: string | null; pinned: boolean; ... 13 more ...; visibility_check: { ...; } | ... 2 more ... | null; }[]): RepoReadiness[] import {repos_not_at_rest} from '@fuzdev/fuz_repos/repo_readiness.js';

The repos not at rest, for the read-only diagnostics' readiness block.

entries

the entries of the repos a diagnostic reads

type readonly ReposEntryStatus[]

returns

RepoReadiness[]

each entry with at-rest problems, in the order given

Imported by
#