forgeos 0.1.0-alpha.7 → 0.1.0-alpha.71

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

@@ -0,0 +1,121 @@
+package dev.forgeos.adapter;
+
+import java.io.IOException;
+import java.io.OutputStream;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+public final class ForgeRegistry {
+  private final Service service;
+  private final Map<String, Object> schemas = new LinkedHashMap<>();
+  private final List<RegisteredEntry> entries = new ArrayList<>();
+  private final Map<String, RegisteredEntry> lookup = new LinkedHashMap<>();
+  private String framework = "java/jdk-http";
+
+  public ForgeRegistry(String serviceName, RegistryOption... options) {
+    this.service = new Service(serviceName, "http", null, null, "/health");
+    for (RegistryOption option : options) {
+      option.apply(this);
+    }
+  }
+
+  public String serviceName() {
+    return service.name();
+  }
+
+  public String baseUrl() {
+    return service.baseUrl();
+  }
+
+  public String healthPath() {
+    return service.health() == null ? "/health" : service.health();
+  }
+
+  public void command(String name, ForgeHandler handler, EntryOption... options) {
+    Entry entry = new Entry();
+    entry.name = name;
+    entry.kind = EntryKind.COMMAND.value();
+    entry.path = "/commands/" + name;
+    entry.method = "POST";
+    entry.transaction = TransactionMode.EXTERNAL_MANAGED.value();
+    entry.risk = Risk.WRITE.value();
+    add(entry, handler, options);
+  }
+
+  public void query(String name, ForgeHandler handler, EntryOption... options) {
+    Entry entry = new Entry();
+    entry.name = name;
+    entry.kind = EntryKind.QUERY.value();
+    entry.path = "/queries/" + name;
+    entry.method = "POST";
+    entry.transaction = TransactionMode.READ_ONLY.value();
+    entry.risk = Risk.READ.value();
+    add(entry, handler, options);
+  }
+
+  public Manifest manifest(String baseUrl) {
+    Service manifestService = service;
+    if (baseUrl != null && !baseUrl.isBlank()) {
+      manifestService = new Service(service.name(), service.transport(), baseUrl, service.command(), service.health());
+    }
+    List<Entry> manifestEntries = entries.stream().map(registered -> registered.entry().copy()).toList();
+    return new Manifest("1.0", "java", framework, manifestService, manifestEntries, schemas.isEmpty() ? null : schemas);
+  }
+
+  public byte[] marshalManifest(String baseUrl) throws IOException {
+    return Json.MAPPER.writerWithDefaultPrettyPrinter().writeValueAsBytes(manifest(baseUrl));
+  }
+
+  public void writeManifest(OutputStream output, String baseUrl) throws IOException {
+    output.write(marshalManifest(baseUrl));
+    output.write('\n');
+  }
+
+  RegisteredEntry lookup(EntryKind kind, String name) {
+    return lookup.get(key(kind, name));
+  }
+
+  void setFramework(String framework) {
+    this.framework = framework;
+  }
+
+  void setBaseUrl(String baseUrl) {
+    this.service.setBaseUrl(baseUrl);
+  }
+
+  void setHealth(String health) {
+    this.service.setHealth(health);
+  }
+
+  void addSchema(String name, Object schema) {
+    this.schemas.put(name, schema);
+  }
+
+  private void add(Entry entry, ForgeHandler handler, EntryOption... options) {
+    for (EntryOption option : options) {
+      option.apply(entry);
+    }
+    RegisteredEntry registered = new RegisteredEntry(entry, handler);
+    entries.add(registered);
+    lookup.put(key(EntryKind.valueOf(entry.kind.toUpperCase()), entry.name), registered);
+  }
+
+  private static String key(EntryKind kind, String name) {
+    return kind.value() + ":" + name;
+  }
+
+  @FunctionalInterface
+  public interface RegistryOption {
+    void apply(ForgeRegistry registry);
+  }
+
+  @FunctionalInterface
+  public interface EntryOption {
+    void apply(Entry entry);
+  }
+
+  record RegisteredEntry(Entry entry, ForgeHandler handler) {
+  }
+}

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

