@enfocussw/switch-scripting-context 0.1.0

package/README.md

@@ -0,0 +1,192 @@
+# 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 10 AI coding agents (Claude Code, GitHub Copilot, Cursor, Codex CLI/OpenCode/Pi, Gemini CLI, Windsurf, Zed, Cline, Continue, and Aider) so AI assistants understand the Switch scripting API out of the box.
+
+See [CHANGELOG.md](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@0.1.0/CHANGELOG.md) (also 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@^0.1.0"
+npx switch-scripting-context init
+```
+
+Re-run after upgrading the package to refresh docs and AI config files.
+
+## 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"
+```
+
+## 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 behaviour, rather than hand-rolling the steps.
+- Editing the script's XML declaration. The agent follows the documented rules and knows which
+  properties (app path/licence) 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](https://cdn.jsdelivr.net/npm/@enfocussw/switch-scripting-context@0.1.0/CHANGELOG.md) for what changed.
+
+## What it does
+
+1. Copies the Switch API reference docs to `docs-for-agents/` in your project
+2. Generates AI config files for each tool (see below)
+3. Appends `docs-for-agents/` to `.gitignore`
+
+### Generated files
+
+| Tool | File | How context is loaded |
+|---|---|---|
+| Claude Code / ClawCode | `CLAUDE.md` | `@docs-for-agents/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` | `alwaysApply: true`; inline key rules + full API file path list |
+| Codex CLI / OpenCode / Pi | `AGENTS.md` | Inline key rules + full API file path list |
+| Gemini CLI | `GEMINI.md` | `@docs-for-agents/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 |
+| Continue | `.continue/rules/switch-scripting.md` | `alwaysApply: true`; inline key rules + full API file path list |
+| Aider | `.aider.conf.yml` | `read:` entry that loads the hub file read-only at startup |
+
+All files use `<!-- switch-scripting-context begin -->` / `<!-- switch-scripting-context end -->` markers, or `# switch-scripting-context begin` / `# switch-scripting-context end` in `.aider.conf.yml`. Re-running `init` replaces only the Switch section in existing files. Project-specific rules outside the markers are untouched.
+
+Two limits apply to Aider:
+
+- Start Aider from the project root. Aider resolves the `read:` path against the folder it starts in, so from a subfolder it skips the file and prints an error.
+- If your `.aider.conf.yml` already has a `read:` key, `init` leaves the file alone and prints the path to add to your list. A second `read:` key would replace your list, not extend it.
+
+## Options
+
+```
+npx switch-scripting-context init [options]
+
+  --tools <list>    Tools to configure. Default: all
+                    IDs: claude, copilot, cursor, codex, gemini, windsurf, zed, cline,
+                         continue, aider
+                    Aliases: opencode, pi (→ codex), clawcode (→ claude)
+  --docs-dir <dir>  Destination folder for docs. Default: docs-for-agents
+  --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
+```
+
+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`:
+
+```
+npx switch-scripting-context remove [options]
+
+  --tools <list>    Only remove these tools' config. Default: remove everything
+  --docs-dir <dir>  Docs folder to remove. Default: docs-for-agents
+  --dry-run         Print what would happen without writing any files
+```
+
+```bash
+# Stop configuring Cursor, keep everything else
+npx switch-scripting-context remove --tools cursor
+```
+
+## Versioning
+
+The package follows [semver](https://semver.org) for its own changes. The version does not say which
+Switch release the docs describe. The docs cover every Switch release with Node.js scripting, and
+mark which release added each API class, method, and enum value.
+
+- **Major** (`2.0.0`): you need to act before upgrading, for example because a tool ID was renamed
+  or a generated file moved. The changelog marks these entries **Breaking**.
+- **Minor** (`1.3.0`): new docs, new agents, or new CLI features.
+- **Patch** (`1.3.1`): corrections.
+
+Before 1.0.0 the package is in private beta. A `0.x` minor version may contain breaking changes,
+which is why `^0.1.0` only accepts `0.1.x` updates.
+
+Versions up to `25.11.1-beta.6` followed the Switch release numbering. They will be deprecated when
+1.0.0 is released.
+
+Versions before `25.11.1-beta.4` used `switch-docs/` as the folder name. Re-running `init` deletes that
+folder and its `.gitignore` line, so your agents do not find a second, stale copy of the docs. It
+only deletes a `switch-docs/` folder that `init` itself wrote. Pass `--docs-dir switch-docs` to
+stay on the old name.
+
+### Prereleases
+
+From 1.0.0 on, prereleases carry a suffix such as `1.3.0-beta.1` and are published under the
+`beta` tag. A plain install never picks them up. Install one with
+`npm install --save-dev "@enfocussw/switch-scripting-context@beta"`.
+
+## Included docs
+
+The `docs-for-agents/` folder contains:
+
+- `switch-scripting.md`: master index with execution environment rules and "load when" routing table
+<!-- docs-index:readme begin -->
+- `switch-project/project-planning.md`: Planning checklist, run before scaffolding or on a project that is already scaffolded: Script vs App, job-processing approach, one script folder or several, target OS, Switch version baseline, concurrency, native/binary npm dependencies, Appstore competition risk
+- `switch-api/entry-points.md`: All entry point signatures, constraints, and when each is called
+- `switch-api/switch.md`: `Switch` (`s`): global data, webhooks, abort, server utilities
+- `switch-api/flow-element.md`: `FlowElement`: properties, connections, job creation, logging
+- `switch-api/job.md`: `Job` **signatures**: routing, file access, child jobs, private data, datasets
+- `switch-api/connection.md`: `Connection`: type, properties, file count
+- `switch-api/http.md`: `HttpRequest` / `HttpResponse` + webhook pattern
+- `switch-api/enums.md`: All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.)
+- `switch-api/document-classes.md`: `PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument`: read-only file introspection
+- `switch-project/script-structure.md`: What files a script folder contains, laying out several script folders side by side, `manifest.xml` format, Script vs App, packing an app with SwitchScripter
+- `switch-project/tooling.md`: SwitchScriptTool commands and install paths, folder vs `.sscript` trade-offs, deployment
+- `switch-project/debugging.md`: Enabling debug mode in Switch Designer, debuggable entry points, VS Code attach
+- `switch-project/vscode.md`: Type declarations, tsconfig for TypeScript 6, ESLint rules, entry point snippets
+- `switch-project/script-declaration.md`: XML declaration reference: properties, connections, execution config; agents may edit this file directly
+- `switch-project/property-editors.md`: Property editor types, string return values, literal editors, dropdowns
+- `switch-api/job-patterns.md`: `Job` **rules and gotchas**: file access semantics, temp cleanup, which `sendTo*()` suits which connection type, dataset/child ordering, locking shared global data, executor limits
+- `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
+- `switch-api/logging.md`: Log level semantics, logging practice, `console.log` limitation, common gotchas
+- `switch-project/logs-and-dataroot.md`: Locating the Application Data Root, querying `ServerLogs.db3` directly
+- `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)
+- `switch-project/property-documentation.md`: Writing guidance for `Tooltip` and `DetailedInfo` content on properties/connections
+- `switch-appstore/app-store-listing.md`: Writing guidance for the declaration's Appstore listing fields: `Description`, `Compatibility`, `SupportInfo`, `AppDiscovery`, `Connections`
+- `switch-appstore/app-manual.md`: Writing guidance for the separate app manual document uploaded during Appstore review (`documentation-app_name.docx` template)
+- `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
+- `switch-api/api-versions.md`: Which Switch release added each scripting API class, method, and enum value; API availability follows the running Switch, not `manifest.xml`
+- `switch-project/node-versions.md`: How `SwitchVersion` in `manifest.xml` selects the Node.js version, the version table per Switch release, which tools overwrite `SwitchVersion`, values missing from the table, other effects of `SwitchVersion`
+<!-- docs-index:readme end -->

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,78 @@
+export interface Markers {
+    begin: string;
+    end: string;
+}
+export interface ToolFile {
+    targetPath: (root: string, docsDir: string) => string;
+    generate: (docsDir: string) => string;
+    /** Comment syntax around the generated section. Default: HTML comments, for Markdown files. */
+    markers?: Markers;
+    /**
+     * Checks an existing file that has no Switch section yet. Returns why appending one would break
+     * the file, or null when appending is safe. init then skips the file and prints the reason.
+     */
+    appendConflict?: (existing: string, docsDir: string) => string | null;
+    /**
+     * Frontmatter that earlier versions generated above the marker. init replaces it and remove
+     * deletes it like the current frontmatter, instead of keeping it as if the user had edited it.
+     */
+    previousFrontmatter?: string[];
+}
+export interface ToolDefinition {
+    id: string;
+    label: string;
+    aliases?: string[];
+    altIds?: string[];
+    files: ToolFile[];
+}
+export interface ApiDoc {
+    /** Path within docs/, e.g. "switch-api/job.md". */
+    file: string;
+    /** The routing table's "Load when" text, verbatim. */
+    loadWhen: string;
+}
+/**
+ * The routing table in docs/switch-scripting.md is the single source of truth for
+ * which API docs exist and when to load each one. Everything the CLI generates is
+ * derived from it, so a new doc file needs registering in exactly one place here
+ * (plus README.md, which init.test.ts checks).
+ */
+export declare function parseRoutingTable(root?: string): ApiDoc[];
+/** Filenames only, in routing-table order. */
+export declare function apiFiles(root?: string): string[];
+/**
+ * The bullets under "## Key rules" in docs/switch-scripting.md, verbatim. Like the routing table,
+ * the hub is the single source: tools that get the rules inlined see exactly what the hub says.
+ */
+export declare function parseKeyRules(root?: string): string;
+/**
+ * Rewrites each backticked doc path (`switch-api/job.md`, `switch-project/`) to start with the
+ * docs folder, so it resolves from the project root rather than from the hub's own folder.
+ */
+export declare function prefixDocPaths(text: string, docsDir: string): string;
+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 generateContinueRule(docsDir: string): string;
+export declare function generateAiderConf(docsDir: string): string;
+/**
+ * A second top-level read key would not merge with the user's own: Aider keeps only the last
+ * one, so appending ours would silently drop every file the user already loads.
+ */
+export declare function aiderReadConflict(existing: string, docsDir: string): string | null;
+export declare function buildIdMap(registry: ToolDefinition[]): Map<string, string>;
+export declare function findMarkerRange(content: string, markers?: Markers): [number, number] | null;
+/** The running package's own version, so a git-clone install stamps what actually ran. */
+export declare function packageVersion(root?: string): string;
+/** The comment init writes as the first line of the copied hub file. */
+export declare function versionStamp(version: string): string;
+/**
+ * Drop the `docsDir/` line init added, together with the comment line directly above it.
+ * The comment and the path are matched as one unit so that a project carrying entries for
+ * two docs folders (one left by an older version, one current) keeps the comment belonging
+ * to the entry that stays.
+ */
+export declare function stripGitignoreEntry(content: string, docsDir: string): string;
+export declare function run(argv?: string[]): Promise<void>;