suitescript-verify 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Nemchik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,55 @@
-# Temporary Holding Version
+# suitescript-verify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run probes in a NetSuite **sandbox** to verify what SuiteScript modules do, from a CLI that is safe to hand to an agent: sandbox only, a person approves every write at a terminal, and output is scrubbed of identifiers.
+
+> This package never accepts Oracle's SuiteCloud license. Install `@oracle/suitecloud-cli` in your project and accept the license yourself.
+
+```sh
+npm install --save-dev suitescript-verify @oracle/suitecloud-cli
+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.
+
+`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).
+
+## Development
+
+You need the Node.js and npm versions in `package.json` `devEngines`.
+
+```sh
+npm install
+npm run skills:install   # optional: restores the agent skills for Claude Code
+npm test                 # builds, then runs the CLI tests against a fake SuiteCloud CLI
+npm run format           # type-checks, then applies Biome's fixes
+```
+
+Git hooks (lefthook) run Biome on staged files before each commit.
+
+## License
+
+MIT

package/dist/bin/suitescript-verify.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "../cli.js";
+process.exitCode = await main(process.argv.slice(2));

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

@@ -0,0 +1,196 @@
+import { randomBytes } from "node:crypto";
+import { certificate } from "./certificate.js";
+import { loadConfig } from "./config.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:
+  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.`;
+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));
+    if (refuse && config.problems.length > 0) {
+        throw new UsageError(`Refusing to run:\n${config.problems.map((p) => `- ${p.message}`).join("\n")}`);
+    }
+    return config;
+}
+/** Loads the configuration for `doctor` and `init`, which report problems instead of refusing. */
+function reporting(args) {
+    const config = configure(args, false);
+    if (config.problems.length > 0) {
+        console.log("Configuration problems:");
+        for (const problem of config.problems)
+            console.log(`- ${problem.message}`);
+        console.log("");
+    }
+    return config;
+}
+function doctor(args) {
+    const config = reporting(args);
+    const checks = runChecks(process.cwd(), config);
+    console.log(formatChecks(checks));
+    return config.problems.length === 0 && checks.every((c) => c.ok) ? 0 : 1;
+}
+function initCommand(args) {
+    console.log(init(process.cwd(), reporting(args)));
+    return 0;
+}
+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("\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).");
+    }
+    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;
+    try {
+        if (command === undefined || command === "help" || command === "--help") {
+            console.log(USAGE);
+            return 0;
+        }
+        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")
+            return initCommand(rest);
+        throw new UsageError(`Unknown command "${command}".\n\n${USAGE}`);
+    }
+    catch (error) {
+        if (error instanceof UsageError) {
+            console.error(error.message);
+            return 1;
+        }
+        throw error;
+    }
+}

package/dist/config.js

@@ -0,0 +1,141 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+const prefix = "SUITESCRIPT_VERIFY_";
+/** Layout keys: the only ones the committed `.env` may hold. Each is a path in the project. */
+export const layoutKeys = [
+    "SUITESCRIPT_VERIFY_PROBES_DIR",
+    "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];
+    if (value.length >= 2 &&
+        (quote === '"' || quote === "'") &&
+        value.endsWith(quote)) {
+        return value.slice(1, -1);
+    }
+    return value;
+};
+/** Reads `NAME=value` lines; comments and other lines are ignored. */
+export function parseEnv(text) {
+    const values = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/.exec(line);
+        if (match)
+            values.set(match[1] ?? "", unquote(match[2] ?? ""));
+    }
+    return values;
+}
+function readEnvFile(path) {
+    return existsSync(path)
+        ? parseEnv(readFileSync(path, "utf8"))
+        : new Map();
+}
+const insideProject = (project, path) => {
+    const rel = relative(project, resolve(project, path));
+    return !isAbsolute(rel) && rel.split(/[\\/]/)[0] !== "..";
+};
+/** A value a person would not write as a folder: a PEM block, a JWT or a long token. */
+const looksSecret = (value) => /-----BEGIN /.test(value) ||
+    /^eyJ[\w-]+\.[\w-]+\.[\w-]+$/.test(value) ||
+    /^[A-Za-z0-9+_=-]{32,}$/.test(value);
+/** Checks the committed `.env` against the allowlist. Messages name the key, never the value. */
+function checkCommitted(project, committed, file) {
+    const problems = [];
+    for (const [key, value] of committed) {
+        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, extraTagsKey].join(", ")}); put anything else in .env.local or the process environment.`,
+            });
+        }
+        else if (!insideProject(project, value)) {
+            problems.push({
+                message: `${key} in ${file} points outside the project. Use a path inside the project.`,
+            });
+        }
+        else if (looksSecret(value)) {
+            problems.push({
+                message: `${key} in ${file} looks like a secret, not a path. The committed file is public: move a secret to .env.local.`,
+            });
+        }
+    }
+    return problems;
+}
+/** `.env.local` holds credentials: it must be gitignored and never tracked. */
+function checkLocalIgnored(project, localFile) {
+    const git = (args) => spawnSync("git", args, { cwd: project, encoding: "utf8" });
+    const rel = relative(project, localFile).replaceAll("\\", "/");
+    if (git(["rev-parse", "--is-inside-work-tree"]).status !== 0)
+        return [];
+    const problems = [];
+    if (git(["ls-files", "--error-unmatch", "--", rel]).status === 0) {
+        problems.push({
+            message: `${rel} is tracked by git, so its credentials are in the repository. Run git rm --cached ${rel} and rotate what it held.`,
+        });
+    }
+    if (git(["check-ignore", "-q", "--", rel]).status !== 0) {
+        problems.push({
+            message: `${rel} is not gitignored. Add it to .gitignore before saving any value: it holds credentials.`,
+        });
+    }
+    return problems;
+}
+/**
+ * Layers defaults, the committed `.env`, the gitignored `.env.local` and the
+ * process environment (later wins). The root of the env files is `dir`
+ * (default `verification`), relative to the project.
+ */
+export function loadConfig(project, dir, processEnv = process.env) {
+    const root = resolve(project, dir ?? "verification");
+    const envFile = join(root, ".env");
+    const localFile = join(root, ".env.local");
+    const committed = readEnvFile(envFile);
+    const values = {};
+    const layers = [
+        committed,
+        readEnvFile(localFile),
+        Object.entries(processEnv),
+    ];
+    for (const layer of layers) {
+        for (const [key, value] of layer) {
+            if (key.startsWith(prefix) && value !== undefined)
+                values[key] = value;
+        }
+    }
+    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),
+            ...checkLocalIgnored(project, localFile),
+        ],
+        resultsDir: path("SUITESCRIPT_VERIFY_RESULTS_DIR", "docs/verification/results"),
+        root,
+        sdfDir: path("SUITESCRIPT_VERIFY_SDF_DIR", join(root, "sdf")),
+        values,
+    };
+}

