suitescript-verify 0.0.0 → 0.1.0

package/README.md

@@ -4,8 +4,6 @@ Run probes in a NetSuite **sandbox** to verify what SuiteScript modules do, from
 
 > This package never accepts Oracle's SuiteCloud license. Install `@oracle/suitecloud-cli` in your project and accept the license yourself.
 
-Early version: `help`, `init`, `doctor` and `deploy` exist. The rest of the CLI (`certificate`, `passkey`, `env`, `setup-ci`, `run`, `cleanup`) is being extracted from an existing project.
-
 ```sh
 npm install --save-dev suitescript-verify @oracle/suitecloud-cli
 npx suitescript-verify help
@@ -13,7 +11,29 @@ npx suitescript-verify help
 
 `init` scaffolds `verification/probes`, `verification/sdf`, `docs/verification/results` and a committed `verification/.env` of layout keys, then prints a to-do list. It creates no credentials. `doctor` checks the SuiteCloud CLI, account, sandbox, certificates, passkey and project files, and says which failing steps are the maintainer's own; it exits 1 while any fails.
 
-`deploy` dry-runs the runner deployment through your project's SuiteCloud CLI from `verification/sdf` (`--dir <path>` moves `verification/`). A real deploy needs `--approved` and a person at a terminal who types `DEPLOY`.
+`certificate` generates the runner key pair (EC P-256) and the SDF key pair (RSA-4096) outside the project with `openssl` (`--keys-dir`, default `~/.suitescript-verify`), `passkey` and `env set NAME=value` save settings in the gitignored `verification/.env.local` (values are never printed; a different existing value is kept unless `--overwrite`), and `setup-ci` registers the SDF credentials with the SuiteCloud CLI.
+
+`setup-ci` prepares a pipeline: it registers the SDF credentials (auth id `suitescript-verify`) with your project's SuiteCloud CLI and passes the passkey to it through the environment, never an argument. On success it prints the `SUITESCRIPT_VERIFY_` names the pipeline must supply as its own secrets (account, client id, both certificate ids, both private key paths, passkey), never a value. It writes no file, no credential variable and no license variable, and it holds no credential itself: the pipeline provides them. Accepting Oracle's SuiteCloud license in the pipeline is yours.
+
+`deploy` generates the runner and an SDF project into `verification/sdf` (the generated `src/` and `package.json` there are yours to gitignore) from the RESTlet probes in `verification/probes`, then dry-runs it through your project's SuiteCloud CLI. A real deploy needs `--approved` and a person at a terminal who types `DEPLOY`. `cleanup` does the same with the runner's deployment switched off and needs `CLEANUP`. `--dir <path>` moves `verification/`.
+
+`run <probe> [--draft]` runs one probe by name through the deployed runner. The name must be one of the probes in the folder: the runner only runs the fixed list generated into it and never code from a request. Output is scrubbed of the account, client and certificate ids, and refused if it still looks like an identifier. A probe with an `<probe>.expect.json` is compared with it and a difference exits 2 as drift. `--draft` writes `docs/verification/results/<probe>.md` (never over an existing page) with the test, NetSuite version and results, and empty explanation and decision sections. Probes must declare `@scriptType Restlet` and no `@writes`.
+
+A probe takes data by declaring parameters in its leading JSDoc block, one tag per parameter: `@param <name> <pattern>`. The name is lowercase-initial letters and digits (`recordType`); the pattern is a JavaScript regular expression (Unicode mode) that the whole value must match, so `[a-z_]+` cannot match `a;b`. Pass each value with `run <probe> --param name=value`. Every declared parameter is required and its value is always a string. The runner validates the parameters against the declarations before any request, rejecting an invalid, undeclared, missing or repeated one, and a probe that declares none takes none; the generated runner checks them again and hands the probe only declared strings in `run(params)`. A value goes in the JSON request body and is never evaluated or turned into code. A bad `@param` tag (no pattern, an invalid pattern, a duplicate name) stops `run` and `deploy`.
+
+The package validates the tags in a probe's leading JSDoc block: `@scriptType`, `@writes`, `@param`, the NetSuite `@NApiVersion`, `@NScriptType` and `@NModuleScope`, and the ordinary `@see`, `@link`, `@example`, `@returns`, `@since` and `@deprecated`. Any other tag is reported and stops `run` and `deploy`, so a typo cannot pass silently. A project that keeps its own tags registers them with `SUITESCRIPT_VERIFY_EXTRA_TAGS`, a comma-separated list of tag names without the `@` (for example `SUITESCRIPT_VERIFY_EXTRA_TAGS=flavor,other`). Like every `SUITESCRIPT_VERIFY_` setting it layers from the committed `verification/.env`, the gitignored `.env.local` and the process environment. In the committed file the value must be a list of tag names and must not look like a secret. The package checks only that a registered tag is known; what a tag means is up to the project.
+
+```js
+/**
+ * @scriptType Restlet
+ * @param recordType ^[a-z_]+$
+ */
+define(["N/record"], (record) => ({
+  run: ({ recordType }) => /* ... */,
+}));
+```
+
+Every command that reaches the sandbox refuses an account that is not a sandbox (`digits_SBn`). The runner uses the script id `customscript_suitescript_verify_runner` and is limited to a role with the ID `customrole_suitescript_verify`, which you create in the sandbox.
 
 See [docs/verification/README.md](docs/verification/README.md) and [docs/verification/lessons.md](docs/verification/lessons.md).
 

package/dist/certificate.js

@@ -0,0 +1,116 @@
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { names } from "./doctor.js";
+import { allowReplace, flagValue, saveEnv, UsageError } from "./shared.js";
+/** Oracle's documented `openssl` commands: ES256 (EC P-256) and RSA-PSS (RSA-4096, PS256). */
+function generatePair(options) {
+    const keyArgs = options.kind === "ec"
+        ? [
+            "-newkey",
+            "ec",
+            "-pkeyopt",
+            "ec_paramgen_curve:prime256v1",
+            "-pkeyopt",
+            "ec_param_enc:named_curve",
+        ]
+        : [
+            "-newkey",
+            "rsa:4096",
+            "-sigopt",
+            "rsa_padding_mode:pss",
+            "-sha256",
+            "-sigopt",
+            "rsa_pss_saltlen:64",
+        ];
+    const result = spawnSync(options.openssl, [
+        "req",
+        "-new",
+        "-x509",
+        ...keyArgs,
+        "-nodes",
+        "-days",
+        "365",
+        "-subj",
+        "/CN=suitescript-verify",
+        "-out",
+        options.publicKey,
+        "-keyout",
+        options.privateKey,
+    ], { encoding: "utf8" });
+    if (result.status !== 0) {
+        throw new UsageError("openssl failed to generate the key pair.");
+    }
+    try {
+        chmodSync(options.privateKey, 0o600);
+    }
+    catch {
+        // Windows ignores POSIX modes.
+    }
+    if (process.platform === "win32" && process.env.USERNAME) {
+        spawnSync("icacls", [
+            options.privateKey,
+            "/inheritance:r",
+            "/grant:r",
+            `${process.env.USERNAME}:F`,
+        ]);
+    }
+}
+/** Generates the runner (EC P-256) and SDF (RSA-4096) key pairs outside the project and saves their paths in .env.local. */
+export async function certificate(project, config, args) {
+    const dir = resolve(flagValue(args, "--keys-dir") ?? join(homedir(), ".suitescript-verify"));
+    const rel = relative(project, dir);
+    if (rel === "" || !(rel.startsWith("..") || isAbsolute(rel))) {
+        throw new UsageError("Choose a --keys-dir outside the project.");
+    }
+    const openssl = [
+        "openssl",
+        ...(process.platform === "win32"
+            ? ["C:\\Program Files\\Git\\usr\\bin\\openssl.exe"]
+            : []),
+    ].find((candidate) => spawnSync(candidate, ["version"], { encoding: "utf8" }).status === 0);
+    if (!openssl) {
+        throw new UsageError("openssl was not found. Generate the key pairs by hand with Oracle's documented openssl commands.");
+    }
+    // The runner token is signed here (ES256, EC P-256). Oracle's SDK signs the
+    // SDF login with PS256 and an RSA key only, so that pair is RSA-4096.
+    const kinds = { runner: "ec", sdf: "rsa" };
+    const only = flagValue(args, "--only");
+    if (only !== undefined && only !== "runner" && only !== "sdf") {
+        throw new UsageError("--only takes runner or sdf.");
+    }
+    const which = ["runner", "sdf"].filter((name) => only === undefined || only === name);
+    const paths = (name) => ({
+        privateKey: join(dir, `${name}-private.pem`),
+        publicKey: join(dir, `${name}-public.pem`),
+    });
+    mkdirSync(dir, { mode: 0o700, recursive: true });
+    for (const name of which) {
+        const pair = paths(name);
+        const exists = existsSync(pair.privateKey) || existsSync(pair.publicKey);
+        const mapped = config.values[name === "runner" ? names.certificateId : names.sdfCertificateId];
+        if (exists && mapped) {
+            console.log(`Warning: a ${name} certificate id is already saved. A mapping cannot be recreated with the same certificate, and replacing this pair makes that mapping unusable (its private key is lost).`);
+        }
+        if (!exists || (await allowReplace(args, `The ${name} key pair`))) {
+            generatePair({ kind: kinds[name], openssl, ...pair });
+            console.log(`Generated the ${name} key pair (${kinds[name] === "ec" ? "EC P-256" : "RSA-4096, RSA-PSS certificate"}, valid for 365 days).`);
+        }
+        else
+            console.log(`Kept the existing ${name} key pair.`);
+    }
+    await saveEnv(config, args, {
+        ...(which.includes("runner")
+            ? { [names.privateKeyPath]: paths("runner").privateKey }
+            : {}),
+        ...(which.includes("sdf")
+            ? { [names.sdfPrivateKeyPath]: paths("sdf").privateKey }
+            : {}),
+    });
+    console.log([
+        "",
+        "Upload these public certificates in your sandbox (Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup):",
+        ...which.map((name) => `  ${name}: ${paths(name).publicKey}`),
+    ].join("\n"));
+}

package/dist/cli.js

@@ -1,68 +1,33 @@
-import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { createInterface } from "node:readline/promises";
+import { randomBytes } from "node:crypto";
+import { certificate } from "./certificate.js";
 import { loadConfig } from "./config.js";
-import { formatChecks, runChecks } from "./doctor.js";
+import { formatChecks, names, runChecks } from "./doctor.js";
+import { envNames } from "./envfile.js";
 import { init } from "./init.js";
+import { runProbe } from "./run.js";
+import { buildSdfProject } from "./sdf.js";
+import { confirmWrite, flagValue, positionals, requireSandbox, saveEnv, suitecloud, UsageError, } from "./shared.js";
 export const USAGE = `Usage: suitescript-verify <command> [options]
 
 Commands:
