forgeos 0.1.0-alpha.0 → 0.1.0-alpha.10

package/adapters/go/registry.go

@@ -0,0 +1,234 @@
+package forge
+
+import (
+	"encoding/json"
+	"io"
+)
+
+type Registry struct {
+	service   Service
+	framework string
+	schemas   map[string]any
+	entries   []registeredEntry
+	lookup    map[string]registeredEntry
+}
+
+type registeredEntry struct {
+	entry   Entry
+	handler HandlerFunc
+}
+
+type RegistryOption func(*Registry)
+type EntryOption func(*Entry)
+
+func New(serviceName string, options ...RegistryOption) *Registry {
+	registry := &Registry{
+		service: Service{
+			Name:      serviceName,
+			Transport: "http",
+			Health:    "/health",
+		},
+		framework: "net/http",
+		schemas:   map[string]any{},
+		lookup:    map[string]registeredEntry{},
+	}
+	for _, option := range options {
+		option(registry)
+	}
+	return registry
+}
+
+func Framework(value string) RegistryOption {
+	return func(registry *Registry) {
+		registry.framework = value
+	}
+}
+
+func BaseURL(value string) RegistryOption {
+	return func(registry *Registry) {
+		registry.service.BaseURL = value
+	}
+}
+
+func Health(path string) RegistryOption {
+	return func(registry *Registry) {
+		registry.service.Health = path
+	}
+}
+
+func SchemaRef(name string, schema any) RegistryOption {
+	return func(registry *Registry) {
+		registry.schemas[name] = schema
+	}
+}
+
+func (registry *Registry) Command(name string, handler HandlerFunc, options ...EntryOption) {
+	entry := Entry{
+		Name:        name,
+		Kind:        KindCommand,
+		Path:        "/commands/" + name,
+		Method:      "POST",
+		Transaction: TransactionExternalManaged,
+		Risk:        RiskWrite,
+	}
+	registry.add(entry, handler, options...)
+}
+
+func (registry *Registry) Query(name string, handler HandlerFunc, options ...EntryOption) {
+	entry := Entry{
+		Name:        name,
+		Kind:        KindQuery,
+		Path:        "/queries/" + name,
+		Method:      "POST",
+		Transaction: TransactionReadOnly,
+		Risk:        RiskRead,
+	}
+	registry.add(entry, handler, options...)
+}
+
+func (registry *Registry) add(entry Entry, handler HandlerFunc, options ...EntryOption) {
+	for _, option := range options {
+		option(&entry)
+	}
+	registered := registeredEntry{entry: entry, handler: handler}
+	registry.entries = append(registry.entries, registered)
+	registry.lookup[lookupKey(entry.Kind, entry.Name)] = registered
+}
+
+func Description(value string) EntryOption {
+	return func(entry *Entry) {
+		entry.Description = value
+	}
+}
+
+func Path(value string) EntryOption {
+	return func(entry *Entry) {
+		entry.Path = value
+	}
+}
+
+func Method(value string) EntryOption {
+	return func(entry *Entry) {
+		entry.Method = value
+	}
+}
+
+func InputSchema(schema any) EntryOption {
+	return func(entry *Entry) {
+		entry.InputSchema = schema
+	}
+}
+
+func OutputSchema(schema any) EntryOption {
+	return func(entry *Entry) {
+		entry.OutputSchema = schema
+	}
+}
+
+func Policy(value string) EntryOption {
+	return func(entry *Entry) {
+		entry.Policy = value
+	}
+}
+
+func TenantScoped(value bool) EntryOption {
+	return func(entry *Entry) {
+		entry.TenantScoped = value
+	}
+}
+
+func TransactionMode(value Transaction) EntryOption {
+	return func(entry *Entry) {
+		entry.Transaction = value
+	}
+}
+
+func EntryRisk(value Risk) EntryOption {
+	return func(entry *Entry) {
+		entry.Risk = value
+	}
+}
+
+func NeedsApproval(value bool) EntryOption {
+	return func(entry *Entry) {
+		entry.NeedsApproval = &value
+	}
+}
+
+func Effects(values ...string) EntryOption {
+	return func(entry *Entry) {
+		entry.Effects = append([]string{}, values...)
+	}
+}
+
+func ReadOnly() EntryOption {
+	return func(entry *Entry) {
+		entry.Transaction = TransactionReadOnly
+		entry.Risk = RiskRead
+	}
+}
+
+func (registry *Registry) Manifest(baseURL string) Manifest {
+	service := registry.service
+	if baseURL != "" {
+		service.BaseURL = baseURL
+	}
+	entries := make([]Entry, 0, len(registry.entries))
+	for _, registered := range registry.entries {
+		entries = append(entries, registered.entry)
+	}
+	manifest := Manifest{
+		ForgeProtocol: ProtocolVersion,
+		Language:      "go",
+		Framework:     registry.framework,
+		Service:       service,
+		Entries:       entries,
+	}
+	if len(registry.schemas) > 0 {
+		manifest.Schemas = registry.schemas
+	}
+	return manifest
+}
+
+func (registry *Registry) MarshalManifest(baseURL string) ([]byte, error) {
+	return json.MarshalIndent(registry.Manifest(baseURL), "", "  ")
+}
+
+func (registry *Registry) WriteManifest(writer io.Writer, baseURL string) error {
+	encoded, err := registry.MarshalManifest(baseURL)
+	if err != nil {
+		return err
+	}
+	if _, err := writer.Write(encoded); err != nil {
+		return err
+	}
+	_, err = writer.Write([]byte("\n"))
+	return err
+}
+
+func Object(properties map[string]any, required ...string) Schema {
+	schema := Schema{
+		"type":       "object",
+		"properties": properties,
+	}
+	if len(required) > 0 {
+		schema["required"] = required
+	}
+	return schema
+}
+
+func String() Schema {
+	return Schema{"type": "string"}
+}
+
+func Boolean() Schema {
+	return Schema{"type": "boolean"}
+}
+
+func Array(items any) Schema {
+	return Schema{"type": "array", "items": items}
+}
+
+func lookupKey(kind EntryKind, name string) string {
+	return string(kind) + ":" + name
+}

