scenery

README

scenery

One CLI for building, running, and inspecting Go services — built for humans and AI agents.

Scenery applications use one current specification: app.scn and package-local package.scn files compile into one canonical typed resource graph, with dependencies captured in generated app.lock.scn. Retired contract filenames fail with an exact SCN1021 rename instruction rather than acting as aliases. The graph drives Go and TypeScript generation, HTTP, durable execution, events, data, deployment, UI, semantic inspection, and revision-bound mutation.

Unavailable future surfaces—such as declarative extensions, workflows, streaming/WebSockets, full registry trust, entity-evolution syntax, platform listener/certificate schemas, and fixed-target native toolchain identities—fail explicitly instead of receiving invented defaults.

scenery is a Go-native local runtime and toolchain for building service applications from ordinary Go packages.

Applications mark their root with .scenery.json, declare their application graph in .scn, and implement generated native contracts in Go. scenery handles graph compilation, route registration, auth context, request decoding, generated internal calls, local development supervision, inspection, logs, traces, metrics, and TypeScript client generation.

The Go-comment declaration frontend is not supported. The local dashboard, native observability, local HTTPS routing, and durable worker tooling are development-focused capabilities; their backing services and files are substrate details unless you intentionally debug them.

Why scenery?

• One canonical app model. Services, operations, bindings, auth, middleware, durable executions, schedules, data, and UI resources are declared in .scn source.
• Full local dev loop. scenery up runs the app root's one live dev runtime with file watching, rebuild/restart supervision, dashboard, API explorer, logs, traces, metrics, and optional HTTPS local domains.
• Typed HTTP by default. scenery decodes path params, query params, headers, cookies, and JSON bodies into Go structs, then encodes typed responses.
• Generated internal calls. Binding clients preserve private access, auth context, tracing, and delivery semantics.
• Inspectable by tools and agents. scenery inspect, scenery check, scenery logs, scenery harness, and scenery validate expose machine-readable JSON contracts.
• Generated clients and pages. scenery generates typed TypeScript clients plus routed table, content, split, workspace, and entity-detail pages from the same graph.

Status

Available now:

• lossless source, truthful source/effective/expanded graphs with path-indexed provenance, stable revisions, recursive authoring schemas with wire-label policies, schema-driven creation for exactly advertised resource kinds, receipt-proven semantic rename, dependency graph, and normalized agent mutation protocol
• Go contract/application/composition generation and exact TypeScript clients with descriptors, constraints, cross-field validation, canonical HTTP sets, Fetch-safe header validation, declared multipart, and structurally disjoint typed response-map coverage
• exact Go build-input/toolchain identities and runtime-bundle sidecars, with host-CGO native-tool identities and fail-closed fixed-target CGO
• authored CLI execution with generated help/completion and typed outcomes, plus environment-selected typed fixtures shared by deployment and local database seeding
• HTTP, typed terminal zero-or-more path tails, durable execution, schedules, events, data/CRUD/provider, deployment plan/apply, patches, UI validation, and semantic evolution analysis
• workspace-issued, revision-bound semantic change and deployment transactions; apply rejects caller-recomputed plans before trusting approvals, edits, or provider actions
• .scenery.json root discovery
• scenery up, scenery task, scenery validate, scenery build, scenery check
• typed HTTP bindings
• public, auth, and private endpoints
• authentication resources and request auth helpers
• generated typed service constructors
• middleware
• private/internal endpoint calls
• secrets from environment and local .env
• local logs, traces, and metrics inspection
• native local observability
• durable execution and schedule runtime support
• local HTTPS edge and frontend routing with optional trust-store installation
• beta public deploy edge for serving a live local app on your own domain
• dashboard and API explorer
• configured generators, SQLC refresh, database lifecycle commands, and repo task commands
• portable checksummed database-and-storage snapshots with recoverable overwrite loads
• app-local code tasks
• TypeScript client generation
• benchmark fixture

Exact CLI and artifact details live in docs/local-contract.md. The evolving current specification begins at docs/spec/SPEC.md. Agent workflows live in docs/agent-guide.md. Architecture notes live in ARCHITECTURE.md.

Requirements

• Go 1.26+
• Bun, only when working on the dashboard UI or the benchmark fixture

Run scenery doctor -o json after install when you want a read-only readiness report for the host, Go toolchain, disk/memory resources, Docker engine reachability, and optional local-development dependencies.

Install From Source

git clone https://github.com/scenery-sh/scenery.git scenery
cd scenery
go install ./cmd/scenery
scenery doctor -o json
scenery version -o json

