@sparelabs/sightline-extension-cli 0.1.5 → 0.1.6

package/README.md

@@ -18,8 +18,8 @@ You need Node 20.19+, [Deno](https://deno.com) (the extension runtime) and Docke
 | `build` | Validates `sightline.extension.json` against the published contract (`@sparelabs/sightline-extension-manifest`) and the rules Sightline applies at publish (trust `T2`, a hosted runtime, a kebab-case id, `MAJOR.MINOR.PATCH`), checks `migrations/NNNN_<name>.sql` (numbered from `0001`, no gaps, at most 256 KB each), bundles `server/main.ts` into one ESM file (`runtime.entry`, usually `dist/server.mjs`, at most 5 MB) and lints the bundle with the same `lintBundle` Sightline runs at publish (from `@sparelabs/sightline-extension-manifest`: no remote, package or relative imports, no computed dynamic import). With `ui.frames` in the manifest it also reads your UI build from `dist/ui` (set `"ui": { "dir": … }` in `sightline-ext.json` to move it; build the UI with your own tool first) and checks it with Sightline's publish rules: allowed file types, sizes, no scripts from other origins, no root-absolute URLs (use a relative base, e.g. Vite `base: './'`), the entry HTML present. |
 | `dev [--port <n>] [--core-port 8787] [--no-db]` | Builds, starts the emulated core (`@sparelabs/sightline-extension-devkit`), your Postgres with your migrations, and the bundle under the **same Deno permission flags as production**; rebuilds and restarts on every change. `npx sightline-devkit invoke tool <name> --as user:alice` calls it. |
 | `test [--no-build] [--no-db] [--keep-db]` | Builds, runs the extension against the emulator and its own database, and checks it against the HTTP contract (`@sparelabs/sightline-extension-testing`): health, token refusal, the `ToolResult` envelope, routing. Exit 1 on any failure. |
-| `deploy [--bindings bindings.json] [--no-build]` | Builds, publishes the release to a workspace (identical bytes are a no-op) and installs it. Refuses when another version is installed: use `upgrade`. |
-| `upgrade [--bindings bindings.json] [--no-build]` | Builds, publishes, and moves the installed extension to the manifest's version. A permission the new version adds needs a binding. |
+| `deploy [--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 [--no-build]` | Builds, publishes, and moves the installed extension to the manifest's version. A default access line the new version adds needs an Administrator's approval first. |
 | `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. |
@@ -71,7 +71,7 @@ The emulator also gets the manifest, so its webhooks are verified like Sightline
 ```bash
 export SIGHTLINE_URL=https://<your workspace>
 export SIGHTLINE_DEPLOY_TOKEN=…        # issued by a workspace admin; only ever read from the environment
-npx sightline-ext deploy --bindings bindings.json
+npx sightline-ext deploy
 ```
 
 | Variable | Meaning |
@@ -81,7 +81,7 @@ npx sightline-ext deploy --bindings bindings.json
 | `SIGHTLINE_DEPLOY_TOKEN` | A deploy token (`slxd_…`) a workspace admin issued for your extension ids and actions, or an admin's own session token. A deploy token goes to the workspace's deploy routes (`/functions/v1/core/v1/deploy/…`), the only place it works. It is sent to that workspace only, never accepted as a flag, never in the URL. |
 | `SIGHTLINE_API_KEY` | The gateway's public API key, when the workspace needs one (sent as `apikey`). |
 
-`bindings.json` maps each permission your manifest declares to a Sightline permission the deploying admin holds: `{ "my-notes.read": "employees", "my-notes.write": "employees" }`. A permission left out gets the manifest's proposed `default` when the admin holds it.
+Access control is the manifest's `rbac`: its resources, the permissions your tools name, and default access lines (`grants`). A deploy token never approves access: when the release has default access lines nobody decided yet, `deploy` and `upgrade` stop with `consent_required` and list them; an Administrator approves or declines them in Setup → Extensions (or installs from there), then run it again. `--bindings` (permission bindings) was removed in 0.1.6 and is refused.
 
 The deploy publishes the server bundle and migrations. Publishing a UI (`ui.frames`) to the workspace's extension-UI host is not part of the release API yet.
 

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  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 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: [--no-build]; new default access waits for an admin's approval)\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,7 +8,7 @@ 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, runJob, uninstall, upgrade, yank } from "./deploy.js";
+import { deploy, 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";
@@ -24,7 +24,7 @@ export const USAGE = `sightline-ext <command> [options]
                  [--no-build] [--no-db] [--keep-db]
   deploy         Build, publish the release and install it in a workspace
   upgrade        Build, publish the release and move the installed extension to it
-                 (deploy, upgrade: [--bindings bindings.json] [--no-build])
+                 (deploy, upgrade: [--no-build]; new default access waits for an admin's approval)
   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
@@ -253,11 +253,11 @@ function extensionId(flags) {
         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)
-        return undefined;
-    return parseBindings(JSON.parse(readFileSync(file, "utf8")));
+/** `--bindings` was removed with permission bindings: say so instead of silently ignoring it. */
+function refuseBindingsFlag(flags) {
+    if (flags.bindings !== undefined) {
+        throw new Error("--bindings was removed: declare `rbac` in the manifest; an Administrator approves its default access in Setup → Extensions");
+    }
 }
 async function release(flags, out) {
     const p = project(flags);
@@ -291,13 +291,15 @@ export async function main(argv, out = console.log) {
             case "test":
                 return await test(flags, out);
             case "deploy": {
+                refuseBindingsFlag(flags);
                 const api = coreApiFromEnv(flags);
-                await deploy(api, await release(flags, out), { bindings: readBindings(flags) }, out);
+                await deploy(api, await release(flags, out), out);
                 return 0;
             }
             case "upgrade": {
+                refuseBindingsFlag(flags);
                 const api = coreApiFromEnv(flags);
-                await upgrade(api, await release(flags, out), { bindings: readBindings(flags) }, out);
+                await upgrade(api, await release(flags, out), out);
                 return 0;
             }
             case "uninstall": {

package/dist/core-api.d.ts

@@ -35,7 +35,6 @@ export interface InstallationView {
     installationId: string;
     state: string;
     version: string;
-    bindings?: Record<string, string>;
     lastError?: string | null;
     [key: string]: unknown;
 }
@@ -104,11 +103,9 @@ export interface CoreApi {
     }>;
     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;

package/dist/core-api.js

@@ -3,8 +3,8 @@
 //
 //   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/install       { version }
+//   POST /core/v1/extensions/:id/upgrade       { version }
 //   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 }
@@ -62,11 +62,9 @@ export function describeError(err) {
     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 "consent_required": {
+            const pending = (d.ledger?.pending ?? []).map((l) => l.id).filter(Boolean);
+            return `${err.message}${pending.length ? `\n  pending: ${pending.join(", ")}` : ""}\n  an Administrator approves it in Setup → Extensions, then run this again`;
         }
         case "invalid_manifest": {
             const errors = (d.errors ?? []);

package/dist/deploy.d.ts

@@ -1,16 +1,10 @@
 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>;
-}, out: Out): Promise<InstallationView>;
-export declare function upgrade(api: CoreApi, release: PublishInput, options: {
-    bindings?: Record<string, string>;
-}, out: Out): Promise<InstallationView>;
+export declare function deploy(api: CoreApi, release: PublishInput, out: Out): Promise<InstallationView>;
+export declare function upgrade(api: CoreApi, release: PublishInput, 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>;
 /** Core's cap on a yank reason. */
 export declare const MAX_YANK_REASON = 500;
 /**

package/dist/deploy.js

@@ -23,7 +23,7 @@ async function publish(api, release, out) {
     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) {
+export async function deploy(api, release, out) {
     const id = release.manifest.id;
     const version = release.manifest.version;
     const existing = await current(api, id);
@@ -35,11 +35,11 @@ export async function deploy(api, release, options, out) {
         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 } : {}) });
+    const installation = await api.install(id, { version });
     out(`installed ${id}@${installation.version}: ${installation.state} (installation ${installation.installationId})`);
     return installation;
 }
-export async function upgrade(api, release, options, out) {
+export async function upgrade(api, release, out) {
     const id = release.manifest.id;
     const version = release.manifest.version;
     const existing = await current(api, id);
@@ -50,7 +50,7 @@ export async function upgrade(api, release, options, out) {
         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 } : {}) });
+    const installation = await api.upgrade(id, { version });
     out(`upgraded ${id} ${existing.version} → ${installation.version}: ${installation.state}`);
     return installation;
 }
@@ -63,18 +63,6 @@ export async function uninstall(api, id, options, out) {
         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;
-}
 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;

package/dist/index.d.ts

@@ -2,7 +2,7 @@ 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, 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 { deploy, MAX_YANK_REASON, 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";

package/dist/index.js

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

package/dist/template.js

@@ -34,10 +34,16 @@ export function templateFiles(options) {
         trust: "T2",
         coreApi: "^0.1",
         runtime: { kind: "hosted", entry: "dist/server.mjs", memoryMb: 256 },
-        permissions: [
-            { key: `${id}.read`, label: "Read notes", default: "employees" },
-            { key: `${id}.write`, label: "Write notes", default: "employees" },
-        ],
+        // Access control: one resource, the permissions the tools name, and the
+        // default access a workspace admin approves on install (Setup → Extensions).
+        rbac: {
+            resources: [{ key: `${id}.notes`, label: "Notes", description: "Notes your team keeps.", read: ["self", "reports", "others"], write: ["self"] }],
+            permissions: [
+                { key: `${id}.read`, label: "Read notes", requires: [`${id}.notes`] },
+                { key: `${id}.write`, label: "Write notes", requires: [`${id}.notes`], requireWrite: true },
+            ],
+            grants: [{ role: "employee", resource: `${id}.notes`, read: ["others"], write: ["self"] }],
+        },
         tools: [
             {
                 name: `${p}_list`,
@@ -203,7 +209,7 @@ SIGHTLINE_URL=https://<your workspace> SIGHTLINE_DEPLOY_TOKEN=… npx sightline-
 
 | Path | What |
 | --- | --- |
-| \`sightline.extension.json\` | The manifest: id, version, permissions, tools |
+| \`sightline.extension.json\` | The manifest: id, version, access control (\`rbac\`), tools |
 | \`server/main.ts\` | The backend (\`@sparelabs/sightline-extension-sdk\`) |
 | \`migrations/NNNN_<name>.sql\` | Your database, in order; only ever add files |
 | \`sightline-ext.json\` | Local only: what \`test\` calls, dev settings and secrets |

package/package.json

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