The plugin authoring contract for NetScript: a fluent definePlugin builder producing type-safe
manifests that host tooling turns into runtime files, services, and Aspire resources.
Every NetScript plugin — workers, sagas, triggers, streams, auth, AI, and yours — is at its core a
manifest: plain, validated data declaring what the plugin contributes to an app. This package is
where that contract lives. definePlugin gives authors a chainable, type-narrowing builder;
inspectPlugin and verifyPlugin give hosts and tests a way to interrogate any manifest without
executing it. If you are building a plugin or a tool that consumes plugins, this is the package you
build against.
Because manifests are data, the whole ecosystem stays inspectable: the CLI scaffolds from them, Aspire wiring is generated from them, and marketplace tooling reads them — all without running plugin code.
- A builder that catches mistakes at compile time —
definePlugin(name, version)returns a chainable, type-narrowingPluginBuilder;.build()yields a schema-validatedPluginManifestwith typedPluginErrorclasses for invalid or duplicate definitions. - A rich contribution vocabulary — declare services, background processors, stream topics, database schemas, migrations, runtime-config topics, and telemetry as typed contribution axes.
- Typed cross-plugin dependencies —
.withDependencies({...})registers sibling plugins by alias and threads aDependencyContextinto contribution callbacks. - Inspection without execution —
inspectPluginreturns a JSON-stable report for a manifest, registry, or path target;verifyPluginchecks a manifest against declared expectations. - One service identity contract —
PrincipalandServiceHandlerContextare owned by@netscript/service; the plugin root and./serviceentrypoint re-export those same types rather than defining plugin-local copies. - Focused subpaths for every consumer — host tooling, CLI command groups, discovery, abstract bases, protocol, templates, and test fixtures each get their own entrypoint, so nobody imports more than they need.
flowchart LR
A["Plugin author<br/>definePlugin(...).build()"] --> M["PluginManifest<br/>(validated data)"]
M --> C["NetScript CLI<br/>install · sync · doctor"]
M --> G["Generated wiring<br/>files · registries · Aspire"]
M --> I["inspectPlugin / verifyPlugin<br/>(tests, tooling, marketplace)"]
deno add jsr:@netscript/plugin@<version>Pin <version> to match your installed CLI; bare jsr:@netscript/* specifiers do not resolve on
the pre-release line.
import { definePlugin, inspectPlugin } from '@netscript/plugin';
const plugin = definePlugin('@example/billing', '0.0.1-alpha.0')
.withDescription('Billing service and invoice processor.')
.withService({
name: 'billing-api',
entrypoint: 'services/api/main.ts',
})
.build();
console.log(inspectPlugin(plugin).summary);Contribution methods such as .withService(...) accumulate plain data; .build() validates the
whole manifest at once, so a malformed contribution fails the build with a typed error rather than
surfacing later inside a host.
Plugin authors can import service identity types from the plugin surface when a contribution names them directly:
import type { Principal, ServiceHandlerContext } from '@netscript/plugin';
type BillingContext = ServiceHandlerContext<{ readonly tenantId: string }>;
function requirePrincipal(context: BillingContext): Principal {
if (!context.principal) {
throw new Error('authenticated principal required');
}
return context.principal;
}These are re-exports of the public @netscript/service contracts. The service package remains the
owner, and ServiceHandlerContext.principal remains optional so unguarded handlers and existing
plugin services are unaffected. Narrow the principal in handlers that require identity; do not add a
second plugin-specific principal shape.
@netscript/plugin/health exports ChildHealthState, ChildHealthSnapshot, ChildFatalError,
ChildHealthMonitor, CHILD_CRASH_LOOP_THRESHOLD, childHealthResponse, and
runChildHealthProcess.
import { ChildHealthMonitor } from '@netscript/plugin/health';
const health = new ChildHealthMonitor();
health.registryLoaded();
health.dependenciesReady();
health.running();
console.log(health.snapshot().state); // readyThe closed state vocabulary is starting | ready | degraded | crash-looping | stopped | failed. The
payload also reports registryReady, dependencyReady, cumulative restartCount, and
lastFatalError (a fixed redacted message plus an epoch-millisecond timestamp, or null). Registry
readiness means the generated definitions were loaded and validated. Dependency readiness includes
runtime registration, startup checks, and listener failures, rather than a continuous
backing-service heartbeat.
By default, three restarts within 60 seconds, including the window boundary, latch
crash-looping. Recovery requires a full 60 seconds of uninterrupted running with both readiness
fields true; a brief retry cannot turn the child green. A new failure resets the clean window, and
clean shutdown reports stopped. Restart history retains at most the configured number of
timestamps. Health responses return HTTP 200 only for ready with both readiness fields true; all
other states return HTTP 503. Raw exception messages, stacks, credentials, and definition data never
enter this payload.
Generated sagas and triggers retain this history across process replacements in
.data/child-health/sagas.json and .data/child-health/triggers.json, relative to the background
service's working directory. The project already ignores .data/. The first boot does not count as
a restart. A recorded fatal failure counts on the next boot, including Deno watch reloads in the
same OS process. An unclean replacement with a different process identity also counts. Ordinary
healthy watch reloads and a restart after clean shutdown do not count. At the third restart in the
window, /health reports crash-looping and HTTP 503 during bootstrap and after brief successful
starts. A single failed boot followed by stable running stays ready.
Configure the threshold through the health monitor options and pass the same monitor to runtime and process transport:
import { ChildHealthMonitor, runChildHealthProcess } from '@netscript/plugin/health';
const health = new ChildHealthMonitor(Date.now, {
crashLoopThreshold: { restarts: 5, windowMs: 120_000 },
});
await runChildHealthProcess(
async (monitor, signal) => {
monitor.registryLoaded();
monitor.dependenciesReady();
monitor.running();
await new Promise<void>((resolve) => {
if (signal.aborted) resolve();
else signal.addEventListener('abort', () => resolve(), { once: true });
});
},
undefined,
{ health, restartHistoryPath: '.data/child-health/custom.json' },
);Both threshold values must be positive; the restart count must be a safe integer and the window must
be finite. TriggerHealthMonitor accepts the same options as its second constructor argument. Each
history path has one process owner: replicas need separate paths on persistent local storage. The
service needs read/write access to the parent directory. FileChildRestartHistory atomically
replaces a versioned record, storing only process identity, failure status, bounded timestamps and
restart accounting. A missing record means first boot; corrupt, oversized or unwritable history
fails health closed. Storage loss resets process history, so ephemeral filesystems and distributed
replica detection are outside this local guarantee. Healthy polling reads memory; it does not read
the filesystem. A complete live ready window clears the stored latch; downtime never counts as
recovery. Workers retain their existing in-process listener restart budget and health behavior.
To extend storage, implement the synchronous ChildRestartHistoryPort and call
health.trackProcess(history, processId) before bootstrap. Synchronous writes ensure abrupt
termination cannot skip a pending accounting write. Read this section as the contributor entry
point, then run the generated-process regressions in tests/health/generated-crash-loop_test.ts.
Generated workers, triggers, and sagas glue starts the health listener before bootstrap. The
listener binds 127.0.0.1 by default. PORT selects the port; without it, the operating system
assigns an ephemeral port. Pass ChildHealthProcessOptions.hostname: '0.0.0.0' when container
health checks must reach the listener from another network namespace. Generated workers, sagas and
triggers forward NETSCRIPT_CHILD_HEALTH_HOSTNAME to that option, so a container launch can set it
to 0.0.0.0 without editing generated glue. Leave it unset for loopback probes, including the
generated Aspire executable launches.
On a stop signal, runChildHealthProcess gives work 30 seconds to drain and reserves five more
seconds for onShutdown resource callbacks and the health listener. drainTimeoutMs bounds the
whole shutdown (default 35_000); cleanupTimeoutMs reserves part of that total (default
min(5_000, drainTimeoutMs / 5)). Every cleanup is attempted even if work or another cleanup hangs.
Generated roles close the shared KV/Redis connection with closeKv() and dispose database clients
actually acquired by the host bootstrap, without opening unused clients during shutdown.
Exit codes are 0 for a clean drain, 1 for a fatal runtime or cleanup failure, and 2 when work
or cleanup exceeds its deadline. Fatal bootstrap causes are logged to stderr and remain visible as
red health for one second before shutdown begins. exitOnShutdown: false leaves termination to an
embedding host: clean shutdown returns and failures reject with PluginError.
The optional PluginServiceContext.dispose callback belongs to the host. The context factory
memoizes it but never closes lazy KV or database accessors implicitly. A service signal runs that
callback in the reserved cleanup phase. Manual service stop and external cancellation leave
process-owned disposal to the embedding host.
| Entry | What it gives you |
|---|---|
. |
definePlugin, PluginBuilder, inspectPlugin, verifyPlugin, Principal, ServiceHandlerContext, the manifest schema, and the typed error classes |
./health |
Background child state, bounded restart policy, and the child HTTP health transport |
./adapter |
The adapter seam deployable plugins expose and hosts drive |
./config |
Configuration surfaces for host tooling |
./cli |
Plugin CLI command-group plumbing and argument parsing |
./sdk |
Plugin discovery for external tooling |
./contract-base |
The base oRPC contract every plugin API contract extends |
./abstracts |
Abstract bases marking plugin extension points |
./testing |
Fixtures for exercising manifests and adapters in tests |
./loader |
The host-side plugin loader entrypoint |
./service |
Plugin service composition plus the service-owned Principal and ServiceHandlerContext types |
The always-current symbol list is
deno doc jsr:@netscript/plugin@<version> (pin <version>
on the pre-release line, as above).
Hosts compose many manifests. validatePluginComposition rejects duplicate plugin names, unknown
contribution keys, colliding contribution identities, and missing or version-mismatched
dependencies. It returns structured diagnostics instead of throwing. createPluginHostBootstrap,
the CLI host loader, and netscript generate aspire run the same check, so you do not need your own
axis allowlist.
import { definePlugin, validatePluginComposition } from '@netscript/plugin/config';
const result = validatePluginComposition([
definePlugin('@example/a', '1.0.0').withService({ name: 'api', entrypoint: './a.ts' }).build(),
definePlugin('@example/b', '1.0.0').withService({ name: 'api', entrypoint: './b.ts' }).build(),
]);
if (!result.ok) {
for (const diagnostic of result.diagnostics) console.error(diagnostic.code, diagnostic.message);
}Breaking: unknown contribution keys now fail validation; they are no longer ignored. Rename a misspelled key to the documented one. The per-key identity and scope rules are listed in the plugin reference.
Each plugin owns its discovery declaration. Its generated control-plane module exports the factory
name and registry axis that AstExtractor reads from the same files it already walks:
export const NETSCRIPT_CONTRIBUTION_BUILDERS = [
{ callee: 'defineChannelSync', axis: 'channel-syncs' },
] as const;External tooling can also add a plugin's contribution factory to one discovery run without changing source files:
import { type AstExtractorOptions, startWalker } from '@netscript/plugin/sdk';
const options = {
additionalBuilders: [
{ callee: 'defineChannelSync', axis: 'channel-syncs' },
],
} satisfies AstExtractorOptions;
const registries = await startWalker('.', options);Official core packages publish factory-owned patterns at their /discovery subpath. The CLI
composes these patterns through additionalBuilders before walking any project; install and sync
render each plugin's control-plane declaration from the same metadata. The generic SDK contains no
plugin-specific factory table. Published core dependencies are not walked. Additional mappings are
snapshotted per extractor instance. Malformed identifiers, blank axes, conflicting declarations for
a callee, and a recognizable contribution factory call without a matching declaration throw a
TypeError instead of silently omitting contributions.
This changes the migration boundary for projects scaffolded before 0.0.7: re-run plugin sync or
update so each installed plugin's control-plane module receives its declaration before using
no-argument discovery. Updates validate the staged, regenerated modules, so older workers and
triggers installations can acquire their missing declarations during the update itself. Passing
additionalBuilders is the explicit compatibility path when regeneration is not available.
A host using the published @netscript/plugin-sagas-core in-process does not need a saga plugin
service. Put this literal declaration in a TypeScript module inside the walked project, for example
discovery.ts at the project root. It need not be imported by the application. Discovery reads
source text; it does not traverse published dependency imports to find metadata.
export const NETSCRIPT_CONTRIBUTION_BUILDERS = [
{ callee: 'defineSaga', axis: 'sagas' },
{ callee: 'defineStreamSchema', axis: null },
] as const;defineSaga produces an id-bearing definition for the sagas registry. defineStreamSchema
returns a collection schema map consumed by the durable stream producer; it has no contribution id.
axis: null explicitly declares a non-registry factory: discovery validates its declaration and
excludes its values before the id-based registry emitter. Do not invent a schema axis or an id. The
streams control-plane module now emits this exclusion during installation. Identical metadata from a
host and a control module is accepted; conflicting axes still fail. Tooling can also pass either
declaration through additionalBuilders.
The CLI supplies first-party metadata even for core-only hosts and older installed control modules.
Single-plugin updates succeed in either order: plugin update streams then plugin update workers,
or workers then streams. No bulk update or host workaround is required. Standalone SDK tooling still
passes the core package patterns through additionalBuilders or supplies literal declarations.
plugin update runs installation in an isolated copy of the project, then walks that updated tree
and resolves every registry emission before applying changes to the live project. New declarations
and contribution files participate in the same walk. An undeclared factory, malformed declaration,
or extraction/emission failure leaves existing files byte-identical and creates no installation
files in the live project. The temporary tree is removed on success or failure. This guarantee
covers discovery failures; applying files retains normal filesystem error behavior.
SDK compatibility: ContributionBuilderPattern.axis is now string | null; tooling reading this
property must narrow axis !== null before using it as a string.
- Plugin reference — builder, contributions, and inspection: rickylabs.github.io/netscript/reference/plugin/
- Orchestration & Runtime — how manifests become running apps: rickylabs.github.io/netscript/orchestration-runtime/
- How-to — author a plugin: rickylabs.github.io/netscript/how-to/author-a-plugin/
- API docs on JSR: jsr.io/@netscript/plugin/doc
Manifests and the builder are plain TypeScript — importable in any TypeScript environment, including Node.js and Bun via JSR's npm compatibility. The loader and CLI plumbing target Deno 2.9+, matching the NetScript hosts that consume them.
Apache-2.0 — see LICENSE. Published to JSR with cryptographically verified provenance.
createPluginService requires auth. Guarded services pass native service-auth options; JavaScript
callers receive a TypeError for missing or ambiguous policies before a builder is constructed.
TypeScript callers must migrate their service configuration.
import { assemblePluginContractRouter, createPluginService } from '@netscript/plugin/service';
import { createAuthServiceAuthenticator } from '@netscript/plugin-auth/authenticator';
import { createContractAuthorizer } from '@netscript/service/auth';
import { mountPluginContract } from '@netscript/plugin/contract-base';
import { baseContract, SuccessSchema } from '@netscript/contracts';
import { implement } from '@orpc/server';
const contract = {
list: baseContract.route({ method: 'GET', path: '/reports' }).output(SuccessSchema)
.meta({ access: { authentication: 'required', authorization: { scopes: ['reports:read'] } } }),
};
const contractMount = { version: 'v1', namespace: 'reports' };
const implementation = implement(contract);
const router = assemblePluginContractRouter(implementation, {
...contractMount,
handlers: { list: implementation.list.handler(() => ({ success: true })) },
});
const service = createPluginService(router, {
name: 'reports',
auth: {
authn: {
authenticator: createAuthServiceAuthenticator({ serviceName: 'auth', timeoutMs: 10_000 }),
},
authz: { authorizer: createContractAuthorizer(mountPluginContract(contract, contractMount)) },
},
});The contract must declare the required access metadata, and the plugin must declare its auth service dependency. The builder resolves procedure policy across REST and RPC; do not infer a procedure's required scope from the transport's HTTP method.
contractMount is the same { version, namespace } value used to assemble the router.
mountPluginContract prefixes REST paths and nests RPC keys without changing the source contract,
its access metadata, or its errors. Passing the flat contract to the authorizer would deny mounted
requests because their paths differ. The generator exports one mount constant in handlers.ts and
shares it with the authorizer; preserve that single authority when adapting the scaffold.
For a deliberately public service, record the reason instead:
import { createPluginService } from '@netscript/plugin/service';
const service = createPluginService({}, {
name: 'public-health',
auth: { public: true, reason: 'Public health service without protected operations' },
});Never combine public and guarded fields. Public reasons must be nonblank. Options pass through
unchanged: a custom nonempty allowAnonymous list replaces the native default. The builder's
built-in health routes remain public because they are registered before auth middleware; raw routes
are installed after it and follow the configured guards.
The existing first-party public declarations record unfinished adoption, not proof that those services are guarded. Their credential propagation, session seeding, per-service access policy and auth discovery work remain under #1383; auth signout authorization remains under #1384. This source change does not imply availability in an existing published package.