swallowkit 1.1.2 → 2.0.0-alpha.2

package/src/core/project/agent-templates/AGENTS.md

@@ -393,9 +393,9 @@ This is a full-stack application deployed on Azure with a TypeScript
 frontend/BFF and an Azure Functions backend in {{backendLanguageLabel}}.
 
 ```text
-Frontend (React / Next.js App Router)
+Frontend ({{frontendLabel}})
   ↓
-BFF (Next.js API Routes)
+BFF ({{bffLabel}})
   ↓
 Azure Functions
   ↓
@@ -404,7 +404,7 @@ Azure Cosmos DB
 
 ### Core architecture rules
 
-1. Next.js API routes are a BFF/proxy layer. Do not place application business
+1. {{bffLabel}} are a BFF/proxy layer. Do not place application business
    logic or direct database access there.
 2. Zod schemas under `shared/models/` are the application model source of truth.
 3. Do not duplicate model definitions across layers.
@@ -415,6 +415,11 @@ Azure Cosmos DB
    markers and boundaries.
 7. Production access to Azure resources must follow the generated security
    architecture; do not introduce hard-coded credentials or connection strings.
+8. Never link standalone Functions to SWA. The same-origin BFF calls the
+   independent backend with server-side BACKEND_FUNCTIONS_BASE_URL and
+   BACKEND_FUNCTIONS_KEY. Never expose these values in browser bundles or VITE_*.
+   Managed Functions use HTTP triggers only; database access, non-HTTP triggers,
+   managed identity, and private networking belong to the standalone backend.
 
 ### Backend-specific rules
 
@@ -427,16 +432,13 @@ values for these fields.
 
 ```text
 {{projectName}}/
-├── app/                    # Next.js App Router
-│   ├── api/                # BFF routes
-│   └── {model}/            # generated/custom UI
+{{frontendStructure}}
 ├── functions/              # Azure Functions backend
 {{functionsStructureLine}}
 ├── shared/
 │   ├── models/             # Zod source-of-truth models
 │   └── index.ts
-├── lib/
-│   └── api/
+├── lib/                    # auth, navigation, and shared application utilities
 ├── components/
 ├── infra/                  # Bicep infrastructure
 ├── .swallowkit/            # SwallowKit project metadata and runbooks
@@ -470,13 +472,26 @@ same generated structure.
 {{pm}} install
 {{runCmd}} swallowkit dev
 {{pm}} run build
