@enfocussw/switch-scripting-context 25.11.1-beta.4 → 25.11.1-beta.6

package/docs/switch-project/tooling.md

@@ -9,6 +9,16 @@ triggers:
 
 # Script Folders, Packages & SwitchScriptTool
 
+<!-- docs-index:contents begin -->
+## Contents
+
+- Script folder vs script package
+- SwitchScriptTool
+- Commands
+- Verify entry points before packing
+- Deployment
+<!-- docs-index:contents end -->
+
 ## Script folder vs script package
 
 | | Script folder | Script package (`.sscript`) |
@@ -49,9 +59,9 @@ location for the current OS if the bare command isn't found.
 
 **Pack** transpiles `main.ts` fresh into the package on every run; it never reads or modifies any `main.js` already sitting in the source folder (a stale hand-edited `main.js` there is ignored and left untouched).
 
-Pack copies an allowlist of files, not the whole folder. Only these end up in the `.sscript`: `manifest.xml`, the declaration file named in `ScriptDeclarationFile`, the program file named in `ScriptProgramFiles` plus the `main.js` and `main.js.map` pack transpiles from it, the icon named in `ScriptIconFile`, `tsconfig.json`, the placeholder `<ScriptID>.sscript`, `Resources/`, and `node_modules/`. Everything else in the folder is left out and printed in an "Info: ... will not be packed" list, even without `--verbose`. That includes `package.json`, `package-lock.json`, `.vscode/`, a README, other `.ts`/`.js` files, subfolders other than `Resources/` and `node_modules/`, and AI agent config and docs folders. `--verbose` additionally prints the full list of what *will* be packed. Translation files were not part of this test. Verified with SwitchScriptTool 26.07.
+Pack copies an allowlist of files, not the whole folder. Only these end up in the `.sscript`: `manifest.xml`, the declaration file named in `ScriptDeclarationFile`, the program file named in `ScriptProgramFiles` plus the `main.js` and `main.js.map` pack transpiles from it, the icon named in `ScriptIconFile`, `tsconfig.json`, the placeholder `<ScriptID>.sscript`, `Resources/`, and `node_modules/`. Everything else in the folder is left out and printed in an "Info: ... will not be packed" list, even without `--verbose`. That includes `package.json`, `package-lock.json`, `.vscode/`, a README, other `.ts`/`.js` files, subfolders other than `Resources/` and `node_modules/`, and AI agent config and docs folders. `--verbose` additionally prints the full list of what *will* be packed. Translation files were not part of this test. Verified with a pre-release SwitchScriptTool build.
 
-`node_modules` is packed as-is, so run `npm prune --production` first (see Deployment) — otherwise `devDependencies` (including `@types/*` packages, which the scaffolded `package.json` puts there) get bundled into the package for no runtime benefit. One harmless quirk: the placeholder `<ScriptID>.sscript` file scaffolded by `--create` is on the allowlist and ends up packed inside the real `.sscript` too. Pack also replaces `SwitchVersion` in the packed `manifest.xml` with SwitchScriptTool's own version (`--create` writes it too), and that value picks the Node.js version the package runs on. See [script-structure.md § What writes `SwitchVersion`](script-structure.md#what-writes-switchversion).
+`node_modules` is packed as-is, so run `npm prune --production` first (see Deployment) — otherwise `devDependencies` (including `@types/*` packages, which the scaffolded `package.json` puts there) get bundled into the package for no runtime benefit. One harmless quirk: the placeholder `<ScriptID>.sscript` file scaffolded by `--create` is on the allowlist and ends up packed inside the real `.sscript` too. Pack also replaces `SwitchVersion` in the packed `manifest.xml` with SwitchScriptTool's own version (`--create` writes it too), and that value picks the Node.js version the package runs on. See [node-versions.md § What writes `SwitchVersion`](node-versions.md#what-writes-switchversion).
 
 **Gotcha: local modules break pack.** A `main.ts` that imports a local module (`import { x } from './helper'` or `'./lib/helper'`) fails to pack with TypeScript error TS2307 (`Cannot find module`), and no `.sscript` is written. Pack's own output shows why: `helper.ts` and `lib/helper.ts` appear in its "will not be packed" list, and the TS2307 error points at pack's temporary copy of the folder, which doesn't contain them. A `main.js` that `require`s a local file was not tested, but that file isn't packed either. The manifest also accepts only one `ScriptProgramFile` (pack errors with `The manifest must contain only one script program file`), so listing the helper there doesn't work. The verified option is to keep script code in the single program file. Shared code in an npm package under `node_modules/` might work, since `node_modules/` is packed, but that was not tested, and neither was a `file:` dependency, which npm installs as a symlink.
 

package/docs/switch-project/vscode.md

@@ -24,13 +24,13 @@ Enables autocomplete and type checking for `Switch`, `Job`, `FlowElement` and al
 > `SwitchScriptTool --create` sets this up automatically for new TypeScript script folders.
 
 v24.1.1-final is the last published version and matches the API of every Switch release from 24.1
-to 26.07. It declares every method without marking which Switch release added it, so the compiler
+to 26.11. It declares every method without marking which Switch release added it, so the compiler
 won't flag a call that an older target Switch lacks. Check those against
 [api-versions.md](../switch-api/api-versions.md).
 