-  deploy [--approved] [--dir <path>]   Dry-run the runner deployment; --approved deploys, from your own terminal
-  doctor [--dir <path>]                Check the setup; each failing step says who does it
-  init [--dir <path>]                  Scaffold the folders and .env, and print a to-do list
+  init                                 Scaffold the folders and .env, and print a to-do list
+  doctor                               Check the setup; each failing step says who does it
+  certificate [--only runner|sdf] [--keys-dir <path>] [--overwrite | --keep]
+                                       Generate the key pairs outside the project
+  passkey [--overwrite | --keep]       Generate the SuiteCloud passkey into .env.local
+  env set NAME=value [--overwrite | --keep]
+                                       Save a setting in .env.local
+  setup-ci                             Register the SDF credentials (account:setup:ci)
+  deploy [--approved]                  Dry-run the runner deployment; --approved deploys, from your own terminal
+  run <probe> [--param name=value ...] [--draft]              Run one RESTlet probe through the runner; --draft writes a results page
+  cleanup [--approved]                 Turn the runner's deployment off (dry run without --approved)
   help                                 Show this help
 
+Every command takes --dir <path> to move the verification folder (default verification).
+
 Probes run in a NetSuite sandbox only. The package never accepts Oracle's SuiteCloud license:
 install @oracle/suitecloud-cli in your project and accept the license yourself.`;
-class UsageError extends Error {
-}
-/** The project's own SuiteCloud CLI (a peer dependency), never a global one. */
-function suitecloudEntry(project) {
-    const entry = join(project, "node_modules", "@oracle", "suitecloud-cli", "src", "suitecloud.js");
-    if (!existsSync(entry)) {
-        throw new UsageError("Install @oracle/suitecloud-cli in this project (npm install --save-dev @oracle/suitecloud-cli), and accept Oracle's license yourself.");
-    }
-    return entry;
-}
-/** Runs the project's SuiteCloud CLI from the SDF project folder. */
-function suitecloud(project, sdfDir, args, layered) {
-    const env = { ...process.env, ...layered };
-    // Hand the passkey to the CLI for this child process only.
-    if (env.SUITESCRIPT_VERIFY_PASSKEY) {
-        env.SUITECLOUD_CI_PASSKEY = env.SUITESCRIPT_VERIFY_PASSKEY;
-    }
-    if (env.SUITECLOUD_CI_PASSKEY)
-        env.SUITECLOUD_CI = "1";
-    const result = spawnSync(process.execPath, [suitecloudEntry(project), ...args], { cwd: sdfDir, env, stdio: "inherit" });
-    return result.status ?? 1;
-}
-/**
- * A write to the sandbox needs a person at a terminal, on top of --approved:
- * an agent's shell has none, so an agent cannot run it. The person types the
- * action name to confirm.
- */
-async function confirmWrite(action, what) {
-    if (!process.stdin.isTTY) {
-        throw new UsageError(`${what} needs the user at a terminal. Ask the user to run this same command, with --approved, in their own terminal.`);
-    }
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    const answer = await rl.question(`${what}. Type ${action} to continue: `);
-    rl.close();
-    if (answer.trim() !== action) {
-        throw new UsageError("Not confirmed. Nothing was changed.");
-    }
-}
-/** The value after `--dir`, when given. */
-function dirFlag(args) {
-    const flag = args.indexOf("--dir");
-    if (flag < 0)
-        return undefined;
-    const value = args[flag + 1];
-    if (!value)
-        throw new UsageError("--dir needs a path.");
-    return value;
-}
+const dirFlag = (args) => flagValue(args, "--dir");
 /** Loads the layered configuration; a problem stops every command except the reporting ones. */
 function configure(args, refuse) {
     const config = loadConfig(process.cwd(), dirFlag(args));
@@ -95,13 +60,96 @@ function initCommand(args) {
 async function deploy(args) {
     const project = process.cwd();
     const config = configure(args, true);
+    requireSandbox(config);
+    const { files, slugs } = buildSdfProject(config.sdfDir, config.probesDir, {
+        deployed: true,
+        extraTags: config.extraTags,
+    });
+    console.log(`Probes in the runner: ${slugs.join(", ") || "(none)"}`);
+    console.log(`Files to upload: ${files.join(", ")}`);
     const approved = args.includes("--approved");
     if (approved)
         await confirmWrite("DEPLOY", "This deploys to the sandbox");
     else {
-        console.log("Dry run only. Deploying writes to the sandbox, so ask the user for approval, then rerun with --approved.");
+        console.log("\nDry run only. Deploying writes to the sandbox, so ask the user for approval, then rerun with --approved.");
+    }
+    return suitecloud(project, config, [
+        "project:deploy",
+        ...(approved ? [] : ["--dryrun"]),
+    ]);
+}
+async function cleanup(args) {
+    const project = process.cwd();
+    const config = configure(args, true);
+    requireSandbox(config);
+    const approved = args.includes("--approved");
+    if (approved) {
+        await confirmWrite("CLEANUP", "This turns the runner's deployment off");
+    }
+    else {
+        console.log("Dry run only. This turns the runner's deployment off in the sandbox, so ask the user for approval, then rerun with --approved.\nTo remove access entirely, the user revokes the certificate mapping (Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup).");
     }
-    return suitecloud(project, config.sdfDir, ["project:deploy", ...(approved ? [] : ["--dryrun"])], config.values);
+    buildSdfProject(config.sdfDir, config.probesDir, {
+        deployed: false,
+        extraTags: config.extraTags,
+    });
+    return suitecloud(project, config, [
+        "project:deploy",
+        ...(approved ? [] : ["--dryrun"]),
+    ]);
+}
+const CI_SETTINGS = [
+    "ACCOUNT",
+    "CLIENT_ID",
+    "CERTIFICATE_ID",
+    "PRIVATE_KEY_PATH",
+    "SDF_CERTIFICATE_ID",
+    "SDF_PRIVATE_KEY_PATH",
+    "PASSKEY",
+].map((name) => `  SUITESCRIPT_VERIFY_${name}`);
+const CI_NOTES = [
+    "",
+    "Registered the SDF credentials with the SuiteCloud CLI. To run probes from a pipeline, the pipeline supplies these settings as its own secrets and variables (names only; this command wrote none and holds no value):",
+    ...CI_SETTINGS,
+    "Accept Oracle's SuiteCloud license yourself in the pipeline; this package never does.",
+].join("\n");
+function setupCi(args) {
+    const config = configure(args, true);
+    const creds = requireSandbox(config);
+    const status = suitecloud(process.cwd(), config, [
+        "account:setup:ci",
+        "--account",
+        creds.account,
+        "--authid",
+        "suitescript-verify",
+        "--certificateid",
+        creds.sdfCertificateId,
+        "--privatekeypath",
+        creds.sdfPrivateKeyPath,
+        ...(config.values.SUITESCRIPT_VERIFY_DOMAIN
+            ? ["--domain", config.values.SUITESCRIPT_VERIFY_DOMAIN]
+            : []),
+    ]);
+    if (status === 0)
+        console.log(CI_NOTES);
+    return status;
+}
+async function envCommand(args) {
+    const config = configure(args, true);
+    const [action, assignment] = positionals(args);
+    const match = /^([A-Z0-9_]+)=([\s\S]*)$/.exec(assignment ?? "");
+    if (action !== "set" || !match) {
+        throw new UsageError("Usage: suitescript-verify env set NAME=value [--overwrite | --keep]");
+    }
+    const name = match[1] ?? "";
+    if (name === names.passkey) {
+        throw new UsageError("Generate the passkey with `suitescript-verify passkey`.");
+    }
+    if (!envNames.includes(name)) {
+        throw new UsageError(`Unknown variable ${name}. Known: ${envNames.join(", ")}`);
+    }
+    await saveEnv(config, args, { [name]: match[2] ?? "" });
+    return 0;
 }
 export async function main(args) {
     const [command, ...rest] = args;
@@ -112,6 +160,26 @@ export async function main(args) {
         }
         if (command === "deploy")
             return await deploy(rest);
+        if (command === "cleanup")
+            return await cleanup(rest);
+        if (command === "run") {
+            const config = configure(rest, true);
+            return await runProbe(process.cwd(), config, rest);
+        }
+        if (command === "certificate") {
+            await certificate(process.cwd(), configure(rest, true), rest);
+            return 0;
+        }
+        if (command === "passkey") {
+            await saveEnv(configure(rest, true), rest, {
+                [names.passkey]: randomBytes(30).toString("hex"),
+            });
+            return 0;
+        }
+        if (command === "env")
+            return await envCommand(rest);
+        if (command === "setup-ci")
+            return setupCi(rest);
         if (command === "doctor")
             return doctor(rest);
         if (command === "init")

package/dist/config.js

@@ -8,6 +8,14 @@ export const layoutKeys = [
     "SUITESCRIPT_VERIFY_RESULTS_DIR",
     "SUITESCRIPT_VERIFY_SDF_DIR",
 ];
+/** The committed `.env` may also register extra probe tags: a comma-separated list of tag names, not a path. */
+export const extraTagsKey = "SUITESCRIPT_VERIFY_EXTRA_TAGS";
+const tagName = /^[A-Za-z][A-Za-z0-9_-]*$/;
+/** The tag names in a registration value, without the `@`; blank entries are dropped. */
+export const parseTagList = (value) => value
+    .split(",")
+    .map((name) => name.trim().replace(/^@/, ""))
+    .filter((name) => name !== "");
 const unquote = (raw) => {
     const value = raw.trim();
     const quote = value[0];
@@ -45,9 +53,21 @@ const looksSecret = (value) => /-----BEGIN /.test(value) ||
 function checkCommitted(project, committed, file) {
     const problems = [];
     for (const [key, value] of committed) {
-        if (!layoutKeys.includes(key)) {
+        if (key === extraTagsKey) {
+            if (!parseTagList(value).every((name) => tagName.test(name))) {
+                problems.push({
+                    message: `${key} in ${file} is not a comma-separated list of tag names like flavor,other.`,
+                });
+            }
+            else if (looksSecret(value)) {
+                problems.push({
+                    message: `${key} in ${file} looks like a secret, not a list of tag names. The committed file is public: move a secret to .env.local.`,
+                });
+            }
+        }
+        else if (!layoutKeys.includes(key)) {
             problems.push({
-                message: `${key} in ${file} is not a layout key. The committed file holds layout only (${layoutKeys.join(", ")}); put anything else in .env.local or the process environment.`,
+                message: `${key} in ${file} is not a layout key. The committed file holds layout only (${[...layoutKeys, extraTagsKey].join(", ")}); put anything else in .env.local or the process environment.`,
             });
         }
         else if (!insideProject(project, value)) {
@@ -107,6 +127,7 @@ export function loadConfig(project, dir, processEnv = process.env) {
     const path = (key, fallback) => resolve(project, values[key] || fallback);
     const shown = relative(project, envFile).replaceAll("\\", "/");
     return {
+        extraTags: parseTagList(values[extraTagsKey] ?? ""),
         probesDir: path("SUITESCRIPT_VERIFY_PROBES_DIR", join(root, "probes")),
         problems: [
             ...checkCommitted(project, committed, shown),

package/dist/doctor.js

@@ -1,7 +1,7 @@
 import { createPrivateKey } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-const names = {
+export const names = {
     account: "SUITESCRIPT_VERIFY_ACCOUNT",
     certificateId: "SUITESCRIPT_VERIFY_CERTIFICATE_ID",
     clientId: "SUITESCRIPT_VERIFY_CLIENT_ID",
@@ -26,7 +26,7 @@ function keyType(path) {
     return "other";
 }
 /** A sandbox account id looks like `1234567_SB1`. Verification never runs in production. */
-export const isSandboxAccount = (account) => /^\d+_SB\d*$/i.test(account);
+export const isSandboxAccount = (account) => /^\d{5,8}_SB\d+$/i.test(account);
 /** Read-only checklist: each failing step says what to do next and who does it. */
 export function runChecks(project, config, env = process.env) {
     const checks = [];

package/dist/envfile.js

@@ -0,0 +1,56 @@
+import { parseEnv } from "./config.js";
+/** The variables `env set` accepts. The passkey has its own command, layout keys live in the committed `.env`. */
+export const envNames = [
+    "SUITESCRIPT_VERIFY_ACCOUNT",
+    "SUITESCRIPT_VERIFY_CLIENT_ID",
+    "SUITESCRIPT_VERIFY_CERTIFICATE_ID",
+    "SUITESCRIPT_VERIFY_PRIVATE_KEY_PATH",
+    "SUITESCRIPT_VERIFY_SDF_CERTIFICATE_ID",
+    "SUITESCRIPT_VERIFY_SDF_PRIVATE_KEY_PATH",
+    "SUITESCRIPT_VERIFY_DOMAIN",
+];
+const header = "# Local credentials for suitescript-verify. This file is gitignored.\n# Do not commit it and do not copy these values elsewhere.\n";
+/** Forward slashes keep a Windows path valid inside a dotenv file. */
+export const envValue = (value) => {
+    const normalized = value.replace(/\\/g, "/");
+    if (!/[\s#"']/.test(normalized))
+        return normalized;
+    // The reader does not unescape, so quote with a character the value lacks.
+    if (!normalized.includes('"'))
+        return `"${normalized}"`;
+    if (!normalized.includes("'"))
+        return `'${normalized}'`;
+    throw new Error("A value can not contain both kinds of quote.");
+};
+export function planEnvUpdate(text, entries) {
+    const current = parseEnv(text);
+    const plan = { conflicts: [], fresh: [], same: [] };
+    for (const [name, value] of Object.entries(entries)) {
+        const existing = current.get(name);
+        if (existing === undefined || existing === "")
+            plan.fresh.push(name);
+        else if (existing === value.replace(/\\/g, "/") || existing === value) {
+            plan.same.push(name);
+        }
+        else
+            plan.conflicts.push(name);
+    }
+    return plan;
+}
+/** Writes the entries, replacing a conflicting value only if its name is in `overwrite`. */
+export function applyEnvUpdate(text, entries, overwrite) {
+    const plan = planEnvUpdate(text, entries);
+    const write = new Set([
+        ...plan.fresh,
+        ...plan.conflicts.filter((name) => overwrite.has(name)),
+    ]);
+    let out = text === "" ? header : text;
+    for (const name of write) {
+        const line = `${name}=${envValue(entries[name] ?? "")}`;
+        const pattern = new RegExp(`^(\\s*(?:export\\s+)?${name}\\s*=).*$`, "m");
+        out = pattern.test(out)
+            ? out.replace(pattern, () => line)
+            : `${out.endsWith("\n") ? out : `${out}\n`}${line}\n`;
+    }
+    return out;
+}

package/dist/netsuite.js

@@ -0,0 +1,65 @@
+import { createPrivateKey, sign } from "node:crypto";
+export const runnerScriptId = "customscript_suitescript_verify_runner";
+export const runnerDeployId = "customdeploy_suitescript_verify_runner";
+export const fileCabinetFolder = "suitescript-verify";
+const host = (account) => account.trim().toLowerCase().replace(/_/g, "-");
+export const tokenUrl = (account) => `https://${host(account)}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token`;
+export const restletUrl = (account) => `https://${host(account)}.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=${runnerScriptId}&deploy=${runnerDeployId}`;
+const base64url = (data) => Buffer.from(data).toString("base64url");
+/** The signed JWT NetSuite's OAuth 2.0 client credentials flow expects: ES256 with an EC P-256 key. */
+export function clientAssertion(options) {
+    const key = createPrivateKey(options.privateKeyPem);
+    const curve = key.asymmetricKeyDetails?.namedCurve;
+    if (key.asymmetricKeyType !== "ec" || curve !== "prime256v1") {
+        throw new Error("The runner private key must be an EC P-256 key (ES256). Generate one with `suitescript-verify certificate`.");
+    }
+    const iat = Math.floor((options.now ?? Date.now()) / 1000);
+    const header = { alg: "ES256", kid: options.certificateId, typ: "JWT" };
+    const claims = {
+        aud: options.tokenEndpoint,
+        exp: iat + 55 * 60,
+        iat,
+        iss: options.clientId,
+        scope: "restlets",
+    };
+    const input = `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(claims))}`;
+    const signature = sign("sha256", Buffer.from(input), {
+        dsaEncoding: "ieee-p1363",
+        key,
+    });
+    return `${input}.${base64url(signature)}`;
+}
+const identifierPatterns = [
+    ["an account number", /\b\d{5,8}[_-](?:SB|RP|TSTDRV)\w*\b/i],
+    ["an account number", /\bTSTDRV\d+\b/i],
+    ["a NetSuite host", /[a-z0-9-]+\.[a-z0-9.-]*netsuite\.com/i],
+    ["a JWT", /\beyJ[\w-]{10,}\.[\w-]{10,}\./],
+    ["a long hex token", /\b[a-f0-9]{40,}\b/i],
+    ["a PEM block", /-----BEGIN [A-Z ]+-----/],
+    ["an email address", /[\w.+-]+@[\w-]+\.[\w.-]+/],
+];
+/**
+ * Replaces the configured account, client and certificate ids with
+ * placeholders, then reports anything that still looks like an identifier.
+ * Callers fail closed: they print or write nothing when `problems` is not empty.
+ */
+export function scrub(text, known) {
+    let out = text;
+    const replacements = [
+        [known.account, "<ACCOUNT>"],
+        [known.clientId, "<CLIENT-ID>"],
+        [known.certificateId, "<CERTIFICATE-ID>"],
+        [known.sdfCertificateId, "<SDF-CERTIFICATE-ID>"],
+    ];
+    for (const [value, placeholder] of replacements) {
+        if (value && value.length >= 4) {
+            out = out.split(value).join(placeholder);
+            out = out.split(value.toLowerCase()).join(placeholder);
+            out = out.split(value.replace(/_/g, "-").toLowerCase()).join(placeholder);
+        }
+    }
+    const problems = identifierPatterns
+        .filter(([, pattern]) => pattern.test(out))
+        .map(([label]) => `the output looks like it contains ${label}`);
+    return { problems: [...new Set(problems)], text: out };
+}

