@sonisoft/now-sdk-ext-core 5.3.0 → 6.1.0

package/dist/policy/Policy.js

@@ -0,0 +1,161 @@
+/**
+ * Process-wide permission policy.
+ *
+ * INERT UNTIL CONFIGURED. With no policy installed every check allows, so importing
+ * this library changes nothing for existing consumers — `new TableAPIRequest(i).post()`
+ * behaves exactly as it did. The applications that are actually driven by agents (the
+ * `nex` CLI and the MCP server) install a policy in their entrypoints.
+ *
+ * That split is deliberate. The risk being managed is "an agent drives the CLI or the
+ * MCP server", not "a program imports this library"; gating here by default would break
+ * every embedder to mitigate a risk they do not have.
+ *
+ * Those applications currently install a ladder whose LAST layer grants both verbs, so
+ * changes are permitted unless something above revokes them — `NEX_POLICY_DENY`, or a
+ * CLI deny flag. Flipping to deny-by-default is deleting that trailing layer; nothing
+ * in this file assumes either direction.
+ */
+/**
+ * Layers in priority order. The FIRST layer to answer anything other than `abstain`
+ * decides.
+ *
+ * Ordered layers rather than an escalating if-chain because not every source is a
+ * grant: `--read-only` (NEX-76) REVOKES, and an escalate-only model cannot express a
+ * source that lowers permission. Getting this shape right now is what lets NEX-76 add
+ * `ApprovalToken` and `--approve-all` later without a rewrite.
+ *
+ * Index 0 is the only layer an agent cannot reach — see `denyFromEnvironment`.
+ */
+const DEFAULT_LAYER = "default";
+let layers = [];
+let installed = false;
+/** True once an application has installed a policy. Until then, everything is allowed. */
+export function isPolicyInstalled() {
+    return installed;
+}
+/**
+ * Installs the process policy. Call once, from the application that owns the entry
+ * point — never from a library.
+ *
+ * Layers are supplied in priority order (highest first).
+ */
+export function installPolicy(orderedLayers) {
+    layers = [...orderedLayers];
+    installed = true;
+}
+/** Removes the policy, returning to the permissive default. Test seam. */
+export function resetPolicyForTests() {
+    layers = [];
+    installed = false;
+}
+/** The layers currently installed, highest priority first. Diagnostics and `nex policy status`. */
+export function currentLayers() {
+    return layers;
+}
+/**
+ * Resolves a single verb against the ladder.
+ *
+ * Returns the deciding layer's name alongside the answer so refusals can say which one
+ * spoke. Without that, a precedence bug is invisible: the user sees "refused" and has
+ * no way to tell whether the environment denied it or nothing granted it.
+ */
+function resolveVerb(verb) {
+    for (const layer of layers) {
+        const answer = layer.answer(verb);
+        if (answer === "grant") {
+            return { granted: true, decidingLayer: layer.name };
+        }
+        if (answer === "deny") {
+            return { granted: false, decidingLayer: layer.name };
+        }
+    }
+    return { granted: false, decidingLayer: DEFAULT_LAYER };
+}
+/**
+ * Decides whether an operation may proceed.
+ *
+ * Only `target: "instance"` is gated. A local file write or a session-preference change
+ * is not what this exists to prevent, and refusing them would produce false refusals on
+ * operations that never touch instance data (`script-sync pull` being the clearest).
+ */
+export function checkRequirement(requirement) {
+    if (!installed || requirement.verbs.length === 0 || requirement.target !== "instance") {
+        return {
+            allowed: true,
+            verbs: requirement.verbs,
+            decidingLayer: installed ? "not-gated" : "no-policy",
+        };
+    }
+    // Every required verb must be granted. A script needing execute AND write is not
+    // satisfied by execute alone.
+    for (const verb of requirement.verbs) {
+        const { granted, decidingLayer } = resolveVerb(verb);
+        if (!granted) {
+            return {
+                allowed: false,
+                verbs: requirement.verbs,
+                decidingLayer,
+                remediation: remediationFor(requirement.verbs, verb, decidingLayer),
+            };
+        }
+    }
+    // Report EVERY layer that granted, not just the first verb's.
+    //
+    // A requirement like ["execute", "write"] can be satisfied by two different layers
+    // — execute from the environment, write from the default — and naming only the
+    // first makes the audit log quietly wrong about how a mutation was permitted. That
+    // log is the thing meant to surface a missing floor rule, so it has to be accurate.
+    const granting = [...new Set(requirement.verbs.map((v) => resolveVerb(v).decidingLayer))];
+    return {
+        allowed: true,
+        verbs: requirement.verbs,
+        decidingLayer: granting.join(" + "),
+    };
+}
+/**
+ * How the application explains a refusal.
+ *
+ * Set by the CLI to name its flags. Left unset by the MCP server, whose caller is the
+ * model — naming the parameter there would advertise the escape hatch.
+ */
+let remediationWriter;
+export function setRemediationWriter(writer) {
+    remediationWriter = writer;
+}
+function remediationFor(verbs, missing, layer) {
+    if (remediationWriter) {
+        return remediationWriter(verbs, missing, layer);
+    }
+    return `This operation requires ${missing} permission on the instance, which has not been granted.`;
+}
+/**
+ * A layer that denies the listed verbs outright.
+ *
+ * Placed at the top of the ladder so nothing below can grant past it. This is the layer
+ * that makes pointing the tool at production meaningful.
+ *
+ * The guarantee has a precise limit, and the docs must state it: this only holds when
+ * the variable is set somewhere the agent cannot write — a shell profile, a systemd
+ * unit, a container environment. A project-local `.mcp.json` is a file in the workspace,
+ * and an agent with file-write access can edit it.
+ */
+export function denyLayer(name, denied) {
+    const set = new Set(denied);
+    return {
+        name,
+        answer: (verb) => (set.has(verb) ? "deny" : "abstain"),
+    };
+}
+/** A layer that grants the listed verbs and abstains on the rest. */
+export function grantLayer(name, granted) {
+    const set = new Set(granted);
+    return {
+        name,
+        answer: (verb) => (set.has(verb) ? "grant" : "abstain"),
+    };
+}
+/** Convenience for tests and for embedders that want the old unrestricted behaviour. */
+export function allowAllLayer() {
+    return grantLayer("allow-all", ["write", "execute"]);
+}
+//# sourceMappingURL=Policy.js.map