@@ -0,0 +1,14 @@
+package dev.forgeos.adapter;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.databind.DeserializationFeature;
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+public final class Json {
+  public static final ObjectMapper MAPPER = new ObjectMapper()
+      .setSerializationInclusion(JsonInclude.Include.NON_NULL)
+      .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
+
+  private Json() {
+  }
+}

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

@@ -0,0 +1,14 @@
+package dev.forgeos.adapter;
+
+import java.util.List;
+import java.util.Map;
+
+public record Manifest(
+    String forgeProtocol,
+    String language,
+    String framework,
+    Service service,
+    List<Entry> entries,
+    Map<String, Object> schemas
+) {
+}

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

@@ -0,0 +1,6 @@
+package dev.forgeos.adapter;
+
+import com.fasterxml.jackson.databind.JsonNode;
+
+public record RequestEnvelope(JsonNode args, Auth auth, ForgeCall forge) {
+}

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

@@ -0,0 +1,25 @@
+package dev.forgeos.adapter;
+
+import java.util.List;
+
+public record ResponseEnvelope(
+    boolean ok,
+    Object result,
+    List<Diagnostic> diagnostics,
+    ErrorInfo error,
+    String traceId
+) {
+  public static ResponseEnvelope ok(Object result, String traceId) {
+    return new ResponseEnvelope(true, result, null, null, traceId);
+  }
+
+  public static ResponseEnvelope error(String code, String message, String traceId) {
+    return new ResponseEnvelope(
+        false,
+        null,
+        List.of(Diagnostic.error(code, message == null || message.isBlank() ? code : message)),
+        new ErrorInfo(code, message == null || message.isBlank() ? code : message),
+        traceId
+    );
+  }
+}

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

@@ -0,0 +1,18 @@
+package dev.forgeos.adapter;
+
+public enum Risk {
+  READ("read"),
+  WRITE("write"),
+  DESTRUCTIVE("destructive"),
+  EXTERNAL("external");
+
+  private final String value;
+
+  Risk(String value) {
+    this.value = value;
+  }
+
+  public String value() {
+    return value;
+  }
+}

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

@@ -0,0 +1,36 @@
+package dev.forgeos.adapter;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+public final class Schemas {
+  private Schemas() {
+  }
+
+  public static Map<String, Object> object(Map<String, Object> properties, String... required) {
+    Map<String, Object> schema = new LinkedHashMap<>();
+    schema.put("type", "object");
+    schema.put("properties", properties);
+    if (required.length > 0) {
+      schema.put("required", List.of(required));
+    }
+    return schema;
+  }
+
+  public static Map<String, Object> string() {
+    return Map.of("type", "string");
+  }
+
+  public static Map<String, Object> bool() {
+    return Map.of("type", "boolean");
+  }
+
+  public static Map<String, Object> number() {
+    return Map.of("type", "number");
+  }
+
+  public static Map<String, Object> array(Object items) {
+    return Map.of("type", "array", "items", items);
+  }
+}

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

@@ -0,0 +1,65 @@
+package dev.forgeos.adapter;
+
+public final class Service {
+  private final String name;
+  private final String transport;
+  private String baseUrl;
+  private String command;
+  private String health;
+
+  public Service(String name, String transport, String baseUrl, String command, String health) {
+    this.name = name;
+    this.transport = transport;
+    this.baseUrl = baseUrl;
+    this.command = command;
+    this.health = health;
+  }
+
+  public String name() {
+    return name;
+  }
+
+  public String getName() {
+    return name;
+  }
+
+  public String transport() {
+    return transport;
+  }
+
+  public String getTransport() {
+    return transport;
+  }
+
+  public String baseUrl() {
+    return baseUrl;
+  }
+
+  public String getBaseUrl() {
+    return baseUrl;
+  }
+
+  public String command() {
+    return command;
+  }
+
+  public String getCommand() {
+    return command;
+  }
+
+  public String health() {
+    return health;
+  }
+
+  public String getHealth() {
+    return health;
+  }
+
+  void setBaseUrl(String baseUrl) {
+    this.baseUrl = baseUrl;
+  }
+
+  void setHealth(String health) {
+    this.health = health;
+  }
+}

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