package/dist/probes.js

@@ -0,0 +1,93 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+export const read = (path) => readFileSync(path, "utf8").replace(/\r\n/g, "\n");
+/** A probe name is a lowercase slug: it ends up in a file name and the runner's fixed list. */
+export const isSlug = (name) => /^[a-z0-9][a-z0-9-]*$/.test(name);
+const paramName = /^[a-z][A-Za-z0-9]*$/;
+/** The whole value must match: a declared pattern is anchored, so `[0-9]+` cannot match `1;x`. */
+export const anchored = (pattern) => new RegExp(`^(?:${pattern})$`, "u");
+function parseParams(block) {
+    const params = [];
+    const paramProblems = [];
+    for (const match of block.matchAll(/^[ \t]*\*?[ \t]*@param\b[ \t]*(.*)$/gm)) {
+        const line = (match[1] ?? "").trim();
+        const [, name = "", pattern = ""] = /^(\S*)[ \t]*(.*)$/.exec(line) ?? [];
+        if (!paramName.test(name)) {
+            paramProblems.push(`@param "${name}" needs a name like recordType: @param <name> <pattern>`);
+        }
+        else if (params.some((param) => param.name === name)) {
+            paramProblems.push(`@param ${name} is declared more than once`);
+        }
+        else if (pattern === "") {
+            paramProblems.push(`@param ${name} needs a pattern: @param ${name} <pattern>`);
+        }
+        else {
+            try {
+                anchored(pattern);
+                params.push({ name, pattern });
+            }
+            catch {
+                paramProblems.push(`@param ${name} has an invalid pattern: ${pattern}`);
+            }
+        }
+    }
+    return { paramProblems, params };
+}
+/** The tags the package gives meaning to, and the ordinary NetSuite and JSDoc ones it lets through. */
+const builtinTags = new Set([
+    "scriptType",
+    "writes",
+    "param",
+    "NApiVersion",
+    "NScriptType",
+    "NModuleScope",
+    "see",
+    "link",
+    "example",
+    "returns",
+    "since",
+    "deprecated",
+].map((name) => name.toLowerCase()));
+/**
+ * Reads the tags in a probe's leading JSDoc block. A tag that is neither the
+ * package's own nor in `extraTags` (registered by the project) is reported.
+ */
+export function parseProbe(slug, source, extraTags = []) {
+    const block = /^\s*\/\*\*([\s\S]*?)\*\//.exec(source)?.[1] ?? "";
+    const tags = (name) => [...block.matchAll(new RegExp(`@${name}\\b[ \\t]*([^\\n*]*)`, "g"))].map((match) => (match[1] ?? "").trim());
+    const registered = new Set(extraTags.map((name) => name.toLowerCase()));
+    const unknownTags = [
+        ...new Set([...block.matchAll(/^[ \t]*\*?[ \t]*@([A-Za-z][\w-]*)/gm)].map((match) => match[1] ?? "")),
+    ].filter((name) => !builtinTags.has(name.toLowerCase()) &&
+        !registered.has(name.toLowerCase()));
+    return {
+        ...parseParams(block),
+        scriptType: tags("scriptType")[0] ?? "",
+        slug,
+        unknownTags,
+        writes: tags("writes").length > 0,
+    };
+}
+export function listProbes(dir, extraTags = []) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((file) => file.endsWith(".js"))
+        .map((file) => file.replace(/\.js$/, ""))
+        .filter(isSlug)
+        .sort()
+        .map((slug) => parseProbe(slug, read(join(dir, `${slug}.js`)), extraTags));
+}
+export const isRestlet = (probe) => probe.scriptType.toLowerCase() === "restlet";
+/** The output a probe produced when it was verified, if it declared one. */
+export function readExpect(slug, dir) {
+    const path = join(dir, `${slug}.expect.json`);
+    return existsSync(path) ? JSON.parse(read(path)) : undefined;
+}
+export const matchesExpect = (result, expected) => isDeepStrictEqual(result, expected);
+/** What is wrong with a probe's tags, for the commands that refuse to run it. */
+export const tagProblems = (probe) => [
+    ...probe.paramProblems,
+    ...probe.unknownTags.map((name) => `@${name} is not a tag the package knows; register it with SUITESCRIPT_VERIFY_EXTRA_TAGS=${name}`),
+];

