thatcher 1.0.4

package/src/index.js

@@ -0,0 +1,368 @@
+/**
+ * Thatcher SDK - Configuration-Driven Application Framework
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Forward-declare so we can set later
+let _configEngine = null;
+let _databaseInitialized = false;
+let _pluginsLoaded = false;
+let _server = null;
+let _hotReloadWatchers = [];
+
+/**
+ * Resolve a path relative to this package's src directory as an import URL
+ * @param {string} relative - Path like './src/lib/database-core.js'
+ * @returns {string} file:// URL
+ */
+function resolveModule(relative) {
+  const abs = path.resolve(__dirname, relative);
+  return pathToFileURL(abs).href;
+}
+
+/**
+ * Thatcher class - main API
+ */
+export class Thatcher {
+  constructor(options = {}) {
+    this.options = this.normalizeOptions(options);
+    this.config = null;
+    this.initialized = false;
+    this.started = false;
+  }
+
+  normalizeOptions(options) {
+    return {
+      config: options.config || null,
+      databasePath: options.databasePath || path.resolve(process.cwd(), 'data', 'app.db'),
+      env: options.env || {},
+      plugins: options.plugins || [],
+      server: {
+        port: options.server?.port || parseInt(process.env.PORT || '3000', 10),
+        host: options.server?.host || '0.0.0.0',
+        hotReload: options.server?.hotReload !== false,
+      },
+      ui: options.ui !== false,
+    };
+  }
+
+  /**
+   * Initialize the system (config, DB, plugins)
+   */
+  async init() {
+    if (this.initialized) return this;
+
+    // Apply env overrides
+    Object.assign(process.env, this.options.env);
+
+    // Load configuration
+    await this.loadConfig();
+
+    // Initialize database
+    await this.initDatabase();
+
+    // Load plugins
+    await this.loadPlugins();
+
+    // Hot reload
+    if (this.options.server.hotReload) {
+      this.setupHotReload();
+    }
+
+    this.initialized = true;
+    return this;
+  }
+
+  /**
+   * Load master configuration
+   */
+  async loadConfig() {
+    const { config } = this.options;
+    let masterConfig;
+
+    if (typeof config === 'string') {
+      const configPath = path.resolve(process.cwd(), config);
+      if (!fs.existsSync(configPath)) {
+        throw new Error(`Configuration file not found: ${configPath}`);
+      }
+      const content = fs.readFileSync(configPath, 'utf-8');
+      const { default: yaml } = await import('js-yaml');
+      masterConfig = yaml.load(content);
+    } else if (typeof config === 'object') {
+      masterConfig = config;
+    } else {
+      // Auto-discover
+      const defaultPaths = [
+        path.resolve(process.cwd(), 'master-config.yml'),
+        path.resolve(process.cwd(), 'thatcher.config.yml'),
+      ];
+      for (const p of defaultPaths) {
+        if (fs.existsSync(p)) {
+          this.options.config = p;
+          const content = fs.readFileSync(p, 'utf-8');
+          const { default: yaml } = await import('js-yaml');
+          masterConfig = yaml.load(content);
+          break;
+        }
+      }
+    }
+
+    if (!masterConfig) {
+      throw new Error('No configuration provided. Supply config path or object.');
+    }
+
+    // Init config engine
+    const { ConfigGeneratorEngine } = await import(resolveModule('./src/lib/config-generator-engine.js'));
+    _configEngine = new ConfigGeneratorEngine(masterConfig);
+
+    // Debug exposure
+    if (globalThis.__debug__) {
+      globalThis.__debug__.expose('configEngine', _configEngine, 'Config Engine');
+    }
+
+    this.config = masterConfig;
+  }
+
+  /**
+   * Initialize database with schema from config
+   */
+  async initDatabase() {
+    if (_databaseInitialized) return;
+    const { migrate } = await import(resolveModule('./lib/database-core.js'));
+    migrate(_configEngine);
+    const { getDatabase } = await import(resolveModule('./lib/database-core.js'));
+    getDatabase(); // prime the connection
+    _databaseInitialized = true;
+  }
+
+  /**
+   * Load .plugin.js files
+   */
+  async loadPlugins() {
+    if (_pluginsLoaded) return;
+
+    // User-supplied plugins
+    for (const plugin of this.options.plugins) {
+      if (_configEngine && plugin.entityName) {
+        _configEngine.registerPlugin(plugin.entityName, plugin);
+      }
+    }
+
+    // Auto-discover in cwd/plugins and cwd/src/plugins
+    const pluginDirs = [
+      path.resolve(process.cwd(), 'plugins'),
+      path.resolve(process.cwd(), 'src/plugins'),
+    ];
+    for (const dir of pluginDirs) {
+      if (fs.existsSync(dir)) {
+        const files = fs.readdirSync(dir).filter(f => f.endsWith('.plugin.js'));
+        for (const file of files) {
+          try {
+            const mod = await import(`file://${path.join(dir, file)}?t=${Date.now()}`);
+            const plugin = mod.default || mod;
+            if (plugin.entityName) {
+              _configEngine.registerPlugin(plugin.entityName, plugin);
+            }
+          } catch (e) {
+            console.error(`[plugins] Failed to load ${file}:`, e.message);
+          }
+        }
+      }
+    }
+
+    _pluginsLoaded = true;
+  }
+
+  /**
+   * Setup hot reload watchers
+   */
+  setupHotReload() {
+    const dirs = [
+      path.resolve(process.cwd(), 'config'),
+      path.resolve(process.cwd(), 'api'),
+      path.resolve(process.cwd(), 'ui'),
+      path.resolve(process.cwd(), 'plugins'),
+    ];
+
+    for (const dir of dirs) {
+      if (!fs.existsSync(dir)) continue;
+      try {
+        const watcher = fs.watch(dir, { recursive: true }, (_, filename) => {
+          if (filename && (filename.endsWith('.js') || filename.endsWith('.jsx') || filename.endsWith('.yml'))) {
+            console.log(`[HotReload] ${filename} changed`);
+            this.invalidateCache();
+          }
+        });
+        _hotReloadWatchers.push(watcher);
+      } catch (err) {
+        console.warn(`[HotReload] Failed to watch ${dir}:`, err.message);
+      }
+    }
+  }
+
+  invalidateCache() {
+    if (_configEngine) {
+      _configEngine.invalidateCache();
+    }
+  }
+
+  /**
+   * Start HTTP server
+   */
+  async startServer(opts = {}) {
+    if (!this.initialized) throw new Error('Call init() first');
+
+    const port = opts.port || this.options.server.port;
+    const host = opts.host || this.options.server.host;
+
+    const { createServer } = await import(resolveModule('./src/server/server.js'));
+    _server = createServer({
+      thatcher: this,
+      config: this.config,
+      configEngine: _configEngine,
+      port,
+      host,
+    });
+
+    return new Promise((resolve) => {
+      _server.listen(port, host, () => {
+        console.log(`\n▲ Thatcher Server\n- Local: http://localhost:${port}\n✓ Ready\n`);
+        resolve(_server);
+      });
+    });
+  }
+
+  /**
+   * Stop server
+   */
+  async stop() {
+    if (_server) {
+      _server.close();
+      _server = null;
+    }
+    for (const w of _hotReloadWatchers) w.close();
+    _hotReloadWatchers = [];
+  }
+
+  /**
+   * Get config engine
+   */
+  getConfigEngine() {
+    return _configEngine;
+  }
+
+  /**
+   * Get entity spec
+   */
+  getEntitySpec(name) {
+    return _configEngine?.generateEntitySpec(name);
+  }
+
+  /**
+   * List all entities
+   */
+  getAllEntities() {
+    return _configEngine?.getAllEntities() || [];
+  }
+
+  /**
+   * Get workflow definition
+   */
+  getWorkflow(name) {
+    return _configEngine?.getWorkflow(name);
+  }
+
+  // === CRUD operations ===
+
+  async list(entity, where = {}, opts = {}) {
+    const { list } = await import(resolveModule('./src/lib/query-engine.js'));
+    return list(entity, where, opts);
+  }
+
+  async get(entity, id) {
+    const { get } = await import(resolveModule('./src/lib/query-engine.js'));
+    return get(entity, id);
+  }
+
+  async create(entity, data, user) {
+    const { create } = await import(resolveModule('./src/lib/query-engine-write.js'));
+    return create(entity, data, user);
+  }
+
+  async update(entity, id, data, user) {
+    const { update } = await import(resolveModule('./src/lib/query-engine-write.js'));
+    return update(entity, id, data, user);
+  }
+
+  async delete(entity, id) {
+    const { remove } = await import(resolveModule('./src/lib/query-engine-write.js'));
+    return remove(entity, id);
+  }
+
+  async search(entity, query, where = {}, opts = {}) {
+    const { search } = await import(resolveModule('./src/lib/query-engine.js'));
+    return search(entity, query, where, opts);
+  }
+
+  // === Workflow ===
+
+  async transition(entityType, entityId, workflowName, toState, user, reason = '') {
+    const { transition } = await import(resolveModule('./src/lib/workflow-engine.js'));
+    return transition(entityType, entityId, workflowName, toState, user, reason);
+  }
+
+  async getAvailableTransitions(workflowName, currentState, user, record = null) {
+    const { getAvailableTransitions } = await import(resolveModule('./src/lib/workflow-engine.js'));
+    return getAvailableTransitions(workflowName, currentState, user, record);
+  }
+
+  // === AuthZ ===
+
+  async can(user, spec, action) {
+    const { can } = await import(resolveModule('./services/permission.service.js'));
+    return can(user, spec, action);
+  }
+
+  async requirePermission(user, spec, action) {
+    const { require } = await import(resolveModule('./services/permission.service.js'));
+    return require(user, spec, action);
+  }
+
+  // === Hooks ===
+
+  async executeHook(event, context) {
+    const { executeHook } = await import(resolveModule('./lib/hook-engine.js'));
+    return executeHook(event, context);
+  }
+
+  // === Database transaction ===
+
+  async withTransaction(callback) {
+    const { withTransaction } = await import(resolveModule('./lib/query-engine.js'));
+    return withTransaction(callback);
+  }
+}
+
+/**
+ * Create thatcher instance
+ */
+export function createThatcher(options) {
+  return new Thatcher(options);
+}
+
+/**
+ * Quick-start helper
+ */
+export async function startThatcher(options = {}) {
+  const t = new Thatcher(options);
+  await t.init();
+  await t.startServer();
+  return t;
+}
+
+export default Thatcher;

