@dboio/cli 0.4.1

package/src/plugins/claudecommands/dbo.md

@@ -0,0 +1,248 @@
+---
+description: Execute DBO.io CLI commands (pull, push, add, clone, output, input, content, deploy, etc.)
+allowed-tools: [Bash, Read, Write, Grep, Glob]
+---
+
+# DBO CLI Command
+
+The dbo CLI interacts with DBO.io — a database-driven application framework.
+
+**STEP 1: Check if `$ARGUMENTS` is empty or blank.**
+
+If `$ARGUMENTS` is empty — meaning the user typed just `/dbo` with nothing after it — then you MUST NOT run any bash command. Do NOT run `dbo`, `dbo --help`, or anything else. Instead, respond ONLY with this text message:
+
+---
+
+Hi there! I can help you with running dbo commands. What would you like to do?
+
+Here are the available commands:
+
+| Command   | Description                                      |
+|-----------|--------------------------------------------------|
+| init      | Initialize .dbo/ configuration                   |
+| login     | Authenticate with a DBO.io instance              |
+| logout    | Clear session                                    |
+| status    | Show config, domain, and session info            |
+| input     | Submit CRUD operations (add/edit/delete records)  |
+| output    | Query data from outputs or entities              |
+| content   | Get or deploy content                            |
+| media     | Get media files                                  |
+| upload    | Upload a file                                    |
+| message   | Send messages (email, SMS, chatbot)              |
+| pull      | Pull records to local files                      |
+| push      | Push local files back to DBO.io                  |
+| add       | Add a new file to DBO.io                         |
+| clone     | Clone an app to local project structure           |
+| deploy    | Deploy via manifest                              |
+| cache     | Manage cache                                     |
+| install   | Install components                               |
+| update    | Update CLI or plugins                            |
+
+Just tell me what you'd like to do and I'll help you build the right command!
+
+---
+
+Then STOP. Wait for the user to respond. Guide them step by step — asking about entities, UIDs, file paths, flags, etc. to construct the correct `dbo` command. Run `dbo status` proactively to check if the CLI is initialized and authenticated before suggesting data commands.
+
+**STEP 2: If `$ARGUMENTS` is NOT empty, run the command:**
+
+```bash
+dbo $ARGUMENTS
+```
+
+## Command Reference
+
+Available subcommands:
+- `init` — Initialize .dbo/ configuration for the current directory
+- `login` — Authenticate with a DBO.io instance
+- `logout` — Clear session
+- `status` — Show config, domain, and session info
+- `input -d '<expr>'` — CRUD operations (add/edit/delete records)
+- `output -e <entity>` — Query data from entities
+- `output <uid>` — Query custom outputs
+- `content <uid>` — Get content, `content deploy <uid> <file>` to deploy
+- `pull [uid]` — Pull records to local files (default: content entity)
+- `pull -e <entity> [uid]` — Pull from any entity
+- `push <path>` — Push local files back to DBO using metadata
+- `add <path>` — Add a new file to DBO (creates record on server)
+- `media <uid>` — Get media files
+- `upload <file>` — Upload binary files
+- `message <uid>` — Send messages (email, SMS, chatbot)
+- `cache list|refresh` — Manage cache
+- `clone [source]` — Clone an app to local project (from file or server)
+- `clone --app <name>` — Clone by app short name from server
+- `deploy [name]` — Deploy via dbo.deploy.json manifest
+- `install` — Install components (claudecode, claudecommands)
+- `update` — Update CLI, plugins, or Claude commands
+
+## Smart Command Building
+
+When helping the user build a command interactively:
+
+1. **Check readiness first**: Run `dbo status` to see if initialized and authenticated. If not, guide them through `dbo init` and `dbo login` first.
+2. **Understand intent**: Ask what they want to do (query data, deploy a file, add a record, etc.)
+3. **Gather parameters**: Ask for the specific values needed (entity name, UID, file path, filters, etc.)
+4. **Build the command**: Construct the full `dbo` command with proper flags and syntax
+5. **Execute**: Run it and explain the results
+
+### Common workflows to suggest:
+
+- **"I want to query data"** → Guide toward `dbo output -e <entity>` with filters
+- **"I want to deploy/update a file"** → Check if `.metadata.json` exists → `dbo push` or `dbo content deploy`
+- **"I want to add a new file"** → `dbo add <path>` (will create metadata interactively)
+- **"I want to pull files from the server"** → `dbo pull` or `dbo pull -e <entity>`
+- **"I want to see what's on the server"** → `dbo output -e <entity> --format json`
+- **"I need to set up this project"** → `dbo init` → `dbo login` → `dbo status`
+- **"I want to clone an app"** → `dbo clone --app <name>` or `dbo clone <local.json>`
+- **"I want to set up and clone"** → `dbo init --domain <host> --app <name> --clone`
+
+## Add Command Details
+
+`dbo add <path>` registers a new local file with the DBO server by creating an insert record.
+
+```bash
+# Add a single file (interactive metadata wizard if no .metadata.json exists)
+dbo add assets/css/colors.css
+
+# Add with auto-accept and ticket
+dbo add assets/css/colors.css -y --ticket abc123
+
+# Scan current directory for all un-added files
+dbo add .
+
+# Scan a specific directory
+dbo add assets/
+```
+
+Flags: `-C/--confirm <true|false>`, `--ticket <id>`, `-y/--yes`, `--json`, `--jq <expr>`, `-v/--verbose`, `--domain <host>`
+
+### How add works
+
+1. Checks for a companion `<basename>.metadata.json` next to the file
+2. If metadata exists with `_CreatedOn` → already on server, skips (use `push` instead)
+3. If metadata exists without `_CreatedOn` → uses it to insert the record
+4. If no metadata → interactive wizard prompts for: entity, content column, AppID, BinID, SiteID, Path
+5. Creates `.metadata.json`, submits insert to `/api/input/submit`
+6. Writes returned UID back to metadata file
+7. Suggests running `dbo pull -e <entity> <uid>` to populate all server columns
+
+### Non-interactive add (for scripting)
+
+To add without prompts, create the `.metadata.json` first, then run `dbo add <file> -y`:
+
+```json
+{
+  "Name": "colors",
+  "Path": "assets/css/colors.css",
+  "Content": "@colors.css",
+  "_entity": "content",
+  "_contentColumns": ["Content"]
+}
+```
+
+Optional fields like `AppID`, `BinID`, `SiteID` are only included if the user provides values — they have no defaults and are omitted when left blank.
+
+The `@colors.css` value means "read content from colors.css in the same directory".
+
+### Directory scan (`dbo add .`)
+
+Finds files that have no `.metadata.json` or whose metadata lacks `_CreatedOn`. Skips `.dbo/`, `.git/`, `node_modules/`, dotfiles, and `.metadata.json` files. When adding multiple files, defaults from the first file are reused.
+
+## Push Command Details
+
+`dbo push <path>` pushes local file changes back to existing DBO records using their `.metadata.json`.
+
+```bash
+dbo push assets/css/colors.css          # single file
+dbo push assets/                         # all records in directory
+dbo push assets/ --content-only          # only file content, skip metadata
+dbo push assets/ --meta-only             # only metadata columns, skip files
+dbo push assets/ -y --ticket abc123      # auto-accept + ticket
+```
+
+Flags: `-C/--confirm`, `--ticket <id>`, `--meta-only`, `--content-only`, `-y/--yes`, `--json`, `--jq`, `-v/--verbose`, `--domain`
+
+## Column Filtering (add & push)
+
+These columns are **never submitted** in add or push payloads:
+- `_CreatedOn`, `_LastUpdated` — server-managed timestamps
+- `_LastUpdatedUserID`, `_LastUpdatedTicketID` — session-provided values
+- `UID` — server-assigned on insert; used as identifier on push (not as column value)
+- `_id`, `_entity`, `_contentColumns`, `_mediaFile` — internal/metadata fields
+
+## Pull → Edit → Push/Add Workflow
+
+```bash
+# Pull existing records
+dbo pull -e content --filter 'AppID=10100'
+
+# Edit files locally, then push changes back
+dbo push assets/css/colors.css
+
+# Or add a brand new file
+dbo add assets/css/newstyle.css
+```
+
+## Clone Command Details
+
+`dbo clone` scaffolds a local project from a DBO.io app export JSON, creating directories, files, metadata, and config.
+
+```bash
+# Clone from a local JSON export file
+dbo clone /path/to/app_export.json
+
+# Clone from server by app short name (requires login)
+dbo clone --app myapp
+
+# Clone using AppShortName already in config
+dbo clone
+
+# Init + clone in one step
+dbo init --domain beta-dev.dbo.io --app myapp --clone
+```
+
+Flags: `--app <name>`, `--domain <host>`, `-y/--yes`, `-v/--verbose`
+
+### What clone does
+
+1. Loads app JSON (local file, server API, or prompt)
+2. Updates `.dbo/config.json` with `AppID`, `AppUID`, `AppName`, `AppShortName`
+3. Updates `package.json` with `name`, `productName`, `description`, `homepage`, and `deploy` script
+4. Creates directory structure from `children.bin` hierarchy → saves `.dbo/structure.json`
+5. Writes content files (decodes base64) with `*.metadata.json` into bin directories
+6. Downloads media files from server via `/api/media/{uid}` with `*.metadata.json`
+7. Processes other entities with BinID into corresponding directories
+8. Saves `app.json` to project root with `@path/to/*.metadata.json` references
+
+### Placement preferences
+
+When a record has both `Path`/`FullPath` and `BinID`, clone prompts the user to choose placement. Preferences are saved to `.dbo/config.json` and reused on future clones:
+
+- `ContentPlacement`: `bin` | `path` | `ask` — for content and other entities
+- `MediaPlacement`: `bin` | `fullpath` | `ask` — for media files
+
+Pre-set these in config.json to skip prompts. `.dbo/config.json` and `.dbo/structure.json` are shared via git; `.dbo/credentials.json` and `.dbo/cookies.txt` are gitignored (per-user).
+
+### AppID awareness (add & input)
+
+After cloning, the config has an `AppID`. When running `dbo add` or `dbo input` without an AppID in the data, the CLI prompts:
+1. Yes, use AppID from config
+2. No
+3. Enter custom AppID
+
+### Init flags for clone
+
+`dbo init` now supports `--app <shortName>` and `--clone` flags to combine initialization with app cloning.
+
+## Error Handling
+
+- If the command fails with a session/authentication error, suggest: `dbo login`
+- If it fails with "No domain configured", suggest: `dbo init`
+- If a command is not found, suggest: `dbo --help`
+
+## Output
+
+When showing results:
+- Format JSON output readably
+- For pull/push/add operations, list the files created or modified
+- For query operations, summarize the row count and key fields