@mannyc1/ts-release 0.0.7 → 0.2.2

package/ARCHITECTURE.md

@@ -1,98 +1,130 @@
 # Architecture
 
-`@mannyc1/ts-release` is artifact-first, library-first, and CLI-second.
-
-The package turns release intent into staged artifacts, installable artifact
-variants, target-specific distribution plans, evidence, and approved operations.
-The CLI and GitHub Action are adapters over those workflows.
-
-## Target Boundary
-
-The intended repository shape separates reusable library code from the
-first-party release application:
-
-```text
-src/                 reusable TypeScript release library
-apps/release-ts/     official CLI app, Bun runtime shell, and self-release dogfood
-apps/ts-release-action/
-                     official JavaScript action app and Node runtime shell
-scripts/             repo-wide maintenance gates only
-examples/            reusable release config examples
-```
-
-`src/` contains generic library code only. It may require platform services
-such as `FileSystem`, `Path`, `ReleaseCommandRunner`, `ReleaseHttp`, or
-`HttpClient`, but it must not provide the concrete Bun runtime for the official
-CLI.
-
-`apps/release-ts/` owns argv parsing, terminal output, Bun runtime assembly,
-standalone CLI compilation, and self-release policy/config. A module consumed
-only by the official CLI or self-release dogfood belongs in `apps/release-ts/`
-unless it is made generic and documented as public library API.
-
-`apps/ts-release-action/` owns GitHub Action input parsing, GitHub step-summary
-and output adapters, evidence artifact upload, and the Node runtime assembly
-used by the bundled action. Action code should call public workflow APIs rather
-than reaching into CLI modules.
-
-## Current Module Taxonomy
-
-- `domain/` contains durable schema-backed data models, typed errors, and scalar schemas owned by their semantic domain modules, such as release names in `domain/release`, target IDs in `domain/target`, artifact IDs and installable variants in `domain/artifact`, operation IDs in `domain/operation`, and evidence IDs in `domain/evidence`.
-- `config/` parses and validates release config into domain values.
-- `artifacts/` defines the recipe staging adapter and registry boundary. Recipes are data until a runtime provides a staging layer.
-- `planner/` normalizes release intent, builds artifact inventory, carries installable variants, builds plans, renders plans, executes operation data through injected services, records evidence, and reconciles modeled remote state.
-- `targets/` models ecosystem-specific target semantics and produces operation data. Target modules may describe commands and HTTP checks, but they do not execute them.
-- `host/` defines injectable command and HTTP services plus live or test implementations.
-- `workflows/` contains reusable application workflows over config files, init/scaffolding plans, diagnostics, evidence files, and live target/HTTP composition. This is the high-level programmatic surface.
-- `apps/release-ts/src/runtime/` contains the Bun runtime shell for the official CLI app.
-- `apps/release-ts/src/cli/` parses command-line flags, calls workflows, prints terminal output, and writes user-requested CLI output files.
-- `apps/ts-release-action/src/runtime/` contains the Node runtime shell for the bundled GitHub Action.
-- `apps/ts-release-action/src/` adapts GitHub Action inputs, outputs, step summaries, and artifact uploads to workflow calls.
-- `scripts/` contains repository maintenance checks. Scripts may use app runtime layers, but they are not package library code.
-
-## Dependency Direction
-
-Library modules must not import from `cli/`.
-
-The normal flow is:
+The release engine has five canonical forms:
 
 ```text
-domain <- config
-domain <- planner <- targets
-domain <- artifacts
-domain <- host
-workflows -> config/artifacts/planner/host/targets
-apps/release-ts runtime -> host/workflows/platform layers
-apps/release-ts cli -> workflows/runtime boundary
-apps/ts-release-action runtime -> host/workflows/platform layers
-apps/ts-release-action action -> workflows/runtime boundary
+authored intent
+      ↓ observe and resolve
+verified context
+      ↓ compile and stage
+ephemeral graph
+      ↓ execute and capture
+prepared release bytes
+      ↓ observe destinations
+publication status or correction proposal
 ```
 
