@checkstack/script-packages-common 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,105 @@
+# @checkstack/script-packages-common
+
+## 0.2.0
+
+### Minor Changes
+
+- 270ef29: Fix several correctness defects around distributed coordination and stored-data handling.
+
+  - Dwell `for:` timers now fire via an atomic `DELETE ... RETURNING` claim, so two pods (or the stalled sweeper vs the queue consumer) can no longer both fire the same dwell.
+  - Postgres session-level advisory locks now keep connection affinity. A shared `AdvisoryLockService` (backed by a dedicated pooled client) replaces the previous acquire/release-on-different-connection pattern that leaked locks. Used by the script-packages installer election, the automation run resume + stalled sweeper, and (via a new transaction-scoped `withXactLock`) incident dedup.
+  - A storage migration that crashed mid-flight is now resumed on startup under the installer-election lock, instead of permanently wedging installs.
+  - Distributed script-package blobs carry a `blobSha256` and are verified before extraction (the SRI `integrity` hashes the npm tarball, not the transported archive). Backward-safe: entries without the field skip verification until a re-install regenerates the manifest.
+  - Archive extraction rejects zip-slip paths (absolute or `..` entries) before writing anything.
+  - `incident.create` with `dedupe_open_for_system` serializes its check-then-create per system, so concurrent triggers for the same system can't both open a duplicate incident.
+  - Seeded auto-incident filter expressions JSON-encode interpolated ids so a quote/backslash can't corrupt the expression.
+  - Stored jsonb snapshots (dwell `actorSnapshot`, wait-lock `waitConfig`) are validated with zod on load and degrade safely instead of flowing through as the wrong type.
+
+- 270ef29: Core-side satellite script-package distribution.
+
+  - `satellite-backend`: the WS handler now carries the desired script-package
+    lockfile hash in `authenticated` / `config_updated` payloads (the durable
+    backstop), exposes `pushRefreshScriptPackagesToAll` (wired to the
+    `script-packages.changed` broadcast hook in `mode: "broadcast"`, so each
+    core instance fans the refresh out to its own connected satellites), and
+    persists `script_package_sync_state` reports from satellites.
+  - `script-packages-*`: new `reportSatelliteSyncState` RPC + store method so
+    satellite-backend can record per-satellite reconcile state for the admin
+    UI. Satellites pull blobs from core via the existing `getManifest` /
+    `downloadBlob` endpoints, never the registry.
+
+- 270ef29: Add the script-packages common package: zod schemas (package allowlist
+  spec, registry config, lockfile manifest, install / storage / migration
+  state, per-host sync state, package types, size-cap config), the oRPC
+  contract, frontend signal + `script-packages.changed` hook id/payload,
+  the dedicated `script-packages.manage` and `script-packages.read` access
+  rules, and plugin metadata.
+- 270ef29: Add garbage collection for script packages, reclaiming both shared blob storage and per-host disk.
+
+  Two things accumulated and were never reclaimed; both are now collected with provably-safe guards (referenced-set + grace + lock / active-run protection - when in doubt, retain).
+
+  - **Blob GC (Postgres / S3 reclamation).** A new `gcBlobs` RPC (manage-gated) plus a daily scheduled job prune content-addressed blobs no longer referenced by any retained lockfile manifest (the current desired hash plus the previous N, default 1, for rollback / in-flight reconciles). Candidates are only deleted after a grace window (default 24h, keyed on `created_at`), each blob's bytes are removed from its recorded backend before its index row, and the pass holds the installer-election advisory lock so it is mutually exclusive with installs and storage migrations. The settings UI surfaces last-run and total-reclaimed figures and a "Run cleanup now" action. The installer now records each successful manifest in a new `script_package_lockfile_history` table so the retained set is computable; GC state lives in `script_package_blob_gc_state`.
+  - **Tree GC (per-host disk).** After a successful symlink flip, each host (core pod or satellite) sweeps its `trees/<lockfileHash>/` dirs, deleting non-current trees older than a grace window (default 1h). `current`'s target is never deleted. Active-run safety uses a conservative mtime-keyed grace window chosen to exceed the longest run timeout, since runs are throwaway subprocesses with no robust cross-process refcount - a tree only becomes eligible once no live run could still be pinned to it.
+
+  Adds the `gcBlobs` / `getBlobGcState` RPCs, the `BlobGcSummary` / `BlobGcState` schemas, and two new Drizzle tables (`script_package_lockfile_history`, `script_package_blob_gc_state`).
+
+- b995afb: Fix package IntelliSense in script editors: lazy Automatic Type Acquisition (ATA) with proper `@types/*` resolution.
+
+  Script editors (automation "Run Script (TypeScript)" and healthcheck collectors) now provide real autocomplete for installed npm packages. Importing a package whose types live in DefinitelyTyped - e.g. `import { debounce } from "lodash"` (lodash ships no own types; `@types/lodash` does) - now yields member completions. Previously no package completions appeared at all.
+
+  Root cause: the old rollup wrapped each package's raw, multi-file `.d.ts` (with `export =`, `export as namespace`, and triple-slash `/// <reference path>` chains) inside a single `declare module "<name>" { ... }`, which the TypeScript worker silently rejected, and it truncated large type sets (lodash is ~866 KB across ~700 files) at a 256 KB cap.
+
+  The fix registers the REAL declaration files at their `node_modules/...` virtual paths and lets TypeScript's own NodeJs + `@types` resolution do the work:
+
+  - `@checkstack/script-packages-backend`: replaced `rollupPackageTypes` with a tree-driven closure extractor (`resolvePackageTypeClosure`). Given a bare specifier, it resolves against the materialized tree - own types via `package.json` `types`/`typings`/`exports` (bundled-types packages like `zod`/`dayjs`), the `@types/<mangled>` companion when it exists (`lodash` -> `@types/lodash`, scoped `@babel/core` -> `@types/babel__core`), or both, or neither (graceful empty, never a throw). It follows `/// <reference path|types>` and relative imports, includes each package's `package.json`, leaves every file UNWRAPPED, and surfaces a `truncated` flag instead of silently capping. Served from a new raw, HTTP-cacheable route `GET /api/script-packages/types/:lockfileHash/:specifier` (`Cache-Control: private, max-age=1y, immutable`), auth-gated by `script-packages.read`.
+  - `@checkstack/script-packages-common`: **BREAKING** - replaced the `listPackageTypes` RPC procedure and `PackageTypesSchema { name, version, dts }` with `PackageTypeClosureSchema` (a `{ path, content }` file-map plus `hasOwnTypes`/`hasAtTypes`/`notFound`/`truncated`) served over the cacheable HTTP route. Added a shared `buildTypeAcquisitionPath`/`parseTypeAcquisitionPath` path contract.
+  - `@checkstack/ui`: `CodeEditor`/`TypefoxEditor` gained an injected `acquireTypes` resolver + `acquireResetKey`. On debounced buffer change it parses bare `import`/`require` specifiers (pure, unit-tested) and lazily fetches + registers each NEW package's closure via `addExtraLib` at `file:///node_modules/...`, deduped by a shared acquired-set that resets when the install hash changes. Compiler options set `moduleResolution: NodeJs`, `baseUrl: "file:///"`, and `typeRoots` so a bare import resolves to its `@types` companion. The `context` ambient global keeps working unchanged.
+  - `@checkstack/script-packages-frontend`: replaced the old `useScriptPackageTypes` (which concatenated the broken `dts`) with `useScriptPackageTypeAcquisition()`, returning the `acquireTypes` resolver (targets the cacheable route, zod-validates the response) and the current `lockfileHash` as `acquireResetKey`.
+  - `@checkstack/automation-frontend` / `@checkstack/healthcheck-frontend`: wired the resolver into the Run Script and collector editors.
+
+  State & scale: the type closure is derived on read from the materialized package tree (no new durable state). The editor's acquired-set is pod-local UI bookkeeping; the route is keyed by the cluster-wide `lockfileHash`, so the browser HTTP cache is correct across pods and only refetches after a new install changes the hash.
+
+- b995afb: Add live, backend-proxied npm package-name autocomplete and version lookup to the Script Packages "Allowed packages" form.
+
+  The package-name field now searches the configured registry as you type (debounced). The version field suggests the package's published versions newest-first, defaulting to the registry's `latest` dist-tag while staying free-typeable for an exact manual pin. Picking a package now auto-fills its version (from the search hit, then upgraded to `latest`) instead of clearing the field, and the version dropdown stays open so a version is actually selectable.
+
+  This is fully backend-proxied so it reuses the SAME configured registry + auth the install path uses: the registry can be private with a server-side-only auth token (the client only ever sees `hasAuthToken`), and browsers can't reach arbitrary registries due to CORS.
+
+  - `@checkstack/script-packages-common`: two new `manage`-gated query procedures - `searchPackages` (input `{ text }`, output `{ items: [{ name, version?, description? }] }`) and `getPackageVersions` (input `{ name }`, output `{ versions, distTags? }`). Output `version`/`versions` are relaxed to plain strings so valid-but-unusual registry versions surface as suggestions; strict `PackageVersionSchema` validation still applies on `addPackage`.
+  - `@checkstack/script-packages-backend`: new `registry-client` (fetch-based, AbortController timeout, size cap, zod-validated registry responses, scoped-registry selection, tolerant semver-descending sort, a best-effort pod-local read cache that is never a source of truth, and errors that never leak the auth token). Search results use the registry's own relevance ranking from `-/v1/search`. The registry + token resolution used by the install path is factored into a shared `resolveRegistryRequestConfig` helper reused by both the new RPC handlers and the installer.
+  - `@checkstack/script-packages-frontend`: the package and version inputs become live comboboxes (Popover + Input) with inline pinned-version validation before "Add" is enabled. Selecting a suggestion routes through a dedicated `onSelect(hit)` callback (separate from manual-typing `onValueChange`) so a pick auto-fills the version instead of clearing it; the popover dismissable layer ignores interactions originating on the anchor input, fixing the version dropdown that previously opened then immediately closed. The version-autofill decision logic is extracted into a pure, unit-tested helper.
+
+  State & scale: the registry-client TTL cache is an explicitly non-authoritative, pod-local best-effort read cache (search/version lookups are non-authoritative reads); a cache miss on another pod simply re-fetches, so pod-local divergence is harmless. No new durable state of record is introduced.
+
+- 270ef29: Wire up the script-packages RPC router, admin UI, and editor IntelliSense.
+
+  - `script-packages-backend`: the oRPC router implementing the full
+    contract (allowlist CRUD, registry config with encrypted write-only auth
+    token, `installNow` via the elected installer, size cap, storage backend
+    selection, install state, `getManifest` / `downloadBlob` for reconcilers,
+    and `listPackageTypes`), the `installNow` controller (election, size-cap
+    enforcement, `script-packages.changed` emit, blocked during migration),
+    the `.d.ts` rollup, the singleton config stores, and the full plugin
+    wiring (broadcast-hook reconcile + startup backstop).
+  - `script-packages-common`: admin route for the settings page.
+  - `script-packages-frontend`: the Settings -> Script Packages admin page
+    (allowlist, install state + size, registry/storage summary, satellite
+    sync) and the `useScriptPackageTypes()` hook.
+  - `automation-frontend` / `healthcheck-frontend`: merge installed-package
+    `.d.ts` into the script-editor `typeDefinitions` so `import` from an
+    allowlisted package autocompletes in every script field.
+
+- 270ef29: Add storage-backend migration for script packages.
+
+  - `migrateStorage({ target })` copies every blob from the active backend to
+    the target, verifies each copy byte-for-byte (read back + SHA-256 compare),
+    flips the per-blob `backend` only after a verified copy, then atomically
+    switches the active backend. Resumable from a partial state (the work set
+    is re-derived from the index), aborts cleanly on an integrity mismatch
+    (active backend untouched), and supports optional source GC. Built on the
+    Phase 2 dual-backend read fallback, so reads keep working mid-migration.
+  - Migration and `installNow` are mutually exclusive via the installer
+    advisory lock; `setStorageBackend` is refused while a migration runs.
+  - New `listStorageBackends` RPC + admin UI: a storage-backend card with a
+    target selector, "Migrate" action, and live progress / completion / error
+    state.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@checkstack/script-packages-common",
+  "version": "0.2.0",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@checkstack/common": "0.12.0",
+    "@checkstack/signal-common": "0.2.5",
+    "@orpc/contract": "^1.13.14",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/scripts": "0.3.4"
+  },
+  "checkstack": {
+    "type": "common"
+  }
+}

