refactor(plan-60 B1+B2): hoist ensureAppScope + add cmcConstants module

B1 (S1) — `ts/cmc/appScope.ts`: canonical `ensureAppScope(conn, appCode, subPath?)`
from doctor-dashboard's defensive version (tolerates `item-already-exists`
+ `forbidden`). Also exports `pryvErrorCode(e)` (B4 folded in). Replaces
3 drifting copies (doctor-dashboard, bridge-mira, archived migration).

B2 (S2) — `ts/cmc/constants.ts`: `CMC_APP_CODES` (PATIENT/COLLECTOR/
BRIDGE_MIRA/BRIDGE_ATHENA), `CMC_EVENT_TYPES` (INVITE_TRIGGER/ACCEPT),
`appSubScope(appCode, sub)` builder + `extractAppSubScopeSuffix(streamId,
appCode)` extractor (preserves the original `.*?` leading-prefix
tolerance). Locks the values consumers were duplicating as literals.
`CMC_CLIENTDATA` from the plan example dropped — paths don't exist in
active code.

`formSpec.ts`: 2 `consent/request-cmc` literals → `CMC_EVENT_TYPES.
INVITE_TRIGGER` via relative import.

`index.ts`: exports `cmcAppScope` + `cmcConstants` (namespace pattern,
matches `cmcFormSpec`).

Tests: `tests/appScope.test.js` (12), `tests/cmcConstants.test.js` (8).
532/532 hds-lib tests pass.

package-lock: stale 0.11.0 → 0.12.1 sync from earlier npm runs.

Author: perki

package-lock.json

