@mannyc1/ts-release 0.0.6 → 0.2.2

package/SPEC.md

@@ -1,305 +1,206 @@
-# Release Package Spec
-
-## Purpose
-
-The `release` package is a small TypeScript library for turning release intent into explicit, inspectable, and repeatable publishing operations.
-
-It should not be a build system, a package-manager wrapper, or a generic task runner. Its job is to model what is being released, where it is being published, what must be true before publication, and which irreversible actions require deliberate approval.
-
-The package should make release work boring: the same inputs should produce the same plan, the same validations should produce auditable evidence, and the same publish operation should be understandable before anything is executed.
-
-## Core Idea
-
-A release is a data flow:
-
-```text
-release intent
-  -> normalized release model
-  -> target-specific operations
-  -> optional generated files
-  -> validation evidence
-  -> gated execution
-  -> post-publish verification
-  -> status and conservative resume
-```
-
-The package owns the model and the orchestration. Ecosystem tools remain the source of truth for ecosystem-specific behavior.
-
-For example, npm, PyPI, GitHub Releases, Homebrew taps, OCI registries, app stores, or other targets may each need different commands, credentials, artifacts, and validators. The release package should describe those differences directly instead of hiding them behind one fake universal publish abstraction.
-
-## Current Shape
-
-The root package is the reusable library. It exposes explicit subpaths for domain data, config loading, planners, target adapters, host services, and high-level workflows. The official Bun CLI lives in `apps/release-ts`, and the GitHub Action lives in `apps/ts-release-action`; both are runtime adapters over the same TypeScript workflows.
-
-Current first-party workflows cover:
-
-- config validation and plan rendering
-- data-first init/scaffolding previews with approved writes
-- static doctor/auth/CI diagnostics
-- render, validation, execution, verification, and workflow evidence
-- status reporting from existing evidence
-- conservative resume after interrupted work
-- narrow GitHub release reconciliation without republishing npm versions
-
-Reusable configs live in `templates/`, runnable fixtures live in `examples/`, and publish operations remain data until an execute approval and any irreversible approval are supplied.
-
-## Design Goals
-
-### Plan-first
-
-The primary output of the package is a release plan, not a side effect.
-
-A plan should be serializable, reviewable, and suitable for CI artifacts. It should explain:
-
-- release identity: name, version, commit, tag, notes, source metadata, and the strategy that resolved it
-- artifact inventory: files, checksums, sizes, formats, and intended consumers
-- target operations: what each target will do and what inputs it needs
-- validation steps: which checks must run before publishing
-- execution gates: which operations are irreversible or require explicit approval
-- evidence paths: where validation and publish results will be recorded
-
-### Explicit target semantics
-
-Different distribution targets have different shapes. The package should model those shapes instead of flattening them.
-
-Examples:
-
-- A release host publish creates or updates a release record and uploads assets.
-- A registry publish creates immutable package versions.
-- A catalog update changes a repository or index that points at artifacts.
-- A deployment promotes already-built assets into an environment.
-
-Each target should declare its required inputs, auth requirements, dry-run support, validation strategy, mutability rules, and recovery behavior. When auth cannot be proven locally, the target should also model the expected execution context, provider-specific setup, and setup prerequisites.
-
-### Evidence-driven validation
-
-Validation should produce structured evidence, not just console output.
-
-Evidence should be machine-readable enough for CI and human-readable enough for debugging. It should include command invocations, tool versions where practical, exit statuses, important paths, skipped checks, warnings, failures, and timestamps.
-
-Evidence should also support status reporting and conservative resume after failed or interrupted releases.
-
-Strict mode should fail on missing required validators. Non-strict mode may record skips, but skips must be visible in the evidence.
-
-### Gated irreversible actions
-
-Operations that publish immutable versions, create public releases, overwrite indexes, or otherwise affect users must be marked as irreversible or externally visible.
-
-The default behavior should be dry-run or print-only. Execution should require an explicit execute flag, and irreversible operations should require a second confirmation flag or equivalent programmatic approval.
-
-Failed publish evidence must not be treated as proof that nothing was published.
-
-The package should make it hard to accidentally publish and easy to see exactly what would be published.
-
-### Library-first, CLI-second
-
-The core package should be a reusable library. A CLI can exist as an adapter, but it should not contain the release logic.
-
-The library should expose APIs for:
-
-- loading and normalizing config
-- constructing a release plan
-- scaffolding starter configs and CI workflows as proposed files
-- rendering config schemas and validation results
-- rendering target files or generated metadata
-- validating plans and artifacts
-- reporting static auth and CI readiness with confidence levels
-- preparing executable operations
-- running approved operations through an injected host interface
-- recording evidence
-- reporting release status from evidence
-- conservatively resuming safe unfinished work
-- reconciling narrowly modeled remote state without replaying immutable publishes
-
-The CLI and GitHub Action should mainly parse host inputs, call the library, format host-specific output, and persist evidence.
-
-### Host abstraction without pretending the world is pure
-
-The package should isolate filesystem, environment, process execution, network calls, and time behind a narrow host interface where that improves testability and portability.
-
-The host boundary should not become a full application framework. It exists so core planning logic can be deterministic and so execution can be tested without touching real registries or release hosts.
-
-### Composable, not magical
-
-The package should compose with existing tools rather than replace them.
-
-Builders, packagers, changelog generators, signing tools, registry CLIs, provenance tools, and ecosystem validators should be treated as inputs or adapters. The release package should coordinate them, capture their evidence, and enforce release policy around them.
-
-## Non-goals
-
-The package should not try to:
-
-- build every artifact itself
-- replace ecosystem-native publishing tools
-- invent a universal package format
-- hide target-specific auth requirements
-- guarantee semantic versioning policy for the project using it
-- own changelog generation as a core requirement
-- require a monorepo
-- require a specific CI provider
-- treat dry-run output as equivalent to successful publication
-
-These may be integrated through adapters, but they should not define the core.
-
-## Core Concepts
-
-### Release Intent
-
-User-authored input describing what should be released.
-
-It should be concise but complete enough to identify the release, locate artifacts, choose targets, and declare policy.
-
-Identity may be static config data or may be derived from a package manifest. Decision strategies may then decide whether a release should be attempted from explicit remote-state config, the current Git tag, conventional commits since the latest matching tag, or first-party intent files. These strategies choose the intended identity and skipped/ready/complete/partial eligibility result; they do not publish.
-
-Intent files are a small first-party reviewed-intent format, not a promise of full Changesets compatibility. An empty/no-release intent can satisfy CI while producing a skipped release decision.
-
-### Release Model
-
-A normalized internal representation with defaults resolved, paths normalized, targets expanded, and invalid combinations rejected.
-
-The model should be deterministic and independent of terminal formatting or CLI flags.
-
-### Release Plan
-
-A serializable plan derived from the release model.
-
-The plan is the contract between planning, validation, execution, and CI review. It should be stable enough to diff in tests and inspect in logs.
-
-### Target Adapter
-
-A module that knows how to plan, validate, and execute operations for one distribution target.
-
-Adapters should expose capabilities clearly: dry-run support, required credentials, validation commands, generated files, publish commands, and expected evidence.
-
-### Operation
-
-A concrete action that may be rendered, validated, executed, or skipped.
-
-Operations should carry enough metadata to explain their risk level, inputs, outputs, and execution requirements.
-
-### Evidence
-
-Structured records produced by validation, rendering, execution, and verification.
-
-Evidence should survive outside the process as JSON or another stable format. It should be useful for CI summaries, release audits, and debugging failed publishes.
-
-## Expected Public Surface
-
-The package should make these workflows straightforward:
-
-- initialize a starter config and optional CI workflow from templates
-- validate config JSON and schema shape
-- create a plan from config
-- inspect the plan without executing anything
-- render target-specific files
-- validate artifacts and target readiness
-- report static auth and CI readiness
-- produce evidence artifacts
-- print publish operations
-- execute approved operations
-- verify published state after execution
-- inspect status and resume only safe unfinished work
-- reconcile a matching GitHub draft release without republishing immutable registries
-
-The API should favor explicit functions and typed data over hidden global state.
-
-## Configuration Principles
-
-Configuration should be declarative and boring.
-
-It should describe release facts and target policy, not arbitrary scripts. Escape hatches can exist, but they should be visible in the plan and evidence.
-
-Good config answers:
-
-- What is the release?
-- Which artifacts are part of it?
-- Which targets receive it?
-- What credentials or environment are required?
-- What must be validated first?
-- Which generated files or indexes will change?
-- Which operations are allowed to execute in this environment?
-
-Release strategies should stay declarative:
-
-- static config is for manually audited release identity
-- package manifest identity is for package releases with one version source
-- Git tag decisions are for tag-triggered workflows
-- conventional commit decisions are for automated SemVer from commit messages
-- intent-file decisions are for release intent reviewed in PRs
-
-Artifact path templates may interpolate only named release data such as `{version}`, `{name}`, and `{normalizedName}`. They must be expanded before path safety and artifact inventory checks.
-
-## Testing Strategy
-
-The core should be heavily testable without real external services.
-
-Important test categories:
-
-- config parsing and normalization
-- invalid config diagnostics
-- deterministic plan generation
-- adapter capability modeling
-- dry-run behavior
-- irreversible-operation gating
-- evidence recording
-- command construction without execution
-- execution through fake host implementations
-- target adapter contract tests
-
-Real integration tests can exist for official validators and sandbox registries, but the core should not depend on live services to prove its behavior.
-
-## Success Criteria
-
-The rewrite is successful when:
-
-- a user can define release intent in a small config
-- the package produces a reviewable release plan with no side effects
-- target differences are explicit in the plan
-- validation emits structured evidence
-- publish operations are blocked by default
-- irreversible operations require deliberate approval
-- core behavior is covered with deterministic tests
-- a CLI can be rebuilt as a thin adapter over the library
-- a GitHub Action can run the same workflows without embedding CLI behavior
-- starter templates can be checked by the same workflow path as examples
-- adding a new target does not require rewriting the core planner
-
-## Biases
-
-Prefer:
-
-- explicit data over implicit conventions
-- small target adapters over a large universal abstraction
-- official ecosystem validators over homegrown approximations
-- deterministic planning over clever runtime discovery
-- evidence artifacts over terminal-only output
-- hard failures for unsafe ambiguity
-- dry-run as the default mode
-
-Avoid:
-
-- hook-runner architecture as the core design
-- hidden publish side effects during validation
-- target adapters that silently shell out without modeling risk
-- global process state in the planning layer
-- special cases that only work for one repository shape
-- abstractions that erase important ecosystem differences
-
-## Implementation Direction
-
-Continue from the data model.
-
-Keep the smallest set of types needed to represent release identity, artifacts, targets, operations, validation results, execution gates, and evidence. Add target adapters end to end only when they prove the abstractions carry real differences without becoming generic mush.
-
-The implementation should stay narrow but honest:
-
-1. Load config.
-2. Normalize into a release model.
-3. Generate a serializable plan.
-4. Render generated files only through explicit render operations.
-5. Validate with structured evidence.
-6. Print executable operations.
-7. Execute only when explicitly approved.
-8. Verify remote state and report status from evidence.
-
-Everything else should be added only after it has a clear place in that flow.
+# ts-release specification
+
+## 1. Public operations
+
+The root package exports `inspect`, `prepare`, `observe`, `publish`, `release`,
+and `correct`, plus `makeReleaseApi`, durable-reference codecs, configuration helpers, and
+tagged input/runtime errors. The total observation and release report schemas,
+transient credential acquisition errors, and their secret-free durable causes
+are also public. The constructed API adds `dispose` for its host runtime. CLI
+and Action boundaries call these same operations.
+
+## 2. Authored and verified forms
+
+Authored configuration is decoded strictly. Resolution combines it with
+observed package and Git facts; disagreement is an error. Verified context
+records the clean source commit/tree and package-manifest digest. Preparation
+materializes that exact commit into a fresh private staging root. Changed,
+ignored, or untracked workspace bytes are never implicit inputs.
+
+## 3. Derived graph
+
+The graph contains imported artifacts, build, archive, checksum, command check,
+command artifact, typed Homebrew/Scoop rendering, npm publication, exact-file
+PyPI publication, GitHub Release publication, and catalog Git publication
+primitives. It is
+sorted and linked inside one process. It is never serialized as authority and
+never crosses a runner boundary.
+
+## 4. Prepared release
+
+`prepared-release/v2` is canonical JSON plus content-addressed blobs. A
+`CompletePreparedReleaseRef` is the only public cross-process locator and
+contains content identity, never a local path. The complete manifest records
+materialized source identity, project coordinates, artifact IDs, exact
+sizes/digests/media types, input basis, execution provenance, and provider
+subjects. A prepared store refuses missing, altered, extra, symlinked,
+non-canonical, or producer-mismatched content.
+
+An npm trusted-publishing subject also binds the exact verified source commit
+and a versioned GitHub/npm provenance-environment contract. The host validates
+all npm-consumed GitHub run facts before reading OIDC authority, snapshots them
+privately onto the issued workload grant, and projects only that snapshot plus
+the two OIDC request values into the closed npm child.
+
+A PyPI publication records one independent subject per prebuilt wheel or gzip
+sdist. Preparation parses archive structure and embedded metadata and requires
+project/version/filename agreement before the file can enter a prepared
+manifest. Each subject binds the closed PyPI/TestPyPI Simple and upload
+endpoints, exact filename, size, SHA-256, media type, and distribution tags.
+
+## 5. Observation
+
+Publication is subject-based. `observe` uses a read-only report algebra.
+`publish` observes every subject before mutation and again afterward.
+Equivalent subjects are idempotent skips; only a typed provider decision may
+authorize mutation; conflict or inconclusive state blocks. Provider correction
+intent is typed and bound to the prepared digest. npm and GitHub Release
+requests produce external proposals; catalog Git admits one SemVer-forward
+conditional replacement of its exact target/state pair. Credential unavailability
+and unsupported authentication remain total report data with distinct tagged,
+secret-free causes; they do not escape as publication control flow.
+
+PyPI observation accepts only a standards-shaped JSON Simple response with
+API major 1 and the API 1.1 equality fields. A visible project page that omits
+the exact filename can authorize token upload only after the host atomically
+creates a shared, durable, terminal claim for the prepared subject. Claim
+unavailability or occupation blocks before credential acquisition. A project
+404 never authorizes first creation. Yanked files conflict; no yank mutation
+is installed. Trusted publishing is an external PyPA Action path and is
+rejected by the stock coordinator before dispatch.
+
+Catalog observation reads the exact branch ref, commit, complete untruncated
+recursive tree, and both managed blobs. Mutation creates exact blobs and a tree
+with the observed root as `base_tree`, verifies every unrelated object and mode
+in the proposed full tree, creates a commit with the observed commit as its
+sole parent, and updates the ref with `force: false`. A catalog subject depends
+on convergence of its configured GitHub release asset subjects.
+
+## 6. Native preparation
+
+`CommandCheck` runs trusted argv code against declared inputs. `CommandArtifact`
+generates or transforms declared regular-file outputs. `builder: "command"`
+lowers to the same primitive. Generic preparation children inherit no host
+environment. A nonempty authored environment request is rejected unless a
+future dedicated capability certifies its safe build-time contract. There is
+no generic hook or remote-publisher escape hatch. The public API recognizes
+reserved partition and merge preparation modes and rejects them with
+`PreparationModeUnsupported`; it creates no partial durable object.
+
+## 7. Hosts
+
+The capability registry owns separate execution-host, artifact-target, and
+native-tool-host axes. Linux is the only installed execution host. The exact
+advertised artifact targets are Linux x64/arm64 and macOS x64/arm64; macOS
+binaries are cross-compiled artifacts, not execution-host evidence. Windows is
+neither an execution host nor an advertised artifact target, and the
+self-release does not distribute a Windows ts-release binary. WSL is Linux for
+this contract.
+
+The checked-in Action is a Linux workflow boundary: its composite step
+requires Bash and a workflow-installed, pinned Bun runtime. The distributed
+package and CLI run under the declared Node engine, but preparation and
+network-denied command execution delegate to an external Bun executable whose
+Linux child loads `libseccomp.so.2`. The standalone CLI is therefore not a
+self-contained preparation sandbox. These declared axes still require the
+clean-candidate public-entrypoint smoke matrix before release certification.
+
+## 8. Error and safety contract
+
+Structured Effect errors cross the library boundary. A pre-commit preparation
+failure proves no remote mutation; a post-commit abort carries the exact
+durable reference. Filesystem paths are contained and symlink-checked. Public
+inputs contain no credential values. Secrets are acquired through host layers,
+consumed only by audience- and purpose-checking sinks, and redacted at process
+output boundaries. Host credential error text never enters durable reports;
+only request-derived, secret-free cause data does. The Action validates its
+inputs before calling the library.
+
+## 9. Recovery limits
+
+Rerun the same prepared bytes. A partial release is possible; atomic rollback,
+deletion, exactly-once publication, and universal correction are not claimed.
+PyPI filenames remain consumed after deletion and uncertain token uploads are
+never blindly replayed; the required terminal claim survives process loss and
+must be shared by every runner capable of dispatching that subject.
+Read-convergence timing defaults are conservative assumed bounds until live
+post-write evidence measures them. Announcements and unsupported providers
+remain outside the retained product.
+
+## 10. Product evidence
+
+In the source distribution, the generated capability inventory is joined
+one-to-one from executable module values and dated evidence. Evidence records
+contain sanitized references only and cannot configure runtime support. A
+source checkout, configuration field, detached test, or protocol double is not
+release certification.
+
+## 11. Distribution
+
+The canonical package identity is `@mannyc1/ts-release`. The canonical Action
+is the monorepo subpath `mannyc2/ts-release/apps/ts-release-action`. Public
+consumer documents bind an immutable version only when its tag targets the
+exact certified result commit before the package README becomes visible.
+Installed Node package consumers require
+`^22.22.2 || ^24.15.0 || >=26.0.0`. The checked-in Action declares a composite
+runtime and runs `dist/index.js` with the pinned Bun installed earlier in each
+advertised Linux workflow. Its entrypoint evidence is separate from installed
+package evidence and does not alter the package's Node engine. The packaged
+Node CLI still requires external Bun and, for network-denied commands on its
+Linux execution host, `libseccomp.so.2`.
+
+## 12. Non-goals
+
+The engine does not transport host-gate identity or persist execution history as authority,
+provide generic lifecycle hooks, or claim to be a language-specific clone of
+another release product. Arbitrary catalog templates, engine-owned downstream
+announcements, dynamic adapter discovery, and command publishers are not
+capabilities installed in the stock kernel.
+
+## 13. Root export audit
+
+The root runtime exports are exactly:
+
+- `AuthoredGithubReleaseAmendment`
+- `AuthoredCatalogForwardCorrection`
+- `AuthoredNpmDeprecation`
+- `CompletePreparedReleaseRef`
+- `CorrectionReport`
+- `CredentialFailureCause`
+- `CredentialStrategyUnsupported`
+- `CredentialStrategyUnsupportedCause`
+- `CredentialUnavailable`
+- `CredentialUnavailableCause`
+- `GitHubActionsCompletePreparedReleaseRef`
+- `LocalCompletePreparedReleaseRef`
+- `ObservationReport`
+- `PreparationModeUnsupported`
+- `PreparedReleaseRefCodecError`
+- `PreparedReleaseRefMalformedError`
+- `PreparedReleaseRefUnknownSchemeError`
+- `ReleaseAbortedError`
+- `ReleaseIncompleteError`
+- `ReleasePreparationError`
+- `ReleaseReport`
+- `correct`
+- `decodeAuthoredCorrection`
+- `decodeCompletePreparedReleaseRef`
+- `defineRelease`
+- `encodeCompletePreparedReleaseRef`
+- `encodeResolvedConfig`
+- `inspect`
+- `makeGitHubActionsCompletePreparedReleaseRef`
+- `makeLocalCompletePreparedReleaseRef`
+- `makeReleaseApi`
+- `observe`
+- `prepare`
+- `publish`
+- `release`
+- `ReleaseInputError`
+- `ReleaseRuntime`
+- `resolveConfig`
+- `unsupportedExecutionHost`
+
+## 14. License
+
+MIT.