package/dist/results.js

@@ -0,0 +1,33 @@
+import { relative } from "node:path";
+/** A draft results page: the test, the NetSuite version, the results, and empty explanation and decision sections for a person to fill in. */
+export function resultsDraft(options) {
+    const link = relative(options.resultsDir, options.probeFile).replaceAll("\\", "/");
+    return `# TODO(verify): what was verified
+
+- **NetSuite version:** ${options.version}
+- **Account type:** sandbox
+- **Date:** ${options.date}
+- **Method:** deployed RESTlet (the suitescript-verify runner)
+- **Probe:** [${options.probe.slug}](${link})
+
+## Test
+
+\`\`\`js
+${options.scriptSource.trimEnd()}
+\`\`\`
+
+## Results
+
+\`\`\`json
+${JSON.stringify(options.output, null, 2)}
+\`\`\`
+
+## Explanation
+
+TODO(verify): what the results mean, and how they relate to what each source claims.
+
+## Decision
+
+TODO(verify): what was decided because of the results.
+`;
+}

package/dist/run.js

@@ -0,0 +1,184 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { clientAssertion, restletUrl, scrub, tokenUrl } from "./netsuite.js";
+import { anchored, isRestlet, isSlug, listProbes, matchesExpect, read, readExpect, tagProblems, } from "./probes.js";
+import { resultsDraft } from "./results.js";
+import { positionals, requireSandbox, UsageError } from "./shared.js";
+/** Every `--param name=value` in the arguments, in order. The value may start with anything. */
+function suppliedParams(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] !== "--param")
+            continue;
+        const text = args[++i] ?? "";
+        const at = text.indexOf("=");
+        if (at < 1) {
+            throw new UsageError(`--param needs name=value, got "${text}".`);
+        }
+        out.push([text.slice(0, at), text.slice(at + 1)]);
+    }
+    return out;
+}
+/**
+ * Checks the supplied parameters against what the probe declares, before any
+ * request. A value is only ever data: it goes into the JSON body, and the
+ * runner passes it to the probe as a string, never evaluating it.
+ */
+function validateParams(probe, args) {
+    const problems = tagProblems(probe);
+    if (problems.length > 0) {
+        throw new UsageError(`${probe.slug} has invalid tags:\n${problems.map((m) => `- ${m}`).join("\n")}`);
+    }
+    const supplied = suppliedParams(args);
+    if (probe.params.length === 0) {
+        if (supplied.length > 0) {
+            throw new UsageError(`${probe.slug} takes no parameters; it declares no @param tags.`);
+        }
+        return {};
+    }
+    const values = new Map();
+    for (const [name, value] of supplied) {
+        if (!probe.params.some((param) => param.name === name)) {
+            throw new UsageError(`Parameter "${name}" is not declared by ${probe.slug}. Declared: ${probe.params.map((p) => p.name).join(", ")}`);
+        }
+        if (values.has(name)) {
+            throw new UsageError(`Parameter "${name}" was given more than once.`);
+        }
+        values.set(name, value);
+    }
+    for (const { name, pattern } of probe.params) {
+        const value = values.get(name);
+        if (value === undefined) {
+            throw new UsageError(`${probe.slug} needs --param ${name}=<value> matching ${pattern}`);
+        }
+        if (!anchored(pattern).test(value)) {
+            throw new UsageError(`Parameter "${name}" does not match ${pattern}`);
+        }
+    }
+    return Object.fromEntries(probe.params.map(({ name }) => [name, values.get(name) ?? ""]));
+}
+/**
+ * Runs one probe, by name from the fixed list in the probes folder, through
+ * the deployed runner. Nothing from a request or an argument is ever run as
+ * code: the runner only knows the probes generated into it by `deploy`.
+ */
+export async function runProbe(project, config, args) {
+    const creds = requireSandbox(config);
+    const name = positionals(args)[0] ?? "";
+    const probes = listProbes(config.probesDir, config.extraTags);
+    const probe = isSlug(name)
+        ? probes.find((candidate) => candidate.slug === name)
+        : undefined;
+    if (!probe) {
+        throw new UsageError(`Unknown probe "${name}". Known: ${probes.map((p) => p.slug).join(", ") || "(none)"}`);
+    }
+    if (!isRestlet(probe)) {
+        throw new UsageError(`${probe.slug} needs a ${probe.scriptType || "(undeclared)"} script. The runner only runs RESTlet probes (declare @scriptType Restlet); ask the user to run it by hand (docs/verification/README.md).`);
+    }
+    if (probe.writes) {
+        throw new UsageError(`${probe.slug} declares @writes, which needs the user's separate approval. That path is not automated.`);
+    }
+    const params = validateParams(probe, args);
+    if (!existsSync(creds.privateKeyPath)) {
+        throw new UsageError("The runner private key file does not exist.");
+    }
+    const known = {
+        account: creds.account,
+        certificateId: creds.certificateId,
+        clientId: creds.clientId,
+        sdfCertificateId: creds.sdfCertificateId,
+    };
+    const safe = (text) => scrub(text, known).text;
+    const endpoint = tokenUrl(creds.account);
+    const assertion = clientAssertion({
+        certificateId: creds.certificateId,
+        clientId: creds.clientId,
+        privateKeyPem: readFileSync(creds.privateKeyPath, "utf8"),
+        tokenEndpoint: endpoint,
+    });
+    let text;
+    try {
+        const tokenResponse = await fetch(endpoint, {
+            body: new URLSearchParams({
+                client_assertion: assertion,
+                client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
+                grant_type: "client_credentials",
+            }),
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            method: "POST",
+        });
+        const tokenBody = (await tokenResponse.json().catch(() => ({})));
+        if (!tokenResponse.ok || !tokenBody.access_token) {
+            throw new UsageError(safe(`Token request failed: HTTP ${tokenResponse.status} ${tokenBody.error ?? ""} ${tokenBody.error_description ?? ""}`.trim()));
+        }
+        const response = await fetch(restletUrl(creds.account), {
+            body: JSON.stringify(probe.params.length > 0
+                ? { params, probe: probe.slug }
+                : { probe: probe.slug }),
+            headers: {
+                authorization: `Bearer ${tokenBody.access_token}`,
+                "content-type": "application/json",
+            },
+            method: "POST",
+        });
+        text = await response.text();
+        if (!response.ok) {
+            throw new UsageError(`The runner call failed: HTTP ${response.status}\n${safe(text.slice(0, 500))}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            throw error;
+        throw new UsageError(safe(`The request failed: ${error.message}`));
+    }
+    const scrubbed = scrub(text, known);
+    if (scrubbed.problems.length > 0) {
+        throw new UsageError(`Refusing to print or record the output: ${scrubbed.problems.join("; ")}. Review it by hand.`);
+    }
+    let body;
+    try {
+        body = JSON.parse(scrubbed.text);
+    }
+    catch {
+        throw new UsageError("The runner's answer was not JSON.");
+    }
+    if (body.error)
+        throw new UsageError(`The runner refused: ${body.error}`);
+    console.log(JSON.stringify(body, null, 2));
+    let status = 0;
+    const expected = readExpect(probe.slug, config.probesDir);
+    if (expected !== undefined) {
+        if (matchesExpect(body.result, expected)) {
+            console.log("\nMatches the expected output.");
+        }
+        else {
+            status = 2;
+            console.log(`\nDRIFT: the output differs from ${probe.slug}.expect.json. The platform changed, or the expectation is wrong.`);
+        }
+    }
+    if (args.includes("--draft")) {
+        const probeFile = join(config.probesDir, `${probe.slug}.js`);
+        const page = join(config.resultsDir, `${probe.slug}.md`);
+        const shown = relative(project, page).replaceAll("\\", "/");
+        if (existsSync(page)) {
+            console.log(`\n${shown} already exists; not overwriting.`);
+        }
+        else {
+            const draft = scrub(resultsDraft({
+                date: new Date().toISOString().slice(0, 10),
+                output: body.result,
+                probe,
+                probeFile,
+                resultsDir: config.resultsDir,
+                scriptSource: read(probeFile),
+                version: body.version ?? "unknown",
+            }), known);
+            if (draft.problems.length > 0) {
+                throw new UsageError(`Refusing to write ${shown}: ${draft.problems.join("; ")}. Review it by hand.`);
+            }
+            writeFileSync(page, draft.text);
+            console.log(`\nWrote the draft ${shown}. Fill in each TODO(verify), then ask the user to review it.`);
+        }
+    }
+    return status;
+}

package/dist/sdf.js

@@ -0,0 +1,53 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileCabinetFolder } from "./netsuite.js";
+import { isRestlet, listProbes, read, tagProblems, } from "./probes.js";
+import { UsageError } from "./shared.js";
+const templates = new URL("../templates/", import.meta.url);
+const template = (name) => readFileSync(new URL(name, templates), "utf8").replace(/\r\n/g, "\n");
+const q = (value) => JSON.stringify(value);
+/** The runner source with its dependency list generated from the probe slugs. */
+export function generateRunner(probes, source) {
+    const slugs = probes.map((probe) => probe.slug);
+    const names = slugs.map((_, i) => `probe${i}`);
+    // Each list item carries its own leading comma, so the template stays valid
+    // when the formatter moves the placeholder comments around.
+    return source
+        .replace("/*PROBE_PATHS*/", slugs.map((slug) => `, ${q(`./probes/${slug}`)}`).join(""))
+        .replace("/*PROBE_NAMES*/", names.map((name) => `, ${name}`).join(""))
+        .replace("/*PROBE_ENTRIES*/", slugs
+        .map((slug, i) => `[${q(slug)}, [${names[i]}, ${JSON.stringify(probes[i]?.params ?? [])}]],`)
+        .join(" "));
+}
+/**
+ * Writes the generated runner, the probe copies and the SDF project files into
+ * the SDF folder. Only RESTlet probes go in: the runner is a RESTlet. With
+ * `deployed: false` the runner's deployment is switched off (cleanup).
+ */
+export function buildSdfProject(sdfDir, probesDir, { deployed, extraTags = [], }) {
+    const probes = listProbes(probesDir, extraTags).filter(isRestlet);
+    const bad = probes.filter((probe) => tagProblems(probe).length > 0);
+    if (bad.length > 0) {
+        throw new UsageError(`Fix the probe tags before deploying:\n${bad
+            .flatMap((p) => tagProblems(p).map((m) => `- ${p.slug}: ${m}`))
+            .join("\n")}`);
+    }
+    const src = join(sdfDir, "src");
+    const folder = join(src, "FileCabinet", "SuiteScripts", fileCabinetFolder);
+    rmSync(join(src, "FileCabinet"), { force: true, recursive: true });
+    mkdirSync(join(folder, "probes"), { recursive: true });
+    mkdirSync(join(src, "Objects"), { recursive: true });
+    writeFileSync(join(sdfDir, "package.json"), template("sdf/package.json"));
+    writeFileSync(join(sdfDir, "suitecloud.config.js"), template("sdf/suitecloud.config.js"));
+    writeFileSync(join(src, "manifest.xml"), template("sdf/manifest.xml"));
+    writeFileSync(join(src, "deploy.xml"), template("sdf/deploy.xml"));
+    writeFileSync(join(src, "Objects", "customscript_suitescript_verify_runner.xml"), template("sdf/runner.xml").replace("%%DEPLOYED%%", deployed ? "T" : "F"));
+    const slugs = probes.map((probe) => probe.slug);
+    const files = ["runner.js"];
+    writeFileSync(join(folder, "runner.js"), generateRunner(probes, template("runner.template.js")));
+    for (const slug of slugs) {
+        writeFileSync(join(folder, "probes", `${slug}.js`), read(join(probesDir, `${slug}.js`)));
+        files.push(`probes/${slug}.js`);
+    }
+    return { files, slugs };
+}

package/dist/shared.js

@@ -0,0 +1,132 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { isSandboxAccount, names } from "./doctor.js";
+import { applyEnvUpdate, planEnvUpdate } from "./envfile.js";
+/** A refusal or mistake to report to the person; the message holds no secret. */
+export class UsageError extends Error {
+}
+const valueFlags = ["--dir", "--keys-dir", "--only", "--param"];
+/** The value after a flag, when given. */
+export function flagValue(args, flag) {
+    const at = args.indexOf(flag);
+    if (at < 0)
+        return undefined;
+    const value = args[at + 1];
+    if (!value || value.startsWith("--")) {
+        throw new UsageError(`${flag} needs a value.`);
+    }
+    return value;
+}
+/** Arguments that are neither flags nor a flag's value. */
+export function positionals(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? "";
+        if (valueFlags.includes(arg))
+            i++;
+        else if (!arg.startsWith("--"))
+            out.push(arg);
+    }
+    return out;
+}
+/** The project's own SuiteCloud CLI (a peer dependency), never a global one. */
+function suitecloudEntry(project) {
+    const entry = join(project, "node_modules", "@oracle", "suitecloud-cli", "src", "suitecloud.js");
+    if (!existsSync(entry)) {
+        throw new UsageError("Install @oracle/suitecloud-cli in this project (npm install --save-dev @oracle/suitecloud-cli), and accept Oracle's license yourself.");
+    }
+    return entry;
+}
+/**
+ * Runs the project's SuiteCloud CLI from the SDF project folder. The package
+ * never sets SUITECLOUD_CLI_ACCEPT_LICENSE (ADR 0001): the child gets the
+ * parent's environment plus the passkey, nothing about the license.
+ */
+export function suitecloud(project, config, args) {
+    const env = { ...process.env, ...config.values };
+    // Hand the passkey to the CLI for this child process only.
+    if (env.SUITESCRIPT_VERIFY_PASSKEY) {
+        env.SUITECLOUD_CI_PASSKEY = env.SUITESCRIPT_VERIFY_PASSKEY;
+    }
+    if (env.SUITECLOUD_CI_PASSKEY)
+        env.SUITECLOUD_CI = "1";
+    const result = spawnSync(process.execPath, [suitecloudEntry(project), ...args], { cwd: config.sdfDir, env, stdio: "inherit" });
+    return result.status ?? 1;
+}
+/**
+ * A write to the sandbox needs a person at a terminal, on top of --approved:
+ * an agent's shell has none, so an agent cannot run it. The person types the
+ * action name to confirm.
+ */
+export async function confirmWrite(action, what) {
+    if (!process.stdin.isTTY) {
+        throw new UsageError(`${what} needs the user at a terminal. Ask the user to run this same command, with --approved, in their own terminal.`);
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question(`${what}. Type ${action} to continue: `);
+    rl.close();
+    if (answer.trim() !== action) {
+        throw new UsageError("Not confirmed. Nothing was changed.");
+    }
+}
+/** True when the person (or --overwrite) allows replacing something that exists. */
+export async function allowReplace(args, description) {
+    if (args.includes("--overwrite"))
+        return true;
+    if (args.includes("--keep") || !process.stdin.isTTY)
+        return false;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await rl.question(`${description} already exists. Overwrite it? [y/N] `);
+    rl.close();
+    return /^y(es)?$/i.test(answer.trim());
+}
+/**
+ * Saves values to `.env.local`. A name that already holds a different value is
+ * a conflict: ask the person (overwrite or keep). Without a terminal, or with
+ * --keep, keep it and say so; --overwrite replaces it. Values are never printed.
+ */
+export async function saveEnv(config, args, entries) {
+    const file = join(config.root, ".env.local");
+    const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+    const plan = planEnvUpdate(text, entries);
+    const overwrite = new Set();
+    const kept = [];
+    for (const name of plan.conflicts) {
+        if (await allowReplace(args, `${name} in .env.local`))
+            overwrite.add(name);
+        else
+            kept.push(name);
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, applyEnvUpdate(text, entries, overwrite));
+    for (const name of [...plan.fresh, ...overwrite]) {
+        console.log(`Saved ${name} to .env.local.`);
+    }
+    for (const name of plan.same)
+        console.log(`${name} already has this value.`);
+    for (const name of kept) {
+        console.log(`Kept the existing ${name}. To replace it, ask the user, then rerun with --overwrite.`);
+    }
+}
+/** The runner credentials, or a refusal: every command that reaches the sandbox needs a sandbox account. */
+export function requireSandbox(config) {
+    const v = config.values;
+    const missing = Object.values(names).filter((name) => name !== names.passkey && !v[name]);
+    if (missing.length > 0) {
+        throw new UsageError(`Missing ${missing.join(", ")}. Run suitescript-verify doctor.`);
+    }
+    const account = v[names.account] ?? "";
+    if (!isSandboxAccount(account)) {
+        throw new UsageError(`${names.account} is not a sandbox account id (expected digits_SBn). Verification runs in a sandbox only.`);
+    }
+    return {
+        account,
+        certificateId: v[names.certificateId] ?? "",
+        clientId: v[names.clientId] ?? "",
+        privateKeyPath: v[names.privateKeyPath] ?? "",
+        sdfCertificateId: v[names.sdfCertificateId] ?? "",
+        sdfPrivateKeyPath: v[names.sdfPrivateKeyPath] ?? "",
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "suitescript-verify",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Run probes in a NetSuite sandbox to verify what SuiteScript modules do, with guardrails for agents.",
   "keywords": [
     "suitescript",
@@ -23,6 +23,7 @@
   },
   "files": [
     "dist",
+    "templates",
     "README.md",
     "LICENSE"
   ],

package/templates/runner.template.js

@@ -0,0 +1,64 @@
+/**
+ * The verification runner: a RESTlet that runs one probe by name and returns
+ * what it found. It never runs code from the request: the probes below are
+ * the only code it can run, and they are generated from the probes folder
+ * into this file's dependency list by `suitescript-verify deploy`.
+ *
+ * It refuses to run unless the account is a sandbox.
+ *
+ * @NApiVersion 2.1
+ * @NScriptType Restlet
+ */
+define(["N/runtime" /*PROBE_PATHS*/], (runtime /*PROBE_NAMES*/) => {
+  const probes = new Map([
+    /*PROBE_ENTRIES*/
+  ]);
+
+  return {
+    post(body) {
+      if (runtime.envType !== runtime.EnvType.SANDBOX) {
+        return { error: "refused: the runner only runs in a sandbox" };
+      }
+      const name = body && typeof body.probe === "string" ? body.probe : "";
+      const entry = probes.get(name);
+      if (!entry) {
+        return { error: "unknown probe", known: [...probes.keys()] };
+      }
+      const [probe, declared] = entry;
+      // Parameters are data: only declared names, only strings that match the
+      // declared pattern in full, and never evaluated.
+      const sent = body.params === undefined ? {} : body.params;
+      if (!sent || typeof sent !== "object" || Array.isArray(sent)) {
+        return { error: "invalid params: expected an object" };
+      }
+      const params = {};
+      for (const key of Object.keys(sent)) {
+        if (!declared.some((param) => param.name === key)) {
+          return { error: `undeclared param: ${key}` };
+        }
+      }
+      for (const { name: key, pattern } of declared) {
+        const value = sent[key];
+        if (typeof value !== "string") {
+          return { error: `missing or non-string param: ${key}` };
+        }
+        if (!new RegExp(`^(?:${pattern})$`, "u").test(value)) {
+          return { error: `param does not match its pattern: ${key}` };
+        }
+        params[key] = value;
+      }
+      let result;
+      try {
+        result = probe.run(params);
+      } catch (e) {
+        result = `THROWS: ${e.name}: ${e.message}`;
+      }
+      return {
+        probe: name,
+        result,
+        scriptType: "RESTlet",
+        version: String(runtime.version),
+      };
+    },
+  };
+});

package/templates/sdf/deploy.xml

@@ -0,0 +1,8 @@
+<deploy>
+  <files>
+    <path>~/FileCabinet/SuiteScripts/suitescript-verify/*</path>
+  </files>
+  <objects>
+    <path>~/Objects/*</path>
+  </objects>
+</deploy>

package/templates/sdf/manifest.xml

@@ -0,0 +1,12 @@
+<manifest projecttype="ACCOUNTCUSTOMIZATION">
+  <projectname>suitescript-verify</projectname>
+  <frameworkversion>1.0</frameworkversion>
+  <dependencies>
+    <features>
+      <feature required="true">SERVERSIDESCRIPTING</feature>
+    </features>
+    <objects>
+      <object>customrole_suitescript_verify</object>
+    </objects>
+  </dependencies>
+</manifest>

package/templates/sdf/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "suitescript-verify-sdf",
+  "private": true,
+  "type": "commonjs"
+}

package/templates/sdf/runner.xml

@@ -0,0 +1,17 @@
+<restlet scriptid="customscript_suitescript_verify_runner">
+  <description>Runs one version-controlled probe by name in a sandbox. Source: the project's verification folder, through suitescript-verify.</description>
+  <isinactive>F</isinactive>
+  <name>suitescript-verify runner</name>
+  <notifyowner>F</notifyowner>
+  <scriptfile>[/SuiteScripts/suitescript-verify/runner.js]</scriptfile>
+  <scriptdeployments>
+    <scriptdeployment scriptid="customdeploy_suitescript_verify_runner">
+      <allroles>F</allroles>
+      <audslctrole>[customrole_suitescript_verify]</audslctrole>
+      <isdeployed>%%DEPLOYED%%</isdeployed>
+      <loglevel>DEBUG</loglevel>
+      <status>RELEASED</status>
+      <title>suitescript-verify runner</title>
+    </scriptdeployment>
+  </scriptdeployments>
+</restlet>

package/templates/sdf/suitecloud.config.js

@@ -0,0 +1,4 @@
+module.exports = {
+  commands: {},
+  defaultProjectFolder: "src",
+};