forgeos 0.1.0-alpha.4 → 0.1.0-alpha.41

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,36 @@
+<?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>
+</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;

package/docs/cair-protocol.md

@@ -0,0 +1,103 @@
+# CAIR Protocol
+
+CAIR is ForgeOS' compact agent interface for reading code structure, querying symbols, and planning safe edits without loading the whole repository into an agent context window.
+
+CAIR is intentionally CLI-first. It does not add a second mutating tool surface. Agents should use CAIR to inspect structure and create reviewable plans, then apply those plans through the ForgeOS CLI with hash checks and rollback journals.
+
+## Read Workflow
+
+Start with a compact snapshot:
+
+```bash
+forge cair snapshot
+forge cair query "Q STATUS"
+forge cair query "Q ST"
+```
+
+Use symbol, definition, reference, impact, and dependency API queries before opening large files:
+
+```bash
+forge cair query "Q S name=createTicket"
+forge cair query "Q D S#1"
+forge cair query "Q R S#1"
+forge cair query "Q I S#1"
+forge cair query "Q DEP.API package=zod symbol=object"
+```
+
+The goal is to make agent navigation evidence-backed: CAIR gives stable ids for modules, symbols, packages, APIs, and tests so an agent can select a small file set instead of scanning the whole project.
+
+## Action Safety
+
+Mutating CAIR actions should be planned first:
+
+```bash
+forge cair action --plan "A RN t=S#1 nn=openTicket"
+```
+
+The plan lives under `.forge/cair/plans/` and records the target files and expected hashes. Applying a plan checks those hashes before editing:
+
+```bash
+forge cair action "A APPLY plan=<P#|.forge/cair/plans/...json>"
+```
+
+Applied plans write rollback journals under `.forge/cair/journal/`:
+
+```bash
+forge cair action "A ROLLBACK journal=.forge/cair/journal/<journal>.json"
+```
+
+Use `--dry-run` when exploring an action shape without creating a plan:
+
+```bash
+forge cair action --dry-run "A CREATE.SYMBOL path=src/example.ts kind=function name=example export=true createFile=true"
+```
+
+Generated files stay protected by default. Use `--include-generated` only when the edit is intentionally about generated artifacts.
+
+## DeltaDB Evidence
+
+Successful CAIR CLI runs are recorded in DeltaDB as sanitized operational events:
+
+| CAIR command | Delta event |
+|--------------|-------------|
+| `forge cair snapshot` | `cair.snapshot.created` |
+| `forge cair query ...` | `cair.query.run` |
+| `forge cair action --plan ...` | `cair.plan.created` |
+| `forge cair action "A APPLY ..."` | `cair.plan.applied` |
+| `forge cair action --dry-run ...` | `cair.action.previewed` |
+
+The recorder stores compact verbs such as `Q ST` or `A APPLY`; it does not need to store full action bodies as first-class timeline data. Use:
+
+```bash
+forge timeline cair:protocol --json
+forge timeline --kind cair.plan.applied --json
+```
+
+This makes CAIR navigation and guarded edits visible beside file changes, proofs, and agent activity.
+
+## Compact Aliases
+
+| Long form | Compact |
+|-----------|---------|
+| `Q STATUS` | `Q ST` |
+| `Q SYMBOL` | `Q S` |
+| `Q DEF` | `Q D` |
+| `Q REFS` | `Q R` |
+| `Q IMPACT` | `Q I` |
+| `A RENAME.SYMBOL target=S#1 newName=x` | `A RN t=S#1 nn=x` |
+
+## Agent Posture
+
+Use this loop for code work:
+
+```bash
+forge cair snapshot
+forge cair query "Q ST"
+forge cair query "Q S name=<symbol>"
+forge cair query "Q I S#1"
+forge cair action --plan "A RN t=S#1 nn=<newName>"
+forge cair action "A APPLY plan=<P#|path>"
+forge check --json
+```
+
+Do not use CAIR as a bypass around ForgeOS rules. Commands remain transactional writes, queries and liveQueries remain read-only, side effects still belong in actions and workflows, and generated artifacts remain derived.