@guiho/runx 0.2.0 → 0.2.3

package/CHANGELOG.md

@@ -15,6 +15,24 @@ owner: runx
 
 # Changelog
 
+## 0.2.2 - 2026-07-14
+
+### Changed
+
+- Retried the npm trusted-publishing release after the initial `0.2.1` tag could not be created under the repository tag ruleset.
+
+## 0.2.1 - 2026-07-14
+
+### Added
+
+- Added npm OIDC trusted publishing to the protected `production` workflow for `@guiho/runx@*` tags.
+- Expanded CI to validate the complete 12-target native binary matrix.
+- Added active GitHub rulesets protecting `main` and `@guiho/runx@*` release tags.
+
+### Fixed
+
+- Fixed the published `runx` launcher to use the compiled library entrypoint included in the npm package instead of relying on excluded source files.
+
 ## 0.2.0 - 2026-07-12
 
 ### Added

package/DOCS.md

@@ -114,5 +114,7 @@ macOS/Linux assets from GitHub Releases into the user's local bin directory.
 on Windows replacement is scheduled after RunX exits. `runx uninstall` removes
 the same native executable and supports `--dry-run`.
 
-The alpha CI validates code and compiles a native executable but intentionally
-does not publish to npm or GitHub Releases.
+CI validates code and compiles the local executable plus the native release
+matrix. Protected `@guiho/runx@*` tags run the `production` publish workflow,
+which uploads twelve native assets to GitHub Releases and publishes the public
+npm package through OIDC trusted publishing.

package/README.md

@@ -22,8 +22,12 @@ local shell commands rather than package-manager scripts.
 
 ## Install
 