package/src/access.ts

@@ -0,0 +1,45 @@
+import { access } from "@checkstack/common";
+
+/**
+ * Access rules for the script-packages plugin.
+ *
+ * Installing npm packages is an install-time RCE / supply-chain vector
+ * (postinstall scripts, transitive deps), so management gets its own
+ * dedicated, grantable permission (`script-packages.manage`) rather than
+ * riding a general role. The read-only editor / runtime endpoints
+ * (`getInstallState`, `getManifest`, `downloadBlob`, and the cacheable
+ * package-type-closure HTTP route) are gated by the existing
+ * script-authoring access so editors and reconcilers can use them; we
+ * model that as `script-packages.read`.
+ */
+export const scriptPackagesAccess = {
+  /**
+   * Read-only access for editor IntelliSense + runtime reconcilers:
+   * desired manifest, install state, blob download, package `.d.ts`.
+   */
+  read: access(
+    "script-packages",
+    "read",
+    "Read installed script packages, manifest, and types",
+  ),
+
+  /**
+   * Management access: edit the allowlist, registry config, storage
+   * backend, trigger installs / migrations. Dedicated grantable
+   * permission because installing packages can execute code at install
+   * time.
+   */
+  manage: access(
+    "script-packages",
+    "manage",
+    "Manage script packages (allowlist, registry, storage, installs)",
+  ),
+};
+
+/**
+ * All access rules for registration with the plugin system.
+ */
+export const scriptPackagesAccessRules = [
+  scriptPackagesAccess.read,
+  scriptPackagesAccess.manage,
+];

