@kvell007/embed-labs-cli 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,277 @@
+# @embed-labs/cli
+
+Command-line interface for Embed Labs Cloud.
+
+## Package Status
+
+This package is a publish candidate, but it is not ready for public npm publish
+yet. The workspace manifest intentionally remains marked `private: true` until
+package names, license, npm scope ownership, support URLs, and release approval
+are complete.
+
+## What It Provides
+
+- `embed` binary exposed by the npm `bin` entry after install.
+- First-run diagnostic command for CLI runtime, auth, Local Bridge, local scans,
+  and Cloud API readiness.
+- Local bridge startup and status commands.
+- Auth token login, logout, and status commands.
+- Account registration, API key issue/list, token usage metering, and billing
+  statement preview commands.
+- Server-side application source generation through Cloud API agents, followed by
+  task artifacts and downloads.
+- Debug tool, device, serial, SSH, and flash commands routed through the local
+  bridge.
+- Project, task, artifact, and cloud status commands routed through the cloud
+  API.
+- Approval request, list, show, approve, and reject commands routed through the
+  cloud API.
+- Human-readable output by default and `--json` output for automation.
+
+The installed binary is the primary interface. Package and library APIs are
+secondary implementation details for now; do not treat `@embed-labs/cli` as a
+public SDK until a versioned API contract is approved.
+
+## Install
+
+After the package is approved for public release:
+
+```bash
+npm install -g @embed-labs/cli
+embed --help
+embed help getting-started
+```
+
+Local package testing before public npm publish:
+
+```bash
+npm run build
+npm pack --workspace @embed-labs/cli --pack-destination ./tmp
+npm install -g ./tmp/embed-labs-cli-*.tgz
+embed --help
+```
+
+Internal workspace usage without global install:
+
+```bash
+npm run build
+node packages/cli/dist/index.js --help
+node packages/cli/dist/index.js help getting-started
+```
+
+## Quick Start
+
+```bash
+embed --help
+embed help getting-started
+embed doctor
+embed auth login --token <token>
+```
+
+For the current public API plus local TaishanPi verification path, see
+`docs/runbooks/PUBLIC_CLI_USER_VERIFICATION.md`.
+
+For the cloud build path:
+
+```bash
+embed build template list
+embed build template show <template_id>
+embed build workspace provision --account <account_id> --project <project_id> --template <template_id>
+embed build workspace source put <workspace_id> --file ./main.c:src/main.c
+embed build application generate --workspace <workspace_id> --prompt "Create a minimal Linux app"
+embed cloud task artifacts <task_id>
+embed artifact download <artifact_id> --output ./artifact.bin
+```
+
+For local hardware access:
+
+```bash
+embed bridge start
+embed device list
+embed flash plan --board <rp2350|taishanpi> --artifact ./artifact.bin
+```
+
+For cloud API workflows, point the CLI at a running cloud API service:
+
+```bash
+EMBED_CLOUD_API_URL=http://127.0.0.1:18100 embed cloud status
+```
+
+## Interaction Modes
+
+- Human terminal: run `embed` directly and read the default output.
+- Local scripts and CI: run `embed ... --json` and parse the response envelope.
+- Localhost tools: start `embed bridge start` and call the Local Bridge HTTP API
+  only from trusted same-host tools.
+- Remote AI: use Cloud API tasks, events, artifacts, and evidence instead of
+  direct local bridge or unrestricted hardware access.
+- Future IDE and Warp flows: wrap the same CLI, Local Bridge, and Cloud API
+  boundaries rather than depending on internal package APIs.
+
+Remote AI should not receive raw Local Bridge URLs, serial/USB/SSH/debug
+handles, flash endpoints, or localhost tunnels. Hardware-changing operations
+remain local and approval-gated.
+
+## Common Commands
+
+`embed --help` is intentionally a short first-run guide. Use
+`embed help getting-started` for the guided workflow or `embed help commands`
+for the full command reference.
+
+```bash
+embed doctor [--json]
+
+embed auth login --token <token> [--profile default]
+embed auth status
+embed auth logout
+
+embed account create --email <email> [--display-name <name>] [--json]
+embed account show <account_id> [--json]
+embed account keys create --account <account_id> [--name <name>] [--json]
+embed account keys list --account <account_id> [--json]
+embed account keys revoke <api_key_id> [--json]
+
+embed usage record --api-key <key>|--api-key-id <api_key_id> --model <model> --input-tokens <n> --output-tokens <n> [--provider <name>] [--operation <name>] [--task <task_id>] [--request-id <id>] [--json]
+embed usage summary --account <account_id>|--api-key-id <api_key_id> [--from <iso>] [--to <iso>] [--json]
+embed usage events --account <account_id> [--api-key-id <api_key_id>] [--from <iso>] [--to <iso>] [--limit 100] [--json]
+embed billing statement --account <account_id> [--from <iso>] [--to <iso>] [--json]
+embed billing balance --account <account_id> [--json]
+embed billing recharge create --account <account_id> --amount-usd <amount> [--provider mock|stripe|onchain] [--chain <chain>] [--token <symbol>] [--qr] [--json]
+embed billing recharge submit-tx <recharge_session_id> --tx-hash <hash> [--json]
+embed billing recharge list --account <account_id> [--json]
+embed billing recharge show <recharge_session_id> [--json]
+embed billing snapshot create --account <account_id> [--from <iso>] [--to <iso>] [--json]
+embed billing snapshot list --account <account_id> [--json]
+embed billing snapshot show <billing_snapshot_id> [--json]
+
+embed build template list [--json]
+embed build template show <template_id> [--json]
+embed build workspace provision --account <account_id> --project <project_id> [--template <template_id>] [--copy-mode auto|copy|symlink|skeleton] [--require-seed] [--dry-run] [--json]
+embed build workspace list --account <account_id> [--json]
+embed build workspace show <workspace_id> [--json]
+embed build workspace source put <workspace_id> [--account <account_id>] --file <local_path>:<source_path> [--file <local_path>:<source_path>] [--json]
+embed build application stub --workspace <workspace_id> [--account <account_id>] [--json]
+embed build application generate --workspace <workspace_id> --prompt <request> [--account <account_id>] [--target <source_path>] [--provider stub|openai|cc|claude-code] [--model <model>] [--json]
+
+embed bridge start [--host 127.0.0.1] [--port 18083]
+embed bridge status [--json]
+
+embed debug tools [--json]
+
+embed device list [--json]
+embed device probe --host <host> --ports 22,15301 [--serial-path <path>] [--timeout-ms 1000] [--json]
+
+embed serial list [--json]
+embed serial capture --path <port> [--baud 115200] [--duration 5] [--json]
+embed ssh run --host <host> [--user root] -- <command> [--json]
+
+embed flash plan --board <rp2350|taishanpi> [--artifact file.uf2] [--image-dir dir] [--json]
+embed flash run --board <rp2350|taishanpi> --approve [--artifact file.uf2] [--image-dir dir] [--json]
+embed task list [--json]
+embed task status <local_job_id> [--json]
+
+embed project create <name> [--board <board_id>] [--workspace <path>] [--json]
+embed project list [--json]
+embed project status <project_id> [--json]
+
+embed ask --prompt <request> [--project <project_id>] [--board <board_id>] [--json]
+embed cloud status [--json]
+embed cloud task create [--kind build.firmware] [--progress-text "Task created."] [--json]
+embed cloud task list [--json]
+embed cloud task status <task_id> [--json]
+embed cloud task events <task_id> [--json]
+embed cloud task artifacts <task_id> [--json]
+embed cloud task evidence <task_id> [--json]
+embed cloud task event append <task_id> [--state <state>] [--progress-stage <stage>|--stage <stage>] [--progress-text <text>|--message <text>] [--progress-percent 0-100] [--severity info|warning|error] [--type <event_type>] [--artifact-json '<json>'] [--evidence-json '<json>'] [--json]
+embed artifact status <artifact_id> [--json]
+
+embed approval request --task <task_id> --action <action> --risk <low|medium|high|destructive> --plan-summary <summary> [--affected-device <id>] [--affected-artifact <id>] [--expires-at <iso>] [--json]
+embed approval list --task <task_id> [--json]
+embed approval show <approval_id> [--json]
+embed approval approve <approval_id> [--decided-by <name>] [--json]
+embed approval reject <approval_id> [--decided-by <name>] [--json]
+```
+
+`embed approval request` creates a task-scoped approval record with the Cloud
+API. Repeat `--affected-artifact` to attach multiple artifact IDs. Approval
+commands record request and decision state in the Cloud API only. They do not
+execute Local Bridge actions; any future local runner must re-check the approval
+record before running one bounded localhost action.
+
+`embed account keys create` returns the raw API key only in the creation
+response. Store it in a secret manager or environment variable; future list and
+summary commands show metadata, key prefix, and usage totals but never the raw
+key. `embed usage record` is the current metering ingestion path used by smoke
+tests and future billing reports. Reusing the same `request_id` for the same
+API key returns the original usage record so callers can safely retry without
+double counting. `embed account keys revoke` marks a key unusable for future
+usage ingestion while preserving historical usage and billing evidence.
+`embed usage events` lists the account's raw usage records for audit and
+settlement investigation without exposing raw API key material. Event reads are
+bounded; the server default is 100 and the current maximum is 500.
+
+`embed billing statement` reads the account's recorded token usage and applies
+the Cloud API's configured input/output micro USD per-token rates. It is a
+preview for product and settlement validation, not an invoice or payment action.
+`embed billing recharge create --provider onchain --qr` creates a wallet payment
+session and renders the payment URI as a terminal QR. After paying from a wallet,
+`embed billing recharge submit-tx <recharge_session_id> --tx-hash <hash>` sends
+the payment evidence to the server for confirmation and crediting.
+`embed billing snapshot create` freezes one statement preview result so later
+queries can compare against a stable settlement input. Snapshots are still MVP
+preview records; they are not invoices and do not collect payment.
+
+## Environment
+
+- `EMBED_BRIDGE_URL`: local bridge URL used by bridge-backed commands. Default:
+  `http://127.0.0.1:18083`.
+- `EMBED_CLOUD_API_URL`: cloud API URL used by cloud-backed commands. Default:
+  `http://127.0.0.1:18100`.
+- `EMBED_API_TOKEN`: auth token source for non-interactive sessions.
+- `EMBED_AUTH_PROFILE`: profile name used with `EMBED_API_TOKEN`.
+- `EMBED_AUTH_FILE`: token file path for `embed auth login`. Default:
+  `.embed-labs/auth.json`.
+- `EMBED_BILLING_INPUT_MICROUSD_PER_TOKEN` and
+  `EMBED_BILLING_OUTPUT_MICROUSD_PER_TOKEN`: Cloud API server-side statement
+  preview rates. These are read by the Cloud API process, not by the CLI.
+
+`embed doctor --json` is safe to run before services are started. Missing Local
+Bridge or Cloud API services are reported inside the structured doctor result as
+`unreachable` or `not_ready`; the command does not start services or mutate
+hardware or Cloud API state.
+
+## Hardware Support Boundary
+
+The CLI delegates hardware actions to `@embed-labs/local-bridge`; it does not
+perform direct hardware access itself.
+
+Current local workflows are intentionally guarded:
+
+- Device commands can report local detection and probe evidence.
+- `embed debug tools` reports local debug tool availability and version/help
+  evidence without opening probes or starting debug sessions.
+- RP2350 UF2 flashing requires a mounted UF2 volume, a `.uf2` artifact, a ready
+  flash plan, and explicit `--approve`.
+- TaishanPi flash planning can validate expected image files and local tool
+  availability, but real destructive TaishanPi flashing is guarded and not
+  enabled. `embed flash run --board taishanpi --approve` remains blocked until
+  the exact hardware profile and Board Pack command templates are accepted.
+
+These commands should be treated as current local evidence and planning tools,
+not broad hardware support claims.
+
+## Runtime Requirements
+
+- Node.js 20 or newer.
+- A running local bridge for debug tool, device, serial, SSH, flash, and local task
+  commands. Start it with `embed bridge start`.
+- A running Embed Labs Cloud API for account, usage, billing statement, project,
+  cloud task, artifact, approval, and ask commands.
+
+## Publish Readiness
+
+Before public publish, confirm the runbook checklist in
+`docs/runbooks/CLI_NPM_PACKAGING.md`, including approved SPDX license metadata,
+repository, issue tracker, homepage, support metadata, changelog or release
+notes, final npm scope ownership, executable verification for `embed`, and
+removal of `private: true` only in an approved metadata task.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};