Skip to content

Prepare one-command npm distribution and protected release path - #9

Merged
kixelated merged 7 commits into
mainfrom
quest/m0/npm
Nov 7, 2026
Merged

kixelated merged 7 commits into
mainfrom
quest/m0/npm

Conversation

@kixelated

@kixelated kixelated commented Nov 7, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Prepare @kixelated/token-max for one-command npx/Bun distribution: ship a Node-shebang JavaScript bundle with dependency licenses, no consumer dependencies or install hooks, an allowlisted tarball, and --version from package.json. Use a private CLI entry that runs consistently through npm bin symlinks, direct Node, and Bun.

Exercise the actual scoped npx --yes @kixelated/token-max@latest and bunx --bun @kixelated/token-max@latest commands using a synthetic local registry serving only the checked tarball. Each launcher downloads it into a clean isolated cache; Bun runs with no Node on PATH. Tests cover help/version, relative paths in a directory with spaces, priced analysis, text/JSON, exit 0/1/2, malformed selected records, privacy and read-only histories/settings.

The required Check now aggregates source validation and the exact-artifact Linux/macOS/Windows × Node 22/24/26 matrix with Bun 1.4.4. The small aggregate gate also runs on drafts and fails skipped dependencies, preventing a stale skipped Check from satisfying protection while the real validation is pending. PR code retains read-only credentials. A manual, main-only Release workflow checks completion/version/environment protection, reruns validation and the matrix, then automatically publishes those same bytes with public scoped access from the branch-only npm environment. No per-release environment reviewer or approval is required. It supports protected authenticated bootstrap and preferred OIDC afterward.

Delete the completed packaging quest and its link. Preserve m0's owner authentication/publication wait: no version bump and no publication. m0 still owns the complete 0.1.0 release after every child merges. No host-cost audit is claimed.

Decisions

Settled by coordinator correction, 2026-11-07: ✅ unattended publication from a separate environment restricted only to protected main (rejected: mandatory owner reviewer, per-release environment approval, and administrator-bypass requirements for that extra manual gate). These extra review requirements were introduced by this PR and exceeded the accepted packaging plan. Keep all version/completion/artifact/credential boundaries intact.

✅ Configure and verify the branch-only GitHub environment through the authenticated API now (rejected: treating this reversible repository setup as an owner-only wait). The npm environment now has only the main branch policy, no required reviewer, and zero secrets. No npm login, token, or trusted publisher was configured. npm E401/scope authority remains m0's real owner prerequisite.

Choices

  • Bundle the existing dependencies into JavaScript using pinned Bun instead of shipping mutable consumer dependency resolutions. Keep their licenses derived from the module graph. No additional dependencies or native wrapper.
  • Support maintained Node 22/24/26 LTS and Bun 1.4.4; build once and test the identical tarball across the matrix.
  • Keep package version 0.0.0 and retain private:true against accidental direct publication. m0 removes that guard only for the complete release. Block release preparation on remaining m0 children, placeholder/private/mismatched versions, unprotected refs, or absent/main-incompatible release environment.
  • Bootstrap new-package publication only at release time using an environment-only granular token when npm requires it, then remove that token and prefer OIDC near a subsequent real release. Official npm setup currently starts from an existing package's settings and requires first OIDC publication within two days; no expiring publisher was configured now.
  • Document launcher download diagnostics and termination status separately from the CLI's stdout/stderr and signal behavior; package managers can emit their own messages.

Public API and wire impact

Adds -v/--version; keeps token-max as the executable under scoped npm package @kixelated/token-max. No analysis/JSON schema or exit-policy change. Public package files contain compiled JavaScript and public documentation only. The first-use examples remain explicitly marked unpublished until m0's release.

Validation

Conflict-free merge of current main at 7692106 from kixelated/token-max#8 includes native idle analysis/reporting. Additional release behavior changes receive a fresh exact-head review; no merge-only exemption is being claimed. Packed consumer checks now assert the idle advisory is present in JSON and text without enabling a native toggle for SDK usage.

The earlier failed draft aggregate Check run intentionally rejected skipped source/matrix jobs for head 006325d. The completed ready run of that previous head subsequently passed the full matrix, including macOS/Windows. New-head CI remains pending; local validation does not claim results for other operating systems.

  • nix develop --command quest gate just check: 123 synthetic tests under Bun 1.4.4 and Node 24.21.0, formatting, types, JS build, packed consumers, quest checks all pass. Repeated after committing.
  • Same packed artifact: standalone, real npx, and Node-free bunx all pass on Linux x64 under Node 22.23.4 and Node 26.13.0 as well as Node 24.21.0. Caches and fixtures stay under checkout .tmp/.
  • Repeated build and pack produce the same SHA-512 integrity. Scoped public npm publish ... --ignore-scripts --dry-run passes without publishing.
  • actionlint passes. Release preflight synthetic tests accept the branch-only environment without reviewer fields, and reject unsafe versions, refs, missing branch restrictions, API errors, permissive branch policies, and unfinished m0 children.
  • The publication workflow’s exact final verifier is exercised against valid bytes and rejects wrong package names, versions, placeholder versions, integrity metadata and changed tarball bytes.
  • macOS/Windows matrix and GitHub CI are pending, not locally exercised. No waiting on CI/online review in this implementation task.
  • Official npm, Bun, Node and GitHub guidance checked 2026-11-07; sources and release instructions are in docs/releasing.md.

