forgeos 0.1.0-alpha.13 → 0.1.0-alpha.14

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.13 input=3f5e1915da753f2190d1baa076ce591a66915ab697552bf8768f4c1c6850b945 content=1611635edf59c122b013ba76c85bd333ab3b30b289aaea04a9074f9438782a50
+// @forge-generated generator=0.1.0-alpha.14 input=675f1561e5787d5107285fb1d3627501242d220f0be03e89adf99930e6c23c69 content=143ee5e2d6fee031a4952f21ee3cc8f1e5678fd11ea673c2cb79196c251c32b6
 # AGENTS.md
 
 <!-- forge-generated:start -->
@@ -142,9 +142,9 @@ Agents:
 
 Rules:
 
-- Use the local `web/**/lib/forge.ts` bridge to generated hooks.
-- Mount `<ForgeProvider devAuth>` in local development.
-- Use `useQuery`, `useCommand`, and `useLiveQuery` instead of raw Forge endpoint fetches in React components.
+- Use the local `web/**/lib/forge.ts` or Nuxt `web/composables/forge.ts` bridge to generated bindings.
+- Mount `<ForgeProvider devAuth>` or install the Nuxt Forge plugin in local development.
+- Use `useQuery`/`useCommand`/`useLiveQuery` or `useForgeQuery`/`useForgeCommand`/`useForgeLiveQuery` instead of raw Forge endpoint fetches in components.
 - Keep frontend routes reflected in `src/forge/_generated/frontendGraph.json`.
 
 ## Common tasks
@@ -177,6 +177,7 @@ Use:
 forge make resource <name> --fields title:text,status:enum(open,closed) --dry-run --json
 forge make resource <name> --fields title:text,status:enum(open,closed) --with-ui --yes
 forge make ui --framework vite --dry-run --json
+forge make ui --framework nuxt --dry-run --json
 forge make ai-chat support --dry-run --json
 ```
 
@@ -193,7 +194,7 @@ forge inspect frontend --json
 forge inspect capabilities --json
 ```
 
-`forge dev` starts the API runtime and web app together when `web/` exists. `forge dev --once --json` reports routes, components, `ForgeProvider`, bridge files, generated client bindings, direct runtime fetch warnings, capability-map parity warnings, and fix hints.
+`forge dev` starts the API runtime and web app together when `web/` exists. `forge dev --once --json` reports routes, components, providers/plugins, bridge files, generated client bindings, direct runtime fetch warnings, capability-map parity warnings, and fix hints.
 
 ### Apply a feature blueprint
 

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # forgeos
 
+## 0.1.0-alpha.14
+
+Java and Nuxt/Vue support:
+
+- Added the Java external runtime adapter with a lightweight JDK HTTP bridge, manifest export, typed handlers, tenant/auth context, diagnostics, and command/query registration.
+- Added a Spring Boot starter for Java services that want annotation-based Forge command/query exposure.
+- Added the `java-billing` conformance example and packaged it with the public alpha line.
+- Added generated Vue bindings and a `forgeos/vue` export with `provideForge`, `ForgeVuePlugin`, `useForgeQuery`, `useForgeCommand`, and `useForgeLiveQuery`.
+- Added Nuxt UI scaffolding through `forge make ui --framework nuxt`, including plugin wiring, composable bridge files, and frontend graph detection for `.vue` routes/components.
+- Updated docs, agent adapter guidance, generated manifests, and focused Java/Vue/Nuxt tests.
+- Kept H44-H48 memory, sessions, timeline, grouping, and MCP surfaces intact while merging the Java/Nuxt work into `main`.
+
 ## 0.1.0-alpha.13
 
 Agent Memory Bridge:

package/adapters/java/README.md

