forgeos 0.1.0-alpha.0

package/src/forge/compiler/classifier/contexts.ts

@@ -0,0 +1,188 @@
+import type { CapabilitySet } from "../types/capability.ts";
+import type { IntegrationRecipe } from "../types/integration.ts";
+import type { RuntimeContext } from "../types/runtime.ts";
+import {
+  DETERMINISTIC_CONTEXTS,
+  RUNTIME_CONTEXTS,
+} from "../types/runtime.ts";
+import type { PackageSignals } from "./signals.ts";
+import { packageRecipeFor } from "../recipes/registry.ts";
+
+export interface ContextVerdict {
+  ok: boolean;
+  reason: string;
+}
+
+export function hasUnknownCapability(caps: CapabilitySet): boolean {
+  return (
+    caps.network.status === "unknown" ||
+    caps.filesystem.status === "unknown" ||
+    caps.process.status === "unknown"
+  );
+}
+
+export function hasNetworkEgress(caps: CapabilitySet): boolean {
+  return caps.network.status === "required";
+}
+
+export function evaluateContext(
+  context: RuntimeContext,
+  recipe: IntegrationRecipe | undefined,
+  caps: CapabilitySet,
+  signals: PackageSignals,
+  packageName: string,
+): ContextVerdict {
+  const pkgRecipe = recipe ? packageRecipeFor(recipe, packageName) : undefined;
+  const denied = pkgRecipe?.contexts?.denied ?? recipe?.contexts.denied ?? [];
+  const allowed = pkgRecipe?.contexts?.allowed ?? recipe?.contexts.allowed ?? [];
+
+  if (denied.includes(context)) {
+    return { ok: false, reason: "denied by integration recipe" };
+  }
+
+  if (
+    (DETERMINISTIC_CONTEXTS as readonly RuntimeContext[]).includes(context) &&
+    hasUnknownCapability(caps)
+  ) {
+    return {
+      ok: false,
+      reason:
+        "capability is `unknown`; cannot prove determinism (static analysis cannot prove absence of network/fs)",
+    };
+  }
+
+  if (
+    (DETERMINISTIC_CONTEXTS as readonly RuntimeContext[]).includes(context) &&
+    hasNetworkEgress(caps)
+  ) {
+    return {
+      ok: false,
+      reason: "uses network; commands must be deterministic",
+    };
+  }
+
+  if (allowed.includes(context)) {
+    return { ok: true, reason: "allowed by integration recipe" };
+  }
+
+  if (recipe) {
+    return {
+      ok: false,
+      reason: "not in integration recipe allowed contexts",
+    };
+  }
+
+  return evaluateHeuristicContext(context, caps, signals);
+}
+
+function evaluateHeuristicContext(
+  context: RuntimeContext,
+  caps: CapabilitySet,
+  signals: PackageSignals,
+): ContextVerdict {
+  if (context === "shared") {
+    if (
+      hasNetworkEgress(caps) ||
+      caps.filesystem.status === "required" ||
+      caps.process.status === "required"
+    ) {
+      return {
+        ok: false,
+        reason: "shared context requires pure code without network/fs/process",
+      };
+    }
+    if (hasUnknownCapability(caps)) {
+      return {
+        ok: false,
+        reason: "insufficient signals to prove shared-safe purity",
+      };
+    }
+    return { ok: true, reason: "no network/fs/process signals detected" };
+  }
+
+  if (context === "client") {
+    if (caps.process.status === "required" || signals.usesNodeBuiltins) {
+      return { ok: false, reason: "node builtins/process not allowed in client" };
+    }
+    if (hasNetworkEgress(caps)) {
+      return { ok: true, reason: "client may perform network egress" };
+    }
+    if (hasUnknownCapability(caps)) {
+      return { ok: false, reason: "insufficient signals for client compatibility" };
+    }
+    return { ok: true, reason: "no server-only signals detected" };
+  }
+
+  if (
+    context === "server" ||
+    context === "action" ||
+    context === "workflow" ||
+    context === "endpoint"
+  ) {
+    return { ok: true, reason: "server-side context allows IO capabilities" };
+  }
+
+  if (
+    (DETERMINISTIC_CONTEXTS as readonly RuntimeContext[]).includes(context)
+  ) {
+    if (hasNetworkEgress(caps)) {
+      return { ok: false, reason: "uses network; deterministic contexts forbid egress" };
+    }
+    if (hasUnknownCapability(caps)) {
+      return {
+        ok: false,
+        reason: "unknown capability blocks deterministic context",
+      };
+    }
+    if (caps.filesystem.status === "required" || caps.process.status === "required") {
+      return {
+        ok: false,
+        reason: "filesystem/process access incompatible with deterministic context",
+      };
+    }
+    return { ok: true, reason: "no blocking capabilities for deterministic context" };
+  }
+
+  if (context === "edge") {
+    if (caps.process.status === "required") {
+      return { ok: false, reason: "process access incompatible with edge runtime" };
+    }
+    return { ok: true, reason: "edge-compatible by heuristic" };
+  }
+
+  if (context === "test" || context === "build") {
+    return { ok: true, reason: "test/build contexts allow broad compatibility" };
+  }
+
+  return {
+    ok: false,
+    reason: "insufficient signals; defaulting to incompatible",
+  };
+}
+
+export function partitionContexts(
+  recipe: IntegrationRecipe | undefined,
+  caps: CapabilitySet,
+  signals: PackageSignals,
+  packageName: string,
+): {
+  compatible: RuntimeContext[];
+  incompatible: RuntimeContext[];
+  rationale: Record<RuntimeContext, string>;
+} {
+  const compatible: RuntimeContext[] = [];
+  const incompatible: RuntimeContext[] = [];
+  const rationale = {} as Record<RuntimeContext, string>;
+
+  for (const context of RUNTIME_CONTEXTS) {
+    const verdict = evaluateContext(context, recipe, caps, signals, packageName);
+    rationale[context] = verdict.reason;
+    if (verdict.ok) {
+      compatible.push(context);
+    } else {
+      incompatible.push(context);
+    }
+  }
+
+  return { compatible, incompatible, rationale };
+}

