@enfocussw/switch-scripting-context 25.11.0-beta.14 → 25.11.0-beta.16

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.
Files changed (30) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/README.md +28 -22
  3. package/dist/init.d.ts +1 -1
  4. package/dist/init.js +18 -7
  5. package/docs/switch-api/{api-connection.md → connection.md} +18 -3
  6. package/docs/switch-api/{api-document-classes.md → document-classes.md} +10 -1
  7. package/docs/switch-api/{api-entry-points.md → entry-points.md} +14 -5
  8. package/docs/switch-api/{api-enums.md → enums.md} +12 -1
  9. package/docs/switch-api/{api-execution-environment.md → execution-environment.md} +16 -7
  10. package/docs/switch-api/{api-flow-element.md → flow-element.md} +13 -4
  11. package/docs/switch-api/{api-http.md → http.md} +9 -0
  12. package/docs/switch-api/{api-job-patterns.md → job-patterns.md} +23 -8
  13. package/docs/switch-api/{api-job.md → job.md} +13 -4
  14. package/docs/switch-api/{api-logging.md → logging.md} +15 -6
  15. package/docs/switch-api/{api-switch.md → switch.md} +10 -1
  16. package/docs/{switch-api/api-app-guidelines.md → switch-appstore/app-guidelines.md} +50 -33
  17. package/docs/switch-appstore/app-manual.md +84 -0
  18. package/docs/switch-appstore/app-store-listing.md +69 -0
  19. package/docs/switch-appstore/app-store-submission.md +83 -0
  20. package/docs/{switch-api/api-debugging.md → switch-project/debugging.md} +9 -0
  21. package/docs/{switch-api/api-logs-and-dataroot.md → switch-project/logs-and-dataroot.md} +10 -1
  22. package/docs/{switch-api/api-project-planning.md → switch-project/project-planning.md} +22 -13
  23. package/docs/switch-project/property-documentation.md +75 -0
  24. package/docs/{switch-api/api-property-editors.md → switch-project/property-editors.md} +19 -10
  25. package/docs/{switch-api/api-script-declaration.md → switch-project/script-declaration.md} +18 -9
  26. package/docs/{switch-api/api-script-structure.md → switch-project/script-structure.md} +14 -5
  27. package/docs/{switch-api/api-tooling.md → switch-project/tooling.md} +10 -1
  28. package/docs/{switch-api/api-vscode.md → switch-project/vscode.md} +9 -0
  29. package/docs/switch-scripting.md +35 -27
  30. package/package.json +4 -3
