switch-scripting-context

AI coding assistant context for Enfocus 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 for what's changed between versions.

Usage

Run init in any Switch scripting project:

npx @enfocussw/switch-scripting-context init

Or as a dev dependency, to pin the docs version:

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 26.05 → 26.5.0). Note that semver forbids leading zeros, so 26.05 is published as 26.5.
• 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:

# 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:

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