package/src/forge/compiler/classifier/index.ts

@@ -0,0 +1,18 @@
+export type { RuntimeClassifier } from "./classify.ts";
+export { classify, createRuntimeClassifier } from "./classify.ts";
+export { detectCapabilities } from "./capabilities.ts";
+export { detectSecrets } from "./secrets.ts";
+export {
+  evaluateContext,
+  hasUnknownCapability,
+  hasNetworkEgress,
+  partitionContexts,
+} from "./contexts.ts";
+export type { ContextVerdict } from "./contexts.ts";
+export { gatherSignals } from "./signals.ts";
+export type { PackageSignals } from "./signals.ts";
+export {
+  buildRuntimeMatrix,
+  lookupMatrixEntry,
+} from "./runtime-matrix.ts";
+export type { ClassifiedPackage } from "./runtime-matrix.ts";

package/src/forge/compiler/classifier/runtime-matrix.ts

@@ -0,0 +1,45 @@
+import type { RuntimeClassification } from "../types/classification.ts";
+import type { PackageApi } from "../types/package-graph.ts";
+import type { IntegrationRecipe } from "../types/integration.ts";
+import type { RuntimeMatrix, RuntimeMatrixEntry } from "../types/runtime-matrix.ts";
+import { compareBytes } from "../primitives/compare.ts";
+import { RECIPE_SCHEMA_VERSION } from "../recipes/definitions.ts";
+import { resolveByPackageName } from "../recipes/registry.ts";
+
+export interface ClassifiedPackage {
+  api: PackageApi;
+  classification: RuntimeClassification;
+  recipe?: IntegrationRecipe;
+}
+
+export function buildRuntimeMatrix(
+  packages: ClassifiedPackage[],
+): RuntimeMatrix {
+  const entries: RuntimeMatrixEntry[] = packages.map(
+    ({ api, classification, recipe }) => {
+      const resolved = recipe ?? resolveByPackageName(api.name);
+      return {
+        alias: resolved?.alias ?? api.name,
+        packageName: api.name,
+        compatible: [...classification.compatible],
+        incompatible: [...classification.incompatible],
+        rationale: { ...classification.rationale },
+        perEntrypoint: [...classification.perEntrypoint],
+      };
+    },
+  );
+
+  entries.sort((a, b) => compareBytes(a.packageName, b.packageName));
+
+  return {
+    schemaVersion: RECIPE_SCHEMA_VERSION,
+    entries,
+  };
+}
+
+export function lookupMatrixEntry(
+  matrix: RuntimeMatrix,
+  packageName: string,
+): RuntimeMatrixEntry | undefined {
+  return matrix.entries.find((e) => e.packageName === packageName);
+}

