forgeos 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/forge/compiler/external-manifest/validate.ts

@@ -0,0 +1,373 @@
+import { createDiagnostic } from "../diagnostics/create.ts";
+import type { Diagnostic } from "../types/diagnostic.ts";
+import {
+  FORGE_EXTERNAL_MANIFEST_PROTOCOL_VERSION,
+  type ForgeExternalEntryKind,
+  type ForgeExternalEntryRisk,
+  type ForgeExternalManifest,
+  type ForgeExternalManifestEntry,
+  type ForgeExternalManifestRegistryFile,
+  type ForgeExternalTransportKind,
+  type ForgeExternalTransactionMode,
+} from "./types.ts";
+
+const TRANSPORTS: ForgeExternalTransportKind[] = ["http", "grpc", "stdio"];
+const ENTRY_KINDS: ForgeExternalEntryKind[] = ["command", "query"];
+const RISKS: ForgeExternalEntryRisk[] = ["read", "write", "destructive", "external"];
+const TRANSACTIONS: ForgeExternalTransactionMode[] = [
+  "read-only",
+  "external-managed",
+  "forge-managed",
+  "saga",
+];
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function stringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function commandArgsArray(value: unknown): value is string[] {
+  return Array.isArray(value) &&
+    value.length > 0 &&
+    typeof value[0] === "string" &&
+    value[0].length > 0 &&
+    value.every((item) => typeof item === "string");
+}
+
+function externalDiagnostic(
+  severity: Diagnostic["severity"],
+  code: string,
+  message: string,
+  file?: string,
+  fixHint?: string,
+): Diagnostic {
+  return createDiagnostic({
+    severity,
+    code,
+    message,
+    ...(file ? { file } : {}),
+    ...(fixHint ? { fixHint } : {}),
+    docs: ["docs/forge-protocol.md", "schemas/forge-manifest.schema.json"],
+  });
+}
+
+function validateEntry(
+  entry: unknown,
+  index: number,
+  serviceName: string,
+  diagnostics: Diagnostic[],
+  file?: string,
+): ForgeExternalManifestEntry | null {
+  if (!isObject(entry)) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_ENTRY_OBJECT",
+      `external manifest entry at index ${index} must be an object`,
+      file,
+    ));
+    return null;
+  }
+
+  const name = entry.name;
+  const kind = entry.kind;
+  if (!isString(name)) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_ENTRY_NAME",
+      `external manifest entry at index ${index} must have a non-empty name`,
+      file,
+    ));
+  }
+  if (!ENTRY_KINDS.includes(kind as ForgeExternalEntryKind)) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_ENTRY_KIND",
+      `external manifest entry '${String(name || index)}' must be kind command or query`,
+      file,
+    ));
+  }
+  if (entry.effects !== undefined && !stringArray(entry.effects)) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_ENTRY_EFFECTS",
+      `external manifest entry '${String(name || index)}' effects must be a string array`,
+      file,
+    ));
+  }
+  if (entry.risk !== undefined && !RISKS.includes(entry.risk as ForgeExternalEntryRisk)) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_ENTRY_RISK",
+      `external manifest entry '${String(name || index)}' has unsupported risk '${String(entry.risk)}'`,
+      file,
+    ));
+  }
+  if (
+    entry.transaction !== undefined &&
+    !TRANSACTIONS.includes(entry.transaction as ForgeExternalTransactionMode)
+  ) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_ENTRY_TRANSACTION",
+      `external manifest entry '${String(name || index)}' has unsupported transaction mode '${String(entry.transaction)}'`,
+      file,
+    ));
+  }
+  if (
+    entry.kind === "query" &&
+    entry.transaction !== undefined &&
+    entry.transaction !== "read-only"
+  ) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_QUERY_TRANSACTION",
+      `external query '${serviceName}.${String(name)}' must use transaction read-only when transaction is declared`,
+      file,
+      "Declare command for writes, or set transaction to read-only for external queries.",
+    ));
+  }
+  if (entry.kind === "query" && entry.risk !== undefined && entry.risk !== "read") {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_QUERY_RISK",
+      `external query '${serviceName}.${String(name)}' must use risk read when risk is declared`,
+      file,
+    ));
+  }
+
+  if (!isString(name) || !ENTRY_KINDS.includes(kind as ForgeExternalEntryKind)) {
+    return null;
+  }
+
+  return {
+    name,
+    kind: kind as ForgeExternalEntryKind,
+    ...(isString(entry.description) ? { description: entry.description } : {}),
+    ...(isString(entry.path) ? { path: entry.path } : {}),
+    ...(entry.method === "GET" || entry.method === "POST" ? { method: entry.method } : {}),
+    ...(entry.inputSchema !== undefined ? { inputSchema: entry.inputSchema } : {}),
+    ...(entry.outputSchema !== undefined ? { outputSchema: entry.outputSchema } : {}),
+    ...(isString(entry.policy) ? { policy: entry.policy } : {}),
+    ...(typeof entry.tenantScoped === "boolean" ? { tenantScoped: entry.tenantScoped } : {}),
+    ...(TRANSACTIONS.includes(entry.transaction as ForgeExternalTransactionMode)
+      ? { transaction: entry.transaction as ForgeExternalTransactionMode }
+      : {}),
+    ...(RISKS.includes(entry.risk as ForgeExternalEntryRisk)
+      ? { risk: entry.risk as ForgeExternalEntryRisk }
+      : {}),
+    ...(typeof entry.needsApproval === "boolean" ? { needsApproval: entry.needsApproval } : {}),
+    ...(stringArray(entry.effects) ? { effects: entry.effects } : {}),
+  };
+}
+
+export function validateExternalManifest(
+  value: unknown,
+  options: { file?: string } = {},
+): { manifest: ForgeExternalManifest | null; diagnostics: Diagnostic[] } {
+  const diagnostics: Diagnostic[] = [];
+  if (!isObject(value)) {
+    return {
+      manifest: null,
+      diagnostics: [
+        externalDiagnostic(
+          "error",
+          "FORGE_EXTERNAL_MANIFEST_OBJECT",
+          "forge external manifest must be a JSON object",
+          options.file,
+        ),
+      ],
+    };
+  }
+
+  if (value.forgeProtocol !== FORGE_EXTERNAL_MANIFEST_PROTOCOL_VERSION) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_PROTOCOL_VERSION",
+      `forgeProtocol must be '${FORGE_EXTERNAL_MANIFEST_PROTOCOL_VERSION}'`,
+      options.file,
+    ));
+  }
+  if (!isString(value.language)) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_LANGUAGE",
+      "external manifest must declare a non-empty language",
+      options.file,
+    ));
+  }
+  if (!isObject(value.service)) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_SERVICE",
+      "external manifest must declare a service object",
+      options.file,
+    ));
+  }
+  if (!Array.isArray(value.entries)) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_ENTRIES",
+      "external manifest must declare an entries array",
+      options.file,
+    ));
+  }
+
+  const service = isObject(value.service) ? value.service : {};
+  if (!isString(service.name)) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_SERVICE_NAME",
+      "external service must have a non-empty name",
+      options.file,
+    ));
+  }
+  if (!TRANSPORTS.includes(service.transport as ForgeExternalTransportKind)) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_SERVICE_TRANSPORT",
+      `external service '${String(service.name || "unknown")}' must use transport http, grpc, or stdio`,
+      options.file,
+    ));
+  }
+  if (service.transport === "http" && !isString(service.baseUrl)) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_SERVICE_BASE_URL",
+      `external service '${String(service.name || "unknown")}' uses http transport and must declare a non-empty baseUrl`,
+      options.file,
+      "Set service.baseUrl to the external runtime base URL.",
+    ));
+  }
+  const hasCommand = isString(service.command);
+  const hasCommandArgs = commandArgsArray(service.commandArgs);
+  if (service.commandArgs !== undefined && !hasCommandArgs) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_SERVICE_COMMAND_ARGS",
+      `external service '${String(service.name || "unknown")}' commandArgs must be a non-empty string array`,
+      options.file,
+      "Set service.commandArgs to an array whose first item is the executable.",
+    ));
+  }
+  if (service.transport === "stdio" && !hasCommand && !hasCommandArgs) {
+    diagnostics.push(externalDiagnostic(
+      "error",
+      "FORGE_EXTERNAL_SERVICE_COMMAND",
+      `external service '${String(service.name || "unknown")}' uses stdio transport and must declare a non-empty command or commandArgs`,
+      options.file,
+      "Set service.command to a command line string or service.commandArgs to a structured executable/args array.",
+    ));
+  }
+
+  const entries = Array.isArray(value.entries)
+    ? value.entries
+      .map((entry, index) => validateEntry(entry, index, String(service.name || "unknown"), diagnostics, options.file))
+      .filter((entry): entry is ForgeExternalManifestEntry => entry !== null)
+    : [];
+  const seen = new Set<string>();
+  for (const entry of entries) {
+    const key = `${entry.kind}:${entry.name}`;
+    if (seen.has(key)) {
+      diagnostics.push(externalDiagnostic(
+        "error",
+        "FORGE_EXTERNAL_ENTRY_DUPLICATE",
+        `external service '${String(service.name)}' declares duplicate ${entry.kind} '${entry.name}'`,
+        options.file,
+      ));
+    }
+    seen.add(key);
+  }
+
+  if (diagnostics.some((diagnostic) => diagnostic.severity === "error")) {
+    return { manifest: null, diagnostics };
+  }
+
+  return {
+    manifest: {
+      forgeProtocol: FORGE_EXTERNAL_MANIFEST_PROTOCOL_VERSION,
+      language: value.language as ForgeExternalManifest["language"],
+      ...(isString(value.framework) ? { framework: value.framework } : {}),
+      service: {
+        name: service.name as string,
+        transport: service.transport as ForgeExternalTransportKind,
+        ...(isString(service.baseUrl) ? { baseUrl: service.baseUrl } : {}),
+        ...(hasCommand ? { command: service.command as string } : {}),
+        ...(hasCommandArgs ? { commandArgs: service.commandArgs as string[] } : {}),
+        ...(isString(service.health) ? { health: service.health } : {}),
+      },
+      entries,
+      ...(isObject(value.schemas) ? { schemas: value.schemas } : {}),
+    },
+    diagnostics,
+  };
+}
+
+export function validateExternalManifestRegistry(
+  value: unknown,
+  options: { file?: string } = {},
+): { registry: ForgeExternalManifestRegistryFile | null; diagnostics: Diagnostic[] } {
+  if (!isObject(value)) {
+    return {
+      registry: null,
+      diagnostics: [
+        externalDiagnostic(
+          "error",
+          "FORGE_EXTERNAL_REGISTRY_OBJECT",
+          "external manifest registry must be a JSON object",
+          options.file,
+        ),
+      ],
+    };
+  }
+  if (value.schemaVersion !== "0.1.0") {
+    return {
+      registry: null,
+      diagnostics: [
+        externalDiagnostic(
+          "error",
+          "FORGE_EXTERNAL_REGISTRY_VERSION",
+          "external manifest registry schemaVersion must be '0.1.0'",
+          options.file,
+        ),
+      ],
+    };
+  }
+  if (!Array.isArray(value.manifests)) {
+    return {
+      registry: null,
+      diagnostics: [
+        externalDiagnostic(
+          "error",
+          "FORGE_EXTERNAL_REGISTRY_MANIFESTS",
+          "external manifest registry must include a manifests array",
+          options.file,
+        ),
+      ],
+    };
+  }
+
+  const diagnostics: Diagnostic[] = [];
+  const manifests: ForgeExternalManifest[] = [];
+  for (const [index, manifestValue] of value.manifests.entries()) {
+    const result = validateExternalManifest(manifestValue, {
+      file: options.file ? `${options.file}#manifests/${index}` : undefined,
+    });
+    diagnostics.push(...result.diagnostics);
+    if (result.manifest) {
+      manifests.push(result.manifest);
+    }
+  }
+  return {
+    registry: diagnostics.some((diagnostic) => diagnostic.severity === "error")
+      ? null
+      : { schemaVersion: "0.1.0", manifests },
+    diagnostics,
+  };
+}

