@finchtech/cli 0.3.1 → 0.3.3

package/README.md

@@ -10,12 +10,22 @@ CLI-authored EVM addresses accept canonical lowercase or valid EIP-55 input and
 
 Valid remote Identity, Agent, Task, Skill, and OAuth errors are emitted in their original domain envelope with the remote trace ID. Local transport failures use `CLI_REMOTE_UNAVAILABLE`; malformed or contract-invalid responses use `CLI_RESPONSE_INVALID`. Locally synthesized failures use a null trace ID rather than impersonating a server trace.
 
+Skill upload failures also retain the final `uploadBytes`, `uploadObjectKind`, HTTP `remoteStatus` (null when no response was obtained), and available allowlisted `remoteCode`, `remoteRequestId`, and `remoteTraceId` in the JSON-encoded `state`. Locally synthesized errors retain the existing null `reasonCode` and `traceId` contract; downstream evidence is labelled explicitly in `state`. These fields never include raw response text, upload filenames, credentials, or transport causes. `not_attempted` refers only to chain submission: storage may have accepted an object before a response was lost. Follow `contact_support` until the individual attempt is reconciled; another publication's status is not evidence about this attempt.
+
+ZIP import failures return `AGENT_MARKET_REQUEST_INVALID`, exit code `2`, and `fix_request` before upload. The JSON-encoded `state` identifies `SKILL_SOURCE_ZIP_INVALID` and a `zipReason`: `archive_too_large`, `expanded_content_too_large`, `utf8_flag_missing`, `filename_encoding_invalid`, or `invalid_archive`. Size failures include `actualBytes`, `maxBytes` (10,485,760), and `sizeBasis`: `archive` measures the compressed input; `declared_expanded` is the cumulative uncompressed size declared by entries at the first limit violation, before decompression. A safely decoded root-relative entry `path` is included when available. Non-ASCII filenames require valid UTF-8 bytes and bit 11 in the ZIP headers; rebuilding with those flags preserves file contents. These import limits are independent of final upload admission.
+
+Intent HTTP failures include `remotePath: "/api/skills/intents"`, `remoteStatus`, and available safe correlation IDs. `responseIssue` distinguishes `transport_failed`, `body_read_failed`, `empty_body`, `invalid_content_length`, `response_too_large`, `invalid_json`, and `schema_mismatch`. Schema failures include at most eight `schemaIssues` with known field paths and validation keywords; an empty path means the response root or an unrecognized field, whose name is withheld. No response values, arbitrary property names, URLs, or raw causes are printed. Malformed success responses are rejected during `intent`, before signing or writing a pending-send marker. Use the returned recovery command for the same publication; the CLI never automatically retries intent requests or resubmits transactions. The fingerprint identifies the local recovery journal, not a server trace; use returned remote IDs to correlate server logs.
+
+The CLI measures the exact final multipart request, including metadata and framing. Requests above 4,000,000 bytes emit a structured SKILL_UPLOAD_NEAR_LIMIT warning on stderr and continue; requests above 4,500,000 bytes fail before upload. Exactly 4,000,000 bytes do not warn; exactly 4,500,000 bytes warn and continue. These MB thresholds are decimal. The manifest allowance is separately 3 MiB (3,145,728 bytes) on upload and reads. Repacking a compressed source ZIP may increase its size. Passing admission does not certify production upload success or authorize replaying a previously failed publication.
+
 The command groups are `wallet`, `login/status/logout`, `site`, `mcp doctor`, `mcp authorize`, `mcp grant`, `creator`, `credentials`, `intent`, `operation show`, `purchase`, `task`, and `skill`. Run `finch --help` for the exact command list as one JSON value.
 
 `finch site open` creates a sixty-second one-use handoff from the active AgentCLI Session and opens the exact configured Finch origin in the local default Browser. `finch site login <REQUEST_URL>` binds a website-created five-minute request once, then opens the same confirmation page. Both commands require the wallet, CLI, and graphical Browser on the user's machine. A launch failure returns `BROWSER_OPEN_FAILED` without printing the secret completion URL. The Browser receives only a normal seven-day Finch Web Session; wallet signing, broadcast, and market confirmation remain local CLI actions.
 
 `finch mcp doctor` is read-only. It verifies that the active CLI authority, AgentCLI Session, local wallet, MCP challenge, OAuth metadata, and source-controlled persistent-Harness manifest agree. The Agent Harness owns Remote MCP configuration, OAuth credentials, and refresh; the CLI does not configure or launch Codex and never reads Harness OAuth material. During the Harness's native OAuth flow, the authorization page supplies an exact `finch mcp authorize <REQUEST_TOKEN>` command. The versioned base64url token carries the original OAuth request without shell metacharacters so Windows package-manager and Volta launchers cannot split it; the CLI decodes it before applying the existing origin, callback, state, and scope checks. That command uses only the active local AgentCLI Session and opens the verified callback without returning its one-use code. It never uses a Browser Session, Social account, or extension wallet as Agent authority. Configure `https://www.finchtech.ai/mcp` once through the Harness, then use MCP `identity_actor_get` together with `finch status` to verify exact Account and wallet alignment before custody. The server-reported environment is diagnostic and never selects the CLI endpoint or a transaction chain.
 