package/src/forge/compiler/classifier/secrets.ts

@@ -0,0 +1,41 @@
+import type { SecretRequirement } from "../types/capability.ts";
+import type { IntegrationRecipe } from "../types/integration.ts";
+import type { PackageApi } from "../types/package-graph.ts";
+import { secret } from "../recipes/helpers.ts";
+import { gatherSignals } from "./signals.ts";
+
+export function detectSecrets(
+  api: PackageApi,
+  recipe?: IntegrationRecipe,
+): SecretRequirement[] {
+  const found = new Map<string, SecretRequirement>();
+
+  if (recipe) {
+    for (const s of recipe.secrets) {
+      found.set(s.envVar, { ...s });
+    }
+  }
+
+  const signals = gatherSignals(api);
+  for (const evidence of signals.envSecretEvidence) {
+    const envVar = evidence.replace(/^env:/, "");
+    if (!found.has(envVar)) {
+      found.set(envVar, secret(envVar, true, "signature"));
+    }
+  }
+
+  for (const ep of api.entrypoints) {
+    for (const exp of ep.exports) {
+      if (!exp.jsdoc) continue;
+      for (const tag of exp.jsdoc.tags) {
+        if (tag.tag !== "env" && tag.tag !== "secret") continue;
+        const name = tag.text.trim().split(/\s+/)[0];
+        if (name && /^[A-Z][A-Z0-9_]*$/.test(name) && !found.has(name)) {
+          found.set(name, secret(name, true, "jsdoc"));
+        }
+      }
+    }
+  }
+
+  return [...found.values()].sort((a, b) => a.envVar.localeCompare(b.envVar));
+}

package/src/forge/compiler/classifier/signals.ts

