@dboio/cli 0.19.7 → 0.20.3

package/plugins/claude/dbo/skills/white-paper/SKILL.md

@@ -49,10 +49,9 @@ project-root/
 ├── lib/                     # Server-mapped files (mirrors DBO table data)
 │   ├── bins/                # Bin entities and their children (see Bin Mapping below)
 │   ├── extension/           # Extension records, sub-foldered by Descriptor
-│   ├── entity/              # Entity metadata files
+│   ├── data_source/         # Data source configs + entity (table) definitions
 │   ├── site/                # Site definitions
 │   ├── security/            # Security rule records
-│   ├── data_source/         # Data source configurations
 │   └── app_version/         # App version metadata
 │
 ├── docs/                    # Project documentation (scripts, embeds, pages, components)
@@ -83,11 +82,11 @@ Files belonging to a `bin` entity are placed in directories matching their BinID
 }
 ```
 
-So `lib/bins/app/assets/css/colors.css` lives inside the bin whose `fullPath` is `app/assets/css`. Every file has a companion `.metadata.json` (or `.metadata~{uid}.json`) containing the server record fields.
+So `lib/bins/app/assets/css/colors.css` lives inside the bin whose `fullPath` is `app/assets/css`. Every file has a companion `.metadata.json` (e.g. `colors.metadata.json`) containing the server record fields, including the `UID` field.
 
 ### Non-bin entities (no BinID column)
 
-Entities without a BinID column get their own directory under `lib/`, named after the entity: `lib/extension/`, `lib/entity/`, `lib/site/`, `lib/security/`, `lib/data_source/`, `lib/app_version/`.
+Entities without a BinID column get their own directory under `lib/`, named after the entity: `lib/extension/`, `lib/site/`, `lib/security/`, `lib/data_source/`, `lib/app_version/`. Exception: `entity` (table definitions) shares `lib/data_source/` rather than getting its own directory — both `_entity: "data_source"` and `_entity: "entity"` records live there.
 
 ### Extension special case
 
@@ -96,7 +95,7 @@ The `extension` entity has sub-folders based on the **Descriptor** column value:
 - `lib/extension/Widget/` — Widget extensions
 - `lib/extension/Descriptor Definition/` — Descriptor definitions themselves
 
-Each extension file follows: `{Name}.{ContentColumnName}.{ext}` with a companion `{Name}.metadata~{uid}.json`.
+Each extension file follows: `{Name}.{ContentColumnName}.{ext}` with a companion `{Name}.metadata.json` (UID stored inside the JSON).
 
 ## .app/ Configuration
 
@@ -152,10 +151,10 @@ When `app_dependencies/{app_name}/` exists (e.g., `app_dependencies/operator/`),
 ## CLI vs REST API
 
 ### Use the DBO CLI for:
-- **File operations**: `pull`, `push`, `add`, `clone`, `rm`, `diff`
+- **File operations**: `pull`, `push`, `adopt`, `clone`, `rm`, `diff` — for `adopt`, always pass `-e <entity>` (e.g., `-e content` for HTML/CSS/JS, `-e media` for images/binaries); entity cannot be inferred for standalone files in `lib/bins/`
 - **Deployment**: `deploy` (shorthand or UID), content deploy
 - **Project setup**: `init`, `login`, `status`
-- **Batch operations**: pushing directories, scanning for un-added files
+- **Batch operations**: pushing directories, scanning for unadopted files
 
 The CLI handles metadata management, change detection, and file-to-record synchronization automatically.
 
@@ -182,6 +181,48 @@ RowID:del{id};entity:entityName=true            # Delete
 ```
 Always include `_confirm=true`. Special values: `_{now}` (datetime), `_{null}` (null).
 