@@ -0,0 +1,123 @@
+import { assert } from './test-utils/deps-node.js';
+import { ensureAppScope, pryvErrorCode } from '../ts/cmc/appScope.ts';
+
+/**
+ * Unit tests for the Plan 60 B1 hoisted `cmcAppScope.ensureAppScope`.
+ *
+ * The helper wraps two `streams.create` calls (appScope + optional subPath)
+ * and tolerates idempotency / permission errors against the `:_cmc:apps`
+ * plugin-managed namespace. See `ts/cmc/appScope.ts` for the rationale.
+ */
+
+const APP_CODE = 'hds-collector';
+const EXPECTED_APP_SCOPE = ':_cmc:apps:' + APP_CODE;
+
+function makeConn (responder) {
+  const calls = [];
+  return {
+    calls,
+    async apiOne (method, params) {
+      calls.push({ method, params });
+      return responder(method, params, calls.length - 1);
+    }
+  };
+}
+
+function pryvError (id) {
+  const e = new Error('pryv-api: ' + id);
+  e.innerObject = { id };
+  return e;
+}
+
+describe('[CAS] cmcAppScope.ensureAppScope', function () {
+  describe('[CASE] pryvErrorCode', function () {
+    it('[CAS01] reads innerObject.id when present', () => {
+      assert.equal(pryvErrorCode(pryvError('item-already-exists')), 'item-already-exists');
+    });
+    it('[CAS02] falls back to top-level id when no innerObject', () => {
+      assert.equal(pryvErrorCode({ id: 'forbidden' }), 'forbidden');
+    });
+    it('[CAS03] returns undefined for unrelated values', () => {
+      assert.equal(pryvErrorCode(new Error('x')), undefined);
+      assert.equal(pryvErrorCode(null), undefined);
+      assert.equal(pryvErrorCode(undefined), undefined);
+    });
+  });
+
+  describe('[CASH] happy paths', function () {
+    it('[CAS10] provisions appScope only (no subPath)', async () => {
+      const conn = makeConn(() => ({ stream: { id: EXPECTED_APP_SCOPE } }));
+      const out = await ensureAppScope(conn, APP_CODE);
+      assert.equal(out, EXPECTED_APP_SCOPE);
+      assert.equal(conn.calls.length, 1);
+      assert.equal(conn.calls[0].method, 'streams.create');
+      assert.deepEqual(conn.calls[0].params, {
+        id: EXPECTED_APP_SCOPE,
+        parentId: ':_cmc:apps',
+        name: APP_CODE
+      });
+    });
+
+    it('[CAS11] provisions appScope + subPath', async () => {
+      const conn = makeConn(() => ({ stream: {} }));
+      const out = await ensureAppScope(conn, APP_CODE, 'abc123');
+      assert.equal(out, EXPECTED_APP_SCOPE + ':abc123');
+      assert.equal(conn.calls.length, 2);
+      assert.deepEqual(conn.calls[1].params, {
+        id: EXPECTED_APP_SCOPE + ':abc123',
+        parentId: EXPECTED_APP_SCOPE,
+        name: 'abc123'
+      });
+    });
+  });
+
+  describe('[CAST] tolerated errors', function () {
+    it('[CAS20] tolerates item-already-exists on appScope', async () => {
+      const conn = makeConn(() => { throw pryvError('item-already-exists'); });
+      const out = await ensureAppScope(conn, APP_CODE);
+      assert.equal(out, EXPECTED_APP_SCOPE);
+    });
+
+    it('[CAS21] tolerates forbidden on appScope (OAuth-narrow access)', async () => {
+      const conn = makeConn(() => { throw pryvError('forbidden'); });
+      const out = await ensureAppScope(conn, APP_CODE);
+      assert.equal(out, EXPECTED_APP_SCOPE);
+    });
+
+    it('[CAS22] tolerates item-already-exists on subPath', async () => {
+      const conn = makeConn((method, params, idx) => {
+        if (idx === 0) return { stream: {} };
+        throw pryvError('item-already-exists');
+      });
+      const out = await ensureAppScope(conn, APP_CODE, 'abc123');
+      assert.equal(out, EXPECTED_APP_SCOPE + ':abc123');
+      assert.equal(conn.calls.length, 2);
+    });
+  });
+
+  describe('[CASR] rethrows on unrelated errors', function () {
+    it('[CAS30] rethrows non-tolerated pryv error on appScope', async () => {
+      const conn = makeConn(() => { throw pryvError('invalid-parameters-format'); });
+      await assert.rejects(
+        ensureAppScope(conn, APP_CODE),
+        (e) => e.innerObject?.id === 'invalid-parameters-format'
+      );
+    });
+
+    it('[CAS31] rethrows forbidden on subPath (only appScope tolerates forbidden)', async () => {
+      const conn = makeConn((method, params, idx) => {
+        if (idx === 0) return { stream: {} };
+        throw pryvError('forbidden');
+      });
+      await assert.rejects(
+        ensureAppScope(conn, APP_CODE, 'abc123'),
+        (e) => e.innerObject?.id === 'forbidden'
+      );
+    });
+
+    it('[CAS32] rethrows plain Errors with no pryv id', async () => {
+      const conn = makeConn(() => { throw new Error('boom'); });
+      await assert.rejects(ensureAppScope(conn, APP_CODE), /boom/);
+    });
+  });
+});

tests/appScope.test.js

