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

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to this package are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [25.11.0-beta.10] - 2026-09-03
+
+### Added
+- `api-job-patterns.md` — documented a known ordering bug: creating a child job before writing a
+  pending dataset causes the child to inherit the stale dataset, leading to a destructive
+  file-move race at `sendTo*()`. `api-job.md`'s dataset/child-job entries now note which calls
+  are immediate vs. deferred.
+
+## [25.11.0-beta.9] - 2026-08-26
+
+### Added
+- `package.json` now declares `"main": "dist/init.js"`. Deliberately no `"exports"` field, so
+  `switch-scripting-context/package.json` also stays reachable for consumers that need to read the
+  package's own version (e.g. to compare against a script's target Switch version).
+
+### Changed
+- Package now publishes to the public npm registry instead of GitHub Packages.
+
+## [25.11.0-beta.8] - 2026-08-25
+
+### Removed
+- `init` no longer copies `.vscode/switch.code-snippets` (or removes it on `remove`) — Switch script folders already come with these snippets via `SwitchScriptTool --create`, so this package's own copy was redundant.
+- `snippets/switch.code-snippets` and `scripts/scrape_switch_docs.py` (unused internal tooling) removed from the repo.
+
+## [25.11.0-beta.7] - 2026-08-25
+
+### Added
+- README — "Using this with your coding agent" usage guide.
+
+### Fixed
+- `switch-scripting.md`'s routing table and the two hardcoded doc-list arrays in `src/init.ts` (used for Cursor's rules and the shared inline block for Codex/Windsurf/Zed/Cline) were missing `api-execution-environment.md`, `api-logging.md`, and `api-logs-and-dataroot.md` — those three docs were copied to `switch-docs/` but never referenced in 5 of the 8 tools' generated config, making them undiscoverable.
+
+## [25.11.0-beta.6] - 2026-08-25
+
+### Added
+- `docs/switch-api/api-logs-and-dataroot.md` — locating the Application Data Root, querying `ServerLogs.db3` directly (schema, `%N` placeholder reconstruction, retention, and the debug-level logging gate) to diagnose or validate a script from its actual log output.
+
+## [25.11.0-beta.5] - 2026-08-25
+
+### Added
+- `docs/switch-api/api-tooling.md` — `--generate-translations` command, `ScriptID` character constraint, macOS fallback binary path.
+
+### Fixed
+Corrections found by live-testing `SwitchScriptTool` (create/pack/unpack/list/verbose) against `api-tooling.md`:
+- Clarified `--transpile` is only needed for testing a script folder in Switch, not before packing — `--pack` always transpiles `main.ts` fresh and never touches an existing `main.js` in the source folder.
+- Documented that `--pack` always excludes `package.json`/`.vscode/` from the package, and strengthened the `npm prune --production` advice with the concrete reason (unpruned `devDependencies`, especially `@types/*`, get bundled for no runtime benefit).
+- Documented that `--unpack` strips `main.js`/`main.js.map` back out for a TypeScript-sourced package and prints `Type`/`Protection`/`Status` metadata.
+- Clarified `--create` scaffolds into a new `<Path>/<ScriptID>/` subfolder, not into `<Path>` directly.
+
+## [25.11.0-beta.4] - 2026-08-25
+
+### Added
+- `docs/switch-api/api-execution-environment.md` — process/concurrency model, state persistence across job invocations, unhandled-rejection behavior, npm/native module constraints.
+
+### Known issue
+- `docs/switch-api/api-document-classes.md` — flagged that `PdfPage.getArtBoxHeight`/`getArtBoxWidth` (and the `PdfDocument` static equivalents) currently return the crop box value instead of the art box, due to a bug on the Switch side.
+
+### Fixed
+Corrections found by auditing the docs against the actual API/runtime source:
+- `api-execution-environment.md` — corrected the concurrency model: `NumberOfSlots`/`ExecutionGroup` gate job dispatch on the Switch Server per flow-element instance (or via a cross-element named lock for `Serialized` mode); they do not map to a dedicated Node.js OS process per slot. The executor process pool is sized independently and reused across jobs/elements.
+- `api-connection.md` — `getFileCount`'s `nested` parameter is optional (defaults to `true`), not required. Tightened `getId()`'s stability description (renaming the flow is safe; renaming the flow element is not).
+- `api-job.md` — `processLater`'s `seconds` parameter is optional (defaults to `300`). `sendToChannel` throws synchronously on no-subscriber/empty args rather than failing the job. Documented that `getPrivateData`/`listDatasets`/`getDataset` throw on jobs from `getJobs()`, while `setPrivateData`/`removePrivateData` are not restricted. Documented that `getxmlData`/`getxmpData`/`getJdfData`/`getJSONData` resolve to `undefined` on error rather than throwing.
+- `api-flow-element.md` — `createPathWithName`'s `createFolder` parameter is required, not optional; corrected its return-value description (empty string only on a caught exception, not because the path already exists). `getFileCount`'s `nested` parameter is optional (defaults to `true`). Documented `failProcess`'s and `getJobs`'s throw conditions. Corrected `createJob`'s supported entry points (`jobArrived`/`timerFired` only). Documented `getPluginResourcesPath`'s local-only `.sscript` behavior and throw case.
+- `api-http.md` / `api-switch.md` — fixed the `httpRequestSubscribe` example to use a leading-slash path; documented the path-format validation and `httpRequestUnsubscribe` example.
+- `api-switch.md` — `getGlobalData` returns `''` for a missing tag, not `undefined`; documented the 100-call advisory warning. Documented `getPreferenceSetting`'s field redaction and JSON-stringify behavior, and `getServerVersion`'s `major + minor/100` numeric format.
+- `api-document-classes.md` — documented `XmlDocument.evaluate()`'s `object` return case, the `jdf` default-namespace prefix, and `ImageDocument.getICCProfile()`'s EXIF fallback.
+- `api-property-editors.md` / `api-script-declaration.md` — corrected `getPropertyType()`'s description (returns one of several `PropertyType` values, not a literal-vs-user-entered flag) and noted the XML `Type` vocabulary doesn't map one-to-one onto the runtime `PropertyType` enum.
+
+## [25.11.0-beta.3] - 2026-08-25
+
+### Added
+- `docs/switch-api/api-logging.md` — log level semantics, logging practice, `console.log` limitation.
+- `docs/switch-api/api-property-editors.md` — "Common practices" section recommending editor chains by property kind.
+- `docs/switch-api/api-script-declaration.md` — clarified that `ApplicationPath`/`ApplicationLicense` are app-only properties set by the user via the Switch Scripter GUI after packing, not by editing the declaration file.

