suitescript-verify 0.0.0-stage → 0.0.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,35 @@
-# 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.
+
+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
+```
+
+`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`.
+
+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/cli.js

@@ -0,0 +1,128 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { loadConfig } from "./config.js";
+import { formatChecks, runChecks } from "./doctor.js";
+import { init } from "./init.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
+  help                                 Show this help
+
+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;
+}
+/** 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);
+    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.");
+    }
+    return suitecloud(project, config.sdfDir, ["project:deploy", ...(approved ? [] : ["--dryrun"])], config.values);
+}
+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 === "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,120 @@
+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",
+];
+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 (!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.`,
+            });
+        }
+        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 {
+        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";
+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+_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");
+}

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/package.json

@@ -1,6 +1,76 @@
 {
   "name": "suitescript-verify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "Run probes in a NetSuite sandbox to verify what SuiteScript modules do, with guardrails for agents.",
+  "keywords": [
+    "suitescript",
+    "netsuite",
+    "verification",
+    "probe",
+    "suitecloud"
+  ],
+  "homepage": "https://github.com/nemchik/suitescript-verify#readme",
+  "bugs": "https://github.com/nemchik/suitescript-verify/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nemchik/suitescript-verify.git"
+  },
+  "license": "MIT",
+  "author": "Eric Nemchik",
+  "type": "module",
+  "bin": {
+    "suitescript-verify": "./dist/bin/suitescript-verify.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prebuild": "node -e \"require(\\\"node:fs\\\").rmSync(\\\"dist\\\",{recursive:true,force:true})\"",
+    "build": "tsc -p tsconfig.build.json",
+    "check": "biome check",
+    "preformat": "npm run typecheck",
+    "format": "biome check --write",
+    "lint": "biome lint",
+    "prepack": "npm run build",
+    "skills": "node scripts/skills.ts",
+    "skills:add": "node scripts/skills.ts add --skill \"*\" --agent universal --agent claude-code --yes",
+    "skills:check": "node scripts/skills.ts check",
+    "skills:install": "node scripts/skills.ts experimental_install && node scripts/link-claude-skills.ts",
+    "skills:list": "node scripts/skills.ts list",
+    "skills:update": "node scripts/skills.ts update --project --yes && node scripts/link-claude-skills.ts",
+    "pretest": "npm run build",
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.6.6",
+    "@types/node": "24.19.2",
+    "git-pull-run": "2.1.0",
+    "lefthook": "2.2.2",
+    "skills": "1.7.6",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "@oracle/suitecloud-cli": "^4.1.1"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": "24.22.3",
+      "onFail": "error"
+    },
+    "packageManager": {
+      "name": "npm",
+      "version": "12.2.2",
+      "onFail": "warn"
+    }
+  },
+  "allowScripts": {
+    "lefthook": true
+  }
+}