@@ -0,0 +1,68 @@
+# Forge Java Adapter
+
+`adapters/java` is the minimal Java SDK for external Forge runtimes. It mirrors
+the Go adapter: register commands and queries, emit a `forge.manifest.json`, and
+serve Forge-compatible HTTP envelopes.
+
+```java
+ForgeRegistry app = Forge.service("billing",
+    Forge.framework("java/jdk-http"),
+    Forge.baseUrl("http://127.0.0.1:8788"));
+
+app.command("createInvoice",
+    Forge.handle(CreateInvoiceInput.class, Billing::createInvoice),
+    Forge.policy("billing.manage"),
+    Forge.tenantScoped(true),
+    Forge.needsApproval(true),
+    Forge.inputSchema(Schemas.object(Map.of("title", Schemas.string()), "title")));
+
+app.query("listInvoices",
+    Forge.handle(EmptyInput.class, Billing::listInvoices),
+    Forge.policy("billing.manage"),
+    Forge.tenantScoped(true),
+    Forge.readOnly());
+
+ForgeHttpHandler.listen(app, "127.0.0.1", 8788);
+```
+
+The HTTP handler exposes:
+
+```text
+GET  /health
+GET  /manifest?baseUrl=http://127.0.0.1:8788
+POST /commands/:name
+POST /queries/:name
+```
+
+The handler accepts Forge runtime envelopes and returns Forge response
+envelopes:
+
+```json
+{
+  "args": { "title": "Invoice" },
+  "auth": { "kind": "user", "userId": "u1", "tenantId": "t1", "role": "admin" },
+  "forge": { "service": "billing", "entry": "createInvoice", "kind": "command", "traceId": "trace_..." }
+}
+```
+
+Build locally:
+
+```bash
+mvn -f adapters/java/pom.xml install
+mvn -f examples/java-billing/pom.xml package
+```
+
+Emit and import a manifest:
+
+```bash
+java -jar examples/java-billing/target/java-billing-0.1.0-alpha.11-all.jar --manifest --base-url http://127.0.0.1:8788 > java-billing.manifest.json
+forge manifest import java-billing.manifest.json --json
+forge generate
+```
+
+Invoke through Forge:
+
+```bash
+forge run billing.createInvoice --args '{"title":"Invoice"}' --role admin --tenant-id tenant-a
+forge query billing.listInvoices --args '{}' --role admin --tenant-id tenant-a
+```

package/adapters/java/pom.xml

@@ -0,0 +1,34 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>dev.forgeos</groupId>
+  <artifactId>forge-java-adapter</artifactId>
+  <version>0.1.0-alpha.11</version>
+  <name>Forge Java Adapter</name>
+  <description>Minimal Java SDK for Forge external runtimes.</description>
+  <url>https://forgeos.dev</url>
+
+  <licenses>
+    <license>
+      <name>Apache License, Version 2.0</name>
+      <url>https://www.apache.org/licenses/LICENSE-2.0.txt</url>
+    </license>
+  </licenses>
+
+  <properties>
+    <maven.compiler.release>17</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <jackson.version>2.17.2</jackson.version>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+      <version>${jackson.version}</version>
+    </dependency>
+  </dependencies>
+</project>

package/adapters/java/src/main/java/dev/forgeos/adapter/Auth.java