The module path is scenery.sh. Source installs are useful when working from a checkout or testing unreleased changes. Release binaries embed the built dashboard UI from apps/console/ and do not build it at runtime. From source, run ./scripts/build-dashboard-ui-embed.sh before go install ./cmd/scenery when the installed binary should carry the current dashboard build.

Prebuilt CLI Binaries

Tagged releases currently publish a prebuilt scenery archive for macOS Apple Silicon (darwin/arm64) on the GitHub Releases page.

After installing a prebuilt binary, verify it with:

scenery version -o json

To update a local prebuilt install later:

scenery upgrade

scenery upgrade verifies the current release archive against checksums.txt, replaces the current local binary, and then syncs managed toolchain entries already present in the local store. Use scenery upgrade --toolchain all when you intentionally want every frozen tool and image from the upgraded binary pulled immediately.

SSH Source-Sync Deployment

For a simple single-server or preview deployment, allow an ordinary OpenSSH host alias in the app config:

{"name":"hello","envs":{"local":{"default":true},"production":{"deploy":{"ssh":["some-id"]}}}}

Then run scenery deploy some-id. Scenery validates locally, connects with passwordless OpenSSH, stops the remote app, rsyncs the current working tree to $HOME/.scenery/apps/hello, and runs remote scenery up --detach --wait ready. The target needs rsync, scenery, and the app toolchain. .git, local .scenery, .env*, node_modules, and Scenery-owned go.work files are not uploaded; .gitignore exclusions are honored, and remote dotenv, .scenery, and editor workspace state are preserved. Deployment has brief downtime and no rollback.

Public Deploy Edge

scenery deploy is a beta operator surface for serving a live app on a public domain from a macOS (launchd) or Linux (systemd, run setup as root) machine. An environment-scoped frontend with serve: "production" is built on the serving host and served directly by the managed Caddy edge as static files; dynamic /api/* traffic stays on the Scenery router.

{"name":"hello","root":"app","frontends":{"app":{"root":"apps/app"}},"envs":{"local":{"default":true},"production":{"domain":"hello.example.com","frontends":{"app":{"serve":"production"}},"deploy":{}}}}

Then configure the machine once, enable the app, and keep a live dev runtime running:

scenery deploy setup --acme-ca staging --acme-email ops@example.com
scenery deploy enable --app-root /path/to/app
scenery up --detach --app-root /path/to/app
scenery deploy status -o json

Detached startup waits for every advertised route and one frontend script or stylesheet by default, so a successful return means the printed URLs are reachable end to end.

Point DNS A/AAAA records at the reported public IP and forward router TCP 80/443 to the reported LAN IP. scenery deploy status -o json reports listener, DNS, reachability, sleep, firewall, certificate diagnostics, and the login-resume job's last exit; a failed resume makes status not ready. Public resume does not depend on optional local.dev wildcard DNS. Switch to --acme-ca production after staging works.

Agent Skill

scenery includes an installable agent skill for using scenery apps:

npx skills add https://github.com/scenery-sh/scenery

The skill teaches agents the current app model, local development workflow, debugging commands, observability, database inspection, and generated-client workflow.

The skill is shared runtime knowledge. Client apps should still keep a small app-local AGENTS.md for app root, frontend roots, generated client output paths, required environment names, validation commands, and product invariants. Do not copy the whole skill into every app; keep shared scenery behavior in SKILL.md and app-specific facts in the client repository.

A Minimal App

Create .scenery.json and go.mod:

{"name":"hello"}

module example.com/hello

go 1.26.3

require scenery.sh v0.0.0

replace scenery.sh => /path/to/scenery

Create app.scn:

workspace {
  implementation_root "application" {
    path = "."
    revision_include = ["**/*.go", "go.mod"]
  }
}

go_module "application" {
  root        = "."
  import_path = "example.com/hello"
}
go_toolchain "application" {
  version     = "1.26.3"
  experiments = []
}
go_target "development" {
  role      = "development"
  platform  = "host"
  toolchain = go_toolchain.application
  module    = go_module.application
  packages  = ["./..."]
  cgo       = "disabled"
}
application "hello" { version = "1.0.0" }
http_gateway "public" {
  exposure        = "internet"
  base_path       = "/"
  cors            = std.cors.none
  trusted_proxies = std.trusted_proxies.none
  forwarded       = std.forwarded_headers.reject
}
module "service" {
  source = "./service"
  inputs = { gateway = http_gateway.public }
}

Create service/package.scn with one service, operation, execution, and HTTP binding:

