@smartmemory/compose 0.3.6-beta → 0.3.8

package/lib/fluid/ideabox-view.js

@@ -0,0 +1,146 @@
+/**
+ * lib/fluid/ideabox-view.js — fluid records → the ideabox's client-facing shape.
+ *
+ * COMP-PLAN-IDEA-UNIFY S3b-2 (D21, reversed after review).
+ *
+ * THE ONE MAPPING
+ * ---------------
+ * `/api/ideabox` and every mutation response are produced HERE, from records.
+ * The first draft of this slice derived them by parsing the markdown projection
+ * the write had just rendered — one shape, reusing a proven parser, no second
+ * adapter to drift. That was wrong for two reasons that outrank tidiness:
+ *
+ *   1. **The feature's acceptance criterion says otherwise** ("`useIdeaboxStore`
+ *      / `/api/ideabox` serve from fluid records", design.md). Parsing the
+ *      projection is serving from a rendering of the records, which is not the
+ *      same claim.
+ *   2. **It is only correct on the local provider.** The projection is a LOCAL
+ *      file. Configure the SmartMemory provider — a store shared across machines
+ *      — and a write on machine A never regenerates machine B's markdown, so B's
+ *      REST and UI serve an indefinitely stale view of a store that is perfectly
+ *      up to date. Fidelity of the projection says nothing about its freshness.
+ *
+ * The cost of this direction is the one the first draft was avoiding: this file
+ * is a second place where a record's fields become a client's fields, and a
+ * field added to the record contract but not here is invisible to the cockpit.
+ * That is bounded by a test asserting this projection and the markdown one carry
+ * the same field set, so the two cannot silently disagree.
+ *
+ * WHY THE SHAPE IS THE LEGACY PARSER'S AND NOT THE RECORD'S
+ * --------------------------------------------------------
+ * `id` here is the record's HANDLE (`IDEA-42`), not its `id` (a provider UUID
+ * that changes on a provider swap). Every client keys on the handle and always
+ * has. `description` is the record's `body`, `status` is the uppercase display
+ * token, and an untriaged priority is an em dash rather than null. Returning raw
+ * records would have been cleaner and would have broken the cockpit, the mobile
+ * app and their tests in the same commit.
+ */
+
+import { toMarkdownDate } from './ideabox-dates.js';
+import { KIND } from './provider.js';
+
+/** Canonical status → the display token the surfaces have always rendered. */
+const STATUS_TOKEN = Object.freeze({
+  new: 'NEW',
+  discussing: 'DISCUSSING',
+  promoted: 'PROMOTED',
+  killed: 'KILLED',
+});
+
+/** The numeric suffix of a handle, which clients sort and display as `num`. */
+export function handleNumber(handle) {
+  const m = /-([0-9]+)$/.exec(handle ?? '');
+  return m ? Number(m[1]) : 0;
+}
+
+/**
+ * One record → one client idea.
+ *
+ * @param {object} record a normalized fluid record
+ * @param {Map<string,string>} clusterTitles handle → display title. Clients show
+ *   and filter on the cluster's NAME, which is what the markdown surface always
+ *   gave them; the record stores a handle so that renaming an umbrella does not
+ *   orphan its members. Resolution happens here rather than at the call site so
+ *   no caller can forget it and leak `CLUS-3` into the UI.
+ */
+export function toClientIdea(record, clusterTitles = new Map()) {
+  return {
+    id: record.handle,
+    num: handleNumber(record.handle),
+    title: record.title,
+    // `status_label` preserves what an author wrote when the canonical enum
+    // could not hold it (`RE-AIMED (2026-07-21)`); the markdown surface shows
+    // that token, so this one must too.
+    status: record.status_label || STATUS_TOKEN[record.status] || 'NEW',
+    priority: record.priority ?? '—',
+    tags: [...(record.tags ?? [])],
+    source: record.source ?? '',
+    description: record.body ?? '',
+    cluster: record.cluster ? clusterTitles.get(record.cluster) ?? record.cluster : null,
+    clusterHandle: record.cluster ?? null,
+    mapsTo: record.links?.find((l) => l.type === 'maps_to')?.target ?? '',
+    promotedTo: record.links?.find((l) => l.type === 'promoted_to')?.target ?? '',
+    effort: record.effort ?? null,
+    impact: record.impact ?? null,
+    killedReason: record.killed?.reason ?? '',
+    killedDate: record.killed ? toMarkdownDate(record.killed.at) : '',
+    discussion: (record.discussion ?? []).map((d) => ({
+      date: toMarkdownDate(d.at),
+      author: d.author ?? 'unknown',
+      text: d.text,
+    })),
+  };
+}
+
+/** Cluster handle → title, for `toClientIdea`. */
+export function clusterTitleMap(clusters) {
+  return new Map((clusters ?? []).map((c) => [c.handle, c.title]));
+}
+
+/**
+ * The whole `/api/ideabox` payload, read from the provider.
+ *
+ * Live and killed ideas are separate arrays because that is the split every
+ * client already renders, and `nextId` is derived rather than stored — the
+ * markdown parser computed it the same way, and a stored counter would be a
+ * second allocator disagreeing with the provider's.
+ *
+ * @param {import('./provider.js').FluidProvider} provider
+ */
+export async function ideaboxView(provider) {
+  const [ideas, clusters] = await Promise.all([
+    provider.listRecords({ kind: KIND.IDEA }),
+    provider.listRecords({ kind: KIND.CLUSTER }),
+  ]);
+
+  const titles = clusterTitleMap(clusters);
+  const byHandle = (a, b) => handleNumber(a.handle) - handleNumber(b.handle);
+  const ordered = [...ideas].sort(byHandle);
+
+  const maxNum = ordered.reduce((m, r) => Math.max(m, handleNumber(r.handle)), 0);
+
+  return {
+    ideas: ordered.filter((r) => r.status !== 'killed').map((r) => toClientIdea(r, titles)),
+    killed: ordered.filter((r) => r.status === 'killed').map((r) => toClientIdea(r, titles)),
+    nextId: maxNum + 1,
+    clusters: [...clusters]
+      .sort((a, b) => (a.cluster_order ?? Number.MAX_SAFE_INTEGER) - (b.cluster_order ?? Number.MAX_SAFE_INTEGER)
+        || handleNumber(a.handle) - handleNumber(b.handle))
+      .map((c) => ({ handle: c.handle, name: c.title, theme: c.body ?? '', order: c.cluster_order ?? null })),
+  };
+}
+
+/**
+ * One record → the client shape, resolving its cluster title from the provider.
+ *
+ * The convenience form for a mutation response, which has one record and no
+ * cluster list in hand. `listRecords` for clusters is a handful of small reads
+ * on the floor and one call on a remote provider, and getting the name right
+ * matters more: a response whose `cluster` is `CLUS-3` where the hydrate says
+ * `Umbrella A` makes an optimistic client redraw the idea into a group that does
+ * not exist.
+ */
+export async function toClientIdeaWith(provider, record) {
+  if (!record?.cluster) return toClientIdea(record);
+  return toClientIdea(record, clusterTitleMap(await provider.listRecords({ kind: KIND.CLUSTER })));
+}

