@mannyc1/ts-release 0.0.7 → 0.3.0

package/src/resolve/resolve.ts

@@ -0,0 +1,328 @@
+// Authored configuration plus observed facts → the canonical config, by total
+// rules and nothing else. This is the ONLY place authored-to-canonical
+// semantics may live: no recipe and no compiler may infer anything, because
+// plan bytes are a function of the canonical value alone.
+//
+// Every rule is one of three shapes: the authored value wins, a fact fills an
+// omission, or the two disagree and the resolver REFUSES naming both values and
+// where each came from. Silence is never an option — a release that guesses its
+// own identity is the defect this module exists to prevent.
+import * as Schema from "effect/Schema"
+import * as Semver from "semver"
+import { MISSING_COMMIT } from "../model/errors.js"
+import { NonEmptyName, OutputId, Version } from "../model/primitives.js"
+import {
+  CandidateConfig,
+  type CandidateNpmPublish,
+  type CandidatePyPiPublish,
+  CanonicalNpmRegistryEndpoint,
+  NpmDistTag,
+  PyPiProjectName,
+  canonicalizeNpmRegistryEndpoint,
+  normalizePyPiProjectName
+} from "../recipes/config.js"
+import { AuthoredConfig } from "./authored.js"
+import { toPlainJson } from "./encode.js"
+import { ResolveError } from "./errors.js"
+import { ObservedFacts } from "./facts.js"
+
+const refuse = (field: string, reason: string): never => {
+  throw new ResolveError(field, reason)
+}
+const disagreement = (
+  field: string, authored: string, observed: string, source: string
+): never =>
+  refuse(
+    `project.${field}`,
+    `project.${field} is ${JSON.stringify(authored)} in the config but ${
+      JSON.stringify(observed)
+    } ${source}. Remove the authored value or correct the source; the resolver never picks.`
+  )
+
+const decodeAuthored = Schema.decodeUnknownSync(AuthoredConfig, { onExcessProperty: "error" })
+const decodeFacts = Schema.decodeUnknownSync(ObservedFacts, { onExcessProperty: "error" })
+const decodeCandidate = Schema.decodeUnknownSync(CandidateConfig, { onExcessProperty: "error" })
+
+const version = (
+  authored: AuthoredConfig, facts: ObservedFacts
+): Version => {
+  const directive = authored.versionFrom
+  const observed = directive === "manifest"
+    ? facts.manifestVersion
+    : directive === "git-tag"
+    ? facts.headTagVersion
+    : undefined
+  const source = directive === "manifest" ? "in the package manifest" : "on the tag at HEAD"
+  if (authored.project.version !== undefined) {
+    if (observed !== undefined && observed !== authored.project.version) {
+      disagreement("version", authored.project.version, observed, source)
+    }
+    return authored.project.version
+  }
+  if (directive === undefined) {
+    return refuse(
+      "project.version",
+      "project.version is required. State it, or set versionFrom to \"manifest\" or \"git-tag\" so it can be observed."
+    )
+  }
+  if (observed === undefined) {
+    return refuse(
+      "project.version",
+      `versionFrom is ${JSON.stringify(directive)} but no version was observed ${source}.`
+    )
+  }
+  return observed
+}
+
+// `{version}` is the whole grammar. An unrecognized token is a refusal, exactly
+// as the checksum name filter treats one.
+const tag = (authored: AuthoredConfig, resolved: Version): NonEmptyName => {
+  if (authored.project.tag !== undefined) return authored.project.tag
+  const template = authored.project.tagTemplate ?? "v{version}"
+  const rendered = template.replaceAll("{version}", resolved)
+  if (rendered.includes("{") || rendered.includes("}")) {
+    return refuse(
+      "project.tagTemplate",
+      `project.tagTemplate supports only the {version} token, got ${JSON.stringify(template)}.`
+    )
+  }
+  return NonEmptyName.make(rendered)
+}
+
+const requireObservedCommit = (facts: ObservedFacts): void => {
+  if (facts.commit === undefined) refuse("source.commit", MISSING_COMMIT)
+}
+
+const names = (
+  authored: AuthoredConfig, facts: ObservedFacts
+): { readonly name: string, readonly packageName?: string } => {
+  const manifest = facts.manifestName
+  if (manifest !== undefined && authored.project.packageName !== undefined &&
+    manifest !== authored.project.packageName) {
+    disagreement("packageName", authored.project.packageName, manifest, "in the package manifest")
+  }
+  const name = authored.project.name ?? manifest
+  if (name === undefined) {
+    return refuse("project.name", "project.name is required when no package manifest is observed.")
+  }
+  const packageName = authored.project.packageName ?? manifest
+  return { name, ...(packageName === undefined ? {} : { packageName }) }
+}
+
+const repository = (authored: AuthoredConfig, facts: ObservedFacts): string | undefined => {
+  if (authored.project.repository !== undefined && facts.repository !== undefined && authored.project.repository !== facts.repository) {
+    disagreement("repository", authored.project.repository, facts.repository, "in the observed repository")
+  }
+  return authored.project.repository ?? facts.repository
+}
+
+const canonicalRegistry = (value: string | undefined): CanonicalNpmRegistryEndpoint => {
+  try {
+    return CanonicalNpmRegistryEndpoint.make(
+      canonicalizeNpmRegistryEndpoint(value ?? "https://registry.npmjs.org")
+    )
+  } catch (cause) {
+    return refuse(
+      "publish.npm.registry",
+      cause instanceof Error ? cause.message : String(cause)
+    )
+  }
+}
+
+const distTag = (versionValue: Version, authored: string | undefined): NpmDistTag => {
+  const normalized = Semver.valid(versionValue.toString())
+  if (normalized === null || normalized !== versionValue.toString()) {
+    return refuse(
+      "project.version",
+      `npm publication requires a canonical semantic version, got ${JSON.stringify(versionValue)}.`
+    )
+  }
+  const prerelease = Semver.prerelease(normalized) !== null
+  if (authored === undefined) {
+    if (prerelease) {
+      return refuse(
+        "publish.npm.distTag",
+        "Prerelease npm versions require an explicit non-latest distTag."
+      )
+    }
+    return NpmDistTag.make("latest")
+  }
+  let tag: NpmDistTag
+  try { tag = NpmDistTag.make(authored) } catch (cause) {
+    return refuse(
+      "publish.npm.distTag",
+      cause instanceof Error ? cause.message : String(cause)
+    )
+  }
+  if (prerelease && tag === "latest") {
+    return refuse(
+      "publish.npm.distTag",
+      "Prerelease npm versions cannot publish under the latest dist-tag."
+    )
+  }
+  return tag
+}
+
+type ResolvedProject = {
+  readonly name: string
+  readonly packageName?: string
+  readonly version: Version
+  readonly repository?: string
+}
+
+const npmPublish = (
+  authored: AuthoredConfig,
+  project: ResolvedProject
+): CandidateNpmPublish | undefined => {
+  const npm = authored.publish?.npm
+  if (npm === undefined) return undefined
+  if (authored.npmPackage === undefined) {
+    return refuse(
+      "npmPackage",
+      "publish.npm requires npmPackage to declare the exact package artifact prepared by npm pack."
+    )
+  }
+  const packageName = project.packageName ?? project.name
+  if (npm.access === "restricted" && !packageName.startsWith("@")) {
+    return refuse(
+      "publish.npm.access",
+      "npm restricted access is valid only for scoped package names."
+    )
+  }
+  const registry = canonicalRegistry(npm.registry)
+  const authentication = npm.authentication
+  if (authentication.strategy === "trusted-publishing") {
+    if (registry !== "https://registry.npmjs.org/") {
+      return refuse(
+        "publish.npm.authentication",
+        "npm trusted publishing is certified only for https://registry.npmjs.org/."
+      )
+    }
+    if (project.repository === undefined) {
+      return refuse(
+        "project.repository",
+        "npm trusted publishing requires the exact GitHub owner/repository coordinate."
+      )
+    }
+    if (authentication.attestation.repository !== project.repository) {
+      return refuse(
+        "publish.npm.authentication.attestation.repository",
+        `The attested repository ${JSON.stringify(authentication.attestation.repository)} does not match ${
+          JSON.stringify(project.repository)
+        } resolved for the package.`
+      )
+    }
+  }
+  const provenance = npm.provenance ??
+    (authentication.strategy === "trusted-publishing" ? "automatic" : "disabled")
+  if (authentication.strategy === "token" && provenance === "automatic") {
+    return refuse(
+      "publish.npm.provenance",
+      "Automatic provenance is an npm trusted-publishing behavior; token mode must choose required or disabled."
+    )
+  }
+  return {
+    packageArtifact: OutputId.make("npm-package"),
+    packageName: NonEmptyName.make(packageName),
+    registry,
+    distTag: distTag(project.version, npm.distTag),
+    access: npm.access ?? "public",
+    authentication,
+    provenance
+  }
+}
+
+const pypiPublish = (
+  authored: AuthoredConfig,
+  project: ResolvedProject
+): CandidatePyPiPublish | undefined => {
+  const pypi = authored.publish?.pypi
+  if (pypi === undefined) return undefined
+  const artifacts = pypi.artifacts.map((id) => OutputId.make(id)) as [OutputId, ...Array<OutputId>]
+  if (new Set(artifacts).size !== artifacts.length) {
+    return refuse("publish.pypi.artifacts", "PyPI publication cannot repeat one distribution artifact.")
+  }
+  if (pypi.authentication.strategy === "trusted-publishing") {
+    if (project.repository === undefined) {
+      return refuse("project.repository", "External PyPI trusted publishing requires the exact GitHub owner/repository coordinate.")
+    }
+    if (pypi.authentication.repository !== project.repository) {
+      return refuse(
+        "publish.pypi.authentication.repository",
+        `The external PyPI publisher repository ${JSON.stringify(pypi.authentication.repository)} does not match ${JSON.stringify(project.repository)}.`
+      )
+    }
+    let projectName: string
+    let projects: ReadonlyArray<string>
+    try {
+      projectName = normalizePyPiProjectName(project.name)
+      projects = pypi.authentication.projects.map(normalizePyPiProjectName)
+    } catch (cause) {
+      return refuse("publish.pypi", cause instanceof Error ? cause.message : String(cause))
+    }
+    if (!projects.includes(projectName)) {
+      return refuse(
+        "publish.pypi.authentication.projects",
+        `The external PyPI publisher authority set does not include ${JSON.stringify(projectName)}.`
+      )
+    }
+    if (new Set(projects).size !== projects.length) {
+      return refuse("publish.pypi.authentication.projects", "External PyPI publisher project coordinates must be unique after normalization.")
+    }
+  }
+  let projectName: PyPiProjectName
+  try { projectName = PyPiProjectName.make(normalizePyPiProjectName(project.name)) } catch (cause) {
+    return refuse("publish.pypi", cause instanceof Error ? cause.message : String(cause))
+  }
+  return {
+    artifacts,
+    project: projectName,
+    version: project.version,
+    repository: pypi.repository ?? "pypi",
+    authentication: pypi.authentication
+  }
+}
+
+/**
+ * Resolve an authored configuration and observed facts into the canonical
+ * configuration. Pure and total: the same inputs always produce the same value,
+ * and every unfillable or contradicted field raises `ResolveError`.
+ */
+export { MISSING_COMMIT }
+
+export const resolveConfig = (authored: unknown, facts: unknown): CandidateConfig => {
+  const config = decodeAuthored(authored)
+  const observed = decodeFacts(facts)
+  const resolvedVersion = version(config, observed)
+  // The directives are CONSUMED here: they describe how to resolve, and the
+  // canonical world has never heard of them.
+  const { project, versionFrom: _directive, $schema: _schema, ...rest } = config
+  const { tagTemplate: _template, ...projectRest } = project
+  const resolvedNames = names(config, observed)
+  const resolvedRepository = repository(config, observed)
+  // Verified source identity is observation-owned. It must exist, but is not a
+  // human-authored config field and is not copied into canonical release intent.
+  requireObservedCommit(observed)
+  const resolvedProject = {
+    ...projectRest,
+    ...resolvedNames,
+    ...(resolvedRepository === undefined ? {} : { repository: resolvedRepository }),
+    version: resolvedVersion,
+    tag: tag(config, resolvedVersion)
+  }
+  const npm = npmPublish(config, resolvedProject)
+  const pypi = pypiPublish(config, resolvedProject)
+  const publish = config.publish === undefined ? undefined : {
+    ...config.publish,
+    ...(config.publish.npm === undefined ? {} : { npm }),
+    ...(config.publish.pypi === undefined ? {} : { pypi })
+  }
+  // Plain JSON, not class instances: this value goes straight to `plan`, whose
+  // decoder refuses anything with a prototype.
+  const plain = toPlainJson({
+    ...rest,
+    project: resolvedProject,
+    ...(publish === undefined ? {} : { publish })
+  })
+  return toPlainJson(decodeCandidate(plain)) as CandidateConfig
+}

