@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/framework/templates/dotnet/ai-kit/tests/Morph.AiKit.Tests/UsageCostMiddlewareTests.cs

@@ -7,16 +7,10 @@ using Xunit;
 
 namespace Morph.AiKit.Tests;
 
-/// <summary>
-/// Canarios do <see cref="UsageCostMiddleware"/> (T11). A afirmacao central da task e uma
-/// so: <b><c>cost_usd</c> nao sai nulo, e o zero nunca e ambiguo</b> — ou e medicao, ou e
-/// dispensa escrita, ou e lacuna declarada.
-/// </summary>
 public sealed class UsageCostMiddlewareTests
 {
     private static readonly DateTimeOffset FixedNow = new(2026, 9, 8, 12, 0, 0, TimeSpan.Zero);
 
-    /// <summary>Tarifa ilustrativa com desconto de cache — a que exercita a aritmetica inteira.</summary>
     private static ModelPricing Tariff()
         => new(InputPerMTok: 1.25m, OutputPerMTok: 10.0m, CachedInputPerMTok: 0.125m);
 
@@ -42,22 +36,11 @@ public sealed class UsageCostMiddlewareTests
 
         var sink = new FakeUsageCostSink();
 
-        // A extensao publica e o caminho de registro: se ela quebrar, o teste quebra junto.
         var client = inner.AsBuilder().UseUsageCost(alias, sink, new FakeClock(FixedNow)).Build();
 
         return (client, inner, sink);
     }
 
-    // ---------------------------------------------------------------------------------
-    // doneCriteria 1: Usage conhecido + ModelPricing conhecido => CostUsd EXATO
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// O valor esperado esta escrito a mao, com a semantica correta de token cacheado:
-    /// <b>cacheado e SUBCONJUNTO da entrada</b>. 1000 de entrada com 400 servidos do cache
-    /// custam 600 na tarifa cheia mais 400 na de cache — nunca 1000 mais 400. E por isso que
-    /// este caso, e nao um sem cache, e o que denuncia uma segunda aritmetica.
-    /// </summary>
     [Fact]
     public async Task AKnownUsageAgainstAKnownTariffProducesTheExactCostInUsd()
     {
@@ -83,13 +66,6 @@ public sealed class UsageCostMiddlewareTests
         Assert.Equal(FixedNow, record.At);
     }
 
-    /// <summary>
-    /// O canario que torna "nao existe uma segunda conta do custo" verificavel em vez de
-    /// prometido: o custo publicado tem de ser <b>identico</b> ao de
-    /// <see cref="ModelPricing.ComputeCostUsd"/> — inclusive nos casos que separam as duas
-    /// formulas plausiveis (cacheado sem tarifa de cache, cacheado igual a entrada, saida
-    /// zerada).
-    /// </summary>
     [Theory]
     [InlineData(1000, 200, 400L)]
     [InlineData(1000, 200, null)]
@@ -111,11 +87,6 @@ public sealed class UsageCostMiddlewareTests
         Assert.Equal(pricing.ComputeCostUsd(input, output, cached), sink.Records[0].CostUsd);
     }
 
-    /// <summary>
-    /// Tarifa sem desconto de cache declarado: nulo em <c>CachedInputPerMTok</c> significa
-    /// "sem desconto", <b>nunca</b> "de graca" — a entrada inteira e cobrada cheia mesmo com
-    /// tokens vindos do cache.
-    /// </summary>
     [Fact]
     public async Task WithoutADeclaredCacheTariffTheWholeInputIsChargedAsInput()
     {
@@ -127,19 +98,10 @@ public sealed class UsageCostMiddlewareTests
             [new ChatMessage(ChatRole.User, "oi")],
             cancellationToken: TestContext.Current.CancellationToken);
 
-        // (1000 * 1.25) + (200 * 10.0) = 3250 por 1M tokens. O cacheado nao rende desconto.
+        // (1000 * 1.25) + (200 * 10.0) = 3250 por 1M tokens: o cacheado nao rende desconto.
         Assert.Equal(0.00325m, sink.Records[0].CostUsd);
     }
 