-`src/index.ts` intentionally stays empty. Public API is the explicit subpath list in `package.json`, checked by `scripts/check-package-exports.ts` and `scripts/check-tree-shaking.ts`. The only workflow aggregate is the opt-in `./workflows` facade.
-
-## Public Workflow Surface
-
-There is no public `./api` facade, and the root package export stays empty. The public workflow modules are named after the work they own:
-
-- `./workflows` for the curated opt-in `Distribution`, `Config`, `Init`, `Diagnostics`, `Evidence`, and `Live` namespaces.
-- `./workflows/distribution` for the artifact-first high-level distribution facade.
-- `./workflows/config` for config-file release workflows.
-- `./workflows/init` for data-first scaffolding previews and approved writes.
-- `./workflows/diagnostics` for static config, auth, and CI readiness reports.
-- `./workflows/evidence` for reusable evidence persistence.
-- `./workflows/live` for runtime-neutral live target and HTTP services.
-
-The `./workflows` facade lives at `src/workflows/index.ts` and should only re-export workflow namespaces. Use `Distribution` for the product path: stage artifacts, plan distribution, render target files, execute approved operations, verify, and reconcile. Use exact workflow leaf imports for maximum tree-shaking or direct option-class access, and lower-level `domain/`, `config/`, `planner/`, `host/`, and `targets/` subpaths when a caller needs more control than the workflow modules provide.
-
-## Boundary Rules
-
-- Publish operations are data until execution is explicitly approved.
-- `Effect.run*` belongs at true runtime boundaries.
-- Reusable effectful operations use `Effect.fn`; inline orchestration bodies use `Effect.gen`.
-- Durable models, options, target variants, and typed errors use `Schema.Class`, `Schema.TaggedClass`, and `Schema.TaggedErrorClass`.
-- Layers are provided at CLI, action, runtime, script, application, and test boundaries.
-- Config parsing, artifact staging, distribution planning, evidence persistence, reconciliation, and approved execution are library workflows, not CLI behavior.
-- Terminal formatting, argv parsing, and `--out` file writing belong in
-  `apps/release-ts/src/cli/`.
-- GitHub Action input parsing, output names, step summaries, and evidence artifact
-  uploads belong in `apps/ts-release-action/src/`.
+Authored intent is human configuration. Verified context binds it to a clean
+source tree, package manifest, commit, tree, and repository facts. Preparation
+materializes that exact commit rather than executing against ambient workspace
+bytes. The graph is a derived in-process execution form: it is recomputable,
+not transported authority. A complete `prepared-release/v2` manifest plus
+content-addressed blobs is the durable cross-process boundary. Applications
+carry only a content-addressed prepared reference; its host store owns path or
+artifact resolution and provenance verification. Destination observation is
+the authority for publication progress.
+
+## Ownership
+
+- `src/resolve` decodes authored intent and resolves observed facts.
+- `src/release` compiles the graph, executes native preparation, and stores or
+  inspects the prepared release.
+- `src/publication` owns the provider-neutral fact/decision/attempt/report
+  coordinator and provider subjects.
+- `src/correction` binds provider-specific correction requests to exact
+  prepared subjects; catalog Git installs the sole conditional correction writer.
+- `src/api` exposes the public lifecycle used by CLI, Action, and library users.
+- `src/platform` supplies Node or Bun filesystem, process, HTTP, durable-store,
+  and opaque credential sinks at the host boundary.
+- `apps/release-ts` owns CLI parsing and file I/O.
+- `apps/ts-release-action` owns three contained Action commands and reports.
+- `apps/ts-release-agents` owns the single tracked agent projection source.
+
+## Preparation
+
+The compiler lowers useful local work to `CommandCheck` and
+`CommandArtifact`. Checks validate an existing declared input. Artifacts
+generate or transform declared regular files; their bytes are hashed into the
+prepared release. `builder: "command"` is authoring sugar for the same artifact
+primitive. Graph dependencies use declared artifact references, so independent
+node order is not a user contract.
+
+Commands are trusted local argv code with no authored host environment values;
+the runtime rejects every nonempty `environmentNames` request before starting
+a subprocess and may retain only `PATH` to locate the argv executable. They are
+not a sandbox, plugin runtime, lifecycle hook system, or remote-effect escape
+hatch. Staging materializes the verified commit into a fresh private root,
+rejects input mutation, verifies source identity after each command, and
+captures only declared regular-file outputs. Partition and merge are reserved
+input tags that fail with `PreparationModeUnsupported`; no partial object is
+durably committed.
+
+## Publication and correction
+
+Each destination subject is observed before mutation and again afterward.
+Equivalent content is skipped; mutation requires a typed provider decision;
+conflicts and inconclusive results stop; and an unknown response is resolved
+only by a later exact observation. The coordinator therefore tolerates reruns
+and lost responses without claiming exactly-once behavior or atomic rollback.
+
+PyPI adds a stricter history boundary because a filename is permanently
+consumed and an upload is unsafe to replay after response loss. Every PyPI
+token subject is an exact file and must atomically acquire a terminal claim
+from a durable store shared by all runners before mutation authority is read.
+The stock CLI and Action install no pretend runner-local substitute and fail
+closed; external hosts can supply the claim store through the Node, Bun, or
+custom host layer constructors. Trusted publishing remains owned by the
+official external PyPA Action rather than an undocumented in-process OIDC
+exchange.
+
+Corrections are separate typed intents. npm deprecation and GitHub release
+amendment requests are bound to exact prepared subjects and produce canonical
+external proposals because neither provider exposes a proved conditional
+write for the observed generation. Catalog Git installs one
+`forward-catalog-state` adapter: a SemVer-newer replacement deterministically
+renders new consumer bytes and a corrected state record, then conditionally
+updates both against the exact old pair and observed branch commit.
+
+## Hosts and targets
+
+Execution hosts, artifact targets, and native-tool hosts are independent axes.
+Linux is the only installed execution host. The Bun builder cross-compiles the
+advertised Linux and macOS x64/arm64 artifacts, but a target triple is not
+execution-host evidence. The self-release does not distribute a Windows
+ts-release binary. WSL is treated as Linux. Preparation and network-denied
+commands require the external Bun executable and `libseccomp.so.2`; even a
+standalone CLI binary is not a self-contained substitute for those native tools.
+
+## Host automation
+
+The CLI and Action call the same public operations. The automatic workflow
+persists and reload-verifies the complete prepared release before the
+coordinator can acquire mutation authority. A host environment can gate that
+publication job, but identity and consent remain host records rather than
+release-engine data. The Action's redacted report is a workflow artifact; the
+prepared bundle continues to use the dedicated content-addressed Action store.
+
+External library integrations use the supported `store` structural contract
+and the `host` layer constructor. The constructor installs custom source/run,
+prepared-store, credential-acquisition, HTTP-authorization, and optional
+shared publication-claim values behind
+the engine's private service tags. Credential values remain host-owned; the
+public seam carries only prepared requests, opaque grants, safe references,
+typed acquisition failures, and authorized HTTP results.
+
+## Extension translation
+
+The kernel admits extensions only through an owner with a narrow invariant:
+
+- tests and policy gates become `CommandCheck` nodes;
+- generated notes, manifests, and agent bundles become declared
+  `CommandArtifact` bytes;
+- npm, prebuilt PyPI, GitHub Release, and catalog Git reads/writes remain provider-module operations;
+- environment protection and human authorization remain workflow-host state;
+- announcements remain downstream workflow steps after a complete report.
+
+Homebrew and Scoop are typed render modules feeding one exact catalog Git
+provider module. Custom applications may install full provider subjects through
+the library-only SDK; the stock CLI and Action do not discover them from
+configuration. Arbitrary catalog templates are not generic hook behavior hidden inside the kernel. Wrapper-wheel generation
+is not part of the installed prebuilt PyPI capability.

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+## 0.2.2 - 2026-08-14
+
+This release delivers the intended `0.2` product relative to `0.0.7` and
+supersedes the incomplete immutable `v0.2.1` release.
+
+### npm release repair
+
+- Preserve the canonical, digest-only prepared-store blob as the admitted npm
+  publication input, while materializing its exact bytes through a private,
+  mode-0600 `.tgz` transport path only for the lifetime of the npm process.
+  npm treats a suffixless local path as a package directory; the scoped alias
+  gives npm the required file classification without weakening prepared-bundle
+  validation or leaving transport bytes behind after success, failure, or
+  interruption.
+
+## 0.2.1 - incomplete (2026-08-14)
+
+The immutable GitHub tag, release, and configured assets were created, but npm
+did not publish because npm classified the verified digest-only blob path as a
+directory. Those subjects remain an audit record and are superseded by
+`0.2.2`; no `0.2.1` subject was rewritten. This candidate otherwise contained
+the following release content and repairs.
+
+### Release repair
+
+- Preserve caller-declared HTTP body media types through the Effect transport,
+  so GitHub agent archives retain `application/zip` instead of being rewritten
+  to `application/octet-stream`.
+- Authenticate recovery against the canonical workflow path and `head_branch`
+  fields returned by GitHub's run-attempt API, allowing an emitted immutable
+  prepared reference to be reloaded in a later workflow run.
+
+### Release lifecycle
+
+- Replaced the previous `ship` and plan/apply/review command model with one
+  lifecycle: `release`, `prepare`, `inspect`, `observe`, `publish`, and
+  `correct`. The same lifecycle is available through the Promise API, CLI, and
+  GitHub Action.
+- Added complete, content-addressed `prepared-release/v2` bundles. Preparation
+  materializes the exact verified commit, binds declared source inputs, checks
+  the manifest and blobs, and commits the durable bundle only when every
+  declared output is present.
+- Added one-command local release and a one-job automatic GitHub Actions path.
+  Protected-environment publication remains an optional two-job host workflow,
+  not an identity inside ts-release.
+- Added a strict `bun-npm-github` init preset that discovers the canonical
+  repository coordinate and writes explicit npm and GitHub authentication
+  intent.
+
+### Publication, authentication, and recovery
+
+- Retained npm publication and restored explicit trusted-publishing intent.
+  npm authentication must select GitHub Actions OIDC or a named token
+  credential; credential values remain host-owned and do not enter
+  configuration, prepared bytes, reports, or logs.
+- Retained GitHub Releases and asset publication with exact tag, commit,
+  release, and asset observation before mutation.
+- Publication now observes every destination before writing. Equivalent
+  subjects are skipped, conflicts stop, and inconclusive pre-mutation reads do
+  not acquire credentials. A response-lost write remains uncertain until an
+  exact later observation converges.
+- Recovery always reloads and verifies the same prepared bundle. It never
+  rebuilds from the current checkout as a fallback. Reports preserve partial
+  and uncertain outcomes and are redacted before a workflow uploads them.
+- Correction is now proposal-only for the installed npm and GitHub providers.
+  `correct` binds intent to an exact prepared subject and emits a canonical
+  external-operator proposal; it does not delete or mutate provider state.
+
+### Executable capabilities
+
+- Retained Bun compilation, prebuilt-file imports, declared command checks and
+  artifact generation, archives, and checksums behind strict configuration and
+  default runtime layers.
+- Separated execution-host claims from artifact-target claims. Linux is the
+  only execution host, the advertised targets are Linux/macOS x64/arm64, and
+  Windows is neither an execution host nor a shipped target.
+- Added generated capability, recovery-profile, and agent-bundle evidence so a
+  documented support row must join to executable code and tests.
+
+### Breaking removals and migration
+
+- Removed the old `ship`, plan/apply/review, approval, and self-review
+  protocols. Migrate automation to `release`, or cross an explicit boundary
+  with `prepare` followed by `publish` of the returned prepared reference.
+- Replaced implicit npm credential selection with explicit
+  `publish.npm.authentication`. Existing token workflows must name their
+  environment credential; GitHub-hosted trusted publishing must author its
+  exact attestation relationship.
+- Installed Node consumers now require
+  `^22.22.2 || ^24.15.0 || >=26.0.0`. The checked-in GitHub Action is now a
+  native Node 24 launcher around a Linux/Bun boundary: advertised workflows
+  install pinned Bun, the runtime preloader receives no credentials, and the
+  Bun release child receives the runner's Actions-artifact transport. Artifact
+  upload/download is executed by a checked-in Node 24 bridge so the official
+  client uses native Node streams; bridge requests never serialize the GitHub
+  token. This does not change the installed library or CLI's Node engine.
+- PyPI prebuilt publication is temporarily removed despite being available in
+  `0.0.7`; it is assigned to a post-`0.2.2` provider-capability wave. PyPI
+  wrapper wheels are also removed, and will return only after an explicit
+  product decision based on native-wheel or cibuildwheel-class user demand.
+- Homebrew tap and Scoop bucket rendering and delivery are temporarily removed
+  despite being available in `0.0.7`; they are assigned to a separate catalog
+  delivery wave. Old PyPI, Homebrew, Scoop, and generic catalog configurations
+  are rejected rather than accepted as no-ops.
+- A third-party publication-adapter SDK is not part of `0.2.2`. Local extension
+  work must use declared command checks or artifact bytes; downstream effects
+  belong in the workflow host after a complete release report.
+
+## 0.2.0 - incomplete (2026-08-14)
+
+The immutable GitHub tag and release were created, but asset publication did
+not complete and npm was not published. Those immutable subjects remain as an
+audit record and are superseded by `0.2.1`; no `0.2.0` subject was rewritten.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mannyc2
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.