package/src/store.ts

@@ -0,0 +1,28 @@
+/**
+ * Supported durable-store library boundary.
+ *
+ * The store service tag remains private. Hosts pass this structural value to
+ * one of the public layer constructors instead of assembling Effect contexts.
+ */
+export {
+  GitHubActionsPreparedStoreProvenance,
+  LocalPreparedStoreProvenance,
+  PreparedCommitHandoffError,
+  PreparedStoreError,
+  PreparedStoreProvenanceError,
+  verifyPreparedStoreProvenance,
+  makeLocalPreparedReleaseStore
+} from "./release/prepared-store.js"
+export type {
+  CommittedPreparedRelease,
+  PreparedBundle,
+  PreparedStoreProvenance,
+  PreparedReleaseStoreShape
+} from "./release/prepared-store.js"
+export {
+  PreparedManifestError,
+  PreparedReleaseV2,
+  decodePreparedRelease,
+  encodePreparedRelease
+} from "./release/prepared.js"
+export type { CompletePreparedReleaseRef } from "./release/prepared-ref.js"

package/templates/README.md

@@ -1,72 +1,55 @@
-# Release Templates
-
-Templates are copyable starting points for new repositories. They use
-placeholder names and may reference artifacts that you still need to build or
-stage before package-manager targets can consume them.
-The checked-in JSON templates are the same policy shape produced by `release
-init`.
-
-After copying a template, stage declared artifacts when the template has
-`artifactRecipes`, then preview the distribution plan:
-
-```sh
-bun run cli plan --config release.config.json --format text
-```
-
-Runnable fixtures live in `examples/`; templates are for authoring your own
-`release.config.json`.
-
-The CLI can preview or write these configs:
-
-```sh
-bun run cli init --template npm-github --package @scope/pkg --repo owner/repo
-bun run cli init --template bun-cli-github --package @scope/pkg --repo owner/repo
-bun run cli init --template npm-github --package @scope/pkg --repo owner/repo --github-actions --write
-bun run cli init --template npm-github --package @scope/pkg --repo owner/repo --github-actions --package-manager npm --write
-```
-
-Available config templates:
-
-- `npm-only`: existing npm package with GitHub Actions trusted publishing.
-- `npm-github`: npm plus GitHub Releases.
-- `bun-cli-github`: binary-first distribution with a Bun executable artifact recipe, npm package publishing, and GitHub Release assets.
-- `multi-target-homebrew`: npm, GitHub Releases, and a Homebrew tap.
-- `multi-target-scoop`: npm, GitHub Releases, and a Scoop bucket.
-
-Templates with `artifactRecipes` require an explicit staging step before target
-planning expects those files to exist. The Bun CLI template derives
-installable variant metadata such as operating system, architecture, Linux libc,
-and Windows `.exe` extension from each compile target:
-
-```sh
-bun run cli stage-artifacts --config release.config.json
-```
-
-The npm templates enable provenance, require `packageExists: true`, and set
-`verifyPackageExists: true` so planning includes a read-only `npm view` check
-before trusted publishing.
-
-GitHub Actions templates are action-first:
-
-- `github-actions/plan-only.yml`
-- `github-actions/plan-and-approved-execute.yml`
-- `github-actions/trusted-publishing.yml`
-
-They use `mannyc2/ts-release-action@v1`; the action source lives in this repo at
-`apps/ts-release-action` until the first action release is cut or mirrored.
-The action currently defaults to `runtime: bundled`.
-
-Generated workflows support Bun, npm, pnpm, and yarn setup presets. Static
-checked-in workflow templates use npm setup by default; setup, install, and
-build commands are workflow scaffolding rather than release config policy.
-
-The trusted-publishing templates do not use `NPM_TOKEN`; configure npm trusted
-publishing and a protected GitHub environment named `release` before approving
-the execute job.
-
-After writing a workflow, run static diagnostics before executing a release:
-
-```sh
-bun run cli doctor --config release.config.json --format text
-bun run cli check-ci --config release.config.json --workflow .github/workflows/release.yml --format markdown
-```
+# Release templates
+
+Templates are complete starting points for authored configuration and GitHub
+Actions. Replace package, repository, artifact, and provider values before use.
+
+The smallest workflow path is automatic: one job invokes the Action once. On
+a fresh run it selects `release`, and the Action durably commits the complete
+bundle before publication. Copy
+`github-actions/release.yml` with `npm-github/release.config.json`. If a host
+gate is required, copy the two-job `github-actions/reviewed-release.yml` and
+its paired `npm-github/reviewed-release.config.json`; its prepare job emits one
+exact hosted reference and only its publish job has the protected environment
+and mutation permissions. Every Action step uploads only its redacted
+`report-ref` as a workflow artifact. Prepared bytes stay in the dedicated
+content-addressed Action store and are not duplicated by a generic artifact
+step.
+
+Both templates expose only `workflow_dispatch` and require `candidate_sha`.
+Dispatch at `refs/heads/main` and pass the exact current commit; a ref or SHA
+mismatch rejects the entire job before checkout. The automatic template also
+accepts optional `prepared_ref`. Leave it empty for the fresh `release` path.
+To recover a prior automatic run, pass its exact `prepared:gha:` value: the
+same job selects `publish`, passes no config, uses `actions: read` to load the
+prior artifact, and never rebuilds. Config and prepared reference are mutually
+exclusive.
+
+The reviewed template retains the same candidate admission on both jobs. If
+its publish job fails after preparation, rerun that failed job in the same
+workflow run so `${{ needs.prepare.outputs.prepared-ref }}` continues to name
+the original bundle. Do not create a new prepare run as recovery.
+
+The trusted-publishing job installs the Node 22.22.2 and npm 11.11.0
+publisher boundary explicitly. The reviewed prepare job has no OIDC or publish
+authority; only its publish job installs that publisher toolchain.
+Trusted configuration must name the invoking workflow and exact ref: the
+automatic pair uses `release.yml`, while the reviewed pair uses
+`reviewed-release.yml`. Keep those filenames when copying the pair, dispatch
+it from `refs/heads/main`, or update the exact config fields deliberately. A
+repository, workflow path/ref, hosted-runner, direct action, or certified-sink
+mismatch fails before OIDC request material is read.
+
+Runnable configuration templates cover npm, GitHub Releases, portable
+binaries, typed Homebrew formulas, and typed Scoop manifests. Templates are schema-checked;
+support still requires a default-layer vertical test and clean-candidate
+evidence, not merely a field appearing in a template.
+
+`npm-github` is the GitHub-hosted trusted-publishing default. `npm-only` is the
+explicit token-mode migration template for non-OIDC hosts; it names a
+credential reference but never contains a credential value.
+
+All public Action templates use the exact intended monorepo coordinate
+`mannyc2/ts-release/apps/ts-release-action@v0.3.0`. Do not switch it to a
+floating branch. Candidate certification must stop unless the immutable tag
+can exist at the exact result commit before a package README naming it is
+published.

