@sparelabs/sightline-extension-cli 0.1.3 → 0.1.5

package/README.md

@@ -21,6 +21,8 @@ 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. |
+| `yank <version> [--reason "…"] [--id <ext>]` | Withdraws a published release: it can no longer be installed, upgraded or rolled back to. An installation running it keeps running, flagged (the CLI warns) until you upgrade it. Idempotent; there is no un-yank. A deploy token needs the `yank` action. |
+| `run <job> [--no-wait] [--timeout <s>] [--id <ext>]` | Starts a run of the job now, outside its schedule, then reads its status every 2 s until it finishes (a job that continues makes several calls under one run), printing each call (trigger, status, HTTP status, duration, error) and the result. Exit 1 unless it `succeeded`. `--no-wait` returns once it started; past `--timeout` (default 900 s) the CLI stops waiting, the run goes on. A deploy token needs the `run_job` action. |
 | `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>`.
@@ -33,16 +35,36 @@ Local only; never deployed.
 {
   "entry": "server/main.ts",
   "contract": {
-    "tool": { "name": "notes_list", "input": { "limit": 5 }, "as": "user:alice" },
+    "tool": { "name": "notes_list", "input": { "limit": 5 }, "as": "user:alice", "grants": ["my-notes.read"] },
+    "permissions": [
+      { "tool": "notes_add", "input": { "text": "hi" }, "grants": ["my-notes.write"] },
+      { "api": "GET /notes", "grants": ["my-notes.read"] }
+    ],
     "job": { "name": "weekly_digest" },
     "hook": { "name": "inbound", "body": { "event": "ping" } }
   },
   "settings": { "greeting": "hello" },
-  "devSecrets": { "inbound_hook": "dev-only-value" }
+  "devSecrets": { "inbound_hook": "dev-only-value" },
+  "users": [{ "name": "alice", "email": "alice@example.test", "grants": ["my-notes.read", "my-notes.write"] }, { "name": "eve" }],
+  "workspace": { "name": "Acme", "timezone": "Europe/London", "locale": "en-GB", "weekStart": 1 },
+  "people": [{ "displayName": "Ada Lovelace", "title": "Engineer", "department": "R&D" }],
+  "coreScopes": ["core:people:read"]
 }
 ```
 
-Without `contract.tool`, `test` calls the manifest's first tool as `user:alice` with `{}`.
+| Field | `dev` and `test` |
+| --- | --- |
+| `contract.tool` | The tool `test` calls (default: the manifest's first, as `user:alice` with `{}`); `grants`: what the caller holds for it. |
+| `contract.permissions` | Each permission-checked tool or `/api` route (`"<METHOD> /path"`) must succeed holding `grants` and be refused holding nothing (`permission_denied` / `scope_missing`, or 403). Called as `as`, default `user:contract-tester`. |
+| `contract.job`, `contract.hook` | A job and a hook `test` routes as the installation. |
+| `settings` | What `GET /v1/installation/settings` answers. |
+| `devSecrets` | Injected as `SL_SECRET_<NAME>` (over the same variables from your environment); the emulator verifies signed webhooks with them. |
+| `users` | The emulated people: their grants are their tokens' scopes, `access` their bits on your resources. Default: alice and bob, holding nothing. |
+| `workspace` | What `/v1/me` reports (default "Dev workspace", UTC, en-US, Sunday). |
+| `people` | The people directory (`/v1/people`, `/v1/people/:id`): `displayName`, optional `id` (a uuid; default derived from the name, so `alice` is `user:alice`), `avatarUrl`, `title`, `department`, `active`. Default: one person per user. |
+| `coreScopes` | The core scopes the installation holds (default: the manifest's `scopes.required`, which installing grants). The directory needs `core:people:read`. |
+
+The emulator also gets the manifest, so its webhooks are verified like Sightline's.
 
 ## Deploying
 

package/dist/args.js

@@ -1,7 +1,7 @@
 // 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"]);
+const BOOLEAN_FLAGS = new Set(["purge", "yes", "force", "no-db", "no-build", "no-wait", "keep-db", "help", "json", "ui", "watch"]);
 export function parseArgs(argv) {
     const positional = [];
     const flags = {};

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  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 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  yank <version> Withdraw a published release: it can no longer be installed, upgraded or rolled\n                 back to (an installation running it keeps running, flagged). No un-yank.\n                 [--reason \"\u2026\"]\n  run <job>      Start a run of a job now, outside its schedule, wait for it and print each call\n                 and the result; exit 1 unless it succeeded. [--no-wait] [--timeout <seconds, default 900>]\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, yank, run: [--url https://<workspace>] [--api-url <core API base>]\n  yank, run: on the project's extension (the manifest's id), or --id <extension id> with no project.\n  A deploy token needs the action: publish, install, upgrade, uninstall, yank or run_job.\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

@@ -8,8 +8,9 @@ import { assertContract, formatReport, runContractTests } from "@sparelabs/sight
 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 { deploy, parseBindings, runJob, uninstall, upgrade, yank } from "./deploy.js";
+import { contractConfig, emulatorConfig, secretEnv } from "./local-run.js";
+import { loadProject } from "./project.js";
 import { templateFiles } from "./template.js";
 import { planWebhookSend } from "./webhooks.js";
 export const USAGE = `sightline-ext <command> [options]
