@sparelabs/sightline-extension-cli 0.1.0 → 0.1.2

package/README.md

@@ -21,6 +21,7 @@ You need Node 20.19+, [Deno](https://deno.com) (the extension runtime) and Docke
 | `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. |
+| `webhooks send <name> --body <file> [--url <webhook URL>] [--secret-env VAR] [--content-type …] [--timestamp <unix s>]` | Signs the file's raw bytes the way Sightline verifies the manifest webhook `<name>` (HMAC-SHA256 hex after its `prefix`, over `<timestamp>.<raw body>` when it declares a `timestampHeader`) and POSTs them. Without `--url` it goes to the running `dev`, whose emulator verifies it like Sightline (401 with the reason when it fails, 409 for a replay) and forwards it to your `/hooks/<name>`; with `--url` (the webhook URL from the workspace's Setup) to a real workspace. The secret comes from `SL_SECRET_<NAME>` or `--secret-env VAR`, never from a flag; locally `devSecrets` win over the environment, as `dev` injects them, so the delivery is signed with the value the emulator verifies with. Exit 1 on a non-2xx answer. |
 
 Common options: `--dir <project>`, `--manifest <file>`, `--config <file>`, `--entry <file>`.
 
@@ -64,7 +65,7 @@ The deploy publishes the server bundle and migrations. Publishing a UI (`ui.fram
 
 ## Programmatic use
 
-Everything the commands use is exported: `loadProject`, `build`, `createCoreApi`, `deploy`, `upgrade`, `uninstall`, `templateFiles`, `lintBundle`, `migrationProblems`.
+Everything the commands use is exported: `loadProject`, `build`, `createCoreApi`, `deploy`, `upgrade`, `uninstall`, `templateFiles`, `lintBundle`, `migrationProblems`, `planWebhookSend`.
 
 ## License
 

package/dist/cli.d.ts

@@ -1,4 +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 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  webhooks send <name> --body <file>\n                 Sign the file's raw bytes the way Sightline verifies them and POST them: to the\n                 running `dev` (verified and forwarded to your /hooks/<name>), or with\n                 --url <webhook URL from Setup> to a workspace. The secret is read from\n                 SL_SECRET_<NAME> (or --secret-env VAR, or devSecrets), never from a flag.\n                 [--url <url>] [--secret-env VAR] [--content-type application/json] [--timestamp <unix s>]\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

@@ -2,7 +2,7 @@
 // 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 { createCoreEmulator, freePort, listen, runExtension, sendWebhook, startDatabase, webhookSignature } 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";
@@ -11,6 +11,7 @@ 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";
+import { planWebhookSend } from "./webhooks.js";
 export const USAGE = `sightline-ext <command> [options]
 
   init <dir>     Scaffold a new extension repository
@@ -25,6 +26,12 @@ export const USAGE = `sightline-ext <command> [options]
                  (deploy, upgrade: [--bindings bindings.json] [--no-build])
   uninstall      Remove the extension from the workspace (its data is kept 30 days)
                  [--purge --yes]
+  webhooks send <name> --body <file>
+                 Sign the file's raw bytes the way Sightline verifies them and POST them: to the
+                 running \`dev\` (verified and forwarded to your /hooks/<name>), or with
+                 --url <webhook URL from Setup> to a workspace. The secret is read from
+                 SL_SECRET_<NAME> (or --secret-env VAR, or devSecrets), never from a flag.
+                 [--url <url>] [--secret-env VAR] [--content-type application/json] [--timestamp <unix s>]
 
   Common: [--dir <project>] [--manifest sightline.extension.json] [--config sightline-ext.json]
   deploy, upgrade, uninstall: [--url https://<workspace>] [--api-url <core API base>]
@@ -99,10 +106,17 @@ function init(positional, flags, out) {
 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 emulator = await createCoreEmulator({
+        extension: p.id,
+        version: p.version,
+        settings: p.config.settings ?? {},
+        // Its ext-hooks route verifies webhooks with these, as core does with the installation's secrets.
+        manifest: p.manifest,
+        secrets: secretEnv(p),
+    });
     const core = await listen(emulator.handler, { port: int(flags, "core-port") ?? 8787 });
     emulator.setOrigin(core.url);
-    const env = emulator.runtimeEnv(secretEnv(p));
+    const env = emulator.runtimeEnv();
     let db = null;
     if (!bool(flags, "no-db") && hasMigrations(p)) {
         db = await startDatabase({ extension: p.id, migrationsDir: p.migrationsDir });
@@ -111,6 +125,7 @@ async function dev(flags, out) {
     }
     const port = int(flags, "port") ?? (await freePort());
     let ext = await runExtension({ bundle: p.outfile, env, port });
+    emulator.setExtensionUrl(ext.url);
     // 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`);