Remaining npm owner-only release actions

These belong to m0 and do not block this packaging preparation: npm login and authenticated @kixelated scope authority (read-only npm whoami still E401 on 2026-11-07), configure bootstrap authentication only near the complete first release, and configure/validate OIDC near a later publication. The main-only GitHub npm environment is already configured by an agent, with no required reviewer, per-release approval, or stored secrets. An agent can drive Chrome for owner setup when requested. No new maintainer design decision is open.

Caused by

  • kixelated/token-max#3: its direct-path CLI entry guard did not account for package-manager bin symlinks. Clean packed launcher coverage now exercises that path.

Documentation note

AGENTS.md's phrase "everything CI runs" predates the OS/runtime matrix. Repository rules forbid editing agent instructions without a request, so it remains unchanged. README and release docs explicitly state the CI-only platform coverage. Suggested clearer wording if the maintainer authorizes a later instruction edit: "just check runs the local validation suite; CI additionally exercises the packed artifact across the supported OS/runtime matrix."

Models

Size: M
Implementer: Codex, gpt-6.1-sol, xhigh effort

Review

Rewritten by quest review after each round.

  • Reviewer: Claude Code, claude-opus-5-5, medium effort
  • Session: 51e3d6c3-742d-47c3-9c45-7d5f134354fa, round 3
  • Head: 147f8af
  • Base: origin/main at 7692106
  • Score: 9/10, No findings remain and the release path is well tested, but the AGENTS.md line about local checks is now out of date and needs an edit that the maintainer has to request.
  • Findings: none
  • The last round's findings, at 147f8af:
    • Refuted: low, AGENTS.md:10: Agent docs still say `just check` runs everything CI runs; `.tmp/iterate-context.txt:17` shows the Required rule "Never add or change a rule in an `AGENTS.md` ... without being prompted", so the author may not edit that line unprompted; the justfile comment is corrected, and the required Check still blocks landing until every matrix cell passes.

(Written by GPT-6.1 Sol with xhigh)

kixelated and others added 2 commits November 7, 2026 11:13
Quest-Claim: 395292d3c11ffb5b
Co-Authored-By: GPT-6.1 Sol <noreply@openai.com>
@kixelated kixelated changed the title One-command npm distribution Prepare one-command npm distribution and protected release path Nov 7, 2026
Co-Authored-By: GPT-6.1 Sol <noreply@openai.com>
@kixelated
kixelated marked this pull request as ready for review November 7, 2026 19:31
@kixelated
kixelated marked this pull request as draft November 7, 2026 19:32
Co-Authored-By: GPT-6.1 Sol <noreply@openai.com>
@kixelated
kixelated marked this pull request as ready for review November 7, 2026 19:33
@kixelated

Copy link
Copy Markdown
Collaborator Author

Design change: align release preparation with the settled unattended release scope. Remove the mandatory environment reviewer, per-release approval, and the related administrator-bypass requirement introduced by this PR. The coordinator explicitly confirmed these were outside the accepted plan; this is a scope correction, not an open maintainer decision.

Publication still requires protected main, a separate main-only npm environment, a complete non-placeholder version after every m0 child merges, and the exact tarball that passed the full artifact matrix. PR code receives no publisher credentials or OIDC permission. The authenticated GitHub API can configure the branch-only environment, so its creation is not an owner-only release prerequisite. It has been configured without npm secrets; npm login/scope authority remains the real m0 owner wait. No version bump, npm publisher setup, or publication is part of this iteration.

Merged current main from kixelated/token-max#8 without conflicts. The changed release behavior will receive a new independent exact-head review.

(Written by GPT-6.1 Sol with xhigh)

kixelated and others added 2 commits November 7, 2026 11:39
Co-Authored-By: GPT-6.1 Sol <noreply@openai.com>
Co-Authored-By: GPT-6.1 Sol <noreply@openai.com>
@kixelated

Copy link
Copy Markdown
Collaborator Author

The remaining review note concerns AGENTS.md's older claim that just check runs everything CI runs. Its wording should eventually say that CI additionally exercises the packed artifact across the OS/runtime matrix. I corrected the justfile comment and documented the distinction throughout README, release docs and this PR.

I am leaving the agent instruction unchanged under the exact Required rule from nix develop -c quest context: "Never add or change a rule in an AGENTS.md, CONTRIBUTING.md, or skill without being prompted." This task does not request an agent-rule change. The required aggregate Check still blocks landing on any failed/skipped matrix dependency; local Linux results never establish macOS/Windows success.

(Written by GPT-6.1 Sol with xhigh)

@kixelated
kixelated merged commit 63bad49 into main Nov 7, 2026
11 checks passed
@kixelated
kixelated deleted the quest/m0/npm branch November 7, 2026 19:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant