NetScript

The enterprise-grade meta-framework for Deno: contract-first, end-to-end typed, cloud-agnostic — one unified API from typed services and durable workflows to orchestration, observability, and deploy.

What Laravel is to PHP, NetScript aims to be for the TypeScript backend: one coherent framework where today you assemble a stack.

Define your API once as an oRPC contract. The typed Hono service and the typed SDK clients both derive from it — server and callers cannot drift apart. Background jobs, sagas, triggers, event streams, auth, and AI install as first-party plugins behind the same unified API. .NET Aspire brings the whole graph up locally with one command. And it ships: from a single compiled binary to a multi-cloud distributed infrastructure, with observability on by default — one toolchain shared by you and the coding agent you work with.

NetScript is a framework and workspace generator, not a hosted service — you run it on Deno and own all the generated code.

Beta. NetScript is in beta and moving quickly — pin your versions.

---

🚀 Quickstart

You need Deno 2.9+ and the .NET Aspire CLI (or skip orchestration with --no-aspire). Docker provisions Postgres and the cache.

# 1. Install the NetScript CLI on your PATH
deno install --global --allow-all --name netscript jsr:@netscript/cli@<version>

# 2. Scaffold a workspace: contracts + a typed example service + Postgres + Aspire orchestration
netscript init my-app --db postgres --service --yes

The scaffold reports 183 files, 44 directories and prints your numbered next steps — follow them:

# 3. Boot the whole stack: Postgres, cache, and every service come up together
cd my-app/aspire
aspire restore   # one-time: downloads the AppHost SDK modules
aspire start     # starts everything and prints the dashboard URL

Open the dashboard, wait until the postgres resource reports healthy, then initialize the database:

# 4. Initialize the database (from the workspace root)
cd ..
netscript db init --name init
netscript db generate
netscript db seed

The payoff: the Aspire dashboard shows every resource, trace, and log in one place, and your typed service answers on its health probe:

curl http://localhost:3000/health
# {"status":"healthy","timestamp":"…","checks":[{"name":"database","healthy":true,"latency":2}],…}

Want to check the blast radius before anything touches disk? netscript init my-app --dry-run reports the file and directory counts it would create and writes nothing. Run netscript --help or read the CLI reference for all 11 command groups (init, db, generate, plugin, service, deploy, agent, contract, config, marketplace, ui:*).

---

🗺️ One contract, four moves

One contract flows outward: up into typed clients and the UI, down into the service runtime, the plugins, and the Aspire-provisioned platform.

flowchart TD
  AGENT["Developer + coding agent<br/>netscript CLI · skills · MCP server"]
  UI["Fresh UI + @netscript/sdk<br/>islands · typed oRPC clients · cached queries"]
  CONTRACT["@netscript/contracts<br/>one oRPC contract — the single source of truth"]
  SVC["@netscript/service<br/>Hono + oRPC · health probes · OpenAPI · tracing · graceful shutdown"]
  PLUGINS["First-party plugins<br/>auth · workers · sagas · triggers · streams · ai"]
  PLATFORM["@netscript/aspire + data layer<br/>Postgres · cache · service discovery · dashboard · OTLP telemetry"]

  AGENT -->|"scaffolds · regenerates · observes"| CONTRACT
  UI -->|"typed RPC"| SVC
  CONTRACT --> SVC
  CONTRACT --> UI
  SVC --> PLUGINS
  PLUGINS --> PLATFORM
  SVC --> PLATFORM

Loading

The mental model: contract → service → plugins → platform. You author the contract; defineService turns it into a running Hono + oRPC app; plugins add durable capabilities behind the same contract style; @netscript/aspire provisions and connects the infrastructure — keeping the Aspire SDK behind an adapter so no .NET type ever appears in a public signature. Where a service lives is resolved at call time from orchestrator-injected environment variables, so the same client code runs against local processes, containers, and deployed endpoints with no registry or config file. Telemetry stitches scheduler → queue → worker → RPC → SSE spans into one distributed trace using Deno's built-in OTLP exporter — zero OpenTelemetry SDK dependency by default.

---

🔋 Batteries no frontend framework ships

Durable jobs, compensating sagas, trigger ingress, replayable streams, pluggable auth, an in-process AI surface — first-party plugins, in the box. Not the integration project that Next.js, Nuxt, SvelteKit, or Angular leave you to assemble around the frontend.

NetScript does not try to be everything. It aims to be the right tool for the right job — and it gets there through the plugin system. A plugin is, at its core, a manifest: plain, validated data declaring what it contributes, inspected by hosts without executing plugin code. One manifest can contribute across every layer — CLI verbs, scaffolded code, runtime services, storage, stream topics, telemetry, Aspire resources — and the host materializes whatever it declares. One command, four plugin files scaffolded and twelve Aspire helpers regenerated:

