@postman/sdk-config 0.0.3 → 0.1.0

package/README.md

@@ -1,10 +1,11 @@
 # @postman/sdk-config
 
-Shared, runtime-validated configuration contracts for Postman's SDK generation pipeline.
+Shared, runtime-validated public and internal configuration contracts for Postman's SDK generation
+pipeline.
 
-This package is the source of truth for `SdkConfigIr`. It is intended for sdk-gen-core,
-sdk-gen-api, Postman and Fern CLIs, and translators that normalize producer-specific configuration
-before generation.
+This package is the source of truth for the customer-facing `SdkConfig` and internal `SdkConfigIr`.
+It is intended for sdk-gen-core, sdk-gen-api, Postman and Fern CLIs, and translators that normalize
+producer-specific configuration before generation.
 
 ## Install
 
@@ -16,7 +17,15 @@ npm install @postman/sdk-config
 
 ## Use
 
-Prefer the versioned entry point at transport and persistence boundaries:
+Use `SdkConfigV1` for customer-authored, potentially multi-target generation configuration:
+
+```ts
+import { parseSdkConfigV1, type SdkConfigV1 } from '@postman/sdk-config/sdk-config/v1';
+
+const sdkConfig: SdkConfigV1 = parseSdkConfigV1(untrustedInput);
+```
+
+Use `SdkConfigIrV1` only for the normalized, single-target internal generator contract:
 
 ```ts
 import { parseSdkConfigIrV1, type SdkConfigIrV1 } from '@postman/sdk-config/sdk-config-ir/v1';
@@ -24,8 +33,13 @@ import { parseSdkConfigIrV1, type SdkConfigIrV1 } from '@postman/sdk-config/sdk-
 const sdkConfigIr: SdkConfigIrV1 = parseSdkConfigIrV1(untrustedInput);
 ```
 
-The package also exposes `@postman/sdk-config` and `@postman/sdk-config/sdk-config-ir` as convenient
-current-version entry points. Persisted payloads must still include `schemaVersion`.
+The package also exposes `@postman/sdk-config`, `@postman/sdk-config/sdk-config`, and
+`@postman/sdk-config/sdk-config-ir` as convenient current-version entry points. Persisted payloads
+must still include the appropriate `schemaVersion`.
+
+`SdkConfigV1` does not accept source selection, server-owned fields, `SdkConfigIrV1`, or legacy
+Postman `BuildParameters`. See the [SDK Config v1 reference](src/sdk-config/v1/README.md) for the
+boundaries and target precedence rules.
 
 Both ESM `import` and CommonJS `require` consumers are supported.
 
@@ -33,11 +47,17 @@ Both ESM `import` and CommonJS `require` consumers are supported.
 
 ```text
 src/
+  sdk-config-domain/
+    v1/                 # Portable field schemas shared by public config and internal IR
+  sdk-config/
+    v1/                 # Customer-facing multi-target schema and contract reference
   sdk-config-ir/
     v1/                 # Versioned schema, inferred types, and contract reference
 tests/
   fixtures/
+    sdk-config/v1/      # Canonical public configuration payloads
     sdk-config-ir/v1/   # Canonical portable payloads
+  sdk-config/v1/        # Public contract and export tests
   sdk-config-ir/v1/     # Contract behavior tests
 docs/
   migration.md          # sdk-gen-core adoption sequence
@@ -61,7 +81,8 @@ npm pack --dry-run
   publish it.
 - Additive v1 fields require a package minor version and a consumer-first rollout because v1 uses
   strict runtime objects: an older consumer rejects fields it does not know.
-- Breaking wire changes get a new schema directory and discriminator such as `sdk-config-ir/v2`.
+- Breaking wire changes get a new schema directory and discriminator such as `sdk-config/v2` or
+  `sdk-config-ir/v2`.
 - Keep the previous version exported while consumers migrate.
 
 ### Manual release process
@@ -120,20 +141,24 @@ git pull --ff-only origin main
 node -p "require('./package.json').version"
 ```
 
-Create a signed, annotated tag on the checked-out `main` commit, verify it locally, and push it:
+Create the signed tag and dispatch the **Package Release** workflow with the tag as its explicit
+input:
 
 ```sh
-git tag -s v1.1.0 -m "Release v1.1.0"
-git tag -v v1.1.0
-git push origin v1.1.0
+npm run release -- v1.1.0
 ```
 
-Pushing a tag matching `v*.*.*` automatically triggers the **Package Release** workflow defined in
-`.github/workflows/npm-publish.yml`. In GitHub, open **Actions** → **Package Release** and confirm
-the tag-triggered run succeeds.
+The release script requires a clean, up-to-date `main`, verifies that the package version matches
+the tag and that the commit is already contained in `main` and `develop`, creates and verifies a
+signed, annotated tag, pushes it, and dispatches `.github/workflows/npm-publish.yml` with
+`tag=v1.1.0`. The workflow independently rechecks `main` ancestry before calling the shared
+publisher, which verifies `develop` ancestry and the tag signature. Explicit dispatch avoids
+duplicate publish runs and keeps retries tied to the immutable tag. In GitHub, open **Actions** →
+**Package Release** and confirm the dispatched run succeeds.
 
 If publishing fails after the tag has been created, do not delete, move, or recreate the tag. After
-the underlying problem is fixed, open **Actions** → **Package Release** → **Run workflow** and enter
-the existing tag, such as `v1.1.0`, to retry it.
+the underlying problem is fixed, run the same command again. The script verifies and reuses the
+existing tag before dispatching another run. You can also use **Actions** → **Package Release** →
+**Run workflow** and enter the existing tag, such as `v1.1.0`.
 
 See the [SDK Config IR v1 reference](src/sdk-config-ir/v1/README.md) for the complete contract.