neozipkit

neozipkit

Monorepo for NeoZip packages — advanced ZIP file creation, compression, encryption, and blockchain integration.

Beta: neozipkit and neozip-blockchain are published as beta (pre-1.0). See each package README for details.

Packages

Package	Description	npm
neozipkit	ZIP compression, encryption (AES-256, NeoEncrypt), and extraction	neozipkit
neozip-blockchain	Blockchain features: NFT minting, verification, timestamps, wallets	neozip-blockchain

Examples

ZIP-focused sample scripts live under packages/neozipkit/examples/. They are not included in the neozipkit npm tarball (only dist/, src/, and README.md are published); clone this repository to run them. Blockchain-oriented examples are under packages/neozip-blockchain/examples/ (also repo-only).

Getting started

# Install all dependencies (pnpm workspaces)
pnpm install

# Build all packages (topological order: neozipkit first)
pnpm build

# Run unit tests for all packages
pnpm test:unit

Version management

Both packages share the same version number. Use the root scripts to bump:

pnpm version:patch   # 0.7.0 → 0.7.1
pnpm version:minor   # 0.7.0 → 0.8.0
pnpm version:major   # 0.7.0 → 1.0.0
pnpm version:set 1.0.0

Release (automated npm publish)

Publishing is handled by .github/workflows/publish.yml: on push of a tag v* (e.g. v0.7.1), CI builds, tests, publishes neozipkit then neozip-blockchain to npm, and opens a GitHub Release.

One-time GitHub setup

1. Deployment environment (required for the real publish job)
   GitHub → repo Settings → Environments → New environment → name: npm-publish → Configure environment.
   Optional: enable Required reviewers, Wait timer, or Deployment branches so only you (or main / dev) can publish.

2. Authentication (pick one path — not both at once unless you know why):

   A — Trusted Publishing (OIDC, no token in GitHub)

   • On npmjs.com, for each package (neozipkit, neozip-blockchain): Package → Settings → Trusted publishers → GitHub Actions → this repo, workflow file publish.yml, environment name npm-publish (must match the workflow).
   • Do not create a secret named NPM_TOKEN for this path (leave it unset so the job uses OIDC).
   • Requires Node ≥ 22.14 in the workflow (already set). See npm: Trusted publishers.

   B — Classic NPM_TOKEN (CI must bypass publish 2FA)

   • npm returns npm error code EOTP / “requires a one-time password” in GitHub Actions when the token is not allowed to publish without an interactive OTP (common with Classic “Publish” tokens or granular tokens without automation bypass).
   • Fix (pick one token type):
     • Classic → Automation (legacy token type Automation). These are meant for CI and do not require OTP on each publish.
     • Granular access token: when creating the token, enable Bypass two-factor authentication (2FA) for automation (wording on npm may vary) and grant Publish on neozipkit and neozip-blockchain.
   • Create tokens at npm → Access tokens → Generate New Token.
   • Store it in GitHub in one of these places (the publish job uses environment: npm-publish, so either works):
     • Recommended: Settings → Environments → npm-publish → Environment secrets → Add secret → name NPM_TOKEN → paste the token.
     • Alternative: Settings → Secrets and variables → Actions → Repository secrets → New repository secret → name NPM_TOKEN → paste the token.
   • The Publish workflow uses npx --yes npm@11 publish for registry uploads (not the package manager’s publish wrapper).
   • NODE_AUTH_TOKEN is set only when NPM_TOKEN is non-empty (so an empty secret does not block OIDC).
   • If you add NPM_TOKEN, you are using classic auth; you do not need Trusted Publishing configured for CI (you can still use it later and then remove the secret).

   If publish fails with YN0033: No authentication configured or empty NODE_AUTH_TOKEN in the log: the job did not get a token and OIDC did not authenticate. Fix: add NPM_TOKEN under Settings → Environments → npm-publish → Environment secrets (exact name NPM_TOKEN), or under Repository secrets, using an npm Automation or Granular (Publish) token. If you intend to use only Trusted Publishing, confirm both packages on npm have Trusted publishers set to this repo, workflow publish.yml, environment npm-publish.

   If publish fails with EOTP / “This operation requires a one-time password”: your NPM_TOKEN is a type that still requires interactive 2FA for publish. Replace the secret with a Classic Automation token or a Granular token with automation / bypass 2FA for publish (see B above). Then revoke the old token on npm. Alternative: remove NPM_TOKEN from GitHub and use Trusted Publishing (OIDC) only (A).

   Where things live in the GitHub UI (current layout)

   • Repository secrets & variables: Settings → Secrets and variables → Actions (tabs Secrets / Variables).
   • Environment secrets & variables: Settings → Environments → select npm-publish → Environment secrets / Environment variables.

