byob-cli 0.2.9

package/.codex-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "byob-cli",
+  "version": "0.1.0",
+  "description": "Codex connector for BYOB projects, backed by Agent MCP with project context, deployment helpers, and coding tools.",
+  "skills": "./skills/byob_cli/",
+  "mcpServers": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "byob": {
+    "command": "npx",
+    "args": ["-y", "byob-cli", "mcp"],
+    "env_vars": [
+      "BYOB_PROJECT_ID",
+      "BYOB_PROJECT_IDS",
+      "BYOB_MCP_MULTI_PROJECT",
+      "BYOB_AGENT_TOKEN",
+      "BYOB_AIR_URL",
+      "BYOB_PRIM_URL"
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,426 @@
+# BYOB CLI
+
+BYOB CLI is the Codex connector for BYOB. It installs a local `byob` command, configures Codex MCP, and installs the `byob_cli` skill so Codex can safely edit approved BYOB projects.
+
+Under the hood, `byob mcp` starts a stdio MCP server that forwards JSON-RPC to BYOB's hosted Agent MCP endpoint in AIR using a user-approved agent token. The package does not contain BYOB platform credentials.
+
+## Install
+
+Use the package directly from npm. Codex is the primary supported client, and other MCP clients can use the same standard `command` + `args` + `env` model:
+
+```bash
+npx -y byob-cli --help
+```
+
+Install and authorize BYOB for Codex in one command:
+
+```bash
+npx -y byob-cli codex install --client-name "Codex"
+```
+
+The command starts the BYOB OAuth device flow, waits for browser approval, then runs `codex mcp add` with the approved project scope.
+It also installs the `byob_cli` skill into `~/.agents/skills/byob_cli` so Codex can discover it in `/skills` or `$` skill invocation.
+`byob_cli` is the Codex platform contract: it tells Codex how to establish active project context, route tools, handle preview/editor/deployment URLs, protect BYOB-managed files, test changes, and use deployment/billing/domain tools.
+After authentication, the installer also downloads BYOB AIR coding skills into local Codex skill folders with `byob_` prefixes. Those synced skills hold reusable implementation knowledge for SvelteKit, Supabase, BYOB DB, UI quality, SEO, PWA, payments, animations, image generation, and integrations.
+The wizard prints a BYOB banner, auto-opens the approval URL when possible, shows progress steps, and prints the final Codex server/skill install locations. Pass `--no-open` to suppress browser opening, `--no-skill` to skip local skill installation, or `--no-air-skills` to skip downloading AIR coding skills.
+
+Refresh synced coding skills later without rerunning OAuth or changing MCP config:
+
+```bash
+npx -y byob-cli codex sync-skills --project-id <project_id> --token <agent_access_token>
+```
+
+Or install it globally:
+
+```bash
+npm install -g byob-cli
+byob --help
+```
+
+Requirements:
+
+- Node.js 18 or newer.
+- A BYOB agent access token from the OAuth device flow.
+- One or more project ids approved during the OAuth flow.
+
+## URLs And Environments
+
+There are two classes of URLs:
+
+- **Control-plane URLs** are configured by the user or deployment:
+  - `BYOB_AIR_URL`: Agent MCP broker. Production is always `https://air.api.byob.studio`.
+  - `--prim-url` / `BYOB_PRIM_URL`: OAuth/token API. Production is always `https://prim.api.byob.studio`.
+- **Project URLs** are returned by BYOB at runtime:
+  - `preview_url`
+  - `editor_url`
+  - `deployment_url`
+
+Do not hardcode preview or editor hostnames when making tool decisions. Local development often returns VM/host URLs such as `http://10.0.3.1:<port>`. Production project runtime URLs normally use these host patterns:
+
+- Editor: `https://editor.<project_id>.api.byob.studio`
+- Preview: `https://preview.<project_id>.api.byob.studio`
+
+Always prefer the exact URLs returned by `byob_current_project_context`, `byob context`, or `_meta.byob_project`, because custom domains, gateways, or future deployment routing can change the canonical URL.
+
+## Standard MCP Client Config
+
+Most MCP clients accept a `mcpServers` entry with `command`, `args`, and `env`. Add:
+
+```json
+{
+  "mcpServers": {
+    "byob": {
+      "command": "npx",
+      "args": ["-y", "byob-cli", "mcp"],
+      "env": {
+        "BYOB_PROJECT_ID": "<project_id>",
+        "BYOB_AGENT_TOKEN": "<agent_access_token>"
+      }
+    }
+  }
+}
+```
+
+Generate the same shape locally:
+
+```bash
+byob config --project-id <project_id>
+```
+
+`https://air.api.byob.studio` and `https://prim.api.byob.studio` are the package defaults. Set `BYOB_AIR_URL`, `BYOB_PRIM_URL`, `--air-url`, or `--prim-url` only for local development or staging.
+
+Use `npx.cmd` as the command on Windows if your MCP client does not resolve `npx`.
+
+## Codex Setup
+
+For Codex users, prefer installing the BYOB Codex plugin. The plugin bundles:
+
+- `skills/byob_cli/SKILL.md`
+- `.mcp.json`, which starts the `byob` MCP server with `npx -y byob-cli mcp`
+
+Plugin install makes the BYOB skills and MCP server available from one package. The user still needs to provide their project id and agent token, because those are user/project-specific secrets.
+
+For the common MCP setup path, use the installer:
+
+```bash
+npx -y byob-cli codex install --client-name "Codex"
+```
+
+This follows the same wizard pattern used by many MCP providers: the npm package performs auth, writes the Codex MCP config, and installs the BYOB Codex skill into `~/.agents/skills/byob_cli`. It makes BYOB tools available immediately through MCP server instructions and tool discovery, and makes `$byob_cli` available after Codex reloads skills or starts a new session.
+
+Publishing `byob-cli` to npm makes the `byob` binary available to `npx`; it does not automatically create a Codex plugin marketplace. `codex plugin add byob-cli@npm` will fail unless a marketplace named `npm` has been configured and contains a plugin entry.
+
+For local repo testing, add this repository marketplace from the repo root:
+
+```bash
+codex plugin marketplace add /path/to/byob
+codex plugin add byob --marketplace byob-local
+```
+
+For distribution, publish a Codex marketplace JSON from a Git repo or share the plugin through the Codex app. Then users install from that marketplace, while the bundled `.mcp.json` uses npm only to launch the MCP binary.
+
+Example plugin-scoped MCP config:
+
+```toml
+[plugins."<installed_byob_plugin_id>".mcp_servers.byob.env]
+BYOB_PROJECT_ID = "<project_id>"
+BYOB_AGENT_TOKEN = "<agent_access_token>"
+```
+
+For multiple projects:
+
+```toml
+[plugins."<installed_byob_plugin_id>".mcp_servers.byob.env]
+BYOB_PROJECT_IDS = "<project_id_1>,<project_id_2>"
+BYOB_CLI_MULTI_PROJECT = "1"
+BYOB_AGENT_TOKEN = "<agent_access_token>"
+```
+
+Use the plugin id Codex shows after installation, for example `byob` or a marketplace-qualified id.
+
+The bundled MCP server forwards `BYOB_AIR_URL` and `BYOB_PRIM_URL` when set, but production defaults are already `https://air.api.byob.studio` and `https://prim.api.byob.studio`.
+
+### Manual MCP Setup
+
+If the user does not install the plugin, they can still add the stdio MCP server directly:
+
+```bash
+codex mcp add byob \
+  --env BYOB_PROJECT_ID=<project_id> \
+  --env BYOB_AGENT_TOKEN=<agent_access_token> \
+  -- npx -y byob-cli mcp
+```
+
+Equivalent `config.toml`:
+
+```toml
+[mcp_servers.byob]
+command = "npx"
+args = ["-y", "byob-cli", "mcp"]
+
+[mcp_servers.byob.env]
+BYOB_PROJECT_ID = "<project_id>"
+BYOB_AGENT_TOKEN = "<agent_access_token>"
+```
+
+Codex reads MCP server `instructions` returned during initialization. BYOB uses those instructions to tell Codex to establish project context on first BYOB use and after project switches. Context can come from `_meta.byob_project`, resource `byob://project/<project_id>/context`, `byob_current_project_context`, or `byob context`. Codex should show the user the active project name/id and preview URL when the active project was not already clear.
+
+Important: `npx -y byob-cli mcp` starts the MCP server; it does not install Codex skills by itself. With only the MCP server configured, Codex learns about BYOB at runtime from:
+
+- MCP `initialize.instructions`
+- MCP `tools/list`
+- MCP resources and `_meta.byob_project` where the host supports them
+
+To make the `SKILL.md` workflow available to Codex as a skill, run `byob codex install`, install the BYOB Codex plugin, or place the skill folder in a Codex-scanned skills location. The installer copies the skill to `~/.agents/skills/byob_cli`; the MCP server alone does not register that skill name. The main skill installs `CODEX_CORE.md` as a sidecar file and uses synced `byob_*` skills for reusable styling, framework, backend, and integration guidance.
+
+This package includes Codex plugin scaffolding for that:
+
+- `.codex-plugin/plugin.json`
+- `.mcp.json`
+- `skills/byob_cli/SKILL.md`
+
+The local developer skill lives under `local-skills/byob_cli_local/` and is not included in the production plugin manifest.
+
+During local development, the repo marketplace is at `.agents/plugins/marketplace.json`.
+
+### Refreshing Codex Skills
+
+Use this after BYOB updates AIR coding skills or when a Codex machine already has MCP configured:
+
+```bash
+npx -y byob-cli codex sync-skills --project-id <project_id> --token <agent_access_token>
+```
+
+`codex sync-skills` downloads AIR coding-skill resources and rewrites their local skill names with `byob_` prefixes. It does not run OAuth, does not call `codex mcp add`, and does not change the active MCP server config.
+
+## Multiple Projects
+
+BYOB grants can cover more than one approved project. There are two supported install shapes.
+
+### Recommended: One Server Per Project
+
+Use one MCP entry per project when the client supports multiple servers. This is the clearest mode because every server has a stable project target and no tool-call routing ambiguity.
+
+```json
+{
+  "mcpServers": {
+    "byob-web": {
+      "command": "npx",
+      "args": ["-y", "byob-cli", "mcp"],
+      "env": {
+        "BYOB_PROJECT_ID": "<web_project_id>",
+        "BYOB_AGENT_TOKEN": "<agent_access_token>"
+      }
+    },
+    "byob-admin": {
+      "command": "npx",
+      "args": ["-y", "byob-cli", "mcp"],
+      "env": {
+        "BYOB_PROJECT_ID": "<admin_project_id>",
+        "BYOB_AGENT_TOKEN": "<agent_access_token>"
+      }
+    }
+  }
+}
+```
+
+### Single Entry: Multi-Project Routing
+
+Use one MCP entry only when the client cannot manage multiple BYOB servers cleanly. The bridge routes `tools/call` by `arguments.project_id`. Non-tool methods such as `initialize`, `tools/list`, and `ping` use the first configured project.
+
+```json
+{
+  "mcpServers": {
+    "byob": {
+      "command": "npx",
+      "args": ["-y", "byob-cli", "mcp", "--multi-project"],
+      "env": {
+        "BYOB_PROJECT_IDS": "<project_id_1>,<project_id_2>",
+        "BYOB_CLI_MULTI_PROJECT": "1",
+        "BYOB_AGENT_TOKEN": "<agent_access_token>"
+      }
+    }
+  }
+}
+```
+
+For project-specific tools, pass `project_id` in the tool arguments:
+
+```bash
+byob call byob_project_status '{"project_id":"<project_id_2>"}'
+```
+
+Without `project_id`, the first configured project is the default. Use:
+
+```bash
+byob projects
+```
+
+to list projects approved for the grant.
+
+Project switching is intentionally explicit. The bridge does not persist a mutable "current project" on disk; pass `--project-id`, set `BYOB_PROJECT_ID`, or include `project_id` in tool arguments.
+
+## OAuth
+
+Request a device code:
+
+```bash
+byob device-code --client-name "My coding agent"
+```
+
+Open the returned `verification_uri_complete`, approve the project, then exchange:
+
+```bash
+byob token <device_code>
+```
+
+Refresh:
+
+```bash
+byob refresh <refresh_token>
+```
+
+Do not paste access or refresh tokens into chat, logs, or issue reports.
+
+If the needed project is missing from `byob projects`, reconnect with the device flow and approve that project in BYOB.
+
+## CLI Smoke Checks
+
+```bash
+BYOB_PROJECT_ID=<project_id> \
+BYOB_AGENT_TOKEN=<agent_access_token> \
+byob tools
+```
+
+Common aliases:
+
+```bash
+byob status
+byob context
+byob start
+byob deploy
+byob billing
+byob payment-url '{"topup":500}'
+byob env-status
+byob grants
+byob dns
+```
+
+`billing` returns the current credit balance and plan. `payment-url` returns a BYOB pricing/top-up URL that can be shown directly to the user.
+
+Call any tool directly:
+
+```bash
+byob call byob_project_status '{}'
+```
+
+Target another approved project for one command:
+
+```bash
+byob --project-id <other_project_id> status
+byob call byob_project_status '{"project_id":"<other_project_id>"}'
+```
+
+## Project Context Metadata
+
+The MCP server exposes project metadata as both a real tool and a resource.
+
+For Codex reliability, prefer the tool:
+
+```bash
+byob context
+```
+
+The underlying MCP tool is:
+
+```text
+byob_current_project_context
+```
+
+Codex sees MCP tools reliably and receives BYOB server instructions telling it to call this tool when project context is needed.
+
+Read another approved project:
+
+```bash
+byob context '{"project_id":"<other_project_id>"}'
+```
+
+For host UIs that support MCP resources, read the resource:
+
+```bash
+byob context-resource
+byob context-resource '{"project_id":"<other_project_id>"}'
+```
+
+List resources:
+
+```bash
+byob resources
+```
+
+Resource URI shape:
+
+```text
+byob://project/<project_id>/context
+```
+
+The context payload includes:
+
+- project name
+- project id
+- status
+- preview URL
+- editor URL
+- deployment URL
+- publish slug
+- updated/started timestamps
+
+MCP responses also include `_meta.byob_project` where useful. Hosts can use that `_meta` for display without injecting it into model-visible text. Do not put the editor URL into prompts unless the user explicitly needs it.
+
+## Tool Notes
+
+BYOB platform tools are exposed by Agent MCP:
+
+- `byob_current_project_context`
+- `byob_list_projects`
+- `byob_project_status`
+- `byob_start_project`
+- `byob_billing_status`
+- `byob_payment_url`
+- `byob_project_env_status`
+- `byob_list_agent_grants`
+- `byob_revoke_agent_grant`
+- `byob_deploy_project`
+- `byob_deployment_status`
+- `byob_deployment_analytics`
+- `byob_get_custom_domain`
+- `byob_custom_domain_dns_instructions`
+- `byob_set_custom_domain`
+- `byob_delete_custom_domain`
+- `byob_testing_browsers`
+- `byob_browser_session_start`
+- `byob_browser_action`
+- `byob_browser_session_close`
+
+Project coding tools are discovered with `tools/list` and proxied into the selected project's private container MCP.
+After successful mutating coding tools such as `edit_file`, `write_file`, `apply_patch`, package changes, file moves, copies, or deletes, BYOB appends the current preview URL to the tool response when available. Agents should surface that preview URL after code changes.
+
+Codex-driven browser testing is exposed as BYOB platform tools, not as raw container tools. `byob_browser_action` routes browser commands through the connected BYOB browser extension and supports navigation, screenshots, clicks, typing, DOM evaluation, selector waits, viewport resizing, console logs, and network capture. BYOB's internal `delegate_testing` chat/modal flow remains separate and is not advertised through Agent MCP.
+
+Codex does not need BYOB browser tools for every test. For basic smoke checks, it can directly fetch or inspect the `preview_url` and combine that with BYOB preview/browser log tools. Use the BYOB Testing extension only when real browser interaction is needed: screenshots, clicks, typing, viewport checks, DOM evaluation, fresh console logs, or network capture.
+
+If browser-extension testing is needed and no BYOB testing browser is connected, ask the user to install or open the BYOB Testing extension:
+
+```text
+https://chromewebstore.google.com/detail/byob-testing/ncnaebcfklfpcapminohoiekcemmaalj
+```
+
+When a long-running build, image generation, package install, or deploy is already in progress, tell the user they can install the extension during that wait so Codex can test the preview afterward.
+
+## Included Skills
+
+The production plugin includes one Codex skill:
+
+- `skills/byob_cli/SKILL.md`
+
+The local-only developer skill is kept at `local-skills/byob_cli_local/SKILL.md` for BYOB contributors testing a local stack. Do not include it in the production plugin build.