fvtt-world-cli 1.0.0

package/docs/skill.md

@@ -0,0 +1,65 @@
+# Agent skill
+
+fvtt-world-cli ships with `foundry-world-editor`, an installable Agent Skill — a short operating
+manual that teaches an AI agent to drive this CLI safely: how to bring the stack up and check its
+health, the read → preview → commit → verify loop, how to classify failures before retrying, and
+where the hard safety boundaries are. Skills follow the open Agent Skills standard, so the same
+file works in Claude Code, Codex, and every other agent that reads `SKILL.md` files.
+
+The skill deliberately contains no command inventory. Agents discover the exact command surface
+from the CLI itself (`commands --json`, `schema <command>`), so the skill stays valid as commands
+evolve; it carries only the knowledge that runtime discovery cannot provide. The skill itself lives
+at [`skills/foundry-world-editor/SKILL.md`](../skills/foundry-world-editor/SKILL.md).
+
+## Installing
+
+```bash
+fvtt-world-cli skill install
+```
+
+The default installation delegates to the ecosystem's skills CLI (`npx skills add`), which detects
+the agents present on the machine. It keeps one canonical copy under `~/.agents/skills` — the
+vendor-neutral location of the Agent Skills standard — and points each agent's own skill directory
+at it, so every agent reads the same single copy.
+
+An explicit destination works without the skills CLI or network access:
+
+```bash
+fvtt-world-cli skill install --to <skills-directory>
+```
+
+`--to` performs a direct copy and records the location in the CLI's local configuration, so that
+copy participates in updates later. `--link` symlinks instead of copying, which keeps the installed
+skill permanently identical to the CLI it came from.
+
+## Staying up to date
+
+The skill is versioned together with the CLI, and the CLI keeps installed copies current on its
+own: updating the npm package refreshes them, and the daemon performs the same check at startup for
+installations updated by other means, such as a git checkout. For updating purposes a copy is one
+of two kinds:
+
+- An **unmodified** copy — exactly what some version of the CLI shipped — is replaced silently with
+  the current version.
+- A **modified** copy — one with local edits — is never replaced automatically. It produces a
+  warning instead, and keeps producing it until the difference is resolved.
+
+The explicit update command follows the same rule and can override it:
+
+```bash
+fvtt-world-cli skill update
+fvtt-world-cli skill update --force
+```
+
+The CLI tells an old shipped version apart from a local edit by a content checksum recorded inside
+every installed copy, so an outdated installation is never mistaken for a customized one.
+
+## Removing
+
+```bash
+fvtt-world-cli skill remove
+fvtt-world-cli skill remove --to <skills-directory>
+```
+
+The default removal uninstalls the canonical copy, the agent links pointing at it, and every
+location recorded for `--to` installations; `--to` removes one location and forgets it.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "fvtt-world-cli",
+  "version": "1.0.0",
+  "description": "Safe local CLI and authenticated bridge for automating live Foundry VTT worlds.",
+  "license": "MIT",
+  "author": "DroiD16",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DroiD16/fvtt-world-cli.git"
+  },
+  "homepage": "https://github.com/DroiD16/fvtt-world-cli#readme",
+  "bugs": {
+    "url": "https://github.com/DroiD16/fvtt-world-cli/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "fvtt-world-cli": "./bin/fvtt-world-cli.js",
+    "worldctl": "./bin/fvtt-world-cli.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "docs/",
+    "skills/"
+  ],
+  "scripts": {
+    "test": "vitest run packages/cli/tests",
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --external:commander --external:pino --external:tsx --external:ws --external:zod --outfile=dist/index.js",
+    "typecheck": "tsc --project ../../tsconfig.json",
+    "prepack": "npm run build && node ./bin/prepare-package-assets.mjs",
+    "postpack": "node ./bin/prepare-package-assets.mjs --clean",
+    "postinstall": "node ./bin/sync-installed-skill.mjs"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "pino": "^9.6.0",
+    "tsx": "^4.23.12",
+    "ws": "^8.21.0",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@fvtt-world-cli/protocol": "1.0.0"
+  }
+}