package/dist/policy/Policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Policy.js","sourceRoot":"","sources":["../../src/policy/Policy.ts"],"names":[],"mappings":"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"}

package/dist/policy/PolicyEnv.d.ts

@@ -0,0 +1,46 @@
+import { PolicyLayer, Verb } from "./PolicyTypes.js";
+/**
+ * Environment-variable policy layers.
+ *
+ * `NEX_POLICY_DENY` sits at the top of the ladder and cannot be granted past.
+ * `NEX_POLICY_ALLOW` sits near the bottom and exists for backward compatibility, so an
+ * existing CI job can restore its previous behaviour with one variable rather than
+ * editing every command line.
+ *
+ * Named `NEX_POLICY_*` rather than `NEX_ALLOW_WRITE` because `write` and `execute`
+ * collide with ServiceNow ACL vocabulary, and a reader should not have to work out
+ * whether this is about ACLs.
+ */
+export declare const DENY_ENV = "NEX_POLICY_DENY";
+export declare const ALLOW_ENV = "NEX_POLICY_ALLOW";
+export interface ParsedVerbs {
+    readonly verbs: readonly Verb[];
+    /** Tokens that were not recognised. Non-empty means the value was malformed. */
+    readonly unknown: readonly string[];
+}
+/**
+ * Parses a comma-separated verb list.
+ *
+ * `all` expands to every verb. Unrecognised tokens are REPORTED rather than dropped, so
+ * the caller can fail closed — see `denyFromEnvironment`.
+ */
+export declare function parseVerbList(raw: string | undefined): ParsedVerbs;
+/**
+ * The deny layer, built from `NEX_POLICY_DENY`.
+ *
+ * FAILS CLOSED on a malformed value. `NEX_POLICY_DENY=wrtie` denies everything and
+ * warns, rather than silently denying nothing — a typo in the variable that is supposed
+ * to protect production must not quietly disable the protection. That is the whole
+ * reason this function reports `unknown` instead of filtering it away.
+ *
+ * Returns `undefined` when the variable is unset, so the layer is simply absent.
+ */
+export declare function denyFromEnvironment(env?: NodeJS.ProcessEnv, warn?: (message: string) => void): PolicyLayer | undefined;
+/**
+ * The backward-compatibility grant layer, built from `NEX_POLICY_ALLOW`.
+ *
+ * Unrecognised tokens here are dropped with a warning rather than failing closed: this
+ * variable only ever *grants*, so a typo already fails safe — the operation is refused
+ * and the operator sees why.
+ */
+export declare function allowFromEnvironment(env?: NodeJS.ProcessEnv, warn?: (message: string) => void): PolicyLayer | undefined;