package/src/hooks.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+/**
+ * Id + payload schema for the backend `script-packages.changed` hook.
+ *
+ * The hook itself (`createHook`) lives in the backend package (hooks are a
+ * backend concern), but the id + payload contract is shared here so the
+ * satellite-distribution push message and any subscriber agree on the
+ * shape. Emitted by the elected installer after a successful install;
+ * core instances subscribe in `broadcast` mode and kick their reconciler.
+ */
+export const SCRIPT_PACKAGES_CHANGED_HOOK_ID = "script-packages.changed";
+
+export const ScriptPackagesChangedPayloadSchema = z.object({
+  /** The new desired lockfile hash hosts should reconcile to. */
+  lockfileHash: z.string(),
+});
+export type ScriptPackagesChangedPayload = z.infer<
+  typeof ScriptPackagesChangedPayloadSchema
+>;

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from "./schemas";
+export * from "./type-acquisition";
+export * from "./access";
+export * from "./signals";
+export * from "./hooks";
+export * from "./routes";
+export {
+  scriptPackagesContract,
+  ScriptPackagesApi,
+  type ScriptPackagesContract,
+} from "./rpc-contract";
+export * from "./plugin-metadata";

package/src/plugin-metadata.ts

@@ -0,0 +1,10 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the script-packages plugin.
+ * Exported from the common package so backend, frontend, and reconcilers
+ * can reference the same id.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "script-packages",
+});

package/src/routes.ts

