@dboio/cli 0.19.0 → 0.19.2

package/plugins/claude/dbo/skills/white-paper/references/deploy-and-scripts.md

@@ -0,0 +1,210 @@
+# Deploy & Push Reference
+
+The standard workflow for getting local changes to the server uses `dbo push` and `dbo deploy`. Two config files — `.app/deploy_config.json` and `.app/scripts.json` — provide optional shorthand and automation on top of these commands.
+
+## Standard Commands
+
+### `dbo push` — Push local metadata-tracked files to server
+
+Push works with files that have a companion `.metadata.json` (created by `dbo clone` or `dbo adopt`).
+
+```bash
+# Push a single file
+dbo push lib/bins/app/assets/css/colors.css
+
+# Push all changed files in a directory
+dbo push lib/bins/app/assets/
+
+# Push everything in the project
+dbo push
+
+# Validate without submitting
+dbo push lib/bins/app/assets/css/colors.css --confirm false
+
+# Push only file content, skip metadata column changes
+dbo push lib/bins/app/assets/css/colors.css --content-only
+
+# Push only metadata changes, skip file content
+dbo push lib/bins/app/assets/css/colors.css --meta-only
+```
+
+Push detects changes by comparing local files against the server baseline. Records without a UID (created by `dbo adopt`) are submitted as new inserts.
+
+### `dbo deploy` — Push a file to a specific record by UID or shorthand
+
+Use `dbo deploy` when you want to target a record by UID directly, or when you have a named shorthand defined in `.app/deploy_config.json`.
+
+```bash
+# Deploy by UID directly
+dbo deploy bdcaeef375f242df84760c path/to/file.css
+
+# Deploy by shorthand name (requires deploy_config.json entry)
+dbo deploy css:colors
+
+# Deploy all entries
+dbo deploy --all
+
+# Validate without deploying
+dbo deploy css:colors --confirm false
+```
+
+### `dbo clone` — Pull the full app from server to local files
+
+```bash
+# Clone using AppShortName from config
+dbo clone
+
+# Clone a specific entity type only
+dbo clone -e extension
+dbo clone -e content
+```
+
+### `dbo pull` / `dbo diff` — Sync server changes locally
+
+```bash
+# Interactive diff — compare local vs server, accept/skip per file
+dbo diff assets/css/
+
+# Pull a content record directly
+dbo content pull ykqucv0eb0ggjqgcncj6dq
+```
+
+---
+
+## Deploy Config (.app/deploy_config.json)
+
+Optional. Defines shorthand names for `dbo deploy`. Auto-generated by `dbo clone` and `dbo adopt` — one entry per companion file.
+
+### Structure
+```json
+{
+  "deployments": {
+    "{shorthand}": {
+      "uid": "{record_uid}",
+      "file": "lib/bins/path/to/file.ext",
+      "entity": "content|media",
+      "column": "Content|File"
+    }
+  }
+}
+```
+
+### Naming convention
+Shorthands follow `{type}:{name}` pattern:
+- `css:colors` — CSS content record
+- `css:colors_media` — companion media record for same CSS file
+- `css:colors.min` — minified version (content)
+- `js:app.min` — minified JS bundle
+- `doc:chat` — documentation/extension record
+- `cs:_CurrentTicketID` — C# content execution
+
+### Content vs Media records
+Many assets have paired records:
+- **Content record** (`entity: "content"`, `column: "Content"`) — the text/code content
+- **Media record** (`entity: "media"`, `column: "File"`) — the binary file reference
+
+The `_media` suffix in the shorthand indicates the media companion record.
+
+---
+
+## Build Scripts (.app/scripts.json)
+
+Optional. Defines build and post-push lifecycle hooks per target file.
+
+### Structure
+```json
+{
+  "scripts": {
+    "build": []
+  },
+  "targets": {
+    "lib/bins/path/to/output.file": {
+      "build": ["command1", "command2"],
+      "postpush": ["command3"]
+    }
+  },
+  "entities": {}
+}
+```
+
+### Script types
+| Type | When it runs | Purpose |
+|------|-------------|---------|
+| `build` | `dbo build` or `npm run build` | Compile source → output |
+| `postpush` | Automatically after `dbo push` of that target | Deploy dependent assets |
+
+### Common build patterns
+
+**SASS → CSS → Minified CSS:**
+```json
+{
+  "build": [
+    "sass src/sass/core/operator.scss:lib/bins/app/assets/css/operator.css",
+    "csso lib/bins/app/assets/css/operator.css --output lib/bins/app/assets/css/operator.min.css"
+  ]
+}
+```
+
+**Rollup JS bundling:**
+```json
+{
+  "build": [
+    "rollup --config src/rollup.config.mjs"
+  ]
+}
+```
+
+**Post-push deploy chain:**
+```json
+{
+  "postpush": [
+    "dbo deploy doc:chat",
+    "dbo deploy doc:globals"
+  ]
+}
+```
+
+---
+
+## Typical Workflows
+
+### Simple edit and push (most common)
+```bash
+# Edit a file locally, then push it
+dbo push lib/bins/app/assets/css/colors.css
+```
+
+### Source → Build → Push (compiled assets)
+```bash
+# 1. Edit source in src/ (SASS, JS modules, etc.)
+# 2. Build — compiles to lib/bins/
+npm run build
+
+# 3. Push compiled output to server
+dbo push lib/bins/app/assets/css/operator.css
+# postpush scripts in scripts.json run automatically
+```
+
+### New file → Adopt → Push
+```bash
+# 1. Create the file locally
+# 2. Create a metadata companion
+dbo adopt lib/bins/app/assets/css/new-file.css -e content
+
+# 3. Push as a new server record
+dbo push lib/bins/app/assets/css/new-file.css
+```
+
+---
+
+## Template Variables (CLI scaffolding)
+
+When `dbo init` scaffolds this skill into a project's `.claude/`, the CLI can replace these placeholders with app-specific values:
+
+| Variable | Replaced with |
+|----------|--------------|
+| `{{domain}}` | `.app/config.json` → `domain` |
+| `{{appName}}` | `.app/config.json` → `AppName` |
+| `{{appShortName}}` | `.app/config.json` → `AppShortName` |
+| `{{appUID}}` | `.app/config.json` → `AppUID` |
+| `{{appID}}` | `.app/config.json` → `AppID` |

