@mannyc1/ts-release 0.0.7 → 0.3.0

package/src/api/errors.ts

@@ -0,0 +1,36 @@
+import * as Schema from "effect/Schema"
+import { CompletePreparedReleaseRef } from "../release/prepared-ref.js"
+
+export class ReleaseInputError
+  extends Schema.TaggedErrorClass<ReleaseInputError>()("ReleaseInputError", { reason: Schema.String }) {}
+
+/**
+ * Cross-host preparation is deliberately reserved for plan 235. Recognizing
+ * these two tags before strict input decoding gives callers an actionable,
+ * typed refusal without publishing a partial-bundle shape prematurely.
+ */
+export class PreparationModeUnsupported
+  extends Schema.TaggedErrorClass<PreparationModeUnsupported>()("PreparationModeUnsupported", {
+    mode: Schema.Literals(["partition", "merge"]),
+    owner: Schema.Literal("plan-235"),
+    reason: Schema.String
+  }) {}
+
+export class ReleasePreparationError
+  extends Schema.TaggedErrorClass<ReleasePreparationError>()("ReleasePreparationError", {
+    cause: Schema.String
+  }) {}
+
+export class ReleaseAbortedError
+  extends Schema.TaggedErrorClass<ReleaseAbortedError>()("ReleaseAbortedError", {
+    prepared: Schema.optionalKey(CompletePreparedReleaseRef),
+    cause: Schema.String
+  }) {}
+
+/** Product-boundary failure after a truthful total report has been emitted. */
+export class ReleaseIncompleteError
+  extends Schema.TaggedErrorClass<ReleaseIncompleteError>()("ReleaseIncompleteError", {
+    prepared: CompletePreparedReleaseRef,
+    status: Schema.Literals(["blocked", "uncertain"]),
+    reason: Schema.String
+  }) {}

package/src/api/input.ts

@@ -0,0 +1,92 @@
+import * as Schema from "effect/Schema"
+import { existsSync, realpathSync, statSync } from "node:fs"
+import { isAbsolute } from "node:path"
+import { CompletePreparedReleaseRef } from "../release/prepared-ref.js"
+import { AuthoredCorrection } from "../correction/intent.js"
+import { PreparationModeUnsupported, ReleaseInputError } from "./errors.js"
+import type {
+  CorrectInput,
+  InspectInput,
+  ObserveInput,
+  PrepareInput,
+  PublishInput,
+  ReleaseInput
+} from "./types.js"
+
+const prepareInput = Schema.Struct({
+  config: Schema.Unknown,
+  workspace: Schema.String
+})
+
+const inspectConfigInput = Schema.Struct({
+  config: Schema.Unknown,
+  workspace: Schema.String
+})
+
+const preparedInput = Schema.Struct({ prepared: CompletePreparedReleaseRef })
+const inspectInput = Schema.Union([inspectConfigInput, preparedInput])
+const publishInput = preparedInput
+const observeInput = preparedInput
+
+const releaseInput = Schema.Struct({
+  config: Schema.Unknown,
+  workspace: Schema.String,
+  allowEmpty: Schema.optionalKey(Schema.Boolean)
+})
+
+const correctInput = Schema.Struct({
+  prepared: CompletePreparedReleaseRef,
+  correction: AuthoredCorrection
+})
+
+const decode = <S extends Schema.Top & Schema.Decoder<unknown>>(
+  schema: S,
+  value: unknown
+): S["Type"] => {
+  try {
+    return Schema.decodeUnknownSync(schema, { onExcessProperty: "error" })(value) as S["Type"]
+  } catch (cause) {
+    throw new ReleaseInputError({
+      reason: String(cause).split("\n").slice(0, 8).join("\n").slice(0, 500)
+    })
+  }
+}
+
+const rejectReservedPreparationMode = (value: unknown): void => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return
+  const mode = (value as { readonly mode?: unknown }).mode
+  if (mode !== "partition" && mode !== "merge") return
+  throw PreparationModeUnsupported.make({
+    mode,
+    owner: "plan-235",
+    reason: `Preparation mode '${mode}' is reserved and unsupported until plan 235 adds its first certified producer.`
+  })
+}
+
+export const decodePrepareInput = (value: unknown): PrepareInput => {
+  rejectReservedPreparationMode(value)
+  return decode(prepareInput, value)
+}
+
+export const decodeReleaseInput = (value: unknown): ReleaseInput => {
+  rejectReservedPreparationMode(value)
+  return decode(releaseInput, value)
+}
+
+export const decodeObserveInput = (value: unknown): ObserveInput => decode(observeInput, value)
+export const decodePublishInput = (value: unknown): PublishInput => decode(publishInput, value)
+export const decodeCorrectInput = (value: unknown): CorrectInput => decode(correctInput, value)
+export const decodeInspectInput = (value: unknown): InspectInput => decode(inspectInput, value)
+
+export const absoluteDirectory = (value: string, field: string): string => {
+  if (!isAbsolute(value) || !existsSync(value)) {
+    throw new ReleaseInputError({ reason: `${field} must be an existing absolute directory.` })
+  }
+  const canonical = realpathSync(value)
+  if (!statSync(canonical).isDirectory()) {
+    throw new ReleaseInputError({ reason: `${field} must be a directory.` })
+  }
+  return canonical
+}
+
+export const workspaceRoot = (value: string): string => absoluteDirectory(value, "workspace")

