forgeos 0.1.0-alpha.0

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

@@ -0,0 +1,283 @@
+import { join } from "node:path";
+import { nodeFileSystem } from "../fs/index.ts";
+import type { AppGraph } from "../types/app-graph.ts";
+import type { EmitFile, EmitPlan } from "../types/emit.ts";
+import type { ForgeLock, ForgeLockEntry } from "../types/lock.ts";
+import type { IntegrationRecipe } from "../types/integration.ts";
+import type { RuntimeContext } from "../types/runtime.ts";
+import type { ClassifiedPackage } from "../classifier/runtime-matrix.ts";
+import { buildRuntimeMatrix } from "../classifier/runtime-matrix.ts";
+import { detectCapabilities } from "../classifier/capabilities.ts";
+import { detectSecrets } from "../classifier/secrets.ts";
+import { buildGuardArtifactEmitFiles } from "../guards/artifacts.ts";
+import {
+  FORGE_LOCK_PATH,
+  FORGE_LOCK_SCHEMA_VERSION,
+  GENERATED_DIR,
+  GENERATOR_VERSION,
+} from "../emitter/constants.ts";
+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,
+  parseAdapterContext,
+  renderAdapterModule,
+  renderIntegrationDoc,
+  renderIntegrationModule,
+  renderTestkitModule,
+} from "./render.ts";
+
+export interface IntegrationPlanInput {
+  alias: string;
+  recipe: IntegrationRecipe;
+  classified: ClassifiedPackage[];
+  allClassified: ClassifiedPackage[];
+  appGraph: AppGraph;
+  ctx: DiscoverContext;
+  existingLock: ForgeLock | null;
+}
+
+function makeEmitFile(path: string, content: string): EmitFile {
+  return {
+    path,
+    content,
+    contentHash: hashStable(content),
+  };
+}
+
+function primaryPackageName(recipe: IntegrationRecipe): string {
+  return recipe.packages[0]?.packageName ?? recipe.alias;
+}
+
+function mergedCompatibleContexts(
+  recipe: IntegrationRecipe,
+  classified: ClassifiedPackage[],
+): RuntimeContext[] {
+  const contexts = new Set<RuntimeContext>(recipe.contexts.allowed);
+  for (const pkg of recipe.packages) {
+    for (const ctx of pkg.contexts?.allowed ?? []) {
+      contexts.add(ctx);
+    }
+  }
+  for (const item of classified) {
+    for (const ctx of item.classification.compatible) {
+      contexts.add(ctx);
+    }
+  }
+  return [...contexts];
+}
+
+function shouldEmitAdapter(
+  adapterFilename: string,
+  compatible: RuntimeContext[],
+): boolean {
+  const context = parseAdapterContext(adapterFilename);
+  if (context === null) {
+    return true;
+  }
+  return compatible.includes(context);
+}
+
+function buildGeneratedPaths(
+  recipe: IntegrationRecipe,
+  compatible: RuntimeContext[],
+): string[] {
+  const paths: string[] = [];
+
+  for (const adapter of recipe.adapters) {
+    if (!shouldEmitAdapter(adapter, compatible)) {
+      continue;
+    }
+    paths.push(`${GENERATED_DIR}/packages/${adapter}`);
+  }
+
+  for (const testkit of recipe.testkits) {
+    paths.push(`${GENERATED_DIR}/testkits/${testkit}`);
+  }
+
+  for (const doc of recipe.docs) {
+    paths.push(`${GENERATED_DIR}/docs/${doc}`);
+  }
+
+  for (const integration of recipe.integrations ?? []) {
+    paths.push(`${GENERATED_DIR}/integrations/${integration}`);
+  }
+
+  paths.push(
+    `${GENERATED_DIR}/runtimeMatrix.ts`,
+    `${GENERATED_DIR}/runtimeMatrix.json`,
+    `${GENERATED_DIR}/importGuards.ts`,
+    `${GENERATED_DIR}/importGuards.json`,
+  );
+
+  return stableSortStrings(paths);
+}
+
+function buildLockEntry(
+  recipe: IntegrationRecipe,
+  classified: ClassifiedPackage[],
+  generatedFiles: string[],
+): ForgeLockEntry {
+  const primary = classified[0]!;
+  const capabilities = detectCapabilities(primary.api, recipe);
+  const secrets = detectSecrets(primary.api, recipe);
+
+  return {
+    name: recipe.alias,
+    version: primary.api.version,
+    recipeVersion: recipe.recipeVersion,
+    runtimeContexts: stableSortStrings([...primary.classification.compatible]) as ForgeLockEntry["runtimeContexts"],
+    capabilities: {
+      ...capabilities,
+      secrets,
+    },
+    secrets,
+    generatedFiles: stableSortStrings(generatedFiles),
+    contentChecksum: primary.api.contentChecksum,
+  };
+}
+
+function mergeLockPackages(
+  existing: ForgeLock | null,
+  newEntry: ForgeLockEntry,
+  ctx: DiscoverContext,
+): ForgeLock {
+  const existingPackages = existing?.packages ?? [];
+  const withoutAlias = existingPackages.filter(
+    (entry) => entry.name !== newEntry.name,
+  );
+
+  const recipeVersion = newEntry.recipeVersion ?? RECIPE_SCHEMA_VERSION;
+
+  return {
+    schemaVersion: FORGE_LOCK_SCHEMA_VERSION,
+    generatorVersion: GENERATOR_VERSION,
+    analyzerVersion: PACKAGE_ANALYZER_VERSION,
+    inputHash: ctx.inputFingerprint,
+    lockfileHash: ctx.lockfileHash,
+    packageManager: ctx.packageManager,
+    recipeVersion,
+    packages: [...withoutAlias, newEntry].sort((a, b) =>
+      a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+    ),
+  };
+}
+
+export function buildIntegrationEmitPlan(input: IntegrationPlanInput): EmitPlan {
+  const { recipe, classified, allClassified, appGraph, ctx } = input;
+  const primary = classified[0];
+  if (primary === undefined) {
+    throw new Error(`no classified packages for alias '${input.alias}'`);
+  }
+
+  const compatible = mergedCompatibleContexts(recipe, classified);
+  const incompatible = primary.classification.incompatible;
+  const secrets = detectSecrets(primary.api, recipe);
+  const packageNames = recipe.packages.map((pkg) => pkg.packageName);
+  const templateCtx = createRenderContext({
+    alias: recipe.alias,
+    recipe,
+    context: "server",
+    packageName: primaryPackageName(recipe),
+    packageNames,
+    secrets,
+    compatible,
+    incompatible,
+  });
+
+  const files: EmitFile[] = [];
+
+  for (const adapter of recipe.adapters) {
+    if (!shouldEmitAdapter(adapter, compatible)) {
+      continue;
+    }
+    const context = parseAdapterContext(adapter) ?? "server";
+    files.push(
+      makeEmitFile(
+        `${GENERATED_DIR}/packages/${adapter}`,
+        renderAdapterModule({
+          alias: recipe.alias,
+          recipe,
+          context,
+          packageName: primaryPackageName(recipe),
+          packageNames,
+          secrets,
+          compatible,
+          incompatible,
+        }),
+      ),
+    );
+  }
+
+  for (const integration of recipe.integrations ?? []) {
+    files.push(
+      makeEmitFile(
+        `${GENERATED_DIR}/integrations/${integration}`,
+        renderIntegrationModule(integration, templateCtx),
+      ),
+    );
+  }
+
+  for (const testkit of recipe.testkits) {
+    files.push(
+      makeEmitFile(
+        `${GENERATED_DIR}/testkits/${testkit}`,
+        renderTestkitModule(recipe.alias, primaryPackageName(recipe), templateCtx),
+      ),
+    );
+  }
+
+  for (const doc of recipe.docs) {
+    files.push(
+      makeEmitFile(
+        `${GENERATED_DIR}/docs/${doc}`,
+        renderIntegrationDoc({
+          alias: recipe.alias,
+          recipe,
+          packageNames,
+          secrets,
+          compatible,
+          incompatible,
+        }),
+      ),
+    );
+  }
+
+  const matrix = buildRuntimeMatrix(allClassified);
+  files.push(...buildGuardArtifactEmitFiles(matrix, appGraph.moduleGraph));
+
+  const generatedFiles = buildGeneratedPaths(recipe, compatible);
+  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,
+    lock,
+  };
+}
+
+export function loadExistingForgeLock(workspaceRoot: string): ForgeLock | null {
+  const absolute = join(workspaceRoot, FORGE_LOCK_PATH);
+  if (!nodeFileSystem.exists(absolute)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse((nodeFileSystem.readText(absolute) ?? "")) as ForgeLock;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,189 @@
+import type { SecretRequirement } from "../types/capability.ts";
+import type { IntegrationRecipe } from "../types/integration.ts";
+import type { RuntimeContext } from "../types/runtime.ts";
+import { RUNTIME_CONTEXTS } from "../types/runtime.ts";
+import { serializeCanonical } from "../primitives/serialize.ts";
+import {
+  buildTemplateInput,
+  renderQualityAdapter,
+  renderQualityDoc,
+  renderQualityIntegration,
+  renderQualityTestkit,
+} from "./templates/index.ts";
+import type { IntegrationTemplateInput } from "./templates/types.ts";
+
+function capitalizeSegment(value: string): string {
+  return value
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+export function parseAdapterContext(filename: string): RuntimeContext | null {
+  const base = filename.replace(/\.ts$/, "");
+  for (const context of RUNTIME_CONTEXTS) {
+    if (base.endsWith(`.${context}`)) {
+      return context;
+    }
+  }
+  return null;
+}
+
+function skeletonAdapter(input: IntegrationTemplateInput): string {
+  const secretNames = input.secrets.map((secret) => secret.envVar).sort();
+  const exportName = `forge${capitalizeSegment(input.alias)}${capitalizeSegment(input.context)}Adapter`;
+
+  return [
+    `/** Forge generated adapter for ${input.alias} (${input.context} context). */`,
+    `export const ${exportName} = ${serializeCanonical({
+      alias: input.alias,
+      packageName: input.packageName,
+      context: input.context,
+      secrets: secretNames,
+    }).trim()} as const;`,
+    "",
+  ].join("\n");
+}
+
+function skeletonTestkit(alias: string, packageName: string): string {
+  const exportName = `create${capitalizeSegment(alias)}Mock`;
+  return [
+    `/** Forge generated mock testkit for ${alias}. */`,
+    `export function ${exportName}() {`,
+    `  return ${serializeCanonical({
+      alias,
+      packageName,
+      mocked: true,
+    }).trim()} as const;`,
+    `}`,
+    "",
+  ].join("\n");
+}
+
+function skeletonDoc(input: IntegrationTemplateInput): string {
+  const secretNames = input.secrets.map((secret) => secret.envVar).sort();
+  const lines = [
+    `# ${input.alias} integration`,
+    "",
+    "Generated by Forge.",
+    "",
+    `Packages: ${input.packageNames.join(", ")}`,
+    "",
+    `Compatible contexts: ${input.compatible.join(", ")}`,
+    "",
+    `Incompatible contexts: ${input.incompatible.join(", ")}`,
+    "",
+  ];
+
+  if (secretNames.length > 0) {
+    lines.push(`Secrets (names only): ${secretNames.join(", ")}`, "");
+  }
+
+  return lines.join("\n");
+}
+
+export function createRenderContext(input: {
+  alias: string;
+  recipe: IntegrationRecipe;
+  context: RuntimeContext;
+  packageName: string;
+  packageNames: string[];
+  secrets: SecretRequirement[];
+  compatible: RuntimeContext[];
+  incompatible: RuntimeContext[];
+}): IntegrationTemplateInput {
+  return buildTemplateInput(input);
+}
+
+export function renderAdapterModule(input: {
+  alias: string;
+  recipe: IntegrationRecipe;
+  context: RuntimeContext;
+  packageName: string;
+  packageNames: string[];
+  secrets: SecretRequirement[];
+  compatible: RuntimeContext[];
+  incompatible: RuntimeContext[];
+}): string {
+  const ctx = createRenderContext(input);
+  const adapterFilename = `${input.alias}.${input.context}.ts`;
+  const quality = renderQualityAdapter(adapterFilename, ctx);
+  if (quality) {
+    return quality;
+  }
+
+  const resolvedName = input.recipe.adapters.find((name) =>
+    parseAdapterContext(name) === input.context,
+  );
+  if (resolvedName) {
+    const byName = renderQualityAdapter(resolvedName, ctx);
+    if (byName) {
+      return byName;
+    }
+  }
+
+  return skeletonAdapter(ctx);
+}
+
+export function renderIntegrationModule(
+  relativePath: string,
+  input: IntegrationTemplateInput,
+): string {
+  const quality = renderQualityIntegration(relativePath, input);
+  if (quality) {
+    return quality;
+  }
+
+  return [
+    `/** Forge generated integration module: ${relativePath} */`,
+    `export const forgeIntegration = ${serializeCanonical({
+      alias: input.alias,
+      module: relativePath,
+    }).trim()} as const;`,
+    "",
+  ].join("\n");
+}
+
+export function renderTestkitModule(
+  alias: string,
+  packageName: string,
+  input?: IntegrationTemplateInput,
+): string {
+  const filename = `${alias}.mock.ts`;
+  if (input) {
+    const quality = renderQualityTestkit(filename, input);
+    if (quality) {
+      return quality;
+    }
+  }
+  return skeletonTestkit(alias, packageName);
+}
+
+export function renderIntegrationDoc(input: {
+  alias: string;
+  recipe: IntegrationRecipe;
+  packageNames: string[];
+  secrets: SecretRequirement[];
+  compatible: RuntimeContext[];
+  incompatible: RuntimeContext[];
+}): string {
+  const ctx = buildTemplateInput({
+    alias: input.alias,
+    recipe: input.recipe,
+    context: "shared",
+    packageName: input.packageNames[0] ?? input.alias,
+    packageNames: input.packageNames,
+    secrets: input.secrets,
+    compatible: input.compatible,
+    incompatible: input.incompatible,
+  });
+
+  const docName = `${input.alias}.md`;
+  const quality = renderQualityDoc(docName, ctx);
+  if (quality) {
+    return quality;
+  }
+
+  return skeletonDoc(ctx);
+}

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

@@ -0,0 +1,52 @@
+import { join } from "node:path";
+import { nodeFileSystem } from "../fs/index.ts";
+import { detectPackageManager, getLockfileForPm } from "../package-manager/detect.ts";
+import { FORGE_LOCK_PATH } from "../emitter/constants.ts";
+import { manifestPath } from "../orchestrator/manifest.ts";
+
+export interface VersionControlledSnapshot {
+  files: Map<string, string | null>;
+}
+
+function readOptional(path: string): string | null {
+  return nodeFileSystem.readText(path);
+}
+
+export function snapshotVersionControlled(
+  workspaceRoot: string,
+): VersionControlledSnapshot {
+  const pm = detectPackageManager(workspaceRoot);
+  const lockfile = getLockfileForPm(pm);
+  const paths = [
+    "package.json",
+    lockfile,
+    FORGE_LOCK_PATH,
+    manifestPath(join(workspaceRoot, ".forge", "cache")).replace(
+      `${workspaceRoot.replace(/\\/g, "/")}/`,
+      "",
+    ),
+  ];
+
+  const files = new Map<string, string | null>();
+  for (const relative of paths) {
+    const normalized = relative.replace(/\\/g, "/");
+    files.set(normalized, readOptional(join(workspaceRoot, normalized)));
+  }
+
+  return { files };
+}
+
+export function restoreVersionControlledSnapshot(
+  workspaceRoot: string,
+  snapshot: VersionControlledSnapshot,
+): void {
+  for (const [relative, content] of snapshot.files) {
+    const absolute = join(workspaceRoot, relative);
+    if (content === null) {
+      nodeFileSystem.remove(absolute);
+      continue;
+    }
+
+    nodeFileSystem.writeText(absolute, content);
+  }
+}

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

@@ -0,0 +1,131 @@
+import type { IntegrationTemplateInput } from "./types.ts";
+
+export function renderAiServerAdapter(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated AI server adapter — use ctx.ai at runtime, not raw SDK. */",
+    'export type { AiContext, ForgeGenerateTextInput, ForgeGenerateTextResult } from "../aiContext.js";',
+    "",
+    "export const forgeAiRetainPrompts = false;",
+    "export const forgeAiRetainOutputs = false;",
+    "",
+  ].join("\n");
+}
+
+export function renderAiGenerations(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated AI generation telemetry helpers. */",
+    "",
+    "export const FORGE_AI_GENERATION_EVENTS = [",
+    '  "forge.ai.generation.started",',
+    '  "forge.ai.generation.completed",',
+    '  "forge.ai.generation.failed",',
+    '  "forge.ai.stream.started",',
+    '  "forge.ai.stream.completed",',
+    '  "forge.ai.usage",',
+    "] as const;",
+    "",
+    "export type ForgeAiGenerationEvent = (typeof FORGE_AI_GENERATION_EVENTS)[number];",
+    "",
+  ].join("\n");
+}
+
+export function renderAiTestkit(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated mock testkit for AI. */",
+    "",
+    "export interface MockAiQueuedResponse {",
+    "  text: string;",
+    "  usage?: { promptTokens?: number; completionTokens?: number; totalTokens?: number };",
+    "}",
+    "",
+    "export function createMockAiProvider() {",
+    "  const queue: MockAiQueuedResponse[] = [];",
+    "  return {",
+    "    enqueue(response: MockAiQueuedResponse) {",
+    "      queue.push(response);",
+    "    },",
+    "    dequeue(): MockAiQueuedResponse {",
+    "      return queue.shift() ?? { text: 'mock-ai-response', usage: { totalTokens: 30 } };",
+    "    },",
+    "    reset() {",
+    "      queue.length = 0;",
+    "    },",
+    "  };",
+    "}",
+    "",
+  ].join("\n");
+}
+
+export function renderAiTestkitLegacy(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated mock testkit for ai package alias. */",
+    'export { createMockAiProvider } from "./testkit.js";',
+    "",
+  ].join("\n");
+}
+
+export function renderAiEvals(_input: IntegrationTemplateInput): string {
+  return renderAiTestkit(_input);
+}
+
+export function renderAiOpenaiProvider(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated OpenAI provider wiring. */",
+    'import { createOpenAI } from "@ai-sdk/openai";',
+    'import type { SecretsContext } from "../secretsContext.js";',
+    "",
+    "export function createForgeOpenAiProvider(secrets: SecretsContext) {",
+    '  const apiKey = secrets.get("OPENAI_API_KEY");',
+    "  return createOpenAI({ apiKey });",
+    "}",
+    "",
+    'export const forgeOpenAiSecret = "OPENAI_API_KEY" as const;',
+    "",
+  ].join("\n");
+}
+
+export function renderAiAnthropicProvider(_input: IntegrationTemplateInput): string {
+  return [
+    "/** Forge generated Anthropic provider wiring. */",
+    'import { createAnthropic } from "@ai-sdk/anthropic";',
+    'import type { SecretsContext } from "../secretsContext.js";',
+    "",
+    "export function createForgeAnthropicProvider(secrets: SecretsContext) {",
+    '  const apiKey = secrets.get("ANTHROPIC_API_KEY");',
+    "  return createAnthropic({ apiKey });",
+    "}",
+    "",
+    'export const forgeAnthropicSecret = "ANTHROPIC_API_KEY" as const;',
+    "",
+  ].join("\n");
+}
+
+export function renderAiDoc(input: IntegrationTemplateInput): string {
+  return [
+    "# AI integration",
+    "",
+    "Generated by Forge (H12).",
+    "",
+    "Use `ctx.ai` inside action, workflow, endpoint, and server contexts.",
+    "Never import Vercel AI SDK directly from app code.",
+    "",
+    "## Runtime API",
+    "",
+    "- `ctx.ai.generateText({ provider, model, prompt, purpose })`",
+    "- `ctx.ai.streamText({ provider, model, prompt })`",
+    "- `ctx.ai.generateStructured({ provider, model, prompt, schema })`",
+    "",
+    "## Mock mode",
+    "",
+    "- `forge dev --mock-ai` or `FORGE_MOCK_AI=1`",
+    "- `forge ai test --mock`",
+    "",
+    "## Validation",
+    "",
+    "- AI in `action` / `workflow` → passes",
+    "- AI in `command` / `query` / `liveQuery` → `FORGE_AI_FORBIDDEN_CONTEXT`",
+    "",
+    `Incompatible contexts: ${input.incompatible.join(", ")}`,
+    "",
+  ].join("\n");
+}

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

@@ -0,0 +1,8 @@
+export type { IntegrationTemplateInput } from "./types.ts";
+export {
+  buildTemplateInput,
+  renderQualityAdapter,
+  renderQualityDoc,
+  renderQualityIntegration,
+  renderQualityTestkit,
+} from "./render.ts";