-    // ---------------------------------------------------------------------------------
-    // doneCriteria 2: alias sem Pricing => CostUsd == 0, ausencia sinalizada, SEM excecao
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// Alias sem tarifa e caminho previsto, nao erro. E o zero nao e anonimo: o motivo
-    /// escrito no <c>pricingWaiver</c> do registry viaja no record. Nao ha excecao — e nao
-    /// ha nulo em <c>CostUsd</c>.
-    /// </summary>
     [Fact]
     public async Task AnAliasWithoutATariffRecordsTokensWithZeroCostAndSaysWhy()
     {
@@ -156,19 +118,14 @@ public sealed class UsageCostMiddlewareTests
 
         var record = Assert.Single(sink.Records);
 
-        Assert.Equal(0m, record.CostUsd);                       // zero, jamais nulo
+        Assert.Equal(0m, record.CostUsd);
         Assert.Equal(UsageCostStatus.Waived, record.Status);
-        Assert.False(record.IsMeasuredCost);                    // logo, nao entra na soma
+        Assert.False(record.IsMeasuredCost);
         Assert.Equal(alias.PricingWaiver, record.PricingWaiver);
-        Assert.Equal(900, record.InputTokens);                  // os tokens continuam medidos
+        Assert.Equal(900, record.InputTokens);
         Assert.Equal(100, record.OutputTokens);
     }
 
-    /// <summary>
-    /// A regra que sustenta a anterior mora no registry (T8): um alias sem tarifa <b>e</b>
-    /// sem dispensa nao carrega. Por isso um record <c>Waived</c> sempre tem motivo — a
-    /// ausencia por esquecimento morre antes de chegar ao middleware.
-    /// </summary>
     [Fact]
     public void AWaivedRecordAlwaysHasAReasonBecauseTheRegistryRefusesAnAliasWithNeither()
     {
@@ -180,13 +137,9 @@ public sealed class UsageCostMiddlewareTests
         var refusal = Assert.Throws<ModelRegistryException>(() => ModelAlias.ValidatePricingDecision(orphan));
         Assert.Contains("sem-decisao", refusal.Message, StringComparison.Ordinal);
 
-        ModelAlias.ValidatePricingDecision(WaivedAlias());   // com dispensa escrita, passa
+        ModelAlias.ValidatePricingDecision(WaivedAlias());
     }
 
-    /// <summary>
-    /// A soma so junta o que foi medido. Uma volta tarifada mais uma dispensada somam o
-    /// custo da primeira — o zero da dispensa nao "abaixa a media" nem some do relatorio.
-    /// </summary>
     [Fact]
     public async Task OnlyMeasuredCostsEnterTheSum()
     {
@@ -210,15 +163,6 @@ public sealed class UsageCostMiddlewareTests
         Assert.Equal(0.0028m, sink.MeasuredTotalUsd);
     }
 
-    // ---------------------------------------------------------------------------------
-    // O terceiro zero: o provider nao reportou uso
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// Resposta sem <c>Usage</c>: a linha sai marcada como lacuna. Nao publicar nada faria o
-    /// custo desaparecer do relatorio, que e a mesma dor por outro angulo; publicar como
-    /// <c>Computed</c> mentiria que a volta custou zero.
-    /// </summary>
     [Fact]
     public async Task AResponseWithoutUsageIsRecordedAsAGapNotAsFree()
     {
@@ -236,11 +180,6 @@ public sealed class UsageCostMiddlewareTests
         Assert.Equal(0m, sink.MeasuredTotalUsd);
     }
 
-    /// <summary>
-    /// <c>cached &gt; input</c> e o provider se contradizendo. A conta do T8 recusa esse par
-    /// com excecao — e recusar aqui derrubaria a resposta do usuario por causa de um
-    /// contador. O middleware degrada para lacuna declarada, sem lancar.
-    /// </summary>
     [Fact]
     public async Task InconsistentTokenCountsBecomeADeclaredGapInsteadOfAThrownRequest()
     {
@@ -259,26 +198,6 @@ public sealed class UsageCostMiddlewareTests
         Assert.Equal(UsageCostStatus.UsageMissing, Assert.Single(sink.Records).Status);
     }
 