package/src/api/runtime.ts

@@ -0,0 +1,14 @@
+import * as Context from "effect/Context"
+import * as Schema from "effect/Schema"
+import type { SourceObserverShape } from "../release/context.js"
+import type { RunCommand } from "../drivers/process.js"
+
+export class ReleaseRuntimeError
+  extends Schema.TaggedErrorClass<ReleaseRuntimeError>()("ReleaseRuntimeError", { reason: Schema.String }) {}
+
+export interface ReleaseRuntimeShape {
+  readonly source: SourceObserverShape
+  readonly run: RunCommand
+}
+
+export class ReleaseRuntime extends Context.Service<ReleaseRuntime, ReleaseRuntimeShape>()("ReleaseRuntime") {}

package/src/api/types.ts

@@ -0,0 +1,103 @@
+import type * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+import type { CredentialProvider } from "../publication/authority.js"
+import type { AuthoredCorrection } from "../correction/intent.js"
+import type { ObservationReport, ReleaseReport as ReleaseReportType } from "../publication/report.js"
+import { SafeReason } from "../publication/report.js"
+import type {
+  AuthorizedMutationHttp,
+  HttpAuthorizer
+} from "../publication/http.js"
+import type {
+  CertifiedPublisherSpawn,
+  NpmUserConfigResource
+} from "../publication/publisher.js"
+import type { ReleaseInspection, PreparedReleaseInspection } from "../release/inspect.js"
+import {
+  CompletePreparedReleaseRef,
+  type CompletePreparedReleaseRef as CompletePreparedReleaseRefValue
+} from "../release/prepared-ref.js"
+import type { PreparedReleaseStore } from "../release/prepared-store.js"
+import type { ReleaseRuntime } from "./runtime.js"
+import type { CustomProviderAdapter } from "../extensions/provider-adapter.js"
+
+export type ReleaseApiServices =
+  | ReleaseRuntime
+  | PreparedReleaseStore
+  | CredentialProvider
+  | HttpAuthorizer
+  | AuthorizedMutationHttp
+  | NpmUserConfigResource
+  | CertifiedPublisherSpawn
+
+export type ReleaseApiLayer = Layer.Layer<ReleaseApiServices>
+export type InspectOutput = ReleaseInspection | PreparedReleaseInspection
+
+/** Custom application composition only; stock CLI/Action pass no adapters. */
+export interface ReleaseApiOptions {
+  readonly providerAdapters?: ReadonlyArray<CustomProviderAdapter>
+}
+
+export interface PrepareInput {
+  readonly config: unknown
+  readonly workspace: string
+}
+
+export type InspectInput =
+  | {
+    readonly config: unknown
+    readonly workspace: string
+    readonly prepared?: never
+  }
+  | {
+    readonly prepared: CompletePreparedReleaseRefValue
+    readonly config?: never
+    readonly workspace?: never
+  }
+
+export interface ObserveInput {
+  readonly prepared: CompletePreparedReleaseRefValue
+}
+
+export interface PublishInput {
+  readonly prepared: CompletePreparedReleaseRefValue
+}
+
+export interface ReleaseInput extends PrepareInput {
+  /** Diagnostic-only opt-in for exercising an intentionally empty graph. */
+  readonly allowEmpty?: boolean
+}
+
+export interface CorrectInput {
+  readonly prepared: CompletePreparedReleaseRefValue
+  /** Human-authored correction; destination facts are derived from prepared. */
+  readonly correction: AuthoredCorrection
+}
+
+/**
+ * Plan 224 keeps correction on the durable-reference boundary while plan 229
+ * owns the first executable authored-correction grammar.
+ */
+export class CorrectionReport extends Schema.Class<CorrectionReport>("CorrectionReport")({
+    prepared: CompletePreparedReleaseRef,
+    status: Schema.Literals(["unsupported", "complete", "blocked", "uncertain"]),
+    provider: Schema.Literals(["npm", "github", "catalog-git"]),
+    reason: SafeReason,
+    proposal: Schema.String,
+    report: Schema.optionalKey(Schema.Unknown)
+  }) {}
+
+export interface ReleaseResult {
+  readonly prepared: CompletePreparedReleaseRefValue
+  readonly report: ReleaseReportType
+}
+
+export interface ReleaseApi {
+  readonly inspect: (input: InspectInput) => Promise<InspectOutput>
+  readonly prepare: (input: PrepareInput) => Promise<CompletePreparedReleaseRefValue>
+  readonly observe: (input: ObserveInput) => Promise<ObservationReport>
+  readonly publish: (input: PublishInput) => Promise<ReleaseReportType>
+  readonly release: (input: ReleaseInput) => Promise<ReleaseResult>
+  readonly correct: (input: CorrectInput) => Promise<CorrectionReport>
+  readonly dispose: () => Promise<void>
+}

