@atelierai/uco 1.0.0

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@atelierai/uco",
+  "version": "1.0.0",
+  "description": "uco — Unity Co-Pilot CLI. Drive Unity Editor (and runtime game builds) from any AI agent via plain HTTP. No MCP protocol on the wire.",
+  "type": "module",
+  "bin": {
+    "uco": "./bin/uco.mjs",
+    "uco-server": "./bin/server.mjs",
+    "uco-stub-plugin": "./bin/stub-plugin.mjs"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./transport": "./dist/transport/index.js",
+    "./config": "./dist/config/resolve.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "watch": "tsc -p tsconfig.json --watch",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "start": "node bin/cocli.mjs",
+    "dev": "tsx src/index.ts",
+    "prepack": "npm run clean && npm run build",
+    "stage-vendor": "node scripts/stage-vendor.mjs"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "skills",
+    "vendor",
+    "docs/INSTALL.zh-CN.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^12.1.0",
+    "kleur": "^4.1.5",
+    "ws": "^8.18.0",
+    "yocto-spinner": "^1.2.0"
+  },
+  "bundledDependencies": [
+    "chalk",
+    "commander",
+    "kleur",
+    "ws",
+    "yocto-spinner"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/ws": "^8.5.13",
+    "rimraf": "^5.0.5",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.4",
+    "vitest": "^3.1.0"
+  },
+  "keywords": [
+    "unity",
+    "cli",
+    "ai-agent",
+    "claude-code",
+    "unity-mcp",
+    "automation"
+  ],
+  "license": "MIT",
+  "author": "AtelierAI",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DumoeDss/uco.git"
+  },
+  "homepage": "https://github.com/DumoeDss/uco#readme",
+  "bugs": "https://github.com/DumoeDss/uco/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/uco-setup/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: uco-setup
+description: Bootstrap or repair uco integration in a Unity project. Use for Unity Co-Pilot plugin installation or updates, NuGet/config staging, agent Skill generation or migration, project wrapper repair, and bridge readiness failures. Not for routine Editor changes or official Unity lifecycle commands.
+---
+
+# uco setup
+
+Use this Skill for project integration, not ordinary Unity authoring. Run installed project commands through the shared wrapper when it exists:
+
+```bash
+node .uco/agent-runtime/scripts/uco.mjs <command> [...args]
+```
+
+If the wrapper is absent or broken, invoke the installed `uco` command or its known checkout directly, then regenerate the bundle.
+
+## Bootstrap sequence
+
+1. Confirm the target contains `Assets/`, `Packages/`, and `ProjectSettings/`.
+2. Inspect before mutation (both commands print their planned actions and write nothing):
+
+```bash
+uco install-plugin <project> --dry-run
+uco install <project> --dry-run
+```
+
+3. Install the Unity Co-Pilot package alone with `install-plugin`, or use `install` when NuGet and configuration staging are also required.
+4. Open the project and wait for package resolution/compilation.
+5. Require runtime readiness before reading the live catalog:
+
+```bash
+uco open <project>
+uco wait-for-ready <project> --timeout 180000
+uco --project <project> ping
+```
+
+6. Generate the three project Skills:
+
+```bash
+uco setup-skills codex <project> --dry-run
+uco setup-skills codex <project> --migrate-legacy
+```
+
+The result must contain exactly `uco-setup`, `unity-cli`, and `unity-editor`, plus the non-discoverable `.uco/agent-runtime` support directory.
+
+## Ownership boundaries
+
+- `uco create-project`, `install-plugin`, `install`, `configure`, `setup-mcp`, and `setup-skills` belong here.
+- Installing or using the official `unity` executable, Editor inventory, auth/license, and process-based build/test belong to `$unity-cli`.
+- Scene, GameObject, asset, script, graphics, physics, console, profiler, screenshot, and in-Editor tests belong to `$unity-editor`.
+- `open` and `wait-for-ready` are setup handoff commands here; routine runtime preflight is also summarized in `$unity-editor` so normal development does not load this Skill.
+
+Never print project tokens or silently replace an unmanaged Skill directory. For failed installs, stale wrappers, package resolution, or connection diagnosis, read [recovery](references/recovery.md).

package/skills/uco-setup/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "uco Setup"
+  short_description: "Bootstrap and repair uco Unity project integration"
+  default_prompt: "Use $uco-setup to initialize or repair uco for this Unity project."
+
+policy:
+  allow_implicit_invocation: true

