@unifocl/codex-plugin 0.0.0

package/README.md

@@ -0,0 +1,117 @@
+# unifocl Codex Plugin
+
+This folder defines the Codex-side equivalent of `@unifocl/claude-plugin`.
+
+## What the Codex plugin should do
+
+Unlike Claude Code's npm plugin format, Codex integration is primarily:
+
+1. MCP server registration (`unifocl --mcp-server`)
+2. Reusable workflow guidance (Codex skill/playbook)
+
+So the Codex plugin is a **distribution bundle** made of:
+
+- MCP setup automation
+- Codex skill files for `/init`, `/status`, `/context`, `/mutate`, `/workflow`-equivalent flows
+
+## Functional Scope
+
+The Codex plugin must provide the same workflow guarantees as the Claude plugin:
+
+- `/init` equivalent: project bridge setup + post-checks
+- `/status` equivalent: daemon/mode/project/editor/session checks
+- `/context` equivalent: hierarchy + project + inspector hydration
+- `/mutate` equivalent: schema -> validate -> dry-run -> execute -> verify sequence
+- `/workflow` equivalent: canonical multi-step agent workflow
+
+The low-level behavior continues to live in:
+
+- `unifocl --mcp-server`
+- `unifocl exec "..."`
+
+No mutation logic is duplicated in this package.
+
+## Distribution Strategy (No source checkout required)
+
+Not all users clone this repository, so distribution should be release-based:
+
+1. **Primary channel: npm package**
+   - Publish: `@unifocl/codex-plugin`
+   - Contains:
+     - install script that runs Codex MCP registration
+     - bundled skill templates/playbooks
+   - One-liner install target:
+     - `npm install -g @unifocl/codex-plugin`
+     - then run `unifocl-codex-plugin install`
+
+2. **Binary channel: built-in CLI command (recommended follow-up)**
+   - Add command to `unifocl` binary:
+     - `unifocl agent install codex`
+   - This command:
+     - detects Codex config location
+     - registers `mcpServers.unifocl`
+     - installs/updates unifocl skill files under `$CODEX_HOME/skills/unifocl`
+   - Benefit: works for Homebrew/winget/release-binary users with no Node.js requirement.
+
+3. **GitHub release asset fallback**
+   - Ship a small cross-platform installer script in release assets:
+     - `install-codex-plugin.sh`
+     - `install-codex-plugin.ps1`
+   - Users download from release page and run once.
+
+## Versioning & Compatibility
+
+- Keep plugin version aligned with unifocl CLI minor version.
+- On protocol-affecting changes, include migration guidance (for example: rerun `/init`).
+- Installer should be idempotent and safe to rerun.
+
+## File Layout
+
+```text
+src/unifocl.codex-plugin/
+  README.md
+  package.json
+  bin/unifocl-codex-plugin.js
+  skills/unifocl/SKILL.md
+  skills/unifocl/references/init.md
+  skills/unifocl/references/status.md
+  skills/unifocl/references/context.md
+  skills/unifocl/references/mutate.md
+  skills/unifocl/references/workflow.md
+```
+
+## Minimal install behavior
+
+Installer should execute equivalent of:
+
+```bash
+scripts/setup-mcp-agents.sh --workspace <detected-or-provided-workspace> --codex
+```
+
+Then copy bundled skill files to:
+
+```text
+$CODEX_HOME/skills/unifocl/
+```
+
+and print verification steps:
+
+1. Restart Codex session.
+2. Confirm MCP tools include `ListCommands` and `LookupCommand`.
+3. Run a smoke check with `unifocl exec "/status" --agentic --format json`.
+
+## Publish From CLI
+
+From this directory:
+
+```bash
+cd src/unifocl.codex-plugin
+npm publish --access public
+```
+
+If this is your first publish for the scope:
+
+```bash
+npm login
+npm publish --access public
+```