-RunX is distributed as a native executable from GitHub Releases. It is not
-published to npm during the alpha.
+RunX is distributed as a native executable from GitHub Releases and as the
+public `@guiho/runx` package on npm. The npm launcher requires Bun.
+
+```sh
+bun add --global @guiho/runx
+```
 
 ```powershell
 irm https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.ps1 | iex

package/docs/decisions/decisions.xdocs.md

@@ -5,8 +5,10 @@ parent: runx-docs
 children: []
 files:
   alpha-boundaries.md: Captures accepted alpha scope, safety, distribution, and compatibility decisions.
+  npm-trusted-publishing.md: Defines the accepted npm OIDC publishing workflow and protected-branch patch-release trial.
 documents:
   alpha-boundaries.md: Decision record for RunX alpha boundaries.
+  npm-trusted-publishing.md: Decision record for GitHub Actions npm trusted publishing and the first automated patch release.
 tags:
   - decisions
 keywords:

package/docs/decisions/npm-trusted-publishing.md

@@ -0,0 +1,92 @@
+---
+name: RunX npm Trusted Publishing
+purpose: Define the accepted GitHub Actions and Mirror release flow for publishing RunX to npm with OIDC.
+description: Records the two-workflow design, native release preservation, npm trusted-publishing requirements, and protected-branch release path.
+created: 2026-07-14
+flags:
+  - accepted
+tags:
+  - decisions
+  - release
+  - npm
+keywords:
+  - runx
+  - trusted publishing
+  - oidc
+  - github actions
+  - mirror
+owner: runx-decisions
+---
+
+# RunX npm Trusted Publishing
+
+## Context
+
+RunX already has separate CI and tag-triggered publishing workflows. The
+publish workflow validates the package, compiles twelve native binaries, and
+publishes them to a GitHub Release. The original alpha decision excluded npm
+publishing, but RunX is now ready to publish `@guiho/runx` through npm trusted
+publishing without a long-lived npm token.
+
+## Decision
+
+- Keep exactly two workflows: `.github/workflows/ci.yml` and
+  `.github/workflows/publish.yml`.
+- Keep CI read-only and run it for pull requests and pushes to `main`.
+- Keep the publish trigger scoped to tags matching `@guiho/runx@*`.
+- Preserve the existing native-binary GitHub Release and asset-verification
+  behavior.
+- Add npm trusted publishing to the existing publish job after the idempotent
+  GitHub Release steps.
+- Grant `id-token: write` only to the publish workflow and retain the
+  `production` GitHub environment.
+- Use a GitHub-hosted runner, Node 24, npm 11.5.1 or newer, and
+  `npm publish --access public` without an npm token. OIDC trusted publishing
+  supplies authentication and provenance.
+- Keep Bun as the package development, validation, build, and binary toolchain.
+  Node/npm is used only for the registry publication step and does not become a
+  RunX runtime dependency.
+
+## Release Trial
+
+The first automated npm publication trial is the Mirror-managed patch release
+from `0.2.0` to `0.2.1`.
+
+1. Land the workflow and documentation changes on `main` through a pull
+   request, because the default branch is protected.
+2. Run the full RunX validation and `mirror version plan patch` before applying
+   the release.
+3. Prepare the changelog from the planned version, commit release preparation,
+   and apply the patch with Mirror so the release commit and
+   `@guiho/runx@0.2.1` tag remain Mirror-managed.
+4. Push the protected release tag only after the release commit is part of the
+   protected-branch history.
+5. Observe the Publish workflow and verify both the GitHub Release assets and
+   npm package publication.
+
+## Failure and Retry Behavior
+
+- GitHub Release creation/upload remains before npm publication because those
+  operations are idempotent and can be retried safely.
+- If npm rejects OIDC configuration, the workflow fails at the npm step without
+  attempting a second version or modifying the existing tag.
+- After correcting npm trusted-publisher settings, rerun the failed workflow;
+  the GitHub Release assets are updated in place before npm is retried.
+- Never retry by republishing the same version after npm has accepted it;
+  confirm registry state first.
+
+## Validation
+
+- Validate workflow syntax and inspect the resulting diff.
+- Run `bun run typecheck`, `bun test`, `bun run build`, and
+  `bun run binaries` before the release.
+- Run XDocs strict metadata, tree, and doctor checks for every changed
+  documentation module.
+- Confirm the npm trusted publisher names repository `CGuiho/runx`, workflow
+  `publish.yml`, environment `production`, and permission to run `npm publish`.
+
+## Superseded Boundary
+
+This decision supersedes only the alpha statement that RunX has CI without an
+npm publishing job. The remaining safety, manifest, runtime, and scope
+decisions in [RunX Alpha Boundaries](alpha-boundaries.md) remain in force.

package/docs/docs.xdocs.md

@@ -7,6 +7,7 @@ children:
   - runx-architecture
   - runx-decisions
   - runx-plans
+  - runx-reviews
   - runx-todo
   - runx-validation
 files: {}

package/docs/plans/npm-trusted-publishing-release.md

@@ -0,0 +1,119 @@
+---
+name: RunX npm Trusted Publishing Release Plan
+purpose: Sequence the workflow implementation, protected-branch delivery, Mirror patch release, and public publish verification for RunX 0.2.1.
+description: Executable units for adding npm OIDC publishing without removing native releases, then triggering and observing the first trusted publication.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - plans
+  - release
+  - npm
+keywords:
+  - runx
+  - trusted publishing
+  - github actions
+  - mirror patch
+  - 0.2.1
+owner: runx-plans
+---
+
+# RunX npm Trusted Publishing Release Plan
+
+## Source Decision
+
+- [RunX npm Trusted Publishing](../decisions/npm-trusted-publishing.md)
+
+## Unit 1: Implement the Workflows
+
+- Goal: Keep two GitHub workflows while adding npm OIDC publication to the
+  existing tag-triggered publish job.
+- Owner: RunX repository.
+- Dependencies: Accepted trusted-publishing decision; npm trusted publisher for
+  `CGuiho/runx`, `publish.yml`, and environment `production`.
+- Files:
+  - `.github/workflows/ci.yml`
+  - `.github/workflows/publish.yml`
+  - `.github/workflows/workflows.xdocs.md`
+  - `scripts/runx-bin.ts`
+  - `scripts/scripts.xdocs.md`
+  - `AGENTS.md`
+- Permissions: CI retains `contents: read`; Publish retains `contents: write`
+  and gains `id-token: write` only for npm OIDC.
+- Checks: Inspect YAML, run `git diff --check`, and validate the package with
+  Bun before delivery.
+- Acceptance:
+  - CI validates install, typecheck, tests, build, and native builds.
+  - Publish retains tag trigger `@guiho/runx@*`, environment `production`, and
+    twelve-asset GitHub Release handling.
+  - Publish uses Node 24 with npm 11.5.1 or newer and runs
+    `npm publish --access public` without an npm token.
+  - The published `runx` bin launcher prefers the included compiled
+    `library/guiho-runx-bin.js` and retains the source launcher fallback only
+    for repository checkouts.
+  - `npm pack --dry-run --json` confirms the launcher and compiled library are
+    both included, and the packaged launcher can display RunX help through Bun.
+- Stop conditions: Do not continue if the repository URL, workflow filename,
+  environment, OIDC permission, or public access does not match npm trusted
+  publisher configuration.
+
+## Unit 2: Validate and Deliver Through the Protected Branch
+
+- Goal: Land the workflow and documentation changes on `main` without bypassing
+  the new branch ruleset.
+- Dependencies: Unit 1 complete.
+- Checks:
+  - `bun run typecheck`
+  - `bun test`
+  - `bun run build`
+  - `bun run binaries`
+  - `xdocs meta .github --strict --format json`
+  - `xdocs tree`
+  - targeted XDocs doctor checks
+- Delivery:
+  - Commit only understood RunX changes on a `codex/` feature branch.
+  - Push the feature branch, open a pull request, and wait for required checks.
+  - Merge without bypassing protections, then synchronize local `main`.
+- Acceptance: Remote `main` contains the trusted-publishing workflow and its
+  required documentation before a release tag is pushed.
+- Stop conditions: Stop on failed CI, unresolved required review, unexpected
+  worktree changes, or protection failures.
+
+## Unit 3: Prepare and Apply Patch 0.2.1
+
+- Goal: Use Mirror to create the `0.2.1` release commit and tag from the updated
+  protected-branch history.
+- Dependencies: Unit 2 merged and local `main` synchronized.
+- Sequence:
+  - Run `mirror config show` and confirm changelog and dirty-worktree policy.
+  - Confirm a clean worktree.
+  - Run typecheck, tests, build, and native binaries.
+  - Run `mirror version plan patch` and confirm `nextVersion` is `0.2.1`.
+  - Update `CHANGELOG.md` and its XDocs owner metadata if required.
+  - Commit release preparation before applying Mirror.
+  - Run `mirror version apply patch --yes` with the configured release commit.
+- Acceptance: package version, Mirror release commit, and
+  `@guiho/runx@0.2.1` tag agree.
+- Stop conditions: Stop if Mirror plans another version, validation fails, or
+  the worktree is dirty before apply.
+
+## Unit 4: Push and Observe Trusted Publishing
+
+- Goal: Trigger the public Publish workflow and verify npm trusted publishing.
+- Dependencies: Unit 3 complete; explicit user authorization to test the public
+  release path.
+- Delivery:
+  - Land the Mirror release commit through the protected branch when required.
+  - Push `@guiho/runx@0.2.1` only after its commit is part of `main` history.
+  - Monitor the public GitHub Actions run through completion.
+  - Verify the GitHub Release has twelve native assets.
+  - Verify npm reports `@guiho/runx@0.2.1` with trusted provenance.
+- Acceptance: the public Publish run succeeds and both distribution channels
+  expose version `0.2.1`.
+- Stop conditions: If npm fails, capture the exact public job failure and do not
+  create another version or replace the tag; correct trust configuration and
+  rerun the same workflow only after confirming npm did not accept the version.
+
+## First Executable Unit
+
+Unit 1: implement the workflows and their XDocs/agent documentation updates.

package/docs/plans/plans.xdocs.md

@@ -5,8 +5,10 @@ parent: runx-docs
 children: []
 files:
   alpha-implementation.md: Breaks the accepted alpha into implementation and validation units.
+  npm-trusted-publishing-release.md: Sequences workflow implementation, protected delivery, Mirror patching, and public trusted-publishing verification.
 documents:
   alpha-implementation.md: Plan used for the initial RunX implementation.
+  npm-trusted-publishing-release.md: Approved executable plan for the RunX 0.2.1 trusted-publishing release trial.
 tags:
   - plans
 keywords:

package/docs/reviews/plans/npm-trusted-publishing-release-review.md

@@ -0,0 +1,73 @@
+---
+name: RunX npm Trusted Publishing Release Plan Review
+purpose: Verify that the trusted-publishing workflow and patch-release plan is safe, sequenced, testable, and ready for execution.
+description: Reviews protected-branch delivery, Mirror ordering, npm OIDC permissions, failure handling, documentation, and validation gates.
+created: 2026-07-14
+flags:
+  - approved
+tags:
+  - reviews
+  - plans
+  - release
+keywords:
+  - runx
+  - trusted publishing
+  - plan review
+  - mirror
+  - github actions
+owner: runx-plan-reviews
+---
+
+# RunX npm Trusted Publishing Release Plan Review
+
+## Verdict
+
+Ready for execution.
+
+## Findings
+
+- No blocker or high-severity findings remain.
+- A package inspection found that the npm launcher referenced an excluded
+  `source/` fallback. Unit 1 now includes the bounded launcher correction and
+  pack/launcher verification, resolving the issue before publication.
+- The plan traces to the accepted npm trusted-publishing decision and preserves
+  Bun as the RunX runtime and development toolchain.
+- OIDC permission is limited to the publish workflow, and the plan explicitly
+  requires the configured `production` environment.
+- Native GitHub Release publication precedes npm publication, making a failed
+  OIDC attempt safely rerunnable before npm accepts the version.
+
+## Sequencing Review
+
+- Workflow changes land on protected `main` before any release tag is pushed.
+- Mirror plans the patch before changelog preparation and applies the version
+  only after validation and a clean worktree.
+- The release branch is merged before its existing Mirror tag is pushed, so the
+  tagged release commit is already part of protected `main` history when the
+  public workflow starts.
+
+## Acceptance and Validation Review
+
+- Workflow contents, permissions, trigger, environment, native asset count,
+  npm command, and trusted-publisher identity are explicit.
+- Bun typecheck, tests, build, native matrix, XDocs checks, GitHub Actions run,
+  GitHub Release assets, and npm registry state all have verification steps.
+- Failure stop conditions prevent version replacement, duplicate publication,
+  or a second release when the first npm outcome is uncertain.
+
+## TODO Alignment
+
+The repository TODO currently contains completed package and protection tasks.
+This release is a single approved execution session with a durable decision and
+plan, so no additional long-running TODO task is required.
+
+## First Executable Unit
+
+Implement Unit 1 in
+[RunX npm Trusted Publishing Release Plan](../../plans/npm-trusted-publishing-release.md):
+update the two workflows and their XDocs/agent documentation.
+
+## References
+
+- [RunX npm Trusted Publishing Release Plan](../../plans/npm-trusted-publishing-release.md)
+- [RunX npm Trusted Publishing](../../decisions/npm-trusted-publishing.md)

package/docs/reviews/plans/plans.xdocs.md

@@ -0,0 +1,21 @@
+---
+subject: runx-plan-reviews
+description: Execution-readiness reviews for RunX implementation and release plans.
+parent: runx-reviews
+children: []
+files:
+  npm-trusted-publishing-release-review.md: Reviews sequencing, acceptance criteria, safety gates, and validation for the RunX 0.2.1 trusted-publishing plan.
+documents:
+  npm-trusted-publishing-release-review.md: Ready-for-execution review of the npm trusted-publishing release plan.
+tags:
+  - reviews
+  - plans
+keywords:
+  - runx
+  - plan review
+  - trusted publishing
+flags: []
+status: stable
+---
+
+Plan reviews record whether RunX plans are safe and executable before implementation begins.

package/docs/reviews/reviews.xdocs.md

@@ -0,0 +1,18 @@
+---
+subject: runx-reviews
+description: Structured reviews of RunX architecture, plans, implementation, and release readiness.
+parent: runx-docs
+children:
+  - runx-plan-reviews
+files: {}
+documents: {}
+tags:
+  - reviews
+keywords:
+  - runx
+  - reviews
+flags: []
+status: stable
+---
+
+RunX reviews challenge durable plans and implementation evidence before execution or release.

package/docs/validation/npm-trusted-publishing-0.2.2.md

@@ -0,0 +1,54 @@
+---
+name: RunX npm Trusted Publishing 0.2.2 Validation
+purpose: Record the release checks and GitHub result for the 0.2.2 trusted-publishing retry.
+description: Documents successful build validation and the tag-ruleset rejection that prevented the Publish workflow from starting.
+created: 2026-07-14
+flags: []
+tags:
+  - validation
+  - release
+keywords:
+  - runx
+  - npm
+  - trusted publishing
+owner: runx-validation
+---
+
+# npm Trusted Publishing 0.2.2 Validation
+
+## Result
+
+The `0.2.2` package bump was merged to protected `main`, but GitHub rejected
+creation of the `@guiho/runx@0.2.2` tag. Because the tag was not created, the
+Publish workflow did not run and npm remained on `0.2.0`.
+
+## Passed checks
+
+- `bun run typecheck`
+- `bun test`: 4 passed, 0 failed
+- `bun run build`
+- `bun run binary`
+- `bun run binaries`: 12 native assets built and verified
+- `mirror version plan patch`: planned `0.2.1` to `0.2.2`
+- `xdocs meta . --documents --strict --owner runx --format json`
+- Pull request `#4` CI: passed
+
+## Release evidence
+
+- Protected-main merge: `57c7d81`
+- Mirror release commit: `6c67be5`
+- Local annotated tag: `@guiho/runx@0.2.2`
+- Remote tag: not created
+- Publish workflow run: not started
+- npm latest version after the attempt: `0.2.0`
+
+## Blocking rules
+
+GitHub rejected the tag with `GH013` because the active tag ruleset both
+requires linear history and restricts tag creation. The reported merge-commit
+violation was `f445631`. The ruleset had no bypass actors, and the authenticated
+repository owner could not bypass it.
+
+Trusted publishing itself was not exercised by this attempt. The tag ruleset
+must permit the release actor to create the version tag before npm OIDC can be
+validated.

