forgeos 0.1.0-alpha.0

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

@@ -0,0 +1,145 @@
+import type { IntegrationTemplateInput } from "./types.ts";
+
+const SECRETS_IMPORT = 'import type { SecretsContext } from "../secretsContext.js";';
+const CONFIG_IMPORT = 'import type { ConfigContext } from "../secretsContext.js";';
+
+export function renderPosthogClientAdapter(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated PostHog browser adapter. */",
+    'import posthog from "posthog-js";',
+    CONFIG_IMPORT,
+    "",
+    "export function createPosthogClient(",
+    "  config: ConfigContext,",
+    '  options?: { api_host?: string; person_profiles?: "identified_only" | "always" },',
+    ") {",
+    '  const apiKey = config.get("NEXT_PUBLIC_POSTHOG_KEY");',
+    "  return posthog.init(apiKey, {",
+    '    api_host: options?.api_host ?? config.optional("NEXT_PUBLIC_POSTHOG_HOST") ?? "https://us.i.posthog.com",',
+    "    person_profiles: options?.person_profiles ?? \"identified_only\",",
+    "    ...options,",
+    "  });",
+    "}",
+    "",
+    "export type ForgePosthogClient = typeof posthog;",
+    "",
+  ].join("\n");
+}
+
+export function renderPosthogServerAdapter(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated PostHog server adapter. */",
+    'import { PostHog } from "posthog-node";',
+    SECRETS_IMPORT,
+    CONFIG_IMPORT,
+    "",
+    "export function createPosthogServer(",
+    "  secrets: SecretsContext,",
+    "  config: ConfigContext,",
+    "): PostHog {",
+    '  const apiKey = secrets.get("POSTHOG_KEY");',
+    '  const host = config.optional("POSTHOG_HOST") ?? "https://us.i.posthog.com";',
+    "  return new PostHog(apiKey, { host });",
+    "}",
+    "",
+    "export type ForgePosthogServer = PostHog;",
+    "",
+  ].join("\n");
+}
+
+export function renderPosthogEvents(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated PostHog event capture helpers. */",
+    'import type { PostHog } from "posthog-node";',
+    'import type posthog from "posthog-js";',
+    "",
+    "export function captureServerEvent(",
+    "  client: PostHog,",
+    "  distinctId: string,",
+    "  event: string,",
+    "  properties?: Record<string, unknown>,",
+    ") {",
+    "  client.capture({ distinctId, event, properties });",
+    "}",
+    "",
+    "export function captureClientEvent(",
+    "  client: typeof posthog,",
+    "  event: string,",
+    "  properties?: Record<string, unknown>,",
+    ") {",
+    "  client.capture(event, properties);",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderPosthogFlags(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated PostHog feature flag helpers. */",
+    'import type { PostHog } from "posthog-node";',
+    'import type posthog from "posthog-js";',
+    "",
+    "export async function isServerFeatureEnabled(",
+    "  client: PostHog,",
+    "  distinctId: string,",
+    "  flag: string,",
+    "): Promise<boolean> {",
+    "  return client.isFeatureEnabled(flag, distinctId) ?? false;",
+    "}",
+    "",
+    "export function isClientFeatureEnabled(",
+    "  client: typeof posthog,",
+    "  flag: string,",
+    "): boolean {",
+    "  return client.isFeatureEnabled(flag) ?? false;",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderPosthogTestkit(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated mock testkit for posthog. */",
+    "",
+    "export function createPosthogMock() {",
+    "  const flags = new Map<string, boolean>();",
+    "  return {",
+    "    capture: () => undefined,",
+    "    identify: () => undefined,",
+    "    isFeatureEnabled: (flag: string) => flags.get(flag) ?? false,",
+    "    setFlag: (flag: string, value: boolean) => flags.set(flag, value),",
+    "    shutdown: async () => undefined,",
+    "  } as const;",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderPosthogDoc(input: IntegrationTemplateInput): string {
+  return [
+    "# PostHog integration",
+    "",
+    "Generated by Forge (recipe v2).",
+    "",
+    "Client/server split reference.",
+    "",
+    "## Packages",
+    "",
+    "- `posthog-js` → client/shared contexts",
+    "- `posthog-node` → server/action/workflow contexts",
+    "",
+    "## Integrations",
+    "",
+    "- `integrations/posthog/events.ts` — capture helpers",
+    "- `integrations/posthog/flags.ts` — feature flag helpers",
+    "",
+    "## Validation",
+    "",
+    "- `posthog-js` in client → passes",
+    "- `posthog-node` in action → passes",
+    "- `posthog-node` in command → `FORGE_GUARD_VIOLATION`",
+    "",
+    `Packages: ${input.packageNames.join(", ")}`,
+    "",
+  ].join("\n");
+}

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

@@ -0,0 +1,113 @@
+import type { IntegrationTemplateInput } from "./types.ts";
+import * as ai from "./ai.ts";
+import * as posthog from "./posthog.ts";
+import * as sentry from "./sentry.ts";
+import * as stripe from "./stripe.ts";
+import * as zod from "./zod.ts";
+
+type TemplateRenderer = (input: IntegrationTemplateInput) => string;
+
+const ADAPTER_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
+  zod: {
+    "zod.shared.ts": zod.renderZodAdapter,
+  },
+  stripe: {
+    "stripe.server.ts": stripe.renderStripeServerAdapter,
+    "stripe.workflow.ts": stripe.renderStripeWorkflowAdapter,
+  },
+  posthog: {
+    "posthog.client.ts": posthog.renderPosthogClientAdapter,
+    "posthog.server.ts": posthog.renderPosthogServerAdapter,
+  },
+  sentry: {
+    "sentry.client.ts": sentry.renderSentryClientAdapter,
+    "sentry.server.ts": sentry.renderSentryServerAdapter,
+  },
+  ai: {
+    "ai.server.ts": ai.renderAiServerAdapter,
+  },
+};
+
+const INTEGRATION_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
+  stripe: {
+    "stripe/webhook.ts": stripe.renderStripeWebhook,
+  },
+  posthog: {
+    "posthog/events.ts": posthog.renderPosthogEvents,
+    "posthog/flags.ts": posthog.renderPosthogFlags,
+  },
+  sentry: {
+    "sentry/errors.ts": sentry.renderSentryErrors,
+    "sentry/releases.ts": sentry.renderSentryReleases,
+    "sentry/sourcemaps.ts": sentry.renderSentrySourcemaps,
+  },
+  ai: {
+    "ai/generations.ts": ai.renderAiGenerations,
+    "ai/testkit.ts": ai.renderAiTestkit,
+  },
+};
+
+const TESTKIT_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
+  zod: { "zod.mock.ts": zod.renderZodTestkit },
+  stripe: { "stripe.mock.ts": stripe.renderStripeTestkit },
+  posthog: { "posthog.mock.ts": posthog.renderPosthogTestkit },
+  sentry: { "sentry.mock.ts": sentry.renderSentryTestkit },
+  ai: { "ai.mock.ts": ai.renderAiTestkitLegacy },
+};
+
+const DOC_RENDERERS: Record<string, Record<string, TemplateRenderer>> = {
+  zod: { "zod.md": zod.renderZodDoc },
+  stripe: { "stripe.md": stripe.renderStripeDoc },
+  posthog: { "posthog.md": posthog.renderPosthogDoc },
+  sentry: { "sentry.md": sentry.renderSentryDoc },
+  ai: { "ai.md": ai.renderAiDoc },
+};
+
+function lookup(
+  table: Record<string, Record<string, TemplateRenderer>>,
+  alias: string,
+  filename: string,
+): TemplateRenderer | null {
+  return table[alias]?.[filename] ?? null;
+}
+
+export function renderQualityAdapter(
+  filename: string,
+  input: IntegrationTemplateInput,
+): string | null {
+  return lookup(ADAPTER_RENDERERS, input.alias, filename)?.(input) ?? null;
+}
+
+export function renderQualityIntegration(
+  relativePath: string,
+  input: IntegrationTemplateInput,
+): string | null {
+  return lookup(INTEGRATION_RENDERERS, input.alias, relativePath)?.(input) ?? null;
+}
+
+export function renderQualityTestkit(
+  filename: string,
+  input: IntegrationTemplateInput,
+): string | null {
+  return lookup(TESTKIT_RENDERERS, input.alias, filename)?.(input) ?? null;
+}
+
+export function renderQualityDoc(
+  filename: string,
+  input: IntegrationTemplateInput,
+): string | null {
+  return lookup(DOC_RENDERERS, input.alias, filename)?.(input) ?? null;
+}
+
+export function buildTemplateInput(input: {
+  alias: string;
+  recipe: IntegrationTemplateInput["recipe"];
+  context: IntegrationTemplateInput["context"];
+  packageName: string;
+  packageNames: string[];
+  secrets: IntegrationTemplateInput["secrets"];
+  compatible: IntegrationTemplateInput["compatible"];
+  incompatible: IntegrationTemplateInput["incompatible"];
+}): IntegrationTemplateInput {
+  return input;
+}

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