@@ -0,0 +1,10 @@
+import { createRoutes } from "@checkstack/common";
+
+/**
+ * Route definitions for the script-packages admin UI (Settings -> Script
+ * Packages).
+ */
+export const scriptPackagesRoutes = createRoutes("script-packages", {
+  /** Admin settings page: allowlist, registry, storage, sync status. */
+  settings: "/",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,283 @@
+import { z } from "zod";
+import { createClientDefinition, proc } from "@checkstack/common";
+import { scriptPackagesAccess } from "./access";
+import { pluginMetadata } from "./plugin-metadata";
+import {
+  BlobGcStateSchema,
+  BlobGcSummarySchema,
+  GetPackageVersionsInputSchema,
+  GetPackageVersionsOutputSchema,
+  InstallStateSchema,
+  ManifestEntrySchema,
+  PackageNameSchema,
+  PackageSpecSchema,
+  PackageVersionSchema,
+  RegistryConfigSchema,
+  SatelliteSyncStateSchema,
+  SearchPackagesInputSchema,
+  SearchPackagesOutputSchema,
+  SetRegistryConfigInputSchema,
+  SizeCapConfigSchema,
+  StorageConfigSchema,
+} from "./schemas";
+
+/**
+ * Script-packages RPC contract.
+ *
+ * Management endpoints are gated by the dedicated `script-packages.manage`
+ * permission (install-time RCE / supply-chain vector). The read-only
+ * editor / runtime endpoints (`getInstallState`, `getManifest`,
+ * `downloadBlob`) are gated by `script-packages.read` so editors and
+ * reconcilers can use them.
+ *
+ * NOTE: package-type IntelliSense is NOT an RPC procedure. It is served as
+ * a raw, HTTP-cacheable route (`GET /api/script-packages/types/:hash/:spec`)
+ * so the browser can cache each closure per-install via `Cache-Control`;
+ * see `createTypeClosureHttpHandler` in `script-packages-backend`.
+ */
+export const scriptPackagesContract = {
+  // ─── Allowlist (manage) ────────────────────────────────────────────────
+
+  listPackages: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  }).output(z.object({ items: z.array(PackageSpecSchema) })),
+
+  addPackage: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  })
+    .input(
+      z.object({ name: PackageNameSchema, version: PackageVersionSchema }),
+    )
+    .output(PackageSpecSchema),
+
+  removePackage: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  })
+    .route({ method: "DELETE" })
+    .input(z.object({ name: PackageNameSchema }))
+    .output(z.object({ success: z.boolean() })),
+
+  setPackageEnabled: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  })
+    .input(z.object({ name: PackageNameSchema, enabled: z.boolean() }))
+    .output(PackageSpecSchema),
+
+  // ─── Registry autocomplete (manage) ────────────────────────────────────
+
+  /**
+   * Live package-name search against the configured registry, backend-proxied
+   * (the registry may be private with a server-side-only token, and browsers
+   * can't reach arbitrary registries due to CORS). Gated by `manage` like the
+   * other registry endpoints.
+   */
+  searchPackages: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  })
+    .input(SearchPackagesInputSchema)
+    .output(SearchPackagesOutputSchema),
+
+  /**
+   * Fetch published versions (newest-first) + dist-tags for a package from
+   * the configured registry. Backend-proxied for the same reasons as
+   * `searchPackages`. The version list feeds the version field's suggestions.
+   */
+  getPackageVersions: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  })
+    .input(GetPackageVersionsInputSchema)
+    .output(GetPackageVersionsOutputSchema),
+
+  // ─── Registry config (manage) ──────────────────────────────────────────
+
+  getRegistryConfig: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  }).output(RegistryConfigSchema),
+
+  setRegistryConfig: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  })
+    .input(SetRegistryConfigInputSchema)
+    .output(RegistryConfigSchema),
+
+  // ─── Install (manage) ──────────────────────────────────────────────────
+
+  /**
+   * Elect the installer (advisory lock), resolve the pinned allowlist,
+   * publish new blobs, record the manifest, emit `script-packages.changed`.
+   * Blocked while a storage migration is in flight.
+   */
+  installNow: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  }).output(
+    z.object({
+      started: z.boolean(),
+      /** Populated when the install was refused (e.g. migration in flight). */
+      reason: z.string().optional(),
+    }),
+  ),
+
+  getSizeCapConfig: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  }).output(SizeCapConfigSchema),
+
+  setSizeCapConfig: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  })
+    .input(SizeCapConfigSchema)
+    .output(SizeCapConfigSchema),
+
+  // ─── Storage (manage) ──────────────────────────────────────────────────
+
+  getStorageConfig: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  }).output(StorageConfigSchema),
+
+  /** Registered blob-store backend ids available as migration targets. */
+  listStorageBackends: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  }).output(z.object({ backends: z.array(z.string()) })),
+
+  setStorageBackend: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  })
+    .input(z.object({ backend: z.string().min(1) }))
+    .output(StorageConfigSchema),
+
+  migrateStorage: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  })
+    .input(z.object({ target: z.string().min(1) }))
+    .output(z.object({ started: z.boolean(), reason: z.string().optional() })),
+
+  getStorageMigrationState: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  }).output(StorageConfigSchema),
+
+  // ─── Garbage collection (manage) ───────────────────────────────────────
+
+  /**
+   * Admin-triggered blob GC: prune content-addressed blobs no longer
+   * referenced by any RETAINED lockfile manifest (current + the previous N),
+   * older than the grace window. Refuses while an install or storage
+   * migration is in flight (takes the installer-election advisory lock).
+   * Returns a summary (candidates, deleted, bytes reclaimed).
+   */
+  gcBlobs: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  }).output(BlobGcSummarySchema),
+
+  /** Last blob-GC run state (for the settings UI). */
+  getBlobGcState: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  }).output(BlobGcStateSchema),
+
+  // ─── Per-host status (manage) ──────────────────────────────────────────
+
+  listSatelliteSyncState: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.manage],
+  }).output(z.object({ items: z.array(SatelliteSyncStateSchema) })),
+
+  /**
+   * Persist a satellite's reconcile state. Called by satellite-backend
+   * (server-side, on a `script_package_sync_state` WS report) so the admin
+   * UI can show per-satellite sync status. Read-gated because it's an
+   * internal server-to-server call, not a user mutation of managed config.
+   */
+  reportSatelliteSyncState: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.read],
+  })
+    .input(
+      z.object({
+        satelliteId: z.string(),
+        lockfileHash: z.string().nullable(),
+        status: z.enum(["pending", "syncing", "ready", "error"]),
+        errorMessage: z.string().optional(),
+      }),
+    )
+    .output(z.object({ success: z.boolean() })),
+
+  // ─── Authoring / runtime (read) ────────────────────────────────────────
+
+  getInstallState: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.read],
+  }).output(InstallStateSchema),
+
+  /** Manifest for a given lockfile hash - used by reconcilers for delta diffing. */
+  getManifest: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.read],
+  })
+    .input(z.object({ lockfileHash: z.string() }))
+    .output(z.object({ entries: z.array(ManifestEntrySchema) })),
+
+  /**
+   * Download one content-addressed blob (zstd-compressed) by integrity hash.
+   * The payload is base64 so it survives the JSON transport; satellites and
+   * cold core pods pull missing blobs this way.
+   */
+  downloadBlob: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [scriptPackagesAccess.read],
+  })
+    .input(z.object({ integrity: z.string() }))
+    .output(
+      z.object({
+        integrity: z.string(),
+        /** base64-encoded compressed blob bytes. */
+        data: z.string(),
+        sizeBytes: z.number().int().nonnegative(),
+      }),
+    ),
+};
+
+export type ScriptPackagesContract = typeof scriptPackagesContract;
+
+export const ScriptPackagesApi = createClientDefinition(
+  scriptPackagesContract,
+  pluginMetadata,
+);