package "service" {
  go_contract { import_path = "example.com/hello/service" }
}
input "gateway" { type = resource_ref("http_gateway") }
service "service" {
  runtime = "go"
  implementation { constructor = "NewService" }
}
record "hello_input" { field "name" { type = string } }
record "hello_result" { field "message" { type = string } }
operation "hello" {
  service = service.service
  input   = record.hello_input
  handler { method = "Hello" }
  result "ok" { type = record.hello_result }
}
execution "hello_direct" {
  operation = operation.hello
  mode      = "direct"
}
binding "hello_http" {
  gateway   = var.gateway
  operation = operation.hello
  execution = execution.hello_direct
  protocol  = "http"
  delivery  = "call"
  authentication = std.authentication.none
  authorization = std.authorization.public
  pipeline = std.pipeline.empty
  http {
    method        = "POST"
    path          = "/hello"
    codec_profile = std.codec.http_json_v1
    body { codec = "json", to = operation.hello.input }
    response "ok" {
      when   = result.ok
      status = 200
      body { codec = "json", from = result.ok }
    }
  }
}

Implement the generated contract in service/api.go:

package service

import (
	"context"
	contract "example.com/hello/service/scenerycontract"
)

type Service struct{}

func NewService(context.Context, contract.ServiceConstructorInput) (*Service, error) {
	return &Service{}, nil
}

func (*Service) Hello(_ context.Context, input contract.HelloInput) (contract.HelloOutcome, error) {
	return contract.HelloOk{Value: contract.HelloResult{Message: "hello " + input.Name}}, nil
}

Generate, check, and run it:

scenery generate --target go -o json
scenery check -o json
scenery up --detach

Call it (use scenery ps -o json to discover the base URL):

curl -H 'Content-Type: application/json' -d '{"name":"world"}' http://localhost:4001/api/hello

The checked-in native fixture at testdata/apps/basic is the compact runnable reference. .scenery.json configures the runtime; it does not declare application resources.

Local Development

Use scenery up for the full development platform:

scenery up

Common options:

scenery up --port 4000 --listen 127.0.0.1
scenery up -o jsonl
scenery up --detach
scenery system edge dns install
scenery system edge privileged install
scenery system edge install
scenery system edge trust
scenery logs --follow
scenery console

--detach starts the app root's agent-backed dev runtime in the background and, by default, returns after the API and configured frontends are ready; use --wait registered for the faster registration-only path. scenery logs --follow follows that app root's logs from VictoriaLogs. scenery console opens a source-aware terminal console when attached to a real TTY. scenery down stops the app root's one live runtime; for shared storage cells, it releases only that runtime's lease and preserves shared data. Use Git worktrees when you need multiple live code copies.

scenery up runs the single default named environment from .scenery.json (normally local); --env <name> selects another. Top-level root names the frontend served only at / on every surface; when exactly one frontend exists it is the default root. Other frontends remain at /<name>/. Environment fields port, port_start, and port_end constrain its localhost port, domain adds the branded HTTPS origin, expose narrows that origin, and frontends.<name>.serve selects HMR development or built static production serving. A failed domain-edge probe keeps serving localhost and never redirects into another environment.

In host mode, generated routes use the local edge/DNS path under local.dev. Use scenery system edge dns install, scenery system edge privileged install, scenery system edge install, and scenery system edge trust when you want trusted wildcard local HTTPS routes on the default HTTPS port; edge syncs managed dnsmasq and Caddy when needed and keeps Caddy user-owned.

Example frontend config:

{
  "name": "myapp",
  "root": "web",
	"frontends": {
    "web": {
      "root": "apps/web"
    },
    "blog": {
      "root": "apps/blog",
      "upstream": "127.0.0.1:5174"
	},
	"envs": {
	  "local": {"default": true, "mode": "path", "frontends": {"web": {"serve": "development"}, "blog": {"serve": "development"}}}
	}
  }
}

CLI Overview