package/bin/unifocl-codex-plugin.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const cp = require("node:child_process");
+
+function printUsage() {
+    console.log(`Usage:
+  unifocl-codex-plugin install [--server-name <name>] [--config-root <path>] [--skills-dir <path>]
+  unifocl-codex-plugin doctor
+  unifocl-codex-plugin help
+`);
+}
+
+function fail(message) {
+    console.error(`error: ${message}`);
+    process.exit(1);
+}
+
+function run(command, args, options = {}) {
+    const result = cp.spawnSync(command, args, {
+        stdio: "pipe",
+        encoding: "utf8",
+        ...options
+    });
+    return result;
+}
+
+function ensureCommandExists(command) {
+    const checker = process.platform === "win32" ? "where" : "which";
+    const result = run(checker, [command]);
+    if (result.status !== 0) {
+        fail(`required command not found on PATH: ${command}`);
+    }
+}
+
+function parseArgs(argv) {
+    const positional = [];
+    const options = {
+        serverName: "unifocl",
+        configRoot: "",
+        skillsDir: ""
+    };
+
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "--server-name") {
+            options.serverName = argv[++i] || "";
+            continue;
+        }
+        if (token === "--config-root") {
+            options.configRoot = argv[++i] || "";
+            continue;
+        }
+        if (token === "--skills-dir") {
+            options.skillsDir = argv[++i] || "";
+            continue;
+        }
+        positional.push(token);
+    }
+
+    return { positional, options };
+}
+
+function resolveCodexHome() {
+    if (process.env.CODEX_HOME && process.env.CODEX_HOME.trim() !== "") {
+        return path.resolve(process.env.CODEX_HOME);
+    }
+    return path.join(os.homedir(), ".codex");
+}
+
+function copyDirRecursive(srcDir, dstDir) {
+    fs.mkdirSync(dstDir, { recursive: true });
+    const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(srcDir, entry.name);
+        const dstPath = path.join(dstDir, entry.name);
+        if (entry.isDirectory()) {
+            copyDirRecursive(srcPath, dstPath);
+        } else {
+            fs.copyFileSync(srcPath, dstPath);
+        }
+    }
+}
+
+function install(options) {
+    ensureCommandExists("codex");
+    ensureCommandExists("unifocl");
+
+    const serverName = options.serverName || "unifocl";
+    const codexHome = resolveCodexHome();
+    const configRoot = options.configRoot && options.configRoot.trim() !== ""
+        ? path.resolve(options.configRoot)
+        : path.join(codexHome, "unifocl-config");
+    const skillsTarget = options.skillsDir && options.skillsDir.trim() !== ""
+        ? path.resolve(options.skillsDir)
+        : path.join(codexHome, "skills", "unifocl");
+
+    fs.mkdirSync(configRoot, { recursive: true });
+    fs.mkdirSync(path.dirname(skillsTarget), { recursive: true });
+
+    const packageRoot = path.resolve(__dirname, "..");
+    const bundledSkills = path.join(packageRoot, "skills", "unifocl");
+    if (!fs.existsSync(bundledSkills)) {
+        fail(`bundled skills not found: ${bundledSkills}`);
+    }
+
+    run("codex", ["mcp", "remove", serverName], { stdio: "ignore" });
+    const addResult = run("codex", [
+        "mcp",
+        "add",
+        serverName,
+        "--env",
+        `UNIFOCL_CONFIG_ROOT=${configRoot}`,
+        "--",
+        "unifocl",
+        "--mcp-server"
+    ]);
+
+    if (addResult.status !== 0) {
+        const stderr = (addResult.stderr || "").trim();
+        const stdout = (addResult.stdout || "").trim();
+        fail(`failed to register MCP server in Codex.\n${stderr || stdout}`);
+    }
+
+    copyDirRecursive(bundledSkills, skillsTarget);
+
+    console.log("installed: unifocl codex plugin");
+    console.log(`- mcp server: ${serverName} -> unifocl --mcp-server`);
+    console.log(`- config root: ${configRoot}`);
+    console.log(`- skills path: ${skillsTarget}`);
+    console.log("next: restart Codex session and verify MCP tools are available.");
+}
+
+function doctor() {
+    const codexHome = resolveCodexHome();
+    const skillsPath = path.join(codexHome, "skills", "unifocl");
+    console.log(`codex home: ${codexHome}`);
+    console.log(`skills path: ${skillsPath}`);
+    console.log(`skills installed: ${fs.existsSync(skillsPath) ? "yes" : "no"}`);
+}
+
+function main() {
+    const { positional, options } = parseArgs(process.argv.slice(2));
+    const command = positional[0] || "help";
+
+    if (command === "help" || command === "--help" || command === "-h") {
+        printUsage();
+        return;
+    }
+    if (command === "install") {
+        install(options);
+        return;
+    }
+    if (command === "doctor") {
+        doctor();
+        return;
+    }
+
+    fail(`unknown command: ${command}`);
+}
+
+main();

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@unifocl/codex-plugin",
+  "version": "0.0.0",
+  "description": "Codex plugin bundle for unifocl: installs MCP server config and unifocl workflow skills.",
+  "keywords": [
+    "unifocl",
+    "codex",
+    "mcp",
+    "unity",
+    "plugin"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Kiankinakomochi/unifocl.git",
+    "directory": "src/unifocl.codex-plugin"
+  },
+  "bin": {
+    "unifocl-codex-plugin": "./bin/unifocl-codex-plugin.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "README.md",
+    "package.json"
+  ]
+}