package/skills/foundry-world-editor/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: foundry-world-editor
+description: Use when a request involves reading or changing anything in a live Foundry VTT world — or mentions fvtt-world-cli, worldctl, or the Foundry bridge/daemon.
+---
+
+# Foundry World Editor (fvtt-world-cli)
+
+`fvtt-world-cli` talks to a local authenticated daemon that relays typed commands to a bridge
+module running in an open GM Foundry browser session. Every mutation executes through Foundry's
+own Document APIs inside that session. Treat the world as concurrent state: users, game systems,
+modules, and hooks can change it between commands.
+
+## Health check
+
+Confirm the runtime before planning any work:
+
+```bash
+fvtt-world-cli system info --json
+```
+
+Proceed only when `.result.bridge.status` is `connected`, and verify the reported world and GM are
+the intended targets. If the daemon is not running, start `fvtt-world-cli bridge serve` as a
+persistent background process (it does not daemonize itself) and leave it running for the whole
+session. If no bridge connects, a GM must have the target world open in a browser with the
+`fvtt-world-cli` module enabled and paired.
+
+Pairing is a first-run trust decision that needs the human: ask the GM to open Module Settings →
+Authorization, name the browser in the `Browser label` field, and choose Pair; run
+`fvtt-world-cli auth pending`, confirm the listed Origin, world, GM, browser label, and client id,
+then `auth approve <code> --yes`. Never run bare `fvtt-world-cli auth`: that is the human's
+one-command pairing wait, it blocks until a request arrives or Ctrl+C ends it, and it refuses
+`--json` — hand that command to the GM at their own terminal instead of running it here. A pairing
+belongs to one browser, so the same GM on the same world can hold several records, and the label is
+chosen in the browser and fixed once paired. Labels are not unique and can render as nothing, so the
+client id is what tells concurrent requests apart and confirms that a re-pair replaces the record you
+meant; on a first pair it is newly minted, with nothing to match it against. Non-interactive use
+requires `--yes`, which prints no identity and skips the confirmation prompt: read all five fields
+from `auth pending` first, and never approve a request whose Origin, world, or GM you did not
+expect.
+
+`BRIDGE_NOT_READY` means the daemon is reachable but no GM client is connected yet. `BRIDGE_BUSY`
+means another paired browser holds the active bridge slot: clear it with
+`fvtt-world-cli bridge release` and have the GM choose Connect in the module's Authorization
+window or World CLI scene-controls group — do not start a new pairing.
+
+## Hard rules
+
+- Pass `--json` on every automated call.
+- Never edit Foundry world files on disk and never automate the Foundry browser UI; this CLI is
+  the control surface.
+- Address documents by `id`, never by name; names are not unique. Embedded ids are meaningful only
+  with their complete parent chain (actor → item → effect, scene → token → item).
+- Ownership changes go through dedicated `*.ownership.set` commands; raw `ownership` is rejected
+  in ordinary payloads.
+- The CLI cannot execute JavaScript, write settings, edit compendium packs in place, or reach
+  outside the managed file boundary, and executable region-behavior types are rejected on write.
+  Do not look for workarounds; report the limitation instead.
+
+## The working loop
+
+Discover → inspect schema → locate → read → smallest patch → dry-run → commit → verify. Never
+guess a command name or parameter.
+
+1. `fvtt-world-cli commands --json` lists the installed commands and marks mutations. Dotted
+   protocol names map to spaced CLI subcommands (`actor.item.update` → `actor item update`). A
+   command present in the registry but not advertised by the connected bridge is a client/bridge
+   version mismatch.
+2. `fvtt-world-cli schema <command>` shows the exact request parameters, required fields, enums,
+   and whether unknown fields are accepted; `fvtt-world-cli <command path> --help` maps flags.
+3. Locate targets with the narrowest query: a family `list --name <substring> --limit <n>` when
+   the family is known, `world.search` when it is not, `compendium.index` for one pack. Page with
+   `limit`/`offset` until `hasMore` is false. List and search rows are lean discovery projections,
+   never the basis of a write.
+4. `get` the complete target before mutating and work from the returned ids.
+5. Build the smallest valid patch. Nested objects merge recursively; plain arrays replace
+   wholesale; dotted paths reach permitted leaves; deletion operators remove permitted keys. Never
+   send a `get` result back as a patch — it contains read-only and derived fields the update
+   schema rejects. For arrays and extensible `system`/`flags` data: read, preserve everything that
+   stays, change only the intended part.
+6. Dry-run every nontrivial mutation with the global `--dry-run` flag. It runs the same
+   validation, sanitization, permission, capability, and security checks, then stops before
+   persistence; check both `ok` and `.result.dryRun`. A preview reports only what is knowable
+   before execution and reserves nothing.
+7. Commit with the same content. Attach `--idempotency-key <stable-key>` to any create, clone,
+   import, upload, or action that might be retried — one stable key per logical operation.
+8. Verify with a fresh read. This matters most after open-schema writes, bulk operations, and
+   actions, where confirmation can say less than an observed post-state.
+
+The whole loop in miniature:
+
+```bash
+fvtt-world-cli actor list --name "Goblin" --limit 10 --json
+fvtt-world-cli actor get --actor-id <id> --json
+fvtt-world-cli --dry-run actor update --actor-id <id> --name "Goblin Scout" --json
+fvtt-world-cli actor update --actor-id <id> --name "Goblin Scout" --json
+fvtt-world-cli actor get --actor-id <id> --json
+```
+
+## Reading results
+
+Success responses use `{ok: true, result}` and failures `{ok: false, error: {code, message,
+details}}`, alongside `protocolVersion`, `type`, and the correlation `id` (echoing your `id` in
+`exec --stdin` batches). Branch on `error.code`, never on message text.
+Documents live under a type-named key inside `result` that varies between commands but is stable
+for each one. `id` is the public identifier; a `_id` mirror may accompany it. Values requested
+through `include` flags may be derived or version-dependent — never write them back unless the
+update schema explicitly accepts them.
+
+## Retry classification
+
+Classify a failure before reacting:
+
+- Usage or validation error — fix the request.
+- Permission, safety, or capability error — a different operation or runtime is needed; retrying
+  the same call cannot succeed.
+- Not forwarded (connection refused, `BRIDGE_NOT_READY`) — safe to retry once the stack is
+  restored.
+- Forwarded but unresolved (`BRIDGE_TIMEOUT`, `BRIDGE_DISCONNECTED`, a timeout after send) — the
+  mutation may already have committed: inspect world state first, and reuse the same idempotency
+  key when retrying the same logical request. Never mint a new key because a response was lost.
+- Structured Foundry rejection — correct the content and resubmit as a new operation.
+
+## Bulk writes and actions
+
+Bulk commands (`create-many`, `update-many`, `delete-many`) share single-command validation but
+are not transactions: check the top-level `complete` flag and inspect every entry in `outcomes`.
+Persisted statuses such as `created`, `updated`, and `deleted` mean something different from
+`unchanged`, `alreadyDeleted`, `dropped`, and `unknown`; the authoritative status set lives in the
+protocol constants, not here. Action commands
+(playback, draws, deals, combat transitions, thumbnails, fog) call fixed typed Foundry methods and
+can trigger hooks, chat output, and system automation; read the schema, dry-run first, and
+interpret confirmation fields literally rather than assuming an ordinary update happened.
+
+## Managed files
+
+File commands address Foundry's managed `data` source only, and writes are confined to the active
+world's allowed tree. A file mutation never rewrites document fields: upload or move the asset,
+take the normalized returned path, update each document reference with an explicit document
+command, verify, and only then delete the old file. `world.audit-files` finds references to
+missing assets; it is not an orphan-file collector.
+
+## Context hygiene
+
+Large worlds overflow agent context fast. Use server-side filters and small pages, project
+responses with targeted `jq` expressions, fetch bounded id sets with `get-many`, and send
+independent batches through `exec --stdin` (one NDJSON response per request, each judged on its
+own). Request derived fields only when needed, and never dump a whole world, search index, or
+binary file into context.
+
+## Deeper reference
+
+`fvtt-world-cli docs` lists the durable contract documents shipped with the CLI, and
+`fvtt-world-cli docs <name>` prints one: `commands` (human overview and workflows), `protocol`
+(delivery, error, and session semantics), `security` (trust boundary), `compatibility` (Foundry
+version differences), `getting-started` (first-run pairing walkthrough). The runtime registry —
+`commands --json` and `schema` — always outranks prose.

package/skills/foundry-world-editor/SKILL.md.sha256

@@ -0,0 +1 @@
+9551cf818565ba2d70903bb4a28425b233c2b13cbc93625d61b37eb76ef0e0c4