@@ -0,0 +1,18 @@
+package dev.forgeos.adapter;
+
+public enum TransactionMode {
+  READ_ONLY("read-only"),
+  EXTERNAL_MANAGED("external-managed"),
+  FORGE_MANAGED("forge-managed"),
+  SAGA("saga");
+
+  private final String value;
+
+  TransactionMode(String value) {
+    this.value = value;
+  }
+
+  public String value() {
+    return value;
+  }
+}

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

@@ -0,0 +1,6 @@
+package dev.forgeos.adapter;
+
+@FunctionalInterface
+public interface TypedForgeHandler<In, Out> {
+  Out handle(ForgeContext context, In input) throws Exception;
+}

package/adapters/java-spring-boot-starter/README.md

@@ -0,0 +1,32 @@
+# Forge Java Spring Boot Starter
+
+`adapters/java-spring-boot-starter` is the first Spring integration layer for
+Forge external runtimes. It discovers a bean annotated with
+`@ForgeExternalService`, registers methods annotated with `@ForgeCommand` and
+`@ForgeQuery`, and exposes a `ForgeRegistry` bean.
+
+```java
+@Service
+@ForgeExternalService(name = "billing", baseUrl = "http://127.0.0.1:8080")
+public class BillingService {
+  @ForgeCommand(
+      name = "createInvoice",
+      policy = "billing.manage",
+      tenantScoped = true,
+      needsApproval = true,
+      effects = {"invoice.created"})
+  public Invoice createInvoice(ForgeContext context, CreateInvoiceInput input) {
+    return new Invoice("inv_java_1", input.title(), context.auth().tenantId());
+  }
+
+  @ForgeQuery(name = "listInvoices", policy = "billing.manage", tenantScoped = true)
+  public List<Invoice> listInvoices(ForgeContext context) {
+    return List.of(new Invoice("inv_java_1", "Spring invoice", context.auth().tenantId()));
+  }
+}
+```
+
+The starter intentionally keeps HTTP endpoint wiring thin in this first version.
+Applications can inject the generated `ForgeRegistry` and serve it with the core
+adapter, or add their own Spring MVC bridge. Full MVC/Actuator auto-endpoints
+are a follow-up layer.

package/adapters/java-spring-boot-starter/pom.xml

@@ -0,0 +1,49 @@
+<?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-spring-boot-starter</artifactId>
+  <version>0.1.0-alpha.11</version>
+  <name>Forge Java Spring Boot Starter</name>
+  <description>Spring Boot integration for Forge external runtimes.</description>
+
+  <properties>
+    <maven.compiler.release>17</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <spring.boot.version>3.3.5</spring.boot.version>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>dev.forgeos</groupId>
+      <artifactId>forge-java-adapter</artifactId>
+      <version>0.1.0-alpha.11</version>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-autoconfigure</artifactId>
+      <version>${spring.boot.version}</version>
+    </dependency>
+    <dependency>
+      <groupId>org.springframework</groupId>
+      <artifactId>spring-context</artifactId>
+      <version>6.1.14</version>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.13.0</version>
+        <configuration>
+          <release>${maven.compiler.release}</release>
+        </configuration>
+      </plugin>
+    </plugins>
+  </build>
+</project>

package/adapters/java-spring-boot-starter/src/main/java/dev/forgeos/adapter/spring/ForgeCommand.java

