@dboio/cli 0.4.2 → 0.5.1

package/README.md

@@ -46,6 +46,9 @@ The dbo CLI can be used as a `/dbo` slash command inside Claude Code sessions.
 # Install the /dbo command into your project's .claude/commands/
 dbo install claudecommands
 
+# Install globally to ~/.claude/commands/ (shared across projects)
+dbo install claudecommands --global
+
 # Or install Claude Code CLI + commands together
 dbo install claudecode
 ```
@@ -57,41 +60,34 @@ Once installed, use `/dbo` in Claude Code:
 /dbo push assets/css/
 ```
 
-The command source lives in `tools/dbo-cli/src/plugins/claudecommands/`. Installed copies in `.claude/commands/` are gitignored and managed by `dbo install` / `dbo update`.
+The command source lives in `tools/dbo-cli/src/plugins/claudecommands/`. Installed copies in `.claude/commands/` are gitignored and managed by `dbo install`. Each plugin's installation scope (project or global) is stored per-plugin in `.dbo/config.local.json`.
 
 ---
 
-## Updating
+## Upgrading
+
+The `dbo install` command handles both fresh installs and upgrades. If a component is already installed, it will prompt you to upgrade to the latest version.
 
 ```bash
-# Update everything (CLI + Claude commands)
-dbo update
+# Upgrade CLI to latest version
+dbo install dbo@latest
+
+# Install/upgrade to a specific version
+dbo install dbo@0.4.1
 
-# Update only the CLI
-dbo update cli
+# Upgrade from local source
+dbo install /path/to/local/cli/src
 
-# Update only Claude Code commands
-dbo update claudecommands
+# Upgrade Claude Code commands (prompts if already installed)
+dbo install plugins
 
-# Update a specific Claude command
-dbo update --claudecommand dbo
+# Upgrade a specific Claude command
+dbo install --claudecommand dbo
 
 # Check your version
 dbo --version
 ```
 
-For manual updates:
-
-```bash
-# From git repo
-cd tools/dbo-cli && git pull && npm install
-
-# From npm
-npm update -g @dboio/cli
-```
-
-If you used `npm link`, the link updates automatically — no need to re-link.
-
 ---
 
 ## Quick Start
@@ -129,11 +125,12 @@ All configuration is **directory-scoped**. Each project folder maintains its own
 | File | Purpose | Git |
 |------|---------|-----|
 | `config.json` | Domain, app metadata, placement preferences | Committable (shared) |
+| `config.local.json` | Per-user settings: plugin scopes, future user prefs | Gitignored (per-user) |
 | `credentials.json` | Username, user ID, UID, name, email (no password) | Gitignored (per-user) |
 | `cookies.txt` | Session cookie (Netscape format) | Gitignored (per-user) |
 | `structure.json` | Bin directory mapping (created by `dbo clone`) | Committable (shared) |
 