scenery up [--env <name>] [--port <n>] [--listen <addr>] [--app-root <path>] [--claim-aliases] [--verbose] [-o jsonl] [--detach]
scenery logs --follow [--app-root <path>] [--limit <n>] [--stream all|stdout|stderr] [--source <id>] [--kind <kind>] [--level <level>] [--grep <text>] [--since <duration>] [-o jsonl|-o json]
scenery console [--app-root <path>] [--source <id>] [--kind <kind>] [--level <level>] [--grep <text>] [--since <duration>]
scenery system agent [--socket <path>] [--router-listen <addr>] [--router-tls|--router-http] [--trust] [-o json]
scenery system agent restart [--socket <path>] [--router-listen <addr>] [--router-tls|--router-http] [--trust] [-o json]
scenery system agent cleanup [--remove-state] [-o json]
scenery system edge install|trust|status|restart|uninstall|dns|privileged [-o json]
scenery help <command> [-o human|json]
scenery help all
scenery help -o json
scenery ps [-o json] [--app-root <path>] [--watch]
scenery down [--app-root <path>] [--db] [--state] [--all] [-o json]
scenery prune --older-than <duration> [--app-root <path>] [--db] [--state] [--all] [-o json]
scenery worker [--app-root <path>] [--env <name>] [--log-format text|json]
scenery worker durable --endpoint <url> --token <token> [--service <name>]... [--app-root <path>] [--env <name>] [--log-format text|json]
scenery worker durable jobs list|inspect|cancel|retry [job-id] --service <name> [--app-root <path>] -o json
scenery worker durable token create --service <name> [--name <name>] [--id <id>] [--app-root <path>] -o json
scenery version [-o json]
scenery upgrade [--target <path>] [--toolchain installed|all|none] [--force] [--dry-run] [-o json]
scenery deploy <ssh-target> [--app-root <path>]
scenery deploy --env <name> [--app-root <path>]
scenery deploy enable|disable|status|setup|resume|teardown [-o json]
scenery system toolchain list [-o json] [--include-source-locks] [--images]
scenery system toolchain sync [-o json] [--all] [--tool <name>] [--platform <goos/goarch>] [--images]
scenery system toolchain verify [-o json] [--all] [--tool <name>] [--platform <goos/goarch>] [--images] [--strict]
scenery system toolchain path [-o json] --tool <name> [--platform <goos/goarch>]
scenery doctor [--app-root <path>] [-o json]
scenery build [--app-root <path>] [--output <path>] [-o human|json]
scenery build --lib <name> [--version <vN.N.N>] [--platform all|host|darwin/arm64|linux/amd64] [--app-root <path>] [--output <directory>] [-o human|json]
scenery fmt --check [--app-root <path>] -o json
scenery check [--app-root <path>] -o json
scenery compile [--app-root <path>] [--view source|effective|expanded] -o json
scenery list|get|explain|graph ... [--app-root <path>] -o json
scenery diff --semantic BASE TARGET [--rename-receipts <path>] -o json
scenery generate [--app-root <path>] [--target contracts|typescript_client.<name>] [--materialize] [--prune-materialized-go] [--merge-editor-workspace] [--check] -o json
scenery changes plan|apply ... -o json
scenery generate sqlc [--app-root <path>] [--dry-run] [-o json]
scenery task list [--app-root <path>] [-o json]
scenery task inspect <target> [--app-root <path>] [--lang go|typescript] [-o json]
scenery task run <name> [--app-root <path>]
scenery task run [--app-root <path>] [--env <name>] [--lang go|typescript] <domain>:<name> [-- task args...]
scenery task graph -o json [--app-root <path>]
scenery validate [<profile>] [--app-root <path>] [-o json] [--write] [--dry-run]
scenery validate changed [--base <ref>] [--app-root <path>] [-o json] [--write] [--dry-run]
scenery harness [--app-root <path>] [-o json] [--write] [--with-validation[=<profile>]]
scenery harness self [--repo-root <path>] [-o json] [--write] [--quick|--race|--release] [--fresh-tests]
scenery harness ui -o json [--app-root <path>] [--dashboard-url <url>] [--headed] [--write]
scenery inspect app|routes|services|endpoints|build|paths|durable -o json [--app-root <path>]
scenery inspect docs -o json [--repo-root <path>] [--for-path <path>|--tag <tag>|--status active|reference|completed|deprecated|--review-due|--all]
scenery traces list -o json [--app-root <path>]
scenery metrics list -o json [--app-root <path>]
scenery traces clear -o json [--app-root <path>]
scenery logs [--app-root <path>] [--limit <n>] [--stream all|stdout|stderr] [--source <id>] [--kind <kind>] [--level <level>] [--grep <text>] [--since <duration>] [--follow] [-o jsonl|-o json]
scenery test [--app-root <path>] [go test flags/packages...]
scenery db list [--app-root <path>] [-o json]
scenery db shell [--app-root <path>] [--service <name>] [psql args...]
scenery db apply [--app-root <path>] [-o json]
scenery db seed [--app-root <path>] [--env <name>] [--dry-run] [-o json]
scenery db setup [--app-root <path>] [-o json]
scenery db reset [--app-root <path>] [--service <name>] [--yes]
scenery db drop [--app-root <path>] [--service <name>] [--yes]
scenery db server status|start|stop|logs [-o json] [--yes]
scenery snapshot save --output <file.zip> [--db] [--storage] [--app-root <path>] [-o human|json]
scenery snapshot verify --input <file.zip> [-o human|json]
scenery snapshot load --input <file.zip> [--db] [--storage] --mode overwrite|merge [--on-conflict fail|skip|overwrite] [--yes] [--dry-run] [--app-root <path>] [-o human|json]
scenery worktree create <name> [--from <branch>] [--app-root <path>] [-o json]
scenery worktree list [--app-root <path>] [-o json]
scenery worktree remove <name> [--app-root <path>] [--db] [-o json]

