fvtt-world-cli 1.0.0 → 1.1.1

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use for live Foundry VTT reads or edits, or work with fvtt-world-cli, worldctl, the bridge, or daemon.
 ---
 
 # Foundry World Editor (fvtt-world-cli)
@@ -29,7 +29,7 @@ Authorization, name the browser in the `Browser label` field, and choose Pair; r
 `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
+`--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
@@ -41,30 +41,58 @@ 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.
+window or World CLI scene-controls group. Keep the existing pairing.
+
+`UNSUPPORTED_PROTOCOL_VERSION` means the installed components come from different releases. Read
+`details.staleComponent`. Update the Foundry module for `module`. Update the CLI and restart the
+daemon for `cli-daemon`. Compare the reported versions for `unknown`.
 
 ## 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.
+- Keep all world edits in the CLI. Leave Foundry world files and the browser UI untouched.
 - 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 CLI cannot evaluate arbitrary JavaScript, edit compendium packs in place, or reach outside
+  the managed file boundary, and ordinary region-behavior writes reject executable types. Do not
+  look for workarounds; report the limitation instead.
+- Check stderr before diagnosing a hung command. An approval-listed command prints a waiting line
+  while the GM decides in Foundry. Deletions require approval by default.
+
+## Disabled commands
+
+Some commands ship denied. A command that `schema <command>` or `--help` knows but a
+`commands --json` listing with `policy.applied: true` omits is disabled by the GM of this bridge:
+report that it needs enabling in the Command permissions window instead of hunting for an
+equivalent. `macro.execute` is the only way to run code and is not a workaround for a missing
+command.
+
+## Command-specific cautions
+
+A macro that throws fails `macro.execute` with a partial outcome — read what it touched before
+retrying — while a macro that catches its own errors still returns `null`, which proves nothing;
+verify effects with reads, and treat `MACRO_TIMEOUT` as indeterminate — the macro may still be
+running.
+`setting.set` cannot touch this module's own namespace (`SETTING_PROTECTED` is final; never retry).
+When a setting write returns `requiresReload: true`, the change needs a GM-client reload to take
+effect; `system.reload` performs it, drops the bridge, and requires a reconnect wait before the
+next command. The reload commonly races its own result: the page can go away before the confirming
+`reloading: true` is delivered, so a disconnect or `APPROVAL_UNKNOWN` there is the expected success
+signal, not a failure — reconnect and continue rather than retrying the reload.
 
 ## 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.
+1. Run `fvtt-world-cli commands --json`. Continue only when `policy.applied` is `true` and the
+   required command is present. A `false` value means no bridge answered and the output is the static
+   registry, not the client's permissions. Report an absent command instead of seeking another way
+   to produce the same effect. Warn the user before a command marked `"approval": true`, and prefer
+   one `*-many` command when it can replace several approvals. Dotted protocol names map to spaced
+   CLI subcommands, such as `actor.item.update` to `actor item update`.
 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
@@ -73,16 +101,19 @@ guess a command name or parameter.
    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
+   wholesale; dotted paths reach permitted leaves; deletion operators remove permitted keys. A
+   `get` result contains read-only and derived fields, so build the patch from accepted fields only.
+   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.
+   before execution and reserves nothing. Approval does not hold a preview. A denied command still
+   fails, and `approvalRequired: true` means the commit will wait for the GM.
 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.
+   import, upload, or action that might be retried. Use one key per logical operation. After response
+   loss, follow the retry classification below because the delivery state determines whether to
+   reuse the key or create a fresh one.
 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.
 
@@ -103,22 +134,30 @@ details}}`, alongside `protocolVersion`, `type`, and the correlation `id` (echoi
 `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
+through `include` flags may be derived or version-dependent. Write them back only when 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.
+- Fix usage and validation errors before sending a new request.
+- Treat permission, safety, and capability errors as unavailable operations. Change the operation or
+  runtime instead of retrying the same call.
+- Connection refusal, `BRIDGE_NOT_READY`, and `IDEMPOTENCY_STORE_FULL` mean Foundry received nothing.
+  Retry after restoring the connection or after earlier keys settle. Reuse the same request and key.
+- `BRIDGE_TIMEOUT` and a response timeout after send are unresolved deliveries. Read world state
+  first. Reuse the same key only while the bridge session that carried the request remains connected.
+- `BRIDGE_DISCONNECTED` is indeterminate. Read world state, report the result, and use a fresh key if
+  the operation still needs to run.
+- `COMMAND_DENIED` means nothing ran and the command is unavailable in that client. Report the
+  limitation instead of seeking another command with the same effect.
+- `APPROVAL_DENIED`, `APPROVAL_TIMEOUT`, and `APPROVAL_CANCELLED` mean nothing ran. Report the outcome
+  and wait for user direction. `APPROVAL_QUEUE_FULL` also means nothing ran, but it can clear after
+  earlier requests settle.
+- `APPROVAL_UNKNOWN` and unconfirmed cancellation are indeterminate. Read the affected documents,
+  report the result, and use a fresh key if the operation still needs to run.
+- Correct a structured Foundry rejection and submit the corrected content as a new operation.
 
 ## Bulk writes and actions
 