@@ -26,6 +27,11 @@ 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]
+  yank <version> Withdraw a published release: it can no longer be installed, upgraded or rolled
+                 back to (an installation running it keeps running, flagged). No un-yank.
+                 [--reason "…"]
+  run <job>      Start a run of a job now, outside its schedule, wait for it and print each call
+                 and the result; exit 1 unless it succeeded. [--no-wait] [--timeout <seconds, default 900>]
   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
@@ -34,7 +40,9 @@ export const USAGE = `sightline-ext <command> [options]
                  [--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>]
+  deploy, upgrade, uninstall, yank, run: [--url https://<workspace>] [--api-url <core API base>]
+  yank, run: on the project's extension (the manifest's id), or --id <extension id> with no project.
+  A deploy token needs the action: publish, install, upgrade, uninstall, yank or run_job.
 
 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)
@@ -62,18 +70,6 @@ async function buildProject(p, out) {
         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) => {
@@ -106,14 +102,9 @@ 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 ?? {},
-        // Its ext-hooks route verifies webhooks with these, as core does with the installation's secrets.
-        manifest: p.manifest,
-        secrets: secretEnv(p),
-    });
+    // sightline-ext.json's users, workspace, people and coreScopes; the manifest (its webhooks, its
+    // required core scopes); devSecrets, which its ext-hooks route verifies with as core does.
+    const emulator = await createCoreEmulator(emulatorConfig(p, secretEnv(p, process.env)));
     const core = await listen(emulator.handler, { port: int(flags, "core-port") ?? 8787 });
     emulator.setOrigin(core.url);
     const env = emulator.runtimeEnv();
@@ -181,11 +172,12 @@ async function test(flags, out) {
         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 ?? {} });
+    // Read and checked before anything starts: a config mistake costs no container.
+    const contract = contractConfig(p);
+    const emulator = await createCoreEmulator(emulatorConfig(p, secretEnv(p, process.env)));
     const core = await listen(emulator.handler);
     emulator.setOrigin(core.url);
-    const env = emulator.runtimeEnv(secretEnv(p));
+    const env = emulator.runtimeEnv();
     let db = null;
     let ext = null;
     try {
@@ -197,9 +189,7 @@ async function test(flags, out) {
         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,
+            ...contract,
             expect: { version: p.version },
         });
         out(formatReport(report));
@@ -256,6 +246,13 @@ function coreApiFromEnv(flags, env = process.env) {
     const apiUrl = str(flags, "api-url") ?? (str(flags, "url") ? undefined : env.SIGHTLINE_API_URL);
     return createCoreApi({ url, apiUrl, token, apiKey: env.SIGHTLINE_API_KEY });
 }
+/** `--id <extension>`, else the project's manifest id. */
+function extensionId(flags) {
+    const id = str(flags, "id") ?? project(flags).id;
+    if (!id)
+        throw new Error("name the extension: --id <extension id>, or run in its project (the manifest's id)");
+    return id;
+}
 function readBindings(flags) {
     const file = str(flags, "bindings");
     if (!file)
@@ -312,6 +309,27 @@ export async function main(argv, out = console.log) {
                 await uninstall(api, id, { purge }, out);
                 return 0;
             }
+            case "yank": {
+                const version = rest[0];
+                if (!version)
+                    throw new Error('usage: sightline-ext yank <version> [--reason "…"]');
+                const api = coreApiFromEnv(flags);
+                await yank(api, extensionId(flags), version, { reason: str(flags, "reason") }, out);
+                return 0;
+            }
+            case "run": {
+                const job = rest[0];
+                if (!job)
+                    throw new Error("usage: sightline-ext run <job> [--no-wait] [--timeout <seconds>]");
+                const timeout = str(flags, "timeout");
+                const seconds = timeout === undefined ? undefined : Number(timeout);
+                if (seconds !== undefined && (!Number.isInteger(seconds) || seconds < 1))
+                    throw new Error("--timeout is a whole number of seconds");
+                const api = coreApiFromEnv(flags);
+                const wait = !bool(flags, "no-wait");
+                const run = await runJob(api, extensionId(flags), job, { wait, timeoutMs: seconds === undefined ? undefined : seconds * 1000 }, out);
+                return !wait || run.status === "succeeded" ? 0 : 1;
+            }
             case "webhooks":
                 return await webhooks(rest, flags, out);
             case "version":

package/dist/core-api.d.ts

@@ -39,6 +39,36 @@ export interface InstallationView {
     lastError?: string | null;
     [key: string]: unknown;
 }
+/** One call of a job run (core's `runView`). */
+export interface JobCallView {
+    id: string;
+    seq: number;
+    attempt: number;
+    trigger: string;
+    status: string;
+    startedAt?: string | null;
+    finishedAt?: string | null;
+    durationMs?: number | null;
+    httpStatus?: number | null;
+    error?: string | null;
+    retryAt?: string | null;
+    [key: string]: unknown;
+}
+/** A job run: 202 from run-now (`status: "running"`), or the run lookup with its calls. */
+export interface JobRunView {
+    runId: string;
+    job: string;
+    version: string;
+    /** running, succeeded, failed, timed_out or abandoned. */
+    status: string;
+    trigger?: string;
+    startedAt?: string | null;
+    finishedAt?: string | null;
+    /** Between calls: when the next continuation or retry is due. */
+    resumeAt?: string | null;
+    calls?: JobCallView[];
+    [key: string]: unknown;
+}
 export interface PublishInput {
     manifest: Record<string, unknown>;
     bundle: Uint8Array;
@@ -86,6 +116,17 @@ export interface CoreApi {
         installation: InstallationView;
         warnings: string[];
     }>;
+    /** Withdraw a published release (a deploy token needs the `yank` action). */
+    yank(id: string, version: string, body: {
+        reason?: string;
+    }): Promise<{
+        release: ReleaseView;
+        installed: boolean;
+    }>;
+    /** Start a run of a job now (a deploy token needs `run_job`): 202 `{ run }`. */
+    runJob(id: string, job: string): Promise<JobRunView>;
+    /** A run's state and calls (`run_job`). */
+    jobRun(id: string, job: string, runId: string): Promise<JobRunView>;
 }
 /** A deploy token an admin issued (`slxd_…`), as opposed to an admin's own session token. */
 export declare function isDeployToken(token: string): boolean;

package/dist/core-api.js

@@ -6,6 +6,9 @@
 //   POST /core/v1/extensions/:id/install       { version, bindings? }
 //   POST /core/v1/extensions/:id/upgrade       { version, bindings? }
 //   POST /core/v1/extensions/:id/uninstall     { purge? }
+//   POST /core/v1/extensions/:id/releases/:version/yank   { reason? } → { release, installed }
+//   POST /core/v1/extensions/:id/jobs/:name/run           202 { run }
+//   GET  /core/v1/extensions/:id/jobs/:name/runs/:runId   { run } (status and calls)
 //
 // 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
@@ -69,6 +72,8 @@ export function describeError(err) {
             const errors = (d.errors ?? []);
             return `${err.message}${errors.map((e) => `\n  ${e.path ?? ""}: ${e.message ?? ""}`).join("")}`;
         }
+        case "job_running":
+            return `${err.message}${typeof d.runId === "string" ? `\n  the run in progress: ${d.runId}` : ""}`;
         case "bundle_rejected":
         case "ui_rejected": {
             const errors = (d.errors ?? []);
@@ -162,5 +167,15 @@ export function createCoreApi(options) {
             const r = await call("POST", `/extensions/${encodeURIComponent(id)}/uninstall`, body);
             return { installation: r.installation, warnings: r.warnings ?? [] };
         },
+        async yank(id, version, body) {
+            const r = await call("POST", `/extensions/${encodeURIComponent(id)}/releases/${encodeURIComponent(version)}/yank`, body);
+            return { release: r.release, installed: r.installed === true };
+        },
+        async runJob(id, job) {
+            return (await call("POST", `/extensions/${encodeURIComponent(id)}/jobs/${encodeURIComponent(job)}/run`, {})).run;
+        },
+        async jobRun(id, job, runId) {
+            return (await call("GET", `/extensions/${encodeURIComponent(id)}/jobs/${encodeURIComponent(job)}/runs/${encodeURIComponent(runId)}`)).run;
+        },
     };
 }

package/dist/deploy.d.ts

@@ -1,4 +1,4 @@
-import type { CoreApi, InstallationView, PublishInput } from "./core-api.ts";
+import { type CoreApi, type InstallationView, type JobRunView, type PublishInput, type ReleaseView } from "./core-api.ts";
 export type Out = (line: string) => void;
 export declare function deploy(api: CoreApi, release: PublishInput, options: {
     bindings?: Record<string, string>;
@@ -11,3 +11,33 @@ export declare function uninstall(api: CoreApi, id: string, options: {
 }, out: Out): Promise<InstallationView>;
 /** --bindings <file>: { "<ext>.<permission>": "<core permission>" }. */
 export declare function parseBindings(raw: unknown): Record<string, string>;
+/** Core's cap on a yank reason. */
+export declare const MAX_YANK_REASON = 500;
+/**
+ * yank <version>: withdraw a published release. It can no longer be installed,
+ * upgraded or rolled back to; an installation running it keeps running, flagged,
+ * until it is upgraded. Idempotent (the first yank stands); there is no un-yank.
+ */
+export declare function yank(api: CoreApi, id: string, version: string, options: {
+    reason?: string;
+}, out: Out): Promise<{
+    release: ReleaseView;
+    installed: boolean;
+}>;
+export interface RunJobOptions {
+    /** false: start the run and return at once. */
+    wait?: boolean;
+    /** Between status reads. Default 2 s. */
+    pollMs?: number;
+    /** Give up waiting (the run goes on in the workspace). Default 15 min. */
+    timeoutMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+/**
+ * run <job>: start a run of a job now, outside its schedule, then read its
+ * status until it finishes (a job that continues makes several calls under one
+ * run id) and print each call and the result. The run happens in the
+ * workspace: giving up waiting does not stop it.
+ */
+export declare function runJob(api: CoreApi, id: string, job: string, options: RunJobOptions, out: Out): Promise<JobRunView>;

package/dist/deploy.js

@@ -1,3 +1,9 @@
+// deploy / upgrade / uninstall: the release lifecycle against a workspace's
+// installer API. A deploy publishes the built release (idempotent for identical
+// bytes) and installs it; an upgrade publishes and moves an existing
+// installation to it; an uninstall removes it (data kept 30 days unless --purge).
+// A yank withdraws a published release; a run starts a job now and waits for it.
+import { CoreApiError } from "./core-api.js";
 /** 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) {
@@ -69,3 +75,76 @@ export function parseBindings(raw) {
     }
     return out;
 }
+const RELEASE_VERSION_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+/** Core's cap on a yank reason. */
+export const MAX_YANK_REASON = 500;
+/**
+ * yank <version>: withdraw a published release. It can no longer be installed,
+ * upgraded or rolled back to; an installation running it keeps running, flagged,
+ * until it is upgraded. Idempotent (the first yank stands); there is no un-yank.
+ */
+export async function yank(api, id, version, options, out) {
+    if (!RELEASE_VERSION_RE.test(version))
+        throw new Error(`usage: sightline-ext yank <version> [--reason "…"]; "${version}" is not MAJOR.MINOR.PATCH`);
+    const reason = options.reason?.trim();
+    if (reason !== undefined && reason.length > MAX_YANK_REASON)
+        throw new Error(`--reason is at most ${MAX_YANK_REASON} characters`);
+    const result = await api.yank(id, version, reason ? { reason } : {});
+    out(`yanked ${id}@${version}${reason ? ` (${reason})` : ""}: it can no longer be installed, upgraded or rolled back to`);
+    if (result.installed)
+        out(`  warning: the workspace runs ${id}@${version} now; it keeps running, flagged, until you \`sightline-ext upgrade\` to a release that is not yanked`);
+    return result;
+}
+/** Statuses a run ends in (core's run lookup). */
+const FINISHED = new Set(["succeeded", "failed", "timed_out", "abandoned"]);
+function describeCall(c) {
+    const parts = [`call ${c.seq}`, c.trigger, c.status];
+    if (typeof c.httpStatus === "number")
+        parts.push(`HTTP ${c.httpStatus}`);
+    if (typeof c.durationMs === "number")
+        parts.push(`${c.durationMs} ms`);
+    return `  ${parts.join(", ")}${c.error ? `: ${c.error}` : ""}${c.retryAt ? ` (retry at ${c.retryAt})` : ""}`;
+}
+/**
+ * run <job>: start a run of a job now, outside its schedule, then read its
+ * status until it finishes (a job that continues makes several calls under one
+ * run id) and print each call and the result. The run happens in the
+ * workspace: giving up waiting does not stop it.
+ */
+export async function runJob(api, id, job, options, out) {
+    if (!job)
+        throw new Error("usage: sightline-ext run <job>");
+    const started = await api.runJob(id, job);
+    out(`started ${id} job ${job} (run ${started.runId}, version ${started.version})`);
+    if (options.wait === false)
+        return started;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = options.now ?? Date.now;
+    const timeoutMs = options.timeoutMs ?? 15 * 60_000;
+    const deadline = now() + timeoutMs;
+    let printed = 0;
+    let run = started;
+    for (;;) {
+        await sleep(options.pollMs ?? 2_000);
+        try {
+            run = await api.jobRun(id, job, started.runId);
+        }
+        catch (e) {
+            // A run is claimed before its first call is readable everywhere: not found yet is not an answer.
+            if (!(e instanceof CoreApiError && e.code === "run_not_found"))
+                throw e;
+        }
+        const done = (run.calls ?? []).filter((c) => c.status !== "running");
+        for (const c of done.slice(printed))
+            out(describeCall(c));
+        printed = Math.max(printed, done.length);
+        if (FINISHED.has(run.status))
+            break;
+        if (now() >= deadline) {
+            out(`still ${run.status} after ${Math.round(timeoutMs / 1000)} s; the run goes on in the workspace (run ${started.runId})`);
+            return run;
+        }
+    }
+    out(`${job} ${run.status}${run.finishedAt ? ` at ${run.finishedAt}` : ""} (${(run.calls ?? []).length} call(s))`);
+    return run;
+}

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 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 { apiBase, type CoreApi, CoreApiError, type CoreApiOptions, createCoreApi, describeError, type InstallationView, isDeployToken, type JobCallView, type JobRunView, lifecycleBase, type PublishInput, type ReleaseView, sha256Hex } from "./core-api.ts";
+export { deploy, MAX_YANK_REASON, parseBindings, runJob, type RunJobOptions, uninstall, upgrade, yank } from "./deploy.ts";
+export { contractConfig, type ContractRunConfig, type EmulatorConfig, emulatorConfig, secretEnv } from "./local-run.ts";
+export { CONFIG_FILE, type ContractConfig, defaultContract, hostedRuleProblems, loadProject, MANIFEST_FILE, migrationProblems, type MigrationFile, type PermissionCheckConfig, type PersonConfig, type Project, type ProjectConfig, readMigrations, readUiFiles, type UiFileOnDisk, uiFrames, type UserConfig, type WorkspaceConfig, } 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

