forgeos 0.1.0-alpha.4 → 0.1.0-alpha.40

package/src/forge/compiler/integration/plan.ts

@@ -20,7 +20,6 @@ import { PACKAGE_ANALYZER_VERSION } from "../package-graph/constants.ts";
 import { RECIPE_SCHEMA_VERSION } from "../recipes/definitions.ts";
 import { hashStable } from "../primitives/hash.ts";
 import { stableSortEmitFiles, stableSortStrings } from "../primitives/index.ts";
-import { detectOrphanedGeneratedFiles } from "../orchestrator/orphans.ts";
 import type { DiscoverContext } from "../orchestrator/types.ts";
 import {
   createRenderContext,
@@ -28,6 +27,7 @@ import {
   renderAdapterModule,
   renderIntegrationDoc,
   renderIntegrationModule,
+  renderRootFile,
   renderTestkitModule,
 } from "./render.ts";
 
@@ -41,11 +41,23 @@ export interface IntegrationPlanInput {
   existingLock: ForgeLock | null;
 }
 
+function headerForGeneratedPath(path: string): EmitFile["header"] {
+  return path.endsWith(".yml") || path.endsWith(".yaml") ? "none" : undefined;
+}
+
+function headerForRootFile(path: string): EmitFile["header"] {
+  if (path.endsWith(".env.example") || path.endsWith(".yml") || path.endsWith(".yaml")) {
+    return "none";
+  }
+  return "deterministic";
+}
+
 function makeEmitFile(path: string, content: string): EmitFile {
   return {
     path,
     content,
     contentHash: hashStable(content),
+    header: headerForGeneratedPath(path),
   };
 }
 
@@ -85,6 +97,7 @@ function shouldEmitAdapter(
 function buildGeneratedPaths(
   recipe: IntegrationRecipe,
   compatible: RuntimeContext[],
+  workspaceRoot: string,
 ): string[] {
   const paths: string[] = [];
 
@@ -107,6 +120,13 @@ function buildGeneratedPaths(
     paths.push(`${GENERATED_DIR}/integrations/${integration}`);
   }
 
+  for (const rootFile of recipe.rootFiles ?? []) {
+    if (rootFile.startsWith("web/") && !nodeFileSystem.exists(join(workspaceRoot, "web", "package.json"))) {
+      continue;
+    }
+    paths.push(rootFile);
+  }
+
   paths.push(
     `${GENERATED_DIR}/runtimeMatrix.ts`,
     `${GENERATED_DIR}/runtimeMatrix.json`,
@@ -187,6 +207,8 @@ export function buildIntegrationEmitPlan(input: IntegrationPlanInput): EmitPlan
     secrets,
     compatible,
     incompatible,
+    workspaceRoot: ctx.workspaceRoot,
+    appGraph,
   });
 
   const files: EmitFile[] = [];
@@ -208,6 +230,8 @@ export function buildIntegrationEmitPlan(input: IntegrationPlanInput): EmitPlan
           secrets,
           compatible,
           incompatible,
+          workspaceRoot: ctx.workspaceRoot,
+          appGraph,
         }),
       ),
     );
@@ -222,6 +246,19 @@ export function buildIntegrationEmitPlan(input: IntegrationPlanInput): EmitPlan
     );
   }
 
+  for (const rootFile of recipe.rootFiles ?? []) {
+    if (rootFile.startsWith("web/") && !nodeFileSystem.exists(join(ctx.workspaceRoot, "web", "package.json"))) {
+      continue;
+    }
+    const content = renderRootFile(rootFile, templateCtx);
+    files.push({
+      path: rootFile,
+      content,
+      contentHash: hashStable(content),
+      header: headerForRootFile(rootFile),
+    });
+  }
+
   for (const testkit of recipe.testkits) {
     files.push(
       makeEmitFile(
@@ -242,6 +279,8 @@ export function buildIntegrationEmitPlan(input: IntegrationPlanInput): EmitPlan
           secrets,
           compatible,
           incompatible,
+          workspaceRoot: ctx.workspaceRoot,
+          appGraph,
         }),
       ),
     );
@@ -250,21 +289,13 @@ export function buildIntegrationEmitPlan(input: IntegrationPlanInput): EmitPlan
   const matrix = buildRuntimeMatrix(allClassified);
   files.push(...buildGuardArtifactEmitFiles(matrix, appGraph.moduleGraph));
 
-  const generatedFiles = buildGeneratedPaths(recipe, compatible);
+  const generatedFiles = buildGeneratedPaths(recipe, compatible, ctx.workspaceRoot);
   const lockEntry = buildLockEntry(recipe, classified, generatedFiles);
   const lock = mergeLockPackages(input.existingLock, lockEntry, ctx);
 
-  const sortedFiles = stableSortEmitFiles(files);
-  const plannedPathSet = new Set(sortedFiles.map((file) => file.path));
-  const orphanedFiles = detectOrphanedGeneratedFiles(
-    ctx.workspaceRoot,
-    ctx.generatedDir,
-    plannedPathSet,
-  );
-
   return {
-    files: sortedFiles,
-    orphanedFiles,
+    files: stableSortEmitFiles(files),
+    orphanedFiles: [],
     lock,
   };
 }

package/src/forge/compiler/integration/render.ts

@@ -1,4 +1,5 @@
 import type { SecretRequirement } from "../types/capability.ts";
+import type { AppGraph } from "../types/app-graph.ts";
 import type { IntegrationRecipe } from "../types/integration.ts";
 import type { RuntimeContext } from "../types/runtime.ts";
 import { RUNTIME_CONTEXTS } from "../types/runtime.ts";
@@ -8,6 +9,7 @@ import {
   renderQualityAdapter,
   renderQualityDoc,
   renderQualityIntegration,
+  renderQualityRootFile,
   renderQualityTestkit,
 } from "./templates/index.ts";
 import type { IntegrationTemplateInput } from "./templates/types.ts";
@@ -92,6 +94,8 @@ export function createRenderContext(input: {
   secrets: SecretRequirement[];
   compatible: RuntimeContext[];
   incompatible: RuntimeContext[];
+  workspaceRoot?: string;
+  appGraph?: AppGraph;
 }): IntegrationTemplateInput {
   return buildTemplateInput(input);
 }
@@ -105,6 +109,8 @@ export function renderAdapterModule(input: {
   secrets: SecretRequirement[];
   compatible: RuntimeContext[];
   incompatible: RuntimeContext[];
+  workspaceRoot?: string;
+  appGraph?: AppGraph;
 }): string {
   const ctx = createRenderContext(input);
   const adapterFilename = `${input.alias}.${input.context}.ts`;
@@ -167,6 +173,8 @@ export function renderIntegrationDoc(input: {
   secrets: SecretRequirement[];
   compatible: RuntimeContext[];
   incompatible: RuntimeContext[];
+  workspaceRoot?: string;
+  appGraph?: AppGraph;
 }): string {
   const ctx = buildTemplateInput({
     alias: input.alias,
@@ -177,6 +185,8 @@ export function renderIntegrationDoc(input: {
     secrets: input.secrets,
     compatible: input.compatible,
     incompatible: input.incompatible,
+    workspaceRoot: input.workspaceRoot,
+    appGraph: input.appGraph,
   });
 
   const docName = `${input.alias}.md`;
@@ -187,3 +197,22 @@ export function renderIntegrationDoc(input: {
 
   return skeletonDoc(ctx);
 }
+
+export function renderRootFile(
+  relativePath: string,
+  input: IntegrationTemplateInput,
+): string {
+  const quality = renderQualityRootFile(relativePath, input);
+  if (quality) {
+    return quality;
+  }
+
+  return [
+    `/** Forge generated root file for ${input.alias}: ${relativePath}. */`,
+    `export const forgeIntegrationRootFile = ${serializeCanonical({
+      alias: input.alias,
+      path: relativePath,
+    }).trim()} as const;`,
+    "",
+  ].join("\n");
+}

package/src/forge/compiler/integration/snapshot.ts

@@ -14,6 +14,7 @@ function readOptional(path: string): string | null {
 
 export function snapshotVersionControlled(
   workspaceRoot: string,
+  extraRelativePaths: string[] = [],
 ): VersionControlledSnapshot {
   const pm = detectPackageManager(workspaceRoot);
   const lockfile = getLockfileForPm(pm);
@@ -25,6 +26,7 @@ export function snapshotVersionControlled(
       `${workspaceRoot.replace(/\\/g, "/")}/`,
       "",
     ),
+    ...extraRelativePaths,
   ];
 
   const files = new Map<string, string | null>();

package/src/forge/compiler/integration/templates/convex.ts

@@ -0,0 +1,70 @@
+import type { IntegrationTemplateInput } from "./types.ts";
+
+export function renderConvexTestkit(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated mock testkit for Convex app-contract evaluation. */",
+    "export interface ConvexFunctionRef {",
+    "  readonly kind: \"query\" | \"mutation\" | \"action\";",
+    "  readonly path: string;",
+    "}",
+    "",
+    "export function createConvexMock(functions: ConvexFunctionRef[] = []) {",
+    "  const calls: Array<{ path: string; args: unknown }> = [];",
+    "  return {",
+    "    functions,",
+    "    calls,",
+    "    call(path: string, args: unknown = {}) {",
+    "      calls.push({ path, args });",
+    "      return { ok: true, path, args } as const;",
+    "    },",
+    "  } as const;",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderConvexDoc(input: IntegrationTemplateInput): string {
+  return [
+    "# Convex integration",
+    "",
+    "Generated by Forge (recipe v1).",
+    "",
+    "Convex is treated as an agent-friendly backend package. ForgeOS treats it as an app-contract integration surface: package placement, frontend/backend usage, generated docs, and future function-map import.",
+    "",
+    "## Runtime placement",
+    "",
+    "- Use Convex client hooks and generated Convex APIs in frontend/client code.",
+    "- Use Convex server/admin clients only from server, action, workflow, or endpoint contexts.",
+    "- Do not import Convex runtime clients from Forge commands, queries, or liveQueries.",
+    "- Type-only imports are acceptable when the TypeScript compiler erases them.",
+    "",
+    "## App-contract import targets",
+    "",
+    "Future Convex import support should inspect:",
+    "",
+    "- `convex/schema.ts` for table names and fields;",
+    "- `convex/_generated/api.d.ts` for query, mutation, and action references;",
+    "- frontend `useQuery`, `useMutation`, and `useAction` calls for route/component capability mapping;",
+    "- auth and deployment notes from Convex config files.",
+    "",
+    "## Commands",
+    "",
+    "```bash",
+    "forge add convex",
+    "forge deps inspect convex --json",
+    "forge inspect runtime-matrix --json",
+    "forge check --json",
+    "```",
+    "",
+    "## Generated evidence",
+    "",
+    `Compatible contexts: ${input.compatible.join(", ")}`,
+    "",
+    `Incompatible contexts: ${input.incompatible.join(", ")}`,
+    "",
+    "Optional environment names:",
+    "",
+    ...input.secrets.map((secret) => `- ${secret.envVar}`),
+    "",
+  ].join("\n");
+}

package/src/forge/compiler/integration/templates/index.ts

@@ -4,5 +4,6 @@ export {
   renderQualityAdapter,
   renderQualityDoc,
   renderQualityIntegration,
+  renderQualityRootFile,
   renderQualityTestkit,
 } from "./render.ts";

package/src/forge/compiler/integration/templates/render.ts

@@ -1,8 +1,10 @@
 import type { IntegrationTemplateInput } from "./types.ts";
 import * as ai from "./ai.ts";
+import * as convex from "./convex.ts";
 import * as posthog from "./posthog.ts";
 import * as sentry from "./sentry.ts";
 import * as stripe from "./stripe.ts";
+import * as workos from "./workos.ts";
 import * as zod from "./zod.ts";
 
 type TemplateRenderer = (input: IntegrationTemplateInput) => string;
@@ -26,6 +28,9 @@ const ADAPTER_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
   ai: {
     "ai.server.ts": ai.renderAiServerAdapter,
   },
+  workos: {
+    "workos.server.ts": workos.renderWorkosServerAdapter,
+  },
 };
 
 const INTEGRATION_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
@@ -45,6 +50,17 @@ const INTEGRATION_RENDERERS: Record<string, Record<string, TemplateRenderer>> =
     "ai/generations.ts": ai.renderAiGenerations,
     "ai/testkit.ts": ai.renderAiTestkit,
   },
+  workos: {
+    "workos/authkit.ts": workos.renderWorkosAuthkit,
+    "workos/auth-routes.ts": workos.renderWorkosAuthRoutes,
+    "workos/fga.ts": workos.renderWorkosFga,
+    "workos/http-handler.ts": workos.renderWorkosHttpHandler,
+    "workos/resource-map.ts": workos.renderWorkosResourceMap,
+    "workos/seed.ts": workos.renderWorkosSeed,
+    "workos/session.ts": workos.renderWorkosSession,
+    "workos/webhook.ts": workos.renderWorkosWebhook,
+    "workos/workos-seed.yml": workos.renderWorkosSeedYaml,
+  },
 };
 
 const TESTKIT_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
@@ -52,7 +68,9 @@ const TESTKIT_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
   stripe: { "stripe.mock.ts": stripe.renderStripeTestkit },
   posthog: { "posthog.mock.ts": posthog.renderPosthogTestkit },
   sentry: { "sentry.mock.ts": sentry.renderSentryTestkit },
+  convex: { "convex.mock.ts": convex.renderConvexTestkit },
   ai: { "ai.mock.ts": ai.renderAiTestkitLegacy },
+  workos: { "workos.mock.ts": workos.renderWorkosTestkit },
 };
 
 const DOC_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
@@ -60,7 +78,18 @@ const DOC_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
   stripe: { "stripe.md": stripe.renderStripeDoc },
   posthog: { "posthog.md": posthog.renderPosthogDoc },
   sentry: { "sentry.md": sentry.renderSentryDoc },
+  convex: { "convex.md": convex.renderConvexDoc },
   ai: { "ai.md": ai.renderAiDoc },
+  workos: { "workos.md": workos.renderWorkosDoc },
+};
+
+const ROOT_FILE_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
+  workos: {
+    ".env.example": workos.renderWorkosEnvExample,
+    "src/policies.workos.ts": workos.renderWorkosPolicies,
+    "web/src/lib/workos-auth.tsx": workos.renderWorkosReactBridge,
+    "workos-seed.yml": workos.renderWorkosSeedYaml,
+  },
 };
 
 function lookup(
@@ -99,6 +128,13 @@ export function renderQualityDoc(
   return lookup(DOC_RENDERERS, input.alias, filename)?.(input) ?? null;
 }
 
+export function renderQualityRootFile(
+  filename: string,
+  input: IntegrationTemplateInput,
+): string | null {
+  return lookup(ROOT_FILE_RENDERERS, input.alias, filename)?.(input) ?? null;
+}
+
 export function buildTemplateInput(input: {
   alias: string;
   recipe: IntegrationTemplateInput["recipe"];
@@ -108,6 +144,8 @@ export function buildTemplateInput(input: {
   secrets: IntegrationTemplateInput["secrets"];
   compatible: IntegrationTemplateInput["compatible"];
   incompatible: IntegrationTemplateInput["incompatible"];
+  workspaceRoot?: string;
+  appGraph?: IntegrationTemplateInput["appGraph"];
 }): IntegrationTemplateInput {
   return input;
 }

package/src/forge/compiler/integration/templates/types.ts

@@ -1,4 +1,5 @@
 import type { SecretRequirement } from "../../types/capability.ts";
+import type { AppGraph } from "../../types/app-graph.ts";
 import type { IntegrationRecipe } from "../../types/integration.ts";
 import type { RuntimeContext } from "../../types/runtime.ts";
 
@@ -11,4 +12,6 @@ export interface IntegrationTemplateInput {
   secrets: SecretRequirement[];
   compatible: RuntimeContext[];
   incompatible: RuntimeContext[];
+  workspaceRoot?: string;
+  appGraph?: AppGraph;
 }