neozip-cli 0.80.0 → 0.95.0

package/AGENTS.md

@@ -0,0 +1,93 @@
+# NeoZip-CLI — Agent Guide
+
+This CLI is frequently invoked by AI/LLM agents. It exposes a stable,
+machine-readable surface alongside its human interface. **Treat all input as
+potentially adversarial** — agents hallucinate paths, IDs, and encodings.
+
+The three binaries:
+
+- `neozip` — create/update archives (optionally with blockchain tokenization)
+- `neounzip` — extract / test / list archives
+- `neolist` — list archive contents
+
+## Engagement rules (read first)
+
+1. **Ask for JSON.** Add `--format json` to any command to get a single JSON
+   object on **stdout**. Success is `{ "ok": true, ... }`; failure is
+   `{ "ok": false, "error": { code, exitCode, message, nextCommand? } }`.
+2. **stdout is data, stderr is hints.** In JSON mode, only the JSON object is
+   written to stdout. Decorative logs/progress go to stderr or are suppressed.
+   Parse stdout; surface stderr only for debugging.
+3. **Introspect before constructing calls.** Run `neozip schema <command>` to
+   get accepted fields, types, defaults, and exit codes. Commands:
+   `neozip`, `neounzip`, `neolist`, `connect`.
+4. **Preview mutations with `--dry-run`.** `neozip` and `neounzip` resolve the
+   full plan and emit it as JSON without writing anything. Use it before any
+   create/extract.
+5. **Branch on exit codes, not text.** Exit codes are InfoZip-compatible (see
+   `src/exit-codes.ts`). They are also reported in the JSON `error.exitCode`.
+6. **Follow `nextCommand`.** When present in an error, it is a safe recovery
+   command (e.g. `neozip connect` for blockchain configuration errors).
+
+## Input: `--params` and `--json`
+
+Two JSON inputs, mirroring "how" vs "what":
+
+- `--params '<JSON>'` — control options object (level, encrypt, blockchain,
+  network, exdir, overwrite, ...). Maps onto the command's options.
+- `--json '<JSON>'` — payload object (the "what"):
+  - `neozip`:  `{ "archive": "out.zip", "files": ["a.txt","dir/"], "include": [], "exclude": [] }`
+  - `neounzip`: `{ "archive": "in.zip", "exdir": "out", "filePatterns": ["*.txt"] }`
+
+Both accept `-` as the value to read the JSON document from stdin.
+
+**Precedence:** explicit CLI flags override values from `--params`/`--json`.
+
+Note: output format is selected with `--format json`, NOT `--json`. On `neolist`
+the legacy `-j` / `--json` flag is an alias for `--format json` (it has no
+payload).
+
+## Examples
+
+```bash
+# Introspect
+neozip schema neozip
+
+# Create (agent-style, fully JSON-driven)
+neozip --format json \
+  --params '{"level":9,"encrypt":true,"password":"s3cret"}' \
+  --json '{"archive":"out.zip","files":["src/","README.md"]}'
+
+# Preview an extraction without writing
+neounzip --format json --dry-run --params '{"exdir":"out"}' in.zip
+
+# Extract
+neounzip --format json --params '{"exdir":"out","overwrite":true}' in.zip
+
+# List
+neolist --format json in.zip
+```
+
+## Safety rails (enforced by the CLI)
+
+- **Control characters / dangerous Unicode** in archive names and extraction
+  dirs are rejected (`src/cli/validate.ts`).
+- **Zip-slip protection:** `neounzip` refuses any entry whose resolved output
+  path escapes the target directory.
+- **`--dry-run`** never touches the filesystem.
+
+## InfoZip / PKZIP compatibility
+
+- Default compression is **zstd**, which stock InfoZip `unzip` cannot read.
+- Pass `--legacy` to `neozip` to produce a standard archive readable by stock
+  `unzip`: it forces deflate (or store at `-0`) + PKZIP encryption and disables
+  all NeoZip extensions (zstd, blockchain `-b`/`-bd`/`-bm`, `-ots`, `-ts`).
+- `--legacy` combined with blockchain features is a hard error (exit 10).
+
+## Where things live
+
+- Shared agent layer: `src/cli/` (`output.ts`, `params.ts`, `validate.ts`, `schema.ts`)
+- Exit codes: `src/exit-codes.ts`
+- Connection store / `neozip connect`: `src/connect/`, `src/connection/`
+- MCP server is **not** in this repo; it lives in `neozip-mcp` and shares the
+  same `~/.neozip/connection/` store.

