@uniai-test-1/cli 0.1.0

package/install.md

@@ -0,0 +1,167 @@
+# UniAI CLI — install guide (for AI agents)
+
+**This document is written for an AI agent.** Follow the steps below to install and verify the
+**UniAI CLI** (npm package `@uniai/cli`, command `uniai`) on the user's machine. The user normally
+installs it globally via **npm** and does **not** need this repository's source. Do not invent
+version numbers or paths; defer to the user's actual environment.
+
+The CLI is built for agents: every command accepts `--json` and returns a structured envelope, so
+read the JSON fields (`ok`, `text`, `url`, `error`) instead of scraping prose.
+
+---
+
+## 1. Pre-install checks
+
+**Principle:** run the checks first; if **Node / npm / network** does not meet the requirements
+below, the agent should **fix the environment itself in the user's terminal** (e.g. upgrade Node,
+configure an npm registry/proxy) and then continue. Only escalate to the user when you lack
+permission or the environment cannot be automated.
+
+1. **Node.js** — requires **>= 20.0.0**. Verify with `node -v`. If missing or too old, install or
+   upgrade Node.
+2. **npm** (**the only** supported package manager) — verify with `npm -v`. If broken, repair npm.
+   Do **not** use `pnpm` / `yarn` to install `@uniai/cli`; even if they are present they are only
+   for other projects.
+3. **Network** — must be able to reach the npm registry (default `registry.npmjs.org`). If
+   unreachable, configure a mirror or proxy, then retry.
+
+---
+
+## 2. Install the CLI (and, optionally, skills)
+
+**Only the commands below are allowed** (do not use `pnpm add -g`, `yarn global add`, etc.). Run
+them in order; proceed to the next step only after the previous one passes.
+
+### 2.1 Install the CLI
+
+```bash
+npm install -g @uniai/cli
+```
+
+**Verify** (check the exit code and output):
+
+```bash
+uniai --version
+which uniai   # on Windows: where uniai
+```
+
+If `command not found`: the global bin directory is not on `PATH`. Check `npm config get prefix`;
+its `bin` directory must be on `PATH`.
+
+### 2.2 Install the UniAI agent skill (recommended)
+
+Register the UniAI skill so agents (Claude Code, Cursor, codex, ...) discover the `uniai` command and
+use it on their own. It installs into the shared `~/.agents/skills` and is symlink-bridged into each
+agent's native skills directory.
+
+Pull the latest **published** skill from the remote source. The content there is maintained
+out-of-band, so re-running this command picks up updates without reinstalling the CLI:
+
+```bash
+uniai skills add Clion-a/uniai-skills --ref release -g
+uniai skills list -g
+```
+
+`--ref release` pins to the published tag (not in-progress drafts). The command **auto-falls back** to
+the copy bundled in this npm package when the remote is unreachable (offline / rate-limited / no git);
+you can also force the bundled copy explicitly:
+
+```bash
+uniai skills add --self -g
+```
+
+---
+
+## 3. Authentication (required before any API call)
+
+UniAI authenticates with a **Personal Access Token (PAT)** that starts with `uap_`. Get one from
+the UniAI web console: **log in → Personal Center → Security tab → Personal Access Tokens → Generate**
+(<https://www.uniai.ai>).
+
+Always probe the current state first, then act, then confirm with a masked value.
+
+### Recommended: persist the token once
+
+1. Point the user to create/copy a PAT at **<https://www.uniai.ai> → Personal Center → Security tab →
+   Personal Access Tokens → Generate**.
+2. Offer **two ways to log in** and let the user choose:
+   - **(A) you do it** — the user pastes the token into the chat and you run the command yourself via
+     your shell/terminal tool (do **not** echo the token back in your prose replies);
+   - **(B) they do it** — the user runs the command in their own terminal, so the token never passes
+     through the chat (prefer this if they are security-conscious).
+
+   ```bash
+   uniai auth login --token <USER_PROVIDED_PAT>
+   ```
+
+3. Confirm:
+
+   ```bash
+   uniai auth status   # prints a masked token only, never the full value
+   ```
+
+### Other ways
+
+- **Environment variable** (no file written): set `UNIAI_TOKEN=uap_...` in the shell.
+- **Per-command flag** (this run only, not persisted): append `--token uap_...` to any command,
+  e.g. `uniai chat "hello" --token uap_...`.
+- **Custom / on-prem endpoint**: pass `--api-base <url>`, set `UNIAI_API_BASE`, or
+  `uniai config set --key apiBase --value <url>`. The default is `https://www.uniai.ai/api/v1`.
+
+Credential precedence: `--token` > `UNIAI_TOKEN` env > `~/.uniai/config.json`.
+
+### Agent security boundaries
+
+- **Never** write a real PAT into repositories, logs, skills, or the public part of a chat
+  transcript. When reporting status, use only the **masked** field; never echo the full token.
+- In CI / non-interactive environments, inject the token via a secret manager or env var; never
+  hardcode it in a script. Read errors from the `--json` envelope rather than printing raw output.
+
+---
+
+## 4. Minimal functional verification
+
+After authentication, run a real round-trip and read the structured fields:
+
+```bash
+uniai auth status
+uniai chat "ping" --json
+```
+
+A successful chat prints `{"ok":true,"text":"..."}`. On failure it prints
+`{"ok":false,"error":"..."}` — diagnose from the `error` field (network, invalid token, out of
+credits, etc.) and consult the table below.
+
+---
+
+## 5. Troubleshooting (agent checklist)
+
+| Symptom | Likely cause | Suggested action |
+| --- | --- | --- |
+| `uniai: command not found` | global bin not on `PATH` | check `npm config get prefix`, add its `bin` to `PATH` |
+| install error mentioning `engines` | Node too old | upgrade Node to **>= 20** |
+| `{"ok":false,"error":"...401..."}` / auth failed | not logged in or invalid/expired PAT | regenerate the PAT in the console, then `uniai auth login --token <PAT>` |
+| `{"ok":false,"error":"...402..."}` / out of credits | insufficient credits | ask the user to top up in the console, then retry |
+| cannot reach the API / network error | network, proxy, or wrong endpoint | check connectivity; for on-prem pass `--api-base <url>` |
+| only `pnpm` available, no `npm` | agent tried to install with pnpm | install/repair **npm** first, then `npm install -g @uniai/cli` (do not use pnpm) |
+
+---
+
+## What you can do once installed
+
+Tell the user, briefly, what the CLI enables — calling UniAI platform features straight from the
+terminal, all with `--json` for scripting:
+
+```bash
+uniai chat "explain async/await in one paragraph"
+uniai image generate "a watercolor fox" --download fox.png
+uniai video generate "a drone shot over mountains" --aspect-ratio 16:9 --download clip.mp4
+uniai speech synthesize "hello world" --download hello.mp3
+uniai speech recognize ./note.m4a --language auto
+uniai ocr ./receipt.jpg
+uniai usage                       # check your credit balance before spending (alias: quota)
+uniai code "binary search in rust" --language rust
+uniai search "latest on WebGPU" --limit 5
+```
+
+Run `uniai <command> --help` for the full options of any single command.

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@uniai-test-1/cli",
+  "version": "0.1.0",
+  "private": false,
+  "description": "UniAI CLI — install UniAI's MCP tool server into an external Codex CLI (init / uninstall / status), call UniAI platform features directly from the terminal (chat / image / video / speech / code / search), or install Agent Skills into ~/.agents/skills (skills add / list / remove).",
+  "type": "module",
+  "keywords": [
+    "cli",
+    "mcp",
+    "codex",
+    "ai-agent",
+    "agent-skills",
+    "image-generation",
+    "video-generation",
+    "text-to-speech",
+    "speech-to-text",
+    "web-search",
+    "uniai",
+    "llm"
+  ],
+  "author": "UniAI (https://www.uniai.ai)",
+  "bin": {
+    "uniai": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "install.md",
+    "skill"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit --pretty",
+    "build": "tsc --noEmit && node esbuild.config.mjs && node scripts/copy-bundle.mjs",
+    "prepack": "npm run build",
+    "test": "node --import tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run build && npm test && node scripts/prepublish-guard.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.9",
+    "esbuild": "^0.25.0",
+    "tsx": "^4.16.2",
+    "typescript": "^5.4.5"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://www.uniai.ai"
+  },
+  "homepage": "https://www.uniai.ai",
+  "bugs": {
+    "url": "https://www.uniai.ai"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: uniai-cli
+description: Call UniAI platform AI features from the terminal with the `uniai` CLI — text chat, image generation & editing, video generation, text-to-speech (TTS) and speech recognition (STT), OCR, web search, code generation, and credit-balance checks. Use whenever the user wants to create an image or video, synthesize or transcribe speech, read text out of an image, search the web for current information, generate code, chat with a model, or check their UniAI credits — and the `uniai` command is available on PATH.
+---
+
+# UniAI CLI
+
+The `uniai` command calls UniAI platform AI features directly from the terminal. Every command
+accepts `--json` and returns a structured envelope, so prefer `--json` and read the fields
+(`ok`, `text`, `url`, `credits`, `error`) instead of scraping prose.
+
+## When to use this skill
+
+Reach for `uniai` when the user wants any of: an image, a video, speech audio (TTS), a transcript
+of audio (STT), text read out of an image (OCR), a web search for up-to-date information, generated
+code, a quick model chat, or their credit balance — and `uniai` is installed.
+
+## Prerequisites
+
+- `uniai --version` must succeed. If it is missing, install with `npm i -g @uniai/cli` (npm only;
+  do not use pnpm/yarn for this), or have the user read the package's `install.md`.
+- Auth: needs a UniAI Personal Access Token (PAT, starts with `uap_`). Probe with `uniai auth status`
+  (prints a masked token). If it is not configured, first tell the user to create a PAT at
+  <https://www.uniai.ai> → Personal Center → Security tab → Personal Access Tokens → Generate, then
+  offer **two ways to log in** and let them choose:
+  - **(A) you do it** — they paste the token into the chat and you run `uniai auth login --token
+    <pasted_pat>` yourself via your shell/terminal tool.
+  - **(B) they do it** — they run `uniai auth login --token <pat>` themselves in their own terminal,
+    so the token never passes through the chat (prefer this if they are security-conscious).
+  After either path, verify with `uniai auth status`. Security: never echo the token back in your
+  prose replies — report only the masked value.
+- Before a paid generation (image/video/speech), you may check budget first with
+  `uniai usage --json` and read `credits.total`.
+
+## Commands
+
+```bash
+uniai chat "<message>" --json
+uniai image generate "<prompt>" [--model <id>] [--aspect-ratio 1:1|16:9|9:16|4:3|3:4|21:9|3:1] [--count <n>] [--quality low|medium|high] [--reference <path|url>[,...]] [--download out.png] --json
+uniai image models --json     # list available image models + their supported params
+uniai image edit --image <url> [--output-format png|jpg|webp] [--download out.png] --json
+uniai video generate "<prompt>" [--model <id>] [--aspect-ratio 16:9|9:16|1:1] [--duration <2-15>] [--first-frame <img>] [--reference <img,..>] [--source-video <vid>] [--download out.mp4] --json
+uniai video models --json     # list available video models + their modes/durations/resolutions
+uniai speech synthesize "<text>" [--voice <id>] [--format mp3|wav] [--download out.mp3] --json
+uniai speech recognize <audio: path|url> [--language auto|zh|en|ja|ko] --json
+uniai ocr <image: path|url> --json
+uniai search "<query>" [--limit 1-20] --json
+uniai code "<description>" --language <python|typescript|...> --json
+uniai usage --json            # credit balance (alias: uniai quota)
+```
+
+For media commands, pass `--download <file>` to save the result locally; report the saved path to
+the user. Run `uniai <command> --help` for the full options of any single command.
+
+**Image-to-image (from an uploaded/existing photo):** when the user wants a new image based on a photo
+they gave you — e.g. "full-body shot of this person", "change the clothing", "same character, new
+pose", "make a variation of this" — use `uniai image generate "<prompt>" --reference <path>` and pass
+the photo's **local file path** (the tool uploads it for you; up to 5, comma-separated). Do NOT use
+`uniai image edit` for that — `edit` only sharpens/feathers edges or processes the background of a URL,
+it cannot follow a prompt or change content.
+
+**Choosing model / parameters:** the CLI does not pop confirmation dialogs — it passes only the flags
+you give and uses the platform-recommended model + parameters for everything else. So if the user cares
+about the model, aspect ratio, count, or quality, ask them (or run `uniai image models` to show the
+options), then pass the matching flags (`--model`, `--aspect-ratio`, `--count`, `--quality`). If they
+don't care, just generate; sensible defaults are used. (No need to re-implement a selection flow — the
+recommendation/confirmation logic lives in the shared core.)
+
+**Video from an image / clip (animate, edit, extend):** for `uniai video generate`, the mode is
+auto-derived from the media you attach — `--first-frame <img>` animates a photo (image-to-video),
+`--first-frame` + `--last-frame` interpolates first→last, `--reference <img,..>` does reference-to-video,
+`--source-video <vid>` edits/restyles a clip, `--continuation-video <vid>` extends one; none = text-to-video.
+Pass the user's uploaded file's **local path** (it is uploaded for you). A prompt is always required
+(describe the motion/scene). Run `uniai video models` to see which models support which modes. The same
+`--model` / `--aspect-ratio` / parameter logic as image applies.
+
+## Output contract
+
+- success: `{"ok":true,"text":"...","url":"<media url, when applicable>"}`
+- failure: `{"ok":false,"error":"..."}`
+- exit codes: `0` success · `1` runtime / auth / network error · `2` invalid usage
+
+On `out of credits`, tell the user to top up in the UniAI web console. On an auth failure, have them
+re-run `uniai auth login --token uap_...`. On a forbidden/scope error for `usage`, the PAT needs the
+`read:credits` scope.