@dboio/cli 0.6.13 → 0.7.2

package/README.md

@@ -158,6 +158,7 @@ All configuration is **directory-scoped**. Each project folder maintains its own
 | `AppShortName` | string | App short name (used for `dbo clone --app`) |
 | `AppModifyKey` | string | ModifyKey for locked/production apps (set by `dbo clone`, used for submission guards) |
 | `TransactionKeyPreset` | `RowUID` \| `RowID` | Row key type for auto-assembled expressions (set during `dbo init`/`dbo clone`, default `RowUID`) |
+| `TicketSuggestionOutput` | string | Output UID for fetching ticket suggestions during error recovery (set during `dbo init`, default `ojaie9t3o0kfvliahnuuda`) |
 | `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`) |
@@ -169,6 +170,10 @@ All configuration is **directory-scoped**. Each project folder maintains its own
 
 These are set interactively on first clone and saved for future use. Pre-set them in `config.json` to skip the prompt entirely.
 
+#### `app.json._domain`
+
+The `_domain` field in `app.json` stores the project's reference domain (set during `dbo clone`). This is committed to git and used for domain-change detection when running `dbo init --force` or `dbo clone --domain`. It provides a stable cross-user baseline — all collaborators share the same reference domain.
+
 ### Legacy migration
 
 If your project uses the older `.domain`, `.username`, `.password`, `.cookies` files, `dbo init` will detect them and offer to migrate automatically.
@@ -196,17 +201,20 @@ 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
+dbo init --scaffold                                   # scaffold dirs (prompts for domain)
+dbo init --scaffold --yes                             # scaffold dirs non-interactively
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--domain <host>` | DBO instance domain |
 | `--username <user>` | DBO username (stored for login default) |
-| `--force` | Overwrite existing configuration |
+| `--force` | Overwrite existing configuration. Triggers a domain-change confirmation prompt when the new domain differs from the project reference domain |
 | `--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/`) |
+| `--scaffold` | Pre-create standard project directories (`App Versions`, `Automations`, `Bins`, `Data Sources`, `Documentation`, `Extensions`, `Groups`, `Integrations`, `Sites`) |
 | `-y, --yes` | Skip all interactive prompts (legacy migration, Claude Code setup) |
 | `--non-interactive` | Alias for `--yes` |
 
@@ -234,10 +242,16 @@ dbo init --domain my-domain.com --app myapp --clone
 |------|-------------|
 | `<source>` | Local JSON file path (optional positional argument) |
 | `--app <name>` | App short name to fetch from server |
-| `--domain <host>` | Override domain |
+| `--domain <host>` | Override domain. Triggers a domain-change confirmation prompt when it differs from the project reference domain |
 | `-y, --yes` | Auto-accept all prompts |
 | `-v, --verbose` | Show HTTP request details |
 
+#### Domain change detection
+
+When cloning with a different domain than the project's reference domain (`app.json._domain` or `config.json.domain`), the CLI warns before proceeding. When `TransactionKeyPreset=RowID`, this escalates to a critical error because numeric IDs are not unique across domains — pushing to the wrong domain can corrupt records. In non-interactive mode (`-y`), RowUID domain changes proceed with a warning, but RowID domain changes throw a hard error.
+
+The project's reference domain is stored in `app.json._domain` (committed to git) during clone, giving the CLI a stable cross-user baseline.
+
 #### What clone does
 
 1. **Loads app JSON** — from a local file, server API, or interactive prompt
@@ -438,7 +452,6 @@ Output:
   Domain: my-domain.com
   Username: user@example.com
   User ID: 10296
-  User UID: albain3dwkofbhnd1qtd1q
   Directory: /Users/me/projects/operator
   Session: Active (expires: 2026-03-15T10:30:00.000Z)
   Cookies: /Users/me/projects/operator/.dbo/cookies.txt
@@ -447,7 +460,7 @@ Output:
   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.
+User ID is populated by `dbo login`. If it shows "(not set)", run `dbo login` to fetch it.
 
 Plugin scopes (project or global) are displayed when plugins have been installed. Scopes are stored in `.dbo/config.local.json`.
 
@@ -559,8 +572,24 @@ dbo output myOutputUID --debug-sql
 | `--maxrows <n>` | Maximum rows |
 | `--rows <range>` | Row range, e.g., `1-10` |
 | `--template <value>` | Custom template |
+| `--limit <n>` | Maximum rows to return (preferred over `--maxrows`) |
+| `--rowcount <bool>` | Include row count: `true` (default) or `false` for performance |
+| `--display <expr>` | Show/hide template tags (repeatable), e.g., `sidebar=hide` |
+| `--format-values` | Enable value formatting in `json_raw` output |
+| `--empty-response-code <code>` | HTTP status code when output returns no results |
+| `--fallback-content <expr>` | Fallback content UID for error codes, e.g., `404=contentUID` |
+| `--escape-html <bool>` | Control HTML escaping: `true` or `false` |
+| `--mime <type>` | Override MIME/content type |
+| `--strict` | Strict error mode |
+| `--confirm` | Confirmation flag |
+| `--include <expr>` | Include token |
+| `--no-transaction` | Disable transaction wrapping |
+| `--skip <phase>` | Skip execution phases (repeatable, admin-only) |
+| `--profile` | Enable MiniProfiler output |
 | `--debug` | Include debug info |
 | `--debug-sql` | Include SQL debug info |
+| `--debug-verbose` | Verbose debug output |
+| `--debug-analysis` | Analysis debug output |
 | `--meta` | Use meta output endpoint |
 | `--meta-column <uid>` | Column metadata |
 | `--save` | Interactive save-to-disk mode |
@@ -1144,6 +1173,22 @@ When the server returns a `ticket_error` (record update requires a Ticket ID), t
   Skip all updates that require a Ticket ID
 ```
 