@@ -0,0 +1,20 @@
+package dev.forgeos.adapter;
+
+import java.util.List;
+import java.util.Map;
+
+public record Auth(
+    String kind,
+    String userId,
+    String tenantId,
+    String role,
+    List<String> roles,
+    List<String> permissions,
+    String email,
+    String name,
+    Map<String, Object> claims
+) {
+  public static Auth anonymous() {
+    return new Auth("anonymous", null, null, null, null, null, null, null, null);
+  }
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/Diagnostic.java

@@ -0,0 +1,16 @@
+package dev.forgeos.adapter;
+
+import java.util.List;
+
+public record Diagnostic(
+    String severity,
+    String code,
+    String message,
+    String file,
+    String fixHint,
+    List<String> docs
+) {
+  public static Diagnostic error(String code, String message) {
+    return new Diagnostic("error", code, message, null, null, List.of("docs/forge-protocol.md"));
+  }
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/Entry.java

@@ -0,0 +1,38 @@
+package dev.forgeos.adapter;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public final class Entry {
+  public String name;
+  public String kind;
+  public String description;
+  public String path;
+  public String method;
+  public Object inputSchema;
+  public Object outputSchema;
+  public String policy;
+  public Boolean tenantScoped;
+  public String transaction;
+  public String risk;
+  public Boolean needsApproval;
+  public List<String> effects;
+
+  public Entry copy() {
+    Entry copy = new Entry();
+    copy.name = name;
+    copy.kind = kind;
+    copy.description = description;
+    copy.path = path;
+    copy.method = method;
+    copy.inputSchema = inputSchema;
+    copy.outputSchema = outputSchema;
+    copy.policy = policy;
+    copy.tenantScoped = tenantScoped;
+    copy.transaction = transaction;
+    copy.risk = risk;
+    copy.needsApproval = needsApproval;
+    copy.effects = effects == null ? null : new ArrayList<>(effects);
+    return copy;
+  }
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/EntryKind.java

@@ -0,0 +1,16 @@
+package dev.forgeos.adapter;
+
+public enum EntryKind {
+  COMMAND("command"),
+  QUERY("query");
+
+  private final String value;
+
+  EntryKind(String value) {
+    this.value = value;
+  }
+
+  public String value() {
+    return value;
+  }
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/ErrorInfo.java

@@ -0,0 +1,4 @@
+package dev.forgeos.adapter;
+
+public record ErrorInfo(String code, String message) {
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/Forge.java

@@ -0,0 +1,94 @@
+package dev.forgeos.adapter;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import java.util.Arrays;
+import java.util.List;
+
+public final class Forge {
+  private Forge() {
+  }
+
+  public static ForgeRegistry service(String serviceName, ForgeRegistry.RegistryOption... options) {
+    return new ForgeRegistry(serviceName, options);
+  }
+
+  public static ForgeRegistry.RegistryOption framework(String value) {
+    return registry -> registry.setFramework(value);
+  }
+
+  public static ForgeRegistry.RegistryOption baseUrl(String value) {
+    return registry -> registry.setBaseUrl(value);
+  }
+
+  public static ForgeRegistry.RegistryOption health(String path) {
+    return registry -> registry.setHealth(path);
+  }
+
+  public static ForgeRegistry.RegistryOption schemaRef(String name, Object schema) {
+    return registry -> registry.addSchema(name, schema);
+  }
+
+  public static ForgeRegistry.EntryOption description(String value) {
+    return entry -> entry.description = value;
+  }
+
+  public static ForgeRegistry.EntryOption path(String value) {
+    return entry -> entry.path = value;
+  }
+
+  public static ForgeRegistry.EntryOption method(String value) {
+    return entry -> entry.method = value;
+  }
+
+  public static ForgeRegistry.EntryOption inputSchema(Object schema) {
+    return entry -> entry.inputSchema = schema;
+  }
+
+  public static ForgeRegistry.EntryOption outputSchema(Object schema) {
+    return entry -> entry.outputSchema = schema;
+  }
+
+  public static ForgeRegistry.EntryOption policy(String value) {
+    return entry -> entry.policy = value;
+  }
+
+  public static ForgeRegistry.EntryOption tenantScoped(boolean value) {
+    return entry -> entry.tenantScoped = value;
+  }
+
+  public static ForgeRegistry.EntryOption transaction(TransactionMode value) {
+    return entry -> entry.transaction = value.value();
+  }
+
+  public static ForgeRegistry.EntryOption risk(Risk value) {
+    return entry -> entry.risk = value.value();
+  }
+
+  public static ForgeRegistry.EntryOption needsApproval(boolean value) {
+    return entry -> entry.needsApproval = value;
+  }
+
+  public static ForgeRegistry.EntryOption effects(String... values) {
+    return entry -> entry.effects = List.copyOf(Arrays.asList(values));
+  }
+
+  public static ForgeRegistry.EntryOption readOnly() {
+    return entry -> {
+      entry.transaction = TransactionMode.READ_ONLY.value();
+      entry.risk = Risk.READ.value();
+    };
+  }
+
+  public static <In, Out> ForgeHandler handle(
+      Class<In> inputClass,
+      TypedForgeHandler<In, Out> handler
+  ) {
+    return (context, rawArgs) -> {
+      JsonNode args = rawArgs == null || rawArgs.isNull()
+          ? Json.MAPPER.createObjectNode()
+          : rawArgs;
+      In input = Json.MAPPER.treeToValue(args, inputClass);
+      return handler.handle(context, input);
+    };
+  }
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/ForgeCall.java

@@ -0,0 +1,12 @@
+package dev.forgeos.adapter;
+
+public record ForgeCall(String service, String entry, String kind, String traceId) {
+  public ForgeCall withDefaults(String serviceName, String entryName, String entryKind, String fallbackTraceId) {
+    return new ForgeCall(
+        service == null || service.isBlank() ? serviceName : service,
+        entry == null || entry.isBlank() ? entryName : entry,
+        kind == null || kind.isBlank() ? entryKind : kind,
+        traceId == null || traceId.isBlank() ? fallbackTraceId : traceId
+    );
+  }
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/ForgeContext.java

@@ -0,0 +1,11 @@
+package dev.forgeos.adapter;
+
+import java.util.List;
+import java.util.Map;
+
+public record ForgeContext(
+    Auth auth,
+    ForgeCall forge,
+    Map<String, List<String>> headers
+) {
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/ForgeHandler.java

@@ -0,0 +1,8 @@
+package dev.forgeos.adapter;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+@FunctionalInterface
+public interface ForgeHandler {
+  Object handle(ForgeContext context, JsonNode args) throws Exception;
+}

package/adapters/java/src/main/java/dev/forgeos/adapter/ForgeHttpHandler.java

@@ -0,0 +1,179 @@
+package dev.forgeos.adapter;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.sun.net.httpserver.Headers;
+import com.sun.net.httpserver.HttpExchange;
+import com.sun.net.httpserver.HttpHandler;
+import com.sun.net.httpserver.HttpServer;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+import java.net.InetSocketAddress;
+import java.net.URI;
+import java.net.URLDecoder;
+import java.nio.charset.StandardCharsets;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+public final class ForgeHttpHandler implements HttpHandler {
+  private final ForgeRegistry registry;
+
+  public ForgeHttpHandler(ForgeRegistry registry) {
+    this.registry = registry;
+  }
+
+  public static HttpServer listen(ForgeRegistry registry, String host, int port) throws IOException {
+    HttpServer server = HttpServer.create(new InetSocketAddress(host, port), 0);
+    ForgeHttpHandler handler = new ForgeHttpHandler(registry);
+    server.createContext("/", handler);
+    server.start();
+    return server;
+  }
+
+  @Override
+  public void handle(HttpExchange exchange) throws IOException {
+    String path = exchange.getRequestURI().getPath();
+    try {
+      if (registry.healthPath().equals(path)) {
+        writeJson(exchange, 200, Map.of("ok", true, "service", registry.serviceName()));
+        return;
+      }
+      if ("/manifest".equals(path)) {
+        String baseUrl = queryParams(exchange.getRequestURI()).getOrDefault("baseUrl", registry.baseUrl());
+        writeJson(exchange, 200, registry.manifest(baseUrl));
+        return;
+      }
+      if (path.startsWith("/commands/")) {
+        handleRuntime(exchange, EntryKind.COMMAND, path.substring("/commands/".length()));
+        return;
+      }
+      if (path.startsWith("/queries/")) {
+        handleRuntime(exchange, EntryKind.QUERY, path.substring("/queries/".length()));
+        return;
+      }
+      writeError(exchange, 404, traceIdFrom(exchange, null), "FORGE_JAVA_ROUTE_NOT_FOUND", "route not found");
+    } catch (Exception error) {
+      writeError(exchange, 500, traceIdFrom(exchange, null), "FORGE_JAVA_HANDLER_FAILED", error.getMessage());
+    }
+  }
+
+  private void handleRuntime(HttpExchange exchange, EntryKind kind, String rawName) throws IOException {
+    String name = decode(rawName);
+    if (!"POST".equals(exchange.getRequestMethod()) && !"GET".equals(exchange.getRequestMethod())) {
+      writeError(exchange, 405, traceIdFrom(exchange, null), "FORGE_JAVA_METHOD_NOT_ALLOWED", "external entry only accepts GET or POST");
+      return;
+    }
+
+    ForgeRegistry.RegisteredEntry registered = registry.lookup(kind, name);
+    if (registered == null) {
+      writeError(exchange, 404, traceIdFrom(exchange, null), "FORGE_JAVA_ENTRY_NOT_FOUND", "external entry not found");
+      return;
+    }
+
+    RequestEnvelope envelope;
+    try {
+      envelope = readEnvelope(exchange);
+    } catch (Exception error) {
+      writeError(exchange, 400, traceIdFrom(exchange, null), "FORGE_JAVA_BAD_REQUEST", error.getMessage());
+      return;
+    }
+
+    String traceId = traceIdFrom(exchange, envelope);
+    ForgeCall forge = envelope.forge() == null
+        ? new ForgeCall(registry.serviceName(), name, kind.value(), traceId)
+        : envelope.forge().withDefaults(registry.serviceName(), name, kind.value(), traceId);
+    Auth auth = envelope.auth() == null || envelope.auth().kind() == null
+        ? authFromHeaders(exchange.getRequestHeaders())
+        : envelope.auth();
+
+    ForgeContext context = new ForgeContext(auth, forge, exchange.getRequestHeaders());
+    try {
+      Object result = registered.handler().handle(context, envelope.args());
+      writeJson(exchange, 200, ResponseEnvelope.ok(result, forge.traceId()));
+    } catch (Exception error) {
+      writeError(exchange, 500, forge.traceId(), "FORGE_JAVA_HANDLER_FAILED", error.getMessage());
+    }
+  }
+
+  private RequestEnvelope readEnvelope(HttpExchange exchange) throws IOException {
+    if ("GET".equals(exchange.getRequestMethod())) {
+      String args = queryParams(exchange.getRequestURI()).getOrDefault("args", "{}");
+      JsonNode argsNode = Json.MAPPER.readTree(args);
+      return new RequestEnvelope(argsNode, null, null);
+    }
+
+    try (InputStream body = exchange.getRequestBody()) {
+      byte[] bytes = body.readAllBytes();
+      if (bytes.length == 0) {
+        return new RequestEnvelope(Json.MAPPER.createObjectNode(), null, null);
+      }
+      RequestEnvelope envelope = Json.MAPPER.readValue(bytes, RequestEnvelope.class);
+      JsonNode args = envelope.args() == null ? Json.MAPPER.createObjectNode() : envelope.args();
+      return new RequestEnvelope(args, envelope.auth(), envelope.forge());
+    }
+  }
+
+  private static Auth authFromHeaders(Headers headers) {
+    String kind = firstHeader(headers, "x-forge-auth-kind");
+    if (kind == null || kind.isBlank()) {
+      kind = "anonymous";
+    }
+    return new Auth(
+        kind,
+        firstHeader(headers, "x-forge-user-id"),
+        firstHeader(headers, "x-forge-tenant-id"),
+        firstHeader(headers, "x-forge-role"),
+        null,
+        null,
+        null,
+        null,
+        null
+    );
+  }
+
+  private static String traceIdFrom(HttpExchange exchange, RequestEnvelope envelope) {
+    if (envelope != null && envelope.forge() != null && envelope.forge().traceId() != null) {
+      return envelope.forge().traceId();
+    }
+    return firstHeader(exchange.getRequestHeaders(), "x-forge-trace-id");
+  }
+
+  private static String firstHeader(Headers headers, String name) {
+    List<String> values = headers.get(name);
+    if (values == null || values.isEmpty()) {
+      values = headers.get(name.toLowerCase());
+    }
+    return values == null || values.isEmpty() ? null : values.get(0);
+  }
+
+  private static Map<String, String> queryParams(URI uri) {
+    Map<String, String> params = new HashMap<>();
+    String query = uri.getRawQuery();
+    if (query == null || query.isBlank()) {
+      return params;
+    }
+    for (String part : query.split("&")) {
+      String[] pieces = part.split("=", 2);
+      params.put(decode(pieces[0]), pieces.length > 1 ? decode(pieces[1]) : "");
+    }
+    return params;
+  }
+
+  private static String decode(String value) {
+    return URLDecoder.decode(value, StandardCharsets.UTF_8);
+  }
+
+  private static void writeError(HttpExchange exchange, int status, String traceId, String code, String message) throws IOException {
+    writeJson(exchange, status, ResponseEnvelope.error(code, message, traceId));
+  }
+
+  private static void writeJson(HttpExchange exchange, int status, Object body) throws IOException {
+    byte[] bytes = Json.MAPPER.writeValueAsBytes(body);
+    exchange.getResponseHeaders().set("content-type", "application/json");
+    exchange.sendResponseHeaders(status, bytes.length);
+    try (OutputStream response = exchange.getResponseBody()) {
+      response.write(bytes);
+    }
+  }
+}