package/skills/uco-setup/references/recovery.md

@@ -0,0 +1,24 @@
+# uco integration recovery
+
+Read this only after the bootstrap happy path fails.
+
+## Diagnose by layer
+
+1. Verify `Packages/manifest.json` contains `com.atelierai.unity.copilot` and inspect its source/version without rewriting unrelated dependencies.
+2. Check the OpenUPM scopes required by the package and preserve an active local package source.
+3. Check that `Assets/Plugins/NuGet` is present when using full `uco install`. (No server directory is staged — the Unity plugin launches its Node server itself.)
+4. Check `UserSettings/AI-Game-Developer-Config.json` exists, but never print its token.
+5. Confirm the expected Unity Editor process owns this exact project before diagnosing REST readiness.
+6. Use `uco status`, then `open` plus `wait-for-ready`; only then run `ping` and `instance-get-current`.
+
+## Safe repair
+
+- Run `install-plugin --dry-run` or `install --dry-run` before mutation.
+- Close Unity before a repair that replaces staged NuGet files or rewrites package resolution state.
+- If package installation fails after project creation, retain the project and retry `install-plugin`; do not recreate the project or switch lifecycle backend blindly.
+- After package or script changes, reopen Unity, wait for import/domain reload, and inspect new console errors.
+- Regenerate Skills only from a ready live catalog. A moved uco checkout requires regeneration because the project wrapper pins the entry path.
+
+## Skill migration
+
+`setup-skills --migrate-legacy` removes only recognizable one-tool-per-Skill leaves in the selected agent root. A managed v1 `unity-copilot` bundle is upgraded automatically. User-authored files or unknown ownership cause a refusal instead of data loss.

package/skills/unity-cli/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: unity-cli
+description: Operate Unity's official unity CLI directly or through uco lifecycle wrappers. Use for Unity CLI or Editor/module installation, project creation and opening, auth, licensing, configuration, Pipeline/MCP, diagnostics, CI, or process-based run/build/test. Not for live scene or asset manipulation.
+---
+
+# Official Unity CLI
+
+Use raw `unity` for the complete official surface and uco for its bounded installation/lifecycle/build/test wrappers. These operations do not require a uco runtime ping. The official CLI is beta, so `unity <command> --help` is authoritative when examples drift.
+
+## Command ownership
+
+| Need | Command family |
+|---|---|
+| Install the official CLI explicitly | `uco setup-unity-cli` |
+| Discover/install Editors and modules | `unity editors/install/...` or uco `editors`/`install-unity` |
+| Create/register/open projects | `unity projects ...`, `unity open`, or uco `create-project` |
+| Auth, license, cloud, config, diagnostics | raw `unity auth`, `unity license`, `unity cloud`, `unity config`, `unity doctor` |
+| Process-based build/test/run | raw `unity build/test/run` or top-level uco `build/test` |
+| Official Pipeline/MCP bridge | raw `unity pipeline`, `unity status/list/command/mcp` |
+
+## Rules
+
+1. Prefer `--json` or another documented machine-readable format and check the process exit code.
+2. Use non-interactive flags/environment in CI; never allow a missing value to hang on a prompt.
+3. Do not require REST `ping` before Editor inventory/install, project creation/open, or process-based build/test/run.
+4. A non-empty `UNITY_CLI_PATH` is authoritative to uco. Automatic Hub fallback is absence-only and must never retry an already-started official mutation.
+5. Top-level uco `build` and `test` are official-only. Generated `build-*` and `tests-run` tools instead belong to `$unity-editor`.
+6. Do not place credentials in opaque build arguments, test tails, examples, logs, or Skill files.
+
+Quick inspection:
+
+```bash
+unity --version
+unity editors -i --json
+unity projects info .
+unity auth status
+```
+
+Read [installation and projects](references/installation-projects.md) for local lifecycle details. Read [automation and services](references/automation-services.md) for build/test/run, auth/license, CI, diagnostics, and Pipeline/MCP.

package/skills/unity-cli/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Unity CLI"
+  short_description: "Operate the official Unity CLI and batch workflows"
+  default_prompt: "Use $unity-cli to complete this official Unity CLI task."
+
+policy:
+  allow_implicit_invocation: true

package/skills/unity-cli/references/automation-services.md