Each invocation best-effort appends command, duration, exit code, version, and oneshot or long_running mode to ~/.scenery/telemetry.jsonl. Full arguments are never recorded, and telemetry write failures never affect the command.

scenery system agent restart restarts only the local control plane and router; registered shared Postgres and Victoria processes keep their PIDs. Destructive substrate shutdown stays with substrate-specific commands.

scenery system agent cleanup stops only fingerprint-verified same-user processes tied to the pre-rebrand ~/.onlava config or socket. It reports old state by default and removes it only with --remove-state.

scenery prune --older-than 14d removes stale runtime records and substrate leases without deleting databases or state. Add --state, --db, or --all for those explicit destructive cleanup scopes; managed database cleanup refuses external DSNs.

The agent and managed Caddy edge are single-owner processes. Startup fails closed instead of choosing an unadvertised port, safely reaps only fingerprint-verified stale Scenery owners, and scenery doctor -o json reports duplicate or foreign listeners.

scenery db list -o json reports the app's Postgres database and service schemas. An explicit app-level DATABASE_URL wins and makes the database external; otherwise scenery up creates one isolated database per app root/worktree on the shared local Postgres dev server, with one schema per configured service plus the scenery schema for framework state.

See docs/local-contract.md for the full command contract and JSON schema list.

Source Or Shared Go Libraries

A package beneath pkg/ can declare a Go library and record-shaped operations in package.scn. Scenery generates one typed scenerylib_<name> facade, so consumers keep the same import and call surface while .scenery.json selects source or shared linkage per environment.

scenery build --lib <name> --version <vN.N.N> emits the supported darwin/arm64 .dylib, linux/amd64 .so, and a portable manifest binding exact platform, digest, ABI, Go version, and Linux glibc floor. Shared mode verifies that identity before loading and supports load-alongside hot swaps; old Go runtimes remain resident and are never unloaded. See the cookbook for the declaration and config recipe.

Public Go Packages

• scenery.sh exposes app metadata and current request metadata.
• scenery.sh/auth exposes request auth state helpers.
• Standard auth owns its tenant tables under the app database's scenery schema; app-local tenants services or tables are product-domain concerns. Google connections store encrypted refresh tokens for app-owned Google API calls through auth.GoogleAccessToken.
• scenery.sh/errs exposes coded errors and HTTP status mapping.
• scenery.sh/library provides the cgo-free verified loader used by generated shared-library facades.
• scenery.sh/durable exposes non-registering durable runtime helpers such as steps and signals; task, execution, and schedule ownership is declared in .scn.
• scenery.sh/db exposes Postgres *sql.DB pools pinned to a service schema for app code and sqlc.
• scenery.sh/datasource and scenery.sh/object expose typed constructor capabilities.

TypeScript Client Generation

Declare each TypeScript target in app.scn. Use materialization = "source" with an output_root beneath a declared managed generated root for a checked-in SDK, or materialization = "cache" for disposable output under .scenery/gen/typescript/<name>, then run:

scenery inspect endpoints -o json
scenery generate --target typescript_client.public_api -o json
scenery generate --target typescript_client.public_api --check -o json

The generated client implements the declared gateway/binding contract.

Add react { tsconfig = "apps/web/tsconfig.json" } to a TypeScript target to opt into generated React apps. Scenery writes page adapters, typed route/search descriptors, a TanStack route-tree adapter, generated navigation, the catalog-owned app shell, and @scenery/ui beneath the same output root, then checks the staged target with managed tsgo. Call createSceneryApp, register any hand-written pages through its descriptor extension, and fill its fixed visual/auth slots; the app does not maintain a parallel router, navigation list, or shell.

WithMeta methods expose response headers, status, and the raw Response alongside decoded data.

scenery generate sqlc remains the configured SQLC source-artifact command; it must not apply database schema or seed data.

The DB lifecycle split uses scenery db apply for schema/app database mutation, scenery db seed for initial data such as SERVICE/db/seed.sql, and scenery db setup for apply then seed. Seed files apply to their matching service schema and fail closed when previously-applied content changes or destructive SQL is detected.

scenery up runs the setup lifecycle before app startup when DB setup inputs exist, using the same managed service database env values that the app receives. Rebuilds skip setup until the apply config or seed file hashes change.