package/CHANGELOG.md

@@ -5,6 +5,122 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+**Release notes** for each version are documented here (not in a separate “what’s new” file).
+
+## [Unreleased]
+
+## [0.95.0] - 2026-07-03
+
+### Added
+
+- **AI-agent support** — machine-readable mode across `neozip`, `neounzip`, and `neolist`:
+  - `--format json` emits a single structured JSON object on stdout (`{ "ok": true, ... }` / `{ "ok": false, "error": { code, exitCode, message, nextCommand? } }`); human hints stay on stderr.
+  - `--params '<JSON>'` (control options) and `--json '<JSON>'` (payload: archive + files/targets) input flags; both accept `-` to read from stdin. Explicit CLI flags override JSON input.
+  - `neozip schema <neozip|neounzip|neolist|connect>` introspection command emits accepted fields, types, defaults, and exit codes.
+  - `--dry-run` on `neozip`/`neounzip` resolves and prints the plan as JSON without writing.
+  - Structured JSON errors mapped from `src/exit-codes.ts`, with `nextCommand` recovery hints (InfoZip-compatible exit codes preserved).
+  - Input hardening: control-character/Unicode rejection on names and extraction dirs; zip-slip protection refuses entries that escape the extraction directory.
+  - Agent docs and skills: [AGENTS.md](AGENTS.md) and [skills/](skills/) (`neozip-shared`, `neozip-create`, `neozip-extract`, `neozip-list`, `neozip-legacy`, `neozip-connect`).
+- **`neozip skills`** — install bundled Agent Skills from the npm package: `path`, `list`, `install` (symlink into `~/.claude/skills` and/or `~/.cursor/skills`), and `pack` (ZIP per skill for Claude Cowork / claude.ai upload). Skills ship in the tarball under `skills/`.
+- **`neozip --legacy`** — produce an InfoZip/PKZIP-compatible archive (forces deflate/store + PKZIP encryption, disables zstd and all blockchain extensions) readable by stock `unzip`. Combining `--legacy` with blockchain features is a parameter error.
+- **`neozip connect refresh`** — renew an expired Token Service access token without disturbing the wallet/identity. Prefers a **silent wallet-signature login** (no email round-trip) when the Token Service supports it, and falls back to the email OTP flow otherwise. `connect status` now reports access-token expiry (`accessTokenExpired` / `accessTokenExpiresAt` in JSON; an "Access token" line in text).
+- **Automatic token renewal for `-ts`** — before a Token Service timestamp, an expired access token is silently renewed via wallet signature when possible, so timestamping "just works" without a manual refresh.
+- **`neozip connect fund`** — request native gas for the local Data Wallet from the Token Service funding API. Subactions: `request` (default; sends the policy-defined grant to your primary linked wallet), `status` (eligibility + recent grants), and `policy` (grant size/cooldown, no auth). Accepts `--network NAME` / `--chain ID` and `--json`; an expired access token is silently renewed via wallet signature first. The recipient is server-authoritative — the client cannot redirect funds. Wallet/insufficient-balance error messages across `-b`, `-ts`, `-ots`, and `--upgrade` now point to `neozip connect fund` (with the public faucet kept as a fallback).
+
+### Changed
+
+- **Token Service HTTP clients moved to `neozip-blockchain`** — the account-auth (email/code, magic link, silent wallet-login, phone OTP), funding, and wallet/identity-key HTTP clients now live in `neozip-blockchain/token-service` (v0.8.0) and are shared with NeoZip Desktop and MCP. The CLI keeps only the local orchestration that needs the wallet private key (`runWalletEnsureAndAttach` in `src/account/wallet-setup.ts`) and product-specific UX (token-expiry guidance in `src/connection/token-auth.ts`). No user-facing command behavior changes; the library emits generic auth errors and the CLI maps them to `neozip connect refresh` guidance.
+- **Production dependencies** — `neozipkit` and `neozip-blockchain` updated to `^0.8.0` (npm).
+- **Development workflow** — pnpm-only from source (`engines.pnpm` `>=10.0.0`); Yarn config removed. Use `pnpm install`, `pnpm build`, and `pnpm test`.
+
+### Fixed
+
+- **Blockchain tokenization (`-b`) blocked by an expired Token Service token** — `-b` and on-chain `mint` sign locally with the wallet key and never use the Token Service access token, but the readiness gate required a non-expired token for them. The gate now distinguishes on-chain abilities (wallet only) from Token Service abilities (`-ts`, which still require a current token), and expired-token errors now point to `neozip connect refresh`.
+- **`pack:dry-run` script** — use `npm pack --dry-run` (pnpm has no `--dry-run` flag).
+
+## [0.90.0] - 2026-03-18
+
+### Added
+
+- **`neozip connect`** — Token Service account setup subcommand (status, register, verify, wallet, finish, migrate). Shares `~/.neozip/connection/` with NeoZip Desktop and MCP (`neozip-connect` from neozip-mcp).
+- **Connection store bootstrap** — non-blocking startup read of active connection; gated operations (`-ts`, mint) require connect readiness with actionable guidance.
+
+### Changed
+
+- **Unified wallet** — all blockchain operations (`-b`, `-ts`, mint) use the connection store wallet (`secrets.enc`); `wallet.json` retired. `neozip init` is an alias for `neozip connect`. On-chain prefs (`defaultNetwork`, RPC, gas) live on `public.json`.
+- **Token Service configuration** — URL, verified email, and access token are read **only** from the connection store (`~/.neozip/connection/`), not from `wallet.json`, env vars, or CLI flags.
+- **Package manager** — development workflow uses pnpm (`packageManager: pnpm@10.12.1`); use `pnpm install` and `pnpm build` from source.
+
+### Removed
+
+- **`~/.neozip/wallet.json`** — migrate via `neozip connect migrate`; archived as `wallet.json.migrated`.
+- **`NEOZIP_WALLET_PASSKEY`** as user-facing configuration (connection store only; `-w` remains for one-off overrides).
+
+- **`neozip verify-email`** command and `npm run verify-email` script — use `neozip connect` instead.
+- **`--timestamp-email`** flag and `wallet.json` `tokenService.timestampEmail` — configure via `neozip connect`.
+- **`TOKEN_SERVICE_URL`**, **`NEOZIP_TIMESTAMP_EMAIL`** runtime env vars for Token Service operations.
+
+### Added (encryption)
+
+- **Full AES-256 encryption support** — create, list, and extract password-protected archives with WinZip-compatible AES-256 (default) or legacy PKZIP encryption.
+
+#### Creating encrypted archives
+
+- **AES-256 (default)** — use `-e` / `--encrypt` or `--aes256`.
+
+  ```bash
+  neozip -e secure.nzip file.txt
+  neozip -e -P "mypassword" secure.nzip file.txt
+  neozip --aes256 -P "mypassword" secure.nzip file.txt folder/
+  ```
+
+- **Legacy PKZIP** — use `--pkzip` or `--pkzip-encrypt` only for older-tool compatibility (weak; prefer AES-256 for sensitive data).
+
+  ```bash
+  neozip --pkzip -P "mypassword" legacy.nzip file.txt
+  ```
+
+#### Listing encrypted archives
+
+- **neolist** lists contents; filenames are visible without a password. Encryption method (AES-256 or PKZIP) is shown where applicable. Extraction requires the password.
+
+#### Extracting encrypted archives
+
+- **neounzip** auto-detects AES-256 vs PKZIP. Use `-P` / `--password`.
+
+  ```bash
+  neounzip -P "mypassword" secure.nzip output/
+  neounzip --in-memory -P "mypassword" secure.nzip output/
+  ```
+
+- Wrong password yields a clear error (e.g. bad password / decryption failed).
+
+#### Compatibility
+
+- **AES-256**: WinZip, 7-Zip, and other tools supporting ZIP AES extension (AE-2).
+- **PKZIP** (ZipCrypto): create/extract legacy archives only.
+
+#### Encryption options summary
+
+| Command   | Option             | Effect |
+|-----------|--------------------|--------|
+| neozip    | `-e`, `--encrypt`  | AES-256 (default); prompt if no `-P` |
+| neozip    | `--aes256`         | Explicit AES-256 |
+| neozip    | `--pkzip`          | Legacy PKZIP encryption |
+| neozip    | `-P`, `--password`| Encryption password |
+| neounzip  | `-P`, `--password` | Decryption password (AES-256/PKZIP auto-detected) |
+| neounzip  | `--pkzip-decrypt`  | Force legacy PKZip 2.0 decryption |
+
+See [README.md](README.md) and [DOCUMENTATION.md](DOCUMENTATION.md) for more examples.
+
+### Changed
+
+- **Dependencies**: `neozipkit` and `neozip-blockchain` updated to **^0.7.2** (latest).
+- **Token service API**: imports migrated from `neozip-blockchain/zipstamp-server` to `neozip-blockchain/token-service`; `getZipStampServerUrl()` replaced by `getTokenServiceUrl()`. Configure the server with `TOKEN_SERVICE_URL` (see `env.example`).
+- **ZipStamp → Token Service rename**: all user-facing "Zipstamp" terminology replaced with "Token Service"; `wallet.json` key `zipstamp.timestampEmail` removed in favor of `tokenService.timestampEmail`; CLI flags `--zipstamp-auto-upgrade` / `--zipstamp-skip-upgrade` replaced with `--token-service-auto-upgrade` / `--token-service-skip-upgrade`.
+
+---
+
 ## [0.80.0] - 2026-03-04
 
 ### Added