package/docs/switch-project/property-documentation.md ADDED
@@ -0,0 +1,75 @@
1
+ ---
2
+ id: property-documentation
3
+ category: switch-project
4
+ order: 21
5
+ summary: "Writing guidance for `Tooltip` and `DetailedInfo` content on properties/connections"
6
+ triggers:
7
+ - "Writing or reviewing the text in a property's or connection's `Tooltip`/`DetailedInfo`"
8
+ ---
9
+
10
+ # Writing Property and Connection Documentation
11
+
12
+ Guidance for the *content* of `Tooltip` and `DetailedInfo` on properties and connections — see
13
+ [script-declaration.md](script-declaration.md#custom-property-elements-elementfields) for
14
+ the attribute mechanics (when each is required, what breaks if omitted). This page covers what to
15
+ actually write in them.
16
+
17
+ Both attributes are read only inside Switch Designer, by someone who has already added the flow
18
+ element to a flow. Compare with [app-store-listing.md](../switch-appstore/app-store-listing.md), read by
19
+ someone deciding whether to install the app at all, and [app-manual.md](../switch-appstore/app-manual.md), a
20
+ separate uploaded document.
21
+
22
+ **Delivery:** write this content directly into the `Tooltip`/`DetailedInfo` attributes in
23
+ `<ScriptID>.xml` — there is no separate file. See
24
+ [script-declaration.md § Agent editing policy](script-declaration.md#agent-editing-policy)
25
+ for how to edit the declaration safely.
26
+
27
+ ## Tooltip
28
+
29
+ The one-line hint shown in the Properties pane. This is the field that matters most here — it's
30
+ always visible to whoever is configuring the property, connection, or the app's own icon, with no
31
+ extra click required.
32
+
33
+ - Add information the property name doesn't already give: units, valid range, format, or an
34
+ example value. A tooltip that just restates the label ("Output folder: the output folder to
35
+ use") wastes the one line a user reliably reads.
36
+ - If no sensible default is possible, put an example value in the tooltip — see the `Default`
37
+ guideline in [script-declaration.md](script-declaration.md#custom-property-elements-elementfields).
38
+ - Sentence-style capitalization, no trailing period, one line. Match the style already used in
39
+ declarations: `Tooltip="Select the output folder"`.
40
+ - Skip it only when the property is genuinely self-explanatory from its name alone, with no
41
+ constraints worth stating (e.g. "Number of copies" with no min/max).
42
+
43
+ ## DetailedInfo
44
+
45
+ Feeds the HTML documentation Switch Designer can export for a whole *flow* — not something
46
+ specific to this app, it's compiled from every element the flow builder happens to have placed in
47
+ that flow. Real, but low priority in practice: it's an opt-in export most flow builders never
48
+ generate, and plenty of shipped apps leave it blank. Don't treat an empty `DetailedInfo` as a
49
+ defect to pad out.
50
+
51
+ Fill it in when the tooltip's one line genuinely isn't enough — an interaction with another
52
+ property, an edge case worth flagging, or why a setting matters, not a restatement of the tooltip
53
+ in longer sentences. A trivial property with `DetailedInfo=""` is expected and fine.
54
+
55
+ If you do write `DetailedInfo`, don't rely on it being the only place that content exists — the
56
+ property's fuller description belongs in [app-manual.md](../switch-appstore/app-manual.md#properties-detailed-info)
57
+ regardless, since that document is far more likely to actually be read.
58
+
59
+ ## Writing quality
60
+
61
+ Applies to both fields, and is the same bar [app-store-listing.md](../switch-appstore/app-store-listing.md)
62
+ and [app-manual.md](../switch-appstore/app-manual.md) hold their content to:
63
+
64
+ - **Don't restate the field name.** A tooltip on "Output folder" that says "The output folder"
65
+ adds nothing a user didn't already know.
66
+ - **No generic AI/marketing vocabulary** — powerful, seamless, robust, intuitive, and similar
67
+ words that could describe any property in any app. Say the specific thing this one does.
68
+ - **No meta-commentary about the implementation.** Write what the user sees or does, not how the
69
+ script is coded internally ("this property is passed to the internal handler").
70
+ - **No vague filler.** "Set this to an appropriate value" tells a user nothing; a concrete unit,
71
+ range, or example does.
72
+ - **No copy-pasted boilerplate across properties.** Identical tooltip text reused on unrelated
73
+ properties signals nobody thought about the individual property.
74
+ - **Keep it translatable.** Idioms and culture-specific references don't translate cleanly into
75
+ the six Switch languages — see [switch.md § Translation extraction rules](../switch-api/switch.md#translation-extraction-rules).
package/docs/{switch-api/api-property-editors.md → switch-project/property-editors.md} RENAMED
@@ -1,20 +1,29 @@
1
+ ---
2
+ id: property-editors
3
+ category: switch-project
4
+ order: 15
5
+ summary: "Property editor types, string return values, literal editors, dropdowns"
6
+ triggers:
7
+ - "Defining property editors in XML or reading property values in code"
8
+ ---
9
+
1
10
  # Property Editors
2
11
 
3
12
  Property editors determine how a user enters a value in Switch Designer, and what string is
4
13
  returned by `getPropertyStringValue()` at runtime. They're set in the XML declaration via the
5
14
  `Editor` and `Type` attributes on a custom property — see
6
- [api-script-declaration.md](api-script-declaration.md) for the surrounding attribute grammar.
15
+ [script-declaration.md](script-declaration.md) for the surrounding attribute grammar.
7
16
 
8
17
  All property values are returned as `string` or `string[]`. `getPropertyType()` returns one of a
9
18
  fixed set of `PropertyType` values (`literal`, `string`, `number`, `date`, `boolean`, `filepath`,
10
- `folderpath`, `regex`, `oauthtoken`, etc. — see [api-enums.md](api-enums.md)) describing what kind of
19
+ `folderpath`, `regex`, `oauthtoken`, etc. — see [enums.md](../switch-api/enums.md)) describing what kind of
11
20
  value is actually present; `literal` is only one of these, not a binary "literal vs. user-entered"
12
21
  flag. Use it before interpreting the returned string, e.g. to check for a literal editor's constant
13
22
  before comparing it.
14
23
 
15
24
  `Editor` is a `;`-joined list: the inline editor's token (if any) first, then modal editor tokens in
16
25
  the order they're offered. `Type` follows from which editor(s) are chosen — see the tables below and
17
- [the Type reference](api-script-declaration.md#type-reference).
26
+ [the Type reference](script-declaration.md#type-reference).
18
27
 
19
28
  ---
20
29
 
@@ -48,8 +57,8 @@ open a dialog when the user clicks the editor button. All have `Type="string"` u
48
57
  | `regexp` | Regular expression string as entered |
49
58
  | `filetype` | Filename pattern(s) for the selected file type |
50
59
  | `types` (`Type="filefilter"`) | `string[]` — one pattern string per selected file type |
51
- | `askplugin` | String value selected from the library dialog (calls `getLibraryForProperty`) — **requires the script to implement `getLibraryForProperty`** (`getLibraryForConnectionProperty` for a connection field), see [api-entry-points.md](api-entry-points.md#property-ui-callbacks) |
52
- | `askplugin2` | `string[]` — one string per selected library item (calls `getLibraryForMultipleProperty`) — **requires a matching library-callback entry point**, same as `askplugin` above. ⚠ `getLibraryForMultipleProperty` isn't documented anywhere in [api-entry-points.md](api-entry-points.md#property-ui-callbacks), which only lists `getLibraryForProperty`/`getLibraryForConnectionProperty` — this may be the same entry point handling both single- and multi-select, or a genuinely separate, undocumented one; needs verifying against source before relying on the name here. |
60
+ | `askplugin` | String value selected from the library dialog (calls `getLibraryForProperty`) — **requires the script to implement `getLibraryForProperty`** (`getLibraryForConnectionProperty` for a connection field), see [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks) |
61
+ | `askplugin2` | `string[]` — one string per selected library item (calls `getLibraryForMultipleProperty`) — **requires a matching library-callback entry point**, same as `askplugin` above. ⚠ `getLibraryForMultipleProperty` isn't documented anywhere in [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks), which only lists `getLibraryForProperty`/`getLibraryForConnectionProperty` — this may be the same entry point handling both single- and multi-select, or a genuinely separate, undocumented one; needs verifying against source before relying on the name here. |
53
62
  | `description` | Multi-line text as a single string (may include newlines) |
54
63
  | `scriptexp` | Result of script expression evaluated in job context, as a string |
55
64
  | `sltextwithvar` | Single-line text with variables substituted, as a string |
@@ -58,7 +67,7 @@ open a dialog when the user clicks the editor button. All have `Type="string"` u
58
67
  | `filepatterns` | `string[]` — one pattern string per entry |
59
68
  | `folderpatterns` | `string[]` — one pattern string per entry |
60
69
  | `stringlist` (`Type="stringlist"`) | `string[]` — one string per line |
61
- | `oauth` | OAuth 2.0 access token string, or `""` if not yet authorized — see [ExtraProperties](api-script-declaration.md#extraproperties) |
70
+ | `oauth` | OAuth 2.0 access token string, or `""` if not yet authorized — see [ExtraProperties](script-declaration.md#extraproperties) |
62
71
  | `external`, `external2`, … | File path to a property set edited by an external companion app |
63
72
 
64
73
  > Duplicate tokens in `Editor` are meaningless — each modal editor can only be offered once, except
@@ -157,7 +166,7 @@ offer it as the property's only editor — pair it with a module-free option (e.
157
166
  | Boolean consumed directly by script logic (not a `Dependency` master) | `inline` + `conditionwithvar` + `scriptexp` | Safe to toggle dynamically since nothing else depends on it for visibility. Also covers booleans that are themselves a `Dependency` *dependent* (not a master). |
158
167
  | Enum (`Type="enum:..."`) | `inline` only, always | No editor guarantees a var/expression result matches one of the declared items. |
159
168
  | File/folder path that must exist for the app to work | `choosefile`/`choosefolder` only | Switch validates the picked path exists at flow start. |
160
- | File/folder path that legitimately varies per job | `choosefile`/`choosefolder` + `sltextwithvar` + `scriptexp` | Dynamic values only resolve when read during `jobArrived` — see the "Workaround for deferred processing" note in [api-flow-element.md](api-flow-element.md#properties) if the path is needed later in the flow. |
169
+ | File/folder path that legitimately varies per job | `choosefile`/`choosefolder` + `sltextwithvar` + `scriptexp` | Dynamic values only resolve when read during `jobArrived` — see the "Workaround for deferred processing" note in [flow-element.md](../switch-api/flow-element.md#properties) if the path is needed later in the flow. |
161
170
  | Connection include-mask filter (which jobs pass through) | `allfiles;allotherfiles;types;filepatterns;regexp;scriptexp`, `Default="All Files"`, `Subtype="allfiles"` | Matches Switch's own built-in connection filter properties exactly — `Default`/`Subtype` must hold the chosen literal's exact rendered string. Folder version: `allfolders;allotherfolders;folderpatterns;regexp;scriptexp` with `Default="All Folders"`, `Subtype="allfolders"`. |
162
171
  | Connection exclude-mask filter (which jobs are blocked) | `nofiles;types;filepatterns;regexp;scriptexp`, `Default="No Files"`, `Subtype="nofiles"` | Same reasoning as the include mask, starting from `nofiles` instead since there's no "exclude all/all other" case. Folder version: `nofolders;folderpatterns;regexp;scriptexp` with `Default="No Folders"`, `Subtype="nofolders"`. |
163
172
 
@@ -171,12 +180,12 @@ dedicated row above.
171
180
 
172
181
  - **OAuth 2.0**: endpoint, client ID/secret, scope, and redirect ports are configured per-property
173
182
  in a matching `<ExtraProperties>` child element (see
174
- [api-script-declaration.md § ExtraProperties](api-script-declaration.md#extraproperties)), not in
183
+ [script-declaration.md § ExtraProperties](script-declaration.md#extraproperties)), not in
175
184
  `Editor`/`Type`. The script receives a ready-to-use access token string via
176
185
  `getPropertyStringValue()`.
177
186
  - **External editor**: requires a separate companion application. The script receives a file path to
178
187
  the property set file. Entry point `findExternalEditorPath` resolves the editor executable path.
179
188
  One of these two must be true — either a dependent property named `Application` (see
180
- [Dependency](api-script-declaration.md#custom-property-elements-elementfields)) is non-empty, or
189
+ [Dependency](script-declaration.md#custom-property-elements-elementfields)) is non-empty, or
181
190
  the script implements `findExternalEditorPath` — see
182
- [api-entry-points.md](api-entry-points.md#property-ui-callbacks).
191
+ [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks).
package/docs/{switch-api/api-script-declaration.md → switch-project/script-declaration.md} RENAMED
@@ -1,3 +1,12 @@
1
+ ---
2
+ id: script-declaration
3
+ category: switch-project
4
+ order: 14
5
+ summary: "XML declaration reference: properties, connections, execution config; agents may edit this file directly"
6
+ triggers:
7
+ - "Understanding, adding, or editing script properties/connections/execution config"
8
+ ---
9
+
1
10
  # Script Declaration (XML)
2
11
 
3
12
  The file `<ScriptID>.xml` defines the script's metadata, custom properties, connection properties,
@@ -57,8 +66,8 @@ value is non-string (see the table); an empty string field can omit `Type`.
57
66
  | `Version` | number | Format `[1-9][0-9]*(\.(0\|[1-9][0-9]*))*`, e.g. `1`, `2.1`. Bump on every declaration change. |
58
67
  | `Keywords` | string | Space/comma/semicolon-separated. Elements pane search. |
59
68
  | `Tooltip` | string | Elements pane tooltip. |
60
- | `IncomingConnections` | `Yes` \| `No` | Add `RequireAtLeastOne="Yes"` when `Yes`. When `Yes`, the script must implement `jobArrived` (optionally `timerFired` too); when `No`, it must implement `timerFired` instead — see [api-entry-points.md](api-entry-points.md#job-processing). |
61
- | `OutgoingConnections` | `No` \| `One` \| `Unlimited` | Add `RequireAtLeastOne="Yes"` when `One`/`Unlimited`. Always carries `DetailedInfo=""` (or a prose description of the connections, for generated docs). When not `No`, the script must call a `sendTo*()` method at least once for any job it actually routes (a purely timer/event-driven script that never touches a job — polling an API, rotating logs, etc. — is a legitimate exception); when `Unlimited`, never use `job.sendToSingle()` — see [api-job-patterns.md § Sending jobs](api-job-patterns.md#sending-jobs). |
69
+ | `IncomingConnections` | `Yes` \| `No` | Add `RequireAtLeastOne="Yes"` when `Yes`. When `Yes`, the script must implement `jobArrived` (optionally `timerFired` too); when `No`, it must implement `timerFired` instead — see [entry-points.md](../switch-api/entry-points.md#job-processing). |
70
+ | `OutgoingConnections` | `No` \| `One` \| `Unlimited` | Add `RequireAtLeastOne="Yes"` when `One`/`Unlimited`. Always carries `DetailedInfo=""` (or a prose description of the connections, for generated docs). When not `No`, the script must call a `sendTo*()` method at least once for any job it actually routes (a purely timer/event-driven script that never touches a job — polling an API, rotating logs, etc. — is a legitimate exception); when `Unlimited`, never use `job.sendToSingle()` — see [job-patterns.md § Sending jobs](../switch-api/job-patterns.md#sending-jobs). |
62
71
  | `ConnectionType` | `Move` \| `Filter` \| `TrafficLight` | Governs which `ConnectionFields` children are legal — see [ConnectionFields](#connectionfields). |
63
72
  | `FunctionsNodeJSScript` | `;`-separated names | Entry point function names found in the script. Omit the element entirely if there is no Node.js program. |
64
73
  | `ExecutionMode` | `Concurrent` \| `Serialized` | |
@@ -108,12 +117,12 @@ Key attributes:
108
117
  |---|---|
109
118
  | `UserDefined` | Always `"true"` for custom properties. |
110
119
  | `Type` | Value type discriminator — see [Type reference](#type-reference). |
111
- | `Editor` | `;`-joined chain of editor tokens (inline editor first, then modal editors) — see [api-property-editors.md](api-property-editors.md). |
120
+ | `Editor` | `;`-joined chain of editor tokens (inline editor first, then modal editors) — see [property-editors.md](property-editors.md). |
112
121
  | `Subtype` | Which editor in the `Editor` chain is currently active for the stored value. For a single-editor property this equals that editor's token (e.g. `"inline"`); for a bare modal editor with no inline component, leave it `""`. This attribute is read by Switch's validator at runtime, not just bookkeeping — keep it consistent with `Editor`. |
113
122
  | `LocalizedTagName` | Display name shown in the Properties pane. **App guideline (mandatory for apps, recommended for scripts):** 30 characters max, sentence-style capitalization (`"Customer name"`, not `"Customer Name"`). |
114
123
  | `Tooltip` | Tooltip shown in the Properties pane. **App guideline (mandatory for apps, recommended for scripts):** give every property a tooltip. The only exception is a property that's fully self-explanatory from its name alone with no extra constraints (e.g. "Number of copies" with no min/max) — if there's anything a user would need to know (units, valid range, format, an example value), put it in the tooltip. |
115
124
  | `DetailedInfo` | Long-form description for generated docs. Always include the attribute (empty string `""` is fine) — omitting it makes the property non-editable in Switch Designer. |
116
- | `Validation` | `None` (skip validation) \| `Standard` (built-in validator) \| `Custom` (needs a `validateProperties` entry point) \| `Standard and custom` (both, custom only runs if standard passes). If any property uses `Custom` or `Standard and custom`, the script must implement `validateProperties` (or `validateConnectionProperties` for a connection field) — see [api-entry-points.md](api-entry-points.md#property-ui-callbacks). To let a property hold an empty value under `Standard` validation, add the `none` literal editor to the `Editor` chain (see [api-property-editors.md § Literal editors](api-property-editors.md#literal-editors)) instead of relaxing to `Validation="None"` just to permit emptiness. |
125
+ | `Validation` | `None` (skip validation) \| `Standard` (built-in validator) \| `Custom` (needs a `validateProperties` entry point) \| `Standard and custom` (both, custom only runs if standard passes). If any property uses `Custom` or `Standard and custom`, the script must implement `validateProperties` (or `validateConnectionProperties` for a connection field) — see [entry-points.md](../switch-api/entry-points.md#property-ui-callbacks). To let a property hold an empty value under `Standard` validation, add the `none` literal editor to the `Editor` chain (see [property-editors.md § Literal editors](property-editors.md#literal-editors)) instead of relaxing to `Validation="None"` just to permit emptiness. |
117
126
  | `Default` | Default value string. Omit only if the value is emitted as CDATA instead. **App guideline (mandatory for apps, recommended for scripts):** always provide a default unless there's genuinely no sensible one; if a default truly isn't possible, give an example value in the `Tooltip` instead. |
118
127
  | `Dependency` | Tag of the master property this one depends on. Written flat (not nested) — the dependent element is a sibling of its master, not a child. |
119
128
  | `DependencyCondition` | One of: `Not-empty`, `Equals`, `Not-equals`, `Contains`, `Does not contain`, `Matches`, `Does not match`, `Starts with`, `Does not start with`. |
@@ -134,7 +143,7 @@ Key attributes:
134
143
  **Runtime pitfall:** when a dependent property is hidden (its master's current value doesn't satisfy
135
144
  `DependencyCondition`/`Dependencyvalue`), Switch treats the tag as if it doesn't exist. Calling
136
145
  `flowElement.getPropertyStringValue(tag)` on it throws `"Invalid tag: <tag>"` — see
137
- [api-flow-element.md](api-flow-element.md#properties). Only fetch a dependent property once you know
146
+ [flow-element.md](../switch-api/flow-element.md#properties). Only fetch a dependent property once you know
138
147
  its condition holds, either by checking the already-read master value yourself, or by calling
139
148
  `flowElement.hasProperty(tag)` first (it returns `false` for a hidden dependent). This matters most
140
149
  for an enum/drop-down master with several dependents keyed off different values — fetch only the
@@ -191,7 +200,7 @@ most important thing to get right when hand-editing this section:
191
200
  Custom (author-defined) connection properties may be added regardless of `ConnectionType`.
192
201
 
193
202
  The declared connections and the script's `sendTo*()` calls must agree with each other — see
194
- [api-job-patterns.md § Sending jobs](api-job-patterns.md#sending-jobs) for the exact rules per
203
+ [job-patterns.md § Sending jobs](../switch-api/job-patterns.md#sending-jobs) for the exact rules per
195
204
  `ConnectionType`. In particular, omit a `Success`/`Warning`/`Error` element entirely (as shown
196
205
  above) if the script never routes to it, rather than leaving an unused connection declared.
197
206
 
@@ -207,7 +216,7 @@ properties to reset on next package update.
207
216
  ## ExtraProperties
208
217
 
209
218
  Only used for OAuth 2.0 (`Editor` containing `oauth`, see
210
- [api-property-editors.md](api-property-editors.md)). One child element per OAuth property, named
219
+ [property-editors.md](property-editors.md)). One child element per OAuth property, named
211
220
  identically to the property's tag, in `ElementFields` or `ConnectionFields`:
212
221
 
213
222
  ```xml
@@ -259,7 +268,7 @@ If no OAuth property exists on the script, omit `ExtraProperties` entirely or le
259
268
 
260
269
  This is the *authoring* vocabulary written into the XML `Type` attribute. It does not map one-to-one
261
270
  onto the runtime `PropertyType` returned by `getPropertyType()` (see
262
- [api-property-editors.md](api-property-editors.md) and [api-enums.md](api-enums.md)) — e.g. XML
271
+ [property-editors.md](property-editors.md) and [enums.md](../switch-api/enums.md)) — e.g. XML
263
272
  `bool` becomes runtime `boolean`, XML `path` splits into runtime `filepath`/`folderpath`, and several
264
273
  XML types (`rational`, `stringlist`, `accountlist`, `enum:...`, `datetime`, `time`) have no direct
265
274
  `PropertyType` counterpart while several runtime values (`filetype`, `folderpattern`, `regex`,
@@ -267,7 +276,7 @@ XML types (`rational`, `stringlist`, `accountlist`, `enum:...`, `datetime`, `tim
267
276
  interchangeable.
268
277
 
269
278
  `Type` is not independently authored on properties with a modal editor chain — it follows from
270
- which editor(s) you choose, per [api-property-editors.md](api-property-editors.md). When combining
279
+ which editor(s) you choose, per [property-editors.md](property-editors.md). When combining
271
280
  an inline editor with modal editors (e.g. `Editor="inline;sltextwithvar;scriptexp"`), the inline
272
281
  editor's type wins: an inline Number editor plus those modal editors still yields `Type="number"`.
273
282
 
package/docs/{switch-api/api-script-structure.md → switch-project/script-structure.md} RENAMED
@@ -1,15 +1,24 @@
1
+ ---
2
+ id: script-structure
3
+ category: switch-project
4
+ order: 10
5
+ summary: "What files a script folder contains, `manifest.xml` format, Node.js version per Switch release, Script vs App"
6
+ triggers:
7
+ - "Setting up a new script project, or converting a Script to an App"
8
+ ---
9
+
1
10
  # Script Project Structure
2
11
 
3
12
  A Switch script project lives in a **script folder** during development and is distributed as a `.sscript` package (ZIP).
4
13
 
5
- > **Agent editing policy**: Edit TypeScript/JavaScript source files (`main.ts`, `main.js`) and the XML declaration (`<ScriptID>.xml`) freely — see [api-script-declaration.md](api-script-declaration.md) for the declaration's rules, and [api-entry-points.md § Entry-point scanner constraints](api-entry-points.md#entry-point-scanner-constraints) before writing any string/regex literal or division, since certain shapes make Switch's entry-point scanner silently drop functions. Leave `manifest.xml` to the user unless explicitly asked.
14
+ > **Agent editing policy**: Edit TypeScript/JavaScript source files (`main.ts`, `main.js`) and the XML declaration (`<ScriptID>.xml`) freely — see [script-declaration.md](script-declaration.md) for the declaration's rules, and [entry-points.md § Entry-point scanner constraints](../switch-api/entry-points.md#entry-point-scanner-constraints) before writing any string/regex literal or division, since certain shapes make Switch's entry-point scanner silently drop functions. Leave `manifest.xml` to the user unless explicitly asked.
6
15
 
7
16
  ## Script folder files
8
17
 
9
18
  | File | Required | Notes |
10
19
  |---|---|---|
11
20
  | `manifest.xml` | Yes | Switch internal use only. Do not edit manually. |
12
- | `<ScriptID>.xml` | Yes | Script declaration (properties, connections, execution config). See [api-script-declaration.md](api-script-declaration.md). |
21
+ | `<ScriptID>.xml` | Yes | Script declaration (properties, connections, execution config). See [script-declaration.md](script-declaration.md). |
13
22
  | `main.ts` | Yes (TypeScript) | Source file. Edit this. |
14
23
  | `main.js` | Yes | Compiled output executed by Switch. Generated by transpiling `main.ts`. |
15
24
  | `main.js.map` | No | Source map, generated alongside `main.js`. |
@@ -105,13 +114,13 @@ testing before submission; it loads elsewhere only once Enfocus has signed it.
105
114
  ## App Store submission guidelines
106
115
 
107
116
  App-specific submission rules (localization, universal/signed macOS binaries, immutable extra
108
- files) live in [api-app-guidelines.md § App-only](api-app-guidelines.md#app-only), alongside the
117
+ files) live in [app-guidelines.md § App-only](../switch-appstore/app-guidelines.md#app-only), alongside the
109
118
  rest of the pre-publish checklist.
110
119
 
111
120
  ## Execution modes
112
121
 
113
122
  `Concurrent`/`Serialized`, `ExecutionGroup` and `NumberOfSlots` are set in the XML declaration (see
114
- [api-script-declaration.md](api-script-declaration.md#built-in-elementfields) for the attributes)
123
+ [script-declaration.md](script-declaration.md#built-in-elementfields) for the attributes)
115
124
  and documented in
116
- [api-execution-environment.md § Execution modes](api-execution-environment.md#execution-modes),
125
+ [execution-environment.md § Execution modes](../switch-api/execution-environment.md#execution-modes),
117
126
  which also explains why none of them maps to a count of Node.js processes.
package/docs/{switch-api/api-tooling.md → switch-project/tooling.md} RENAMED
@@ -1,3 +1,12 @@
1
+ ---
2
+ id: tooling
3
+ category: switch-project
4
+ order: 11
5
+ summary: "SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment"
6
+ triggers:
7
+ - "Running SwitchScriptTool: transpiling, packing, unpacking, or deploying"
8
+ ---
9
+
1
10
  # Script Folders, Packages & SwitchScriptTool
2
11
 
3
12
  ## Script folder vs script package
@@ -44,7 +53,7 @@ location for the current OS if the bare command isn't found.
44
53
 
45
54
  Switch's entry-point scanner is regex-based, not a real parser, and can silently drop entry-point
46
55
  functions from certain string/regex/division shapes — see
47
- [api-entry-points.md § Entry-point scanner constraints](api-entry-points.md#entry-point-scanner-constraints).
56
+ [entry-points.md § Entry-point scanner constraints](../switch-api/entry-points.md#entry-point-scanner-constraints).
48
57
  `--pack` does not validate or warn about this: a script that packs cleanly can still fail to load,
49
58
  or load with a property callback that silently never runs. Compiling and passing tests doesn't
50
59
  catch it either, since the source is syntactically valid JS/TS — only extraction against the built
package/docs/{switch-api/api-vscode.md → switch-project/vscode.md} RENAMED
@@ -1,3 +1,12 @@
1
+ ---
2
+ id: vscode
3
+ category: switch-project
4
+ order: 13
5
+ summary: "Type declarations, tsconfig for TypeScript 6, ESLint rules"
6
+ triggers:
7
+ - "Setting up VS Code or fixing type errors"
8
+ ---
9
+
1
10
  # VS Code Setup
2
11
 
3
12
  ## Type declarations
package/docs/switch-scripting.md CHANGED
@@ -7,46 +7,54 @@ Enfocus Switch workflow automation scripts written in TypeScript/Node.js.
7
7
  - Type declarations are in `node_modules/@types/switch-scripting/index.d.ts` and must be followed precisely.
8
8
 
9
9
  ## API reference
10
- Detailed API docs are in `docs/switch-api/`:
10
+ Detailed docs live in three folders, alongside this file: `switch-api/` (the scripting API itself),
11
+ `switch-project/` (script/app project structure and tooling), and `switch-appstore/` (Appstore
12
+ publishing guidance).
11
13
 
12
14
  | File | Contents | Load when |
13
15
  |---|---|---|
14
- | `switch-api/api-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 |
15
- | `switch-api/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 |
16
- | `switch-api/api-switch.md` | `Switch` (`s`) — global data, webhooks, abort, server utilities | Using global data, webhooks, abort, or server settings |
17
- | `switch-api/api-flow-element.md` | `FlowElement` — properties, connections, job creation, logging | Reading properties, creating jobs, logging, connections |
18
- | `switch-api/api-job.md` | `Job` **signatures**: routing, file access, child jobs, private data, datasets | Looking up what a `job.*` method takes, returns, or throws |
19
- | `switch-api/api-connection.md` | `Connection` — type, properties, file count | Routing to specific connections or reading connection properties |
20
- | `switch-api/api-http.md` | `HttpRequest` / `HttpResponse` + webhook pattern | Handling incoming HTTP webhooks |
21
- | `switch-api/api-enums.md` | All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.) | Looking up enum values |
22
- | `switch-api/api-document-classes.md` | `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument` — read-only file introspection | Inspecting PDF, image, XML, or XMP file contents |
23
- | `switch-api/api-script-structure.md` | What files a script folder contains, `manifest.xml` format, Node.js version per Switch release, Script vs App | Setting up a new script project, or converting a Script to an App |
24
- | `switch-api/api-tooling.md` | SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment | Running SwitchScriptTool: transpiling, packing, unpacking, or deploying |
25
- | `switch-api/api-debugging.md` | Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach | Debugging a script |
26
- | `switch-api/api-vscode.md` | Type declarations, tsconfig for TypeScript 6, ESLint rules | Setting up VS Code or fixing type errors |
27
- | `switch-api/api-script-declaration.md` | XML declaration reference: properties, connections, execution config — agents may edit this file directly | Understanding, adding, or editing script properties/connections/execution config |
28
- | `switch-api/api-property-editors.md` | Property editor types, string return values, literal editors, dropdowns | Defining property editors in XML or reading property values in code |
29
- | `switch-api/api-job-patterns.md` | `Job` **rules and gotchas**: file access semantics, temp cleanup, which `sendTo*()` suits which connection type, dataset/child ordering, executor limits | Writing or reviewing job-handling code. Pair with `api-job.md` when you also need signatures |
30
- | `switch-api/api-execution-environment.md` | Execution modes (`Concurrent`/`Serialized`, `ExecutionGroup`, `NumberOfSlots`), process/concurrency model, state persistence across job invocations, unhandled-rejection behavior, npm/native module constraints | Choosing or changing an execution mode, relying on module-level state across jobs, handling errors/rejections, or using third-party npm packages |
31
- | `switch-api/api-logging.md` | Log level semantics, logging practice, `console.log` limitation, common gotchas | Adding or reviewing `job.log()`/`flowElement.log()`/`job.fail()`/`failProcess()` calls |
32
- | `switch-api/api-logs-and-dataroot.md` | Locating the Application Data Root, querying `ServerLogs.db3` directly | Diagnosing or validating a script from its actual log output rather than by reading the code |
33
- | `switch-api/api-app-guidelines.md` | Pre-publish checklist for Appstore apps: property naming/tooltips/editors, entry point and sendTo consistency, logging quality, packaging, and the app-only submission rules (localization, signed universal macOS binaries) | Preparing a script for publication as an app, or reviewing one against Appstore submission criteria |
16
+ <!-- docs-index:table begin -->
17
+ | `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-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 |
19
+ | `switch-api/switch.md` | `Switch` (`s`): global data, webhooks, abort, server utilities | Using global data, webhooks, abort, or server settings |
20
+ | `switch-api/flow-element.md` | `FlowElement`: properties, connections, job creation, logging | Reading properties, creating jobs, logging, connections |
21
+ | `switch-api/job.md` | `Job` **signatures**: routing, file access, child jobs, private data, datasets | Looking up what a `job.*` method takes, returns, or throws |
22
+ | `switch-api/connection.md` | `Connection`: type, properties, file count | Routing to specific connections or reading connection properties |
23
+ | `switch-api/http.md` | `HttpRequest` / `HttpResponse` + webhook pattern | Handling incoming HTTP webhooks |
24
+ | `switch-api/enums.md` | All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.) | Looking up enum values |
25
+ | `switch-api/document-classes.md` | `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument`: read-only file introspection | Inspecting PDF, image, XML, or XMP file contents |
26
+ | `switch-project/script-structure.md` | What files a script folder contains, `manifest.xml` format, Node.js version per Switch release, Script vs App | Setting up a new script project, or converting a Script to an App |
27
+ | `switch-project/tooling.md` | SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment | Running SwitchScriptTool: transpiling, packing, unpacking, or deploying |
28
+ | `switch-project/debugging.md` | Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach | Debugging a script |
29
+ | `switch-project/vscode.md` | Type declarations, tsconfig for TypeScript 6, ESLint rules | Setting up VS Code or fixing type errors |
30
+ | `switch-project/script-declaration.md` | XML declaration reference: properties, connections, execution config; agents may edit this file directly | Understanding, adding, or editing script properties/connections/execution config |
31
+ | `switch-project/property-editors.md` | Property editor types, string return values, literal editors, dropdowns | Defining property editors in XML or reading property values in code |
32
+ | `switch-api/job-patterns.md` | `Job` **rules and gotchas**: file access semantics, temp cleanup, which `sendTo*()` suits which connection type, dataset/child ordering, executor limits | Writing or reviewing job-handling code. Pair with `job.md` when you also need signatures |
33
+ | `switch-api/execution-environment.md` | Execution modes (`Concurrent`/`Serialized`, `ExecutionGroup`, `NumberOfSlots`), process/concurrency model, state persistence across job invocations, unhandled-rejection behavior, npm/native module constraints | Choosing or changing an execution mode, relying on module-level state across jobs, handling errors/rejections, or using third-party npm packages |
34
+ | `switch-api/logging.md` | Log level semantics, logging practice, `console.log` limitation, common gotchas | Adding or reviewing `job.log()`/`flowElement.log()`/`job.fail()`/`failProcess()` calls |
35
+ | `switch-project/logs-and-dataroot.md` | Locating the Application Data Root, querying `ServerLogs.db3` directly | Diagnosing or validating a script from its actual log output rather than by reading the code |
36
+ | `switch-appstore/app-guidelines.md` | Pre-publish checklist for Appstore apps: property naming/tooltips/editors, entry point and sendTo consistency, logging quality, packaging, and the app-only submission rules (localization, signed universal macOS binaries) | Preparing a script for publication as an app, or reviewing one against Appstore submission criteria |
37
+ | `switch-project/property-documentation.md` | Writing guidance for `Tooltip` and `DetailedInfo` content on properties/connections | Writing or reviewing the text in a property's or connection's `Tooltip`/`DetailedInfo` |
38
+ | `switch-appstore/app-store-listing.md` | Writing guidance for the declaration's Appstore listing fields: `Description`, `Compatibility`, `SupportInfo`, `AppDiscovery`, `Connections` | Writing or reviewing the app's Appstore listing text |
39
+ | `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 |
40
+ | `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 |
41
+ <!-- docs-index:table end -->
34
42
 
35
43
  ## Key rules
36
- - Before scaffolding a new script or app, work through `switch-api/api-project-planning.md` with the user.
44
+ - Before scaffolding a new script or app, work through `switch-project/project-planning.md` with the user.
37
45
  - Always consult the API reference files above before writing or modifying script code.
38
- - To find documented behavioural pitfalls before writing code in an area, grep `docs/switch-api/`
39
- for `known issue`, `gotcha`, `quirk`, `caveat` (case-insensitive) — every documented pitfall uses
40
- one of these four terms.
46
+ - To find documented behavioural pitfalls before writing code in an area, grep the `switch-api/`,
47
+ `switch-project/`, and `switch-appstore/` folders alongside this file for `known issue`, `gotcha`,
48
+ `quirk`, `caveat` (case-insensitive) — every documented pitfall uses one of these four terms.
41
49
  - Do not `export` entry point functions. Declare them with the literal `function` keyword at top
42
50
  level — arrow functions, `exports.name = ...`, and class methods are invisible to Switch.
43
51
  - Switch discovers entry points with a regex, not a parser. Never write a string literal whose
44
52
  content ends with a backslash, a regex literal, or division outside the plain `word / word`
45
53
  shape — each silently deletes a span of real code, and every entry point inside that span
46
- disappears with no error anywhere. Read `switch-api/api-entry-points.md` §
54
+ disappears with no error anywhere. Read `switch-api/entry-points.md` §
47
55
  Entry-point scanner constraints before editing `main.ts`/`main.js`.
48
56
  - Every `jobArrived` invocation must end with exactly one `job.sendTo*()` or `job.fail()` call — either in the same invocation or deferred to `timerFired` via job information stored in global data.
49
57
  - Use `AccessLevel.ReadOnly` for `job.get()` unless the file content will be modified.
50
58
  - Use VS Code snippets (`.vscode/switch.code-snippets`, prefix `switch…`) to scaffold entry points.
51
59
  - After calling `createJob()`, `createChild()`, or `createDataset()` with a file path, the script must delete the source file/folder after routing — Switch does not auto-remove it.
52
- - The XML declaration (`<ScriptID>.xml`) can be edited directly — read `switch-api/api-script-declaration.md` first and follow its rules exactly (no schema validates this format, so mistakes fail silently). Never change an existing script's `Name`. Bump `Version` on every declaration edit. Leave `manifest.xml` edits (package type, declaration filename, program files) to the user unless explicitly asked.
60
+ - The XML declaration (`<ScriptID>.xml`) can be edited directly — read `switch-project/script-declaration.md` first and follow its rules exactly (no schema validates this format, so mistakes fail silently). Never change an existing script's `Name`. Bump `Version` on every declaration edit. Leave `manifest.xml` edits (package type, declaration filename, program files) to the user unless explicitly asked.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@enfocussw/switch-scripting-context",
3
- "version": "25.11.0-beta.14",
3
+ "version": "25.11.0-beta.16",
4
4
  "description": "AI coding assistant context for Enfocus Switch scripting (Node.js/TypeScript)",
5
5
  "keywords": [
6
6
  "switch",
@@ -33,11 +33,12 @@
33
33
  "scripts": {
34
34
  "build": "tsc -p tsconfig.json",
35
35
  "build:test": "tsc src/init.test.ts --outDir dist --target ES2020 --module commonjs --lib ES2020 --types node --strict --esModuleInterop --skipLibCheck",
36
- "test": "npm run build && npm run build:test && node dist/init.test.js && node scripts/check-prose.js && node scripts/check-gotcha-tags.js",
36
+ "test": "npm run build && npm run build:test && node dist/init.test.js && node scripts/check-prose.js && node scripts/check-gotcha-tags.js && node scripts/generate-docs-index.js --check",
37
37
  "prepack": "npm run build && node scripts/readme-links.js --publish",
38
38
  "postpack": "node scripts/readme-links.js --restore && node -e \"const fs=require('fs');const version=process.env.npm_package_version;const scoped=process.env.npm_package_name.replace(/^@/,'').replace('/','-')+'-'+version+'.tgz';const unscoped=process.env.npm_package_name.replace(/^@[^/]+\\//,'')+'-'+version+'.tgz';if(scoped!==unscoped&&fs.existsSync(scoped))fs.renameSync(scoped,unscoped);\"",
39
39
  "lint:prose": "node scripts/check-prose.js",
40
- "lint:gotchas": "node scripts/check-gotcha-tags.js"
40
+ "lint:gotchas": "node scripts/check-gotcha-tags.js",
41
+ "docs:generate": "node scripts/generate-docs-index.js"
41
42
  },
42
43
  "author": "Sam Wallace",
43
44
  "license": "ISC",