package/README.md

@@ -0,0 +1,151 @@
+# switch-scripting-context
+
+AI coding assistant context for [Enfocus Switch](https://www.enfocus.com/en/switch) scripting projects (Node.js/TypeScript).
+
+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.
+
+See CHANGELOG.md (included in this package) for what's changed between versions.
+
+## Usage
+
+Run `init` in any Switch scripting project:
+
+```bash
+npx @enfocussw/switch-scripting-context init
+```
+
+Or as a dev dependency, to pin the docs version:
+
+```bash
+npm install --save-dev "@enfocussw/switch-scripting-context@~25.11.0"
+npx switch-scripting-context init
+```
+
+Re-run after upgrading the package to refresh docs and AI config files.
+
+## Versioning
+
+The package version tracks the Switch release its docs describe:
+
+```
+25.11.0
+└─┬─┘ │
+  │   └── package revision for that Switch release
+  └────── Switch version (25.11)
+```
+
+- `25.11.x` — every release of this package documenting **Switch 25.11**. Patch increments are doc updates, fixes, and new features of the CLI itself.
+- The next Switch release moves the first two numbers (e.g. Switch 27.07 → `27.7.0`). Note that semver forbids leading zeros, so `27.07` is published as `27.7`.
+- **Pin with `~`, not `^`.** `~25.11.0` stays on Switch 25.11; `^25.11.0` would happily install `25.12.0`, which targets a different Switch release.
+
+### Prereleases
+
+Beta builds append a prerelease suffix — `25.11.0-beta.1`. These sort *below* `25.11.0`,
+so the beta line precedes GA and leaves `25.11.0` free for the first published release.
+
+## What it does
+
+1. Copies the Switch API reference docs to `switch-docs/` in your project
+2. Generates AI config files for each tool (see below)
+3. Appends `switch-docs/` to `.gitignore`
+
+### Generated files
+
+| Tool | File | How context is loaded |
+|---|---|---|
+| Claude Code / ClawCode | `CLAUDE.md` | `@switch-docs/switch-scripting.md` import — hub file routes to specific API docs on demand |
+| GitHub Copilot | `.github/copilot-instructions.md` | `#file:` reference to hub |
+| GitHub Copilot (scoped) | `.github/instructions/switch-scripting.instructions.md` | `applyTo: "**/*.ts"` — auto-attaches to every TypeScript file edit |
+| Cursor | `.cursor/rules/switch-scripting.mdc` | Inline key rules + full API file path list |
+| Codex CLI / OpenCode | `AGENTS.md` | Inline key rules + full API file path list |
+| Gemini CLI | `GEMINI.md` | `@switch-docs/switch-scripting.md` import |
+| Windsurf | `.windsurfrules` | Inline key rules + full API file path list |
+| Zed | `.rules` | Inline key rules + full API file path list |
+| Cline | `.clinerules` | Inline key rules + full API file path list |
+
+All files use `<!-- switch-scripting-context begin -->` / `<!-- switch-scripting-context end -->` markers. Re-running `init` replaces only the Switch section in existing files — project-specific rules outside the markers are untouched.
+
+## Using this with your coding agent
+
+Once `init` has run, just work normally — describe what you want in plain terms and prompt as you
+usually would. Your agent picks up the Switch context automatically (via `@import` for Claude
+Code/Gemini, or the inlined rules + file list for the others) whenever it's working in the project,
+and pulls in the specific API doc it needs for the task at hand on its own. You don't need to know
+the doc file names or tell it which one to read.
+
+A few things this gets you without asking for them by name:
+- Scaffolding a new entry point, handling a webhook, or reading/creating datasets and jobs — the
+  agent consults the matching API reference before writing the code.
+- Diagnosing why a script isn't behaving as expected — the agent knows it can locate and query
+  Switch's own log database (`ServerLogs.db3`) rather than only re-reasoning about the code.
+- Creating, packing, or deploying a script — the agent uses `SwitchScriptTool` with the documented
+  flags and behavior, rather than hand-rolling the steps.
+- Editing the script's XML declaration — the agent follows the documented rules and knows which
+  properties (app path/license) are off-limits and left to SwitchScripter's GUI instead.
+
+Re-run `init` after upgrading this package so the copied docs and generated config files catch up —
+see CHANGELOG.md for what changed.
+
+## Options
+
+```
+npx switch-scripting-context init [options]
+
+  --tools <list>    Tools to configure. Default: all
+                    IDs: claude, copilot, cursor, codex, gemini, windsurf, zed, cline
+                    Aliases: opencode (→ codex), clawcode (→ claude)
+  --docs-dir <dir>  Destination folder for docs. Default: switch-docs
+  --force           Overwrite existing AI config files instead of merging
+  --dry-run         Print what would happen without writing any files
+```
+
+Examples:
+
+```bash
+# Configure Claude Code and Copilot only
+npx switch-scripting-context init --tools claude,copilot
+
+# Configure for OpenCode (alias for codex)
+npx switch-scripting-context init --tools opencode
+
+# Configure Claude Code, Cursor, and Zed
+npx switch-scripting-context init --tools claude,cursor,zed
+
+# Preview without writing
+npx switch-scripting-context init --dry-run
+
+# Use a different docs folder name
+npx switch-scripting-context init --docs-dir ai-context
+```
+
+## TypeScript types
+
+This package does not bundle `@types/switch-scripting`. Add the type declarations to your project manually:
+
+```bash
+npm install --save-dev "https://github.com/enfocus-switch/types-switch-scripting/archive/refs/tags/v24.1.1-final.tar.gz"
+```
+
+## Included docs
+
+The `switch-docs/` folder contains:
+
+- `switch-scripting.md` — master index with execution environment rules and "load when" routing table
+- `switch-api/api-entry-points.md` — all entry point signatures and when each is called
+- `switch-api/api-job.md` — `Job` class: routing, file access, child jobs, private data, datasets
+- `switch-api/api-flow-element.md` — `FlowElement`: properties, connections, job creation, logging
+- `switch-api/api-switch.md` — `Switch` global: global data, webhooks, abort, server utilities
+- `switch-api/api-connection.md` — `Connection`: type, properties, file count
+- `switch-api/api-http.md` — `HttpRequest` / `HttpResponse` and webhook pattern
+- `switch-api/api-enums.md` — all enums with string values (`LogLevel`, `AccessLevel`, `Scope`, etc.)
+- `switch-api/api-document-classes.md` — `PdfDocument`, `ImageDocument`, `XmlDocument`, `XmpDocument`
+- `switch-api/api-script-declaration.md` — XML declaration reference
+- `switch-api/api-script-structure.md` — script folder/package structure and manifest format
+- `switch-api/api-tooling.md` — SwitchScriptTool commands, script folder vs package, build and deployment
+- `switch-api/api-debugging.md` — enabling debug mode, debuggable entry points, VS Code attach
+- `switch-api/api-logging.md` — log levels, when/what to log, `console.log` limitation, common gotchas
+- `switch-api/api-logs-and-dataroot.md` — locating the application data root, querying `ServerLogs.db3` directly to diagnose a script
+- `switch-api/api-vscode.md` — type declarations, tsconfig for TypeScript 6, ESLint rules
+- `switch-api/api-property-editors.md` — property editor types and string return values
+- `switch-api/api-job-patterns.md` — file access semantics, routing rules, child jobs, executor limits
+- `switch-api/api-execution-environment.md` — process model, state persistence across jobs, error handling, npm/native module constraints

package/bin/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+'use strict';
+
+const { run } = require('../dist/init.js');
+run().catch(err => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/init.d.ts

@@ -0,0 +1,19 @@
+export interface ToolFile {
+    targetPath: (root: string, docsDir: string) => string;
+    generate: (docsDir: string) => string;
+}
+export interface ToolDefinition {
+    id: string;
+    label: string;
+    aliases?: string[];
+    altIds?: string[];
+    files: ToolFile[];
+}
+export declare function generateAgentsMd(docsDir: string): string;
+export declare function generateGeminiMd(docsDir: string): string;
+export declare function generateWindsurfRules(docsDir: string): string;
+export declare function generateZedRules(docsDir: string): string;
+export declare function generateClineRules(docsDir: string): string;
+export declare function buildIdMap(registry: ToolDefinition[]): Map<string, string>;
+export declare function findMarkerRange(content: string): [number, number] | null;
+export declare function run(argv?: string[]): Promise<void>;