@@ -18,20 +134,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Configuration**
   - `neozip config` and `neozip init` work when run via ts-node (fixed dynamic import resolution for `.ts` vs `.js`)
 
-### Changed
-
-- User-facing copy now uses "blockchain" instead of "Ethereum blockchain" for Zipstamp and mint flows
-- Zipstamp verification in `neounzip` shows "Zipstamp (blockchain timestamp)" instead of "Ethereum timestamp"
-- Help text: `-ts, --timestamp` described as "Enable Zipstamp timestamp (blockchain)"
-
 ### Fixed
 
-- `neozip config` / `neozip init` no longer fail with "Cannot find module './config/ConfigSetup.js'" when run via `yarn neozip-config` or ts-node
-
-### Security
-
-- `.env.*` (including `.env.local`, `.env.local.rem`) added to `.gitignore` to avoid committing secrets
-- Documented how to purge env files from git history if they were ever committed
+- `neozip config` / `neozip init` no longer fail with "Cannot find module './config/ConfigSetup.js'" when run via `pnpm neozip-config` or ts-node
 
 ---
 

package/DOCUMENTATION.md

@@ -47,11 +47,9 @@ neolist --help     # Show listing help
   - NeoZip ecosystem overview
   - Technical innovations
 
-- **[CHANGELOG.md](CHANGELOG.md)** - Version history
-  - Release notes
-  - Feature additions
-  - Known limitations
-  - Breaking changes
+- **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes
+  - Detailed changes per version (including feature guides, e.g. AES-256 in v0.90.0)
+  - Known limitations and breaking changes
 
 - **[env.example](env.example)** - Environment variable configuration
   - Wallet configuration