@@ -5,7 +5,8 @@ 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 { deploy, MAX_YANK_REASON, parseBindings, runJob, uninstall, upgrade, yank } from "./deploy.js";
+export { contractConfig, emulatorConfig, secretEnv } from "./local-run.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";

package/dist/local-run.d.ts

@@ -0,0 +1,30 @@
+import { type ContractConfig, type PermissionCheckConfig, type PersonConfig, type Project, type UserConfig, type WorkspaceConfig } from "./project.ts";
+/** The devkit's `EmulatorOptions`, as far as the CLI fills them. */
+export interface EmulatorConfig {
+    extension: string;
+    version: string;
+    settings: Record<string, unknown>;
+    manifest: Record<string, unknown>;
+    /** SL_SECRET_<NAME> → value: the runtime gets them, the ext-hooks route verifies with them. */
+    secrets: Record<string, string>;
+    users?: UserConfig[];
+    workspace?: WorkspaceConfig;
+    people?: PersonConfig[];
+    coreScopes?: string[];
+}
+/** The testing package's `ContractOptions`, minus the URLs. */
+export interface ContractRunConfig {
+    tool: NonNullable<ContractConfig["tool"]>;
+    permissions?: PermissionCheckConfig[];
+    job?: ContractConfig["job"];
+    hook?: ContractConfig["hook"];
+}
+/**
+ * The extension's secrets as the runtime gets them: every SL_SECRET_* in the
+ * environment, then `devSecrets` on top (their names upper-cased, `-` → `_`).
+ */
+export declare function secretEnv(p: Project, env: Record<string, string | undefined>): Record<string, string>;
+/** The emulator `dev` and `test` start, from the project and its sightline-ext.json. */
+export declare function emulatorConfig(p: Project, secrets: Record<string, string>): EmulatorConfig;
+/** What `test` asks the contract kit to check: the tool (the manifest's first by default), permissions, job, hook. */
+export declare function contractConfig(p: Project): ContractRunConfig;

