putitoutthere 0.1.43 → 0.1.44

package/README.md

@@ -1,155 +1,429 @@
 # Put It Out There
 
-Polyglot release orchestrator for single-maintainer, LLM-authored projects
-that publish to crates.io, PyPI, and npm from one monorepo. One config file,
-one CLI, one trailer-driven signal — no per-package release plumbing.
+A reusable GitHub Actions workflow that publishes packages to crates.io, PyPI,
+and npm from one repo. OIDC-first, cascade-aware, polyglot. The consumer
+surface is one config file plus ~10 lines of YAML calling
+`uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v1`.
 
-**[Documentation](https://thekevinscott.github.io/put-it-out-there/)**
+## Quickstart
 
-## Install
+### 1. Drop in `.github/workflows/release.yml`
 
-```sh
-npx putitoutthere init
+```yaml
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    uses: thekevinscott/putitoutthere/.github/workflows/release.yml@v1
+    permissions:
+      contents: write
+      id-token: write
 ```
 
-This scaffolds a `putitoutthere.toml`, a `release.yml` workflow, and an
-`AGENTS.md` file explaining the trailer convention to future
-contributors.
+Pinned action versions, `plan → build → publish` orchestration, and GitHub
+Release creation all live inside the reusable workflow.
 
-For one-off runs without scaffolding:
+Optional inputs — `with:` block at the call site:
 
-```sh
-pnpm add -D putitoutthere
-pnpm putitoutthere plan
-```
+| Input            | Default      | Use when                                                                 |
+|------------------|--------------|--------------------------------------------------------------------------|
+| `environment`    | `release`    | Your GitHub deployment environment is named differently.                 |
+| `node_version`   | `24`         | You need a specific Node version for `kind = "npm"` build steps.         |
+| `python_version` | `3.12`       | You need a specific Python version for `kind = "pypi"` build steps.      |
 
-## Minimum config
+### 2. Drop in `putitoutthere.toml`
 
 ```toml
-# putitoutthere.toml
 [putitoutthere]
 version = 1
 
 [[package]]
 name  = "my-lib"
-kind  = "npm"        # or "pypi" | "crates"
+kind  = "pypi"        # or "npm" | "crates"
 path  = "."
-paths = ["src/**", "package.json"]
+paths = ["src/**", "pyproject.toml"]
+build = "hatch"       # required for kind = "pypi"
+tag_format = "v{version}"   # single-package repos often want this
 ```
 
-`paths` are the globs that trigger a release for this package. Any commit
-touching a matching file makes the package a candidate.
+`paths` are the globs that trigger a release. Any commit touching a matching
+file makes the package a candidate.
+
+More config patterns are in [Configuration](#configuration) below.
+
+### 3. Register trusted publishers
 
-## Releasing
+Each registry needs a one-time external setup so OIDC publishes work. See
+[Trusted publishers](#trusted-publishers) below — three short lists, one per
+registry.
 
-Add a trailer to the commit that should ship:
+### 4. Push a release
+
+Merge to `main`. Default behavior: any package whose `paths` matched changed
+files cascades and ships at `patch`. To bump `minor` or `major`:
 
 ```
 fix: handle empty token lists
 
-release: patch
+release: minor
+```
+
+…in the merge commit body. See [Trailer](#trailer) below.
+
+## Configuration
+
+`putitoutthere.toml` lives at the repo root.
+
+### `[putitoutthere]`
+
+```toml
+[putitoutthere]
+version = 1   # required; only 1 is valid today
 ```
 
-Valid bumps: `patch`, `minor`, `major`, `skip`. On push to `main`, the
-`release.yml` workflow runs `putitoutthere plan` against the trailer +
-changed paths, then `putitoutthere publish` per matching package. Tags are
-`{name}-v{version}`.
+### `[[package]]` (one per releasable unit)
+
+| Field           | Type     | Required | Notes                                             |
+|-----------------|----------|----------|---------------------------------------------------|
+| `name`          | string   | yes      | Unique across the config.                         |
+| `kind`          | enum     | yes      | `crates` \| `pypi` \| `npm`.                      |
+| `path`          | string   | yes      | Package working dir (`Cargo.toml` / `pyproject.toml` / `package.json` location). |
+| `paths`         | string[] | yes      | Globs that cascade this package.                  |
+| `depends_on`    | string[] | no       | Package names this one cascades on top of.        |
+| `first_version` | string   | no       | Default `0.1.0`.                                  |
+| `tag_format`    | string   | no       | Template for the git tag. Default `"{name}-v{version}"`. Single-package repos often want `"v{version}"`. |
+| `trust_policy`  | table    | no       | Declared OIDC trust-policy expectations. See [Trusted publishers](#trusted-publishers). |
+
+### `kind = "crates"`
+
+| Field                 | Type     | Notes                                                      |
+|-----------------------|----------|------------------------------------------------------------|
+| `crate`               | string   | Override `name` → crates.io name.                          |
+| `features`            | string[] | Pass through to `cargo publish --features`.                |
+| `no_default_features` | bool     | Pass `--no-default-features` to `cargo publish` when true. |
+
+### `kind = "pypi"`
+
+| Field        | Type                   | Notes                                              |
+|--------------|------------------------|----------------------------------------------------|
+| `pypi`       | string                 | Override `name` → PyPI registered name.            |
+| `build`      | enum                   | `maturin` \| `setuptools` \| `hatch`. Required.    |
+| `targets`    | (string \| object)[]   | Required when `build = "maturin"`. Triples or `{ triple, runner }` objects. |
+| `bundle_cli` | table                  | Opt-in: cross-compile a Rust CLI per target and stage it into each wheel. Only valid with `build = "maturin"`. See [Recipes → Rust CLI inside a PyPI wheel](#rust-cli-inside-a-pypi-wheel). |
+
+### `kind = "npm"`
 
-The trailer is optional. By default, any package whose `paths` matched
-changed files cascades at `patch`. Use `release: minor` / `release: major`
-to override the bump, or `release: skip` to suppress the release for that
-commit.
+| Field     | Type                   | Notes                                                |
+|-----------|------------------------|------------------------------------------------------|
+| `npm`     | string                 | Override `name` → npm name (for scoped packages).    |
+| `access`  | enum                   | `public` \| `restricted`. Default `public`.          |
+| `tag`     | string                 | dist-tag. Default `latest`.                          |
+| `build`   | enum                   | `napi` \| `bundled-cli`. Omitted = vanilla. See [Recipes → Bundled-CLI npm family](#bundled-cli-npm-family). |
+| `targets` | (string \| object)[]   | Required when `build ∈ {napi, bundled-cli}`.         |
 
-## Worked example: polyglot
+### Example: polyglot Rust library
 
-The reference fixture at [`test/fixtures/polyglot-everything/`](./test/fixtures/polyglot-everything/)
-mirrors a real polyglot shape: a Rust crate, a PyO3 Python wheel wrapping it,
-and an npm CLI bundling the Rust binary. One `putitoutthere.toml` declares
-all three:
+One Rust crate feeds three artifacts:
 
 ```toml
 [[package]]
-name = "my-tool-rust"
+name = "my-rust"
 kind = "crates"
-path = "packages/rust"
-paths = ["packages/rust/**"]
+path = "crates/my-rust"
+paths = ["crates/my-rust/**"]
 
 [[package]]
-name = "my-tool-python"
-kind = "pypi"
-path = "packages/python"
-paths = ["packages/python/**"]
-build = "maturin"
-depends_on = ["my-tool-rust"]
+name       = "my-py"
+kind       = "pypi"
+path       = "py/my-py"
+paths      = ["py/my-py/**"]
+build      = "maturin"
+targets    = ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin"]
+depends_on = ["my-rust"]
 
 [[package]]
-name = "my-tool-cli"
-kind = "npm"
-path = "packages/ts"
-paths = ["packages/ts/**"]
-build = "bundled-cli"
-depends_on = ["my-tool-rust"]
+name       = "my-cli"
+kind       = "npm"
+path       = "packages/ts"
+paths      = ["packages/ts/**"]
+build      = "bundled-cli"
+targets    = ["x86_64-unknown-linux-gnu", "aarch64-apple-darwin"]
+depends_on = ["my-rust"]
 ```
 
-A change to `packages/rust/` cascades: the crate ships, and the Python + npm
-wrappers ship on top (bumped to match). A change to only the TS shim ships
-just the npm package.
+A change to `crates/my-rust/` cascades: the crate ships, then the Python
+wheels and npm family ship on top, version-bumped to match.
+
+### Example: multi-package workspace
+
+```toml
+[[package]]
+name  = "@my/core"
+kind  = "npm"
+path  = "packages/core"
+paths = ["packages/core/**"]
+
+[[package]]
+name       = "@my/parser"
+kind       = "npm"
+path       = "packages/parser"
+paths      = ["packages/parser/**"]
+depends_on = ["@my/core"]
+```
 
-## Library shapes
+## Trailer
 
-End-to-end walkthroughs — config + `release.yml` + prerequisites + gotchas —
-for the common shapes. Pick the one that matches your repo:
+The trailer is **optional**. Default behavior is `patch` whenever a package's
+`paths` matched changed files.
 
-**Single-package**
+Grammar:
 
-- [Python library](./docs/guide/shapes/python-library.md) — one `pyproject.toml` to PyPI
-- [npm library](./docs/guide/shapes/npm-library.md) — one `package.json` to npm
-- [Rust crate](./docs/guide/shapes/rust-crate.md) — one `Cargo.toml` to crates.io
+```
+release: <bump> [pkg1, pkg2, ...]
+```
 
-**Multi-package workspaces**
+`<bump>` is `patch` | `minor` | `major` | `skip`. The optional package list
+scopes a non-default bump to specific packages.
 
-- [Rust workspace](./docs/guide/shapes/rust-workspace.md) — multiple crates with `depends_on` cascade
-- [npm workspace](./docs/guide/shapes/npm-workspace.md) — multiple npm packages, shared dependency graph
+| Trailer                  | Effect                                                                 |
+|--------------------------|------------------------------------------------------------------------|
+| *(none)*                 | Cascaded packages bump `patch`.                                        |
+| `release: minor`         | Cascaded packages bump `minor`.                                        |
+| `release: major`         | Cascaded packages bump `major`.                                        |
+| `release: skip`          | No release this commit. Cascade ignored.                               |
+| `release: minor [a, b]`  | `a` and `b` bump `minor`; other cascaded packages stay at `patch`.     |
 
-**Rust core, multi-registry**
+The trailer matches anywhere in the commit body. If multiple `release:` lines
+are present, the **last** one wins.
 
-- [Rust + PyO3 wheels](./docs/guide/shapes/rust-pyo3.md) — crate + PyPI (no napi)
-- [Rust + napi npm](./docs/guide/shapes/rust-napi.md) — crate + npm family (no PyPI)
-- [Polyglot Rust library](./docs/guide/shapes/polyglot-rust.md) — all three registries from one core
-- [Python wheels with C extensions](./docs/guide/shapes/python-cibuildwheel.md) — `cibuildwheel` for the `pillow`/`lxml`/`numpy` shape
+## Cascade
 
-**Distribution patterns**
+A package cascades into the release plan when a commit changes any file
+matching one of its `paths` globs since its last tag. If another package
+declares `depends_on = ["this-package"]`, that package also cascades.
+Transitively, DFS-ordered, with cycle detection at config-load.
 
-- [Bundled-CLI npm family](./docs/guide/shapes/bundled-cli.md) — compiled CLI shipped as an npm per-platform family
-- [Dual-family npm (CLI + napi)](./docs/guide/shapes/dual-family-npm.md) — one library with both an addon and a binary
+Inside a single release, packages publish in topological order of their
+`depends_on` graph. If your Python wrapper depends on a Rust crate, the
+crate publishes first.
 
-Full index at [`docs/guide/shapes/`](./docs/guide/shapes/).
+Each handler's first move on publish is `isPublished` — check the registry
+for the target version. Already there → skip cleanly. Lets you re-run failed
+releases without fighting registry-immutable-publish semantics.
 
 ## Trusted publishers
 
-Preferred over long-lived tokens. One-time setup per registry:
+OIDC trusted publishers — the only auth path supported by the reusable
+workflow. Long-lived registry tokens are not reachable through the workflow.
+
+The fields each registry needs are the same: repository owner/name, workflow
+filename (`release.yml`), and optionally a GitHub environment name.
+
+### crates.io
+
+1. Publish your crate once through the normal `cargo` flow so the crate
+   exists. (Trusted publishing needs a crate owner record.)
+2. Go to `https://crates.io/crates/<crate>/settings` → **Trusted Publishing**
+   → **Add**.
+3. Fill in: repository owner, repository name, workflow filename
+   (`release.yml`), environment (optional).
+
+### PyPI
+
+1. Go to `https://pypi.org/manage/project/<name>/settings/publishing/` (or
+   **Publishing** on the project page).
+2. Add a **GitHub** trusted publisher: owner, repo, workflow filename,
+   environment (optional).
+3. Brand-new project? Use a [pending publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
+   to skip the bootstrap token.
+
+### npm
+
+1. Publish at least one version of your package with a classic
+   `NODE_AUTH_TOKEN` so the package exists on the registry. (npm's trusted
+   publisher requires an existing package.)
+2. Go to `https://www.npmjs.com/package/<name>/access` → **Require trusted
+   publisher**.
+3. Fill in: repository, workflow filename, environment (optional).
+4. Delete the bootstrap token.
+
+### Catching trust-policy drift before release
+
+Renaming `release.yml` to anything else, or renaming the environment, breaks
+publish with an opaque HTTP 400 from the registry. To catch the rename
+before it ships, declare the expected values in `putitoutthere.toml`:
 
-- **npm:** [npm trusted publishing](https://docs.npmjs.com/trusted-publishers) — attach the package to this repo + workflow. `--provenance` is added automatically.
-- **PyPI:** [pending publisher](https://docs.pypi.org/trusted-publishers/) — register the project name pointing at this repo's `release.yml`.
-- **crates.io:** [OIDC via `rust-lang/crates-io-auth-action@v1`](https://github.com/rust-lang/crates-io-auth-action) — the crate needs one manual bootstrap publish first.
+```toml
+[[package]]
+name = "my-crate"
+kind = "crates"
+path = "crates/my-crate"
+paths = ["crates/my-crate/**"]
+
+[package.trust_policy]
+workflow    = "release.yml"      # required; bare filename
+environment = "release"          # optional
+repository  = "my-org/my-crate"  # optional
+```
+
+The engine diffs the declaration against the local workflow file and (in CI)
+against `GITHUB_WORKFLOW_REF` before any registry call. For `kind = "crates"`,
+a registry cross-check runs when `CRATES_IO_DOCTOR_TOKEN` is set — calls the
+trusted-publishing read API and fails on mismatch. PyPI and npm don't expose
+read APIs for trust policy, so the declared diff is the full gate there.
+
+## Recipes
+
+### Bundled-CLI npm family
+
+Ship a compiled CLI as an npm per-platform family — `npm install -g my-cli`
+gives users a working binary on PATH. The `esbuild` / `biome` distribution
+shape.
+
+Config:
+
+```toml
+[[package]]
+name  = "my-cli"
+kind  = "npm"
+npm   = "my-cli"
+build = "bundled-cli"
+path  = "packages/ts-cli"
+paths = ["packages/ts-cli/**", "crates/my-cli/**"]
+targets = [
+  "x86_64-unknown-linux-gnu",
+  "aarch64-unknown-linux-gnu",
+  "x86_64-apple-darwin",
+  "aarch64-apple-darwin",
+  "x86_64-pc-windows-msvc",
+]
+```
+
+The engine publishes a per-platform sub-package per target
+(`my-cli-<triple>`) plus a top-level whose `optionalDependencies` pin them
+at the published version. npm's resolver installs exactly one sub-package
+at consumer install time.
+
+You author the launcher script that picks the right per-platform binary
+once. `package.json`:
+
+```json
+{
+  "name": "my-cli",
+  "bin": { "my-cli": "bin/my-cli.js" }
+}
+```
+
+`bin/my-cli.js`:
+
+```js
+#!/usr/bin/env node
+const { spawnSync } = require('node:child_process');
+const { platform, arch } = process;
+
+const triples = {
+  'linux-x64':    'x86_64-unknown-linux-gnu',
+  'linux-arm64':  'aarch64-unknown-linux-gnu',
+  'darwin-x64':   'x86_64-apple-darwin',
+  'darwin-arm64': 'aarch64-apple-darwin',
+  'win32-x64':    'x86_64-pc-windows-msvc',
+};
+
+const triple = triples[`${platform}-${arch}`];
+if (!triple) {
+  console.error(`my-cli: unsupported platform ${platform}-${arch}`);
+  process.exit(1);
+}
+
+const pkg = `my-cli-${triple}`;
+const binary = require.resolve(`${pkg}/bin/my-cli${platform === 'win32' ? '.exe' : ''}`);
+const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+process.exit(result.status ?? 1);
+```
+
+Each per-platform sub-package needs its own npm trusted-publisher
+registration (a policy on `my-cli` does not cover
+`my-cli-x86_64-unknown-linux-gnu`).
+
+### Rust CLI inside a PyPI wheel
+
+`pip install my-lib` on any platform gets a working CLI on `PATH` without
+the user installing a Rust toolchain. The `ruff` / `uv` / `pydantic-core`
+pattern.
+
+Config:
+
+```toml
+[[package]]
+name  = "my-py"
+kind  = "pypi"
+build = "maturin"
+path  = "packages/python"
+paths = ["packages/python/**", "crates/my-rust/**"]
+targets = [
+  "x86_64-unknown-linux-gnu",
+  "aarch64-unknown-linux-gnu",
+  "x86_64-apple-darwin",
+  "aarch64-apple-darwin",
+  "x86_64-pc-windows-msvc",
+]
+depends_on = ["my-rust"]
+
+[package.bundle_cli]
+bin        = "my-cli"
+stage_to   = "src/my_py/_binary"
+crate_path = "crates/my-rust"
+```
+
+The reusable workflow cross-compiles the binary per target and stages it
+into the package source tree before maturin runs. Your `pyproject.toml`
+ties the staged binary into a `console_scripts` entry:
+
+```toml
+[project.scripts]
+my-cli = "my_py._binary:entrypoint"
+
+[tool.maturin]
+include = ["src/my_py/_binary/**"]
+```
+
+Launcher in `packages/python/src/my_py/_binary/__init__.py`:
+
+```python
+import os, sys
+from pathlib import Path
+
+def entrypoint():
+    here = Path(__file__).parent
+    binary = here / ("my-cli.exe" if os.name == "nt" else "my-cli")
+    if not binary.exists():
+        sys.stderr.write(f"my-cli binary not found at {binary}\n")
+        sys.exit(1)
+    os.execv(binary, [str(binary), *sys.argv[1:]])
+```
 
-Token fallbacks (`NPM_TOKEN`, `PYPI_API_TOKEN`, `CARGO_REGISTRY_TOKEN`) are
-still read as env vars if OIDC isn't available. `putitoutthere doctor`
-reports which path is active.
+## Dynamic-version PyPI gotcha
 
-## What it is not
+If your `pyproject.toml` uses `[project].dynamic = ["version"]` with
+`hatch-vcs` or `setuptools-scm`, the build backend derives the version from
+the latest git tag at build time — which is still the **previous** release
+when the build runs. Without a handoff, the sdist ships as
+`<pkg>-X.Y.Z.devN.tar.gz` instead of `<pkg>-X.Y.Z.tar.gz`.
 
-- Not a changelog generator. Use `git log` + conventional commits if you
-  want one.
-- Not a monorepo manager. Package boundaries are declared, not discovered.
-- Not a dependency resolver across ecosystems. `depends_on` is about
-  *cascading releases*, not runtime version pinning.
-- Not a build system. Handlers shell out to `cargo`, `uv`/`maturin`/`hatch`,
-  `npm` — standard toolchains only.
+The reusable workflow sets `SETUPTOOLS_SCM_PRETEND_VERSION` to the planned
+version on the build step, which both `setuptools-scm` and `hatch-vcs`
+honor. Per-package variants like `SETUPTOOLS_SCM_PRETEND_VERSION_FOR_<PKG>`
+are silently ignored by `hatch-vcs`; only the global form works.
 
-## Docs
+## Project layout
 
-- [Design proposal](./notes/4-17-2026-initial-plan/plan/proposal.md) — why this tool exists.
-- [Implementation plan](./notes/4-17-2026-initial-plan/plan/plan.md) — exhaustive reference.
-- [Migration guides](./migrations/) — per-repo plans for adopting putitoutthere.
-- [v0 epic](https://github.com/thekevinscott/put-it-out-there/issues/2) — remaining work.
+- [`CHANGELOG.md`](./CHANGELOG.md) — per-release changes.
+- [`MIGRATIONS.md`](./MIGRATIONS.md) — per-version upgrade guide.
+- [`notes/design-commitments.md`](./notes/design-commitments.md) — non-goals.
+- [`notes/internals/`](./notes/internals/) — internal contracts (artifact
+  layout, runner setup) that the reusable workflow honors so consumers don't
+  have to.

package/action.yml

@@ -1,10 +1,10 @@
-name: 'Put It Out There'
-description: 'Polyglot release orchestrator for crates.io, PyPI, and npm.'
+name: 'Put It Out There (internal)'
+description: 'Internal step-level wrapper around the putitoutthere CLI. Consumers compose with the reusable workflow at .github/workflows/release.yml@v1, not with this action directly. See notes/design-commitments.md non-goal #10.'
 author: 'Kevin Scott'
 
 inputs:
   command:
-    description: 'Which putitoutthere command to run: plan | publish'
+    description: 'Which CLI subcommand to run. Canonical values are `plan` and `publish`.'
     required: false
     default: 'plan'
   dry_run:
@@ -12,13 +12,13 @@ inputs:
     required: false
     default: 'false'
   fail_on_error:
-    description: 'If true, non-zero putitoutthere exit codes fail the step.'
+    description: 'If true, non-zero CLI exit codes fail the step.'
     required: false
     default: 'true'
 
 outputs:
   matrix:
-    description: 'JSON matrix emitted by `putitoutthere plan`. Empty string for other commands.'
+    description: 'JSON matrix emitted by `plan`. Output key is omitted when the plan resolves to zero rows or when command is anything other than plan; downstream jobs should coalesce with `|| ''[]'''.'
 
 runs:
   using: 'node24'

package/dist/action.js

@@ -13,7 +13,7 @@ export async function main() {
     const dryRun = (process.env.INPUT_DRY_RUN ?? 'false').toLowerCase() === 'true';
     const failOnError = (process.env.INPUT_FAIL_ON_ERROR ?? 'true').toLowerCase() !== 'false';
     if (!command) {
-        process.stderr.write('put-it-out-there action: missing required input `command`\n');
+        process.stderr.write('putitoutthere action: missing required input `command`\n');
         process.exit(1);
     }
     const argv = ['node', 'putitoutthere', command];
@@ -22,7 +22,7 @@ export async function main() {
     argv.push('--json');
     const code = await run(argv);
     if (code !== 0 && !failOnError) {
-        process.stderr.write(`put-it-out-there action: ignoring non-zero exit (fail_on_error=false): ${code}\n`);
+        process.stderr.write(`putitoutthere action: ignoring non-zero exit (fail_on_error=false): ${code}\n`);
         process.exit(0);
     }
     process.exit(code);

package/dist/action.js.map

@@ -1 +1 @@
-{"version":3,"file":"action.js","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,MAAM,CAAC,KAAK,UAAU,IAAI;IACxB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC;IAChD,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;IAC/E,MAAM,WAAW,GACf,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,MAAM,CAAC,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC;IAExE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,6DAA6D,CAC9D,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;IAChD,IAAI,MAAM;QAAE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEpB,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,0EAA0E,IAAI,IAAI,CACnF,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,oFAAoF;AACpF,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACpD,KAAK,IAAI,EAAE,CAAC;AACd,CAAC"}
+{"version":3,"file":"action.js","sourceRoot":"","sources":["../src/action.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,MAAM,CAAC,KAAK,UAAU,IAAI;IACxB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC;IAChD,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;IAC/E,MAAM,WAAW,GACf,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,MAAM,CAAC,CAAC,WAAW,EAAE,KAAK,OAAO,CAAC;IAExE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,0DAA0D,CAC3D,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;IAChD,IAAI,MAAM;QAAE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAEpB,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,uEAAuE,IAAI,IAAI,CAChF,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrB,CAAC;AAED,oFAAoF;AACpF,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACpD,KAAK,IAAI,EAAE,CAAC;AACd,CAAC"}

package/dist/cli.d.ts

@@ -1,16 +1,14 @@
 /**
- * `putitoutthere` CLI entry. Thin wrapper around the SDK.
- *
- * plan   → src/plan.ts
- * publish → src/publish.ts
- * init   → TODO #20
- * doctor → TODO #23
+ * `putitoutthere` CLI entry. Internal seam — the reusable workflow
+ * (`.github/workflows/release.yml`) invokes this. Not a consumer-
+ * facing surface; flags / help text are stable enough to test, but
+ * not promised externally. See `notes/design-commitments.md`.
  *
  * Global flags:
  *   --cwd <path>      working directory (default: process.cwd())
  *   --config <path>   path to putitoutthere.toml
  *   --dry-run         for publish; no side effects
- *   --json            for plan; emit JSON instead of a table
+ *   --json            machine-readable output
  */
 export declare function run(argv: readonly string[]): Promise<number>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAyHH,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA0UlE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA6GH,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAyTlE"}