-{{pm}} run lint
+{{pm}} run --if-present lint
 {{runCmd}} swallowkit machine verify project
 ```
 
 Always invoke SwallowKit using the package-runner convention generated for this
 project. Do not arbitrarily mix package-manager invocation styles.
 
+{{devGuidance}}
+
+Check for an already-running Cosmos DB Emulator before database tests. If it is
+unavailable, report that prerequisite; do not start/restart it or change global
+tools, TLS trust, or machine settings without explicit permission. Test against
+an isolated database and ports, never reset user data, and stop only processes
+you started. `dev --seed-env` replaces data, so inspect its target first.
+
+Build and run `verify project`, then exercise UI, CRUD, error/validation paths,
+and configured authentication through the same-origin BFF. A passing typecheck
+or server readiness probe alone is not an end-to-end verification. Report
+unverified cloud deployment or unavailable local prerequisites explicitly.
+
 ## Final Rules
 
 Do not:

package/src/core/project/agent-templates/bff-routes.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "app/api/**"
+applyTo: "{{bffGlob}}"
 ---
 
 # BFF API Routes — Rules
@@ -7,10 +7,12 @@ applyTo: "app/api/**"
 The root `AGENTS.md` is the canonical contract. Inspect the current
 responsibility boundary before editing files in this layer.
 
-- `app/api/` is a BFF/proxy layer. Never place business logic, database access,
+- `{{bffPath}}/` is a BFF/proxy layer. Never place business logic, database access,
   or direct Cosmos DB calls here.
-- Use `callFunction()` from `@/lib/api/call-function` to forward requests to
+- Use `callFunction()` from `{{helperImport}}` to forward requests to
   Azure Functions.
+- Keep credentials request-local. Never put the backend URL/key in client
+  code or VITE_* variables. Do not link standalone Functions to SWA.
 - Input/output validation may use schemas imported from `@{{projectName}}/shared`.
 - Never directly edit a route reported as deterministic. Change its source of
   truth and use MCP-first plan/apply, with the machine interface as fallback.

package/src/core/project/capabilities.ts

@@ -27,6 +27,13 @@ export interface CapabilityAuthProvider {
 export interface CapabilitiesContract {
   contractVersion: number;
   swallowkitVersion: string;
+  frontends: {
+    supported: string[];
+    default: string;
+    configuration: string;
+    reactArchitecture: string;
+    development: string;
+  };
   modelDeclarations: CapabilityModelDeclaration[];
   authentication: {
     correctWorkflow: string[];
@@ -64,6 +71,13 @@ export function inspectCapabilities(): CapabilitiesContract {
   return {
     contractVersion: 1,
     swallowkitVersion: getSwallowKitVersion(),
+    frontends: {
+      supported: ["nextjs", "react"],
+      default: "nextjs",
+      configuration: "init --frontend nextjs|react; stored as frontend.framework in swallowkit.config.js. Missing settings preserve Next.js.",
+      reactArchitecture: "React/Vite SPA on SWA -> HTTP-only SWA managed Functions BFF (bff/) -> standalone Functions (functions/). Never link standalone Functions to SWA. Backend keys stay server-side.",
+      development: "React dev runs Vite:3000, BFF:7073, Functions:7071 and SWA CLI:4280; use the SWA port for same-origin APIs and authentication. Build/verify include BFF typechecking.",
+    },
     modelDeclarations: [
       {
         name: "schema",

package/src/core/project/manifest.ts

@@ -1,8 +1,8 @@
 import * as fs from "fs";
 import * as path from "path";
-import { getBackendLanguage, getFullConfig, normalizeAuthConfig, validateConfig } from "../config";
+import { getBackendLanguage, getFrontendFramework, getFullConfig, normalizeAuthConfig, validateConfig } from "../config";
 import { getAllModels, toCamelCase, toKebabCase } from "../scaffold/model-parser";
-import { AuthConfig, BackendLanguage, ConnectorDefinition, ModelAuthPolicy, ModelConnectorConfig } from "../../types";
+import { AuthConfig, BackendLanguage, FrontendFramework, ConnectorDefinition, ModelAuthPolicy, ModelConnectorConfig } from "../../types";
 import { captureConsoleMessages, withWorkingDirectory } from "../operations/runtime";
 
 const CONFIG_CANDIDATES = [
@@ -69,6 +69,7 @@ export interface ProjectManifestArtifacts {
 
 export interface ProjectManifestArchitecture {
   pattern: string;
+  frontendFramework?: FrontendFramework;
   backendLanguage: BackendLanguage;
   layerBoundaries: string[];
   hasSharedWorkspace: boolean;
@@ -81,6 +82,7 @@ export interface ProjectManifest {
   generatedAt: string;
   configPath: string | null;
   backendLanguage: BackendLanguage;
+  frontendFramework?: FrontendFramework;
   configValidation: {
     valid: boolean;
     errors: string[];
@@ -115,7 +117,10 @@ function relativeProjectPath(projectRoot: string, targetPath: string): string {
   return path.relative(projectRoot, targetPath).replace(/\\/g, "/");
 }
 
-function buildModules(projectRoot: string): ProjectManifestModule[] {
+function buildModules(projectRoot: string, frontend: FrontendFramework): ProjectManifestModule[] {
+  const bffRoot = frontend === "react" ? "bff" : "app/api";
+  const uiRoot = frontend === "react" ? "src" : "app";
+  const authRoot = frontend === "react" ? "bff/src/auth" : "app/api/auth";
   const candidates: ProjectManifestModule[] = [
     {
       name: "shared-models",
@@ -126,8 +131,8 @@ function buildModules(projectRoot: string): ProjectManifestModule[] {
     {
       name: "bff",
       kind: "bff",
-      rootPath: "app/api",
-      exists: fs.existsSync(path.join(projectRoot, "app", "api")),
+      rootPath: bffRoot,
+      exists: fs.existsSync(path.join(projectRoot, bffRoot)),
     },
     {
       name: "functions",
@@ -138,8 +143,8 @@ function buildModules(projectRoot: string): ProjectManifestModule[] {
     {
       name: "ui",
       kind: "ui",
-      rootPath: "app",
-      exists: fs.existsSync(path.join(projectRoot, "app")),
+      rootPath: uiRoot,
+      exists: fs.existsSync(path.join(projectRoot, uiRoot)),
     },
     {
       name: "infrastructure",
@@ -150,21 +155,21 @@ function buildModules(projectRoot: string): ProjectManifestModule[] {
     {
       name: "auth",
       kind: "auth",
-      rootPath: "app/api/auth",
-      exists: fs.existsSync(path.join(projectRoot, "app", "api", "auth")),
+      rootPath: authRoot,
+      exists: fs.existsSync(path.join(projectRoot, authRoot)),
     },
   ];
 
   return candidates;
 }
 
-function buildArtifacts(projectRoot: string): ProjectManifestArtifacts {
+function buildArtifacts(projectRoot: string, frontend: FrontendFramework): ProjectManifestArtifacts {
   const openApiDir = path.join(projectRoot, "functions", "openapi");
   const generatedDir = path.join(projectRoot, "functions", "generated");
 
   return {
-    callFunctionHelperPath: "lib/api/call-function.ts",
-    callFunctionHelperExists: fs.existsSync(path.join(projectRoot, "lib", "api", "call-function.ts")),
+    callFunctionHelperPath: frontend === "react" ? "bff/src/lib/call-function.ts" : "lib/api/call-function.ts",
+    callFunctionHelperExists: fs.existsSync(path.join(projectRoot, ...(frontend === "react" ? ["bff", "src", "lib", "call-function.ts"] : ["lib", "api", "call-function.ts"]))),
     openApiSpecs: fs.existsSync(openApiDir)
       ? fs.readdirSync(openApiDir)
           .filter((entry) => entry.endsWith(".json"))
@@ -178,8 +183,8 @@ function buildArtifacts(projectRoot: string): ProjectManifestArtifacts {
       : [],
     proxyPath: "proxy.ts",
     proxyExists: fs.existsSync(path.join(projectRoot, "proxy.ts")),
-    loginPagePath: "app/login/page.tsx",
-    loginPageExists: fs.existsSync(path.join(projectRoot, "app", "login", "page.tsx")),
+    loginPagePath: frontend === "react" ? "src/pages/login.tsx" : "app/login/page.tsx",
+    loginPageExists: fs.existsSync(path.join(projectRoot, ...(frontend === "react" ? ["src", "pages", "login.tsx"] : ["app", "login", "page.tsx"]))),
     authContextPath: "lib/auth/auth-context.tsx",
     authContextExists: fs.existsSync(path.join(projectRoot, "lib", "auth", "auth-context.tsx")),
   };
@@ -188,7 +193,8 @@ function buildArtifacts(projectRoot: string): ProjectManifestArtifacts {
 function buildEntityRoutes(
   projectRoot: string,
   backendLanguage: BackendLanguage,
-  entity: ProjectManifestEntity
+  entity: ProjectManifestEntity,
+  frontend: FrontendFramework
 ): ProjectManifestRoute[] {
   const modelCamel = toCamelCase(entity.name);
   const modelKebab = toKebabCase(entity.name);
@@ -229,8 +235,10 @@ function buildEntityRoutes(
       entityName: entity.name,
       methods: listMethods,
       publicPath: `/api/${modelCamel}`,
-      filePath: `app/api/${modelCamel}/route.ts`,
-      exists: fs.existsSync(path.join(projectRoot, "app", "api", modelCamel, "route.ts")),
+      filePath: frontend === "react" ? `bff/src/${modelCamel}/index.ts` : `app/api/${modelCamel}/route.ts`,
+      exists: frontend === "react"
+        ? fs.existsSync(path.join(projectRoot, "bff", "src", modelCamel, "index.ts")) && fs.existsSync(path.join(projectRoot, "bff", modelCamel, "function.json"))
+        : fs.existsSync(path.join(projectRoot, "app", "api", modelCamel, "route.ts")),
     },
     {
       name: `${entity.name}-bff-detail`,
@@ -239,8 +247,10 @@ function buildEntityRoutes(
       entityName: entity.name,
       methods: detailMethods,
       publicPath: `/api/${modelCamel}/{id}`,
-      filePath: `app/api/${modelCamel}/[id]/route.ts`,
-      exists: fs.existsSync(path.join(projectRoot, "app", "api", modelCamel, "[id]", "route.ts")),
+      filePath: frontend === "react" ? `bff/src/${modelCamel}/index.ts` : `app/api/${modelCamel}/[id]/route.ts`,
+      exists: frontend === "react"
+        ? fs.existsSync(path.join(projectRoot, "bff", "src", modelCamel, "index.ts")) && fs.existsSync(path.join(projectRoot, "bff", modelCamel, "function.json"))
+        : fs.existsSync(path.join(projectRoot, "app", "api", modelCamel, "[id]", "route.ts")),
     },
     {
       name: `${entity.name}-functions`,
@@ -255,7 +265,18 @@ function buildEntityRoutes(
   ];
 }
 
-function buildSystemRoutes(projectRoot: string): ProjectManifestRoute[] {
+function buildSystemRoutes(projectRoot: string, frontend: FrontendFramework, auth?: AuthConfig): ProjectManifestRoute[] {
+  if (frontend === "react") {
+    const providers = Object.values(normalizeAuthConfig(auth)?.schemes ?? {}).map(scheme => scheme.provider);
+    return ["login", "logout", "me"].map(action => ({
+      name: `auth-${action}`, kind: "system", surface: "bff",
+      methods: [action === "me" ? "GET" : "POST"], publicPath: `/api/auth/${action}`,
+      filePath: "bff/src/auth/index.ts",
+      exists: (providers.includes("custom-jwt") || (action === "me" && providers.includes("external-token"))) &&
+        fs.existsSync(path.join(projectRoot, "bff", "src", "auth", "index.ts")) &&
+        fs.existsSync(path.join(projectRoot, "bff", "auth", "function.json")),
+    }));
+  }
   return [
     {
       name: "auth-login",
@@ -296,6 +317,7 @@ export async function buildProjectManifest(projectRoot: string = process.cwd()):
   return withWorkingDirectory(projectRoot, async () => {
     const configPath = resolveConfigPath(projectRoot);
     const backendLanguage = getBackendLanguage(configPath || undefined);
+    const frontendFramework = getFrontendFramework(configPath || undefined);
     const config = getFullConfig(configPath || undefined);
     const configValidation = validateConfig(config);
     const { result: entities, messages } = await captureConsoleMessages(async () => {
@@ -327,8 +349,8 @@ export async function buildProjectManifest(projectRoot: string = process.cwd()):
     );
 
     const routes = [
-      ...entities.flatMap((entity) => buildEntityRoutes(projectRoot, backendLanguage, entity)),
-      ...buildSystemRoutes(projectRoot),
+      ...entities.flatMap((entity) => buildEntityRoutes(projectRoot, backendLanguage, entity, frontendFramework)),
+      ...buildSystemRoutes(projectRoot, frontendFramework, config.auth),
     ].sort((left, right) => left.name.localeCompare(right.name));
 
     const manifest: ProjectManifest = {
@@ -336,6 +358,7 @@ export async function buildProjectManifest(projectRoot: string = process.cwd()):
       generatedAt: new Date().toISOString(),
       configPath,
       backendLanguage,
+      frontendFramework,
       configValidation,
       connectors: Object.entries(config.connectors || {})
         .map(([name, definition]) => ({ name, definition }))
@@ -343,16 +366,18 @@ export async function buildProjectManifest(projectRoot: string = process.cwd()):
       auth: normalizeAuthConfig(config.auth) || null,
       entities: entities.sort((left, right) => left.name.localeCompare(right.name)),
       routes,
-      modules: buildModules(projectRoot),
-      artifacts: buildArtifacts(projectRoot),
+      modules: buildModules(projectRoot, frontendFramework),
+      artifacts: buildArtifacts(projectRoot, frontendFramework),
       architecture: {
-        pattern: "Next.js BFF + Azure Functions + shared Zod models",
+        pattern: frontendFramework === "react" ? "React SPA + SWA managed Functions BFF + standalone Azure Functions + shared Zod models" : "Next.js BFF + Azure Functions + shared Zod models",
+        frontendFramework,
         backendLanguage,
         layerBoundaries: [
           "shared/models -> schema source of truth",
-          "app/api -> BFF layer only",
+          `${frontendFramework === "react" ? "bff" : "app/api"} -> BFF layer only`,
           "functions -> backend logic and data access",
-          "app -> UI and pages",
+          `${frontendFramework === "react" ? "src" : "app"} -> UI and pages`,
+          "SWA and standalone Functions are not linked; backend credentials stay in the BFF",
         ],
         hasSharedWorkspace: fs.existsSync(path.join(projectRoot, "shared", "package.json")),
         hasConnectors: Object.keys(config.connectors || {}).length > 0,