package/adapters/go/types.go

@@ -0,0 +1,136 @@
+package forge
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+)
+
+const ProtocolVersion = "1.0"
+
+type EntryKind string
+type Risk string
+type Transaction string
+
+const (
+	KindCommand EntryKind = "command"
+	KindQuery   EntryKind = "query"
+
+	RiskRead        Risk = "read"
+	RiskWrite       Risk = "write"
+	RiskDestructive Risk = "destructive"
+	RiskExternal    Risk = "external"
+
+	TransactionReadOnly        Transaction = "read-only"
+	TransactionExternalManaged Transaction = "external-managed"
+	TransactionForgeManaged    Transaction = "forge-managed"
+	TransactionSaga            Transaction = "saga"
+)
+
+type Schema map[string]any
+
+type Manifest struct {
+	ForgeProtocol string         `json:"forgeProtocol"`
+	Language      string         `json:"language"`
+	Framework     string         `json:"framework,omitempty"`
+	Service       Service        `json:"service"`
+	Entries       []Entry        `json:"entries"`
+	Schemas       map[string]any `json:"schemas,omitempty"`
+}
+
+type Service struct {
+	Name      string `json:"name"`
+	Transport string `json:"transport"`
+	BaseURL   string `json:"baseUrl,omitempty"`
+	Command   string `json:"command,omitempty"`
+	Health    string `json:"health,omitempty"`
+}
+
+type Entry struct {
+	Name          string      `json:"name"`
+	Kind          EntryKind   `json:"kind"`
+	Description   string      `json:"description,omitempty"`
+	Path          string      `json:"path,omitempty"`
+	Method        string      `json:"method,omitempty"`
+	InputSchema   any         `json:"inputSchema,omitempty"`
+	OutputSchema  any         `json:"outputSchema,omitempty"`
+	Policy        string      `json:"policy,omitempty"`
+	TenantScoped  bool        `json:"tenantScoped,omitempty"`
+	Transaction   Transaction `json:"transaction,omitempty"`
+	Risk          Risk        `json:"risk,omitempty"`
+	NeedsApproval *bool       `json:"needsApproval,omitempty"`
+	Effects       []string    `json:"effects,omitempty"`
+}
+
+type Auth struct {
+	Kind        string         `json:"kind"`
+	UserID      string         `json:"userId,omitempty"`
+	TenantID    string         `json:"tenantId,omitempty"`
+	Role        string         `json:"role,omitempty"`
+	Roles       []string       `json:"roles,omitempty"`
+	Permissions []string       `json:"permissions,omitempty"`
+	Email       string         `json:"email,omitempty"`
+	Name        string         `json:"name,omitempty"`
+	Claims      map[string]any `json:"claims,omitempty"`
+}
+
+type ForgeCall struct {
+	Service string `json:"service"`
+	Entry   string `json:"entry"`
+	Kind    string `json:"kind"`
+	TraceID string `json:"traceId"`
+}
+
+type Context struct {
+	Auth    Auth
+	Forge   ForgeCall
+	Headers http.Header
+}
+
+type HandlerFunc func(context.Context, *Context, json.RawMessage) (any, error)
+
+type RequestEnvelope struct {
+	Args  json.RawMessage `json:"args"`
+	Auth  Auth            `json:"auth"`
+	Forge ForgeCall       `json:"forge"`
+}
+
+type ResponseEnvelope struct {
+	OK          bool         `json:"ok"`
+	Result      any          `json:"result,omitempty"`
+	Diagnostics []Diagnostic `json:"diagnostics,omitempty"`
+	Error       *ErrorInfo   `json:"error,omitempty"`
+	TraceID     string       `json:"traceId,omitempty"`
+}
+
+type Diagnostic struct {
+	Severity string   `json:"severity"`
+	Code     string   `json:"code"`
+	Message  string   `json:"message"`
+	File     string   `json:"file,omitempty"`
+	FixHint  string   `json:"fixHint,omitempty"`
+	Docs     []string `json:"docs,omitempty"`
+}
+
+type ErrorInfo struct {
+	Code    string `json:"code"`
+	Message string `json:"message"`
+}
+
+func Decode(raw json.RawMessage, target any) error {
+	if len(raw) == 0 || string(raw) == "null" {
+		raw = json.RawMessage("{}")
+	}
+	return json.Unmarshal(raw, target)
+}
+
+func Handle[In any, Out any](handler func(context.Context, *Context, In) (Out, error)) HandlerFunc {
+	return func(ctx context.Context, call *Context, raw json.RawMessage) (any, error) {
+		var input In
+		if err := Decode(raw, &input); err != nil {
+			var zero Out
+			return zero, err
+		}
+		return handler(ctx, call, input)
+	}
+}

