@supacloud/cli 0.72.0 → 0.73.0

package/dist/index.js

@@ -207715,7 +207715,7 @@ var ACTION_POLICY = {
     read: ["status", "logs"],
     write: ["upload", "configure", "deploy", "rollback", "reconcile", "retire"]
   },
-  db: { local: ["lint", "explain"], read: ["module_check"] },
+  db: { local: ["context", "lint", "explain"], read: ["module_check"] },
   dev: { read: ["status"], write: ["sync", "watch", "migrate"] }
 };
 function declaredMode(moduleName, action) {
@@ -221498,6 +221498,17 @@ var init_validate = __esm2(() => {
     "route-contract-required": { code: "SC3021", docsUrl: "https://supacloud.dev/errors/SC3021" },
     "route-contract-unverified": { code: "SC3022", docsUrl: "https://supacloud.dev/errors/SC3022" },
     "route-contract-evidence-required": { code: "SC3023", docsUrl: "https://supacloud.dev/errors/SC3023" },
+    "invalid-effect-contract": { code: "SC3030", docsUrl: "https://supacloud.dev/errors/SC3030" },
+    "invalid-effect-retry": { code: "SC3031", docsUrl: "https://supacloud.dev/errors/SC3031" },
+    "invalid-effect-timeout": { code: "SC3032", docsUrl: "https://supacloud.dev/errors/SC3032" },
+    "invalid-effect-dependencies": { code: "SC3033", docsUrl: "https://supacloud.dev/errors/SC3033" },
+    "invalid-effect-errors": { code: "SC3034", docsUrl: "https://supacloud.dev/errors/SC3034" },
+    "effect-return-type": { code: "SC3035", docsUrl: "https://supacloud.dev/errors/SC3035" },
+    "effect-contract-required": { code: "SC3036", docsUrl: "https://supacloud.dev/errors/SC3036" },
+    "effect-error-mapping-required": { code: "SC3037", docsUrl: "https://supacloud.dev/errors/SC3037" },
+    "effect-dependencies-required": { code: "SC3038", docsUrl: "https://supacloud.dev/errors/SC3038" },
+    "effect-command-retry-forbidden": { code: "SC3039", docsUrl: "https://supacloud.dev/errors/SC3039" },
+    "effect-dependency-type": { code: "SC3040", docsUrl: "https://supacloud.dev/errors/SC3040" },
     "invalid-route-response-map": { code: "SC3024", docsUrl: "https://supacloud.dev/errors/SC3024" },
     "invalid-route-response-selector": { code: "SC3025", docsUrl: "https://supacloud.dev/errors/SC3025" },
     "conflicting-route-response-schema": { code: "SC3026", docsUrl: "https://supacloud.dev/errors/SC3026" },
@@ -222026,6 +222037,9 @@ class ModuleGenerator {
           });
           fields.push(`responses: { ${responseFields.join(", ")} }`);
         }
+        if (route.effect !== undefined) {
+          fields.push(`effect: ${JSON.stringify(route.effect)}`);
+        }
         if (route.command)
           fields.push(`command: ${JSON.stringify(route.command)}`);
         if (route.guards && route.guards.length > 0) {
@@ -223838,6 +223852,14 @@ var INTERFACES = `export interface CompiledRoute {
   cookie?: unknown;
   response?: unknown;
   responses?: Record<string | number, unknown>;
+  effect?: {
+    required: true;
+    errors?: Array<{ tag: string; status: number; code: string; message?: string }>;
+    dependencies?: string[];
+    retry?: "none" | "explicit";
+    maxAttempts?: number;
+    timeoutMs?: number;
+  };
   /** Compile-time ownership and transport classification for the route boundary. */
   contract?: {
     body?: "framework" | "domain";
@@ -246265,6 +246287,188 @@ function parseController(input, ctx) {
               Object.assign(route.contract, { [field]: value });
           }
         }
+        const effectExpr = getProp(optionsObject, "effect");
+        if (effectExpr) {
+          const effectObject = resolveStaticObjectLiteral(effectExpr, ctx);
+          if (!effectObject) {
+            ctx.diagnostics.push({
+              severity: "error",
+              code: "invalid-effect-contract",
+              errorCode: "SC3030",
+              docsUrl: "https://supacloud.dev/errors/SC3030",
+              file,
+              line: lineOf2(effectExpr),
+              message: `Route ${route.handler} effect must be a statically resolvable object literal.`,
+              suggestion: "Use effect: { required: true, errors: [...], dependencies: [...] }."
+            });
+          } else {
+            const effect = { required: true };
+            const requiredExpr = getProp(effectObject, "required");
+            if (requiredExpr !== undefined && booleanProp(effectObject, "required") !== true) {
+              ctx.diagnostics.push({
+                severity: "error",
+                code: "invalid-effect-contract",
+                errorCode: "SC3030",
+                docsUrl: "https://supacloud.dev/errors/SC3030",
+                file,
+                line: lineOf2(requiredExpr),
+                message: `Route ${route.handler} effect.required must be the literal true.`
+              });
+            }
+            const retry = stringLiteralProp(effectObject, "retry");
+            if (retry !== undefined) {
+              if (retry !== "none" && retry !== "explicit") {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-retry",
+                  errorCode: "SC3031",
+                  docsUrl: "https://supacloud.dev/errors/SC3031",
+                  file,
+                  line: lineOf2(getProp(effectObject, "retry")),
+                  message: `Route ${route.handler} effect.retry must be "none" or "explicit".`
+                });
+              } else {
+                effect.retry = retry;
+              }
+            }
+            const maxAttemptsExpr = getProp(effectObject, "maxAttempts");
+            if (maxAttemptsExpr !== undefined) {
+              const maxAttempts = numberLiteralProp(effectObject, "maxAttempts");
+              if (maxAttempts === undefined || maxAttempts < 1 || !Number.isInteger(maxAttempts)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-retry",
+                  errorCode: "SC3031",
+                  docsUrl: "https://supacloud.dev/errors/SC3031",
+                  file,
+                  line: lineOf2(maxAttemptsExpr),
+                  message: `Route ${route.handler} effect.maxAttempts must be a positive integer.`
+                });
+              } else {
+                effect.maxAttempts = maxAttempts;
+              }
+            }
+            if (effect.retry === "explicit" && effect.maxAttempts === undefined) {
+              ctx.diagnostics.push({
+                severity: "error",
+                code: "invalid-effect-retry",
+                errorCode: "SC3031",
+                docsUrl: "https://supacloud.dev/errors/SC3031",
+                file,
+                line: lineOf2(effectExpr),
+                message: `Route ${route.handler} effect.maxAttempts is required when retry is "explicit".`
+              });
+            }
+            const timeoutExpr = getProp(effectObject, "timeoutMs");
+            if (timeoutExpr !== undefined) {
+              const timeoutMs = numberLiteralProp(effectObject, "timeoutMs");
+              if (timeoutMs === undefined || timeoutMs <= 0 || !Number.isInteger(timeoutMs)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-timeout",
+                  errorCode: "SC3032",
+                  docsUrl: "https://supacloud.dev/errors/SC3032",
+                  file,
+                  line: lineOf2(timeoutExpr),
+                  message: `Route ${route.handler} effect.timeoutMs must be a positive integer.`
+                });
+              } else {
+                effect.timeoutMs = timeoutMs;
+              }
+            }
+            const dependenciesExpr = getProp(effectObject, "dependencies");
+            if (dependenciesExpr !== undefined) {
+              if (!ts7.isArrayLiteralExpression(dependenciesExpr) || dependenciesExpr.elements.some((element) => !ts7.isStringLiteral(element) || element.text.trim().length === 0)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-dependencies",
+                  errorCode: "SC3033",
+                  docsUrl: "https://supacloud.dev/errors/SC3033",
+                  file,
+                  line: lineOf2(dependenciesExpr),
+                  message: `Route ${route.handler} effect.dependencies must be an explicit string array.`
+                });
+              } else {
+                effect.dependencies = dependenciesExpr.elements.map((element) => element.text);
+              }
+            }
+            const errorsExpr = getProp(effectObject, "errors");
+            if (errorsExpr !== undefined) {
+              if (!ts7.isArrayLiteralExpression(errorsExpr)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "invalid-effect-errors",
+                  errorCode: "SC3034",
+                  docsUrl: "https://supacloud.dev/errors/SC3034",
+                  file,
+                  line: lineOf2(errorsExpr),
+                  message: `Route ${route.handler} effect.errors must be an explicit object array.`
+                });
+              } else {
+                const errors = [];
+                for (const errorExpr of errorsExpr.elements) {
+                  if (!ts7.isObjectLiteralExpression(errorExpr)) {
+                    ctx.diagnostics.push({
+                      severity: "error",
+                      code: "invalid-effect-errors",
+                      errorCode: "SC3034",
+                      docsUrl: "https://supacloud.dev/errors/SC3034",
+                      file,
+                      line: lineOf2(errorExpr),
+                      message: `Route ${route.handler} effect.errors entries must be object literals.`
+                    });
+                    continue;
+                  }
+                  const tag = stringLiteralProp(errorExpr, "tag");
+                  const code = stringLiteralProp(errorExpr, "code");
+                  const status = numberLiteralProp(errorExpr, "status");
+                  const message = stringLiteralProp(errorExpr, "message");
+                  if (!tag || !code || status === undefined || !Number.isInteger(status) || status < 400 || status > 599) {
+                    ctx.diagnostics.push({
+                      severity: "error",
+                      code: "invalid-effect-errors",
+                      errorCode: "SC3034",
+                      docsUrl: "https://supacloud.dev/errors/SC3034",
+                      file,
+                      line: lineOf2(errorExpr),
+                      message: `Route ${route.handler} effect.errors entries require tag, code and an HTTP status from 400 to 599.`
+                    });
+                    continue;
+                  }
+                  errors.push({ tag, code, status, ...message === undefined ? {} : { message } });
+                }
+                effect.errors = errors;
+              }
+            }
+            route.effect = effect;
+            if (!resultType || !/\bEffect(?:\.Effect)?(?:<|\s)/.test(resultType)) {
+              ctx.diagnostics.push({
+                severity: "error",
+                code: "effect-return-type",
+                errorCode: "SC3035",
+                docsUrl: "https://supacloud.dev/errors/SC3035",
+                file,
+                line: lineOf2(method),
+                message: `Route ${route.handler} declares an Effect contract but returns ${resultType ?? "an unresolved type"}.`,
+                suggestion: "Return Effect.Effect<Success, Failure, Requirements> from the handler."
+              });
+            }
+            for (const dependency of effect.dependencies ?? []) {
+              if (!resultType?.includes(dependency)) {
+                ctx.diagnostics.push({
+                  severity: "error",
+                  code: "effect-dependency-type",
+                  errorCode: "SC3040",
+                  docsUrl: "https://supacloud.dev/errors/SC3040",
+                  file,
+                  line: lineOf2(method),
+                  message: `Route ${route.handler} declares Effect dependency "${dependency}", but it is absent from the return type environment ${resultType ?? "unknown"}.`,
+                  suggestion: "Keep effect.dependencies aligned with the third Effect type parameter."
+                });
+              }
+            }
+          }
+        }
         for (const field of ["body", "params", "query", "headers", "cookie", "response"]) {
           const schemaExpr = getProp(optionsObject, field);
           if (schemaExpr && ts7.isIdentifier(schemaExpr)) {
@@ -246848,6 +247052,13 @@ function stringLiteralProp(obj, name) {
   const expr = getProp(obj, name);
   return expr && ts7.isStringLiteral(expr) ? expr.text : undefined;
 }
+function numberLiteralProp(obj, name) {
+  const expr = getProp(obj, name);
+  if (!expr || !ts7.isNumericLiteral(expr))
+    return;
+  const value = Number(expr.text);
+  return Number.isFinite(value) ? value : undefined;
+}
 function arrayProp(obj, name) {
   const expr = getProp(obj, name);
   return expr && ts7.isArrayLiteralExpression(expr) ? [...expr.elements] : [];
@@ -247489,6 +247700,55 @@ function validateClientSchemaBoundaries(graph, options) {
   }
   return diagnostics;
 }
+init_validate();
+function diagnostic(code, message, file, suggestion) {
+  const metadata = COMPILER_DIAGNOSTIC_CODES[code];
+  return {
+    severity: "error",
+    code,
+    message,
+    ...file === undefined ? {} : { file },
+    ...suggestion === undefined ? {} : { suggestion },
+    ...metadata ? { errorCode: metadata.code, docsUrl: metadata.docsUrl } : {}
+  };
+}
+function routeLabel(route, controllerPath) {
+  return `${route.method} ${controllerPath}${route.path}`;
+}
+function validateEffectPolicies(graph, options = {}) {
+  const diagnostics = [];
+  for (const module of graph.modules) {
+    const commands = new Map(module.commands.map((command) => [command.className, command]));
+    for (const controller of module.controllers) {
+      for (const route of controller.routes) {
+        const label = routeLabel(route, controller.path);
+        if (options.requireRouteEffects && route.effect === undefined) {
+          diagnostics.push(diagnostic("effect-contract-required", `Route ${label} must declare an Effect contract.`, controller.file, 'Add effect: { dependencies: [...], errors: [...], retry: "none" } to the route options.'));
+          continue;
+        }
+        const effect = route.effect;
+        if (effect === undefined)
+          continue;
+        if (options.requireErrorMappings && effect.errors === undefined) {
+          diagnostics.push(diagnostic("effect-error-mapping-required", `Route ${label} declares an Effect contract without public error mappings.`, controller.file, "Map every expected domain failure to a stable HTTP status and public code."));
+        }
+        if (options.requireDependencies && effect.dependencies === undefined) {
+          diagnostics.push(diagnostic("effect-dependencies-required", `Route ${label} declares an Effect contract without dependencies.`, controller.file, "Declare the logical services required by the Effect environment."));
+        }
+        if (effect.retry === "explicit" && effect.maxAttempts === undefined) {
+          diagnostics.push(diagnostic("invalid-effect-retry", `Route ${label} enables explicit Effect retry without maxAttempts.`, controller.file, "Declare a positive maxAttempts value including the initial attempt."));
+        }
+        if (route.command && effect.retry === "explicit") {
+          const command = commands.get(route.command);
+          if (command && command.idempotency !== "required") {
+            diagnostics.push(diagnostic("effect-command-retry-forbidden", `Route ${label} enables explicit Effect retry for non-idempotent command "${command.name}".`, controller.file, 'Set command idempotency to "required" or use effect.retry: "none".'));
+          }
+        }
+      }
+    }
+  }
+  return diagnostics;
+}
 function withDefaultGovernance(options) {
   return options.commandCapabilities === undefined ? { ...options, commandCapabilities: {
     requirePersistentAdapters: true,
@@ -247507,7 +247767,8 @@ async function compileProject(options) {
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, options),
-    ...validateClientSchemaBoundaries(graph, options)
+    ...validateClientSchemaBoundaries(graph, options),
+    ...validateEffectPolicies(graph, options.effect)
   ];
   if (diagnostics.some((item) => item.code === "runtime-injection-disallowed")) {
     return { diagnostics, graph, written: [] };
@@ -247571,7 +247832,8 @@ async function checkProject(options) {
   const diagnostics = [
     ...graph.diagnostics ?? [],
     ...validateGraph(graph, options),
-    ...validateClientSchemaBoundaries(graph, options)
+    ...validateClientSchemaBoundaries(graph, options),
+    ...validateEffectPolicies(graph, options.effect)
   ];
   if (diagnostics.some((item) => item.code === "runtime-injection-disallowed")) {
     return { diagnostics, graph, upToDate: false, mismatches: ["Runtime DI must be migrated to constructor injection."] };
@@ -247653,7 +247915,7 @@ init_delivery_schema();
 init_validate();
 var compare2 = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 var sorted = (values) => [...new Set(values)].sort(compare2);
-function diagnostic(error) {
+function diagnostic2(error) {
   return {
     severity: error.severity,
     code: error.code,
@@ -247678,8 +247940,8 @@ function createDeliveryPlan(graph, input) {
     }] };
   }
   const diagnostics = [
-    ...(graph.diagnostics ?? []).map(diagnostic),
-    ...validateGraph(graph, { strict: true }).map(diagnostic)
+    ...(graph.diagnostics ?? []).map(diagnostic2),
+    ...validateGraph(graph, { strict: true }).map(diagnostic2)
   ];
   const fail = (code, message, suggestion) => {
     diagnostics.push({ severity: "error", code, message, suggestion });
@@ -249134,7 +249396,12 @@ var DEFAULT_SUPACLOUD_CONFIG = {
     idempotency: true,
     transaction: true
   },
-  moduleBoundaryPreset: "modular-monolith"
+  moduleBoundaryPreset: "modular-monolith",
+  effect: {
+    requireRouteEffects: true,
+    requireErrorMappings: true,
+    requireDependencies: true
+  }
 };
 function defineSupacloudConfig(config = {}) {
   if (config.delivery !== undefined)
@@ -249146,7 +249413,8 @@ function defineSupacloudConfig(config = {}) {
     ...DEFAULT_SUPACLOUD_CONFIG,
     ...config,
     include: config.include ?? [...DEFAULT_SUPACLOUD_CONFIG.include],
-    graphql: config.graphql ?? DEFAULT_SUPACLOUD_CONFIG.graphql
+    graphql: config.graphql ?? DEFAULT_SUPACLOUD_CONFIG.graphql,
+    effect: config.effect === undefined ? { ...DEFAULT_SUPACLOUD_CONFIG.effect } : { ...DEFAULT_SUPACLOUD_CONFIG.effect, ...config.effect }
   };
 }
 function validateGovernanceConfig(config) {
@@ -249203,6 +249471,16 @@ function validateGovernanceConfig(config) {
     if (config[key] !== undefined && typeof config[key] !== "boolean")
       throw new Error(`${key} must be a boolean.`);
   }
+  if (config.effect !== undefined) {
+    if (!isRecord(config.effect) || Object.keys(config.effect).some((key) => !["requireRouteEffects", "requireErrorMappings", "requireDependencies"].includes(key))) {
+      throw new Error("effect accepts requireRouteEffects, requireErrorMappings and requireDependencies.");
+    }
+    for (const key of ["requireRouteEffects", "requireErrorMappings", "requireDependencies"]) {
+      if (config.effect[key] !== undefined && typeof config.effect[key] !== "boolean") {
+        throw new Error(`effect.${key} must be boolean.`);
+      }
+    }
+  }
 }
 function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
   const resolved = defineSupacloudConfig(config);
@@ -249223,6 +249501,7 @@ function resolveSupacloudConfig(config = {}, cwd = process.cwd()) {
     ...resolved.allowRouteCommandBindings === undefined ? {} : { allowRouteCommandBindings: resolved.allowRouteCommandBindings },
     ...resolved.disallowControllerDirectDb === undefined ? {} : { disallowControllerDirectDb: resolved.disallowControllerDirectDb },
     ...resolved.detectOrphanModules === undefined ? {} : { detectOrphanModules: resolved.detectOrphanModules },
+    effect: resolved.effect === undefined ? { ...DEFAULT_SUPACLOUD_CONFIG.effect } : { ...DEFAULT_SUPACLOUD_CONFIG.effect, ...resolved.effect },
     treeShakeUnusedProviders: resolved.treeShakeUnusedProviders ?? DEFAULT_SUPACLOUD_CONFIG.treeShakeUnusedProviders,
     graphql: resolved.graphql ? {
       ...resolved.graphql,
@@ -249371,16 +249650,16 @@ var starter_metadata_default = {
   generatedBy: "supacloud/starter-metadata-v1",
   packages: {
     compiler: {
-      version: "0.40.1"
+      version: "0.41.0"
     },
     app: {
-      version: "0.23.0",
+      version: "0.24.0",
       dependencies: {
         rxjs: "7.8.2"
       }
     },
     elysia: {
-      version: "0.27.1"
+      version: "0.28.0"
     },
     commands: {
       version: "0.9.1"
@@ -249734,6 +250013,7 @@ function baseFiles(name, sdkDependencies) {
       dependencies: {
         "@supacloud/app": `^${appMetadata.version}`,
         "@supacloud/elysia": `^${elysiaMetadata.version}`,
+        effect: "3.22.1",
         elysia: "2.0.0-beta.21",
         ...sdkDependencies ?? { rxjs: appMetadata.dependencies.rxjs }
       },
@@ -249778,6 +250058,11 @@ export default defineSupacloudConfig({
   outDir: "generated",
   strict: true,
   moduleBoundaryPreset: "modular-monolith",
+  effect: {
+    requireRouteEffects: true,
+    requireErrorMappings: true,
+    requireDependencies: true,
+  },
   typeSafety: { scanProductionSource: true, noAnyInGenerated: true },
   disallowControllerDirectDb: true,
   detectOrphanModules: true,
@@ -249806,20 +250091,34 @@ export const CreateOrderBody = t.Object({ name: t.String({ minLength: 1 }) });
 export const OrderResult = t.Object({ id: t.String(), name: t.String() });
 export const HealthResult = t.Object({ ok: t.Boolean() });
 `,
-    "src/orders/orders.ts": `import { Body, Controller, Get, Param, Post, defineFeatureSlice } from "@supacloud/app";
+    "src/orders/orders.ts": `import * as Effect from "effect/Effect";
+import { Body, Controller, Get, Param, Post, defineFeatureSlice } from "@supacloud/app";
 import { status } from "elysia";
 import { OrderParams, CreateOrderBody, OrderResult, HealthResult } from "./contracts";
 @Controller("/orders")
 export class OrdersController {
-  @Get("/health", { responses: { 200: HealthResult } })
-  health(): { ok: boolean } { return { ok: true }; }
-
-  @Get("/:id", { params: OrderParams, responses: { 200: OrderResult } })
-  get(@Param("id") id: string): { id: string; name: string } { return { id, name: "demo" }; }
-
-  @Post("/", { body: CreateOrderBody, responses: { 201: OrderResult } })
+  @Get("/health", {
+    responses: { 200: HealthResult },
+    effect: { required: true, dependencies: [], errors: [], retry: "none" },
+  })
+  health(): Effect.Effect<{ ok: boolean }, never, never> { return Effect.succeed({ ok: true }); }
+
+  @Get("/:id", {
+    params: OrderParams,
+    responses: { 200: OrderResult },
+    effect: { required: true, dependencies: [], errors: [], retry: "none" },
+  })
+  get(@Param("id") id: string): Effect.Effect<{ id: string; name: string }, never, never> {
+    return Effect.succeed({ id, name: "demo" });
+  }
+
+  @Post("/", {
+    body: CreateOrderBody,
+    responses: { 201: OrderResult },
+    effect: { required: true, dependencies: [], errors: [], retry: "none" },
+  })
   create(@Body() body: { name: string }) {
-    return status(201, { id: "demo", name: body.name });
+    return Effect.succeed(status(201, { id: "demo", name: body.name }));
   }
 }
 
@@ -249993,22 +250292,27 @@ function minimalTemplate(name, sdkDependencies) {
     "src/features/health/contracts.ts": `import { t } from "elysia";
 export const HealthResult = t.Object({ ok: t.Boolean() });
 `,
-    "src/features/health/health.ts": `import { Controller, Get, Module } from "@supacloud/app/core";
+    "src/features/health/health.ts": `import * as Effect from "effect/Effect";
+import { Controller, Get, Module } from "@supacloud/app/core";
 import { HealthResult } from "./contracts";
 @Controller("/health")
 export class HealthController {
-  @Get("/", { responses: { 200: HealthResult } })
-  health(): { ok: boolean } { return { ok: true }; }
+  @Get("/", {
+    responses: { 200: HealthResult },
+    effect: { required: true, dependencies: [], errors: [], retry: "none" },
+  })
+  health(): Effect.Effect<{ ok: boolean }, never, never> { return Effect.succeed({ ok: true }); }
 }
 
 @Module({ name: "health", tags: ["type:feature"], controllers: [HealthController] })
 export class HealthModule {}
 `,
-    "src/features/health/health.test.ts": `import { expect, test } from "bun:test";
+    "src/features/health/health.test.ts": `import * as Effect from "effect/Effect";
+import { expect, test } from "bun:test";
 import { HealthController } from "./health";
 
-test("health is a public, side-effect-free operation", () => {
-  expect(new HealthController().health()).toEqual({ ok: true });
+test("health is a public, side-effect-free operation", async () => {
+  expect(await Effect.runPromise(new HealthController().health())).toEqual({ ok: true });
 });
 `,
     "src/app.module.ts": `import { Module } from "@supacloud/app/core";
@@ -250533,7 +250837,8 @@ export async function createDeliveryWorker(modules: CompiledModule[], lifecycle:
 `;
 
 // src/shared/tools/app-starter-upload.ts
-var STARTER_UPLOAD_FEATURE = `import { Body, Controller, Inject, Injectable, Param, Post, DB_CLIENT, REQUEST_CONTEXT } from "@supacloud/app";
+var STARTER_UPLOAD_FEATURE = `import * as Effect from "effect/Effect";
+import { Body, Controller, Inject, Injectable, Param, Post, DB_CLIENT, REQUEST_CONTEXT } from "@supacloud/app";
 import { ApplicationError } from "@supacloud/elysia";
 import { UploadBody, UploadLocation, UploadParams, UploadResult } from "./contracts";
 
@@ -250563,13 +250868,47 @@ export class ReviewUploads {
 export class ReviewUploadsController {
   constructor(@Inject(ReviewUploads) private readonly uploads: ReviewUploads) {}
 
-  @Post("/:id/attachment-upload", { params: UploadParams, body: UploadBody, responses: { 200: UploadLocation } })
-  preview(@Param("id") id: string, @Body() body: { artifactId: string; expectedVersion: number }): Promise<ReviewUploadLocation> {
-    return this.uploads.preview({ reviewId: id, artifactId: body.artifactId, expectedVersion: body.expectedVersion });
-  }
-  @Post("/:id/attachment-registration", { params: UploadParams, body: UploadBody, responses: { 200: UploadResult } })
-  register(@Param("id") id: string, @Body() body: { artifactId: string; expectedVersion: number }): Promise<ReviewUploadResult> {
-    return this.uploads.register({ reviewId: id, artifactId: body.artifactId, expectedVersion: body.expectedVersion });
+  @Post("/:id/attachment-upload", {
+    params: UploadParams,
+    body: UploadBody,
+    responses: { 200: UploadLocation },
+    effect: {
+      required: true,
+      dependencies: [],
+      errors: [
+        { tag: "AUTHENTICATION_REQUIRED", status: 401, code: "AUTHENTICATION_REQUIRED" },
+        { tag: "UPLOAD_INPUT_INVALID", status: 400, code: "UPLOAD_INPUT_INVALID" },
+        { tag: "UPLOAD_DENIED", status: 403, code: "UPLOAD_DENIED" },
+        { tag: "UPLOADS_UNAVAILABLE", status: 501, code: "UPLOADS_UNAVAILABLE" },
+      ],
+      retry: "none",
+    },
+  })
+  preview(@Param("id") id: string, @Body() body: { artifactId: string; expectedVersion: number }): Effect.Effect<ReviewUploadLocation, unknown, never> {
+    return Effect.promise(() => this.uploads.preview({ reviewId: id, artifactId: body.artifactId, expectedVersion: body.expectedVersion }));
+  }
+  @Post("/:id/attachment-registration", {
+    params: UploadParams,
+    body: UploadBody,
+    responses: { 200: UploadResult },
+    effect: {
+      required: true,
+      dependencies: [],
+      errors: [
+        { tag: "AUTHENTICATION_REQUIRED", status: 401, code: "AUTHENTICATION_REQUIRED" },
+        { tag: "UPLOAD_INPUT_INVALID", status: 400, code: "UPLOAD_INPUT_INVALID" },
+        { tag: "UPLOAD_DENIED", status: 403, code: "UPLOAD_DENIED" },
+        { tag: "UPLOAD_CONTENT_INVALID", status: 400, code: "UPLOAD_CONTENT_INVALID" },
+        { tag: "COMMAND_IDEMPOTENCY_CONFLICT", status: 409, code: "COMMAND_IDEMPOTENCY_CONFLICT" },
+        { tag: "COMMAND_REJECTED", status: 403, code: "COMMAND_REJECTED" },
+        { tag: "UPLOADS_UNAVAILABLE", status: 501, code: "UPLOADS_UNAVAILABLE" },
+        { tag: "UPLOAD_OUTCOME_UNKNOWN", status: 503, code: "UPLOAD_OUTCOME_UNKNOWN" },
+      ],
+      retry: "none",
+    },
+  })
+  register(@Param("id") id: string, @Body() body: { artifactId: string; expectedVersion: number }): Effect.Effect<ReviewUploadResult, unknown, never> {
+    return Effect.promise(() => this.uploads.register({ reviewId: id, artifactId: body.artifactId, expectedVersion: body.expectedVersion }));
   }
 }
 `;
@@ -250853,6 +251192,10 @@ function rows(value: unknown): Record<string, unknown>[] {
   if (!Array.isArray(value)) throw new TypeError("Invalid database result");
   return value.map(record);
 }
+function isPublicConflict(value: unknown): boolean {
+  return value instanceof ApplicationError && value.status === 409
+    || isRecord(value) && value.expose === true && value.status === 409 && typeof value.code === "string";
+}
 function input(value: unknown): Approval {
   const item = record(value);
   if (typeof item.id !== "string" || !item.id.length || typeof item.expectedVersion !== "number"
@@ -250967,7 +251310,7 @@ export async function createReviewPostgresAdapters(options: ReviewPostgresOption
           execute: tx => scope.run(tx, async () => {
             try { return await next(); }
             catch (error) {
-              if (error instanceof ApplicationError && error.status === 409) {
+              if (isPublicConflict(error)) {
                 throw new CommandError("COMMAND_IDEMPOTENCY_CONFLICT");
               }
               throw error;
@@ -251276,6 +251619,7 @@ function appStarterFiles(name) {
         "drizzle-orm": dbMetadata.peerDependencies["drizzle-orm"],
         "@supacloud/js": `^${sdkMetadata.version}`,
         "@supabase/supabase-js": sdkMetadata.peerDependencies["@supabase/supabase-js"],
+        effect: "3.22.1",
         elysia: "2.0.0-beta.21",
         rxjs: appMetadata2.dependencies.rxjs
       },
@@ -251331,6 +251675,11 @@ export default defineSupacloudConfig({
   outDir: "generated",
   strict: true,
   moduleBoundaryPreset: "modular-monolith",
+  effect: {
+    requireRouteEffects: true,
+    requireErrorMappings: true,
+    requireDependencies: true,
+  },
   typeSafety: { scanProductionSource: true, noAnyInGenerated: true },
   disallowControllerDirectDb: true,
   detectOrphanModules: true,
@@ -251531,7 +251880,8 @@ export function createCompiledModules(): never {
   throw new Error("Run bun run compile before starting the application");
 }
 `,
-    "src/review/review.ts": `import {
+    "src/review/review.ts": `import * as Effect from "effect/Effect";
+import {
   Body, Command, Controller, DB_CLIENT, Get, Inject, Param, Post,
   defineFeatureSlice, defineFeatureSpec, type Aspect,
 } from "@supacloud/app";
@@ -251601,12 +251951,36 @@ export class ApproveReview {
 export class ReviewController {
   constructor(@Inject(ApproveReview) private readonly approveReview: ApproveReview) {}
 
-  @Get("/health", { responses: { 200: HealthResult } })
-  health(): { ok: boolean } { return { ok: true }; }
-
-  @Post("/:id/approve", { command: ApproveReview, params: Params, body: ApproveBody, responses: { 200: ReviewResult } })
-  approve(@Param("id") id: string, @Body() body: { expectedVersion: number }): Promise<Review> {
-    return this.approveReview.execute(id, body.expectedVersion);
+  @Get("/health", {
+    responses: { 200: HealthResult },
+    effect: { required: true, dependencies: [], errors: [], retry: "none" },
+  })
+  health(): Effect.Effect<{ ok: boolean }, never, never> { return Effect.succeed({ ok: true }); }
+
+  @Post("/:id/approve", {
+    command: ApproveReview,
+    params: Params,
+    body: ApproveBody,
+    responses: { 200: ReviewResult },
+    effect: {
+      required: true,
+      dependencies: [],
+      errors: [
+        { tag: "AUTHENTICATION_REQUIRED", status: 401, code: "AUTHENTICATION_REQUIRED" },
+        { tag: "REVIEW_NOT_FOUND", status: 404, code: "REVIEW_NOT_FOUND" },
+        { tag: "REVIEW_PERMISSION_DENIED", status: 403, code: "REVIEW_PERMISSION_DENIED" },
+        { tag: "REVIEW_CONFLICT", status: 409, code: "REVIEW_CONFLICT" },
+        { tag: "FEATURE_TRANSITION_CONFLICT", status: 409, code: "FEATURE_TRANSITION_CONFLICT" },
+        { tag: "COMMAND_IDEMPOTENCY_CONFLICT", status: 409, code: "COMMAND_IDEMPOTENCY_CONFLICT" },
+        { tag: "COMMAND_REJECTED", status: 403, code: "COMMAND_REJECTED" },
+        { tag: "REVIEW_COMMAND_UNSUPPORTED", status: 501, code: "REVIEW_COMMAND_UNSUPPORTED" },
+        { tag: "COMMAND_OUTCOME_UNKNOWN", status: 503, code: "COMMAND_OUTCOME_UNKNOWN" },
+      ],
+      retry: "none",
+    },
+  })
+  approve(@Param("id") id: string, @Body() body: { expectedVersion: number }): Effect.Effect<Review, unknown, never> {
+    return Effect.promise(() => this.approveReview.execute(id, body.expectedVersion));
   }
 }
 
@@ -252145,7 +252519,8 @@ export class ${className}Service {
     }
 }
 `,
-    [`${name}.controller.ts`]: `import { Controller, Get, Inject, Param } from "@supacloud/app";
+    [`${name}.controller.ts`]: `import * as Effect from "effect/Effect";
+import { Controller, Get, Inject, Param } from "@supacloud/app";
 import { ${className}Params, ${className}Response, type ${className}Result } from "./${name}.model";
 import { ${className}Service } from "./${name}.service";
 
@@ -252153,9 +252528,13 @@ import { ${className}Service } from "./${name}.service";
 export class ${className}Controller {
     constructor(@Inject(${className}Service) readonly service: Pick<${className}Service, "find">) {}
 
-    @Get("/:id", { params: ${className}Params, responses: { 200: ${className}Response } })
-    find(@Param("id") id: string): Promise<${className}Result> {
-        return this.service.find(id);
+    @Get("/:id", {
+        params: ${className}Params,
+        responses: { 200: ${className}Response },
+        effect: { required: true, dependencies: [], errors: [], retry: "none" },
+    })
+    find(@Param("id") id: string): Effect.Effect<${className}Result, unknown, never> {
+        return Effect.promise(() => this.service.find(id));
     }
 }
 `,
@@ -252190,19 +252569,20 @@ test("${name} preserves permission denial without a privileged fallback", async
     await expect(service.find("example")).rejects.toBe(denied);
 });
 `,
-    [`${name}.controller.test.ts`]: `import { expect, test } from "bun:test";
+    [`${name}.controller.test.ts`]: `import * as Effect from "effect/Effect";
+import { expect, test } from "bun:test";
 import { ${className}Controller } from "./${name}.controller";
 
 test("${name} controller delegates to the supplied asynchronous read port", async () => {
     // Unit-test double only; the generated runtime service remains fail-closed.
     const controller = new ${className}Controller({ find: async (id) => ({ id }) });
-    expect(await controller.find("example")).toEqual({ id: "example" });
+    expect(await Effect.runPromise(controller.find("example"))).toEqual({ id: "example" });
 });
 
 test("${name} controller preserves an asynchronous read failure", async () => {
     const failure = new Error("read port unavailable");
     const controller = new ${className}Controller({ find: async () => { throw failure; } });
-    await expect(controller.find("example")).rejects.toBe(failure);
+    await expect(Effect.runPromise(controller.find("example"))).rejects.toThrow("read port unavailable");
 });
 `
   };
@@ -253726,6 +254106,91 @@ function formatReconcileReport(report) {
   return lines.join(`
 `);
 }
+function moduleObjects2(module) {
+  return [
+    ...module.tables.map((table) => ({
+      kind: "table",
+      name: table,
+      module: module.name,
+      source: null,
+      tests: []
+    })),
+    ...module.policies.map((policy) => ({
+      kind: "policy",
+      name: policy.name,
+      module: module.name,
+      table: policy.table,
+      source: policy.source,
+      tests: policy.tests ?? []
+    })),
+    ...module.functions.map((fn) => ({
+      kind: "function",
+      name: fn.name,
+      module: module.name,
+      source: fn.source,
+      tests: fn.tests ?? [],
+      security: fn.security,
+      permission: fn.permission,
+      transaction: fn.transaction,
+      audit: fn.audit,
+      idempotency: fn.idempotency
+    })),
+    ...module.triggers.map((trigger) => ({
+      kind: "trigger",
+      name: trigger.name,
+      module: module.name,
+      table: trigger.table,
+      source: trigger.source,
+      tests: []
+    })),
+    ...module.grants.map((grant) => ({
+      kind: "grant",
+      name: `${grant.object}:${grant.privilege}:${grant.role}`,
+      module: module.name,
+      source: grant.source,
+      tests: []
+    }))
+  ];
+}
+function objectMatchesTarget(object, target) {
+  return object.name === target || object.table === target || object.kind === "policy" && `${object.table}.${object.name}` === target || object.kind === "grant" && object.name.startsWith(`${target}:`);
+}
+function buildDatabaseAiContext(modules, root, moduleName, target) {
+  const selected = moduleName ? modules.filter((module) => module.name === moduleName) : [...modules];
+  if (moduleName && selected.length === 0) {
+    throw new Error(`未找到数据库模块: ${moduleName}（可用: ${modules.map((module) => module.name).join(", ") || "none"}）`);
+  }
+  const allObjects = selected.flatMap(moduleObjects2);
+  const objects = target ? allObjects.filter((object) => objectMatchesTarget(object, target)) : allObjects;
+  if (target && objects.length === 0)
+    throw new Error(`未找到数据库对象: ${target}`);
+  return {
+    version: 1,
+    scope: "database-ai-context",
+    root,
+    selectedModules: selected.map((module) => module.name),
+    target: target ?? null,
+    objects,
+    maintenance: {
+      structureSource: "drizzle",
+      behaviorSource: "sql",
+      generatedPaths: ["generated/", "bootstrap/schema.sql", "output/database-audit/"],
+      protectedPaths: ["migrations/", "supabase/migrations/", "generated/"],
+      forwardMigrationPath: "migrations/<timestamp>_<intent>.sql",
+      rules: [
+        "Edit the selected maintained source, not a generated snapshot.",
+        "Keep RPC, RLS, trigger and grant behavior in explicit SQL sources.",
+        "Create a new forward migration; never rewrite an applied migration.",
+        "Run lint, focused behavior tests and catalog reconciliation after edits."
+      ]
+    },
+    verification: [
+      "supacloud-cli db lint --module_file db/modules.ts",
+      "supacloud-cli db explain --target <object>",
+      'supacloud-cli db module_check --module_file db/modules.ts --database_url "$DATABASE_URL"'
+    ]
+  };
+}
 async function runModuleCheck(module, executor, schemas = ["public"]) {
   const catalog = await readCatalog(executor, schemas);
   return reconcileModule(module, catalog);
@@ -253769,6 +254234,10 @@ async function runExplain2(args, root) {
   const text = explainObject(manifest, target);
   return textResult2(text, text.startsWith("未找到对象"));
 }
+async function runContext2(args, root) {
+  const modules = await loadDatabaseModules(root, args.module_file);
+  return textResult2(JSON.stringify(buildDatabaseAiContext(modules, root, args.module, args.target), null, 2));
+}
 var defaultLiteSpawn = async (command, cwd) => {
   const proc = Bun.spawn({ cmd: command, cwd, stdout: "pipe", stderr: "pipe" });
   const [exitCode, stdout, stderr] = await Promise.all([
@@ -253826,12 +254295,12 @@ function registerDbGovernanceTools(server2, options = {}) {
   const environment = options.environment || process.env;
   const fallbackRoot = options.currentWorkingDirectory || process.cwd();
   const liteSpawn = options.liteSpawn || defaultLiteSpawn;
-  server2.tool("db", "Local database governance (@supacloud/db): lint declared modules, explain objects, reconcile against a live catalog or a local SupaCloud Lite project. Actions: lint, explain, module_check", {
-    action: withDescription(stringEnum(["lint", "explain", "module_check"]), "Database governance action"),
-    module: optional(String2(), "[lint] Only lint this manifest module (default: all)"),
+  server2.tool("db", "Local database governance (@supacloud/db): provide bounded AI context, lint declared modules, explain objects, reconcile against a live catalog or a local SupaCloud Lite project. Actions: context, lint, explain, module_check", {
+    action: withDescription(stringEnum(["context", "lint", "explain", "module_check"]), "Database governance action"),
+    module: optional(String2(), "[context/lint] Only select this manifest module (default: all)"),
     root: optional(String2(), "[*] Project root (default: current directory)"),
     module_file: optional(String2(), "[*] File exporting defineDatabaseModule(...) (default: <root>/db/modules.ts)"),
-    target: optional(String2(), "[explain] Policy / function / table name to explain"),
+    target: optional(String2(), "[context/explain] Policy / function / table name to explain"),
     database_url: optional(String2(), "[module_check] Postgres connection URL (default: DATABASE_URL)"),
     schema: optional(String2(), "[module_check] Comma-separated schemas to inspect (default: public)"),
     lite: optional(Boolean2(), "[module_check] Reconcile against a local SupaCloud Lite project (runs supacloud-lite db check)"),
@@ -253839,6 +254308,8 @@ function registerDbGovernanceTools(server2, options = {}) {
   }, async (request) => {
     const root = resolve25(request.root || fallbackRoot);
     switch (request.action) {
+      case "context":
+        return runContext2(request, root);
       case "lint":
         return runLint(request, root);
       case "explain":
@@ -256652,7 +257123,7 @@ function registerRemoteDevTools(server2, options = {}) {
 // package.json
 var package_default = {
   name: "@supacloud/cli",
-  version: "0.72.0",
+  version: "0.73.0",
   description: "Project-scoped CLI for SupaCloud users",
   type: "module",
   main: "./dist/index.js",
@@ -256686,7 +257157,7 @@ var package_default = {
     directory: "packages/cli"
   },
   dependencies: {
-    "@supacloud/compiler": "^0.40.1",
+    "@supacloud/compiler": "^0.41.0",
     "@supacloud/delivery": "0.8.0",
     "@supacloud/db": "^0.14.0",
     fflate: "^0.8.3",
@@ -256699,6 +257170,7 @@ var package_default = {
   devDependencies: {
     "@supacloud/elysia": "^0.24.1",
     "@types/bun": "^1.4.2",
+    effect: "3.22.1",
     elysia: "2.0.0-beta.21",
     typescript: "^7.0.2"
   }
@@ -256981,6 +257453,8 @@ EXAMPLES
   ${preferredCommand} context --format json
   ${preferredCommand} context --target CaseModule --format json
   ${preferredCommand} doctor
+  ${preferredCommand} db context --root . --module_file db/modules.ts --module cases
+  ${preferredCommand} db context --root . --module_file db/modules.ts --target public.case_create
   ${preferredCommand} db lint --root . --module_file db/modules.ts
   ${preferredCommand} db explain --target public.cases --module_file db/modules.ts
   ${preferredCommand} db module_check --module_file db/modules.ts --database_url "postgresql://..."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/cli",
-  "version": "0.72.0",
+  "version": "0.73.0",
   "description": "Project-scoped CLI for SupaCloud users",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,7 +34,7 @@
     "directory": "packages/cli"
   },
   "dependencies": {
-    "@supacloud/compiler": "^0.40.1",
+    "@supacloud/compiler": "^0.41.0",
     "@supacloud/delivery": "0.8.0",
     "@supacloud/db": "^0.14.0",
     "fflate": "^0.8.3",
@@ -47,6 +47,7 @@
   "devDependencies": {
     "@supacloud/elysia": "^0.24.1",
     "@types/bun": "^1.4.2",
+    "effect": "3.22.1",
     "elysia": "2.0.0-beta.21",
     "typescript": "^7.0.2"
   }

package/skills/supacloud-cli/SKILL.md

@@ -31,12 +31,21 @@ Use `supacloud-cli` as the project-level control surface and keep durable change
 
 1. Classify the request using [references/command-map.md](references/command-map.md).
 2. For database work, load [references/database-workflow.md](references/database-workflow.md) and choose either new-change or historical-drift reconciliation.
-3. Prefer the smallest read-only inspection that proves current state.
-4. Create or update version-controlled artifacts before remote writes.
-5. Verify locally, inspect the diff, and run the narrowest relevant tests.
-6. Preview remote changes with `--dry_run`.
-7. Apply only within the user-authorized environment and scope.
-8. Read back migration history and affected resources; report exact evidence and any remaining drift.
+3. For AI-assisted database changes, first request bounded context:
+
+   ```bash
+   supacloud-cli db context --module_file db/modules.ts --module <module>
+   supacloud-cli db context --module_file db/modules.ts --target <object>
+   ```
+
+   Use the returned source/test paths and ownership boundary; do not scan or
+   edit the complete schema dump.
+4. Prefer the smallest read-only inspection that proves current state.
+5. Create or update version-controlled artifacts before remote writes.
+6. Verify locally, inspect the diff, and run the narrowest relevant tests.
+7. Preview remote changes with `--dry_run`.
+8. Apply only within the user-authorized environment and scope.
+9. Read back migration history and affected resources; report exact evidence and any remaining drift.
 
 ## Project endpoint inspection