Skip to content

Instantly share code, notes, and snippets.

@ndelangen

ndelangen/lab02-script-refactor-sequence.md

Created August 1, 2026 20:53
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save ndelangen/f1791363ae71f6c9440f3d04f1391203 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save ndelangen/f1791363ae71f6c9440f3d04f1391203 to your computer and use it in GitHub Desktop.
Download ZIP
Lab-02 behavior-preserving script refactor sequence
Raw
lab02-script-refactor-sequence.md

Lab-02 script refactor sequence

Scope

This is the implementation route for the 76 files below scripts/** at Lab-02 revision 67205a7c10f6ecf4420cfb7c83e537d4b269266c. It applies the decisions in plan issues 104–109, 111, 123, and 124 without changing release behavior.

The accepted prototype at 2c64ed3a41a1a68fe3550aec399a5447808053f4 is evidence, not an integration branch. Implementation starts from a fresh Lab-02 main worktree and replays the accepted interfaces in the smaller sequence below. Do not merge or cherry-pick the prototype commits.

Sequencing decision

Use a hybrid type-cleanup sequence:

  1. When a responsibility obtains its final owner, remove, inline, derive, or rename the affected shallow declarations in that same commit.
  2. After all ownership and template moves, perform one complete residual audit.
  3. Add JSDoc only after that audit, so removed declarations are never documented.

This produces the same entity result as an up-front type sweep while avoiding changes to temporary shapes. The audit tracks the 51 existing aliases selected for removal, not a predetermined raw final alias count; a genuinely new schema owner may still deserve a name.

The earlier placement decision mentioned moving generic npm-pack/process mechanics downward. The pinned implementations do not expose one equal generic contract: consumer smoke intentionally runs npm without --ignore-scripts, has a 10 MiB buffer and raw subprocess failure, and validates only consumer-visible files; publication uses the shared 20 MiB diagnostic runner, ignores scripts, and validates identity, version, integrity, and release artifacts. Parameterizing those differences would create a shallow framework or would harden consumer smoke. Therefore the existing shared process runner remains shared, while both npm-pack procedures stay with their current feature until a genuinely equal second operation emerges.

Invariants held by every commit

  • Preserve generated Markdown and JSON bytes, error messages and throw/no-op behavior, iteration order, Git commands, REST/GraphQL requests, npm commands, retry behavior, and prepare/apply privilege separation.
  • Keep stable and prerelease publication controllers separate and linear. Align only their matching phase vocabulary, artifact inputs, and exact Git-tag/GitHub-Release observation.
  • Keep all 30 workflow-loaded default exports at their existing paths. Do not edit any .github/workflows/*.yml file.
  • Keep scripts/api/v1/workspace-packages.ts and its two exports compatible.
  • scripts/shared/** may runtime-import only node:* and relative modules whose complete runtime graph stays inside scripts/shared/**. It must never reach node_modules, GitHub runtime code, an API entrypoint, or a feature command.
  • GitHub transport, raw response validation, webhook types, injected Actions capabilities, and workflow topology remain in scripts/github/**.
  • Do not add a barrel, compatibility re-export, generic release framework, Markdown builder, schema registry, or endpoint-per-function wrapper layer.
  • A one-call-site helper remains only when it owns a substantial invariant or hides unstable mechanics. Otherwise keep the linear controller step visible.
  • Existing permanent tests move only to follow a new interface owner. Temporary characterization tests may compare old and new private implementations and must be deleted before the affected commit is finalized.

Acceptance commands

Every commit runs git diff --check and npm run check:scripts.

  • F means npm run check in addition to the common commands.
  • T(files...) means node --test with the listed files, in addition to the common commands.
  • Template commits also run a temporary byte-for-byte comparison against the parent implementation for every existing initial, patch, maintenance, prerelease, empty, and migration-bearing fixture. The comparison is removed before commit; the existing durable output tests remain under the new owner.
  • The final branch runs the two-axis code-review skill against its merge-base: repository standards and this plan/spec are reviewed independently.

Commit sequence

C01 — Centralize JSON file I/O

Add scripts/shared/io/json.ts with readJsonFile(path): Promise<unknown> and the existing two-space, trailing-newline writeJsonFile(path, value) contract. Migrate the byte-identical file operations from:

  • scripts/github/controller-support.ts
  • scripts/github/patchback/controller.ts
  • scripts/github/prerelease-phase-entry/controller.ts
  • scripts/github/prerelease-proposal/controller.ts
  • scripts/github/prerelease-publication/controller.ts
  • scripts/github/release-proposal/controller.ts
  • scripts/github/release-publication/controller.ts
  • scripts/github/release-publication/promotion-controller.ts
  • scripts/shared/version/materialize.ts
  • scripts/shared/workspace/packages.ts
  • scripts/consumer-smoke/run.ts

Keep parsing of command stdout local; this interface reads and writes files, not arbitrary JSON strings. Interface effect: one shared file-I/O contract, with no change to domain validators or their errors.

Gate: F.

C02 — Give command inputs explicit owners

Add scripts/shared/cli/options.ts with the existing generic requireOption(options, name) contract. Rename scripts/github/controller-support.ts to scripts/github/controller-inputs.ts; retain only the GitHub-specific token validation there and rename it requireControllerGitHubToken to distinguish it from the injected-client authenticatedToken operation.

Update the seven controllers that consume those operations: patchback, prerelease phase entry, prerelease proposal, prerelease publication, release proposal, release publication, and promotion. Preserve both exact errors.

Gate: F.

C03 — Establish the shared repository-fact owner

Add:

  • scripts/shared/repository.ts owning PILOT_REPOSITORY and PRIMARY_BRANCH;
  • scripts/shared/text/regexp.ts owning the reused regular-expression escaping invariant.

Migrate shared consumers first: patchback core, prerelease-proposal body, prerelease-publication core and manifest, publication routing, release communication records, release-proposal body, and stable publication core and manifests. Keep derived refs and URLs as visible concatenation. Remove PATCHBACK_REPOSITORY and the duplicate PILOT_REPOSITORY declarations.

Gate: T(test/patchback-core.test.ts test/prerelease-proposal-core.test.ts test/release-communication.test.ts test/release-pr-body.test.ts test/release-publication-core.test.ts test/prerelease-publication.test.ts).

C04 — Migrate GitHub repository facts and shared HEAD inspection

Add scripts/shared/git/repository.ts with the genuinely reused semantic operation resolveHeadOid(root). It is allowed despite its small implementation because it has multiple real consumers and names one Git fact; do not add a generic runGit wrapper.

Migrate all GitHub consumers of repository identity, primary-branch refs, and HEAD observation, including package publication, patchback, prepared commits, prerelease phase entry/proposal/publication, release history/proposal/publication, promotion, and the repository adapter. Preserve phrases such as “trusted main” in human-facing errors while constructing refs as heads/${PRIMARY_BRANCH} and refs/heads/${PRIMARY_BRANCH}.

Gate: F. Additionally, rg must find no production declaration of fablebookjs/lab-02 outside scripts/shared/repository.ts, and no direct primary-branch ref literal in the migrated production set.

C05 — Put workflow routing in the GitHub adapter

Move scripts/shared/publication-routing/core.ts to scripts/github/publication-routing/core.ts. Update the classifier handler, stable controller, prerelease controller, and publication-routing test.

Inline the one-use PublicationSource constant annotation. Move the stable PublicationResolution result to this neutral owner and remove the equal PrereleasePublicationResolution alias. The classifier remains pure, but its path/event/branch table is explicitly a hosted Actions contract rather than a shared release-domain fact.

Gate: T(test/publication-routing.test.ts test/prerelease-workflow.test.ts test/github-handler.test.ts) and F.

C06 — Isolate GitHub transport and response narrowing

Inside scripts/github/release-repository/, add transport.ts for authenticated HTTP/GraphQL transport and response-schema.ts for the small reused raw-response narrowing helpers. Inline the one-use GitHubRequestOptions parameter shape.

The existing github.ts temporarily consumes these files while later commits move typed capabilities out. This is not a barrel or compatibility layer: no new re-export is added, and callers that still need raw transport import it directly only until C09 gives them a typed capability.

Gate: T(test/github-handler.test.ts test/release-proposal-core.test.ts).

C07 — Split commit and ref capabilities

Add scripts/github/release-repository/commits.ts and refs.ts. Move commit, tree, blob, comparison, and ref validation/operations from github.ts; update prepared-commit mechanics, patchback, package publication, release history, and the proposal/publication controllers.

  • Rename the adapter response view GitCommit to ValidatedGitCommit.
  • Absorb GitObject into GitReference; use GitReference['object'] where the relationship is the useful interface.
  • Inline PreparedFile into the prepared bundle result.
  • Keep BundleRef and GitReference named.
  • Provide typed Git-database operations used by prepared-commit and patchback mechanics; do not expose REST paths or raw payloads to those callers.

Gate: T(test/prepared-commit-mechanics.integration.test.ts test/patchback.integration.test.ts test/release-proposal.integration.test.ts test/prerelease-phase-entry.test.ts).

C08 — Split pull-request capabilities

Add scripts/github/release-repository/pull-requests.ts. Move the validated PR view, canonical stable/prerelease predicates, listing, lookup, merge-commit resolution, draft creation, close/update operations, and associated-PR pagination there.

Move the substantial marked-comment operation behind reconcileUniqueMarkedIssueComment: it owns pagination, duplicate detection, creation, and update. Patchback retains best-effort assignment policy but calls a typed assignment capability. Remove the one-use IssueComment alias. Make getPullRequestMergeCommitOid private; retain extractPullRequestMergeCommitOid only because its focused test seam remains useful.

Gate: T(test/patchback.integration.test.ts test/release-proposal.integration.test.ts test/prerelease-proposal.integration.test.ts test/prerelease-publication.integration.test.ts).

C09 — Split Release and repository capabilities; remove the catch-all

Add scripts/github/release-repository/releases.ts and repository.ts. Move validated GitHub Release and annotated-tag reads/writes to releases.ts, and allowlisted repository observation to repository.ts. Update package publication, patchback, prerelease publication, release proposal, and stable publication. Remove scripts/github/release-repository/github.ts once empty.

AnnotatedTag remains a named validated schema but becomes module-private. GitHubRelease remains a named validated response view. At the end of this commit, transport.ts is imported only inside release-repository/**; no controller or neutral mechanics module contains a raw REST/GraphQL route.

Gate: T(test/release-publication.integration.test.ts test/prerelease-publication.integration.test.ts test/patchback.integration.test.ts test/release-proposal.integration.test.ts) and F. An rg check must prove that raw transport imports and /repos/ route strings are confined to scripts/github/release-repository/**.

C10 — Deepen repository history around normalized facts

Make every public release-history operation take an explicit root. Extend the pure prepared-commit inspection operations with the same explicit root where history needs commit messages, parents, manifests, or tree validation.

Define normalized ReleaseHistoryCommit and ReleaseHistoryPull facts beside the release-communication derivation that consumes them. The GitHub history adapter converts ValidatedGitPullRequest data to those facts before calling shared code. Shared release communication no longer validates raw GitHub REST shapes.

Reuse the history module from patchback for first-parent traversal, release-cut discovery, commit subjects, parents, and associated PRs. Keep previous-release boundary selection, snapshot exclusion, ancestry/recovery policy, and comment timing in patchback. Make ManagedPrereleaseBoundary module-private while retaining it as a meaningful result concept.

Files: release history, patchback controller, prepared-commit inspection, release-communication records, release proposal, prerelease proposal, phase entry, and their history/communication tests.

Gate: T(test/release-communication.test.ts test/release-proposal-core.test.ts test/release-proposal.integration.test.ts test/prerelease-proposal.integration.test.ts test/prerelease-phase-entry.test.ts test/patchback-core.test.ts test/patchback.integration.test.ts).

C11 — Extract patchback artifact schemas

Add scripts/github/patchback/authority-schema.ts and manifest-schema.ts. Move PatchbackAuthority, PatchbackRecord, PatchbackMigrationRecord, PatchbackManifest, and their external-unknown parsers from the controller. Each schema module exposes one parser and keeps narrow field validators private.

Inline ResolvePatchbackOptions, PreparePatchbackOptions, and ApplyPatchbackOptions into their only function signatures. Keep PatchbackResolution named because it is an operation result. The controller continues to own resolution, preparation, and application order.

Gate: T(test/patchback-core.test.ts test/patchback.integration.test.ts).

C12 — Extract the patchback coordination invariant

Add scripts/github/patchback/coordination.ts. Move authenticated commit trailers, expected parentage, exact tree-change and blob-content verification, and coordination-commit creation behind a focused interface. Use the typed commit/ref adapter from C07.

Keep boundary choice, canonical-PR choice, current-main ancestry, recovery policy, examples-comment timing, and best-effort assignment visibly linear in the controller. Do not extract its remaining one-caller steps merely to shorten the file.

Gate: T(test/patchback-core.test.ts test/patchback.integration.test.ts).

C13 — Share observation of staged prerelease proposals

Add scripts/github/staged-prerelease-proposal/observation.ts with separate interfaces to:

  • observe the prerelease ref and at most one canonical open Prerelease PR;
  • parse the staged proposal without declaring it canonical; and
  • structurally validate a staged proposal when a caller requires that stronger guarantee.

Use it from prerelease-proposal maintenance and phase entry. Maintenance may inspect and repair stale state; phase entry explicitly invokes structural, head, ancestry, and current-phase checks before mutating main. No validation is silently added to a maintenance no-op path.

Gate: T(test/prerelease-proposal-core.test.ts test/prerelease-proposal.integration.test.ts test/prerelease-phase-entry.test.ts).

C14 — Extract prerelease transition schemas

Add:

  • scripts/github/prerelease-proposal/transition-schema.ts;
  • scripts/github/prerelease-phase-entry/transition-schema.ts.

Move each serialized transition union and its one external parser out of the controller. Preserve controller-local canonicality policy. Inline the four one-use prepare/apply option aliases. Keep PhaseEntryApplication, transition results, and discriminated action parents named because they describe real state changes.

Gate: T(test/prerelease-proposal.integration.test.ts test/prerelease-phase-entry.test.ts).

C15 — Extract stable proposal transition schemas

Add scripts/github/release-proposal/transition-schema.ts for release-cut and proposal-maintenance artifacts. Absorb DormantAction, OpenAction, SyncAction, MaterializedAction, and ReplacementAction into the owning MaintenanceAction union. Inline PrepareCutOptions, ApplyCutOptions, PrepareMaintenanceOptions, and ApplyMaintenanceOptions.

Keep release-cut and maintenance orchestration together in the existing controller; no subcontroller or mode framework is introduced.

Gate: T(test/release-proposal-core.test.ts test/release-proposal.integration.test.ts).

C16 — Name publication artifact schemas and consolidate equal concepts

Rename:

  • scripts/shared/release-publication/publication.ts to manifest-schema.ts;
  • scripts/shared/prerelease-publication/publication.ts to manifest-schema.ts;
  • scripts/shared/release-publication/promotion.ts to promotion-schema.ts.

Move the one equal-purpose PublicationBinding concept to scripts/shared/package-publication/publication.ts; remove PrereleasePublicationBinding and PromotionBinding. Move one pure ReleaseCommitView to scripts/shared/release-proposal/core.ts and use it from stable and prerelease authority derivation. Absorb the phase-entry and bootstrap authority-only aliases into PrereleaseAuthority. Derive CommunicationChange as Omit<ReleaseChange, 'oid'>.

Keep manifest schemas separate: their serialization versions and compatibility obligations differ even where some fields coincide.

Gate: T(test/publication-plan.test.ts test/promotion-plan.test.ts test/prerelease-publication.test.ts test/release-publication-core.test.ts).

C17 — Align publication artifact inputs and authority schemas

Add authority-schema.ts under stable and prerelease publication. Move the enriched authority-document parsers from the controllers.

In scripts/github/package-publication/mechanics.ts, introduce the two real reused input contracts:

  • PublicationArtifactOptions for the snapshot/version/tarball artifact;
  • AuthenticatedPublicationArtifactOptions for that artifact plus a GitHub token.

Use them from stable publish/finalize and prerelease publish/reconcile/check/ finalize operations. Inline all remaining one-use operation ...Options aliases in both controllers and the promotion controller. Preserve PromotionResolution and the shared PublicationResolution result.

Gate: T(test/release-publication.integration.test.ts test/prerelease-publication.integration.test.ts test/promotion-preparation.test.ts test/promotion-workflow.test.ts).

C18 — Align exact Git tag and GitHub Release observation

Add the accepted two-caller observeGitHubReleaseCompletion operation to package-publication mechanics. Stable and prerelease controllers map its complete, incomplete, and two contradiction results to their existing, domain-specific errors. The optional expected body remains a deliberate difference: prerelease preflight checks it before skipping all mutation; stable finalization verifies its body during reconciliation.

Do not align npm working directories, prerelease completion/retry policy, cumulative versus incremental communication, authority routes, or mutable next reconciliation.

Gate: T(test/release-publication.integration.test.ts test/prerelease-publication.integration.test.ts test/release-publication-core.test.ts test/prerelease-publication.test.ts) and F.

C19 — Move stable and prerelease GitHub Release presentation

Add the project-owned zero-install scripts/shared/text/dedent.ts—with no third-party license or attribution—and add:

  • scripts/github/release-publication/templates.ts with renderStableGitHubReleaseBody;
  • scripts/github/prerelease-publication/templates.ts with renderPrereleaseGitHubReleaseBody.

Move presentation assembly out of the shared authority cores. Keep validation and round-tripped record parsing shared. Update the two controllers and existing publication tests to exercise the new owners. This is the accepted prototype slice, replayed without its evidence document.

Gate: template byte comparison, T(test/release-publication-core.test.ts test/prerelease-publication.test.ts), and F.

C20 — Replace duplicate Release PR assets with one renderer

Add scripts/github/release-proposal/templates.ts and move renderReleasePrBody plus substantial presentation-only sections there. Keep markers, identity extraction, checkbox recovery, and accepted-body validation in scripts/shared/release-proposal/body.ts.

Delete:

  • .github/release-templates/release-pr-initial.md;
  • .github/release-templates/release-pr-patch.md;
  • scripts/shared/release-proposal/template.ts.

Remove file loading and the template parameter from the controller. Express only the release-kind marker, initial highlights section, and preservation sentence conditionally. Keep the large cohesive renderer input named. Update the root README’s obsolete claim that templates are loaded from Markdown files.

Gate: byte comparison against both parent assets, T(test/release-pr-body.test.ts test/release-proposal.integration.test.ts).

C21 — Move Prerelease PR presentation

Add scripts/github/prerelease-proposal/templates.ts and move only renderPrereleasePrBody and its presentation-only change renderer from the shared body module. Parsing, identity, marker, and accepted-shape validation remain together in scripts/shared/prerelease-proposal/body.ts.

Update the controller and its core/integration tests. Keep the commit-message format in shared/prerelease-proposal/core.ts.

Gate: template byte comparison, T(test/prerelease-proposal-core.test.ts test/prerelease-proposal.integration.test.ts).

C22 — Move Patchback PR presentation

Add scripts/github/patchback/templates.ts. Move renderPatchbackPrBody, the item presentation helper, and the examples text there. Replace the input-free factory with PATCHBACK_EXAMPLES_COMMENT. Keep Patchback commit-message and release/migration-record protocols in shared core. Export presentation markers from the template owner where the controller must recognize its generated PR and comment.

Update patchback controller and tests. Do not move error messages, refs, paths, or commit-message serialization merely because they are strings.

Gate: template byte comparison, T(test/patchback-core.test.ts test/patchback.integration.test.ts).

C23 — Complete the residual entity and export audit

Apply every remaining high-confidence local cleanup from the 156-alias and 332-export audits:

  • inline the nested or one-signature aliases in consumer smoke, events, pull-request description, release communication, release-proposal body, version materialization, and GitHub runtime;
  • rename purpose collisions: workspace discovery/materialization/package-set manifests, workspace package views, release authority pulls, and the zero-install analyzed source;
  • remove the unused deriveReleaseHighlights;
  • make orderMigrationRecords, validateReleaseHighlights, and formatImportBoundaryDiagnostic private;
  • confirm the adapter, prepared-commit, history, and tag exports narrowed in their ownership commits.

The appendix is the completion checklist for all 51 old aliases and eight strong export candidates. Do not create a schema map or indexed-access chain merely to improve a count.

Gate: F, plus a symbol search proving that every appendix “remove” name is gone and the 30 handler defaults and two v1 API exports remain.

C24 — Update architecture and terminology documentation

Update scripts/shared/README.md to state explicitly that no runtime path, including transitive imports, may reach node_modules, and to describe the semantic repository-fact boundary. Update scripts/github/README.md for the typed repository capabilities, GitHub-local publication routing, sibling controllers, schema modules, and template modules. Keep scripts/api/README.md unless wording actually became false.

Add the curated root README.md terminology table with at least Release proposal, Release snapshot, Prerelease snapshot, publication authority, and query-first publication. Documentation describes maintainers’ concepts, not the temporary refactor or the disposable prototype.

Gate: F and rg -n "node_modules" scripts/shared/README.md with human review of the dependency statement.

C25 — Document the surviving API and shared interfaces

Add contextual JSDoc to the surviving versioned API, serialized schemas, domain transitions, validated records, planners, parsers, generic utilities, and reusable operations in scripts/api/v1/** and scripts/shared/**.

Document purpose, reuse boundary, invariants, trust, side effects, ordering, no-op/retry semantics, and caller-relevant failures. Do not restate TypeScript parameters, return types, obvious fields, or local mechanics. A retained single-use schema receives documentation only when it names an independent protocol or invariant.

Gate: git diff --check, npm run check:scripts, and human review against the JSDoc contract; comments do not require new runtime tests.

C26 — Document GitHub interfaces and close the branch gate

Add contextual JSDoc to non-obvious GitHub runtime/adapter capabilities, artifact parsers, template renderers, controller operations, and the shared stable/prerelease observation mechanic. Leave obvious default handlers and linear local steps uncommented. Use @remarks, @example, @throws, and @see only when they answer a real reuse or failure question.

Final gate:

  1. git diff --check
  2. npm run check
  3. confirm no .github/workflows/*.yml diff
  4. confirm all 30 handler paths/default exports and both v1 API exports
  5. confirm no shared runtime import reaches node_modules transitively
  6. measure production TypeScript total LOC, executable/type LOC excluding comments, JSDoc/comment LOC, named exports, and disposition of the 156 original aliases; report measurements as evidence, not targets
  7. run the two-axis code-review skill from the merge-base and require no blocking Standards or Spec finding

Original 76-file disposition ledger

“Unchanged” means the file was inspected and intentionally keeps its current role and bytes. A documentation commit is listed only where useful prose is expected, not merely because JSDoc is the default consideration.

Original file Disposition
scripts/api/README.md Verify after C24; otherwise unchanged because its versioned boundary remains accurate.
scripts/api/v1/workspace-packages.ts Preserve both v1 exports; add contextual API JSDoc in C25.
scripts/consumer-smoke/run.ts Stay a linear feature command; use JSON I/O in C01, inline PackedFile in C23; keep Fablebook assertions and its distinct process behavior local.
scripts/github/README.md Update adapter/routing/schema/template boundaries in C24.
scripts/github/controller-support.ts JSON leaves in C01; rename to controller-inputs.ts and narrow to GitHub token input in C02.
scripts/github/events.ts Keep webhook adapter; derive/remove two intermediaries in C23 and document validated views in C26.
scripts/github/package-publication/mechanics.ts Repository facts C04, typed Release adapter C09, shared artifact inputs C17, observation C18, JSDoc C26.
scripts/github/patchback/apply.ts Unchanged workflow handler.
scripts/github/patchback/controller.ts Utilities C01–C04, typed adapter/history C07–C10, schemas C11, coordination C12, templates C22, JSDoc C26; retain linear policy.
scripts/github/patchback/prepare.ts Unchanged workflow handler.
scripts/github/patchback/resolve.ts Unchanged workflow handler.
scripts/github/prepared-commit/mechanics.ts Repository fact C04, typed commit/ref adapter and PreparedFile inlining C07, explicit-root inspection C10, JSDoc C26.
scripts/github/prerelease-phase-entry/apply.ts Unchanged workflow handler.
scripts/github/prerelease-phase-entry/controller.ts Utilities/facts C01–C04, adapter/history C07–C10, staged observation C13, transition schema/type cleanup C14, JSDoc C26.
scripts/github/prerelease-phase-entry/prepare.ts Unchanged workflow handler.
scripts/github/prerelease-proposal/apply.ts Unchanged workflow handler.
scripts/github/prerelease-proposal/check-pr.ts Use repository facts and typed ref adapter in C04/C07; keep handler role and behavior.
scripts/github/prerelease-proposal/controller.ts Utilities/facts C01–C04, adapter/history C07–C10, staged observation C13, transition schema C14, templates C21, JSDoc C26.
scripts/github/prerelease-proposal/prepare.ts Unchanged workflow handler.
scripts/github/prerelease-publication/check-completion.ts Unchanged workflow handler.
scripts/github/prerelease-publication/controller.ts Utilities/routing C01–C05, typed adapter C07–C09, schema/types C16–C17, aligned observation C18, template C19, JSDoc C26.
scripts/github/prerelease-publication/finalize.ts Unchanged workflow handler.
scripts/github/prerelease-publication/inspect-authority.ts Unchanged workflow handler.
scripts/github/prerelease-publication/prepare.ts Unchanged workflow handler.
scripts/github/prerelease-publication/publish.ts Unchanged workflow handler.
scripts/github/prerelease-publication/reconcile-next.ts Unchanged workflow handler.
scripts/github/prerelease-publication/resolve.ts Unchanged workflow handler.
scripts/github/publication-routing/classify.ts Import move only in C05; default handler contract unchanged.
scripts/github/pull-request/check-description.ts Unchanged workflow handler; shared input type cleanup is internal to its dependency.
scripts/github/release-history/history.ts Repository fact C04, typed PR/commit adapters C07–C08, explicit-root normalized history C10, JSDoc C26.
scripts/github/release-proposal/apply-cut.ts Unchanged workflow handler.
scripts/github/release-proposal/apply-maintenance.ts Unchanged workflow handler.
scripts/github/release-proposal/check-pr.ts Unchanged workflow handler.
scripts/github/release-proposal/controller.ts Utilities/facts C01–C04, typed adapter/history C07–C10, transition schema C15, renderer C20, JSDoc C26; retain cut and maintenance together.
scripts/github/release-proposal/prepare-cut.ts Unchanged workflow handler.
scripts/github/release-proposal/prepare-maintenance.ts Unchanged workflow handler.
scripts/github/release-proposal/signal.ts Unchanged shared workflow handler.
scripts/github/release-publication/controller.ts Utilities/routing C01–C05, typed adapter C07–C09, schema/types C16–C17, observation C18, template C19, JSDoc C26.
scripts/github/release-publication/finalize.ts Unchanged workflow handler.
scripts/github/release-publication/prepare-promotion.ts Unchanged workflow handler.
scripts/github/release-publication/prepare.ts Unchanged workflow handler.
scripts/github/release-publication/promote.ts Unchanged workflow handler.
scripts/github/release-publication/promotion-controller.ts Utilities/facts C01–C04, typed Release adapter C09, promotion schema/types C16–C17, JSDoc C26.
scripts/github/release-publication/publish.ts Unchanged workflow handler.
scripts/github/release-publication/resolve-promotion.ts Unchanged workflow handler.
scripts/github/release-publication/resolve.ts Unchanged workflow handler.
scripts/github/release-repository/github.ts Decompose without a barrel across C06–C09; remove after transport, refs, commits, PRs, Releases, and repository capabilities own its behavior.
scripts/github/runtime.ts Inline/derive GitHubContext in C23; retain handler runtime seam and document injected capabilities in C26.
scripts/release-communication/validate.ts Unchanged linear feature command.
scripts/shared/README.md Strengthen semantic and transitive zero-install boundary in C24.
scripts/shared/package-publication/core.ts Keep package-publication policy; contextual JSDoc C25.
scripts/shared/package-publication/package-set.ts Keep tagged-API compatibility loader; rename private workspace view C23; JSDoc C25.
scripts/shared/package-publication/publication.ts Own common binding in C16; retain planner/adapter seam and document in C25.
scripts/shared/patchback/core.ts Repository fact C03, presentation leaves C22, local type cleanup C23, protocol JSDoc C25.
scripts/shared/prepared-commit/inspection.ts Explicit-root repository inspection C10; retain substantial validators and document C25.
scripts/shared/prerelease-phase-entry/core.ts Keep pure phase planner and protocols; JSDoc C25.
scripts/shared/prerelease-proposal/body.ts Repository fact C03; presentation leaves C21; parser/validator remains and is documented C25.
scripts/shared/prerelease-proposal/core.ts Keep planner and commit-message protocol; JSDoc C25.
scripts/shared/prerelease-publication/core.ts Repository fact C03; authority type consolidation C16; Release presentation leaves C19; JSDoc C25.
scripts/shared/prerelease-publication/publication.ts Rename to manifest-schema.ts and consolidate binding C16; JSDoc C25.
scripts/shared/process/run.ts Keep reused process/error contract; JSDoc C25.
scripts/shared/publication-routing/core.ts Move to GitHub routing C05 because its pure table is still an Actions contract.
scripts/shared/pull-request/description.ts Keep deep one-caller description invariant; inline its shallow input alias C23; JSDoc only if the restriction is not obvious.
scripts/shared/release-communication/records.ts Repository fact C03, normalized history input C10, residual types/exports C23, protocol JSDoc C25.
scripts/shared/release-proposal/body.ts Repository fact C03, renderer leaves C20, residual local types/exports C23, parser/validator JSDoc C25.
scripts/shared/release-proposal/core.ts Gain pure ReleaseCommitView C16; otherwise retain version/proposal protocols and document C25.
scripts/shared/release-proposal/template.ts Delete in C20 with the generic placeholder engine.
scripts/shared/release-publication/core.ts Repository fact C03, authority types C16, Release renderer leaves and unused function is removed C19/C23, JSDoc C25.
scripts/shared/release-publication/promotion.ts Rename to promotion-schema.ts, consolidate binding C16, document C25.
scripts/shared/release-publication/publication.ts Rename to manifest-schema.ts, consolidate binding C16, document C25.
scripts/shared/version/materialize.ts Shared JSON C01, inline/rename local shapes C23, retain version mechanics and document reusable operation C25.
scripts/shared/workspace/packages.ts Shared JSON C01, rename purpose-specific types C23, document discovery interface C25.
scripts/type-safety/check-escapes.ts Unchanged diagnostic command; existing private diagnostic vocabulary remains useful.
scripts/version/set-version.ts Unchanged linear command; its inherited-stdio process behavior is intentionally not forced through shared run.
scripts/workspace/list-packages.ts Unchanged thin command over shared workspace discovery.
scripts/zero-install/check-imports.ts Rename analyzed Source, narrow formatter export C23; preserve import-policy behavior and diagnostics.

New and moved module ledger

Final module Owner
scripts/shared/cli/options.ts Generic required command option.
scripts/shared/git/repository.ts Reused semantic local-Git observations, beginning with HEAD OID.
scripts/shared/io/json.ts JSON file byte contract.
scripts/shared/repository.ts Pilot repository identity and primary branch.
scripts/shared/text/dedent.ts Project-owned tagged-template indentation normalization.
scripts/shared/text/regexp.ts Reused regular-expression escaping invariant.
scripts/github/controller-inputs.ts GitHub controller command-input authentication.
scripts/github/publication-routing/core.ts Pure hosted-workflow route table and route results.
scripts/github/release-repository/transport.ts Raw authenticated GitHub transport.
scripts/github/release-repository/response-schema.ts Adapter-internal raw response primitives.
scripts/github/release-repository/refs.ts Validated Git refs and guarded ref operations.
scripts/github/release-repository/commits.ts Validated commits, trees, blobs, and comparisons.
scripts/github/release-repository/pull-requests.ts Validated PR observation/mutation and marked comments.
scripts/github/release-repository/releases.ts Annotated tags and GitHub Releases.
scripts/github/release-repository/repository.ts Allowlisted repository observation.
scripts/github/patchback/authority-schema.ts Patchback authority artifact.
scripts/github/patchback/manifest-schema.ts Prepared Patchback manifest artifact.
scripts/github/patchback/coordination.ts Coordination commit/tree protocol.
scripts/github/patchback/templates.ts Patchback PR body and examples comment.
scripts/github/staged-prerelease-proposal/observation.ts Neutral staged ref/open PR observation and optional validation.
scripts/github/prerelease-phase-entry/transition-schema.ts Phase-entry transition artifact.
scripts/github/prerelease-proposal/transition-schema.ts Prerelease-proposal transition artifact.
scripts/github/prerelease-proposal/templates.ts Prerelease PR presentation.
scripts/github/release-proposal/transition-schema.ts Stable release-cut and maintenance transition artifacts.
scripts/github/release-proposal/templates.ts Stable Release PR presentation.
scripts/github/release-publication/authority-schema.ts Stable publication authority artifact.
scripts/github/release-publication/templates.ts Stable GitHub Release presentation.
scripts/github/prerelease-publication/authority-schema.ts Prerelease publication authority artifact.
scripts/github/prerelease-publication/templates.ts Prerelease GitHub Release presentation.
scripts/shared/release-publication/manifest-schema.ts Stable publication manifest; moved from publication.ts.
scripts/shared/prerelease-publication/manifest-schema.ts Prerelease publication manifest; moved from publication.ts.
scripts/shared/release-publication/promotion-schema.ts Promotion manifest; moved from promotion.ts.

Existing alias-removal checklist

These are the 51 current declarations whose identities disappear. A replacement owner may retain the useful fields or relationship.

  • PackedFile
  • AuthoritativeWorkflowRunCompletion
  • WorkflowConclusion
  • IssueComment
  • ResolvePatchbackOptions
  • PreparePatchbackOptions
  • ApplyPatchbackOptions
  • PreparedFile
  • PreparePhaseEntryOptions
  • ApplyPhaseEntryOptions
  • PreparePrereleaseProposalOptions
  • ApplyPrereleaseProposalOptions
  • ResolvePrereleasePublicationOptions
  • PrereleasePublicationResolution
  • PreparePrereleasePublicationOptions
  • InspectPrereleaseAuthorityOptions
  • PublishPrereleasePackagesOptions
  • ReconcilePrereleaseNextOptions
  • CheckPrereleaseCompletionOptions
  • DormantAction
  • OpenAction
  • SyncAction
  • MaterializedAction
  • ReplacementAction
  • PrepareCutOptions
  • ApplyCutOptions
  • PrepareMaintenanceOptions
  • ApplyMaintenanceOptions
  • ResolvePublicationOptions
  • PreparePublicationOptions
  • FinalizeReleaseOptions
  • ResolvePromotionOptions
  • PreparePromotionOptions
  • PromoteLatestOptions
  • GitObject
  • GitHubRequestOptions
  • GitHubContext
  • PatchbackMigrationRecord in shared Patchback presentation input
  • PhaseEntryPrereleaseAuthority
  • BootstrapPrereleaseAuthority
  • PrereleasePublicationBinding
  • PublicationSource
  • PullRequestDescription
  • MigrationRecordSource
  • ParsedReleaseRecordChange
  • PredecessorPull
  • RenderMarkdownTemplateOptions
  • duplicate stable-publication GitCommit
  • ComposeGitHubReleaseBodyOptions
  • PromotionBinding
  • JsonObject

The current FinalizePrereleaseOptions, PublishPackagesOptions, PublicationResolution, publication GitCommit, and stable PublicationBinding names are repurposed into neutral owners; they are not additional surviving identities under their old owners.

Strong export-narrowing checklist

  • AnnotatedTag: named but private in the Release capability.
  • PreparedFile: inlined.
  • ManagedPrereleaseBoundary: named but private in release history.
  • getPullRequestMergeCommitOid: private in the PR capability.
  • orderMigrationRecords: private in release communication.
  • validateReleaseHighlights: private in the Release PR body validator.
  • formatImportBoundaryDiagnostic: private in the zero-install command.
  • deriveReleaseHighlights: deleted as unused.

Explicitly untouched hosted contracts

All 16 .github/workflows/*.yml files remain byte-identical. The 30 default handler exports remain at their existing paths. No workflow loader string, input/output name, permission, environment, concurrency key, event, run name, or artifact path changes in this refactor.

The tagged API path scripts/api/v1/workspace-packages.ts, its default export, and WorkspacePackage export remain compatible. The root commands validate:release-communication, set-version, list-packages, check:type-escapes, and check:zero-install-imports retain their package script names and invocation behavior.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment