@oiioii/cli 0.1.0 → 0.1.5

package/README.md

@@ -12,8 +12,9 @@ human-readable output and a stable JSON envelope for AI agents and automation.
 
 | Command | Capability | Status |
 |---|---|---|
-| `auth login` | Persist API Key and backend configuration | Implemented |
-| `workspace create/set/current` | Create, configure, and inspect workspaces | Implemented |
+| `auth login` | Browser authorization for terminal/Codex/WorkBuddy/Kimi/Claude Code/DeepSeek, or explicit API Key persistence | Implemented |
+| `workspace create/set/current/rename` | Create, configure, inspect, and rename workspaces | Implemented |
+| `workspace assets list/download` | List workspace assets and download ready resources | Implemented |
 | `image text` | Text-to-image generation | Implemented |
 | `image edit` | Image-to-image editing | Implemented |
 | `video text` | Text-to-video generation | Implemented |
@@ -24,7 +25,7 @@ human-readable output and a stable JSON envelope for AI agents and automation.
 | `record get/open` | Query generation metadata and download resources | Implemented |
 | `inspect capabilities/models` | Inspect declared capabilities and live backend models | Implemented |
 | `preview latest/bundle` | Read local preview bundles created by generation commands | Implemented |
-| `task list/status/wait` | Inspect and wait for local generation tasks | Implemented |
+| `task list/status/wait/retry` | Inspect, wait for, and safely retry local generation tasks | Implemented |
 | `logs list/export/path` | Inspect and export structured local logs | Implemented |
 | `points balance/quote/cost` | Inspect balance, estimate a request, and query actual charges | Implemented |
 
@@ -34,19 +35,21 @@ Important current limitations:
 - Generation submits `submit_async_media_generation` and returns immediately with the authoritative backend `task_id` plus a `local_task_id`.
 - The backend task ID, workspace, media type, asset ID, progress, and terminal outputs are cached in the owner-only local task store.
 - `task status/wait` query `query_async_media_generation` for non-terminal cached tasks and accept either the backend or local task ID.
+- If submission times out or disconnects before the backend task ID is received, the task remains `submitting`; `task retry <local_task_id>` resends the saved request with the original idempotency key.
+- REST metadata requests time out after 30 seconds; raw resource uploads/downloads use a 5-minute transfer timeout, and VOD transcode polling has a 10-minute overall deadline.
 - Image, video, and audio generation create local preview bundles after a queried task reaches a terminal state.
 - `inspect capabilities` is local metadata; `inspect models` requires authentication and queries the active backend.
-- Asset-library browsing/search/update/delete and style-library commands are not available.
+- Asset search/update/delete and style-library commands are not available. Workspace-scoped asset listing and download are available.
 
 ## Requirements
 
-- Node.js 18 or newer when running from source or the npm package.
-- An existing Hogi MCP API Key.
+- Node.js 18.18 or newer when running from source or the npm package.
+- A Hogi account for browser authorization, or an existing Hogi MCP API Key.
 - A workspace ID for image/video/audio generation and resource upload. It can be
   created with `oiioii workspace create` or supplied from an existing project.
 - `npm` is the repository package manager.
 
-The hosted installer uses Node.js 18 or newer when available. If no compatible
+The hosted installer uses Node.js 18.18 or newer when available. If no compatible
 Node.js/npm installation exists, it downloads an official Node.js runtime,
 verifies its SHA256, and keeps it under the oiioii installation directory.
 
@@ -83,21 +86,28 @@ write `install.json`, and create stable `oiioii` / `oiioii-cli` wrappers. CLI
 updates reuse the exact Node.js, npm, registry, package, and prefix recorded by
 the installer.
 
+The maintained production bootstrap sources are `scripts/install.sh` for
+macOS/Linux and `scripts/install.ps1` for Windows. They always follow npm's
+`latest` dist-tag. Set `OIIOII_CLI_VERSION` only when you need one exact stable
+version.
+
 macOS (Apple Silicon and Intel are detected automatically):
 
 ```bash
-curl -fsSL https://<public-host>/install.sh | bash
+curl -fsSL https://static-oiioii-sg.hogiai.cn/cli/install.sh | bash
 ```
 
 Windows x64, from PowerShell:
 
 ```powershell
-$script = Join-Path $env:TEMP "install.ps1"; curl.exe -fsSL https://<public-host>/install.ps1 -o $script; powershell.exe -NoProfile -ExecutionPolicy Bypass -File $script; Remove-Item $script
+$script = Join-Path $env:TEMP "install.ps1"; curl.exe -fsSL https://static-oiioii-sg.hogiai.cn/cli/install.ps1 -o $script; powershell.exe -NoProfile -ExecutionPolicy Bypass -File $script; Remove-Item $script
 ```
 
-Production is the default and follows npm's `latest` dist-tag. For the HOE test
-build, set `OIIOII_ENV=test`; it follows the `test` dist-tag and accepts only
-prerelease versions. Set `OIIOII_CLI_VERSION` to install one exact version.
+Test builds use `scripts/test/install.sh` and `scripts/test/install.ps1` as
+maintained static-runtime installer templates. The build writes generated
+installers with the runtime MD5 embedded under `scripts/test/dist/`; they verify
+the runtime archive SHA-256 before installing it and do not share the production
+npm installer/update metadata.
 
 After bootstrap installation:
 
@@ -113,15 +123,28 @@ rebuilt from the checkout.
 
 ## Build Environments
 
-The default backend URL is embedded into the generated bundle at build time.
+The default backend URL and browser authorization page are embedded into the generated bundle at build time.
 
-| Build command | Environment | Embedded default backend |
-|---|---|---|
-| `npm run build:production` | production | `https://api.oiioii.ai` |
-| `npm run build:test` | test (HOE) | `https://api-hoe.oiioii.tv` |
-| `npm run build:local` | local | `http://localhost:4000` |
+| Build command | Environment | Embedded default backend | Authorization page |
+|---|---|---|---|
+| `npm run build:production` | production | `https://api.oiioii.ai` (optional `OIIOII_PRODUCTION_BASE_URL` override) | `https://oiioii.tv/auth/cli` |
+| `npm run build:test` | test | `OIIOII_TEST_BASE_URL` from `.env` | Build-specific test authorization page |
+| `npm run build:local` | local | `http://localhost:4000` | `http://localhost:3000/auth/cli` |
+
+Use the environment-specific build entry points. Only test builds require a
+URL in `.env`:
+
+```bash
+npm run build:production
+cp .env.example .env
+npm run build:test
+```
 
-`npm run build` builds the test environment to preserve the existing default.
+`npm run build` is an alias for `build:production`. `build:test:runtime` is a
+separate release path: it builds the test bundle, installs production-only
+dependencies into an isolated staging directory, verifies the embedded URL,
+and writes generated installers plus an MD5-addressed runtime archive and its
+SHA-256 checksum under the ignored `scripts/test/dist/` directory.
 
 For a custom deployment, override the embedded URL during the build:
 
@@ -132,6 +155,11 @@ OIIOII_BUILD_BASE_URL=https://custom.example.com npm run build:production
 Supported build environment names are exactly `production`, `test`, and
 `local`. Unknown values fail the build instead of silently selecting a domain.
 
+Publishing always rebuilds the package during npm's `prepublishOnly` lifecycle.
+Publishing rejects the one-off `OIIOII_BUILD_BASE_URL` override and uses the
+matching environment-specific variable, so an inherited custom URL cannot leak
+into a published package.
+
 The embedded URL is a fallback. Existing runtime overrides remain available:
 
 - Root option: `--base-url <url>` for commands that consume the root override.
@@ -140,17 +168,52 @@ The embedded URL is a fallback. Existing runtime overrides remain available:
 
 ## Authentication and Workspace
 
