mdboard 1.3.0 → 2.1.0

package/src/core/config.js

@@ -1,19 +1,28 @@
 /**
- * mdboard — Configuration loader
+ * mdboard — Configuration Engine
+ *
+ * Loads and resolves the 6 configuration files (entities, structure, cli, api, ui, docs).
+ * Provides the public API that the rest of the system consumes.
  *
  * Resolution order (highest priority first):
  *   1. Explicit path via --config / MDBOARD_CONFIG
- *   2. <projectDir>/project/mdboard.json  (per-project)
- *   3. <projectDir>/mdboard.json          (workspace)
- *   4. ~/.config/mdboard/mdboard.json     (global)
- *   5. defaults.json                      (built-in)
+ *   2. <projectDir>/project/<file>.json  (per-project overrides)
+ *   3. preset directory (built-in)
+ *
+ * The preset is determined by entities.json methodology field, defaulting to "shape-up".
  */
 
+'use strict';
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-const defaults = require('../../defaults.json');
+const PRESETS_DIR = path.join(__dirname, '..', '..', 'presets');
+const CONFIG_FILES = ['entities', 'structure', 'cli', 'api', 'ui', 'docs'];
+const DEFAULT_PRESET = 'shape-up';
+
+// --- Utilities ---
 
 function deepMerge(target, source) {
   const result = { ...target };
@@ -31,68 +40,512 @@ function deepMerge(target, source) {
 
 function tryReadJson(filePath) {
   try {
-    const raw = fs.readFileSync(filePath, 'utf-8');
-    return JSON.parse(raw);
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
   } catch {
     return null;
   }
 }
 
+// --- Loader ---
+
+/**
+ * Load all configuration files for a project.
+ *
+ * @param {string} projectDir - The workspace root directory
+ * @param {string} [explicitPath] - Explicit path to a config directory
+ * @returns {object} - Merged configuration object with all 6 configs
+ */
 function loadConfig(projectDir, explicitPath) {
-  const candidates = [];
+  // Determine which preset to use
+  // Priority: project mdboard.json > project entities.json > env var > default
+  let preset = process.env.MDBOARD_PRESET || DEFAULT_PRESET;
 
-  if (explicitPath) {
-    candidates.push(path.resolve(explicitPath));
+  if (projectDir) {
+    const userMdboard = tryReadJson(path.join(projectDir, 'project', 'mdboard.json'));
+    if (userMdboard && userMdboard.preset) {
+      preset = userMdboard.preset;
+    }
   }
 
-  if (projectDir) {
-    candidates.push(path.join(projectDir, 'project', 'mdboard.json'));
-    candidates.push(path.join(projectDir, 'mdboard.json'));
+  const userEntities = projectDir
+    ? tryReadJson(path.join(projectDir, 'project', 'entities.json'))
+    : null;
+  if (userEntities && userEntities.methodology) {
+    preset = userEntities.methodology;
   }
 
-  const globalPath = path.join(os.homedir(), '.config', 'mdboard', 'mdboard.json');
-  candidates.push(globalPath);
+  const presetDir = path.join(PRESETS_DIR, preset);
+  const config = { _preset: preset, _projectDir: projectDir };
 
-  let userConfig = null;
-  let configPath = null;
+  for (const name of CONFIG_FILES) {
+    // Load preset base
+    const presetFile = tryReadJson(path.join(presetDir, name + '.json'));
 
-  for (const p of candidates) {
-    const data = tryReadJson(p);
-    if (data) {
-      userConfig = data;
-      configPath = p;
-      break;
+    // Load user overrides
+    const candidates = [];
+    if (explicitPath) {
+      candidates.push(path.join(path.resolve(explicitPath), name + '.json'));
+    }
+    if (projectDir) {
+      candidates.push(path.join(projectDir, 'project', name + '.json'));
+    }
+
+    let userFile = null;
+    let userPath = null;
+    for (const p of candidates) {
+      const data = tryReadJson(p);
+      if (data) {
+        userFile = data;
+        userPath = p;
+        break;
+      }
+    }
+
+    if (presetFile && userFile) {
+      config[name] = deepMerge(presetFile, userFile);
+    } else {
+      config[name] = userFile || presetFile || {};
     }
+    config['_' + name + 'Path'] = userPath || path.join(presetDir, name + '.json');
   }
 
-  const config = userConfig ? deepMerge(defaults, userConfig) : { ...defaults };
-  config._path = configPath;
+  // Also load legacy mdboard.json for theme resolution
+  config._theme = resolveTheme(projectDir, explicitPath);
+
   return config;
 }
 
-function resolveTheme(projectDir, explicitPath) {
-  const candidates = [];
+// --- Entity API ---
+
+/**
+ * Get entity definition by type name.
+ * @param {object} config - Loaded config
+ * @param {string} type - Entity type (e.g. "cycle", "task")
+ * @returns {object|null}
+ */
+function getEntity(config, type) {
+  return (config.entities && config.entities.entities && config.entities.entities[type]) || null;
+}
+
+/**
+ * Get all entity type names.
+ * @param {object} config - Loaded config
+ * @returns {string[]}
+ */
+function getEntityTypes(config) {
+  return config.entities && config.entities.entities
+    ? Object.keys(config.entities.entities)
+    : [];
+}
+
+/**
+ * Get fields definition for an entity type.
+ * @param {object} config - Loaded config
+ * @param {string} type - Entity type
+ * @returns {object} - Field definitions
+ */
+function getFields(config, type) {
+  const entity = getEntity(config, type);
+  return entity ? entity.fields || {} : {};
+}
+
+/**
+ * Get status values for an entity type (if it has a status enum field).
+ * @param {object} config - Loaded config
+ * @param {string} type - Entity type
+ * @returns {object[]|null} - Array of status value objects
+ */
+function getStatuses(config, type) {
+  const fields = getFields(config, type);
+  return fields.status && fields.status.type === 'enum' ? fields.status.values : null;
+}
+
+/**
+ * Check if a status key is considered "completed".
+ * @param {object} config - Loaded config
+ * @param {string} statusKey - Status key to check
+ * @returns {boolean}
+ */
+function isCompletedStatus(config, statusKey) {
+  const completed = (config.entities && config.entities.completedStatuses) || [];
+  return completed.includes(statusKey);
+}
+
+/**
+ * Get priority definitions.
+ * @param {object} config - Loaded config
+ * @returns {object[]}
+ */
+function getPriorities(config) {
+  return (config.entities && config.entities.priorities) || [];
+}
+
+// --- Hierarchy API ---
+
+/**
+ * Get the hierarchy tree from structure config.
+ * @param {object} config - Loaded config
+ * @returns {object} - Hierarchy tree
+ */
+function getHierarchy(config) {
+  return (config.structure && config.structure.hierarchy) || {};
+}
+
+/**
+ * Get the project root directory name.
+ * @param {object} config - Loaded config
+ * @returns {string}
+ */
+function getRoot(config) {
+  return (config.structure && config.structure.root) || 'project';
+}
+
+/**
+ * Flatten the hierarchy into an ordered array of { type, dir, depth, parent }.
+ * @param {object} config - Loaded config
+ * @returns {object[]}
+ */
+function flattenHierarchy(config) {
+  const result = [];
+
+  function walk(node, depth, parentType) {
+    for (const [type, def] of Object.entries(node)) {
+      result.push({ type, dir: def.dir, depth, parent: parentType });
+      if (def.children) {
+        walk(def.children, depth + 1, type);
+      }
+    }
+  }
+
+  walk(getHierarchy(config), 0, null);
 
-  if (explicitPath) {
-    candidates.push(path.resolve(explicitPath));
+  // Also add standalone entities
+  const standalone = (config.structure && config.structure.standalone) || {};
+  for (const [type, def] of Object.entries(standalone)) {
+    result.push({ type, dir: def.dir, depth: 0, parent: null, standalone: true });
   }
 
+  return result;
+}
+
+/**
+ * Get the parent type for an entity type.
+ * @param {object} config - Loaded config
+ * @param {string} type - Entity type
+ * @returns {string|null}
+ */
+function getParent(config, type) {
+  const flat = flattenHierarchy(config);
+  const entry = flat.find(e => e.type === type);
+  return entry ? entry.parent : null;
+}
+
+/**
+ * Get the direct children types for an entity type.
+ * @param {object} config - Loaded config
+ * @param {string} type - Entity type
+ * @returns {string[]}
+ */
+function getChildren(config, type) {
+  const flat = flattenHierarchy(config);
+  return flat.filter(e => e.parent === type).map(e => e.type);
+}
+
+/**
+ * Get all ancestor types for an entity type (from immediate parent to root).
+ * @param {object} config - Loaded config
+ * @param {string} type - Entity type
+ * @returns {string[]}
+ */
+function getAncestors(config, type) {
+  const ancestors = [];
+  let current = type;
+  while (true) {
+    const parent = getParent(config, current);
+    if (!parent) break;
+    ancestors.push(parent);
+    current = parent;
+  }
+  return ancestors;
+}
+
+/**
+ * Resolve the filesystem path for an entity instance.
+ *
+ * @param {object} config - Loaded config
+ * @param {string} type - Entity type to resolve
+ * @param {object} ids - Map of entity type → slug/id for each ancestor
+ *   e.g. { cycle: "cycle-01", bet: "config-engine", scope: "schema" }
+ * @returns {string} - Resolved path relative to project root
+ *
+ * Example for task in shape-up:
+ *   resolveEntityPath(config, "task", { cycle: "cycle-01", bet: "config-engine", scope: "schema" })
+ *   → "cycles/cycle-01/bets/config-engine/scopes/schema/tasks"
+ */
+function resolveEntityPath(config, type, ids) {
+  ids = ids || {};
+  const root = getRoot(config);
+
+  // Check standalone first
+  const standalone = (config.structure && config.structure.standalone) || {};
+  if (standalone[type]) {
+    return path.join(root, standalone[type].dir);
+  }
+
+  // Walk the hierarchy to build the path
+  const segments = [root];
+
+  function walk(node, targetType) {
+    for (const [nodeType, def] of Object.entries(node)) {
+      segments.push(def.dir);
+      if (ids[nodeType]) {
+        segments.push(ids[nodeType]);
+      }
+
+      if (nodeType === targetType) {
+        return true;
+      }
+
+      if (def.children) {
+        if (walk(def.children, targetType)) {
+          return true;
+        }
+      }
+
+      // Backtrack
+      if (ids[nodeType]) segments.pop();
+      segments.pop();
+    }
+    return false;
+  }
+
+  walk(getHierarchy(config), type);
+  return segments.join('/');
+}
+
+/**
+ * Resolve the full file path for a new entity instance.
+ *
+ * @param {object} config - Loaded config
+ * @param {string} type - Entity type
+ * @param {string} slug - Slug for the new entity
+ * @param {object} ids - Ancestor ids map
+ * @returns {string} - Full relative file path
+ */
+function resolveEntityFile(config, type, slug, ids) {
+  const entity = getEntity(config, type);
+  if (!entity) return null;
+
+  const dirPath = resolveEntityPath(config, type, ids);
+  const filePattern = entity.file || 'README.md';
+
+  if (filePattern === 'README.md') {
+    // Directory-based entity: create dir/slug/README.md
+    return path.join(dirPath, slug, 'README.md');
+  }
+
+  if (filePattern === 'PREFIX-NNN.md') {
+    // File-based entity: create dir/PREFIX-NNN.md (caller resolves NNN)
+    return dirPath; // Return the directory; caller adds the filename
+  }
+
+  return path.join(dirPath, filePattern);
+}
+
+/**
+ * Check if an entity type is standalone (not in hierarchy).
+ * @param {object} config - Loaded config
+ * @param {string} type - Entity type
+ * @returns {boolean}
+ */
+function isStandalone(config, type) {
+  const standalone = (config.structure && config.structure.standalone) || {};
+  return !!standalone[type];
+}
+
+// --- Ref resolution ---
+
+/**
+ * Get all ref fields for an entity type (fields that reference other entities).
+ * @param {object} config - Loaded config
+ * @param {string} type - Entity type
+ * @returns {object[]} - Array of { fieldName, targetEntity, multiple }
+ */
+function getRefFields(config, type) {
+  const fields = getFields(config, type);
+  const refs = [];
+  for (const [name, def] of Object.entries(fields)) {
+    if (def.type === 'ref') {
+      refs.push({ fieldName: name, targetEntity: def.entity, multiple: !!def.multiple });
+    }
+  }
+  return refs;
+}
+
+/**
+ * Get all filterable fields for an entity type (enums + refs + ancestors).
+ * Used by API autoFilters and UI auto filters.
+ * @param {object} config - Loaded config
+ * @param {string} type - Entity type
+ * @returns {string[]} - Field names that can be used as filters
+ */
+function getFilterableFields(config, type) {
+  const fields = getFields(config, type);
+  const filters = [];
+
+  for (const [name, def] of Object.entries(fields)) {
+    if (def.type === 'enum' || def.type === 'ref') {
+      filters.push(name);
+    }
+  }
+
+  // Add ancestor types as implicit filters
+  const ancestors = getAncestors(config, type);
+  for (const ancestor of ancestors) {
+    if (!filters.includes(ancestor)) {
+      filters.push(ancestor);
+    }
+  }
+
+  return filters;
+}
+
+// --- CLI helpers ---
+
+/**
+ * Get CLI-available entities for a command.
+ * @param {object} config - Loaded config
+ * @param {string} command - Command name (create, update, delete)
+ * @returns {string[]}
+ */
+function getCliEntities(config, command) {
+  const cmd = config.cli && config.cli.commands && config.cli.commands[command];
+  return cmd ? cmd.entities || [] : [];
+}
+
+/**
+ * Generate CLI flags for an entity type.
+ * Returns auto-generated flags from entity fields + ancestor flags from hierarchy.
+ * @param {object} config - Loaded config
+ * @param {string} type - Entity type
+ * @returns {object[]} - Array of { flag, field, type, required, values }
+ */
+function getCliFlags(config, type) {
+  const flags = [];
+  const fields = getFields(config, type);
+
+  // Flags from entity fields
+  for (const [name, def] of Object.entries(fields)) {
+    const flag = '--' + name.replace(/_/g, '-');
+    flags.push({
+      flag,
+      field: name,
+      type: def.type,
+      label: def.label || name,
+      values: def.type === 'enum' ? def.values.map(v => v.key) : undefined
+    });
+  }
+
+  // Flags from parent entities in hierarchy
+  const ancestors = getAncestors(config, type);
+  for (const ancestor of ancestors) {
+    const flag = '--' + ancestor.replace(/_/g, '-');
+    flags.push({
+      flag,
+      field: ancestor,
+      type: 'parent-ref',
+      label: getEntity(config, ancestor).singular,
+      required: true
+    });
+  }
+
+  return flags;
+}
+
+// --- UI helpers ---
+
+/**
+ * Get UI tab definitions.
+ * @param {object} config - Loaded config
+ * @returns {object[]}
+ */
+function getUiTabs(config) {
+  return (config.ui && config.ui.tabs) || [];
+}
+
+/**
+ * Get board columns (status values) for a board view entity.
+ * @param {object} config - Loaded config
+ * @param {string} type - Entity type displayed in board
+ * @returns {object[]}
+ */
+function getBoardColumns(config, type) {
+  const statuses = getStatuses(config, type);
+  if (!statuses) return [];
+  return statuses.filter(s => !isCompletedStatus(config, s.key) || s.key === 'done');
+}
+
+// --- Theme ---
+
+function resolveTheme(projectDir, explicitPath) {
+  const candidates = [];
+  if (explicitPath) candidates.push(path.join(path.resolve(explicitPath), 'mdboard.json'));
   if (projectDir) {
     candidates.push(path.join(projectDir, 'project', 'mdboard.json'));
     candidates.push(path.join(projectDir, 'mdboard.json'));
   }
-
-  const globalPath = path.join(os.homedir(), '.config', 'mdboard', 'mdboard.json');
-  candidates.push(globalPath);
+  candidates.push(path.join(os.homedir(), '.config', 'mdboard', 'mdboard.json'));
 
   for (const p of candidates) {
     const data = tryReadJson(p);
-    if (data && data.theme) {
-      return data.theme;
-    }
+    if (data && data.theme) return data.theme;
   }
-
   return null;
 }
 
-module.exports = { loadConfig, deepMerge, resolveTheme };
+// --- Export ---
+
+module.exports = {
+  // Loader
+  loadConfig,
+  deepMerge,
+
+  // Entity API
+  getEntity,
+  getEntityTypes,
+  getFields,
+  getStatuses,
+  isCompletedStatus,
+  getPriorities,
+
+  // Hierarchy API
+  getHierarchy,
+  getRoot,
+  flattenHierarchy,
+  getParent,
+  getChildren,
+  getAncestors,
+  resolveEntityPath,
+  resolveEntityFile,
+  isStandalone,
+
+  // Ref & filter API
+  getRefFields,
+  getFilterableFields,
+
+  // CLI helpers
+  getCliEntities,
+  getCliFlags,
+
+  // UI helpers
+  getUiTabs,
+  getBoardColumns,
+
+  // Theme
+  resolveTheme,
+
+  // Constants
+  PRESETS_DIR,
+  CONFIG_FILES,
+  DEFAULT_PRESET,
+};

package/src/core/history.js

@@ -127,4 +127,20 @@ function removeFromHistory(projectPath) {
   writeHistory(entries);
 }
 
-module.exports = { readHistory, registerProject, getHistory, isValidProject, removeFromHistory };
+/**
+ * Remove history entries whose directories no longer exist on disk.
+ * @returns {{ removed: string[], kept: number }}
+ */
+function pruneHistory() {
+  const entries = readHistory();
+  const removed = [];
+  const kept = entries.filter(e => {
+    if (fs.existsSync(e.path)) return true;
+    removed.push(e.path);
+    return false;
+  });
+  if (removed.length > 0) writeHistory(kept);
+  return { removed, kept: kept.length };
+}
+
+module.exports = { readHistory, registerProject, getHistory, isValidProject, removeFromHistory, pruneHistory };