Worktree database isolation is automatic: the managed database name includes a hash of the app root, so scenery worktree create <name> -o json only creates the Git worktree. scenery db reset <service> drops and recreates only that service schema. scenery snapshot save --db --storage --output app.zip writes a portable, checksummed restore point. Stop the runtime before snapshot load; overwrite requires --yes, verifies the whole archive first, and is safe to rerun after an interrupted database restore or storage swap.

scenery snapshot verify --input app.zip validates an archive without a target app or stopped runtime. For scheduled DB+storage backups, use scripts/snapshot-backup.sh from the host scheduler; it verifies before optional rclone replication and local retention.

The default self-harness includes a Docker-gated Postgres probe for the shared server, one app database, service schemas, durable state, auth bootstrap, worktree isolation, service-schema reset, and a database-plus-storage snapshot round-trip.

Managed Toolchain

The root scenery.toolchain.json freezes Scenery-owned local tools, images, plugins, and source lock references for this source version. Managed binaries install under .scenery/toolchain/ by default, while machine-level edge tools install under ~/.scenery/toolchain/; set SCENERY_TOOLCHAIN_DIR to use a controlled cache elsewhere.

scenery system toolchain list -o json
scenery system toolchain sync -o json
scenery system toolchain verify -o json

scenery upgrade uses the upgraded binary's bundled manifest for the post-upgrade toolchain sync, so pinned versions change with the Scenery release instead of ambient system tools.

Caddy edge and Victoria sidecars are backing substrate for local capabilities; Caddy edge is managed-toolchain only. Storage is not a managed substrate: declaring storage.stores makes scenery up serve them from a Scenery-owned local directory tree (atomic writes, checked fsync, sidecar metadata) with no managed process, toolchain artifact, or dev-service entry. Offsite durability is an operator concern — replicate the storage-cell object directories to S3 with rclone/restic (see docs/app-development-cookbook.md). For the managed tools, use documented env overrides, the managed store, scenery ps -o json substrate records, and the recorded stdout/stderr log paths when intentionally debugging them. They do not silently fall back to system PATH binaries.

Observability And Inspection

scenery exposes local development logs, traces, and metrics through app-session capabilities. The current backing substrate can run VictoriaMetrics, VictoriaLogs, and VictoriaTraces for local inspection.

Useful commands:

scenery logs --limit 200
scenery logs --follow
scenery console
scenery logs --source api --level error -o jsonl --limit 200
scenery inspect routes -o json
scenery inspect endpoints -o json
scenery traces list -o json --since 15m --slowest
scenery metrics list -o json --since 1h
scenery ps -o json
scenery harness -o json --write

Victoria substrate failures are exposed in scenery ps -o json as last_exit / component_exits and emit structured dev log events with component, PID, exit code or signal, and log paths. Dead registered runtime children such as managed frontend processes appear as session degraded status with status_reason; managed Vite/Astro frontends are restarted by scenery up when their dev-server process exits unexpectedly.

Development

Run the Go test suite:

go test ./...

Rebuild the CLI after changes:

go install ./cmd/scenery

Run the self-harness when making substantial changes:

scenery harness self -o json --write

Self-harness Go test steps use the Go test result cache by default; add --fresh-tests only for explicit fresh measurement or nondeterminism investigation. That lane uses the locally measured package parallelism -p 3. Timing reports distinguish cached, fresh, and release budgets; only fresh runs confirm package/test hotspots in isolation.

Contributing

scenery prefers small, explicit changes and minimal dependencies. When adding behavior, keep the canonical graph as the source of truth and add tests at stable boundaries: .scn validation, generated code, runtime HTTP behavior, CLI JSON contracts, and fixture apps.

See CONTRIBUTING.md for setup and pull request guidance.

Before opening a pull request, run:

go test ./...
go install ./cmd/scenery

For larger changes, also run:

scenery harness self -o json --write

Security

Please do not open public issues for vulnerabilities. Report security issues to security@scenery.sh. See SECURITY.md.

License

scenery is licensed under the Apache License 2.0.

Documentation

Index

• Constants
• func ApprovalTokenPayload(token ApprovalToken) ([]byte, error)
• func ContractIntConstraint(value int64) *int64
• func ContractStringConstraint(value string) *string
• func DecodeContractOutcomeEnvelope(data []byte) (kind, name string, payload json.RawMessage, err error)
• func DecodeJSONObject(data []byte) (map[string]json.RawMessage, error)
• func EncodeContractCompositeKey(components ...[]byte) (string, error)
• func EncodeContractKeyComponent(value any, typeExpression string) ([]byte, error)
• func MarshalContractOutcomeVariant(kind, name string, value any, typeExpression string) ([]byte, error)
• func MarshalContractValue(value any, typeExpression string) ([]byte, error)
• func UnmarshalContractValue(data []byte, target any, typeExpression string) error
• func UnmarshalContractValueWithNamed(data []byte, target any, typeExpression string, named ContractNamedDecoder) error
• func ValidateApprovalToken(token ApprovalToken) error
• func ValidateContractRecord(fields map[string]any, fieldTypes map[string]string, ...) error
• func ValidateContractValue(value any, typeExpression string, constraints ContractConstraints) error
• type APIDesc
• type AppMetadata
  • func Meta() *AppMetadata