package/src/lib/accessibility.js

@@ -0,0 +1,162 @@
+export const aria = {
+  label: (text) => `aria-label="${escapeHtml(text)}"`,
+  labelledBy: (id) => `aria-labelledby="${id}"`,
+  describedBy: (id) => `aria-describedby="${id}"`,
+  live: (politeness = 'polite') => `aria-live="${politeness}" aria-atomic="true"`,
+  hidden: (hidden = true) => hidden ? 'aria-hidden="true"' : '',
+  expanded: (expanded) => `aria-expanded="${expanded}"`,
+  pressed: (pressed) => `aria-pressed="${pressed}"`,
+  checked: (checked) => `aria-checked="${checked}"`,
+  disabled: (disabled) => disabled ? 'aria-disabled="true"' : '',
+  current: (type = 'page') => `aria-current="${type}"`,
+  haspopup: (type = 'dialog') => `aria-haspopup="${type}"`,
+  controls: (id) => `aria-controls="${id}"`,
+  owns: (id) => `aria-owns="${id}"`,
+  invalid: (invalid) => invalid ? 'aria-invalid="true"' : '',
+  required: () => 'aria-required="true"',
+};
+
+export const role = {
+  button: 'role="button"',
+  dialog: 'role="dialog"',
+  alertdialog: 'role="alertdialog"',
+  navigation: 'role="navigation"',
+  main: 'role="main"',
+  search: 'role="search"',
+  form: 'role="form"',
+  region: 'role="region"',
+  banner: 'role="banner"',
+  contentinfo: 'role="contentinfo"',
+  complementary: 'role="complementary"',
+  list: 'role="list"',
+  listitem: 'role="listitem"',
+  menu: 'role="menu"',
+  menuitem: 'role="menuitem"',
+  status: 'role="status"',
+  alert: 'role="alert"',
+  progressbar: 'role="progressbar"',
+  tablist: 'role="tablist"',
+  tab: 'role="tab"',
+  tabpanel: 'role="tabpanel"',
+};
+
+function escapeHtml(text) {
+  return String(text).replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+export function skipLink(href, text) {
+  return `<a href="${href}" class="skip-link" ${aria.label('Skip to ' + text)}>${text}</a>`;
+}
+
+export function landmark(type, label, content) {
+  const r = role[type] || `role="${type}"`;
+  const a = label ? aria.label(label) : '';
+  return `<div ${r} ${a}>${content}</div>`;
+}
+
+export function semanticButton(text, attrs = {}) {
+  const label = attrs.label || text;
+  const disabled = attrs.disabled ? 'disabled' : '';
+  const pressed = attrs.pressed !== undefined ? aria.pressed(attrs.pressed) : '';
+  const expanded = attrs.expanded !== undefined ? aria.expanded(attrs.expanded) : '';
+  const controls = attrs.controls ? aria.controls(attrs.controls) : '';
+  const onClick = attrs.onclick ? `onclick="${attrs.onclick}"` : '';
+  const className = attrs.class || 'btn';
+  return `<button type="button" class="${className}" ${aria.label(label)} ${disabled} ${pressed} ${expanded} ${controls} ${onClick}>${text}</button>`;
+}
+
+export function semanticLink(href, text, attrs = {}) {
+  const label = attrs.label || text;
+  const current = attrs.current ? aria.current(attrs.current) : '';
+  const className = attrs.class || '';
+  return `<a href="${href}" class="${className}" ${aria.label(label)} ${current}>${text}</a>`;
+}
+
+export function formField(type, name, attrs = {}) {
+  const id = attrs.id || `field-${name}`;
+  const label = attrs.label || name;
+  const required = attrs.required ? aria.required() : '';
+  const invalid = attrs.invalid ? aria.invalid(true) : '';
+  const describedBy = attrs.description ? aria.describedBy(`${id}-desc`) : '';
+  const value = attrs.value !== undefined ? `value="${escapeHtml(attrs.value)}"` : '';
+  const placeholder = attrs.placeholder ? `placeholder="${escapeHtml(attrs.placeholder)}"` : '';
+  const className = attrs.class || 'input input-bordered';
+
+  let field;
+  if (type === 'textarea') {
+    field = `<textarea id="${id}" name="${name}" class="${className}" ${required} ${invalid} ${describedBy} ${placeholder}>${attrs.value || ''}</textarea>`;
+  } else if (type === 'select') {
+    const options = (attrs.options || []).map(opt =>
+      `<option value="${opt.value}"${opt.selected ? ' selected' : ''}>${opt.label}</option>`
+    ).join('');
+    field = `<select id="${id}" name="${name}" class="${className}" ${required} ${invalid} ${describedBy}>${options}</select>`;
+  } else {
+    field = `<input type="${type}" id="${id}" name="${name}" class="${className}" ${value} ${placeholder} ${required} ${invalid} ${describedBy}/>`;
+  }
+
+  const labelEl = `<label for="${id}" class="label"><span class="label-text">${label}${attrs.required ? ' <span aria-hidden="true">*</span>' : ''}</span></label>`;
+  const descEl = attrs.description ? `<p id="${id}-desc" class="text-xs text-gray-500 mt-1">${attrs.description}</p>` : '';
+
+  return `<div class="form-control">${labelEl}${field}${descEl}</div>`;
+}
+
+export function liveRegion(id, politeness = 'polite') {
+  return `<div id="${id}" ${aria.live(politeness)} class="sr-only"></div>`;
+}
+
+export function announceToScreenReader(regionId, message) {
+  return `document.getElementById('${regionId}').textContent = '${escapeHtml(message).replace(/'/g, "\\'")}';`;
+}
+
+export const focusTrap = {
+  activate: (containerId) => `
+    (function() {
+      const container = document.getElementById('${containerId}');
+      if (!container) return;
+      const focusable = container.querySelectorAll('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      container._trapHandler = (e) => {
+        if (e.key !== 'Tab') return;
+        if (e.shiftKey && document.activeElement === first) {
+          e.preventDefault();
+          last.focus();
+        } else if (!e.shiftKey && document.activeElement === last) {
+          e.preventDefault();
+          first.focus();
+        }
+      };
+      container.addEventListener('keydown', container._trapHandler);
+      first?.focus();
+    })();
+  `,
+  deactivate: (containerId) => `
+    (function() {
+      const container = document.getElementById('${containerId}');
+      if (container?._trapHandler) {
+        container.removeEventListener('keydown', container._trapHandler);
+        delete container._trapHandler;
+      }
+    })();
+  `
+};
+
+export const keyboard = {
+  escape: (callback) => `if (event.key === 'Escape') { ${callback} }`,
+  enter: (callback) => `if (event.key === 'Enter') { ${callback} }`,
+  space: (callback) => `if (event.key === ' ' || event.key === 'Spacebar') { event.preventDefault(); ${callback} }`,
+  arrowNav: (upCallback, downCallback) => `
+    if (event.key === 'ArrowUp') { event.preventDefault(); ${upCallback} }
+    if (event.key === 'ArrowDown') { event.preventDefault(); ${downCallback} }
+  `,
+};
+
+export function visuallyHidden(content) {
+  return `<span class="sr-only">${content}</span>`;
+}
+
+export function accessibleImage(src, alt, attrs = {}) {
+  const className = attrs.class || '';
+  const decorative = attrs.decorative ? 'alt="" role="presentation"' : `alt="${escapeHtml(alt)}"`;
+  return `<img src="${src}" ${decorative} class="${className}"/>`;
+}

package/src/lib/action-factory.js

@@ -0,0 +1,34 @@
+'use server';
+
+import { create, update, remove } from '@/engine';
+import { requireUser, check } from '@/engine.server';
+import { getSpec } from '@/config/spec-helpers';
+import { revalidatePath } from '@/lib/next-polyfills';
+
+export async function serverCreateEntity(entityName, data) {
+  const user = await requireUser();
+  const spec = getSpec(entityName);
+  await check(user, spec, 'create');
+  const result = create(entityName, data, user);
+  revalidatePath(`/${entityName}`);
+  return result;
+}
+
+export async function serverUpdateEntity(entityName, id, data) {
+  const user = await requireUser();
+  const spec = getSpec(entityName);
+  await check(user, spec, 'edit');
+  const result = update(entityName, id, data, user);
+  revalidatePath(`/${entityName}/${id}`);
+  revalidatePath(`/${entityName}`);
+  return result;
+}
+
+export async function serverDeleteEntity(entityName, id) {
+  const user = await requireUser();
+  const spec = getSpec(entityName);
+  await check(user, spec, 'delete');
+  const result = remove(entityName, id);
+  revalidatePath(`/${entityName}`);
+  return result;
+}

package/src/lib/action-utils.js

@@ -0,0 +1,21 @@
+import { serverCreateEntity, serverUpdateEntity, serverDeleteEntity } from '@/lib/action-factory';
+
+export function createCRUDActions(entityName) {
+  return {
+    create: (data) => serverCreateEntity(entityName, data),
+    update: (id, data) => serverUpdateEntity(entityName, id, data),
+    delete: (id) => serverDeleteEntity(entityName, id),
+  };
+}
+
+export function createEntityAction(entityName, actionName, permission, handler) {
+  return async (...args) => {
+    'use server';
+    const { requireUser, check } = await import('@/engine.server');
+    const { getSpec } = await import('@/config');
+    const user = await requireUser();
+    const spec = getSpec(entityName);
+    await check(user, spec, permission);
+    return handler(user, spec, ...args);
+  };
+}