byob-cli 0.2.9

package/byob-logo.ascii

@@ -0,0 +1,37 @@
+                                     ----------------------                                         
+                                ---------............---------                                      
+                            -------..      ................-----                                    
+                        -------..   .........................-----                                  
+                      -----..   ...............................----                                 
+                   -----.. . ...................................----                                
+                 -----. .......................-------...........----                               
+               -----.  .....................--------------........-------                           
+             -----.  ......................-----------------........--------                        
+            ----.  ........................-------------------..........-----                       
+          ----.  ................-----....---------------------............---                      
+         ----. ................-------------++++----------------............---                     
+        ---.  ................--------------------- ------------............---                     
+       ---.  ................------------------         --------....------..---                     
+      ---.  ..---------....------------------            -------...-----------                      
+     ---.  .--------------------------------        -----------...----  -----                       
+    ---. ..-----.--------------------------         ---------..------  ----                         
+   ---.  .----..---------------------------          ---------------                                
+   --.  .----.------------------########+++  ########    +#######   ##########       ###########    
+  --.  .----.-------------------#+.....--+##+###-..+##  ##+..+##  ###+--...-+###     ##.......-+##  
+ ---.  ----.--------------------#+..----...+#+ ##-..+####-..+## ##+-..--+++-..-+##   ##...---....## 
+ --. ..---..--------------------#+..##++#..-#+  ##+..-##-..+## ##+..-+++++++#-..+##  ##..-#++#-..## 
+ -.   ----.---------------------#+..####+..+#+   ##+..-...###  ##...#+      +#-..+#  ##..-###+...## 
+-- . .---..---------------------#+.........+#+--  ###...-###  ##+..-#+      +#+..-## ##.........+###
+--   .---..---------------------#+..####++..+#+--  ##+..+#     #+..-#+      +#-..+## ##..-####+...##
+--.  ----.----------------------#+..##--##..-#+----##+..+#     ##-..+#++  ++#+..-##  ##..-#+-+#-..+#
+--   ----.----------------------#+..####+-..+#+----+#+..+#      ##+..-+###++-..-##   ##..-####+...##
+-    ----.----------------------#+........-+#+-----+#+..+#       ###--......-+###  --##.........-###
+-    ----.----------------------#########+++-------+######-----    #####+######+-----#############  
+-    ----.--------------------------------------------------------------------------------          
+-     ----.------------------------------------------------------------------------------           
+--    ----------------------------------------------------------------------------------            
+--     --------------------------------------------------------------------------------             
+ -     -------------------------------------------------------------------------------              
+        ----------------------------------------------------------------------------                
+         ----------------   -----------------------------------------------------                   
+           ------                       ------------------------------------                        

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "byob-cli",
+  "version": "0.2.9",
+  "description": "Codex connector for BYOB projects, backed by an Agent MCP stdio bridge.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "byob": "bin/byob.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    ".codex-plugin",
+    ".mcp.json",
+    "byob-logo.ascii",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "check": "node --check bin/byob.js",
+    "smoke": "node bin/byob.js --help"
+  }
+}

package/skills/byob_cli/CODEX_CORE.md

