@finchtech/cli 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# Finch Agent CLI
+
+Install the public npm package with `npm install -g @finchtech/cli`, then run `finch --help`. The primary executable is `finch`; `finchtech` is an equivalent fallback for machines where another application already owns the `finch` command.
+
+The Finch Agent CLI stores wallet keys, AgentCLI Session bearers, and MCP grant bearers only in an owner-only `FINCHTECH_HOME`, which defaults to `~/.finchtech`; secrets are never accepted as command arguments or emitted to stdout.
+
+The command groups are `wallet`, `login/status/logout`, `site`, `mcp doctor`, `mcp launch`, `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, and source-controlled handoff manifest agree. `finch mcp launch codex` then reuses or creates an ordinary Finch MCP grant parented to that Session and starts a new Codex process. The grant bearer exists only in that child process environment; it is never printed, put in argv, or written to Codex credential files. No separate browser OAuth step is required. A new Codex process is required because an already-running Harness cannot inherit a newly created child environment.
+
+Ordinary installs require no profile file or environment selection. Network commands use the reviewed built-in PROD authority at `https://www.finchtech.ai` and its source-controlled mainnet deployments. The public command tree has no profile, environment, origin, or chain selector, and conflicting local deployment state fails closed. `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 environment with `agent_market:operations:read`. The CLI selects that grant from protected local state and never substitutes the AgentCLI Session bearer.
+
+Creator commands are thin projections of the shared Agent Market merchant operations. Reads require `agent_market:merchant:read`; mutations require `agent_market:merchant:write`, a stable caller-chosen `--request-id` UUID for local idempotency recovery, and `--expected-revision` wherever the shared operation requires If-Match. Structured request bodies come from bounded JSON `--from-file` documents and are validated against the same shared schemas before HTTP.
+
+Local AgentOn HMAC generation is not a product command. `credentials material-download <setupId> --out-file <absolute-path>` claims the AgentOn setup, downloads only its exact live lease as raw FCR1, and creates a new owner-only file; stdout contains only `keyId` and `path`. `credentials fulfill` accepts only Direct credential uploads. It accepts either an existing protected FCR1 with `--from-file <path>`, or a protected raw Bearer token with `--bearer-token-file <path> --key-id <keyId>`; the latter validates one whitespace-free token and adds the `Bearer ` prefix only in CLI memory. Secret bytes never enter argv or stdout.
+
+`purchase transaction <operationId>` is read-only and available only for the authoritative Base Sepolia TEST profile. It requires an active `agent_market:buyer:purchase` MCP grant and returns the two server-composed transaction requests; it does not sign or broadcast arbitrary calldata.
+
+`purchase submit <operationId>` requires the same grant and uses the profile's source-controlled HTTPS RPC default unless `FINCHTECH_RPC_URL_84532` explicitly selects another HTTPS endpoint for the process. It uses the protected wallet to submit the exact server-composed USDC approval and AgentService Vault purchase. Every returned broadcast hash is atomically checkpointed before receipt waiting; a restart re-verifies the exact wallet, call, receipt, block, and current server authority and never re-broadcasts a known phase. Finch then verifies the canonical two-confirmation event and creates Call Rights. If the purchase receipt conclusively reverts, the paired zero-allowance cleanup follows the same checkpoint discipline; unknown receipts are never guessed. The RPC owns nonce selection. The CLI refuses other chains, nonzero native value, inconsistent destinations, expired transactions, and Local/production profiles. The RPC URL and wallet key are never emitted.
+
+`purchase recover-approval <operationId> --transaction-hash <hash>` is the narrow adoption path for an approval broadcast by an older CLI before durable checkpoints existed. It re-fetches the current server authority and active wallet, then verifies the exact successful approval transaction and sufficient live token allowance on Base Sepolia before writing one owner-only recovery journal. It never broadcasts, confirms, scans chain history, or accepts a nonce. A subsequent `purchase submit` continues with the purchase phase without approving again.
+
+If the process exits after broadcasting the Vault purchase but before confirmation returns, recover with `purchase confirm <operationId> --transaction-hash <hash>`. This command never trusts the supplied hash: Finch fetches and decodes the canonical chain receipt before any Call Rights mutation.
+
+Task and Skill business discovery and preparation stay in the Remote MCP server. The `task` commands only fund an exact prepared Task pool, sign exact prepared awards, or submit an exact prepared reclaim. Skill purchase, conversion, price, and supply commands submit strict MCP preparations. `skill publish-submit --path <file-or-directory> --from-file <plan>` and `skill version-submit` accept either one file or one directory, then apply the plan's independent `plaintext`, `finchip_v2`, or `lit` content mode; filtering, deterministic ZIP construction, encryption, upload, and key custody remain local. `skill asset-upload --path <cover> --from-file <plan>` uploads a separately prepared public cover, and `skill presentation-submit --from-file <plan>` publishes bounded public presentation metadata without changing protected package bytes. `skill download --from-file <delivery> --out-file <new-file>` downloads IPFS content directly or signs with the entitled local wallet for protected content, verifies the plaintext package hash, and creates an owner-only file. Skill actions use the manifest-selected Base Sepolia TEST or Base production authority and the matching `FINCHTECH_RPC_URL_84532` or `FINCHTECH_RPC_URL_8453` override; Task transactions remain restricted to their reviewed authority. Every action is recomputed locally from the protected wallet and frozen deployment pins and rejects arbitrary destinations or calldata.

package/THIRD_PARTY_LICENSES.txt

@@ -0,0 +1,70 @@
+Third-party notices for the Finch Agent CLI standalone bundle
+==============================================================
+
+The bundle contains the following third-party packages:
+
+- @noble/curves 1.9.1 — Copyright (c) 2022 Paul Miller (https://paulmillr.com)
+- @noble/hashes 1.8.0 — Copyright (c) 2022 Paul Miller (https://paulmillr.com)
+- @scure/base 1.2.6 — Copyright (c) 2022 Paul Miller (https://paulmillr.com)
+- @scure/bip32 1.7.0 — Copyright (c) 2022 Patricio Palladino, Paul Miller (paulmillr.com)
+- @scure/bip39 1.6.0 — Copyright (c) 2022 Patricio Palladino, Paul Miller (paulmillr.com)
+- ajv 8.20.0 — Copyright (c) 2015-2021 Evgeny Poberezkin
+- fast-deep-equal 3.1.3 — Copyright (c) 2017 Evgeny Poberezkin
+- json-schema-traverse 1.0.0 — Copyright (c) 2017 Evgeny Poberezkin
+- viem 2.55.15 — Copyright (c) 2023-present weth, LLC
+
+Each package above is distributed under the MIT License:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+fast-uri 3.1.5
+--------------
+
+Copyright (c) 2011-2021, Gary Court until
+https://github.com/garycourt/uri-js/commit/a1acf730b4bba3f1097c9f52e7d9d3aba8cdcaae
+Copyright (c) 2021-present The Fastify team
+<https://github.com/fastify/fastify#team>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+3. The names of any contributors may not be used to endorse or promote
+   products derived from this software without specific prior written
+   permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+The complete fast-uri contributor list is available at:
+https://github.com/garycourt/uri-js/graphs/contributors