package/docs/validation/validation.xdocs.md

@@ -7,6 +7,7 @@ files:
   alpha-implementation-summary.md: Records the completed alpha implementation, checks, and release boundaries.
 documents:
   alpha-implementation-summary.md: Validation summary for the first RunX implementation.
+  npm-trusted-publishing-0.2.2.md: Validation evidence for the blocked 0.2.2 npm trusted-publishing retry.
 tags:
   - validation
 keywords:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guiho/runx",
   "description": "A language-agnostic, documented command catalog and local CLI executor.",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "type": "module",
   "main": "./library/guiho-runx.js",
   "types": "./library/guiho-runx.d.ts",

package/scripts/runx-bin.ts

@@ -2,6 +2,7 @@
 
 const args = process.argv.slice(2)
 const binaryPath = new URL(`../vendor/runx${process.platform === 'win32' ? '.exe' : ''}`, import.meta.url)
+const libraryPath = new URL('../library/guiho-runx-bin.js', import.meta.url)
 const sourcePath = new URL('../source/guiho-runx-bin.ts', import.meta.url)
 
 if (await Bun.file(binaryPath).exists()) {
@@ -9,6 +10,11 @@ if (await Bun.file(binaryPath).exists()) {
   process.exit(await child.exited)
 }
 
+if (await Bun.file(libraryPath).exists()) {
+  const child = Bun.spawn([process.execPath, Bun.fileURLToPath(libraryPath), ...args], { stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' })
+  process.exit(await child.exited)
+}
+
 if (await Bun.file(sourcePath).exists()) {
   const child = Bun.spawn([process.execPath, Bun.fileURLToPath(sourcePath), ...args], { stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' })
   process.exit(await child.exited)

package/scripts/scripts.xdocs.md

@@ -4,7 +4,7 @@ description: Package-manager launcher scripts for RunX.
 parent: runx
 children: []
 files:
-  runx-bin.ts: Executes a packaged native binary when present or the source CLI in a checkout.
+  runx-bin.ts: Executes a packaged native binary, the published compiled library launcher, or the source CLI fallback in a checkout.
 documents: {}
 tags:
   - scripts
@@ -16,5 +16,5 @@ flags: []
 status: stable
 ---
 
-The package launcher preserves the `runx` bin command in development checkouts
-and installed packages.
+The package launcher preserves the `runx` bin command in installed npm packages
+and development checkouts without requiring unpublished source files.

package/skills/guiho-s-runx/agents/openai.yaml

@@ -1,4 +1,4 @@
-interface:
-  display_name: "RunX"
-  short_description: "Manage documented RunX command catalogs safely."
-  default_prompt: "Use the RunX CLI to inspect, validate, and run commands from runx.yaml safely."
+interface:
+  display_name: "RunX"
+  short_description: "Manage documented RunX command catalogs safely."
+  default_prompt: "Use the RunX CLI to inspect, validate, and run commands from runx.yaml safely."