@sparelabs/sightline-extension-cli 0.1.0

package/dist/core-api.d.ts

@@ -0,0 +1,98 @@
+export interface CoreApiOptions {
+    /** The workspace's URL, e.g. https://sightline.example.com (the API is under /functions/v1/core/v1). */
+    url?: string;
+    /** The full API base instead, e.g. https://api.example.com/functions/v1/core/v1. */
+    apiUrl?: string;
+    token: string;
+    /** Sent as `apikey` when the workspace's gateway wants one. */
+    apiKey?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+export interface ReleaseView {
+    extensionId: string;
+    version: string;
+    manifestSha256: string;
+    bundleSha256: string;
+    coreApiCompatible?: boolean;
+    permissions?: {
+        key: string;
+        label?: string;
+        default?: string | null;
+    }[];
+    checks?: {
+        warnings?: string[];
+        ui?: {
+            files: number;
+            bytes: number;
+            sha256: string;
+        };
+    };
+    [key: string]: unknown;
+}
+export interface InstallationView {
+    extensionId: string;
+    installationId: string;
+    state: string;
+    version: string;
+    bindings?: Record<string, string>;
+    lastError?: string | null;
+    [key: string]: unknown;
+}
+export interface PublishInput {
+    manifest: Record<string, unknown>;
+    bundle: Uint8Array;
+    migrations: {
+        file: string;
+        sql: string;
+    }[];
+    /** The UI build (ui.frames), uploaded with the release: each file's path relative to the build and its bytes. */
+    ui?: {
+        path: string;
+        bytes: Uint8Array;
+    }[] | null;
+}
+export declare class CoreApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown>);
+}
+export declare function apiBase(options: Pick<CoreApiOptions, "url" | "apiUrl">): string;
+export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+/** A human sentence for an installer error, with the details that tell you what to do. */
+export declare function describeError(err: CoreApiError): string;
+export interface CoreApi {
+    readonly base: string;
+    list(): Promise<{
+        installations: InstallationView[];
+        releases: ReleaseView[];
+    }>;
+    publish(input: PublishInput): Promise<{
+        release: ReleaseView;
+        created: boolean;
+    }>;
+    install(id: string, body: {
+        version: string;
+        bindings?: Record<string, string>;
+    }): Promise<InstallationView>;
+    upgrade(id: string, body: {
+        version: string;
+        bindings?: Record<string, string>;
+    }): Promise<InstallationView>;
+    uninstall(id: string, body: {
+        purge?: boolean;
+    }): Promise<{
+        installation: InstallationView;
+        warnings: string[];
+    }>;
+}
+/** A deploy token an admin issued (`slxd_…`), as opposed to an admin's own session token. */
+export declare function isDeployToken(token: string): boolean;
+/**
+ * Where the lifecycle routes are for this token. A deploy token (`slxd_…`) is
+ * accepted only under `<core>/deploy` (the one hosted path CI reaches past the
+ * workspace's sign-in proxy); an admin's session token uses the admin routes.
+ */
+export declare function lifecycleBase(coreBase: string, token: string): string;
+export declare function createCoreApi(options: CoreApiOptions): CoreApi;

package/dist/core-api.js

