@tomako/connect (0.1.0 development package)

Machine-oriented device-flow CLI for connecting one deployed, read-only goal metric endpoint to Tomako. This package is not published yet.

npx --yes @tomako/[email protected] install \
  --device PUBLIC_DEVICE_CODE \
  --goal GOAL_ID \
  --digest sha256:v1:GOAL_DIGEST

The first invocation fetches a non-sensitive goal brief and outputs WAITING_AGENT, briefHash, and the canonical proposal-file schema. The coding agent must inspect the repository and create .tomako/metric-proposal.json; the CLI never guesses the metric definition. The file is a generated envelope, not a raw metric object:

If the repository supports materially different valid interpretations (for example, account created vs. email verified vs. first workspace entry), metric.semanticDecision may include one bounded question and 2-4 complete options. The recommended option must exactly match the proposal's default fields. Tomako requires the signed-in owner to choose one option in the existing confirmation card, then signs only the selected semantics into the immutable contract. Do not invent alternatives when repository facts do not create a real count difference.

{
  "schemaVersion": 1,
  "generatedBy": "@tomako/connect",
  "goalBinding": {
    "goalId": "copy from goalBrief",
    "goalVersion": 1,
    "goalDigest": "copy from goalBrief"
  },
  "briefHash": "copy the WAITING_AGENT briefHash",
  "metric": { "strategy": "SIGNED_PULL_SNAPSHOT", "...": "canonical metric fields" }
}

The CLI rejects stale proposal files unless all three goal-binding fields and the exact generated brief hash match. Only the inner canonical metric is sent to the backend.

Every stdout event is one machine-readable JSON line containing a version-pinned nextCommand (or an explicit manual/no-op instruction), required inputs, and acceptance checks. The agent does not need to infer the next protocol step from this README.

npx --yes @tomako/[email protected] install \
  --device PUBLIC_DEVICE_CODE \
  --goal GOAL_ID \
  --digest sha256:v1:GOAL_DIGEST \
  --proposal .tomako/metric-proposal.json \
  --endpoint https://product.example/api/tomako/metric

The proposal is submitted before owner confirmation. resume polls the authorization state, verifies the server-signed immutable contract and exact goal/proposal binding, then writes .tomako/connection.json read-only. Private Ed25519 installation identity stays under .git/tomako-connect with mode 0600.

Before owner confirmation, the CLI also derives a small project-identity summary so the owner can verify that the agent connected the intended codebase. The canonical client object contains only agent, projectFingerprint, cliVersion, repository, framework, deploymentDomain, and device. The project directory basename and package name are embedded only in the human-readable repository label. Git usernames, passwords, tokens, query strings, fragments, local absolute paths, and endpoint paths are never sent. Remote URLs that cannot be safely reduced are reported only as a local Git project.

Automatic runtime installation currently supports Node 20+ projects where a Next.js App Router directory is detected. Java, Python, Go, other runtimes, and unknown repositories fail closed with PROJECT_RUNTIME_UNSUPPORTED and USE_MANUAL_PROGRESS; the CLI never submits a claim that the published runtime cannot fulfill.

Starting a different device flow or goal safely generates a new installation ID, Ed25519 identity, and idempotency key after the new public goal brief has been validated. Previous confirmed .tomako/connection.json and the exact claimed proposal are moved unchanged to .tomako/history/ and reported in the JSON event. Generated goal briefs are replaced only when their stored ownership hash is intact and the goal binding changes; user-owned or changed files fail closed. Server-confirmed REJECTED, STALE, EXPIRED, and REVOKED states converge to an explicit rotation or cleanup command.

Before the claim request, the CLI persists a CLAIM_SUBMITTING recovery record. If the server accepted the claim but the response was lost, rerunning the same install command reads the signed installation status first and, only when the server reports INSTALLATION_NOT_FOUND, resubmits the byte-equivalent idempotent claim data. It never fetches a new one-time brief during this recovery path.

In a monorepo, public .tomako files are scoped to the nearest package containing package.json, while private credentials remain in the repository's real Git directory. The project fingerprint binds both real paths, so running the same command in a different workspace rotates identity instead of silently reusing it.

Commands after confirmation:

• auth-check: verifies only the CLI installation identity (AUTH_VERIFIED).
• test: asks Tomako's backend to perform a real signed pull against the deployed HTTPS endpoint. It accepts only RUNTIME_TEST_PASSED plus a backend proof.
• activate: requires the runtime proof.
• status, resume, revoke, cleanup-local.

Production control origin is compiled as https://tomako.ai; there is no --api. Only TOMAKO_DEV=1 with a loopback TOMAKO_DEV_API enables local protocol tests. Redirects are rejected and symlinked state paths fail closed.

Release blocker: the production contract-signing Ed25519 root key is intentionally absent from src/trust.mjs; the package must not be published until it is inserted and pinned.