@forklaunch/core 2.1.0 → 3.0.0

package/bin/gateway-mock/server.mjs

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+/**
+ * A local stand-in for the ForkLaunch instance gateway — and for the vendors
+ * behind it — so managed features run on a laptop and in CI with no accounts,
+ * no keys and no network. No dependencies; deterministic answers.
+ *
+ * Each feature (models, payments, email, sms, whatsapp, voice, …) is one file
+ * in ./routes, discovered at start-up. A route file exports:
+ *
+ *   export default {
+ *     feature: 'payments',
+ *     // Instance-gateway routes, router-relative (the part after
+ *     // /instance-gateway). Requests are HMAC-verified exactly as the platform
+ *     // verifies them before the handler runs.
+ *     routes: [{ method: 'POST', path: '/payments/checkout-sessions', handler }],
+ *     // Optional vendor emulation (Foundry, Entra, …), unauthenticated here.
+ *     vendorRoutes: [{ method: 'POST', path: /\/v1\/chat\/completions$/, handler }],
+ *     // Optional: reset per-feature state (POST /__mock/reset).
+ *     reset() {}
+ *   }
+ *
+ * A handler gets `ctx` = { req, res, body, raw, path, params, instanceId, env,
+ * send(status, body, headers), stream(chunks, headers), emit(type, data),
+ * state, record } and answers through `send`/`stream`. `record` is this
+ * call's entry in /__mock/requests; a handler may annotate it (e.g. with what
+ * it forwarded upstream). `state` is a per-feature object
+ * that survives between requests until a reset. `path` may be a string or a
+ * RegExp; a RegExp's named groups arrive in `params`.
+ *
+ * Signatures cover the router-relative path plus its query string, and the
+ * body: JSON as parsed, a form-encoded body (the Stripe SDK's) verbatim — in
+ * which case `body` is {} and the handler reads `raw`.
+ *
+ * Events: `ctx.emit(type, data)` — or POST /__mock/events/<feature> with
+ * { type, data } — delivers a signed platform event to the app at
+ * `${MOCK_EVENTS_URL}/platform-events/<feature>`, signed with the instance
+ * key under key id `platform`, exactly as the platform does. The app verifies
+ * it with `verifyPlatformEvent` from @forklaunch/core/http.
+ *
+ * Control endpoints (for tests):
+ *   GET  /health
+ *   GET  /__mock/requests[?feature=x]   gateway calls received, in order
+ *   GET  /__mock/events[?feature=x]     events delivered and their outcomes
+ *   POST /__mock/events/<feature>       deliver an event now
+ *   POST /__mock/reset                  forget requests, events and state
+ *
+ * Environment:
+ *   PORT                    default 8080
+ *   MOCK_INSTANCE_HMAC_KEY  verify instance signatures and sign events
+ *                           (unset: accept any signature; events unsigned)
+ *   MOCK_EVENTS_URL         the app's base URL for event delivery
+ *   MOCK_EVENTS_URL_<FEATURE>  per-feature override (the service that declared it)
+ *   (plus each feature's own MOCK_* settings; see its route file)
+ *
+ * Usage: npx -p @forklaunch/core forklaunch-gateway-mock
+ */
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { readdirSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MAX_SKEW_MS = 5 * 60 * 1000;
+const GATEWAY_MOUNT = '/instance-gateway';
+
+/** createHmacToken's canonical string, reimplemented without the framework. */
+function sign(key, method, path, bodyPart, timestamp, nonce) {
+  return createHmac('sha256', key)
+    .update(`${method}\n${path}\n${bodyPart}${timestamp}\n${nonce}`)
+    .digest('base64');
+}
+
+export async function loadFeatures(dir = join(HERE, 'routes')) {
+  const files = readdirSync(dir)
+    .filter((f) => f.endsWith('.mjs'))
+    .sort();
+  const features = [];
+  for (const file of files) {
+    const mod = await import(pathToFileURL(join(dir, file)).href);
+    if (mod.default?.feature) features.push(mod.default);
+  }
+  return features;
+}
+
+function matchPath(pattern, path) {
+  if (typeof pattern === 'string') return pattern === path ? {} : null;
+  const m = pattern.exec(path);
+  return m ? { ...(m.groups ?? {}) } : null;
+}
+
+export async function startGatewayMock(env = process.env) {
+  const port = Number(env.PORT ?? 8080);
+  const hmacKey = env.MOCK_INSTANCE_HMAC_KEY || '';
+  const eventsUrl = env.MOCK_EVENTS_URL || '';
+  const features = await loadFeatures();
+  const state = new Map(features.map((f) => [f.feature, {}]));
+  const seenNonces = new Map();
+  let requests = [];
+  let events = [];
+
+  function verifyHmac(req, raw, routerPath, verbatim = false) {
+    if (!hmacKey) return { ok: true, instanceId: 'local-instance' };
+    const header = req.headers.authorization ?? '';
+    const m = /^HMAC keyId=(\S+) ts=(\S+) nonce=(\S+) signature=(\S+)$/.exec(
+      header
+    );
+    if (!m) return { ok: false, message: 'Missing or malformed HMAC authorization' };
+    const [, keyId, ts, nonce, signature] = m;
+    const timestamp = new Date(ts);
+    if (
+      Number.isNaN(timestamp.getTime()) ||
+      Math.abs(Date.now() - timestamp.getTime()) > MAX_SKEW_MS
+    ) {
+      return { ok: false, message: 'Stale or invalid timestamp' };
+    }
+    // createHmacToken: an absent body contributes the string "undefined",
+    // a present one its JSON text plus a newline.
+    const bodyPart = raw
+      ? `${verbatim ? raw : JSON.stringify(JSON.parse(raw))}\n`
+      : 'undefined';
+    const expected = Buffer.from(
+      sign(hmacKey, req.method, routerPath, bodyPart, timestamp.toISOString(), nonce)
+    );
+    const received = Buffer.from(signature);
+    if (expected.length !== received.length || !timingSafeEqual(expected, received)) {
+      return { ok: false, message: 'Invalid signature' };
+    }
+    const now = Date.now();
+    for (const [seen, at] of seenNonces) if (now - at > MAX_SKEW_MS) seenNonces.delete(seen);
+    if (seenNonces.has(nonce)) return { ok: false, message: 'Replayed request' };
+    seenNonces.set(nonce, now);
+    return { ok: true, instanceId: keyId };
+  }
+
+  async function emit(feature, type, data) {
+    const event = {
+      id: `evt_mock_${randomUUID()}`,
+      feature,
+      type,
+      occurredAt: new Date().toISOString(),
+      data: data ?? {}
+    };
+    const record = { event, status: null, error: null };
+    events.push(record);
+    // A feature's events can go to its own service (MOCK_EVENTS_URL_<FEATURE>).
+    const target =
+      env[`MOCK_EVENTS_URL_${feature.toUpperCase().replace(/-/g, '_')}`] ||
+      eventsUrl;
+    if (!target) {
+      record.error = 'MOCK_EVENTS_URL is not set; event recorded, not delivered';
+      return record;
+    }
+    const path = `/platform-events/${feature}`;
+    const body = JSON.stringify(event);
+    const headers = { 'content-type': 'application/json' };
+    if (hmacKey) {
+      const ts = new Date().toISOString();
+      const nonce = randomUUID();
+      headers.authorization = `HMAC keyId=platform ts=${ts} nonce=${nonce} signature=${sign(hmacKey, 'POST', path, `${body}\n`, ts, nonce)}`;
+    }
+    try {
+      const response = await fetch(`${target.replace(/\/$/, '')}${path}`, {
+        method: 'POST',
+        headers,
+        body
+      });
+      record.status = response.status;
+    } catch (error) {
+      record.error = String(error?.message ?? error);
+    }
+    return record;
+  }
+
+  function send(res, status, body, headers = {}) {
+    const text = typeof body === 'string' ? body : JSON.stringify(body);
+    res.writeHead(status, {
+      'content-type': typeof body === 'string' ? 'text/plain' : 'application/json',
+      ...headers
+    });
+    res.end(text);
+  }
+
+  function stream(res, chunks, headers = {}, withIds = false) {
+    res.writeHead(200, {
+      'content-type': 'text/event-stream',
+      'cache-control': 'no-cache',
+      ...headers
+    });
+    let id = 0;
+    for (const chunk of chunks) {
+      res.write(`${withIds ? `id: ${id++}\n` : ''}data: ${typeof chunk === 'string' ? chunk : JSON.stringify(chunk)}\n\n`);
+    }
+    res.end();
+  }
+
+  const server = createServer((req, res) => {
+    let raw = '';
+    req.setEncoding('utf8');
+    req.on('data', (chunk) => {
+      raw += chunk;
+    });
+    req.on('end', async () => {
+      try {
+        const url = new URL(req.url ?? '/', 'http://mock');
+        const path = url.pathname;
+        let body = {};
+        let parsed = true;
+        if (raw) {
+          try {
+            body = JSON.parse(raw);
+          } catch {
+            parsed = false;
+          }
+        }
+        const reply = (status, b, h) => send(res, status, b, h);
+
+        if (req.method === 'GET' && path === '/health') return reply(200, { ok: true });
+        if (req.method === 'GET' && path === '/__mock/requests') {
+          const f = url.searchParams.get('feature');
+          return reply(200, f ? requests.filter((r) => r.feature === f) : requests);
+        }
+        if (req.method === 'GET' && path === '/__mock/events') {
+          const f = url.searchParams.get('feature');
+          return reply(200, f ? events.filter((e) => e.event.feature === f) : events);
+        }
+        if (req.method === 'POST' && path === '/__mock/reset') {
+          requests = [];
+          events = [];
+          for (const f of features) {
+            state.set(f.feature, {});
+            f.reset?.();
+          }
+          return reply(200, { ok: true });
+        }
+        const eventMatch = /^\/__mock\/events\/([a-z-]+)$/.exec(path);
+        if (req.method === 'POST' && eventMatch) {
+          return reply(200, await emit(eventMatch[1], body.type, body.data));
+        }
+
+        const ctxBase = (feature, params, instanceId) => ({
+          req,
+          res,
+          body,
+          raw,
+          path,
+          params,
+          instanceId,
+          env,
+          state: state.get(feature),
+          send: (status, b, h) => send(res, status, b, h),
+          stream: (chunks, h, withIds) => stream(res, chunks, h, withIds),
+          emit: (type, data) => emit(feature, type, data)
+        });
+
+        if (path.startsWith(`${GATEWAY_MOUNT}/`)) {
+          const form = /x-www-form-urlencoded/.test(req.headers['content-type'] ?? '');
+          if (!parsed && !form) return reply(400, 'Body is not JSON');
+          if (form) body = {};
+          const routerPath = path.slice(GATEWAY_MOUNT.length);
+          const verified = verifyHmac(req, raw, routerPath + url.search, form);
+          if (!verified.ok) return reply(401, verified.message);
+          for (const feature of features) {
+            for (const route of feature.routes ?? []) {
+              if (route.method !== req.method) continue;
+              const params = matchPath(route.path, routerPath);
+              if (!params) continue;
+              const record = {
+                feature: feature.feature,
+                method: req.method,
+                path: routerPath,
+                instanceId: verified.instanceId,
+                body: raw ? (form ? raw : body) : undefined,
+                at: new Date().toISOString()
+              };
+              requests.push(record);
+              return await route.handler({
+                ...ctxBase(feature.feature, params, verified.instanceId),
+                record
+              });
+            }
+          }
+          return reply(404, 'No such gateway route');
+        }
+
+        for (const feature of features) {
+          for (const route of feature.vendorRoutes ?? []) {
+            if (route.method !== req.method) continue;
+            const params = matchPath(route.path, path);
+            if (!params) continue;
+            return await route.handler(ctxBase(feature.feature, params, undefined));
+          }
+        }
+        return reply(404, 'Not found');
+      } catch (error) {
+        if (!res.headersSent) send(res, 500, `Mock error: ${error?.message ?? error}`);
+      }
+    });
+  });
+
+  await new Promise((resolve) => server.listen(port, resolve));
+  console.log(
+    `gateway mock on :${port} — features ${features.map((f) => f.feature).join(', ')}; ` +
+      (hmacKey
+        ? 'verifying instance signatures'
+        : 'NOT verifying signatures (set MOCK_INSTANCE_HMAC_KEY)') +
+      (eventsUrl ? `; events to ${eventsUrl}` : '')
+  );
+  return server;
+}
+
+const isMain =
+  process.argv[1] &&
+  (fileURLToPath(import.meta.url) === process.argv[1] ||
+    process.argv[1].endsWith('forklaunch-gateway-mock'));
+if (isMain) {
+  const server = await startGatewayMock();
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, () => server.close(() => process.exit(0)));
+  }
+}