+#### Ticket suggestions
+
+When `TicketSuggestionOutput` is configured in `.dbo/config.json` (set during `dbo init`), the CLI automatically fetches relevant ticket suggestions from the server and presents them as selectable choices:
+
+```
+? Select a Ticket ID:
+❯ 1 (TKT-001): Fix login page [login-fix]
+  2 (TKT-002): Update dashboard [dashboard-v2]
+  3 (TKT-003): Refactor auth [auth-refactor]
+  Enter a Ticket ID manually…
+```
+
+The suggestions are fetched from the configured output endpoint, filtered by the current record's UID. Users can arrow-key through the list to select a ticket, or choose "Enter a Ticket ID manually" for custom input.
+
+If `TicketSuggestionOutput` is not configured or the fetch fails, the CLI falls back to a plain text input prompt.
+
 When the server returns a `repo_mismatch` (Ticket ID belongs to a different repository), the CLI prompts:
 
 ```
@@ -1496,6 +1541,158 @@ Both `--json` and `--jq` output use syntax highlighting:
 
 ---
 
+## DBO API Parameter Reference
+
+The DBO.io API uses a token architecture for dynamic parameters. All parameters are passed as URL query string key-value pairs.
+
+### Token Syntax
+
+Parameters follow the token delimiter system:
+
+```
+_tokenType@reference$target!defaultValue:modifier=value
+```
+
+| Delimiter | Purpose | Example |
+|-----------|---------|---------|
+| `_` | Prefix for token type | `_filter`, `_sort`, `_limit` |
+| `@` | Reference (column, field, key) | `_filter@FirstName=John` |
+| `$` | Target (scope to a specific output/entity) | `_limit$outputUid=100` |
+| `!` | Default value (fallback) | `_filter@Status!active=value` |
+| `:` | Modifier(s) | `_filter@Name:Contains=john` |
+
+### Output Parameters
+
+These parameters control the output endpoint behavior (`/api/output/{uid}` and `/api/output/entity/{entityUid}`):
+
+#### Filtering
+
+```
+_filter@ColumnName=value                          # exact match (default)
+_filter@ColumnName:Contains=value                 # LIKE %value%
+_filter@ColumnName:StartsWith=value               # LIKE value%
+_filter@ColumnName:EndsWith=value                 # LIKE %value
+_filter@ColumnName:LessThan=value                 # < comparison
+_filter@ColumnName:LessThanOrEqualTo=value        # <= comparison
+_filter@ColumnName:GreaterThan=value              # > comparison
+_filter@ColumnName:GreaterThanOrEqualTo=value     # >= comparison
+_filter@ColumnName:Contains,And=value             # AND logic (default is OR)
+_filter@ColumnName:Contains,Exclude=value         # NOT LIKE
+_filter$outputTarget@ColumnName=value             # scoped to specific output
+```
+
+#### Sorting
+
+```
+_sort=ColumnName                                  # ascending (default)
+_sort=ColumnName:ASC                              # explicit ascending
+_sort=ColumnName:DESC                             # descending
+_sort=Column1:ASC,Column2:DESC                    # multiple sorts (comma-separated)
+_sort=ColumnName ASC                              # space-separated also works
+```
+
+Multiple `_sort` parameters can be specified; earlier sorts take precedence.
+
+#### Pagination
+
+```
+_limit=30                                         # max 30 rows
+_limit=10-30                                      # rows 10 through 30 (range)
+_limit=10&_page=3                                 # 10 rows per page, page 3
+_rowcount=false                                   # disable row count for performance
+```
+
+Deprecated (still accepted): `_maxrows`, `_rows`, `_rowsperpage`
+
+#### Search
+
+```
+_search=keyword                                   # full-text search across searchable columns
+_search@ColumnName=keyword                        # search specific column
+```
+
+#### Template & Format
+
+```
+_template=json_raw                                # format name: json_raw, html, json, json_indented, csv, xml, txt, pdf
+_template=3iX9fHFTL064Shgol8Bktw                 # content UID (custom template)
+_format_values=true                               # enable value formatting in json_raw
+_format=json                                      # legacy format specifier
+_mime=application/json                             # override MIME/content type
+_escape_html=false                                # disable HTML escaping of data values
+```
+
+#### Display Control
+
+```
+_display@tagName=show                             # show a template content tag
+_display@tagName=hide                             # hide a template content tag
+_empty_response_code=404                          # HTTP status when results are empty
+_fallback_content:404=contentUID                  # render a different content on 404
+```
+
+#### Debug & Profiling
+
+```
+_debug=true                                       # general debug output
+_debug:sql=true                                   # return SQL without executing
+_debug:verbose=true                               # verbose debug
+_debug:analysis=true                              # analysis debug
+_profile=true                                     # MiniProfiler output
+```
+
+Other debug sub-keys: `http_modules`, `instance`, `rewrites`, `cache`, `executable_contents`, `security`, `controllers`, `embeds`, `includes`, `contents`, `template_render`, `tokens`, `messages`, `media`, `request_stack`, `query_execution`, `query_building`
+
+#### Control Flags
+
+```
+_strict=true                                      # strict error mode
+_confirm=true                                     # confirmation flag for operations
+_no_transaction=true                              # disable transaction wrapping
+_skip=all                                         # skip execution phases (admin-only)
+_include=value                                    # include token
+_security=value                                   # security filter enforcement
+```
+
+### Data Tokens (used in templates)
+
+| Token | Description |
+|-------|-------------|
+| `#{value@ColumnName}` | Column value from output row |
+| `#{id}` | Row primary key |
+| `#{uid}` | Row UID |
+| `#{CurrentUser@field}` | Current user field (e.g., `FirstName`, `Email`) |
+| `#{request@key}` | URL parameter value |
+| `#{session@variable}` | Session variable |
+| `#{site@field}` | Site field |
+| `#{date:format}` | Current date/time |
+| `#{unique:uid}` | Generate unique UID |
+| `#{count}` | Row count |
+| `#{page}` | Current page number |
+
+### Template Tags
+
+System tags (used in output templates):
+
+| Tag | Purpose |
+|-----|---------|
+| `<#_row>` | Row template |
+| `<#_header>` | Header template |
+| `<#_footer>` | Footer template |
+| `<#_cell>` | Cell template |
+| `<#_empty>` | Empty result template |
+| `<#_noresult>` | No result template |
+| `<#_prompt>` | Prompt template |
+| `<#_shared>` | Shared template |
+| `<#_rowdelimiter>` | Row delimiter |
+| `<#_celldelimiter>` | Cell delimiter |
+| `<#_value>` | Value template |
+| `<#_embed url="...">` | Embed nested content/output |
+
+User-defined tags use `<#reference>` (no underscore prefix).
+
+---
+
 ## Migration from curl
 
 The `dbo` CLI is a drop-in replacement for the curl-based workflow. Here's how common operations translate:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dboio/cli",
-  "version": "0.6.13",
+  "version": "0.7.2",
   "description": "CLI for the DBO.io framework",
   "type": "module",
   "bin": {