@dboio/cli 0.4.1

package/bin/dbo.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { initCommand } from '../src/commands/init.js';
+import { loginCommand } from '../src/commands/login.js';
+import { logoutCommand } from '../src/commands/logout.js';
+import { statusCommand } from '../src/commands/status.js';
+import { inputCommand } from '../src/commands/input.js';
+import { outputCommand } from '../src/commands/output.js';
+import { contentCommand } from '../src/commands/content.js';
+import { mediaCommand } from '../src/commands/media.js';
+import { uploadCommand } from '../src/commands/upload.js';
+import { messageCommand } from '../src/commands/message.js';
+import { cacheCommand } from '../src/commands/cache.js';
+import { instanceCommand } from '../src/commands/instance.js';
+import { deployCommand } from '../src/commands/deploy.js';
+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';
+
+const program = new Command();
+
+program
+  .name('dbo')
+  .description('CLI for the DBO.io framework')
+  .version('0.4.1');
+
+program.addCommand(initCommand);
+program.addCommand(loginCommand);
+program.addCommand(logoutCommand);
+program.addCommand(statusCommand);
+program.addCommand(inputCommand);
+program.addCommand(outputCommand);
+program.addCommand(contentCommand);
+program.addCommand(mediaCommand);
+program.addCommand(uploadCommand);
+program.addCommand(messageCommand);
+program.addCommand(cacheCommand);
+program.addCommand(instanceCommand);
+program.addCommand(deployCommand);
+program.addCommand(pushCommand);
+program.addCommand(pullCommand);
+program.addCommand(addCommand);
+program.addCommand(installCommand);
+program.addCommand(updateCommand);
+program.addCommand(cloneCommand);
+
+program.parse();

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@dboio/cli",
+  "version": "0.4.1",
+  "description": "CLI for the DBO.io framework",
+  "type": "module",
+  "bin": {
+    "dbo": "./bin/dbo.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test src/**/*.test.js"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0",
+    "inquirer": "^9.3.0"
+  },
+  "keywords": ["dbo", "dboio", "database", "cli", "api"],
+  "license": "UNLICENSED"
+}

package/src/commands/add.js