@@ -0,0 +1,22 @@
+package dev.forgeos.adapter.spring;
+
+import dev.forgeos.adapter.Risk;
+import dev.forgeos.adapter.TransactionMode;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ForgeCommand {
+  String name();
+  String description() default "";
+  String path() default "";
+  String policy() default "";
+  boolean tenantScoped() default false;
+  TransactionMode transaction() default TransactionMode.EXTERNAL_MANAGED;
+  Risk risk() default Risk.WRITE;
+  boolean needsApproval() default false;
+  String[] effects() default {};
+}

package/adapters/java-spring-boot-starter/src/main/java/dev/forgeos/adapter/spring/ForgeExternalService.java

@@ -0,0 +1,15 @@
+package dev.forgeos.adapter.spring;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ForgeExternalService {
+  String name();
+  String baseUrl() default "";
+  String framework() default "spring-boot";
+  String health() default "/health";
+}

package/adapters/java-spring-boot-starter/src/main/java/dev/forgeos/adapter/spring/ForgeQuery.java

@@ -0,0 +1,16 @@
+package dev.forgeos.adapter.spring;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ForgeQuery {
+  String name();
+  String description() default "";
+  String path() default "";
+  String policy() default "";
+  boolean tenantScoped() default false;
+}

package/adapters/java-spring-boot-starter/src/main/java/dev/forgeos/adapter/spring/ForgeServiceBeanCondition.java

@@ -0,0 +1,18 @@
+package dev.forgeos.adapter.spring;
+
+import org.springframework.beans.factory.BeanFactory;
+import org.springframework.beans.factory.ListableBeanFactory;
+import org.springframework.context.annotation.Condition;
+import org.springframework.context.annotation.ConditionContext;
+import org.springframework.core.type.AnnotatedTypeMetadata;
+
+public final class ForgeServiceBeanCondition implements Condition {
+  @Override
+  public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
+    BeanFactory beanFactory = context.getBeanFactory();
+    if (!(beanFactory instanceof ListableBeanFactory listable)) {
+      return false;
+    }
+    return !listable.getBeansWithAnnotation(ForgeExternalService.class).isEmpty();
+  }
+}

package/adapters/java-spring-boot-starter/src/main/java/dev/forgeos/adapter/spring/ForgeSpringAutoConfiguration.java

@@ -0,0 +1,16 @@
+package dev.forgeos.adapter.spring;
+
+import dev.forgeos.adapter.ForgeRegistry;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.context.ApplicationContext;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Conditional;
+
+@AutoConfiguration
+public class ForgeSpringAutoConfiguration {
+  @Bean
+  @Conditional(ForgeServiceBeanCondition.class)
+  public ForgeRegistry forgeRegistry(ApplicationContext context) {
+    return ForgeSpringRuntime.buildRegistry(context);
+  }
+}

package/adapters/java-spring-boot-starter/src/main/java/dev/forgeos/adapter/spring/ForgeSpringRuntime.java

