@1endpoint/coding-helper 0.1.0 → 0.1.1

package/README.md

@@ -110,7 +110,7 @@ yarn test
 yarn pack --out ../coding-helper-0.1.0.tgz
 ```
 
-No production dependencies and no build step. The published entry is native ESM. Package contents are allowlisted. See [release checklist](docs/RELEASE.md) for current verification boundaries and publishing steps. Publishing is a separate maintainer action; creating or pushing the repository does not publish npm.
+No production dependencies and no build step. The published entry is native ESM. Package contents are allowlisted. See the [publishing guide](docs/PUBLISHING.md) for step-by-step npm authentication, first publication, verification, updates and troubleshooting. See the [release checklist](docs/RELEASE.md) for current verification boundaries. Publishing is a separate maintainer action; creating or pushing the repository does not publish npm.
 
 ## Reference and attribution
 

package/docs/PUBLISHING.md

@@ -0,0 +1,153 @@
+# Publishing @1endpoint/coding-helper to npm
+
+This guide is for maintainers publishing the package, not for end users configuring a coding tool. For tool setup, see the [README](../README.md). For implementation and verification boundaries, see the [release checklist](RELEASE.md).
+
+**Publishing is a separate action from pushing to GitHub.** Run the publish command only when you intend to release the selected version publicly. This document does not mean that a release has already been published.
+
+## 1. Requirements
+
+- Node.js **22.19.0 or newer**.
+- Yarn **4.17.0**, matching the repository's `packageManager` setting.
+- An npm account authorized to publish under the **`@1endpoint`** scope.
+- Access to the account's required two-factor authentication method.
+- A reviewed, committed checkout of [the repository](https://github.com/dothinh115/1endpoint-coding-helper).
+
+The npm scope and GitHub owner are independent. Owning the GitHub repository does not grant npm publishing rights. If `1endpoint` is an npm organization, the publishing account must be a member with package creation/publish permissions. Create or obtain access to that scope before continuing; do not change the package name merely to work around a permission failure.
+
+Never put npm passwords, access tokens, recovery codes, or one-time codes in source files, issue comments, screenshots, or chat. Use the package manager's authentication flow. The helper's `ONEENDPOINT_API_KEY` is **not** an npm credential and is not needed for publication.
+
+## 2. Open the checkout and authenticate
+
+From this workspace:
+
+```bash
+cd /Users/thinhdo/Documents/1endpoint/coding-helper
+node --version
+yarn --version
+
+yarn npm login --scope 1endpoint --publish
+yarn npm whoami --scope 1endpoint --publish
+```
+
+Follow the login prompts privately. The final command should identify the intended publishing account. Authentication alone does not prove permission to create this scoped package.
+
+## 3. Review the version and source
+
+```bash
+git status --short
+git log -1 --oneline
+node --input-type=module -e 'import fs from "node:fs"; const p = JSON.parse(fs.readFileSync("package.json", "utf8")); console.log(`${p.name}@${p.version}`)'
+```
+
+The worktree should be clean, and the name/version must be the release you intend to publish. The initial package version is `0.1.0`.
+
+Optionally inspect the registry before releasing:
+
+```bash
+yarn npm info @1endpoint/coding-helper --fields name,version,versions
+```
+
+Before the first publication, a package-not-found response can be expected. It does **not** establish that your account owns the scope. If the target version already exists, do not retry publishing that same version: published versions are immutable, even after unpublishing. Prepare a new version instead.
+
+## 4. Run the release checks
+
+```bash
+yarn install --immutable
+yarn check
+yarn test
+yarn pack --dry-run
+git diff --check
+```
+
+There is no separate compilation step: the package ships native ESM source. `prepack` also runs the syntax check and test suite when packaging/publishing.
+
+The ordinary test suite deliberately skips the opt-in installed-Claude loopback fixture. To run that fixture on a machine with Claude Code installed, set its absolute executable path:
+
+```bash
+CODING_HELPER_TEST_CLAUDE="$(command -v claude)" yarn test
+```
+
+This fixture uses a local synthetic server and dummy credentials, not paid gateway inference. Review skips and failures; a test run does not establish support for operating systems or CLI versions that were not exercised.
+
+Inspect the package file list. It should contain only package metadata, the license, README, documentation and the intended source modules. Do not ship environment files, credentials, helper runtime homes, test output or unrelated workspace files.
+
+## 5. Publish the package publicly
+
+For the initial stable release:
+
+```bash
+yarn npm publish --access public --tag latest
+```
+
+If npm requests an authenticator code, follow the prompt or provide a current code using the supported option:
+
+```bash
+yarn npm publish --access public --tag latest --otp YOUR_CURRENT_CODE
+```
+
+Replace the placeholder privately. Be aware that command arguments may be visible in shell history or process listings; prefer an interactive prompt when available. Never copy the real code into documentation or chat.
+
+`--access public` is intentional for this scoped package. `--tag latest` makes the release the default installed version. For a prerelease, use a prerelease version and a separate tag such as `next`; do not accidentally move `latest` to an experimental build.
+
+**Do not repeat the publish command blindly after an ambiguous network failure.** Check whether the version reached the registry first.
+
+## 6. Verify the public release
+
+For version `0.1.0`:
+
+```bash
+yarn npm info @1endpoint/coding-helper --fields name,version,bin,dist
+npx @1endpoint/coding-helper@0.1.0 --version
+npx @1endpoint/coding-helper@0.1.0 --help
+npx @1endpoint/coding-helper@0.1.0
+```
+
+Verify:
+
+1. Registry metadata reports the expected name and version, binary entries, and tarball integrity.
+2. `--version` prints `0.1.0` and `--help` lists the documented commands.
+3. The interactive entry asks for **English / Tiếng Việt first**.
+4. Arrow keys and Enter select actions; confirmation does not require typing `y/n`.
+5. Setup offers the public 1endpoint text-model catalog, with independent Claude tier mappings.
+6. Setup/reconfigure emphasizes restarting the session through the helper.
+
+Do the interactive smoke in a fresh environment or set `ONEENDPOINT_HELPER_HOME` to a new absolute test directory. Setup does not require a real API key. Do not launch inference merely to verify that npm installation works. Use the helper's `remove` action to remove its generated connection configuration afterward; runtime data is intentionally preserved.
+
+Registry propagation and local package-manager caches can briefly lag. Check the exact pinned version before assuming a publish failed. After propagation, also verify the unpinned entry resolves to the intended `latest` release:
+
+```bash
+npx @1endpoint/coding-helper --version
+```
+
+## 7. Finish the release handoff
+
+- Record the released version, source commit, registry integrity and verification outcome.
+- Ensure public setup documentation matches the released CLI rather than unreleased local changes.
+- Deploy Console documentation separately through its normal pipeline if needed. Removing a Console warning does not publish an npm package or prove registry availability.
+- Keep live-provider inference, browser/mobile QA and operating-system coverage distinct from package installation checks.
+
+## Publishing an update
+
+1. Make and review the change.
+2. Update the `version` in `package.json` to a new semantic version. Use a patch release for compatible fixes, a minor release for compatible features, and a major release for breaking changes. Pre-1.0 compatibility expectations should still be documented explicitly.
+3. Run `yarn install` to reconcile the lockfile if necessary, then repeat the checks above.
+4. Commit and push the reviewed release source when authorized.
+5. Publish, then verify the exact new version and the intended distribution tag.
+
+Never overwrite an existing version. For a bad release, prepare a fixed version; consider npm deprecation according to the project's release policy rather than treating unpublish as rollback.
+
+## Troubleshooting
+
+| Symptom | What to check |
+| --- | --- |
+| `401`, `ENEEDAUTH`, or invalid credentials | Repeat `yarn npm login --scope 1endpoint --publish`, then check `whoami`. Confirm the publishing registry and account. |
+| `403` or scope/package permission denied | Confirm organization membership, package creation/publish rights, account security requirements and token restrictions if using token authentication. Login alone is insufficient. |
+| Package not found before the first release | Expected for an unpublished package, but also possible with the wrong registry or inaccessible package. Verify scope ownership and registry configuration. |
+| Version already published | Select a new version; an existing version cannot be replaced. |
+| OTP invalid or expired | Use a fresh code from the publishing account and check the device clock. Do not weaken account security. |
+| `prepack` fails | Fix the syntax/test failure and rerun the release checks. Do not bypass the release gate to publish. |
+| Publish timed out or disconnected | Query the exact version in the registry before attempting another publish. |
+| `npx` cannot find the release immediately | Check exact registry metadata, allow propagation time, and use the pinned version. Confirm you did not publish only under a prerelease tag. |
+| CLI exits because Node is unsupported | Install a Node version satisfying `>=22.19.0` and retry. |
+
+For CI automation, configure npm trusted publishing or appropriately restricted credentials using current npm and CI-provider documentation. Do not assume this local Yarn login procedure configures CI identity, provenance or release approvals.

package/docs/RELEASE.md

@@ -1,5 +1,7 @@
 # Release and verification gate
 
+For the complete maintainer procedure, follow the [npm publishing guide](PUBLISHING.md): account/scope permissions, login, release checks, publication, pinned npx verification, updates and troubleshooting.
+
 ## Scope
 
 Initial package: `@1endpoint/coding-helper@0.1.0`, public npm access. Independent repository: `dothinh115/1endpoint-coding-helper`. First Git commit: `first push`. **Git push does not authorize npm publication.** Maintainer publishes after reviewing the handoff.
@@ -34,7 +36,7 @@ Console checks: focused coding-helper documentation regressions, scoped ESLint,
 - Verify the npm account has publish rights for scope `@1endpoint` and satisfies npm 2FA/trusted-publishing requirements. Never copy npm credentials into repository or chat.
 - Re-run the checks above from the committed source.
 - Maintainer may publish with Yarn's npm publish command, public access, and the desired release tag. This task deliberately does not run it.
-- After publication verify registry version, integrity, bin mapping and real `npx @1endpoint/coding-helper --version` from a fresh environment. Only then remove the Console/docs unpublished warning, commit/deploy the Console update through its normal pipeline, and announce availability.
+- After publication verify registry version, integrity, bin mapping and real `npx @1endpoint/coding-helper --version` from a fresh environment before announcing availability. The Console unpublished warning was removed separately at the user's request; that presentation change is not proof of publication. Commit/deploy Console changes through its normal pipeline when authorized.
 
 ## Verification record
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1endpoint/coding-helper",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Safe isolated 1endpoint setup for DeepSeek Harness and Claude Code CLI",
   "type": "module",
   "bin": {
@@ -42,4 +42,4 @@
     "cli",
     "setup"
   ]
-}
+}