-    // ---------------------------------------------------------------------------------
-    // Uma linha por volta ao modelo — inclusive no streaming
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>
-    /// Duas <b>chamadas</b> a <c>GetResponseAsync</c> publicam <b>duas</b> linhas: uma por
-    /// ida ao modelo, cada uma com o seu proprio numero.
-    /// </summary>
-    /// <remarks>
-    /// O que este teste prova, e so isto: <b>uma linha por chamada</b>, sem acumulo de
-    /// estado entre chamadas. Ele NAO prova nada sobre a posicao do middleware no pipeline
-    /// — sao duas chamadas separadas, nao uma chamada com volta de tool, e aqui o
-    /// middleware e montado sozinho, sem <c>FunctionInvokingChatClient</c> nenhum. A
-    /// posicao real e o oposto do que uma leitura apressada deste teste sugeriria: o
-    /// middleware fica <b>ACIMA</b> da invocacao de funcoes, e quem prova isso e
-    /// <c>AgentFactoryTests.ThePipelineOrderIsUsageCostAboveFunctionInvocationAndTelemetryBelowIt</c>
-    /// (com <c>...SeesTheUsageOfEveryToolRoundSummedOnce</c> mostrando o uso ja somado das
-    /// duas voltas). Acima do FICC, uma conversa com tool call e <b>uma</b> chamada com o
-    /// uso ja totalizado — nao duas.
-    /// </remarks>
     [Fact]
     public async Task EveryTripToTheModelPublishesItsOwnLine()
     {
@@ -301,10 +220,6 @@ public sealed class UsageCostMiddlewareTests
         Assert.Equal(0.0035m, sink.Records[1].CostUsd);   // (2000*1.25 + 100*10) / 1M
     }
 
-    /// <summary>
-    /// No streaming o uso chega como <c>UsageContent</c> avulso. A linha sai <b>uma</b> vez,
-    /// ao fim da enumeracao, com o mesmo numero do caminho nao-streaming.
-    /// </summary>
     [Fact]
     public async Task StreamingPublishesOneLineAtTheEndWithTheSameNumber()
     {
@@ -325,11 +240,6 @@ public sealed class UsageCostMiddlewareTests
         Assert.Equal(0.0028m, Assert.Single(sink.Records).CostUsd);
     }
 
-    // ---------------------------------------------------------------------------------
-    // Higiene de construcao
-    // ---------------------------------------------------------------------------------
-
-    /// <summary>Alias ou sink nulos sao defeito de composicao e falham na construcao.</summary>
     [Fact]
     public void TheMiddlewareRefusesToBeBuiltWithoutAnAliasOrASink()
     {
@@ -342,11 +252,6 @@ public sealed class UsageCostMiddlewareTests
             () => new UsageCostMiddleware(inner, PricedAlias(), null!));
     }
 
