@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/src/lib/ai/registry-audit.js

@@ -0,0 +1,285 @@
+/**
+ * registry-audit.js — o registry de modelos do projeto: tarifa por alias e
+ * protocolo (`api`) por alias.
+ *
+ * As duas perguntas saem do standard `ai-agents/providers/model-registry.md`,
+ * não da memória de quem implementa:
+ *
+ *   - **tarifa por alias** — um alias sem tarifa é um custo que ninguém
+ *     consegue prever antes de a chamada ser paga. O caso medido no acervo é o
+ *     GHLBrain, cujo mapa `Pricing.Models` é literalmente `{}`.
+ *   - **`api` por alias** — o standard mede, sobre o pin, que
+ *     `AgentApi.Responses = 0`, ou seja `default(AgentApi)` é Responses, e que
+ *     `ModelRegistry.ReadApi` devolve `AgentApi.Responses` quando o campo está
+ *     ausente. A ausência do campo, portanto, NÃO é defeito: é uma decisão
+ *     tomada por omissão. O achado NOMEIA o default assumido e pede
+ *     confirmação — nunca afirma defeito.
+ *
+ * Severidade: `warn` nas duas. Só `pin-drift` produz `error`.
+ */
+
+import { readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, basename } from 'node:path';
+import { collectProjectFiles } from './ai-project-scan.js';
+import { jsoncToJson } from './comment-stripper.js';
+
+/** Limite de tamanho para um JSON candidato (bytes de texto) — evita ler dumps. */
+const MAX_JSON_CHARS = 512 * 1024;
+
+/**
+ * Lê um candidato a registry aceitando **JSONC**.
+ *
+ * Não é indulgência: é paridade com o leitor de produção. O exemplar canônico
+ * `framework/templates/dotnet/ai-kit/src/Morph.AiKit/Providers/model-registry.v2.json`
+ * — que diz na primeira linha "copie para `config/model-registry.json` no
+ * projeto" — tem 20 linhas de `//`, e `ModelRegistry.FromJson` do kit declara
+ * `CommentHandling = JsonCommentHandling.Skip` + `AllowTrailingCommas = true`.
+ * Com `JSON.parse` cru, as duas checagens de registry saíam `skip` sobre a
+ * ÚNICA forma que existem para auditar — e `skip` não muda o código de saída,
+ * então o silêncio era total. A auditoria tem de enxergar a mesma forma que o
+ * leitor de produção enxerga.
+ */
+function readJsonSafe(file) {
+  try {
+    const raw = readFileSync(file, 'utf8');
+    if (raw.length > MAX_JSON_CHARS) return null;
+    const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return JSON.parse(jsoncToJson(text));
+    }
+  } catch {
+    return null;
+  }
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** A forma que `ai-agents/providers/model-registry.md` define. */
+function asAliasSource(file, data) {
+  if (!isPlainObject(data)) return null;
+  if (typeof data.defaultAlias !== 'string') return null;
+  if (!isPlainObject(data.aliases)) return null;
+  return { file, aliases: data.aliases, defaultAlias: data.defaultAlias, data };
+}
+
+/** A forma medida no GHLBrain: a seção `Pricing` de um `appsettings*.json`. */
+function asPricingSource(file, data) {
+  if (!isPlainObject(data)) return null;
+  const pricing = data.Pricing ?? data.pricing;
+  if (!isPlainObject(pricing)) return null;
+  const models = pricing.Models ?? pricing.models;
+  if (!isPlainObject(models)) return null;
+  return { file, models };
+}
+
+/**
+ * Localiza o registry de modelos do projeto.
+ *
+ * Ordem, primeira ocorrência ganha (spec §3.5):
+ *   1. path declarado em `.morph/config/config.json → project.ai.modelRegistry`;
+ *   2. um `*.json` cujo objeto raiz tenha `defaultAlias` **e** um mapa `aliases`;
+ *   3. a seção `Pricing` de um `appsettings*.json`.
+ *
+ * @param {string} root - raiz do projeto
+ * @param {object|null} config - conteúdo de `.morph/config/config.json`, se houver
+ * @returns {null | { aliasSource: object|null, pricingSource: object|null }}
+ *   `null` quando NENHUMA das três formas foi encontrada.
+ */
+export function locateAiRegistry(root, config = null) {
+  let aliasSource = null;
+  let pricingSource = null;
+
+  const declared = config?.project?.ai?.modelRegistry;
+  if (typeof declared === 'string' && declared.trim()) {
+    const file = isAbsolute(declared) ? declared : join(root, declared);
+    if (existsSync(file)) {
+      const data = readJsonSafe(file);
+      aliasSource = asAliasSource(file, data);
+      pricingSource = extractPricingFromRegistry(file, data) ?? pricingSource;
+    }
+  }
+
+  if (!aliasSource) {
+    const candidates = collectProjectFiles(root, (name) => name.toLowerCase().endsWith('.json'));
+    for (const file of candidates) {
+      const data = readJsonSafe(file);
+      const found = asAliasSource(file, data);
+      if (found) {
+        aliasSource = found;
+        pricingSource = pricingSource ?? extractPricingFromRegistry(file, data);
+        break;
+      }
+    }
+  }
+
+  if (!pricingSource) {
+    const appsettings = collectProjectFiles(root, (name) => {
+      const lower = name.toLowerCase();
+      return lower.startsWith('appsettings') && lower.endsWith('.json');
+    });
+    for (const file of appsettings) {
+      const found = asPricingSource(file, readJsonSafe(file));
+      if (found) { pricingSource = found; break; }
+    }
+  }
+
+  if (!aliasSource && !pricingSource) return null;
+  return { aliasSource, pricingSource };
+}
+
+/** Mapa de tarifas embutido no próprio registry de modelos, quando existir. */
+function extractPricingFromRegistry(file, data) {
+  if (!isPlainObject(data)) return null;
+  const pricing = data.pricing ?? data.Pricing;
+  if (isPlainObject(pricing)) {
+    const models = pricing.Models ?? pricing.models;
+    return { file, models: isPlainObject(models) ? models : pricing };
+  }
+  return null;
+}
+
+/** O alias declara tarifa **no próprio elemento** (a forma v2 do exemplar canônico)? */
+function aliasHasPricing(def) {
+  return isPlainObject(def) && isPlainObject(def.pricing);
+}
+
+/** O alias declara a AUSÊNCIA de tarifa por escrito? */
+function aliasHasWaiver(def) {
+  return isPlainObject(def) && typeof def.pricingWaiver === 'string' && def.pricingWaiver.trim() !== '';
+}
+
+/**
+ * O documento usa a forma **por alias** (`pricing` / `pricingWaiver` dentro de
+ * cada alias) em vez da forma de mapa no topo?
+ *
+ * Basta UM alias declarar qualquer uma das duas: um documento meio-preenchido
+ * ainda é um documento na forma v2, e os aliases que faltam é que são o achado.
+ */
+export function usesPerAliasPricing(aliasSource) {
+  if (!aliasSource) return false;
+  return Object.values(aliasSource.aliases).some((d) => aliasHasPricing(d) || aliasHasWaiver(d));
+}
+
+/**
+ * Todo alias do registry tem uma DECISÃO de tarifa?
+ *
+ * Duas formas, e a checagem cobra a que o documento usa:
+ *
+ * 1. **Por alias** (`model-registry.v2.json`, o exemplar que o framework manda
+ *    copiar) — a REGRA DURA escrita no próprio exemplar e imposta por
+ *    `ModelRegistry.ReadPricing`: *"todo alias declara `pricing` OU
+ *    `pricingWaiver` — nunca os dois, nunca nenhum"*. Um `pricingWaiver` é uma
+ *    tarifa **decidida**: a ausência está escrita, não esquecida, e acusá-la
+ *    seria gritar em código correto.
+ * 2. **Mapa no topo** (`pricing` na raiz, ou a seção `Pricing.Models` de um
+ *    `appsettings*.json` — a forma medida no GHLBrain, cujo mapa é
+ *    literalmente `{}`).
+ *
+ * Os achados de MAPA (`pricing-map-missing` / `pricing-map-empty`) só existem
+ * na forma 2: num documento v2 não há mapa a faltar, e emitir o achado ali era
+ * o primeiro dos seis falsos positivos sobre o exemplar canônico.
+ *
+ * @param {ReturnType<typeof locateAiRegistry>} registry
+ * @returns {null | Array<{ id: string, severity: 'warn', alias?: string, message: string }>}
+ */
+export function auditModelPricing(registry) {
+  if (!registry) return null;
+  const { aliasSource, pricingSource } = registry;
+  const findings = [];
+
+  const models = pricingSource?.models ?? null;
+  const tariffKeys = models ? new Set(Object.keys(models)) : new Set();
+  const perAlias = usesPerAliasPricing(aliasSource);
+
+  if (!perAlias) {
+    if (models === null) {
+      findings.push({
+        id: 'pricing-map-missing',
+        severity: 'warn',
+        message: 'Nenhuma tarifa encontrada: nem `pricing`/`pricingWaiver` por alias (a forma do '
+          + 'exemplar `model-registry.v2.json`), nem `pricing` na raiz, nem `Pricing.Models` num '
+          + 'appsettings. Sem tarifa não há previsão de custo antes de a chamada ser paga.',
+      });
+    } else if (tariffKeys.size === 0) {
+      findings.push({
+        id: 'pricing-map-empty',
+        severity: 'warn',
+        message: `O mapa de tarifas em \`${basename(pricingSource.file)}\` está vazio — declarado e `
+          + 'sem uma única entrada. É a forma mais silenciosa de não ter tarifa: o campo existe, o '
+          + 'dado não.',
+      });
+    }
+  }
+
+  if (aliasSource) {
+    for (const [alias, def] of Object.entries(aliasSource.aliases)) {
+      const model = isPlainObject(def) ? def.model : null;
+      const rotulo = `\`${alias}\`${model ? ` (modelo \`${model}\`)` : ''}`;
+      const hasPricing = aliasHasPricing(def);
+      const hasWaiver = aliasHasWaiver(def);
+
+      if (hasPricing && hasWaiver) {
+        findings.push({
+          id: 'alias-pricing-and-waiver',
+          severity: 'warn',
+          alias,
+          message: `O alias ${rotulo} declara \`pricing\` E \`pricingWaiver\`. A regra do exemplar `
+            + 'é uma OU a outra, nunca as duas: com as duas presentes não dá para saber se a '
+            + 'tarifa vale ou se a isenção vale.',
+        });
+        continue;
+      }
+      if (hasPricing || hasWaiver) continue; // decisão tomada — inclusive a de não haver tarifa
+
+      const cobertoPeloMapa = tariffKeys.has(alias) || (model !== null && tariffKeys.has(model));
+      if (cobertoPeloMapa) continue;
+
+      findings.push({
+        id: 'alias-without-pricing',
+        severity: 'warn',
+        alias,
+        message: `O alias ${rotulo} não declara \`pricing\` nem \`pricingWaiver\`, e não aparece em `
+          + 'nenhum mapa de tarifas. Não é a tarifa que falta: falta a DECISÃO — um `pricingWaiver` '
+          + 'com o motivo por extenso também fecha a questão.',
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Todo alias declara `api`?
+ *
+ * O default do standard é **`responses`**: medido sobre o pin, `AgentApi.Responses = 0`
+ * e `ModelRegistry.ReadApi` devolve Responses quando o campo está ausente. A mensagem
+ * nomeia esse default e PEDE CONFIRMAÇÃO — a ausência do campo é uma decisão por
+ * omissão, não um defeito. É a pergunta que o `ModelRegistry.cs` do ProspectPRO
+ * documenta ter custado um bug.
+ *
+ * @param {ReturnType<typeof locateAiRegistry>} registry
+ * @returns {null | Array<{ id: string, severity: 'warn', alias: string, message: string }>}
+ *   `null` quando não há aliases para perguntar.
+ */
+export function auditApiPerAlias(registry) {
+  if (!registry || !registry.aliasSource) return null;
+  const findings = [];
+  for (const [alias, def] of Object.entries(registry.aliasSource.aliases)) {
+    const api = isPlainObject(def) ? def.api : undefined;
+    if (typeof api === 'string' && api.trim()) continue;
+    findings.push({
+      id: 'alias-without-api',
+      severity: 'warn',
+      alias,
+      message: `O alias \`${alias}\` não declara o campo \`api\`. O registry trata a omissão como `
+        + '`responses` (Responses API) — confirme que este alias não precisa falar `chat` '
+        + '(Chat Completions). Não é acusação: é a decisão que está sendo tomada por omissão.',
+    });
+  }
+  return findings;
+}

package/src/lib/e2e/compose-env.js

@@ -20,23 +20,37 @@
 
 import { join } from 'path';
 
+import chalk from 'chalk';
+
 import { loadEnvFile } from '../../../framework/hooks/shared/e2e-check.js';
-import { allocateEnvBlock, resolveFleetConfig } from '../worktree/env-allocator.js';
+import { allocateEnvBlock, portLayout, resolveFleetConfig } from '../worktree/env-allocator.js';
 
 /**
  * Build the environment a `docker compose` invocation should carry.
  *
- * Port variables mirror `buildEnvFileContent()` in env-allocator.js so a
- * compose file and a `.morph/worktree.env` describe the same world: `PORT` for
- * the web tier, `ASPNETCORE_URLS` on base+1 for a .NET backend.
+ * Port variables come from `portLayout()` in env-allocator.js — the SAME
+ * function that renders `.morph/worktree.env` — so a compose file and the
+ * worktree manifest describe the same world by construction (`PORT`,
+ * `API_PORT`/`ASPNETCORE_URLS`, `POSTGRES_PORT`, `COMPOSE_PROJECT_NAME`).
  *
  * `PLAYWRIGHT_BASE_URL` is derived here rather than left to the spec config —
  * the suite has to be told where the app actually landed, otherwise a feature
  * on port 4020 gets tested against a hardcoded localhost:3000 and fails with
  * ECONNREFUSED that looks exactly like a broken app.
  *
+ * The credentials env file loads AFTER the layout but cannot outrank it: a
+ * `.env.e2e` copied from a sibling worktree carries THAT worktree's block, and
+ * letting it win points this stack at the neighbour's postgres while every
+ * other surface still reports the allocated port. The protected keys are the
+ * ones actually assigned above — never a second literal list, which is exactly
+ * how an offset lands in one writer and not the other. A key that gets ignored
+ * is announced on stderr (never stdout: `morph-spec env` writes shell-eval
+ * output there), because swapping a silent override for a silent discard just
+ * moves the debugging session.
+ *
  * Fail-open throughout: with no git dir (or a corrupt registry) the caller gets
- * default ports, which only matters when two stacks run at once.
+ * default ports, which only matters when two stacks run at once. With no layout
+ * applied nothing is filtered — there the env file is the only port source.
  *
  * @param {object} params
  * @param {string} params.cwd - project root
@@ -47,20 +61,20 @@ import { allocateEnvBlock, resolveFleetConfig } from '../worktree/env-allocator.
  */
 export function buildComposeEnv({ cwd, config, featureName, gitCommonDir }) {
   const env = {};
+  /** @type {Set<string>|null} - null while no layout has been applied */
+  let layoutKeys = null;
 
   if (gitCommonDir) {
     try {
       const { basePort, blockSize } = resolveFleetConfig(cwd);
       const block = allocateEnvBlock(featureName, { gitCommonDir, basePort, blockSize });
 
-      env.MORPH_PORT_BASE = String(block.base);
-      env.MORPH_PORT_RANGE = `${block.range[0]}-${block.range[1]}`;
-      env.PORT = String(block.base);
-      env.PLAYWRIGHT_BASE_URL = `http://localhost:${block.base}`;
-
-      if (/\bdotnet\b/i.test(String(config?.project?.stack ?? ''))) {
-        env.ASPNETCORE_URLS = `http://localhost:${block.base + 1}`;
-      }
+      const layout = {
+        ...portLayout(block, { stack: config?.project?.stack ?? '', feature: featureName }),
+        PLAYWRIGHT_BASE_URL: `http://localhost:${block.base}`,
+      };
+      Object.assign(env, layout);
+      layoutKeys = new Set(Object.keys(layout));
     } catch {
       // No block → default ports. Surfaces later as a port conflict, never here.
     }
@@ -68,7 +82,34 @@ export function buildComposeEnv({ cwd, config, featureName, gitCommonDir }) {
 
   // Credentials live in a gitignored env file, never in the committed config.
   const envFile = config?.e2e?.auth?.envFile;
-  if (envFile) Object.assign(env, loadEnvFile(join(cwd, envFile)));
+  if (envFile) {
+    const ignored = [];
+    for (const [key, value] of Object.entries(loadEnvFile(join(cwd, envFile)))) {
+      if (layoutKeys?.has(key)) ignored.push(key);
+      else env[key] = value;
+    }
+    if (ignored.length) reportIgnoredLayoutKeys(envFile, ignored, env);
+  }
 
   return env;
 }
+
+/**
+ * Tell the caller — `e2e up`, the `e2e` node of `verify`, `stack-teardown` and
+ * `morph-spec env` all reach this through `buildComposeEnv` — which keys of the
+ * credentials file were dropped and what won instead.
+ *
+ * stderr, always: `morph-spec env` prints `export K=v` on stdout for a
+ * shell to eval, and `verify` prints JSON there.
+ *
+ * @param {string} envFile
+ * @param {string[]} ignored
+ * @param {Record<string,string>} env - the layout that won
+ */
+function reportIgnoredLayoutKeys(envFile, ignored, env) {
+  const shown = ignored.map((key) => `${key}=${env[key]}`).join(', ');
+  console.warn(chalk.yellow(
+    `  ⚠ ${envFile}: ${ignored.join(', ')} ignorada(s) — o bloco de portas desta worktree prevalece (${shown}). `
+    + 'O envFile carrega credenciais; portas vêm do bloco alocado.',
+  ));
+}

package/src/lib/e2e/stack-teardown.js

@@ -0,0 +1,115 @@
+/**
+ * Reclaim a feature's verification stack — containers, ports, named volumes
+ * and the freshness stamp — from the tree that owns the feature.
+ *
+ * `morph-spec verify` leaves the stack UP on purpose (cold-starting a
+ * container per task is what makes the loop unusable), so something has to be
+ * the one place that brings it down when the feature closes. That place is
+ * this module, shared by `finish` and `delete --with-worktree`.
+ *
+ * Three things the old root-side teardown got wrong, each pinned by a test:
+ *   1. It ran from the ROOT. A compose that exists only in the worktree was
+ *      never found, and a bind mount resolved to the wrong checkout.
+ *   2. It passed a bare `COMPOSE_PROJECT_NAME`. Without the port block
+ *      (`PORT`, `POSTGRES_PORT`, …) compose resolves a different config than
+ *      the one that came up, and `down` misses the containers.
+ *   3. It never removed volumes or the stamp. Postgres data and a stamp saying
+ *      "source unchanged since build" outlived the feature.
+ *
+ * Entirely fail-open: no compose, no docker, or a stubborn container are all
+ * non-events for the caller — a stack that refuses to come down must never
+ * fail a finish that already merged.
+ *
+ * @module lib/e2e/stack-teardown
+ */
+
+import { execFileSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+
+import {
+  composeProjectName,
+  defaultExec,
+  deleteStamp,
+  resolveComposeFile,
+  tearDownStack,
+} from '../../../framework/hooks/shared/e2e-check.js';
+import { buildComposeEnv } from './compose-env.js';
+
+/**
+ * @param {string} feature
+ * @param {object} params
+ * @param {string} params.root - primary root (absolute)
+ * @param {string|null} [params.worktreePath] - the feature's live worktree, if any
+ * @param {boolean} [params.volumes=true] - also remove named volumes (`down -v`)
+ * @param {Function} [params._exec] - injectable executor (testing)
+ * @returns {{ attempted: boolean, cwd: string, status: 'pass'|'fail'|'skip', stampDeleted: boolean, output?: string }}
+ */
+export function tearDownFeatureStack(feature, { root, worktreePath = null, volumes = true, _exec = defaultExec } = {}) {
+  const cwd = worktreePath && existsSync(worktreePath) ? worktreePath : root;
+  const projectName = composeProjectName(feature);
+  const gitCommonDir = resolveGitCommonDir(root);
+
+  try {
+    const config = readConfig(cwd) ?? readConfig(root);
+
+    // The owning tree's compose first; the root's copy is the fallback for a
+    // worktree already half torn down (versioned file, so equivalent).
+    let composeCwd = cwd;
+    let composeFile = resolveComposeFile(cwd, config);
+    if (!composeFile && cwd !== root) {
+      composeCwd = root;
+      composeFile = resolveComposeFile(root, config);
+    }
+
+    if (!composeFile) {
+      // Nothing to bring down — but a stamp left behind would tell the next
+      // `up` that a stack it cannot see is still fresh.
+      return { attempted: false, cwd, status: 'skip', stampDeleted: deleteStamp(gitCommonDir, projectName) };
+    }
+
+    const env = {
+      COMPOSE_PROJECT_NAME: projectName,
+      ...buildComposeEnv({ cwd: composeCwd, config, featureName: feature, gitCommonDir }),
+    };
+    const result = tearDownStack(composeCwd, { composeFile, projectName, env, volumes }, _exec);
+
+    return {
+      attempted: true,
+      cwd: composeCwd,
+      status: result.status,
+      stampDeleted: deleteStamp(gitCommonDir, projectName),
+      ...(result.status === 'fail' && result.output ? { output: result.output } : {}),
+    };
+  } catch {
+    // Unconditional even when the teardown itself blew up: the stamp must not
+    // outlive the stack it described.
+    return { attempted: false, cwd, status: 'fail', stampDeleted: deleteStamp(gitCommonDir, projectName) };
+  }
+}
+
+/** BOM-tolerant config read; null when absent or malformed. */
+function readConfig(dir) {
+  try {
+    const path = join(dir, '.morph', 'config', 'config.json');
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, 'utf8').replace(/^/, ''));
+  } catch {
+    return null;
+  }
+}
+
+/** Same resolution (and same fail-open) as verify-runner's. */
+function resolveGitCommonDir(cwd) {
+  try {
+    const common = execFileSync('git', ['rev-parse', '--git-common-dir'], {
+      cwd,
+      stdio: 'pipe',
+      encoding: 'utf-8',
+      windowsHide: true,
+    }).trim();
+    return common ? resolve(cwd, common) : null;
+  } catch {
+    return null;
+  }
+}