package/src/schemas.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "bun:test";
+import {
+  DEFAULT_BLOCK_BYTES,
+  DEFAULT_WARN_BYTES,
+  PackageNameSchema,
+  PackageVersionSchema,
+  RegistryConfigSchema,
+  SizeCapConfigSchema,
+} from "./schemas";
+
+describe("PackageNameSchema", () => {
+  test("accepts plain and scoped names", () => {
+    expect(PackageNameSchema.safeParse("lodash").success).toBe(true);
+    expect(PackageNameSchema.safeParse("@acme/utils").success).toBe(true);
+  });
+  test("rejects uppercase / invalid names", () => {
+    expect(PackageNameSchema.safeParse("Lodash").success).toBe(false);
+    expect(PackageNameSchema.safeParse("../evil").success).toBe(false);
+  });
+});
+
+describe("PackageVersionSchema", () => {
+  test("accepts exact versions and rejects ranges", () => {
+    expect(PackageVersionSchema.safeParse("4.17.21").success).toBe(true);
+    expect(PackageVersionSchema.safeParse("1.0.0-beta.1").success).toBe(true);
+    expect(PackageVersionSchema.safeParse("^4.17.0").success).toBe(false);
+    expect(PackageVersionSchema.safeParse("latest").success).toBe(false);
+  });
+});
+
+describe("RegistryConfigSchema", () => {
+  test("ignoreScripts defaults to true (RCE mitigation)", () => {
+    const cfg = RegistryConfigSchema.parse({});
+    expect(cfg.ignoreScripts).toBe(true);
+    expect(cfg.hasAuthToken).toBe(false);
+    expect(cfg.registryUrl).toBe("https://registry.npmjs.org/");
+  });
+});
+
+describe("SizeCapConfigSchema", () => {
+  test("defaults to 150MB warn / 300MB block", () => {
+    const cap = SizeCapConfigSchema.parse({});
+    expect(cap.warnBytes).toBe(DEFAULT_WARN_BYTES);
+    expect(cap.blockBytes).toBe(DEFAULT_BLOCK_BYTES);
+    expect(DEFAULT_WARN_BYTES).toBe(150 * 1024 * 1024);
+    expect(DEFAULT_BLOCK_BYTES).toBe(300 * 1024 * 1024);
+  });
+});

package/src/schemas.ts

