forgeos 0.1.0-alpha.8 → 0.1.0-alpha.9

package/docs/forge-protocol.md

@@ -0,0 +1,155 @@
+# Forge External Runtime Protocol
+
+Forge apps can import and call services written outside TypeScript through a
+`forge.manifest.json` compatible manifest. The manifest is the source of truth
+for external commands and queries:
+
+- validate and import external service metadata;
+- expose external services in generated inspect/API/agent artifacts;
+- execute external commands and queries through the Forge runtime bridge.
+
+This lets Java/Spring, Go, Rust, C#, Python, and other runtimes join the Forge
+contract without requiring the Forge compiler to parse every language AST.
+
+## Manifest
+
+External services publish JSON that matches
+`schemas/forge-manifest.schema.json`.
+
+```json
+{
+  "forgeProtocol": "1.0",
+  "language": "java",
+  "framework": "spring-boot",
+  "service": {
+    "name": "billing",
+    "transport": "http",
+    "baseUrl": "http://localhost:8080",
+    "health": "/actuator/health"
+  },
+  "entries": [
+    {
+      "name": "createInvoice",
+      "kind": "command",
+      "path": "/invoices",
+      "policy": "billing.write",
+      "transaction": "external-managed",
+      "risk": "write",
+      "needsApproval": true,
+      "effects": ["invoice.created"]
+    },
+    {
+      "name": "listInvoices",
+      "kind": "query",
+      "path": "/invoices",
+      "policy": "billing.read",
+      "transaction": "read-only",
+      "risk": "read",
+      "tenantScoped": true
+    }
+  ]
+}
+```
+
+Queries must stay read-only. Commands can declare write, destructive, or
+external risk. Policies are metadata until the runtime bridge enforces them for
+the external transport.
+
+## CLI
+
+Validate a manifest:
+
+```bash
+forge manifest validate ./forge.manifest.json --json
+```
+
+Import or update a service in the app registry:
+
+```bash
+forge manifest import ./forge.manifest.json --json
+```
+
+Imports are stored in `.forge/external-manifests.json`. A root
+`forge.manifest.json` is also discovered automatically for single-service
+experiments.
+
+## Generated Artifacts
+
+After `forge generate`, external services are emitted to:
+
+- `src/forge/_generated/externalServices.json`
+- `src/forge/_generated/api.json` under `external`
+- `src/forge/_generated/agentContract.json`
+- `src/forge/_generated/agentTools.json`
+- `src/forge/_generated/capabilityMap.json`
+
+External auto-tools use `execution: "external-runtime-endpoint"`. Forge exposes
+runtime bridge endpoints for these tools:
+
+```text
+POST /external/:service/commands/:name
+POST /external/:service/queries/:name
+```
+
+The generated client exposes the same bridge through:
+
+```ts
+await client.externalCommand("billing.createInvoice", args);
+await client.externalQuery(api.external.queries["billing.listInvoices"], args);
+```
+
+Command entries can also be invoked from the CLI with a qualified external
+name:
+
+```bash
+forge run billing.createInvoice --args '{"title":"Invoice"}'
+forge query billing.listInvoices --args '{}'
+```
+
+## Runtime Bridge
+
+Forge accepts the normal JSON body:
+
+```json
+{ "args": {} }
+```
+
+For HTTP services, Forge forwards a JSON envelope:
+
+```json
+{
+  "args": {},
+  "auth": { "kind": "user", "userId": "u1", "tenantId": "t1", "role": "member" },
+  "forge": {
+    "service": "billing",
+    "entry": "createInvoice",
+    "kind": "command",
+    "traceId": "trace_..."
+  }
+}
+```
+
+Forge also forwards runtime headers such as `x-forge-trace-id`,
+`x-forge-auth-kind`, `x-forge-user-id`, `x-forge-tenant-id`, `x-forge-role`,
+and the inbound `Authorization` header when present.
+
+External services can return either a Forge envelope:
+
+```json
+{ "ok": true, "result": { "id": "inv_1" } }
+```
+
+or a raw JSON value, which Forge treats as the result for successful HTTP
+responses. Error envelopes should include `ok: false`, `diagnostics`, or
+`error`.
+
+Supported runtime transports:
+
+- `http`: calls `service.baseUrl + entry.path`.
+- `stdio`: starts `service.command`, writes the JSON envelope to stdin, and
+  reads a JSON envelope or raw JSON result from stdout.
+- `grpc`: accepted in manifests for forward compatibility, but not executable
+  by the built-in runtime bridge yet.
+
+Manifest `policy` values are added to Forge policy bindings during generation.
+Use a named Forge policy, or `public`, `user`, or `system`.

