neozip-cli 0.95.0 → 0.95.1

package/CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.95.1] - 2026-07-07
+
+### Documentation
+
+- **[README.md](README.md)** — v0.95.1 release: expanded AI agent integration guide (CLI + JSON, Skills, neozip-mcp), NeoZip Token Service (`connect refresh`, `connect fund`), advanced-feature matrix, and agent workflow documentation.
+
 ## [0.95.0] - 2026-07-03
 
 ### Added
@@ -38,6 +44,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **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).
 
+### Documentation
+
+- **[README.md](README.md)** — updated for v0.95: NeoZip Token Service (`connect refresh`, `connect fund`, silent wallet-login renewal), AI agent integration guide (CLI + JSON, bundled Skills via `neozip skills install`, neozip-mcp), advanced-feature matrix for agents (encryption, compression, blockchain, legacy mode), and agent workflow (schema → dry-run → execute → recover via `nextCommand`).
+- **[AGENTS.md](AGENTS.md)** — engagement rules for machine-readable I/O, schema introspection, dry-run, exit codes, and safety rails.
+- **[skills/](skills/)** — six bundled Agent Skills (`neozip-shared`, `neozip-create`, `neozip-extract`, `neozip-list`, `neozip-connect`, `neozip-legacy`) with per-command guidance for autonomous agents.
+
 ## [0.90.0] - 2026-03-18
 
 ### Added

package/README.md

@@ -8,7 +8,7 @@
 
 ## Release Notice
 
-**Current version: v0.90.0.** This release adds full AES-256 encryption support. See [CHANGELOG.md](CHANGELOG.md) for details.
+**Current version: v0.95.1.** This release adds first-class **AI agent** support (JSON I/O, schema introspection, bundled Skills with `neozip skills install`), deep **NeoZip Token Service** integration (silent token refresh, wallet funding), and `--legacy` InfoZip compatibility. See [CHANGELOG.md](CHANGELOG.md) for details.
 
 - **API Stability**: Command-line interface is becoming more stable but may still change
 - **Testing**: Please test thoroughly and report any issues
@@ -18,8 +18,10 @@
 
 NeoZip CLI is a modern, full-featured ZIP utility that provides:
 
-- **Standard ZIP Compatibility**: ~99% compatible with InfoZip utilities
+- **Standard ZIP Compatibility**: ~99% compatible with InfoZip utilities (`--legacy` for stock `unzip`)
 - **Blockchain Integration**: Tokenize archives and verify integrity on-chain
+- **NeoZip Token Service**: Email-verified timestamps, wallet-linked identity, and testnet gas grants
+- **AI Agent Ready**: Machine-readable JSON I/O, schema introspection, dry-run, and bundled [Skills](skills/)
 - **Advanced Compression**: Zstd, Deflate, and Store compression methods
 - **Encryption Support**: AES-256 (default) and PKZIP encryption
 - **Cross-Platform**: Works on macOS, Linux, and Windows
@@ -48,10 +50,11 @@ NeoZip CLI is a modern, full-featured ZIP utility that provides:
 - Auto-detection of encryption method during extraction
 
 ### Blockchain Features
-- **Tokenization**: Create on-chain tokens for archives
-- **OpenTimestamp**: Bitcoin blockchain timestamping
-- **Token Service**: Ethereum blockchain timestamping (NeoZip Token Service)
-- **Integrity Verification**: Verify archive integrity on-chain
+- **Tokenization (`-b`)**: Create on-chain tokens for archives (signs locally with the Data Wallet)
+- **OpenTimestamp (`-ots`)**: Bitcoin blockchain timestamping
+- **Token Service (`-ts`)**: Ethereum timestamping via the NeoZip Token Service (requires a verified account)
+- **Integrity Verification**: Verify archive integrity on-chain during extract (`neounzip --pre-verify`)
+- **Wallet funding**: Request testnet gas grants via `neozip connect fund`
 - **Network Support**: Base Sepolia, Base Mainnet, Arbitrum, and more
 
 ### Advanced Features
@@ -303,7 +306,7 @@ neolist -1 archive.nzip
 
 ### Account and wallet setup
 