package/src/capabilities/bun-targets.ts

@@ -0,0 +1,2 @@
+/** Compatibility projection; the vocabulary is model-owned for strict decode. */
+export * from "../model/bun-targets.js"

package/src/capabilities/field-ownership.ts

@@ -0,0 +1,60 @@
+import type {
+  CapabilityId,
+  CapabilityModule,
+  FieldEffect
+} from "./module.js"
+
+export interface ConfigFieldOwnership {
+  readonly path: string
+  readonly owner: CapabilityId | "authoring"
+  readonly effect: FieldEffect
+}
+
+export interface FieldOwnershipReport {
+  readonly rows: ReadonlyArray<ConfigFieldOwnership>
+  readonly failures: ReadonlyArray<string>
+}
+
+/**
+ * Exact join between the generated authored schema paths and executable
+ * modules. Prefix matches are intentionally forbidden: a broad `publish`
+ * entry cannot accidentally claim npm authentication fields.
+ */
+export const validateFieldOwnership = (
+  schemaPaths: ReadonlyArray<string>,
+  modules: ReadonlyArray<CapabilityModule>
+): FieldOwnershipReport => {
+  const failures: Array<string> = []
+  const assignments = new Map<string, Array<ConfigFieldOwnership>>()
+
+  for (const module of modules) {
+    for (const field of module.fields) {
+      const rows = assignments.get(field.path) ?? []
+      rows.push({ path: field.path, owner: module.id, effect: field.effect })
+      assignments.set(field.path, rows)
+    }
+  }
+  assignments.set("$schema", [{
+    path: "$schema",
+    owner: "authoring",
+    effect: "authoring-only"
+  }])
+
+  const schema = new Set(schemaPaths)
+  for (const path of schemaPaths) {
+    const owners = assignments.get(path) ?? []
+    if (owners.length === 0) failures.push(`public config field has no canonical owner: ${path}`)
+    if (owners.length > 1) {
+      failures.push(`public config field has multiple canonical owners: ${path} (${owners.map((row) => row.owner).join(", ")})`)
+    }
+  }
+  for (const path of assignments.keys()) {
+    if (!schema.has(path)) failures.push(`field ownership names no public config field: ${path}`)
+  }
+
+  const rows = schemaPaths.flatMap((path) => {
+    const assignment = assignments.get(path)
+    return assignment?.length === 1 ? assignment : []
+  })
+  return { rows, failures }
+}

package/src/capabilities/module.ts