@@ -98,10 +96,15 @@ neolist --help     # Show listing help
   - No compression (fastest)
   - Useful for already-compressed files
 
-- **PKZIP Encryption**
-  - Legacy encryption for maximum compatibility
+- **AES-256 Encryption** (default, recommended)
+  - Strong WinZip-compatible AES-256 encryption
   - Password-protected archives
-  - InfoZip-compatible encrypted archives
+  - Compatible with WinZip, 7-Zip, and other AES-capable tools
+
+- **PKZIP Encryption** (legacy)
+  - Traditional encryption for maximum compatibility
+  - Use `--pkzip` flag to select
+  - Not recommended for sensitive data
 
 ### Blockchain Features
 
@@ -116,16 +119,16 @@ neolist --help     # Show listing help
   - Cryptographic proof of archive existence
   - Timestamp verification
 
-- **Zipstamp**
-  - Ethereum blockchain timestamping via Zipstamp server
+- **Token Service**
+  - Ethereum blockchain timestamping via NeoZip Token Service
+  - Account setup via `neozip connect` (shared store at `~/.neozip/connection/`)
   - Pending timestamps (TS-SUBMIT.NZIP) can be upgraded to confirmed (TIMESTAMP.NZIP)
   - Use `neozip upgrade <archive> [output] [--wait]` to upgrade pending timestamps
 
 - **Wallet Integration**