netscript plugin install worker --name workers
# Installed worker plugin "workers" on port 8091.
# Created 4 plugin files.
# Regenerated 12 Aspire helper files.

The same mechanism that ships the six first-party plugins below is how a team extends the framework for its own needs — no host edits, no forks.

Plugin	What it gives you
workers	Durable jobs and workflows; tasks in 4 runtimes (Deno, PowerShell, Python, shell) with at-least-once delivery keyed on idempotencyKey
sagas	Durable multi-step workflows with compensation — saga state persists, so a crash mid-flow resumes instead of stranding half-applied effects
triggers	Webhook, scheduled, and file-watch ingress with ack-then-process semantics, idempotency, retry, and dead-lettering
streams	Durable, replayable typed topics with no database required — the common pipe the other plugins publish to
auth	One auth API with swappable backends (kv-oauth, workos, better-auth), auth schema, and durable session streams
ai	An app-owned, in-process chat/tool/agent surface — the agent loop runs inside your server process, no AI gateway, no extra network hop

---

📦 Packages

The monorepo publishes 29 packages and 6 first-party plugins to JSR as small, single-purpose @netscript/* packages — adopt only the layers you need. Add any of them with deno add jsr:@netscript/<name>@<version>.

Published package map (name → README → JSR)

Foundation core

Package	JSR	Capability
@netscript/contracts		Contract primitives, shared error map, CRUD generators, query/transform helpers
@netscript/config		Typed project config schemas, loaders, env helpers, scaffold constants
@netscript/logger		Structured logging for services, packages, workers, and Hono + oRPC
@netscript/sdk		Service discovery, typed oRPC clients, cache-backed query factories
@netscript/runtime-config		Hot-reloadable runtime override types, loaders, watchers, diagnostics
@netscript/telemetry		One distributed trace across scheduler, queue, worker, RPC, and SSE

Data, messaging & scheduling

Package	JSR	Capability
@netscript/kv		Reactive key-value abstraction over Redis, Deno KV, and in-memory
@netscript/database		DB adapter contracts, Prisma driver helpers, tracing, schema tooling
@netscript/prisma-adapter-mysql		Prisma driver adapter for MySQL / MariaDB on Deno
@netscript/queue		Provider-agnostic message queue with Deno KV, Redis, and RabbitMQ adapters
@netscript/cron		Runtime-agnostic cron scheduling abstraction for Deno
@netscript/watchers		Composable file-watching runtime — strategies, filters, stability, stop

AI & agent tooling

Package	JSR	Capability
@netscript/ai		Zero-dependency AI engine core: model/tool registries, bounded agent loop, MCP client
@netscript/mcp		MCP server: 13 token-bounded tools for monitoring, debugging, and operating an app

Plugin system

Package	JSR	Capability
@netscript/plugin		Plugin manifest builder, validation, discovery, and host-context contracts
@netscript/plugin-ai-core		Contract-only core for the AI plugin: typed routes for chat, models, tools, embeddings
@netscript/plugin-auth-core		Auth plugin contracts, backend ports, stream/config schemas, testing primitives
@netscript/plugin-workers-core		Job / task / workflow / runtime / config / testing primitives for workers
@netscript/plugin-sagas-core		Saga DSL, runtime ports, adapters, telemetry, config, testing primitives
@netscript/plugin-triggers-core		Trigger DSL, runtime ports, adapters, telemetry, config, testing primitives
@netscript/plugin-streams-core		Schema / producer / config / telemetry / testing primitives for streams

Runtime plugins

Package	JSR	Capability
@netscript/plugin-auth		Unified auth API, single-active backend selection, auth DB schema, session streams
@netscript/plugin-workers		Background job scheduling, multi-runtime task execution, workers API
@netscript/plugin-sagas		Durable saga orchestration with compensation, workflow APIs
@netscript/plugin-triggers		Trigger ingress, scheduling, file watching, trigger runtime APIs
@netscript/plugin-streams		Durable streams service with CLI, Aspire wiring, and scaffolding
@netscript/plugin-ai		In-process chat/tool/agent surface scaffolded into your app

Auth backends

Package	JSR	Capability
@netscript/auth-kv-oauth		KV-backed OAuth2 / OIDC AuthBackendPort backend
@netscript/auth-workos		WorkOS AuthKit authenticators
@netscript/auth-better-auth		better-auth integration helpers

Application surface

Package	JSR	Capability
@netscript/aspire		appsettings.json → validated Aspire resource graphs, SDK-neutral by contract
@netscript/service		defineService: Hono + oRPC runtime, health probes, OpenAPI, graceful shutdown
@netscript/fresh		Fresh runtime extensions, builders, forms, defer primitives, route contracts
@netscript/fresh-ui		Design-system components rendered server-side, hydrated in the browser
@netscript/cli		The netscript binary: scaffold, generate, plugin, db, deploy, and agent commands

---

🚢 Ship anywhere

The same app model spans the whole spectrum: a single compiled binary on one machine today, a multi-cloud distributed infrastructure tomorrow — and, coming next, a native desktop app on a consumer machine. Cloud-agnostic by design: every target is an adapter behind one router, and more lanes follow the same contract as the framework grows.

netscript deploy <target> <op> is one thin router over target adapters sharing a canonical lifecycle (plan, up, down, with status/logs on the targets that honour them — netscript deploy list inventories the installed targets; check netscript deploy <target> --help for the exact operations each one ships). Cloud auth stays operator-owned: NetScript mints no credentials and hand-authors no Helm/Bicep/Kubernetes manifests.

Target	Lane
Docker / Compose	Container image and multi-resource Compose lanes with status/logs
OS services	deno compile → single binary managed as a Linux or Windows service
Deno Deploy	deno deploy with a preflight guard that refuses a --prod push using unsupported APIs
Kubernetes / Azure (ACA, App Service, AKS)	Validates the generated AppHost declares the matching hosting integration, then delegates to Aspire publish/deploy
Cloud Run	Docker-image lane: build → push → gcloud run deploy

Coming next: native desktop lane

A native desktop deploy target is landing: deploy desktop package builds native installers per OS (.app/.dmg, .AppImage/.deb/.rpm, .msi), an Ed25519-signed update-manifest release server prepares and serves updates, and an SDK auto-update seam surfaces update-ready events in the app.

---

🤖 Built for devs working with agents

Not a framework for agents instead of developers — a framework for developers who work with one. The properties that make NetScript easy for you to adopt, review, and debug — one unified API, typed end to end, reference docs generated from source — are exactly what make it legible to a coding agent. So the agent tooling ships first-party, with you in control. One command wires it in:

netscript agent init

It auto-detects your agent host, writes the MCP config (.mcp.json for Claude Code, .vscode/mcp.json for VS Code) pointing at netscript agent mcp, and installs the NetScript skill bundle — all pinned to the installed CLI version, so the tool catalog the agent sees always matches the release it runs.

• MCP is the eyes. @netscript/mcp exposes 13 token-bounded tools — app status, run inspection, recent errors, service/database performance analysis, doctor, docs search, and command execution — over stdio. Every result is capped server-side (50 items, 2,000 characters per string) so telemetry never floods the context window, and tools classify traces into worker/saga/trigger/stream/service domains and correlate whole executions by id.
• Skills are the playbook. agent init installs three content-hashed skills (netscript, netscript-operate, netscript-build) shipped with the same release as the CLI.
• The CLI is the hands. The MCP execute_command tool shells the real CLI through a default-deny policy gate: 17 allowed command prefixes, 6 explicit denies (deploy, init, marketplace, db reset, plugin remove, ui:remove), deny beats allow, anything unmatched is denied.

You review the agent's work the way you review a colleague's: type-checked changes, one correlated trace per execution, and a command gate where high-risk operations like deploy, init, and db reset sit behind an explicit deny list — deny beats allow, unmatched commands are denied. The server runs on Deno 2.9+ with a minimal stdio JSON-RPC transport — no npm MCP SDK in the dependency graph — and complements Aspire's own MCP server rather than replacing it: Aspire speaks resources and containers; this server speaks your app.

---

📖 Documentation

Full guides live at rickylabs.github.io/netscript, organized in four lanes: tutorials teach a path end to end, how-to guides are the recipe when you know the path, reference pages give exact symbols and signatures (generated from source with deno doc, so they always describe the published surface), and explanation pages carry the design reasoning.

Start here: Why NetScript · Quickstart · Architecture overview · Glossary

Five tutorial tracks — each builds one complete application from a fresh netscript init and ends by running it locally under .NET Aspire:

• Live dashboard
• AI chat
• Workspace
• Storefront
• ERP sync

Then: How-to guides (28 task-focused recipes, from adding a plugin to building a desktop frontend) · Reference · Explanation · CLI reference

---

🧭 Status

NetScript is in beta and moving quickly. The published package surface is the contract: what you import from jsr:@netscript/* is what's documented and type-checked. Follow what's landing next via the milestones, issues, and discussions.

---

🤝 Contributing

NetScript is built in the open. Start with CONTRIBUTING.md, the Code of Conduct, and the security policy. Bug reports and feature proposals belong on the issue tracker.

---

📝 License

Apache-2.0 — see LICENSE. Every published @netscript/* package ships to JSR with provenance.