package/dist/policy/PolicyEnv.js

@@ -0,0 +1,92 @@
+import { denyLayer, grantLayer } from "./Policy.js";
+/**
+ * Environment-variable policy layers.
+ *
+ * `NEX_POLICY_DENY` sits at the top of the ladder and cannot be granted past.
+ * `NEX_POLICY_ALLOW` sits near the bottom and exists for backward compatibility, so an
+ * existing CI job can restore its previous behaviour with one variable rather than
+ * editing every command line.
+ *
+ * Named `NEX_POLICY_*` rather than `NEX_ALLOW_WRITE` because `write` and `execute`
+ * collide with ServiceNow ACL vocabulary, and a reader should not have to work out
+ * whether this is about ACLs.
+ */
+export const DENY_ENV = "NEX_POLICY_DENY";
+export const ALLOW_ENV = "NEX_POLICY_ALLOW";
+const ALL = "all";
+const VALID = ["write", "execute"];
+/**
+ * Parses a comma-separated verb list.
+ *
+ * `all` expands to every verb. Unrecognised tokens are REPORTED rather than dropped, so
+ * the caller can fail closed — see `denyFromEnvironment`.
+ */
+export function parseVerbList(raw) {
+    if (raw === undefined) {
+        return { verbs: [], unknown: [] };
+    }
+    const tokens = raw
+        .split(",")
+        .map((t) => t.trim().toLowerCase())
+        .filter((t) => t.length > 0);
+    if (tokens.includes(ALL)) {
+        return { verbs: [...VALID], unknown: [] };
+    }
+    const verbs = [];
+    const unknown = [];
+    for (const token of tokens) {
+        if (VALID.includes(token)) {
+            verbs.push(token);
+        }
+        else {
+            unknown.push(token);
+        }
+    }
+    return { verbs, unknown };
+}
+/**
+ * The deny layer, built from `NEX_POLICY_DENY`.
+ *
+ * FAILS CLOSED on a malformed value. `NEX_POLICY_DENY=wrtie` denies everything and
+ * warns, rather than silently denying nothing — a typo in the variable that is supposed
+ * to protect production must not quietly disable the protection. That is the whole
+ * reason this function reports `unknown` instead of filtering it away.
+ *
+ * Returns `undefined` when the variable is unset, so the layer is simply absent.
+ */
+export function denyFromEnvironment(env = process.env, warn = () => undefined) {
+    const raw = env[DENY_ENV];
+    if (raw === undefined || raw.trim().length === 0) {
+        return undefined;
+    }
+    const { verbs, unknown } = parseVerbList(raw);
+    if (unknown.length > 0) {
+        warn(`${DENY_ENV} contains unrecognised value(s): ${unknown.join(", ")}. ` +
+            `Denying all changes. Valid values are: ${VALID.join(", ")}, all.`);
+        return denyLayer(`${DENY_ENV} (malformed, failing closed)`, VALID);
+    }
+    return denyLayer(DENY_ENV, verbs);
+}
+/**
+ * The backward-compatibility grant layer, built from `NEX_POLICY_ALLOW`.
+ *
+ * Unrecognised tokens here are dropped with a warning rather than failing closed: this
+ * variable only ever *grants*, so a typo already fails safe — the operation is refused
+ * and the operator sees why.
+ */
+export function allowFromEnvironment(env = process.env, warn = () => undefined) {
+    const raw = env[ALLOW_ENV];
+    if (raw === undefined || raw.trim().length === 0) {
+        return undefined;
+    }
+    const { verbs, unknown } = parseVerbList(raw);
+    if (unknown.length > 0) {
+        warn(`${ALLOW_ENV} contains unrecognised value(s): ${unknown.join(", ")}, ignored. ` +
+            `Valid values are: ${VALID.join(", ")}, all.`);
+    }
+    if (verbs.length === 0) {
+        return undefined;
+    }
+    return grantLayer(ALLOW_ENV, verbs);
+}
+//# sourceMappingURL=PolicyEnv.js.map