@@ -0,0 +1,166 @@
+// A client for core's hosted-extension lifecycle API
+// (docs/platform/hosted-extensions-registry.md → "The core routes"):
+//
+//   GET  /core/v1/extensions                   { installations, releases }
+//   POST /core/v1/extensions/releases          { manifest, bundle: { base64, sha256 }, migrations? }
+//   POST /core/v1/extensions/:id/install       { version, bindings? }
+//   POST /core/v1/extensions/:id/upgrade       { version, bindings? }
+//   POST /core/v1/extensions/:id/uninstall     { purge? }
+//
+// Auth is a bearer token from SIGHTLINE_DEPLOY_TOKEN: a deploy token a tenant
+// admin issued (`slxd_…`, sent to the same routes under /core/v1/deploy, the
+// only place one is accepted), or an admin's own session token.
+// Errors are `{ error: { code, message, ...details } }`.
+export class CoreApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details = {}) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+        this.name = "CoreApiError";
+    }
+}
+export function apiBase(options) {
+    const raw = options.apiUrl ?? (options.url ? `${options.url.replace(/\/+$/, "")}/functions/v1/core/v1` : undefined);
+    if (!raw)
+        throw new Error("name the workspace: --url https://<your sightline> (or SIGHTLINE_URL)");
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new Error(`not a URL: ${raw}`);
+    }
+    // WHATWG URL keeps the brackets on an IPv6 hostname ("[::1]"); accept both spellings.
+    const local = ["localhost", "127.0.0.1", "[::1]", "::1"].includes(u.hostname);
+    if (u.protocol !== "https:" && !(u.protocol === "http:" && local)) {
+        throw new Error(`refusing to send a deploy token over ${u.protocol}//${u.host}; use https (http is allowed for localhost only)`);
+    }
+    if (u.username || u.password)
+        throw new Error("put the token in SIGHTLINE_DEPLOY_TOKEN, not in the URL");
+    return u.toString().replace(/\/+$/, "");
+}
+const toBase64 = (bytes) => {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        bin += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(bin);
+};
+export async function sha256Hex(bytes) {
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** A human sentence for an installer error, with the details that tell you what to do. */
+export function describeError(err) {
+    const d = err.details;
+    switch (err.code) {
+        case "route_missing":
+            return err.message;
+        case "consent_required":
+        case "binding_required": {
+            const missing = (d.missing ?? d.permissions ?? []);
+            const names = missing.map((p) => (typeof p === "string" ? p : `${p.permission ?? p.key}${p.proposed ? ` (proposed: ${p.proposed})` : ""}`));
+            return `${err.message}${names.length ? `\n  bind: ${names.join(", ")}` : ""}\n  pass --bindings bindings.json ({ "<permission>": "<core permission you hold>" })`;
+        }
+        case "invalid_manifest": {
+            const errors = (d.errors ?? []);
+            return `${err.message}${errors.map((e) => `\n  ${e.path ?? ""}: ${e.message ?? ""}`).join("")}`;
+        }
+        case "bundle_rejected":
+        case "ui_rejected": {
+            const errors = (d.errors ?? []);
+            return `${err.message}${errors.map((e) => `\n  ${e}`).join("")}`;
+        }
+        default:
+            return err.message;
+    }
+}
+/** A deploy token an admin issued (`slxd_…`), as opposed to an admin's own session token. */
+export function isDeployToken(token) {
+    return /^slxd_/i.test(token);
+}
+/**
+ * Where the lifecycle routes are for this token. A deploy token (`slxd_…`) is
+ * accepted only under `<core>/deploy` (the one hosted path CI reaches past the
+ * workspace's sign-in proxy); an admin's session token uses the admin routes.
+ */
+export function lifecycleBase(coreBase, token) {
+    return isDeployToken(token) ? `${coreBase}/deploy` : coreBase;
+}
+export function createCoreApi(options) {
+    if (!options.token || /\s/.test(options.token))
+        throw new Error("SIGHTLINE_DEPLOY_TOKEN is missing or malformed");
+    const base = lifecycleBase(apiBase(options), options.token);
+    const doFetch = options.fetch ?? fetch;
+    const timeoutMs = options.timeoutMs ?? 180_000;
+    async function call(method, path, body) {
+        const headers = { authorization: `Bearer ${options.token}`, accept: "application/json" };
+        if (options.apiKey)
+            headers.apikey = options.apiKey;
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        let res;
+        try {
+            res = await doFetch(`${base}${path}`, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                redirect: "error",
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (e) {
+            throw new Error(`cannot reach ${base}: ${e.message}`);
+        }
+        const text = await res.text();
+        let parsed = null;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            parsed = null;
+        }
+        if (res.ok)
+            return parsed;
+        const error = (parsed && typeof parsed === "object" ? parsed.error : undefined);
+        if (error && typeof error.code === "string") {
+            const { code, message, ...details } = error;
+            throw new CoreApiError(res.status, code, typeof message === "string" ? message : code, details);
+        }
+        if (res.status === 401)
+            throw new CoreApiError(401, "unauthenticated", "the deploy token was refused (expired, revoked, or not a tenant admin's)");
+        if (res.status === 403)
+            throw new CoreApiError(403, "forbidden", "the deploy token may not manage extensions in this workspace");
+        if (res.status === 404) {
+            throw new CoreApiError(404, "route_missing", `${base}${path} does not exist: this Sightline has no hosted-extension installer yet, or --url is not a Sightline workspace`);
+        }
+        throw new CoreApiError(res.status, "http_error", `${method} ${path} answered HTTP ${res.status}${text ? `: ${text.slice(0, 300)}` : ""}`);
+    }
+    return {
+        base,
+        list: () => call("GET", "/extensions"),
+        async publish({ manifest, bundle, migrations, ui }) {
+            return await call("POST", "/extensions/releases", {
+                manifest,
+                bundle: { base64: toBase64(bundle), sha256: await sha256Hex(bundle) },
+                migrations,
+                ...(ui && ui.length > 0
+                    ? { ui: { files: await Promise.all(ui.map(async (f) => ({ path: f.path, base64: toBase64(f.bytes), sha256: await sha256Hex(f.bytes) }))) } }
+                    : {}),
+            });
+        },
+        async install(id, body) {
+            return (await call("POST", `/extensions/${encodeURIComponent(id)}/install`, body)).installation;
+        },
+        async upgrade(id, body) {
+            return (await call("POST", `/extensions/${encodeURIComponent(id)}/upgrade`, body)).installation;
+        },
+        async uninstall(id, body) {
+            const r = await call("POST", `/extensions/${encodeURIComponent(id)}/uninstall`, body);
+            return { installation: r.installation, warnings: r.warnings ?? [] };
+        },
+    };
+}

package/dist/deploy.d.ts

@@ -0,0 +1,13 @@
+import type { CoreApi, InstallationView, PublishInput } from "./core-api.ts";
+export type Out = (line: string) => void;
+export declare function deploy(api: CoreApi, release: PublishInput, options: {
+    bindings?: Record<string, string>;
+}, out: Out): Promise<InstallationView>;
+export declare function upgrade(api: CoreApi, release: PublishInput, options: {
+    bindings?: Record<string, string>;
+}, out: Out): Promise<InstallationView>;
+export declare function uninstall(api: CoreApi, id: string, options: {
+    purge: boolean;
+}, out: Out): Promise<InstallationView>;
+/** --bindings <file>: { "<ext>.<permission>": "<core permission>" }. */
+export declare function parseBindings(raw: unknown): Record<string, string>;

package/dist/deploy.js

@@ -0,0 +1,71 @@
+/** States in which an extension counts as installed (core keeps the row after uninstall). */
+const LIVE = new Set(["enabled", "disabled", "provisioning"]);
+async function current(api, id) {
+    const { installations } = await api.list();
+    return installations.find((i) => i.extensionId === id && LIVE.has(i.state)) ?? null;
+}
+async function publish(api, release, out) {
+    const id = release.manifest.id;
+    const version = release.manifest.version;
+    const { release: published, created } = await api.publish(release);
+    out(created ? `published ${id}@${version} (bundle sha256 ${published.bundleSha256.slice(0, 12)}…)` : `${id}@${version} is already published with these exact bytes`);
+    const ui = published.checks?.ui;
+    if (created && ui)
+        out(`  uploaded the UI: ${ui.files} files, ${ui.bytes} bytes (sha256 ${ui.sha256.slice(0, 12)}…)`);
+    for (const w of published.checks?.warnings ?? [])
+        out(`  warning: ${w}`);
+    if (published.coreApiCompatible === false)
+        out(`  warning: this workspace's core does not satisfy coreApi ${String(release.manifest.coreApi)}; install will be refused`);
+}
+export async function deploy(api, release, options, out) {
+    const id = release.manifest.id;
+    const version = release.manifest.version;
+    const existing = await current(api, id);
+    if (existing && existing.version !== version) {
+        throw new Error(`${id} is already installed at ${existing.version}; run \`sightline-ext upgrade\` to move it to ${version}`);
+    }
+    await publish(api, release, out);
+    if (existing) {
+        out(`${id}@${version} is already installed (${existing.state}); nothing to do`);
+        return existing;
+    }
+    const installation = await api.install(id, { version, ...(options.bindings ? { bindings: options.bindings } : {}) });
+    out(`installed ${id}@${installation.version}: ${installation.state} (installation ${installation.installationId})`);
+    return installation;
+}
+export async function upgrade(api, release, options, out) {
+    const id = release.manifest.id;
+    const version = release.manifest.version;
+    const existing = await current(api, id);
+    if (!existing)
+        throw new Error(`${id} is not installed in this workspace; run \`sightline-ext deploy\` first`);
+    await publish(api, release, out);
+    if (existing.version === version) {
+        out(`${id} already runs ${version}; nothing to upgrade (bump "version" in the manifest to release a change)`);
+        return existing;
+    }
+    const installation = await api.upgrade(id, { version, ...(options.bindings ? { bindings: options.bindings } : {}) });
+    out(`upgraded ${id} ${existing.version} → ${installation.version}: ${installation.state}`);
+    return installation;
+}
+export async function uninstall(api, id, options, out) {
+    const { installation, warnings } = await api.uninstall(id, { purge: options.purge });
+    out(options.purge
+        ? `uninstalled ${id} and dropped its data`
+        : `uninstalled ${id}; its data is kept${installation.purgeAfter ? ` until ${String(installation.purgeAfter)}` : " for 30 days"} (\`--purge\` drops it now)`);
+    for (const w of warnings)
+        out(`  warning: ${w}`);
+    return installation;
+}
+/** --bindings <file>: { "<ext>.<permission>": "<core permission>" }. */
+export function parseBindings(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("bindings must be a JSON object of permission → core permission");
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v !== "string" || v === "")
+            throw new Error(`the binding for ${k} must be a core permission name`);
+        out[k] = v;
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { main, packageVersion, USAGE } from "./cli.ts";
+export { bool, type Flags, parseArgs, type ParsedArgs, str } from "./args.ts";
+export { build, type BuildDeps, type BuildResult, type Bundler, type BundleLinter, bundleOptions, type BundleOptions, collectUi, manifestProblems, type ManifestValidator, type UiValidator } from "./build.ts";
+export { apiBase, type CoreApi, CoreApiError, type CoreApiOptions, createCoreApi, describeError, type InstallationView, isDeployToken, lifecycleBase, type PublishInput, type ReleaseView, sha256Hex } from "./core-api.ts";
+export { deploy, parseBindings, uninstall, upgrade } from "./deploy.ts";
+export { CONFIG_FILE, type ContractConfig, defaultContract, hostedRuleProblems, loadProject, MANIFEST_FILE, migrationProblems, type MigrationFile, type Project, type ProjectConfig, readMigrations, readUiFiles, type UiFileOnDisk, uiFrames, } from "./project.ts";
+export { lintBundle, MAX_BUNDLE_BYTES } from "@sparelabs/sightline-extension-manifest";
+export { templateFiles, type TemplateOptions, templateProblems, toolPrefix } from "./template.ts";

package/dist/index.js

@@ -0,0 +1,12 @@
+// @sparelabs/sightline-extension-cli: the `sightline-ext` command, and its parts
+// for scripts that want them. This package imports nothing from the app
+// (extension-sdk/test/boundary.test.ts).
+export { main, packageVersion, USAGE } from "./cli.js";
+export { bool, parseArgs, str } from "./args.js";
+export { build, bundleOptions, collectUi, manifestProblems } from "./build.js";
+export { apiBase, CoreApiError, createCoreApi, describeError, isDeployToken, lifecycleBase, sha256Hex } from "./core-api.js";
+export { deploy, parseBindings, uninstall, upgrade } from "./deploy.js";
+export { CONFIG_FILE, defaultContract, hostedRuleProblems, loadProject, MANIFEST_FILE, migrationProblems, readMigrations, readUiFiles, uiFrames, } from "./project.js";
+// The bundle lint is the published contract's, the same function core's installer runs.
+export { lintBundle, MAX_BUNDLE_BYTES } from "@sparelabs/sightline-extension-manifest";
+export { templateFiles, templateProblems, toolPrefix } from "./template.js";

package/dist/project.d.ts

@@ -0,0 +1,99 @@
+/** The file reads a project needs; the tests pass an in-memory one. */
+export interface ProjectFs {
+    readText(path: string): string;
+    readBytes(path: string): Uint8Array;
+    exists(path: string): boolean;
+    isDirectory(path: string): boolean;
+    list(dir: string): string[];
+}
+export declare const nodeFs: ProjectFs;
+export declare const MANIFEST_FILE = "sightline.extension.json";
+export declare const CONFIG_FILE = "sightline-ext.json";
+export declare const DEFAULT_ENTRY = "server/main.ts";
+export declare const DEFAULT_OUTFILE = "dist/server.mjs";
+export declare const DEFAULT_MIGRATIONS = "migrations";
+/** Where the extension's UI build is read from when the manifest declares ui.frames. */
+export declare const DEFAULT_UI_DIR = "dist/ui";
+/** Core's publish limits (installer.ts) on migrations. The bundle's limit and lint come from the manifest package. */
+export declare const MAX_MIGRATION_BYTES: number;
+export declare const MAX_MIGRATIONS = 200;
+export declare const EXT_ID_RE: RegExp;
+export declare const MIGRATION_FILE_RE: RegExp;
+export interface ContractConfig {
+    tool?: {
+        name: string;
+        input?: Record<string, unknown>;
+        as?: string;
+    };
+    job?: {
+        name: string;
+        payload?: unknown;
+    };
+    hook?: {
+        name: string;
+        body?: unknown;
+    };
+}
+/** sightline-ext.json: how `dev` and `test` run the extension locally. Never deployed. */
+export interface ProjectConfig {
+    /** The server entry (default server/main.ts). */
+    entry?: string;
+    /** What `test` checks: a tool that succeeds, and optionally a job and a hook. */
+    contract?: ContractConfig;
+    /** The installation settings the emulated core answers with. */
+    settings?: Record<string, unknown>;
+    /** Development-only secret values, injected as SL_SECRET_<NAME>. Never deployed. */
+    devSecrets?: Record<string, string>;
+    /** The built UI `deploy` uploads with the release, for ui.frames (default dist/ui; build it with your own tool first). */
+    ui?: {
+        dir?: string;
+    };
+}
+export interface UiFileOnDisk {
+    /** Relative to the UI directory, `/`-separated. */
+    path: string;
+    bytes: Uint8Array;
+}
+export interface MigrationFile {
+    file: string;
+    sql: string;
+}
+export interface Project {
+    dir: string;
+    manifestPath: string;
+    manifest: Record<string, unknown>;
+    id: string;
+    version: string;
+    entry: string;
+    outfile: string;
+    migrationsDir: string;
+    uiDir: string;
+    config: ProjectConfig;
+    fs: ProjectFs;
+}
+export declare function loadProject(dir: string, options?: {
+    manifest?: string;
+    config?: string;
+    entry?: string;
+}, fs?: ProjectFs): Project;
+/**
+ * Problems core's publish would refuse that the manifest schema alone does
+ * not catch: a hosted, T2 extension, a kebab-case id, a plain MAJOR.MINOR.PATCH
+ * version, and a coreApi range.
+ */
+export declare function hostedRuleProblems(manifest: Record<string, unknown>): string[];
+/** The manifest's `ui.frames`, when it declares an iframe UI. */
+export declare function uiFrames(manifest: Record<string, unknown>): {
+    entry: string;
+} | null;
+/**
+ * Every file under the UI build directory, with `/`-separated relative paths,
+ * sorted. Hidden files and directories (`.DS_Store`, `.vite/`) are skipped:
+ * they are never served.
+ */
+export declare function readUiFiles(dir: string, fs?: ProjectFs): UiFileOnDisk[];
+/** The migrations directory's .sql files, checked the way core's publish checks them. */
+export declare function readMigrations(dir: string, fs?: ProjectFs): MigrationFile[];
+export declare function migrationProblems(files: MigrationFile[]): string[];
+/** The tool `test` calls when sightline-ext.json names none: the manifest's first, as user:alice. */
+export declare function defaultContract(project: Project): Required<Pick<ContractConfig, "tool">> & ContractConfig;

package/dist/project.js

@@ -0,0 +1,165 @@
+// An extension project on disk: the manifest, the server entry and bundle path,
+// the migrations, and the optional sightline-ext.json. The checks here mirror
+// what core's installer refuses at publish (docs/platform/hosted-extensions-registry.md
+// → "The rules"), so a developer sees the problem at build time, not at deploy.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+export const nodeFs = {
+    readText: (path) => readFileSync(path, "utf8"),
+    readBytes: (path) => new Uint8Array(readFileSync(path)),
+    exists: (path) => existsSync(path),
+    isDirectory: (path) => existsSync(path) && statSync(path).isDirectory(),
+    list: (dir) => readdirSync(dir),
+};
+export const MANIFEST_FILE = "sightline.extension.json";
+export const CONFIG_FILE = "sightline-ext.json";
+export const DEFAULT_ENTRY = "server/main.ts";
+export const DEFAULT_OUTFILE = "dist/server.mjs";
+export const DEFAULT_MIGRATIONS = "migrations";
+/** Where the extension's UI build is read from when the manifest declares ui.frames. */
+export const DEFAULT_UI_DIR = "dist/ui";
+/** Core's publish limits (installer.ts) on migrations. The bundle's limit and lint come from the manifest package. */
+export const MAX_MIGRATION_BYTES = 256 * 1024;
+export const MAX_MIGRATIONS = 200;
+export const EXT_ID_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+export const MIGRATION_FILE_RE = /^(\d{4})_([a-z0-9][a-z0-9_]{0,47})\.sql$/;
+const VERSION_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+function readJson(fs, path, what) {
+    let text;
+    try {
+        text = fs.readText(path);
+    }
+    catch (e) {
+        throw new Error(`cannot read ${what} ${path}: ${e.message}`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`${what} ${path} is not valid JSON: ${e.message}`);
+    }
+}
+export function loadProject(dir, options = {}, fs = nodeFs) {
+    const root = resolve(dir);
+    const manifestPath = resolve(root, options.manifest ?? MANIFEST_FILE);
+    const manifest = readJson(fs, manifestPath, "the manifest");
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+        throw new Error(`${manifestPath} must be a JSON object`);
+    const m = manifest;
+    const configPath = resolve(root, options.config ?? CONFIG_FILE);
+    const config = (fs.exists(configPath) ? readJson(fs, configPath, "the config") : {});
+    const runtime = (m.runtime ?? {});
+    return {
+        dir: root,
+        manifestPath,
+        manifest: m,
+        id: typeof m.id === "string" ? m.id : "",
+        version: typeof m.version === "string" ? m.version : "",
+        entry: resolve(root, options.entry ?? config.entry ?? DEFAULT_ENTRY),
+        outfile: resolve(root, typeof runtime.entry === "string" ? runtime.entry : DEFAULT_OUTFILE),
+        migrationsDir: join(root, DEFAULT_MIGRATIONS),
+        uiDir: resolve(root, typeof config.ui?.dir === "string" ? config.ui.dir : DEFAULT_UI_DIR),
+        config,
+        fs,
+    };
+}
+/**
+ * Problems core's publish would refuse that the manifest schema alone does
+ * not catch: a hosted, T2 extension, a kebab-case id, a plain MAJOR.MINOR.PATCH
+ * version, and a coreApi range.
+ */
+export function hostedRuleProblems(manifest) {
+    const problems = [];
+    const runtime = (manifest.runtime ?? {});
+    if (manifest.trust !== "T2" || runtime.kind !== "hosted")
+        problems.push('a hosted extension needs "trust": "T2" and "runtime": { "kind": "hosted", … }');
+    const id = manifest.id;
+    if (typeof id !== "string" || !EXT_ID_RE.test(id) || id.length > 40)
+        problems.push("id must be kebab-case, at most 40 characters");
+    if (typeof manifest.version !== "string" || !VERSION_RE.test(manifest.version))
+        problems.push("version must be MAJOR.MINOR.PATCH (no pre-release)");
+    if (typeof manifest.coreApi !== "string" || manifest.coreApi.trim() === "")
+        problems.push('coreApi must name the core API range you build against, e.g. "^0.1"');
+    return problems;
+}
+/** The manifest's `ui.frames`, when it declares an iframe UI. */
+export function uiFrames(manifest) {
+    const frames = (manifest.ui ?? {}).frames;
+    if (!frames || typeof frames !== "object")
+        return null;
+    return { entry: typeof frames.entry === "string" && frames.entry !== "" ? frames.entry : "index.html" };
+}
+/**
+ * Every file under the UI build directory, with `/`-separated relative paths,
+ * sorted. Hidden files and directories (`.DS_Store`, `.vite/`) are skipped:
+ * they are never served.
+ */
+export function readUiFiles(dir, fs = nodeFs) {
+    const out = [];
+    const walk = (abs, rel) => {
+        for (const name of fs.list(abs).sort()) {
+            if (name.startsWith("."))
+                continue;
+            const childAbs = join(abs, name);
+            const childRel = rel ? `${rel}/${name}` : name;
+            if (fs.isDirectory(childAbs))
+                walk(childAbs, childRel);
+            else
+                out.push({ path: childRel, bytes: fs.readBytes(childAbs) });
+        }
+    };
+    walk(dir, "");
+    return out.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+/** The migrations directory's .sql files, checked the way core's publish checks them. */
+export function readMigrations(dir, fs = nodeFs) {
+    if (!fs.isDirectory(dir))
+        return [];
+    const files = fs.list(dir).filter((f) => !f.startsWith(".")).sort();
+    const out = [];
+    for (const file of files) {
+        if (!file.endsWith(".sql"))
+            throw new Error(`migrations/${file}: only NNNN_<name>.sql files belong in migrations/`);
+        out.push({ file, sql: fs.readText(join(dir, file)) });
+    }
+    const problems = migrationProblems(out);
+    if (problems.length)
+        throw new Error(`migrations: ${problems.join("; ")}`);
+    return out;
+}
+export function migrationProblems(files) {
+    const problems = [];
+    if (files.length > MAX_MIGRATIONS)
+        problems.push(`at most ${MAX_MIGRATIONS} migrations`);
+    const versions = [];
+    for (const { file, sql } of files) {
+        const m = MIGRATION_FILE_RE.exec(file);
+        if (!m) {
+            problems.push(`${file}: file names are NNNN_<name>.sql (lowercase name, at most 48 characters)`);
+            continue;
+        }
+        if (sql.trim() === "")
+            problems.push(`${file} is empty`);
+        if (sql.includes("\u0000"))
+            problems.push(`${file} contains a NUL character`);
+        if (new TextEncoder().encode(sql).length > MAX_MIGRATION_BYTES)
+            problems.push(`${file} is over ${MAX_MIGRATION_BYTES} bytes`);
+        versions.push(Number(m[1]));
+    }
+    versions.sort((a, b) => a - b).forEach((v, i) => {
+        if (v !== i + 1 && problems.length === 0)
+            problems.push(`migrations are numbered from 0001 with no gaps (expected ${String(i + 1).padStart(4, "0")}, found ${String(v).padStart(4, "0")})`);
+    });
+    return problems;
+}
+/** The tool `test` calls when sightline-ext.json names none: the manifest's first, as user:alice. */
+export function defaultContract(project) {
+    const configured = project.config.contract ?? {};
+    if (configured.tool)
+        return { ...configured, tool: configured.tool };
+    const tools = Array.isArray(project.manifest.tools) ? project.manifest.tools : [];
+    const first = tools.find((t) => typeof t?.name === "string");
+    if (!first)
+        throw new Error(`the manifest declares no tools; name one under "contract.tool" in ${CONFIG_FILE}`);
+    return { ...configured, tool: { name: first.name, input: {}, as: "user:alice" } };
+}

package/dist/template.d.ts

@@ -0,0 +1,11 @@
+export interface TemplateOptions {
+    id: string;
+    name?: string;
+    publisher?: string;
+    /** The published packages' version (the CLI's own); dependencies use ^<version>. */
+    packagesVersion: string;
+}
+/** kebab-case id → the snake_case prefix of its tool names. */
+export declare const toolPrefix: (id: string) => string;
+export declare function templateProblems(options: TemplateOptions): string[];
+export declare function templateFiles(options: TemplateOptions): Record<string, string>;