@@ -0,0 +1,374 @@
+import { Command } from 'commander';
+import { readFile, readdir, stat, writeFile } from 'fs/promises';
+import { join, dirname, basename, extname, relative } from 'path';
+import { DboClient } from '../lib/client.js';
+import { buildInputBody, checkSubmitErrors } from '../lib/input-parser.js';
+import { formatResponse, formatError } from '../lib/formatter.js';
+import { log } from '../lib/logger.js';
+import { shouldSkipColumn } from '../lib/columns.js';
+import { loadAppConfig } from '../lib/config.js';
+
+// Directories and patterns to skip when scanning with `dbo add .`
+const IGNORE_DIRS = new Set(['.dbo', '.git', 'node_modules', '.svn', '.hg']);
+
+export const addCommand = new Command('add')
+  .description('Add a new file to DBO.io (creates record on server)')
+  .argument('<path>', 'File or "." to scan current directory')
+  .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
+  .option('--ticket <id>', 'Override ticket ID')
+  .option('-y, --yes', 'Auto-accept all prompts')
+  .option('--json', 'Output raw JSON')
+  .option('--jq <expr>', 'Filter JSON response')
+  .option('-v, --verbose', 'Show HTTP request details')
+  .option('--domain <host>', 'Override domain')
+  .action(async (targetPath, options) => {
+    try {
+      const client = new DboClient({ domain: options.domain, verbose: options.verbose });
+
+      if (targetPath === '.') {
+        await addDirectory(process.cwd(), client, options);
+      } else {
+        const pathStat = await stat(targetPath);
+        if (pathStat.isDirectory()) {
+          await addDirectory(targetPath, client, options);
+        } else {
+          await addSingleFile(targetPath, client, options);
+        }
+      }
+    } catch (err) {
+      formatError(err);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Add a single file to DBO.io.
+ * Returns the defaults used (entity, contentColumn) for batch reuse.
+ */
+async function addSingleFile(filePath, client, options, batchDefaults) {
+  const dir = dirname(filePath);
+  const ext = extname(filePath);
+  const base = basename(filePath, ext);
+  const fileName = basename(filePath);
+  const metaPath = join(dir, `${base}.metadata.json`);
+
+  // Step 1: Check for existing metadata
+  let meta = null;
+  try {
+    const raw = await readFile(metaPath, 'utf8');
+    if (raw.trim()) {
+      meta = JSON.parse(raw);
+    }
+  } catch {
+    // No metadata file — that's fine, we'll create one
+  }
+
+  // Step 2: If metadata exists with _CreatedOn, already on server
+  if (meta && meta._CreatedOn) {
+    log.warn(`"${fileName}" is already on the server (has _CreatedOn). Use "dbo push" to update.`);
+    return null;
+  }
+
+  // Step 3: If metadata exists without _CreatedOn, use it for insert
+  if (meta && meta._entity) {
+    log.info(`Found metadata for "${fileName}" — proceeding with insert`);
+    return await submitAdd(meta, metaPath, filePath, client, options);
+  }
+
+  // Step 4: No usable metadata — interactive wizard
+  const inquirer = (await import('inquirer')).default;
+
+  log.plain('');
+  log.warn(`I cannot add "${fileName}" to the server, because I don't have any metadata.`);
+  log.plain(`I have a few things that I need, and I can set that up for you,`);
+  log.plain(`or you manually add "${base}.metadata.json" next to the file.`);
+  log.plain('');
+
+  if (!options.yes) {
+    const { proceed } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'proceed',
+      message: 'Want me to set that up for you?',
+      default: true,
+    }]);
+
+    if (!proceed) {
+      log.dim(`Skipping "${fileName}". Create "${base}.metadata.json" manually and try again.`);
+      return null;
+    }
+  }
+
+  // Prompt for required fields (reuse batch defaults if available)
+  // Check if config has AppID for smart default
+  const appConfig = await loadAppConfig();
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'entity',
+      message: 'Entity name (e.g. content, template, style):',
+      default: batchDefaults?.entity || 'content',
+      validate: v => v.trim() ? true : 'Entity is required',
+    },
+    {
+      type: 'input',
+      name: 'contentColumn',
+      message: 'Column name for the file content (e.g. Content, Body, Template):',
+      default: batchDefaults?.contentColumn || 'Content',
+      validate: v => v.trim() ? true : 'Column name is required',
+    },
+    {
+      type: 'input',
+      name: 'BinID',
+      message: 'BinID (optional, press Enter to skip):',
+      default: batchDefaults?.BinID || '',
+    },
+    {
+      type: 'input',
+      name: 'SiteID',
+      message: 'SiteID (optional, press Enter to skip):',
+      default: batchDefaults?.SiteID || '',
+    },
+    {
+      type: 'input',
+      name: 'Path',
+      message: 'Path (optional, press Enter for auto-generated):',
+      default: batchDefaults?.Path || relative(process.cwd(), filePath).replace(/\\/g, '/'),
+    },
+  ]);
+
+  // AppID: smart prompt when config has app info
+  if (batchDefaults?.AppID) {
+    answers.AppID = batchDefaults.AppID;
+  } else if (appConfig.AppID) {
+    const { appIdChoice } = await inquirer.prompt([{
+      type: 'list',
+      name: 'appIdChoice',
+      message: `You're submitting data without an AppID, but your config has information about the current App. Do you want me to add that Column information along with your submission?`,
+      choices: [
+        { name: `Yes, use AppID ${appConfig.AppID}`, value: 'use_config' },
+        { name: 'No', value: 'none' },
+        { name: 'Enter custom AppID', value: 'custom' },
+      ],
+    }]);
+    if (appIdChoice === 'use_config') {
+      answers.AppID = String(appConfig.AppID);
+    } else if (appIdChoice === 'custom') {
+      const { customAppId } = await inquirer.prompt([{
+        type: 'input', name: 'customAppId',
+        message: 'Custom AppID:',
+      }]);
+      answers.AppID = customAppId;
+    } else {
+      answers.AppID = '';
+    }
+  } else {
+    const { appId } = await inquirer.prompt([{
+      type: 'input', name: 'appId',
+      message: 'AppID (optional, press Enter to skip):',
+      default: '',
+    }]);
+    answers.AppID = appId;
+  }
+
+  // Build metadata object
+  meta = {};
+  if (answers.AppID.trim()) meta.AppID = isFinite(answers.AppID) ? Number(answers.AppID) : answers.AppID;
+  if (answers.BinID.trim()) meta.BinID = isFinite(answers.BinID) ? Number(answers.BinID) : answers.BinID;
+  if (answers.SiteID.trim()) meta.SiteID = isFinite(answers.SiteID) ? Number(answers.SiteID) : answers.SiteID;
+  meta.Name = base;
+  if (answers.Path.trim()) meta.Path = answers.Path.trim();
+  meta[answers.contentColumn.trim()] = `@${fileName}`;
+  meta._entity = answers.entity.trim();
+  meta._contentColumns = [answers.contentColumn.trim()];
+
+  // Write metadata file
+  await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+  log.success(`Created ${basename(metaPath)}`);
+
+  // Submit the insert
+  const defaults = {
+    entity: answers.entity.trim(),
+    contentColumn: answers.contentColumn.trim(),
+    AppID: answers.AppID,
+    BinID: answers.BinID,
+    SiteID: answers.SiteID,
+    Path: answers.Path,
+  };
+
+  await submitAdd(meta, metaPath, filePath, client, options);
+  return defaults;
+}
+
+/**
+ * Submit an insert to the server from a metadata object.
+ */
+async function submitAdd(meta, metaPath, filePath, client, options) {
+  const entity = meta._entity;
+  const contentCols = new Set(meta._contentColumns || []);
+  const metaDir = dirname(metaPath);
+
+  if (!entity) {
+    throw new Error(`No _entity found in ${metaPath}`);
+  }
+
+  const dataExprs = [];
+  let addIndex = 1;
+
+  for (const [key, value] of Object.entries(meta)) {
+    if (shouldSkipColumn(key)) continue;
+    if (key === 'UID') continue; // Never submit UID on add — server assigns it
+    if (value === null || value === undefined) continue;
+
+    const strValue = String(value);
+
+    if (strValue.startsWith('@')) {
+      // @filename reference — resolve to actual file path
+      const refFile = strValue.substring(1);
+      const refPath = join(metaDir, refFile);
+      dataExprs.push(`RowID:add${addIndex};column:${entity}.${key}@${refPath}`);
+    } else {
+      dataExprs.push(`RowID:add${addIndex};column:${entity}.${key}=${strValue}`);
+    }
+  }
+
+  if (dataExprs.length === 0) {
+    log.warn(`Nothing to submit for ${basename(metaPath)}`);
+    return null;
+  }
+
+  log.info(`Adding ${basename(filePath)} (${entity}) — ${dataExprs.length} field(s)`);
+
+  const extraParams = { '_confirm': options.confirm };
+  if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
+
+  let body = await buildInputBody(dataExprs, extraParams);
+  let result = await client.postUrlEncoded('/api/input/submit', body);
+
+  // Retry with prompted params if needed (ticket, user)
+  const retryParams = await checkSubmitErrors(result);
+  if (retryParams) {
+    Object.assign(extraParams, retryParams);
+    body = await buildInputBody(dataExprs, extraParams);
+    result = await client.postUrlEncoded('/api/input/submit', body);
+  }
+
+  formatResponse(result, { json: options.json, jq: options.jq });
+
+  if (!result.successful) {
+    throw new Error('Add failed');
+  }
+
+  // Extract UID from response and update metadata
+  const addResults = result.payload?.Results?.Add || result.data?.Payload?.Results?.Add || [];
+  if (addResults.length > 0) {
+    const returnedUID = addResults[0].UID;
+    if (returnedUID) {
+      meta.UID = returnedUID;
+      await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+      log.success(`UID assigned: ${returnedUID}`);
+      log.dim(`  Run "dbo pull -e ${entity} ${returnedUID}" to populate all columns`);
+    }
+  }
+
+  return { entity: meta._entity };
+}
+
+/**
+ * Scan a directory for un-added files and add them.
+ */
+async function addDirectory(dirPath, client, options) {
+  const unadded = await findUnaddedFiles(dirPath);
+
+  if (unadded.length === 0) {
+    log.info('No un-added files found.');
+    return;
+  }
+
+  log.info(`Found ${unadded.length} file(s) to add:`);
+  for (const f of unadded) {
+    log.plain(`  ${relative(process.cwd(), f)}`);
+  }
+  log.plain('');
+
+  if (!options.yes) {
+    const inquirer = (await import('inquirer')).default;
+    const { proceed } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'proceed',
+      message: `Add ${unadded.length} file(s)?`,
+      default: true,
+    }]);
+    if (!proceed) return;
+  }
+
+  let succeeded = 0;
+  let failed = 0;
+  let batchDefaults = null;
+
+  for (const filePath of unadded) {
+    try {
+      const result = await addSingleFile(filePath, client, options, batchDefaults);
+      if (result) {
+        batchDefaults = result;
+        succeeded++;
+      }
+    } catch (err) {
+      log.error(`Failed: ${relative(process.cwd(), filePath)} — ${err.message}`);
+      failed++;
+    }
+  }
+
+  log.info(`Add complete: ${succeeded} succeeded, ${failed} failed`);
+}
+
+/**
+ * Recursively find files that are not yet added to the server.
+ * A file is "un-added" if:
+ *   - It has no companion .metadata.json, OR
+ *   - Its .metadata.json exists but has no _CreatedOn (never been on server)
+ */
+async function findUnaddedFiles(dir) {
+  const results = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (IGNORE_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
+      results.push(...await findUnaddedFiles(fullPath));
+      continue;
+    }
+
+    // Skip metadata files themselves
+    if (entry.name.endsWith('.metadata.json')) continue;
+    // Skip dotfiles
+    if (entry.name.startsWith('.')) continue;
+
+    // Check for companion metadata
+    const ext = extname(entry.name);
+    const base = basename(entry.name, ext);
+    const metaPath = join(dir, `${base}.metadata.json`);
+
+    let hasMetadata = false;
+    let isOnServer = false;
+
+    try {
+      const raw = await readFile(metaPath, 'utf8');
+      if (raw.trim()) {
+        const meta = JSON.parse(raw);
+        hasMetadata = true;
+        isOnServer = !!meta._CreatedOn;
+      }
+    } catch {
+      // No metadata file
+    }
+
+    if (!isOnServer) {
+      results.push(fullPath);
+    }
+  }
+
+  return results;
+}

