neozip-cli 0.90.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

@@ -7,10 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 **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
@@ -62,6 +113,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 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
@@ -79,7 +136,7 @@ See [README.md](README.md) and [DOCUMENTATION.md](DOCUMENTATION.md) for more exa
 
 ### Fixed
 
-- `neozip config` / `neozip init` no longer fail with "Cannot find module './config/ConfigSetup.js'" when run via `yarn neozip-config` or ts-node
+- `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

@@ -119,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
 
@@ -142,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
 

package/README.md

@@ -50,7 +50,7 @@ NeoZip CLI is a modern, full-featured ZIP utility that provides:
 ### Blockchain Features
 - **Tokenization**: Create on-chain tokens for archives
 - **OpenTimestamp**: Bitcoin blockchain timestamping
-- **Zipstamp**: Ethereum blockchain timestamping (Zipstamp server)
+- **Token Service**: Ethereum blockchain timestamping (NeoZip Token Service)
 - **Integrity Verification**: Verify archive integrity on-chain
 - **Network Support**: Base Sepolia, Base Mainnet, Arbitrum, and more
 
@@ -69,7 +69,8 @@ NeoZip CLI is a modern, full-featured ZIP utility that provides:
 ### Prerequisites
 
 - Node.js 16.0.0 or higher
-- npm or yarn package manager
+- [pnpm](https://pnpm.io/) 10+ (required for development from source)
+- npm (optional — for global install of the published package only)
 
 ### Install from npm
 
@@ -164,11 +165,11 @@ neozip -b tokenized.nzip file.txt
 # Tokenize with OpenTimestamp proof (Bitcoin)
 neozip -ots timestamped.nzip file.txt
 
-# Create Zipstamp timestamp (Ethereum)
-neozip -ts zipstamp.nzip file.txt
+# Create Token Service timestamp (Ethereum)
+neozip -ts timestamped.nzip file.txt
 
-# Upgrade pending Zipstamp timestamp to confirmed
-neozip upgrade zipstamp.nzip [output.nzip] [--wait]
+# Upgrade pending Token Service timestamp to confirmed
+neozip upgrade timestamped.nzip [output.nzip] [--wait]
 
 # Extract and verify blockchain integrity
 neounzip tokenized.nzip tests/extracted/
@@ -196,17 +197,16 @@ neozip [options] <archive> [files...]
 - `--pkzip` - Use legacy PKZIP encryption (weak, for compatibility only)
 - `-b, --blockchain` - Enable blockchain tokenization
 - `-ots, --opentimestamp` - Enable OpenTimestamp proof (Bitcoin)
-- `-ts, --timestamp` - Enable Zipstamp timestamp (Ethereum)
-- `--timestamp-email <email>` - Email for Zipstamp server (some servers require verified email)
+- `-ts, --timestamp` - Enable Token Service timestamp (Ethereum; requires `neozip connect`)
 - `-T, --test-integrity` - Test archive after creation
 - `-v, --verbose` - Enable verbose output
 - `-q, --quiet` - Suppress output
 
 **Configuration Commands:**
 ```bash
-neozip init      # Interactive wallet setup wizard
-neozip config    # Show current configuration
-neozip upgrade <archive> [output] [--wait]  # Upgrade pending Zipstamp timestamp to confirmed
+neozip connect   # Token Service account + wallet setup (alias: neozip init)
+neozip config    # Connection dashboard (status, prefs, migrate)
+neozip upgrade <archive> [output] [--wait]  # Upgrade pending Token Service timestamp to confirmed
 ```
 
 **Examples:**
@@ -301,41 +301,26 @@ neolist -1 archive.nzip
 
 ## Configuration
 
-### Wallet Setup (for Blockchain Features)
+### Account and wallet setup
 
-To use blockchain features, you need to configure a wallet:
+All wallet identity and Token Service credentials live in the shared connection store (`~/.neozip/connection/`). Use the same profile as NeoZip Desktop and MCP.
 
 ```bash
-# Interactive setup wizard
-neozip init
+neozip connect          # Interactive setup (alias: neozip init)
+neozip connect status   # Show connection phase and credentials
+neozip connect settings # Default network, RPC overrides, gas prefs
+neozip connect migrate  # Import legacy wallet.json / MCP profiles
+neozip config           # Connection dashboard (status, prefs, migrate)
 ```
 
-This will guide you through:
-1. Creating or importing a wallet
-2. Selecting a blockchain network
-3. Saving configuration to `~/.neozip/wallet.json`
+On-chain preferences (`defaultNetwork`, custom RPC URLs, gas) are stored in each connection's `public.json`.
 
-### Environment Variables
-
-You can also configure via environment variables:
+Optional overrides:
 
 ```bash