• type ApprovalToken
  • func NewApprovalToken(planID, caller string, riskScopes []string, expiresAt time.Time) ApprovalToken
• type CloudProvider
• type ContractConstraints
• type ContractNamedDecoder
• type ContractValidationError
• type Date
  • func ParseDate(value string) (Date, error)
• type DateTime
  • func ParseDateTime(value string) (DateTime, error)
• type Decimal
  • func ParseDecimal(value string) (Decimal, error)
• type Duration
  • func ParseDuration(value string) (Duration, error)
• type Environment
• type EnvironmentType
• type ExecutionReceipt
• type Int
  • func ParseInt(value string) (Int, error)
• type Invocation
  • func InvocationFromContext(ctx context.Context) (Invocation, bool)
• type JSON
• type Nullable
  • func NullOf[T any]() Nullable[T]
  • func ValueOf[T any](value T) Nullable[T]
• type Optional
  • func NoneOf[T any]() Optional[T]
  • func Some[T any](value T) Optional[T]
• type PathParam
• type PathParams
• type Problem
• type Registry
• type RelativePath
  • func ParseRelativePath(value string) (RelativePath, error)
• type Request
  • func CurrentRequest() *Request
• type RequestType
• type SecretRef
• type Set
• type Size
  • func ParseSize(value string) (Size, error)
• type URL
  • func ParseURL(value string) (URL, error)
• type UUID
  • func ParseUUID(value string) (UUID, error)
• type Unit

Constants

const (
	EnvProduction  = shared.EnvProduction
	EnvDevelopment = shared.EnvDevelopment
	EnvEphemeral   = shared.EnvEphemeral
	EnvLocal       = shared.EnvLocal
	EnvTest        = shared.EnvTest
	CloudAWS       = shared.CloudAWS
	CloudGCP       = shared.CloudGCP
	CloudAzure     = shared.CloudAzure
	CloudLocal     = shared.CloudLocal
	None           = shared.None
	APICall        = shared.APICall
	InternalCall   = shared.InternalCall
	RawAPICall     = shared.RawAPICall
)

Functions

func ApprovalTokenPayload

func ApprovalTokenPayload(token ApprovalToken) ([]byte, error)

ApprovalTokenPayload returns the canonical bytes an approval service signs.

func ContractIntConstraint

func ContractIntConstraint(value int64) *int64

func ContractStringConstraint

func ContractStringConstraint(value string) *string

func DecodeContractOutcomeEnvelope

func DecodeContractOutcomeEnvelope(data []byte) (kind, name string, payload json.RawMessage, err error)

DecodeContractOutcomeEnvelope validates a closed durable outcome envelope and returns a defensive copy of its schema-directed payload.

func DecodeJSONObject

func DecodeJSONObject(data []byte) (map[string]json.RawMessage, error)

DecodeJSONObject is the strict object decoder used by generated contract records.

func EncodeContractCompositeKey

func EncodeContractCompositeKey(components ...[]byte) (string, error)

func EncodeContractKeyComponent

func EncodeContractKeyComponent(value any, typeExpression string) ([]byte, error)

EncodeContractKeyComponent preserves the schema type and presence state of one idempotency or concurrency-key component.

func MarshalContractOutcomeVariant

func MarshalContractOutcomeVariant(kind, name string, value any, typeExpression string) ([]byte, error)

MarshalContractOutcomeVariant encodes one closed operation outcome using a stable envelope suitable for durable storage and wait delivery.

func MarshalContractValue

func MarshalContractValue(value any, typeExpression string) ([]byte, error)

MarshalContractValue applies the schema-directed contract JSON wire representation. Generated contract packages use it for record fields so exact integers, nested collections, and sets never fall back to Go's lossy/default encoding choices.

func UnmarshalContractValue

func UnmarshalContractValue(data []byte, target any, typeExpression string) error

UnmarshalContractValue decodes one schema-directed contract value into target. Target must be a non-nil pointer.

func UnmarshalContractValueWithNamed

func UnmarshalContractValueWithNamed(data []byte, target any, typeExpression string, named ContractNamedDecoder) error