package/dist/local-run.js

@@ -0,0 +1,115 @@
+// What `dev` and `test` hand the devkit's emulator and the contract kit, from
+// the project and its sightline-ext.json: the manifest (its webhooks, its
+// required core scopes), devSecrets, users, workspace, people, coreScopes, and
+// the contract's tool, permissions, job and hook. Pure, so each field is tested
+// without starting anything (test/cli.test.ts).
+import { CONFIG_FILE, defaultContract } from "./project.js";
+const SECRET_NAME_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
+const where = (field) => `${CONFIG_FILE}: ${field}`;
+const isObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const isStrings = (v) => Array.isArray(v) && v.every((s) => typeof s === "string");
+/**
+ * The extension's secrets as the runtime gets them: every SL_SECRET_* in the
+ * environment, then `devSecrets` on top (their names upper-cased, `-` → `_`).
+ */
+export function secretEnv(p, env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env))
+        if (k.startsWith("SL_SECRET_") && v !== undefined)
+            out[k] = v;
+    const dev = p.config.devSecrets ?? {};
+    if (!isObject(dev))
+        throw new Error(where("devSecrets must be an object of secret name → value"));
+    for (const [name, value] of Object.entries(dev)) {
+        if (!SECRET_NAME_RE.test(name) || typeof value !== "string")
+            throw new Error(`devSecrets: "${name}" must be a secret name with a string value`);
+        out[`SL_SECRET_${name.toUpperCase().replace(/-/g, "_")}`] = value;
+    }
+    return out;
+}
+function checkUsers(users) {
+    if (!Array.isArray(users))
+        throw new Error(where('users must be [{ "name": "alice", "email"?: "…", "grants"?: ["…"] }]'));
+    return users.map((u, i) => {
+        if (!isObject(u) || typeof u.name !== "string" || u.name === "")
+            throw new Error(where(`users[${i}] needs a "name"`));
+        if (u.email !== undefined && typeof u.email !== "string")
+            throw new Error(where(`users[${i}].email must be a string`));
+        if (u.grants !== undefined && !isStrings(u.grants))
+            throw new Error(where(`users[${i}].grants must be a list of permission keys`));
+        if (u.access !== undefined && !isObject(u.access))
+            throw new Error(where(`users[${i}].access must be { "<ext>.<resource>": [read, write] }`));
+        return u;
+    });
+}
+function checkWorkspace(workspace) {
+    if (!isObject(workspace))
+        throw new Error(where('workspace must be { "name"?, "timezone"?, "locale"?, "weekStart"? }'));
+    for (const k of ["name", "timezone", "locale"]) {
+        if (workspace[k] !== undefined && typeof workspace[k] !== "string")
+            throw new Error(where(`workspace.${k} must be a string`));
+    }
+    const ws = workspace.weekStart;
+    if (ws !== undefined && (typeof ws !== "number" || !Number.isInteger(ws) || ws < 1 || ws > 7))
+        throw new Error(where("workspace.weekStart is 1 (Monday) to 7 (Sunday)"));
+    return workspace;
+}
+function checkPeople(people) {
+    if (!Array.isArray(people))
+        throw new Error(where('people must be [{ "displayName": "…", "id"?, "title"?, "department"?, "avatarUrl"?, "active"? }]'));
+    people.forEach((p, i) => {
+        if (!isObject(p) || typeof p.displayName !== "string")
+            throw new Error(where(`people[${i}] needs a "displayName"`));
+    });
+    return people;
+}
+function checkPermissions(permissions) {
+    if (!Array.isArray(permissions))
+        throw new Error(where('contract.permissions must be [{ "tool": "<name>" | "api": "<METHOD> /path", "grants": ["…"] }]'));
+    return permissions.map((c, i) => {
+        const at = `contract.permissions[${i}]`;
+        if (!isObject(c))
+            throw new Error(where(`${at} must be an object`));
+        if ((typeof c.tool === "string") === (typeof c.api === "string"))
+            throw new Error(where(`${at} names exactly one of "tool" and "api"`));
+        if (typeof c.api === "string" && !/^[A-Z]+ \/\S*$/.test(c.api))
+            throw new Error(where(`${at}.api is "<METHOD> /path", e.g. "POST /kudos"`));
+        if (!isStrings(c.grants))
+            throw new Error(where(`${at}.grants must be a list of permission keys`));
+        if (c.as !== undefined && typeof c.as !== "string")
+            throw new Error(where(`${at}.as must be "user:<name>"`));
+        return c;
+    });
+}
+/** The emulator `dev` and `test` start, from the project and its sightline-ext.json. */
+export function emulatorConfig(p, secrets) {
+    const c = p.config;
+    const out = { extension: p.id, version: p.version, settings: c.settings ?? {}, manifest: p.manifest, secrets };
+    if (c.users !== undefined)
+        out.users = checkUsers(c.users);
+    if (c.workspace !== undefined)
+        out.workspace = checkWorkspace(c.workspace);
+    if (c.people !== undefined)
+        out.people = checkPeople(c.people);
+    if (c.coreScopes !== undefined) {
+        if (!isStrings(c.coreScopes))
+            throw new Error(where('coreScopes must be a list of core scopes, e.g. ["core:people:read"]'));
+        out.coreScopes = c.coreScopes;
+    }
+    return out;
+}
+/** What `test` asks the contract kit to check: the tool (the manifest's first by default), permissions, job, hook. */
+export function contractConfig(p) {
+    const contract = defaultContract(p);
+    const tool = contract.tool;
+    if (tool.grants !== undefined && !isStrings(tool.grants))
+        throw new Error(where("contract.tool.grants must be a list of permission keys"));
+    const out = { tool };
+    if (contract.permissions !== undefined)
+        out.permissions = checkPermissions(contract.permissions);
+    if (contract.job)
+        out.job = contract.job;
+    if (contract.hook)
+        out.hook = contract.hook;
+    return out;
+}