@@ -0,0 +1,104 @@
+package dev.forgeos.adapter.spring;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import dev.forgeos.adapter.Forge;
+import dev.forgeos.adapter.ForgeContext;
+import dev.forgeos.adapter.ForgeHandler;
+import dev.forgeos.adapter.ForgeRegistry;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.lang.reflect.Parameter;
+import org.springframework.aop.support.AopUtils;
+import org.springframework.context.ApplicationContext;
+import org.springframework.core.annotation.AnnotatedElementUtils;
+import org.springframework.util.ReflectionUtils;
+
+public final class ForgeSpringRuntime {
+  private ForgeSpringRuntime() {
+  }
+
+  public static ForgeRegistry buildRegistry(ApplicationContext context) {
+    String[] serviceBeanNames = context.getBeanNamesForAnnotation(ForgeExternalService.class);
+    if (serviceBeanNames.length == 0) {
+      throw new IllegalStateException("no @ForgeExternalService bean found");
+    }
+
+    Object serviceBean = context.getBean(serviceBeanNames[0]);
+    Class<?> serviceClass = AopUtils.getTargetClass(serviceBean);
+    ForgeExternalService service = AnnotatedElementUtils.findMergedAnnotation(
+        serviceClass,
+        ForgeExternalService.class
+    );
+    if (service == null) {
+      throw new IllegalStateException("selected bean is missing @ForgeExternalService");
+    }
+
+    ForgeRegistry registry = Forge.service(service.name(),
+        Forge.framework(service.framework()),
+        Forge.baseUrl(service.baseUrl()),
+        Forge.health(service.health())
+    );
+
+    ReflectionUtils.doWithMethods(serviceClass, method -> registerMethod(registry, serviceBean, method));
+    return registry;
+  }
+
+  private static void registerMethod(ForgeRegistry registry, Object bean, Method method) {
+    ForgeCommand command = AnnotatedElementUtils.findMergedAnnotation(method, ForgeCommand.class);
+    if (command != null) {
+      registry.command(command.name(), handlerFor(bean, method),
+          command.description().isBlank() ? entry -> { } : Forge.description(command.description()),
+          command.path().isBlank() ? entry -> { } : Forge.path(command.path()),
+          command.policy().isBlank() ? entry -> { } : Forge.policy(command.policy()),
+          Forge.tenantScoped(command.tenantScoped()),
+          Forge.transaction(command.transaction()),
+          Forge.risk(command.risk()),
+          Forge.needsApproval(command.needsApproval()),
+          Forge.effects(command.effects())
+      );
+    }
+
+    ForgeQuery query = AnnotatedElementUtils.findMergedAnnotation(method, ForgeQuery.class);
+    if (query != null) {
+      registry.query(query.name(), handlerFor(bean, method),
+          query.description().isBlank() ? entry -> { } : Forge.description(query.description()),
+          query.path().isBlank() ? entry -> { } : Forge.path(query.path()),
+          query.policy().isBlank() ? entry -> { } : Forge.policy(query.policy()),
+          Forge.tenantScoped(query.tenantScoped()),
+          Forge.readOnly()
+      );
+    }
+  }
+
+  private static ForgeHandler handlerFor(Object bean, Method method) {
+    ReflectionUtils.makeAccessible(method);
+    return (context, args) -> {
+      try {
+        return method.invoke(bean, argumentsFor(method, context, args));
+      } catch (InvocationTargetException error) {
+        Throwable target = error.getTargetException();
+        if (target instanceof Exception exception) {
+          throw exception;
+        }
+        throw new RuntimeException(target);
+      }
+    };
+  }
+
+  private static Object[] argumentsFor(Method method, ForgeContext context, JsonNode args) throws Exception {
+    Parameter[] parameters = method.getParameters();
+    Object[] values = new Object[parameters.length];
+    for (int index = 0; index < parameters.length; index += 1) {
+      Class<?> type = parameters[index].getType();
+      if (type.equals(ForgeContext.class)) {
+        values[index] = context;
+      } else {
+        JsonNode safeArgs = args == null || args.isNull()
+            ? dev.forgeos.adapter.Json.MAPPER.createObjectNode()
+            : args;
+        values[index] = dev.forgeos.adapter.Json.MAPPER.treeToValue(safeArgs, type);
+      }
+    }
+    return values;
+  }
+}

package/adapters/java-spring-boot-starter/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

@@ -0,0 +1 @@
+dev.forgeos.adapter.spring.ForgeSpringAutoConfiguration

package/bin/forge.mjs

@@ -1,8 +1,26 @@
 #!/usr/bin/env node
 import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const args = process.argv.slice(2);
+
+if (args.includes("--version") || args.includes("-v")) {
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  const version = typeof pkg.version === "string" ? pkg.version : "unknown";
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({
+      version,
+      cliVersion: version,
+      forgeosVersion: version,
+    }, null, 2));
+  } else {
+    console.log(version);
+  }
+  process.exit(0);
+}
+
 const entrypoint = join(root, "src", "forge", "cli", "main.ts");
 
 let register;