From d835b79ae36f0047bb61411eee4259f635ae8333 Mon Sep 17 00:00:00 2001 From: hyscodebase <193484132+hyscodebase@users.noreply.github.com> Date: Tue, 3 Nov 2026 14:16:18 +0900 Subject: [PATCH] Prepare alpha.4 for verified npm distribution --- CHANGELOG.md | 9 +++++++++ README.md | 14 +++++++------- docs/README.ko.md | 12 +++++++----- docs/execution.md | 6 +++--- docs/npm-publishing.md | 40 +++++++++++++++++++++++++++++----------- docs/releasing.md | 6 +++--- docs/validation.md | 17 ++++++++++++++++- package-lock.json | 4 ++-- package.json | 2 +- 9 files changed, 77 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a2f7df2..0dd67ce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,14 @@ # Changelog +## 0.1.0-alpha.4 — 2026-11-03 + +- Recommend the public npm `alpha` installation in the English and Korean + quickstarts after an isolated registry install and demo passed for alpha.3. +- Record the initial package's integrity against the compiled GitHub release, + and document npm's publish-time availability delay and OIDC validation gate. +- Include reviewed GitHub Actions updates in this release. Native capture + support and comparison behavior are unchanged from alpha.3. + ## 0.1.0-alpha.3 — 2026-11-02 - Add specific next steps for unsupported, partial, and failed captures and diff --git a/README.md b/README.md index 910d4fc..b1d1509 100644 --- a/README.md +++ b/README.md @@ -12,22 +12,22 @@ Actual CLI output from synthetic fixtures, shown as excerpts. [Video](https://gi ## Try the offline demo -Requires Node.js 22 or later and Git: +Requires Node.js 22 or later: ```sh -npx --yes github:hyscodebase/skillwhy#v0.1.0-alpha.3 demo +npx --yes @hyscodebase/skillwhy@alpha demo ``` -The first run downloads and builds the tagged source. The demo uses synthetic snapshots. It needs no Codex installation, API key, or model call. +The first run downloads the compiled [npm package](https://www.npmjs.com/package/@hyscodebase/skillwhy). The demo uses synthetic snapshots. It needs no Codex installation, API key, or model call. -To install the compiled GitHub release once and use the shorter `skillwhy` command: +To install once and use the shorter `skillwhy` command: ```sh -npm install --global https://github.com/hyscodebase/skillwhy/releases/download/v0.1.0-alpha.3/hyscodebase-skillwhy-0.1.0-alpha.3.tgz +npm install --global @hyscodebase/skillwhy@alpha skillwhy demo ``` -This is a GitHub release, not an npm registry publication. Release assets include a SHA-256 checksum. From a checkout, use `npm ci`, then `npm run demo`; replace `skillwhy` below with `node dist/src/cli.js`. +Use the explicit `alpha` tag while prereleases are being evaluated. [GitHub release tarballs](https://github.com/hyscodebase/skillwhy/releases) with SHA-256 checksums remain available. From a checkout, use `npm ci`, then `npm run demo`; replace `skillwhy` below with `node dist/src/cli.js`. ```text SkillWhy · skill discovery comparison @@ -101,7 +101,7 @@ No runtime dependencies. Tests use synthetic records and local fake subprocesses Try the [10-minute pilot](docs/pilot.md) to report installation friction or a useful support case. External pilot outcomes have not yet been established. -For incomplete results, see [troubleshooting](docs/troubleshooting.md). Maintainers can use the [interview guide](docs/interviews.md) and [weekly metrics](docs/metrics.md) to track feedback. Registry publication is being prepared separately; [npm distribution](docs/npm-publishing.md) records its current status. +For incomplete results, see [troubleshooting](docs/troubleshooting.md). Maintainers can use the [interview guide](docs/interviews.md) and [weekly metrics](docs/metrics.md) to track feedback. [npm distribution](docs/npm-publishing.md) records publication and clean-install evidence. [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [한국어](docs/README.ko.md) · [Roadmap](docs/roadmap.md) diff --git a/docs/README.ko.md b/docs/README.ko.md index 22c5947..f662930 100644 --- a/docs/README.ko.md +++ b/docs/README.ko.md @@ -7,20 +7,22 @@ Codex CLI를 새로 실행해 발견 목록을 수집하고 두 환경을 비교 실제 CLI 출력의 일부를 사용한 합성 예시입니다. [영상](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo.mp4)과 [전체 출력 기록](https://github.com/hyscodebase/skillwhy/blob/main/assets/demo-transcript.txt)도 제공합니다. -Node.js 22 이상과 Git이 있다면 한 줄로 데모를 실행할 수 있습니다. +Node.js 22 이상이 있다면 한 줄로 데모를 실행할 수 있습니다. ```sh -npx --yes github:hyscodebase/skillwhy#v0.1.0-alpha.3 demo +npx --yes @hyscodebase/skillwhy@alpha demo ``` -처음에는 해당 태그의 소스와 빌드 의존성을 다운로드합니다. +처음에는 빌드된 [npm 패키지](https://www.npmjs.com/package/@hyscodebase/skillwhy)를 다운로드합니다. 빌드된 패키지를 한 번 설치하고 짧은 명령으로 사용하려면: ```sh -npm install --global https://github.com/hyscodebase/skillwhy/releases/download/v0.1.0-alpha.3/hyscodebase-skillwhy-0.1.0-alpha.3.tgz +npm install --global @hyscodebase/skillwhy@alpha skillwhy demo ``` +초기 버전을 사용하려면 `alpha` 태그를 명시하세요. SHA-256 체크섬이 포함된 +[GitHub 릴리스 파일](https://github.com/hyscodebase/skillwhy/releases)도 제공합니다. 데모는 합성 데이터이며 API 키와 Codex 설치가 필요하지 않습니다. 실제 수집은 검증된 Codex/OS 조합만 지원합니다. @@ -55,7 +57,7 @@ Desktop 채팅의 상태도 검사하지 않습니다. 공유 파일은 한 항 1,000스타는 도전 목표이며 제품의 성능이나 성공을 보장하는 수치가 아닙니다. 실제 실행 검증은 [검증 기록](validation.md), 다음 버전 발행과 지원 범위 확대 절차는 -[릴리스 가이드](releasing.md)를 참고하세요. GitHub에서 패키지를 배포하며 npm 레지스트리에는 아직 게시하지 않았습니다. +[릴리스 가이드](releasing.md)를 참고하세요. npm 공개 레지스트리와 GitHub에서 패키지를 배포합니다. 첫 사용 경험과 실제 도움 여부를 확인할 [10분 파일럿 안내](pilot.md)와 피드백 양식도 제공합니다. 외부 사용자의 파일럿 결과와 반복 사용은 아직 검증되지 않았습니다. diff --git a/docs/execution.md b/docs/execution.md index 7c548fd..7a19c63 100644 --- a/docs/execution.md +++ b/docs/execution.md @@ -8,7 +8,7 @@ Preparing materials is not equivalent to completing an external validation gate. | 1. Maintainer problem interviews | Five candidate projects researched; bilingual questions and invitation drafts prepared | Five actual interviews and two recurring, relevant problems | | 2. External pilots | Self-serve guide and report form available | Three external attempts; at least two useful comparisons without author assistance | | 3. Correct repeated pilot friction | Engineering review added explicit next steps for unsupported, partial, and unassociated results | Two repeated pilot blockers corrected and rechecked by participants | -| 4. npm distribution | Public alpha metadata and an optional packaging/publication workflow prepared | Namespace owner authenticates, first package publishes, clean registry install passes; then trusted publisher setup | +| 4. npm distribution | Alpha.3 published publicly; isolated registry install and npx demo passed with matching release integrity; exact GitHub Trusted Publisher configured | First successful OIDC publication and clean install of that release | | 5. Broader native compatibility | Ubuntu 24.04 x64 candidate and production checks passed on Node 22/24; macOS production checks pass | Complete for the newly admitted Codex 0.166.0/Linux x64 tuple; other combinations remain outside the evidence | | 6. Two useful external cases | Interview and evidence-register formats prepared | Two participant-confirmed, approved public accounts of help with an actual problem | | 7. Demonstration and README | 42-second GIF/MP4 and transcript published; public assets were fetched and matched their local hashes | Complete for the synthetic demonstration; actual user cases remain task 6 | @@ -16,8 +16,8 @@ Preparing materials is not equivalent to completing an external validation gate. | 9. Targeted introduction and weekly evidence | Two channel drafts prepared; first hosted public-aggregate report succeeded | Approved account-based publication and response handling | The initial external interview, completed-pilot, and approved-case registers are -empty. npm authentication was unavailable during preparation. These are pending -dependencies, not successful outcomes. Keep [the interview record](interviews.md), +empty. npm publication and an isolated registry install were verified on +2026-11-03; external participants remain pending. Keep [the interview record](interviews.md), [outreach record](outreach.md), [npm status](npm-publishing.md), and [native compatibility evidence](compatibility.md) aligned as evidence arrives. diff --git a/docs/npm-publishing.md b/docs/npm-publishing.md index 9cc4f81..0feeb95 100644 --- a/docs/npm-publishing.md +++ b/docs/npm-publishing.md @@ -1,14 +1,14 @@ # npm distribution -Registry publication is pending. GitHub release tarballs remain the currently -available installation route. The `alpha` npm dist-tag below becomes usable only -after the first successful registry publication. +The public [npm package](https://www.npmjs.com/package/@hyscodebase/skillwhy) is +available. The initial `0.1.0-alpha.3` publication and an isolated public registry +installation were verified on 2026-11-03; see [the validation record](validation.md#public-npm-installation). +Use `npx --yes @hyscodebase/skillwhy@alpha demo` for the offline demo. -The package is prepared as `@hyscodebase/skillwhy`, with public access, an `alpha` -dist-tag, and `https://registry.npmjs.org` in its publication metadata. Confirm -that the npm account owns this namespace before the first publication. +The package is published as `@hyscodebase/skillwhy`, with public access, an `alpha` +dist-tag, and `https://registry.npmjs.org` in its publication metadata. The namespace owner performed the initial interactive publication. -## First publication +## Initial publication procedure 1. Authenticate interactively with `npm login --registry=https://registry.npmjs.org`. Complete npm's account verification in your own browser. Credentials and @@ -29,14 +29,15 @@ describes namespace ownership, public visibility, and account verification. ## Subsequent releases from GitHub Actions -Configure the package's npm Trusted Publisher with: +The package's npm Trusted Publisher is configured with: | Field | Value | | --- | --- | | Organization or user | `hyscodebase` | | Repository | `skillwhy` | | Workflow filename | `npm-publish.yml` | -| Allowed action | Direct `npm publish` | +| Allowed action | Direct `npm publish` (and npm's implicit `npm stage publish`) | +| Environment name | None | The manual **npm distribution** workflow accepts an existing prerelease tag on `main`. Its default `publish: false` runs tag validation, the shared CI matrix, @@ -45,8 +46,9 @@ No registry version is created in that mode. To publish after account setup, dispatch from that exact tag with `publish: true`, for example: ```sh -gh workflow run npm-publish.yml --ref v0.1.0-alpha.3 \ - -f release_tag=v0.1.0-alpha.3 -F publish=true +RELEASE_TAG=vX.Y.Z-alpha.N # Replace with the next unpublished prerelease. +gh workflow run npm-publish.yml --ref "$RELEASE_TAG" \ + -f release_tag="$RELEASE_TAG" -F publish=true ``` Real publication requires both the dispatch ref and event commit to match the @@ -62,3 +64,19 @@ workflow uses Node 24 and checks the required npm CLI version. Follow the [official Trusted Publishing instructions](https://docs.npmjs.com/trusted-publishers/) when configuring the package; a successful dry run does not prove npm publishing authorization is configured. + +A newly created connection must complete its first successful publication within +2 days. The connection was saved on 2026-11-03; its first real OIDC publication is +still pending. Do not treat saving the form or a dry run as successful registry +authorization. Once a version is published, use a new version and tag for the +next attempt that changes package contents; do not replace published versions. + +## Availability after publication + +npm can accept a publication before the version becomes installable. Its +[publish-time scanning announcement](https://github.blog/changelog/2026-07-28-npm-publish-time-malware-scanning-and-dual-use-metadata/) +describes a typical delay of a few minutes, which can take longer. An immediate +404 after a successful publish is not evidence that the version can be safely +republished. Check the existing version and its integrity again before any retry. +The initial alpha.3 request returned HTTP 202 and became publicly installable +before the clean-install checks above. diff --git a/docs/releasing.md b/docs/releasing.md index 1e45919..5e0acce 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -6,7 +6,7 @@ SkillWhy's release workflow builds a downloadable npm tarball and `SHA256SUMS` o 1. Change the version in `package.json` and both version fields in `package-lock.json`. `src/version.ts` reads the installed package metadata, so there is no second CLI version constant to update. 2. Update the changelog and compatibility evidence. Run `npm ci`, `npm test`, and `npm run typecheck`. `npm test` includes the release gate and publication state tests. -3. Merge the release commit into `main`. Wait for the normal branch CI, then tag that exact commit, for example `git tag -a v0.1.0-alpha.3 -m 'SkillWhy 0.1.0-alpha.2'` and `git push origin v0.1.0-alpha.3`. +3. Merge the release commit into `main`. Wait for the normal branch CI, then tag that exact commit, for example `git tag -a v0.1.0-alpha.4 -m 'SkillWhy 0.1.0-alpha.4'` and `git push origin v0.1.0-alpha.4`. 4. Watch **GitHub prerelease** in Actions. The release becomes public only after workflow lint, all four Linux/macOS × Node 22/24 jobs, and the packaged installation smoke checks pass. Tag pushes matching `v*` trigger the workflow. The tag must equal `v` plus the package version, point to the checked out/event commit, and already be an ancestor of `origin/main`. Annotated and lightweight tags both work. Only prerelease versions such as `0.1.0-alpha.2` are accepted; stable versions and build metadata are deliberately rejected until a stable-release policy is added. A prerelease is never marked as the repository's latest stable release. @@ -35,7 +35,7 @@ npm ci RELEASE_DIR="$(mktemp -d)/assets" node scripts/release-build.mjs ``` -The command prints a manifest of the two assets. It installs only into a temporary prefix and does not publish anything. `RELEASE_DIR` must not already exist; keeping old artifacts in place causes a failure instead of silently reusing them. The temporary installed prefix is removed; the requested output directory remains for inspection. Version/tag ancestry is checked separately by `RELEASE_TAG=v0.1.0-alpha.3 node scripts/release-check.mjs` after creating the tag. +The command prints a manifest of the two assets. It installs only into a temporary prefix and does not publish anything. `RELEASE_DIR` must not already exist; keeping old artifacts in place causes a failure instead of silently reusing them. The temporary installed prefix is removed; the requested output directory remains for inspection. Version/tag ancestry is checked separately by `RELEASE_TAG=v0.1.0-alpha.4 node scripts/release-check.mjs` after creating the tag. ## Install a release asset @@ -43,7 +43,7 @@ Download the `.tgz` file and `SHA256SUMS` from the same GitHub prerelease. In th ```sh shasum -a 256 -c SHA256SUMS -npm install --prefix ./skillwhy-install --ignore-scripts --no-audit --no-fund ./hyscodebase-skillwhy-0.1.0-alpha.3.tgz +npm install --prefix ./skillwhy-install --ignore-scripts --no-audit --no-fund ./hyscodebase-skillwhy-0.1.0-alpha.4.tgz ./skillwhy-install/node_modules/.bin/skillwhy --version ./skillwhy-install/node_modules/.bin/skillwhy demo ``` diff --git a/docs/validation.md b/docs/validation.md index 95d34bc..566d270 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -1,8 +1,23 @@ # Alpha validation record -Date: 2026-11-02. These observations are scoped engineering checks, not a claim +Updated: 2026-11-03. These observations are scoped engineering checks, not a claim of production readiness, adoption, or model accuracy. +## Public npm installation + +On 2026-11-03, `@hyscodebase/skillwhy@0.1.0-alpha.3` became available from the +public npm registry. Its registry SHA-1 and SHA-512 integrity matched the compiled +GitHub release tarball; that file's SHA-256 is +`7e87ba34b8da5fca027cd5eb54e7aa796b27ec536e19f9eb4cdcd8f8221a3fcd`. + +An installation into a new temporary prefix, with a new cache and empty user and +global npm configuration, reported `0.1.0-alpha.3` and ran `demo --json` with +`status: complete`. An isolated `npm exec --package=@hyscodebase/skillwhy@alpha` +demo produced the same JSON. These checks used Node 24.8.0 and npm 11.11.0 on +macOS arm64, with no registry login available to the installation process. +This establishes public package distribution and the offline demo, rather than +additional native Codex compatibility or external adoption. + ## Alpha.3 native support investigation After extracting the production compatibility manifest, the existing macOS arm64 diff --git a/package-lock.json b/package-lock.json index 1fb2113..8fe3c39 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@hyscodebase/skillwhy", - "version": "0.1.0-alpha.3", + "version": "0.1.0-alpha.4", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@hyscodebase/skillwhy", - "version": "0.1.0-alpha.3", + "version": "0.1.0-alpha.4", "license": "MIT", "bin": { "skillwhy": "dist/src/cli.js" diff --git a/package.json b/package.json index f2491c3..56cd32b 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@hyscodebase/skillwhy", - "version": "0.1.0-alpha.3", + "version": "0.1.0-alpha.4", "description": "Compare the skills your Codex CLI environments actually discover.", "type": "module", "license": "MIT",