package/skills/unifocl/SKILL.md

@@ -0,0 +1,42 @@
+# unifocl Codex Skill
+
+Use this skill when working with Unity projects through `unifocl` in Codex.
+
+## Purpose
+
+Provide a low-token workflow that mirrors the Claude plugin prompts:
+
+- init
+- status
+- context
+- mutate
+- workflow
+
+## MCP Prerequisite
+
+This skill assumes Codex MCP is configured:
+
+- server name: `unifocl`
+- command: `unifocl --mcp-server`
+
+If not configured, run:
+
+```bash
+unifocl-codex-plugin install
+```
+
+## Workflow Shortcuts
+
+Read these references and follow them strictly:
+
+- `references/init.md`
+- `references/status.md`
+- `references/context.md`
+- `references/mutate.md`
+- `references/workflow.md`
+
+## Guardrails
+
+- Always prefer `GetAgentWorkflowGuide` over stale docs.
+- Always run mutation validation + dry-run before execution.
+- Use stable `--session-seed` values across multi-step flows.

package/skills/unifocl/references/context.md

@@ -0,0 +1,22 @@
+Hydrate full scene context from the active unifocl project for agent reasoning.
+
+Arguments (optional — pass any combination): $ARGUMENTS
+  --project <path>   explicit project path
+  --depth <n>        hierarchy/asset traversal depth
+  --limit <n>        max objects to return
+  --compact          omit null/default fields
+
+Steps:
+
+1. Dump scene hierarchy:
+   `unifocl exec "/dump hierarchy --format json --depth 6 --limit 2000 $ARGUMENTS" --agentic --format json`
+
+2. Dump project asset structure:
+   `unifocl exec "/dump project --format json --depth 4 --limit 1000 $ARGUMENTS" --agentic --format json`
+
+3. For inspector detail on a specific object:
+   `unifocl exec "/inspect <path>" --agentic --format json $ARGUMENTS`
+   then:
+   `unifocl exec "/dump inspector --format json $ARGUMENTS" --agentic --format json`
+
+Use this context before planning any mutation operation.

package/skills/unifocl/references/init.md