@@ -118,6 +133,9 @@ async function dev(flags, out) {
     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");
+    const firstHook = Array.isArray(p.manifest.webhooks) ? p.manifest.webhooks.find((w) => typeof w?.name === "string")?.name : undefined;
+    if (firstHook)
+        out(`webhooks   npx sightline-ext webhooks send ${String(firstHook)} --body event.json   (signed, verified like Sightline, forwarded)`);
     out("watching for changes; Ctrl-C stops");
     const esbuild = await import("esbuild");
     let restarting = Promise.resolve();
@@ -201,6 +219,34 @@ async function test(flags, out) {
             await db.stop();
     }
 }
+async function webhooks(positional, flags, out) {
+    const [sub, name] = positional;
+    if (sub !== "send" || !name)
+        throw new Error("usage: sightline-ext webhooks send <name> --body <file> [--url <webhook URL>]");
+    const p = project(flags);
+    const hook = webhookSignature(p.manifest, name);
+    let localCoreUrl;
+    try {
+        localCoreUrl = JSON.parse(readFileSync(join(p.dir, ".sightline-devkit", "state.json"), "utf8")).coreUrl;
+    }
+    catch {
+        localCoreUrl = undefined;
+    }
+    const plan = planWebhookSend({
+        hook: name,
+        secretName: hook.secret,
+        flags,
+        env: process.env,
+        devSecrets: p.config.devSecrets,
+        readFile: (path) => new Uint8Array(readFileSync(resolve(path))),
+        localCoreUrl,
+    });
+    const result = await sendWebhook({ url: plan.url, hook, secret: plan.secret, body: plan.body, contentType: plan.contentType, timestamp: plan.timestamp });
+    out(`POST ${plan.url}  (${plan.body.length} bytes, signed with ${plan.secretFrom}${hook.timestampHeader ? `, ${hook.timestampHeader} ${result.headers[hook.timestampHeader]}` : ""})`);
+    out(`HTTP ${result.status}`);
+    out(typeof result.body === "string" ? result.body : JSON.stringify(result.body, null, 2));
+    return result.status >= 200 && result.status < 300 ? 0 : 1;
+}
 function coreApiFromEnv(flags, env = process.env) {
     const token = env.SIGHTLINE_DEPLOY_TOKEN;
     if (!token)
@@ -266,6 +312,8 @@ export async function main(argv, out = console.log) {
                 await uninstall(api, id, { purge }, out);
                 return 0;
             }
+            case "webhooks":
+                return await webhooks(rest, flags, out);
             case "version":
                 out(packageVersion());
                 return 0;

package/dist/index.d.ts

@@ -6,3 +6,4 @@ 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";
+export { planWebhookSend, secretVar, type WebhookSendInput, type WebhookSendPlan } from "./webhooks.ts";

package/dist/index.js

@@ -10,3 +10,4 @@ export { CONFIG_FILE, defaultContract, hostedRuleProblems, loadProject, MANIFEST
 // 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";
+export { planWebhookSend, secretVar } from "./webhooks.js";

package/dist/template.d.ts

@@ -2,7 +2,7 @@ export interface TemplateOptions {
     id: string;
     name?: string;
     publisher?: string;
-    /** The published packages' version (the CLI's own); dependencies use ^<version>. */
+    /** The CLI's own version. The packages share MAJOR.MINOR (patches are per package), so dependencies use ^MAJOR.MINOR.0. */
     packagesVersion: string;
 }
 /** kebab-case id → the snake_case prefix of its tool names. */

package/dist/template.js

@@ -22,7 +22,8 @@ export function templateFiles(options) {
     const name = options.name ?? id.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
     const publisher = options.publisher ?? id;
     const p = toolPrefix(id);
-    const range = `^${packagesVersion}`;
+    const [major, minor] = packagesVersion.split(".");
+    const range = `^${major}.${minor}.0`;
     const manifest = {
         manifestVersion: 2,
         id,

package/dist/webhooks.d.ts

@@ -0,0 +1,31 @@
+import { type Flags } from "./args.ts";
+export interface WebhookSendPlan {
+    /** The local emulator's ext-hooks route, or the workspace's webhook URL (`--url`, from Setup). */
+    url: string;
+    /** The environment variable the secret came from (never the value). */
+    secretFrom: string;
+    secret: string;
+    body: Uint8Array;
+    contentType: string;
+    timestamp?: number;
+}
+export interface WebhookSendInput {
+    hook: string;
+    /** The manifest secret that signs this webhook (`verify.secret`). */
+    secretName: string;
+    flags: Flags;
+    env: Record<string, string | undefined>;
+    /** sightline-ext.json `devSecrets`: the values `dev` and `test` inject. */
+    devSecrets?: Record<string, string>;
+    readFile(path: string): Uint8Array;
+    /** The running `sightline-ext dev`'s emulator (.sightline-devkit/state.json), if any. */
+    localCoreUrl?: string;
+}
+/** `inbound_hook` → `SL_SECRET_INBOUND_HOOK`. */
+export declare function secretVar(secretName: string): string;
+/**
+ * Resolve a send. The secret is read from the environment (`--secret-env`, default
+ * `SL_SECRET_<NAME>`) or sightline-ext.json `devSecrets`, never from a flag value,
+ * so it stays out of shell history.
+ */
+export declare function planWebhookSend(input: WebhookSendInput): WebhookSendPlan;

package/dist/webhooks.js

@@ -0,0 +1,72 @@
+// `sightline-ext webhooks send <name> --body <file>`: where a signed test delivery
+// goes and what signs it. The signing itself is the devkit's `signWebhook`, which
+// signs `<timestamp>.<raw body>` (or the raw body) exactly like core's
+// `signHookDelivery` (docs/platform/hosted-extensions-hooks-secrets.md).
+import { str } from "./args.js";
+const ENV_NAME_RE = /^[A-Z][A-Z0-9_]*$/;
+/** `inbound_hook` → `SL_SECRET_INBOUND_HOOK`. */
+export function secretVar(secretName) {
+    return `SL_SECRET_${secretName.toUpperCase().replace(/-/g, "_")}`;
+}
+/**
+ * Resolve a send. The secret is read from the environment (`--secret-env`, default
+ * `SL_SECRET_<NAME>`) or sightline-ext.json `devSecrets`, never from a flag value,
+ * so it stays out of shell history.
+ */
+export function planWebhookSend(input) {
+    const bodyFile = str(input.flags, "body");
+    if (!bodyFile)
+        throw new Error("usage: sightline-ext webhooks send <name> --body <file> [--url <webhook URL>]");
+    const explicitVar = str(input.flags, "secret-env");
+    if (explicitVar !== undefined && !ENV_NAME_RE.test(explicitVar))
+        throw new Error("--secret-env names an environment variable, e.g. SL_SECRET_INBOUND_HOOK");
+    const variable = explicitVar ?? secretVar(input.secretName);
+    let secret = input.env[variable];
+    let secretFrom = `$${variable}`;
+    // Locally, the same precedence `dev` uses for the emulator and the runtime (devSecrets over the
+    // environment), so the delivery is signed with the value it is verified with. A workspace target
+    // (--url) never uses devSecrets: those are local values.
+    const devValue = input.devSecrets?.[input.secretName];
+    if (str(input.flags, "url") === undefined && explicitVar === undefined && typeof devValue === "string" && devValue !== "") {
+        secret = devValue;
+        secretFrom = `sightline-ext.json devSecrets.${input.secretName}`;
+    }
+    if (!secret) {
+        throw new Error(`no value for the "${input.secretName}" secret: set ${variable} (the workspace's value for a real target; it is never read from a flag)`);
+    }
+    let url = str(input.flags, "url");
+    if (url !== undefined) {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new Error("--url must be the webhook URL, e.g. https://<workspace>/functions/v1/ext-hooks/i/<token>/<hook>");
+        }
+        const local = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1" || parsed.hostname === "[::1]";
+        if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && local))
+            throw new Error("--url must be https (http only for localhost)");
+        if (parsed.username || parsed.password)
+            throw new Error("--url must not carry credentials");
+    }
+    else {
+        if (!input.localCoreUrl)
+            throw new Error("no running `sightline-ext dev` here: start it, or pass --url <webhook URL> to send to a workspace");
+        url = `${input.localCoreUrl.replace(/\/+$/, "")}/functions/v1/ext-hooks/i/devkit/${input.hook}`;
+    }
+    const ts = str(input.flags, "timestamp");
+    let timestamp;
+    if (ts !== undefined) {
+        timestamp = Number(ts);
+        if (!Number.isInteger(timestamp) || timestamp < 0 || timestamp > 999_999_999_999)
+            throw new Error("--timestamp is Unix seconds");
+    }
+    return {
+        url,
+        secretFrom,
+        secret,
+        body: input.readFile(bodyFile),
+        contentType: str(input.flags, "content-type") ?? "application/json",
+        timestamp,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparelabs/sightline-extension-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "sightline-ext: scaffold, run, build, test and deploy a hosted Sightline extension.",
   "license": "MIT",
   "author": "Spare Labs Inc.",
@@ -34,8 +34,8 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {
-    "@sparelabs/sightline-extension-devkit": "0.1.0",
-    "@sparelabs/sightline-extension-manifest": "0.1.0",
+    "@sparelabs/sightline-extension-devkit": "0.1.1",
+    "@sparelabs/sightline-extension-manifest": "0.1.2",
     "@sparelabs/sightline-extension-testing": "0.1.0",
     "esbuild": "^0.25.10"
   },