@oiioii/cli 0.1.0 → 0.1.1

package/README.md

@@ -13,7 +13,8 @@ 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 |
+| `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.
+- Node.js 18.18 or newer when running from source or the npm package.
 - 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:
 
@@ -117,11 +127,24 @@ The default backend URL is 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:production` | production | `OIIOII_PRODUCTION_BASE_URL` from `.env` |
+| `npm run build:test` | test | `OIIOII_TEST_BASE_URL` from `.env` |
 | `npm run build:local` | local | `http://localhost:4000` |
 
-`npm run build` builds the test environment to preserve the existing default.
+Copy the environment template once, then use the environment-specific build
+entry points:
+
+```bash
+cp .env.example .env
+npm run build:production
+npm run build:test
+```
+
+`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,24 @@ The embedded URL is a fallback. Existing runtime overrides remain available:
 
 ## Authentication and Workspace
 
-Persist an existing MCP API Key and the backend URL:
+Persist an existing MCP API Key. The CLI keeps the backend URL embedded for its
+build environment unless you explicitly override it:
 
 ```bash
-oiioii auth login \
-  --api-key "oii_sk_..." \
-  --base-url "https://api-hoe.oiioii.tv"
+oiioii auth login --api-key "oii_sk_..."
 ```
 
-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.
+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 +208,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 +363,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 +601,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 +691,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 |
@@ -769,7 +838,9 @@ 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` | URL embedded by the production build |
+| `OIIOII_TEST_BASE_URL` | URL 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 +864,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 +894,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
 ```