package/plugins/claude/dbo/skills/white-paper/references/template-syntax.md

@@ -0,0 +1,178 @@
+# DBO Template & Token Syntax
+
+Reference for the DBO template language used in outputs, content, and embeds.
+
+## Token Syntax
+
+```
+#{type@reference$target!default:modifier;comment}
+```
+
+Order: `type` → `@ref` → `$target` → `!default` → `:modifier` → `;comment`. All parts except `type` are optional.
+
+### Token Types
+
+| Token | Reads from |
+|-------|-----------|
+| `#{value@Field}` | Current row data in render context |
+| `#{request@Param}` | URL / request parameters |
+| `#{session@Field}` | Authenticated session (e.g., `#{session@UserID}`) |
+| `#{input@add1.id}` | ID of record created in same input batch |
+| `#{payload$Target}` | Rendered output of a named embed |
+| `#{unique}` | Generated unique ID |
+
+### Defaults
+```
+#{request@Param!fallback}
+#{session@CustomerID!#{request@CustomerID}}   ← nested token as default
+```
+
+### Modifiers
+
+| Modifier | Effect |
+|----------|--------|
+| `:cached$Target` | Deferred read from named embed — resolves after all embeds execute |
+| `:no_escape` | Raw value, bypasses format-based escaping |
+| `:raw` | Deferred injection via placeholder (final render pass) |
+| `:escape_json` | Force JSON-safe escaping |
+| `:url_encode` | URL percent-encode |
+| `:url_decode` | URL-decode |
+| `:truncate` | Truncate to 100 chars with "..." |
+| `:{format}` | .NET format string (`:d` short date, `:f2` 2 decimals) |
+
+**Rule**: Always pair `:cached` with an explicit `$Target`.
+
+## Tag Syntax
+
+Three tag systems — do NOT conflate with tokens (`#{...}`):
+
+```html
+<#_tagname attr="val"/>          system tags  (structural, underscore prefix)
+<#CustomSection>...</#Custom>    custom tags  (user-defined named sections)
+<@slotName>...</@slotName>       slot tags    (master template slots)
+```
+
+### System Tags
+
+| Tag | Purpose |
+|-----|---------|
+| `<#_embed url="..." .../>` | Embed another output, content, or input |
+| `<#_row>...</#_row>` | Repeating section — once per result row |
+| `<#_header>` / `<#_footer>` | Before / after all rows |
+| `<#_noresult>` | Renders when query returns zero rows |
+| `<#_empty>` | Also renders on zero rows (after noresult) |
+| `<#_successful>` | Inside input embed — on success |
+| `<#_failed>` | Inside input embed — on failure |
+| `<#_value.Field value="_null">` | Conditional: renders when Field is null |
+| `<#_value.Field modifier="exclude" value="_null">` | Conditional: Field is NOT null |
+| `<#_include target="name">val</#_include>` | Set named variable |
+
+### Parser prefixes
+- **Output & Input parsers**: Accept both `#` and `#_` prefix
+- **Message parser**: Only accepts `#_` prefix
+- **Email parser**: Accepts `~` and `#_` prefix
+
+Use `<#_` for system tags consistently to avoid parser ambiguity.
+
+## Embed System
+
+Embeds are the primary composition mechanism — internal API call with inlined result.
+
+### Self-closing embed
+```html
+<#_embed url="/api/output/{uid}" name="label.name" secure="false" target="MyTarget"/>
+```
+
+### Block embed
+```html
+<#_embed.myid url="/api/output/{uid}" name="label.name">
+  <#_row><li>#{value@Name}</li></#_row>
+  <#_noresult><p>None.</p></#_noresult>
+</#_embed.myid>
+```
+
+The `.myid` serialization suffix is required for nested block embeds.
+
+### Embed Attributes
+
+| Attribute | Default | Notes |
+|-----------|---------|-------|
+| `url` | required | Endpoint to embed |
+| `name` | — | Label for debugging and payload ID |
+| `target` | — | Context for `:cached` tokens and `#{payload$...}` |
+| `secure` | `true` | `false` bypasses access control for this request |
+| `execute` | `true` | `false` skips the call entirely |
+| `hide` | `false` | `true` executes but suppresses output |
+| `payload` | `true` | `false` skips caching rendered output |
+| `catch_exception` | `"401,406"` | HTTP codes caught silently; `"true"` catches all |
+
+### URL prefixes
+| Short | Full |
+|-------|------|
+| `/api/o/` | `/api/output/{uid}` |
+| `/api/c/` | `/api/content/{uid}` |
+| `/api/i/s` | `/api/input/submit` |
+
+## Output Template Sections
+
+```
+[_header] → [_row × N] → [_footer]
+          ↘ [_noresult] + [_empty] if N = 0
+```
+
+Custom sections (`<#SectionName>...</#SectionName>`) are named blocks for composability.
+
+## Common Patterns
+
+### Data read with inline template
+```html
+<#_embed.list url="/api/output/{uid}" name="my.list">
+  <#_row><div>#{value@Name}</div></#_row>
+  <#_noresult><p>No results.</p></#_noresult>
+</#_embed.list>
+```
+
+### Two-phase write (insert + cross-reference)
+```html
+<#_embed.first url="/api/input/submit?_confirm=true
+    &RowID:add1;column:table.TypeID=24">
+  <#_successful>
+    <#_embed url="/api/input/submit?_confirm=true
+        &RowID:add2;column:table.ParentID=#{input@add1.id}"/>
+  </#_successful>
+  <#_failed>Write failed.</#_failed>
+</#_embed.first>
+```
+
+### Read from named embed payload
+```html
+<#_embed url="/api/output/{uid}" target="MyOutput"/>
+#{value@SomeField:cached$MyOutput}
+```
+
+### Flow file (backend action, no UI)
+```html
+<#_embed url="/api/output/{uid}" target="Ctx" hide="true" secure="false"/>
+<#_embed.action url="/api/input/submit?_confirm=true&RowID:add1;...">
+  <#_successful>{"ok": true}</#_successful>
+  <#_failed>{"ok": false}</#_failed>
+</#_embed.action>
+```
+
+## Input Forms (browser-side)
+
+```html
+<form id="my-form" data-os-form="{validate: true, done: function() {...}}">
+  <input name="RowID:{id};column:table.Field" value="#{value@Field}" />
+</form>
+```
+
+Submit: `os.form.submit('#my-form')`
+
+## Security Context
+
+- `LoggedInUser` — always used for security evaluation
+- `CurrentUser` — render context, changed by impersonation (`_as`)
+- `Administrator` flag — bypasses all security checks
+- `secure="false"` on embed — bypasses access control for that request only
+- Default: 401/406 from embeds are caught silently

