@enfocussw/switch-scripting-context 25.11.0-beta.10

package/docs/switch-scripting.md

@@ -0,0 +1,40 @@
+# Switch Scripting (Node.js)
+Enfocus Switch workflow automation scripts written in TypeScript/Node.js.
+
+## 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.
+- Type declarations are in `node_modules/@types/switch-scripting/index.d.ts` and must be followed precisely.
+
+## API reference
+Detailed API docs are in `docs/switch-api/`:
+
+| File | Contents | Load when |
+|---|---|---|
+| `switch-api/api-entry-points.md` | All entry point signatures, constraints, and when each is called | Scaffolding a new script or adding an entry point |
+| `switch-api/api-switch.md` | `Switch` (`s`) — global data, webhooks, abort, server utilities | Using global data, webhooks, abort, or server settings |
+| `switch-api/api-flow-element.md` | `FlowElement` — properties, connections, job creation, logging | Reading properties, creating jobs, logging, connections |
+| `switch-api/api-job.md` | `Job` — routing, file access, child jobs, private data, datasets | Processing/routing jobs, file access, private data, datasets |
+| `switch-api/api-connection.md` | `Connection` — type, properties, file count | Routing to specific connections or reading connection properties |
+| `switch-api/api-http.md` | `HttpRequest` / `HttpResponse` + webhook pattern | Handling incoming HTTP webhooks |
+| `switch-api/api-enums.md` | All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.) | Looking up enum values |
+| `switch-api/api-document-classes.md` | `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument` — read-only file introspection | Inspecting PDF, image, XML, or XMP file contents |
+| `switch-api/api-script-structure.md` | Script folder/package files, manifest format, App vs Script, execution modes | Setting up a new script project or converting to an App |
+| `switch-api/api-tooling.md` | SwitchScriptTool commands, script folder vs package, build and deployment | Creating, building, packaging, or deploying a script |
+| `switch-api/api-debugging.md` | Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach | Debugging a script |
+| `switch-api/api-vscode.md` | Type declarations, tsconfig for TypeScript 6, ESLint rules | Setting up VS Code or fixing type errors |
+| `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 |
+| `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 |
+| `switch-api/api-job-patterns.md` | File access semantics, temp cleanup, routing rules, child jobs, executor limits | Processing jobs, creating child jobs, working with datasets, routing to multiple connections |
+| `switch-api/api-execution-environment.md` | Process/concurrency model, state persistence across job invocations, unhandled-rejection behavior, npm/native module constraints | Relying on module-level state across jobs, handling errors/rejections, or using third-party npm packages |
+| `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 |
+| `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 |
+
+## Key rules
+- Always consult the API reference files above before writing or modifying script code.
+- Do not `export` entry point functions.
+- 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.
+- Use `AccessLevel.ReadOnly` for `job.get()` unless the file content will be modified.
+- Use VS Code snippets (`.vscode/switch.code-snippets`, prefix `switch…`) to scaffold entry points.
+- 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.
+- 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.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@enfocussw/switch-scripting-context",
+  "version": "25.11.0-beta.10",
+  "description": "AI coding assistant context for Enfocus Switch scripting (Node.js/TypeScript)",
+  "keywords": [
+    "switch",
+    "enfocus",
+    "switch-scripting",
+    "ai-context",
+    "claude",
+    "copilot",
+    "cursor",
+    "codex",
+    "gemini",
+    "windsurf",
+    "zed",
+    "cline"
+  ],
+  "main": "dist/init.js",
+  "bin": {
+    "switch-scripting-context": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "!dist/*.test.js",
+    "docs/",
+    "!docs/superpowers",
+    "!docs/temp",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:test": "tsc src/init.test.ts --outDir dist --target ES2020 --module commonjs --lib ES2020 --types node --strict --esModuleInterop --skipLibCheck",
+    "test": "npm run build && npm run build:test && node dist/init.test.js",
+    "prepack": "npm run build",
+    "postpack": "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);\""
+  },
+  "author": "Sam Wallace",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/samw_pacol/enf-switch-scripting-context.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "homepage": "https://github.com/samw_pacol/enf-switch-scripting-context#readme",
+  "bugs": {
+    "url": "https://github.com/samw_pacol/enf-switch-scripting-context/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}