Apply PitchScript runtime and compatibility fixes

README.md

@@ -1,91 +1,103 @@
 # PitchScript
 
-A TypeScript implementation of the DexScript DSL for FCDex.
+PitchScript is a TypeScript port of the DexScript command DSL, adapted for the FCDex Prisma models. The syntax stays command-oriented; scripts are still plain text and are not JavaScript or TypeScript source code.
 
-PitchScript preserves DexScript's command-oriented syntax while
-providing integration with a TypeScript and Prisma-based codebase.
+## Current support
 
-## Development status
+PitchScript includes:
 
-PitchScript is under development. The parser, command handlers,
-and FCDex adapter must pass the build and compatibility tests
-before the package is considered ready for production.
+- The original command parser and sequential dispatcher.
+- Global model commands: `CREATE`, `DELETE`, `UPDATE`, `VIEW`, and `ATTRIBUTES`.
+- `FILTER` bulk update, delete, and view commands.
+- Saved PitchScript presets through `EVAL > SAVE`, `REMOVE`, `LIST`, and `RUN`.
+- `FILE` read, write, clear, list-directory, and delete commands.
+- The `TEMPLATE > CREATE` helper for the FCDex `CLUB` model.
+- A Discord.js message-command adapter and a Prisma-backed FCDex host.
 
-## Commands
+The FCDex registry currently exposes `CLUB` (mapped to Prisma's `Ball` model) and `SPECIAL`. `REGIME` and `ECONOMY` are not registered because they are not present as Prisma models in the supplied FCDex schema.
 
-### Global commands
+## Syntax
 
 ```text
-CREATE > MODEL > IDENTIFIER
-DELETE > MODEL > IDENTIFIER
-UPDATE > MODEL > IDENTIFIER > ATTRIBUTE > VALUE(?)
-VIEW > MODEL > IDENTIFIER > ATTRIBUTE(?)
-ATTRIBUTES > MODEL > FILTER(?)
-```
-
-### Filter commands
-
-```text
-FILTER > UPDATE > MODEL > ATTRIBUTE > OLD_VALUE > NEW_VALUE > TORTOISE_OPERATOR(?)
-FILTER > DELETE > MODEL > ATTRIBUTE > VALUE > TORTOISE_OPERATOR(?)
-FILTER > VIEW > MODEL > ATTRIBUTE > VALUE > TORTOISE_OPERATOR(?)
-```
+CREATE > CLUB > Manchester City
+UPDATE > CLUB > Manchester City > RARITY > T5
+VIEW > CLUB > Manchester City > RARITY
+ATTRIBUTES > CLUB
 
-### Saved evals
+FILTER > UPDATE > CLUB > RARITY > T5 > T3
+FILTER > DELETE > CLUB > RARITY > T5 > GT
+FILTER > VIEW > CLUB > RARITY > T5
 
-```text
-EVAL > SAVE > NAME
-EVAL > REMOVE > NAME
+EVAL > SAVE > rarity-update
+EVAL > RUN > rarity-update
 EVAL > LIST
-EVAL > RUN > NAME
-```
-
-Saved evals contain PitchScript source and are executed by the
-PitchScript interpreter.
+EVAL > REMOVE > rarity-update
 
-### File commands
+FILE > READ > README.md
+FILE > WRITE > output.txt
+FILE > CLEAR > output.txt
+FILE > LISTDIR
+FILE > DELETE > output.txt
 
-```text
-FILE > READ > FILE_PATH
-FILE > WRITE > FILE_PATH
-FILE > CLEAR > FILE_PATH
-FILE > LISTDIR > FILE_PATH(?)
-FILE > DELETE > FILE_PATH
+TEMPLATE > CREATE > CLUB > Manchester City
 ```
 
-### Templates
+To execute a script in Discord, mention the bot and use `run`, for example:
 
 ```text
-TEMPLATE > CREATE > MODEL > ARGUMENT(?)
+@FCDex run VIEW > CLUB > Manchester City > RARITY
 ```
 
-## TypeScript integration
-
-PitchScript exposes a parser, dispatcher, command handlers,
-and an FCDex adapter through its package entry point.
-
-The database adapter must be configured against the target
-application's actual Prisma schema.
+The Discord adapter restricts commands to the configured `ownerIds`, matching the owner-only behavior of the original DexScript command.
 
-## Development
+## Installation and build
 
-Install dependencies:
+Node.js 20 or newer is required.
 
 ```bash
 npm install
+npm run build
+npm test
 ```
 
-Build the package:
-
-```bash
-npm run build
+## FCDex integration
+
+Create the Prisma-backed engine and register the message handler:
+
+```ts
+import { Client } from "discord.js";
+import { PrismaClient } from "./generated/prisma/client.js";
+import {
+  createFCDexPitchScript,
+  registerPitchScriptDiscord,
+} from "pitchscript";
+
+const client = new Client({ intents: [/* your configured intents */] });
+const prisma = new PrismaClient();
+
+const pitchScript = createFCDexPitchScript(prisma, {
+  host: {
+    createDefaults: {
+      // capacity_logic is required by the supplied Prisma schema.
+      // Replace this empty object with the capacity logic your bot uses.
+      Club: { capacity_logic: {} },
+    },
+  },
+});
+
+registerPitchScriptDiscord(client, pitchScript, {
+  ownerIds: ["YOUR_DISCORD_USER_ID"],
+  repository: "YOUR_GITHUB_OWNER/PitchScript",
+});
 ```
 
-Run tests:
+The host stores uploaded images in the configured media directory. You can override the `saveAttachment` host option to match your deployment's storage layout.
 
-```bash
-npm test
-```
+**Schema note:** the supplied FCDex files disagree about `Ball.regime_id`: `prisma/schema.prisma` declares `regimeId BigInt?`, while `prisma/schema.sql` declares `regime_id bigint NOT NULL`. PitchScript follows the Prisma model and treats this field as optional; if your live database was created from the SQL snapshot, reconcile the mismatch before using `CREATE > CLUB`. The SQL snapshot also has no `Regime` table/model, so PitchScript does not invent a regime record or ID. PitchScript does not migrate your database.
+
+## Scope
+
+This repository contains the PitchScript library and Discord integration. It is not the FCDex web admin-panel UI itself; the admin panel must integrate the engine and host with its own routes and permissions.
 
 ## License