package/dist/project.d.ts

@@ -19,11 +19,23 @@ 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;
+/** A permission-checked tool or /api route `test` calls with and without its grants (the testing package's `PermissionCheck`). */
+export interface PermissionCheckConfig {
+    /** A tool name. Name exactly one of `tool` and `api`. */
+    tool?: string;
+    /** An /api route as `"<METHOD> /path"`, e.g. `"POST /kudos"`. */
+    api?: string;
+    input?: unknown;
+    as?: string;
+    grants: string[];
+}
 export interface ContractConfig {
+    /** `grants`: what `as` holds for these calls; absent, what `users` gives them. */
     tool?: {
         name: string;
         input?: Record<string, unknown>;
         as?: string;
+        grants?: string[];
     };
     job?: {
         name: string;
@@ -33,17 +45,53 @@ export interface ContractConfig {
         name: string;
         body?: unknown;
     };
+    /** Each must succeed with its grants and be refused (permission_denied / scope_missing / 403) with none. */
+    permissions?: PermissionCheckConfig[];
+}
+/** An emulated person who can call the extension (`--as user:<name>`): the devkit's `DevUser`. */
+export interface UserConfig {
+    name: string;
+    email?: string;
+    /** The permission keys they hold: their tokens' scopes. */
+    grants?: string[];
+    /** Their bits on the extension's own resources (`{ "<ext>.<resource>": [read, write] }`): the token's `access`. */
+    access?: Record<string, [number, number]>;
+}
+/** A person in the emulated people directory (/v1/people): the devkit's `DevPerson`. */
+export interface PersonConfig {
+    id?: string;
+    displayName: string;
+    avatarUrl?: string | null;
+    title?: string | null;
+    department?: string | null;
+    active?: boolean;
+}
+/** The workspace /v1/me reports (default: "Dev workspace", UTC, en-US, Sunday). */
+export interface WorkspaceConfig {
+    name?: string;
+    timezone?: string;
+    locale?: string;
+    /** ISO: 1 = Monday … 7 = Sunday. */
+    weekStart?: 1 | 2 | 3 | 4 | 5 | 6 | 7;
 }
 /** 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. */
+    /** What `test` checks: a tool that succeeds, permission checks, 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. */
+    /** Development-only secret values, injected as SL_SECRET_<NAME> (and verified with by the emulator's ext-hooks). Never deployed. */
     devSecrets?: Record<string, string>;
+    /** The emulated people and their grants (default: alice and bob, holding nothing). */
+    users?: UserConfig[];
+    /** The workspace the emulated core reports. */
+    workspace?: WorkspaceConfig;
+    /** The emulated people directory (default: one person per user). */
+    people?: PersonConfig[];
+    /** The core scopes the installation holds (default: the manifest's `scopes.required`, as installing grants them). */
+    coreScopes?: 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;

package/package.json

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