package/dist/policy/PolicyEnv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PolicyEnv.js","sourceRoot":"","sources":["../../src/policy/PolicyEnv.ts"],"names":[],"mappings":"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"}

package/dist/policy/PolicyRefusal.d.ts

@@ -0,0 +1,17 @@
+import { Decision, Verb } from "./PolicyTypes.js";
+export interface PolicyRefusalError extends Error {
+    readonly decision: Decision;
+}
+/** True when `value` is a refusal thrown by ANY copy of this library. */
+export declare function isPolicyRefusal(value: unknown): value is PolicyRefusalError;
+/**
+ * Builds the error thrown when an operation is refused.
+ *
+ * The message states what was needed and what to do about it. It deliberately does NOT
+ * name an MCP tool parameter: on that surface the caller is the model, and a refusal
+ * that advertises its own escape hatch just teaches the model to set it and retry.
+ * The CLI remediation names its flags, because there a human typed the command.
+ */
+export declare function policyRefusal(decision: Decision): PolicyRefusalError;
+/** Convenience for the common single-verb refusal. */
+export declare function refusalFor(verb: Verb, decidingLayer: string, remediation?: string): PolicyRefusalError;

package/dist/policy/PolicyRefusal.js

@@ -0,0 +1,69 @@
+/**
+ * Marks an error as a policy refusal.
+ *
+ * `Symbol.for`, not a class and not `instanceof`. This package is published, and a
+ * consumer can easily end up with two copies in `node_modules` — a transitive
+ * dependency on an older major, a pruned install, a bundler that duplicated it. With a
+ * class, `instanceof` then returns false for an error thrown by the *other* copy, and
+ * the failure is silent: `BackgroundScriptExecutor.executeScriptAuto` would stop
+ * recognising a refusal and fall back to `sys_trigger`, executing the very script that
+ * was just refused.
+ *
+ * The registry symbol is global to the process, so it identifies correctly across
+ * copies. This repo already carries the dual-copy exposure with `StaleInstanceError`
+ * (see `RequestHandler.toThrowable`, which goes out of its way to preserve identity);
+ * this is that lesson applied rather than repeated.
+ */
+const POLICY_REFUSAL = Symbol.for("now-sdk-ext.policy-refusal");
+/** True when `value` is a refusal thrown by ANY copy of this library. */
+export function isPolicyRefusal(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    return value[POLICY_REFUSAL] === true;
+}
+/**
+ * Builds the error thrown when an operation is refused.
+ *
+ * The message states what was needed and what to do about it. It deliberately does NOT
+ * name an MCP tool parameter: on that surface the caller is the model, and a refusal
+ * that advertises its own escape hatch just teaches the model to set it and retry.
+ * The CLI remediation names its flags, because there a human typed the command.
+ */
+export function policyRefusal(decision) {
+    const verbs = decision.verbs.join(" and ");
+    const detail = decision.remediation
+        ? `${decision.remediation}`
+        : `This operation requires ${verbs} permission, which has not been granted.`;
+    const error = new Error(detail);
+    error.name = "PolicyRefusalError";
+    error[POLICY_REFUSAL] = true;
+    // Non-enumerable AND writable, both load-bearing.
+    //
+    // `stripSecretsFromError` walks `Object.keys(err)` and reassigns every object-valued
+    // child through the redactor. An enumerable, non-writable `decision` made that throw
+    // `Cannot assign to read only property 'decision'` — which replaced the refusal with
+    // a TypeError on the way out, so callers saw a crash instead of a refusal and
+    // `isPolicyRefusal` returned false. Found by the live integration run, not by any
+    // unit test, because nothing in isolation puts a refusal through the redactor.
+    //
+    // Non-enumerable also keeps it out of JSON.stringify and out of log serialisation,
+    // which is where it would otherwise show up as noise.
+    Object.defineProperty(error, "decision", {
+        value: decision,
+        enumerable: false,
+        writable: true,
+        configurable: true,
+    });
+    return error;
+}
+/** Convenience for the common single-verb refusal. */
+export function refusalFor(verb, decidingLayer, remediation) {
+    return policyRefusal({
+        allowed: false,
+        verbs: [verb],
+        decidingLayer,
+        remediation,
+    });
+}
+//# sourceMappingURL=PolicyRefusal.js.map