@@ -0,0 +1,158 @@
+import type { CandidateConfig } from "../recipes/config.js"
+import type { ReleaseSubject } from "../publication/coordinator.js"
+import type {
+  AuthorizedMutationHttpShape,
+  HttpAuthorizerShape
+} from "../publication/http.js"
+import type {
+  CertifiedPublisherSpawnShape,
+  NpmUserConfigResourceShape
+} from "../publication/publisher.js"
+import type { PublicationProfileRegistration } from "../publication/recovery.js"
+import type { PublicationClaimStoreShape } from "../publication/claim.js"
+import type {
+  PreparedGitHubPublication,
+  PreparedCatalogPublication,
+  PreparedNpmPublication,
+  PreparedPyPiPublication
+} from "../release/prepared.js"
+import type { PreparedBundle } from "../release/prepared-store.js"
+import type { VerifiedReleaseContext } from "../release/context.js"
+import type {
+  CapabilityContribution,
+  OutputDeclaration
+} from "../release/graph.js"
+import type { ObservedFacts } from "../resolve/facts.js"
+
+/** The deliberately small, installed product algebra. Inclusion means support. */
+export type CapabilityId =
+  | "release.identity"
+  | "prepare.source"
+  | "prepare.package"
+  | "render.homebrew"
+  | "render.scoop"
+  | "publish.npm"
+  | "publish.pypi"
+  | "publish.catalog-git"
+  | "publish.github"
+
+export type FieldEffect =
+  | "resolved-intent"
+  | "graph"
+  | "prepared-bytes"
+  | "runtime-requirement"
+  | "recovery-policy"
+  | "authoring-only"
+
+export interface OwnedConfigField {
+  /** Exact path emitted by scripts/lib/config-fields.ts; prefixes never count. */
+  readonly path: string
+  readonly effect: FieldEffect
+}
+
+export interface CapabilityCertification {
+  /** Evidence references do not install a capability. */
+  readonly tests: ReadonlyArray<string>
+  readonly boundary: "root-api" | "provider-protocol"
+}
+
+export interface CapabilityRequirements {
+  readonly executionHosts: ReadonlyArray<"linux" | "darwin">
+  readonly nativeTools: ReadonlyArray<string>
+  readonly artifactTargets: ReadonlyArray<string>
+  readonly credentialStrategies: ReadonlyArray<string>
+}
+
+export interface CompilationSnapshot {
+  readonly config: CandidateConfig
+  readonly context: VerifiedReleaseContext
+  /** Immutable outputs from the preceding explicit compilation phase. */
+  readonly availableArtifacts: ReadonlyArray<OutputDeclaration>
+}
+
+interface CapabilityCommon {
+  readonly id: CapabilityId
+  readonly fields: ReadonlyArray<OwnedConfigField>
+  readonly requirements: CapabilityRequirements
+  readonly certification: CapabilityCertification
+}
+
+/** Canonical authored identity and observed facts have one resolver. */
+export interface ResolutionCapability extends CapabilityCommon {
+  readonly _tag: "ResolutionCapability"
+  readonly resolve: (authored: unknown, facts: ObservedFacts) => CandidateConfig
+}
+
+/** Preparation has no provider, credential, or subject surface. */
+export interface PreparationCapability extends CapabilityCommon {
+  readonly _tag: "PreparationCapability"
+  readonly phase: "source" | "package" | "render"
+  readonly contribute: (input: CompilationSnapshot) => CapabilityContribution
+}
+
+/** Opaque provider services supplied only by the default or custom host layer. */
+export interface PublicationSubjectServices {
+  readonly http: HttpAuthorizerShape
+  readonly mutationHttp: AuthorizedMutationHttpShape
+  readonly userConfigs: NpmUserConfigResourceShape
+  readonly publisher: CertifiedPublisherSpawnShape
+  readonly claims: PublicationClaimStoreShape
+}
+
+interface PublicationCapabilityCommon extends CapabilityCommon {
+  readonly _tag: "PublicationCapability"
+  /** The exact registration also consumed by recovery documentation. */
+  readonly profile: PublicationProfileRegistration
+  readonly contribute: (input: CompilationSnapshot) => CapabilityContribution
+}
+
+export interface NpmPublicationCapability extends PublicationCapabilityCommon {
+  readonly id: "publish.npm"
+  readonly preparedTag: "PreparedNpmPublication"
+  readonly subjects: (
+    bundle: PreparedBundle,
+    publication: PreparedNpmPublication,
+    services: PublicationSubjectServices
+  ) => readonly [ReleaseSubject]
+}
+
+export interface GitHubPublicationCapability extends PublicationCapabilityCommon {
+  readonly id: "publish.github"
+  readonly preparedTag: "PreparedGitHubPublication"
+  readonly subjects: (
+    bundle: PreparedBundle,
+    publication: PreparedGitHubPublication,
+    services: PublicationSubjectServices
+  ) => readonly [ReleaseSubject]
+}
+
+export interface PyPiPublicationCapability extends PublicationCapabilityCommon {
+  readonly id: "publish.pypi"
+  readonly preparedTag: "PreparedPyPiPublication"
+  readonly subjects: (
+    bundle: PreparedBundle,
+    publication: PreparedPyPiPublication,
+    services: PublicationSubjectServices
+  ) => ReadonlyArray<ReleaseSubject>
+}
+
+export interface CatalogPublicationCapability extends PublicationCapabilityCommon {
+  readonly id: "publish.catalog-git"
+  readonly preparedTag: "PreparedCatalogPublication"
+  readonly subjects: (
+    bundle: PreparedBundle,
+    publication: PreparedCatalogPublication,
+    services: PublicationSubjectServices
+  ) => readonly [ReleaseSubject]
+}
+
+export type PublicationCapability =
+  | NpmPublicationCapability
+  | PyPiPublicationCapability
+  | CatalogPublicationCapability
+  | GitHubPublicationCapability
+
+export type CapabilityModule =
+  | ResolutionCapability
+  | PreparationCapability
+  | PublicationCapability