@plaiful/cli 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +82 -80
  2. package/package.json +21 -21
  3. package/src/cli.js +1070 -970
  4. package/src/mcp.js +144 -0
package/README.md CHANGED
@@ -1,80 +1,82 @@
1
- # The Plaiful CLI
2
-
3
- `plaiful` is how a product team's person or agent works on their Plaiful product from the game repo, with no AWS
4
- access. Every command runs as the signed-in CMS account (or a product API key that account issued), so it can only see
5
- and change that account's products. Design: `docs/system/product/PARTNER_API_AND_CLI.md`.
6
-
7
- ## Install
8
-
9
- Node 18 or later:
10
-
11
- ```sh
12
- npm install -g @plaiful/cli
13
- plaiful --version
14
- ```
15
-
16
- It's public on npmjs.com (it holds no secrets; everything it does needs a CMS sign-in or a key). From a PlaifulCMS
17
- checkout instead: `npm install -g <path to PlaifulCMS>/packages/plaiful-cli`.
18
-
19
- **Publishing a new version** (Plaiful staff): bump `version` here, then `npm publish` from this folder, signed in to
20
- npm as a member of the `plaiful` org.
21
-
22
- ## Use
23
-
24
- ```sh
25
- plaiful login # opens the CMS: check the code matches, approve. 12 hours.
26
- plaiful clone roadforge # clone the game repo, write .env.development, docs pull, npm install, open Zed
27
- plaiful init roadforge # (a repo you already have) writes .plaiful.json (commit it; no secrets) and makes the resources/ folders
28
- plaiful docs pull # the latest onboarding docs + client-config.md into docs/plaiful/
29
- plaiful env # rewrite .env.development from the dev client config (keeps your own lines)
30
- plaiful ovid check # checks docs/plaiful/roadforge-ovid-declaration.json
31
- plaiful ovid publish # checks it again and publishes it; OVID reads it within ~5 minutes
32
- plaiful ovid show # what OVID has now
33
- plaiful seed world # dry run: what resources/world/roadforge/*.json make, and what changes in dev
34
- plaiful seed world --apply # write it (then lore, then map); --reset also puts the clock, reveals and NPC bindings back
35
- plaiful seed personas # THESPIS personas and situations from resources/personas/roadforge/ (same dry run / --apply)
36
- plaiful status # what OVID and THESPIS have in dev: counts per store, the clock, the declaration
37
- plaiful assets # per agent: records, and how many have art made / pending / failed / none yet
38
- plaiful assets crew-portrait --state failed # one agent's records: state, why a render failed, where the files are
39
- plaiful quests # the quests OVID wrote: steps, and what each pays (--track, --series); quests show <id>
40
- plaiful lore # the lore sets (lore show <setId>: a set's snippets)
41
- plaiful world # the world's states and events in story order, and the clock
42
- plaiful lists # the product's SSM lists
43
- plaiful lists set shop_type tavern blacksmith healer # write one (lists get shop_type reads it)
44
- plaiful midas pricing # what each quest pays, in your reward kinds (MIDAS); delivered in the quest's rewards
45
- plaiful midas pricing set scrap --base 20 --per-effort 10 # price a kind (unset <kind>, weight <step> <n>, apply [file])
46
- plaiful upload ovid-map-biomes-tiles.json ovid-map-kingdoms-tiles.json ovid-map-colors.json # map tiles → map-data/
47
- plaiful whoami # who you are (or which key), and your products
48
- plaiful logout
49
- ```
50
-
51
- - `--json` on any command prints the platform's answer as JSON (for agents). Exit codes: `0` done, `1` the platform
52
- said no (invalid, not allowed, not signed in), `2` the command itself was wrong.
53
- - Everything works in **dev**. Staging and prod get your content through Plaiful's promotion.
54
- - `docs pull` keeps `client-config.md` (your keys) out of git with `docs/plaiful/.gitignore`, and prints the
55
- `git rm --cached` line if it was committed before.
56
- - `clone` needs access to the repo on GitHub (git signed in: `gh auth login` or Git Credential Manager), and
57
- `npm install` needs npm access to the `@plaiful` packages. It writes `.env.development` only when the repo has the
58
- web template's `.env.development.example`.
59
- - `lists set` writes a StringList in your product's namespace. It won't touch a key (SecureString), a setting (a plain
60
- String), or `access/*` (who may play).
61
- - The sign-in is kept in `~/.plaiful/credentials`, never in the repo. `PLAIFUL_API_URL` or `--api` points at another API.
62
- - You need to be on the Plaiful allowlist, and own or be shared the product (Plaiful staff: every product).
63
-
64
- ## Keys for agents and CI
65
-
66
- A product's owner issues keys in the CMS: Product deployment → the product → **CLI keys**. A key is shown once; set
67
- it as `PLAIFUL_TOKEN` in CI or the agent's environment (never in the repo) and the CLI uses it instead of a sign-in:
68
-
69
- ```sh
70
- PLAIFUL_TOKEN=plf_k_… plaiful seed world --apply
71
- ```
72
-
73
- A key acts as the owner who issued it, on that one product, in dev, for the scopes picked (`docs`, `status`, `seed`,
74
- `ovid:publish`, `lists`, `upload`). Revoking it in the CMS stops it at once; so does its issuer losing the product. The
75
- same screen shows the product's activity: everything the CLI and its keys did.
76
-
77
- ## Tests
78
-
79
- The end-to-end tests run this CLI against the partner API handler:
80
- `lambda/functions/partner-api/__tests__/partner-api.test.js`.
1
+ # The Plaiful CLI
2
+
3
+ `plaiful` is how a product team's person or agent works on their Plaiful product from the game repo, with no AWS
4
+ access. Every command runs as the signed-in CMS account (or a product API key that account issued), so it can only see
5
+ and change that account's products. Design: `docs/system/product/PARTNER_API_AND_CLI.md`.
6
+
7
+ ## Install
8
+
9
+ Node 18 or later:
10
+
11
+ ```sh
12
+ npm install -g @plaiful/cli
13
+ plaiful --version
14
+ ```
15
+
16
+ It's public on npmjs.com (it holds no secrets; everything it does needs a CMS sign-in or a key). From a PlaifulCMS
17
+ checkout instead: `npm install -g <path to PlaifulCMS>/packages/plaiful-cli`.
18
+
19
+ **Publishing a new version** (Plaiful staff): bump `version` here, then `npm publish` from this folder, signed in to
20
+ npm as a member of the `plaiful` org.
21
+
22
+ ## Use
23
+
24
+ ```sh
25
+ plaiful login # opens the CMS: check the code matches, approve. 12 hours.
26
+ plaiful clone roadforge # clone the game repo, write .env.development, docs pull, npm install, open Zed
27
+ plaiful init roadforge # (a repo you already have) writes .plaiful.json (commit it; no secrets) and makes the resources/ folders
28
+ plaiful docs # the platform docs, live (docs read <doc>, docs search <words>, docs changes)
29
+ plaiful docs pull # your client-config.md into docs/plaiful/ (--copies: local copies of the docs too)
30
+ plaiful mcp # the docs as MCP tools for your coding assistant: claude mcp add plaiful -- plaiful mcp
31
+ plaiful env # rewrite .env.development from the dev client config (keeps your own lines)
32
+ plaiful ovid check # checks docs/plaiful/roadforge-ovid-declaration.json
33
+ plaiful ovid publish # checks it again and publishes it; OVID reads it within ~5 minutes
34
+ plaiful ovid show # what OVID has now
35
+ plaiful seed world # dry run: what resources/world/roadforge/*.json make, and what changes in dev
36
+ plaiful seed world --apply # write it (then lore, then map); --reset also puts the clock, reveals and NPC bindings back
37
+ plaiful seed personas # THESPIS personas and situations from resources/personas/roadforge/ (same dry run / --apply)
38
+ plaiful status # what OVID and THESPIS have in dev: counts per store, the clock, the declaration
39
+ plaiful assets # per agent: records, and how many have art made / pending / failed / none yet
40
+ plaiful assets crew-portrait --state failed # one agent's records: state, why a render failed, where the files are
41
+ plaiful quests # the quests OVID wrote: steps, and what each pays (--track, --series); quests show <id>
42
+ plaiful lore # the lore sets (lore show <setId>: a set's snippets)
43
+ plaiful world # the world's states and events in story order, and the clock
44
+ plaiful lists # the product's SSM lists
45
+ plaiful lists set shop_type tavern blacksmith healer # write one (lists get shop_type reads it)
46
+ plaiful midas pricing # what each quest pays, in your reward kinds (MIDAS); delivered in the quest's rewards
47
+ plaiful midas pricing set scrap --base 20 --per-effort 10 # price a kind (unset <kind>, weight <step> <n>, apply [file])
48
+ plaiful upload ovid-map-biomes-tiles.json ovid-map-kingdoms-tiles.json ovid-map-colors.json # map tiles → map-data/
49
+ plaiful whoami # who you are (or which key), and your products
50
+ plaiful logout
51
+ ```
52
+
53
+ - `--json` on any command prints the platform's answer as JSON (for agents). Exit codes: `0` done, `1` the platform
54
+ said no (invalid, not allowed, not signed in), `2` the command itself was wrong.
55
+ - Everything works in **dev**. Staging and prod get your content through Plaiful's promotion.
56
+ - `docs pull` keeps `client-config.md` (your keys) out of git with `docs/plaiful/.gitignore`, and prints the
57
+ `git rm --cached` line if it was committed before.
58
+ - `clone` needs access to the repo on GitHub (git signed in: `gh auth login` or Git Credential Manager), and
59
+ `npm install` needs npm access to the `@plaiful` packages. It writes `.env.development` only when the repo has the
60
+ web template's `.env.development.example`.
61
+ - `lists set` writes a StringList in your product's namespace. It won't touch a key (SecureString), a setting (a plain
62
+ String), or `access/*` (who may play).
63
+ - The sign-in is kept in `~/.plaiful/credentials`, never in the repo. `PLAIFUL_API_URL` or `--api` points at another API.
64
+ - You need to be on the Plaiful allowlist, and own or be shared the product (Plaiful staff: every product).
65
+
66
+ ## Keys for agents and CI
67
+
68
+ A product's owner issues keys in the CMS: Product deployment → the product → **CLI keys**. A key is shown once; set
69
+ it as `PLAIFUL_TOKEN` in CI or the agent's environment (never in the repo) and the CLI uses it instead of a sign-in:
70
+
71
+ ```sh
72
+ PLAIFUL_TOKEN=plf_k_… plaiful seed world --apply
73
+ ```
74
+
75
+ A key acts as the owner who issued it, on that one product, in dev, for the scopes picked (`docs`, `status`, `seed`,
76
+ `ovid:publish`, `lists`, `upload`). Revoking it in the CMS stops it at once; so does its issuer losing the product. The
77
+ same screen shows the product's activity: everything the CLI and its keys did.
78
+
79
+ ## Tests
80
+
81
+ The end-to-end tests run this CLI against the partner API handler:
82
+ `lambda/functions/partner-api/__tests__/partner-api.test.js`.
package/package.json CHANGED
@@ -1,21 +1,21 @@
1
- {
2
- "name": "@plaiful/cli",
3
- "version": "0.4.0",
4
- "description": "The Plaiful CLI: work on your Plaiful product from your game repo, with no AWS access",
5
- "bin": {
6
- "plaiful": "bin/plaiful.js"
7
- },
8
- "files": [
9
- "bin",
10
- "src",
11
- "README.md"
12
- ],
13
- "engines": {
14
- "node": ">=18"
15
- },
16
- "license": "UNLICENSED",
17
- "publishConfig": {
18
- "registry": "https://registry.npmjs.org/",
19
- "access": "public"
20
- }
21
- }
1
+ {
2
+ "name": "@plaiful/cli",
3
+ "version": "0.5.0",
4
+ "description": "The Plaiful CLI: work on your Plaiful product from your game repo, with no AWS access",
5
+ "bin": {
6
+ "plaiful": "bin/plaiful.js"
7
+ },
8
+ "files": [
9
+ "bin",
10
+ "src",
11
+ "README.md"
12
+ ],
13
+ "engines": {
14
+ "node": ">=18"
15
+ },
16
+ "license": "UNLICENSED",
17
+ "publishConfig": {
18
+ "registry": "https://registry.npmjs.org/",
19
+ "access": "public"
20
+ }
21
+ }