undercity 1.0.0

package/src/lib/icons.js

@@ -0,0 +1,72 @@
+const ICON_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export const DEFAULT_ICON_NAME = 'stars';
+
+export const LEGACY_ICON_MAP = Object.freeze({
+  '🔐': 'shield-lock',
+  '⬜': 'app-indicator',
+  '✦': 'stars',
+  '✅': 'check-circle',
+  '✓': 'check-circle',
+  '⚠️': 'exclamation-triangle',
+  '⚠': 'exclamation-triangle',
+  '📋': 'clipboard-check',
+  '✎': 'pencil-square',
+  '✏️': 'pencil-square',
+  '🤖': 'robot',
+  '✨': 'magic',
+  '⚡': 'lightning-charge',
+  '⌘': 'command',
+  '⊡': 'arrows-angle-expand',
+  '⟳': 'cursor',
+  '●': 'record-circle',
+  '◆': 'diamond',
+  '◎': 'bullseye',
+  '→': 'box-arrow-right',
+  '✕': 'x-lg',
+  '⧉': 'copy',
+  '🧭': 'signpost',
+  '🎒': 'backpack',
+  '🖼': 'image',
+  '🎬': 'film',
+  '🌐': 'globe',
+  '💬': 'chat-dots',
+  '📡': 'broadcast',
+  '⚙️': 'gear',
+  '💾': 'floppy',
+});
+
+function escapeAttr(str) {
+  return String(str ?? '')
+    .replace(/&/g, '&')
+    .replace(/"/g, '"')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+export function normalizeIconName(value, fallback = DEFAULT_ICON_NAME) {
+  if (typeof value !== 'string') return fallback;
+  const trimmed = value.trim();
+  if (!trimmed) return fallback;
+
+  const normalized = trimmed.toLowerCase();
+  if (ICON_NAME_RE.test(normalized)) return normalized;
+
+  return LEGACY_ICON_MAP[trimmed] ?? fallback;
+}
+
+export function renderAfIcon(value, attrs = {}, fallback = DEFAULT_ICON_NAME) {
+  const name = normalizeIconName(value, fallback);
+  const parts = [`name="${escapeAttr(name)}"`];
+
+  for (const [key, rawValue] of Object.entries(attrs)) {
+    if (rawValue === false || rawValue === null || rawValue === undefined) continue;
+    if (rawValue === true) {
+      parts.push(key);
+      continue;
+    }
+    parts.push(`${key}="${escapeAttr(rawValue)}"`);
+  }
+
+  return `<af-icon ${parts.join(' ')}></af-icon>`;
+}

package/src/lib/scope.js

@@ -0,0 +1,88 @@
+/**
+ * scope.js — Hierarchical resource management.
+ *
+ * Inspired by dirge (github.com/nicholasgasior/dirge).
+ * A Scope holds cleanup callbacks in a named tree.
+ * On dispose(), children run first (depth-first), then local resources LIFO.
+ *
+ * Accepts three cleanup resource shapes:
+ *   function      — called directly
+ *   { dispose }   — Disposable from signal.js (subscription, event handle)
+ *   { [Symbol.dispose] } — TC39 explicit resource management
+ *
+ * Usage — package lifecycle:
+ *
+ *   let _scope = null;
+ *
+ *   export function activate(env) {
+ *     _scope = new Scope('my-package');
+ *
+ *     const opener = env.workspace.addOpener(uri => { ... });
+ *     _scope.add(() => opener.dispose());
+ *
+ *     const handler = () => { ... };
+ *     document.addEventListener('my-event', handler);
+ *     _scope.add(() => document.removeEventListener('my-event', handler));
+ *   }
+ *
+ *   export function deactivate() {
+ *     _scope?.dispose();   // all resources cleaned up in one call
+ *     _scope = null;
+ *   }
+ *
+ * Usage — child scopes for different lifetimes:
+ *
+ *   // Per-render listeners that must be replaced on next render:
+ *   const perRender = this.#scope.scope('per-render');
+ *   perRender.dispose();             // remove previous listeners
+ *   perRender.add(() => el.removeEventListener('dragover', onDragover));
+ *
+ *   // The parent scope disposes all children on its own dispose().
+ */
+
+export class Scope {
+  #fns      = [];
+  #children = new Map(); // name → Scope
+
+  /**
+   * Add a cleanup resource. Returns `this` for fluent chaining.
+   *   scope.add(signal.subscribe(fn))
+   *   scope.add(() => el.removeEventListener('click', handler))
+   */
+  add(resource) {
+    this.#fns.push(resource);
+    return this;
+  }
+
+  /**
+   * Get or create a named child scope.
+   * The child disposes before this scope's own resources.
+   * Calling scope.scope(name).dispose() clears only that child;
+   * scope.scope(name) again returns the same (now empty) child.
+   */
+  scope(name) {
+    if (!this.#children.has(name)) this.#children.set(name, new Scope());
+    return this.#children.get(name);
+  }
+
+  /**
+   * Dispose all children (depth-first), then local resources (LIFO).
+   * After disposal the scope is empty and can be reused.
+   */
+  dispose() {
+    for (const child of this.#children.values()) child.dispose();
+    // Don't clear children Map — named children remain accessible for reuse.
+    // (Their resources are empty after dispose; adding to them works again.)
+
+    for (let i = this.#fns.length - 1; i >= 0; i--) {
+      const r = this.#fns[i];
+      try {
+        if (typeof r === 'function') r();
+        else r?.dispose?.() ?? r?.[Symbol.dispose]?.();
+      } catch (err) {
+        console.error('[Scope] dispose error:', err);
+      }
+    }
+    this.#fns.length = 0;
+  }
+}

package/src/lib/signal.js

@@ -0,0 +1,155 @@
+/**
+ * signal.js — Reactive primitives
+ *
+ * Signal     — reactive value cell. subscribe(fn, autorun=true) fires fn immediately
+ *              by default, then on every change. autorun=false defers first fire.
+ *              Static helpers: combineLatest(), derive(), from(). Instance: map().
+ * Emitter    — typed event emitter.
+ * Disposable — single cleanup handle.
+ * CompositeDisposable — group of disposables, disposed in reverse order.
+ * Repeater   — keyed list renderer (reconciles add/remove/reorder without clearing).
+ * on()       — DOM addEventListener returning a Disposable.
+ */
+
+export class Signal {
+  #value;
+  #subs = new Set();
+  #collected = [];
+
+  constructor(init) { this.#value = init; }
+
+  get value() { return this.#value; }
+  set value(v) {
+    if (v === this.#value) return;
+    this.#value = v;
+    for (const fn of [...this.#subs]) fn(v);
+  }
+
+  /** Subscribe to changes. autorun=true fires fn immediately with current value. */
+  subscribe(fn, autorun = true) {
+    this.#subs.add(fn);
+    if (autorun) fn(this.#value);
+    return new Disposable(() => this.#subs.delete(fn));
+  }
+
+  /** Re-fire all subscribers with the current value (used after in-place mutations). */
+  notify() {
+    for (const fn of [...this.#subs]) fn(this.#value);
+  }
+
+  peek() { return this.#value; }
+
+  /** Attach a cleanup function that runs when this signal is disposed. */
+  collect(fn) { this.#collected.push(fn); }
+
+  /** Run all collected cleanup functions and clear the list. */
+  dispose() {
+    const fns = this.#collected.splice(0);
+    for (const fn of fns) fn();
+  }
+
+  /**
+   * Combine multiple signals into one Signal whose value is an array of
+   * the current values of all inputs. Fires whenever any input changes.
+   * The returned signal has a dispose() that cleans up all subscriptions.
+   */
+  static combineLatest(signals) {
+    const out = new Signal(signals.map(s => s.value));
+    const subs = signals.map((s, i) => s.subscribe(v => {
+      const next = out.value.slice();
+      next[i] = v;
+      out.value = next;
+    }, false));
+    out.collect(() => subs.forEach(sub => sub.dispose()));
+    return out;
+  }
+
+  /** Create a derived Signal that updates when source changes. Disposable via .dispose(). */
+  static derive(source, transform) {
+    const derived = new Signal(transform(source.value));
+    const sub = source.subscribe(v => { derived.value = transform(v); }, false);
+    derived.collect(() => sub.dispose());
+    return derived;
+  }
+
+  /** Wrap a Promise as a Signal. Starts at `initial`, resolves to the value when ready. */
+  static from(promise, initial = null) {
+    const sig = new Signal(initial);
+    Promise.resolve(promise).then(v => { sig.value = v; }).catch(() => {});
+    return sig;
+  }
+
+  /** Shorthand for Signal.derive(this, fn). */
+  map(fn) { return Signal.derive(this, fn); }
+}
+
+export class Emitter {
+  #map = new Map();
+
+  on(event, fn) {
+    let set = this.#map.get(event);
+    if (!set) { set = new Set(); this.#map.set(event, set); }
+    set.add(fn);
+    return new Disposable(() => set.delete(fn));
+  }
+
+  emit(event, data) {
+    for (const fn of this.#map.get(event) ?? []) fn(data);
+  }
+}
+
+export class Disposable {
+  #fn; #done = false;
+  constructor(fn) { this.#fn = fn; }
+  dispose() { if (this.#done) return; this.#done = true; this.#fn(); }
+}
+
+export class CompositeDisposable {
+  #items = []; #done = false;
+  add(...items) { this.#items.push(...items); return this; }
+  dispose() {
+    if (this.#done) return; this.#done = true;
+    for (const d of [...this.#items].reverse()) d.dispose();
+  }
+}
+
+/**
+ * Keyed list renderer — reconciles add/remove/reorder without clearing the container.
+ * Implements dispose() so it can be passed directly to a Scope:
+ *   scope.add(new Repeater(container, signal, render))
+ */
+export class Repeater {
+  #container; #render; #key; #nodes = new Map();
+  #sub;
+
+  constructor(container, signal, render, { key = 'id' } = {}) {
+    this.#container = container;
+    this.#render    = render;
+    this.#key       = typeof key === 'function' ? key : item => item[key];
+    this.#sub       = signal.subscribe(items => this.#update(items));
+  }
+
+  dispose() {
+    this.#sub.dispose();
+    this.#nodes.clear();
+  }
+
+  #update(items) {
+    const incoming = new Map(items.map(item => [this.#key(item), item]));
+    for (const [k, node] of this.#nodes) {
+      if (!incoming.has(k)) { node.remove(); this.#nodes.delete(k); }
+    }
+    for (const item of items) {
+      const k = this.#key(item);
+      let node = this.#nodes.get(k);
+      if (!node) { node = this.#render(item); this.#nodes.set(k, node); }
+      this.#container.appendChild(node);
+    }
+  }
+}
+
+/** DOM addEventListener returning a Disposable. */
+export function on(target, type, handler, opts) {
+  target.addEventListener(type, handler, opts);
+  return new Disposable(() => target.removeEventListener(type, handler, opts));
+}

package/src/lib/state-machine.js

@@ -0,0 +1,113 @@
+/**
+ * state-machine — JSON-declared hybrid state machine.
+ *
+ * Each context key in `config.state` becomes a named Signal on the machine,
+ * so consumers subscribe directly: `machine.dirty.subscribe(v => ...)`.
+ *
+ * The event bus (framework Emitter) drives transitions automatically.
+ * Calling `machine.emit('save')` fires the bus; the machine reads the current
+ * state, finds the next state in `states[current].on.save`, and enters it.
+ *
+ * `enter` patches can be plain values or functions:
+ *   enter: { filename: ({ payload }) => payload ?? '' }
+ *
+ * Usage:
+ *   import { createMachine } from 'state-machine';
+ *
+ *   const machine = createMachine({
+ *     state:   { dirty: false, saving: false },
+ *     initial: 'idle',
+ *     states: {
+ *       idle:   { enter: { dirty: false, saving: false }, on: { edit: 'dirty' } },
+ *       dirty:  { enter: { dirty: true },                 on: { save: 'saving' } },
+ *       saving: { enter: { saving: true },                on: { 'save-ok': 'idle', 'save-fail': 'dirty' } },
+ *     },
+ *   });
+ *
+ *   machine.dirty.subscribe(v => console.log('dirty:', v));
+ *   machine.emit('edit');   // dirty → true
+ *   machine.emit('save');   // saving → true
+ *   machine.emit('save-ok');// dirty → false, saving → false
+ */
+
+import { Signal, Emitter } from 'framework';
+
+// ── MapSet ─────────────────────────────────────────────────────────────────────
+// Map<key, Set<value>> — useful for multi-listener registries.
+
+export class MapSet {
+  #map = new Map();
+
+  add(key, value) {
+    let set = this.#map.get(key);
+    if (!set) { set = new Set(); this.#map.set(key, set); }
+    set.add(value);
+    return this;
+  }
+
+  delete(key, value) {
+    const set = this.#map.get(key);
+    if (!set) return false;
+    const deleted = set.delete(value);
+    if (set.size === 0) this.#map.delete(key);
+    return deleted;
+  }
+
+  get(key)     { return this.#map.get(key); }
+  keys()       { return this.#map.keys(); }
+  values()     { return this.#map.values(); }
+  entries()    { return this.#map.entries(); }
+  has(key)     { return this.#map.has(key); }
+  get size()   { return this.#map.size; }
+}
+
+// ── createMachine ──────────────────────────────────────────────────────────────
+
+export function createMachine(config) {
+  const bus = new Emitter();
+
+  const machine = {
+    bus,
+    current: new Signal(config.initial),
+    signals: {},
+    /** Dispatch an event into the machine. payload is optional. */
+    emit(event, payload) { bus.emit(event, payload); },
+  };
+
+  // Create a named Signal for each context key.
+  for (const [key, initialValue] of Object.entries(config.state)) {
+    const sig = new Signal(initialValue);
+    machine.signals[key] = sig;
+    machine[key] = sig;
+  }
+
+  function applyPatch(patch = {}, payload) {
+    for (const [key, value] of Object.entries(patch)) {
+      if (!machine.signals[key]) throw new Error(`state-machine: unknown signal "${key}" in enter patch`);
+      machine.signals[key].value = typeof value === 'function'
+        ? value({ payload, machine, current: machine.current.value })
+        : value;
+    }
+  }
+
+  function enterState(name, payload) {
+    const stateDef = config.states[name];
+    if (!stateDef) throw new Error(`state-machine: unknown state "${name}"`);
+    machine.current.value = name;
+    applyPatch(stateDef.enter ?? {}, payload);
+  }
+
+  // Auto-discover all event names and wire them to transitions.
+  const events = new Set(
+    Object.values(config.states).flatMap(s => Object.keys(s.on ?? {}))
+  );
+  for (const event of events) {
+    bus.on(event, payload => {
+      const next = config.states[machine.current.value]?.on?.[event];
+      if (next) enterState(next, payload);
+    });
+  }
+
+  enterState(config.initial);
+  return machine;
+}

package/src/server/index.js

@@ -0,0 +1,96 @@
+/**
+ * src/server/index.js — HTTP server setup.
+ *
+ * createServer(options?) builds the Express-compatible app.
+ * listen(app, port?)   starts it and returns {server, port, url, close}.
+ *
+ * Options accepted by createServer():
+ *   projDir  — absolute path to the projects directory  (default: <root>/projects)
+ *   genDir   — absolute path to the generated directory (default: <root>/generated)
+ *
+ * Passing explicit directories is how integration tests achieve full isolation:
+ *   const app = createServer({ projDir: tmpDir, genDir: tmpGenDir });
+ *   const { url, close } = await listen(app, 0);  // port 0 → OS picks one
+ */
+
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+import express from '../../packages/undercity-http-server/index.js';
+
+import { registerProjectRoutes }  from './routes/projects.js';
+import { registerGenerateRoute }  from './routes/generate.js';
+import { registerAIRoute }        from './routes/ai.js';
+import { registerSubmitRoute }    from './routes/submit.js';
+import { registerTemplatesRoute } from './routes/templates.js';
+import { registerActionsRoute }   from './routes/actions.js';
+import { registerResetRoute }     from './routes/reset.js';
+import { registerThingsRoute }    from './routes/things.js';
+
+const __dir  = dirname(fileURLToPath(import.meta.url));
+const ROOT   = join(__dir, '..', '..');
+
+const DEFAULT_PROJ   = join(ROOT, 'projects');
+const DEFAULT_GENDIR = join(ROOT, 'generated');
+const DEFAULT_PORT   = process.env.PORT ?? 3000;
+
+// ── App factory ────────────────────────────────────────────────────────────────
+
+export function createServer({ projDir = DEFAULT_PROJ, genDir = DEFAULT_GENDIR } = {}) {
+  const app = express();
+
+  // Middleware
+  app.use(express.json({ limit: '4mb' }));
+
+  // Static assets
+  app.use('/lib/bootstrap', express.static(join(ROOT, 'generator', 'base')));
+  app.use('/packages',      express.static(join(ROOT, 'packages')));
+  app.use('/src',           express.static(join(ROOT, 'src')));
+  app.use('/generated',     express.static(genDir));
+  app.use('/actions',       express.static(join(ROOT, 'actions')));
+  app.use('/',              express.static(join(ROOT, 'public')));
+
+  // API routes
+  registerProjectRoutes(app, projDir);
+  registerGenerateRoute(app, projDir, genDir);
+  registerAIRoute(app);
+  registerSubmitRoute(app);
+  registerTemplatesRoute(app);
+  registerActionsRoute(app);
+  registerResetRoute(app, projDir, genDir);
+  registerThingsRoute(app);
+
+  // Serve thing.json and associated assets
+  app.use('/things', express.static(join(ROOT, 'things')));
+
+  return app;
+}
+
+// ── Server lifecycle ───────────────────────────────────────────────────────────
+
+/**
+ * Start the app listening. Returns a promise that resolves once the server
+ * is ready, yielding { server, port, url, close }.
+ *
+ * Pass port = 0 for a random available port (useful in tests).
+ */
+export function listen(app, port) {
+  const listenPort = port ?? Number(DEFAULT_PORT);
+  return new Promise((resolve, reject) => {
+    const srv = app.listen(listenPort, () => {
+      const addr = srv.address();
+      const p    = addr.port;
+      if (!port) {
+        // Production boot — emit to stdout
+        console.log(`\n  Undercity IDE  →  http://localhost:${p}\n`);
+      }
+      resolve({
+        server: srv,
+        port:   p,
+        url:    `http://localhost:${p}`,
+        close:  () => new Promise((res, rej) => srv.close(err => err ? rej(err) : res())),
+      });
+    });
+    srv.on('error', reject);
+  });
+}

package/src/server/routes/actions.js

@@ -0,0 +1,144 @@
+/**
+ * routes/actions.js — Action plugin discovery API.
+ *
+ * GET /api/actions/plugins
+ *   Scans <root>/actions/<category>/<action-name>/action.json and returns
+ *   all plugin definitions grouped by category, ready to merge into the IDE's
+ *   ACTION_LIBRARY.
+ *
+ * Response shape:
+ *   {
+ *     "<categoryId>": {
+ *       label:   string,
+ *       icon:    string,
+ *       color:   string,
+ *       actions: {
+ *         "<action.id>": { label, desc, params, ... }
+ *       }
+ *     },
+ *     ...
+ *   }
+ *
+ * Each action.json must have at minimum: id, category, label, desc, params[].
+ * Optional fields: categoryLabel, icon, color, version.
+ */
+
+import { readdir, readFile } from 'fs/promises';
+import { join, dirname }     from 'path';
+import { fileURLToPath }     from 'url';
+
+const __dir      = dirname(fileURLToPath(import.meta.url));
+const ACTIONS_DIR = join(__dir, '..', '..', '..', 'actions');
+
+// Default icon/color per category (fallback when action.json omits them)
+const CATEGORY_DEFAULTS = {
+  display:        { icon: 'type',               color: 'var(--sol-cyan)'    },
+  render:         { icon: 'layout-text-window', color: 'var(--sol-violet)'  },
+  auth:           { icon: 'shield-lock',        color: 'var(--sol-blue)'    },
+  media:          { icon: 'film',               color: 'var(--sol-magenta)' },
+  data:           { icon: 'database',           color: 'var(--sol-yellow)'  },
+  notification:   { icon: 'bell',               color: 'var(--sol-orange)'  },
+};
+
+export function registerActionsRoute(app) {
+  /**
+   * GET /api/actions/tests
+   * Returns a list of { actionId, url } objects for all discovered action.test.js files.
+   * The testbench can dynamically import these to run per-action tests.
+   */
+  app.get('/api/actions/tests', async (_req, res) => {
+    try {
+      const tests = [];
+      let catDirs;
+      try { catDirs = await readdir(ACTIONS_DIR, { withFileTypes: true }); }
+      catch { return res.json([]); }
+
+      for (const catEnt of catDirs) {
+        if (!catEnt.isDirectory()) continue;
+        const catDir = join(ACTIONS_DIR, catEnt.name);
+        let actionDirs;
+        try { actionDirs = await readdir(catDir, { withFileTypes: true }); }
+        catch { continue; }
+
+        for (const actEnt of actionDirs) {
+          if (!actEnt.isDirectory()) continue;
+          const testPath = join(catDir, actEnt.name, 'action.test.js');
+          try {
+            await readFile(testPath); // check existence
+            tests.push({
+              actionId: `${catEnt.name}.${actEnt.name}`,
+              url: `/actions/${catEnt.name}/${actEnt.name}/action.test.js`,
+            });
+          } catch { /* no test file */ }
+        }
+      }
+      res.json(tests);
+    } catch (err) {
+      console.error('[actions/tests]', err);
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  /**
+   * GET /api/actions/plugins
+   * Returns all discovered plugins merged into ACTION_LIBRARY-compatible shape.
+   */
+  app.get('/api/actions/plugins', async (_req, res) => {
+    try {
+      const result = {};
+
+      // Each sub-directory of actions/ is a category
+      let catDirs;
+      try {
+        catDirs = await readdir(ACTIONS_DIR, { withFileTypes: true });
+      } catch {
+        return res.json({});   // actions/ dir missing → no plugins
+      }
+
+      for (const catEnt of catDirs) {
+        if (!catEnt.isDirectory()) continue;
+        const catId  = catEnt.name;
+        const catDir = join(ACTIONS_DIR, catId);
+
+        let actionDirs;
+        try { actionDirs = await readdir(catDir, { withFileTypes: true }); }
+        catch { continue; }
+
+        for (const actEnt of actionDirs) {
+          if (!actEnt.isDirectory()) continue;
+          const manifestPath = join(catDir, actEnt.name, 'action.json');
+
+          let manifest;
+          try {
+            manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+          } catch { continue; }   // skip malformed / missing manifests
+
+          if (!manifest.id || !manifest.label) continue;
+
+          // Initialise category bucket if first action from this category
+          if (!result[catId]) {
+            const defaults = CATEGORY_DEFAULTS[catId] ?? {};
+            result[catId] = {
+              label:   manifest.categoryLabel ?? catId.charAt(0).toUpperCase() + catId.slice(1),
+              icon:    manifest.icon  ?? defaults.icon  ?? 'puzzle',
+              color:   manifest.color ?? defaults.color ?? 'var(--sol-base1)',
+              actions: {},
+            };
+          }
+
+          result[catId].actions[manifest.id] = {
+            label:  manifest.label,
+            desc:   manifest.desc  ?? '',
+            params: manifest.params ?? [],
+            ...(manifest.version ? { version: manifest.version } : {}),
+          };
+        }
+      }
+
+      res.json(result);
+    } catch (err) {
+      console.error('[actions/plugins]', err);
+      res.status(500).json({ error: err.message });
+    }
+  });
+}