@dboio/cli 0.16.2 → 0.19.0

package/src/lib/metadata-schema.js

@@ -1,10 +1,9 @@
 import { readFile, writeFile, readdir, access } from 'fs/promises';
 import { join, relative, basename, extname } from 'path';
 import { EXTENSION_DESCRIPTORS_DIR, ENTITY_DIR_NAMES } from './structure.js';
+import { metadataSchemaPath } from './config.js';
 import inquirer from 'inquirer';
 
-export const METADATA_SCHEMA_FILE = '.dbo/metadata_schema.json';
-
 const STATIC_DIRECTIVE_MAP = {
   docs: { entity: 'extension', descriptor: 'documentation' },
 };
@@ -67,33 +66,29 @@ export function resolveDirective(filePath) {
 }
 
 /**
- * Load metadata schema from .dbo/metadata_schema.json.
+ * Load metadata schema from .app/<shortName>.metadata_schema.json.
  */
 export async function loadMetadataSchema() {
   try {
-    const raw = await readFile(METADATA_SCHEMA_FILE, 'utf8');
-    try {
-      return JSON.parse(raw);
-    } catch {
-      console.warn('Warning: .dbo/metadata_schema.json is malformed JSON — falling back to generic wizard');
-      return null;
-    }
-  } catch (err) {
-    if (err.code === 'ENOENT') return {};
-    return {};
+    const path = await metadataSchemaPath();
+    const raw = await readFile(path, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
   }
 }
 
 /**
- * Save metadata schema to .dbo/metadata_schema.json.
+ * Save metadata schema to .app/<shortName>.metadata_schema.json.
  */
-export async function saveMetadataSchema(templates) {
-  await writeFile(METADATA_SCHEMA_FILE, JSON.stringify(templates, null, 2) + '\n');
+export async function saveMetadataSchema(data) {
+  const path = await metadataSchemaPath();
+  await writeFile(path, JSON.stringify(data, null, 2) + '\n');
 }
 
 /**
  * Merge extension descriptor definitions from dependency metadata_schema.json files.
- * For each dependency in .dbo/dependencies/<name>/, reads its .dbo/metadata_schema.json
+ * For each dependency in app_dependencies/<name>/, reads its .app/<name>.metadata_schema.json
  * and copies any extension descriptor entries that don't already exist locally.
  *
  * @param {Object} localSchema - The current project's metadata_schema object (mutated in place)
@@ -102,7 +97,7 @@ export async function saveMetadataSchema(templates) {
 export async function mergeDescriptorSchemaFromDependencies(localSchema) {
   if (!localSchema) return false;
 
-  const depsRoot = join('.dbo', 'dependencies');
+  const depsRoot = join(process.cwd(), 'app_dependencies');
   let depNames;
   try {
     depNames = await readdir(depsRoot);
@@ -113,7 +108,7 @@ export async function mergeDescriptorSchemaFromDependencies(localSchema) {
   let merged = false;
 
   for (const depName of depNames) {
-    const depSchemaPath = join(depsRoot, depName, '.dbo', 'metadata_schema.json');
+    const depSchemaPath = join(depsRoot, depName, '.app', `${depName}.metadata_schema.json`);
     let depSchema;
     try {
       depSchema = JSON.parse(await readFile(depSchemaPath, 'utf8'));
@@ -489,4 +484,3 @@ export function generateMetadataFromSchema(schema, existing = {}) {
 // Backward-compat re-exports
 export const loadMetadataTemplates = loadMetadataSchema;
 export const saveMetadataTemplates = saveMetadataSchema;
-export const METADATA_TEMPLATES_FILE = METADATA_SCHEMA_FILE;

package/src/lib/metadata-templates.js

@@ -3,7 +3,7 @@ import { relative, basename, extname } from 'path';
 import { EXTENSION_DESCRIPTORS_DIR, ENTITY_DIR_NAMES } from './structure.js';
 import inquirer from 'inquirer';
 
-const METADATA_TEMPLATES_FILE = '.dbo/metadata_templates.json';
+const METADATA_TEMPLATES_FILE = '.app/metadata_templates.json';
 
 const STATIC_DIRECTIVE_MAP = {
   docs: { entity: 'extension', descriptor: 'documentation' },
@@ -67,7 +67,7 @@ export function resolveDirective(filePath) {
 }
 
 /**
- * Load metadata templates from .dbo/metadata_templates.json.
+ * Load metadata templates from .app/metadata_templates.json.
  */
 export async function loadMetadataTemplates() {
   try {
@@ -75,7 +75,7 @@ export async function loadMetadataTemplates() {
     try {
       return JSON.parse(raw);
     } catch {
-      console.warn('Warning: .dbo/metadata_templates.json is malformed JSON — falling back to generic wizard');
+      console.warn('Warning: .app/metadata_templates.json is malformed JSON — falling back to generic wizard');
       return null;
     }
   } catch (err) {
@@ -85,7 +85,7 @@ export async function loadMetadataTemplates() {
 }
 
 /**
- * Save metadata templates to .dbo/metadata_templates.json.
+ * Save metadata templates to .app/metadata_templates.json.
  */
 export async function saveMetadataTemplates(templates) {
   await writeFile(METADATA_TEMPLATES_FILE, JSON.stringify(templates, null, 2) + '\n');

package/src/lib/migrations.js

@@ -17,7 +17,7 @@ export async function runPendingMigrations(options = {}) {
   // --no-migrate suppresses for this invocation
   if (options.migrate === false) return;
 
-  // No .dbo/ project in this directory — nothing to migrate
+  // No .app/ project in this directory — nothing to migrate
   if (!(await isInitialized())) return;
 
   // Discover migration files

package/src/lib/modify-key.js

@@ -104,6 +104,6 @@ export async function handleModifyKeyError() {
   }
 
   await saveAppModifyKey(key);
-  log.info('  ModifyKey saved to .dbo/config.json for future use.');
+  log.info('  ModifyKey saved to .app/config.json for future use.');
   return { modifyKey: key, cancel: false };
 }

package/src/lib/scaffold.js

@@ -3,6 +3,7 @@ import { join } from 'path';
 import { SCAFFOLD_DIRS } from './structure.js';
 import { log } from './logger.js';
 import { applyTrashIcon } from './tagging.js';
+import { appMetadataPath } from './config.js';
 
 /**
  * Scaffold the standard DBO project directory structure in cwd.
@@ -37,21 +38,12 @@ export async function scaffoldProjectDirs(cwd = process.cwd()) {
   // Best-effort: apply trash icon to the trash directory
   await applyTrashIcon(join(cwd, 'trash'));
 
-  // Create app.json if absent
-  const appJsonPath = join(cwd, 'app.json');
-  try {
-    await access(appJsonPath);
-  } catch {
-    await writeFile(appJsonPath, '{}\n');
-    created.push('app.json');
-  }
-
   // Create manifest.json if absent
   const manifestPath = join(cwd, 'manifest.json');
   try {
     await access(manifestPath);
   } catch {
-    // Try to resolve values from local app.json; fall back to empty strings
+    // Try to resolve values from app metadata file; fall back to empty strings
     let appName = '';
     let shortName = '';
     let description = '';
@@ -59,7 +51,8 @@ export async function scaffoldProjectDirs(cwd = process.cwd()) {
     let domain = '';
 
     try {
-      const appData = JSON.parse(await readFile(appJsonPath, 'utf8'));
+      const appMetaPath = await appMetadataPath();
+      const appData = JSON.parse(await readFile(appMetaPath, 'utf8'));
       appName = appData.Name || '';
       shortName = appData.ShortName || '';
       description = appData.Description || '';
@@ -74,7 +67,7 @@ export async function scaffoldProjectDirs(cwd = process.cwd()) {
           }
         }
       }
-    } catch { /* app.json missing or unparseable — use empty defaults */ }
+    } catch { /* metadata file missing or unparseable — use empty defaults */ }
 
     const manifest = {
       name: `${appName} | ${domain}`,

package/src/lib/schema.js

@@ -1,53 +1,83 @@
-import { readFile, writeFile } from 'fs/promises';
-import { DboClient } from './client.js';
+import { readFile } from 'fs/promises';
+import { join, sep } from 'path';
 
-export const SCHEMA_FILE = 'schema.json';
-const SCHEMA_API_PATH = '/api/app/object/_system';
+const SYSTEM_BASELINE_PATH = join('app_dependencies', '_system', '.app', '_system.json');
 
-/** Fetch schema from /api/app/object/_system. Returns parsed JSON or throws. */
-export async function fetchSchema(options = {}) {
-  const client = new DboClient({ domain: options.domain, verbose: options.verbose });
-  const result = await client.get(SCHEMA_API_PATH);
-  if (!result.ok || !result.data) throw new Error(`Schema fetch failed: HTTP ${result.status}`);
-  return result.data;
+/**
+ * Kept for call-site compatibility with commands that pass systemSchemaPath.
+ * Points to the _system dependency baseline location.
+ */
+export const SCHEMA_FILE = SYSTEM_BASELINE_PATH;
+
+/**
+ * Load schema from the _system dependency baseline.
+ * When inside a dependency checkout (app_dependencies/<dep>/), traverses up
+ * to the parent project's _system baseline.
+ * Returns parsed object or null if the dependency hasn't been cloned yet.
+ */
+export async function loadSchema() {
+  // Try local path first (works for top-level projects)
+  try {
+    return JSON.parse(await readFile(SYSTEM_BASELINE_PATH, 'utf8'));
+  } catch { /* not found locally */ }
+
+  // If inside a dependency checkout, try parent project's schema
+  const cwd = process.cwd();
+  const marker = `${sep}app_dependencies${sep}`;
+  const depIdx = cwd.indexOf(marker);
+  if (depIdx >= 0) {
+    const parentRoot = cwd.substring(0, depIdx);
+    const parentSchemaPath = join(parentRoot, SYSTEM_BASELINE_PATH);
+    try {
+      return JSON.parse(await readFile(parentSchemaPath, 'utf8'));
+    } catch { /* parent schema not available either */ }
+  }
+
+  return null;
 }
 
 /**
- * Fetch only the _LastUpdated timestamp from the schema endpoint.
- * Uses the column-filter syntax: /api/app/object/_system[_LastUpdated]
- * Returns ISO date string or null on failure.
+ * saveSchema() is now a no-op — schema is managed by the _system dependency clone.
+ * Kept for call-site compatibility.
  */
-export async function fetchSchemaLastUpdated(options = {}) {
-  const client = new DboClient({ domain: options.domain, verbose: options.verbose });
-  const result = await client.get(`${SCHEMA_API_PATH}[_LastUpdated]`);
-  if (!result.ok || !result.data) return null;
-  return result.data._LastUpdated || null;
+export async function saveSchema(_data) {
+  // no-op
 }
 
 /**
- * Check whether the server schema is newer than the local schema.json.
- * Returns true if the server _LastUpdated is more recent (or local is missing).
+ * Check whether the _system dependency needs refreshing.
+ * Delegates to checkDependencyStaleness('_system').
  */
 export async function isSchemaStale(options = {}) {
-  const local = await loadSchema();
-  if (!local || !local._LastUpdated) return true;
-
-  const serverTs = await fetchSchemaLastUpdated(options);
-  if (!serverTs) return false; // can't determine — assume not stale
-
-  return new Date(serverTs) > new Date(local._LastUpdated);
+  const { checkDependencyStaleness } = await import('./dependencies.js');
+  return checkDependencyStaleness('_system', options);
 }
 
-/** Load schema.json from project root. Returns parsed object or null if missing. */
-export async function loadSchema() {
-  try {
-    return JSON.parse(await readFile(SCHEMA_FILE, 'utf8'));
-  } catch {
-    return null;
+/**
+ * "Fetch" schema by forcing a re-clone of the _system dependency.
+ * When inside a dependency checkout, falls back to direct API fetch
+ * (syncDependencies would skip due to the self-detection guard).
+ * Returns the freshly loaded schema after sync completes.
+ */
+export async function fetchSchema(options = {}) {
+  const cwd = process.cwd();
+  if (cwd.includes(`${sep}app_dependencies${sep}`)) {
+    // Inside a dependency checkout — can't sync _system here.
+    // Try parent's schema first (already cloned by parent).
+    const existing = await loadSchema();
+    if (existing) return existing;
+
+    // Fallback: fetch directly from API (old behavior)
+    const { DboClient } = await import('./client.js');
+    const { loadConfig } = await import('./config.js');
+    const config = await loadConfig();
+    const domain = options.domain || config.domain;
+    const client = new DboClient({ domain, verbose: options.verbose });
+    const resp = await client.get('/api/app/object/_system');
+    return resp?.data || resp;
   }
-}
 
-/** Write schema.json to project root. */
-export async function saveSchema(data) {
-  await writeFile(SCHEMA_FILE, JSON.stringify(data, null, 2) + '\n');
+  const { syncDependencies } = await import('./dependencies.js');
+  await syncDependencies({ ...options, only: ['_system'], force: true });
+  return loadSchema();
 }

package/src/lib/structure.js

@@ -1,7 +1,7 @@
 import { readFile, writeFile, mkdir } from 'fs/promises';
 import { join } from 'path';
 
-const STRUCTURE_FILE = '.dbo/structure.json';
+const STRUCTURE_FILE = '.app/directories.json';
 
 /** All server-managed directories live under this subdirectory */
 export const LIB_DIR = 'lib';
@@ -271,15 +271,15 @@ export async function createDirectories(structure) {
 }
 
 /**
- * Save the bin structure to .dbo/structure.json.
+ * Save the bin structure to .app/directories.json.
  */
 export async function saveStructureFile(structure) {
-  await mkdir('.dbo', { recursive: true });
+  await mkdir('.app', { recursive: true });
   await writeFile(STRUCTURE_FILE, JSON.stringify(structure, null, 2) + '\n');
 }
 
 /**
- * Load bin structure from .dbo/structure.json.
+ * Load bin structure from .app/directories.json.
  */
 export async function loadStructureFile() {
   try {
@@ -389,7 +389,7 @@ export function resolveFieldValue(value) {
 }
 
 /**
- * Persist descriptorMapping and extensionDescriptorDirs into .dbo/structure.json.
+ * Persist descriptorMapping and extensionDescriptorDirs into .app/directories.json.
  * Extends the existing structure object (already contains bin entries).
  *
  * @param {Object} structure  - Current structure from loadStructureFile()
@@ -411,7 +411,7 @@ export async function saveDescriptorMapping(structure, mapping) {
 }
 
 /**
- * Load descriptorMapping from .dbo/structure.json.
+ * Load descriptorMapping from .app/directories.json.
  * Returns {} if not yet persisted.
  */
 export async function loadDescriptorMapping() {

package/src/lib/tagging.js

@@ -149,13 +149,13 @@ async function _findUntrackedFiles(dir, ig, knownMetaPaths) {
   return all.filter(fp => !knownCompanions.has(fp));
 }
 
-// Recursively collect non-metadata, non-hidden, non-.dbo content files
+// Recursively collect non-metadata, non-hidden, non-.app content files
 async function _collectContentFiles(dir, ig) {
   const results = [];
   let entries;
   try { entries = await readdir(dir, { withFileTypes: true }); } catch { return []; }
   for (const entry of entries) {
-    if (entry.name.startsWith('.')) continue; // skip hidden and .dbo
+    if (entry.name.startsWith('.')) continue; // skip hidden and .app
     const fullPath = join(dir, entry.name);
     const relPath = relative(process.cwd(), fullPath).replace(/\\/g, '/');
     if (entry.isDirectory()) {

package/src/lib/ticketing.js

@@ -1,16 +1,12 @@
 import { readFile, writeFile, mkdir } from 'fs/promises';
 import { join } from 'path';
 import { log } from './logger.js';
+import { projectDir } from './config.js';
 
-const DBO_DIR = '.dbo';
 const TICKETING_FILE = 'ticketing.local.json';
 
-function dboDir() {
-  return join(process.cwd(), DBO_DIR);
-}
-
 function ticketingPath() {
-  return join(dboDir(), TICKETING_FILE);
+  return join(projectDir(), TICKETING_FILE);
 }
 
 const DEFAULT_TICKETING = { ticket_id: null, ticketing_required: false, ticket_confirmed: false, records: [] };
@@ -48,7 +44,7 @@ export async function loadTicketing() {
  * Save ticketing.local.json.
  */
 export async function saveTicketing(data) {
-  await mkdir(dboDir(), { recursive: true });
+  await mkdir(projectDir(), { recursive: true });
   await writeFile(ticketingPath(), JSON.stringify(data, null, 2) + '\n');
 }
 

package/src/lib/toe-stepping.js

@@ -87,8 +87,8 @@ export async function fetchServerRecords(client, requests) {
  * makes a single HTTP request and the server only returns records modified
  * after the given date.
  *
- * The response is used ONLY for comparison — it must NOT replace app.json or
- * app_baseline.json.
+ * The response is used ONLY for comparison — it must NOT replace the metadata
+ * or baseline files.
  *
  * @param {DboClient} client
  * @param {string} appShortName - App short name for the /api/app/object/ endpoint
@@ -181,7 +181,7 @@ function decodeServerValue(value) {
  * a newer server edit, and _LastUpdatedUserID identifies who made the change.
  *
  * @param {Object} serverEntry    - Record from per-record server fetch
- * @param {Object} baselineEntry  - Record from .app_baseline.json
+ * @param {Object} baselineEntry  - Record from the baseline file
  * @param {Object} localMeta      - Local .metadata.json object
  * @param {string} metaDir        - Absolute directory of the metadata file
  * @returns {Promise<Array<{ col: string, serverValue: string, localValue: string, baselineValue: string }>>}
@@ -278,12 +278,12 @@ function findOldestBaselineDate(records, baseline) {
  * unavailable or returns no data.
  *
  * The bulk response is used ONLY for comparison — it does NOT replace
- * app.json or app_baseline.json.
+ * the metadata or baseline files.
  *
  * @param {Array<{ meta: Object, metaPath: string }>} records
  *   Records about to be pushed. Each must have meta.UID, meta._entity.
  * @param {DboClient} client
- * @param {Object} baseline - Loaded baseline from .dbo/.app_baseline.json
+ * @param {Object} baseline - Loaded baseline from .app/<shortName>.json (baseline)
  * @param {Object} options  - Commander options (options.yes used for auto-accept)
  * @param {string} [appShortName] - App short name for bulk fetch (optional)
  * @param {string} [serverTz] - Server timezone from config (e.g. "America/Chicago")

package/src/lib/transaction-key.js

@@ -41,6 +41,6 @@ export async function resolveTransactionKey(options = {}) {
   }]);
 
   await saveTransactionKeyPreset(preset);
-  log.dim(`  Saved TransactionKeyPreset: ${preset} to .dbo/config.json`);
+  log.dim(`  Saved TransactionKeyPreset: ${preset} to .app/config.json`);
   return preset;
 }

package/src/migrations/004-rename-output-files.js

@@ -73,10 +73,10 @@ async function rewriteReferences(filePath) {
 
 /**
  * Recursively find directories that contain _output~ files.
- * Skips .dbo/, node_modules/, trash/, .git/.
+ * Skips .app/, node_modules/, trash/, .git/.
  */
 async function findDirsWithOutputFiles(root) {
-  const SKIP = new Set(['.dbo', 'node_modules', 'trash', '.git', '.claude']);
+  const SKIP = new Set(['.app', 'node_modules', 'trash', '.git', '.claude', 'app_dependencies']);
   const results = [];
 
   async function walk(dir) {

package/src/migrations/005-rename-output-metadata.js

@@ -57,10 +57,10 @@ export default async function run(_options) {
 
 /**
  * Recursively find directories that contain output .json files (with ~ in name).
- * Skips .dbo/, node_modules/, trash/, .git/.
+ * Skips .app/, node_modules/, trash/, .git/.
  */
 async function findDirsWithOutputJsonFiles(root) {
-  const SKIP = new Set(['.dbo', 'node_modules', 'trash', '.git', '.claude']);
+  const SKIP = new Set(['.app', 'node_modules', 'trash', '.git', '.claude', 'app_dependencies']);
   const results = [];
 
   async function walk(dir) {

package/src/migrations/006-remove-uid-companion-filenames.js

@@ -161,7 +161,7 @@ export default async function run(_options) {
   }
 }
 
-const SKIP = new Set(['.dbo', 'node_modules', 'trash', '.git', '.claude']);
+const SKIP = new Set(['.app', 'node_modules', 'trash', '.git', '.claude', 'app_dependencies']);
 
 async function findAllMetadataFiles(dir) {
   const results = [];

package/src/migrations/007-natural-entity-companion-filenames.js

@@ -127,7 +127,7 @@ const ENTITY_DIRS = new Set([
   'data_source', 'group', 'site', 'redirect',
 ]);
 
-const SKIP = new Set(['.dbo', 'node_modules', 'trash', '.git', '.claude']);
+const SKIP = new Set(['.app', 'node_modules', 'trash', '.git', '.claude', 'app_dependencies']);
 
 /**
  * Find all .metadata.json files inside entity directories (lib/<entity>/).

package/src/migrations/008-metadata-uid-in-suffix.js

@@ -50,7 +50,7 @@ export default async function run(_options) {
   }
 }
 
-const SKIP = new Set(['.dbo', 'node_modules', 'trash', '.git', '.claude']);
+const SKIP = new Set(['.app', 'node_modules', 'trash', '.git', '.claude', 'app_dependencies']);
 
 async function findAllLegacyMetadataFiles(dir) {
   const results = [];

package/src/migrations/009-fix-media-collision-metadata-names.js

@@ -141,7 +141,7 @@ export default async function run(_options) {
   }
 }
 
-const SKIP = new Set(['.dbo', 'node_modules', 'trash', '.git', '.claude']);
+const SKIP = new Set(['.app', 'node_modules', 'trash', '.git', '.claude', 'app_dependencies']);
 
 async function findAllMetadataFiles(dir) {
   const results = [];

package/src/migrations/010-delete-paren-media-orphans.js

@@ -41,7 +41,7 @@ export default async function run(_options) {
   }
 }
 
-const SKIP = new Set(['.dbo', 'node_modules', 'trash', '.git', '.claude']);
+const SKIP = new Set(['.app', 'node_modules', 'trash', '.git', '.claude', 'app_dependencies']);
 
 async function findParenMediaFiles(dir) {
   const results = [];