+Doctor's `ready: true` is scoped by `readinessScope: "cli_session_and_mcp_discovery"`. Its `harnessOAuth.status` is always `not_checked`: CLI login and valid discovery metadata do not establish that the connected Harness has usable OAuth credentials, a saved issuer, or working refresh. The result includes identity-verification and native reauthorization guidance. If the Harness reports an OAuth failure, complete its native MCP authorization flow and the authorization page's fresh `finch mcp authorize` command, then verify MCP identity again.
+
 Ordinary installs require no profile file or environment selection. Network commands default to the PROD endpoint at `https://www.finchtech.ai`. An internal TEST installation may provide one strict owner-only `{ "version": 1, "origin": "..." }` profile override; it cannot configure an environment, chain, contract, or RPC. `finch login --chain-id <CHAIN_ID>` explicitly selects only the authentication chain, which the selected server must support. Market transaction chains come from Remote MCP/API plans and are independent of the login chain. `intent approve` signs only the shared publication-v2 or Local-purchase-v1 EIP-712 authorization; it cannot sign arbitrary transaction calldata.
 
 `operation show` and signing-decision recovery require an active, unexpired MCP grant for the current account and endpoint with `agent_market:operations:read`. The CLI selects that grant from protected local state and never substitutes the AgentCLI Session bearer.
@@ -41,7 +51,7 @@ Version 0.3.1 fixes Skill search continuation: pass the returned `nextCursor` un
 Older clients receive an upgrade message from the Skill search API.
 
 Version 0.3.0 upgrades Skill publication and encrypted delivery together. Upgrade with
-`pnpm add -g @finchtech/cli@0.3.1` and verify `finch --version` before publishing new Skills
+`pnpm add -g @finchtech/cli@0.3.3` and verify `finch --version` before publishing new Skills
 or downloading encrypted Skills from the upgraded gateway. Older CLI versions cannot use
 the new encrypted delivery, including for historical Skills; 0.3.0 retains historical package support.
 
@@ -65,3 +75,38 @@ manifest for server validation; URI intents are prepared after the new chain bin
 Finch-managed publication key requests use a signed timestamp and a one-time nonce. Each request is
 valid for five minutes; retrying after expiry or a lost response requires a fresh signature. The
 gateway rejects older CLI publication requests without timestamps. Historical downloads are unchanged.
+
+### Local publication failures
+
+Directory publication rejects symbolic links, including internal relative links and broken links.
+It skips excluded paths (for example `.git`, `node_modules`, `.aws`, and credential files) before reading
+or descending into them. `excluded` lists a skipped directory once instead of enumerating its children.
+Keep required resource paths functional when preparing a link-free source; deleting required links is
+not a valid repair. ZIP imports also reject symbolic links.
+
+Source errors keep exit code 2 and `AGENT_MARKET_REQUEST_INVALID`. Parse the JSON string in `error.state`
+for `diagnosticCode`: `SKILL_SOURCE_SYMLINK_UNSUPPORTED`, `SKILL_SOURCE_UNREADABLE`, or
+`SKILL_UPLOAD_SIZE_INVALID`, `SKILL_SOURCE_ZIP_INVALID`, `SKILL_SOURCE_PRIMARY_DOCUMENT_INVALID`, `SKILL_UPLOAD_REQUEST_TOO_LARGE`, or `SKILL_MANIFEST_SIZE_INVALID`. Source diagnostics include a root-relative `path` (`.` for the selected
+root); size diagnostics include `actualBytes` and `maxBytes`. The 10 MiB internal packaging bound is independent of the stricter HTTP limit and applies to the final
+upload object, including SkillRoot metadata and encryption overhead. STORE ZIP construction does not
+compress files. A size rejection occurs before that upload and before transaction submission.
+
+Publish, version, and publication-recovery failures also include `phase`, `fingerprint`,
+`transactionHashes` (keyed by `primary`, `uri`, or `lit`), `submissionStatus`, and `recoveryCommand` in
+`error.state`. `packaging` includes local hashing/encryption; `transaction` covers signing, broadcast,
+and receipt handling. A validated remote error keeps its code, message, trace and HTTP status
+(`remoteStatus`), with its original state retained as `remoteState`; publication retry guidance takes
+precedence over a remote service's generic retry flag. Private causes, RPC URLs, credentials and
+journal contents are never printed.
+
+Publication failures set `retryable: false`: this is not permission to replay a paid operation.
+`not_attempted` means no send was attempted in this invocation and no hashes were found in the
+validated journal; it is not proof about other invocations. `hash_known` includes known transaction
+hashes. `uncertain` means sending or durable checkpointing failed; contact support before retrying or
+recovering, even when a hash is shown. A non-null `recoveryCommand` is provided only after a journal
+is validated or saved and no submission/checkpoint uncertainty was observed. Recheck CLI/MCP identity
+and use that command rather than repeating publish-submit. Cleanup failures do not claim a journal
+still exists. If source is unavailable or its excluded-path inventory changed across CLI versions,
+the fingerprint-only recovery command can use the already stored publication bytes.
+
+These fixes require CLI 0.3.3 or newer; npm 0.3.2 does not include them. Updating a Skill does not upgrade the installed CLI. Journal v6 saves a pending stage before signing/submitting. Missing hashes in a pending stage or a legacy v4/v5 journal block automatic resubmission; contact support. Known hashes are verified without rebroadcast. The pending marker also blocks destructive local authorization/wallet cleanup through the recovery inventory.