@mannyc1/ts-release 0.0.1 → 0.0.2

package/ARCHITECTURE.md

@@ -0,0 +1,53 @@
+# Architecture
+
+`@mannyc1/ts-release` is library-first and CLI-second.
+
+The package turns release intent into typed data, plans, evidence, and approved operations. The CLI is only an argv, console, and terminal-file adapter over those workflows.
+
+## Module Taxonomy
+
+- `domain/` contains durable schema-backed data models and errors.
+- `config/` parses and validates release config into domain values.
+- `planner/` normalizes release intent, builds plans, renders plans, executes operation data through injected services, records evidence, reports status, resumes safe work, and reconciles 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, evidence files, and live target/HTTP composition. This is the high-level programmatic surface.
+- `runtime/` contains runtime-specific layer assembly. `runtime/bun` is the Bun composition used by the published executable and maintenance scripts.
+- `cli/` parses command-line flags, calls workflows, prints terminal output, and writes user-requested CLI output files.
+- `scripts/` contains repository maintenance checks. Scripts may use runtime layers, but they are not package library code.
+
+## Dependency Direction
+
+Library modules must not import from `cli/`.
+
+The normal flow is:
+
+```text
+domain <- config
+domain <- planner <- targets
+domain <- host
+workflows -> config/planner/host/targets
+runtime -> host/workflows/platform layers
+cli -> workflows/runtime boundary
+```
+
+`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`.
+
+## Public Workflow Surface
+
+There is no public `./api` facade. The public workflow modules are named after the work they own:
+
+- `./workflows/config` for config-file release workflows.
+- `./workflows/evidence` for reusable evidence persistence.
+- `./workflows/live` for runtime-neutral live target and HTTP services.
+- `./runtime/bun` for the Bun runtime composition.
+
+Use 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.
+- Layers are provided at CLI, runtime, script, and test boundaries.
+- Config parsing, evidence persistence, status, resume, reconciliation, and release execution are library workflows, not CLI behavior.
+- Terminal formatting, argv parsing, and `--out` file writing belong in `cli/`.

package/README.md

@@ -21,22 +21,35 @@ bun run cli validate --config release.config.json
 bun run cli print --config release.config.json
 bun run cli execute --config release.config.json --execute --approve-irreversible
 bun run cli verify --config release.config.json
+bun run cli eligibility --config release.config.json --format text
+bun run cli reconcile --config release.config.json --execute
 ```
 
 Rendering writes generated target files locally and records `render.json` evidence. `execute` is a lower-level primitive that runs publish operations only. Publishing is blocked unless execution is explicitly approved. Irreversible operations require a second approval flag.
 
+Status and resume commands use existing `.release/evidence` files to report progress and continue conservative unfinished work:
+
+```sh
+bun run cli status --config release.config.json --format text
+bun run cli resume --config release.config.json --execute --approve-irreversible
+```
+
+Resume skips operations with successful matching evidence, reruns safe read-only failures, and blocks failed publish operations until remote state is reconciled manually.
+`eligibility` checks npm and GitHub remote state before the self-release workflow decides whether to run.
+`reconcile` is separate from resume: it inspects GitHub release state through the API and can publish a matching draft release with explicit `--execute` without republishing immutable npm versions.
+
+The executable is an argv and console adapter over TypeScript workflows. Release workflows are modeled as typed functions first, then exposed through the CLI for terminal and CI usage.
+
 ## Imports
 
 The package intentionally avoids aggregate library barrels. The root `release` export is intentionally empty; import the exact module you need from an explicit subpath.
 
 ```ts
 import * as Effect from "effect/Effect"
-import * as Layer from "effect/Layer"
 import { type ReleaseIntent } from "@mannyc1/ts-release/domain/release"
-import { BunReleaseHostLayer } from "@mannyc1/ts-release/host/bun"
 import { createReleasePlan } from "@mannyc1/ts-release/planner/create-release-plan"
 import { validatePlan } from "@mannyc1/ts-release/planner/executor"
