forgeos 0.1.0-alpha.6 → 0.1.0-alpha.60

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeOS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,15 @@
 # ForgeOS
 
-Agent-native application framework and compiler for building Forge apps without a mandatory dashboard. ForgeOS turns application source into deterministic runtime contracts, generated clients, safety checks, and machine-readable context that humans and AI coding agents can use safely.
+The contract layer for agentic software development. ForgeOS turns application source into deterministic runtime contracts, generated clients, safety checks, and machine-readable context that humans and AI coding agents can use safely.
 
-**Status:** private/public alpha MVP, implemented through H43. ForgeOS already includes the compiler, local runtime, frontend SDK, production auth, RLS compiler, liveQuery, self-host artifacts, generated agent contract, guided dev loop, repair/review/test tooling, AST-aware codemods, package intelligence, native AI tools/agents, npm alpha publishing, and Read the Docs public docs. Public release hardening is still focused on deeper semantic codemods, broader field reports, and more production mileage.
+**Status:** private/public alpha MVP, implemented through H49. ForgeOS already includes the compiler, local runtime, frontend SDK, production auth, RLS compiler, liveQuery, self-host artifacts, generated agent contract, guided dev loop, repair/review/test tooling, AST-aware codemods, package intelligence, native AI tools/agents, DeltaDB work memory, external agent memory ingestion, brownfield import analysis, npm alpha publishing, and Read the Docs public docs. Public release hardening is still focused on deeper semantic codemods, broader field reports, and more production mileage.
 
 Public docs live at [forgeos.readthedocs.io](https://forgeos.readthedocs.io/). The repo builds them with `.readthedocs.yaml`, `mkdocs.yml`, and `docs/index.md`.
 
 Start with [Why ForgeOS](https://forgeos.readthedocs.io/en/latest/why-forgeos/) to understand the agent-native design.
 
+For the short version, read [The Five-Minute ForgeOS Model](https://forgeos.readthedocs.io/en/latest/five-minute-model/), [Alpha Golden Path](https://forgeos.readthedocs.io/en/latest/golden-path/), and [Stable Alpha Surface](https://forgeos.readthedocs.io/en/latest/stable-alpha/). The important distinction is that external coding agents are the primary ForgeOS workflow; integrated AI SDK features are available for apps that need in-product AI, but they are not the main development loop.
+
 ## Agent-First Quickstart
 
 ```bash
@@ -91,6 +93,39 @@ npm run field:test -- --package-managers npm --templates minimal-web --forge-spe
 
 The scheduled/manual `Field Tests` workflow expands that coverage across Linux, macOS, Windows, Node 22, Node 24, and npm/pnpm/yarn/bun.
 
+## External Runtimes And Adapters
+
+ForgeOS can import services written outside TypeScript through the Forge Protocol.
+External runtimes publish a `forge.manifest.json` that describes commands, queries,
+transport, policies, risk metadata, tenant scope, and schemas. Forge then emits
+the same machine-readable app/API/agent artifacts and exposes runtime bridge
+endpoints for those entries.
+
+The Go example starts a manifest-backed service:
+
+```bash
+cd examples/go-billing
+go run . --manifest --base-url http://127.0.0.1:8787 > forge.manifest.json
+go run . --addr 127.0.0.1:8787 --base-url http://127.0.0.1:8787
+```
+
+In a Forge app:
+
+```bash
+forge manifest validate ./forge.manifest.json --json
+forge manifest import ./forge.manifest.json --json
+forge generate
+forge run billing.createInvoice --args '{"title":"Invoice"}' --user-id u1 --tenant-id tenant-a --role admin
+forge query billing.listInvoices --args '{}' --user-id u1 --tenant-id tenant-a --role admin
+```
+
+For Java, see [`adapters/java`](adapters/java/README.md),
+[`adapters/java-spring-boot-starter`](adapters/java-spring-boot-starter/README.md),
+and [`examples/java-billing`](examples/java-billing/README.md).
+
+See [`docs/forge-protocol.md`](docs/forge-protocol.md), [`schemas/forge-manifest.schema.json`](schemas/forge-manifest.schema.json),
+and [`adapters/go`](adapters/go/README.md).
+
 ## What ForgeOS Generates
 
 ```txt
@@ -143,11 +178,14 @@ forge.lock
 | AI | Vercel AI SDK v6 engine, provider registry, `ctx.ai`, `ctx.agent.run`, `aiTool`, `agent`, `/ai/agents/run` JSON automation, `/ai/agents/chat` UIMessage streaming, `forge ai trace`, structural and model-level redteam probes, mock mode, telemetry without prompt/output retention by default |
 | Frontend | generated client SDK, React/Next hooks, template app, liveQuery client support |
 | LiveQuery | durable invalidation log, reconnect/resume semantics, production hardening checks |
+| DeltaDB | ambient local recorder plus inferred work sessions and semantic timelines for Forge commands, dev file saves, generated artifacts, runtime calls, policies, proofs, diagnostics, `forge timeline`, `forge explain`, and optional `forge session` correction |
+| Agent memory | opt-in Codex and Claude Code hooks, Cursor MCP/rules setup, normalized external agent events, redacted local memory, and `forge mcp serve` |
+| Brownfield import | static TypeScript/JavaScript app inventory with routes, frontend calls, env usage, candidate entries, risk report, migration plan, and hidden-by-default imported agent contract |
 | Self-host | compose/deploy artifacts and self-host checks |
 | Agent contract | `AGENTS.md`, `agentContract.json`, app maps, runtime rules, playbooks, inspect/doctor |
 | Authoring | `forge make`, feature blueprints, safe refactor plans, package upgrade plans |
 | Testing/repair | impact-based test planner, repair loop, structured review, UI/browser test bridge |
-| Adapters | agent adapter export for external AI tools |
+| Adapters | Forge Protocol manifest import plus Go, Java, and Spring Boot adapter support for executable external commands and queries |
 | Intent router | `forge do` maps objectives like fix, verify, connect UI, and add feature into plans, files, risks, and next commands |
 | Full-stack map | `frontendGraph` + `capabilityMap` connect routes, components, hooks, runtime entries, tables, policies, and gaps |
 | Dev loop | `forge dev` prints API/Web URLs, phase health, capability coverage, cache status, diagnostics, and next action |
@@ -168,6 +206,16 @@ forge dev
 forge inspect all --json
 forge inspect framework --json
 forge inspect capabilities --json
+forge delta status
+forge timeline
+forge timeline --session current
+forge explain <thing>
+forge explain session current
+forge session list
+forge agent memory --json
+forge mcp serve
+forge import analyze --json
+forge inspect imported --json
 forge doctor
 forge verify --standard
 forge verify --strict
@@ -189,8 +237,10 @@ Common command groups:
 | `forge check --json` | Validate guardrails and emit diagnostics with fix hints |
 | `forge verify --smoke` | Fast local gate: generated drift, Forge checks, typecheck when present, no tests/lint |
 | `forge verify --standard` | Agent development gate: generated drift, Forge/security checks, typecheck, and impact-selected tests |
-| `forge verify --strict` | Full handoff/CI gate: generated drift, Forge/security checks, typecheck, full test script, lint |
+| `forge verify --strict` | Full handoff/CI gate: generated drift, Forge/security checks, typecheck, full TestGraph in bounded parallel/isolated chunks, lint |
 | `forge verify --script-timeout-ms <ms>` | Run package scripts with a predictable timeout and machine-readable timeout diagnostics |
+| `forge verify --test-jobs <n>` | Tune strict TestGraph chunk parallelism; `FORGE_VERIFY_TEST_JOBS` is also supported |
+| `forge verify --strict --test-plan --json` | Print the strict TestGraph scheduler plan without running tests |
 | `forge do "<objective>" --json` | Guided intent router: choose the right workflow, files, risks, and next action |
 | `forge inspect <target> --json` | Inspect generated app/data/runtime/policy/client/agent/UI surfaces |
 | `forge inspect framework --json` | Inspect ForgeOS framework modules, CLI commands, templates, examples, tests, and preferred entrypoints |
@@ -210,7 +260,10 @@ Common command groups:
 | `forge ui` | Browser/UI smoke, scenario, route, snapshot, doctor, and reports |
 | `forge deps` | Package upgrade planning and application |
 | `forge release` | Release/source-map bridge and symbolication |
-| `forge agent`, `forge agent-contract` | Agent-facing contract and adapter exports |
+| `forge agent`, `forge agent-contract` | Agent-facing contract, adapter exports, context, install, ingest, and memory commands |
+| `forge mcp serve` | MCP server for external agents to read Forge context, memory, timeline, and inspect surfaces |
+| `forge import analyze`, `forge import inspect` | Brownfield TypeScript/JavaScript app inventory and reviewed migration planning |
+| `forge inspect imported --json` | Inspect `.forge/import` analysis artifacts |
 | `forge self-host` | Self-host packaging and checks |
 
 Refactor codemods are AST-aware where safety matters most:
@@ -360,7 +413,7 @@ Configure npm Trusted Publisher for package `forgeos`:
 | Environment | blank |
 | Allowed action | `npm publish` |
 
-Do not add `NPM_TOKEN` for normal releases. Alpha releases publish with the `alpha` dist-tag so prerelease builds do not become `latest` accidentally. Use `release:publish-local-alpha -- --dry-run` only to validate the staged tarball locally; real npm publishing should go through `release:publish-alpha`, which dispatches `publish.yml` and uses npm OIDC Trusted Publisher. The workflow checks whether the package version already exists before installing dependencies or running tests, then uses `id-token: write`, Node 24/npm 11+, and provenance for the actual publish. `npm run release:smoke` runs `npm pack`, creates a fresh app with the packed tarball, installs dependencies, runs `forge dev --once --json`, and verifies the app smoke path.
+Do not add `NPM_TOKEN` for normal alpha publishes. Alpha releases publish with the `alpha` dist-tag through npm OIDC Trusted Publisher so prerelease builds do not become `latest` accidentally. Configure `NPM_TOKEN` only when maintainers intentionally want the workflow to promote `latest` with `npm dist-tag add forgeos@<version> latest`; otherwise that step is skipped and `latest` may lag behind `alpha` during hardening. Use `release:publish-local-alpha -- --dry-run` only to validate the staged tarball locally; real npm publishing should go through `release:publish-alpha`, which dispatches `publish.yml` and uses npm OIDC Trusted Publisher. The workflow checks whether the package version already exists before installing dependencies or running tests, then uses `id-token: write`, Node 24/npm 11+, and provenance for the actual publish. `npm run release:smoke` runs `npm pack`, creates a fresh app with the packed tarball, installs dependencies, runs `forge dev --once --json`, and verifies the app smoke path.
 
 ## Milestone History
 
@@ -408,6 +461,12 @@ H40  Windows/runtime hardening
 H41  Node-compatible CLI/runtime
 H42  Verify observability and quieter app workspaces
 H43  Native AI tools and agent loop
+H44  Ambient DeltaDB recorder
+H45  Automatic work-session inference
+H46  Automatic change grouping
+H47  Semantic timeline
+H48  Agent Memory Bridge
+H49  Brownfield import analysis
 ```
 
 ## Remaining Hardening Before Public Release

package/adapters/go/README.md

@@ -0,0 +1,23 @@
+# Forge Go Adapter
+
+`adapters/go` is the minimal Go SDK for external Forge runtimes. It registers
+commands and queries, emits `forge.manifest.json`, and exposes a Forge-compatible
+HTTP handler.
+
+```go
+app := forge.New("billing", forge.BaseURL("http://127.0.0.1:8787"))
+
+app.Command("createInvoice", forge.Handle(createInvoice),
+    forge.Policy("billing.manage"),
+    forge.TenantScoped(true),
+    forge.NeedsApproval(true),
+)
+
+app.Query("listInvoices", forge.Handle(listInvoices),
+    forge.Policy("billing.manage"),
+    forge.TenantScoped(true),
+)
+```
+
+The HTTP handler accepts Forge runtime envelopes on `/commands/:name` and
+`/queries/:name`, then returns `{ "ok": true, "result": ... }` envelopes.

package/adapters/go/go.mod

@@ -0,0 +1,3 @@
+module github.com/Stahldavid/forge/adapters/go
+
+go 1.22

package/adapters/go/http.go

@@ -0,0 +1,149 @@
+package forge
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+)
+
+func (registry *Registry) HTTPHandler() http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc(registry.service.Health, registry.handleHealth)
+	mux.HandleFunc("/manifest", registry.handleManifest)
+	mux.HandleFunc("/commands/", registry.handleRuntime(KindCommand, "/commands/"))
+	mux.HandleFunc("/queries/", registry.handleRuntime(KindQuery, "/queries/"))
+	return mux
+}
+
+func (registry *Registry) handleHealth(response http.ResponseWriter, request *http.Request) {
+	writeJSON(response, http.StatusOK, map[string]any{
+		"ok":      true,
+		"service": registry.service.Name,
+	})
+}
+
+func (registry *Registry) handleManifest(response http.ResponseWriter, request *http.Request) {
+	baseURL := request.URL.Query().Get("baseUrl")
+	if baseURL == "" {
+		baseURL = registry.service.BaseURL
+	}
+	writeJSON(response, http.StatusOK, registry.Manifest(baseURL))
+}
+
+func (registry *Registry) handleRuntime(kind EntryKind, prefix string) http.HandlerFunc {
+	return func(response http.ResponseWriter, request *http.Request) {
+		name := strings.TrimPrefix(request.URL.Path, prefix)
+		registered, ok := registry.lookup[lookupKey(kind, name)]
+		if !ok {
+			writeError(response, http.StatusNotFound, "", "FORGE_GO_ENTRY_NOT_FOUND", "external entry not found")
+			return
+		}
+		if request.Method != http.MethodPost && request.Method != http.MethodGet {
+			writeError(response, http.StatusMethodNotAllowed, "", "FORGE_GO_METHOD_NOT_ALLOWED", "external entry only accepts GET or POST")
+			return
+		}
+
+		envelope, err := readRequestEnvelope(request)
+		traceID := traceIDFrom(request, envelope)
+		if err != nil {
+			writeError(response, http.StatusBadRequest, traceID, "FORGE_GO_BAD_REQUEST", err.Error())
+			return
+		}
+		if envelope.Forge.Service == "" {
+			envelope.Forge.Service = registry.service.Name
+		}
+		if envelope.Forge.Entry == "" {
+			envelope.Forge.Entry = name
+		}
+		if envelope.Forge.Kind == "" {
+			envelope.Forge.Kind = string(kind)
+		}
+		if envelope.Forge.TraceID == "" {
+			envelope.Forge.TraceID = traceID
+		}
+		if envelope.Auth.Kind == "" {
+			envelope.Auth = authFromHeaders(request.Header)
+		}
+
+		call := &Context{
+			Auth:    envelope.Auth,
+			Forge:   envelope.Forge,
+			Headers: request.Header,
+		}
+		result, err := registered.handler(request.Context(), call, envelope.Args)
+		if err != nil {
+			writeError(response, http.StatusInternalServerError, envelope.Forge.TraceID, "FORGE_GO_HANDLER_FAILED", err.Error())
+			return
+		}
+		writeJSON(response, http.StatusOK, ResponseEnvelope{
+			OK:      true,
+			Result:  result,
+			TraceID: envelope.Forge.TraceID,
+		})
+	}
+}
+
+func readRequestEnvelope(request *http.Request) (RequestEnvelope, error) {
+	if request.Method == http.MethodGet {
+		args := request.URL.Query().Get("args")
+		if args == "" {
+			args = "{}"
+		}
+		return RequestEnvelope{Args: json.RawMessage(args)}, nil
+	}
+	defer request.Body.Close()
+	var envelope RequestEnvelope
+	decoder := json.NewDecoder(request.Body)
+	if err := decoder.Decode(&envelope); err != nil {
+		return envelope, err
+	}
+	if len(envelope.Args) == 0 {
+		envelope.Args = json.RawMessage("{}")
+	}
+	if !json.Valid(envelope.Args) {
+		return envelope, errors.New("request args must be valid JSON")
+	}
+	return envelope, nil
+}
+
+func authFromHeaders(headers http.Header) Auth {
+	auth := Auth{Kind: headers.Get("x-forge-auth-kind")}
+	if auth.Kind == "" {
+		auth.Kind = "anonymous"
+	}
+	auth.UserID = headers.Get("x-forge-user-id")
+	auth.TenantID = headers.Get("x-forge-tenant-id")
+	auth.Role = headers.Get("x-forge-role")
+	return auth
+}
+
+func traceIDFrom(request *http.Request, envelope RequestEnvelope) string {
+	if envelope.Forge.TraceID != "" {
+		return envelope.Forge.TraceID
+	}
+	return request.Header.Get("x-forge-trace-id")
+}
+
+func writeError(response http.ResponseWriter, status int, traceID string, code string, message string) {
+	writeJSON(response, status, ResponseEnvelope{
+		OK: false,
+		Diagnostics: []Diagnostic{{
+			Severity: "error",
+			Code:     code,
+			Message:  message,
+			Docs:     []string{"docs/forge-protocol.md"},
+		}},
+		Error: &ErrorInfo{
+			Code:    code,
+			Message: message,
+		},
+		TraceID: traceID,
+	})
+}
+
+func writeJSON(response http.ResponseWriter, status int, body any) {
+	response.Header().Set("content-type", "application/json")
+	response.WriteHeader(status)
+	_ = json.NewEncoder(response).Encode(body)
+}

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
+}