-  - Interactive wallet setup wizard (`neozip init`)
-  - Configuration management (`neozip config`)
-  - Environment variable support
-  - Secure wallet key storage
+  - Token Service account and wallet via `neozip connect` (alias: `neozip init`)
+  - Connection dashboard (`neozip config`) and `neozip connect settings` for on-chain prefs
+  - Wallet key in encrypted `secrets.enc` under `~/.neozip/connection/`
 
 ### Advanced Features
 
@@ -139,44 +142,36 @@ neolist --help     # Show listing help
 
 ## 🔧 Configuration
 
-### Wallet Setup
-
-For blockchain features, configure your wallet:
+### Account, wallet, and on-chain preferences
 
 ```bash
-# Interactive setup wizard
-neozip init
-
-# View or modify configuration
-neozip config
+neozip connect          # Setup (alias: neozip init)
+neozip connect status
+neozip connect settings # default network, RPC, gas
+neozip config           # dashboard
+neozip connect migrate  # legacy wallet.json → connection store
 
-# Upgrade pending Zipstamp timestamp to confirmed
+# Upgrade pending Token Service timestamp
 neozip upgrade archive.nzip [output.nzip] [--wait]
 ```
 
-Configuration is stored in `~/.neozip/wallet.json` and supports:
-- Wallet private key
-- Network selection (testnet/mainnet)
-- Custom RPC endpoints
-- Gas settings
-- Debug options
+Store: `~/.neozip/connection/` (see [dev_doc/CONNECTION_CLI_PREFS.md](dev_doc/CONNECTION_CLI_PREFS.md)).
 
-### Environment Variables
+### Environment Variables (optional session overrides)
 
-You can also configure via environment variables (see [env.example](env.example)):
-- `NEOZIP_WALLET_PASSKEY` - Wallet private key
-- `NEOZIP_NETWORK` - Blockchain network
-- `NEOZIP_BASE_SEPOLIA_RPC_URL` - Custom RPC endpoints
-- `NEOZIP_VERBOSE` - Enable verbose logging
-- `NEOZIP_DEBUG` - Enable debug mode
+See [env.example](env.example):
+- `NEOZIP_NETWORK` — override default network for this process
+- `NEOZIP_BASE_SEPOLIA_RPC_URL` — override RPC for this process
+- `NEOZIP_CONNECTION_DIR`, `NEOZIP_UNLOCK_PASSPHRASE` — connection store
+- `NEOZIP_VERBOSE`, `NEOZIP_DEBUG`, `NEOZIP_GAS_MULTIPLIER`, `NEOZIP_MAX_GAS_PRICE`
 
 ## 📚 Reading Order
 
 1. **Start with** [README.md](README.md) for installation and basic usage
 2. **Read** [WHY_NEOZIP.md](WHY_NEOZIP.md) to understand the project vision
 3. **Review** [CHANGELOG.md](CHANGELOG.md) for version history and known issues
-4. **Configure** wallet using `neozip init` for blockchain features
-5. **Reference** [env.example](env.example) for environment variable configuration
+4. **Configure** via `neozip connect` for blockchain features
+5. **Reference** [env.example](env.example) for optional environment overrides
 
 ## 🔗 Related Links