package/apps/release-ts/README.md

@@ -0,0 +1,32 @@
+# ts-release CLI
+
+The CLI exposes exactly seven commands:
+
+- `init` writes an explicit preset only after that preset passes strict
+  authored-config inspection.
+- `inspect` observes authored configuration or reads a prepared bundle.
+- `prepare` stages native preparations and stores an exact bundle.
+- `observe` reads the remote subjects for one prepared bundle without mutation.
+- `publish` observes and publishes one prepared bundle.
+- `release` composes preparation and publication automatically.
+- `correct` binds one provider-specific correction proposal to the exact
+  prepared subject; the installed kernel has no corrective mutation adapter.
+
+```sh
+bun run cli init --preset bun-npm-github
+bun run cli inspect --config release.config.json
+bun run cli release --config release.config.json
+```
+
+The published Node bundle is built from `src/cli/node-main.ts`; development
+uses the Bun host entrypoint.
+
+The publishing preset first discovers the canonical owner/repository, then
+writes explicit trusted-publishing and GitHub intent and strictly inspects the
+exact generated object. It refuses to guess when repository discovery is
+ambiguous or absent.
+
+The preset binds trusted publication to `.github/workflows/release.yml` at
+`refs/heads/main`. Change both `workflow` and `workflowRef` when another exact
+workflow/ref is the intended host; a mismatch is rejected before OIDC request
+material is read.