-import { LiveTargetRegistryLayer } from "@mannyc1/ts-release/targets/live"
+import { makeBunReleaseWorkflowRuntimeLayer } from "@mannyc1/ts-release/runtime/bun"
 
 const planAndValidate = (intent: ReleaseIntent) =>
   Effect.gen(function*() {
@@ -44,46 +57,109 @@ const planAndValidate = (intent: ReleaseIntent) =>
     const evidence = yield* validatePlan(plan)
     return { plan, evidence }
   }).pipe(
-    Effect.provide(Layer.mergeAll(BunReleaseHostLayer, LiveTargetRegistryLayer))
+    Effect.provide(makeBunReleaseWorkflowRuntimeLayer())
   )
 ```
 
-`createReleasePlan` needs a `TargetRegistry` layer. `validatePlan` needs `ReleaseHost` and `TargetRegistry` layers. Workflows that verify HTTP evidence, such as `verifyPlan`, `runApprovedReleaseWorkflow`, or direct `VerifyHttpOperation` execution, also need a `ReleaseHttp` layer. Bun callers can import `LiveReleaseHttpLayer` from `@mannyc1/ts-release/host/http-live` and provide it with a `ReleaseHost` layer plus an Effect HTTP client such as `@effect/platform-bun/BunHttpClient`; tests can import `makeTestReleaseHttpLayer` from `@mannyc1/ts-release/host/http`. Internal Effect imports use deep module paths such as `effect/Effect` and `effect/Layer` to keep bundlers from depending on broad root-package analysis.
+`createReleasePlan` needs a `TargetRegistry` layer. Command execution needs a `ReleaseCommandRunner` layer, while artifact checks and checksum generation use Effect Platform `FileSystem`, `Path`, and `Crypto` services directly. High-level config-file workflows, render writes, and evidence writes also need Effect Platform `FileSystem` and `Path` services. Workflows that verify HTTP evidence, such as `verifyPlan`, `runApprovedReleaseWorkflow`, or direct `VerifyHttpOperation` execution, also need a `ReleaseHttp` layer. `makeBunReleaseWorkflowRuntimeLayer` is the Bun runtime composition used by the published CLI; applications on other runtimes can compose `@mannyc1/ts-release/workflows/live`, `@mannyc1/ts-release/host/platform`, and their platform services at the edge. Tests can import `makeTestReleaseHttpLayer` from `@mannyc1/ts-release/host/http`. Internal Effect imports use deep module paths such as `effect/Effect` and `effect/Layer` to keep bundlers from depending on broad root-package analysis. See `ARCHITECTURE.md` for the module taxonomy.
 
-## Programmatic CLI
+## TypeScript Workflows
 
-Applications can run the CLI command path without spawning the executable:
+Applications can call high-level release workflows without argv arrays or CLI command names:
 
 ```ts
 import * as Effect from "effect/Effect"