package/bin/migrate-compliant-fields.mjs

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+/**
+ * Codemod for @forklaunch/core compliant fields.
+ *
+ * pii, phi and pci properties now load as CompliantField: the value is read
+ * with `.deanon` (plaintext) or `.anon` (de-identified). This rewrites every
+ * place a project used such a property as its value, by asking the
+ * project's own TypeScript program where a CompliantField meets something
+ * that is not one:
+ *
+ *   const s: string = user.email          ->  user.email.deanon
+ *   return { to: record.to }              ->  record.to.deanon
+ *   send(record.body)                     ->  send(record.body.deanon)
+ *   `Hi ${user.name}`                     ->  `Hi ${user.name.deanon}`
+ *   user.email.toLowerCase()              ->  user.email.deanon.toLowerCase()
+ *   user.email === input                  ->  user.email.deanon === input
+ *   ({ ...entity })                       ->  ({ ...deanon(entity) })
+ *
+ * Nullable fields get `?.deanon`. Entity data (em.create, em.assign) and
+ * `where` clauses are left alone: they accept plain values already.
+ *
+ * What it cannot decide is reported, not guessed: chiefly `where` clauses on
+ * fields that are not queryable, which need `.compliance(level, { queryable:
+ * true })` on the property (and a migration adding its `<column>_idx`).
+ *
+ * It runs on TypeScript 7's API (`typescript/unstable/sync`, the native
+ * compiler's type checker), from the project's own TypeScript when it has
+ * one, else the one installed with @forklaunch/core.
+ *
+ * Usage: npx -y -p @forklaunch/core forklaunch-migrate-compliant-fields
+ *          [path/to/tsconfig.json] [--dry-run] [--import-from <module exporting deanon>]
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const positional = args.filter(
+  (a, i) => !a.startsWith('--') && args[i - 1] !== '--import-from'
+);
+const tsconfigPath = path.resolve(positional[0] ?? 'tsconfig.json');
+const importFrom = args.includes('--import-from')
+  ? args[args.indexOf('--import-from') + 1]
+  : '@forklaunch/core/persistence';
+
+/** A TypeScript 7 module: the project's own first, then ours. */
+async function loadTypeScript(subpath) {
+  for (const from of [tsconfigPath, import.meta.url]) {
+    try {
+      const resolved = createRequire(from).resolve(`typescript/${subpath}`);
+      return await import(pathToFileURL(resolved).href);
+    } catch {
+      // try the next one
+    }
+  }
+  console.error(
+    `This codemod needs TypeScript 7 (typescript/${subpath}). Install typescript@7 in the project and run it again.`
+  );
+  process.exit(1);
+}
+const { API, TypeFlags } = await loadTypeScript('unstable/sync');
+const ast = await loadTypeScript('unstable/ast');
+const { SyntaxKind } = ast;
+
+const READ_MEMBERS = new Set(['anon', 'deanon', 'level']);
+
+/** The kinds TypeScript counts as declarations (ts.isDeclarationKind). */
+const DECLARATION_KINDS = new Set(
+  [
+    'ArrowFunction', 'BindingElement', 'ClassDeclaration', 'ClassExpression',
+    'ClassStaticBlockDeclaration', 'Constructor', 'EnumDeclaration', 'EnumMember',
+    'ExportSpecifier', 'FunctionDeclaration', 'FunctionExpression', 'GetAccessor',
+    'ImportClause', 'ImportEqualsDeclaration', 'ImportSpecifier', 'InterfaceDeclaration',
+    'JsxAttribute', 'MethodDeclaration', 'MethodSignature', 'ModuleDeclaration',
+    'NamespaceExportDeclaration', 'NamespaceImport', 'NamespaceExport', 'Parameter',
+    'PropertyAssignment', 'PropertyDeclaration', 'PropertySignature', 'SetAccessor',
+    'ShorthandPropertyAssignment', 'TypeAliasDeclaration', 'TypeParameter',
+    'VariableDeclaration'
+  ]
+    .map((name) => SyntaxKind[name])
+    .filter((kind) => kind !== undefined)
+);
+const isDeclaration = (node) => Boolean(node) && DECLARATION_KINDS.has(node.kind);
+
+/** Open the project; a fresh API per load so edits on disk are re-read. */
+function loadProject() {
+  const api = new API({ cwd: path.dirname(tsconfigPath) });
+  const snapshot = api.updateSnapshot({ openProjects: [tsconfigPath] });
+  const project = snapshot.getProject(tsconfigPath) ?? snapshot.getProjects()[0];
+  if (!project) {
+    console.error(`Could not open ${tsconfigPath}`);
+    api.close();
+    process.exit(1);
+  }
+  return { api, project };
+}
+
+const isUnion = (type) => Boolean(type && type.flags & TypeFlags.Union);
+
+function isCompliantType(type) {
+  if (!type) return false;
+  if (isUnion(type)) return type.getTypes().some(isCompliantType);
+  const symbol = type.getAliasSymbol() ?? type.getSymbol();
+  return symbol?.name === 'CompliantField';
+}
+
+function isNullableCompliant(type) {
+  return (
+    isUnion(type) &&
+    type.getTypes().some((t) => t.flags & (TypeFlags.Null | TypeFlags.Undefined))
+  );
+}
+
+/** Does `target` accept a CompliantField as it is (entity data, where, any)? */
+function acceptsField(checker, source, target) {
+  if (!target) return true;
+  if (target.flags & (TypeFlags.Any | TypeFlags.Unknown)) return true;
+  return checker.isTypeAssignableTo(source, target);
+}
+
+/** Why this expression, typed CompliantField, needs its value. */
+function needsValue(checker, node, type) {
+  const parent = node.parent;
+  if (!parent) return false;
+
+  // user.email.toLowerCase()  (anything but .anon / .deanon / .level)
+  if (
+    ast.isPropertyAccessExpression(parent) &&
+    parent.expression === node &&
+    !READ_MEMBERS.has(parent.name.text)
+  ) {
+    return true;
+  }
+  // `${user.email}`
+  if (ast.isTemplateSpan(parent) && parent.expression === node) return true;
+  // user.email === input, user.email + '!'
+  if (ast.isBinaryExpression(parent)) {
+    const op = parent.operatorToken.kind;
+    const other = parent.left === node ? parent.right : parent.left;
+    const comparison = [
+      SyntaxKind.EqualsEqualsEqualsToken,
+      SyntaxKind.ExclamationEqualsEqualsToken,
+      SyntaxKind.EqualsEqualsToken,
+      SyntaxKind.ExclamationEqualsToken,
+      SyntaxKind.PlusToken
+    ].includes(op);
+    if (comparison) {
+      const otherType = checker.getTypeAtLocation(other);
+      const otherIsNullish =
+        otherType && otherType.flags & (TypeFlags.Null | TypeFlags.Undefined);
+      return !isCompliantType(otherType) && !otherIsNullish;
+    }
+    if (op === SyntaxKind.EqualsToken && parent.left === node) return false;
+  }
+  // Assignments, returns, arguments, properties: compare with the
+  // contextual type.
+  const contextual = checker.getContextualType(node);
+  if (contextual) return !acceptsField(checker, type, contextual);
+  return false;
+}
+
+function sourceFiles(program) {
+  return program
+    .getSourceFileNames()
+    .filter((fileName) => !fileName.includes('/node_modules/'))
+    .map((fileName) => program.getSourceFile(fileName))
+    .filter((sourceFile) => sourceFile && !sourceFile.isDeclarationFile);
+}
+
+function collectEdits(project) {
+  const { checker, program } = project;
+  const edits = new Map(); // fileName -> [{ pos, text }]
+  let count = 0;
+
+  for (const sourceFile of sourceFiles(program)) {
+    const fileEdits = [];
+    let needsImport = false;
+
+    const visit = (node) => {
+      // { ...entity }: compliant properties live on the prototype, so a
+      // spread drops them; deanon(entity) copies them as values.
+      if (ast.isSpreadAssignment(node)) {
+        const spreadType = checker.getTypeAtLocation(node.expression);
+        const carriesField =
+          spreadType &&
+          checker
+            .getPropertiesOfType(spreadType)
+            .some((property) =>
+              isCompliantType(
+                checker.getTypeOfSymbolAtLocation(property, node.expression)
+              )
+            );
+        if (carriesField) {
+          fileEdits.push({
+            pos: ast.getTokenPosOfNode(node.expression, sourceFile),
+            text: 'deanon('
+          });
+          fileEdits.push({ pos: node.expression.end, text: ')' });
+          needsImport = true;
+          count += 1;
+          return undefined;
+        }
+      }
+      const isCandidate =
+        ast.isPropertyAccessExpression(node) ||
+        ast.isElementAccessExpression(node) ||
+        (ast.isIdentifier(node) &&
+          !ast.isPropertyAccessExpression(node.parent) &&
+          !isDeclaration(node.parent));
+      if (isCandidate) {
+        const type = checker.getTypeAtLocation(node);
+        if (isCompliantType(type) && needsValue(checker, node, type)) {
+          fileEdits.push({
+            pos: node.end,
+            text: isNullableCompliant(type) ? '?.deanon' : '.deanon'
+          });
+          count += 1;
+          return undefined; // do not descend into a rewritten expression
+        }
+      }
+      node.forEachChild(visit);
+      return undefined; // a truthy return would stop forEachChild
+    };
+    visit(sourceFile);
+
+    if (needsImport && !/\bdeanon\b[^;]*from/.test(sourceFile.text)) {
+      const imports = sourceFile.statements.filter(ast.isImportDeclaration);
+      const pos = imports.length ? imports[imports.length - 1].end : 0;
+      fileEdits.push({
+        pos,
+        text: `${pos ? '\n' : ''}import { deanon } from '${importFrom}';${pos ? '' : '\n'}`
+      });
+    }
+    if (fileEdits.length) edits.set(sourceFile.fileName, fileEdits);
+  }
+  return { edits, count };
+}
+
+function applyEdits(edits) {
+  for (const [fileName, fileEdits] of edits) {
+    let text = readFileSync(fileName, 'utf8');
+    // Apply back to front; at one position, later-pushed edits go first so
+    // pushes read left to right in the result.
+    const ordered = fileEdits
+      .map((edit, index) => ({ ...edit, index }))
+      .sort((a, b) => b.pos - a.pos || b.index - a.index);
+    for (const edit of ordered) {
+      text = text.slice(0, edit.pos) + edit.text + text.slice(edit.pos);
+    }
+    if (!dryRun) writeFileSync(fileName, text);
+    console.log(
+      `${dryRun ? 'would edit' : 'edited'} ${path.relative(process.cwd(), fileName)} (${fileEdits.length})`
+    );
+  }
+}
+
+/** A diagnostic's message and its chain, flattened. */
+function flatten(diagnostic, separator) {
+  return [diagnostic.text, ...(diagnostic.messageChain ?? []).map((d) => flatten(d, separator))]
+    .filter(Boolean)
+    .join(separator);
+}
+
+function reportRemaining(project) {
+  const { program } = project;
+  const remaining = sourceFiles(program)
+    .flatMap((sourceFile) => [
+      ...program.getSyntacticDiagnostics(sourceFile.fileName),
+      ...program.getSemanticDiagnostics(sourceFile.fileName)
+    ])
+    .filter((d) => flatten(d, '\n').includes('CompliantField'));
+  if (remaining.length === 0) {
+    console.log('No compliant-field type errors remain.');
+    return 0;
+  }
+  console.log(`\n${remaining.length} compliant-field error(s) need a decision:`);
+  for (const d of remaining) {
+    const sourceFile = d.fileName ? program.getSourceFile(d.fileName) : undefined;
+    const where = sourceFile
+      ? (() => {
+          const { line, character } = sourceFile.getLineAndCharacterOfPosition(d.pos ?? 0);
+          return `${path.relative(process.cwd(), d.fileName)}:${line + 1}:${character + 1}`;
+        })()
+      : '';
+    const message = flatten(d, ' ');
+    const hint = /FilterQuery|FilterValue|ExpandScalar|OperatorMap/.test(message)
+      ? '  -> a `where` on a field that is not queryable: add `{ queryable: true }` to its .compliance() call and generate a migration'
+      : '';
+    console.log(`  ${where}  ${message.slice(0, 240)}${hint ? `\n${hint}` : ''}`);
+  }
+  return remaining.length;
+}
+
+let loaded = loadProject();
+const { edits, count } = collectEdits(loaded.project);
+applyEdits(edits);
+console.log(
+  `${count} read(s) ${dryRun ? 'would be' : ''} rewritten to .deanon across ${edits.size} file(s).`
+);
+if (!dryRun && count > 0) {
+  loaded.api.close();
+  loaded = loadProject();
+}
+const left = reportRemaining(loaded.project);
+loaded.api.close();
+console.log(
+  '\nNext: generate a migration (queryable fields add <column>_idx), deploy, then run ' +
+    'reencryptEncryptedColumns() once to seal existing rows into v4 and write blind indexes.'
+);
+process.exit(left > 0 ? 2 : 0);

package/bin/model-gateway-mock.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * The ForkLaunch gateway mock, under its original name. Every feature's mock
+ * (models, payments, email, sms, whatsapp, voice) now lives in
+ * ./gateway-mock; see gateway-mock/server.mjs for settings and control
+ * endpoints. Kept so existing docker-compose files and scripts keep working.
+ */
+import { startGatewayMock } from './gateway-mock/server.mjs';
+
+const server = await startGatewayMock();
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => server.close(() => process.exit(0)));
+}