ts2077 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.0.2
+
+- The README and the guide are written for people installing the package.
+- Published files no longer include a path from the machine that generated them.
+
 ## 1.0.1
 
 - `create`, `init`, and `build` write `tsconfig.json`. The editor reads that file and then the client or server project, so `@open77/sdk/client` and the native declarations resolve.

package/README.md

@@ -1,71 +1,73 @@
 # TS77
 
-Compile OPEN//77 resources from TypeScript. Gameplay becomes Lua 5.4. A separate Node process runs backend services. React interfaces stay JavaScript inside the game's Chromium surface. Native names, parameters, and permissions come from the OPEN//77 Devkit catalogue, which in this workspace is **2.50.0+op77.148**.
+Write OPEN//77 plugins in TypeScript. TS77 compiles the client and the server to Lua 5.4, writes the `open77.lua` manifest, and can build a React page and an optional Node companion.
 
-The long-form guide is in [docs/README.md](docs/README.md). [docs/index.html](docs/index.html) is the same guide as one page for GitHub Pages: set the site source to the `/docs` folder on the branch you publish.
+The game runs the Lua. It does not run TypeScript. A web page cannot call natives. The server decides anything a player can gain.
 
-The server sandbox has no global `require` and no `debug` library. The compiler bundles each side into one Lua file and keeps source maps on your machine.
-
-## Requirements
-
-- Node.js 20 or newer
-- The Devkit index cache created by `npx -y @open2077/mcp init --server-dir <server>`
-
-## Install
-
-```bash
-npm install
-npm run build:tools
-```
-
-`build:tools` compiles the compiler and regenerates `packages/types/generated` from the Devkit index.
+The full guide is at [imviloh.github.io/TS77](https://imviloh.github.io/TS77/).
 
 ## Create a plugin
 
-The npm package name is `ts2077`. The commands it installs are `ts77` and `open77-ts`.
+You need Node.js 20 or newer. A plugin with a Node companion needs Node.js 22 for that process.
 
 ```bash
 npx ts2077 create my_plugin --template basic --no-install
 cd my_plugin
 npm install
 npm run dev
-npm run build
 ```
 
-`npm run dev` watches TypeScript and rebuilds Lua. Add `--server <server-directory>` at create time, or later run `npx ts2077 deploy --server <server-directory>`, to copy the resource into that server's `resources` folder. TS77 does not reload the dedicated server.
+The npm package is `ts2077`. It installs the `ts77` and `open77-ts` commands. `npm run dev` watches `src/` and rebuilds Lua when you save.
+
+Open the folder in your editor. `tsconfig.json` is already there, so `@open77/sdk/client` and the native declarations resolve.
+
+The folder name is the resource name: a lowercase letter, then letters, digits, or underscores, 3 to 64 characters. `my_plugin` is valid. `my-plugin` is not.
+
+| Template | What you get |
+|---|---|
+| `basic` | A client and a server that print a greeting. No network permission. |
+| `gameplay` | One typed event from the client to the server and back. |
+| `webui` | Gameplay plus a React page in `ui/`. |
+| `fullstack` | Gameplay, a React page, and a Node companion. |
 
 ```bash
-npx ts2077 create my_resource --template basic
 npx ts2077 create my_job --template gameplay
 npx ts2077 create my_hud --template webui
 npx ts2077 create my_notes --template fullstack
 ```
 
-The directory name and `open77-ts.json` `name` must match: a lowercase letter, then letters, digits, or underscores, 3 to 64 characters.
+## Commands
+
+Inside the plugin, `package.json` already has these scripts:
 
 ```bash
-npx ts2077 build my_resource
-npx ts2077 watch my_resource
-npx ts2077 validate my_resource
-npx ts2077 doctor my_resource
+npm run dev
+npm run build
+npm run deploy
+npm run validate
 ```
 
-`init` writes the basic template into an existing directory. `dev` watches TypeScript and, when `ui/` has Vite installed, starts the WebUI dev server at `http://127.0.0.1:5173/`.
+The same actions from any directory:
 
-To copy a built resource into a server, set `serverResourcesDir` in `open77-ts.json` and run `npx ts2077 build <resource> --deploy`. Reloading a running server is a console command on that server (`reload <name>`). This CLI does not send it. Inside this repository, `npx open77-ts` runs the same local program.
+```bash
+npx ts2077 build my_plugin
+npx ts2077 watch my_plugin
+npx ts2077 validate my_plugin
+npx ts2077 doctor my_plugin
+```
 
-## Write gameplay
+`build` writes `open77.lua`, `dist/client/main.lua`, and `dist/server/main.lua`. Leave those files alone. Change the TypeScript and build again.
 
-Client code lives in `src/client`, server code in `src/server`, and modules imported by either side in `src/shared`. Shared modules are copied into each bundle. They are not `shared_script` files and they do not call `require` at runtime.
+## Gameplay
+
+Client code is `src/client`. Server code is `src/server`. Code imported by both is `src/shared`.
 
 ```ts
-import { emitServer, onClientResourceStart, onNet } from "@open77/sdk/client";
+import { onClientResourceStart } from "@open77/sdk/client";
 import { greet } from "../shared/greeting";
 
 onClientResourceStart(() => {
     print(greet(GetCurrentResourceName()));
-    const ok = emitServer("demo:ping", { text: "Night City" });
-    if (!ok) print("demo:ping was not sent");
 });
 ```
 
@@ -79,95 +81,22 @@ onNet("demo:ping", (payload) => {
 });
 ```
 
-`authenticatedPlayer()` reads the server-assigned `source`. A client cannot choose that id. Check payload fields before using them, and do not let a client grant money, items, or character changes.
+`authenticatedPlayer()` is the server-assigned player. A client cannot choose that id. Check the payload before you use it.
 
-Natives are the real catalogue functions. `Open77.webui.create`, `TriggerServerEvent`, and `TriggerClientEvent` are called with a dot. Page methods such as `page:send` use a colon. A native that returns a value and a reason is destructured so both Lua results are kept:
+Natives come from the OPEN//77 catalogue shipped with this package, **2.50.0+op77.148**. A client file cannot call `TriggerClientEvent`. A server file cannot call `TriggerServerEvent`. `class`, `async`, and Node.js imports are compile errors in gameplay.
 
-```ts
-const [page, reason] = Open77.webui.create({ entry: "web/index.html" });
-const [ok, failure] = TriggerClientEvent("demo:pong", playerId, payload);
-```
-
-`tsconfig.json` points the editor at `tsconfig.client.json` and `tsconfig.server.json`. Those two files are rewritten on each build and point at the generated declarations, so completion follows the catalogue.
-
-A client file cannot see `TriggerClientEvent`. A server file cannot see `TriggerServerEvent`. `class`, `async`, `Promise`, `Map`, `Set`, and Node.js imports are compile errors.
-
-The build writes `open77.lua` with the Lua files that were actually produced and the permissions of the natives it found. `network.events` is added when the resource sends or receives network events. Empty script globs are not written.
-
-## React WebUI
-
-The `webui` template and `examples/hello_world` put a Vite React app in `ui/`. `npm run build` inside `ui/` writes `web/`, and the manifest lists those files one by one. The page talks to Lua through the documented bridge:
-
-```ts
-window.Open77?.on("hud:state", (payload) => render(payload));
-window.Open77?.emit("hud:ping", { text: "Night City" });
-window.Open77?.ready();
-```
-
-Lua listens with `page.on` and sends with `page.send`. For Vite during development, build with `--dev` or set the WebUI entry to `http://127.0.0.1:5173/`. That address is the player's PC. Call `Open77.ready()` again after a hot reload so Lua can send the current state.
-
-`hud` and `menu` do not need a WebUI permission. `modal`, `system`, and `debug` do, and the helper does not offer them.
-
-## Targets
-
-A resource lists the runtimes it actually builds. The defaults are client Lua, server Lua, a WebUI when `web.root` is set, and a Node companion when `backend` is set.
-
-| Target | Result |
-|---|---|
-| `open77-client` | One Lua 5.4 client bundle |
-| `open77-server` | One Lua 5.4 server bundle |
-| `node` | CommonJS from `src/backend`, run with Node.js 22 |
-| `webui` | Vite bundle from `src/webui` or `ui` |
-
-`@open77-ts/client`, `@open77-ts/server`, and `@open77-ts/shared` are compiled into Lua. `@open77-ts/shared` in gameplay is the contract module: plain values and checks, no Node APIs. `@open77-ts/node` is the companion and is rejected in a Lua or page build. `@open77-ts/webui` is the page bridge and is rejected in Lua. The older `@open77/sdk/client` and `@open77/sdk/server` names still resolve.
-
-`npx open77-ts create my_notes --template fullstack` writes `src/client`, `src/server`, `src/backend`, `src/webui`, and `src/shared`. `dev` rebuilds those targets, restarts `dist/backend/index.js` when that file exists, and starts Vite when its dependencies are installed. Set `OPEN77_BRIDGE_SECRET` in the environment before starting the companion. The game server reads the same value from the `open77_bridge_secret` convar or from that resource's tunable. Leave it empty and the server reports `bridge_secret_missing` instead of calling out.
-
-The companion listens on `127.0.0.1:11782` unless `OPEN77_BRIDGE_PORT` is set. The dedicated server must enable outbound HTTP and allow that host:
-
-```jsonc
-"http": { "enabled": true, "allowedHosts": ["127.0.0.1"] }
-```
-
-`http.allowedHosts` is a hostname, not a URL. Inbound calls from Node use `httpHandlers` and `Open77.http.listen`, which is off until the operator enables it. `OPEN77_NOTES_DRIVER` may be `memory` (the default), `mysql`, `postgres`, or `redis`. The database URL is `OPEN77_DATABASE_URL`. File reads stay inside the root configured on the companion and reject `..`.
-
-`examples/player_notes` is the full path: the React page emits `notes:submit`, client Lua sends `notes:save`, the server checks `authenticatedPlayer()` and the text, `Open77.http.request` calls `notes.save`, and the page renders the saved text or `backend_offline`. The page's health `fetch` does not save anything. Saving does not grant money, items, or vehicles. No play session in Cyberpunk 2077 was run for this example.
-
-## Debugging
-
-Type errors name the TypeScript file and line. Lua is formatted by TypeScriptToLua and carries a source map next to the bundle. The sandbox cannot run `debug.traceback`, so the map is applied by the CLI:
+## Deploy
 
 ```bash
-npx open77-ts map examples/hello_world/dist/server/main.lua 120
+npx ts2077 deploy --server <server-directory>
 ```
 
-When the map has a position, the output looks like:
-
-```text
-[OPEN77-TS] Resource: hello_world
-
-Runtime Error:
-src/shared/greeting.ts:2
-```
+`<server-directory>` is the folder that contains `server.jsonc`. TS77 copies the built resource into `resources/<plugin>` inside it. Restart that resource on the server afterward. TS77 does not reload the server.
 
-## Updating OPEN//77
+## React and Node
 
-When a newer Devkit index is published, refresh the MCP cache and run `npm run generate` (or `npx open77-ts types`). Declarations, permissions, and reserved event prefixes are rewritten from that index. Do not hand-edit `packages/types/generated`.
-
-## Example
-
-`examples/hello_world` is a client, a server, a shared greeting module, a typed ping, and a React HUD.
-
-- The server registers `/hello` with `RegisterCommand`. Arguments arrive as strings. A console `source` of `0` is not sent to a client, because target `0` is a host error.
-- The page emits `hud:ping`. The client sends `hello:ping`. The server checks the payload and replies to `authenticatedPlayer()` with `hello:notice`.
-- The client updates the HUD with `page.send`.
-
-```bash
-npx open77-ts build examples/hello_world
-npx open77-ts validate examples/hello_world
-npm test
-```
+A `webui` plugin keeps its page in `ui/`. Run `npm install` there before the first page build. The page uses `window.Open77` only: `ready`, `on`, `emit`, and `invoke`.
 
-Build, Lua parse, call syntax, the `require` shim, and source-map lookup are covered by `npm test`. `open77_validate` is the Devkit's static check. Neither one replaces joining the server in Cyberpunk 2077.
+A `fullstack` plugin adds `src/backend`. Set `OPEN77_BRIDGE_SECRET` to the same value on Node and on the game server before the companion will accept a call. Databases and other npm packages belong in that process, not in Lua.
 
-See [docs/limitations.md](docs/limitations.md) for the runtime restrictions and what this project does not claim.
+Details, the native index, and the companion protocol are in the [guide](https://imviloh.github.io/TS77/).

package/docs/README.md

@@ -1,6 +1,6 @@
 # TS77 documentation
 
-These files are the local reference for this repository. The same material is also published as one page at [index.html](index.html), which is what GitHub Pages serves when the site source is the `/docs` folder.
+The published guide is [index.html](index.html), also served at [imviloh.github.io/TS77](https://imviloh.github.io/TS77/).
 
 The catalogue this tree was generated from is **2.50.0+op77.148**. Natives, permissions, and reserved event names come from that index. They are not invented.
 
@@ -22,4 +22,4 @@ The catalogue this tree was generated from is **2.50.0+op77.148**. Natives, perm
 | [Examples](examples.md) | `hello_world` and `player_notes`, end to end |
 | [Limitations](limitations.md) | What the sandbox and this toolchain do not do |
 
-Start with [Install](install.md), then [Commands](commands.md). The player-notes walkthrough is in [Examples](examples.md).
+Plugin authors should start at the [published guide](https://imviloh.github.io/TS77/). [Install](install.md) also covers building this repository. [Commands](commands.md) lists every flag. The player-notes walkthrough is in [Examples](examples.md).

package/docs/debugging.md

@@ -8,7 +8,7 @@ A Node entry that imports `@open77-ts/client` fails before `tsc` runs, with `Nod
 
 ## Lua that does not parse
 
-`validate` parses each bundle with luaparse. `open77_validate` from the Devkit compiles them with the server's own Lua when the server is installed. The notes resource has been compiled that way against binary 2.50.0+op77.156. That check is static. It does not start a session.
+`validate` parses each bundle. `open77_validate` from the Devkit compiles them with the server's Lua when a server is installed. That check does not start a session.
 
 The manifest is not Lua. Do not run it through a Lua parser.
 

package/docs/examples.md

@@ -1,7 +1,5 @@
 # Examples
 
-Neither example has been played inside Cyberpunk 2077 as part of this repository's checks. `npm test` compiles them. `open77_validate` has compiled `hello_world` and `player_notes` with the server's Lua. Join a server before treating gameplay as verified.
-
 ## hello_world
 
 `examples/hello_world` is a client, a server, a shared greeting, and a React HUD in `ui/`.

package/docs/guide/deployment.md

@@ -10,6 +10,6 @@ The server directory is the folder that contains `server.jsonc`. The resources d
 
 If that field is missing, deploy stops and tells you. It does not guess a server and it does not copy the resource somewhere else.
 
-After a successful copy, restart the resource on the OPEN//77 server. TS77 does not call a reload API. A live reload was not available as a verified command in this toolchain.
+After a successful copy, restart the resource on the OPEN//77 server. TS77 does not reload the server.
 
 The copy does not include `node_modules`, `src`, or `.env`. The Node companion is a separate process. Start it with `npm run dev` on the machine that should run it, with `OPEN77_BRIDGE_SECRET` set in that environment.

package/docs/index.html

@@ -703,7 +703,7 @@ const db = require("rethinkdb");</pre>
 <section id="limits">
   <h2>Limits</h2>
   <p>The dedicated server sandbox has no <code>require</code>, <code>os</code>, <code>io</code>, <code>debug</code>, <code>package</code>, <code>load</code>, or <code>collectgarbage</code>. The client also removes <code>setmetatable</code>. Bundles inline their helpers and do not fall back to a global <code>require</code>.</p>
-  <p>This page and the tests were checked by compiling Lua and by installing a packed <code>ts77</code> on Windows. A Cyberpunk 2077 session was not joined, so in-game rendering, a live reload, and a live database server are unverified. Linux CI is described in the repository workflow and was not executed in this workspace.</p>
+  <p>Declarations in this package follow catalogue 2.50.0+op77.148. A native added in a later server build is not declared until that catalogue is updated.</p>
   <footer>TS77 · catalogue 2.50.0+op77.148 · declarations generated from the OPEN//77 Devkit index · 1595 declared natives · 164 omitted</footer>
 </section>
 </main>

package/docs/install.md

@@ -1,8 +1,21 @@
 # Install
 
-## What you need
+## Install the package
 
-- Node.js 20 or newer to run the compiler. The companion process is written for Node.js 22 or newer. `open77-ts doctor` fails below 20 and warns below 22.
+Node.js 20 or newer. A Node companion needs Node.js 22.
+
+```bash
+npx ts2077 create my_plugin --template basic --no-install
+cd my_plugin
+npm install
+npm run dev
+```
+
+The npm package is `ts2077`. The commands are `ts77` and `open77-ts`. The rest of this page is for working on the TS77 repository itself.
+
+## What the repository build needs
+
+- Node.js 20 or newer. `ts77 doctor` fails below 20 and warns below 22.
 - An OPEN//77 dedicated server if you want to deploy a resource. Compiling a plugin does not require one.
 - The Devkit index produced by:
 

package/docs/limitations.md

@@ -1,6 +1,6 @@
 # Limitations
 
-This toolchain targets the OPEN//77 catalogue it was generated from. In this workspace that catalogue is **2.50.0+op77.148**. A newer server binary can exist. A native that exists only in a later build is not declared, and a native removed from the catalogue is not invented.
+This package targets OPEN//77 catalogue **2.50.0+op77.148**. A native added in a later server build is not declared until that catalogue is updated. A native removed from the catalogue is not invented.
 
 ## Runtime
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts2077",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "TypeScript framework for OPEN//77 plugins. Compiles gameplay to Lua 5.4 and can host a React WebUI and an optional Node companion.",
   "license": "MIT",
   "repository": {

package/packages/types/dist/generate.js

@@ -302,7 +302,6 @@ function renderRuntime(runtime, cards, build, skipped) {
         `/**`,
         ` * OPEN//77 ${runtime} declarations for catalogue build ${build}.`,
         ` * Generated from the official Devkit index. Do not edit by hand.`,
-        ` * Regenerate with \`npm run generate\` inside the TS77 repo.`,
         ` */`,
         `/// <reference path="./tstl-language-extensions.d.ts" />`,
         ``,
@@ -435,7 +434,6 @@ function main() {
     const reserved = [...new Set((events.reservedPrefixes ?? []).map((entry) => entry.prefix))].sort();
     const catalogue = {
         build,
-        indexDir: directory,
         omittedUnavailable: omitted,
         skipped,
         reservedPrefixes: reserved,