package/examples/go-billing/go.mod

@@ -0,0 +1,7 @@
+module github.com/Stahldavid/forge/examples/go-billing
+
+go 1.22
+
+require github.com/Stahldavid/forge/adapters/go v0.0.0
+
+replace github.com/Stahldavid/forge/adapters/go => ../../adapters/go

package/examples/go-billing/main.go

@@ -0,0 +1,120 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"log"
+	"net/http"
+	"os"
+
+	forge "github.com/Stahldavid/forge/adapters/go"
+)
+
+type CreateInvoiceInput struct {
+	Title string `json:"title"`
+}
+
+type Invoice struct {
+	ID       string `json:"id"`
+	Title    string `json:"title,omitempty"`
+	Tenant   string `json:"tenant"`
+	TraceID  string `json:"traceId,omitempty"`
+	AuthKind string `json:"authKind,omitempty"`
+	UserID   string `json:"userId,omitempty"`
+}
+
+func main() {
+	addr := flag.String("addr", "127.0.0.1:8787", "address for the external billing service")
+	baseURL := flag.String("base-url", "", "base URL written into the Forge manifest")
+	manifest := flag.Bool("manifest", false, "write forge.manifest.json to stdout and exit")
+	flag.Parse()
+
+	if *baseURL == "" {
+		*baseURL = "http://" + *addr
+	}
+
+	app := newBillingApp(*baseURL)
+	if *manifest {
+		if err := app.WriteManifest(os.Stdout, *baseURL); err != nil {
+			log.Fatal(err)
+		}
+		return
+	}
+
+	log.Printf("go billing external service listening on http://%s", *addr)
+	if err := http.ListenAndServe(*addr, app.HTTPHandler()); err != nil {
+		log.Fatal(err)
+	}
+}
+
+func newBillingApp(baseURL string) *forge.Registry {
+	app := forge.New("billing",
+		forge.Framework("go/net-http"),
+		forge.BaseURL(baseURL),
+		forge.Health("/health"),
+	)
+
+	app.Command("createInvoice", forge.Handle(createInvoice),
+		forge.Description("Create an invoice in the external Go billing service."),
+		forge.Policy("billing.manage"),
+		forge.TenantScoped(true),
+		forge.TransactionMode(forge.TransactionExternalManaged),
+		forge.EntryRisk(forge.RiskWrite),
+		forge.NeedsApproval(true),
+		forge.Effects("invoice.created"),
+		forge.InputSchema(forge.Object(map[string]any{
+			"title": forge.String(),
+		}, "title")),
+		forge.OutputSchema(invoiceSchema()),
+	)
+
+	app.Query("listInvoices", forge.Handle(listInvoices),
+		forge.Description("List invoices visible to the current tenant."),
+		forge.Policy("billing.manage"),
+		forge.TenantScoped(true),
+		forge.ReadOnly(),
+		forge.OutputSchema(forge.Array(invoiceSchema())),
+	)
+
+	return app
+}
+
+func createInvoice(ctx context.Context, call *forge.Context, input CreateInvoiceInput) (Invoice, error) {
+	if input.Title == "" {
+		return Invoice{}, errors.New("title is required")
+	}
+	if call.Auth.TenantID == "" {
+		return Invoice{}, errors.New("tenant id is required")
+	}
+	return Invoice{
+		ID:       "inv_go_1",
+		Title:    input.Title,
+		Tenant:   call.Auth.TenantID,
+		TraceID:  call.Forge.TraceID,
+		AuthKind: call.Auth.Kind,
+		UserID:   call.Auth.UserID,
+	}, nil
+}
+
+func listInvoices(ctx context.Context, call *forge.Context, input struct{}) ([]Invoice, error) {
+	if call.Auth.TenantID == "" {
+		return nil, errors.New("tenant id is required")
+	}
+	return []Invoice{{
+		ID:     "inv_go_1",
+		Title:  "Go adapter invoice",
+		Tenant: call.Auth.TenantID,
+	}}, nil
+}
+
+func invoiceSchema() forge.Schema {
+	return forge.Object(map[string]any{
+		"id":       forge.String(),
+		"title":    forge.String(),
+		"tenant":   forge.String(),
+		"traceId":  forge.String(),
+		"authKind": forge.String(),
+		"userId":   forge.String(),
+	}, "id", "tenant")
+}

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.8",
+  "version": "0.1.0-alpha.9",
   "description": "Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.",
   "type": "module",
   "files": [
+    "adapters/",
     "bin/",
+    "docs/forge-protocol.md",
+    "examples/go-billing/",
     "packages/eslint-plugin-forge/",
+    "schemas/",
     "src/",
     "templates/",
     "README.md",

package/schemas/forge-manifest.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forgeos.dev/schemas/forge-manifest.schema.json",
+  "title": "Forge external runtime manifest",
+  "type": "object",
+  "required": ["forgeProtocol", "language", "service", "entries"],
+  "properties": {
+    "forgeProtocol": { "const": "1.0" },
+    "language": { "type": "string", "minLength": 1 },
+    "framework": { "type": "string", "minLength": 1 },
+    "service": {
+      "type": "object",
+      "required": ["name", "transport"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "transport": { "enum": ["http", "grpc", "stdio"] },
+        "baseUrl": { "type": "string", "minLength": 1 },
+        "command": { "type": "string", "minLength": 1 },
+        "health": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "kind"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "kind": { "enum": ["command", "query"] },
+          "description": { "type": "string" },
+          "path": { "type": "string", "minLength": 1 },
+          "method": { "enum": ["GET", "POST"] },
+          "inputSchema": {},
+          "outputSchema": {},
+          "policy": { "type": "string", "minLength": 1 },
+          "tenantScoped": { "type": "boolean" },
+          "transaction": {
+            "enum": ["read-only", "external-managed", "forge-managed", "saga"]
+          },
+          "risk": { "enum": ["read", "write", "destructive", "external"] },
+          "needsApproval": { "type": "boolean" },
+          "effects": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "schemas": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}

package/src/forge/_generated/actionSubscriptions.json

@@ -1,2 +1,2 @@
-// @forge-generated generator=0.1.0-alpha.8 input=e4d0ef83fd5056a122576670ab55ecc6b5a1d72260ddaca89b6299c392878b3c content=f62e8f96c72dd5960d89f4933c387e85f2b9307f6089e51a734517418b8342f1
-{"analyzerVersion":"0.1.0","byEvent":{},"diagnostics":[],"generatorVersion":"0.1.0-alpha.8","inputHash":"099a57bf0e87b463179c80ef6e83d66c03122652b2030c8a81335eabde721b8d","schemaVersion":"0.1.0","subscriptions":[]}
+// @forge-generated generator=0.1.0-alpha.9 input=f9063a03ef56a20a89f1418951bede5ab5ed87d800bb0512a0d0445309642a36 content=c8c99213f5084424d71502987d05ae14288f88174ee2c4c9d46d7d5dc3d71d5d
+{"analyzerVersion":"0.1.0","byEvent":{},"diagnostics":[],"generatorVersion":"0.1.0-alpha.9","inputHash":"d32670173917f0bc753936a6605c4345a1a51a9dfd187e3171e5bff881bcef1a","schemaVersion":"0.1.0","subscriptions":[]}

package/src/forge/_generated/actionSubscriptions.ts

@@ -1,10 +1,10 @@
-// @forge-generated generator=0.1.0-alpha.8 input=e4d0ef83fd5056a122576670ab55ecc6b5a1d72260ddaca89b6299c392878b3c content=74dd6e67d53e02442f71b7506ea722bc7a427bf40fd66f5a4bc7b381cc941c2a
+// @forge-generated generator=0.1.0-alpha.9 input=f9063a03ef56a20a89f1418951bede5ab5ed87d800bb0512a0d0445309642a36 content=01e5de0cead87f1785ce7afd777c960e141d2f42782db5d9a4ab6b3044353212
 export const actionSubscriptions = {
   "analyzerVersion": "0.1.0",
   "byEvent": {},
   "diagnostics": [],
-  "generatorVersion": "0.1.0-alpha.8",
-  "inputHash": "099a57bf0e87b463179c80ef6e83d66c03122652b2030c8a81335eabde721b8d",
+  "generatorVersion": "0.1.0-alpha.9",
+  "inputHash": "d32670173917f0bc753936a6605c4345a1a51a9dfd187e3171e5bff881bcef1a",
   "schemaVersion": "0.1.0",
   "subscriptions": []
 } as const;

package/src/forge/_generated/agentAdapterManifest.json

@@ -1,2 +1,2 @@
-// @forge-generated generator=0.1.0-alpha.8 input=e4d0ef83fd5056a122576670ab55ecc6b5a1d72260ddaca89b6299c392878b3c content=12ed7405ea17ef844e952d95a882ced49138eed6b3e6c70b180c3197038ca108
-{"generatorVersion":"0.1.0-alpha.8","schemaVersion":"0.1.0","sourceHash":"sha256:4b16f8c1f20404acd104a50e0543ce44b8730bc85eadf09a65a99b8ae846873b","targets":[{"adapterVersion":"agent-adapter-0.1.0","default":true,"files":["AGENTS.md",".forge/agent/context.json",".forge/agent/commands.json",".forge/agent/done-criteria.json",".forge/agent/playbooks/add-command.md",".forge/agent/playbooks/add-query.md",".forge/agent/playbooks/add-livequery.md",".forge/agent/playbooks/add-resource.md",".forge/agent/playbooks/refactor-field.md",".forge/agent/playbooks/fix-policy-denied.md",".forge/agent/playbooks/fix-guard-violation.md",".forge/agent/playbooks/upgrade-package.md",".forge/agent/playbooks/debug-trace.md",".forge/agent/playbooks/frontend-change.md",".forge/agent/playbooks/self-host-check.md"],"formatVersion":"2026-06","name":"generic"},{"adapterVersion":"agent-adapter-0.1.0","files":[".codex/skills/forge-add-command/SKILL.md",".codex/skills/forge-add-resource/SKILL.md",".codex/skills/forge-fix-guard-violation/SKILL.md",".codex/skills/forge-fix-policy-denied/SKILL.md",".codex/skills/forge-upgrade-package/SKILL.md",".codex/skills/forge-debug-trace/SKILL.md",".codex/agents/forge-explorer.toml",".codex/agents/forge-worker.toml",".codex/agents/forge-reviewer.toml",".codex/agents/forge-security.toml"],"formatVersion":"2026-06","name":"codex","optional":true},{"adapterVersion":"agent-adapter-0.1.0","files":[".cursor/rules/forge-runtime.mdc",".cursor/rules/forge-frontend.mdc",".cursor/rules/forge-security.mdc",".cursor/rules/forge-workflow.mdc"],"formatVersion":"2026-06","name":"cursor","optional":true},{"adapterVersion":"agent-adapter-0.1.0","files":["CLAUDE.md",".claude/forge-runtime.md",".claude/forge-playbooks.md",".claude/forge-security.md"],"formatVersion":"2026-06","name":"claude","optional":true}]}
+// @forge-generated generator=0.1.0-alpha.9 input=f9063a03ef56a20a89f1418951bede5ab5ed87d800bb0512a0d0445309642a36 content=39cfb6cb79d2ae3e0970fd2ba9b0c89810c43765e187c5b2cfe3f26861ccc160
+{"generatorVersion":"0.1.0-alpha.9","schemaVersion":"0.1.0","sourceHash":"sha256:44ca56cd05d6dc2a8f4845990c0ecd6d54d7a209e04f9bcf190656f0da09ea7a","targets":[{"adapterVersion":"agent-adapter-0.1.0","default":true,"files":["AGENTS.md",".forge/agent/context.json",".forge/agent/commands.json",".forge/agent/done-criteria.json",".forge/agent/playbooks/add-command.md",".forge/agent/playbooks/add-query.md",".forge/agent/playbooks/add-livequery.md",".forge/agent/playbooks/add-resource.md",".forge/agent/playbooks/refactor-field.md",".forge/agent/playbooks/fix-policy-denied.md",".forge/agent/playbooks/fix-guard-violation.md",".forge/agent/playbooks/upgrade-package.md",".forge/agent/playbooks/debug-trace.md",".forge/agent/playbooks/frontend-change.md",".forge/agent/playbooks/self-host-check.md"],"formatVersion":"2026-06","name":"generic"},{"adapterVersion":"agent-adapter-0.1.0","files":[".codex/skills/forge-add-command/SKILL.md",".codex/skills/forge-add-resource/SKILL.md",".codex/skills/forge-fix-guard-violation/SKILL.md",".codex/skills/forge-fix-policy-denied/SKILL.md",".codex/skills/forge-upgrade-package/SKILL.md",".codex/skills/forge-debug-trace/SKILL.md",".codex/agents/forge-explorer.toml",".codex/agents/forge-worker.toml",".codex/agents/forge-reviewer.toml",".codex/agents/forge-security.toml"],"formatVersion":"2026-06","name":"codex","optional":true},{"adapterVersion":"agent-adapter-0.1.0","files":[".cursor/rules/forge-runtime.mdc",".cursor/rules/forge-frontend.mdc",".cursor/rules/forge-security.mdc",".cursor/rules/forge-workflow.mdc"],"formatVersion":"2026-06","name":"cursor","optional":true},{"adapterVersion":"agent-adapter-0.1.0","files":["CLAUDE.md",".claude/forge-runtime.md",".claude/forge-playbooks.md",".claude/forge-security.md"],"formatVersion":"2026-06","name":"claude","optional":true}]}

package/src/forge/_generated/agentAdapterManifest.ts

@@ -1,8 +1,8 @@
-// @forge-generated generator=0.1.0-alpha.8 input=e4d0ef83fd5056a122576670ab55ecc6b5a1d72260ddaca89b6299c392878b3c content=6bf1062059a35cdb9f8295f710bf248c96e6946884a70ed46b3b904780577095
+// @forge-generated generator=0.1.0-alpha.9 input=f9063a03ef56a20a89f1418951bede5ab5ed87d800bb0512a0d0445309642a36 content=f36afd529102056d863ddd230ef5782084a29e1fdfa2863a7c02668e9f1798d3
 export const agentAdapterManifest = {
-  "generatorVersion": "0.1.0-alpha.8",
+  "generatorVersion": "0.1.0-alpha.9",
   "schemaVersion": "0.1.0",
-  "sourceHash": "sha256:4b16f8c1f20404acd104a50e0543ce44b8730bc85eadf09a65a99b8ae846873b",
+  "sourceHash": "sha256:44ca56cd05d6dc2a8f4845990c0ecd6d54d7a209e04f9bcf190656f0da09ea7a",
   "targets": [
     {
       "adapterVersion": "agent-adapter-0.1.0",