package/lib/fluid/import-ideabox.js

@@ -0,0 +1,186 @@
+/**
+ * lib/fluid/import-ideabox.js — one-time markdown → fluid records import.
+ *
+ * COMP-PLAN-IDEA-UNIFY S2. `ONE-WAY-WRITES`: this is an import, executed once,
+ * NOT a sync. There is no reverse path and there must never be one — the
+ * ideabox↔vision-store fragmentation this epic exists to end was created by
+ * exactly that kind of two-way bridge. After the import, `ideabox.md` is a
+ * projection (see render-ideabox.js) and the records are canon.
+ *
+ * The import is deliberately conservative about identity:
+ *   - existing `IDEA-N` handles are carried over VERBATIM, because they are
+ *     cited in docs, commits and conversation (the substrate ruling itself
+ *     cites IDEA-20). A migration that renumbered would silently invalidate
+ *     every one of those references.
+ *   - every imported record is stamped `origin: import:ideabox`, so a migrated
+ *     row stays distinguishable from a natively captured one for the rest of
+ *     its life. Provenance is captured at write time and never retrofitted.
+ */
+
+import { readFileSync } from 'node:fs';
+
+import { parseIdeabox } from '../ideabox.js';
+import { toRecordTimestamp } from './ideabox-dates.js';
+import { KIND } from './provider.js';
+
+/** Markdown status token → canonical fluid status. */
+const STATUS_MAP = Object.freeze({
+  NEW: 'new',
+  DISCUSSING: 'discussing',
+  PROMOTED: 'promoted',
+  KILLED: 'killed',
+});
+
+/**
+ * The ideabox writes free-form status values (`RE-AIMED (2026-07-21)`,
+ * `PROMOTED (→ FEAT-1)`). Map on the leading token and keep the full original
+ * so nothing is silently normalized away.
+ */
+function toStatus(raw) {
+  const token = String(raw ?? '').trim().split(/[\s(]/)[0].toUpperCase();
+  return STATUS_MAP[token] ?? 'new';
+}
+
+function toPriority(raw) {
+  const p = String(raw ?? '').trim();
+  return /^P[012]$/.test(p) ? p : null;
+}
+
+/**
+ * Import an ideabox markdown document into a fluid provider.
+ *
+ * @param {import('./provider.js').FluidProvider} provider
+ * @param {object} opts
+ * @param {string} [opts.markdown] document contents
+ * @param {string} [opts.path] read the document from here instead
+ * @param {boolean} [opts.dryRun] compute the plan without writing
+ * @returns {Promise<{imported: string[], skipped: string[], clusters: string[], alreadyImported: boolean}>}
+ */
+export async function importIdeabox(provider, { markdown, path, dryRun = false } = {}) {
+  const source = markdown ?? readFileSync(path, 'utf8');
+  const parsed = parseIdeabox(source);
+
+  const provenance = { origin: 'import:ideabox' };
+
+  // Idempotence: a handle already present is left ALONE, not overwritten.
+  // Re-running must not clobber edits made through the tools after the first
+  // import, and must not throw on the handle-already-issued guard.
+  const existing = new Set((await provider.listRecords()).map((r) => r.handle));
+
+  const imported = [];
+  const skipped = [];
+  const clusterHandles = [];
+
+  // ---- clusters first: members reference them by handle --------------------
+  const clusterHandleByName = new Map();
+  for (const cluster of parsed.clusters ?? []) {
+    const known = (await provider.listRecords({ kind: KIND.CLUSTER }))
+      .find((r) => r.title === cluster.name);
+    if (known) {
+      clusterHandleByName.set(cluster.name, known.handle);
+      skipped.push(known.handle);
+      continue;
+    }
+    if (dryRun) {
+      clusterHandleByName.set(cluster.name, `(new cluster) ${cluster.name}`);
+      continue;
+    }
+    const rec = await provider.createRecord({
+      kind: KIND.CLUSTER,
+      title: cluster.name,
+      // The umbrella's hand-authored Theme paragraph. This is the field the
+      // whole cluster-as-record decision exists for.
+      body: cluster.theme ?? '',
+      cluster_order: cluster.order,
+      provenance,
+      // See below — the import is the one caller that must survive a rerun.
+      reclaimAborted: true,
+    });
+    clusterHandleByName.set(cluster.name, rec.handle);
+    clusterHandles.push(rec.handle);
+    imported.push(rec.handle);
+  }
+
+  // ---- ideas ---------------------------------------------------------------
+  const all = [
+    ...(parsed.ideas ?? []).map((i) => ({ idea: i, killed: false })),
+    ...(parsed.killed ?? []).map((i) => ({ idea: i, killed: true })),
+  ];
+
+  for (const { idea, killed } of all) {
+    if (existing.has(idea.id)) {
+      skipped.push(idea.id);
+      continue;
+    }
+    const clusterHandle = idea.cluster ? clusterHandleByName.get(idea.cluster) ?? null : null;
+    const clusterOrder = idea.cluster
+      ? (parsed.clusters ?? []).find((c) => c.name === idea.cluster)?.order ?? null
+      : null;
+
+    const record = {
+      kind: KIND.IDEA,
+      // Verbatim. The whole point of the caller-supplied handle path.
+      handle: idea.id,
+      title: idea.title,
+      body: idea.description ?? '',
+      status: killed ? 'killed' : toStatus(idea.status),
+      // Keep the author's token when the canonical enum cannot hold it, so a
+      // closed enum does not quietly flatten `RE-AIMED (2026-07-21)` to `NEW`.
+      status_label: STATUS_MAP[String(idea.status ?? '').trim().toUpperCase()]
+        ? null
+        : (idea.status || null),
+      priority: toPriority(idea.priority),
+      // Carried, not dropped. `parseIdeabox` already validates both against
+      // their enums and yields null otherwise (`lib/ideabox.js:304-311`), so
+      // there is nothing to re-check here — but omitting them is not a harmless
+      // gap. This function is the first-use migration gate every upgrading
+      // install runs, and the render that follows it rewrites the markdown from
+      // the records. A dropped field is therefore deleted from the user's file
+      // on upgrade, silently, with no way back. No idea in THIS repo carries
+      // either, which is exactly why it went unnoticed.
+      effort: idea.effort ?? null,
+      impact: idea.impact ?? null,
+      cluster: clusterHandle,
+      cluster_order: clusterOrder,
+      tags: idea.tags ?? [],
+      source: idea.source || null,
+      links: idea.mapsTo ? [{ type: 'maps_to', target: idea.mapsTo }] : [],
+      killed: (killed || idea.killedReason)
+        ? {
+          at: toRecordTimestamp(idea.killedDate),
+          reason: idea.killedReason || 'reason not recorded in markdown',
+        }
+        : null,
+      discussion: (idea.discussion ?? []).map((d) => ({
+        at: toRecordTimestamp(d.date),
+        text: d.text ?? '',
+        author: d.author ?? null,
+      })),
+      provenance,
+    };
+
+    if (dryRun) {
+      imported.push(idea.id);
+      continue;
+    }
+    // `reclaimAborted` makes the import RESTARTABLE. Creation burns the handle
+    // before writing the record, and this loop skips only handles with a live
+    // record — so a crash between those two steps leaves a handle that is
+    // issued, absent, and permanently un-creatable. Without this flag the
+    // one-time migration of a project's entire idea corpus cannot be rerun
+    // after a partial failure, which is the failure it is most likely to have.
+    // Narrow by construction: the provider reclaims ONLY a handle that was
+    // never live and never deleted, and no other caller passes this.
+    await provider.createRecord({ ...record, reclaimAborted: true });
+    imported.push(idea.id);
+  }
+
+  return {
+    imported,
+    skipped,
+    clusters: clusterHandles,
+    // True when the document had content and every handle in it was already
+    // present — i.e. this was a re-run, not a first import.
+    alreadyImported: imported.length === 0 && skipped.length > 0,
+  };
+}