-    /// <summary>
-    /// O instante do record vem do <see cref="TimeProvider"/> injetado, nao do relogio do
-    /// processo — sem isso o campo <c>At</c> seria intestavel (standard
-    /// <c>backend-dotnet-testing</c>).
-    /// </summary>
     [Fact]
     public async Task TheTimestampComesFromTheInjectedClock()
     {

package/framework/templates/feature/decisions.md

@@ -1,122 +1,124 @@
-# Architecture Decision Records - {{titleCase FEATURE_NAME}}
-
-## ADR-001: {Decision Title}
-
-**Date:** {{DATE}}
-**Status:** Proposed | Accepted | Deprecated | Superseded
-**Deciders:** MORPH Agents, Developer
-
-### Context
-
-{Describe the context and problem that led to this decision}
-
-### Decision
-
-{Describe the decision made}
-
-### Consequences
-
-**Pros:**
-- {Positive consequence 1}
-- {Positive consequence 2}
-
-**Cons:**
-- {Negative consequence 1}
-
-**Risks:**
-- {Identified risk}
-
-### Alternatives Considered
-
-#### Option A: {Name}
-- Pros: {advantages}
-- Cons: {disadvantages}
-- **Rejected because:** {reason}
-
-#### Option B: {Name}
-- Pros: {advantages}
-- Cons: {disadvantages}
-- **Rejected because:** {reason}
-
----
-
-{{#if (eq STACK "nextjs-neon")}}
-## ADR-002: Database Access Strategy
-
-**Date:** {{DATE}}
-**Status:** Accepted
-
-### Context
-
-Need to decide how the .NET API accesses Neon PostgreSQL.
-
-### Decision
-
-Use Dapper with Npgsql for direct SQL queries. No EF Core.
-
-### Consequences
-
-**Pros:**
-- Full control over SQL queries
-- Better performance (no ORM overhead)
-- Direct access to PostgreSQL features (jsonb, pgvector, functions)
-- RLS policies apply naturally through connection
-
-**Cons:**
-- No automatic migrations (use Neon CLI / dotnet ef instead)
-- Manual SQL query writing
-- No change tracking
-
----
-
-## ADR-003: Auth Strategy
-
-**Date:** {{DATE}}
-**Status:** Accepted
-
-### Context
-
-Need authentication for both Next.js frontend and .NET API.
-
-### Decision
-
-Use Neon Auth (Better Auth) for authentication. Auth data lives in the Neon database. JWT validated by .NET API middleware.
-
-### Consequences
-
-**Pros:**
-- Auth data in same database — no external provider, no sync delays
-- RLS policies work with Neon Auth JWT via auth.user_id() / pg_session_jwt
-- Built-in social login, email/password via @neondatabase/auth SDK
-- Branch isolation — each Neon branch gets isolated auth data
-- No webhooks needed — query neon_auth schema directly
-
-**Cons:**
-- Neon Auth is currently in Beta
-- JWT must be forwarded to .NET API for backend auth
-{{/if}}
-
----
-
-## Template for New ADRs
-
-```markdown
-## ADR-XXX: {Title}
-
-**Date:**
-**Status:** Proposed | Accepted | Deprecated | Superseded
-
-### Context
-{Why is this decision needed?}
-
-### Decision
-{What was decided?}
-
-### Consequences
-**Pros:** {list}
-**Cons:** {list}
-```
-
----
-
-*Generated by MORPH Framework*
+# Architecture Decision Records - {{titleCase FEATURE_NAME}}
+
+## ADR-001: {Decision Title}
+
+**Date:** {{DATE}}
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Deciders:** MORPH Agents, Developer
+**Alcance:** feature
+
+### Context
+
+{Describe the context and problem that led to this decision}
+
+### Decision
+
+{Describe the decision made}
+
+### Consequences
+
+**Pros:**
+- {Positive consequence 1}
+- {Positive consequence 2}
+
+**Cons:**
+- {Negative consequence 1}
+
+**Risks:**
+- {Identified risk}
+
+### Alternatives Considered
+
+#### Option A: {Name}
+- Pros: {advantages}
+- Cons: {disadvantages}
+- **Rejected because:** {reason}
+
+#### Option B: {Name}
+- Pros: {advantages}
+- Cons: {disadvantages}
+- **Rejected because:** {reason}
+
+---
+
+{{#if (eq STACK "nextjs-neon")}}
+## ADR-002: Database Access Strategy
+
+**Date:** {{DATE}}
+**Status:** Accepted
+
+### Context
+
+Need to decide how the .NET API accesses Neon PostgreSQL.
+
+### Decision
+
+Use Dapper with Npgsql for direct SQL queries. No EF Core.
+
+### Consequences
+
+**Pros:**
+- Full control over SQL queries
+- Better performance (no ORM overhead)
+- Direct access to PostgreSQL features (jsonb, pgvector, functions)
+- RLS policies apply naturally through connection
+
+**Cons:**
+- No automatic migrations (use Neon CLI / dotnet ef instead)
+- Manual SQL query writing
+- No change tracking
+
+---
+
+## ADR-003: Auth Strategy
+
+**Date:** {{DATE}}
+**Status:** Accepted
+
+### Context
+
+Need authentication for both Next.js frontend and .NET API.
+
+### Decision
+
+Use Neon Auth (Better Auth) for authentication. Auth data lives in the Neon database. JWT validated by .NET API middleware.
+
+### Consequences
+
+**Pros:**
+- Auth data in same database — no external provider, no sync delays
+- RLS policies work with Neon Auth JWT via auth.user_id() / pg_session_jwt
+- Built-in social login, email/password via @neondatabase/auth SDK
+- Branch isolation — each Neon branch gets isolated auth data
+- No webhooks needed — query neon_auth schema directly
+
+**Cons:**
+- Neon Auth is currently in Beta
+- JWT must be forwarded to .NET API for backend auth
+{{/if}}
+
+---
+
+## Template for New ADRs
+
+```markdown
+## ADR-XXX: {Title}
+
+**Date:**
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Alcance:** feature | projeto — `projeto` when the rule holds beyond this feature: `morph-spec finish` copies it to `.morph/specs/adrs/`, the folder brainstorming and plan read instead of archived decisions.md
+
+### Context
+{Why is this decision needed?}
+
+### Decision
+{What was decided?}
+
+### Consequences
+**Pros:** {list}
+**Cons:** {list}
+```
+
+---
+
+*Generated by MORPH Framework*

package/framework/templates/frontend/nextjs/Dockerfile.nextjs.hbs

@@ -1,43 +1,39 @@
-# Multi-stage Next.js production build for Coolify
-# Stage 1: Dependencies
-FROM node:20-alpine AS deps
-RUN apk add --no-cache libc6-compat
-WORKDIR /app
-
-COPY package.json package-lock.json* ./
-RUN npm ci --only=production && npm cache clean --force
-
-# Stage 2: Build
-FROM node:20-alpine AS builder
-WORKDIR /app
-
-COPY --from=deps /app/node_modules ./node_modules
-COPY . .
-
-# Build args for NEXT_PUBLIC_ variables (must be available at build time)
-ARG NEXT_PUBLIC_APP_URL
-ENV NEXT_PUBLIC_APP_URL=$NEXT_PUBLIC_APP_URL
-
-RUN npm run build
-
-# Stage 3: Production runner
-FROM node:20-alpine AS runner
-WORKDIR /app
-
-ENV NODE_ENV=production
-ENV NEXT_TELEMETRY_DISABLED=1
-
-RUN addgroup --system --gid 1001 nodejs
-RUN adduser --system --uid 1001 nextjs
-
-COPY --from=builder /app/public ./public
-COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
-COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
-
-USER nextjs
-
-EXPOSE 3000
-ENV PORT=3000
-ENV HOSTNAME="0.0.0.0"
-
-CMD ["node", "server.js"]
+FROM node:20-alpine AS deps
+RUN apk add --no-cache libc6-compat
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+RUN npm ci --only=production && npm cache clean --force
+
+FROM node:20-alpine AS builder
+WORKDIR /app
+
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+
+# NEXT_PUBLIC_ vars are inlined by next build, so they must exist at build time
+ARG NEXT_PUBLIC_APP_URL
+ENV NEXT_PUBLIC_APP_URL=$NEXT_PUBLIC_APP_URL
+
+RUN npm run build
+
+FROM node:20-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+RUN addgroup --system --gid 1001 nodejs
+RUN adduser --system --uid 1001 nextjs
+
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+CMD ["node", "server.js"]

package/framework/templates/frontend/nextjs/env.mjs.hbs

@@ -1,32 +1,29 @@
-// env.mjs — Zod-validated environment variables
-// Crashes at startup if required vars are missing — no silent undefined
-import { z } from 'zod';
-
-const serverSchema = z.object({
-  API_URL: z.string().url('API_URL must be a valid URL'),
-  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
-});
-
-const clientSchema = z.object({
-  NEXT_PUBLIC_APP_URL: z.string().url().optional(),
-});
-
-// Validate server-side env (only available on server)
-const serverEnv = serverSchema.safeParse(process.env);
-if (!serverEnv.success) {
-  console.error('❌ Invalid server environment variables:');
-  console.error(serverEnv.error.flatten().fieldErrors);
-  throw new Error('Invalid environment variables');
-}
-
-// Validate client-side env
-const clientEnv = clientSchema.safeParse({
-  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
-});
-if (!clientEnv.success) {
-  console.error('❌ Invalid client environment variables:');
-  console.error(clientEnv.error.flatten().fieldErrors);
-  throw new Error('Invalid client environment variables');
-}
-
-export const env = { ...serverEnv.data, ...clientEnv.data };
+import { z } from 'zod';
+
+const serverSchema = z.object({
+  API_URL: z.string().url('API_URL must be a valid URL'),
+  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+});
+
+const clientSchema = z.object({
+  NEXT_PUBLIC_APP_URL: z.string().url().optional(),
+});
+
+const serverEnv = serverSchema.safeParse(process.env);
+if (!serverEnv.success) {
+  console.error('❌ Invalid server environment variables:');
+  console.error(serverEnv.error.flatten().fieldErrors);
+  throw new Error('Invalid environment variables');
+}
+
+// Listed one by one: Next.js only inlines NEXT_PUBLIC_ vars read by their literal name.
+const clientEnv = clientSchema.safeParse({
+  NEXT_PUBLIC_APP_URL: process.env.NEXT_PUBLIC_APP_URL,
+});
+if (!clientEnv.success) {
+  console.error('❌ Invalid client environment variables:');
+  console.error(clientEnv.error.flatten().fieldErrors);
+  throw new Error('Invalid client environment variables');
+}
+
+export const env = { ...serverEnv.data, ...clientEnv.data };

package/framework/templates/frontend/nextjs/page.tsx.hbs

@@ -1,22 +1,21 @@
-// app/(dashboard)/{{kebabCase featureName}}/page.tsx
-// Server Component — fetches initial data, renders feature component
-import { {{pascalCase featureName}}List } from '@/features/{{kebabCase featureName}}';
-
-async function get{{pascalCase featureName}}List() {
-  const res = await fetch(`${process.env.API_URL}/api/{{kebabCase featureName}}`, {
-    next: { revalidate: 30 },
-    headers: { 'Content-Type': 'application/json' },
-  });
-  if (!res.ok) throw new Error('Failed to fetch {{featureName}}');
-  return res.json();
-}
-
-export default async function {{pascalCase featureName}}Page() {
-  const data = await get{{pascalCase featureName}}List();
-  return (
-    <div className="container py-6">
-      <h1 className="text-2xl font-bold mb-6">{{pascalCase featureName}}</h1>
-      <{{pascalCase featureName}}List initialData={data} />
-    </div>
-  );
-}
+// app/(dashboard)/{{kebabCase featureName}}/page.tsx
+import { {{pascalCase featureName}}List } from '@/features/{{kebabCase featureName}}';
+
+async function get{{pascalCase featureName}}List() {
+  const res = await fetch(`${process.env.API_URL}/api/{{kebabCase featureName}}`, {
+    next: { revalidate: 30 },
+    headers: { 'Content-Type': 'application/json' },
+  });
+  if (!res.ok) throw new Error('Failed to fetch {{featureName}}');
+  return res.json();
+}
+
+export default async function {{pascalCase featureName}}Page() {
+  const data = await get{{pascalCase featureName}}List();
+  return (
+    <div className="container py-6">
+      <h1 className="text-2xl font-bold mb-6">{{pascalCase featureName}}</h1>
+      <{{pascalCase featureName}}List initialData={data} />
+    </div>
+  );
+}