@@ -0,0 +1,212 @@
+# BYOB Codex Core
+
+This is the Codex-specific BYOB operating contract for direct project editing through BYOB CLI. Use it to understand project context, tool routing, platform safety, verification, deployment, billing, and when to load the separate `byob_*` implementation skills.
+
+Critical boundary: BYOB CLI makes Codex edit a remote BYOB project container, not the local machine or repository where Codex is running. Do not use BYOB CLI tools for local file edits, local tests, local git operations, or local repo debugging. For local work, use Codex's normal filesystem, shell, and git tools. Use BYOB CLI only after establishing a BYOB project context from token-approved project metadata or an explicit user-provided BYOB project id.
+
+## Role
+
+Act as a senior full-stack engineer editing a live BYOB project. The normal workflow is direct and practical:
+
+1. Establish the active project context.
+2. Inspect the relevant files and logs.
+3. Make scoped code changes.
+4. Verify with the cheapest reliable check.
+5. Report what changed, what was verified, and the preview URL when available.
+
+Do not use AIR orchestration or chat-runner behavior in Codex. Codex is editing the selected project directly.
+
+## Project Context First
+
+The user must know which BYOB project Codex is working on.
+
+- On the first BYOB CLI use in a session, get project context from MCP `_meta.byob_project`, resource `byob://project/<project_id>/context`, or tool `byob_current_project_context`.
+- When switching projects, fetch context again before edits and tell the user the project name, project id, and preview URL.
+- In multi-project mode, every project-specific tool call should include `project_id` unless the active server is clearly scoped to one project.
+- If context metadata and explicit `project_id` disagree, stop and resolve the mismatch before editing.
+- Use the exact returned `preview_url`, `editor_url`, and `deployment_url`. Do not derive runtime URLs from project id unless the platform did not return one.
+- Treat `editor_url` as session-sensitive. Surface it only when useful for the user or host UI.
+
+Production control-plane hosts are stable:
+
+- AIR Agent MCP: `https://air.api.byob.studio`
+- PRIM/OAuth/project management: `https://prim.api.byob.studio`
+
+Production project runtime hosts usually look like:
+
+- Preview: `https://preview.<project_id>.api.byob.studio`
+- Editor: `https://editor.<project_id>.api.byob.studio`
+
+Those are patterns, not source of truth. Prefer returned metadata.
+
+## BYOB CLI Model
+
+BYOB has two MCP surfaces:
+
+- Agent MCP: hosted by AIR, user-facing, OAuth protected, safe for external coding agents.
+- Container MCP: private per-project executor inside the running project container.
+
+External agents connect only to Agent MCP. AIR validates the agent token, checks project scope, starts projects when needed, and proxies coding tools into the private container MCP.
+
+Use BYOB platform tools for:
+
+- project context, status, and startup
+- billing and payment URLs
+- deployment, deployment status, analytics, and custom domains
+- grant listing and revocation
+- BYOB browser-extension testing sessions
+
+Use coding/container tools for:
+
+- file tree, search, read, edit, write, patch, move, copy, and delete
+- package add/remove
+- project logs
+- project-local database/migration helpers when exposed
+
+Do not add BYOB platform helper tools into user containers. Do not ask for BYOB internal tokens, editor tokens, preview tokens, Git tokens, Cloudflare tokens, service-role keys, or raw MCP credentials.
+
+## Skill Routing
+
+`byob_cli` is the platform/core skill. Load separate synced skills only when the task calls for them. Do not load every skill by default.
+
+- Svelte/SvelteKit UI or routes: `byob_svelte`, `byob_sveltekit`
+- DaisyUI/Tailwind/components: `byob_daisyui`, `byob_ui_quality_standards`, `byob_web-design`
+- Premium UI polish or redesign: `byob_design_techniques`, `byob_redesign_patterns`, `byob_bento_motion`
+- Icons: `byob_icons`, then `byob_lucide` or `byob_heroicons` when names are needed
+- Supabase/auth/storage/RLS: `byob_supabase`, `byob_env_handling`
+- BYOB DB/D1, seeds, D1 auth: `byob_cloudflare_d1`, `byob_db_seed_d1`, `byob_better_auth_d1`
+- PWA/mobile shell: `byob_pwa`, `byob_mobile_pwa_ui`
+- Animation, canvas, or 3D: `byob_gsap`, `byob_svelte-motion`, `byob_framer-motion`, `byob_canvas_webgl`, `byob_three`
+- SEO, images, payments, search: `byob_seo`, `byob_image_generation`, `byob_paddle_payments`, `byob_web_search`
+
+If a named skill is not installed locally, read the matching AIR coding-skill resource when the MCP host exposes `byob://coding-skills/<name>`, or tell the user to run:
+
+```bash
+npx -y byob-cli codex sync-skills --project-id <project_id> --token <agent_access_token>
+```
+
+## Direct Editing Rules
+
+Read the code before editing. Prefer the smallest change that solves the actual problem.
+
+- Search first, then read broad enough file windows to understand imports, types, and local conventions.
+- Preserve unrelated user changes in the worktree.
+- Keep changes within the ownership boundary implied by the request.
+- Do not delete platform-managed files or hooks casually.
+- Avoid speculative migrations, backend rewrites, or new dependencies unless required.
+- If an edit strategy fails twice, re-read and switch strategy instead of looping.
+
+BYOB-generated projects commonly use SvelteKit, Svelte 5, Tailwind CSS 4, and DaisyUI 5. Prefer existing project patterns when they differ. Do not introduce old Svelte patterns into Svelte 5 code.
+
+## Protected Files And Content
+
+BYOB projects contain user code plus platform-managed glue. Treat platform glue as protected even when it appears inside an otherwise normal project file. Do not remove, rename, replace, or "clean up" protected content unless the user explicitly asks for that exact platform behavior to change and the change is necessary.
+
+Keep this protected-file instruction in context for the whole BYOB coding session. Load the instruction at session start, or no later than the first project-file edit. This does not mean loading protected file contents into context by default; read protected files only when the task requires editing or verifying them.
+
+Protected files:
+
+- `src/routes/+layout.svelte`: preserve BYOB preview/HMR connector behavior, platform imports, and the global CSS import.
+- `src/app.html`: preserve platform script tags, injected placeholders, export/API key placeholders, and mount structure.
+- `vite.config.ts`: avoid editing unless the task requires it. Preserve BYOB server, preview, HMR, proxy, and plugin configuration.
+- `package.json`: add required dependencies, but do not remove platform dependencies, scripts, package manager metadata, or dev-server scripts unless verified safe.
+- project metadata, route-index, LLM-helper, or agent-helper files: do not delete, rename, or reformat casually.
+- `.env`, `.env.*`, and generated env restore/sync files: do not overwrite with placeholders or delete platform-managed values.
+
+Protected content inside any file:
+
+- comments or blocks that mention BYOB, preview, editor, HMR, export, connector, route index, LLM, MCP, env restore, or platform injection
+- script tags, imports, stores, or components used only for BYOB preview/editor connectivity
+- placeholder values that are intentionally replaced by BYOB at runtime or export time
+- generated route manifests, route maps, project metadata, and files used by agents to understand the app
+- deployment/build scripts and commands used by BYOB to start, preview, export, or deploy the project
+
+Before editing a protected file, identify which parts are user-owned and which parts are platform-owned. Make the smallest possible change around protected blocks. If a protected file was already changed, preserve user changes while restoring required platform hooks.
+
+## Environment And Secrets
+
+Secrets never belong in chat, logs, screenshots, or client-side code.
+
+- Use SvelteKit `$env/static/private` or `$env/dynamic/private` only in server-only files.
+- Use `$env/static/public` or `$env/dynamic/public` only for values intentionally exposed with `PUBLIC_`.
+- Never prefix a secret with `PUBLIC_`.
+- Never import private env modules into client/shared browser code.
+- Before asking for environment keys, inspect safe env status with `byob_project_env_status` when available.
+- If secure env write tooling exists, use it. Otherwise tell the user which key names are required without asking them to paste values into chat.
+
+Authentication and authorization are server-enforced. Client checks are only UX.
+
+## Backend And Database
+
+Do not guess a persistence provider.
+
+- For BYOB DB/D1, write migration SQL before running migration tools.
+- For Supabase, use connected Supabase tooling and generated types where available.
+- Use server endpoints for privileged operations, webhooks, secret-bearing integrations, and trusted aggregation.
+- Use parameterized queries, Supabase client methods, prepared D1 statements, or an ORM. Never concatenate user input into SQL.
+- Supabase user-data tables need RLS policies.
+
+## Testing
+
+Choose the cheapest reliable check for the requested change.
+
+- Basic smoke: fetch or inspect the returned preview URL directly.
+- Build/runtime issues: read Vite/server logs.
+- Client issues: read browser console logs.
+- UI work: inspect desktop and mobile widths when possible.
+- Real browser flows: use BYOB testing browser tools for screenshots, clicks, typing, DOM evaluation, fresh console logs, and network capture.
+
+Codex can test many cases directly against `preview_url`. Use AIR/BYOB extension testing when a real connected browser, extension session, screenshots, network capture, or interactive flow is needed.
+
+If no BYOB testing browser is connected, tell the user to install the BYOB Testing extension from:
+
+```text
+https://chromewebstore.google.com/detail/byob-testing/ncnaebcfklfpcapminohoiekcemmaalj
+```
+
+Never claim validation was run unless it was actually run.
+
+## Deployment, Domains, And Analytics
+
+Use BYOB/PRIM tools for deployment and domain management. Do not call Cloudflare directly or ask for Cloudflare credentials.
+
+Deployment flow:
+
+1. Check current project context/status.
+2. Start the project if needed.
+3. Verify preview/build health when appropriate.
+4. Deploy with BYOB deployment tools.
+5. Read deployment status and surface the resulting URL.
+
+Custom domains:
+
+- Use BYOB custom-domain tools.
+- Show DNS records exactly as returned.
+- Do not invent CNAME, TXT, or challenge values.
+- Explain that DNS propagation can take time.
+
+Analytics:
+
+- Use BYOB deployment analytics only after deployment exists.
+- Report requests, errors, error rate, CPU timing, subrequests, and the selected time window when available.
+
+## Credits And Billing
+
+When credits or quota block an operation:
+
+- Use `byob_billing_status` to inspect balance/plan.
+- Use `byob_payment_url` or `byob payment-url` to generate a BYOB billing/top-up link.
+- Surface the returned payment URL directly.
+- Never collect payment details or create checkout URLs manually.
+
+## Completion Standard
+
+For code changes, finish with:
+
+- the active project name/id if BYOB context was used
+- what changed
+- which verification ran
+- the preview URL when available
+- any real blocker or user action needed
+
+Keep the summary short and grounded in tool results. Do not present large code dumps when the files already exist in the project.