@jhizzard/termdeck 0.10.4 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.10.4",
+  "version": "0.11.0",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"

package/packages/cli/src/init-rumen.js

@@ -34,6 +34,7 @@ const {
   dotenv,
   supabaseUrl: urlHelper,
   migrations,
+  migrationTemplating,
   pgRunner,
   preconditions
 } = require(SETUP_DIR);
@@ -428,26 +429,53 @@ async function testFunction(projectRef, secrets, dryRun) {
   return true;
 }
 
+// Sprint 42 T3: bundle of cron-schedule migrations whose `<project-ref>`
+// placeholder must be substituted at apply-time. Both are idempotent
+// (cron.unschedule + cron.schedule), so applying in sequence is safe even
+// when one was already installed. Pre-Sprint 42, only 002 was applied —
+// migration 003 (graph-inference-tick) shipped bundled but unsubstituted
+// and unscheduled, which is part of why Sprint 38 close-out left the
+// graph-inference cron disabled.
+const SCHEDULE_MIGRATIONS = [
+  { matcher: /002.*pg_cron/, label: '002_pg_cron_schedule (rumen-tick)' },
+  { matcher: /003.*graph_inference/, label: '003_graph_inference_schedule (graph-inference-tick)' }
+];
+
 async function applySchedule(projectRef, secrets, dryRun) {
-  step('Applying pg_cron schedule (every 15 minutes)...');
+  step('Applying pg_cron schedules (rumen-tick + graph-inference-tick)...');
   if (dryRun) { ok('(dry-run)'); return true; }
 
   const files = migrations.listRumenMigrations();
-  const scheduleFile = files.find((f) => /002.*pg_cron/.test(path.basename(f)));
-  if (!scheduleFile) { fail('bundled 002_pg_cron_schedule.sql is missing'); return false; }
-
-  const raw = migrations.readFile(scheduleFile);
-  // Substitute the project ref into the schedule body. The bundled migration
-  // ships with the placeholder `<project-ref>` per Rumen's deploy docs; we
-  // also accept `{{PROJECT_REF}}` for robustness.
-  const substituted = raw
-    .replace(/<project-ref>/g, projectRef)
-    .replace(/\{\{PROJECT_REF\}\}/g, projectRef);
-
-  // The shipped migration uses Supabase Vault (`vault.decrypted_secrets`) to
-  // pull the service-role key. If the user hasn't stored the key in Vault the
-  // cron call will fail. We leave that as a post-install step and print a
-  // reminder below.
+  const planned = [];
+  for (const { matcher, label } of SCHEDULE_MIGRATIONS) {
+    const file = files.find((f) => matcher.test(path.basename(f)));
+    if (!file) { fail(`bundled ${label} is missing`); return false; }
+    planned.push({ file, label });
+  }
+
+  // Substitute the project ref into each schedule body. Both bundled
+  // migrations ship with the `<project-ref>` placeholder per Rumen's
+  // deploy docs; the helper also accepts `{{PROJECT_REF}}` for robustness
+  // and refuses to ship an unsubstituted placeholder to the database.
+  const substituted = [];
+  try {
+    for (const { file, label } of planned) {
+      const raw = migrations.readFile(file);
+      substituted.push({
+        sql: migrationTemplating.applyTemplating(raw, { projectRef }),
+        label
+      });
+    }
+  } catch (err) {
+    fail(err.message);
+    return false;
+  }
+
+  // The shipped migrations use Supabase Vault (`vault.decrypted_secrets`)
+  // to pull the service-role keys (`rumen_service_role_key` for 002 and
+  // `graph_inference_service_role_key` for 003). If a key isn't stored in
+  // Vault the corresponding cron call will fail at runtime. We leave that
+  // as a post-install step and print a reminder below.
 
   let client;
   try {
@@ -457,20 +485,21 @@ async function applySchedule(projectRef, secrets, dryRun) {
     return false;
   }
   try {
-    // Run the substituted SQL directly rather than applying the original file.
-    try {
-      await pgRunner.run(client, substituted);
-      ok();
-      return true;
-    } catch (err) {
-      fail(err.message);
-      process.stderr.write(
-        '\nThe schedule SQL failed — the most common cause is that pg_cron or pg_net\n' +
-        'is not enabled in the Supabase project. Enable them in Dashboard → Database\n' +
-        '→ Extensions, then re-run `termdeck init --rumen --skip-schedule=false`.\n'
-      );
-      return false;
+    for (const { sql, label } of substituted) {
+      try {
+        await pgRunner.run(client, sql);
+      } catch (err) {
+        fail(`${label}: ${err.message}`);
+        process.stderr.write(
+          '\nThe schedule SQL failed — the most common cause is that pg_cron or pg_net\n' +
+          'is not enabled in the Supabase project. Enable them in Dashboard → Database\n' +
+          '→ Extensions, then re-run `termdeck init --rumen --skip-schedule=false`.\n'
+        );
+        return false;
+      }
     }
+    ok();
+    return true;
   } finally {
     try { await client.end(); } catch (_err) { /* ignore */ }
   }

package/packages/client/public/app.js

@@ -91,6 +91,65 @@
       setupGuideRail();
     }
 
+    // ===== Drag/drop reorder of PTY panels (Sprint 42 T4) =====
+    // The grip handle in panel-header-left flips draggable=true on mousedown
+    // so an accidental drag inside the xterm region never fires. Drop
+    // position is determined by cursor x within the target panel — left half
+    // inserts before, right half inserts after — so reordering matches the
+    // intent in any grid layout (1x2, 2x2, 2x4, etc.). DOM reorder only;
+    // session.creation-order remains canonical for Alt+1…9 and panel-index.
+    function setupPanelDragDrop(panel) {
+      const handle = panel.querySelector('.panel-drag-handle');
+      if (!handle) return;
+
+      handle.addEventListener('mousedown', () => { panel.draggable = true; });
+      // Mouse leaves handle without a drag starting → reset
+      handle.addEventListener('mouseleave', () => {
+        if (!panel.classList.contains('dragging')) panel.draggable = false;
+      });
+
+      panel.addEventListener('dragstart', (e) => {
+        if (!panel.draggable) { e.preventDefault(); return; }
+        try { e.dataTransfer.effectAllowed = 'move'; } catch (_e) {}
+        try { e.dataTransfer.setData('text/plain', panel.id); } catch (_e) {}
+        panel.classList.add('dragging');
+      });
+
+      panel.addEventListener('dragend', () => {
+        panel.classList.remove('dragging');
+        panel.draggable = false;
+        document.querySelectorAll('.term-panel.drag-over').forEach((p) => p.classList.remove('drag-over'));
+      });
+
+      panel.addEventListener('dragover', (e) => {
+        const dragging = document.querySelector('.term-panel.dragging');
+        if (!dragging || dragging === panel) return;
+        e.preventDefault();
+        try { e.dataTransfer.dropEffect = 'move'; } catch (_e) {}
+        panel.classList.add('drag-over');
+      });
+
+      panel.addEventListener('dragleave', (e) => {
+        // Only clear when leaving the panel entirely (not entering a child).
+        if (!panel.contains(e.relatedTarget)) panel.classList.remove('drag-over');
+      });
+
+      panel.addEventListener('drop', (e) => {
+        e.preventDefault();
+        panel.classList.remove('drag-over');
+        const draggedId = (() => {
+          try { return e.dataTransfer.getData('text/plain'); } catch (_e) { return ''; }
+        })();
+        const dragged = draggedId
+          ? document.getElementById(draggedId)
+          : document.querySelector('.term-panel.dragging');
+        if (!dragged || dragged === panel) return;
+        const rect = panel.getBoundingClientRect();
+        const dropAfter = (e.clientX - rect.left) > rect.width / 2;
+        panel.parentNode.insertBefore(dragged, dropAfter ? panel.nextSibling : panel);
+      });
+    }
+
     // ===== Create Terminal Panel =====
     function createTerminalPanel(sessionData) {
       const id = sessionData.id;
@@ -128,6 +187,7 @@
       panel.innerHTML = `
         <div class="panel-header">
           <div class="panel-header-left">
+            <span class="panel-drag-handle" title="Drag to reorder">⋮⋮</span>
             <span class="status-dot" id="dot-${id}" style="background:${getStatusColor(meta.status)}"></span>
             <span class="panel-type">${getTypeLabel(meta.type)}</span>
             ${meta.project ? `<span class="panel-project ${projClass}">${meta.project}</span>` : ''}
@@ -193,6 +253,11 @@
 
       document.getElementById('termGrid').appendChild(panel);
 
+      // Sprint 42 T4: drag/drop reorder. Inject identifier is the session
+      // UUID, so DOM reorder is purely visual — Alt+1…9 (creation-order),
+      // /api/sessions/:id/input, and reply-form targets are unaffected.
+      setupPanelDragDrop(panel);
+
       // Create xterm.js instance
       const terminal = new Terminal({
         fontFamily: "'SF Mono', 'Cascadia Code', 'JetBrains Mono', 'Fira Code', Consolas, monospace",
@@ -265,6 +330,15 @@
                 if (typeof updateRagIndicator === 'function') updateRagIndicator();
               }
               break;
+            case 'projects_changed':
+              // Sprint 42 T4: server broadcasts on POST/DELETE /api/projects.
+              // Sync the in-memory projects map and re-render the dropdown so
+              // other open dashboard tabs stay consistent without a refresh.
+              if (msg.projects && state.config) {
+                state.config.projects = msg.projects;
+                if (typeof rebuildProjectDropdown === 'function') rebuildProjectDropdown();
+              }
+              break;
           }
         } catch (err) { console.error('[client] ws message parse failed:', err); }
       };
@@ -1281,6 +1355,14 @@
                 if (typeof updateRagIndicator === 'function') updateRagIndicator();
               }
               break;
+            case 'projects_changed':
+              // Sprint 42 T4: parity with main WS handler. Project add/remove
+              // broadcasts arrive on every ws client; idempotent.
+              if (msg.projects && state.config) {
+                state.config.projects = msg.projects;
+                if (typeof rebuildProjectDropdown === 'function') rebuildProjectDropdown();
+              }
+              break;
           }
         } catch (err) { console.error('[client] reconnect ws message failed:', err); }
       };
@@ -1552,6 +1634,104 @@
       }
     }
 
+    // ===== Remove Project modal (Sprint 42 T4) =====
+    // Removes a project from ~/.termdeck/config.yaml. Files on disk at the
+    // project's `path` are NEVER touched — the modal copy makes that explicit
+    // so users don't fear data loss. 409 from the server (live PTY sessions
+    // for that project) prompts the user with a force-override.
+    function openRemoveProjectModal() {
+      const modal = document.getElementById('removeProjectModal');
+      const sel = document.getElementById('rpmSelect');
+      sel.innerHTML = '<option value="">— pick a project —</option>';
+      for (const name of Object.keys(state.config.projects || {})) {
+        const opt = document.createElement('option');
+        opt.value = name;
+        opt.textContent = name;
+        sel.appendChild(opt);
+      }
+      sel.value = '';
+      document.getElementById('rpmConfirm').disabled = true;
+      document.getElementById('rpmConfirm').dataset.force = '';
+      document.getElementById('rpmConfirm').textContent = 'remove project';
+      const warn = document.getElementById('rpmWarning');
+      warn.hidden = true;
+      warn.textContent = '';
+      setRpmStatus('', null);
+      modal.classList.add('open');
+      setTimeout(() => sel.focus(), 50);
+    }
+
+    function closeRemoveProjectModal() {
+      document.getElementById('removeProjectModal').classList.remove('open');
+    }
+
+    function setRpmStatus(msg, kind) {
+      const el = document.getElementById('rpmStatus');
+      if (!el) return;
+      el.textContent = msg || '';
+      el.classList.remove('error', 'ok');
+      if (kind) el.classList.add(kind);
+    }
+
+    function onRpmSelectChange() {
+      const name = document.getElementById('rpmSelect').value;
+      const btn = document.getElementById('rpmConfirm');
+      btn.disabled = !name;
+      btn.dataset.force = '';
+      btn.textContent = name ? `remove "${name}"` : 'remove project';
+      const warn = document.getElementById('rpmWarning');
+      warn.hidden = true;
+      warn.textContent = '';
+      setRpmStatus('', null);
+    }
+
+    async function submitRemoveProject() {
+      const name = document.getElementById('rpmSelect').value;
+      if (!name) return;
+      const btn = document.getElementById('rpmConfirm');
+      const force = btn.dataset.force === 'true';
+      btn.disabled = true;
+      setRpmStatus(force ? 'Removing (with force)…' : 'Removing…', null);
+
+      try {
+        const url = `${API}/api/projects/${encodeURIComponent(name)}${force ? '?force=true' : ''}`;
+        const res = await fetch(url, { method: 'DELETE' });
+        const text = await res.text();
+        let body = {};
+        try { body = JSON.parse(text); } catch { body = { error: text }; }
+
+        if (res.status === 409) {
+          const live = body.liveSessions || 0;
+          const warn = document.getElementById('rpmWarning');
+          warn.hidden = false;
+          warn.innerHTML =
+            `<strong>"${name}" has ${live} live PTY session${live === 1 ? '' : 's'}.</strong> ` +
+            `Closing those terminals first is recommended. ` +
+            `Or click <em>remove anyway</em> to force removal — terminals stay open but lose their project tag in config.yaml.`;
+          btn.dataset.force = 'true';
+          btn.textContent = 'remove anyway';
+          btn.disabled = false;
+          setRpmStatus('', null);
+          return;
+        }
+
+        if (!res.ok) {
+          setRpmStatus(`Failed: ${body.error || res.statusText}`, 'error');
+          btn.disabled = false;
+          return;
+        }
+
+        // Success — sync in-memory config + dropdown.
+        state.config.projects = body.projects || {};
+        rebuildProjectDropdown();
+        setRpmStatus(`Removed "${name}" ✓ (files on disk untouched)`, 'ok');
+        setTimeout(() => { closeRemoveProjectModal(); }, 900);
+      } catch (err) {
+        setRpmStatus(`Failed: ${err.message || err}`, 'error');
+        btn.disabled = false;
+      }
+    }
+
     // ===== Orchestration preview modal (Sprint 37 T3) =====
     // The preview button next to the project select shows what
     // `termdeck init --project <name>` would create for the currently
@@ -3714,6 +3894,16 @@
       if (e.key === 'Escape') { e.preventDefault(); closeAddProjectModal(); }
     });
 
+    // Remove-project modal wiring (Sprint 42 T4)
+    document.getElementById('btnRemoveProject').addEventListener('click', openRemoveProjectModal);
+    document.getElementById('rpmCancel').addEventListener('click', closeRemoveProjectModal);
+    document.getElementById('rpmConfirm').addEventListener('click', submitRemoveProject);
+    document.getElementById('rpmSelect').addEventListener('change', onRpmSelectChange);
+    document.querySelector('#removeProjectModal .remove-project-backdrop').addEventListener('click', closeRemoveProjectModal);
+    document.getElementById('removeProjectModal').addEventListener('keydown', (e) => {
+      if (e.key === 'Escape') { e.preventDefault(); closeRemoveProjectModal(); }
+    });
+
     // Orchestration preview modal wiring (Sprint 37 T3)
     document.getElementById('btnPreviewProject').addEventListener('click', openPreviewModal);
     document.getElementById('promptProject').addEventListener('change', syncPreviewButton);

package/packages/client/public/index.html

@@ -135,6 +135,7 @@
       <option value="">no project</option>
     </select>
     <button class="prompt-add-project" id="btnAddProject" title="Add a new project">+</button>
+    <button class="prompt-remove-project" id="btnRemoveProject" title="Remove a project (files on disk are untouched)">−</button>
     <button class="prompt-preview-project" id="btnPreviewProject" title="Preview orchestration scaffolding for the selected project" disabled>preview</button>
     <button class="prompt-launch" id="promptLaunch">launch</button>
   </div>
@@ -169,6 +170,29 @@
     </div>
   </div>
 
+  <!-- Remove-project modal (Sprint 42 T4). Hidden by default. -->
+  <div class="remove-project-modal" id="removeProjectModal" role="dialog" aria-modal="true" aria-labelledby="rpmTitle">
+    <div class="remove-project-backdrop"></div>
+    <div class="remove-project-card">
+      <h3 id="rpmTitle">Remove a project</h3>
+      <p class="rpm-help">
+        This unregisters the project from <code>~/.termdeck/config.yaml</code>.
+        <strong>Files on disk are untouched</strong> — your source code, git history,
+        and everything at the project's path stay exactly where they are.
+      </p>
+      <label>
+        <span>Project to remove</span>
+        <select id="rpmSelect"><option value="">— pick a project —</option></select>
+      </label>
+      <div class="rpm-warning" id="rpmWarning" hidden></div>
+      <div class="rpm-status" id="rpmStatus"></div>
+      <div class="rpm-actions">
+        <button class="rpm-cancel" id="rpmCancel">cancel</button>
+        <button class="rpm-confirm" id="rpmConfirm" disabled>remove project</button>
+      </div>
+    </div>
+  </div>
+
   <!-- Orchestration-preview modal (Sprint 37 T3). Hidden by default. -->
   <div class="preview-project-modal" id="previewProjectModal" role="dialog" aria-modal="true" aria-labelledby="ppmTitle">
     <div class="preview-project-backdrop"></div>

package/packages/client/public/style.css

@@ -389,6 +389,31 @@
       flex: 1;
     }
 
+    /* Sprint 42 T4 — drag handle for PTY panel reordering. Only the handle
+       is grabbable; the rest of the panel header / xterm body are unaffected. */
+    .panel-drag-handle {
+      cursor: grab;
+      color: var(--tg-text-dim);
+      font-size: 12px;
+      letter-spacing: -2px;
+      user-select: none;
+      flex-shrink: 0;
+      padding: 0 2px;
+      opacity: 0.5;
+      transition: opacity 0.15s;
+    }
+    .panel-drag-handle:hover { opacity: 1; color: var(--tg-accent); }
+    .panel-drag-handle:active { cursor: grabbing; }
+    .term-panel.dragging {
+      opacity: 0.5;
+      outline: 2px dashed var(--tg-accent);
+      outline-offset: -2px;
+    }
+    .term-panel.drag-over {
+      outline: 2px solid var(--tg-accent);
+      outline-offset: -2px;
+    }
+
     .status-dot {
       width: 8px; height: 8px;
       border-radius: 50%;
@@ -768,6 +793,156 @@
       filter: none;
     }
 
+    /* ===== REMOVE PROJECT BUTTON + MODAL (Sprint 42 T4) ===== */
+    .prompt-remove-project {
+      background: var(--tg-bg);
+      border: 1px solid var(--tg-border);
+      color: var(--tg-text-dim);
+      font-size: 18px;
+      line-height: 1;
+      padding: 0;
+      width: 26px;
+      height: 26px;
+      border-radius: var(--tg-radius-sm);
+      cursor: pointer;
+      font-family: var(--tg-sans);
+      transition: all 0.15s;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      margin-left: 4px;
+    }
+    .prompt-remove-project:hover {
+      border-color: var(--tg-red, #f7768e);
+      color: var(--tg-red, #f7768e);
+    }
+    .remove-project-modal {
+      display: none;
+      position: fixed;
+      inset: 0;
+      z-index: 3000;
+      align-items: center;
+      justify-content: center;
+    }
+    .remove-project-modal.open { display: flex; }
+    .remove-project-backdrop {
+      position: absolute;
+      inset: 0;
+      background: rgba(0, 0, 0, 0.72);
+    }
+    .remove-project-card {
+      position: relative;
+      background: var(--tg-surface);
+      border: 1px solid var(--tg-accent-dim);
+      border-radius: 10px;
+      padding: 22px 24px 18px;
+      width: 460px;
+      max-width: calc(100vw - 40px);
+      box-shadow: 0 16px 48px rgba(0, 0, 0, 0.55);
+      font-family: var(--tg-sans);
+      color: var(--tg-text);
+    }
+    .remove-project-card h3 {
+      margin: 0 0 4px;
+      font-size: 16px;
+      color: var(--tg-accent);
+    }
+    .remove-project-card .rpm-help {
+      margin: 0 0 14px;
+      font-size: 12px;
+      color: var(--tg-text-dim);
+      line-height: 1.5;
+    }
+    .remove-project-card .rpm-help code {
+      background: var(--tg-bg);
+      padding: 1px 5px;
+      border-radius: 3px;
+      font-family: var(--tg-mono);
+      font-size: 11px;
+    }
+    .remove-project-card .rpm-help strong {
+      color: var(--tg-green);
+    }
+    .remove-project-card label {
+      display: block;
+      margin-bottom: 10px;
+    }
+    .remove-project-card label > span {
+      display: block;
+      font-size: 11px;
+      color: var(--tg-text-dim);
+      margin-bottom: 3px;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+    }
+    .remove-project-card select {
+      width: 100%;
+      background: var(--tg-bg);
+      border: 1px solid var(--tg-border);
+      color: var(--tg-text);
+      font-size: 13px;
+      padding: 7px 10px;
+      border-radius: var(--tg-radius-sm);
+      font-family: var(--tg-mono);
+      box-sizing: border-box;
+    }
+    .remove-project-card select:focus {
+      outline: none;
+      border-color: var(--tg-accent-dim);
+    }
+    .remove-project-card .rpm-warning {
+      background: rgba(247, 118, 142, 0.08);
+      border: 1px solid rgba(247, 118, 142, 0.4);
+      color: var(--tg-text);
+      font-size: 12px;
+      padding: 8px 10px;
+      border-radius: 4px;
+      margin: 6px 0 8px;
+      line-height: 1.5;
+    }
+    .remove-project-card .rpm-status {
+      font-size: 12px;
+      min-height: 16px;
+      margin: 4px 0 8px;
+      color: var(--tg-text-dim);
+    }
+    .remove-project-card .rpm-status.error { color: var(--tg-red); }
+    .remove-project-card .rpm-status.ok { color: var(--tg-green); }
+    .remove-project-card .rpm-actions {
+      display: flex;
+      justify-content: flex-end;
+      gap: 8px;
+      margin-top: 6px;
+    }
+    .remove-project-card button {
+      font-size: 12px;
+      font-weight: 600;
+      padding: 6px 16px;
+      border-radius: 4px;
+      cursor: pointer;
+      font-family: var(--tg-sans);
+      border: 1px solid var(--tg-border);
+    }
+    .remove-project-card .rpm-cancel {
+      background: transparent;
+      color: var(--tg-text-dim);
+    }
+    .remove-project-card .rpm-cancel:hover {
+      color: var(--tg-text);
+      border-color: var(--tg-border-active);
+    }
+    .remove-project-card .rpm-confirm {
+      background: var(--tg-red, #f7768e);
+      color: var(--tg-bg);
+      border-color: var(--tg-red, #f7768e);
+    }
+    .remove-project-card .rpm-confirm:hover { filter: brightness(1.1); }
+    .remove-project-card .rpm-confirm:disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+      filter: none;
+    }
+
     /* ===== Orchestration preview button + modal (Sprint 37 T3) ===== */
     .prompt-preview-project {
       background: transparent;

package/packages/server/src/config.js

@@ -298,6 +298,54 @@ function addProject({ name, path: projectPath, defaultTheme, defaultCommand }) {
   return parsed.projects;
 }
 
+// Remove a project from ~/.termdeck/config.yaml and return the updated projects
+// map. Mirrors addProject for the inverse operation. Throws ENOENT-shaped
+// errors with `code` set so callers can map cleanly to HTTP status. Files on
+// disk at the project's `path` are NEVER touched — this only edits the YAML
+// entry. The user retains all source code.
+function removeProject(name, configPath = CONFIG_PATH) {
+  if (!name || !/^[A-Za-z0-9_.-]+$/.test(name)) {
+    const err = new Error('Project name must be non-empty and contain only letters, digits, . _ or -');
+    err.code = 'BAD_NAME';
+    throw err;
+  }
+
+  const yaml = require('yaml');
+  let parsed = {};
+  if (fs.existsSync(configPath)) {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    try {
+      parsed = yaml.parse(raw) || {};
+    } catch (err) {
+      throw new Error(`config.yaml is not valid YAML — cannot safely rewrite: ${err.message}`);
+    }
+  }
+
+  if (!parsed.projects || typeof parsed.projects !== 'object' || !parsed.projects[name]) {
+    const err = new Error(`Project "${name}" not found in config.yaml`);
+    err.code = 'NOT_FOUND';
+    throw err;
+  }
+
+  delete parsed.projects[name];
+
+  if (fs.existsSync(configPath)) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const bak = `${configPath}.${ts}.bak`;
+    try {
+      fs.copyFileSync(configPath, bak);
+    } catch (err) {
+      console.warn('[config] Could not write backup before removing project:', err.message);
+    }
+  }
+
+  const out = yaml.stringify(parsed);
+  fs.writeFileSync(configPath, out, 'utf-8');
+  console.log(`[config] Removed project "${name}" (files on disk untouched)`);
+
+  return parsed.projects;
+}
+
 // Apply a structural patch to ~/.termdeck/config.yaml. Sprint 36 introduces
 // this for the dashboard RAG toggle (PATCH /api/config) but the helper is
 // generic — pass a deep partial of the config tree, every leaf in `patch` that
@@ -394,6 +442,7 @@ function updateConfig(patch, configPath = CONFIG_PATH) {
 module.exports = {
   loadConfig,
   addProject,
+  removeProject,
   updateConfig,
   // exported for tests / introspection
   _parseDotenv: parseDotenv,

package/packages/server/src/index.js

@@ -62,11 +62,13 @@ const { TranscriptWriter } = require('./transcripts');
 const { createHealthHandler, runPreflight } = require('./preflight');
 const { getFullHealth } = require('./health');
 const { themes, statusColors } = require('./themes');
-const { loadConfig, addProject, updateConfig } = require('./config');
+const { loadConfig, addProject, removeProject, updateConfig } = require('./config');
 const { createAuthMiddleware, verifyWebSocketUpgrade, hasAuth } = require('./auth');
 const { createSprintRoutes } = require('./sprint-routes');
 const { createGraphRoutes } = require('./graph-routes');
+const { createProjectsRoutes } = require('./projects-routes');
 const orchestrationPreview = require('./orchestration-preview');
+const { createPtyReaper } = require('./pty-reaper');
 
 // Sprint 37 T3 — lazy resolution of T2's CLI modules. The orchestration-preview
 // helper is decoupled from T2's templates.js / init-project.js; we resolve
@@ -167,6 +169,33 @@ function createServer(config) {
   // Initialize session manager
   const sessions = new SessionManager(db);
 
+  // PTY orphan reaper (Sprint 42 T2). Periodically walks the live process
+  // tree, tracks descendants of each session's shell PTY, and SIGTERMs any
+  // that survive the leader's death — closing the kern.tty.ptmx_max leak
+  // path that bit Joshua on 2026-04-28 (forkpty: Device not configured).
+  // Skipped when node-pty is unavailable (no PTYs to reap) and when the
+  // explicit kill switch is set (tests / opt-out).
+  const ptyReaperEnabled = pty
+    && process.env.TERMDECK_PTY_REAPER !== 'off'
+    && config.ptyReaper?.enabled !== false;
+  const ptyReaperIntervalMs = Number.parseInt(
+    process.env.TERMDECK_PTY_REAPER_INTERVAL_MS
+      || config.ptyReaper?.intervalMs
+      || 30000,
+    10
+  );
+  const ptyReaper = ptyReaperEnabled
+    ? createPtyReaper({ sessions, intervalMs: ptyReaperIntervalMs })
+    : null;
+  if (ptyReaper) {
+    ptyReaper.start();
+    console.log(`[pty-reaper] enabled (interval ${ptyReaperIntervalMs}ms)`);
+  } else if (!pty) {
+    console.log('[pty-reaper] disabled (node-pty unavailable)');
+  } else {
+    console.log('[pty-reaper] disabled by config');
+  }
+
   // Initialize RAG + Mnestra bridge
   const rag = new RAGIntegration(config, db);
   const mnestraBridge = createBridge(config);
@@ -1262,20 +1291,29 @@ function createServer(config) {
     res.json(payload);
   });
 
-  // POST /api/projects - add a new project on the fly, persist to config.yaml
-  // Body: { name, path, defaultTheme?, defaultCommand? }
-  // Updates both the on-disk config.yaml and the in-memory config so new
-  // sessions can select the project immediately without a server restart.
-  app.post('/api/projects', (req, res) => {
-    const { name, path: projectPath, defaultTheme, defaultCommand } = req.body || {};
-    try {
-      const updatedProjects = addProject({ name, path: projectPath, defaultTheme, defaultCommand });
-      config.projects = updatedProjects;
-      res.json({ ok: true, projects: updatedProjects });
-    } catch (err) {
-      console.error('[config] addProject failed:', err.message);
-      res.status(400).json({ error: err.message });
-    }
+  // POST /api/projects (add) + DELETE /api/projects/:name (remove) — Sprint 42
+  // T4 extracted both into projects-routes.js so tests can drive them without
+  // bootstrapping the full server. Sessions are passed via getSessions() so
+  // DELETE can enforce the 409 live-PTY guard. Files on disk at the project's
+  // `path` are NEVER touched by remove — only the YAML entry is rewritten.
+  createProjectsRoutes({
+    app,
+    config,
+    getSessions: () => sessions.getAll(),
+    addProject,
+    removeProject,
+    broadcast: (payload) => {
+      try {
+        const wsPayload = JSON.stringify(payload);
+        wss.clients.forEach((client) => {
+          if (client.readyState === 1) {
+            try { client.send(wsPayload); } catch (err) { console.error('[ws] projects_changed send failed:', err); }
+          }
+        });
+      } catch (err) {
+        console.error('[ws] projects_changed broadcast failed:', err);
+      }
+    },
   });
 
   // GET /api/projects/:name/orchestration-preview — Sprint 37 T3.
@@ -1404,6 +1442,20 @@ function createServer(config) {
     res.json({ count: events.length, events });
   });
 
+  // GET /api/pty-reaper/status — Sprint 42 T2 observability surface.
+  // Returns the live registry (per-session PTY pid + tracked descendants) and
+  // the reaped-history ring buffer so heavy-use installs can tell whether the
+  // reaper is firing and what it's killing. Read-only.
+  app.get('/api/pty-reaper/status', (req, res) => {
+    if (!ptyReaper) {
+      return res.json({
+        enabled: false,
+        reason: !pty ? 'node-pty-unavailable' : 'disabled-by-config',
+      });
+    }
+    res.json({ enabled: true, ...ptyReaper.status() });
+  });
+
   // ==================== Transcript endpoints (Sprint 6 T3) ====================
 
   // GET /api/transcripts/search - FTS across all sessions
@@ -1757,7 +1809,7 @@ function createServer(config) {
     res.sendFile(path.join(clientDir, 'index.html'));
   });
 
-  return { app, server, wss, sessions, rag, db, transcriptWriter };
+  return { app, server, wss, sessions, rag, db, transcriptWriter, ptyReaper };
 }
 
 // ==================== Setup-configure helpers (Sprint 23 T2) ====================
@@ -1975,7 +2027,7 @@ if (require.main === module) {
     }
   }
 
-  const { server, transcriptWriter } = createServer(config);
+  const { server, transcriptWriter, ptyReaper } = createServer(config);
 
   // Graceful shutdown — flush transcript buffer before exit
   let shutdownInProgress = false;
@@ -1983,6 +2035,11 @@ if (require.main === module) {
     if (shutdownInProgress) return;
     shutdownInProgress = true;
     console.log(`\n[server] ${signal} received, shutting down...`);
+    if (ptyReaper) {
+      try { ptyReaper.stop(); } catch (err) {
+        console.error('[pty-reaper] stop failed:', err.message);
+      }
+    }
     if (transcriptWriter) {
       console.log('[transcript] Flushing buffer before exit...');
       try { await transcriptWriter.close(); } catch (err) {

package/packages/server/src/projects-routes.js

@@ -0,0 +1,119 @@
+// Projects routes — POST /api/projects (add) + DELETE /api/projects/:name
+// (remove) extracted into a small factory so tests can drive them without
+// bootstrapping the full server. Sprint 42 T4.
+//
+// Surface contract:
+//
+//   POST   /api/projects                       → add (existing v0.2 behavior)
+//   DELETE /api/projects/:name[?force=true]    → remove
+//
+// DELETE semantics:
+//   - 404 if the project is not in config.yaml
+//   - 409 if any live PTY session has meta.project === name (i.e.
+//     meta.status !== 'exited'), unless ?force=true is set
+//   - On success: rewrites ~/.termdeck/config.yaml (with .bak), updates the
+//     in-memory config map, broadcasts `projects_changed` to all WS clients,
+//     and returns { ok, removed, projects, files_on_disk: 'untouched' }
+//
+// File contents at the project's `path` are NEVER touched here — the user's
+// source code stays put. The dashboard modal copy reflects this so users
+// don't fear data loss.
+
+function createProjectsRoutes({
+  app,
+  config,
+  getSessions,           // () => array of session objects with .meta.{project,status}
+  addProject,            // (opts) => updated projects map (mutates config.yaml)
+  removeProject,         // (name) => updated projects map (mutates config.yaml)
+  broadcast,             // ({ type, projects }) => void   (optional)
+}) {
+  if (!app) throw new Error('createProjectsRoutes: app is required');
+  if (typeof addProject !== 'function') throw new Error('createProjectsRoutes: addProject is required');
+  if (typeof removeProject !== 'function') throw new Error('createProjectsRoutes: removeProject is required');
+
+  const safeBroadcast = (payload) => {
+    if (typeof broadcast !== 'function') return;
+    try { broadcast(payload); }
+    catch (err) { console.error('[projects-routes] broadcast failed:', err); }
+  };
+
+  // POST /api/projects — add a project, persist to config.yaml, broadcast.
+  // Body: { name, path, defaultTheme?, defaultCommand? }
+  app.post('/api/projects', (req, res) => {
+    const { name, path: projectPath, defaultTheme, defaultCommand } = req.body || {};
+    try {
+      const updatedProjects = addProject({ name, path: projectPath, defaultTheme, defaultCommand });
+      config.projects = updatedProjects;
+      safeBroadcast({ type: 'projects_changed', projects: updatedProjects });
+      res.json({ ok: true, projects: updatedProjects });
+    } catch (err) {
+      console.error('[config] addProject failed:', err.message);
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  // DELETE /api/projects/:name — remove a project. ?force=true to override
+  // the live-session 409 guard. Files on disk are untouched.
+  app.delete('/api/projects/:name', (req, res) => {
+    const name = req.params.name;
+    if (!name || !/^[A-Za-z0-9_.-]+$/.test(name)) {
+      return res.status(400).json({ error: 'Project name must be non-empty and contain only letters, digits, . _ or -' });
+    }
+
+    const projects = (config && config.projects) || {};
+    if (!projects[name]) {
+      return res.status(404).json({ error: `Project "${name}" not found` });
+    }
+
+    const force = req.query && (req.query.force === 'true' || req.query.force === '1');
+
+    let liveSessions = [];
+    try {
+      const all = (typeof getSessions === 'function' ? getSessions() : []) || [];
+      liveSessions = all.filter((s) => {
+        if (!s || !s.meta) return false;
+        return s.meta.project === name && s.meta.status !== 'exited';
+      });
+    } catch (err) {
+      console.error('[projects-routes] getSessions failed:', err);
+      liveSessions = [];
+    }
+
+    if (liveSessions.length > 0 && !force) {
+      return res.status(409).json({
+        error: `Project "${name}" has ${liveSessions.length} live PTY session${liveSessions.length === 1 ? '' : 's'}. Close them first, or pass ?force=true.`,
+        liveSessions: liveSessions.length,
+        sessionIds: liveSessions.map((s) => s.id).filter(Boolean),
+      });
+    }
+
+    let updatedProjects;
+    try {
+      updatedProjects = removeProject(name);
+    } catch (err) {
+      if (err && err.code === 'NOT_FOUND') {
+        return res.status(404).json({ error: err.message });
+      }
+      if (err && err.code === 'BAD_NAME') {
+        return res.status(400).json({ error: err.message });
+      }
+      console.error('[config] removeProject failed:', err.message);
+      return res.status(500).json({ error: err.message });
+    }
+
+    config.projects = updatedProjects;
+    safeBroadcast({ type: 'projects_changed', projects: updatedProjects });
+
+    res.json({
+      ok: true,
+      removed: name,
+      forced: !!force,
+      projects: updatedProjects,
+      files_on_disk: 'untouched',
+    });
+  });
+}
+
+module.exports = {
+  createProjectsRoutes,
+};

package/packages/server/src/pty-reaper.js

@@ -0,0 +1,297 @@
+// PTY orphan reaper (Sprint 42 T2).
+//
+// Each TermDeck session spawns one shell PTY (`term.pid` from node-pty). That
+// shell typically forks Claude Code, which in turn forks MCP children
+// (rag-system, imessage-mcp, …). When the user closes a panel TermDeck calls
+// `term.kill()`, which delivers SIGHUP to the leader's process group — but
+// some MCPs `setsid` to detach, escape the pgroup, and survive the parent.
+// Reparented to launchd, those processes keep holding their PTY file
+// descriptors, and on macOS that drains `kern.tty.ptmx_max` (511 by default).
+// Joshua's 2026-04-28 morning incident: 585 PTY refs, `forkpty: Device not
+// configured` blocking new terminals.
+//
+// This module periodically (every 30s by default) walks the live process tree
+// and, for each known session, tracks descendants of its PTY leader. When the
+// leader is gone or the session has transitioned to `exited`, any descendants
+// that survived get SIGTERM'd and recorded to a ring buffer surfaced via
+// /api/pty-reaper/status.
+//
+// All side-effects (`ps`, `kill`, `now`, the timer) are injectable so the
+// tests in tests/pty-reaper.test.js can drive deterministic orphan scenarios
+// without forking real processes.
+//
+// Public surface:
+//   createPtyReaper({ sessions, intervalMs?, ps?, kill?, now?, logger? })
+//     → { start(), stop(), tick(), status(), _resetForTest() }
+
+const { execFileSync } = require('child_process');
+
+const RING_SIZE = 200;
+const DEFAULT_INTERVAL_MS = 30000;
+
+// Default `ps` boundary — execFileSync is sandbox-friendly (no shell).
+// `-e` lists every process; the trailing `=` on each column header suppresses
+// the header row, so the output is one process per line: "<pid> <ppid> <cmd>".
+function defaultPs() {
+  const stdout = execFileSync('ps', ['-e', '-o', 'pid=,ppid=,command='], {
+    encoding: 'utf8',
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  return parsePsOutput(stdout);
+}
+
+function parsePsOutput(stdout) {
+  const out = [];
+  const lines = stdout.split('\n');
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;
+    // Two leading whitespace-separated integers, then the rest is command.
+    const m = line.match(/^(\d+)\s+(\d+)\s+(.*)$/);
+    if (!m) continue;
+    const pid = parseInt(m[1], 10);
+    const ppid = parseInt(m[2], 10);
+    if (!Number.isFinite(pid) || !Number.isFinite(ppid)) continue;
+    out.push({ pid, ppid, command: m[3] });
+  }
+  return out;
+}
+
+function defaultKill(pid, signal) {
+  process.kill(pid, signal);
+}
+
+function createPtyReaper({
+  sessions,
+  intervalMs = DEFAULT_INTERVAL_MS,
+  ps = defaultPs,
+  kill = defaultKill,
+  now = Date.now,
+  logger = console,
+} = {}) {
+  if (!sessions) {
+    throw new Error('createPtyReaper: sessions (SessionManager) is required');
+  }
+
+  // Per-session registry: sessionId → { ptyPid, descendants:Set<pid>,
+  // firstSeenAt, lastSeenAliveAt }. Refreshed each tick while the leader is
+  // alive so when it dies we still know which descendants to chase.
+  const registry = new Map();
+  let reapedHistory = [];
+  let tickCount = 0;
+  let lastTickAt = null;
+  let lastError = null;
+  let timer = null;
+
+  function isoNow() {
+    return new Date(now()).toISOString();
+  }
+
+  function recordReap(entry) {
+    reapedHistory.push(entry);
+    if (reapedHistory.length > RING_SIZE) {
+      reapedHistory = reapedHistory.slice(-RING_SIZE);
+    }
+  }
+
+  function bfsDescendants(rootPid, childrenByPpid) {
+    const out = new Set();
+    const stack = [rootPid];
+    const seen = new Set([rootPid]);
+    while (stack.length) {
+      const cur = stack.pop();
+      const kids = childrenByPpid.get(cur);
+      if (!kids) continue;
+      for (const kid of kids) {
+        if (seen.has(kid.pid)) continue;
+        seen.add(kid.pid);
+        out.add(kid.pid);
+        stack.push(kid.pid);
+      }
+    }
+    return out;
+  }
+
+  function iterSessions() {
+    // SessionManager.sessions is a Map<id, Session>; iterate the values
+    // directly so we get the live Session instances (not toJSON copies).
+    if (sessions.sessions && typeof sessions.sessions.values === 'function') {
+      return Array.from(sessions.sessions.values());
+    }
+    return [];
+  }
+
+  function tick() {
+    tickCount += 1;
+    lastTickAt = isoNow();
+
+    let snapshot;
+    try {
+      snapshot = ps();
+    } catch (err) {
+      lastError = err && err.message ? err.message : String(err);
+      if (logger && logger.error) {
+        logger.error('[pty-reaper] ps() failed:', lastError);
+      }
+      return { reaped: 0, refreshed: 0, error: lastError };
+    }
+
+    if (!Array.isArray(snapshot)) snapshot = [];
+    const livePids = new Set();
+    const procByPid = new Map();
+    const childrenByPpid = new Map();
+    for (const proc of snapshot) {
+      if (!proc || !Number.isFinite(proc.pid)) continue;
+      livePids.add(proc.pid);
+      procByPid.set(proc.pid, proc);
+      const kids = childrenByPpid.get(proc.ppid);
+      if (kids) kids.push(proc);
+      else childrenByPpid.set(proc.ppid, [proc]);
+    }
+
+    let refreshed = 0;
+    let reaped = 0;
+    const liveSessionIds = new Set();
+
+    // Pass 1: refresh registry for every known session whose leader is alive.
+    for (const session of iterSessions()) {
+      if (!session || !session.id) continue;
+      liveSessionIds.add(session.id);
+      const ptyPid = session.pid;
+      if (!Number.isFinite(ptyPid)) continue;
+
+      const leaderAlive = livePids.has(ptyPid);
+      const exited = session.meta && session.meta.status === 'exited';
+
+      if (leaderAlive && !exited) {
+        const descendants = bfsDescendants(ptyPid, childrenByPpid);
+        const existing = registry.get(session.id);
+        registry.set(session.id, {
+          ptyPid,
+          descendants,
+          firstSeenAt: existing ? existing.firstSeenAt : isoNow(),
+          lastSeenAliveAt: isoNow(),
+        });
+        refreshed += 1;
+      }
+    }
+
+    // Pass 2: for each registry entry whose leader has died OR whose session
+    // has transitioned to 'exited' (or whose Session has been removed from
+    // the manager entirely), kill any descendants still alive and drop the
+    // entry. We rely on the descendant snapshot captured by the most recent
+    // refresh — once the leader is reaped we can't BFS from a dead pid.
+    for (const [sessionId, entry] of Array.from(registry.entries())) {
+      const session = sessions.get ? sessions.get(sessionId) : null;
+      const stillRegistered = liveSessionIds.has(sessionId);
+      const leaderAlive = livePids.has(entry.ptyPid);
+      const exited = session && session.meta && session.meta.status === 'exited';
+
+      if (stillRegistered && leaderAlive && !exited) continue;
+
+      const reason = !leaderAlive
+        ? 'leader_dead'
+        : exited
+          ? 'session_exited'
+          : 'session_removed';
+
+      for (const descPid of entry.descendants) {
+        if (!livePids.has(descPid)) continue;
+        const meta = procByPid.get(descPid) || { pid: descPid, ppid: null, command: '' };
+        try {
+          kill(descPid, 'SIGTERM');
+          recordReap({
+            ts: isoNow(),
+            sessionId,
+            ptyPid: entry.ptyPid,
+            pid: descPid,
+            ppid: meta.ppid,
+            command: (meta.command || '').slice(0, 200),
+            reason,
+            outcome: 'signaled',
+          });
+          reaped += 1;
+        } catch (err) {
+          // ESRCH = already dead; anything else we record but don't throw.
+          const code = err && err.code ? err.code : null;
+          recordReap({
+            ts: isoNow(),
+            sessionId,
+            ptyPid: entry.ptyPid,
+            pid: descPid,
+            ppid: meta.ppid,
+            command: (meta.command || '').slice(0, 200),
+            reason,
+            outcome: code === 'ESRCH' ? 'already_dead' : 'kill_failed',
+            error: err && err.message ? err.message : String(err),
+          });
+        }
+      }
+      registry.delete(sessionId);
+    }
+
+    return { reaped, refreshed, error: null };
+  }
+
+  function start() {
+    if (timer) return;
+    timer = setInterval(() => {
+      try {
+        tick();
+      } catch (err) {
+        lastError = err && err.message ? err.message : String(err);
+        if (logger && logger.error) {
+          logger.error('[pty-reaper] tick() threw:', lastError);
+        }
+      }
+    }, intervalMs);
+    if (typeof timer.unref === 'function') timer.unref();
+  }
+
+  function stop() {
+    if (timer) {
+      clearInterval(timer);
+      timer = null;
+    }
+  }
+
+  function status() {
+    const registrySnapshot = [];
+    for (const [sessionId, entry] of registry) {
+      registrySnapshot.push({
+        sessionId,
+        ptyPid: entry.ptyPid,
+        descendantPids: Array.from(entry.descendants),
+        firstSeenAt: entry.firstSeenAt,
+        lastSeenAliveAt: entry.lastSeenAliveAt,
+      });
+    }
+    return {
+      tickCount,
+      lastTickAt,
+      intervalMs,
+      lastError,
+      registry: registrySnapshot,
+      reapedCount: reapedHistory.length,
+      reapedHistory: reapedHistory.slice(),
+    };
+  }
+
+  function _resetForTest() {
+    stop();
+    registry.clear();
+    reapedHistory = [];
+    tickCount = 0;
+    lastTickAt = null;
+    lastError = null;
+  }
+
+  return { start, stop, tick, status, _resetForTest };
+}
+
+module.exports = {
+  createPtyReaper,
+  parsePsOutput,
+  RING_SIZE,
+  DEFAULT_INTERVAL_MS,
+};

package/packages/server/src/setup/index.js

@@ -10,6 +10,7 @@ module.exports = {
   yaml: require('./yaml-io'),
   supabaseUrl: require('./supabase-url'),
   migrations: require('./migrations'),
+  migrationTemplating: require('./migration-templating'),
   pgRunner: require('./pg-runner'),
   migrationRunner: require('./migration-runner'),
   preconditions: require('./preconditions')

package/packages/server/src/setup/migration-templating.js

@@ -0,0 +1,76 @@
+// Migration SQL templating helper.
+//
+// Several Rumen migrations ship with placeholder markers for values that
+// can only be resolved at apply-time: the user's Supabase project ref,
+// service-role JWT name, etc. Migration 002 (rumen-tick schedule) and 003
+// (graph-inference-tick schedule) both embed the project ref inside the
+// pg_cron body that calls `net.http_post` on
+// `https://<project-ref>.supabase.co/functions/v1/<name>`.
+//
+// Pre-Sprint 42, init-rumen.js::applySchedule did this substitution inline
+// for migration 002 only — and migration 003 (added Sprint 38) shipped its
+// `<project-ref>` placeholder unsubstituted. Sprint 42 T3 extracts the
+// substitution into this shared helper so every migration that lists a
+// known placeholder gets templated consistently.
+//
+// Supported placeholder syntaxes (both accepted; legacy + sigil-style):
+//   <project-ref>
+//   {{PROJECT_REF}}
+//
+// API:
+//   applyTemplating(sql, vars)
+//     sql:  string — raw migration body
+//     vars: { projectRef?: string }
+//   returns: string — substituted body
+//   throws:  Error — when SQL contains a placeholder but `vars` lacks the
+//            corresponding value. (Quietly leaving the placeholder in
+//            would let an unsubstituted URL ship to pg_cron, which is the
+//            very bug this module exists to prevent.)
+//
+// Idempotent: applying twice yields the same string. Safe on SQL with no
+// placeholders (returns the input unchanged).
+
+'use strict';
+
+const PLACEHOLDER_SYNTAXES = Object.freeze({
+  projectRef: [/<project-ref>/g, /\{\{PROJECT_REF\}\}/g],
+});
+
+function hasPlaceholder(sql, patterns) {
+  for (const pat of patterns) {
+    pat.lastIndex = 0;
+    if (pat.test(sql)) return true;
+  }
+  return false;
+}
+
+function substitute(sql, patterns, value) {
+  let out = sql;
+  for (const pat of patterns) {
+    out = out.replace(pat, value);
+  }
+  return out;
+}
+
+function applyTemplating(sql, vars) {
+  if (typeof sql !== 'string') {
+    throw new TypeError('applyTemplating: sql must be a string');
+  }
+  const v = vars || {};
+  let out = sql;
+
+  for (const [varName, patterns] of Object.entries(PLACEHOLDER_SYNTAXES)) {
+    if (!hasPlaceholder(out, patterns)) continue;
+    const value = v[varName];
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new Error(
+        `applyTemplating: SQL contains ${varName} placeholder but vars.${varName} is missing or empty. ` +
+        `Refusing to ship an unsubstituted placeholder to the database.`
+      );
+    }
+    out = substitute(out, patterns, value);
+  }
+  return out;
+}
+
+module.exports = { applyTemplating, PLACEHOLDER_SYNTAXES };