@smartmemory/compose 0.3.6-beta → 0.3.8

package/server/ideabox-routes.js

@@ -1,58 +1,75 @@
 /**
  * server/ideabox-routes.js — REST API for the ideabox feature.
  *
+ * COMP-PLAN-IDEA-UNIFY S3b-2: this module reads and writes FLUID RECORDS.
+ *
  * Routes:
- *   GET    /api/ideabox                  — return parsed ideabox JSON (cached)
- *   POST   /api/ideabox/ideas            — add new idea
- *   PATCH  /api/ideabox/ideas/:id        — update priority/status/etc.
- *   POST   /api/ideabox/ideas/:id/promote — promote to feature
- *   POST   /api/ideabox/ideas/:id/kill   — kill with reason
- *   DELETE /api/ideabox/ideas/:id        — not allowed (use kill)
+ *   GET    /api/ideabox                     — the whole ideabox, from the records
+ *   POST   /api/ideabox/ideas               — capture a new idea
+ *   PATCH  /api/ideabox/ideas/:id           — edit fields (priority, effort, impact, …)
+ *   POST   /api/ideabox/ideas/:id/promote   — promote to a feature
+ *   POST   /api/ideabox/ideas/:id/kill      — kill with a reason
+ *   POST   /api/ideabox/ideas/:id/resurrect — return a killed idea to the live set
+ *   POST   /api/ideabox/ideas/:id/discuss   — append to the deliberation trail
+ *   DELETE /api/ideabox/ideas/:id           — not allowed (use kill)
+ *
+ * WHAT S3b-1 LEFT HERE AND WHY IT IS GONE
+ * ---------------------------------------
+ * S3b-1 cut the CLI over to the record store and closed all six mutating
+ * handlers with a 409, because they rewrote `docs/product/ideabox.md` directly
+ * and that file had just become generated output: an idea saved here would have
+ * reported success, been overwritten by the next render, and taken the user's
+ * text with it. Failing closed was the honest interim state. This slice replaces
+ * it with real handlers rather than restoring the old bodies.
+ *
+ * EVERY MUTATION GOES THROUGH `fluid/ideabox-ops.js`, WHICH THE CLI ALSO USES.
+ * Not "the same way the CLI does" — the same code. Two call sites that each had
+ * to remember to run the migration gate before writing, and to re-render after,
+ * would drift exactly the way `smartmemory-provider.js` drifted from
+ * `local-provider.js` in S3b-1: satisfying the interface completely while
+ * silently missing a guarantee.
+ *
+ * Responses come from `fluid/ideabox-view.js`, which projects records into the
+ * shape the cockpit and the mobile app have always consumed (`id` is the handle,
+ * `description` is the body, an untriaged priority is an em dash).
  */
 
 import fs from 'node:fs'
 import path from 'node:path'
+
 import {
-  readIdeabox,
-  writeIdeabox,
+  ideaboxContext,
   addIdea,
-  promoteIdea,
+  addDiscussion,
   killIdea,
+  promoteIdea,
   resurrectIdea,
-  setPriority,
   updateIdea,
-  addDiscussion,
-} from '../lib/ideabox.js'
-import { writeFeature } from '../lib/feature-json.js'
-import { IdeaboxCache } from './ideabox-cache.js'
-import { resolveIdeaboxPathFromConfig, resolveFeaturesPathFromConfig, relForDisplay } from '../lib/project-paths.js'
+  IdeaboxConflict,
+  IdeaboxInvalid,
+  IdeaboxNotFound,
+  IdeaboxRenderFailed,
+} from '../lib/fluid/ideabox-ops.js'
+import { writeIdeaboxProjection } from '../lib/fluid/render-ideabox.js'
+import { ideaboxView, toClientIdeaWith } from '../lib/fluid/ideabox-view.js'
+import { relForDisplay } from '../lib/project-paths.js'
 
 /**
  * @param {object} app              — Express app
  * @param {{ getProjectRoot, getDataDir, broadcastMessage }} deps
  */