package/plugins/claude/track/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "track",
+  "version": "1.0.0",
+  "description": "Changelog and Track API logging for Claude Code — automatically logs changes to changelog.md and the remote Track task_log on every session",
+  "author": {
+    "name": "DBO.io"
+  },
+  "hooks": [
+    {
+      "path": "hooks/hooks.json"
+    }
+  ],
+  "skills": [
+    {
+      "path": "skills/changelog/SKILL.md",
+      "name": "changelog",
+      "description": "Changelog and Track API logging instructions — when and how to write changelog.md entries and submit to the Track task_log API after editing source files or pushing DBO assets"
+    }
+  ]
+}

package/plugins/claude/track/README.md

@@ -0,0 +1,135 @@
+# Track Plugin for Claude Code
+
+Claude Code plugin that automatically logs every change to a local `changelog.md` and to the centralized Track `task_log` API. Runs on every session, across every project.
+
+## Why this plugin exists (and why the old approach was messy)
+
+Before this plugin, the changelog and Track API workflow was managed by a bash setup script (`changelog-setup.sh`) that:
+
+1. **Mutated global `~/.claude/CLAUDE.md` in-place** — appended a large `## Changelog` section directly into the user's personal instructions file. This made the file hard to maintain, impossible to version, and fragile to update (the script used `sed` to find and remove the section before rewriting it).
+
+2. **Had no source of truth** — the changelog instructions lived in a generated file that no one committed, so it was unclear what version any given machine was running.
+
+3. **No per-project opt-out** — once installed, the behavior applied everywhere with no way to suppress it for projects where it doesn't make sense (non-manolab apps, open-source contributions, scratch projects).
+
+4. **Installed a skill to the wrong location** — `/changelog-summary` was written to `~/.claude/skills/`, outside any versioned repository, making it invisible to code review and hard to iterate on.
+
+5. **Required re-running the script to update** — any change to the instructions meant running the script again, hoping the sed cleanup worked, and restarting Claude.
+
+### What the plugin approach solves
+
+| Problem | Old approach | Plugin approach |
+|---------|-------------|-----------------|
+| Changelog instructions | Appended to `~/.claude/CLAUDE.md` | Owned by `skills/changelog/SKILL.md` |
+| Versioning | Unversioned, generated | Committed alongside the CLI source |
+| Updates | Re-run bash script | `dbo install plugins` or `npm update @dboio/cli` |
+| Per-project opt-out | Not possible | One line in local `CLAUDE.md` overrides globally |
+| `/changelog-summary` skill | Written to `~/.claude/skills/` | Defined in the CLI package |
+| Session loading | Always in context (inflates every session) | Loaded via SessionStart hook (loaded once, cleanly) |
+
+### Architecture: additive, not replacing
+
+The plugin does **not** remove or replace the `## Changelog` section in `~/.claude/CLAUDE.md`. Both run in parallel:
+
+```
+Global ~/.claude/CLAUDE.md        → "always log changelog"     (universal floor — fires even outside repos)
+Plugin SessionStart hook          → loads changelog skill       (versioned, updatable delivery mechanism)
+Project CLAUDE.md (opt-out)       → "skip for this project"    → overrides both ↑
+```
+
+The global CLAUDE.md is the coverage guarantee — it fires unconditionally on every session including scratch files and paths outside any repository. The plugin is the delivery mechanism that keeps the instructions versioned and makes per-project opt-out possible. The two sources carry identical instructions, so duplication is invisible in practice.
+
+A local project CLAUDE.md opt-out suppresses both sources. Claude Code's CLAUDE.md hierarchy treats the project-level file as more specific than global, and the opt-out language is explicit enough to make the override unambiguous.
+
+## Plugin Structure
+
+```
+track/
+├── .claude-plugin/
+│   └── plugin.json                 # Plugin manifest (version, hooks, skills)
+├── commands/
+│   └── install.md                  # /track install — one-time machine setup
+├── hooks/
+│   └── hooks.json                  # SessionStart: always loads changelog skill
+├── skills/
+│   └── changelog/
+│       └── SKILL.md               # Full changelog + Track API logging instructions
+└── README.md                       # This file
+```
+
+## Components
+
+### `/track install` command (`commands/install.md`)
+
+User-invocable slash command for one-time machine setup. Run this once per machine after the CLI is installed. It:
+
+1. Creates `~/.claude/track-changelog` — the interactive login script that authenticates with `beta-track.dbo.io` and saves a session cookie to `~/.claude/track-cookies.txt`
+2. Prints next-step instructions
+
+It does **not** touch `~/.claude/CLAUDE.md` — the global changelog instructions stay in place as a coverage guarantee (see Architecture above).
+
+### SessionStart hook (`hooks/hooks.json`)
+
+Fires at the start of every Claude Code session. Tells Claude to load the `changelog` skill unconditionally. Also instructs Claude to honour any per-project opt-out directive found in a local CLAUDE.md.
+
+### Changelog skill (`skills/changelog/SKILL.md`)
+
+The authoritative source of truth for all logging behavior. Contains:
+
+- **When to log**: after any source file edit; additionally after DBO asset pushes
+- **File format**: `changelog.md` table schema with Date, Time, Asset Type, Name, UID, Description columns
+- **Track API session check**: how to verify the cookie is valid before the first log entry of each session
+- **Track API write**: the `curl` command for submitting a `task_log` row, including all field semantics
+- **Error handling**: what to do when the API is unreachable or the session has expired
+- **Opt-out awareness**: how to detect and respect per-project suppression directives
+
+## Installation
+
+The track plugin ships inside the `@dboio/cli` npm package alongside the `dbo` plugin. It is installed automatically when you run:
+
+```bash
+dbo install plugins --local   # install into the current project
+dbo install plugins --global  # install for all projects on this machine
+```
+
+After installation, run the one-time machine setup:
+
+```
+/track install
+```
+
+This creates `~/.claude/track-changelog`. Then open a terminal and authenticate:
+
+```bash
+~/.claude/track-changelog
+```
+
+## Per-project opt-out
+
+To suppress changelog logging and Track API calls for a specific project, add this to the project's `CLAUDE.md`:
+
+```markdown
+## Track Logging
+
+**Do not write changelog entries or call the Track API for this project.**
+
+This project is not tracked in Track. Skip all `changelog.md` writes and
+`beta-track.dbo.io` API calls, even though the track plugin is installed globally.
+This directive overrides both the global CLAUDE.md and the track plugin.
+```
+
+Claude Code's CLAUDE.md hierarchy treats the project-level file as more specific than global, so this suppresses both sources. The SessionStart hook is also explicitly instructed to honour local opt-out directives.
+
+## Authentication
+
+The Track API uses cookie-based session auth. The session cookie is stored at `~/.claude/track-cookies.txt` and is shared across all Claude Code sessions on the machine.
+
+- **To log in**: run `~/.claude/track-changelog` in a terminal
+- **If the session expires**: Claude will tell you "Track Access Denied" — re-run `~/.claude/track-changelog`
+- Claude never attempts to log in on your behalf or store credentials
+
+## Version History
+
+| Version | Changes |
+|---------|---------|
+| 1.0.0 | Initial release — replaces `changelog-setup.sh`. SessionStart hook, changelog skill, `/track install` command |

