由 OpenAI Codex 辅助完成;新增回归覆盖 satisfies、非空断言和尖括号类型断言。 Co-authored-by: danyaberezun <danya.berezun@gmail.com>
13 KiB
id, type, status, title, parent, references, tags, depends-on
| id | type | status | title | parent | references | tags | depends-on | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| module-repo-scripts | module-design | active | Repository development and conformance scripts | architecture |
|
|
|
Responsibility
Repository-wide development orchestration and conformance gates that do not belong to one product package. These scripts validate architecture, specification, and artifact assumptions; they never implement product behavior.
Boundary
- Owns: the multi-process development launcher; the on-demand provider sign-in smoke (
smoke:logins); exact-version/catalog validation; the PI binary-seam canary; module dependency/import boundary validation; the UI-text gate (check:i18n); declared-spec-surface to TypeScript-barrel conformance; the on-demand CI flake report (ci:flakes); and focused root contract tests that compose otherwise independent product implementations. - Public surface: the root
package.jsoncommands consumed by developers, Husky, and CI. - Allowed deps: Bun/Node, the developer's authenticated
ghCLI (read-only,ci:flakesonly), the TypeScript 7 API (typescript/async,typescript/ast,typescript/ast/is) for the spec-surface andcheck:i18nchecks,oxc-parserfor the syntax-only import scans of the boundary and binary-seam checks,pi-spec-graph/corefor the canonical spec/frontmatter model, andmdast-util-from-markdownfor CommonMark block structure; read-only inspection of workspace manifests and source trees; the public package metadata and bundle outputs each check validates; and test-only imports of real product internals when a root harness must prove a cross-package contract without creating a product dependency. - Forbidden: product runtime logic, a second source of package or feature behavior, editing source as part of a check, or application-internal imports outside focused root contract tests. A root contract test may compose implementations but must not become the protocol source or a product dependency.
smoke:logins boots a throwaway host in a temp HOME/data/pi-agent sandbox (no ambient credentials, real
network): it runs from the sandbox with --no-env-file and toolHomeEnv, so neither the repo .env nor a
real tool home leaks in, and the host binds port 0 and reports it. For every provider provider.status lists,
it starts each offered sign-in method over the wire, walks every branch of pi's select prompts, and passes
only when each flow reaches its first user step (a sign-in page, a device code, or a prompt); any other
terminal frame (an immediate success included), a 15 s stall, a 10 s request timeout, a dropped host
connection, or zero flows fails it. It waits for the host to exit before deleting the sandbox. It cancels every flow, so nothing
is ever stored, and needs no accounts — it catches a pi upgrade or registry change that breaks how a sign-in
starts, not whether a real credential is accepted. It is on demand, never a commit or CI gate, because it
depends on providers' live endpoints.
check:boundaries runs the checker's focused tests before scanning the real workspace. It enforces both manifest edges and static source imports, including type-only, dynamic, re-export, CommonJS, import-type, package-subpath, and relative cross-module forms. Generated/build directories, including Hutch's projected .hutch SDK trees and transient .cottontail-tmp loaders, are excluded. The current product rings and launcher edges are exhaustive: contracts, pi-delegation, and pi-background-commands → none; pi-subagents and pi-dag → pi-delegation; shared → contracts; server → contracts/shared plus its existing bundled extension and delegation packages; web → contracts, locales, and the browser SDK/extension entries below; CLI → server/shared; desktop → server/shared/contracts/locales; server, UI, and extension web halves may also use locales, which itself has no workspace edges; artifact-tests → CLI/server/shared. Product packages may not import artifact-tests. A future composition root must add an explicit rule rather than silently inheriting access to every workspace package.
The extension boundary follows module-thinkrail-extensions and is registered from discovered manifests, not a fixed extension-name list:
- Discover workspace roots under
apps/*,packages/*,pi-extensions/*, andthinkrail-extensions/*. Every discovered pi extension has no host workspace dependencies. Every ThinkRail extension is scanned, including extensions other than the pilot. - Register
packages/uiandpackages/extension-apionly when present, so the boundary-first delivery does not require future SDK manifests. Both may depend on contracts, never host internals. UI permits per-file public imports; browser consumers of extension-api must use exactly@thinkrail/extension-api/web, not its root, server entry, deep paths, or relative bypasses. Server consumers use its public./serverentry. - An extension manifest may declare the union of its halves' dependencies. Its
web/**sources may use UI, extension-api's public./web, and contracts; itsserver/**sources may use extension-api's public./serverand its correspondingpi-extensions/<name>package. Neither half may import the other, even within the same package, with relative paths, or with type-only syntax. Extension code may not import host internals. apps/webmay consume only the exact public@thinkrail/ext-*/webentry of a discovered extension;packages/serveronly@thinkrail/ext-*/server. Root, deep, opposite-half, and relative source imports are rejected. Their manifests may depend on the extension package because manifests cannot express subpath edges. Existing server pi-package edges remain until each extension's server-wiring delivery.- Browser sources (web app, UI, extension-api's browser half, and extension web halves) must never import extension-api's server half. All of extension-api remains runtime-browser-safe: pi types may describe the server contract, but neither entry may value-import pi. Browser sources and contracts likewise reject pi value imports, including external pi packages not registered as workspace roots. Explicit type imports/re-exports remain subject to the existing workspace-edge rules; a type-only import cannot bypass a forbidden module or source-half edge.
These are static literal-import checks, not a runtime module resolver. Negative filesystem fixtures cover the same discovery and scan entrypoint as the real workspace gate.
ci:flakes (bun run ci:flakes [--days 14] [--repo …] [--workflow ci.yml] [--concurrency 8]) prints a
Markdown report of the CI workflow's test failures over a window, read through gh api; a call failing with a
GitHub 5xx or a timeout is retried twice with backoff, since one transient error would discard the whole run. REST supplies the runs,
the per-attempt jobs of every run that failed, was re-run, or holds a failed job, and failed test jobs' logs;
GraphQL, batched 100 nodes a query (about one rate-limit point per 100 check runs), supplies the PRs updated in
the window and every run's check runs of all attempts with their annotations. A job a re-run carried over from an
earlier attempt (started before it was created) is dropped, so an attempt counts only what it ran, and an
attempt-1 failure counts even when attempt 2 passed. Pure parsers read bun (fail) lines keyed by their
##[group]<file>: context (the closing N tests failed: summary only repeats them) and Playwright
failed/flaky summary blocks, from a failed job's log or else from the 🎭 Playwright Run Summary annotation
every Playwright job publishes, so a test that failed then passed on retry inside a green job is seen.
A change is a PR or, without one, a branch. A run resolves to its PR by head repository and branch (the latest PR
opened by then, since GitHub links only open same-repo PRs to runs) or by its merge-queue pr-<N> branch, so a
PR's runs and queue entries count once. PRs linked because one's base branch is, or was before a retarget,
another's head branch form a stack that counts as one change: members carry each other's commits, so one
deterministic failure would otherwise count once per member. A base resolves to the PR that owned that head
branch when the base was set (the newest opened by then, or the branch's only PR), so a reused branch name
never joins a later PR to an old stack. A merge-queue entry whose
gh-readonly-queue/…/pr-<N>-<sha> base is another entry's head SHA contains that entry's commits, so a test or
step both failed counts for the lower entry's change; a failure the lower entry lacked stays the entry's own. Per
test it counts failures, Playwright flaky passes, distinct changes, merge-queue failures, and failures whose SHA
later passed the same job or a whole run. A test is flake-classified on a passing rerun, a flaky mark, failures
for 3+ changes, or merge-queue failures for 2+ changes; the rest are listed apart as probably genuine. Failed
steps no parsed test explains (build, install, download, or a step failing beside a test failure) are listed by
step, and an attempt counts as flake-only only when every failure in it is a flake-classified test. Known limits:
stacks are seen only through base branches, so PRs sharing commits while all targeting main stay apart, and a
parent PR untouched in the window is not fetched; independent failures inside one stack collapse into one
change, leaving reruns and flaky marks as their evidence; at most 100 check runs per run are read. It automates
the hand analysis behind the 2026-10 CI-flake series; it is a diagnostic, never a gate, and has no scheduled run.
check:spec-surface enrolls only valid specs tagged public-surface-checked. Enrollment is explicit so adding prose cannot silently turn enforcement off: an enrolled spec must retain a bare backticked identifier list and a discoverable TypeScript barrel, or the check fails. Unenrolled prose surfaces remain descriptive and are reported only by --list-skipped.
The TypeScript 7 checker, reached through its API server, resolves the barrel's effective export names, including type-only and default exports and transitive re-exports; a CommonJS export = assignment is the module's singular default surface rather than the assigned value's synthetic members. An unresolved re-export is a violation rather than a silently incomplete surface. The declared and effective name sets must match in both directions. The check uses the async API because the sync client reads Node-internal pipe handles that Bun does not expose; one API process serves every compiler group and is closed before the check returns. Filesystem-level tests exercise enrollment, resolution, and failure behavior through the same runner CI invokes.
check:i18n enforces architecture Decision 23 over apps/web/src, packages/ui, and extension web/
halves (tests and generated files excluded). With the TypeScript 7 AST it rejects literal
UI text in four shapes: JSX text; text-bearing JSX attributes (aria-label, title, placeholder, alt, label,
description, hint, and *Label/*Title/*Description/… props), including literals reached through
conditionals, ||/??, +, and template parts; literal children inside {…}; prose in text-named object
properties (label, title, description, detail, hint, message, reason, …); and literal
toast.*() messages or errorText() fallbacks. "Text" means a run of two or more letters after trimming
symbols, so ⌘K, ·, and counts pass; the bare brand ThinkRail is the one allowed word. It is a
heuristic floor, not a proof: review still owns strings returned from plain functions. The literal scan unwraps
parentheses, type assertions (as and <T>), satisfies, and non-null assertions. It also checks
packages/locales/en.json: keys sorted, values non-empty, and every key (plural base for _one/_other)
referenced as a string literal by some UI, desktop, or locales source, so removed UI leaves no orphaned
translations. Finally, on the same TypeScript API process, it builds the web TypeScript 7 program and fails on any render-time read of the global
translator (module-locales § Render reads the translator as a value): a reference to t, i18n,
currentLocale or currentTranslator from @thinkrail/locales/react evaluated in a render root — a
component or hook body, a class render(), and what they run synchronously: useMemo/useState
initializers, useAppStore selectors, .map-style callbacks, JSX function children and render* props;
a call (direct, through a namespace import, or passed by reference to such a callback) of any function that
reaches them synchronously, default parameters included, transitively; a module-load call; and any getter
or registered tool summary that reads them. Event handlers (on* and other non-render props), effects and
deferred callbacks are event-time and pass. Fixture tests pin each shape, both flagged and allowed. There is no suppression mechanism; a false positive is fixed in the checker with a test.
typecheck:root type-checks root tooling: these scripts and the root Playwright configs, plus the e2e/ helpers those configs import, through the root tsconfig.json. Turbo registers it as //#typecheck:root, and bun run typecheck runs it beside every workspace typecheck. Each nested tooling tree extends the root config with its own include and runs as an extra tsc -p step of typecheck:root (today: e2e/tsconfig.json).