@@ -0,0 +1,49 @@
+# Official automation, services, and diagnostics
+
+## Build, test, and run
+
+Build requires a real static C# execute method:
+
+```bash
+unity build . --target StandaloneWindows64 \
+  --execute-method BuildScript.BuildWindows --output-path Build/Game.exe --no-tail
+uco build . --target StandaloneWindows64 \
+  --execute-method BuildScript.BuildWindows --output-path Build/Game.exe --json
+
+unity test . --mode EditMode --output TestResults/editmode.xml
+uco test . --mode PlayMode --output TestResults/playmode.xml --timeout 1800 --json
+unity run . -- -nographics
+```
+
+The timeout after uco `test` is seconds; the root REST timeout is milliseconds. Batch/no-graphics execution has no normal Game view. Use a running GUI Editor or explicit render-texture flow for visual capture.
+
+## Auth, license, cloud, and CI
+
+```bash
+unity auth login
+unity auth status
+unity auth logout
+unity license
+unity cloud
+unity config
+```
+
+In CI, supply `UNITY_SERVICE_ACCOUNT_ID` and `UNITY_SERVICE_ACCOUNT_SECRET` through the secret store. Use non-interactive and machine-readable output without echoing secret values.
+
+## Pipeline and MCP
+
+```bash
+unity pipeline install --project-path .
+unity open .
+unity status
+unity list
+unity command
+unity mcp --project-path .
+unity mcp configure --list
+```
+
+Pipeline/MCP requires Unity 6 and an already-running Editor. It is distinct from uco's REST runtime bridge.
+
+## Diagnostics
+
+Use `unity doctor`, `diagnose`, `env`, `logs`, `cache`, `config`, `shell`, `completion`, `changelog`, and `upgrade` as appropriate. Redact reports before sharing them and prefer live help for current beta syntax.

package/skills/unity-cli/references/installation-projects.md

@@ -0,0 +1,47 @@
+# Official CLI installation, Editors, and projects
+
+## Install the CLI
+
+Use uco's bounded, explicit installer flow:
+
+```bash
+uco setup-unity-cli --dry-run --json
+uco setup-unity-cli
+# Non-interactive only after operator approval:
+uco setup-unity-cli --yes --json
+unity --version
+```
+
+Npm installation and ordinary uco discovery never execute Unity's remote installer implicitly. Raw platform installation uses Unity's documented installer and `UNITY_CLI_CHANNEL=stable|beta`.
+
+## Editors and modules
+
+```bash
+unity editors -i --json
+unity releases --lts
+unity install 6000.5.6f1 --accept-eula
+unity install-modules -e 6000.5.6f1 -l
+
+uco editors --diagnostics --json
+uco editors --releases --json
+uco install-unity 6000.5.6f1 --accept-eula --json
+```
+
+Specific historical versions may require release filters or a changeset. First install/import can take many minutes; interruption can leave partial state, so inspect before retrying.
+
+## Projects
+
+```bash
+unity projects list
+unity projects info .
+unity projects add ./MyGame
+unity projects remove ./MyGame
+unity projects new MyGame --path . --editor-version 6000.5.6f1 \
+  --template com.unity.template.3d --non-interactive
+unity open ./MyGame
+
+uco create-project ./MyGame --unity 6000.5.6f1 \
+  --template com.unity.template.3d --json
+```
+
+`uco create-project` installs `com.atelierai.unity.copilot` by default; project integration repair then belongs to `$uco-setup`. `unity open` proves process launch, not uco REST readiness.

