1# Contributing to nzip23Thanks for helping improve nzip. CLI and shared-package work is Deno-first; the Cloudflare Worker4uses Node.js tooling for type generation, tests, and Wrangler.56## Prerequisites78- Deno 2.x9- Node.js 24 and npm10- A Cloudflare account only when testing a real deployment1112Install the repository tooling:1314```sh15npm ci16cd worker17npm ci18```1920## Repository checks2122Run the Deno workspace checks from the repository root:2324```sh25deno task fmt:check26deno task lint27deno task doc28deno task check29deno task test30deno publish --dry-run --allow-dirty31```3233Run the Worker checks from `worker/`:3435```sh36npm run check37npm test38npx wrangler deploy --dry-run39```4041The Worker runtime tests bind localhost and Wrangler writes diagnostic logs. If a sandbox blocks42either operation, rerun the same command with the required permissions rather than treating it as a43code failure.4445## Local Worker development4647Create local secrets from the non-secret example, initialize local D1 state, and start Wrangler:4849```sh50cd worker51cp .dev.vars.example .dev.vars52npx wrangler d1 execute nzip --local --file schema.sql53npm run dev54```5556In another terminal, point the CLI at the local Worker:5758```sh59nzip auth --server http://localhost:8787 --token dev-token-local-only60```6162The example environment sets `SITE_DOMAIN=localhost`, so a committed address is returned as63`http://2a3f.localhost:8787/`. Modern browsers and `curl` resolve `*.localhost` to loopback; the64control shorthand `http://localhost:8787/2a3f` exercises the same permanent redirect used in65production.6667To exercise scheduled handlers, run `npx wrangler dev --test-scheduled`, then request a cron:6869```sh70curl "http://localhost:8787/__scheduled?cron=*/5+*+*+*+*" # alerts and delivery retries71curl "http://localhost:8787/__scheduled?cron=0+4+*+*+*" # GC, pruning, and digest72```7374Local configuration and secrets are ignored by Git. Never commit `.dev.vars` or75`worker/wrangler.local.jsonc`.7677## Project structure7879- `shared/` contains the runtime-neutral wire contract and canonical manifest logic.80- `cli/` contains the Deno command-line client published as `@nzip/cli`.81- `worker/` contains serving, storage, security telemetry, notifications, and scheduled work.8283See [ARCHITECTURE.md](ARCHITECTURE.md) for component boundaries and data flow.8485## Documentation8687Keep documentation portable Markdown:8889- Prefer headings, lists, tables, fenced code blocks, and relative links.90- Avoid raw HTML that only renders correctly on one host.91- Keep user workflows in `README.md`, contributor workflows here, internals in `ARCHITECTURE.md`,92 security guidance in `SECURITY.md`, and deployment operations in `worker/setup.md`.93- Update the CLI help, project README, CLI README, and repo-local skill together when command94 grammar changes.9596## Releases9798Package versions in `cli/deno.json`, `shared/deno.json`, and `shared/version.ts` must match. Tags in99the form `vX.Y.Z` trigger the publication workflow, which validates the workspace, publishes both100JSR packages, and creates the GitHub Release.