@@ -0,0 +1,151 @@
+import type { IntegrationTemplateInput } from "./types.ts";
+
+const SECRETS_IMPORT = 'import type { SecretsContext } from "../secretsContext.js";';
+const CONFIG_IMPORT = 'import type { ConfigContext } from "../secretsContext.js";';
+
+export function renderSentryClientAdapter(input: IntegrationTemplateInput): string {
+  const framework = input.recipe.frameworkTarget ?? "nextjs";
+  return [
+    `/** Forge generated Sentry client adapter (${framework} target). */`,
+    'import * as Sentry from "@sentry/nextjs";',
+    SECRETS_IMPORT,
+    "",
+    "export function initSentryClient(secrets: SecretsContext, options?: Sentry.BrowserOptions) {",
+    "  Sentry.init({",
+    "    dsn: secrets.optional(\"SENTRY_DSN\"),",
+    "    tracesSampleRate: 0.1,",
+    "    ...options,",
+    "  });",
+    "}",
+    "",
+    "export { Sentry };",
+    "",
+  ].join("\n");
+}
+
+export function renderSentryServerAdapter(input: IntegrationTemplateInput): string {
+  const framework = input.recipe.frameworkTarget ?? "nextjs";
+  return [
+    `/** Forge generated Sentry server adapter (${framework} target). */`,
+    'import * as Sentry from "@sentry/nextjs";',
+    SECRETS_IMPORT,
+    "",
+    "export function initSentryServer(secrets: SecretsContext, options?: Sentry.NodeOptions) {",
+    "  Sentry.init({",
+    "    dsn: secrets.optional(\"SENTRY_DSN\"),",
+    "    tracesSampleRate: 0.1,",
+    "    ...options,",
+    "  });",
+    "}",
+    "",
+    "export function captureServerException(error: unknown) {",
+    "  return Sentry.captureException(error);",
+    "}",
+    "",
+    "export { Sentry };",
+    "",
+  ].join("\n");
+}
+
+export function renderSentryErrors(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated Sentry error capture helpers. */",
+    'import * as Sentry from "@sentry/nextjs";',
+    "",
+    "export function captureActionError(error: unknown, context?: Record<string, unknown>) {",
+    "  if (context) {",
+    "    Sentry.withScope((scope) => {",
+    "      for (const [key, value] of Object.entries(context)) {",
+    "        scope.setExtra(key, value);",
+    "      }",
+    "      Sentry.captureException(error);",
+    "    });",
+    "    return;",
+    "  }",
+    "  Sentry.captureException(error);",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderSentryReleases(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated Sentry release tracking helpers. */",
+    CONFIG_IMPORT,
+    "",
+    "export function resolveSentryRelease(config: ConfigContext): string | undefined {",
+    '  return config.optional("SENTRY_RELEASE") ?? config.optional("VERCEL_GIT_COMMIT_SHA");',
+    "}",
+    "",
+    "export const sentryReleaseEnvVars = [",
+    '  "SENTRY_RELEASE",',
+    '  "VERCEL_GIT_COMMIT_SHA",',
+    "] as const;",
+    "",
+  ].join("\n");
+}
+
+export function renderSentrySourcemaps(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated Sentry source map upload configuration (names only). */",
+    "",
+    "export const sentrySourceMapEnvVars = {",
+    '  authToken: "SENTRY_AUTH_TOKEN",',
+    '  org: "SENTRY_ORG",',
+    '  project: "SENTRY_PROJECT",',
+    "} as const;",
+    "",
+    "export function describeSentrySourceMapUpload(): string {",
+    '  return "Configure SENTRY_AUTH_TOKEN, SENTRY_ORG, and SENTRY_PROJECT for CI source map uploads.";',
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderSentryTestkit(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated mock testkit for sentry. */",
+    "",
+    "export function createSentryMock() {",
+    "  const events: unknown[] = [];",
+    "  return {",
+    "    captureException: (error: unknown) => {",
+    "      events.push(error);",
+    "      return \"mock-event-id\";",
+    "    },",
+    "    getEvents: () => [...events],",
+    "    init: () => undefined,",
+    "  } as const;",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderSentryDoc(input: IntegrationTemplateInput): string {
+  const framework = input.recipe.frameworkTarget ?? "nextjs";
+  return [
+    "# Sentry integration",
+    "",
+    "Generated by Forge (recipe v2).",
+    "",
+    `Framework target: **${framework}** (uses \`@sentry/nextjs\`).`,
+    "",
+    "## Integrations",
+    "",
+    "- `integrations/sentry/errors.ts` — server/action error capture",
+    "- `integrations/sentry/releases.ts` — release tracking",
+    "- `integrations/sentry/sourcemaps.ts` — source map env vars for CI",
+    "",
+    "## Source map env vars",
+    "",
+    "- `SENTRY_AUTH_TOKEN`",
+    "- `SENTRY_ORG`",
+    "- `SENTRY_PROJECT`",
+    "",
+    "## Validation",
+    "",
+    "- Sentry server capture in `action` → passes",
+    "- Direct Sentry capture in `command` → `FORGE_GUARD_VIOLATION`",
+    "",
+  ].join("\n");
+}

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

@@ -0,0 +1,109 @@
+import type { IntegrationTemplateInput } from "./types.ts";
+
+const SECRETS_IMPORT = 'import type { SecretsContext } from "../secretsContext.js";';
+
+export function renderStripeServerAdapter(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated Stripe server adapter — action/workflow/endpoint contexts. */",
+    'import Stripe from "stripe";',
+    SECRETS_IMPORT,
+    "",
+    'const DEFAULT_API_VERSION = "2024-11-20.acacia" as Stripe.LatestApiVersion;',
+    "",
+    "export function createStripeClient(secrets: SecretsContext): Stripe {",
+    '  const secretKey = secrets.get("STRIPE_SECRET_KEY");',
+    "  return new Stripe(secretKey, { apiVersion: DEFAULT_API_VERSION });",
+    "}",
+    "",
+    "export type ForgeStripeServerClient = Stripe;",
+    "",
+  ].join("\n");
+}
+
+export function renderStripeWorkflowAdapter(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated Stripe workflow adapter — durable workflow steps only. */",
+    'import type Stripe from "stripe";',
+    'import { createStripeClient } from "./stripe.server.js";',
+    SECRETS_IMPORT,
+    "",
+    "export function createStripeWorkflowClient(secrets: SecretsContext): Stripe {",
+    "  return createStripeClient(secrets);",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderStripeWebhook(input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated Stripe webhook verification helper. */",
+    'import Stripe from "stripe";',
+    SECRETS_IMPORT,
+    "",
+    "export function constructStripeWebhookEvent(",
+    "  payload: string | Buffer,",
+    "  signature: string,",
+    "  secrets: SecretsContext,",
+    "): Stripe.Event {",
+    '  const secret = secrets.get("STRIPE_WEBHOOK_SECRET");',
+    "  return Stripe.webhooks.constructEvent(payload, signature, secret);",
+    "}",
+    "",
+    `// Secrets (names only): ${input.secrets.map((s) => s.envVar).join(", ")}`,
+    "",
+  ].join("\n");
+}
+
+export function renderStripeTestkit(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated mock testkit for stripe. */",
+    "",
+    "export function createStripeMock() {",
+    "  return {",
+    "    customers: {",
+    "      create: async () => ({ id: \"cus_forge_mock\" }),",
+    "      retrieve: async (id: string) => ({ id, email: \"test@forge.local\" }),",
+    "    },",
+    "    checkout: {",
+    "      sessions: {",
+    "        create: async () => ({ id: \"cs_forge_mock\", url: \"https://checkout.forge.test\" }),",
+    "      },",
+    "    },",
+    "    webhooks: {",
+    "      constructEvent: () => ({ type: \"checkout.session.completed\", data: { object: {} } }),",
+    "    },",
+    "  } as const;",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderStripeDoc(input: IntegrationTemplateInput): string {
+  return [
+    "# Stripe integration",
+    "",
+    "Generated by Forge (recipe v2).",
+    "",
+    "Server/action/workflow package reference. **Not allowed in command/query/liveQuery.**",
+    "",
+    "## Adapters",
+    "",
+    "- `packages/stripe.server.ts` — server/action client factory (`ctx.secrets`)",
+    "- `packages/stripe.workflow.ts` — workflow-safe client",
+    "- `integrations/stripe/webhook.ts` — webhook signature verification",
+    "",
+    "## Secrets (names only)",
+    "",
+    input.secrets.map((s) => `- \`${s.envVar}\``).join("\n"),
+    "",
+    "## Validation",
+    "",
+    "- Stripe in `action` → passes",
+    "- Stripe in `command` → `FORGE_GUARD_VIOLATION`",
+    "- Transitive stripe in command → fails",
+    '- `import type Stripe from "stripe"` in command → passes (type-only)',
+    "",
+    `Incompatible contexts: ${input.incompatible.join(", ")}`,
+    "",
+  ].join("\n");
+}

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

@@ -0,0 +1,14 @@
+import type { SecretRequirement } from "../../types/capability.ts";
+import type { IntegrationRecipe } from "../../types/integration.ts";
+import type { RuntimeContext } from "../../types/runtime.ts";
+
+export interface IntegrationTemplateInput {
+  alias: string;
+  recipe: IntegrationRecipe;
+  context: RuntimeContext;
+  packageName: string;
+  packageNames: string[];
+  secrets: SecretRequirement[];
+  compatible: RuntimeContext[];
+  incompatible: RuntimeContext[];
+}

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

@@ -0,0 +1,55 @@
+import type { IntegrationTemplateInput } from "./types.ts";
+
+export function renderZodAdapter(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated — pure validation reference (all runtime contexts). */",
+    'import { z } from "zod";',
+    "",
+    "export { z };",
+    'export type { ZodSchema, ZodType, ZodTypeDef } from "zod";',
+    "",
+    "/** Safe in command, client, server, and every Forge context. */",
+    "export const forgeZod = z;",
+    "",
+  ].join("\n");
+}
+
+export function renderZodTestkit(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated mock testkit for zod. */",
+    'import { z } from "zod";',
+    "",
+    "export function createZodMock() {",
+    "  return {",
+    "    parse: <T>(schema: z.ZodType<T>, value: unknown) => schema.parse(value),",
+    "    safeParse: <T>(schema: z.ZodType<T>, value: unknown) => schema.safeParse(value),",
+    "  } as const;",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderZodDoc(input: IntegrationTemplateInput): string {
+  return [
+    "# Zod integration",
+    "",
+    "Generated by Forge (recipe v2).",
+    "",
+    "Zod is a **pure package reference** — allowed in every runtime context.",
+    "",
+    "## Usage",
+    "",
+    "```ts",
+    'import { z, forgeZod } from "./packages/zod.shared";',
+    "",
+    "const schema = forgeZod.object({ id: z.string() });",
+    "```",
+    "",
+    "## Validation",
+    "",
+    "- Import in `command` → passes",
+    "- Import in `client` → passes",
+    `- Compatible contexts: ${input.compatible.join(", ")}`,
+    "",
+  ].join("\n");
+}