-export NEOZIP_WALLET_PASSKEY="your-wallet-key"
-export NEOZIP_NETWORK="base-sepolia"  # or base-mainnet, arbitrum-sepolia, etc.
-export ZIPSTAMP_SERVER_URL="https://zipstamp-dev.neozip.io"  # Zipstamp server (optional)
-export NEOZIP_TIMESTAMP_EMAIL="your@email.com"  # Email for Zipstamp (some servers require verified email)
-```
-
-### Configuration File
-
-Configuration is stored in `~/.neozip/wallet.json`:
-
-```json
-{
-  "walletKey": "0x...",
-  "network": "base-sepolia",
-  "rpcUrl": "https://..."
-}
+export NEOZIP_CONNECTION_DIR="/path/to/connection"  # Store path override
+export NEOZIP_UNLOCK_PASSPHRASE="..."               # Decrypt secrets.enc non-interactively
+export NEOZIP_NETWORK="base-sepolia"                # Override default network for this session
 ```
 
 ## Advanced Examples
@@ -427,6 +412,73 @@ neozip -X archive.nzip ./files/
 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.
+
+### 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`:
+
+```bash
+# Symlink bundled skills into ~/.claude/skills and ~/.cursor/skills
+neozip skills install
+
+# Claude Code only
+neozip skills install --target claude
+
+# Show where skills live in your install
+neozip skills path
+neozip skills list
+
+# ZIP files for Claude Cowork / claude.ai upload (Customize > Skills)
+neozip skills pack --output-dir ./neozip-skills-zips
+```
+
+Alternative (skills registry, same format as Google Workspace CLI):
+
+```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
+
+- **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`.
+
+```bash
+# Introspect, then create fully from JSON
+neozip schema neozip
+neozip --format json \
+  --params '{"level":9,"encrypt":true,"password":"s3cret"}' \
+  --json '{"archive":"out.zip","files":["src/","README.md"]}'
+
+# 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
+
+# List as JSON
+neolist --format json in.zip
+```
+
+For an archive that stock InfoZip `unzip` can read, add `--legacy` (forces
+deflate/store + PKZIP, disables NeoZip extensions).
+
 ## Requirements
 
 - **Node.js**: 16.0.0 or higher
@@ -479,11 +531,11 @@ neozip new-archive.nzip original-files/
 
 **Blockchain errors:**
 ```bash
-# Check wallet configuration
-neozip config
+# Check connection status
+neozip connect status
 
-# Reconfigure wallet
-neozip init
+# Re-run setup
+neozip connect
 ```
 
 **Encryption errors:**
@@ -503,6 +555,16 @@ We welcome feedback and contributions:
 2. **Suggest Features**: Share your ideas and use cases
 3. **Test and Provide Feedback**: Help us improve by testing and reporting your experience
 