-SwitchScriptTool 26.07 also scaffolds `@types/node` 24.x whatever Node.js version the script will
+SwitchScriptTool 26.11 also scaffolds `@types/node` 24.x whatever Node.js version the script will
 run on. When the package will run on an older Node.js (see
-[script-structure.md § Node.js version per Switch version](script-structure.md#nodejs-version-per-switch-version)),
+[node-versions.md](node-versions.md)),
 pin `@types/node` to that major version so the compiler flags newer Node.js APIs.
 
 ## TypeScript 6 / VS Code 1.114+

package/docs/switch-scripting.md

@@ -1,11 +1,13 @@
 # Switch Scripting (Node.js)
 Enfocus Switch workflow automation scripts written in TypeScript/Node.js.
 
+Read the matching file from the API reference table below before answering any question about Switch scripting, not only before writing code. This applies to short and yes/no questions too. This page only summarises; the answer usually depends on a detail that is only in the linked file, and Switch often differs from what general Node.js or scripting knowledge suggests.
+
 ## Execution environment
 - Entry points are top-level `async` functions with specific names — **not exported** — executed in a `node:vm.Script()` context.
 - ESM is supported: if ES modules are present the script is bundled with ESBuild before running (when `SwitchVersion` in `manifest.xml` is `24.0` or higher).
 - Type declarations are in `node_modules/@types/switch-scripting/index.d.ts` and must be followed precisely. They list every method up to Switch 24.1 without saying which release added it.
-- The Node.js version comes from `SwitchVersion` in `manifest.xml`; the available API methods come from the Switch version the script runs on. See `switch-project/script-structure.md` and `switch-api/api-versions.md`.
+- The Node.js version comes from `SwitchVersion` in `manifest.xml`; the available API methods come from the Switch version the script runs on. See `switch-project/node-versions.md` and `switch-api/api-versions.md`.
 
 ## API reference
 Detailed docs live in three folders, alongside this file: `switch-api/` (the scripting API itself),
@@ -15,7 +17,7 @@ publishing guidance).
 <!-- docs-index:table begin -->
 | File | Contents | Load when |
 |---|---|---|
-| `switch-project/project-planning.md` | Pre-scaffolding checklist: Script vs App, job-processing approach, one script folder or several, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk | Starting a new script or app, before scaffolding any files |
+| `switch-project/project-planning.md` | Planning checklist, run before scaffolding or on a project that is already scaffolded: Script vs App, job-processing approach, one script folder or several, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk | Starting a new script or app, before scaffolding any files, or working in a script folder that is already scaffolded where Script vs App has not been settled |
 | `switch-api/entry-points.md` | All entry point signatures, constraints, and when each is called | Scaffolding a script, adding/editing an entry point, or making any edit to main.ts/main.js |
 | `switch-api/switch.md` | `Switch` (`s`): global data, webhooks, abort, server utilities | Using global data, webhooks, abort, or server settings |
 | `switch-api/flow-element.md` | `FlowElement`: properties, connections, job creation, logging | Reading properties, creating jobs, logging, connections |
@@ -24,7 +26,7 @@ publishing guidance).
 | `switch-api/http.md` | `HttpRequest` / `HttpResponse` + webhook pattern | Handling incoming HTTP webhooks |
 | `switch-api/enums.md` | All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.) | Looking up enum values |
 | `switch-api/document-classes.md` | `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument`: read-only file introspection | Inspecting PDF, image, XML, or XMP file contents |
-| `switch-project/script-structure.md` | What files a script folder contains, laying out several script folders side by side, `manifest.xml` format, how `SwitchVersion` selects the Node.js version and which tools overwrite it, Script vs App | Setting up a new script project, converting a Script to an App, or working out which Node.js version a script or app will run on |
+| `switch-project/script-structure.md` | What files a script folder contains, laying out several script folders side by side, `manifest.xml` format, Script vs App, packing an app with SwitchScripter | Setting up a new script project or converting a Script to an App |
 | `switch-project/tooling.md` | SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment | Running SwitchScriptTool: transpiling, packing, unpacking, or deploying |
 | `switch-project/debugging.md` | Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach | Debugging a script |
 | `switch-project/vscode.md` | Type declarations, tsconfig for TypeScript 6, ESLint rules | Setting up VS Code or fixing type errors |
@@ -40,11 +42,12 @@ publishing guidance).
 | `switch-appstore/app-manual.md` | Writing guidance for the separate app manual document uploaded during Appstore review (`documentation-app_name.docx` template) | Preparing the app manual document for Appstore submission |
 | `switch-appstore/app-store-submission.md` | Writing guidance for the Create Appstore App / Create Appstore App Version web forms: Short Description, What's new, Eula, icon specs, and which fields reuse content already written elsewhere | Preparing content for the Appstore website submission forms |
 | `switch-api/api-versions.md` | Which Switch release added each scripting API class, method, and enum value; API availability follows the running Switch, not `manifest.xml` | Writing or reviewing code for a script or app that must run on a Switch version older than the latest, or when the user names a minimum Switch version |
+| `switch-project/node-versions.md` | How `SwitchVersion` in `manifest.xml` selects the Node.js version, the version table per Switch release, which tools overwrite `SwitchVersion`, values missing from the table, other effects of `SwitchVersion` | Working out which Node.js version a script or app will run on, or what `SwitchVersion` in manifest.xml does |
 <!-- docs-index:table end -->
 
 ## Key rules
 - Before scaffolding a new script or app, work through `switch-project/project-planning.md` with the user.
-- Always consult the API reference files above before writing or modifying script code.
+  If the script folder is already scaffolded, still ask Script or App; the manifest cannot answer it.
 - If the script or app must run on a Switch version older than the latest, check each API call
   against `switch-api/api-versions.md`. The API files mark anything newer than the baseline with
   "Switch X+" (a `// Switch X+` comment above a signature, or a note in the text), meaning that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enfocussw/switch-scripting-context",
-  "version": "25.11.1-beta.4",
+  "version": "25.11.1-beta.6",
   "description": "AI coding assistant context for Enfocus Switch scripting (Node.js/TypeScript)",
   "keywords": [
     "switch",