@sparelabs/sightline-extension-cli 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,71 @@
+# @sparelabs/sightline-extension-cli
+
+`sightline-ext`: scaffold, run, build, test and deploy a **hosted Sightline extension**, a backend (and optionally a UI) that runs in Sightline's sandbox, one instance per workspace, and talks to Sightline only through its published contract.
+
+```bash
+npx @sparelabs/sightline-extension-cli init my-notes
+cd my-notes && npm install
+npm test            # build + contract tests against an emulated Sightline
+```
+
+You need Node 20.19+, [Deno](https://deno.com) (the extension runtime) and Docker (your extension's local Postgres).
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `init <dir> [--id <kebab-id>] [--name "…"] [--publisher <kebab-id>] [--force]` | Writes a new extension repository: manifest, server, a first migration, `sightline-ext.json`, tsconfig, a CI workflow and a README. It depends on the published packages only. |
+| `build` | Validates `sightline.extension.json` against the published contract (`@sparelabs/sightline-extension-manifest`) and the rules Sightline applies at publish (trust `T2`, a hosted runtime, a kebab-case id, `MAJOR.MINOR.PATCH`), checks `migrations/NNNN_<name>.sql` (numbered from `0001`, no gaps, at most 256 KB each), bundles `server/main.ts` into one ESM file (`runtime.entry`, usually `dist/server.mjs`, at most 5 MB) and lints the bundle with the same `lintBundle` Sightline runs at publish (from `@sparelabs/sightline-extension-manifest`: no remote, package or relative imports, no computed dynamic import). With `ui.frames` in the manifest it also reads your UI build from `dist/ui` (set `"ui": { "dir": … }` in `sightline-ext.json` to move it; build the UI with your own tool first) and checks it with Sightline's publish rules: allowed file types, sizes, no scripts from other origins, no root-absolute URLs (use a relative base, e.g. Vite `base: './'`), the entry HTML present. |
+| `dev [--port <n>] [--core-port 8787] [--no-db]` | Builds, starts the emulated core (`@sparelabs/sightline-extension-devkit`), your Postgres with your migrations, and the bundle under the **same Deno permission flags as production**; rebuilds and restarts on every change. `npx sightline-devkit invoke tool <name> --as user:alice` calls it. |
+| `test [--no-build] [--no-db] [--keep-db]` | Builds, runs the extension against the emulator and its own database, and checks it against the HTTP contract (`@sparelabs/sightline-extension-testing`): health, token refusal, the `ToolResult` envelope, routing. Exit 1 on any failure. |
+| `deploy [--bindings bindings.json] [--no-build]` | Builds, publishes the release to a workspace (identical bytes are a no-op) and installs it. Refuses when another version is installed: use `upgrade`. |
+| `upgrade [--bindings bindings.json] [--no-build]` | Builds, publishes, and moves the installed extension to the manifest's version. A permission the new version adds needs a binding. |
+| `uninstall [<id>] [--purge --yes]` | Uninstalls. Data is kept 30 days; `--purge --yes` drops it now. |
+
+Common options: `--dir <project>`, `--manifest <file>`, `--config <file>`, `--entry <file>`.
+
+## sightline-ext.json
+
+Local only; never deployed.
+
+```json
+{
+  "entry": "server/main.ts",
+  "contract": {
+    "tool": { "name": "notes_list", "input": { "limit": 5 }, "as": "user:alice" },
+    "job": { "name": "weekly_digest" },
+    "hook": { "name": "inbound", "body": { "event": "ping" } }
+  },
+  "settings": { "greeting": "hello" },
+  "devSecrets": { "inbound_hook": "dev-only-value" }
+}
+```
+
+Without `contract.tool`, `test` calls the manifest's first tool as `user:alice` with `{}`.
+
+## Deploying
+
+```bash
+export SIGHTLINE_URL=https://<your workspace>
+export SIGHTLINE_DEPLOY_TOKEN=…        # issued by a workspace admin; only ever read from the environment
+npx sightline-ext deploy --bindings bindings.json
+```
+
+| Variable | Meaning |
+| --- | --- |
+| `SIGHTLINE_URL` | The workspace. The API is `<url>/functions/v1/core/v1`. `https` only (`http` for localhost). |
+| `SIGHTLINE_API_URL` | The full core API base instead, when it is not under `/functions/v1/core/v1`. |
+| `SIGHTLINE_DEPLOY_TOKEN` | A deploy token (`slxd_…`) a workspace admin issued for your extension ids and actions, or an admin's own session token. A deploy token goes to the workspace's deploy routes (`/functions/v1/core/v1/deploy/…`), the only place it works. It is sent to that workspace only, never accepted as a flag, never in the URL. |
+| `SIGHTLINE_API_KEY` | The gateway's public API key, when the workspace needs one (sent as `apikey`). |
+
+`bindings.json` maps each permission your manifest declares to a Sightline permission the deploying admin holds: `{ "my-notes.read": "employees", "my-notes.write": "employees" }`. A permission left out gets the manifest's proposed `default` when the admin holds it.
+
+The deploy publishes the server bundle and migrations. Publishing a UI (`ui.frames`) to the workspace's extension-UI host is not part of the release API yet.
+
+## Programmatic use
+
+Everything the commands use is exported: `loadProject`, `build`, `createCoreApi`, `deploy`, `upgrade`, `uninstall`, `templateFiles`, `lintBundle`, `migrationProblems`.
+
+## License
+
+MIT

package/bin/sightline-ext.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { main } from "../dist/cli.js";
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code),
+  (e) => {
+    console.error(`sightline-ext: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(1);
+  },
+);

package/dist/args.d.ts

@@ -0,0 +1,11 @@
+export type Flags = Record<string, string | true>;
+export interface ParsedArgs {
+    positional: string[];
+    flags: Flags;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** A string flag, or undefined (a bare `--flag` is not a value). */
+export declare function str(flags: Flags, name: string): string | undefined;
+/** A boolean flag: present bare, or `--flag=true|false`. */
+export declare function bool(flags: Flags, name: string): boolean;
+export declare function int(flags: Flags, name: string): number | undefined;

package/dist/args.js

@@ -0,0 +1,53 @@
+// Argument parsing for sightline-ext: positionals, `--flag value`, `--flag=value`
+// and bare `--flag` (true). No dependencies, so it runs under Node and Deno alike.
+/** Flags that never take a value, so `--purge my-ext` keeps `my-ext` positional. */
+const BOOLEAN_FLAGS = new Set(["purge", "yes", "force", "no-db", "no-build", "help", "json", "ui", "watch"]);
+export function parseArgs(argv) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--") {
+            positional.push(...argv.slice(i + 1));
+            break;
+        }
+        if (a.startsWith("--")) {
+            const eq = a.indexOf("=");
+            if (eq > 0) {
+                flags[a.slice(2, eq)] = a.slice(eq + 1);
+                continue;
+            }
+            const name = a.slice(2);
+            if (!BOOLEAN_FLAGS.has(name) && i + 1 < argv.length && !argv[i + 1].startsWith("--"))
+                flags[name] = argv[++i];
+            else
+                flags[name] = true;
+        }
+        else if (a === "-h") {
+            flags.help = true;
+        }
+        else {
+            positional.push(a);
+        }
+    }
+    return { positional, flags };
+}
+/** A string flag, or undefined (a bare `--flag` is not a value). */
+export function str(flags, name) {
+    const v = flags[name];
+    return typeof v === "string" ? v : undefined;
+}
+/** A boolean flag: present bare, or `--flag=true|false`. */
+export function bool(flags, name) {
+    const v = flags[name];
+    return v === true || v === "true" || v === "1";
+}
+export function int(flags, name) {
+    const v = str(flags, name);
+    if (v === undefined)
+        return undefined;
+    const n = Number(v);
+    if (!Number.isInteger(n) || n < 0 || n > 65_535)
+        throw new Error(`--${name} must be a port number`);
+    return n;
+}

package/dist/build.d.ts

@@ -0,0 +1,56 @@
+import { type MigrationFile, type Project, type UiFileOnDisk } from "./project.ts";
+export interface BundleOptions {
+    entryPoints: string[];
+    outfile: string;
+    bundle: true;
+    format: "esm";
+    platform: "node";
+    target: string;
+    packages: "bundle";
+    external: string[];
+    legalComments: "none";
+    logLevel: "warning" | "info" | "silent";
+    absWorkingDir: string;
+}
+export type Bundler = (options: BundleOptions) => Promise<unknown>;
+export type ManifestValidator = (manifest: unknown) => {
+    ok: boolean;
+    errors: {
+        path: string;
+        message: string;
+    }[];
+};
+/** The published contract's bundle lint (`lintBundle` from @sparelabs/sightline-extension-manifest). */
+export type BundleLinter = (source: string) => {
+    errors: string[];
+    warnings: string[];
+};
+export interface BuildDeps {
+    bundler: Bundler;
+    validate: ManifestValidator;
+    lint: BundleLinter;
+    /** Core's bundle size limit (`MAX_BUNDLE_BYTES` from the manifest package). */
+    maxBundleBytes: number;
+    /** The published UI asset rules (`uiAssetProblems`); checks the UI build of a manifest with ui.frames. */
+    validateUi?: UiValidator;
+}
+export interface BuildResult {
+    bundle: Uint8Array;
+    bundlePath: string;
+    migrations: MigrationFile[];
+    /** The UI build to upload (ui.frames), or null. */
+    ui: UiFileOnDisk[] | null;
+    warnings: string[];
+}
+export declare function bundleOptions(project: Project): BundleOptions;
+/** Manifest problems: the published schema and rules, then what core's publish adds. */
+export declare function manifestProblems(project: Project, validate: ManifestValidator): string[];
+/** The published contract's UI asset rules (`uiAssetProblems` from @sparelabs/sightline-extension-manifest). */
+export type UiValidator = (files: UiFileOnDisk[], entry: string) => string[];
+/**
+ * The UI build `deploy` uploads, for a manifest with ui.frames: every file
+ * under the UI directory, checked with core's own publish rules. Null when the
+ * manifest declares no frames.
+ */
+export declare function collectUi(project: Project, validate?: UiValidator): UiFileOnDisk[] | null;
+export declare function build(project: Project, deps: BuildDeps): Promise<BuildResult>;

package/dist/build.js

@@ -0,0 +1,73 @@
+// `sightline-ext build`: validate the manifest against the published contract,
+// check the migrations, bundle the server into one ESM file (the ext-runtime's
+// bundle contract: no npm or remote imports at runtime; node: built-ins stay
+// external), and lint the bundle the way core's publish does.
+//
+// The bundler, the manifest validator and the bundle lint are passed in, so
+// this module has no package imports (the Deno tests run it with fakes; cli.ts
+// wires esbuild and @sparelabs/sightline-extension-manifest, whose lintBundle
+// and MAX_BUNDLE_BYTES are the very ones core's installer uses).
+import { relative } from "node:path";
+import { hostedRuleProblems, readMigrations, readUiFiles, uiFrames } from "./project.js";
+export function bundleOptions(project) {
+    return {
+        entryPoints: [project.entry],
+        outfile: project.outfile,
+        bundle: true,
+        format: "esm",
+        platform: "node",
+        target: "es2022",
+        packages: "bundle",
+        external: ["node:*"],
+        legalComments: "none",
+        logLevel: "warning",
+        absWorkingDir: project.dir,
+    };
+}
+/** Manifest problems: the published schema and rules, then what core's publish adds. */
+export function manifestProblems(project, validate) {
+    const result = validate(project.manifest);
+    const problems = result.errors.map((e) => `${e.path || "(root)"}: ${e.message}`);
+    if (problems.length === 0)
+        problems.push(...hostedRuleProblems(project.manifest));
+    return problems;
+}
+/**
+ * The UI build `deploy` uploads, for a manifest with ui.frames: every file
+ * under the UI directory, checked with core's own publish rules. Null when the
+ * manifest declares no frames.
+ */
+export function collectUi(project, validate) {
+    const frames = uiFrames(project.manifest);
+    if (!frames)
+        return null;
+    const rel = relative(project.dir, project.uiDir) || project.uiDir;
+    if (!project.fs.isDirectory(project.uiDir)) {
+        throw new Error(`the manifest declares ui.frames, but there is no UI build at ${rel}: build your UI there first (or set "ui": { "dir": … } in sightline-ext.json)`);
+    }
+    const files = readUiFiles(project.uiDir, project.fs);
+    const problems = validate ? validate(files, frames.entry) : [];
+    if (problems.length)
+        throw new Error(`the UI build at ${rel} would be refused at publish:\n  ${problems.join("\n  ")}`);
+    return files;
+}
+export async function build(project, deps) {
+    const rel = (p) => relative(project.dir, p) || p;
+    const problems = manifestProblems(project, deps.validate);
+    if (problems.length)
+        throw new Error(`${rel(project.manifestPath)} does not meet the extension contract:\n  ${problems.join("\n  ")}`);
+    const migrations = readMigrations(project.migrationsDir, project.fs);
+    if (!project.fs.exists(project.entry))
+        throw new Error(`no server entry at ${rel(project.entry)} (set "entry" in sightline-ext.json)`);
+    const ui = collectUi(project, deps.validateUi);
+    await deps.bundler(bundleOptions(project));
+    const bundle = project.fs.readBytes(project.outfile);
+    if (bundle.length === 0)
+        throw new Error(`${rel(project.outfile)} is empty`);
+    if (bundle.length > deps.maxBundleBytes)
+        throw new Error(`${rel(project.outfile)} is ${bundle.length} bytes; core accepts at most ${deps.maxBundleBytes}`);
+    const lint = deps.lint(new TextDecoder().decode(bundle));
+    if (lint.errors.length)
+        throw new Error(`${rel(project.outfile)} would be refused at publish:\n  ${lint.errors.join("\n  ")}`);
+    return { bundle, bundlePath: project.outfile, migrations, ui, warnings: lint.warnings };
+}

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+export declare const USAGE = "sightline-ext <command> [options]\n\n  init <dir>     Scaffold a new extension repository\n                 [--id <kebab-id>] [--name \"Display name\"] [--publisher <kebab-id>] [--force]\n  build          Validate the manifest and migrations, bundle server/main.ts into dist/server.mjs\n  dev            Build, then run the extension against an emulated Sightline, rebuilding on change\n                 [--port <n>] [--core-port 8787] [--no-db]\n  test           Build, run the extension against the emulator, and check the HTTP contract\n                 [--no-build] [--no-db] [--keep-db]\n  deploy         Build, publish the release and install it in a workspace\n  upgrade        Build, publish the release and move the installed extension to it\n                 (deploy, upgrade: [--bindings bindings.json] [--no-build])\n  uninstall      Remove the extension from the workspace (its data is kept 30 days)\n                 [--purge --yes]\n\n  Common: [--dir <project>] [--manifest sightline.extension.json] [--config sightline-ext.json]\n  deploy, upgrade, uninstall: [--url https://<workspace>] [--api-url <core API base>]\n\nDeploying needs the workspace and a deploy token issued by one of its admins:\n  SIGHTLINE_URL           https://<your workspace>   (or SIGHTLINE_API_URL, the full core API base)\n  SIGHTLINE_DEPLOY_TOKEN  the token (only ever read from the environment)\n  SIGHTLINE_API_KEY       the gateway's public api key, when your workspace needs one";
+export type Out = (line: string) => void;
+export declare function packageVersion(): string;
+export declare function main(argv: string[], out?: Out): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,288 @@
+// sightline-ext: scaffold, run, build, test and deploy a hosted Sightline extension.
+// docs/platform/hosted-extensions.md → "The CLI".
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { createCoreEmulator, freePort, listen, runExtension, startDatabase } from "@sparelabs/sightline-extension-devkit";
+import { lintBundle, MAX_BUNDLE_BYTES, uiAssetProblems, validateManifest } from "@sparelabs/sightline-extension-manifest";
+import { assertContract, formatReport, runContractTests } from "@sparelabs/sightline-extension-testing";
+import { bool, int, parseArgs, str } from "./args.js";
+import { build, bundleOptions } from "./build.js";
+import { CoreApiError, createCoreApi, describeError } from "./core-api.js";
+import { deploy, parseBindings, uninstall, upgrade } from "./deploy.js";
+import { defaultContract, loadProject } from "./project.js";
+import { templateFiles } from "./template.js";
+export const USAGE = `sightline-ext <command> [options]
+
+  init <dir>     Scaffold a new extension repository
+                 [--id <kebab-id>] [--name "Display name"] [--publisher <kebab-id>] [--force]
+  build          Validate the manifest and migrations, bundle server/main.ts into dist/server.mjs
+  dev            Build, then run the extension against an emulated Sightline, rebuilding on change
+                 [--port <n>] [--core-port 8787] [--no-db]
+  test           Build, run the extension against the emulator, and check the HTTP contract
+                 [--no-build] [--no-db] [--keep-db]
+  deploy         Build, publish the release and install it in a workspace
+  upgrade        Build, publish the release and move the installed extension to it
+                 (deploy, upgrade: [--bindings bindings.json] [--no-build])
+  uninstall      Remove the extension from the workspace (its data is kept 30 days)
+                 [--purge --yes]
+
+  Common: [--dir <project>] [--manifest sightline.extension.json] [--config sightline-ext.json]
+  deploy, upgrade, uninstall: [--url https://<workspace>] [--api-url <core API base>]
+
+Deploying needs the workspace and a deploy token issued by one of its admins:
+  SIGHTLINE_URL           https://<your workspace>   (or SIGHTLINE_API_URL, the full core API base)
+  SIGHTLINE_DEPLOY_TOKEN  the token (only ever read from the environment)
+  SIGHTLINE_API_KEY       the gateway's public api key, when your workspace needs one`;
+/** The published contract's checks, the same functions core's installer runs at publish. */
+const CONTRACT = { validate: validateManifest, lint: lintBundle, maxBundleBytes: MAX_BUNDLE_BYTES, validateUi: uiAssetProblems };
+export function packageVersion() {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    return pkg.version;
+}
+const esbuildBundler = async (options) => {
+    const esbuild = await import("esbuild");
+    await esbuild.build(options);
+};
+function project(flags) {
+    return loadProject(str(flags, "dir") ?? ".", { manifest: str(flags, "manifest"), config: str(flags, "config"), entry: str(flags, "entry") });
+}
+async function buildProject(p, out) {
+    const result = await build(p, { bundler: esbuildBundler, ...CONTRACT });
+    out(`built ${relative(process.cwd(), result.bundlePath) || result.bundlePath} (${result.bundle.length} bytes; ${result.migrations.length} migration(s)); manifest ${p.id}@${p.version} is valid`);
+    if (result.ui)
+        out(`  UI: ${result.ui.length} file(s) from ${relative(process.cwd(), p.uiDir) || p.uiDir}, uploaded with the release on deploy`);
+    for (const w of result.warnings)
+        out(`  warning: ${w}`);
+    return result;
+}
+function secretEnv(p) {
+    const env = {};
+    for (const [k, v] of Object.entries(process.env))
+        if (k.startsWith("SL_SECRET_") && v !== undefined)
+            env[k] = v;
+    for (const [name, value] of Object.entries(p.config.devSecrets ?? {})) {
+        if (!/^[a-z][a-z0-9_-]{0,63}$/i.test(name) || typeof value !== "string")
+            throw new Error(`devSecrets: "${name}" must be a secret name with a string value`);
+        env[`SL_SECRET_${name.toUpperCase().replace(/-/g, "_")}`] = value;
+    }
+    return env;
+}
+const hasMigrations = (p) => existsSync(p.migrationsDir) && readdirSync(p.migrationsDir).some((f) => f.endsWith(".sql"));
+function waitForSignal() {
+    return new Promise((done) => {
+        process.once("SIGINT", () => done());
+        process.once("SIGTERM", () => done());
+    });
+}
+// ── commands ─────────────────────────────────────────────────────────────────
+function init(positional, flags, out) {
+    const target = positional[0];
+    if (!target)
+        throw new Error("usage: sightline-ext init <dir> [--id <kebab-id>]");
+    const dir = resolve(target);
+    const id = str(flags, "id") ?? basename(dir);
+    const files = templateFiles({ id, name: str(flags, "name"), publisher: str(flags, "publisher"), packagesVersion: packageVersion() });
+    if (existsSync(dir) && readdirSync(dir).length > 0 && !bool(flags, "force")) {
+        throw new Error(`${target} is not empty (pass --force to write into it anyway; existing files with the same names are replaced)`);
+    }
+    for (const [path, content] of Object.entries(files)) {
+        const file = join(dir, path);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, content);
+    }
+    out(`created ${id} in ${target}:`);
+    for (const path of Object.keys(files))
+        out(`  ${path}`);
+    out(`\nnext:\n  cd ${target}\n  npm install\n  npm test        # needs Deno and Docker`);
+    return 0;
+}
+async function dev(flags, out) {
+    const p = project(flags);
+    await buildProject(p, out);
+    const emulator = await createCoreEmulator({ extension: p.id, version: p.version, settings: p.config.settings ?? {} });
+    const core = await listen(emulator.handler, { port: int(flags, "core-port") ?? 8787 });
+    emulator.setOrigin(core.url);
+    const env = emulator.runtimeEnv(secretEnv(p));
+    let db = null;
+    if (!bool(flags, "no-db") && hasMigrations(p)) {
+        db = await startDatabase({ extension: p.id, migrationsDir: p.migrationsDir });
+        env.SL_DB_URL = db.url;
+        out(`database   ${db.container} (${db.database}; applied ${db.applied.length ? db.applied.join(", ") : "nothing new"})`);
+    }
+    const port = int(flags, "port") ?? (await freePort());
+    let ext = await runExtension({ bundle: p.outfile, env, port });
+    // The devkit's state file, so `npx sightline-devkit invoke …` finds this run.
+    mkdirSync(join(p.dir, ".sightline-devkit"), { recursive: true });
+    writeFileSync(join(p.dir, ".sightline-devkit", "state.json"), `${JSON.stringify({ coreUrl: core.url, extensionUrl: ext.url }, null, 2)}\n`);
+    out(`core       ${core.url}  (emulated: JWKS, ext-api, /__devkit/token)`);
+    out(`extension  ${ext.url}  (Sightline's runtime flags)`);
+    const firstTool = Array.isArray(p.manifest.tools) ? p.manifest.tools.find((t) => typeof t?.name === "string")?.name : undefined;
+    out(firstTool ? `try        npx sightline-devkit invoke tool ${String(firstTool)} --as user:alice` : "try        npx sightline-devkit invoke api /<path> --as user:alice");
+    out("watching for changes; Ctrl-C stops");
+    const esbuild = await import("esbuild");
+    let restarting = Promise.resolve();
+    const ctx = await esbuild.context({
+        ...bundleOptions(p),
+        plugins: [{
+                name: "sightline-ext-restart",
+                setup(b) {
+                    let first = true;
+                    b.onEnd((result) => {
+                        if (first) {
+                            first = false;
+                            return;
+                        }
+                        if (result.errors.length)
+                            return;
+                        const lint = lintBundle(readFileSync(p.outfile, "utf8"));
+                        if (lint.errors.length) {
+                            out(`rebuilt, but the bundle would be refused at publish: ${lint.errors.join("; ")}`);
+                            return;
+                        }
+                        restarting = restarting.then(async () => {
+                            await ext.stop();
+                            ext = await runExtension({ bundle: p.outfile, env, port });
+                            out(`rebuilt and restarted ${ext.url}`);
+                        }).catch((e) => out(`restart failed: ${e.message}`));
+                    });
+                },
+            }],
+    });
+    await ctx.watch();
+    await waitForSignal();
+    await ctx.dispose();
+    await restarting;
+    await ext.stop();
+    await core.close();
+    out(db ? `stopped (the database container ${db.container} keeps running; \`npx sightline-devkit db down\` removes it)` : "stopped");
+    return 0;
+}
+async function test(flags, out) {
+    const p = project(flags);
+    if (!bool(flags, "no-build"))
+        await buildProject(p, out);
+    else if (!existsSync(p.outfile))
+        throw new Error(`--no-build, but ${p.outfile} does not exist`);
+    const contract = defaultContract(p);
+    const emulator = await createCoreEmulator({ extension: p.id, version: p.version, settings: p.config.settings ?? {} });
+    const core = await listen(emulator.handler);
+    emulator.setOrigin(core.url);
+    const env = emulator.runtimeEnv(secretEnv(p));
+    let db = null;
+    let ext = null;
+    try {
+        if (!bool(flags, "no-db") && hasMigrations(p)) {
+            db = await startDatabase({ extension: p.id, migrationsDir: p.migrationsDir, container: `sightline-ext-test-${p.id}-${process.pid}` });
+            env.SL_DB_URL = db.url;
+            out(`database ${db.database}: applied ${db.applied.join(", ") || "nothing"}`);
+        }
+        ext = await runExtension({ bundle: p.outfile, env, port: await freePort() });
+        const report = await runContractTests(ext.url, {
+            coreUrl: core.url,
+            tool: contract.tool,
+            job: contract.job,
+            hook: contract.hook,
+            expect: { version: p.version },
+        });
+        out(formatReport(report));
+        try {
+            assertContract(report);
+        }
+        catch {
+            return 1;
+        }
+        out(`${p.id}@${p.version} meets the contract`);
+        return 0;
+    }
+    finally {
+        await ext?.stop();
+        await core.close();
+        if (db && !bool(flags, "keep-db"))
+            await db.stop();
+    }
+}
+function coreApiFromEnv(flags, env = process.env) {
+    const token = env.SIGHTLINE_DEPLOY_TOKEN;
+    if (!token)
+        throw new Error("set SIGHTLINE_DEPLOY_TOKEN to a deploy token from a workspace admin (it is only read from the environment)");
+    // --url / --api-url override SIGHTLINE_URL / SIGHTLINE_API_URL; the token never comes from a flag.
+    const url = str(flags, "url") ?? env.SIGHTLINE_URL;
+    const apiUrl = str(flags, "api-url") ?? (str(flags, "url") ? undefined : env.SIGHTLINE_API_URL);
+    return createCoreApi({ url, apiUrl, token, apiKey: env.SIGHTLINE_API_KEY });
+}
+function readBindings(flags) {
+    const file = str(flags, "bindings");
+    if (!file)
+        return undefined;
+    return parseBindings(JSON.parse(readFileSync(file, "utf8")));
+}
+async function release(flags, out) {
+    const p = project(flags);
+    let built;
+    if (bool(flags, "no-build")) {
+        if (!existsSync(p.outfile))
+            throw new Error(`--no-build, but ${p.outfile} does not exist`);
+        built = await build(p, { bundler: async () => undefined, ...CONTRACT });
+    }
+    else {
+        built = await buildProject(p, out);
+    }
+    return { manifest: p.manifest, bundle: built.bundle, migrations: built.migrations, ui: built.ui };
+}
+export async function main(argv, out = console.log) {
+    const { positional, flags } = parseArgs(argv);
+    const [command, ...rest] = positional;
+    if (!command && flags.version === true) {
+        out(packageVersion());
+        return 0;
+    }
+    try {
+        switch (command) {
+            case "init":
+                return init(rest, flags, out);
+            case "build":
+                await buildProject(project(flags), out);
+                return 0;
+            case "dev":
+                return await dev(flags, out);
+            case "test":
+                return await test(flags, out);
+            case "deploy": {
+                const api = coreApiFromEnv(flags);
+                await deploy(api, await release(flags, out), { bindings: readBindings(flags) }, out);
+                return 0;
+            }
+            case "upgrade": {
+                const api = coreApiFromEnv(flags);
+                await upgrade(api, await release(flags, out), { bindings: readBindings(flags) }, out);
+                return 0;
+            }
+            case "uninstall": {
+                const purge = bool(flags, "purge");
+                if (purge && !bool(flags, "yes"))
+                    throw new Error("--purge drops the extension's data now and cannot be undone; add --yes to confirm");
+                const api = coreApiFromEnv(flags);
+                const id = rest[0] ?? project(flags).id;
+                await uninstall(api, id, { purge }, out);
+                return 0;
+            }
+            case "version":
+                out(packageVersion());
+                return 0;
+            case undefined:
+            case "help":
+                out(USAGE);
+                return command ? 0 : bool(flags, "help") ? 0 : 2;
+            default:
+                out(`unknown command ${command}\n\n${USAGE}`);
+                return 2;
+        }
+    }
+    catch (e) {
+        if (e instanceof CoreApiError) {
+            out(`error: ${describeError(e)}`);
+            return 1;
+        }
+        throw e;
+    }
+}