-export function attachIdeaboxRoutes(app, { getProjectRoot, getDataDir, broadcastMessage }) {
-  // Lazily created per project root — we need to handle project switches
-  let _cache = null
-  let _lastProjectRoot = null
-  let _lastDataDir = null
-
-  function getCache() {
+export function attachIdeaboxRoutes(app, { getProjectRoot, broadcastMessage }) {
+  /**
+   * A fresh context per request, deliberately.
+   *
+   * The provider holds paths, not state — every handle lookup re-reads the
+   * records directory and the events log — so caching one would buy nothing and
+   * cost correctness the moment the project root changes underneath a long-lived
+   * server, which is the case this file has always had to handle.
+   */
+  function context() {
     const projectRoot = getProjectRoot()
-    const dataDir = getDataDir()
-    if (!_cache || _lastProjectRoot !== projectRoot || _lastDataDir !== dataDir) {
-      const config = loadConfig(projectRoot)
-      const sourceFile = resolveIdeaboxPathFromConfig(projectRoot, config)
-      _cache = new IdeaboxCache(dataDir, sourceFile)
-      _lastProjectRoot = projectRoot
-      _lastDataDir = dataDir
-    }
-    return _cache
-  }
-
-  function getIdeaboxPath(projectRoot) {
-    const config = loadConfig(projectRoot)
-    return config?.paths?.ideabox || 'docs/product/ideabox.md'
+    return ideaboxContext(projectRoot, { config: loadConfig(projectRoot) ?? {}, origin: 'ui:ideabox' })
   }
 
   function broadcastUpdate() {
@@ -61,220 +78,145 @@ export function attachIdeaboxRoutes(app, { getProjectRoot, getDataDir, broadcast
     }
   }
 
-  // GET /api/ideabox
-  app.get('/api/ideabox', (_req, res) => {
+  /**
+   * Map an op failure onto HTTP.
+   *
+   * `IdeaboxRenderFailed` is deliberately NOT an error response. The record is
+   * durable; only the generated markdown is stale. Both clients roll their
+   * optimistic update back on any non-ok response, so reporting a failure here
+   * would make a committed idea vanish from the UI and invite the user to type
+   * it again — producing the duplicate the whole record store exists to prevent.
+   * It is answered as a success carrying `projectionStale`, so a client that
+   * wants to surface the staleness can, and one that ignores unknown fields
+   * behaves correctly by default.
+   */
+  async function send(res, run, okStatus = 200) {
     try {
-      const cache = getCache()
-      const data = cache.get()
-      res.json(data)
+      const { body, broadcast = true } = await run()
+      if (broadcast) broadcastUpdate()
+      res.status(okStatus).json(body)
     } catch (err) {
-      res.status(500).json({ error: err.message })
+      if (err instanceof IdeaboxRenderFailed) {
+        // The write landed. Tell the truth about both halves.
+        broadcastUpdate()
+        const idea = err.record ? await safeIdea(err.record) : null
+        return res.status(okStatus).json({
+          ...(idea ?? {}),
+          projectionStale: true,
+          warning: err.message,
+        })
+      }
+      if (err instanceof IdeaboxNotFound) return res.status(404).json({ error: err.message, code: err.code })
+      if (err instanceof IdeaboxInvalid) return res.status(400).json({ error: err.message, code: err.code, field: err.field })
+      if (err instanceof IdeaboxConflict) return res.status(409).json({ error: err.message, code: err.code })
+      return res.status(500).json({ error: err.message })
     }
-  })
+  }
 
-  // POST /api/ideabox/ideas
-  app.post('/api/ideabox/ideas', (req, res) => {
+  /** Best-effort client projection for the render-failed path, which must not
+   *  fail a second time on the way out. */
+  async function safeIdea(record) {
     try {
-      const { title, description, source, tags, cluster } = req.body || {}
-      if (!title) return res.status(400).json({ error: 'title is required' })
+      const ctx = await context()
+      return await toClientIdeaWith(ctx.provider, record)
+    } catch {
+      return null
+    }
+  }
 
-      const projectRoot = getProjectRoot()
-      const ideaboxPath = getIdeaboxPath(projectRoot)
-      const parsed = readIdeabox(projectRoot, ideaboxPath)
-      addIdea(parsed, { title, description, source, tags, cluster })
-      writeIdeabox(projectRoot, ideaboxPath, parsed)
-      getCache().invalidate()
-      broadcastUpdate()
-      // Return the newly created idea
-      const newIdea = parsed.ideas[parsed.ideas.length - 1]
-      res.status(201).json(newIdea)
+  // GET /api/ideabox — served from the records, per the feature's acceptance
+  // criterion. NOT from `docs/product/ideabox.md`: that file is a local
+  // projection, and on a store shared across machines (the SmartMemory
+  // provider) a write on one machine never regenerates another's copy, so
+  // reading it would serve an indefinitely stale view of a current store.
+  app.get('/api/ideabox', async (_req, res) => {
+    try {
+      const ctx = await context()
+      res.json(await ideaboxView(ctx.provider))
     } catch (err) {
       res.status(500).json({ error: err.message })
     }
   })
 
-  // PATCH /api/ideabox/ideas/:id
-  app.patch('/api/ideabox/ideas/:id', (req, res) => {
-    try {
-      const { id } = req.params
-      const fields = req.body || {}
-
-      const projectRoot = getProjectRoot()
-      const ideaboxPath = getIdeaboxPath(projectRoot)
-      const parsed = readIdeabox(projectRoot, ideaboxPath)
-
-      // Handle priority shortcut
-      if (fields.priority) {
-        setPriority(parsed, id, fields.priority)
-        delete fields.priority
-      }
-
-      // Reject status changes via PATCH — must use /promote or /kill endpoints
-      // to ensure proper transition logic (move to killed section, set fields, etc.)
-      if (fields.status !== undefined) {
-        return res.status(400).json({
-          error: 'Status changes must go through /promote or /kill endpoints, not PATCH'
-        })
-      }
-
-      // Handle remaining fields (no status)
-      const allowed = ['title', 'description', 'source', 'tags', 'cluster', 'mapsTo', 'effort', 'impact']
-      const safeFields = {}
-      for (const k of allowed) {
-        if (fields[k] !== undefined) safeFields[k] = fields[k]
-      }
-      // Validate enum fields
-      if (safeFields.effort !== undefined && safeFields.effort !== null && !['S', 'M', 'L'].includes(safeFields.effort)) {
-        return res.status(400).json({ error: 'effort must be S, M, L, or null' })
-      }
-      if (safeFields.impact !== undefined && safeFields.impact !== null && !['low', 'medium', 'high'].includes(safeFields.impact)) {
-        return res.status(400).json({ error: 'impact must be low, medium, high, or null' })
-      }
-      if (Object.keys(safeFields).length > 0) {
-        updateIdea(parsed, id, safeFields)
-      }
-
-      writeIdeabox(projectRoot, ideaboxPath, parsed)
-      getCache().invalidate()
-      broadcastUpdate()
+  // POST /api/ideabox/ideas
+  app.post('/api/ideabox/ideas', async (req, res) => {
+    const { title, description, source, tags, cluster } = req.body || {}
+    await send(res, async () => {
+      const ctx = await context()
+      const { record } = await addIdea(ctx, { title, body: description, source, tags, cluster })
+      return { body: await toClientIdeaWith(ctx.provider, record) }
+    }, 201)
+  })
 
-      // Find and return the updated idea
-      const upper = id.toUpperCase()
-      const updated = [...parsed.ideas, ...parsed.killed].find(i => i.id.toUpperCase() === upper)
-      res.json(updated || { id })
-    } catch (err) {
-      const status = err.message.includes('not found') ? 404 : 500
-      res.status(status).json({ error: err.message })
-    }
+  // PATCH /api/ideabox/ideas/:id
+  app.patch('/api/ideabox/ideas/:id', async (req, res) => {
+    await send(res, async () => {
+      const ctx = await context()
+      const { record } = await updateIdea(ctx, req.params.id, req.body || {})
+      return { body: await toClientIdeaWith(ctx.provider, record) }
+    })
   })
 
   // POST /api/ideabox/ideas/:id/promote
-  app.post('/api/ideabox/ideas/:id/promote', (req, res) => {
-    try {
-      const { id } = req.params
-      const { featureCode } = req.body || {}
-
-      const projectRoot = getProjectRoot()
-      const ideaboxPath = getIdeaboxPath(projectRoot)
-      const parsed = readIdeabox(projectRoot, ideaboxPath)
-
-      // Find the idea before promoting (need title for feature folder seed)
-      const upper = id.toUpperCase()
-      const sourceIdea = parsed.ideas.find(i => i.id.toUpperCase() === upper)
-      if (!sourceIdea) {
-        return res.status(404).json({ error: `Idea not found: ${id}` })
-      }
-
-      // Resolve feature code: explicit, or derived from idea
-      let resolvedCode = featureCode
-      if (!resolvedCode) {
-        const slug = sourceIdea.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 20).replace(/-+$/, '')
-        resolvedCode = `IDEA-${sourceIdea.num}-${slug}`.toUpperCase()
-      }
-
-      // Create feature folder + feature.json (same logic as CLI promote).
-      // COMP-PATHS-EXTERNAL: resolve the ABSOLUTE features base (may be
-      // relocated outside projectRoot). Re-rooting under projectRoot would make
-      // existsSync check the wrong path and risk overwriting external canon.
-      const composeJsonPath = path.join(projectRoot, '.compose', 'compose.json')
-      let cfg = {}
-      if (fs.existsSync(composeJsonPath)) {
-        try { cfg = JSON.parse(fs.readFileSync(composeJsonPath, 'utf-8')) } catch {}
-      }
-      const featuresBase = resolveFeaturesPathFromConfig(projectRoot, cfg)  // absolute
-      const featuresDir = path.join(featuresBase, resolvedCode)
-      if (!fs.existsSync(featuresDir)) {
-        // COMP-MCP-VALIDATE-1: route through the validated writer instead of a
-        // raw fs.writeFileSync so the promoted feature.json is schema-guarded.
-        writeFeature(projectRoot, {
-          code: resolvedCode,
-          description: sourceIdea.title,
-          status: 'PLANNED',
-          promotedFrom: sourceIdea.id,
-          createdAt: new Date().toISOString(),
-        }, featuresBase)
+  app.post('/api/ideabox/ideas/:id/promote', async (req, res) => {
+    await send(res, async () => {
+      const ctx = await context()
+      const { record, featureCode, featurePath } = await promoteIdea(
+        ctx, req.params.id, (req.body || {}).featureCode || ''
+      )
+      // `featureCode` and `featurePath` are a promotion-specific envelope around
+      // the idea, not fields of it. The mobile client reads `result.featureCode`
+      // to name what it just created, and it matters most in exactly the case
+      // where the client did not supply one and the server derived it.
+      return {
+        body: {
+          ...(await toClientIdeaWith(ctx.provider, record)),
+          featureCode,
+          featurePath: relForDisplay(ctx.cwd, featurePath),
+        },
       }
-
-      promoteIdea(parsed, id, resolvedCode)
-      writeIdeabox(projectRoot, ideaboxPath, parsed)
-      getCache().invalidate()
-      broadcastUpdate()
-
-      const updated = parsed.ideas.find(i => i.id.toUpperCase() === upper)
-      res.json({ ...(updated || { id }), featureCode: resolvedCode, featurePath: relForDisplay(projectRoot, featuresDir) })
-    } catch (err) {
-      const status = err.message.includes('not found') ? 404 : 500
-      res.status(status).json({ error: err.message })
-    }
+    })
   })
 
   // POST /api/ideabox/ideas/:id/kill
-  app.post('/api/ideabox/ideas/:id/kill', (req, res) => {
-    try {
-      const { id } = req.params
-      const { reason } = req.body || {}
-
-      const projectRoot = getProjectRoot()
-      const ideaboxPath = getIdeaboxPath(projectRoot)
-      const parsed = readIdeabox(projectRoot, ideaboxPath)
-      killIdea(parsed, id, reason || '')
-      writeIdeabox(projectRoot, ideaboxPath, parsed)
-      getCache().invalidate()
-      broadcastUpdate()
-
-      const upper = id.toUpperCase()
-      const killed = parsed.killed.find(i => i.id.toUpperCase() === upper)
-      res.json(killed || { id })
-    } catch (err) {
-      const status = err.message.includes('not found') ? 404 : 500
-      res.status(status).json({ error: err.message })
-    }
+  app.post('/api/ideabox/ideas/:id/kill', async (req, res) => {
+    await send(res, async () => {
+      const ctx = await context()
+      const { record } = await killIdea(ctx, req.params.id, (req.body || {}).reason || '')
+      return { body: await toClientIdeaWith(ctx.provider, record) }
+    })
   })
 
   // POST /api/ideabox/ideas/:id/resurrect
-  app.post('/api/ideabox/ideas/:id/resurrect', (req, res) => {
-    try {
-      const { id } = req.params
-      const projectRoot = getProjectRoot()
-      const ideaboxPath = getIdeaboxPath(projectRoot)
-      const parsed = readIdeabox(projectRoot, ideaboxPath)
-      resurrectIdea(parsed, id)
-      writeIdeabox(projectRoot, ideaboxPath, parsed)
-      getCache().invalidate()
-      broadcastUpdate()
-
-      const upper = id.toUpperCase()
-      const restored = parsed.ideas.find(i => i.id.toUpperCase() === upper)
-      res.json(restored || { id })
-    } catch (err) {
-      const status = err.message.includes('not found') ? 404 : 500
-      res.status(status).json({ error: err.message })
-    }
+  app.post('/api/ideabox/ideas/:id/resurrect', async (req, res) => {
+    await send(res, async () => {
+      const ctx = await context()
+      const { record } = await resurrectIdea(ctx, req.params.id)
+      return { body: await toClientIdeaWith(ctx.provider, record) }
+    })
   })
 
   // POST /api/ideabox/ideas/:id/discuss
-  app.post('/api/ideabox/ideas/:id/discuss', (req, res) => {
-    try {
-      const { id } = req.params
-      const { author, text } = req.body || {}
-      if (!author) return res.status(400).json({ error: 'author is required' })
-      if (!text) return res.status(400).json({ error: 'text is required' })
-
-      const projectRoot = getProjectRoot()
-      const ideaboxPath = getIdeaboxPath(projectRoot)
-      const parsed = readIdeabox(projectRoot, ideaboxPath)
-      addDiscussion(parsed, id, author, text)
-      writeIdeabox(projectRoot, ideaboxPath, parsed)
-      getCache().invalidate()
-      broadcastUpdate()
+  app.post('/api/ideabox/ideas/:id/discuss', async (req, res) => {
+    const { author, text } = req.body || {}
+    if (!author) return res.status(400).json({ error: 'author is required' })
+    await send(res, async () => {
+      const ctx = await context()
+      const { record } = await addDiscussion(ctx, req.params.id, { author, text })
+      return { body: await toClientIdeaWith(ctx.provider, record) }
+    }, 201)
+  })
 
-      const upper = id.toUpperCase()
-      const updated = [...parsed.ideas, ...parsed.killed].find(i => i.id.toUpperCase() === upper)
-      res.status(201).json(updated || { id })
-    } catch (err) {
-      const status = err.message.includes('not found') ? 404 : 500
-      res.status(status).json({ error: err.message })
-    }
+  // POST /api/ideabox/render — rebuild the projection from the records (the
+  // repair for a landed-unrendered write: the durable record is fine, only the
+  // generated file is stale). The HTTP twin of `compose ideabox render`;
+  // touches no record. (FOH-6 S4 — the colleague panel's repair affordance.)
+  app.post('/api/ideabox/render', async (_req, res) => {
+    await send(res, async () => {
+      const ctx = await context()
+      await writeIdeaboxProjection(ctx.provider, ctx.ideaboxPath)
+      return { body: { ok: true } }
+    })
   })
 
   // DELETE /api/ideabox/ideas/:id — not allowed