package/dist/doctor.js

@@ -0,0 +1,97 @@
+import { createPrivateKey } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+export const names = {
+    account: "SUITESCRIPT_VERIFY_ACCOUNT",
+    certificateId: "SUITESCRIPT_VERIFY_CERTIFICATE_ID",
+    clientId: "SUITESCRIPT_VERIFY_CLIENT_ID",
+    passkey: "SUITESCRIPT_VERIFY_PASSKEY",
+    privateKeyPath: "SUITESCRIPT_VERIFY_PRIVATE_KEY_PATH",
+    sdfCertificateId: "SUITESCRIPT_VERIFY_SDF_CERTIFICATE_ID",
+    sdfPrivateKeyPath: "SUITESCRIPT_VERIFY_SDF_PRIVATE_KEY_PATH",
+};
+/** `ec:<curve>`, `rsa:<bits>` or `other`, from a private key file. Never the key itself. */
+function keyType(path) {
+    try {
+        const key = createPrivateKey(readFileSync(path));
+        const details = key.asymmetricKeyDetails;
+        if (key.asymmetricKeyType === "ec")
+            return `ec:${details?.namedCurve}`;
+        if (key.asymmetricKeyType === "rsa")
+            return `rsa:${details?.modulusLength}`;
+    }
+    catch {
+        // Unreadable or not a private key.
+    }
+    return "other";
+}
+/** A sandbox account id looks like `1234567_SB1`. Verification never runs in production. */
+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 = [];
+    const add = (name, ok, owner, next) => checks.push({ name, next, ok, owner });
+    const v = config.values;
+    add("SuiteCloud CLI (@oracle/suitecloud-cli) is installed in the project", existsSync(join(project, "node_modules", "@oracle", "suitecloud-cli", "src", "suitecloud.js")), "maintainer", "Run npm install --save-dev @oracle/suitecloud-cli, read Oracle's license and accept it yourself. This package never accepts it.");
+    const missing = [
+        names.account,
+        names.clientId,
+        names.certificateId,
+        names.sdfCertificateId,
+    ].filter((name) => !v[name]);
+    add("Account, client id and both certificate ids are set", missing.length === 0, "maintainer", `Missing: ${missing.join(", ")}. Create the integration record and mapping in your sandbox, then save the values in .env.local (never the committed .env).`);
+    add("The account is a sandbox", isSandboxAccount(v[names.account] ?? ""), "maintainer", `${names.account} must look like digits_SBn. Verification never runs in production.`);
+    for (const [label, key, expected, accepts] of [
+        [
+            "runner",
+            names.privateKeyPath,
+            "an EC P-256 key",
+            (t) => t === "ec:prime256v1",
+        ],
+        [
+            "SDF",
+            names.sdfPrivateKeyPath,
+            "an RSA key of 3072 or 4096 bits",
+            (t) => t === "rsa:3072" || t === "rsa:4096",
+        ],
+    ]) {
+        const path = v[key] ?? "";
+        const exists = path !== "" && existsSync(path);
+        add(`The ${label} private key exists (${key})`, exists, "maintainer", `Generate the key pair outside the repository and set ${key} in .env.local.`);
+        if (exists) {
+            add(`The ${label} private key is ${expected}`, accepts(keyType(path)), "maintainer", "Generate a key of that type and upload its new public certificate in a new mapping.");
+        }
+    }
+    const passkey = v[names.passkey] ?? env.SUITECLOUD_CI_PASSKEY ?? "";
+    add(`${names.passkey} (or SUITECLOUD_CI_PASSKEY) is set, 32 to 100 letters and digits`, /^[A-Za-z0-9]{32,100}$/.test(passkey), "maintainer", `Generate a random passkey and save it as ${names.passkey} in .env.local. Keep a copy somewhere safe: it encrypts the stored credentials. Never set it user-wide.`);
+    add("SUITECLOUD_FALLBACK_PASSKEY is not set", !env.SUITECLOUD_FALLBACK_PASSKEY, "maintainer", "Unset it: the CLI refuses to run with both passkeys.");
+    const projectJson = join(config.sdfDir, "project.json");
+    let authId = "";
+    if (existsSync(projectJson)) {
+        try {
+            authId =
+                JSON.parse(readFileSync(projectJson, "utf8")).defaultAuthId ?? "";
+        }
+        catch {
+            // A malformed project.json fails the step.
+        }
+    }
+    const absent = [config.probesDir, config.resultsDir, config.sdfDir].filter((dir) => !existsSync(dir));
+    add("Project files: the probe, results and SDF folders exist and the SDF project has a default auth id", absent.length === 0 && authId !== "", absent.length > 0 ? "agent" : "maintainer", absent.length > 0
+        ? "Run suitescript-verify init to create the missing folders."
+        : "Run account:setup:ci from the SDF folder once the steps above pass, so project.json gets a default auth id.");
+    return checks;
+}
+export function formatChecks(checks) {
+    const lines = checks.map((c) => c.ok
+        ? `ok   ${c.name}`
+        : `FAIL ${c.name}\n     ${c.owner === "maintainer" ? "Maintainer's own step" : "Agent can do this"}: ${c.next ?? ""}`);
+    const failed = checks.filter((c) => !c.ok);
+    if (failed.length === 0)
+        lines.push("\nAll checks passed.");
+    else {
+        const own = failed.filter((c) => c.owner === "maintainer").length;
+        lines.push(`\n${failed.length} check(s) failed.${own > 0 ? ` ${own} are the Maintainer's own: relay each next step to the maintainer and wait. Never accept the license, create credentials or touch an account for them.` : ""}`);
+    }
+    return lines.join("\n");
+}