@@ -0,0 +1,344 @@
+import { z } from "zod";
+
+/**
+ * Schemas for the script-packages platform.
+ *
+ * The admin curates a global allowlist of pinned npm packages
+ * (`name@exact-version`). The central backend resolves + bundles the
+ * package tree, publishes per-package content-addressed blobs to a
+ * pluggable blob store, and records a lockfile manifest. Every host that
+ * runs a user script (N core instances + each satellite) reconciles to
+ * the desired `lockfileHash` by delta-syncing only the blobs it lacks.
+ *
+ * See the feature plan for the full distribution model.
+ */
+
+// ─── Package allowlist ───────────────────────────────────────────────────
+
+/** A package name must be a valid (optionally scoped) npm package name. */
+export const PackageNameSchema = z
+  .string()
+  .min(1)
+  .max(214)
+  .regex(
+    /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/,
+    "Invalid npm package name",
+  );
+
+/**
+ * An exact semver version. Pinned (no ranges) so installs are
+ * deterministic and the resulting tree is reproducible across hosts.
+ */
+export const PackageVersionSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(
+    /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z-.]+)?$/,
+    "Version must be exact (e.g. 4.17.21), not a range",
+  );
+
+/** One allowlist entry: a pinned package and whether it's currently enabled. */
+export const PackageSpecSchema = z.object({
+  name: PackageNameSchema,
+  version: PackageVersionSchema,
+  enabled: z.boolean().default(true),
+  addedBy: z.string().nullable().optional(),
+  addedAt: z.coerce.date().optional(),
+  updatedAt: z.coerce.date().optional(),
+});
+export type PackageSpec = z.infer<typeof PackageSpecSchema>;
+
+// ─── Registry autocomplete (live search / version lookup) ─────────────────
+
+/** Input for `searchPackages`: a partial package-name query. */
+export const SearchPackagesInputSchema = z.object({
+  text: z.string().min(1).max(214),
+});
+export type SearchPackagesInput = z.infer<typeof SearchPackagesInputSchema>;
+
+/**
+ * One live search hit. `version` is relaxed to a plain string in the OUTPUT
+ * so a valid-but-unusual registry version is surfaced as a suggestion rather
+ * than dropped - strict `PackageVersionSchema` validation still applies on
+ * `addPackage`.
+ */
+export const PackageSearchHitSchema = z.object({
+  name: PackageNameSchema,
+  version: z.string().optional(),
+  description: z.string().optional(),
+});
+export type PackageSearchHit = z.infer<typeof PackageSearchHitSchema>;
+
+export const SearchPackagesOutputSchema = z.object({
+  items: z.array(PackageSearchHitSchema),
+});
+export type SearchPackagesOutput = z.infer<typeof SearchPackagesOutputSchema>;
+
+/** Input for `getPackageVersions`: an exact (optionally scoped) package name. */
+export const GetPackageVersionsInputSchema = z.object({
+  name: PackageNameSchema,
+});
+export type GetPackageVersionsInput = z.infer<
+  typeof GetPackageVersionsInputSchema
+>;
+
+/** Versions newest-first plus dist-tags (e.g. `latest`). Versions relaxed. */
+export const GetPackageVersionsOutputSchema = z.object({
+  versions: z.array(z.string()),
+  distTags: z.record(z.string(), z.string()).optional(),
+});
+export type GetPackageVersionsOutput = z.infer<
+  typeof GetPackageVersionsOutputSchema
+>;
+
+// ─── Registry config ─────────────────────────────────────────────────────
+
+/** A scoped-registry override: `@scope` → registry URL. */
+export const ScopedRegistrySchema = z.object({
+  scope: z
+    .string()
+    .regex(/^@[a-z0-9-~][a-z0-9-._~]*$/, "Scope must look like @acme"),
+  registryUrl: z.string().url(),
+});
+export type ScopedRegistry = z.infer<typeof ScopedRegistrySchema>;
+
+/**
+ * Registry configuration rendered to `.npmrc` at install time. The auth
+ * token is stored as a connection-store secret and NEVER returned to the
+ * client in plaintext - the DTO carries only a boolean `hasAuthToken`.
+ */
+export const RegistryConfigSchema = z.object({
+  registryUrl: z.string().url().default("https://registry.npmjs.org/"),
+  scopedRegistries: z.array(ScopedRegistrySchema).default([]),
+  /** True when an auth token secret is configured (never the value). */
+  hasAuthToken: z.boolean().default(false),
+  /**
+   * `--ignore-scripts` toggle. Default ON: postinstall is the RCE vector
+   * and the size guardrail (native builds / binary downloads won't run).
+   */
+  ignoreScripts: z.boolean().default(true),
+  updatedAt: z.coerce.date().optional(),
+});
+export type RegistryConfig = z.infer<typeof RegistryConfigSchema>;
+
+/** Input for `setRegistryConfig`. The token is write-only. */
+export const SetRegistryConfigInputSchema = z.object({
+  registryUrl: z.string().url(),
+  scopedRegistries: z.array(ScopedRegistrySchema).default([]),
+  ignoreScripts: z.boolean().default(true),
+  /**
+   * New auth token. Omit to leave the existing secret untouched; pass an
+   * empty string to clear it. Never echoed back.
+   */
+  authToken: z.string().optional(),
+});
+export type SetRegistryConfigInput = z.infer<
+  typeof SetRegistryConfigInputSchema
+>;
+
+// ─── Lockfile manifest ─────────────────────────────────────────────────────
+
+/** One resolved package in the lockfile manifest. */
+export const ManifestEntrySchema = z.object({
+  name: PackageNameSchema,
+  version: PackageVersionSchema,
+  /** Integrity hash (sri, e.g. `sha512-...`) - the content-addressed key. */
+  integrity: z.string().min(1),
+  /**
+   * SHA-256 (hex) of the DISTRIBUTED blob (our gzip-tar of the Bun cache
+   * entry), computed at publish time. Unlike `integrity` (which hashes the
+   * upstream npm tarball, not our archive), this lets a host verify the
+   * transported bytes before extraction. Optional for backward
+   * compatibility: entries published before this field skip verification
+   * until the manifest is regenerated by a re-install.
+   */
+  blobSha256: z.string().length(64).optional(),
+});
+export type ManifestEntry = z.infer<typeof ManifestEntrySchema>;
+
+export const InstallStatusSchema = z.enum([
+  "idle",
+  "installing",
+  "ready",
+  "error",
+]);
+export type InstallStatus = z.infer<typeof InstallStatusSchema>;
+
+/**
+ * Desired install state: the `lockfileHash` every host reconciles to,
+ * its manifest, and resolved total size. Surfaced to editors (for the
+ * "packages ready" gate) and reconcilers (for delta diffing).
+ */
+export const InstallStateSchema = z.object({
+  status: InstallStatusSchema,
+  lockfileHash: z.string().nullable(),
+  manifest: z.array(ManifestEntrySchema),
+  totalSizeBytes: z.number().int().nonnegative(),
+  lastInstalledAt: z.coerce.date().nullable(),
+  errorMessage: z.string().nullable(),
+});
+export type InstallState = z.infer<typeof InstallStateSchema>;
+
+// ─── Storage config / migration ────────────────────────────────────────────
+
+/** Backend identifier for the active blob store. Open-ended (plugins). */
+export const StorageBackendIdSchema = z.string().min(1);
+
+export const MigrationStatusSchema = z.enum([
+  "idle",
+  "migrating",
+  "completed",
+  "error",
+]);
+export type MigrationStatus = z.infer<typeof MigrationStatusSchema>;
+
+export const StorageConfigSchema = z.object({
+  activeBackend: StorageBackendIdSchema,
+  migrationStatus: MigrationStatusSchema,
+  migrationTarget: z.string().nullable(),
+  migratedCount: z.number().int().nonnegative(),
+  migrationError: z.string().nullable(),
+  updatedAt: z.coerce.date().optional(),
+});
+export type StorageConfig = z.infer<typeof StorageConfigSchema>;
+
+// ─── Per-host reconcile state ───────────────────────────────────────────────
+
+export const HostSyncStatusSchema = z.enum([
+  "pending",
+  "syncing",
+  "ready",
+  "error",
+]);
+export type HostSyncStatus = z.infer<typeof HostSyncStatusSchema>;
+
+export const SatelliteSyncStateSchema = z.object({
+  satelliteId: z.string(),
+  lockfileHash: z.string().nullable(),
+  status: HostSyncStatusSchema,
+  errorMessage: z.string().nullable(),
+  syncedAt: z.coerce.date().nullable(),
+});
+export type SatelliteSyncState = z.infer<typeof SatelliteSyncStateSchema>;
+
+// ─── Editor IntelliSense (lazy ATA) ──────────────────────────────────────────
+
+/**
+ * One declaration file in a package's type closure. The `path` is a real
+ * `node_modules/...`-relative path (e.g. `node_modules/@types/lodash/index.d.ts`
+ * or `node_modules/zod/index.d.ts`); the frontend registers it at
+ * `file:///<path>` so TypeScript's NodeJs + `@types` resolution finds it.
+ * Files are UNWRAPPED (no `declare module` envelope).
+ */
+export const PackageTypeFileSchema = z.object({
+  /** `node_modules/...`-relative virtual path. */
+  path: z.string(),
+  /** Verbatim file content. */
+  content: z.string(),
+});
+export type PackageTypeFile = z.infer<typeof PackageTypeFileSchema>;
+
+/**
+ * The declaration-file closure for ONE requested specifier, resolved against
+ * the materialized package tree. Returned by the lazy ATA route.
+ */
+export const PackageTypeClosureSchema = z.object({
+  /** The requested bare specifier (e.g. `lodash`, `@babel/core`). */
+  specifier: z.string(),
+  /** Declaration files (own types and/or `@types` companion), unwrapped. */
+  files: z.array(PackageTypeFileSchema),
+  /** The package ships its own declarations. */
+  hasOwnTypes: z.boolean(),
+  /** A DefinitelyTyped `@types/...` companion exists in the tree. */
+  hasAtTypes: z.boolean(),
+  /** Neither own types nor an `@types` companion were found (graceful). */
+  notFound: z.boolean(),
+  /** The closure hit the size ceiling and dropped files (NOT silent). */
+  truncated: z.boolean(),
+});
+export type PackageTypeClosure = z.infer<typeof PackageTypeClosureSchema>;
+
+// ─── Size guardrail ─────────────────────────────────────────────────────────
+
+/**
+ * Total-size cap. The admin UI warns above `warnBytes` and blocks installs
+ * above `blockBytes`. Defaults: warn 150 MB, block 300 MB (admin-configurable).
+ */
+export const SizeCapConfigSchema = z.object({
+  warnBytes: z
+    .number()
+    .int()
+    .positive()
+    .default(150 * 1024 * 1024),
+  blockBytes: z
+    .number()
+    .int()
+    .positive()
+    .default(300 * 1024 * 1024),
+});
+export type SizeCapConfig = z.infer<typeof SizeCapConfigSchema>;
+
+export const DEFAULT_WARN_BYTES = 150 * 1024 * 1024;
+export const DEFAULT_BLOCK_BYTES = 300 * 1024 * 1024;
+
+// ─── Garbage collection ──────────────────────────────────────────────────────
+
+/**
+ * How many *previous* lockfile hashes (beyond the current desired one) the
+ * blob GC keeps blobs for. Small by design: enough for rollback / an
+ * in-flight reconcile toward a just-superseded hash, not an archive. The
+ * current hash is ALWAYS retained on top of this.
+ */
+export const DEFAULT_BLOB_GC_RETAIN_PREVIOUS = 1;
+
+/**
+ * Grace window (ms) below which an unreferenced blob is kept even though no
+ * retained manifest references it. Protects a core pod / satellite that is
+ * mid-reconcile toward a just-superseded hash: it may still pull a blob that
+ * was just dropped from the retained set. Keyed on `script_package_blob`
+ * `created_at`. Default: 24h.
+ */
+export const DEFAULT_BLOB_GC_GRACE_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Grace window (ms) below which a non-current tree dir is kept even though
+ * `current` no longer points at it. Keyed on the tree dir's mtime and chosen
+ * to comfortably exceed the longest possible script-run timeout so a live run
+ * pinned to that tree (via its `resolutionRoot`) can never have its
+ * node_modules deleted out from under it. Default: 1h.
+ */
+export const DEFAULT_TREE_GC_GRACE_MS = 60 * 60 * 1000;
+
+/**
+ * Result summary of a blob-GC pass, returned by `gcBlobs` and surfaced in the
+ * Script Packages settings UI.
+ */
+export const BlobGcSummarySchema = z.object({
+  /** True when the pass actually ran (false when refused, e.g. lock held). */
+  ran: z.boolean(),
+  /** Populated when the pass was refused or aborted. */
+  reason: z.string().optional(),
+  /** Candidate blobs unreferenced by any retained manifest. */
+  candidates: z.number().int().nonnegative(),
+  /** Blobs actually deleted (past-grace candidates). */
+  deleted: z.number().int().nonnegative(),
+  /** Candidates kept because they are still within the grace window. */
+  keptWithinGrace: z.number().int().nonnegative(),
+  /** Bytes reclaimed by the deletions. */
+  bytesReclaimed: z.number().int().nonnegative(),
+});
+export type BlobGcSummary = z.infer<typeof BlobGcSummarySchema>;
+
+/**
+ * Persisted last-run state for the blob GC, so the admin UI can show "last
+ * reclaimed N bytes at T" without re-running the (destructive) pass.
+ */
+export const BlobGcStateSchema = z.object({
+  lastRunAt: z.coerce.date().nullable(),
+  lastDeleted: z.number().int().nonnegative(),
+  lastBytesReclaimed: z.number().int().nonnegative(),
+  /** Cumulative bytes reclaimed across every run. */
+  totalBytesReclaimed: z.number().int().nonnegative(),
+});
+export type BlobGcState = z.infer<typeof BlobGcStateSchema>;