package/src/forge/compiler/frontend-graph/build.ts

@@ -13,6 +13,7 @@ import { createDiagnostic } from "../diagnostics/create.ts";
 
 const WEB_ROOT = "web";
 const API_URL_ENV = "NEXT_PUBLIC_FORGE_URL";
+const NUXT_API_URL_ENV = "NUXT_PUBLIC_FORGE_URL";
 const VITE_API_URL_ENV = "VITE_FORGE_URL";
 
 function toPosix(path: string): string {
@@ -43,7 +44,7 @@ function walkFiles(root: string): string[] {
     for (const entry of nodeFileSystem.readDir(dir)) {
       const absolute = join(dir, entry.name);
       if (entry.isDirectory) {
-        if (entry.name === "node_modules" || entry.name === ".next" || entry.name === "dist") {
+        if (entry.name === "node_modules" || entry.name === ".next" || entry.name === ".nuxt" || entry.name === "dist" || entry.name === ".output") {
           continue;
         }
         walk(absolute);
@@ -71,6 +72,14 @@ function detectFramework(webRoot: string): FrontendGraph["framework"] {
   if (deps.next || nodeFileSystem.exists(join(webRoot, "next.config.ts"))) {
     return "next";
   }
+  if (
+    deps.nuxt ||
+    nodeFileSystem.exists(join(webRoot, "nuxt.config.ts")) ||
+    nodeFileSystem.exists(join(webRoot, "nuxt.config.js")) ||
+    nodeFileSystem.exists(join(webRoot, "nuxt.config.mjs"))
+  ) {
+    return "nuxt";
+  }
   if (deps.vite || nodeFileSystem.exists(join(webRoot, "vite.config.ts"))) {
     return "vite";
   }
@@ -105,6 +114,27 @@ function routePathForFile(webRoot: string, file: string): string | null {
   if (rel === "app/page.tsx" || rel === "app/page.ts" || rel === "app/page.jsx" || rel === "app/page.js") {
     return "/";
   }
+  if (rel === "app.vue") {
+    return "/";
+  }
+  if (rel === "pages/index.vue") {
+    return "/";
+  }
+  const vueRoute = rel.match(/^pages\/(.+)\.vue$/);
+  if (vueRoute) {
+    const route = vueRoute[1]
+      .split("/")
+      .map((segment) => {
+        if (segment === "index") {
+          return "";
+        }
+        const dynamic = segment.match(/^\[([A-Za-z0-9_]+)\]$/);
+        return dynamic ? `:${dynamic[1]}` : segment;
+      })
+      .filter(Boolean)
+      .join("/");
+    return `/${route}`;
+  }
   const match = rel.match(/^app\/(.+)\/page\.(tsx|ts|jsx|js)$/);
   if (match) {
     const route = match[1]
@@ -117,7 +147,7 @@ function routePathForFile(webRoot: string, file: string): string | null {
 }
 
 function componentNameForFile(file: string): string {
-  return basename(file).replace(/\.(tsx|ts|jsx|js)$/, "");
+  return basename(file).replace(/\.(tsx|ts|jsx|js|vue)$/, "");
 }
 
 function componentNameForText(file: string, text: string): string {
@@ -134,6 +164,14 @@ function componentNameForText(file: string, text: string): string {
 
 function isComponentFile(webRoot: string, file: string, text: string): boolean {
   const rel = toPosix(relative(webRoot, file));
+  if (file.endsWith(".vue")) {
+    return (
+      rel === "app.vue" ||
+      rel.startsWith("components/") ||
+      rel.startsWith("src/components/") ||
+      rel.startsWith("pages/")
+    );
+  }
   if (!/\.(tsx|jsx)$/.test(file)) {
     return false;
   }
@@ -206,6 +244,9 @@ function devCommandFor(webRoot: string, framework: FrontendGraph["framework"]):
 }
 
 function apiEnvFor(framework: FrontendGraph["framework"]): string {
+  if (framework === "nuxt") {
+    return NUXT_API_URL_ENV;
+  }
   return framework === "vite" || framework === "static" ? VITE_API_URL_ENV : API_URL_ENV;
 }
 
@@ -224,7 +265,7 @@ function stringProp(text: string, prop: "userId" | "tenantId" | "role"): string
 }
 
 function defaultWebPort(framework: FrontendGraph["framework"]): number {
-  return framework === "next" ? 3000 : 5173;
+  return framework === "next" || framework === "nuxt" ? 3000 : 5173;
 }
 
 function componentNamesInText(text: string, components: FrontendComponentInfo[]): string[] {
@@ -299,7 +340,7 @@ export function buildFrontendGraph(input: {
   const defaultApiUrl = `http://127.0.0.1:${input.apiPort ?? 3765}`;
   const devUrl = `http://127.0.0.1:${input.webPort ?? defaultWebPort(framework)}`;
   const files = walkFiles(webRoot);
-  const sourceFiles = files.filter((file) => /\.(tsx|ts|jsx|js|html)$/.test(file));
+  const sourceFiles = files.filter((file) => /\.(tsx|ts|jsx|js|vue|html)$/.test(file));
   const routes: FrontendRouteInfo[] = [];
   const components: FrontendComponentInfo[] = [];
   const providers: FrontendProviderInfo[] = [];
@@ -314,7 +355,9 @@ export function buildFrontendGraph(input: {
       rel === "web/lib/forge.ts" ||
       rel === "web/lib/forge.tsx" ||
       rel === "web/src/lib/forge.ts" ||
-      rel === "web/src/lib/forge.tsx";
+      rel === "web/src/lib/forge.tsx" ||
+      rel === "web/composables/forge.ts" ||
+      rel === "web/plugins/forge.ts";
     textByRel.set(rel, text);
     const uses = detectUses(text, input.clientManifest);
     if (isComponentFile(webRoot, file, text)) {
@@ -335,11 +378,32 @@ export function buildFrontendGraph(input: {
         ...(devAuth && stringProp(text, "role") ? { devAuthRole: stringProp(text, "role") } : {}),
       });
     }
+    if (
+      text.includes("provideForge({") ||
+      text.includes("vueApp.use(ForgeVuePlugin") ||
+      text.includes("app.use(ForgeVuePlugin")
+    ) {
+      const devAuth =
+        text.includes("devAuth") ||
+        (text.includes("userId") && text.includes("tenantId") && text.includes("role"));
+      providers.push({
+        name: framework === "nuxt" ? "ForgeNuxtPlugin" : "ForgeVueProvider",
+        file: rel,
+        ...(text.includes(NUXT_API_URL_ENV) ? { apiUrlEnv: NUXT_API_URL_ENV } : {}),
+        ...(text.includes(VITE_API_URL_ENV) ? { apiUrlEnv: VITE_API_URL_ENV } : {}),
+        devAuth,
+        ...(devAuth && stringProp(text, "userId") ? { devAuthUserId: stringProp(text, "userId") } : {}),
+        ...(devAuth && stringProp(text, "tenantId") ? { devAuthTenantId: stringProp(text, "tenantId") } : {}),
+        ...(devAuth && stringProp(text, "role") ? { devAuthRole: stringProp(text, "role") } : {}),
+      });
+    }
     if (
       rel === "web/lib/forge.ts" ||
       rel === "web/lib/forge.tsx" ||
       rel === "web/src/lib/forge.ts" ||
-      rel === "web/src/lib/forge.tsx"
+      rel === "web/src/lib/forge.tsx" ||
+      rel === "web/composables/forge.ts" ||
+      rel === "web/plugins/forge.ts"
     ) {
       bridgeFiles.push(rel);
     }
@@ -350,7 +414,7 @@ export function buildFrontendGraph(input: {
         message: "frontend imports generated files directly; prefer the local web/lib/forge bridge",
         file: rel,
         fixHint: "Import generated client APIs through web/lib/forge.ts so agents and humans have one stable frontend bridge.",
-        suggestedCommands: ["forge inspect frontend --json", "forge make ui --framework vite --dry-run --json"],
+        suggestedCommands: ["forge inspect frontend --json", `forge make ui --framework ${framework === "nuxt" ? "nuxt" : "vite"} --dry-run --json`],
         docs: ["src/forge/_generated/frontendGraph.json", "src/forge/_generated/appMap.md"],
       }));
     }
@@ -401,9 +465,13 @@ export function buildFrontendGraph(input: {
     diagnostics.push(createDiagnostic({
       severity: "warning",
       code: "FORGE_FRONTEND_PROVIDER_MISSING",
-      message: "web app does not expose a ForgeProvider; generated hooks may not be wired",
-      fixHint: "Mount ForgeProvider once in the web app root/provider layer and pass devAuth for local development.",
-      suggestedCommands: ["forge inspect frontend --json", "forge make ui --framework vite --dry-run --json"],
+      message: framework === "nuxt"
+        ? "Nuxt app does not expose a Forge plugin; generated composables may not be wired"
+        : "web app does not expose a ForgeProvider; generated hooks may not be wired",
+      fixHint: framework === "nuxt"
+        ? "Create web/plugins/forge.ts and call provideForge with runtimeConfig.public.forgeUrl and devAuth for local development."
+        : "Mount ForgeProvider once in the web app root/provider layer and pass devAuth for local development.",
+      suggestedCommands: ["forge inspect frontend --json", `forge make ui --framework ${framework === "nuxt" ? "nuxt" : "vite"} --dry-run --json`],
       docs: ["src/forge/_generated/frontendGraph.json", "AGENTS.md"],
     }));
   }
@@ -411,9 +479,13 @@ export function buildFrontendGraph(input: {
     diagnostics.push(createDiagnostic({
       severity: "warning",
       code: "FORGE_FRONTEND_BRIDGE_MISSING",
-      message: "web/**/lib/forge.ts bridge is missing; agents may use fragile generated import paths",
-      fixHint: "Create web/lib/forge.ts or web/src/lib/forge.ts and re-export api, client, ForgeProvider, and generated hooks from src/forge/_generated.",
-      suggestedCommands: ["forge make ui --framework vite --dry-run --json", "forge generate"],
+      message: framework === "nuxt"
+        ? "web/composables/forge.ts bridge is missing; agents may use fragile generated import paths"
+        : "web/**/lib/forge.ts bridge is missing; agents may use fragile generated import paths",
+      fixHint: framework === "nuxt"
+        ? "Create web/composables/forge.ts and re-export api plus generated Forge Vue composables from src/forge/_generated."
+        : "Create web/lib/forge.ts or web/src/lib/forge.ts and re-export api, client, ForgeProvider, and generated hooks from src/forge/_generated.",
+      suggestedCommands: [`forge make ui --framework ${framework === "nuxt" ? "nuxt" : "vite"} --dry-run --json`, "forge generate"],
       docs: ["src/forge/_generated/frontendGraph.json", "AGENTS.md"],
     }));
   }