fvtt-world-cli 1.1.0 → 1.1.2

package/docs/skill.md

@@ -1,15 +1,7 @@
 # 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).
+The package includes [foundry-world-editor](../skills/foundry-world-editor/SKILL.md), operating
+instructions for AI agents that support Agent Skills.
 
 ## Installing
 
@@ -17,10 +9,8 @@ at [`skills/foundry-world-editor/SKILL.md`](../skills/foundry-world-editor/SKILL
 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.
+The default installation runs `npx skills add`, which detects the agents present on the machine.
+It keeps a shared copy under `~/.agents/skills` and links the agents' skill directories to it.
 
 An explicit destination works without the skills CLI or network access:
 
@@ -28,31 +18,27 @@ An explicit destination works without the skills CLI or network access:
 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.
+The CLI records this destination for later updates. Add `--link` to use the packaged skill
+directly through a symlink:
 
-## Staying up to date
+```bash
+fvtt-world-cli skill install --to <skills-directory> --link
+```
+
+`--link` requires `--to`. A linked skill follows CLI package updates automatically.
 
-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 updates, a copy is one
-of two kinds:
+## Staying up to date
 
-- 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.
+At startup, the daemon updates unmodified copies in the shared directory and recorded `--to`
+locations. It preserves locally edited copies and warns instead of overwriting them.
 
-The explicit update command follows the same rule and can override it:
+To update manually:
 
 ```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.
+Add `--force` to replace a locally edited copy with the packaged version.
 
 ## Removing
 
@@ -63,3 +49,12 @@ 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.
+
+## JSON output
+
+For `skill install`, `skill update`, and `skill remove`, `--json` requires an explicit `--to`
+destination:
+
+```bash
+fvtt-world-cli skill install --to <skills-directory> --json
+```

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "fvtt-world-cli",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Safe local CLI and authenticated bridge for automating live Foundry VTT worlds.",
+  "keywords": [
+    "foundry-vtt",
+    "foundryvtt",
+    "fvtt",
+    "virtual-tabletop",
+    "ttrpg",
+    "cli",
+    "automation",
+    "ai",
+    "ai-agent",
+    "agent-skills"
+  ],
   "license": "MIT",
   "author": "DroiD16",
   "repository": {
@@ -20,8 +32,8 @@
   },
   "type": "module",
   "bin": {
-    "fvtt-world-cli": "./bin/fvtt-world-cli.js",
-    "worldctl": "./bin/fvtt-world-cli.js"
+    "fvtt-world-cli": "bin/fvtt-world-cli.js",
+    "worldctl": "bin/fvtt-world-cli.js"
   },
   "files": [
     "bin/",
@@ -34,8 +46,7 @@
     "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"
+    "postpack": "node ./bin/prepare-package-assets.mjs --clean"
   },
   "dependencies": {
     "commander": "^13.1.0",
@@ -45,6 +56,6 @@
     "zod": "^3.24.3"
   },
   "devDependencies": {
-    "@fvtt-world-cli/protocol": "1.1.0"
+    "@fvtt-world-cli/protocol": "1.1.2"
   }
 }

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

@@ -155,8 +155,16 @@ Classify a failure before reacting:
 - `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_STALE` means the GM allowed a macro execution whose body or type changed — or whose
+  macro was deleted — after it was shown, so nothing ran. Read the macro again and re-send the execution if the current content is
+  still what the user wants; that opens a fresh approval.
 - `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.
+- For an update `INTERNAL_ERROR` with `details.partial: true` or `details.indeterminate: true`,
+  read the affected document before retrying. `changedFields` names requested top-level fields
+  observed to change, not fully applied nested values. An embedded creation without a requested
+  id may already exist despite an indeterminate error. Send only the remaining changes as a new
+  operation with a fresh idempotency key, if using one.
 - Correct a structured Foundry rejection and submit the corrected content as a new operation.
 
 ## Bulk writes and actions

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

@@ -1 +1 @@
-1834777e1d540cb4cc11b6eac862ff99878a6e4920ebbc1e2599871893e19dc9
+d1757739e55e01589814ed919912bbe5423afa99aee16a1422fbaee5bed11c8a

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);
-}

package/docs/images/icon.svg

@@ -1,16 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
-  <rect width="512" height="512" fill="#0b0a13"/>
-  <g fill="none" stroke="#fc6119" stroke-linecap="round" stroke-linejoin="round">
-    <g stroke-width="15">
-      <path d="M256 36 446.53 146V366L256 476 65.47 366V146Z"/>
-      <path d="M256 120 373.78 324H138.22Z"/>
-      <path d="M256 36 256 120M446.53 146 256 120M65.47 146 256 120"/>
-      <path d="M446.53 366 373.78 324M446.53 146 373.78 324M256 476 373.78 324"/>
-      <path d="M65.47 366 138.22 324M65.47 146 138.22 324M256 476 138.22 324"/>
-    </g>
-    <g stroke-width="12">
-      <path d="M223 240 251 268 223 296"/>
-      <path d="M266 296H306" stroke-linecap="butt"/>
-    </g>
-  </g>
-</svg>

package/docs/images/mark.svg

@@ -1,15 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
-  <g fill="none" stroke="#fc6119" stroke-linecap="round" stroke-linejoin="round">
-    <g stroke-width="15">
-      <path d="M256 36 446.53 146V366L256 476 65.47 366V146Z"/>
-      <path d="M256 120 373.78 324H138.22Z"/>
-      <path d="M256 36 256 120M446.53 146 256 120M65.47 146 256 120"/>
-      <path d="M446.53 366 373.78 324M446.53 146 373.78 324M256 476 373.78 324"/>
-      <path d="M65.47 366 138.22 324M65.47 146 138.22 324M256 476 138.22 324"/>
-    </g>
-    <g stroke-width="12">
-      <path d="M223 240 251 268 223 296"/>
-      <path d="M266 296H306" stroke-linecap="butt"/>
-    </g>
-  </g>
-</svg>