package/src/signals.ts

@@ -0,0 +1,16 @@
+import { createSignal } from "@checkstack/signal-common";
+import { z } from "zod";
+import { pluginMetadata } from "./plugin-metadata";
+
+/**
+ * Fired when an install completes (or fails) so frontends invalidate the
+ * install-state + per-host status queries. The frontend signal is separate
+ * from the backend `script-packages.changed` hook (which drives reconcilers).
+ */
+export const SCRIPT_PACKAGES_CHANGED_SIGNAL = createSignal({
+  pluginMetadata,
+  event: "script_packages_changed",
+  payloadSchema: z.object({
+    lockfileHash: z.string().nullable(),
+  }),
+});

package/src/type-acquisition.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import {
+  buildTypeAcquisitionPath,
+  parseTypeAcquisitionPath,
+  TYPE_ACQUISITION_PATH_PREFIX,
+} from "./type-acquisition";
+
+describe("buildTypeAcquisitionPath", () => {
+  test("unscoped specifier", () => {
+    expect(
+      buildTypeAcquisitionPath({ lockfileHash: "abc123", specifier: "lodash" }),
+    ).toBe(`${TYPE_ACQUISITION_PATH_PREFIX}/abc123/lodash`);
+  });
+  test("scoped specifier is percent-encoded into one segment", () => {
+    const built = buildTypeAcquisitionPath({
+      lockfileHash: "abc123",
+      specifier: "@babel/core",
+    });
+    expect(built).toBe(`${TYPE_ACQUISITION_PATH_PREFIX}/abc123/%40babel%2Fcore`);
+    // No un-encoded slash in the specifier segment.
+    expect(built.split("/").length).toBe(4); // "", "types", hash, encodedSpec
+  });
+});
+
+describe("parseTypeAcquisitionPath", () => {
+  test("round-trips an unscoped specifier", () => {
+    const parsed = parseTypeAcquisitionPath("/abc123/lodash");
+    expect(parsed).toEqual({ lockfileHash: "abc123", specifier: "lodash" });
+  });
+  test("round-trips a scoped (encoded) specifier", () => {
+    const parsed = parseTypeAcquisitionPath("/abc123/%40babel%2Fcore");
+    expect(parsed).toEqual({
+      lockfileHash: "abc123",
+      specifier: "@babel/core",
+    });
+  });
+  test("build -> parse round trip", () => {
+    const path = buildTypeAcquisitionPath({
+      lockfileHash: "deadbeef",
+      specifier: "@scope/name",
+    }).slice(TYPE_ACQUISITION_PATH_PREFIX.length);
+    expect(parseTypeAcquisitionPath(path)).toEqual({
+      lockfileHash: "deadbeef",
+      specifier: "@scope/name",
+    });
+  });
+  test("rejects an un-encoded extra slash (path traversal guard)", () => {
+    expect(parseTypeAcquisitionPath("/abc123/foo/bar")).toBeUndefined();
+  });
+  test("rejects missing segments", () => {
+    expect(parseTypeAcquisitionPath("/abc123")).toBeUndefined();
+    expect(parseTypeAcquisitionPath("/abc123/")).toBeUndefined();
+    expect(parseTypeAcquisitionPath("/")).toBeUndefined();
+    expect(parseTypeAcquisitionPath("")).toBeUndefined();
+  });
+});