package/dist/policy/PolicyRefusal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PolicyRefusal.js","sourceRoot":"","sources":["../../src/policy/PolicyRefusal.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;AAMhE,yEAAyE;AACzE,MAAM,UAAU,eAAe,CAAC,KAAc;IAC1C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,OAAQ,KAAiC,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;AACvE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,QAAkB;IAC5C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAW;QAC/B,CAAC,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE;QAC3B,CAAC,CAAC,2BAA2B,KAAK,0CAA0C,CAAC;IAEjF,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,CAAiD,CAAC;IAChF,KAAK,CAAC,IAAI,GAAG,oBAAoB,CAAC;IAClC,KAAK,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC;IAC7B,kDAAkD;IAClD,EAAE;IACF,qFAAqF;IACrF,qFAAqF;IACrF,qFAAqF;IACrF,8EAA8E;IAC9E,kFAAkF;IAClF,+EAA+E;IAC/E,EAAE;IACF,mFAAmF;IACnF,sDAAsD;IACtD,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE;QACrC,KAAK,EAAE,QAAQ;QACf,UAAU,EAAE,KAAK;QACjB,QAAQ,EAAE,IAAI;QACd,YAAY,EAAE,IAAI;KACrB,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACjB,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,UAAU,CAAC,IAAU,EAAE,aAAqB,EAAE,WAAoB;IAC9E,OAAO,aAAa,CAAC;QACjB,OAAO,EAAE,KAAK;QACd,KAAK,EAAE,CAAC,IAAI,CAAC;QACb,aAAa;QACb,WAAW;KACd,CAAC,CAAC;AACP,CAAC"}