+import { makeBunReleaseWorkflowRuntimeLayer } from "@mannyc1/ts-release/runtime/bun"
 import {
   PlanReleaseConfigOptions,
+  ReleaseExecutionOptions,
+  ReleaseEligibilityConfigOptions,
+  ReleaseReconcileConfigOptions,
+  ReleaseResumeConfigOptions,
+  ReleaseStatusOptions,
+  checkReleaseConfigEligibility,
+  reconcileReleaseConfig,
   planReleaseConfig,
-  ReleaseCliOptions,
-  runReleaseCli
-} from "@mannyc1/ts-release/cli/programmatic"
-
-await Effect.runPromise(
-  runReleaseCli([
-    "plan",
-    "--config",
-    "release.config.json",
-    "--format",
-    "text"
-  ], ReleaseCliOptions.make({ root: "/path/to/release-workspace" }))
+  renderReleaseConfigPlan,
+  resumeReleaseConfig,
+  runReleaseConfig,
+  statusReleaseConfig
+} from "@mannyc1/ts-release/workflows/config"
+
+const root = "/path/to/release-workspace"
+const RuntimeLayer = makeBunReleaseWorkflowRuntimeLayer({ root })
+
+const textPlan = await Effect.runPromise(
+  renderReleaseConfigPlan(
+    PlanReleaseConfigOptions.make({ root, configPath: "release.config.json", format: "text" })
+  ).pipe(Effect.provide(RuntimeLayer))
 )
 
 const plan = await Effect.runPromise(
-  planReleaseConfig(
-    PlanReleaseConfigOptions.make({
-      root: "/path/to/release-workspace",
+  planReleaseConfig(PlanReleaseConfigOptions.make({ root, configPath: "release.config.json" })).pipe(
+    Effect.provide(RuntimeLayer)
+  )
+)
+
+const evidence = await Effect.runPromise(
+  runReleaseConfig(
+    ReleaseExecutionOptions.make({
+      root,
+      configPath: "release.config.json",
+      execute: true,
+      approveIrreversible: true
+    })
+  ).pipe(
+    Effect.provide(RuntimeLayer)
+  )
+)
+
+const status = await Effect.runPromise(
+  statusReleaseConfig(
+    ReleaseStatusOptions.make({ root, configPath: "release.config.json", format: "json" })
+  ).pipe(
+    Effect.provide(RuntimeLayer)
+  )
+)
+
+const resumedEvidence = await Effect.runPromise(
+  resumeReleaseConfig(
+    ReleaseResumeConfigOptions.make({
+      root,
+      configPath: "release.config.json",
+      execute: true,
+      approveIrreversible: true
+    })
+  ).pipe(
+    Effect.provide(RuntimeLayer)
+  )
+)
+
+const eligibility = await Effect.runPromise(
+  checkReleaseConfigEligibility(
+    ReleaseEligibilityConfigOptions.make({
+      root,
       configPath: "release.config.json"
     })
+  ).pipe(
+    Effect.provide(RuntimeLayer)
+  )
+)
+
+const reconciliationEvidence = await Effect.runPromise(
+  reconcileReleaseConfig(
+    ReleaseReconcileConfigOptions.make({
+      root,
+      configPath: "release.config.json",
+      execute: true
+    })
+  ).pipe(
+    Effect.provide(RuntimeLayer)
   )
 )
 ```
 
-The helper provides the Bun host and live target registry internally, so callers do not need to import `effect/unstable/cli/Command` or assemble CLI layers by hand.
+Use `@mannyc1/ts-release/workflows/config` for high-level config-file workflows, `@mannyc1/ts-release/workflows/evidence` for reusable evidence persistence, and `@mannyc1/ts-release/workflows/live` for the live target/HTTP layer. Bun callers can use `@mannyc1/ts-release/runtime/bun` for the same runtime layer used by the published binary. Node callers can provide Node platform services and a Node HTTP client instead. Use explicit lower-level planner, config, target, host, and domain subpaths when an application needs finer control over planning, execution, or test layers.
 
 ## Example Config
 
@@ -115,10 +191,15 @@ The helper provides the Bun host and live target registry internally, so callers
       "_tag": "NpmRegistryTarget",
       "id": "npm",
       "registry": "https://registry.npmjs.org",
+      "packageName": "@mannyc1/ts-release",
       "packagePath": ".",
-      "tokenEnv": "NPM_TOKEN",
+      "trustedPublishing": {
+        "provider": "github-actions",
+        "workflow": "release.yml",
+        "packageExists": true,
+        "verifyPackageExists": true
+      },
       "access": "public",
-      "provenance": true,
       "dryRunSupport": "native",
       "mutability": "immutable",
       "recovery": "publish-new-version"
@@ -135,11 +216,11 @@ The helper provides the Bun host and live target registry internally, so callers
     }
   ],
   "strict": true,
-  "evidenceDirectory": ".release/evidence"
+  "evidenceDirectory": ".release/evidence/{version}"
 }
 ```
 
-Paths are release-workspace relative and may not be absolute or contain parent traversal.
+Paths are release-workspace relative and may not be absolute or contain parent traversal. `evidenceDirectory` may include the literal `{version}` placeholder, which is resolved during planning so each release version can use its own evidence directory.
 
 Homebrew tap targets model catalog updates as generated files plus an approval-gated push:
 
@@ -205,23 +286,31 @@ Text plans include the release identity, evidence directory, artifact inventory,
 ```text
 @mannyc1/ts-release@0.1.0
 commit: abc123
-evidence: .release/evidence
+evidence: .release/evidence/0.1.0
 artifacts: 2
 targets: 2
 operations: 9
 
 targets:
   - github [GitHubReleaseTarget] auth=env-token dry-run=simulated strategy=simulated-plan mutability=mutable-release recovery=delete-and-recreate
-  - npm [NpmRegistryTarget] auth=env-token dry-run=native strategy=native-command mutability=immutable recovery=publish-new-version
+  - npm [NpmRegistryTarget] auth=trusted-publishing runs-in=ci provider=github-actions workflow=release.yml required-permission=id-token:write package-prerequisite=exists dry-run=native strategy=native-command mutability=immutable recovery=publish-new-version
 ```
 
 JSON plans include the same data in a stable, CI-artifact-friendly shape, including `targetCapabilities`.
 
 GitHub release verification uses the GitHub REST API to check the release tag, title, draft flag, prerelease flag, and each uploaded artifact name.
 
+## Status and Resume
+
+`status` reads local phase evidence and reports each current operation as pending, passed, failed, blocked, or complete without executing anything. The JSON format is schema-backed for CI or dashboards; the text format is intended for terminal review.
+
+`resume` is intentionally conservative. It skips successful matching evidence, can rerun missing work and failed read-only validation or verification operations, and never reruns a failed publish operation. A failed publish command can still have changed the outside world, so resume blocks until a maintainer reconciles npm, GitHub, or any other remote state manually.
+
+`reconcile` is the narrow remote repair path for GitHub Releases. It reads the GitHub release by tag, blocks on mismatched metadata or assets, skips an already matching published release, and can run `gh release edit <tag> --draft=false` for a matching draft when the target expects a public release. It does not run `npm publish`.
+
 ## Public API
 
-The intentional public API is the explicit subpath list in `package.json`. `release/cli` and `release/cli/command` are public so applications can embed the CLI command, while the executable remains available through the `release` binary.
+The intentional public API is the explicit subpath list in `package.json`. The npm package exposes the `release` executable through `bin`; programmatic callers should import high-level workflows from `@mannyc1/ts-release/workflows/config` or use the explicit lower-level planner/config/target/status subpaths for finer control. `release/cli` and `release/cli/command` remain public for applications that need to embed the CLI command adapter.
 
 The package export checker fails if a new export is added without being added to the intentional API list.
 
@@ -231,6 +320,7 @@ Runnable example configs live in `examples/`:
 
 - `examples/multi-target`
 - `examples/npm-only`
+- `examples/npm-first-publish`
 - `examples/github-release`
 - `examples/homebrew-tap`
 - `examples/pypi-registry`
@@ -247,7 +337,7 @@ bun ../../dist/cli/main.js plan --config release.config.json --format text
 
 ## Evidence
 
-Render, validation, execution, and verification evidence is written as JSON bundles. Failed commands still preserve partial evidence before the command failure is returned.
+Render, validation, execution, and verification evidence is written as JSON bundles. Failed commands still preserve partial evidence before the command failure is returned. Use `evidenceDirectory` such as `.release/evidence/{version}` when older local evidence should not collide with the current release version.
 
 ```json
 {
@@ -287,7 +377,7 @@ RELEASE_INTEGRATION_GITHUB=1 bun run test:integration:tools
 
 The first command validates npm adapter operations against the real `npm` CLI. The second also validates GitHub adapter readiness checks against the real `gh` CLI and requires `gh auth status` to succeed. GitHub release creation itself has no native dry-run; release validation is simulated from the deterministic plan before publish and verified against GitHub only after publish.
 
-Example configs are checked through the same programmatic CLI command path:
+Example configs are checked through the TypeScript workflow path:
 
 ```sh
 bun run check:examples
@@ -299,8 +389,61 @@ This repository also includes a first release config at `release.config.json` th
 bun run check:self-release-config
 ```
 
+### Self Release
+
+The local non-publish gates for this package are:
+
+```sh
+bun run check:release
+bun run release:artifacts
+bun dist/cli/main.js plan --config release.config.json --format text
+```
+
+`release:artifacts` writes ignored files under `.release/artifacts`: the npm package tarball and standalone CLI executables for Linux, macOS, and Windows. GitHub Actions runs the approved release workflow on protected `main` when the package version has not already been published. The workflow uses npm trusted publishing with GitHub Actions OIDC instead of an npm token, and uploads `.release/evidence/**` for audit.
+
 ### Local Release Auth
 
-Use `.env.example` as the local credential contract. Export `NPM_TOKEN` and `GH_TOKEN`, or copy `.env.example` to `.env` and fill in the tokens locally. `.env` and `.npmrc` are ignored intentionally; keep token values out of commits. `.npmrc.example` shows npm's `${NPM_TOKEN}` interpolation form for local setup.
+Use `.env.example` as the local credential contract. Export `GH_TOKEN`, or copy
+`.env.example` to `.env` and fill in token values locally. `.env` and `.npmrc`
+are ignored intentionally; keep token values out of commits. `.npmrc.example`
+shows npm's `${NPM_TOKEN}` interpolation form for token-based npm targets.
+
+For npmjs releases from GitHub Actions, prefer structured `trustedPublishing` on
+the npm target:
+
+```json
+{
+  "packageName": "@mannyc1/ts-release",
+  "trustedPublishing": {
+    "provider": "github-actions",
+    "workflow": "release.yml",
+    "packageExists": true,
+    "verifyPackageExists": true
+  }
+}
+```
 
-The first-release GitHub target uses `GH_TOKEN` for both `gh` command authentication and read-only REST API verification. Draft release verification requires authenticated API access. Enable npm provenance for CI-based publishes where the registry can generate provenance.
+Trusted publishing authenticates during `npm publish` with CI OIDC, so
+`ts-release` records that mode in validation evidence instead of running
+`npm whoami`, which does not validate OIDC publishing. Configure npmjs trusted
+publishing for an existing package and use a GitHub-hosted runner with
+`id-token: write`, Node 22.14+ and npm 11.5.1+. The `packageExists` field must be
+`true` as a precondition acknowledgement, not first-publish support. Setting
+`verifyPackageExists` to `true` adds a read-only `npm view <package>` validation
+check. Trusted publishing does not use `NPM_TOKEN` for `npm publish`; token-based
+npm targets may still use `.npmrc.example` and `NPM_TOKEN`.
+
+### First npm Publish Bootstrap
+
+Trusted publishing is the preferred steady state for GitHub Actions, but npm
+requires the package to exist before trusted publishing can be configured. For a
+new package, use a temporary token-based npm target with `tokenEnv: "NPM_TOKEN"`
+and no `trustedPublishing` object. After the first version exists on npm,
+configure npm trusted publishing for owner `mannyc2`, repository `ts-release`,
+and workflow filename `release.yml`, then switch the target to
+`trustedPublishing`.
+
+Do not commit token values. Keep `.env.example` and `.npmrc.example` as
+placeholder contracts only.
+
+The first-release GitHub target uses `GH_TOKEN` for both `gh` command authentication and read-only REST API verification. The release workflow sets up a current Node/npm toolchain for trusted publishing and enables npm provenance for CI-based publishes where the registry can generate provenance.

package/SPEC.md

@@ -19,6 +19,7 @@ release intent
   -> 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.
@@ -51,7 +52,7 @@ Examples:
 - 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.
+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
 
@@ -59,6 +60,8 @@ 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
@@ -67,6 +70,8 @@ Operations that publish immutable versions, create public releases, overwrite in
 
 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
@@ -82,6 +87,8 @@ The library should expose APIs for:
 - preparing executable operations
 - running approved operations through an injected host interface
 - recording evidence
+- reporting release status from evidence
+- conservatively resuming safe unfinished work
 
 The CLI should mainly parse arguments, call the library, and format output.
 

package/dist/cli/command.d.ts

@@ -1,4 +1,4 @@
 import * as Command from "effect/unstable/cli/Command";
 export type * from "../types/effect-internal.js";
-export declare const cli: Command.Command<"release", {}, {}, import("../domain/operation.js").ExecutionApprovalError | import("../config/errors.js").ConfigParseError | import("../config/errors.js").ConfigValidationError | import("../host/host.js").HostError | import("../planner/errors.js").ReleaseNormalizationError | import("../planner/errors.js").PlanConstructionError | import("../planner/errors.js").EvidenceWriteError | import("../planner/errors.js").OperationFailedError | import("../targets/registry.js").MissingTargetAdapterError, never>;
+export declare const cli: Command.Command<"release", {}, {}, import("effect/PlatformError").PlatformError | import("../config/errors.js").ConfigReadError | import("../config/errors.js").ConfigParseError | import("../config/errors.js").ConfigValidationError | import("../domain/operation.js").ExecutionApprovalError | import("../planner/errors.js").ReleaseNormalizationError | import("../planner/errors.js").PlanConstructionError | import("../planner/errors.js").EvidenceWriteError | import("../planner/errors.js").EvidenceReadError | import("../planner/errors.js").WorkspaceWriteError | import("../planner/errors.js").ResumeBlockedError | import("../planner/errors.js").RemoteStateInspectionError | import("../planner/errors.js").ReleaseEligibilityCheckError | import("../planner/errors.js").ReconciliationBlockedError | import("../planner/errors.js").OperationFailedError | import("../targets/registry.js").MissingTargetAdapterError | import("../host/host.js").CommandRunnerError, never>;
 //# sourceMappingURL=command.d.ts.map

package/dist/cli/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/cli/command.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,OAAO,MAAM,6BAA6B,CAAA;AAatD,mBAAmB,6BAA6B,CAAA;AAsMhD,eAAO,MAAM,GAAG,0gBAEf,CAAA"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/cli/command.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,OAAO,MAAM,6BAA6B,CAAA;AAqCtD,mBAAmB,6BAA6B,CAAA;AAiQhD,eAAO,MAAM,GAAG,o8BAcf,CAAA"}