@@ -152,5 +191,5 @@ binary file into context.
 `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.
+version differences), `getting-started` (first-run pairing walkthrough). The runtime registry in
+`commands --json` and `schema` always outranks prose.

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

@@ -1 +1 @@
-9551cf818565ba2d70903bb4a28425b233c2b13cbc93625d61b37eb76ef0e0c4
+1834777e1d540cb4cc11b6eac862ff99878a6e4920ebbc1e2599871893e19dc9

package/bin/sync-installed-skill.mjs

@@ -1,89 +0,0 @@
-import { createHash } from "node:crypto";
-import { cpSync, lstatSync, readFileSync, rmSync, statSync } from "node:fs";
-import { homedir, platform } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const SKILL_NAME = "foundry-world-editor";
-
-try {
-  const binDirectory = dirname(fileURLToPath(import.meta.url));
-  const sourceDirectory = [resolve(binDirectory, "../skills"), resolve(binDirectory, "../../../skills")]
-    .map((candidate) => resolve(candidate, SKILL_NAME))
-    .find((candidate) => {
-      try {
-        return statSync(join(candidate, "SKILL.md")).isFile();
-      } catch {
-        return false;
-      }
-    });
-  if (!sourceDirectory) process.exit(0);
-  const packaged = readFileSync(join(sourceDirectory, "SKILL.md"), "utf8");
-
-  const home = process.env.HOME?.trim() || homedir();
-  const xdgHome = process.env.XDG_CONFIG_HOME?.trim();
-  const configPath = xdgHome
-    ? join(xdgHome, "fvtt-world-cli", "config.json")
-    : platform() === "darwin"
-      ? join(home, "Library", "Application Support", "fvtt-world-cli", "config.json")
-      : platform() === "win32"
-        ? join(
-            process.env.APPDATA?.trim() || join(home, "AppData", "Roaming"),
-            "fvtt-world-cli",
-            "config.json"
-          )
-        : join(home, ".config", "fvtt-world-cli", "config.json");
-
-  const roots = new Set([join(home, ".agents", "skills")]);
-  try {
-    const config = JSON.parse(readFileSync(configPath, "utf8"));
-    if (Array.isArray(config?.skillInstalls)) {
-      for (const root of config.skillInstalls) {
-        if (typeof root === "string" && root.length > 0) roots.add(root);
-      }
-    }
-  } catch {
-    // no or unreadable config: the standard location is still checked
-  }
-
-  for (const root of roots) {
-    try {
-      const destination = join(root, SKILL_NAME);
-      const existing = (() => {
-        try {
-          return lstatSync(destination);
-        } catch {
-          return null;
-        }
-      })();
-      if (!existing || existing.isSymbolicLink()) continue;
-
-      const installed = readFileSync(join(destination, "SKILL.md"), "utf8");
-      if (installed === packaged) continue;
-
-      const recorded = (() => {
-        try {
-          return readFileSync(join(destination, "SKILL.md.sha256"), "utf8").trim();
-        } catch {
-          return null;
-        }
-      })();
-
-      if (recorded === createHash("sha256").update(installed).digest("hex")) {
-        rmSync(destination, { recursive: true, force: true });
-        cpSync(sourceDirectory, destination, { recursive: true });
-        console.error(
-          `fvtt-world-cli: updated the installed agent skill at ${destination} to the packaged version.`
-        );
-      } else {
-        console.error(
-          `fvtt-world-cli: the installed agent skill at ${destination} has local modifications and was NOT updated. Compare them, then run \`fvtt-world-cli skill update --force\` to replace it.`
-        );
-      }
-    } catch {
-      continue;
-    }
-  }
-} catch {
-  process.exit(0);
-}