-`dbo init` automatically adds `.dbo/credentials.json` and `.dbo/cookies.txt` to `.gitignore` (creates the file if it doesn't exist).
+`dbo init` automatically adds `.dbo/credentials.json`, `.dbo/cookies.txt`, and `.dbo/config.local.json` to `.gitignore` (creates the file if it doesn't exist).
 
 #### config.json reference
 
@@ -158,6 +155,7 @@ All configuration is **directory-scoped**. Each project folder maintains its own
 | `AppShortName` | string | App short name (used for `dbo clone --app`) |
 | `ContentPlacement` | `bin` \| `path` \| `ask` | Where to place content files during clone |
 | `MediaPlacement` | `bin` \| `fullpath` \| `ask` | Where to place media files during clone |
+| `<Entity>FilenameCol` | column name | Filename column for entity-dir records (e.g., `ExtensionFilenameCol`) |
 
 **Placement values:**
 - `bin` — Place files in the BinID-mapped directory (from `structure.json`)
@@ -187,11 +185,12 @@ Environment variables override file-based configuration:
 Initialize DBO CLI configuration for the current directory.
 
 ```bash
-dbo init                                          # interactive prompts
-dbo init --domain my-domain.com           # non-interactive
-dbo init --domain my-domain.com --username me@co.io  # with credentials
-dbo init --force                                  # overwrite existing config
-dbo init --domain my-domain.com --app myapp --clone  # init + clone an app
+dbo init                                              # interactive prompts
+dbo init --domain my-domain.com                       # non-interactive
+dbo init --domain my-domain.com --username me@co.io   # with credentials
+dbo init --force                                      # overwrite existing config
+dbo init --domain my-domain.com --app myapp --clone   # init + clone an app
+dbo init --domain my-domain.com -y                    # skip all prompts
 ```
 
 | Flag | Description |
@@ -201,6 +200,10 @@ dbo init --domain my-domain.com --app myapp --clone  # init + clone an app
 | `--force` | Overwrite existing configuration |
 | `--app <shortName>` | App short name (triggers clone after init) |
 | `--clone` | Clone the app after initialization |
+| `-g, --global` | Install Claude commands globally (`~/.claude/commands/`) |
+| `--local` | Install Claude commands to project (`.claude/commands/`) |
+| `-y, --yes` | Skip all interactive prompts (legacy migration, Claude Code setup) |
+| `--non-interactive` | Alias for `--yes` |
 
 ---
 
@@ -239,8 +242,13 @@ dbo init --domain my-domain.com --app myapp --clone
 5. **Saves `.dbo/structure.json`** — maps BinIDs to directory paths for file placement
 6. **Writes content files** — decodes base64 content, creates `*.metadata.json` + content files in the correct bin directory
 7. **Downloads media files** — fetches binary files (images, CSS, fonts) from the server via `/api/media/{uid}` and saves with metadata
-8. **Processes other entities** — entities with a `BinID` are placed in the corresponding directory
-9. **Saves `app.json`** — clone of the original JSON with processed entries replaced by `@path/to/*.metadata.json` references
+8. **Processes entity-dir records** — entities matching project directories (`extension`, `app_version`, `data_source`, `site`, `group`, `integration`, `automation`) are saved as `.metadata.json` files in their corresponding directory (e.g., `Extensions/`, `Data Sources/`)
+9. **Processes other entities** — remaining entities with a `BinID` are placed in the corresponding bin directory
+10. **Saves `app.json`** — clone of the original JSON with processed entries replaced by `@path/to/*.metadata.json` references
+
+#### Change detection on re-clone
+
+When cloning an app that was already cloned locally, the CLI detects existing files and compares modification times against the server's `_LastUpdated`. You'll be prompted to overwrite, compare differences, or skip — same as `dbo pull`. Use `-y` to auto-accept all changes.
 
 #### Path resolution
 
@@ -251,6 +259,26 @@ Where do you want me to place filename.ext?
   2. Into the BinID of 12345 (mapped BinName → bin/directory)
 ```
 
+#### Entity directory processing
+
+Entity types that correspond to project directories (`extension`, `app_version`, `data_source`, `site`, `group`, `integration`, `automation`) are processed into their named directories without requiring a `BinID`:
+
+| Entity Key | Directory |
+|------------|-----------|
+| `extension` | `Extensions/` |
+| `app_version` | `App Versions/` |
+| `data_source` | `Data Sources/` |
+| `site` | `Sites/` |
+| `group` | `Groups/` |
+| `integration` | `Integrations/` |
+| `automation` | `Automations/` |
+
+For each entity type, the CLI prompts to choose which column becomes the filename (defaults to `Name`, fallback `UID`). The choice is saved per entity type in `config.json` (e.g., `ExtensionFilenameCol`).
+
+If any columns contain base64-encoded content, the CLI prompts to extract them as companion files. Extracted columns produce files named `<name>.<Column>.<ext>` alongside the metadata, with `@reference` entries in the metadata and a `_contentColumns` array.
+
+Use `-y` to skip prompts (uses `Name` column, no content extraction).
+
 #### Output structure
 
 ```
@@ -261,7 +289,7 @@ project/
   .gitignore                 # credentials.json + cookies.txt added
   package.json               # Updated with app info + deploy script
   app.json                   # Clone of original with @references
-  bins/                      # ← root for all bin-placed files
+  Bins/                      # ← root for all bin-placed files
     app/                     # ← directory from children.bin
       thomas-scratch.md
       thomas-scratch.metadata.json
@@ -269,6 +297,13 @@ project/
       CurrentTicketID.metadata.json
     ticket_test/             # ← another bin directory
       ...
+  Extensions/                # ← entity-dir records
+    MyExtension.metadata.json
+    MyExtension.CustomCSS.css    # ← extracted content column
+  Data Sources/
+    MySQL-Primary.metadata.json
+  Sites/
+    MainSite.metadata.json
   media/operator/app/...     # ← FullPath placement (when MediaPlacement=fullpath)
 ```
 
@@ -329,10 +364,15 @@ Output:
   Directory: /Users/me/projects/operator
   Session: Active (expires: 2026-03-15T10:30:00.000Z)
   Cookies: /Users/me/projects/operator/.dbo/cookies.txt
+
+  Claude Code Plugins:
+  dbo: ✓ global (~/.claude/commands/dbo.md)
 ```
 
 User ID and UID are populated by `dbo login`. If they show "(not set)", run `dbo login` to fetch them.
 
+Plugin scopes (project or global) are displayed when plugins have been installed. Scopes are stored in `.dbo/config.local.json`.
+
 ---
 
 ### `dbo input`
@@ -380,7 +420,7 @@ dbo input -d 'RowUID:abc;column:content.Content@file.css' -v
 #### Input expression syntax
 
 ```
-RowID:identifier;column:entity.ColumnName=value       # direct value
+RowID:identifier;column:entity.ColumnName=value        # direct value
 RowUID:identifier;column:entity.ColumnName@filepath    # value from file
 RowID:delIdentifier;entity:entityName=true             # delete
 ```
@@ -539,6 +579,17 @@ js/
   app.metadata.json
 ```
 
+#### Smart change detection
+
+When pulling records that already exist locally, the CLI compares your local file modification times against the server's `_LastUpdated` timestamp. If the server has newer data, you'll be prompted:
+
+1. **Overwrite** — replace local with server version
+2. **Compare** — show a line-by-line diff and selectively merge
+3. **Skip** — keep local unchanged
+4. **Overwrite all** / **Skip all** — bulk action for remaining files
+
+After writing, file modification times are synced to the server's `_LastUpdated` to establish a sync point for future comparisons. Use `dbo diff` to compare without pulling.
+
 ---
 
 ### `dbo media`
@@ -679,6 +730,55 @@ dbo instance export --confirm false
 
 ---
 
+### `dbo diff`
+
+Compare local files against their server versions and selectively merge changes. This is a one-directional comparison: only server → local changes can be accepted. To push local changes back, use `dbo push`.
+
+```bash
+# Compare all records in the current directory
+dbo diff
+
+# Compare a specific file
+dbo diff assets/css/colors.css
+
+# Compare all records in a directory
+dbo diff assets/
+
+# Display diffs without prompting
+dbo diff --no-interactive
+
+# Accept all server changes without prompting
+dbo diff -y
+```
+
+| Flag | Description |
+|------|-------------|
+| `[path]` | File, directory, or `.` (default: current directory) |
+| `--no-interactive` | Show diffs without prompting to accept |
+| `-y, --yes` | Accept all server changes automatically |
+| `-v, --verbose` | Show HTTP request details |
+| `--domain <host>` | Override domain |
+
+#### Interactive mode
+
+For each file with differences, you can:
+1. **Accept all changes** — overwrite local with server version
+2. **Cherry-pick fields** — accept/skip individual field changes
+3. **Skip** — keep local files unchanged
+4. **Accept all remaining** — auto-accept for all remaining files
+5. **Skip all remaining** — skip all remaining files
+
+#### Diff output
+
+Shows a unified diff format with color coding:
+- Red lines (`-`) — content only in your local file
+- Green lines (`+`) — content only on the server
+- Cyan headers — hunk markers showing line positions
+
+After accepting changes, file modification times are synced to the server's `_LastUpdated` timestamp to establish a new sync point.
+
+---
+
 ### `dbo push`
 
 Push local files back to DBO.io using metadata from a previous pull. This is the counterpart to `dbo content pull` and `dbo output --save`.
@@ -771,6 +871,85 @@ The `@colors.css` reference tells push to read the content from that file. All o
 
 ---
 
+### `dbo rm`
+
+Remove a file or directory locally and stage server deletions for the next `dbo push`. Similar to `git rm`.
+
+#### Single file
+
+```bash
+# Remove a content file (finds companion .metadata.json automatically)
+dbo rm Bins/app/some-file.txt
+
+# Remove by metadata file directly
+dbo rm Bins/app/some-file.metadata.json
+
+# Skip confirmation prompt
+dbo rm -f Bins/app/some-file.txt
+
+# Stage server deletion without deleting local files
+dbo rm --keep-local Bins/app/some-file.txt
+```
+
+#### Directory
+
+```bash
+# Remove a directory and all its contents (prompts for approach)
+dbo rm Bins/app/ui/
+
+# Remove directory without prompts
+dbo rm -f Bins/app/ui/
+
+# Stage deletions without removing local files/directories
+dbo rm --keep-local Bins/app/ui/
+```
+
+When removing a directory, the CLI:
+1. Looks up the BinID from `.dbo/structure.json`
+2. Recursively collects all sub-directories (processed leaves-first)
+3. Prompts: "Remove all files and directories", "Prompt for each file", or "Cancel"
+4. Stages each file's deletion, then each bin's deletion (`entity:bin`)
+5. Removes the local directory (unless `--keep-local`)
+
+| Flag | Description |
+|------|-------------|
+| `<path>` | File, `.metadata.json`, or directory to remove |
+| `-f, --force` | Skip all confirmation prompts |
+| `--keep-local` | Only stage server deletions, keep local files/directories |
+
+#### What rm does (single file)
+
+1. **Resolves metadata** — if given a content file, finds the companion `.metadata.json`
+2. **Reads row ID** — uses `_id` (shorthand) or derives from entity (e.g., `ContentID`, `MediaID`)
+3. **Prompts for confirmation** — "Do you really want to remove this file and all of its nodes?"
+4. **Stages deletion** — adds a delete entry to `.dbo/synchronize.json`
+5. **Updates app.json** — removes the `@path/to/file.metadata.json` reference from children arrays
+6. **Deletes local files** — removes the metadata file and all referenced content/media files (unless `--keep-local`)
+
+#### synchronize.json
+
+Pending deletions are stored in `.dbo/synchronize.json`:
+
+```json
+{
+  "delete": [
+    {
+      "UID": "a2dxvg23rk6xsmnum7pdxa",
+      "RowID": 16012,
+      "entity": "content",
+      "name": "nima-test-test",
+      "expression": "RowID:del16012;entity:content=true"
+    }
+  ],
+  "edit": [],
+  "add": []
+}
+```
+
+The next `dbo push` processes all pending deletions before pushing file changes. Successful deletions are removed from synchronize.json; failures remain staged for retry.
+
+---
+
 ### `dbo add`
 
 Add a new file to DBO.io by creating a server record. Similar to `git add`, this registers a local file with the server.
@@ -895,61 +1074,58 @@ If no stored user info is available, it prompts for direct input. The CLI automa
 
 ### `dbo install`
 
-Install dbo-cli components including Claude Code integration.
+Install or upgrade dbo-cli components including the CLI itself, plugins, and Claude Code integration.
 
 ```bash
 # Interactive — choose what to install
 dbo install
 
-# Install Claude Code commands into .claude/commands/
-dbo install claudecommands
-
-# Install Claude Code CLI (if not present) + commands
-dbo install claudecode
-
-# Install a specific command plugin
-dbo install --claudecommand dbo
-```
-
-| Flag | Description |
-|------|-------------|
-| `[target]` | What to install: `claudecode`, `claudecommands` |
-| `--claudecommand <name>` | Install a specific command by name |
-
-When installing Claude commands:
-- Creates `.claude/commands/` if it doesn't exist (prompts first)
-- Prompts before overwriting existing commands
-- Adds installed files to `.gitignore` (source of truth is `src/plugins/claudecommands/`)
+# Install/upgrade CLI from npm (latest)
+dbo install dbo
+dbo install dbo@latest
 
----
+# Install a specific CLI version
+dbo install dbo@0.4.1
 
-### `dbo update`
+# Install CLI from local source directory
+dbo install /path/to/local/cli/src
 
-Update the dbo CLI, plugins, or Claude Code commands.
+# Install/upgrade Claude Code commands
+dbo install plugins
+dbo install claudecommands
 
-```bash
-# Update CLI + ask about Claude commands
-dbo update
+# Install Claude Code commands globally (shared across projects)
+dbo install plugins --global
 
-# Update only the CLI (git pull or npm update)
-dbo update cli
+# Explicitly install to project directory
+dbo install plugins --local
 
-# Update all plugins
-dbo update plugins
+# Install Claude Code CLI (if not present) + commands
+dbo install claudecode
 
-# Re-sync Claude commands from source
-dbo update claudecommands
+# Install/upgrade a specific command plugin
+dbo install --claudecommand dbo
 
-# Update a specific Claude command
-dbo update --claudecommand dbo
+# Install a specific command globally
+dbo install --claudecommand dbo --global
 ```
 
 | Flag | Description |
 |------|-------------|
-| `[target]` | What to update: `cli`, `plugins`, `claudecommands` |
-| `--claudecommand <name>` | Update a specific command by name |
-
-The update compares file hashes — unchanged files are skipped with "already up to date".
+| `[target]` | What to install: `dbo[@version]`, `plugins`, `claudecommands`, `claudecode`, or a local path |
+| `--claudecommand <name>` | Install/upgrade a specific command by name |
+| `-g, --global` | Install commands to user home directory (`~/.claude/commands/`) |
+| `--local` | Install commands to project directory (`.claude/commands/`) |
+
+Smart behavior:
+- If the CLI is already installed, prompts to upgrade (with version comparison)
+- If plugins are already installed and up to date, reports "already up to date"
+- If plugins differ from source, prompts to upgrade to the latest version
+- Compares file hashes — unchanged files are skipped
+- Adds project-scoped command files to `.gitignore` (source of truth is `src/plugins/claudecommands/`)
+- Per-plugin scope (project or global) is stored in `.dbo/config.local.json` and remembered for future upgrades
+- On first install of a plugin without a stored preference, prompts for scope
+- `--global` / `--local` flags override stored preferences and update them
 
 ---
 

package/bin/dbo.js

@@ -18,15 +18,17 @@ import { pushCommand } from '../src/commands/push.js';
 import { pullCommand } from '../src/commands/pull.js';
 import { addCommand } from '../src/commands/add.js';
 import { installCommand } from '../src/commands/install.js';
-import { updateCommand } from '../src/commands/update.js';
 import { cloneCommand } from '../src/commands/clone.js';
+import { diffCommand } from '../src/commands/diff.js';
+import { rmCommand } from '../src/commands/rm.js';
+import { mvCommand } from '../src/commands/mv.js';
 
 const program = new Command();
 
 program
   .name('dbo')
   .description('CLI for the DBO.io framework')
-  .version('0.4.2');
+  .version('0.5.0');
 
 program.addCommand(initCommand);
 program.addCommand(loginCommand);
@@ -45,7 +47,9 @@ program.addCommand(pushCommand);
 program.addCommand(pullCommand);
 program.addCommand(addCommand);
 program.addCommand(installCommand);
-program.addCommand(updateCommand);
 program.addCommand(cloneCommand);
+program.addCommand(diffCommand);
+program.addCommand(rmCommand);
+program.addCommand(mvCommand);
 
 program.parse();

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "@dboio/cli",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "CLI for the DBO.io framework",
   "type": "module",
   "bin": {
     "dbo": "./bin/dbo.js"
   },
+  "files": [
+    "plugins/",
+    "bin/",
+    "src/",
+    "README.md"
+  ],
   "engines": {
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node --test src/**/*.test.js"
+    "test": "node --test src/**/*.test.js tests/**/*.test.js"
   },
   "dependencies": {
     "commander": "^12.1.0",
@@ -26,7 +32,7 @@
     "rest",
     "crud"
   ],
-  "license": "UNLICENSED",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/dboio/api.git",