@@ -0,0 +1,74 @@
+import { assert } from './test-utils/deps-node.js';
+import {
+  CMC_APP_CODES,
+  CMC_EVENT_TYPES,
+  appSubScope,
+  extractAppSubScopeSuffix
+} from '../ts/cmc/constants.ts';
+
+/**
+ * Unit tests for the Plan 60 B2 shared CMC constants + scope helpers.
+ *
+ * The constants are locked per Plan 59 Decisions; tests assert the exact
+ * values so any drift becomes a deliberate change with an explicit diff.
+ */
+
+describe('[CCST] cmcConstants', function () {
+  describe('[CCSA] CMC_APP_CODES', function () {
+    it('[CCS01] PATIENT, COLLECTOR, BRIDGE_MIRA, BRIDGE_ATHENA match locked values', () => {
+      assert.equal(CMC_APP_CODES.PATIENT, 'hds-patient');
+      assert.equal(CMC_APP_CODES.COLLECTOR, 'hds-collector');
+      assert.equal(CMC_APP_CODES.BRIDGE_MIRA, 'hds-bridge-mira');
+      assert.equal(CMC_APP_CODES.BRIDGE_ATHENA, 'hds-bridge-athena');
+    });
+  });
+
+  describe('[CCSE] CMC_EVENT_TYPES', function () {
+    it('[CCS10] INVITE_TRIGGER + ACCEPT match the CMC plugin convention', () => {
+      assert.equal(CMC_EVENT_TYPES.INVITE_TRIGGER, 'consent/request-cmc');
+      assert.equal(CMC_EVENT_TYPES.ACCEPT, 'consent/accept-cmc');
+    });
+  });
+
+  describe('[CCSB] appSubScope', function () {
+    it('[CCS20] builds the canonical sub-scope id', () => {
+      assert.equal(
+        appSubScope(CMC_APP_CODES.COLLECTOR, 'abc123'),
+        ':_cmc:apps:hds-collector:abc123'
+      );
+    });
+    it('[CCS21] composes deeper paths via colon-joined sub', () => {
+      assert.equal(
+        appSubScope(CMC_APP_CODES.PATIENT, 'chats:dr-smith'),
+        ':_cmc:apps:hds-patient:chats:dr-smith'
+      );
+    });
+  });
+
+  describe('[CCSX] extractAppSubScopeSuffix', function () {
+    it('[CCS30] strips the appScope prefix', () => {
+      assert.equal(
+        extractAppSubScopeSuffix(':_cmc:apps:hds-collector:abc123', CMC_APP_CODES.COLLECTOR),
+        'abc123'
+      );
+    });
+    it('[CCS31] tolerates leading prefix (matches original .*? regex behavior)', () => {
+      assert.equal(
+        extractAppSubScopeSuffix('peer:_cmc:apps:hds-collector:abc123', CMC_APP_CODES.COLLECTOR),
+        'abc123'
+      );
+    });
+    it('[CCS32] returns streamId unchanged when prefix absent', () => {
+      assert.equal(
+        extractAppSubScopeSuffix(':some-other-stream', CMC_APP_CODES.COLLECTOR),
+        ':some-other-stream'
+      );
+    });
+    it('[CCS33] does not cross-match a different appCode', () => {
+      assert.equal(
+        extractAppSubScopeSuffix(':_cmc:apps:hds-collector:abc', CMC_APP_CODES.PATIENT),
+        ':_cmc:apps:hds-collector:abc'
+      );
+    });
+  });
+});

tests/cmcConstants.test.js

@@ -0,0 +1,61 @@
+/**
+ * Idempotently provision streams under `:_cmc:apps` on a CMC-enabled account.
+ *
+ * The CMC plugin auto-creates the `:_cmc:apps` parent but does not
+ * auto-create the per-app children — each `:_cmc:apps:<appCode>` and its
+ * sub-scopes (e.g. `:_cmc:apps:hds-collector:<collectorId>`) need explicit
+ * `streams.create` calls. The two error modes are tolerated:
+ *
+ *   - `'item-already-exists'` — the stream is already there (idempotent re-run).
+ *   - `'forbidden'` — happens on the appScope when the caller's OAuth-scoped
+ *     access has `manage` on `:_cmc:apps:<appCode>` but not on the parent
+ *     `:_cmc:apps` (the plugin-managed namespace). In that case the appScope
+ *     is typically pre-existing anyway because the CMC plugin auto-provisions
+ *     app-scope roots on first invite.
+ *
+ * Hoisted in Plan 60 B1 from three independent copies that had drifted:
+ * `doctor-dashboard/app/cmcDoctor.ts` (canonical, used here),
+ * `bridge-mira/src/methods/cmcBridgeMira.ts`, and the archived
+ * `_plans/_archives/59-…/scripts/cmc-migrate.mjs`.
+ */
+
+import { cmc, pryv } from '../patchedPryv.ts';
+
+/** Extract a Pryv API error-code id from a thrown error, regardless of nesting depth. */
+export function pryvErrorCode (e: unknown): string | undefined {
+  const inner = (e as { innerObject?: { id?: string } })?.innerObject?.id;
+  if (inner != null) return inner;
+  return (e as { id?: string })?.id;
+}
+
+/**
+ * Idempotently provision `:_cmc:apps:<appCode>` (and optionally
+ * `:_cmc:apps:<appCode>:<subPath>`) on the caller's account.
+ *
+ * @param connection  caller's Pryv connection (doctor / patient / bridge).
+ * @param appCode     `hds-collector`, `hds-patient`, `hds-bridge-mira`, etc.
+ * @param subPath     optional leaf scope under the appScope (e.g. a collectorId).
+ * @returns           the streamId of the deepest scope provisioned.
+ */
+export async function ensureAppScope (
+  connection: pryv.Connection,
+  appCode: string,
+  subPath?: string
+): Promise<string> {
+  const appScope = cmc.appScope(appCode); // :_cmc:apps:<appCode>
+  try {
+    await connection.apiOne('streams.create', { id: appScope, parentId: ':_cmc:apps', name: appCode });
+  } catch (e: unknown) {
+    const code = pryvErrorCode(e);
+    if (code !== 'item-already-exists' && code !== 'forbidden') throw e;
+  }
+  if (subPath == null) return appScope;
+  const sub = appScope + ':' + subPath;
+  try {
+    await connection.apiOne('streams.create', { id: sub, parentId: appScope, name: subPath });
+  } catch (e: unknown) {
+    const code = pryvErrorCode(e);
+    if (code !== 'item-already-exists') throw e;
+  }
+  return sub;
+}