-Persist an existing MCP API Key and the backend URL:
+Authorize through the Hogi browser page for the application that launched the CLI:
 
 ```bash
-oiioii auth login \
-  --api-key "oii_sk_..." \
-  --base-url "https://api-hoe.oiioii.tv"
+oiioii auth login
+oiioii auth login --codex
+oiioii auth login --workbuddy
+oiioii auth login --kimi
+oiioii auth login --claude-code
+oiioii auth login --deepseek
 ```
 
-The CLI writes the API Key and Base URL to `~/.oiioii/config.json` with file
-permissions `0600`. `OIIOII_API_KEY` remains available as a temporary process
-override. A legacy `~/.oiioii/credentials.json` file, if present, is ignored.
+Without an application option, `auth login` opens the browser authorization page
+and asks the user to return to the terminal when authorization completes. The
+application options label the authorization for the selected host. Codex and
+WorkBuddy use verified macOS/Windows activation contracts; other targets print
+the localized manual-return fallback when no verified OS activation contract is
+available. The browser flow uses a loopback callback, state validation, and PKCE. It creates
+an API Key through the current build's backend, stores it locally, and requests
+that macOS or Windows return to the selected application after the hosted success
+page acknowledges it is ready, with a bounded fallback if that acknowledgement is blocked. If the browser or app
+cannot be opened, the CLI prints a localized manual fallback. Use `--no-browser`
+to print the authorization URL for a headless environment.
+
+Browser authorization only runs against the backend paired with the current CLI
+build. Remove `OIIOII_BASE_URL` and use `--reset-base-url` when an older persisted
+override is present. For a custom backend, use the explicit `--api-key` mode.
+
+You can still persist an existing MCP API Key only through the explicit
+`--api-key` mode. The CLI keeps the backend URL
+embedded for its build environment unless you explicitly override it:
+
+```bash
+oiioii auth login --api-key "oii_sk_..."
+```
+
+The CLI writes the API Key to `~/.oiioii/config.json` with file permissions
+`0600`. Pass `--base-url` only for an intentional backend override.
+`OIIOII_API_KEY` remains available as a temporary process override. A legacy
+`~/.oiioii/credentials.json` file, if present, is ignored.
+
+Remove an existing backend override and return to the default embedded in the
+current CLI build:
+
+```bash
+oiioii auth login --api-key "oii_sk_..." --reset-base-url
+```
 
 Create a workspace using the injected API Key:
 
@@ -173,6 +236,26 @@ oiioii workspace set <workspace_id> --json
 oiioii workspace current --json
 ```
 
+Rename the active workspace, or pass an explicit workspace ID:
+
+```bash
+oiioii workspace rename --name "Renamed project" --json
+oiioii workspace rename <workspace_id> --name "Renamed project" --json
+```
+
+List assets in the active workspace and download a ready asset by its workspace
+asset ID:
+
+```bash
+oiioii workspace assets list --json
+oiioii workspace assets download <asset_id> --output ./downloads --json
+```
+
+`workspace assets download` accepts either the plain `assetId` or the
+`hogi://asset/<assetId>` identity returned by the list command. It resolves that
+identity to the asset's downloadable `uri`; loading, uploading, empty, failed,
+or URI-less assets fail before the download request.
+
 Workspace resolution order is:
 
 1. Root `--workspace <id>` option.
@@ -308,7 +391,7 @@ oiioii audio generate --prompt "为画面生成氛围音" --image hogi://image/<
 ```
 
 Suno supports description mode, custom lyrics/style mode, and instrumental
-music. The supported variants are `chirp-v4-5` and `chirp-v5`:
+music. The supported variants are `chirp-v4-5`, `chirp-v5`, and `chirp-v5-5`:
 
 ```bash
 oiioii audio generate --prompt "cinematic orchestral background music" --model suno --instrumental --json
@@ -546,12 +629,25 @@ The public commands accept the cached backend ID or local ID:
 oiioii task list
 oiioii task status <task_id>
 oiioii task wait <task_id> --timeout 300