@@ -0,0 +1,23 @@
+Initialize the unifocl bridge in a Unity project.
+
+Project path (optional — defaults to current working directory if omitted): $ARGUMENTS
+
+Steps:
+
+1. Run the init command to install the editor-side bridge package:
+   `unifocl exec "/init $ARGUMENTS" --agentic --format json`
+
+2. If `ok` is false, inspect the `message` field and surface the error. Common causes:
+   - Path does not contain `ProjectSettings/ProjectVersion.txt` (not a Unity project root)
+   - Unity Editor is not installed or not detected
+   - Write permission denied on `Packages/` directory
+
+3. After a successful `/init`, confirm the bridge is ready:
+   `unifocl exec "/status" --agentic --format json --project "$ARGUMENTS"`
+   Check that `data.mode` is `bridge` (Unity Editor connected) or `host` (headless/batch).
+
+4. If `protocolMismatch` appears in the response, the editor package is outdated — re-run step 1 to redeploy the updated version.
+
+Next steps after a successful init:
+- Use context workflow to hydrate scene state before any mutations.
+- Use mutate workflow for guided scene mutations with dry-run validation.

package/skills/unifocl/references/mutate.md

@@ -0,0 +1,31 @@
+Guided scene mutation with mandatory dry-run validation first.
+
+Describe what to mutate: $ARGUMENTS
+
+Follow this order exactly.
+
+Step 1 — Plan
+- Determine the `/mutate` op array.
+- Call `GetMutateSchema` via MCP to verify supported ops and fields.
+
+Step 2 — Validate
+- Call `ValidateMutateBatch` via MCP with the planned JSON array.
+- Fix all validation errors.
+
+Step 3 — Dry-run
+- `unifocl exec "/mutate --dry-run <json-array>" --agentic --format json`
+- Review returned diff and paths.
+- Do not proceed if `data.allOk` is false.
+
+Step 4 — Execute
+- `unifocl exec "/mutate <json-array>" --agentic --format json`
+- Confirm `data.allOk: true`.
+
+Step 5 — Verify
+- Re-run context workflow or targeted dumps to confirm state.
+
+Path rules:
+- Root: `/`
+- Top-level: `/ObjectName`
+- Nested: `/Parent/Child`
+- Case-sensitive names.

package/skills/unifocl/references/status.md

@@ -0,0 +1,23 @@
+Check unifocl daemon and project status.
+
+Optional project path or flags: $ARGUMENTS
+
+Steps:
+
+1. Get current status:
+   `unifocl exec "/status" --agentic --format json $ARGUMENTS`
+
+2. Report from the response:
+   - `data.daemon` — running port and uptime
+   - `data.mode` — `bridge` (Unity Editor connected) or `host` (headless/batch)
+   - `data.project` — loaded project path and name
+   - `data.editor` — Unity Editor version in use
+   - `data.session` — active session seed if set
+
+3. If daemon is not running:
+   `unifocl exec "/daemon ps" --agentic --format json`
+
+4. If no project is open, run init workflow first.
+
+5. If environment issues are suspected:
+   `unifocl exec "/doctor" --agentic --format json`

package/skills/unifocl/references/workflow.md

@@ -0,0 +1,27 @@
+Full agentic workflow guide for unifocl Unity operations.
+
+Task or workflow to plan: $ARGUMENTS
+
+Start by calling `GetAgentWorkflowGuide` via the unifocl MCP server.
+
+Standard session pattern:
+
+1. Setup
+   - Ensure `unifocl` is installed.
+   - Install Codex integration: `unifocl-codex-plugin install`
+
+2. Open project
+   - `unifocl exec "/open <project-path>" --agentic --format json`
+   - Wait for `data.ok: true`
+
+3. Hydrate context
+   - Follow context workflow before planning mutations.
+
+4. Discover commands
+   - Use `ListCommands(scope="all")` and `LookupCommand(command="...")`.
+
+5. Mutate safely
+   - Follow mutate workflow (validate + dry-run first).
+
+6. Session efficiency
+   - Reuse stable `--session-seed <id>` across related exec calls.