package/dist/policy/PolicyTypes.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Vocabulary for gating instance mutations.
+ *
+ * This is a GUARDRAIL, not a security boundary. Anything holding the credential can
+ * reach the instance directly — by importing this library and calling the SDK, or with
+ * curl. What it buys is that *inadvertent* mutation stops being the default when an AI
+ * agent is driving, and that an operator can hard-deny from an environment the agent
+ * cannot write to. Do not describe it as anything stronger.
+ */
+/**
+ * What an operation does. Two verbs, deliberately.
+ *
+ * CRUD was considered and rejected: `nex exec`, ATF runs and flow execution all mutate
+ * without being create, edit or delete, so a CRUD vocabulary leaves them homeless.
+ */
+export type Verb = "write" | "execute";
+/**
+ * WHERE the effect lands. Not every write is a write to the instance.
+ *
+ * `pull_script` overwrites a local file, `scope set` changes session state, and the
+ * `auth` commands write the credential store. Gating those as instance writes would
+ * produce false refusals on operations that never touch ServiceNow data, so the target
+ * is carried alongside the verb rather than inventing more verbs.
+ *
+ * Only `instance` is gated today; the rest exist so the distinction is recorded at the
+ * call site rather than rediscovered later.
+ */
+export type Target = "instance" | "local" | "session";
+/** What an operation needs before it may proceed. */
+export interface Requirement {
+    readonly verbs: readonly Verb[];
+    readonly target: Target;
+}
+/** A requirement that needs no permission at all. */
+export declare const READ_ONLY: Requirement;
+/**
+ * A layer's answer.
+ *
+ * `abstain` is distinct from `deny` on purpose — it means "I have no opinion", so a
+ * lower-priority layer still gets to speak. Collapsing the two would make an unset
+ * environment variable behave like an explicit denial.
+ */
+export type LayerAnswer = "grant" | "deny" | "abstain";
+/** One rung of the precedence ladder. */
+export interface PolicyLayer {
+    /** Appears in refusals and the audit log, so make it recognisable to an operator. */
+    readonly name: string;
+    answer(verb: Verb): LayerAnswer;
+}
+/**
+ * The result of a check.
+ *
+ * An object rather than a boolean so the deciding layer can be reported — "why was this
+ * refused" is otherwise unanswerable — and so a future `ApprovalToken` (NEX-76) can be
+ * added as a grant layer without changing this signature.
+ */
+export interface Decision {
+    readonly allowed: boolean;
+    /** The verbs actually required. Empty means the operation needed no permission. */
+    readonly verbs: readonly Verb[];
+    /** Name of the layer that decided. `"default"` when nothing granted. */
+    readonly decidingLayer: string;
+    /** Present only when refused. Written for a human, never naming an MCP parameter. */
+    readonly remediation?: string;
+}

package/dist/policy/PolicyTypes.js

@@ -0,0 +1,15 @@
+/**
+ * Vocabulary for gating instance mutations.
+ *
+ * This is a GUARDRAIL, not a security boundary. Anything holding the credential can
+ * reach the instance directly — by importing this library and calling the SDK, or with
+ * curl. What it buys is that *inadvertent* mutation stops being the default when an AI
+ * agent is driving, and that an operator can hard-deny from an environment the agent
+ * cannot write to. Do not describe it as anything stronger.
+ */
+/** A requirement that needs no permission at all. */
+export const READ_ONLY = Object.freeze({
+    verbs: Object.freeze([]),
+    target: "instance",
+});
+//# sourceMappingURL=PolicyTypes.js.map

package/dist/policy/PolicyTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PolicyTypes.js","sourceRoot":"","sources":["../../src/policy/PolicyTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA6BH,qDAAqD;AACrD,MAAM,CAAC,MAAM,SAAS,GAAgB,MAAM,CAAC,MAAM,CAAC;IAChD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAoB;IAC3C,MAAM,EAAE,UAAU;CACrB,CAAC,CAAC"}

package/dist/policy/ScanScript.d.ts

@@ -0,0 +1,22 @@
+import { Verb } from "./PolicyTypes.js";
+export interface ScriptScanResult {
+    /** Verbs the script needs BEYOND `execute`. Today this is `["write"]` or `[]`. */
+    readonly verbs: readonly Verb[];
+    /** Why, in the order found. Surfaced to the user so a refusal is explainable. */
+    readonly reasons: readonly string[];
+    /** True when the scan could not resolve something and escalated as a result. */
+    readonly escalated: boolean;
+}
+/**
+ * Reports the extra permission a script needs.
+ *
+ * Call this with the script that will ACTUALLY be sent — after any `{param}`
+ * substitution. Scanning the pre-substitution text is a hole you could drive a
+ * parameter value of `gr.insert()` through.
+ */
+export declare function scanScript(script: string): ScriptScanResult;
+/** Convenience: what a background script needs in total. */
+export declare function requirementForScript(script: string): {
+    verbs: Verb[];
+    reasons: readonly string[];
+};