Release steps

1. Bump both package versions: pnpm version:patch (or version:minor / version:major).
2. Commit and tag: git commit -am "release: v0.7.1" && git tag v0.7.1.
3. Push branch and tags: git push origin <branch> && git push origin v0.7.1.
4. The tag must match version in both packages/neozipkit/package.json and packages/neozip-blockchain/package.json (the workflow enforces this).

“Re-run” does not load a newer workflow file

GitHub Actions pins each run to the commit that started it. Re-run failed jobs / Re-run all jobs replays the same commit — including .github/workflows/publish.yml from that SHA. Updating the file on main later does nothing to an old run.

To use an updated workflow:

• Tag publish: push a new tag whose target commit already contains the new workflow (e.g. delete the remote tag and push it again only if you accept rewriting that tag), or release a new version tag (v0.7.1, …).
• Manual dry run: Actions → Publish → Run workflow → pick a branch whose tip commit has the new YAML (then click Run workflow). That creates a new run, not a re-run.

On the run summary page, open “X workflow runs” / commit line and confirm the commit SHA matches the commit where you changed publish.yml.

Dry run (no publish)

In GitHub (manual trigger):

Do not use Settings → Actions → General / Runners / OIDC. That screen only configures Actions for the repo (permissions, self-hosted runners, OpenID Connect for cloud deployments). It does not list workflows or offer Run workflow.

Use the Actions item in the top repository navigation bar (same row as Code, Issues, Pull requests). Direct URL pattern: https://github.com/<org>/<repo>/actions.

1. Open the repo → click Actions in the top bar (not under Settings).
2. In the left sidebar, under “All workflows”, click Publish (from name: Publish in .github/workflows/publish.yml).
3. Click Run workflow (right side) → choose branch → leave npm_dry_run checked → Run workflow.

If “Publish” does not appear: The workflow file must exist on the default branch (often main) for Run workflow to show. Merge .github/workflows/publish.yml to main if needed. Under Settings → Actions → General, ensure Actions permissions allow workflows (that’s the only Settings → Actions step most repos need).

Locally (same checks, no GitHub UI):

pnpm install --frozen-lockfile && pnpm build && pnpm test:quick
pnpm --filter neozipkit publish:dry-run
pnpm --filter neozip-blockchain publish:dry-run

Publish a single package from anywhere under the repo (correct cwd is handled for you):

pnpm publish:neozipkit
pnpm publish:neozip-blockchain

Manual fallback

From the monorepo root: pnpm publish:all (requires local npm login / token).

GitHub Actions: “Node.js 20 actions are deprecated” / still mentions @v4

Workflows use actions/checkout@v6.0.2 and actions/setup-node@v6.3.0, plus workflow env FORCE_JAVASCRIPT_ACTIONS_TO_NODE24=true (GitHub changelog).

If the run log still lists actions/checkout@v4 / actions/setup-node@v4, GitHub is using an older copy of the workflow (common causes: changes not pushed, Run workflow branch doesn’t have the update, or you opened a re-run of an old job). Fix: merge/push the workflow to the branch you select in Run workflow, then start a new workflow run (not re-run). On the run page, confirm the commit SHA matches the commit that contains .github/workflows/publish.yml with @v6.

The tag publish job also uses softprops/action-gh-release@v2, which still declares Node 20; you may see a separate deprecation line for that action until upstream ships a Node 24 runtime.

License

MIT — Copyright (c) NeoWare, Inc.