ts/cmc/appScope.ts

@@ -0,0 +1,60 @@
+/**
+ * Canonical constants for the HDS x CMC integration.
+ *
+ * Centralizes:
+ * - **App codes** — the `:_cmc:apps:<code>` namespace identifiers for each
+ *   HDS surface (patient app, doctor's collector flow, per-bridge services).
+ * - **CMC event types** — the well-known consent trigger/accept types the
+ *   CMC plugin emits.
+ * - **Stream-ID helpers** — build / extract the `:_cmc:apps:<appCode>:<sub>`
+ *   sub-scope pattern used by collector forms and chat anchors.
+ *
+ * Hoisted in Plan 60 B2 from per-file literals + per-file constants.
+ */
+
+/** Locked HDS app codes for the `:_cmc:apps:<appCode>` namespace. */
+export const CMC_APP_CODES = {
+  /** Patient-side HDS-webapp scope (chats anchor, inbox routing). */
+  PATIENT: 'hds-patient',
+  /** Doctor-side collector flow scope (form-spec sub-scopes + invites). */
+  COLLECTOR: 'hds-collector',
+  /** bridge-mira service-account scope (Mira API ingest). */
+  BRIDGE_MIRA: 'hds-bridge-mira',
+  /** bridge-athena service-account scope (Athena/EHR ingest; CMC wiring pending). */
+  BRIDGE_ATHENA: 'hds-bridge-athena'
+} as const;
+
+export type CmcAppCode = typeof CMC_APP_CODES[keyof typeof CMC_APP_CODES];
+
+/** Well-known CMC consent event types. */
+export const CMC_EVENT_TYPES = {
+  /** Doctor's invite trigger event under their collector sub-scope. */
+  INVITE_TRIGGER: 'consent/request-cmc',
+  /** Patient's accept event (mirrored to the doctor's inbox via the plugin). */
+  ACCEPT: 'consent/accept-cmc'
+} as const;
+
+export type CmcEventType = typeof CMC_EVENT_TYPES[keyof typeof CMC_EVENT_TYPES];
+
+/**
+ * Build `:_cmc:apps:<appCode>:<sub>` — the per-sub-scope stream id used by
+ * collector forms (`:<collectorId>`), chat anchors (`:chats:<peerSlug>`), etc.
+ *
+ * Mirrors the upstream `cmc.appScope(appCode)` builder which only handles the
+ * top-level appScope; this helper handles the one-level-deeper case the HDS
+ * integration uses pervasively.
+ */
+export function appSubScope (appCode: string, sub: string): string {
+  return ':_cmc:apps:' + appCode + ':' + sub;
+}
+
+/**
+ * Extract the trailing `<sub>` from a stream id of the form
+ * `:_cmc:apps:<appCode>:<sub>` (tolerant of any leading prefix — matches the
+ * `^.*?:_cmc:apps:<appCode>:` pattern used in the original sites).
+ * Returns the original streamId unchanged if the prefix is not found.
+ */
+export function extractAppSubScopeSuffix (streamId: string, appCode: string): string {
+  const escaped = appCode.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return streamId.replace(new RegExp('^.*?:_cmc:apps:' + escaped + ':'), '');
+}