-All wallet identity and Token Service credentials live in the shared connection store (`~/.neozip/connection/`). Use the same profile as NeoZip Desktop and MCP.
+All wallet identity and Token Service credentials live in the shared connection store (`~/.neozip/connection/`). Use the same profile as NeoZip Desktop and the [neozip-mcp](https://github.com/NeoWareInc/neozip-mcp) server.
 
 ```bash
 neozip connect          # Interactive setup (alias: neozip init)
@@ -315,6 +318,38 @@ neozip config           # Connection dashboard (status, prefs, migrate)
 
 On-chain preferences (`defaultNetwork`, custom RPC URLs, gas) are stored in each connection's `public.json`.
 
+### NeoZip Token Service
+
+The Token Service provides email-verified identity, Ethereum timestamps (`-ts`), and optional testnet gas grants. Configuration is read **only** from the connection store — not from env vars or CLI flags.
+
+**Setup (interactive or scripted):**
+
+```bash
+neozip connect register --email you@example.com --json
+neozip connect verify --email you@example.com --code 123456 --json
+neozip connect wallet create --ack-backup --json
+neozip connect finish --json
+```
+
+**Token refresh** — access tokens expire. Renewal prefers a **silent wallet-signature login** (no email round-trip); falls back to email OTP on older deployments:
+
+```bash
+neozip connect refresh --json                              # silent wallet login (preferred)
+neozip connect refresh --email you@example.com --json      # send OTP code
+neozip connect refresh --email you@example.com --code 123456 --json
+```
+
+`-ts` auto-renews an expired token before failing, so timestamping usually needs no manual step. `-b` tokenization and `mint` sign on-chain with the local wallet key and do **not** require a current access token.
+
+**Wallet funding** — on-chain operations need native gas. The Token Service can send a small fixed grant to your primary linked wallet (recipient is server-authoritative):
+
+```bash
+neozip connect fund policy --json    # grant size + cooldown (no auth)
+neozip connect fund status --json    # eligibility and recent grants
+neozip connect fund --json           # request a grant (default action)
+neozip connect fund --network base-sepolia --json
+```
+
 Optional overrides:
 
 ```bash
@@ -383,14 +418,17 @@ neounzip -P "secure-password" secret.nzip decrypted/
 ### Blockchain Features
 
 ```bash
-# Tokenize archive
+# Tokenize archive (on-chain mint; needs gas — run neozip connect fund if low)
 neozip -b tokenized.nzip important-file.txt
 
-# Tokenize with OpenTimestamp
+# Token Service timestamp (needs verified account + current access token)
+neozip -ts timestamped.nzip document.pdf
+
+# OpenTimestamp (Bitcoin)
 neozip -ots timestamped.nzip document.pdf
 
-# Extract and verify
-neounzip tokenized.nzip verified/
+# Extract and verify on-chain integrity
+neounzip --pre-verify tokenized.nzip verified/
 ```
 
 ### Advanced Operations
@@ -414,14 +452,49 @@ neozip -y archive.nzip ./symlinks/
 
 ## For AI agents
 
-NeoZip ships an agent-friendly surface. See [AGENTS.md](AGENTS.md) and the
-[skills/](skills/) directory for the full guide.
+NeoZip is designed for autonomous AI/LLM agents. Every command exposes a stable,
+machine-readable surface alongside its human interface. Agents can integrate via
+three paths:
+
+| Path | When to use |
+|------|-------------|
+| **CLI + JSON** | Direct shell invocation from any agent runtime |
+| **Bundled Skills** | Cursor, Claude Code, or other skill-aware hosts — load from [skills/](skills/) |
+| **neozip-mcp** | MCP-native agents — same `~/.neozip/connection/` store, tool-based API |
+
+Start with [AGENTS.md](AGENTS.md) for engagement rules, then load the relevant
+skill for each task.
+
+### Agent workflow
+
+1. **Introspect** — `neozip schema <neozip|neounzip|neolist|connect>` returns accepted fields, types, defaults, and exit codes.
+2. **Preview** — add `--dry-run` to `neozip`/`neounzip` to resolve the full plan as JSON without writing.
+3. **Execute** — run with `--format json`; parse stdout only (stderr is hints).
+4. **Recover** — on failure, check `error.exitCode` and run `error.nextCommand` when present.
+
+```bash
+neozip schema neozip
+neozip --format json --dry-run \
+  --params '{"level":9,"encrypt":true,"password":"s3cret"}' \
+  --json '{"archive":"out.zip","files":["src/","README.md"]}'
+neozip --format json \
+  --params '{"level":9,"encrypt":true,"password":"s3cret"}' \
+  --json '{"archive":"out.zip","files":["src/","README.md"]}'
+```
 
 ### Install Agent Skills
 
-Six bundled skills (`neozip-shared`, `neozip-create`, `neozip-extract`, `neozip-list`,
-`neozip-connect`, `neozip-legacy`) ship inside the npm package. Install them into
-Claude Code or Cursor after `npm install -g neozip-cli`:
+Six bundled skills ship inside the npm package. Install them into Claude Code or
+Cursor after `npm install -g neozip-cli`:
+
+| Skill | Covers |
+|-------|--------|
+| [neozip-shared](skills/neozip-shared/SKILL.md) | JSON output, `--params`/`--json`, schema, dry-run, exit codes |
+| [neozip-create](skills/neozip-create/SKILL.md) | Archive creation: compression, encryption, blockchain flags |
+| [neozip-extract](skills/neozip-extract/SKILL.md) | Extract, test, verify; zip-slip protection; `--pre-verify` |
+| [neozip-list](skills/neozip-list/SKILL.md) | List archive contents as JSON |
+| [neozip-connect](skills/neozip-connect/SKILL.md) | Token Service setup, refresh, funding |
+| [neozip-legacy](skills/neozip-legacy/SKILL.md) | InfoZip/PKZIP-compatible archives (`--legacy`) |
 
 ```bash
 # Symlink bundled skills into ~/.claude/skills and ~/.cursor/skills
@@ -438,46 +511,75 @@ neozip skills list
 neozip skills pack --output-dir ./neozip-skills-zips
 ```
 
-Alternative (skills registry, same format as Google Workspace CLI):
+Alternative (skills registry):
 
 ```bash
 npx skills add https://github.com/NeoWareInc/neozip-cli
 npx skills add https://github.com/NeoWareInc/neozip-cli/tree/main/skills/neozip-create
 ```
 
-### CLI conventions
+### JSON I/O conventions
+
+- **Output:** `--format json` writes a single object to stdout:
+  - Success: `{ "ok": true, ... }`
+  - Failure: `{ "ok": false, "error": { "code", "exitCode", "message", "nextCommand"? } }`
+- **Input:** `--params '<JSON>'` (control options) and `--json '<JSON>'` (payload: archive + files/targets). Either accepts `-` to read from stdin. Explicit CLI flags override JSON input.
+- **Exit codes:** InfoZip-compatible; echoed in `error.exitCode`. Branch on codes, not message text.
+
+### Advanced features for agents
 
-- **Machine-readable output:** add `--format json` to any command to get a
-  single JSON object on stdout (`{ "ok": true, ... }` or
-  `{ "ok": false, "error": { ... } }`). Human hints go to stderr.
-- **JSON input:** `--params '<JSON>'` (options) and `--json '<JSON>'` (payload:
-  archive + files/targets). Either accepts `-` to read from stdin. Explicit CLI
-  flags override JSON input.
-- **Schema introspection:** `neozip schema <neozip|neounzip|neolist|connect>`
-  emits the accepted fields, types, defaults, and exit codes.
-- **Dry-run:** `neozip`/`neounzip` accept `--dry-run` to resolve and print the
-  plan as JSON without writing anything.
-- **Safety:** archive names and extraction dirs are validated for control
-  characters; `neounzip` refuses zip-slip (entries escaping the target dir).
-- **Exit codes:** InfoZip-compatible and echoed in `error.exitCode`.
+| Feature | Agent params / flags | Prerequisites |
+|---------|---------------------|---------------|
+| AES-256 encryption | `"encrypt": true`, `"password": "…"` | None |
+| PKZIP encryption | `"encryptionMethod": "pkzip"` | None |
+| Zstd compression (default) | `"compression": "zstd"`, `"level": 0–9` | None |
+| InfoZip compatibility | `"legacy": true` | Disables blockchain extensions |
+| On-chain tokenization | `"blockchain": true` | `neozip connect` + gas (`connect fund`) |
+| Token Service timestamp | `"blockchainTokenService": true` | Verified account + access token |
+| OpenTimestamp | `"blockchainOts": true` | None |
+| Pre-verify on extract | `"preVerify": true` | Archive must be tokenized |
+| Network selection | `"network": "base-sepolia"` | Connection `defaultNetwork` or override |
+
+**Blockchain from JSON:**
 
 ```bash
-# Introspect, then create fully from JSON
-neozip schema neozip
+# Tokenize with Token Service timestamp
 neozip --format json \
-  --params '{"level":9,"encrypt":true,"password":"s3cret"}' \
-  --json '{"archive":"out.zip","files":["src/","README.md"]}'
+  --params '{"blockchain":true,"blockchainTokenService":true,"network":"base-sepolia"}' \
+  --json '{"archive":"tokenized.nzip","files":["contract.pdf"]}'
+
+# Extract with on-chain integrity check
+neounzip --format json \
+  --params '{"exdir":"out","preVerify":true}' \
+  --json '{"archive":"tokenized.nzip"}'
+```
 
-# Preview an extraction, then run it
-neounzip --format json --dry-run --params '{"exdir":"out"}' in.zip
-neounzip --format json --params '{"exdir":"out","overwrite":true}' in.zip
+**Token Service from an agent** — use explicit `connect` subcommands (not the interactive wizard):
 
-# List as JSON
-neolist --format json in.zip
+```bash
+neozip connect status --json
+neozip connect refresh --json                    # silent wallet-signature renewal
+neozip connect fund status --json                # check gas eligibility
+neozip connect fund --json                       # request testnet gas
 ```
 
-For an archive that stock InfoZip `unzip` can read, add `--legacy` (forces
-deflate/store + PKZIP, disables NeoZip extensions).
+On config errors, archive commands return `error.nextCommand: "neozip connect"` so the agent can run setup and retry.
+
+### Safety rails
+
+- Archive names and extraction dirs are validated for control characters and dangerous Unicode.
+- `neounzip` refuses zip-slip (entries whose resolved path escapes the target directory).
+- `--dry-run` never touches the filesystem.
+- Treat all agent-supplied paths and IDs as potentially adversarial.
+
+### InfoZip / PKZIP compatibility
+
+Default compression is **zstd**, which stock InfoZip `unzip` cannot read. For consumers that need standard ZIP, pass `--legacy` (forces deflate/store + PKZIP encryption, disables zstd and all NeoZip extensions). Combining `--legacy` with blockchain features is a hard error (exit 10). See [neozip-legacy](skills/neozip-legacy/SKILL.md).
+
+```bash
+neozip --format json --params '{"legacy":true,"level":9}' \
+  --json '{"archive":"compat.zip","files":["src/"]}'
+```
 
 ## Requirements
 
@@ -490,6 +592,8 @@ deflate/store + PKZIP, disables NeoZip extensions).
 The following documentation is included with this package:
 
 - **[README.md](README.md)** - This file, containing installation, usage, and examples