@@ -0,0 +1,129 @@
+import type { PackageApi } from "../types/package-graph.ts";
+
+export interface PackageSignals {
+  usesNodeBuiltins: boolean;
+  nodeBuiltins: string[];
+  usesNetwork: boolean;
+  networkEvidence: string[];
+  usesFilesystem: boolean;
+  filesystemEvidence: string[];
+  usesProcess: boolean;
+  processEvidence: string[];
+  usesEnvSecrets: boolean;
+  envSecretEvidence: string[];
+  usesNativeAddon: boolean;
+  nativeAddonEvidence: string[];
+}
+
+const NODE_BUILTIN_PATTERNS = [
+  /\bnode:/,
+  /\brequire\s*\(\s*["'](?:fs|child_process|net|http|https|dns|tls|os|crypto)["']/,
+  /\bfrom\s+["'](?:fs|child_process|net|http|https|dns|tls|os|crypto)["']/,
+];
+
+const NETWORK_PATTERNS = [
+  /\bfetch\s*\(/,
+  /\bXMLHttpRequest\b/,
+  /\bWebSocket\b/,
+  /\bhttp\.request\b/,
+  /\bhttps\.request\b/,
+  /\bnet\.connect\b/,
+  /\baxios\b/,
+  /\bgot\b/,
+  /\bnode-fetch\b/,
+  /\bRequestInit\b/,
+  /\bResponse\b/,
+];
+
+const FILESYSTEM_PATTERNS = [
+  /\bfs\./,
+  /\breadFileSync\b/,
+  /\bwriteFileSync\b/,
+  /\bcreateReadStream\b/,
+  /\bcreateWriteStream\b/,
+  /\bnode:fs\b/,
+];
+
+const PROCESS_PATTERNS = [
+  /\bchild_process\b/,
+  /\bspawn\s*\(/,
+  /\bexec\s*\(/,
+  /\bexecFile\s*\(/,
+  /\bprocess\.env\b/,
+  /\bnode:child_process\b/,
+];
+
+const ENV_SECRET_PATTERNS = [
+  /\bprocess\.env\.([A-Z][A-Z0-9_]*)/g,
+  /\bgetenv\s*\(\s*["']([A-Z][A-Z0-9_]*)["']/g,
+];
+
+const NATIVE_ADDON_PATTERNS = [
+  /\b\.node\b/,
+  /\bnative\b/,
+  /\bffi\b/,
+  /\bnode-gyp\b/,
+];
+
+function collectMatches(text: string, patterns: RegExp[]): string[] {
+  const evidence: string[] = [];
+  for (const pattern of patterns) {
+    if (pattern.test(text)) {
+      evidence.push(`pattern:${pattern.source}`);
+    }
+  }
+  return evidence;
+}
+
+function collectEnvVars(text: string): string[] {
+  const vars = new Set<string>();
+  for (const pattern of ENV_SECRET_PATTERNS) {
+    const globalPattern = new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`);
+    let match: RegExpExecArray | null;
+    while ((match = globalPattern.exec(text)) !== null) {
+      const name = match[1];
+      if (name) vars.add(name);
+    }
+  }
+  return [...vars];
+}
+
+export function gatherSignals(api: PackageApi): PackageSignals {
+  const texts: string[] = [];
+  for (const ep of api.entrypoints) {
+    for (const exp of ep.exports) {
+      texts.push(exp.signature);
+      if (exp.overloads) texts.push(...exp.overloads);
+      if (exp.declarations) texts.push(...exp.declarations);
+      if (exp.jsdoc) {
+        texts.push(exp.jsdoc.summary);
+        for (const tag of exp.jsdoc.tags) {
+          texts.push(`${tag.tag} ${tag.text}`);
+        }
+      }
+    }
+  }
+  const corpus = texts.join("\n");
+
+  const nodeBuiltins = collectMatches(corpus, NODE_BUILTIN_PATTERNS);
+  const networkEvidence = collectMatches(corpus, NETWORK_PATTERNS);
+  const filesystemEvidence = collectMatches(corpus, FILESYSTEM_PATTERNS);
+  const processEvidence = collectMatches(corpus, PROCESS_PATTERNS);
+  const nativeAddonEvidence = collectMatches(corpus, NATIVE_ADDON_PATTERNS);
+  const envVars = collectEnvVars(corpus);
+
+  return {
+    usesNodeBuiltins: nodeBuiltins.length > 0,
+    nodeBuiltins,
+    usesNetwork: networkEvidence.length > 0,
+    networkEvidence,
+    usesFilesystem: filesystemEvidence.length > 0,
+    filesystemEvidence,
+    usesProcess: processEvidence.length > 0,
+    processEvidence,
+    usesEnvSecrets: envVars.length > 0,
+    envSecretEvidence: envVars.map((v) => `env:${v}`),
+    usesNativeAddon: nativeAddonEvidence.length > 0,
+    nativeAddonEvidence,
+  };
+}

package/src/forge/compiler/client-sdk/build-manifest.ts

@@ -0,0 +1,151 @@
+import { hashStable } from "../primitives/hash.ts";
+import { canonicalJson } from "../primitives/serialize.ts";
+import { GENERATOR_VERSION } from "../emitter/constants.ts";
+import type { ApiSurface } from "../api-surface/build.ts";
+import type { ClassifiedPackage } from "../classifier/runtime-matrix.ts";
+import { resolveByPackageName } from "../recipes/registry.ts";
+
+export interface ClientManifest {
+  schemaVersion: string;
+  generatorVersion: string;
+  inputHash: string;
+  queries: string[];
+  commands: string[];
+  liveQueries: string[];
+  transport: {
+    queries: string;
+    commands: string;
+    liveQueries: string;
+  };
+  react: {
+    entrypoint: string;
+    hooks: string[];
+  };
+  excluded: {
+    actions: string[];
+    workflows: string[];
+    serverAdapters: string[];
+    serverPackages: string[];
+  };
+}
+
+export interface ReactManifest {
+  schemaVersion: string;
+  generatorVersion: string;
+  inputHash: string;
+  entrypoint: string;
+  hooks: string[];
+  queries: string[];
+  commands: string[];
+  liveQueries: string[];
+  clientSafe: true;
+}
+
+const SERVER_ADAPTER_SUFFIX = ".server.ts";
+
+function collectServerAdapters(classified: ClassifiedPackage[]): string[] {
+  const adapters = new Set<string>();
+  for (const pkg of classified) {
+    const recipe = pkg.recipe ?? resolveByPackageName(pkg.api.name);
+    if (!recipe?.adapters) {
+      continue;
+    }
+    for (const adapter of recipe.adapters) {
+      if (adapter.endsWith(SERVER_ADAPTER_SUFFIX) || adapter.includes(".server.")) {
+        adapters.add(adapter);
+      }
+    }
+  }
+  return [...adapters].sort();
+}
+
+function collectServerPackages(classified: ClassifiedPackage[]): string[] {
+  const packages = new Set<string>();
+  for (const pkg of classified) {
+    const recipe = pkg.recipe ?? resolveByPackageName(pkg.api.name);
+    if (!recipe) {
+      continue;
+    }
+    if (recipe.contexts.denied.includes("client")) {
+      packages.add(pkg.api.name);
+    }
+  }
+  return [...packages].sort();
+}
+
+export function buildClientManifest(
+  surface: ApiSurface,
+  classified: ClassifiedPackage[],
+): ClientManifest {
+  const queries = Object.keys(surface.queries).sort();
+  const commands = Object.keys(surface.commands).sort();
+  const liveQueries = Object.keys(surface.liveQueries).sort();
+  const actions = Object.keys(surface.actions).sort();
+  const workflows = Object.keys(surface.workflows).sort();
+
+  return {
+    schemaVersion: "1.0.0",
+    generatorVersion: GENERATOR_VERSION,
+    inputHash: hashStable(
+      canonicalJson({
+        apiInputHash: surface.inputHash,
+        queries,
+        commands,
+        liveQueries,
+      }),
+    ),
+    queries,
+    commands,
+    liveQueries,
+    transport: {
+      queries: "POST /queries/:name",
+      commands: "POST /commands/:name",
+      liveQueries: "GET /live/:name",
+    },
+    react: {
+      entrypoint: "src/forge/_generated/react.ts",
+      hooks: [
+        "ForgeProvider",
+        "useForgeClient",
+        "useAuth",
+        "useQuery",
+        "useCommand",
+        "useLiveQuery",
+      ],
+    },
+    excluded: {
+      actions,
+      workflows,
+      serverAdapters: collectServerAdapters(classified),
+      serverPackages: collectServerPackages(classified),
+    },
+  };
+}
+
+export function buildReactManifest(clientManifest: ClientManifest): ReactManifest {
+  const hooks = [
+    "ForgeProvider",
+    "useForgeClient",
+    "useAuth",
+    "useQuery",
+    "useCommand",
+    "useLiveQuery",
+  ];
+
+  return {
+    schemaVersion: "1.0.0",
+    generatorVersion: GENERATOR_VERSION,
+    inputHash: hashStable(
+      canonicalJson({
+        clientInputHash: clientManifest.inputHash,
+        hooks,
+      }),
+    ),
+    entrypoint: "src/forge/_generated/react.ts",
+    hooks,
+    queries: clientManifest.queries,
+    commands: clientManifest.commands,
+    liveQueries: clientManifest.liveQueries,
+    clientSafe: true,
+  };
+}