+oiioii task retry <local_task_id>
 ```
 
 For non-terminal tasks, `status` makes one authenticated backend query and
 `wait` polls the backend until a terminal state or `TASK_TIMEOUT`. Every query
 uses the workspace cached with the original submission.
 
+A network error or timeout before the CLI receives a backend task ID has an
+unknown submission outcome, so the local task remains `submitting` instead of
+being marked `failed`. Run the `retry` command shown in the JSON error. It
+reuses the original local task ID and saved submission request as the
+idempotency key, allowing the backend to return the already-accepted task
+without creating a duplicate generation.
+The task stores only a one-way fingerprint of the submitting API Key; retry is
+refused if the active credential has changed because backend idempotency is
+scoped to the authenticated principal.
+`task wait` fails immediately with `TASK_RETRY_REQUIRED` for this state instead
+of waiting for a backend ID that only an explicit retry can recover.
+
 Existing preview bundles can be read with:
 
 ```bash
@@ -623,6 +719,7 @@ Stable error codes include:
 | `GENERATION_TIMEOUT` | Long-running request timed out |
 | `RECORD_NOT_FOUND` | Record/resource/bundle not found |
 | `TASK_NOT_FOUND` | Local task ID not found |
+| `TASK_RETRY_REQUIRED` | Submission outcome is unknown; retry the saved task with its original idempotency key |
 | `TASK_TIMEOUT` | Local task did not become terminal before the wait deadline |
 | `QUOTA_EXCEEDED` | Insufficient points, subgroup quota, or backend rate limit exceeded |
 | `PAYLOAD_TOO_LARGE` | Upload exceeds the backend limit |
@@ -648,15 +745,43 @@ feature.started
   -> feature.completed | feature.failed
 ```
 
-This is CLI-side observability only. It does not collect or depend on logs from
-inside the Hogi backend.
-
-Recorded API events use the same `request_id` for correlation:
+Logs remain local; backend response IDs link them to server logs without
+downloading server logs. Recorded API events use the same `clientRequestId`
+(also stored as the backwards-compatible `request_id`) for local correlation:
 
 ```text
 api.request -> api.response | api.error
 ```
 
+| Field | Meaning |
+| --- | --- |
+| `id` | Unique local log record ID, not a backend chain ID. |
+| `trace_id` | One CLI command, including all of its HTTP calls. |
+| `clientRequestId` / legacy `request_id` | One local API call, pairing its start and result/error. |
+| `logid` | Backend chain ID read from response header `x-logid`. |
+| `requestId` | Current gateway request ID read from response header `x-request-id`; never generated by CLI. |
+| `uid` | Server request identity returned in `x-hogi-log-uid`, or already verified for the command's endpoint/credential. Public routes can return `anonymous_user`. |
+| `workspaceId` | Explicit business target, command workspace, or `x-hogi-log-workspace-id` from the response. |
+
+CLI sends an optional `x-workspace-id` diagnostic hint. Authentication still uses
+the API Key; neither a client-provided uid nor a workspace hint authorizes access.
+Incoming response fields are optional, including when talking to older servers.
+Malformed/missing diagnostics and logging failures do not reject requests.
+
+Before the response arrives, `api.request` cannot know its backend/gateway IDs.
+They appear on `api.response` or `api.error` after receiving headers. Network
+failures without a response legitimately have neither. Follow `clientRequestId`
+back to the start event and `trace_id` to other steps of the command. Command
+steps do not inherit the last HTTP request's `logid` or `requestId`: concurrent
+calls, polling and follow-up requests retain their own IDs. The REST envelope's
+legacy `request_id` is another API-generated ID, not the gateway `requestId`.
+
+Resource downloads retain IDs from the backend's 302 redirect and emit
+`api.redirect` before following the CDN URL. Cross-origin redirects strip
+credentials and workspace hints; CDN request IDs do not replace backend IDs.
+Public resource reads retain their existing anonymous access/watermark behavior;
+an anonymous response does not erase the command's previously verified identity.
+
 Feature traces cover workspace, image/video/audio generation, upload, records,
 inspection, preview, task commands, and their local storage steps. API boundary
 events cover:
@@ -664,10 +789,12 @@ events cover:
 - GenAI and Asset MCP calls.
 - Resource upload and download.
 - Generation-record lookup.
+- Workspace REST, debug APIs, model catalog and authorization exchange.
+- Each VOD token, commit and polling HTTP request (third-party byte upload is separate).
 
 Logs contain safe operational fields such as source, operation, HTTP method,
 path, status, duration, and selected non-sensitive metadata. They do not record
-request headers, API Keys, bearer tokens, prompts, request bodies, or response
+arbitrary request headers, API Keys, bearer tokens, prompts, request bodies, or response
 bodies. Sensitive key names and recognizable secret values are redacted again
 inside the central logger before persistence.
 
@@ -690,6 +817,9 @@ oiioii logs list --category api --level error --limit 20 --json
 oiioii logs list --source hogi_mcp_client --since 2026-08-14T00:00:00Z --json
 oiioii logs list --feature image.text --json
 oiioii logs list --trace trace_<id> --json
+oiioii logs list --logid <backend-logid> --json
+oiioii logs list --request-id <gateway-requestId> --json
+oiioii logs list --uid <uid> --workspace-id <workspaceId> --json
 ```
 
 Export logs as JSONL or JSON:
@@ -769,7 +899,10 @@ Environment variables:
 | `OIIOII_BASE_URL` | Override the backend URL at runtime |
 | `OIIOII_WORKSPACE_ID` | Override the active workspace |
 | `OIIOII_BUILD_ENV` | Select `production`, `test`, or `local` while building |
-| `OIIOII_BUILD_BASE_URL` | Override the URL embedded in a build |
+| `OIIOII_PRODUCTION_BASE_URL` | Optional override for the production build's canonical backend URL |
+| `OIIOII_TEST_BASE_URL` | URL embedded by the test build |
+| `OIIOII_TEST_AUTHORIZATION_PAGE_URL` | Browser authorization page embedded by the test build |
+| `OIIOII_BUILD_BASE_URL` | One-off URL override for a local/custom build; rejected by publish preparation |
 | `OIIOII_API_KEY` | Temporarily override the persisted API Key for the current process |
 | `OIIOII_E2E` | Explicit opt-in marker for credit-consuming E2E workflows |
 | `OIIOII_LOG_DISABLED` | Set to `1` to disable local logging, primarily for isolated tests |
@@ -793,13 +926,11 @@ files at present; running the normal test command does not consume GenAI credits
 
 Most recent local verification for this README update:
 
-- 45 test files passed.
-- 333 tests passed.
+- 54 test files passed.
+- 454 tests passed; 2 Windows-only installer tests were skipped on macOS.
 - `npm run typecheck` passed.
 - `npm run lint` passed.
-- Production, HOE test, and local builds passed; their embedded backend
-  URLs were verified as `api.oiioii.ai`, `api-hoe.oiioii.tv`, and
-  `localhost:4000` respectively.
+- Production, injected test, and local build configuration passed.
 
 ## Project Structure
 
@@ -825,7 +956,17 @@ oiioii-cli/
   tests/
     unit/                          Unit tests
     cli/                           CLI subprocess integration tests
-  .plan/release/                   Standalone installer workflow/assets
+  scripts/
+    build-environment.mjs          Loads environment-specific build configuration
+    build-test-runtime.mjs         Creates the independent test static runtime
+    install.sh                     Production macOS/Linux npm installer
+    install.ps1                    Production Windows npm installer
+    test/
+      install.sh                   Test macOS/Linux installer template
+      install.ps1                  Test Windows installer template
+      dist/                        Ignored generated installers and MD5 runtime
+    prepare-publish.mjs            Environment-aware npm publish preparation
+    verify-release-version.mjs     Release channel/version validation
   tsup.config.ts                   Environment-aware ESM bundling
   package.json
 ```