+- **[AGENTS.md](AGENTS.md)** - AI agent engagement rules (JSON I/O, schema, dry-run, exit codes)
+- **[skills/](skills/)** - Bundled agent Skills for create, extract, list, connect, and legacy mode
 - **[WHY_NEOZIP.md](WHY_NEOZIP.md)** - Introduction to NeoZip and its blockchain integration
 - **[CHANGELOG.md](CHANGELOG.md)** - Version history and release notes
 - **[DOCUMENTATION.md](DOCUMENTATION.md)** - Complete documentation index and reference
@@ -585,6 +689,6 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**Version**: 0.90.0
+**Version**: 0.95.1
 **Status**: Release (see [CHANGELOG.md](CHANGELOG.md) for latest changes)
-**Last Updated**: March 18, 2026
+**Last Updated**: July 7, 2026

package/dist/src/account/token-service-funding.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FundingUnavailableError = void 0;
+exports.getFundingPolicy = getFundingPolicy;
+exports.getFundingStatus = getFundingStatus;
+exports.requestFundingGrant = requestFundingGrant;
+/**
+ * Token Service funding API client.
+ *
+ * The Token Service can disburse small native-gas grants to the user's primary
+ * linked Data Wallet so on-chain operations (-b tokenization, -ts timestamp,
+ * -ots) can pay for gas. The recipient is server-authoritative — a client may
+ * only request a grant, never redirect it.
+ *
+ *   GET  /funding/policy?chainId=<id>   (no auth)
+ *   GET  /funding/status?chainId=<id>   (Bearer)
+ *   POST /funding/request               (Bearer, optional Idempotency-Key)
+ */
+const recipient_lookup_1 = require("../archive/recipient-lookup");
+const token_service_fetch_1 = require("../util/token-service-fetch");
+const token_auth_1 = require("../connection/token-auth");
+/** Thrown when the Token Service does not expose the funding endpoints (older deployment). */
+class FundingUnavailableError extends Error {
+    constructor(message = "Token Service does not support funding") {
+        super(message);
+        this.name = "FundingUnavailableError";
+    }
+}
+exports.FundingUnavailableError = FundingUnavailableError;
+async function safeJson(response) {
+    const ct = response.headers.get("content-type") || "";
+    if (!ct.includes("json"))
+        return null;
+    try {
+        return (await response.json());
+    }
+    catch {
+        return null;
+    }
+}
+function extractError(parsed, fallback, options) {
+    const authHint = options?.status != null
+        ? (0, token_auth_1.tokenServiceAuthErrorMessage)(options.status, options.email)
+        : null;
+    if (authHint)
+        return authHint;
+    if (parsed && typeof parsed === "object") {
+        const p = parsed;
+        if (typeof p.error === "string")
+            return p.error;
+        if (typeof p.message === "string")
+            return p.message;
+    }
+    return fallback;
+}
+function baseUrlFor(baseUrl) {
+    return (0, recipient_lookup_1.resolveTokenServiceBaseUrl)({ tokenServiceUrl: baseUrl });
+}
+async function getFundingPolicy(baseUrl, chainId) {
+    const url = baseUrlFor(baseUrl);
+    let res;
+    try {
+        res = await fetch(`${url}/funding/policy?chainId=${encodeURIComponent(String(chainId))}`, {
+            method: "GET",
+        });
+    }
+    catch (err) {
+        throw new Error((0, token_service_fetch_1.formatTokenServiceFetchError)(url, err));
+    }
+    if (res.status === 404) {
+        throw new FundingUnavailableError();
+    }
+    const parsed = await safeJson(res);
+    if (!res.ok || !parsed || parsed.success !== true) {
+        throw new Error(extractError(parsed, `Funding policy lookup failed (HTTP ${res.status})`));
+    }
+    const policy = parsed.policy;
+    if (!policy) {
+        throw new Error("Funding policy response missing policy");
+    }
+    return {
+        chainId: typeof parsed.chainId === "number" ? parsed.chainId : chainId,
+        network: typeof parsed.network === "string" ? parsed.network : "",
+        policy,
+    };
+}
+async function getFundingStatus(baseUrl, accessToken, chainId) {
+    const url = baseUrlFor(baseUrl);
+    let res;
+    try {
+        res = await fetch(`${url}/funding/status?chainId=${encodeURIComponent(String(chainId))}`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+    }
+    catch (err) {
+        throw new Error((0, token_service_fetch_1.formatTokenServiceFetchError)(url, err));
+    }
+    if (res.status === 404) {
+        throw new FundingUnavailableError();
+    }
+    const parsed = await safeJson(res);
+    if (!res.ok || !parsed || parsed.success !== true) {
+        throw new Error(extractError(parsed, `Funding status lookup failed (HTTP ${res.status})`, {
+            status: res.status,
+        }));
+    }
+    return {
+        chainId: typeof parsed.chainId === "number" ? parsed.chainId : chainId,
+        recipientAddress: typeof parsed.recipientAddress === "string" ? parsed.recipientAddress : null,
+        enabled: parsed.enabled === true,
+        requiresPayment: parsed.requiresPayment === true,
+        lastGrantAt: typeof parsed.lastGrantAt === "string" ? parsed.lastGrantAt : null,
+        nextEligibleAt: typeof parsed.nextEligibleAt === "string" ? parsed.nextEligibleAt : null,
+        recentGrants: Array.isArray(parsed.recentGrants)
+            ? parsed.recentGrants
+            : [],
+    };
+}
+async function requestFundingGrant(baseUrl, accessToken, chainId, idempotencyKey) {
+    const url = baseUrlFor(baseUrl);
+    const headers = {
+        Authorization: `Bearer ${accessToken}`,
+        "content-type": "application/json",
+    };
+    if (idempotencyKey) {
+        headers["Idempotency-Key"] = idempotencyKey;
+    }
+    let res;
+    try {
+        res = await fetch(`${url}/funding/request`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ chainId }),
+        });
+    }
+    catch (err) {
+        throw new Error((0, token_service_fetch_1.formatTokenServiceFetchError)(url, err));
+    }
+    if (res.status === 404) {
+        throw new FundingUnavailableError();
+    }
+    const parsed = await safeJson(res);
+    if (!parsed) {
+        // Auth failures and other non-JSON responses.
+        throw new Error((0, token_auth_1.tokenServiceAuthErrorMessage)(res.status, null) ??
+            `Funding request failed (HTTP ${res.status})`);
+    }
+    return parsed;
+}
+//# sourceMappingURL=token-service-funding.js.map