suitescript-verify 0.3.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +240 -9
- package/dist/cli.js +15 -11
- package/dist/config.js +38 -16
- package/dist/doctor.js +38 -0
- package/dist/init.js +4 -1
- package/dist/netsuite.js +17 -4
- package/dist/run.js +1 -1
- package/dist/sdf.js +23 -9
- package/package.json +2 -2
- package/templates/sdf/deploy.xml +1 -1
- package/templates/sdf/runner.xml +5 -5
package/README.md
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
# suitescript-verify
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/suitescript-verify)
|
|
4
|
+
[](https://github.com/nemchik/suitescript-verify/actions/workflows/ci.yml)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
3
7
|
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.
|
|
4
8
|
|
|
5
9
|
> This package never accepts Oracle's SuiteCloud license. Install `@oracle/suitecloud-cli` in your project and accept the license yourself.
|
|
@@ -9,19 +13,151 @@ npm install --save-dev suitescript-verify @oracle/suitecloud-cli
|
|
|
9
13
|
npx suitescript-verify help
|
|
10
14
|
```
|
|
11
15
|
|
|
12
|
-
|
|
16
|
+
This README is the whole guide and ships with each published version. Read the copy installed with the package, which matches the version you use: `suitescript-verify init` prints its path (it is in `node_modules/suitescript-verify/` under npm and pnpm).
|
|
17
|
+
|
|
18
|
+
## Contents
|
|
19
|
+
|
|
20
|
+
- [Verification method](#verification-method): when to verify, how, and how to record it
|
|
21
|
+
- [Setup](#setup): `init`, credentials, the role and `doctor`
|
|
22
|
+
- [Deploy](#deploy): put the runner in the sandbox
|
|
23
|
+
- [Probes](#probes): write and run them
|
|
24
|
+
- [Settings](#settings): every `SUITESCRIPT_VERIFY_` key
|
|
25
|
+
- [Troubleshooting](#troubleshooting): by symptom
|
|
26
|
+
- [Adding a lesson](#adding-a-lesson)
|
|
27
|
+
- [Development](#development)
|
|
28
|
+
|
|
29
|
+
## Verification method
|
|
30
|
+
|
|
31
|
+
Oracle's skills, type definitions and documentation disagree with each other and sometimes with the platform. A verification is a test run in a NetSuite account that shows what the platform actually does. Where a source's claim about platform behavior and the verified behavior differ, the verified behavior wins.
|
|
32
|
+
|
|
33
|
+
### When to verify
|
|
34
|
+
|
|
35
|
+
Verify, or mark the claim **unverified**, whenever you depend on what the platform accepts, rejects or returns, research how a module, method or script type behaves, or find a source that contradicts itself or another. An unverified claim stays marked unverified until a results page settles it. Do not mark a claim verified from a paraphrase of documentation: verified means a test ran.
|
|
36
|
+
|
|
37
|
+
### For agents
|
|
38
|
+
|
|
39
|
+
- If you can run the test yourself, do: a **probe** runs in a sandbox through the runner. Run `suitescript-verify doctor` first.
|
|
40
|
+
- Setup is mostly the person's (browser login, role, certificate). When a check fails, relay its next step and wait.
|
|
41
|
+
- Never run anything in production, never create credentials, and never run a real deploy or cleanup yourself: both need a person at a terminal.
|
|
42
|
+
- Prompt the person to run a snippet by hand (the methods below) only when a probe cannot run: setup cannot pass, the claim depends on a script type the runner does not cover (anything but a RESTlet), or the probe would write to the account. Give the exact snippet and say where to run it.
|
|
43
|
+
- Before you write a batch of probes, read [Probes](#probes) and [Troubleshooting](#troubleshooting): each probe change costs a deploy, and one bad probe can take the whole runner down.
|
|
44
|
+
|
|
45
|
+
### Methods
|
|
46
|
+
|
|
47
|
+
Record the method, the NetSuite version (for example `2026.2`; Help > About), and whether the account is a sandbox or production.
|
|
48
|
+
|
|
49
|
+
| Method | Use it for | Limits |
|
|
50
|
+
| ------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
51
|
+
| The runner (a deployed RESTlet) | RESTlet behavior | Sandbox only; RESTlet only |
|
|
52
|
+
| Browser console | Client scripts | Runs in the browser's engine, so it says nothing about server-only behavior |
|
|
53
|
+
| Script debugger | Quick server checks (Customization > Scripting > Script Debugger) | Behaves differently from a deployed script in places; confirm a surprising result with a deployed script |
|
|
54
|
+
| A deployed script | The authoritative server result | Upload a script, create the Script record and a Deployment (status Testing, audience yourself) and call it; other script types can behave differently from a RESTlet, so test the type you care about |
|
|
55
|
+
|
|
56
|
+
In the browser console, open any record page, open the developer tools, load modules with `require` and print the results:
|
|
57
|
+
|
|
58
|
+
```js
|
|
59
|
+
require(["N/util"], function (u) {
|
|
60
|
+
console.log(JSON.stringify({ isArray: u.isArray([]) }));
|
|
61
|
+
});
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**Note:** do not put the account number in a verification, nor an account URL, user, token or the internal id of a real record. They identify a company's account, they are not needed to reproduce a result, and they are a security risk in a public repository. Replace ids with placeholders.
|
|
65
|
+
|
|
66
|
+
### Documenting a verification
|
|
67
|
+
|
|
68
|
+
Write one page per verification (lowercase, hyphens, for example `util-each.md`) in your project's results folder. Every section is required: a verification without its test, results and decision is not a verification. `run <probe> --draft` writes the page with the test, NetSuite version and results filled in.
|
|
69
|
+
|
|
70
|
+
```markdown
|
|
71
|
+
# <What was verified>
|
|
72
|
+
|
|
73
|
+
- **NetSuite version:** 2026.2
|
|
74
|
+
- **Account type:** sandbox
|
|
75
|
+
- **Date:** YYYY-MM-DD
|
|
76
|
+
- **Method:** browser console | script debugger | deployed <script type> | deployed RESTlet (the runner)
|
|
77
|
+
- **Probe:** the path to the probe, when there is one
|
|
78
|
+
|
|
79
|
+
## Test
|
|
80
|
+
|
|
81
|
+
The script, verbatim, so anyone can run it again.
|
|
82
|
+
|
|
83
|
+
## Results
|
|
84
|
+
|
|
85
|
+
The raw output, including error messages.
|
|
86
|
+
|
|
87
|
+
## Explanation
|
|
88
|
+
|
|
89
|
+
What the results mean, and how they relate to what each source claims.
|
|
90
|
+
|
|
91
|
+
## Decision
|
|
92
|
+
|
|
93
|
+
What was decided because of the results.
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Setup
|
|
97
|
+
|
|
98
|
+
Every step that creates a credential or accepts a license is the person's. `init` creates none.
|
|
99
|
+
|
|
100
|
+
1. **Scaffold.** `suitescript-verify init` creates `verification/probes`, `verification/sdf`, your results folder and a committed `verification/.env` of layout keys, then prints a to-do list. `--dir <path>` moves `verification/`.
|
|
101
|
+
- The package imposes no layout for results. Where results pages live is your choice, set as `SUITESCRIPT_VERIFY_RESULTS_DIR` in the committed `.env` (a path inside the project).
|
|
102
|
+
- `init` will not pick it for you: at a terminal it asks (suggesting `docs/verification/results`), and without one it needs `--results-dir <path>`, for example `init --results-dir docs/verification/results`.
|
|
103
|
+
- A project that already sets the key is not asked again, and a command that needs the folder without the key stops and names it.
|
|
104
|
+
2. **Install the SuiteCloud CLI** (`@oracle/suitecloud-cli`) in your project and accept Oracle's license yourself. On a desktop machine its postinstall opens the license. A headless machine needs the maintainer to accept it first, or an install with `--ignore-scripts` (see [Troubleshooting](#the-suitecloud-cli-postinstall-exits-3)).
|
|
105
|
+
3. **Gitignore `verification/.env.local`** before saving any value: it holds credentials.
|
|
106
|
+
4. **Create the certificate pairs.** `suitescript-verify certificate` generates both key pairs outside the project with `openssl` (`--keys-dir`, default `~/.suitescript-verify`; `--only runner|sdf`; `--overwrite` or `--keep`).
|
|
107
|
+
|
|
108
|
+
| Pair | Key type | Used for |
|
|
109
|
+
| ------ | ------------------------------------ | -------------------------------------------------------- |
|
|
110
|
+
| Runner | EC P-256, signed ES256 | The token for calls to the runner |
|
|
111
|
+
| SDF | RSA-4096 with an RSA-PSS certificate | Oracle's SDK login (PS256), which only parses an RSA key |
|
|
112
|
+
|
|
113
|
+
Oracle allows one certificate per integration, role and entity, so the two pairs cannot be shared, and an EC key fails the SDF login (see [Troubleshooting](#setup-ci-fails-with-an-error-with-the-private-key)).
|
|
114
|
+
5. **In the sandbox, create the integration record, the role and the certificate mappings.**
|
|
115
|
+
- The integration needs more than the machine-to-machine grant: also enable the token-based authentication flags and the RESTlets and REST Web Services scopes (see [Troubleshooting](#every-call-fails-with-401-invalid_login_attempt)).
|
|
116
|
+
- The runner is limited to a role with the id `customrole_suitescript_verify`, which you create. Use your own id by setting `SUITESCRIPT_VERIFY_ROLE_ID`; do not rely on a fixed id, since a custom role's id may be read-only after saving. The platform rejects a role id over 40 characters, `customrole_` included, so the id after the prefix is at most 29 characters; the package refuses a longer one before it reaches the sandbox.
|
|
117
|
+
- Keep the role minimal (see [Probes](#probes)).
|
|
118
|
+
6. **Save the settings.** `suitescript-verify passkey` generates the SuiteCloud passkey into `verification/.env.local`. `suitescript-verify env set NAME=value` saves any other key there (values are never printed; a different existing value is kept unless `--overwrite`). See [Settings](#settings) for the names.
|
|
119
|
+
7. **Run `suitescript-verify doctor`** until every step passes. It checks the SuiteCloud CLI, Java 17 or 21, the SuiteCloud SDK jar and login, account, sandbox, certificates, passkey and project files, says which failing steps are the maintainer's own, and exits 1 while any fails.
|
|
120
|
+
8. **`suitescript-verify setup-ci`** (for a pipeline) registers the SDF credentials (auth id `suitescript-verify`) with your project's SuiteCloud CLI, passing the passkey through the environment, never an argument. On success it prints the `SUITESCRIPT_VERIFY_` names the pipeline must supply as its own secrets, never a value. It writes no file, no credential variable and no license variable. Accepting Oracle's license in the pipeline is yours.
|
|
121
|
+
|
|
122
|
+
**Note:** projects on one machine that register the same SDF auth id (this package always uses `suitescript-verify`) share one stored credential entry. That is harmless while their certificate and passkey values match; when they differ, the later `setup-ci` replaces the earlier entry.
|
|
123
|
+
|
|
124
|
+
**Note:** never put `SUITECLOUD_CI_PASSKEY` in your user-wide environment. It stops browser login in your other SuiteCloud projects. Keep the passkey in `.env.local`, where the package hands it to the CLI for its own child process only.
|
|
125
|
+
|
|
126
|
+
Every command that reaches the sandbox refuses an account that is not a sandbox (`digits_SBn`).
|
|
127
|
+
|
|
128
|
+
### Keeping the tooling in a subfolder
|
|
129
|
+
|
|
130
|
+
A project that publishes its own package from the repository root may keep the tooling in a subfolder that is an npm project of its own, with its own `package.json` and `node_modules` holding `suitescript-verify` and `@oracle/suitecloud-cli`. The package treats the folder it runs in as the project, so run it from the subfolder and pass `--dir .`, which makes the subfolder itself the verification folder (its `.env`, `.env.local`, `probes` and `sdf`):
|
|
131
|
+
|
|
132
|
+
```json
|
|
133
|
+
{
|
|
134
|
+
"scripts": {
|
|
135
|
+
"verify:doctor": "suitescript-verify doctor --dir .",
|
|
136
|
+
"verify:run": "suitescript-verify run --dir ."
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
A script at the repository root then calls it with `npm --prefix <subfolder> run verify:doctor --`. Give `init`, `deploy`, `cleanup` and the other commands the same `--dir .`. The subfolder's `.env.local` is checked against the repository's `.gitignore`.
|
|
13
142
|
|
|
14
|
-
|
|
143
|
+
## Deploy
|
|
15
144
|
|
|
16
|
-
|
|
145
|
+
```sh
|
|
146
|
+
suitescript-verify deploy # generate, then dry-run
|
|
147
|
+
suitescript-verify deploy --approved # the real deploy: a person at a terminal types DEPLOY
|
|
148
|
+
suitescript-verify cleanup --approved # turns the runner's deployment off: the person types CLEANUP
|
|
149
|
+
```
|
|
17
150
|
|
|
18
|
-
`deploy` generates the runner and an SDF project into `verification/sdf` (the generated `src/` there is yours to gitignore) from the RESTlet probes in `verification/probes`, then dry-runs it through your project's SuiteCloud CLI.
|
|
151
|
+
`deploy` generates the runner and an SDF project into `verification/sdf` (the generated `src/` there is yours to gitignore) from the RESTlet probes in `verification/probes`, then dry-runs it through your project's SuiteCloud CLI. `cleanup` does the same with the deployment switched off, and without `--approved` it is a dry run. The runner's script id is `customscript_suitescript_verify_runner` and its deployment id `customdeploy_suitescript_verify_runner`; both come from the runner id (`SUITESCRIPT_VERIFY_RUNNER_ID`, default `suitescript_verify`).
|
|
19
152
|
|
|
20
|
-
|
|
153
|
+
- **Projects that share a sandbox need their own runner id.** A deploy replaces the runner's probe list, so two projects with the same runner id overwrite each other: whichever deployed last decides which probes exist, and the other's answer `unknown probe` until it deploys again. Set a different `SUITESCRIPT_VERIFY_RUNNER_ID` in each project's committed `.env` (for example `my_project`). The runner, its deployment and its File Cabinet folder are named from it (`customscript_my_project_runner`, `my-project`), while the projects can still share one role and token mapping. The id is at most 20 characters because the platform rejects a script or deployment id over 40 characters, prefix included (`The script ID must not exceed 40 characters.`): `customscript_` and `customdeploy_` take 13 and `_runner` takes 7. Changing a project's id leaves its old runner deployed in the sandbox, because the SuiteCloud CLI cannot delete a script. The next `deploy` or `cleanup` removes the old runner from the generated SDF folder (so it is not deployed again) and warns with the old id; to turn the old runner off, run `cleanup --approved` once with `SUITESCRIPT_VERIFY_RUNNER_ID` set to the old id, then switch back. The warning only sees runners generated in this folder.
|
|
154
|
+
- **Every probe change needs a deploy.** The runner's probe list is generated into its dependency list, so a new, renamed or edited probe only exists in the sandbox after a deploy. Write and review **all** the probes of a batch first, dry-run once, and ask for one deploy. A deploy is the person's, in their own terminal, so a wasted one costs a person's time.
|
|
155
|
+
- **After every deploy, run the chain-proving probe first** (a trivial probe, for example `probe-zero`, that only proves the runner loads). If it fails, the runner is broken and no other result means anything (see [Troubleshooting](#every-probe-returns-http-400-and-names-no-probe)).
|
|
156
|
+
- **A sandbox refresh clears the token mappings and, presumably, the deployed runner.** After one, redo the role, mapping and deploy steps.
|
|
21
157
|
|
|
22
|
-
|
|
158
|
+
## Probes
|
|
23
159
|
|
|
24
|
-
|
|
160
|
+
A probe is a version-controlled module that exercises one platform behavior and returns the result as data. It must declare `@scriptType Restlet` and no `@writes`.
|
|
25
161
|
|
|
26
162
|
```js
|
|
27
163
|
/**
|
|
@@ -33,9 +169,104 @@ define(["N/record"], (record) => ({
|
|
|
33
169
|
}));
|
|
34
170
|
```
|
|
35
171
|
|
|
36
|
-
|
|
172
|
+
### Running one
|
|
173
|
+
|
|
174
|
+
```sh
|
|
175
|
+
suitescript-verify run <probe> [--param name=value ...] [--draft]
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
- 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.
|
|
179
|
+
- Output is scrubbed of the account, client and certificate ids, and refused if it still looks like an identifier.
|
|
180
|
+
- A probe with an `<probe>.expect.json` is compared with it, and a difference exits 2 as drift. The expectation is the `result` object, sorted and indented, not the whole output. Commit it only once the output is stable: a flaky probe reports drift.
|
|
181
|
+
- `--draft` writes `<probe>.md` into your results folder, never over an existing page. A draft goes stale: after a probe changes, refresh the page's Test and Results sections from the probe and its expected output.
|
|
182
|
+
|
|
183
|
+
### Parameters
|
|
184
|
+
|
|
185
|
+
Declare each parameter in the probe's leading JSDoc block, one tag per parameter: `@param <name> <pattern>`.
|
|
186
|
+
|
|
187
|
+
- The name is lowercase-initial letters and digits (`recordType`).
|
|
188
|
+
- The pattern is a JavaScript regular expression (Unicode mode) that the whole value must match, so `[a-z_]+` cannot match `a;b`.
|
|
189
|
+
- Pass each value with `run <probe> --param name=value`. Every declared parameter is required and its value is always a string.
|
|
190
|
+
- The runner validates the parameters against the declarations before any request, rejecting an invalid, undeclared, missing or repeated one. A probe that declares none takes none.
|
|
191
|
+
- 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.
|
|
192
|
+
- A bad `@param` tag (no pattern, an invalid pattern, a duplicate name) stops `run` and `deploy`.
|
|
193
|
+
|
|
194
|
+
### Tags
|
|
195
|
+
|
|
196
|
+
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 `flavor,other`). The package checks only that a registered tag is known; what a tag means is up to the project.
|
|
197
|
+
|
|
198
|
+
### Writing probes that do not cost a deploy
|
|
199
|
+
|
|
200
|
+
- **Keep module-scope code rare and tiny.** The runner loads every probe as a dependency of its own `define()`. A probe whose top-level code fails in a way its own `try/catch` cannot capture takes the whole runner down. If you need one, make it one governed call, run it last and one per deploy, so a failure points at one call. Do not keep a probe that is expected to take the runner down; its results page carries the code.
|
|
201
|
+
- **The role is minimal.** A probe that searches transactions or creates a record gets `INSUFFICIENT_PERMISSION`. That error comes after type validation, which is often still evidence, but a probe that needs a record permission should say so in its header. Prefer objects that need no permission (`runtime`, `search.createColumn`).
|
|
202
|
+
- **Check how an API is chained before relying on it.** `crypto.createHash(...).update(...)` returns nothing, so chaining `.digest()` threw `Cannot read property 'digest' of undefined` and cost a deploy. Read the method page for the return type.
|
|
203
|
+
- **Outbound calls rate-limit.** A public echo service answered four requests in a row and failed the fifth with a body that had no `headers`. Keep a probe to four requests or fewer and put the status code in the failure, not just a `TypeError`.
|
|
204
|
+
- **Write probes with your editor or file tools, not a shell heredoc.** Backticks, `${}` and quotes in a probe broke a shell heredoc on Windows.
|
|
205
|
+
- **An agent's tool can refuse the deploy command.** An auto-mode classifier blocked a deploy dry run chained in one shell line with other commands. Run the dry run alone and say so if it is still refused; the real deploy is the person's anyway.
|
|
206
|
+
|
|
207
|
+
## Settings
|
|
208
|
+
|
|
209
|
+
Every setting is a `SUITESCRIPT_VERIFY_` key. They layer from the committed `verification/.env`, the gitignored `verification/.env.local` and the process environment, in that order. The committed file may hold only the keys marked "committed", and its values must not look like a secret. A bad value stops every command that reaches the sandbox, and the error names the key, never the value.
|
|
210
|
+
|
|
211
|
+
| Key | Where | What it is |
|
|
212
|
+
| ----------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
213
|
+
| `SUITESCRIPT_VERIFY_PROBES_DIR` | committed | Folder of probes (a path in the project) |
|
|
214
|
+
| `SUITESCRIPT_VERIFY_RESULTS_DIR` | committed | Folder of results pages (a path in the project). No default: you choose |
|
|
215
|
+
| `SUITESCRIPT_VERIFY_SDF_DIR` | committed | Folder for the generated SDF project (a path in the project) |
|
|
216
|
+
| `SUITESCRIPT_VERIFY_ROLE_ID` | committed | The runner's role id, matching `^customrole_[a-z0-9_]{1,29}$` (40 characters at most in all); default `customrole_suitescript_verify`. Used in the generated manifest and the runner, and reported by `doctor` |
|
|
217
|
+
| `SUITESCRIPT_VERIFY_RUNNER_ID` | committed | The runner's name: 1 to 20 lowercase letters, digits and underscores, starting with a letter; default `suitescript_verify`. Names the script (`customscript_<id>_runner`), the deployment and the File Cabinet folder, so projects sharing a sandbox can each have their own runner |
|
|
218
|
+
| `SUITESCRIPT_VERIFY_EXTRA_TAGS` | committed | Extra probe tag names, comma-separated, without the `@` |
|
|
219
|
+
| `SUITESCRIPT_VERIFY_ACCOUNT` | local | The sandbox account (`digits_SBn`) |
|
|
220
|
+
| `SUITESCRIPT_VERIFY_CLIENT_ID` | local | The integration's client id |
|
|
221
|
+
| `SUITESCRIPT_VERIFY_CERTIFICATE_ID` | local | Certificate id of the runner pair |
|
|
222
|
+
| `SUITESCRIPT_VERIFY_PRIVATE_KEY_PATH` | local | Path to the runner pair's private key (outside the project) |
|
|
223
|
+
| `SUITESCRIPT_VERIFY_SDF_CERTIFICATE_ID` | local | Certificate id of the SDF pair |
|
|
224
|
+
| `SUITESCRIPT_VERIFY_SDF_PRIVATE_KEY_PATH` | local | Path to the SDF pair's private key (outside the project) |
|
|
225
|
+
| `SUITESCRIPT_VERIFY_PASSKEY` | local | The SuiteCloud passkey, saved by `passkey` |
|
|
226
|
+
| `SUITESCRIPT_VERIFY_DOMAIN` | local | Optional NetSuite domain passed to the SuiteCloud CLI |
|
|
227
|
+
|
|
228
|
+
"Local" keys go in `.env.local` or the process environment (a pipeline's secrets), never in the committed file.
|
|
229
|
+
|
|
230
|
+
## Troubleshooting
|
|
231
|
+
|
|
232
|
+
### Every probe returns HTTP 400 and names no probe
|
|
233
|
+
|
|
234
|
+
The message looks like `com.netsuite.suitescript.scriptobject.ScriptNullObjectAdapter@...`. One probe's top-level code failed in a way its own `try/catch` cannot capture, so the runner never loaded.
|
|
235
|
+
|
|
236
|
+
1. Move the suspect probe out of the probes folder.
|
|
237
|
+
2. Dry-run, then ask the person for a redeploy.
|
|
238
|
+
|
|
239
|
+
### A probe returns `INSUFFICIENT_PERMISSION`
|
|
240
|
+
|
|
241
|
+
The runner's role is minimal, so a probe that searches transactions or creates a record gets this error. It comes after type validation, which is often still evidence. See [Probes](#writing-probes-that-do-not-cost-a-deploy) for how to write around it.
|
|
242
|
+
|
|
243
|
+
### Every call fails with `401 INVALID_LOGIN_ATTEMPT`
|
|
244
|
+
|
|
245
|
+
With the machine-to-machine grant alone, the token endpoint issues a token but every call fails. On the integration record, also enable the token-based authentication flags and the RESTlets and REST Web Services scopes.
|
|
246
|
+
|
|
247
|
+
### `setup-ci` fails with "an error with the private key"
|
|
248
|
+
|
|
249
|
+
The full message is "There was an error with the private key used to authenticate". The SDF pair is not RSA. Oracle's SDK signs the SDF login with PS256 and only parses an RSA key. Use an RSA-4096 key with an RSA-PSS certificate for the SDF pair, and an EC P-256 pair for the runner. They cannot share a pair (see [Setup](#setup)).
|
|
250
|
+
|
|
251
|
+
### An authentication or "not found" error after a sandbox refresh
|
|
252
|
+
|
|
253
|
+
A refresh clears the token mappings and, presumably, the deployed runner. Redo the role, mapping and deploy steps.
|
|
254
|
+
|
|
255
|
+
### The SuiteCloud CLI postinstall exits 3
|
|
256
|
+
|
|
257
|
+
On a headless machine, with `SUITECLOUD_CLI_ACCEPT_LICENSE` unset, the postinstall opens the license with `start`, `open` or `xdg-open`, which fails without a desktop. A desktop install is fine. A headless job needs the maintainer to accept the license, or an install with `--ignore-scripts`.
|
|
258
|
+
|
|
259
|
+
### SuiteCloud browser login stopped working in another project
|
|
260
|
+
|
|
261
|
+
A user-wide `SUITECLOUD_CI_PASSKEY` stops browser login in your other SuiteCloud projects. Remove it from the environment and keep the passkey in `verification/.env.local`.
|
|
262
|
+
|
|
263
|
+
## Adding a lesson
|
|
264
|
+
|
|
265
|
+
A **lesson** is a short, generic account of a runner, deploy, probe or sandbox problem: what happened, what it cost and how to avoid it. Keep it concrete (the message, the cause, the fix), and never put an account number, id, token or real record id in it. Fix an entry that proves wrong instead of adding a second one that contradicts it.
|
|
37
266
|
|
|
38
|
-
|
|
267
|
+
- **A generic problem with this package or its flow:** open an issue or pull request at [nemchik/suitescript-verify](https://github.com/nemchik/suitescript-verify). It is added in the same pull request to the matching section above (setup, deploy, probes or troubleshooting), so it ships with the next version.
|
|
268
|
+
- **A release or toolchain problem in that repository:** it is added to the repository's `docs/maintaining.md` instead, which is not shipped because it does not apply to anyone using the package.
|
|
269
|
+
- **A finding about NetSuite itself:** write a [results page](#documenting-a-verification) in your own project. It is not a lesson.
|
|
39
270
|
|
|
40
271
|
## Development
|
|
41
272
|
|
package/dist/cli.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { randomBytes } from "node:crypto";
|
|
2
2
|
import { createInterface } from "node:readline/promises";
|
|
3
3
|
import { certificate } from "./certificate.js";
|
|
4
|
-
import { loadConfig, resultsDirGuidance, resultsDirKey, suggestedResultsDir, } from "./config.js";
|
|
4
|
+
import { loadConfig, resultsDirGuidance, resultsDirKey, runnerIdKey, suggestedResultsDir, } from "./config.js";
|
|
5
5
|
import { formatChecks, names, runChecks } from "./doctor.js";
|
|
6
6
|
import { envNames } from "./envfile.js";
|
|
7
7
|
import { init } from "./init.js";
|
|
@@ -73,15 +73,23 @@ async function initCommand(args) {
|
|
|
73
73
|
console.log(init(process.cwd(), config, await chooseResultsDir(config, args)));
|
|
74
74
|
return 0;
|
|
75
75
|
}
|
|
76
|
+
/**
|
|
77
|
+
* Generates the runner and its SDF project. A runner generated here under
|
|
78
|
+
* another id may still be deployed (the SuiteCloud CLI cannot delete a script),
|
|
79
|
+
* so say how to turn it off.
|
|
80
|
+
*/
|
|
81
|
+
function buildRunner(config, deployed) {
|
|
82
|
+
const built = buildSdfProject(config, { deployed });
|
|
83
|
+
for (const id of built.replacedRunners) {
|
|
84
|
+
console.warn(`This folder held a runner for the id "${id}", which may still be deployed in the sandbox. To turn it off, run cleanup with ${runnerIdKey}=${id}, then switch back.`);
|
|
85
|
+
}
|
|
86
|
+
return built;
|
|
87
|
+
}
|
|
76
88
|
async function deploy(args) {
|
|
77
89
|
const project = process.cwd();
|
|
78
90
|
const config = configure(args, true);
|
|
79
91
|
requireSandbox(config);
|
|
80
|
-
const { files, slugs } =
|
|
81
|
-
deployed: true,
|
|
82
|
-
extraTags: config.extraTags,
|
|
83
|
-
roleId: config.roleId,
|
|
84
|
-
});
|
|
92
|
+
const { files, slugs } = buildRunner(config, true);
|
|
85
93
|
console.log(`Probes in the runner: ${slugs.join(", ") || "(none)"}`);
|
|
86
94
|
console.log(`Files to upload: ${files.join(", ")}`);
|
|
87
95
|
const approved = args.includes("--approved");
|
|
@@ -106,11 +114,7 @@ async function cleanup(args) {
|
|
|
106
114
|
else {
|
|
107
115
|
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).");
|
|
108
116
|
}
|
|
109
|
-
|
|
110
|
-
deployed: false,
|
|
111
|
-
extraTags: config.extraTags,
|
|
112
|
-
roleId: config.roleId,
|
|
113
|
-
});
|
|
117
|
+
buildRunner(config, false);
|
|
114
118
|
return suitecloud(project, config, [
|
|
115
119
|
"project:deploy",
|
|
116
120
|
...(approved ? [] : ["--dryrun"]),
|
package/dist/config.js
CHANGED
|
@@ -15,10 +15,27 @@ export const suggestedResultsDir = "docs/verification/results";
|
|
|
15
15
|
export const resultsDirGuidance = `Choose where results pages live in your project, then run suitescript-verify init --results-dir <path> (${suggestedResultsDir} is the suggested value) or set ${resultsDirKey} in the committed .env.`;
|
|
16
16
|
/** The committed `.env` may also register extra probe tags: a comma-separated list of tag names, not a path. */
|
|
17
17
|
export const extraTagsKey = "SUITESCRIPT_VERIFY_EXTRA_TAGS";
|
|
18
|
-
/** The committed `.env` may
|
|
18
|
+
/** The committed `.env` may name the runner role: a NetSuite custom role id. */
|
|
19
19
|
export const roleIdKey = "SUITESCRIPT_VERIFY_ROLE_ID";
|
|
20
20
|
export const defaultRoleId = "customrole_suitescript_verify";
|
|
21
|
-
const
|
|
21
|
+
const roleSetting = {
|
|
22
|
+
// `customrole_` is 11 characters, so 29 more make 40.
|
|
23
|
+
expects: "a NetSuite custom role id like customrole_suitescript_verify (lowercase letters, digits and underscores after customrole_, 40 characters at most in all)",
|
|
24
|
+
fallback: defaultRoleId,
|
|
25
|
+
key: roleIdKey,
|
|
26
|
+
pattern: /^customrole_[a-z0-9_]{1,29}$/,
|
|
27
|
+
};
|
|
28
|
+
/** The committed `.env` may name the runner: a short stem for its script id, deployment id and File Cabinet folder. */
|
|
29
|
+
export const runnerIdKey = "SUITESCRIPT_VERIFY_RUNNER_ID";
|
|
30
|
+
export const defaultRunnerId = "suitescript_verify";
|
|
31
|
+
const runnerSetting = {
|
|
32
|
+
// `customscript_` and `customdeploy_` are 13 characters and `_runner` is 7, so 20 more make 40.
|
|
33
|
+
expects: "a runner id like my_project (a lowercase letter, then lowercase letters, digits and underscores, 20 characters at most)",
|
|
34
|
+
fallback: defaultRunnerId,
|
|
35
|
+
key: runnerIdKey,
|
|
36
|
+
pattern: /^[a-z][a-z0-9_]{0,19}$/,
|
|
37
|
+
};
|
|
38
|
+
const idSettings = [roleSetting, runnerSetting];
|
|
22
39
|
const tagName = /^[A-Za-z][A-Za-z0-9_-]*$/;
|
|
23
40
|
/** The tag names in a registration value, without the `@`; blank entries are dropped. */
|
|
24
41
|
export const parseTagList = (value) => value
|
|
@@ -58,17 +75,19 @@ export const insideProject = (project, path) => {
|
|
|
58
75
|
const looksSecret = (value) => /-----BEGIN /.test(value) ||
|
|
59
76
|
/^eyJ[\w-]+\.[\w-]+\.[\w-]+$/.test(value) ||
|
|
60
77
|
/^[A-Za-z0-9+_=-]{32,}$/.test(value);
|
|
61
|
-
const
|
|
62
|
-
message: `${
|
|
78
|
+
const idProblem = (setting, file) => ({
|
|
79
|
+
message: `${setting.key} in ${file} is not ${setting.expects}.`,
|
|
63
80
|
});
|
|
64
81
|
/** Checks the committed `.env` against the allowlist. Messages name the key, never the value. */
|
|
65
82
|
function checkCommitted(project, committed, file) {
|
|
66
83
|
const problems = [];
|
|
67
84
|
for (const [key, value] of committed) {
|
|
68
|
-
|
|
85
|
+
const idSetting = idSettings.find((setting) => setting.key === key);
|
|
86
|
+
if (idSetting) {
|
|
69
87
|
// The pattern is the whole check: a valid id may be long enough to look like a token.
|
|
70
|
-
if (!
|
|
71
|
-
problems.push(
|
|
88
|
+
if (!idSetting.pattern.test(value)) {
|
|
89
|
+
problems.push(idProblem(idSetting, file));
|
|
90
|
+
}
|
|
72
91
|
}
|
|
73
92
|
else if (key === extraTagsKey) {
|
|
74
93
|
if (!parseTagList(value).every((name) => tagName.test(name))) {
|
|
@@ -84,7 +103,7 @@ function checkCommitted(project, committed, file) {
|
|
|
84
103
|
}
|
|
85
104
|
else if (!layoutKeys.includes(key)) {
|
|
86
105
|
problems.push({
|
|
87
|
-
message: `${key} in ${file} is not a layout key. The committed file holds layout only (${[...layoutKeys, extraTagsKey,
|
|
106
|
+
message: `${key} in ${file} is not a layout key. The committed file holds layout only (${[...layoutKeys, extraTagsKey, ...idSettings.map((setting) => setting.key)].join(", ")}); put anything else in .env.local or the process environment.`,
|
|
88
107
|
});
|
|
89
108
|
}
|
|
90
109
|
else if (!insideProject(project, value)) {
|
|
@@ -142,13 +161,15 @@ export function loadConfig(project, dir, processEnv = process.env) {
|
|
|
142
161
|
}
|
|
143
162
|
}
|
|
144
163
|
const path = (key, fallback) => resolve(project, values[key] || fallback);
|
|
145
|
-
const
|
|
164
|
+
const idValue = (setting) => values[setting.key] || setting.fallback;
|
|
146
165
|
// The committed file reports its own bad value; this covers .env.local and the environment.
|
|
147
|
-
const
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
166
|
+
const idProblems = idSettings.flatMap((setting) => {
|
|
167
|
+
const committedValue = committed.get(setting.key);
|
|
168
|
+
return setting.pattern.test(idValue(setting)) ||
|
|
169
|
+
(committedValue !== undefined && !setting.pattern.test(committedValue))
|
|
170
|
+
? []
|
|
171
|
+
: [idProblem(setting, ".env.local or the environment")];
|
|
172
|
+
});
|
|
152
173
|
const shown = relative(project, envFile).replaceAll("\\", "/");
|
|
153
174
|
return {
|
|
154
175
|
extraTags: parseTagList(values[extraTagsKey] ?? ""),
|
|
@@ -156,13 +177,14 @@ export function loadConfig(project, dir, processEnv = process.env) {
|
|
|
156
177
|
problems: [
|
|
157
178
|
...checkCommitted(project, committed, shown),
|
|
158
179
|
...checkLocalIgnored(project, localFile),
|
|
159
|
-
...
|
|
180
|
+
...idProblems,
|
|
160
181
|
],
|
|
161
182
|
resultsDir: values[resultsDirKey]
|
|
162
183
|
? resolve(project, values[resultsDirKey])
|
|
163
184
|
: undefined,
|
|
164
|
-
roleId,
|
|
185
|
+
roleId: idValue(roleSetting),
|
|
165
186
|
root,
|
|
187
|
+
runnerId: idValue(runnerSetting),
|
|
166
188
|
sdfDir: path("SUITESCRIPT_VERIFY_SDF_DIR", join(root, "sdf")),
|
|
167
189
|
values,
|
|
168
190
|
};
|
package/dist/doctor.js
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
|
+
import { spawnSync } from "node:child_process";
|
|
1
2
|
import { createPrivateKey } from "node:crypto";
|
|
2
3
|
import { existsSync, readFileSync } from "node:fs";
|
|
4
|
+
import { homedir } from "node:os";
|
|
3
5
|
import { join } from "node:path";
|
|
4
6
|
import { insideProject, resultsDirGuidance, resultsDirKey, } from "./config.js";
|
|
5
7
|
export const names = {
|
|
@@ -11,6 +13,33 @@ export const names = {
|
|
|
11
13
|
sdfCertificateId: "SUITESCRIPT_VERIFY_SDF_CERTIFICATE_ID",
|
|
12
14
|
sdfPrivateKeyPath: "SUITESCRIPT_VERIFY_SDF_PRIVATE_KEY_PATH",
|
|
13
15
|
};
|
|
16
|
+
/**
|
|
17
|
+
* The Java versions Oracle's SDK runs on: the SuiteCloud CLI's own
|
|
18
|
+
* `SDK_COMPATIBLE_JAVA_VERSIONS`, which refuses to run on any other.
|
|
19
|
+
*/
|
|
20
|
+
const javaVersions = ["17", "21"];
|
|
21
|
+
/** Where Oracle's SDK keeps its jar (`cli/`) and its saved logins, under the home folder. */
|
|
22
|
+
const sdkFolder = ".suitecloud-sdk";
|
|
23
|
+
const loginFiles = ["credentials_browser_based.p12", "credentials_ci.p12"];
|
|
24
|
+
/** The installed Java's version, read the way the SuiteCloud CLI reads it (`java -version`, no shell); empty when there is none. */
|
|
25
|
+
function installedJavaVersion() {
|
|
26
|
+
const result = spawnSync("java", ["-version"], {
|
|
27
|
+
encoding: "utf8",
|
|
28
|
+
shell: false,
|
|
29
|
+
});
|
|
30
|
+
const match = /(?:\bjava version\b|\bopenjdk version\b) "([\d.]+)"/.exec(result.stderr ?? "");
|
|
31
|
+
return match?.[1] ?? "";
|
|
32
|
+
}
|
|
33
|
+
/** The SDK jar the installed SuiteCloud CLI downloads, from its package.json; empty when unknown. */
|
|
34
|
+
function sdkFilename(project) {
|
|
35
|
+
try {
|
|
36
|
+
const manifest = JSON.parse(readFileSync(join(project, "node_modules", "@oracle", "suitecloud-cli", "package.json"), "utf8"));
|
|
37
|
+
return manifest.sdkFilename ?? "";
|
|
38
|
+
}
|
|
39
|
+
catch {
|
|
40
|
+
return "";
|
|
41
|
+
}
|
|
42
|
+
}
|
|
14
43
|
/** `ec:<curve>`, `rsa:<bits>` or `other`, from a private key file. Never the key itself. */
|
|
15
44
|
function keyType(path) {
|
|
16
45
|
try {
|
|
@@ -34,6 +63,14 @@ export function runChecks(project, config, env = process.env) {
|
|
|
34
63
|
const add = (name, ok, owner, next) => checks.push({ name, next, ok, owner });
|
|
35
64
|
const v = config.values;
|
|
36
65
|
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.");
|
|
66
|
+
const javaVersion = installedJavaVersion();
|
|
67
|
+
add(`Java ${javaVersions.join(" or ")} is on the PATH`,
|
|
68
|
+
// The major version: "17.0.4" is Java 17, but "170.0.1" is not.
|
|
69
|
+
javaVersions.includes(javaVersion.split(".")[0] ?? ""), "maintainer", `Install Java ${javaVersions.join(" or ")} and make sure \`java -version\` works: the SuiteCloud SDK runs on no other version.`);
|
|
70
|
+
const sdkRoot = join(homedir(), sdkFolder);
|
|
71
|
+
const jarName = sdkFilename(project);
|
|
72
|
+
add("The SuiteCloud SDK jar is downloaded", jarName !== "" && existsSync(join(sdkRoot, "cli", jarName)), "maintainer", "Run the SuiteCloud CLI's postinstall script in your project (node node_modules/@oracle/suitecloud-cli/postinstall.js) and read and accept Oracle's license yourself when it asks. This package never accepts it. A headless machine needs a desktop install, or the maintainer to accept the license first.");
|
|
73
|
+
add("SuiteCloud login is set up (browser-based once, or CI)", loginFiles.some((file) => existsSync(join(sdkRoot, file))), "maintainer", "With SUITECLOUD_CI_PASSKEY unset, run the project's SuiteCloud CLI account:setup from the SDF folder, log in to the sandbox and choose a role. This one-time browser login installs Oracle's SuiteCloud Development Integration in the account.");
|
|
37
74
|
const missing = [
|
|
38
75
|
names.account,
|
|
39
76
|
names.clientId,
|
|
@@ -84,6 +121,7 @@ export function runChecks(project, config, env = process.env) {
|
|
|
84
121
|
? "Run suitescript-verify init to create the missing folders."
|
|
85
122
|
: "Run account:setup:ci from the SDF folder once the steps above pass, so project.json gets a default auth id.");
|
|
86
123
|
add(`Runner role id: ${config.roleId}`, true, "agent", "");
|
|
124
|
+
add(`Runner id: ${config.runnerId}`, true, "agent", "");
|
|
87
125
|
return checks;
|
|
88
126
|
}
|
|
89
127
|
export function formatChecks(checks) {
|
package/dist/init.js
CHANGED
|
@@ -1,7 +1,10 @@
|
|
|
1
1
|
import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
|
|
2
2
|
import { dirname, join, relative, resolve } from "node:path";
|
|
3
|
+
import { fileURLToPath } from "node:url";
|
|
3
4
|
import { insideProject, resultsDirKey } from "./config.js";
|
|
4
5
|
import { UsageError } from "./shared.js";
|
|
6
|
+
/** The README shipped with the running package, wherever the package manager put it. */
|
|
7
|
+
const readme = fileURLToPath(new URL("../README.md", import.meta.url));
|
|
5
8
|
/** A path relative to the project, with forward slashes, for messages and the committed `.env`. */
|
|
6
9
|
const shown = (project, path) => relative(project, path).replaceAll("\\", "/");
|
|
7
10
|
/**
|
|
@@ -75,7 +78,7 @@ export function init(project, config, chosenResultsDir) {
|
|
|
75
78
|
"1. Install the SuiteCloud CLI: npm install --save-dev @oracle/suitecloud-cli. Read Oracle's license and accept it yourself; this package never does.",
|
|
76
79
|
`2. Add ${local} to .gitignore before saving any value: it holds credentials.`,
|
|
77
80
|
"3. In a sandbox, create the integration record, the role and the certificate mappings, and generate the private keys outside the repository.",
|
|
78
|
-
`4. Save the account, client id, certificate ids, key paths and a passkey in ${local}. Setup is described in the package README:
|
|
81
|
+
`4. Save the account, client id, certificate ids, key paths and a passkey in ${local}. Setup is described in the installed package README: ${shown(project, readme)}`,
|
|
79
82
|
"5. Run suitescript-verify doctor until every step passes.",
|
|
80
83
|
].join("\n");
|
|
81
84
|
}
|
package/dist/netsuite.js
CHANGED
|
@@ -1,10 +1,23 @@
|
|
|
1
1
|
import { createPrivateKey, sign } from "node:crypto";
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
export const
|
|
2
|
+
import { defaultRunnerId } from "./config.js";
|
|
3
|
+
/** The names a runner takes from its id: the script, the deployment, the File Cabinet folder and the title shown in the account. */
|
|
4
|
+
export const runnerNames = (runnerId) => ({
|
|
5
|
+
deployId: `customdeploy_${runnerId}_runner`,
|
|
6
|
+
folder: runnerId.replaceAll("_", "-"),
|
|
7
|
+
scriptId: `customscript_${runnerId}_runner`,
|
|
8
|
+
// A runner of another id says so, so two runners in one account can be told apart.
|
|
9
|
+
title: runnerId === defaultRunnerId
|
|
10
|
+
? "suitescript-verify runner"
|
|
11
|
+
: `suitescript-verify runner (${runnerId})`,
|
|
12
|
+
});
|
|
13
|
+
/** The id of the runner that wrote an object file, from its name; undefined for any other file. */
|
|
14
|
+
export const runnerIdOfObjectFile = (file) => /^customscript_([a-z0-9_]+)_runner.xml$/.exec(file)?.[1];
|
|
5
15
|
const host = (account) => account.trim().toLowerCase().replace(/_/g, "-");
|
|
6
16
|
export const tokenUrl = (account) => `https://${host(account)}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token`;
|
|
7
|
-
export const restletUrl = (account) =>
|
|
17
|
+
export const restletUrl = (account, runnerId) => {
|
|
18
|
+
const { deployId, scriptId } = runnerNames(runnerId);
|
|
19
|
+
return `https://${host(account)}.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=${scriptId}&deploy=${deployId}`;
|
|
20
|
+
};
|
|
8
21
|
const base64url = (data) => Buffer.from(data).toString("base64url");
|
|
9
22
|
/** The signed JWT NetSuite's OAuth 2.0 client credentials flow expects: ES256 with an EC P-256 key. */
|
|
10
23
|
export function clientAssertion(options) {
|
package/dist/run.js
CHANGED
|
@@ -115,7 +115,7 @@ export async function runProbe(project, config, args) {
|
|
|
115
115
|
if (!tokenResponse.ok || !tokenBody.access_token) {
|
|
116
116
|
throw new UsageError(safe(`Token request failed: HTTP ${tokenResponse.status} ${tokenBody.error ?? ""} ${tokenBody.error_description ?? ""}`.trim()));
|
|
117
117
|
}
|
|
118
|
-
const response = await fetch(restletUrl(creds.account), {
|
|
118
|
+
const response = await fetch(restletUrl(creds.account, config.runnerId), {
|
|
119
119
|
body: JSON.stringify(probe.params.length > 0
|
|
120
120
|
? { params, probe: probe.slug }
|
|
121
121
|
: { probe: probe.slug }),
|
package/dist/sdf.js
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
|
-
import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
|
|
1
|
+
import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
|
|
2
2
|
import { join } from "node:path";
|
|
3
|
-
import {
|
|
4
|
-
import { fileCabinetFolder } from "./netsuite.js";
|
|
3
|
+
import { runnerIdOfObjectFile, runnerNames } from "./netsuite.js";
|
|
5
4
|
import { isRestlet, listProbes, read, tagProblems, } from "./probes.js";
|
|
6
5
|
import { UsageError } from "./shared.js";
|
|
7
6
|
const templates = new URL("../templates/", import.meta.url);
|
|
@@ -23,9 +22,11 @@ export function generateRunner(probes, source) {
|
|
|
23
22
|
/**
|
|
24
23
|
* Writes the generated runner, the probe copies and the SDF project files into
|
|
25
24
|
* the SDF folder. Only RESTlet probes go in: the runner is a RESTlet. With
|
|
26
|
-
* `deployed: false` the runner's deployment is switched off (cleanup).
|
|
25
|
+
* `deployed: false` the runner's deployment is switched off (cleanup). A runner
|
|
26
|
+
* generated here under another id is removed so it is not deployed again;
|
|
27
|
+
* `replacedRunners` names those ids, since each may still be deployed in the sandbox.
|
|
27
28
|
*/
|
|
28
|
-
export function buildSdfProject(
|
|
29
|
+
export function buildSdfProject({ extraTags, probesDir, roleId, runnerId, sdfDir, }, { deployed }) {
|
|
29
30
|
const probes = listProbes(probesDir, extraTags).filter(isRestlet);
|
|
30
31
|
const bad = probes.filter((probe) => tagProblems(probe).length > 0);
|
|
31
32
|
if (bad.length > 0) {
|
|
@@ -34,15 +35,28 @@ export function buildSdfProject(sdfDir, probesDir, { deployed, extraTags = [], r
|
|
|
34
35
|
.join("\n")}`);
|
|
35
36
|
}
|
|
36
37
|
const src = join(sdfDir, "src");
|
|
37
|
-
const
|
|
38
|
+
const names = runnerNames(runnerId);
|
|
39
|
+
const folder = join(src, "FileCabinet", "SuiteScripts", names.folder);
|
|
38
40
|
rmSync(join(src, "FileCabinet"), { force: true, recursive: true });
|
|
39
41
|
mkdirSync(join(folder, "probes"), { recursive: true });
|
|
40
42
|
mkdirSync(join(src, "Objects"), { recursive: true });
|
|
43
|
+
const replacedRunners = [];
|
|
44
|
+
for (const file of readdirSync(join(src, "Objects"))) {
|
|
45
|
+
const id = runnerIdOfObjectFile(file);
|
|
46
|
+
if (id !== undefined && id !== runnerId) {
|
|
47
|
+
rmSync(join(src, "Objects", file));
|
|
48
|
+
replacedRunners.push(id);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
41
51
|
writeFileSync(join(sdfDir, "package.json"), template("sdf/package.json"));
|
|
42
52
|
writeFileSync(join(sdfDir, "suitecloud.config.js"), template("sdf/suitecloud.config.js"));
|
|
43
53
|
writeFileSync(join(src, "manifest.xml"), template("sdf/manifest.xml").replaceAll("%%ROLE_ID%%", roleId));
|
|
44
|
-
writeFileSync(join(src, "deploy.xml"), template("sdf/deploy.xml"));
|
|
45
|
-
writeFileSync(join(src, "Objects",
|
|
54
|
+
writeFileSync(join(src, "deploy.xml"), template("sdf/deploy.xml").replaceAll("%%FOLDER%%", names.folder));
|
|
55
|
+
writeFileSync(join(src, "Objects", `${names.scriptId}.xml`), template("sdf/runner.xml")
|
|
56
|
+
.replaceAll("%%SCRIPT_ID%%", names.scriptId)
|
|
57
|
+
.replaceAll("%%DEPLOY_ID%%", names.deployId)
|
|
58
|
+
.replaceAll("%%FOLDER%%", names.folder)
|
|
59
|
+
.replaceAll("%%TITLE%%", names.title)
|
|
46
60
|
.replace("%%DEPLOYED%%", deployed ? "T" : "F")
|
|
47
61
|
.replaceAll("%%ROLE_ID%%", roleId));
|
|
48
62
|
const slugs = probes.map((probe) => probe.slug);
|
|
@@ -52,5 +66,5 @@ export function buildSdfProject(sdfDir, probesDir, { deployed, extraTags = [], r
|
|
|
52
66
|
writeFileSync(join(folder, "probes", `${slug}.js`), read(join(probesDir, `${slug}.js`)));
|
|
53
67
|
files.push(`probes/${slug}.js`);
|
|
54
68
|
}
|
|
55
|
-
return { files, slugs };
|
|
69
|
+
return { files, replacedRunners, slugs };
|
|
56
70
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "suitescript-verify",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Run probes in a NetSuite sandbox to verify what SuiteScript modules do, with guardrails for agents.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"suitescript",
|
|
@@ -50,7 +50,7 @@
|
|
|
50
50
|
"@types/node": "24.19.2",
|
|
51
51
|
"git-pull-run": "2.1.0",
|
|
52
52
|
"lefthook": "2.2.2",
|
|
53
|
-
"skills": "1.8.
|
|
53
|
+
"skills": "1.8.1",
|
|
54
54
|
"typescript": "7.0.2"
|
|
55
55
|
},
|
|
56
56
|
"peerDependencies": {
|
package/templates/sdf/deploy.xml
CHANGED
package/templates/sdf/runner.xml
CHANGED
|
@@ -1,17 +1,17 @@
|
|
|
1
|
-
<restlet scriptid="
|
|
1
|
+
<restlet scriptid="%%SCRIPT_ID%%">
|
|
2
2
|
<description>Runs one version-controlled probe by name in a sandbox. Source: the project's verification folder, through suitescript-verify.</description>
|
|
3
3
|
<isinactive>F</isinactive>
|
|
4
|
-
<name
|
|
4
|
+
<name>%%TITLE%%</name>
|
|
5
5
|
<notifyowner>F</notifyowner>
|
|
6
|
-
<scriptfile>[/SuiteScripts
|
|
6
|
+
<scriptfile>[/SuiteScripts/%%FOLDER%%/runner.js]</scriptfile>
|
|
7
7
|
<scriptdeployments>
|
|
8
|
-
<scriptdeployment scriptid="
|
|
8
|
+
<scriptdeployment scriptid="%%DEPLOY_ID%%">
|
|
9
9
|
<allroles>F</allroles>
|
|
10
10
|
<audslctrole>[%%ROLE_ID%%]</audslctrole>
|
|
11
11
|
<isdeployed>%%DEPLOYED%%</isdeployed>
|
|
12
12
|
<loglevel>DEBUG</loglevel>
|
|
13
13
|
<status>RELEASED</status>
|
|
14
|
-
<title
|
|
14
|
+
<title>%%TITLE%%</title>
|
|
15
15
|
</scriptdeployment>
|
|
16
16
|
</scriptdeployments>
|
|
17
17
|
</restlet>
|