suitescript-verify 0.0.0-stage → 0.1.0

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/init.js

@@ -0,0 +1,35 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+/**
+ * Scaffolds the folders and a committed `.env` of layout keys, then returns
+ * the to-do list for the person. Creates no credential and installs nothing.
+ */
+export function init(project, config) {
+    const rel = (path) => relative(project, path).replaceAll("\\", "/");
+    const dirs = [config.probesDir, config.resultsDir, config.sdfDir];
+    for (const dir of dirs)
+        mkdirSync(dir, { recursive: true });
+    const envFile = join(config.root, ".env");
+    const created = !existsSync(envFile);
+    if (created) {
+        mkdirSync(dirname(envFile), { recursive: true });
+        writeFileSync(envFile, [
+            "# Layout only: this file is committed. Credentials go in .env.local, which is gitignored.",
+            `SUITESCRIPT_VERIFY_PROBES_DIR=${rel(config.probesDir)}`,
+            `SUITESCRIPT_VERIFY_RESULTS_DIR=${rel(config.resultsDir)}`,
+            `SUITESCRIPT_VERIFY_SDF_DIR=${rel(config.sdfDir)}`,
+            "",
+        ].join("\n"));
+    }
+    const local = rel(join(config.root, ".env.local"));
+    return [
+        `${created ? "Created" : "Kept"} ${rel(envFile)} and the folders ${dirs.map(rel).join(", ")}. No credentials were created.`,
+        "",
+        "To do (each step is yours, the maintainer's):",
+        "1. Install the SuiteCloud CLI: npm install --save-dev @oracle/suitecloud-cli. Read Oracle's license and accept it yourself; this package never does.",
+        `2. Add ${local} to .gitignore before saving any value: it holds credentials.`,
+        "3. In a sandbox, create the integration record, the role and the certificate mappings, and generate the private keys outside the repository.",
+        `4. Save the account, client id, certificate ids, key paths and a passkey in ${local} (see docs/verification/README.md).`,
+        "5. Run suitescript-verify doctor until every step passes.",
+    ].join("\n");
+}

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] ?? "",
+    };
+}