func ValidateApprovalToken

func ValidateApprovalToken(token ApprovalToken) error

ValidateApprovalToken enforces the current scenery.approval-token shape and signature encoding before a caller attempts trust-root verification.

func ValidateContractRecord

func ValidateContractRecord(fields map[string]any, fieldTypes map[string]string, encodedProgram, code, message, path string) error

ValidateContractRecord evaluates a compiler-validated, data-only expression over generated record fields. The public runtime deliberately does not include the HCL compiler; generated packages carry the compiled expression.

func ValidateContractValue

func ValidateContractValue(value any, typeExpression string, constraints ContractConstraints) error

ValidateContractValue enforces one field's contract constraints against the generated Go representation.

Types

type APIDesc

type APIDesc = shared.APIDesc

type AppMetadata

type AppMetadata = shared.AppMetadata

func Meta

func Meta() *AppMetadata

type ApprovalToken

type ApprovalToken = contract.ApprovalToken

ApprovalToken is a detached, plan-bound authorization for explicitly named risk scopes. Signature is excluded from ApprovalTokenPayload.

func NewApprovalToken

func NewApprovalToken(planID, caller string, riskScopes []string, expiresAt time.Time) ApprovalToken

NewApprovalToken creates the current detached approval shape. The caller signs ApprovalTokenPayload and then fills Signature.

type CloudProvider

type CloudProvider = shared.CloudProvider

type ContractConstraints

type ContractConstraints = contract.ContractConstraints

ContractConstraints is emitted by generated contract packages. Pointer fields distinguish an absent limit from an explicit zero limit.

type ContractNamedDecoder

type ContractNamedDecoder = contract.ContractNamedDecoder

ContractNamedDecoder lets a generated package provide codecs for named tagged unions while the shared runtime continues to recurse through optional, nullable, collection, map, and tuple wrappers.

type ContractValidationError

type ContractValidationError = contract.ContractValidationError

ContractValidationError is a declared record-validation failure. Code, message, and path come from the named validation block in the contract.

type Date

type Date = contract.Date

func ParseDate

func ParseDate(value string) (Date, error)

type DateTime

type DateTime = contract.DateTime

func ParseDateTime

func ParseDateTime(value string) (DateTime, error)

type Decimal

type Decimal = contract.Decimal

Decimal preserves an exact coefficient and base-10 scale.

func ParseDecimal

func ParseDecimal(value string) (Decimal, error)

type Duration

type Duration = contract.Duration

func ParseDuration

func ParseDuration(value string) (Duration, error)

type Environment

type Environment = shared.Environment

type EnvironmentType

type EnvironmentType = shared.EnvironmentType

type ExecutionReceipt

type ExecutionReceipt = runtimeapi.ExecutionReceipt

type Int

type Int = contract.Int

Int is the arbitrary-precision integer used by Scenery contracts.

func ParseInt

func ParseInt(value string) (Int, error)

type Invocation

type Invocation = runtimeapi.Invocation

func InvocationFromContext

func InvocationFromContext(ctx context.Context) (Invocation, bool)

type JSON

type JSON = json.RawMessage

type Nullable

type Nullable[T any] = contract.Nullable[T]

Nullable distinguishes a present null from a present concrete value.

func NullOf

func NullOf[T any]() Nullable[T]

func ValueOf

func ValueOf[T any](value T) Nullable[T]

type Optional

type Optional[T any] = contract.Optional[T]

Optional distinguishes an absent field from a present zero value.

func NoneOf

func NoneOf[T any]() Optional[T]

func Some

func Some[T any](value T) Optional[T]

type PathParam

type PathParam = shared.PathParam

type PathParams

type PathParams = shared.PathParams

type Problem

type Problem = contract.Problem

type Registry

type Registry = runtimeapi.Registry

Registry is the generated-adapter registration boundary.

type RelativePath

type RelativePath = contract.RelativePath

func ParseRelativePath

func ParseRelativePath(value string) (RelativePath, error)

type Request

type Request = shared.Request

func CurrentRequest

func CurrentRequest() *Request

type RequestType

type RequestType = shared.RequestType

type SecretRef

type SecretRef = contract.SecretRef

type Set

type Set[T any] = contract.Set[T]

Set is represented canonically by generator/runtime adapters.

type Size

type Size = contract.Size

func ParseSize

func ParseSize(value string) (Size, error)

type URL

type URL = contract.URL

func ParseURL

func ParseURL(value string) (URL, error)

type UUID

type UUID = contract.UUID

func ParseUUID

func ParseUUID(value string) (UUID, error)

type Unit

type Unit = contract.Unit

Unit is the canonical value for a contract with no semantic fields.