feat(cmc/formSpec): add FormSpecRecord + listFormSpecs + getFormSpecById (plan 61 C1.0)

perki · perki · commit 9efba2715bff · 2026-05-27T11:38:26.000+02:00
Pre-work for Phase C consumer port. New exports:
- FormSpecRecord interface (collectorId, formSpec, event)
- eventToFormSpecRecord pure helper
- listFormSpecs(connection, opts?) — replaces appManaging.getCollectors()
- getFormSpecById(connection, collectorId, opts?) — replaces getCollectorById

13 new unit tests [CFS30]-[CFS52]. 546/546 pass. Lifecycle locked
publish-on-save (no draft state) — consumers will drop the legacy
statusCode === 'active' filter.
diff --git a/tests/cmcFormSpec.test.js b/tests/cmcFormSpec.test.js
@@ -70,6 +70,139 @@ describe('[CFSP] cmcFormSpec helpers', function () {
       assert.equal(cmcFormSpec.isChatOnlyFormSpec(undefined), false);
     });
   });
+
+  describe('[CFSR] eventToFormSpecRecord (pure helper)', function () {
+    function eventOn (streamId, content = basicSpec()) {
+      return { id: 'evt-' + streamId, streamIds: [streamId], content };
+    }
+
+    it('[CFS30] extracts collectorId from a hds-collector sub-scope', () => {
+      const rec = cmcFormSpec.eventToFormSpecRecord(eventOn(':_cmc:apps:hds-collector:abc123'));
+      assert.equal(rec.collectorId, 'abc123');
+      assert.equal(rec.formSpec.title.en, 'Hello World');
+      assert.equal(rec.event.id, 'evt-:_cmc:apps:hds-collector:abc123');
+    });
+
+    it('[CFS31] honors a custom appCode parameter', () => {
+      const rec = cmcFormSpec.eventToFormSpecRecord(
+        eventOn(':_cmc:apps:hds-patient:xyz'),
+        'hds-patient'
+      );
+      assert.equal(rec.collectorId, 'xyz');
+    });
+
+    it('[CFS32] picks the matching stream when an event has multiple streamIds', () => {
+      const ev = { id: 'evt', streamIds: ['other-stream', ':_cmc:apps:hds-collector:formA'], content: basicSpec() };
+      const rec = cmcFormSpec.eventToFormSpecRecord(ev);
+      assert.equal(rec.collectorId, 'formA');
+    });
+
+    it('[CFS33] returns the raw streamId when no matching scope marker is found (fallback)', () => {
+      const ev = { id: 'evt', streamIds: ['orphan'], content: basicSpec() };
+      const rec = cmcFormSpec.eventToFormSpecRecord(ev);
+      // extractAppSubScopeSuffix returns the input unchanged when the prefix is missing.
+      assert.equal(rec.collectorId, 'orphan');
+    });
+
+    it('[CFS34] tolerates a missing streamIds array', () => {
+      const ev = { id: 'evt', content: basicSpec() };
+      const rec = cmcFormSpec.eventToFormSpecRecord(ev);
+      assert.equal(rec.collectorId, '');
+    });
+  });
+
+  describe('[CFSL] listFormSpecs', function () {
+    function fakeConnection (events) {
+      const calls = [];
+      const conn = {
+        apiOne (method, params, resultKey) {
+          calls.push({ method, params, resultKey });
+          if (method === 'events.get') return events;
+          throw new Error('unexpected apiOne method ' + method);
+        }
+      };
+      return { conn, calls };
+    }
+
+    it('[CFS40] queries the :_cmc:apps:hds-collector parent stream filtered to hds:form-spec-v1', async () => {
+      const { conn, calls } = fakeConnection([]);
+      await cmcFormSpec.listFormSpecs(conn);
+      assert.equal(calls.length, 1);
+      assert.equal(calls[0].method, 'events.get');
+      assert.deepEqual(calls[0].params.streams, [':_cmc:apps:hds-collector']);
+      assert.deepEqual(calls[0].params.types, ['hds:form-spec-v1']);
+      assert.equal(calls[0].params.limit, 1000);
+      assert.equal(calls[0].resultKey, 'events');
+    });
+
+    it('[CFS41] maps every returned event to a FormSpecRecord with collectorId set', async () => {
+      const events = [
+        { id: 'e1', streamIds: [':_cmc:apps:hds-collector:form-a'], content: basicSpec({ title: { en: 'Form A' } }) },
+        { id: 'e2', streamIds: [':_cmc:apps:hds-collector:form-b'], content: basicSpec({ title: { en: 'Form B' } }) }
+      ];
+      const { conn } = fakeConnection(events);
+      const records = await cmcFormSpec.listFormSpecs(conn);
+      assert.equal(records.length, 2);
+      assert.deepEqual(records.map(r => r.collectorId), ['form-a', 'form-b']);
+      assert.equal(records[0].formSpec.title.en, 'Form A');
+      assert.equal(records[1].event.id, 'e2');
+    });
+
+    it('[CFS42] returns [] when the api returns null/undefined', async () => {
+      const { conn } = fakeConnection(null);
+      const records = await cmcFormSpec.listFormSpecs(conn);
+      assert.deepEqual(records, []);
+    });
+
+    it('[CFS43] honors a custom appCode opt', async () => {
+      const { conn, calls } = fakeConnection([]);
+      await cmcFormSpec.listFormSpecs(conn, { appCode: 'hds-patient' });
+      assert.deepEqual(calls[0].params.streams, [':_cmc:apps:hds-patient']);
+    });
+
+    it('[CFS44] honors a custom limit opt', async () => {
+      const { conn, calls } = fakeConnection([]);
+      await cmcFormSpec.listFormSpecs(conn, { limit: 50 });
+      assert.equal(calls[0].params.limit, 50);
+    });
+  });
+
+  describe('[CFSG] getFormSpecById', function () {
+    it('[CFS50] returns null when loadFormSpec finds nothing', async () => {
+      const conn = { apiOne: async () => [] };
+      const rec = await cmcFormSpec.getFormSpecById(conn, 'missing');
+      assert.equal(rec, null);
+    });
+
+    it('[CFS51] returns a FormSpecRecord with the requested collectorId when found', async () => {
+      const event = { id: 'evt-xyz', streamIds: [':_cmc:apps:hds-collector:xyz'], content: basicSpec({ title: { en: 'XYZ' } }) };
+      const calls = [];
+      const conn = {
+        apiOne (method, params, resultKey) {
+          calls.push({ method, params, resultKey });
+          return [event];
+        }
+      };
+      const rec = await cmcFormSpec.getFormSpecById(conn, 'xyz');
+      assert.ok(rec);
+      assert.equal(rec.collectorId, 'xyz');
+      assert.equal(rec.formSpec.title.en, 'XYZ');
+      // Verify the underlying loadFormSpec was scoped to the exact sub-scope stream
+      assert.deepEqual(calls[0].params.streams, [':_cmc:apps:hds-collector:xyz']);
+    });
+
+    it('[CFS52] honors a custom appCode opt', async () => {
+      const calls = [];
+      const conn = {
+        apiOne (method, params) {
+          calls.push(params);
+          return [];
+        }
+      };
+      await cmcFormSpec.getFormSpecById(conn, 'foo', { appCode: 'hds-patient' });
+      assert.deepEqual(calls[0].streams, [':_cmc:apps:hds-patient:foo']);
+    });
+  });
 });
 
 describe('[CTFS] Contact.aggregateCmc hdsFormSpec pass-through', function () {
diff --git a/ts/cmc/formSpec.ts b/ts/cmc/formSpec.ts
@@ -24,8 +24,8 @@
  * patient's hds-webapp provisions `:hds:noop` on first launch.
  */
 
-import { pryv } from '../patchedPryv.ts';
-import { CMC_EVENT_TYPES } from './constants.ts';
+import { cmc, pryv } from '../patchedPryv.ts';
+import { CMC_APP_CODES, CMC_EVENT_TYPES, appSubScope, extractAppSubScopeSuffix } from './constants.ts';
 import type { Permission } from '../appTemplates/interfaces.ts';
 import type { localizableText } from '../localizeText.ts';
 import type {
@@ -118,6 +118,87 @@ export async function loadFormSpec (
   return (events && events.length > 0) ? events[0] : null;
 }
 
+/**
+ * A FormSpec persisted on the doctor's `:_cmc:apps:<appCode>:<collectorId>`
+ * scope, paired with the raw event id + the parsed collectorId. Returned by
+ * `listFormSpecs` and `getFormSpecById`.
+ *
+ * Phase C (plan 61): replaces the legacy `Collector` runtime as the doctor-
+ * side data-set handle. Every record is "published" — there is no draft
+ * state in the CMC FormSpec model; `saveFormSpec` writes the canonical event
+ * immediately.
+ */
+export interface FormSpecRecord {
+  /** The collectorId suffix of the scope stream (the doctor's data-set id). */
+  collectorId: string;
+  /** The FormSpec content as authored. */
+  formSpec: FormSpec;
+  /** The raw `hds:form-spec-v1` event (id, modified, etc.). */
+  event: pryv.Event;
+}
+
+/**
+ * Pure helper: lift a raw `hds:form-spec-v1` event onto its scope-stream
+ * `collectorId`. Exported for unit-testing in isolation from the I/O layer.
+ *
+ * @param event   a `hds:form-spec-v1` event read from a `:_cmc:apps:<appCode>:*` stream.
+ * @param appCode defaults to `CMC_APP_CODES.COLLECTOR`.
+ */
+export function eventToFormSpecRecord (
+  event: pryv.Event,
+  appCode: string = CMC_APP_CODES.COLLECTOR
+): FormSpecRecord {
+  const streamIds = ((event as any).streamIds || []) as string[];
+  const marker = ':_cmc:apps:' + appCode + ':';
+  const subScope = streamIds.find(s => s.indexOf(marker) !== -1) ?? streamIds[0] ?? '';
+  const collectorId = extractAppSubScopeSuffix(subScope, appCode);
+  return {
+    collectorId,
+    formSpec: (event as any).content as FormSpec,
+    event
+  };
+}
+
+/**
+ * Doctor-side: list every FormSpec the doctor owns under their
+ * `:_cmc:apps:<appCode>` scope (one per data-set). Every result is
+ * "published" — saveFormSpec writes the canonical event immediately
+ * (no draft state in the CMC model).
+ *
+ * Phase C (plan 61): replaces `appManaging.getCollectors()`.
+ */
+export async function listFormSpecs (
+  connection: pryv.Connection,
+  opts?: { appCode?: string; limit?: number }
+): Promise<FormSpecRecord[]> {
+  const appCode = opts?.appCode ?? CMC_APP_CODES.COLLECTOR;
+  const parentStream = cmc.appScope(appCode);
+  const events = await connection.apiOne('events.get', {
+    streams: [parentStream],
+    types: [FORM_SPEC_EVENT_TYPE],
+    limit: opts?.limit ?? 1000
+  } as any, 'events') as unknown as pryv.Event[];
+  return (events ?? []).map(e => eventToFormSpecRecord(e, appCode));
+}
+
+/**
+ * Doctor-side: load a single FormSpec by its `collectorId`. Returns null
+ * if no FormSpec event exists yet on `:_cmc:apps:<appCode>:<collectorId>`.
+ *
+ * Phase C (plan 61): replaces `appManaging.getCollectorById()`.
+ */
+export async function getFormSpecById (
+  connection: pryv.Connection,
+  collectorId: string,
+  opts?: { appCode?: string }
+): Promise<FormSpecRecord | null> {
+  const appCode = opts?.appCode ?? CMC_APP_CODES.COLLECTOR;
+  const subScope = appSubScope(appCode, collectorId);
+  const event = await loadFormSpec(connection, subScope);
+  if (!event) return null;
+  return eventToFormSpecRecord(event, appCode);
+}
+
 /**
  * Doctor-side: mint a CMC invite with the FormSpec snapshot embedded on
  * the trigger event content at events.create time.