ts/cmc/constants.ts

@@ -25,6 +25,7 @@
  */
 
 import { pryv } from '../patchedPryv.ts';
+import { CMC_EVENT_TYPES } from './constants.ts';
 import type { Permission } from '../appTemplates/interfaces.ts';
 import type { localizableText } from '../localizeText.ts';
 import type {
@@ -182,7 +183,7 @@ export async function createInviteWithFormSpec (
   }
   const event = await connection.apiOne('events.create', {
     streamIds: [params.scopeStreamId],
-    type: 'consent/request-cmc',
+    type: CMC_EVENT_TYPES.INVITE_TRIGGER,
     content
   } as any, 'event') as any;
   return {
@@ -256,7 +257,7 @@ export async function readOfferWithFormSpec (
   const pryvMod = (opts && opts.pryv) || (pryv as any);
   const cap = new pryvMod.Connection(capabilityUrl);
   const events = await cap.apiOne('events.get', {
-    types: ['consent/request-cmc'],
+    types: [CMC_EVENT_TYPES.INVITE_TRIGGER],
     limit: 1
   }, 'events') as any[];
   if (!events || events.length === 0) {

ts/cmc/formSpec.ts

@@ -21,6 +21,8 @@ import { EuclidianDistanceEngine } from './converters/EuclidianDistanceEngine.ts
 import { HDSLibError } from './errors.ts';
 import { extractOverloadAsDefinitions } from './HDSModel/overloadExtract.ts';
 import * as cmcFormSpec from './cmc/formSpec.ts';
+import * as cmcAppScope from './cmc/appScope.ts';
+import * as cmcConstants from './cmc/constants.ts';
 export type { MonitorScopeConfig, MonitorScopeCallbacks } from './MonitorScope.ts';
 export type { ReminderConfig } from './HDSModel/HDSItemDef.ts';
 export type { ReminderSource, ReminderStatus } from './HDSModel/reminders.ts';
@@ -34,7 +36,7 @@ export type { InitHDSModelOptions } from './HDSModel/HDSModelInitAndSingleton.ts
 
 export const getHDSModel = HDSModelInitAndSingleton.getModel;
 export const initHDSModel = HDSModelInitAndSingleton.initHDSModel;
-export { pryv, cmc, settings, HDSService, HDSModel, appTemplates, localizeText, localizeText as l, toolkit, logger, durationToSeconds, durationToLabel, computeReminders, eventToShortText, formatEventDate, MonitorScope, HDSSettings, SETTING_TYPES, HDSProfile, PROFILE_FIELDS, HDSModelConversions, HDSModelConverters, HDSModelPreferred, getPreferredInput, getPreferredDisplay, HDSModelAppStreams, EuclidianDistanceEngine, HDSLibError, extractOverloadAsDefinitions, cmcFormSpec };
+export { pryv, cmc, settings, HDSService, HDSModel, appTemplates, localizeText, localizeText as l, toolkit, logger, durationToSeconds, durationToLabel, computeReminders, eventToShortText, formatEventDate, MonitorScope, HDSSettings, SETTING_TYPES, HDSProfile, PROFILE_FIELDS, HDSModelConversions, HDSModelConverters, HDSModelPreferred, getPreferredInput, getPreferredDisplay, HDSModelAppStreams, EuclidianDistanceEngine, HDSLibError, extractOverloadAsDefinitions, cmcFormSpec, cmcAppScope, cmcConstants };
 export type { FormSpec } from './cmc/formSpec.ts';
 
 // Plan 45 — top-level type re-exports so consumers can `import type { CustomFieldDeclaration } from 'hds-lib'`.
@@ -93,6 +95,8 @@ const HDSLib = {
   HDSModelConverters,
   EuclidianDistanceEngine,
   extractOverloadAsDefinitions,
-  cmcFormSpec
+  cmcFormSpec,
+  cmcAppScope,
+  cmcConstants
 };
 export default HDSLib;