package/plugins/claude/track/commands/install.md

@@ -0,0 +1,96 @@
+---
+name: install
+description: Install the Track changelog integration — creates ~/.claude/track-changelog login script.
+user-invokable: true
+allowed-tools: Write, Bash(chmod:*)
+---
+
+# Track Plugin Install
+
+Set up the Track changelog integration on this machine. Run this once per machine after installing the track plugin.
+
+## Steps
+
+### 1. Create `~/.claude/track-changelog`
+
+Write the following script to `~/.claude/track-changelog` (use the Write tool):
+
+```bash
+#!/bin/bash
+# track-changelog — Authenticate with Track (beta-track.dbo.io) and store session cookie
+# Usage: ~/.claude/track-changelog
+# Cookie is saved to ~/.claude/track-cookies.txt for use by the Track Claude plugin
+
+TRACK_DOMAIN="beta-track.dbo.io"
+COOKIE_FILE="$HOME/.claude/track-cookies.txt"
+SESSION_API="https://$TRACK_DOMAIN/api/o/asqor6nmxuiwqbhldlki7g"
+
+echo "=== Track Login ==="
+echo "Domain: $TRACK_DOMAIN"
+echo ""
+
+# Prompt for credentials (password hidden)
+read -p "Email: " email
+read -s -p "Password: " password
+echo ""
+
+# Authenticate
+response=$(curl -s -c "$COOKIE_FILE" -w "\n%{http_code}" \
+  "https://$TRACK_DOMAIN/api/input/submit" \
+  --data-urlencode "_username=$email" \
+  --data-urlencode "_password=$password" \
+  --data-urlencode "_confirm=true")
+
+http_code=$(echo "$response" | tail -1)
+
+if [ "$http_code" = "307" ] || [ "$http_code" = "403" ]; then
+  echo "Login failed (HTTP $http_code). Check your credentials."
+  rm -f "$COOKIE_FILE"
+  exit 1
+fi
+
+# Verify session
+session=$(curl -s -b "$COOKIE_FILE" "$SESSION_API")
+
+if [ "$session" = "[]" ] || [ -z "$session" ]; then
+  echo "Login failed — session not established."
+  rm -f "$COOKIE_FILE"
+  exit 1
+fi
+
+# Extract user info
+name=$(echo "$session" | grep -o '"FirstName":"[^"]*"' | head -1 | cut -d'"' -f4)
+contact_id=$(echo "$session" | grep -o '"ContactID":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+echo ""
+echo "Logged in as: $name (ContactID: $contact_id)"
+echo "Cookie saved: $COOKIE_FILE"
+echo ""
+echo "Session is ready for the Track Claude plugin."
+```
+
+After writing the file, make it executable:
+```bash
+chmod +x ~/.claude/track-changelog
+```
+
+### 2. Confirm and show next steps
+
+Tell the user:
+
+```
+Track plugin installed.
+
+Next steps:
+  1. Open a new terminal and run:  ~/.claude/track-changelog
+     (Enter your Track email and password to establish a session)
+
+  2. Restart any open Claude Code sessions to pick up the plugin
+
+  3. Claude will now automatically:
+     - Log changes to <project-memory>/changelog.md (local)
+     - Write each entry to the Track task_log (remote)
+     - Honour per-project opt-out directives in CLAUDE.md
+
+  If you see "Track Access Denied", re-run ~/.claude/track-changelog
+```

package/plugins/claude/track/hooks/hooks.json

@@ -0,0 +1,11 @@
+{
+  "description": "Track plugin hooks — loads versioned changelog and Track API logging instructions at every session start",
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "prompt",
+        "prompt": "Invoke the /track:changelog skill to load the versioned changelog and Track API logging instructions. If a local CLAUDE.md in the current project contains an explicit directive to skip changelog logging or Track API calls (e.g. 'Do not write changelog entries or call the Track API for this project'), honour that override — it supersedes both this skill and the global CLAUDE.md changelog instructions."
+      }
+    ]
+  }
+}