package/src/commands/cache.js

@@ -0,0 +1,49 @@
+import { Command } from 'commander';
+import { DboClient } from '../lib/client.js';
+import { formatResponse, formatError } from '../lib/formatter.js';
+
+export const cacheCommand = new Command('cache')
+  .description('Manage DBO.io cache');
+
+cacheCommand
+  .command('list')
+  .description('List cached items')
+  .option('--metadata', 'Include cache metadata')
+  .option('--json', 'Output raw JSON')
+  .option('--jq <expr>', 'Filter JSON response with jq-like expression')
+  .option('-v, --verbose', 'Show HTTP request details')
+  .option('--domain <host>', 'Override domain')
+  .action(async (options) => {
+    try {
+      const client = new DboClient({ domain: options.domain, verbose: options.verbose });
+      const params = {};
+      if (options.metadata) params['_metadata'] = 'true';
+      const result = await client.get('/api/cache/list', params);
+      formatResponse(result, { json: options.json, jq: options.jq });
+    } catch (err) {
+      formatError(err);
+      process.exit(1);
+    }
+  });
+
+cacheCommand
+  .command('refresh')
+  .description('Refresh a cache entry by key')
+  .requiredOption('--key <value>', 'Cache key to refresh')
+  .option('--part <value>', 'Cache partition')
+  .option('--json', 'Output raw JSON')
+  .option('--jq <expr>', 'Filter JSON response with jq-like expression')
+  .option('-v, --verbose', 'Show HTTP request details')
+  .option('--domain <host>', 'Override domain')
+  .action(async (options) => {
+    try {
+      const client = new DboClient({ domain: options.domain, verbose: options.verbose });
+      const params = { '_key': options.key };
+      if (options.part) params['_part'] = options.part;
+      const result = await client.get('/api/cache/refresh', params);
+      formatResponse(result, { json: options.json, jq: options.jq });
+    } catch (err) {
+      formatError(err);
+      process.exit(1);
+    }
+  });