+### Development setup
+
+Requires [pnpm](https://pnpm.io/) (`packageManager: pnpm@10.12.1`):
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+```
+
 **Important**: Please test thoroughly and report issues. See [CHANGELOG.md](CHANGELOG.md) for version history.
 
 ## License

package/dist/src/account/account-state.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeAccountPhase = computeAccountPhase;
+exports.buildAccountStatusReport = buildAccountStatusReport;
+const token_service_1 = require("neozip-blockchain/token-service");
+const mask_1 = require("../util/mask");
+const profile_store_1 = require("./profile-store");
+const token_auth_1 = require("../connection/token-auth");
+function nextStepsForPhase(phase) {
+    switch (phase) {
+        case "no_profile":
+            return (0, profile_store_1.listProfiles)().length > 0
+                ? ["account_select", "account_list", "account_create"]
+                : ["account_create", "account_list"];
+        case "email_unverified":
+            return ["account_register_email", "account_verify_email"];
+        case "no_wallet":
+            return ["account_create_wallet", "account_import_wallet"];
+        case "wallet_unlinked":
+            return ["account_link_wallet"];
+        case "identity_missing":
+            return ["account_provision_identity"];
+        case "ready":
+            return ["account_logout"];
+        case "degraded":
+            return ["account_status"];
+        default:
+            return ["account_status"];
+    }
+}
+function computeAccountPhase() {
+    const profileId = (0, profile_store_1.getActiveProfileId)();
+    if (!profileId) {
+        return "no_profile";
+    }
+    const profile = (0, profile_store_1.getActiveProfile)();
+    const secrets = (0, profile_store_1.readActiveSecrets)();
+    if (!profile || !secrets)
+        return "no_profile";
+    if (!secrets.accessToken || !profile.emailVerified) {
+        return "email_unverified";
+    }
+    if (!secrets.evmPrivateKey || !profile.evmAddress) {
+        return "no_wallet";
+    }
+    if (!profile.walletId || profile.linkId == null) {
+        return "wallet_unlinked";
+    }
+    if (!profile.identityKeyId) {
+        return "identity_missing";
+    }
+    return "ready";
+}
+async function buildAccountStatusReport(options) {
+    const profile = (0, profile_store_1.getActiveProfile)();
+    const secrets = (0, profile_store_1.readActiveSecrets)();
+    const phase = computeAccountPhase();
+    const tokenExpiresAt = secrets?.accessTokenExpiresAt ?? null;
+    const tokenExpired = Boolean(secrets?.accessToken) && (0, token_auth_1.isAccessTokenExpired)(secrets);
+    const tokenServiceUrl = (0, token_service_1.getTokenServiceUrl)({
+        serverUrl: profile?.tokenServiceUrl || undefined,
+    });
+    let tokenServiceReachable = null;
+    if (options?.probeTokenService !== false) {
+        try {
+            tokenServiceReachable = await (0, token_service_1.fetchCoordinatorConfig)(tokenServiceUrl);
+        }
+        catch {
+            tokenServiceReachable = false;
+        }
+    }
+    const nextSteps = nextStepsForPhase(tokenServiceReachable === false && phase !== "ready" ? "degraded" : phase);
+    const reloadRequired = phase === "ready" &&
+        Boolean(profile &&
+            (!process.env.NEOZIP_TOKEN_SERVICE_ACCESS_TOKEN ||
+                !process.env.NEOZIP_WALLET_PASSKEY));
+    return {
+        success: true,
+        phase: tokenServiceReachable === false && phase !== "ready" ? "degraded" : phase,
+        activeProfileId: (0, profile_store_1.getActiveProfileId)(),
+        profile: profile
+            ? {
+                ...profile,
+                email: profile.email ? (0, mask_1.maskEmail)(profile.email) : null,
+            }
+            : null,
+        tokenServiceReachable,
+        tokenServiceUrl,
+        tokenExpiresAt,
+        tokenExpired,
+        nextSteps,
+        reloadRequired,
+    };
+}
+//# sourceMappingURL=account-state.js.map

package/dist/src/account/format-account-status.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAccountStatusText = formatAccountStatusText;
+function formatExpiry(expiresAt) {
+    const deltaMs = expiresAt - Date.now();
+    const abs = Math.abs(deltaMs);
+    const minutes = Math.round(abs / 60000);
+    const hours = Math.round(abs / 3600000);
+    const days = Math.round(abs / 86400000);
+    let rel;
+    if (abs < 3600000)
+        rel = `${minutes} min`;
+    else if (abs < 86400000)
+        rel = `${hours} hr`;
+    else
+        rel = `${days} day${days === 1 ? "" : "s"}`;
+    const when = new Date(expiresAt).toISOString();
+    return deltaMs >= 0 ? `in ${rel} (${when})` : `${rel} ago (${when})`;
+}
+function formatAccountStatusText(report) {
+    const lines = [];
+    lines.push("NeoZip account status");
+    lines.push(`Phase: ${report.phase}`);
+    lines.push(`Token Service: ${report.tokenServiceUrl}`);
+    if (report.tokenServiceReachable != null) {
+        lines.push(`Token Service reachable: ${report.tokenServiceReachable ? "yes" : "no"}`);
+    }
+    if (report.tokenExpired) {
+        lines.push("Access token: EXPIRED — run neozip connect refresh");
+    }
+    else if (report.tokenExpiresAt != null) {
+        lines.push(`Access token: valid (expires ${formatExpiry(report.tokenExpiresAt)})`);
+    }
+    if (report.activeProfileId) {
+        lines.push(`Active profile: ${report.activeProfileId}`);
+    }
+    if (report.profile) {
+        lines.push(`Label: ${report.profile.label}`);
+        if (report.profile.email)
+            lines.push(`Email: ${report.profile.email}`);
+        if (report.profile.evmAddress) {
+            lines.push(`EVM address: ${report.profile.evmAddress}`);
+        }
+        if (report.profile.walletId != null) {
+            lines.push(`Wallet ID: ${report.profile.walletId}`);
+        }
+        if (report.profile.identityKeyId != null) {
+            lines.push(`Identity key ID: ${report.profile.identityKeyId}`);
+        }
+        if (report.profile.x25519Fingerprint) {
+            lines.push(`X25519 fingerprint: ${report.profile.x25519Fingerprint}`);
+        }
+    }
+    if (report.nextSteps.length) {
+        lines.push(`Next steps: ${report.nextSteps.join(", ")}`);
+    }
+    if (report.reloadRequired) {
+        lines.push("Reload MCP in Cursor so the active connection credentials are loaded into this session.");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=format-account-status.js.map