package/skills/unity-editor/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: unity-editor
+description: Inspect or change a running Unity Editor through uco tools. Use for scenes, GameObjects, components, assets, scripts, packages, UI, graphics, physics, screenshots, console, profiler, live build jobs, or in-Editor tests. Requires a ready Unity Co-Pilot project bridge.
+---
+
+# Running Unity Editor
+
+Requires a ready project bridge. Use the project-pinned wrapper:
+
+```bash
+node .uco/agent-runtime/scripts/uco.mjs <command> [...args]
+```
+
+## Preflight and core loop
+
+```bash
+node .uco/agent-runtime/scripts/uco.mjs ping
+node .uco/agent-runtime/scripts/uco.mjs status --json
+```
+
+If the Editor is stopped, use `open` followed by `wait-for-ready`; process spawn alone is not REST readiness. If installation/configuration is broken rather than merely stopped, use `$uco-setup`.
+
+For every task:
+
+1. Inspect/find/read before mutation.
+2. Prefer the narrowest typed tool and use `<tool> --help` for ordinary flags.
+3. For a nested or unclear payload, extract exactly one schema:
+
+```bash
+node .uco/agent-runtime/scripts/tool-info.mjs <exact-tool-name>
+```
+
+4. Make the smallest coherent change, save Unity serialized state, and re-read it.
+5. After source/package changes, wait for import/domain reload and inspect new console errors.
+6. Use a focused in-Editor test or screenshot when behavior or appearance matters.
+
+Never load `.uco/agent-runtime/catalog/tools.json` wholesale.
+
+## Runtime reference map
+
+- [Scenes, GameObjects, components, assets, and prefabs](references/authoring.md)
+- [C# scripts, packages, docs, types, and reflection](references/code.md)
+- [Cameras, graphics, UI, textures, screenshots, and VFX](references/visuals.md)
+- [Physics queries, colliders, rigidbodies, and simulation](references/physics.md)
+- [Console, profiler, frame debugger, instances, and tool diagnostics](references/diagnostics.md)
+- [Live build jobs, build settings, batching, and in-Editor tests](references/build-and-tests.md)
+- [Preset instruction prompts](references/prompts.md)
+- [Read-only state resources](references/resources.md)
+
+Simple scene/GameObject reads and mutations can use the core loop without loading a reference. Raw official Editor/project lifecycle and process-based build/test/run belong to `$unity-cli`.

package/skills/unity-editor/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Unity Editor"
+  short_description: "Control a running Unity Editor through uco"
+  default_prompt: "Use $unity-editor to inspect or change this running Unity Editor."
+
+policy:
+  allow_implicit_invocation: true

package/skills/unity-editor/references/authoring.md

@@ -0,0 +1,7 @@
+# Scenes, GameObjects, components, assets, and prefabs
+
+Use this reference when the primary result is a Unity serialized-content change.
+
+Inspect open scenes and locate target objects/assets first. Use Unity asset operations when preserving `.meta` identity matters. Validate a representative mutation before batching; never batch destructive work merely to save latency. Save and re-read the scene, prefab, or asset, then inspect console errors.
+
+## Live tool groups

package/skills/unity-editor/references/build-and-tests.md

@@ -0,0 +1,11 @@
+# Live build jobs, build settings, batching, and in-Editor tests
+
+These tools operate through the already-running Editor bridge. They are not aliases for raw/top-level official process commands.
+
+- `build-*` can inspect build settings, manage scenes/platform, start a player build job, and poll its state.
+- `tests-run` executes inside the current ready Editor. Save every dirty scene first.
+- `batch-execute` reduces round trips for validated independent calls; do not hide ordering dependencies or destructive risk inside a batch.
+
+Use `$unity-cli` instead when the task is a standalone batch process, CI build/test/run, or does not need the current GUI Editor session.
+
+## Live tool groups

package/skills/unity-editor/references/code.md

@@ -0,0 +1,7 @@
+# C# scripts, packages, docs, types, and reflection
+
+Prefer `rg`, normal filesystem reads, and structured patches for local C# source. Use uco script tools for remote access, guarded edits, or Unity-owned representations. After source/package changes, wait for compilation/domain reload, inspect new console errors, and run the smallest relevant test.
+
+Prefer documented typed tools over reflection or arbitrary execution. Inspect a reflected method signature first and verify effects immediately. Do not repeat a package mutation merely because the bridge disappears during reload.
+
+## Live tool groups

package/skills/unity-editor/references/diagnostics.md

@@ -0,0 +1,7 @@
+# Console, profiler, frame debugger, instances, and tool diagnostics
+
+Capture the smallest relevant evidence before changing anything: new console entries, bounded counters/traces, frame events, or instance state. Test one hypothesis at a time and repeat the same measurement after an authorized fix.
+
+Profiler and frame-debugger capture can perturb results. Record capture conditions and keep output bounded. Unknown third-party prefixes remain reachable here with a generation warning.
+
+## Live tool groups

package/skills/unity-editor/references/physics.md

@@ -0,0 +1,7 @@
+# Physics queries, colliders, rigidbodies, and simulation
+
+Inspect objects, components, transforms, layers, and physics settings. Keep observation-only queries separate from serialized mutations. For nested shapes/filters, query one exact schema. Validate changes with a deterministic query or focused PlayMode test.
+
+Do not infer collider bounds from mesh appearance. Keep world/local coordinates, trigger policy, layer masks, 2D versus 3D physics, and fixed-step timing explicit. Restore temporary simulation/diagnostic settings.
+
+## Live tool groups

package/skills/unity-editor/references/prompts.md

@@ -0,0 +1,7 @@
+# Prompts
+
+Use this reference to discover preset instruction prompts (slash-command style templates) the Unity plugin exposes. Resolve a prompt with `uco prompt <name>` to inject its pre-written guidance into the AI context.
+
+Prompts do not passively consume context — they only apply when explicitly invoked.
+
+## Live prompt groups

package/skills/unity-editor/references/resources.md

@@ -0,0 +1,7 @@
+# Resources
+
+Use this reference to discover read-only state resources (editor state, project info, scene hierarchy, ...) the Unity plugin exposes. Read a resource with `uco resource <uri>`.
+
+Resources are fetched on-demand; they never modify state.
+
+## Live resources

package/skills/unity-editor/references/visuals.md

@@ -0,0 +1,7 @@
+# Cameras, graphics, UI, textures, screenshots, and VFX
+
+Inspect the render pipeline, scene, camera, and target assets first. Resolve references rather than guessing GUIDs. Make one coherent change, allow imports/shader compilation to finish, inspect console/graphics diagnostics, and view the produced image locally.
+
+Use Game view for player-facing composition and Scene view for authoring state. Batch/no-graphics runs do not provide a normal Game view. For UI, validate hierarchy, target resolutions, assets, interaction states, and contrast.
+
+## Live tool groups

package/skills/unity-editor/scripts/tool-info.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const catalogPath = fileURLToPath(new URL('../catalog/tools.json', import.meta.url));
+const indexPath = fileURLToPath(new URL('../catalog/tool-index.json', import.meta.url));
+const tools = JSON.parse(fs.readFileSync(catalogPath, 'utf8'));
+const index = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+const args = process.argv.slice(2);
+
+function usage() {
+  process.stderr.write('Usage: tool-info.mjs <exact-tool-name> | --search <text> | --list [domain]\n');
+}
+if (args[0] === '--list') {
+  const domain = args[1];
+  const entries = domain ? index.filter((entry) => entry.domain === domain) : index;
+  process.stdout.write(`${JSON.stringify(entries, null, 2)}\n`);
+  process.exit(0);
+}
+if (args[0] === '--search' && args[1]) {
+  const query = args.slice(1).join(' ').toLowerCase();
+  const matches = index.filter((entry) =>
+    `${entry.name} ${entry.title ?? ''} ${entry.description ?? ''}`.toLowerCase().includes(query))
+    .slice(0, 20);
+  process.stdout.write(`${JSON.stringify(matches, null, 2)}\n`);
+  process.exit(matches.length > 0 ? 0 : 1);
+}
+if (args.length !== 1) {
+  usage();
+  process.exit(2);
+}
+const tool = tools.find((entry) => entry.name === args[0]);
+if (!tool) {
+  process.stderr.write(`Unknown Unity tool: ${args[0]}\nRefresh the project Skills from a ready Editor catalog.\n`);
+  process.exit(1);
+}
+process.stdout.write(`${JSON.stringify(tool, null, 2)}\n`);

package/skills/unity-editor/scripts/uco.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const configPath = fileURLToPath(new URL('../catalog/project.json', import.meta.url));
+let config;
+try {
+  config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+} catch (error) {
+  process.stderr.write(`uco project wrapper could not read ${configPath}: ${error.message}\n`);
+  process.exit(1);
+}
+if (!fs.existsSync(config.ucoEntryPath)) {
+  process.stderr.write(`uco entry does not exist: ${config.ucoEntryPath}\nRegenerate project Skills from the uco checkout.\n`);
+  process.exit(1);
+}
+const result = spawnSync(
+  process.execPath,
+  [config.ucoEntryPath, '--project', config.projectPath, ...process.argv.slice(2)],
+  { cwd: config.projectPath, stdio: 'inherit', windowsHide: true },
+);
+if (result.error) {
+  process.stderr.write(`uco project wrapper failed: ${result.error.message}\n`);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);