+## Creating New Assets
+
+Two approaches — choose based on whether the file exists locally first or on the server first.
+
+### File-first (CLI)
+
+Use when you're creating a new file locally and want the server to create the record.
+
+```bash
+# 1. Write the file in the correct lib/ subdirectory
+# 2. Create the metadata companion (required before push)
+dbo adopt -e content lib/bins/app/my-file.html   # HTML/CSS/JS/SQL → content
+dbo adopt -e media lib/bins/app/assets/img/x.png # images/binaries → media
+
+# 3. Push — inserts a new record on the server, assigns a UID, updates local metadata
+dbo push lib/bins/app/my-file.html
+```
+
+Always pass `-e <entity>` to `adopt`. Entity cannot be inferred for standalone files in `lib/bins/` because the directory maps to multiple entity types.
+
+### Server-first (REST API)
+
+Use when you want to create the server record first, then pull the file locally. Required fields for the insert come from three local config files:
+
+- **`.app/<app_short_name>.metadata_schema.json`** — entity schema: which columns are required, their types and allowed values
+- **`.app/directories.json`** — BinID for the target directory (needed for bin-based entities like `content` and `media`)
+- **`.app/config.json`** — `AppID`, `AppUID`, and other app-level fields required on most records
+
+```bash
+# 1. Insert the record via REST API (RowID:add1 — must use RowID:, not RowUID:)
+curl -b .app/cookies.txt \
+  "https://{{domain}}/api/input/submit?_confirm=true" \
+  --data-urlencode 'RowID:add1;column:content.BinID=11042' \
+  --data-urlencode 'RowID:add1;column:content.AppID={{appID}}' \
+  --data-urlencode 'RowID:add1;column:content.Name=My File'
+
+# 2. Pull to create the local file and metadata companion
+dbo pull -e content --filter 'Name=My File'
+```
+
+After pull, the file appears in `lib/bins/` at the path matching its BinID in `directories.json`, with a `.metadata.json` companion.
+
 ## docs/ Directory
 
 Contains Markdown documentation for this project's components — scripts, embeds, pages, UI features. These are project-specific references generated or maintained alongside development. Read these to understand documented behaviors of the current app.
@@ -213,7 +254,7 @@ The `test/` directory is for developer and Claude Code test scripts. Tests targe
 | Write/update data | REST API | `POST /api/input/submit` |
 | Pull files from server | CLI | `dbo pull -e content` |
 | Push local changes | CLI | `dbo push path/to/file` |
-| Add new file to server | CLI | `dbo add path/to/file` |
+| Add new file to server | CLI | `dbo adopt path/to/file -e <entity>` |
 | Deploy by shorthand | CLI | `dbo deploy css:colors` |
 | Deploy by UID | CLI | `dbo deploy {uid}` |
 | Compare with server | CLI | `dbo diff` |

package/plugins/claude/dbo/skills/white-paper/references/api-reference.md

@@ -87,7 +87,7 @@ RowID:{ref};column:{entity}.{Column}={value}
 | `{id}` or `{uid}` | Update existing record |
 | `del{id}` | Delete record |
 