package/src/type-acquisition.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared contract for the lazy package-type Automatic Type Acquisition
+ * (ATA) HTTP route. The path is shared so the backend handler and the
+ * frontend resolver can never drift.
+ *
+ * The route is served as a RAW, HTTP-cacheable handler (not an oRPC
+ * procedure) so the browser caches each closure per-install: the path is
+ * keyed by the current `lockfileHash`, and the response carries
+ * `Cache-Control: private, max-age=..., immutable`. A new install changes
+ * the hash, so a stale install's URL is simply never requested again.
+ *
+ * Shape (within the plugin's `/api/script-packages` namespace):
+ *
+ *   /types/:lockfileHash/:encodedSpecifier
+ *
+ * The specifier is percent-encoded so scoped names (`@babel/core`) survive
+ * the path segment.
+ */
+
+/** Path prefix (within the plugin namespace) for the ATA route. */
+export const TYPE_ACQUISITION_PATH_PREFIX = "/types";
+
+/**
+ * Build the plugin-relative request path for a specifier + lockfile hash.
+ * Pure; used by the frontend resolver. The specifier is percent-encoded so
+ * scoped packages (`@scope/name`) round-trip safely as one path segment.
+ */
+export function buildTypeAcquisitionPath({
+  lockfileHash,
+  specifier,
+}: {
+  lockfileHash: string;
+  specifier: string;
+}): string {
+  return `${TYPE_ACQUISITION_PATH_PREFIX}/${encodeURIComponent(
+    lockfileHash,
+  )}/${encodeURIComponent(specifier)}`;
+}
+
+/**
+ * Parse a request pathname's trailing `:lockfileHash/:encodedSpecifier`
+ * segments back into the hash + decoded specifier. Pure; used by the
+ * backend handler. Returns undefined when the path doesn't match.
+ *
+ * `pathnameAfterPrefix` is the portion AFTER `TYPE_ACQUISITION_PATH_PREFIX`
+ * (e.g. `/<hash>/<encodedSpec>`), with or without a leading slash.
+ */
+export function parseTypeAcquisitionPath(
+  pathnameAfterPrefix: string,
+): { lockfileHash: string; specifier: string } | undefined {
+  const trimmed = pathnameAfterPrefix.replace(/^\/+/, "");
+  // Exactly two segments: hash / encoded-specifier. A scoped specifier is a
+  // single encoded segment (its `/` is percent-encoded), so we split on the
+  // FIRST slash only.
+  const slash = trimmed.indexOf("/");
+  if (slash <= 0 || slash === trimmed.length - 1) return undefined;
+  const lockfileHash = trimmed.slice(0, slash);
+  const encodedSpecifier = trimmed.slice(slash + 1);
+  // Reject further path traversal: the specifier segment must not itself
+  // contain an un-encoded slash.
+  if (encodedSpecifier.includes("/")) return undefined;
+  let specifier: string;
+  try {
+    specifier = decodeURIComponent(encodedSpecifier);
+  } catch {
+    return undefined;
+  }
+  if (lockfileHash.length === 0 || specifier.length === 0) return undefined;
+  return { lockfileHash, specifier };
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "@checkstack/tsconfig/common.json",
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../signal-common"
+    }
+  ]
+}