package/templates/bun-cli-github/README.md

@@ -1,14 +1,12 @@
-# Bun CLI + GitHub Releases
+# Bun CLI and GitHub Releases
 
-This template publishes an npm package and attaches a Bun-compiled CLI matrix
-to a GitHub Release.
-
-Before planning or running the release, stage the executable artifacts:
+This complete fixture prepares an npm package plus a Bun-compiled CLI matrix
+attached to a GitHub Release. Build outputs are captured in the prepared bundle.
 
 ```sh
-bun run cli stage-artifacts --config release.config.json
+ts-release inspect --config release.config.json
+ts-release release --config release.config.json
 ```
 
-The `id` fields are project-local identifiers. Rename the recipe, outputs,
-entrypoint, and paths to match your CLI; ts-release uses those values as data
-when it builds the release plan.
+Rename the project-local ids, entrypoint, target matrix, and output template
+before releasing.

package/templates/bun-cli-github/release.config.json

@@ -1,89 +1,51 @@
 {
-  "$schema": "https://mannyc2.github.io/ts-release/schema/release-config.schema.json",
-  "identity": {
+  "$schema": "https://raw.githubusercontent.com/mannyc2/ts-release/main/schema/release-config.schema.json",
+  "project": {
     "name": "@scope/pkg",
+    "packageName": "@scope/pkg",
+    "repository": "owner/repo",
     "version": "0.1.0",
-    "commit": "abc123",
     "tag": "v0.1.0"
   },
-  "artifacts": [
-    {
-      "id": "package",
-      "path": ".",
-      "format": "directory",
-      "consumers": ["npm"]
-    }
-  ],
-  "artifactRecipes": [
+  "npmPackage": {
+    "path": "."
+  },
+  "builds": [
     {
-      "_tag": "BunExecutableArtifactRecipe",
+      "builder": "bun",
       "id": "cli",
-      "entrypoint": "src/cli.ts",
-      "outputs": [
-        {
-          "id": "cli-linux-x64",
-          "target": "bun-linux-x64-baseline",
-          "path": "artifacts/pkg-{version}-linux-x64",
-          "consumers": ["github"]
-        },
-        {
-          "id": "cli-linux-arm64",
-          "target": "bun-linux-arm64",
-          "path": "artifacts/pkg-{version}-linux-arm64",
-          "consumers": ["github"]
-        },
-        {
-          "id": "cli-darwin-x64",
-          "target": "bun-darwin-x64",
-          "path": "artifacts/pkg-{version}-darwin-x64",
-          "consumers": ["github"]
-        },
-        {
-          "id": "cli-darwin-arm64",
-          "target": "bun-darwin-arm64",
-          "path": "artifacts/pkg-{version}-darwin-arm64",
-          "consumers": ["github"]
-        },
-        {
-          "id": "cli-windows-x64",
-          "target": "bun-windows-x64-baseline",
-          "path": "artifacts/pkg-{version}-windows-x64.exe",
-          "consumers": ["github"]
-        }
-      ]
+      "entry": "src/cli.ts",
+      "targets": [
+        "linux-x64",
+        "linux-arm64",
+        "darwin-x64",
+        "darwin-arm64"
+      ],
+      "output": "artifacts/pkg-{version}-{targetTriple}{ext}"
     }
   ],
-  "targets": [
-    {
-      "_tag": "NpmRegistryTarget",
-      "id": "npm",
-      "registry": "https://registry.npmjs.org",
-      "packageName": "@scope/pkg",
-      "packagePath": ".",
-      "trustedPublishing": {
-        "provider": "github-actions",
-        "workflow": "release.yml",
-        "packageExists": true,
-        "verifyPackageExists": true
+  "publish": {
+    "npm": {
+      "registry": "https://registry.npmjs.org/",
+      "authentication": {
+        "strategy": "trusted-publishing",
+        "attestation": {
+          "provider": "github-actions",
+          "runner": "github-hosted",
+          "repository": "owner/repo",
+          "workflow": "release.yml",
+          "workflowRef": "refs/heads/main",
+          "allowedAction": "npm-publish-direct"
+        }
       },
       "access": "public",
-      "provenance": true,
-      "dryRunSupport": "native",
-      "mutability": "immutable",
-      "recovery": "publish-new-version"
+      "provenance": "automatic"
     },
-    {
-      "_tag": "GitHubReleaseTarget",
-      "id": "github",
+    "github": {
       "repository": "owner/repo",
-      "tokenEnv": "GH_TOKEN",
+      "tokenEnv": "GITHUB_TOKEN",
       "draft": true,
-      "prerelease": false,
-      "dryRunSupport": "simulated",
-      "mutability": "mutable-release",
-      "recovery": "delete-and-recreate"
+      "prerelease": false
     }
-  ],
-  "strict": true,
-  "evidenceDirectory": ".release/evidence/{version}"
+  }
 }