@enfocussw/switch-scripting-context 25.11.1-beta.0 → 25.11.1-beta.2
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/CHANGELOG.md +33 -0
- package/README.md +19 -4
- package/dist/init.js +53 -10
- package/docs/switch-project/project-planning.md +13 -1
- package/docs/switch-project/script-structure.md +26 -1
- package/docs/switch-project/tooling.md +10 -2
- package/docs/switch-scripting.md +2 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,39 @@ All notable changes to this package are documented here. Format follows
|
|
|
5
5
|
|
|
6
6
|
## [Unreleased]
|
|
7
7
|
|
|
8
|
+
## [25.11.1-beta.2] - 2026-09-17
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- Planning now has agents check whether a design needs more than one flow element, and propose
|
|
13
|
+
one script folder per element before creating files. The script structure docs describe laying
|
|
14
|
+
out several script folders side by side, and creating them without deleting the folder you
|
|
15
|
+
work in.
|
|
16
|
+
|
|
17
|
+
### Fixed
|
|
18
|
+
|
|
19
|
+
- The tooling docs now warn that `SwitchScriptTool --create` deletes an existing target folder
|
|
20
|
+
and everything in it, including git history, without asking. Agents are told to check that the
|
|
21
|
+
target doesn't exist first.
|
|
22
|
+
- The tooling docs now list the files `--pack` actually includes. Pack copies a fixed set of files,
|
|
23
|
+
not the whole folder, so a script that imports a local module fails to pack. Before, the docs
|
|
24
|
+
said pack only left out the npm manifest and VS Code settings.
|
|
25
|
+
|
|
26
|
+
## [25.11.1-beta.1] - 2026-09-17
|
|
27
|
+
|
|
28
|
+
### Added
|
|
29
|
+
|
|
30
|
+
- `remove --tools <list>` removes the Switch section only from the named tools' AI config files.
|
|
31
|
+
The docs folder, the `.gitignore` entry and other tools' config stay in place. Without
|
|
32
|
+
`--tools`, or with every tool listed, `remove` still removes everything.
|
|
33
|
+
|
|
34
|
+
### Fixed
|
|
35
|
+
|
|
36
|
+
- `remove` now deletes the Cursor rule file and the scoped GitHub Copilot instructions file,
|
|
37
|
+
plus their folders if nothing else is in them. Before, it left both files behind containing
|
|
38
|
+
only their frontmatter. A file whose frontmatter you edited or wrote yourself is kept, with only
|
|
39
|
+
the Switch section removed.
|
|
40
|
+
|
|
8
41
|
## [25.11.1-beta.0] - 2026-09-15
|
|
9
42
|
|
|
10
43
|
### Added
|
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@ AI coding assistant context for [Enfocus Switch](https://www.enfocus.com/en/swit
|
|
|
4
4
|
|
|
5
5
|
Installs curated API reference docs and generates config files for 8 AI coding agents (Claude Code, GitHub Copilot, Cursor, Codex CLI/OpenCode, Gemini CLI, Windsurf, Zed, and Cline) so AI assistants understand the Switch scripting API out of the box.
|
|
6
6
|
|
|
7
|
-
See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.1-beta.
|
|
7
|
+
See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.1-beta.2/CHANGELOG.md) (also included in this package) for what's changed between versions.
|
|
8
8
|
|
|
9
9
|
## Usage
|
|
10
10
|
|
|
@@ -84,7 +84,7 @@ A few things this gets you without asking for them by name:
|
|
|
84
84
|
properties (app path/licence) are off-limits and left to SwitchScripter's GUI instead.
|
|
85
85
|
|
|
86
86
|
Re-run `init` after upgrading this package so the copied docs and generated config files catch up.
|
|
87
|
-
See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.1-beta.
|
|
87
|
+
See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@25.11.1-beta.2/CHANGELOG.md) for what changed.
|
|
88
88
|
|
|
89
89
|
## Options
|
|
90
90
|
|
|
@@ -118,6 +118,21 @@ npx switch-scripting-context init --dry-run
|
|
|
118
118
|
npx switch-scripting-context init --docs-dir ai-context
|
|
119
119
|
```
|
|
120
120
|
|
|
121
|
+
To undo `init`, run `remove`. By default it deletes the docs folder, the Switch section in every AI config file, and the `.gitignore` entry. With `--tools`, it only removes those tools' config sections and leaves the docs folder and other tools in place. Listing every tool is the same as a plain `remove`:
|
|
122
|
+
|
|
123
|
+
```
|
|
124
|
+
npx switch-scripting-context remove [options]
|
|
125
|
+
|
|
126
|
+
--tools <list> Only remove these tools' config. Default: remove everything
|
|
127
|
+
--docs-dir <dir> Docs folder to remove. Default: switch-docs
|
|
128
|
+
--dry-run Print what would happen without writing any files
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
# Stop configuring Cursor, keep everything else
|
|
133
|
+
npx switch-scripting-context remove --tools cursor
|
|
134
|
+
```
|
|
135
|
+
|
|
121
136
|
## TypeScript types
|
|
122
137
|
|
|
123
138
|
This package does not bundle `@types/switch-scripting`. Add the type declarations to your project manually:
|
|
@@ -132,7 +147,7 @@ The `switch-docs/` folder contains:
|
|
|
132
147
|
|
|
133
148
|
- `switch-scripting.md`: master index with execution environment rules and "load when" routing table
|
|
134
149
|
<!-- docs-index:readme begin -->
|
|
135
|
-
- `switch-project/project-planning.md`: Pre-scaffolding checklist: Script vs App, job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk
|
|
150
|
+
- `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
|
|
136
151
|
- `switch-api/entry-points.md`: All entry point signatures, constraints, and when each is called
|
|
137
152
|
- `switch-api/switch.md`: `Switch` (`s`): global data, webhooks, abort, server utilities
|
|
138
153
|
- `switch-api/flow-element.md`: `FlowElement`: properties, connections, job creation, logging
|
|
@@ -141,7 +156,7 @@ The `switch-docs/` folder contains:
|
|
|
141
156
|
- `switch-api/http.md`: `HttpRequest` / `HttpResponse` + webhook pattern
|
|
142
157
|
- `switch-api/enums.md`: All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.)
|
|
143
158
|
- `switch-api/document-classes.md`: `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument`: read-only file introspection
|
|
144
|
-
- `switch-project/script-structure.md`: What files a script folder contains, `manifest.xml` format, how `SwitchVersion` selects the Node.js version and which tools overwrite it, Script vs App
|
|
159
|
+
- `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
|
|
145
160
|
- `switch-project/tooling.md`: SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment
|
|
146
161
|
- `switch-project/debugging.md`: Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach
|
|
147
162
|
- `switch-project/vscode.md`: Type declarations, tsconfig for TypeScript 6, ESLint rules
|
package/dist/init.js
CHANGED
|
@@ -381,20 +381,46 @@ function updateGitignore(targetRoot, docsDir, dryRun) {
|
|
|
381
381
|
fs.appendFileSync(gitignorePath, entry, 'utf8');
|
|
382
382
|
console.log(` .gitignore → appended ${docsDir}/ entry`);
|
|
383
383
|
}
|
|
384
|
-
/**
|
|
385
|
-
function
|
|
386
|
-
return TOOL_REGISTRY
|
|
384
|
+
/** AI config files that init may have created, for all tools or only the given tool ids. */
|
|
385
|
+
function aiConfigFiles(targetRoot, docsDir, tools) {
|
|
386
|
+
return TOOL_REGISTRY
|
|
387
|
+
.filter(t => !tools || tools.includes(t.id))
|
|
388
|
+
.flatMap(t => t.files.map(file => ({ filePath: file.targetPath(targetRoot, docsDir), file })));
|
|
387
389
|
}
|
|
388
|
-
|
|
390
|
+
/** The frontmatter a generator writes above the marker, trimmed; empty if it writes none. */
|
|
391
|
+
function generatedFrontmatter(file, docsDir) {
|
|
392
|
+
const generated = file.generate(docsDir);
|
|
393
|
+
return generated.slice(0, generated.indexOf(MARKER_BEGIN)).trim();
|
|
394
|
+
}
|
|
395
|
+
/** Deletes now-empty folders from dir upwards, stopping at targetRoot. */
|
|
396
|
+
function removeEmptyDirs(dir, targetRoot) {
|
|
397
|
+
while (dir !== targetRoot && dir.startsWith(targetRoot + path.sep) && fs.readdirSync(dir).length === 0) {
|
|
398
|
+
fs.rmdirSync(dir);
|
|
399
|
+
dir = path.dirname(dir);
|
|
400
|
+
}
|
|
401
|
+
}
|
|
402
|
+
function removeAiConfig(filePath, file, docsDir, targetRoot, dryRun) {
|
|
389
403
|
if (!fs.existsSync(filePath))
|
|
390
404
|
return;
|
|
391
|
-
const
|
|
405
|
+
const raw = fs.readFileSync(filePath, 'utf8');
|
|
406
|
+
const eol = raw.includes('\r\n') ? '\r\n' : '\n';
|
|
407
|
+
const content = raw.replace(/\r\n/g, '\n');
|
|
392
408
|
const range = findMarkerRange(content);
|
|
393
409
|
if (!range)
|
|
394
410
|
return; // nothing from us in this file
|
|
395
411
|
const rel = path.relative(process.cwd(), filePath);
|
|
396
|
-
|
|
412
|
+
let before = content.slice(0, range[0]).trim();
|
|
397
413
|
const after = content.slice(range[1]).trim();
|
|
414
|
+
// Copilot scoped instructions and Cursor .mdc put frontmatter above the marker. Only an exact
|
|
415
|
+
// copy of what the generator writes counts as ours; edited or user-written frontmatter stays.
|
|
416
|
+
const ours = generatedFrontmatter(file, docsDir);
|
|
417
|
+
if (ours && before === ours) {
|
|
418
|
+
before = '';
|
|
419
|
+
}
|
|
420
|
+
else if (ours && before.endsWith('\n' + ours)) {
|
|
421
|
+
// init appended our block, frontmatter included, below the user's own content
|
|
422
|
+
before = before.slice(0, -ours.length).trim();
|
|
423
|
+
}
|
|
398
424
|
if (!before && !after) {
|
|
399
425
|
// File is entirely our content — delete it
|
|
400
426
|
if (dryRun) {
|
|
@@ -402,6 +428,7 @@ function removeAiConfig(filePath, dryRun) {
|
|
|
402
428
|
return;
|
|
403
429
|
}
|
|
404
430
|
fs.unlinkSync(filePath);
|
|
431
|
+
removeEmptyDirs(path.dirname(filePath), targetRoot);
|
|
405
432
|
console.log(` ${rel} → deleted`);
|
|
406
433
|
}
|
|
407
434
|
else {
|
|
@@ -411,7 +438,7 @@ function removeAiConfig(filePath, dryRun) {
|
|
|
411
438
|
console.log(` [dry-run] ${rel} → removed Switch section`);
|
|
412
439
|
return;
|
|
413
440
|
}
|
|
414
|
-
fs.writeFileSync(filePath, stripped, 'utf8');
|
|
441
|
+
fs.writeFileSync(filePath, stripped.replace(/\n/g, eol), 'utf8');
|
|
415
442
|
console.log(` ${rel} → removed Switch section`);
|
|
416
443
|
}
|
|
417
444
|
}
|
|
@@ -438,6 +465,18 @@ function remove(options) {
|
|
|
438
465
|
const docsDestDir = path.join(targetRoot, options.docsDir);
|
|
439
466
|
if (options.dryRun)
|
|
440
467
|
console.log('\nDry run — no files will be written.\n');
|
|
468
|
+
const tools = options.tools;
|
|
469
|
+
const partial = tools && !TOOL_REGISTRY.every(t => tools.includes(t.id));
|
|
470
|
+
if (partial) {
|
|
471
|
+
// Removing some tools leaves the rest configured, and they still reference the docs folder.
|
|
472
|
+
// Listing every tool leaves nothing referencing it, so that falls through to a full remove.
|
|
473
|
+
console.log('Cleaning AI config files...');
|
|
474
|
+
for (const { filePath, file } of aiConfigFiles(targetRoot, options.docsDir, options.tools)) {
|
|
475
|
+
removeAiConfig(filePath, file, options.docsDir, targetRoot, options.dryRun);
|
|
476
|
+
}
|
|
477
|
+
console.log('\nDone.\n');
|
|
478
|
+
return;
|
|
479
|
+
}
|
|
441
480
|
// 1. Remove docs dir
|
|
442
481
|
console.log('Removing docs...');
|
|
443
482
|
if (fs.existsSync(docsDestDir)) {
|
|
@@ -454,8 +493,8 @@ function remove(options) {
|
|
|
454
493
|
}
|
|
455
494
|
// 2. Remove AI config sections / files
|
|
456
495
|
console.log('\nCleaning AI config files...');
|
|
457
|
-
for (const filePath of
|
|
458
|
-
removeAiConfig(filePath, options.dryRun);
|
|
496
|
+
for (const { filePath, file } of aiConfigFiles(targetRoot, options.docsDir)) {
|
|
497
|
+
removeAiConfig(filePath, file, options.docsDir, targetRoot, options.dryRun);
|
|
459
498
|
}
|
|
460
499
|
// 3. Update .gitignore
|
|
461
500
|
console.log('\nUpdating .gitignore...');
|
|
@@ -530,6 +569,7 @@ function parseArgs(argv) {
|
|
|
530
569
|
process.exit(1);
|
|
531
570
|
}
|
|
532
571
|
initOptions.tools = raw.map(t => idMap.get(t));
|
|
572
|
+
removeOptions.tools = initOptions.tools;
|
|
533
573
|
toolsExplicit = true;
|
|
534
574
|
}
|
|
535
575
|
else if (arg === '--docs-dir' && args[i + 1]) {
|
|
@@ -580,7 +620,7 @@ Usage: switch-scripting-context <command> [options]
|
|
|
580
620
|
|
|
581
621
|
Commands:
|
|
582
622
|
init Copy docs and generate AI context config files
|
|
583
|
-
remove Remove
|
|
623
|
+
remove Remove files and config added by init (all of it, or only some tools' config)
|
|
584
624
|
|
|
585
625
|
Options (init):
|
|
586
626
|
--tools <list> Comma-separated tools to configure
|
|
@@ -593,6 +633,8 @@ Options (init):
|
|
|
593
633
|
--help Show this help message
|
|
594
634
|
|
|
595
635
|
Options (remove):
|
|
636
|
+
--tools <list> Only remove these tools' config; keeps the docs folder and other tools
|
|
637
|
+
Default: remove everything, same as listing every tool
|
|
596
638
|
--docs-dir <dir> Docs folder to remove (default: switch-docs)
|
|
597
639
|
--dry-run Print what would happen without writing any files
|
|
598
640
|
|
|
@@ -602,6 +644,7 @@ Examples:
|
|
|
602
644
|
npx switch-scripting-context init --docs-dir ai-docs --dry-run
|
|
603
645
|
npx switch-scripting-context remove
|
|
604
646
|
npx switch-scripting-context remove --dry-run
|
|
647
|
+
npx switch-scripting-context remove --tools cursor
|
|
605
648
|
`);
|
|
606
649
|
}
|
|
607
650
|
// ─── Entry point ─────────────────────────────────────────────────────────────
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
id: project-planning
|
|
3
3
|
category: switch-project
|
|
4
4
|
order: 1
|
|
5
|
-
summary: "Pre-scaffolding checklist: Script vs App, job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk"
|
|
5
|
+
summary: "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"
|
|
6
6
|
triggers:
|
|
7
7
|
- "Starting a new script or app, before scaffolding any files"
|
|
8
8
|
---
|
|
@@ -58,6 +58,18 @@ an already-registered job quickly, or a large backlog is slow to clear, see
|
|
|
58
58
|
|
|
59
59
|
## Evaluate and flag, don't ask upfront
|
|
60
60
|
|
|
61
|
+
### One script folder or several
|
|
62
|
+
|
|
63
|
+
One script folder produces one flow element. Once the job-processing design from question 2 is
|
|
64
|
+
clear, check whether it needs more than one flow element: distinct steps a flow builder should
|
|
65
|
+
place and configure as separate elements, or several related apps meant to ship as an app bundle.
|
|
66
|
+
Most designs need one, so don't ask about this upfront.
|
|
67
|
+
|
|
68
|
+
If the design needs several, propose the split before creating any files: the Script ID and
|
|
69
|
+
purpose of each script folder and, for apps, whether they form an app bundle. Wait for the user to
|
|
70
|
+
confirm. Then lay them out and create them as described in
|
|
71
|
+
[script-structure.md § Several script folders side by side](script-structure.md#several-script-folders-side-by-side).
|
|
72
|
+
|
|
61
73
|
### Target OS
|
|
62
74
|
|
|
63
75
|
Switch Server runs on Windows and macOS. Default to writing platform-independent code (the `path`
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
id: script-structure
|
|
3
3
|
category: switch-project
|
|
4
4
|
order: 10
|
|
5
|
-
summary: "What files a script folder contains, `manifest.xml` format, how `SwitchVersion` selects the Node.js version and which tools overwrite it, Script vs App"
|
|
5
|
+
summary: "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"
|
|
6
6
|
triggers:
|
|
7
7
|
- "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"
|
|
8
8
|
---
|
|
@@ -33,6 +33,31 @@ A Switch script project lives in a **script folder** during development and is d
|
|
|
33
33
|
|
|
34
34
|
> After editing `main.ts`, transpile with SwitchScriptTool to regenerate `main.js` before testing in Switch.
|
|
35
35
|
|
|
36
|
+
## Several script folders side by side
|
|
37
|
+
|
|
38
|
+
One script folder produces one flow element. A design that needs several flow elements, such as
|
|
39
|
+
the apps in an app bundle, needs one script folder per element. Keep them in one parent folder, a
|
|
40
|
+
**script collection**:
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
my-collection/ the folder the user works in; AI agent config and docs live here
|
|
44
|
+
├── FirstElement/ script folder (manifest.xml, FirstElement.xml, main.ts, ...)
|
|
45
|
+
└── SecondElement/ script folder
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
- Put each script folder directly under the collection, one level down. Don't nest a script folder
|
|
49
|
+
inside another script folder, and don't add grouping folders in between.
|
|
50
|
+
- Create each one with `SwitchScriptTool --create <ScriptID> <CollectionFolder>`. First check that
|
|
51
|
+
`<CollectionFolder>/<ScriptID>/` doesn't exist: `--create` deletes an existing target folder and
|
|
52
|
+
everything in it without asking.
|
|
53
|
+
- Never use `--create` to turn the collection folder itself into a script folder
|
|
54
|
+
(`--create <CollectionFolderName> <ParentFolder>`). That deletes the whole collection, including
|
|
55
|
+
`.git/` and AI agent config. If the user wants a script folder at the top level of the folder
|
|
56
|
+
they work in, or wants an existing top-level script folder moved down into a subfolder, stop and
|
|
57
|
+
leave that step to the user.
|
|
58
|
+
- Each script folder keeps its own `package.json`, `node_modules/` and `tsconfig.json`. Run npm,
|
|
59
|
+
transpile and pack per script folder.
|
|
60
|
+
|
|
36
61
|
## manifest.xml format
|
|
37
62
|
|
|
38
63
|
```xml
|
|
@@ -36,16 +36,24 @@ location for the current OS if the bare command isn't found.
|
|
|
36
36
|
|---|---|---|
|
|
37
37
|
| Create | `SwitchScriptTool --create <ScriptID> <Path> [--JavaScript]` | Scaffold a new script folder with all required files |
|
|
38
38
|
| Transpile | `SwitchScriptTool --transpile <Path>` | Compile `main.ts` → `main.js`. **Must use this, not `tsc` directly** |
|
|
39
|
-
| Pack | `SwitchScriptTool --pack <Folder> <
|
|
39
|
+
| Pack | `SwitchScriptTool --pack <Folder> <OutputFolder> [--password <pwd>] [--verbose]` | Create `<OutputFolder>/<ScriptID>.sscript` for deployment. `<OutputFolder>` is a directory, created if missing, not the package's file path |
|
|
40
40
|
| Unpack | `SwitchScriptTool --unpack <file.sscript> <Folder> [--password <pwd>]` | Extract package to folder |
|
|
41
41
|
| List | `SwitchScriptTool --list <file.sscript>` | List package contents (no password needed) |
|
|
42
42
|
| Generate translations | `SwitchScriptTool --generate-translations <ScriptFolder> <ResultFolder>` | Generate translation files for the script package |
|
|
43
43
|
|
|
44
44
|
**Create** scaffolds: `manifest.xml`, `<ScriptID>.xml`, `<ScriptID>.sscript`, `main.ts` (or `main.js` with `--JavaScript`), `.vscode/launch.json`, `Resources/`, plus `package.json`, `tsconfig.json`, `.vscode/switch.code-snippets`, and type declarations for TypeScript. Creates `<Path>/<ScriptID>/` — it does not write into `<Path>` directly. `ScriptID` may only contain letters, digits, hyphens, and underscores.
|
|
45
45
|
|
|
46
|
+
**Gotcha: `--create` deletes an existing target folder.** If `<Path>/<ScriptID>/` already exists, `--create` removes it and everything in it (including `.git/`, a README, or AI agent config files) without prompting, then scaffolds a fresh folder. The only sign is an `Info: Removed existing target folder` line in its output. Never run `--create` where `<Path>/<ScriptID>/` exists, and never use it to turn the folder you're already working in into a script folder: `--create <FolderName> <ParentOfFolder>` wipes that folder. Check that the target doesn't exist first.
|
|
47
|
+
|
|
46
48
|
**Transpile** is required after every edit to `main.ts` before testing a **script folder** directly in Switch. Switch executes `main.js` only — `main.ts` is never run directly. Using SwitchScriptTool (not `tsc`) ensures the same transpile options as SwitchScripter, which is required for consistent behavior. This step is **not** needed before packing — see Pack below.
|
|
47
49
|
|
|
48
|
-
**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
|
|
50
|
+
**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).
|
|
51
|
+
|
|
52
|
+
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.
|
|
53
|
+
|
|
54
|
+
`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).
|
|
55
|
+
|
|
56
|
+
**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.
|
|
49
57
|
|
|
50
58
|
**Unpack** prints package metadata (`Type`, `Protection`, `Status`) before extracting. For a TypeScript-sourced package it extracts only `main.ts` — the compiled `main.js`/`main.js.map` are not written back out, so a pack → unpack round trip returns a clean, editable script folder rather than a compiled snapshot.
|
|
51
59
|
|
package/docs/switch-scripting.md
CHANGED
|
@@ -15,7 +15,7 @@ publishing guidance).
|
|
|
15
15
|
<!-- docs-index:table begin -->
|
|
16
16
|
| File | Contents | Load when |
|
|
17
17
|
|---|---|---|
|
|
18
|
-
| `switch-project/project-planning.md` | Pre-scaffolding checklist: Script vs App, job-processing approach, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk | Starting a new script or app, before scaffolding any files |
|
|
18
|
+
| `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 |
|
|
19
19
|
| `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 |
|
|
20
20
|
| `switch-api/switch.md` | `Switch` (`s`): global data, webhooks, abort, server utilities | Using global data, webhooks, abort, or server settings |
|
|
21
21
|
| `switch-api/flow-element.md` | `FlowElement`: properties, connections, job creation, logging | Reading properties, creating jobs, logging, connections |
|
|
@@ -24,7 +24,7 @@ publishing guidance).
|
|
|
24
24
|
| `switch-api/http.md` | `HttpRequest` / `HttpResponse` + webhook pattern | Handling incoming HTTP webhooks |
|
|
25
25
|
| `switch-api/enums.md` | All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.) | Looking up enum values |
|
|
26
26
|
| `switch-api/document-classes.md` | `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument`: read-only file introspection | Inspecting PDF, image, XML, or XMP file contents |
|
|
27
|
-
| `switch-project/script-structure.md` | What files a script folder contains, `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 |
|
|
27
|
+
| `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 |
|
|
28
28
|
| `switch-project/tooling.md` | SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment | Running SwitchScriptTool: transpiling, packing, unpacking, or deploying |
|
|
29
29
|
| `switch-project/debugging.md` | Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach | Debugging a script |
|
|
30
30
|
| `switch-project/vscode.md` | Type declarations, tsconfig for TypeScript 6, ESLint rules | Setting up VS Code or fixing type errors |
|