mdboard 1.2.0 → 2.0.0

package/src/core/config.js

@@ -0,0 +1,551 @@
+/**
+ * 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/<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 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 };
+  for (const key of Object.keys(source)) {
+    const sv = source[key];
+    const tv = target[key];
+    if (sv && typeof sv === 'object' && !Array.isArray(sv) && tv && typeof tv === 'object' && !Array.isArray(tv)) {
+      result[key] = deepMerge(tv, sv);
+    } else {
+      result[key] = sv;
+    }
+  }
+  return result;
+}
+
+function tryReadJson(filePath) {
+  try {
+    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) {
+  // Determine which preset to use
+  // Priority: project mdboard.json > project entities.json > env var > default
+  let preset = process.env.MDBOARD_PRESET || DEFAULT_PRESET;
+
+  if (projectDir) {
+    const userMdboard = tryReadJson(path.join(projectDir, 'project', 'mdboard.json'));
+    if (userMdboard && userMdboard.preset) {
+      preset = userMdboard.preset;
+    }
+  }
+
+  const userEntities = projectDir
+    ? tryReadJson(path.join(projectDir, 'project', 'entities.json'))
+    : null;
+  if (userEntities && userEntities.methodology) {
+    preset = userEntities.methodology;
+  }
+
+  const presetDir = path.join(PRESETS_DIR, preset);
+  const config = { _preset: preset, _projectDir: projectDir };
+
+  for (const name of CONFIG_FILES) {
+    // Load preset base
+    const presetFile = tryReadJson(path.join(presetDir, name + '.json'));
+
+    // 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');
+  }
+
+  // Also load legacy mdboard.json for theme resolution
+  config._theme = resolveTheme(projectDir, explicitPath);
+
+  return config;
+}
+
+// --- 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);
+
+  // 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'));
+  }
+  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;
+  }
+  return null;
+}
+
+// --- 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

@@ -0,0 +1,146 @@
+/**
+ * mdboard — Project History
+ *
+ * Persistent history of visited projects stored in
+ * ~/.config/mdboard/history.json.  Allows switching between
+ * projects without restarting the server.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'mdboard');
+const HISTORY_FILE = path.join(CONFIG_DIR, 'history.json');
+const MAX_ENTRIES = 50;
+
+/**
+ * Read the history file.
+ * @returns {Array<{path:string, name:string, lastOpened:string}>}
+ */
+function readHistory() {
+  try {
+    const raw = fs.readFileSync(HISTORY_FILE, 'utf-8');
+    const data = JSON.parse(raw);
+    return Array.isArray(data) ? data : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Write history to disk.
+ * @param {Array} entries
+ */
+function writeHistory(entries) {
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(HISTORY_FILE, JSON.stringify(entries, null, 2), 'utf-8');
+  } catch {
+    // Non-critical — silently ignore write failures
+  }
+}
+
+/**
+ * Register (or update) a project in the history.
+ * Moves the entry to the front of the list.
+ *
+ * @param {string} projectDir - Absolute path to the project directory
+ * @param {string} name - Human-friendly project name
+ */
+function registerProject(projectDir, name) {
+  const absPath = path.resolve(projectDir);
+  let entries = readHistory();
+
+  // Remove existing entry for this path
+  entries = entries.filter(e => e.path !== absPath);
+
+  // Prepend new entry
+  entries.unshift({
+    path: absPath,
+    name: name || path.basename(absPath),
+    lastOpened: new Date().toISOString(),
+  });
+
+  // Enforce limit
+  if (entries.length > MAX_ENTRIES) {
+    entries = entries.slice(0, MAX_ENTRIES);
+  }
+
+  writeHistory(entries);
+}
+
+/**
+ * Get the history list with a `isCurrent` flag.
+ *
+ * @param {string} currentProjectDir - The currently-active project dir
+ * @returns {Array<{path:string, name:string, lastOpened:string, isCurrent:boolean}>}
+ */
+function getHistory(currentProjectDir) {
+  const absCurrentDir = currentProjectDir ? path.resolve(currentProjectDir) : null;
+  const entries = readHistory();
+
+  return entries.map(e => ({
+    ...e,
+    isCurrent: e.path === absCurrentDir,
+  }));
+}
+
+/**
+ * Detect whether a directory looks like a valid mdboard project.
+ * A project has either a `project/` subdirectory or a `workspace.json`
+ * with sources.
+ *
+ * @param {string} dir - Directory to check
+ * @returns {boolean}
+ */
+function isValidProject(dir) {
+  try {
+    const absDir = path.resolve(dir);
+
+    // Check for project/ sub-directory
+    if (fs.existsSync(path.join(absDir, 'project'))) return true;
+
+    // Check for workspace.json with sources
+    const wsPath = path.join(absDir, 'workspace.json');
+    if (fs.existsSync(wsPath)) {
+      const raw = fs.readFileSync(wsPath, 'utf-8');
+      const ws = JSON.parse(raw);
+      if (ws && Array.isArray(ws.sources) && ws.sources.length > 0) return true;
+    }
+
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove an entry from the history.
+ *
+ * @param {string} projectPath - Absolute path to remove
+ */
+function removeFromHistory(projectPath) {
+  const absPath = path.resolve(projectPath);
+  let entries = readHistory();
+  entries = entries.filter(e => e.path !== absPath);
+  writeHistory(entries);
+}
+
+/**
+ * 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 };