-`RowID:` and `RowUID:` are interchangeable. Use `RowUID:` for cross-environment stability.
+`RowID:` and `RowUID:` are interchangeable for updates and deletes. Use `RowUID:` for cross-environment stability. **Inserts (`add1`, `add2`, …) must use `RowID:` — `RowUID:` does not work for inserts.**
 
 ### Cross-referencing within a batch
 ```

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

@@ -1,6 +1,6 @@
 {
   "name": "track",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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"

package/src/commands/adopt.js

@@ -93,9 +93,10 @@ const ROOT_FILE_TEMPLATES = {
  */
 async function buildBinMetadata(filePath, entity, appConfig, structure) {
   const rel = relative(process.cwd(), filePath).replace(/\\/g, '/');
-  const ext = extname(filePath).replace('.', '').toLowerCase();
   const fileName = basename(filePath);
-  const base = basename(filePath, extname(filePath));
+  const ext = extname(filePath).replace('.', '').toLowerCase();
+  const rawBase = basename(filePath, extname(filePath));
+  const base = rawBase || fileName; // dotfiles (.dboignore): rawBase='' → use full filename
   const fileDir = dirname(rel);
   const bin = findBinByPath(fileDir, structure);
   const binPath = bin?.path || '';
@@ -103,9 +104,9 @@ async function buildBinMetadata(filePath, entity, appConfig, structure) {
   const metaPath = join(dirname(filePath), `${base}.metadata.json`);
 
   if (entity === 'content') {
-    const contentPath = binPath
-      ? `${binPath}/${base}.${ext}`
-      : `${base}.${ext}`;
+    // For dotfiles, base === fileName (no real ext), so path = base; otherwise base.ext
+    const localName = (base === fileName) ? fileName : `${base}.${ext}`;
+    const contentPath = binPath ? `${binPath}/${localName}` : localName;
     const meta = {
       _entity: 'content',
       _companionReferenceColumns: ['Content'],
@@ -159,13 +160,13 @@ async function adoptSingleFile(filePath, entityArg, options) {
   // These files live at the project root but their metadata goes in lib/bins/app/.
   // They bypass the dboignore check and entity inference.
   const rootFiles = await loadRootContentFiles();
-  if (rootFiles.includes(fileName) && relPath === fileName) {
+  if (rootFiles.some(f => f.toLowerCase() === fileName.toLowerCase()) && relPath === fileName) {
     const appConfig = await loadAppConfig();
     const structure = await loadStructureFile();
     const appBin = findBinByPath('app', structure);
     const binsAppDir = join(process.cwd(), BINS_DIR, 'app');
     const ext = extname(fileName).replace('.', '').toUpperCase() || 'TXT';
-    const stem = basename(fileName, extname(fileName));
+    const stem = fileName;
 
     const metaFilename = `${stem}.metadata.json`;
     const metaPath = join(binsAppDir, metaFilename);
@@ -174,22 +175,23 @@ async function adoptSingleFile(filePath, entityArg, options) {
     let existingMeta = null;
     try { existingMeta = JSON.parse(await readFile(metaPath, 'utf8')); } catch {}
     if (existingMeta) {
-      if (existingMeta.UID || existingMeta._CreatedOn) {
-        log.warn(`"${fileName}" is already on the server (has UID/_CreatedOn) — skipping.`);
+      if (existingMeta._CreatedOn || existingMeta._LastUpdated) {
+        log.warn(`"${fileName}" is already on the server (_CreatedOn/_LastUpdated present) — skipping.`);
         return;
       }
       if (!options.yes) {
         const inquirer = (await import('inquirer')).default;
         const { overwrite } = await inquirer.prompt([{
           type: 'confirm', name: 'overwrite',
-          message: `Metadata already exists for "${fileName}" (no UID). Overwrite?`,
+          message: `Metadata already exists for "${fileName}" (not yet on server). Overwrite?`,
           default: false,
         }]);
         if (!overwrite) return;
       }
     }
 
-    const tmpl = ROOT_FILE_TEMPLATES[fileName] || { Extension: ext, Public: 0, Active: 1, Title: fileName };
+    const tmplKey = Object.keys(ROOT_FILE_TEMPLATES).find(k => k.toLowerCase() === fileName.toLowerCase());
+    const tmpl = (tmplKey ? ROOT_FILE_TEMPLATES[tmplKey] : null) || { Extension: ext, Public: 0, Active: 1, Title: fileName };
     const meta = {
       _entity: 'content',
       _companionReferenceColumns: ['Content'],
@@ -214,8 +216,8 @@ async function adoptSingleFile(filePath, entityArg, options) {
   }
 
   const dir = dirname(filePath);
-  const ext = extname(filePath);
-  const base = basename(filePath, ext);
+  const rawBase = basename(filePath, extname(filePath));
+  const base = rawBase || basename(filePath); // dotfiles: '' → full filename
 
   // Check for existing metadata
   const metaPath = join(dir, `${base}.metadata.json`);
@@ -225,17 +227,17 @@ async function adoptSingleFile(filePath, entityArg, options) {
   } catch { /* no file — that's fine */ }
 
   if (existingMeta) {
-    if (existingMeta.UID || existingMeta._CreatedOn) {
-      log.warn(`"${fileName}" is already on the server (has UID/_CreatedOn) — skipping.`);
+    if (existingMeta._CreatedOn || existingMeta._LastUpdated) {
+      log.warn(`"${fileName}" is already on the server (_CreatedOn/_LastUpdated present) — skipping.`);
       return;
     }
-    // Metadata exists but no server record
+    // Metadata exists but record not yet on server
     if (!options.yes) {
       const inquirer = (await import('inquirer')).default;
       const { overwrite } = await inquirer.prompt([{
         type: 'confirm',
         name: 'overwrite',
-        message: `Metadata already exists for "${fileName}" (no UID). Overwrite?`,
+        message: `Metadata already exists for "${fileName}" (not yet on server). Overwrite?`,
         default: false,
       }]);
       if (!overwrite) return;
@@ -292,7 +294,7 @@ async function adoptSingleFile(filePath, entityArg, options) {
       Name: docBase,
     };
     if (appConfig.AppID) docMeta.AppID = appConfig.AppID;
-    const contentCol = 'String10';
+    const contentCol = 'Text';
     docMeta[contentCol] = `@/${relPath}`;
     docMeta._companionReferenceColumns = [contentCol];
 
@@ -354,7 +356,8 @@ async function adoptSingleFile(filePath, entityArg, options) {
 async function runInteractiveWizard(filePath, options) {
   const inquirer = (await import('inquirer')).default;
   const fileName = basename(filePath);
-  const base = basename(filePath, extname(filePath));
+  const rawBase = basename(filePath, extname(filePath));
+  const base = rawBase || fileName; // dotfiles: '' → full filename
   const metaPath = join(dirname(filePath), `${base}.metadata.json`);
 
   log.plain('');