feat: official GitHub Action for shipping pkg binaries

[robertsLando]

Packaging a Node.js app with pkg inside a GitHub Actions workflow today means hand-rolling the same pipeline over and over: install @yao-pkg/pkg, run it, locate the outputs, rename them, compress them, generate checksums, upload as artifacts or attach to a release. Every consumer reinvents this boilerplate and the results diverge (naming schemes, compression formats, checksum algorithms, cross-compile caveats, etc.).

Proposal

Ship a first-party yao-pkg/pkg-action repository that wraps the common pipeline. A minimal consumer should look like:

- uses: yao-pkg/pkg-action@v1
  with:
    config: .pkgrc.json
    targets: node22-linux-x64,node22-macos-arm64,node22-win-x64
    compress: tar.gz           # or zip, tar.xz, 7z, none
    filename: '{name}-{version}-{os}-{arch}'
    checksum: sha256
    attach-to-release: true

Inputs (initial scope)

Build configuration

• config — path to pkg config (package.json, .pkgrc once feat: support a .pkgrc configuration file #238 lands, custom JSON/JS). Auto-detect by default.
• entry — entry script if not specified in config.
• targets — comma/newline-separated list. Defaults to host target.
• mode — standard or sea.
• node-version — override the bundled Node.js major (e.g. 22, 24).
• compress-node — pass-through for pkg's --compress (Brotli/GZip/None).
• fallback-to-source — pass-through for the bytecode fallback flag (feat: add --fallback-to-source flag for bytecode failures #246).
• public — expose source (--public).
• extra-args — escape hatch for raw pkg CLI flags.

Post-build

• compress — archive format: tar.gz | tar.xz | zip | 7z | none, one archive per target.
• filename — output filename template. Tokens: {name}, {version}, {target}, {node}, {os}, {arch}, {sha} (short commit), {ref}, {date}, {tag}.
• checksum — sha256 | sha512 | md5 | none (or comma list). Emits sidecar *.sha256 files and a combined SHASUMS256.txt.
• strip — strip debug symbols on Linux/macOS.

Signing & notarization

• macos-sign-identity / macos-keychain-password — codesign wrapper.
• macos-notarize + Apple ID / team ID / app-specific password — notarytool wrapper.
• windows-sign-cert / windows-sign-password — signtool wrapper.

Publishing

• upload-artifact — upload each produced file as a workflow artifact (default true).
• artifact-name — artifact name template (defaults to filename).
• attach-to-release — if the triggering ref is a tag, attach to the matching GitHub Release.
• release-tag — override the target release tag.
• draft-release / prerelease — pass-through to gh release.

Performance

• cache — cache pkg-fetch Node.js downloads (default true).
• cache-key — override the cache key.

Outputs

• binaries — JSON array of produced binary paths (pre-compression).
• artifacts — JSON array of final uploaded file paths (post-compression).
• checksums — path to the combined SHASUMS*.txt.
• version — resolved package version used in templating.

Stretch goals

• Matrix helper — auto-expand targets into a job matrix so each platform runs on its native runner, dodging the cross-compile pitfalls tracked in NodeJS 22/24 issues/feedbacks tracker #87 / Cross-compilation from macOS to Linux on arm64 broken on >=22 #181.
• Release notes block — render a markdown table of binaries + sizes + checksums and append it to the release body.
• SBOM generation — emit CycloneDX/SPDX per binary.
• SLSA / provenance — integrate with actions/attest-build-provenance.
• Docker image — optionally wrap the Linux binary in a distroless image and push to GHCR.
• Homebrew / Scoop manifests — generate and PR formula/manifest updates on release.
• Step summary — markdown table with build time, binary size, compressed size, checksum per target.
• Smoke-test hook — run a user-supplied script against each produced binary (ties into ci: add end-to-end integration workflow with zwave-js-ui #240).

Implementation notes

• Prefer a composite action so setup-node + cache actions compose naturally; drop to a small JavaScript action only for pieces that need real logic (templating, checksums, archive creation, signing orchestration).
• Keep the action repo separate from yao-pkg/pkg so it can version and release on its own cadence, but document the supported pkg major range.
• Publish to the GitHub Marketplace once v1 stabilizes.
• Seed examples/ with: single-binary release, multi-OS matrix, SEA mode, signed macOS bundle, attach-to-release.

Part of #235

[robertsLando]

yao-pkg/pkg-action — Implementation Plan

Upstream issue: yao-pkg/pkg#248 — feat: official GitHub Action for shipping pkg binaries

1. Context

Today, every downstream project that ships @yao-pkg/pkg binaries from GitHub Actions rebuilds the same pipeline: install pkg, run it, rename the outputs, archive, checksum, upload, attach to the release. Results diverge (naming, compression, checksum algo) and the cross-compile landmines tracked in #87 / #181 are rediscovered every time. The roadmap issue #235 calls out a first-party action as the missing piece.

This plan proposes a new repository yao-pkg/pkg-action — a standalone, versioned GitHub Action that wraps the full pipeline: build → (optional) strip/sign/notarize → (optional) Windows resource edit → archive → checksum → upload/release → step summary. The action is enterprise-grade (typed inputs, typed errors, unit + e2e coverage, GHES-friendly, secret-hygienic, pinnable by SHA) and honors Issue #248 scope while adding the Windows metadata recipe the user flagged as a bonus.

2. Success criteria

Goal	Measure
Minimal boilerplate for a user shipping pkg binaries	Issue-#248 "minimal consumer" snippet works verbatim
Safe across all three runner OSes + matrix mode	CI e2e matrix green on ubuntu/macos/windows
Enterprise-grade	yarn lint && yarn test clean, ≥85 % unit coverage, zero any in hot paths
Lean dependency footprint	Runtime deps ≤ 6 packages; node: natives preferred over userland wherever the stdlib suffices (see §16)
Future-proof runtime shape	Node ≥ 22, pure ESM ("type": "module"), TypeScript pinned to match Node's bundled amaro parser, runs locally via node --experimental-strip-types — no ts-node, tsx, or Babel in the toolchain
Native-first test runner	node:test + node --test --experimental-test-coverage — no vitest, no jest
Signed & notarized bundles	macOS notarize path works against a real Apple ID pair (secrets injected)
Windows metadata	resedit post-processing exposed as both integrated inputs AND a standalone sub-action
Cross-compile landmines guided, not buried	matrix: true expands targets into a per-OS job matrix with the right runner
Reproducible & auditable	Pinnable by SHA, provenance attestation stretch input, no network side-effects outside pkg itself

3. Repository layout

New repo: yao-pkg/pkg-action (separate from yao-pkg/pkg so it versions/releases independently — confirmed in #248 implementation notes).

pkg-action/
├── action.yml                          # top-level composite (marketplace entry)
├── package.json                        # yarn workspaces, "type": "module"
├── yarn.lock
├── .node-version                       # pinned to an EXACT patch (e.g. 22.12.0) — see §11 runtime floor
├── tsconfig.base.json                  # strict, ESNext, NodeNext, erasableSyntaxOnly: true
├── .eslintrc.cjs                       # matches pkg's ESLint style
├── .prettierrc                         # matches pkg
├── README.md
├── CHANGELOG.md                        # release-it, conventional commits
├── LICENSE                             # MIT (match pkg)
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                      # lint + unit + integration on push/PR (Node 22 & 24)
│   │   ├── e2e.yml                     # real-repo e2e matrix (ubuntu/macos/windows)
│   │   ├── e2e-signed.yml              # manually-dispatched signed/notarized e2e (secrets-gated)
│   │   ├── release.yml                 # tag → publish to marketplace, fast-forward `v1`
│   │   ├── dependabot-bundle.yml       # rebuild dist/ + action.yml on Dependabot PRs
│   │   └── codeql.yml                  # security scan
│   └── dependabot.yml
├── matrix/                             # PUBLIC sub-action: yao-pkg/pkg-action/matrix@v1
│   └── action.yml                      # runs.using: node24, main: ../packages/matrix/dist/index.mjs — source lives in packages/matrix/
├── windows-metadata/                   # PUBLIC sub-action: yao-pkg/pkg-action/windows-metadata@v1
│   └── action.yml                      # runs.using: node24, main: ../packages/windows-metadata/dist/index.mjs
├── scripts/
│   ├── bundle.ts                       # esbuild orchestration (all sub-actions) — run via strip-types
│   └── gen-action-yml.ts               # reads inputs.ts metadata → writes action.yml + docs/inputs.md
├── packages/
│   ├── core/                           # @pkg-action/core — shared TS lib (ESM), not a sub-action
│   │   ├── src/
│   │   │   ├── inputs.ts               # hand-rolled validator (no zod) — typed parse + mutex checks
│   │   │   ├── logger.ts               # @actions/core wrapper, debug grouping
│   │   │   ├── errors.ts               # typed error classes + annotation helper
│   │   │   ├── templates.ts            # filename/artifact-name template engine (no deps)
│   │   │   ├── targets.ts              # parse/normalize/matrix-expand target triples (no deps)
│   │   │   ├── pkg-runner.ts           # spawn pkg CLI via @actions/exec
│   │   │   ├── pkg-output-map.ts       # map each on-disk pkg output back to its target triple (replicates pkg's diff-only naming heuristic)
│   │   │   ├── strip.ts                # strip binaries (Linux/macOS) via node:child_process
│   │   │   ├── archive.ts              # tar.gz | tar.xz via system `tar`; zip via yazl (in-process, deterministic perms); 7z via system `7z`
│   │   │   ├── checksum.ts             # node:crypto — sha256/sha512/md5 + SHASUMS*.txt
│   │   │   ├── windows-metadata.ts     # resedit programmatic integration (icon, version, strings)
│   │   │   ├── macos-sign.ts           # codesign + ephemeral keychain (node:child_process)
│   │   │   ├── macos-notarize.ts       # xcrun notarytool + staple
│   │   │   ├── windows-sign.ts         # signtool + Azure Trusted Signing (modern)
│   │   │   ├── uploader.ts             # @actions/artifact + @actions/github for releases
│   │   │   ├── sbom.ts                 # CycloneDX generator — deferred to M6; decision on scope in Open Q #4
│   │   │   ├── provenance.ts           # hooks into actions/attest-build-provenance (stretch)
│   │   │   ├── summary.ts              # GH step summary markdown table (no deps)
│   │   │   └── fs-utils.ts             # node:fs/promises — safe-tmp, atomic rename, chmod
│   │   ├── test/
│   │   │   ├── unit/                   # *.test.ts — run via `node --test --experimental-strip-types`
│   │   │   ├── integration/            # against real fixtures (pre-built .exe, pre-built linux bin)
│   │   │   └── fixtures/
│   │   └── package.json
│   ├── build/                          # source for the composite-invoked build action
│   │   ├── action.yml                  # runs.using: node24 — used only by the top-level composite, not published as a sub-action path
│   │   ├── src/
│   │   │   ├── main.ts                 # pre-run: inputs → pkg → finalize → outputs
│   │   │   └── post.ts                 # post-run cleanup: unmount keychains, wipe temp creds
│   │   ├── dist/                       # esbuild ESM bundle (checked in, required for JS actions)
│   │   └── package.json
│   ├── matrix/                         # source — action.yml served from /matrix/action.yml at repo root
│   │   ├── src/main.ts
│   │   ├── dist/                       # esbuild ESM bundle → referenced by /matrix/action.yml via relative main
│   │   └── package.json
│   └── windows-metadata/               # source — action.yml served from /windows-metadata/action.yml at repo root
│       ├── src/main.ts
│       ├── dist/                       # esbuild ESM bundle
│       └── package.json
├── examples/
│   ├── 01-single-binary/
│   ├── 02-multi-os-matrix/
│   ├── 03-sea-mode/
│   ├── 04-signed-notarized-macos/
│   ├── 05-signed-windows-with-metadata/
│   ├── 06-attach-to-release/
│   ├── 07-reproducible-build/
│   └── 08-docker-distroless/           # stretch
└── docs/
    ├── inputs.md                       # auto-generated from inputs.ts metadata (same source as action.yml codegen)
    ├── outputs.md
    ├── recipes.md
    ├── migration.md                    # from hand-rolled workflows
    └── troubleshooting.md

4. Action shape — composite top-level + ESM TS sub-actions

Issue #248 explicitly prefers a composite top-level "so setup-node + cache actions compose naturally". The pkg-action user also wants TypeScript, enterprise-grade, unit/e2e tested. Those two constraints pull in opposite directions — composite actions can't be unit-tested and hide complex logic in YAML.

Resolution: hybrid.

• action.yml at the repo root is composite. It handles the thin glue: setup-node (optional), PKG_CACHE_PATH normalization + actions/cache, npm i -g @yao-pkg/pkg@<version> (skippable via pkg-path), then delegates to ./packages/build (a Node24 JS sub-action).
• All non-trivial logic lives in packages/core (pure TS library, pure ESM) and is orchestrated by packages/build/src/main.ts. This is what we unit-test.
• packages/matrix and packages/windows-metadata are separately-exposed Node24 sub-actions for users who only want those bits.

Why hybrid beats the alternatives

• Pure composite: logic scattered across shell steps, un-testable, secret-leaky on Windows (cmd.exe quoting).
• Pure Node-JS action: re-implements cache + setup-node logic; loses the compose-with-existing-actions ergonomics the issue author (= the user reviewing this plan) wants.
• Hybrid: core is a pure library = easy to unit test; build is a thin adapter; composite top-level still lets users layer their own actions/cache or setup-node versions above.

Composite action.yml is code-generated

Composite actions don't support with: { ...passthrough } — every input for an inner uses: step must be enumerated explicitly. With ~40 inputs that's error-prone YAML nobody maintains correctly. We treat action.yml as a generated artifact:

• Single source of truth: packages/core/src/inputs.ts (the typed validator) — each input has a metadata record (name, description, default, required, secret flag).
• scripts/gen-action-yml.ts (run via node --experimental-strip-types) reads that metadata and emits the three action.yml files (top-level composite + three sub-actions).
• Pre-commit: regenerates and errors if the tree differs. CI job runs the same git diff --exit-code action.yml packages/*/action.yml check, mirroring the dist/ staleness gate.
• README/docs inputs.md is emitted from the same source — never hand-written.

Cache path normalization

actions/cache pointed at ~/.pkg-cache is wrong: pkg-fetch uses XDG on Linux, %LOCALAPPDATA%\pkg-cache on Windows, and honors PKG_CACHE_PATH on every platform. The composite's first step exports PKG_CACHE_PATH=$RUNNER_TEMP/pkg-cache (cross-platform, deterministic, scoped to the run) and keys actions/cache on that single path. No per-OS conditionals needed.

Sub-action resolution paths

GitHub resolves owner/repo/<path>@ref by reading <repo>/<path>/action.yml. For yao-pkg/pkg-action/matrix@v1 to work the action.yml must live at the repo root under /matrix/. We split the layout accordingly:

• /matrix/action.yml (2 lines — runs.using, main) points at ../packages/matrix/dist/index.mjs. Same shape for /windows-metadata/action.yml.
• Source stays monorepo'd under packages/matrix/src/; the esbuild bundler writes to packages/matrix/dist/.
• The main composite (/action.yml) also lives at the root for marketplace discoverability; its delegated JS action lives at packages/build/ and is referenced by composite uses: ./packages/build (resolves relative to the action's own checkout, so it works when consumers pull yao-pkg/pkg-action@v1).
• Sub-action main: paths use ../packages/... — GitHub allows relative paths including .. inside the action repo; CI tests this explicitly to catch regressions.

Module system — pure ESM, pinned TypeScript

• Every package.json ships "type": "module". Source imports carry explicit .js suffixes (NodeNext convention) so both the stripped-types runtime and the bundled dist/*.mjs resolve identically.
• CommonJS-only toolkit deps (@actions/*) are consumed via Node's built-in ESM↔CJS interop — no wrapper shims, no require monkey-patching.
• TypeScript: pinned to the version compatible with the Node floor's bundled amaro parser (see §11 for the pin rationale). tsconfig.base.json:
  • target: ESNext
  • module: NodeNext, moduleResolution: NodeNext
  • strict: true, noUncheckedIndexedAccess: true, exactOptionalPropertyTypes: true
  • erasableSyntaxOnly: true — compiler-enforced that sources stay strip-types-safe (no enum, no namespaces, no decorators metadata, no import = / export =, no parameter properties). Guarantees local dev via node --experimental-strip-types never diverges from the bundled output.
  • verbatimModuleSyntax: true — keeps import type explicit, avoids emit surprises.
• Local dev loop: node --experimental-strip-types path/to/main.ts. No ts-node, no tsx, no swc-node. Source runs straight in Node.
• Production runtime shape inside the action: bundled by esbuild --bundle --format=esm --platform=node --target=node22 to dist/index.mjs. A single-file ESM bundle is what runs.using: node24 executes — no node_modules shipped in the action.

5. Input surface (v1)

Inputs are parsed by packages/core/src/inputs.ts using a hand-rolled validator (no zod, no runtime schema library — inputs are strings, the validation surface is small and well-known). Every input is typed via discriminated unions; booleans coerce from 'true' | 'false'; lists accept both comma- and newline-separated values. The validator is ~200 LOC, 100 % unit-tested, zero runtime deps.

Mutual-exclusion rules enforced at parse time (illustrative, not exhaustive):

• windows-sign-mode: signtool requires windows-sign-cert + windows-sign-password; forbids all azure-* inputs.
• windows-sign-mode: trusted-signing requires all azure-* credentials; forbids windows-sign-cert / windows-sign-password.
• macos-notarize: true requires all of macos-apple-id, macos-team-id, macos-app-password; also requires macos-sign-identity (can't notarize an unsigned binary).
• attach-to-release: true + non-tag trigger requires explicit release-tag.
• matrix sub-action outputs → consumer's yao-pkg/pkg-action step must receive a single target value, not a list.

Each rule has a named unit test.

5.1 Build configuration

Input	Type	Default	Notes
config	string (path)	auto-detect	.pkgrc*, pkg.config.{js,ts,json}, package.json#pkg — matches #238 when it lands
entry	string (path)	from config
targets	list<string>	host target	node22-linux-x64,node22-macos-arm64,...
mode	enum	standard	standard | sea
node-version	string	22	pkg's bundled Node major
compress-node	enum	None	Brotli | GZip | None — maps to pkg -C
fallback-to-source	boolean	false	pkg #246 flag
public	boolean	false	pkg --public
public-packages	list	—	pkg --public-packages
options	list	—	V8 options baked into binary
no-bytecode	boolean	false
no-dict	list	—
debug	boolean	false	pkg --debug
extra-args	string	—	Escape hatch; appended verbatim
pkg-version	string	~${SUPPORTED_MAJOR}	Pinned to the pkg minor-range this pkg-action major was tested against (e.g. pkg-action v1 defaults to ~6.16.0). Users opt into latest or a different range explicitly. Controls npm i -g @yao-pkg/pkg@<ver>.

5.2 Post-build

Input	Type	Default	Notes
strip	boolean	false	strip debug symbols on Linux/macOS
compress	enum	none	tar.gz | tar.xz | zip | 7z | none
filename	string	{name}-{version}-{os}-{arch}	Tokens: {name}, {version}, {target}, {node}, {os}, {arch}, {sha}, {ref}, {date}, {tag}
checksum	list<enum>	sha256	none | sha256 | sha512 | md5 — multiple allowed

5.3 Windows metadata (new — user-requested bonus)

Maps to docs-site advanced-windows-metadata.md (the resedit recipe). Applies post-pkg, pre-archive, for every *-win-* target. Input precedence: explicit inputs > windows-metadata-file JSON > package.json fallbacks.

Input	Type	Maps to resedit	Notes
windows-metadata-file	string (path)	all	Single JSON file — cleaner when many fields
windows-icon	list<string>	icon entries in the PE resource table	Newline- or comma-separated <id>=<path> pairs (e.g. 1=assets/app.ico), or just <path> for id 1. Avoid : as a separator — collides with Windows drive letters.
windows-product-name	string	ProductName
windows-product-version	string	ProductVersion / setProductVersion	auto-padded to 4 parts
windows-file-version	string	FileVersion / setFileVersion
windows-file-description	string	FileDescription
windows-company-name	string	CompanyName
windows-legal-copyright	string	LegalCopyright	© auto-inserted if omitted
windows-original-filename	string	OriginalFilename	defaults to output filename
windows-internal-name	string	InternalName
windows-comments	string	Comments
windows-manifest	string (path)	raw RT_MANIFEST replace	embed a custom app.manifest (UAC / DPI / supportedOS)
windows-lang	string	lang id	default 1033 (en-US)
windows-codepage	string	codepage	default 1200 (Unicode)

5.4 Signing & notarization

Input	Type	Notes
macos-sign-identity	string	Common name or SHA-1; auto-imports into an ephemeral keychain
macos-sign-certificate	string (base64)	.p12 blob — registered as secret at parse time
macos-keychain-password	string (secret)
macos-entitlements	string (path)	.entitlements plist
macos-notarize	boolean
macos-apple-id / macos-team-id / macos-app-password	secrets	passed to xcrun notarytool
windows-sign-mode	enum	none | signtool | trusted-signing (Azure TS — modern, no pfx on disk)
windows-sign-cert	string (base64)	.pfx when sign-mode: signtool
windows-sign-password	string (secret)
windows-sign-rfc3161-url	string	Timestamp server; default http://timestamp.digicert.com
windows-sign-description	string	Passed to /d
azure-tenant-id / azure-client-id / azure-client-secret / azure-endpoint / azure-cert-profile	secrets	Trusted Signing path

5.5 Publishing

Input	Type	Default	Notes
upload-artifact	boolean	true	each produced file uploaded via @actions/artifact
artifact-name	string	{name}-{version}-{target}	Must be unique per target (@actions/artifact v2 rejects collisions); defaults include {target} for that reason. Accepts the full template token set from §5.2.
attach-to-release	boolean	false	only when ref is a tag
release-tag	string	from ref (tag pushes only)	Required when triggered by workflow_dispatch or push: branches: — the action errors at parse time if attach-to-release: true and no tag is resolvable.
release-name	string
release-body	string
release-draft / release-prerelease	boolean
generate-release-table	boolean	true (when attach-to-release)	appends markdown table (size, sha256) to release body

5.6 Performance / observability

Input	Type	Default
cache	boolean	true — caches $RUNNER_TEMP/pkg-cache (pkg-fetch downloads, forced via PKG_CACHE_PATH)
cache-key	string	pkg-fetch-{runner-os}-{runner-arch}-node{node-version}-targets-{sha256(targets)} — auto-scoped so a node-version: 24 bump invalidates the previous node22 cache cleanly
step-summary	boolean	true
sbom	enum	none | cyclonedx | spdx (stretch)
provenance	boolean	false — emits SLSA attestation via actions/attest-build-provenance

5.7 Matrix helper (inputs live on the matrix sub-action, not the main action)

The yao-pkg/pkg-action/matrix@v1 sub-action exposes these inputs:

Input	Type	Notes
targets	list<string>	same grammar as the main action's targets input
allow-cross-compile	boolean	when false (default), warns on known-risky targets; when true, emits them without warning
runner-overrides	JSON map	per-target runner label override: {"node22-linux-arm64": "my-self-hosted-arm"}

Output: matrix — JSON array of {target, runner} objects consumable by strategy: matrix: ${{ fromJSON(steps.m.outputs.matrix) }}.

6. Outputs (v1)

Output	Type	Source
binaries	JSON list	Pre-compression pkg outputs (absolute paths)
artifacts	JSON list	Post-compression final file paths
checksums	string	Path to combined SHASUMS256.txt (or corresponding algo)
version	string	Resolved package version used in templating
release-url	string	When attach-to-release: true
matrix	JSON	(matrix sub-action only) — [{target, runner}, ...]; consumers derive os/arch from target in their job via the template engine

7. Execution flow (packages/build/src/main.ts)

parseInputs()                   # hand-rolled validator in inputs.ts
  ├─ registerSecrets() via core.setSecret
  └─ detectUndeclaredInputs()   # warn on stray INPUT_* envs
resolveConfig()                 # auto-discover package.json/.pkgrc
resolveTargets()                # normalize, default to host, warn on cross-compile landmines
resolveFilenameTokens()         # {name}, {version}, {sha}, {ref}, {date}, {tag}
runPkg()                        # via @actions/exec — streams output, captures timing
for each produced binary:
  ├─ applyWindowsMetadata()     # if *-win-* AND any windows-* input set
  ├─ strip()                    # if inputs.strip AND linux/macos
  ├─ signMacos()                # if *-macos-* AND macos-sign-identity set
  ├─ notarizeMacos()            # if macos-notarize
  ├─ signWindows()              # if *-win-* AND windows-sign-mode != none
  ├─ archive()                  # if compress != none
  ├─ computeChecksums()         # per algo
  ├─ uploadArtifact()           # if upload-artifact
  └─ record step-summary row
attachToRelease()               # if attach-to-release AND (ref is tag OR release-tag explicit)
writeShasumsFile()
writeStepSummary()
setOutputs()

Post step (packages/build/src/post.ts): unmounts ephemeral keychains, wipes this invocation's $RUNNER_TEMP/pkg-action-<uuid>/ (UUID emitted by the pre-step into GITHUB_STATE — not a glob, so concurrent invocations on the same self-hosted runner don't clobber each other), removes imported signing identities. Runs on success and failure.

8. Cross-compile & matrix strategy

The matrix sub-action exists because single-runner cross-compile hits the landmines in docs-site/guide/targets.md:

• node22-linux-arm64 / node22-win-x64 fabrication bug (NodeJS 22/24 issues/feedbacks tracker #87 / Cross-compilation from macOS to Linux on arm64 broken on >=22 #181)
• macos-arm64 requires code signing (mandatory kernel gate)
• Linux→macOS cross-compile known to produce non-functional binaries (issue Cross-compiling from Linux to macOS produces non-functional binaries #183)

packages/matrix/src/main.ts takes a targets list and emits (runner labels shown are illustrative only — the canonical mapping lives in targets.ts and is updated whenever GH deprecates a label):

[
  {"target": "node22-linux-x64",   "runner": "ubuntu-latest"},
  {"target": "node22-linux-arm64", "runner": "ubuntu-24.04-arm"},
  {"target": "node22-macos-x64",   "runner": "macos-13"},
  {"target": "node22-macos-arm64", "runner": "macos-latest"},
  {"target": "node22-win-x64",     "runner": "windows-latest"},
  {"target": "node22-win-arm64",   "runner": "windows-11-arm"}
]

The matrix sub-action also warns (not fails) on known-risky combinations the user can still force with allow-cross-compile: true. Runner labels are overridable via the runner-overrides input (map of target → runner label) for users on self-hosted fleets or who need a specific label.

Example composition:

jobs:
  matrix:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.m.outputs.matrix }}
    steps:
      - uses: yao-pkg/pkg-action/matrix@v1
        id: m
        with:
          targets: node22-linux-x64,node22-linux-arm64,node22-macos-arm64,node22-win-x64
  build:
    needs: matrix
    strategy:
      matrix: ${{ fromJSON(needs.matrix.outputs.matrix) }}
    runs-on: ${{ matrix.runner }}
    steps:
      - uses: actions/checkout@v4
      - uses: yao-pkg/pkg-action@v1
        with:
          targets: ${{ matrix.target }}
          compress: tar.gz
          checksum: sha256
          attach-to-release: true

9. Testing strategy

Runner is node:test exclusively — the Node stdlib test runner — invoked via node --test --experimental-strip-types --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=coverage.lcov "packages/core/test/**/*.test.ts". No vitest, no jest, no mocha. Assertions use node:assert/strict, snapshots use the built-in t.assert.snapshot, function mocks use t.mock.fn. Module mocks (t.mock.module) are treated as experimental pending M-1 spike — if module mocking is flaky across Node 22/24, tests fall back to DI-style test doubles (packages/core modules take their effectful collaborators as constructor args / function params, production code wires concrete impls, tests wire fakes). That shape is cleaner regardless and is the design target.

package.json exposes convenience scripts:

{
  "scripts": {
    "test": "node --test --experimental-strip-types --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=coverage.lcov 'packages/**/test/**/*.test.ts'",
    "test:unit": "node --test --experimental-strip-types 'packages/*/test/unit/**/*.test.ts'",
    "test:int": "node --test --experimental-strip-types 'packages/*/test/integration/**/*.test.ts'",
    "test:watch": "node --test --watch --experimental-strip-types 'packages/*/test/unit/**/*.test.ts'"
  }
}

9.1 Unit — packages/core/test/unit/

Every pure-function module. Targets:

• inputs.ts — happy path + every mutual-exclusion failure mode
• templates.ts — all token substitutions + unknown-token error
• targets.ts — valid/invalid triples, matrix expansion, deduplication
• checksum.ts — known-vector digests (match openssl output), SHASUMS format
• archive.ts — yazl zip writer only (in-process, no shell-out): round-trip byte-equal, deterministic mtimes, Unix exec-bit preservation. tar.gz/tar.xz/7z round-trips live in §9.2 integration since they shell out.
• windows-metadata.ts — against a fixture pre-built .exe, assert resedit round-trip via a read-back
• errors.ts — .cause chaining, GH annotation formatting

Effectful collaborators (@actions/core, @actions/exec, node:child_process, node:fs/promises, resedit) are substituted either via t.mock.module() or DI (decided by M-1 spike outcome). No real GH context needed.

Coverage gate: ≥85 % line, ≥80 % branch in packages/core, parsed from coverage.lcov (emitted via --test-reporter=lcov). Enforced in ci.yml with a tiny awk check (no c8 / nyc dep).

9.2 Integration — packages/core/test/integration/

Runs locally and in CI (ubuntu/macos/windows shards), also via node --test. Invokes real tools:

• windows-metadata.ts → reads back via resedit and asserts string/version/icon presence
• archive.ts → invokes system tar and 7z as oracle
• checksum.ts → shells out to sha256sum / shasum / CertUtil as oracle
• strip.ts → file before/after; byte-size drop assertion

9.3 End-to-end (.github/workflows/e2e.yml)

Two fixtures under test-fixtures/:

• tiny-app-cjs/ — classic CommonJS with a bin entry logging its version.
• tiny-app-esm/ — ESM with top-level await, designed to exercise the SEA path.

Plus a bring-your-own-pkg/ job that demonstrates the pkg-path input (pre-installed pkg, no global npm install) for air-gapped / self-hosted scenarios.

Matrix:

OS	Fixture	Target	Archive	Checksum	Extra
ubuntu-latest	cjs	node22-linux-x64	tar.gz	sha256	strip, attach-to-release (on test tag)
ubuntu-latest	esm	node22-linux-x64	tar.gz	sha256	mode: sea
macos-latest	esm	node22-macos-arm64	zip	sha256	mode: sea — exercises SEA cross-arch (x64 host → arm64 not covered by this cell; uses native-arm64 macos-latest)
ubuntu-latest	cjs	node22-linux-arm64	tar.xz	sha512	fallback-to-source
macos-latest	cjs	node22-macos-arm64	zip	sha256	ad-hoc codesign (no notarize secrets in PR builds)
windows-latest	cjs	node22-win-x64	zip	sha256	resedit metadata (icon + all strings)
windows-latest	cjs	node22-win-x64	7z	none	standalone windows-metadata sub-action
ubuntu-latest	cjs	node22-linux-x64	tar.gz	sha256	pkg-path input (bring-your-own pkg)

Each job asserts:

1. Produced binary runs (./tiny-app --version → matches package.json version).
2. Checksum sidecar matches binary.
3. Archive round-trips; extracted binary still runs.
4. Step summary contains the expected markdown table row.
5. On Windows: pwsh Get-ItemProperty -Path bin.exe | Select VersionInfo reports the injected strings.

Signing / notarization e2e: separate manually-dispatched workflow (e2e-signed.yml) that runs only when a maintainer supplies the repo secrets. Not gated on PRs.

9.4 Self-hosted runner / GHES smoke

CI shard using runs-on: self-hosted with a local runner in Docker to catch PATH/shell assumptions that only fail off github.com.

10. Security & secrets hygiene

• Every credential input is registered via core.setSecret() in inputs.ts before anything else — no chance of it leaking to logs.
• Unix hosts: .p12 / signing blobs land in $RUNNER_TEMP/pkg-action-<random>/ with fs.chmod(..., 0o600). Post step fs.rms the directory and security delete-keychain the temp keychain.
• Windows hosts: chmod is a no-op. Instead we icacls <path> /inheritance:r /grant:r <runnerUser>:F at create time (runner user resolved via whoami /upn to avoid PowerShell-vs-cmd quoting pitfalls around %USERNAME%). Cleanup path: either import to the user cert store and certutil -delstore on post-step, or zero-fill the .pfx then unlink — whichever the signing flow already has open.
• macOS keychain mechanics are modeled on apple-actions/import-codesign-certs: temp keychain via security create-keychain, unlock, add to search list, import cert, and security set-key-partition-list -S apple-tool:,apple: -s -k <pw> (the post-10.13 gotcha most DIY implementations miss and it causes signing to hang waiting for UI approval).
• Undeclared-input detector: after inputs.ts has consumed every declared input, scan process.env for stray INPUT_* keys. Any leftover → core.warning('Unknown input: <name>. Did you mean ...?') with a Levenshtein suggestion. Catches user typos early instead of silently ignoring them.
• No set-output or ::debug:: prints that include user strings not already vetted through a redaction helper.
• Dependabot enabled; CodeQL workflow scans TS + YAML; license-checker gate (§11) blocks non-permissive licenses.
• Pinning: README recommends pinning to a full SHA; we publish @v1 + immutable @v1.2.3 tags via the release pipeline.

11. Build, bundle & release pipeline

• Language: TypeScript, strict, target ESNext, module NodeNext, erasableSyntaxOnly: true. Version is pinned to match Node's bundled amaro parser (see the next bullet), not a moving "latest".
• Node baseline: ≥ 22 for dev, CI, and action runtime (engines.node: ">=22" in every package.json). Action uses runs.using: node24 (the lowest GH-supported runtime ≥ 22).
• Module system: pure ESM ("type": "module") top to bottom.
• Exact .node-version pin: an exact patch (e.g. 22.12.0), not a range. --experimental-strip-types is still experimental — behavior has shifted across 22.x minors, and Node 22's bundled amaro parser is frozen against a specific TS AST version. Pinning the patch makes bumps an explicit, reviewable event. CONTRIBUTING.md documents that touching .node-version is a breaking-dev-env change.
• TypeScript version tied to Node's amaro, not "always latest". tsc's accepted syntax moves faster than strip-types' parser; using a bleeding-edge TS syntax that Node 22 can't parse would pass tsc --noEmit then blow up at node --experimental-strip-types runtime. We pin typescript in package.json to the version compatible with the pinned Node's amaro, bumped in lockstep with .node-version.
• Local dev: node --experimental-strip-types src/main.ts (and the watch variant for tests). No ts-node, no tsx, no Babel. Type stripping is unflagged on Node 23.6+ but we keep the explicit flag for Node 22 parity.
• Bundler: esbuild (not ncc — ncc's ESM story is still rough). Each sub-action bundled to dist/index.mjs (+ dist/post.mjs) with --bundle --format=esm --platform=node --target=node22 --minify-syntax so the action repo ships no node_modules. esbuild is invoked via its Node API from a ~20-line scripts/bundle.ts, itself run via node --experimental-strip-types.
• Action runtime: runs.using: node24 for every JS sub-action. GitHub Actions' runtime values skip node22 (the available entries are node20 / node24); node24 is the first slot that satisfies our ≥22 floor. This is a load-bearing assumption — the M-1 pre-flight spike (§12) verifies node24 is GA across GH-hosted, self-hosted, and GHES; if the self-hosted/GHES picture isn't green, we fall back to runs.using: node20 for the action runtime while keeping engines.node: ">=22" for dev/CI (the bundle still runs fine on Node 20 since esbuild emits down-level-compatible syntax) and document the gap. Decision recorded before M0 closes.
• Pre-commit: husky + lint-staged → yarn lint + yarn build (bundles dist/) — pre-commit fails if dist/ is stale.
• CI ci.yml: lint → build → unit (node --test) → integration → verify dist/ and generated action.yml files + docs/inputs.md match source (git diff --exit-code dist/ action.yml matrix/action.yml windows-metadata/action.yml packages/build/action.yml docs/inputs.md). Runs on a Node version matrix: [<.node-version contents>, 24.x] (first entry reads the pinned floor file — no duplication of the version number in the workflow).
• Dependabot + bundle: dependabot-bundle.yml auto-commits rebuilt dist/ and regenerated action.yml onto Dependabot PRs. Triggered by pull_request (not pull_request_target) with permissions: { contents: write, pull-requests: write }; Dependabot PRs are second-class and can't push their own commits, so the workflow runs under the repo's own GITHUB_TOKEN in the PR head context. This is the pattern used by the actions/* org. We explicitly avoid pull_request_target — running checked-out untrusted code with contents: write is the classic Dependabot-confused-deputy footgun.
• License compliance gate: CI runs npx license-checker-rseidelsohn --onlyAllow 'MIT;ISC;BSD-2-Clause;BSD-3-Clause;Apache-2.0;CC0-1.0' as an ephemeral step (no dev-dep entry), blocking any non-permissive license sneaking into the bundle before Marketplace submission.
• Release release.yml: release-it with conventional commits → tags v1.2.3, fast-forwards the floating v1 tag (tiny custom step using @actions/github — no extra action dep), creates a GH Release with auto-generated notes, publishes to the GitHub Marketplace (manual first time, automated after).
• Supported pkg version range documented in README; CI runs the e2e matrix against the oldest-supported and latest pkg minor.

12. Rollout plan

0. M-1 — Pre-flight spikes (1 day, before any scaffolding). Also includes a non-technical prerequisite: confirm the yao-pkg org has agreed to host yao-pkg/pkg-action (issue feat: official GitHub Action for shipping pkg binaries #248 was filed by the org maintainer, so this is a formality — but record the go-ahead in the spike report). De-risks the three load-bearing assumptions identified in self-review:

   • runs.using: node24 availability: write a throwaway action with runs.using: node24 and dispatch it against ubuntu-latest, macos-latest, windows-latest, a self-hosted runner, and (if accessible) a GHES staging instance. Confirm it resolves. Decision recorded: proceed with node24 OR fall back to node20 + documented Node≥22 tooling requirement.
   • --experimental-strip-types + esbuild-built tests stability: run a minimal inputs.ts + matching inputs.test.ts through node --test --experimental-strip-types --experimental-test-coverage on both Node 22.12.x and 24.x; verify coverage LCOV output (--test-reporter=lcov) parses cleanly. Pin the exact typescript version that matches the Node 22 amaro parser.
   • node:test/mock module-mocking viability: prototype mocks for @actions/core, @actions/exec, and resedit. If any scenario requires --experimental-require-module or behaves differently across 22/24, abandon module mocking in favor of DI-style test doubles (constructor-injected ports, which is the cleaner design anyway); this is an architectural decision taken before M1 code lands, not retrofitted.

   Exit criteria: a short report committed to the repo as docs/spike-report.md at the start of M0 (M-1 work itself happens in a throwaway scratch repo since yao-pkg/pkg-action doesn't exist yet). If any spike is red, the plan's §4/§11 are updated before M0 starts.

1. M0 — Scaffold (1–2 days): repo, yarn workspaces, "type": "module", tsconfig w/ erasableSyntaxOnly, ESLint/Prettier, node:test + esbuild wiring, scripts/gen-action-yml.ts stub, empty action stubs publishing "hello world".

2. M1 — Core build path (3–4 days): inputs (+metadata for codegen), pkg-runner, pkg-output-map, templates, targets, archive (tar + yazl + 7z), checksum, uploader, summary + full unit coverage. Single-target e2e green.

3. M2 — Matrix sub-action + multi-target (1–2 days): matrix expansion, cross-compile warnings, runner-label constants centralized, e2e matrix green.

4. M3 — Windows metadata (2 days): resedit integration + standalone sub-action + e2e assertion of injected strings/icon.

5. M4 — Signing & notarization (3–4 days): macOS codesign + notarytool (modeled on apple-actions/import-codesign-certs — temp keychain, security set-key-partition-list), Windows signtool (w/ icacls-restricted .pfx) + Trusted Signing; manually-dispatched signed e2e.

6. M5 — Release attach + step summary polish + docs + Dependabot bundle workflow (2 days).

7. M6 — Stretch: provenance (verify composite↔sub-action attestation works end-to-end), SBOM (decide: ship via CycloneDX dep bump or defer), Docker/distroless wrap, Homebrew/Scoop manifest.

8. v1.0.0 → publish to Marketplace. Rollback SOP documented in RELEASING.md (see §18).

13. Key design decisions worth flagging

• Hybrid composite + TS sub-actions (§4). Honors both feat: official GitHub Action for shipping pkg binaries #248's "composite preferred" note and the enterprise-grade TS requirement.
• Composite action.yml is code-generated from inputs.ts metadata. The ~40-input pass-through block is too error-prone for hand-maintained YAML; codegen removes the class of bug entirely.
• Pure ESM + latest-compatible TypeScript + erasableSyntaxOnly — future-proof; node --experimental-strip-types runs source as-is, and the compiler forbids any syntax that would break it. TS version is pinned to match Node's amaro parser (not "always latest") to avoid tsc-accepts-but-strip-types-rejects drift.
• node:test over vitest/jest — stdlib test runner, zero framework dep, includes mocking, snapshot, and coverage natively. Module mocking (t.mock.module) treated as experimental — if M-1 spike shows flakiness, we use DI-style test doubles instead (and that's a better design anyway).
• Node natives over userland wherever viable — node:crypto (checksums), node:fs/promises (fs-utils), node:zlib if we ever need in-process gzip, globalThis.fetch (HTTP, no node-fetch), node:child_process (tool invocation). External deps only when the stdlib genuinely doesn't cover it.
• Archive hybrid strategy: tar.gz/tar.xz shell out to system tar (universal); zip uses in-process yazl for cross-platform permission/determinism fidelity; 7z shells out to system 7z (preinstalled on GH-hosted; documented requirement elsewhere).
• resedit as a library, not a CLI — keeps the Windows metadata step in-process, deterministic, and testable. The docs-site recipe uses both; we use the richer Node API. Applies on any host (pure JS, no Wine).
• Windows signing includes Azure Trusted Signing — the .pfx-on-disk flow is being deprecated; modern production installs use Trusted Signing. We support both, default to none. .pfx paths get icacls-restricted, not chmod (which is a no-op on Windows).
• macOS signing mechanics follow apple-actions/import-codesign-certs including the security set-key-partition-list step that causes DIY implementations to hang.
• Matrix is a separate sub-action, not a flag on the main action, because it runs in a setup-style job that feeds strategy: matrix — fundamentally a different execution model.
• Runner labels live in one constant map inside targets.ts; GH deprecates them (macos-13 → macos-13-large → …) on its own schedule.
• Post-step cleanup is mandatory, not opt-in — any action that imports a signing identity MUST clean up even on failure.
• No gh CLI dependency for release attachment — use @actions/github so it works on GHES without extra setup.
• esbuild over ncc for bundling — esbuild's ESM output is battle-tested; ncc's isn't.
• Hand-rolled input validator, not zod — the validation surface is small (strings → typed union), keeping deps tight. Full unit coverage replaces schema-library sugar. Metadata from the same module powers codegen of action.yml + docs/inputs.md.
• pkg-path input for air-gapped/self-hosted users: bypass the npm i -g step and point at a pre-installed pkg binary.

14. Open questions for the reviewer

These are choices I made autonomously; flag any you'd override and I'll adjust before implementation:

1. Hybrid composite vs pure Node-JS TS action — issue feat: official GitHub Action for shipping pkg binaries #248 says "composite preferred"; I went hybrid. Happy to go pure TS if you'd rather skip the composite layer.
2. Monorepo tool — chose yarn workspaces to match pkg repo's toolchain. pnpm would also work.
3. Windows signing modern default — should sign-mode: trusted-signing be the documented default in examples, or keep signtool for discoverability?
4. SBOM in v1 or deferred? — honest CycloneDX generation for a pkg binary requires enumerating the user's lockfile + bundled Node runtime; "hand-rolled JSON" doesn't scale. Either add @cyclonedx/cdxgen to the runtime budget (would go to 7) or drop SBOM from v1 scope and leave the hook in place for a v1.x minor.
5. Rollback: forward-only SOP acceptable? — §17 forbids rewinding v1. If a bug ships to v1 and a revert PR will take hours to ship, the only mitigation users have is pinning to a prior immutable tag via a workflow edit. Alternative: add a manual rollback.yml that does rewind v1 as a break-glass lever. My recommendation is to keep forward-only; flag if you disagree.

15. Verification (once implemented)

1. Unit: yarn test:unit → ≥85 % line / ≥80 % branch coverage, all passing. Runs on Node 22.x (pinned floor) and 24.x.
2. Integration: yarn test:int locally on each host OS; shells out to real tar/7z/codesign/resedit.
3. Codegen drift: yarn build + git diff --exit-code dist/ action.yml packages/*/action.yml docs/inputs.md — zero drift.
4. Smoke (local): act -j build against examples/01-single-binary produces a runnable binary.
5. E2E (GitHub): .github/workflows/e2e.yml green on ubuntu/macos/windows, across the CJS and ESM fixtures; each job's asserted --version output matches fixture's package.json; Windows-metadata job's VersionInfo read-back matches inputs.
6. Signed e2e (maintainer-dispatched): e2e-signed.yml green; notarized bundle passes spctl --assess, signed .exe passes signtool verify /pa.
7. Release dry-run: yarn release --dry-run outputs a valid changelog and tag plan.
8. GHES smoke: self-hosted shard in ci.yml passes.
9. Rollback drill: publish a deliberately-broken v0.0.0-test.X prerelease and execute the forward-revert SOP end-to-end once before v1.0.0.
10. Docs: README renders clean in Marketplace preview; docs/inputs.md matches the generated action.yml byte-for-byte (same source); migration.md walks through porting a hand-rolled workflow from the examples and is validated against at least one real downstream repo.

16. Dependency budget

Hard upper bound: 6 runtime deps, 3 dev deps. Every addition requires a justification comment in package.json.

Runtime (shipped inside dist/*.mjs bundles)

Dep	Purpose	Why we can't drop it
@actions/core	input/output/logging/secrets/annotations	The runner protocol. No stdlib equivalent.
@actions/exec	process spawning w/ streaming capture	Richer than node:child_process for GH logs; small (~200 LOC). Could be replaced later with a node:child_process wrapper if we want to hit 5 deps.
@actions/artifact	artifact upload	Uses the internal, unstable-but-official endpoint; can't be reimplemented cleanly.
@actions/github	GitHub REST/GraphQL w/ auto-auth	Needed for release attach and provenance. No native fetch shim covers the auth/retry bits without effort.
resedit	Windows PE resource editing	The whole point of the Windows metadata feature. Pure JS, no native addons.
yazl	Deterministic, cross-platform zip writing	System tar -a --format=zip on Windows doesn't preserve Unix exec bits — a win-x64 zip extracted on Linux wouldn't be runnable, and zips assembled on Linux hosts for win-x64 distribution don't round-trip correctly. yazl is ~500 LOC pure JS, lets us set mode bits explicitly, and gives byte-stable output for reproducible builds.

System tools still invoked (not deps): tar (all runners), 7z (GH-hosted; self-hosted users must install it — documented).

Deliberately not included: zod, yauzl, tar (npm), 7zip-min, cyclonedx-library, ts-node, tsx, vitest, jest, mocha, c8, nyc, ncc, chalk, minimist, commander, semver (Node has satisfies via node:util or we do string parsing).

Dev

Dep	Purpose
typescript	type-check only; not used at runtime thanks to --experimental-strip-types
esbuild	single-file ESM bundling of dist/*.mjs
eslint + plugins	style / correctness (matching pkg's config). Single logical entry in the budget.

prettier is integrated via eslint-plugin-prettier — no separate dep entry.

Native-first cheat sheet (what stays in node:*)

Need	Use
Hashing	node:crypto.createHash
File I/O	node:fs/promises
Paths / URLs	node:path, node:url.pathToFileURL
Env / args	process.env, process.argv
HTTP	globalThis.fetch (built-in since Node 18)
Spawning	node:child_process.spawn (wrapped by @actions/exec only when GH log streaming is needed)
Streams	node:stream/promises.pipeline
Compression (if ever in-process)	node:zlib
Temp dirs	node:fs/promises.mkdtemp(node:os.tmpdir())
Test runner	node:test
Mocking	node:test/mock
Assertions	node:assert/strict

17. Release & rollback SOP

Published in RELEASING.md. Summary:

• Tagging: v<major>.<minor>.<patch> immutable; v<major> floating, fast-forwarded by the release workflow after CI green.
• Forward: yarn release → release-it cuts a semver tag → workflow creates GH Release, fast-forwards v1, publishes to Marketplace.
• Rollback a bad v1.x.y — always forward, never rewind:
  1. Revert the offending commit(s) on main.
  2. yarn release cuts v1.x.(y+1) containing only the revert.
  3. The release workflow fast-forwards v1 to the new immutable tag.
  4. Mark the bad immutable tag as "deprecated — use vX.Y.Z" in the Marketplace UI (no programmatic API; done manually in the release notes + a Marketplace deprecation notice).
• Never rewind v1 (i.e. never force-move it backwards). Users read @v1 as floating-forward-only; a rewind violates that contract and breaks marketplace cache coherence. Users pinned by SHA are unaffected by design — a rewind doesn't compromise their install, but it silently changes the behavior for everyone else who reasonably assumed forward-only. Forward reverts cost one extra CI cycle but preserve every user's auditability.
• Never delete an immutable tag; users may be pinned to it.
• Pre-release cadence (v1.2.0-rc.1) documented for high-risk changes (e.g. Node runtime bumps) so we trial breakage before the floating v1 picks it up.

18. Critical files to be produced (first PRs)

Path	Purpose
action.yml (generated)	top-level composite entry
scripts/gen-action-yml.ts	codegen — single source of truth for inputs
packages/core/src/inputs.ts	hand-rolled typed validator + metadata — the contract
packages/core/src/pkg-runner.ts	invokes pkg reliably
packages/core/src/pkg-output-map.ts	maps on-disk pkg outputs back to target triples
packages/core/src/windows-metadata.ts	resedit integration (user-requested bonus)
packages/core/src/templates.ts	filename token engine
packages/core/src/targets.ts	target parsing + matrix expansion + runner label map
packages/core/src/archive.ts	tar/7z shell-out + yazl zip writer
packages/build/action.yml (generated) + src/main.ts	orchestrator
packages/matrix/action.yml (generated) + src/main.ts	matrix generator
packages/windows-metadata/action.yml (generated) + src/main.ts	standalone resedit action
.github/workflows/{ci,e2e,release,dependabot-bundle}.yml	CI + release
docs/inputs.md (generated)	input reference, emitted from inputs.ts metadata
docs/spike-report.md	M-1 outcomes — informs M0
CONTRIBUTING.md	dev-env policy (.node-version pinning, strip-types flow, DI vs module-mocks decision)
RELEASING.md	forward-only SOP (§17)
examples/*/	copy-pasteable consumer workflows
README.md	marketplace listing + quickstart

---

Plan file: /home/daniel/.claude/plans/stateless-fluttering-volcano.md