package/bin/forge.mjs

@@ -5,15 +5,16 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
 const entrypoint = join(root, "src", "forge", "cli", "main.ts");
 
-let tsImport;
+let register;
 try {
-  ({ tsImport } = await import("tsx/esm/api"));
+  ({ register } = await import("tsx/esm/api"));
 } catch {
   console.error("error: Forge requires the 'tsx' package to run under Node.");
   console.error("Install dependencies with your package manager, then retry.");
   process.exit(1);
 }
 
-const module = await tsImport(pathToFileURL(entrypoint).href, import.meta.url);
+register();
+const module = await import(pathToFileURL(entrypoint).href);
 const exitCode = await module.main(process.argv.slice(2));
 process.exit(exitCode);

package/docs/changelog.md

@@ -0,0 +1,116 @@
+# Changelog
+
+Release history for the `forgeos` npm package (`alpha` dist-tag).
+
+The canonical source file in the repository is `CHANGELOG.md`.
+
+## 0.1.0-alpha.10
+
+Launch polish:
+
+- Fixed `forge run <external-command> --args ...` so CLI arguments reach the external runtime bridge.
+- Added direct external query CLI support through `forge query <service.query> --args ...`.
+- Emit generated `.json` artifacts as pure JSON while keeping deterministic headers on code/text artifacts.
+- Relaxed the `minimal-web` template verify script to `forge verify --smoke` and added the missing `check` script to `b2b-support-web`.
+- Updated public protocol/changelog docs for the external runtime and Go adapter alpha line.
+- Bumped the create-app wrapper package line to `create-forgeos-app@0.1.0-alpha.4`.
+
+## 0.1.0-alpha.9
+
+Compiler, external runtime, and Go adapter:
+
+- Added the Forge external runtime protocol bridge for manifest-backed commands and queries.
+- Added the Go adapter MVP with a real `go-billing` conformance example.
+- Emitted external service metadata into inspect/API/agent artifacts, including `needsApproval` for agent tools.
+- Reuse compiler classifier package signals across export classification, dropping repeated package signal scans.
+- Reuse serialized graph JSON when rendering the largest generated TypeScript graph artifacts.
+- Keep generated Forge artifacts aligned with the `0.1.0-alpha.9` compiler/runtime version.
+
+## 0.1.0-alpha.8
+
+Publishing:
+
+- Publish prerelease packages through the ForgeOS alpha publisher so npm dist-tags stay aligned.
+
+## 0.1.0-alpha.7
+
+Publishing:
+
+- Keep npm prerelease publishing on the public alpha dist-tag.
+
+## 0.1.0-alpha.6
+
+Release and packaging hardening:
+
+- Added `forge --version` / `forge --version --json`.
+- Updated `create-forgeos-app` help to read the wrapper package version instead of a hardcoded string and bumped the wrapper to `0.1.0-alpha.2`.
+- Added dependency vulnerability evidence with an explicit waiver file and CI release gate.
+- Updated generated web template dependencies to current Vite/plugin-react and Next majors.
+
+## 0.1.0-alpha.5
+
+Release alignment for the public alpha channel:
+
+- Added `forge ai redteam --model-level --json` with deterministic prompt-injection, secret-exfiltration, approval-bypass, cross-tenant, and indirect tool-injection probes.
+- Added `forge security prove --full --json` support for source checkouts, with graceful structural-proof fallback when packaged apps do not include ForgeOS test fixtures.
+- Strengthened npm publish workflows to run `security prove --db postgres --full --json`.
+- Added public registry smoke coverage for `forgeos@alpha` and `create-forgeos-app@alpha`.
+- Bumped the create-app wrapper package line to `create-forgeos-app@0.1.0-alpha.1`.
+
+## 0.1.0-alpha.4
+
+Security assurance and release evidence hardening:
+
+- Added value-aware telemetry redaction for known secret values in safe-looking fields, messages, details, outputs, and stack traces.
+- Added webhook signature, timestamp, and replay protection helpers with Stripe/GitHub/generic HMAC coverage.
+- Added HTTP tenant-isolation tests that exercise the dev server/API boundary, not only the internal runtime executor.
+- Added `forge rls mutate-test --json` to kill dangerous generated RLS mutations such as missing FORCE RLS, missing policies, unconditional predicates, and `BYPASSRLS`.
+- Extended `forge security prove --json` with RLS mutation proof and invariant-level evidence metadata.
+- Added scripts to split security evidence by invariant and emit basic release supply-chain evidence plus CycloneDX SBOM.
+- Strengthened publish/security workflows so release gates use Postgres-backed security proof, RLS mutation proof, release evidence, and SBOM generation.
+
+## 0.1.0-alpha.3
+
+Native Forge AI agents on top of Vercel AI SDK v6:
+
+- Added `aiTool` and `agent` primitives with generated `agentTools.json` / `agentTools.md`.
+- Added `ctx.agent.run` and `ctx.ai.runAgent` using AI SDK `ToolLoopAgent`.
+- Added auto-tools for commands, queries, and liveQueries with read-only vs approval-required writes.
+- Added dev agent endpoints: `POST /ai/agents/run` and `POST /ai/agents/chat`.
+- Extended `forge ai` CLI with `tools`, `agents`, and `trace` subcommands.
+- Added `forge inspect agent-tools` and agent tool metadata in `agentContract.json`.
+- Upgraded runtime dependency to AI SDK v6 for tool calling, streaming UI, and MCP compatibility.
+
+Documentation:
+
+- Added public [AI](ai.md) page and AST-aware `rename command` codemod docs.
+- Full RTD expansion: [Agent Workflow](agent-workflow.md), [Frontend](frontend.md), [Security & Data](security-and-data.md), [Authoring](authoring.md), [Testing & Repair](testing-and-repair.md), [Self-Host](self-host.md), [Templates](templates.md), Material theme, search, and Mermaid diagrams.
+
+## 0.1.0-alpha.2
+
+Windows and generated-app hardening:
+
+- Fixed Node ESM handler loading on Windows by importing generated app modules through `file://` URLs across commands, queries, liveQueries, outbox actions, workflow steps, mocks, and telemetry adapters.
+- Fixed `forge dev` SSE streaming on the Node HTTP fallback so liveQuery snapshots are flushed immediately instead of buffering forever.
+- Hardened generated app scaffolding and web dev spawning on Windows.
+- Updated the B2B support template to route frontend imports through `web/lib/forge.ts` and use safer handler input validation.
+- Added focused tests for Node compatibility, template scaffolding, runtime imports, and streaming responses.
+- Added `create-forgeos-app@alpha` for `npm create forgeos-app@alpha`.
+- Added GitHub Packages mirror workflow for scoped package publishing.
+
+## 0.1.0-alpha.1
+
+Republish alpha with the dependency/API oracle improvements:
+
+- Added dependency API inspection commands for agents: `forge deps api`, `forge deps trace`, and `forge deps runtime-compat`.
+- Added dependency API summaries to `agentContract.json`.
+- Added package resolution traces, runtime compatibility metadata, and runtime/type mismatch diagnostics to `packageGraph`.
+- Reduced package graph warning noise for `package.json` metadata exports, declaration-file subpaths, and pattern exports.
+
+## 0.1.0-alpha.0
+
+Initial alpha packaging baseline for ForgeOS.
+
+This release line validates npm installation, the `forge` CLI binary, template creation, generated contracts, and the agent-native local development loop.
+
+Added Read the Docs-ready public documentation, generator/package version alignment checks, and a broad generated-app field-test harness for release hardening.

package/docs/forge-protocol.md

@@ -0,0 +1,156 @@
+# 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 '{}'
+forge run 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