@plaiful/cli 0.5.0 → 0.6.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.
- package/README.md +63 -15
- package/package.json +1 -1
- package/src/cli.js +52 -2
- package/src/mcp.js +2 -1
package/README.md
CHANGED
|
@@ -1,25 +1,57 @@
|
|
|
1
1
|
# The Plaiful CLI
|
|
2
2
|
|
|
3
|
-
`plaiful` is how
|
|
4
|
-
|
|
5
|
-
and change that account's products. Design: `docs/system/product/PARTNER_API_AND_CLI.md`.
|
|
3
|
+
> `plaiful` is how your team, or your coding agent, works on your Plaiful product from your game's repo. **Part 1**
|
|
4
|
+
> is for the people on your team. **Part 2** is for your coding agent: every command.
|
|
6
5
|
|
|
7
|
-
##
|
|
6
|
+
## Part 1: for your team
|
|
8
7
|
|
|
9
|
-
|
|
8
|
+
### What it is
|
|
9
|
+
|
|
10
|
+
- A command-line tool for your Plaiful product: you type commands in a terminal, in your game's repo.
|
|
11
|
+
- It loads your data into Plaiful, reads back what Plaiful has, and reads the platform docs.
|
|
12
|
+
- It signs in as your CMS account, so it can only see and change your own products.
|
|
13
|
+
- It needs no AWS access.
|
|
14
|
+
- It works in your development environment. Staging and production get your content when you promote.
|
|
15
|
+
|
|
16
|
+
### Install it and sign in
|
|
17
|
+
|
|
18
|
+
You need Node 18 or later.
|
|
10
19
|
|
|
11
20
|
```sh
|
|
12
21
|
npm install -g @plaiful/cli
|
|
13
|
-
plaiful
|
|
22
|
+
plaiful login
|
|
14
23
|
```
|
|
15
24
|
|
|
16
|
-
|
|
17
|
-
|
|
25
|
+
- `plaiful login` opens the CMS. Check the code matches, and approve. The sign-in lasts 12 hours.
|
|
26
|
+
- You need to be on Plaiful's allowlist, and own your product or have it shared with you.
|
|
27
|
+
|
|
28
|
+
### What you'll use it for
|
|
29
|
+
|
|
30
|
+
| To | Run |
|
|
31
|
+
|---|---|
|
|
32
|
+
| Get your game's repo | `plaiful clone <product>`, or `plaiful init <product>` in a repo you already have |
|
|
33
|
+
| Get your product's settings | `plaiful docs pull` |
|
|
34
|
+
| Read the docs | `plaiful docs`, `plaiful docs search <words>` |
|
|
35
|
+
| Load your world into Plaiful | `plaiful seed world`, then `plaiful seed world --apply` (and `lore`, `map`, `personas`) |
|
|
36
|
+
| See what Plaiful has | `plaiful status`, `plaiful quests`, `plaiful lore`, `plaiful world`, `plaiful assets` |
|
|
37
|
+
| Publish your OVID declaration | `plaiful ovid check`, then `plaiful ovid publish` |
|
|
38
|
+
| Deploy and run worker agents | `plaiful agents deploy`, `plaiful agents run <name>` |
|
|
39
|
+
|
|
40
|
+
Every load starts as a dry run: it shows what would change, and changes nothing until you add `--apply`.
|
|
18
41
|
|
|
19
|
-
|
|
20
|
-
npm as a member of the `plaiful` org.
|
|
42
|
+
### Keys for coding agents and CI
|
|
21
43
|
|
|
22
|
-
|
|
44
|
+
- A coding agent working on its own, or a CI job, can use a key instead of a sign-in.
|
|
45
|
+
- Your product's owner makes one in the CMS: **DevOps → Deployment → your product → CLI keys**.
|
|
46
|
+
- A key works on one product, for the jobs you pick, and stops the moment you revoke it.
|
|
47
|
+
- Keep it out of your repo.
|
|
48
|
+
|
|
49
|
+
## Part 2: for your coding agent
|
|
50
|
+
|
|
51
|
+
Every command runs as the signed-in CMS account (or a product API key that account issued), on that account's
|
|
52
|
+
products, in **dev**.
|
|
53
|
+
|
|
54
|
+
### Commands
|
|
23
55
|
|
|
24
56
|
```sh
|
|
25
57
|
plaiful login # opens the CMS: check the code matches, approve. 12 hours.
|
|
@@ -41,6 +73,13 @@ plaiful assets crew-portrait --state failed # one agent's records: state, why
|
|
|
41
73
|
plaiful quests # the quests OVID wrote: steps, and what each pays (--track, --series); quests show <id>
|
|
42
74
|
plaiful lore # the lore sets (lore show <setId>: a set's snippets)
|
|
43
75
|
plaiful world # the world's states and events in story order, and the clock
|
|
76
|
+
plaiful agents # your product's SmartBuilder agents in dev (agents show <name>: one agent's config)
|
|
77
|
+
plaiful agents deploy # deploy or redeploy every config in resources/agents/roadforge/ (or name the files)
|
|
78
|
+
plaiful agents run crew-portrait role=medic # make one record (placeholder values as key=value)
|
|
79
|
+
plaiful agents batch crew-portrait --count 20 # start a batch (or a batch body file) → a job id
|
|
80
|
+
plaiful agents status crew-portrait <jobId> # a batch's progress
|
|
81
|
+
plaiful records import crew-portrait # dry run: records you wrote (resources/records/roadforge/crew-portrait.json)
|
|
82
|
+
# into the agent's table; --apply writes them, --no-render skips the art
|
|
44
83
|
plaiful lists # the product's SSM lists
|
|
45
84
|
plaiful lists set shop_type tavern blacksmith healer # write one (lists get shop_type reads it)
|
|
46
85
|
plaiful midas pricing # what each quest pays, in your reward kinds (MIDAS); delivered in the quest's rewards
|
|
@@ -50,6 +89,10 @@ plaiful whoami # who you are (or which key), and your products
|
|
|
50
89
|
plaiful logout
|
|
51
90
|
```
|
|
52
91
|
|
|
92
|
+
`plaiful help` lists every command and option.
|
|
93
|
+
|
|
94
|
+
### Notes
|
|
95
|
+
|
|
53
96
|
- `--json` on any command prints the platform's answer as JSON (for agents). Exit codes: `0` done, `1` the platform
|
|
54
97
|
said no (invalid, not allowed, not signed in), `2` the command itself was wrong.
|
|
55
98
|
- Everything works in **dev**. Staging and prod get your content through Plaiful's promotion.
|
|
@@ -62,8 +105,10 @@ plaiful logout
|
|
|
62
105
|
String), or `access/*` (who may play).
|
|
63
106
|
- The sign-in is kept in `~/.plaiful/credentials`, never in the repo. `PLAIFUL_API_URL` or `--api` points at another API.
|
|
64
107
|
- You need to be on the Plaiful allowlist, and own or be shared the product (Plaiful staff: every product).
|
|
108
|
+
- From a PlaifulCMS checkout instead of npm: `npm install -g <path to PlaifulCMS>/packages/plaiful-cli`. The package
|
|
109
|
+
is public on npmjs.com; it holds no secrets, and everything it does needs a CMS sign-in or a key.
|
|
65
110
|
|
|
66
|
-
|
|
111
|
+
### Keys for agents and CI
|
|
67
112
|
|
|
68
113
|
A product's owner issues keys in the CMS: Product deployment → the product → **CLI keys**. A key is shown once; set
|
|
69
114
|
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:
|
|
@@ -76,7 +121,10 @@ A key acts as the owner who issued it, on that one product, in dev, for the scop
|
|
|
76
121
|
`ovid:publish`, `lists`, `upload`). Revoking it in the CMS stops it at once; so does its issuer losing the product. The
|
|
77
122
|
same screen shows the product's activity: everything the CLI and its keys did.
|
|
78
123
|
|
|
79
|
-
|
|
124
|
+
### For Plaiful staff
|
|
80
125
|
|
|
81
|
-
|
|
82
|
-
`
|
|
126
|
+
- **Design:** `docs/system/product/PARTNER_API_AND_CLI.md`.
|
|
127
|
+
- **Publishing a new version:** bump `version` in `package.json`, then `npm publish` from this folder, signed in to
|
|
128
|
+
npm as a member of the `plaiful` org.
|
|
129
|
+
- **Tests:** the end-to-end tests run this CLI against the partner API handler:
|
|
130
|
+
`lambda/functions/partner-api/__tests__/partner-api.test.js`.
|
package/package.json
CHANGED
package/src/cli.js
CHANGED
|
@@ -52,6 +52,9 @@ const HELP = `plaiful ${version}: work on your Plaiful product from your game re
|
|
|
52
52
|
plaiful agents run <name> [key=value...] make one record (placeholder values as key=value)
|
|
53
53
|
plaiful agents batch <name> [file] start a batch (a batch body file, or --count <n>) → a job id
|
|
54
54
|
plaiful agents status <name> <jobId> a batch's progress
|
|
55
|
+
plaiful records import <agent> [file] dry run: records you wrote, into the agent's table (default file:
|
|
56
|
+
resources/records/<product>/<agent>.json; matched on the agent's duplicate field)
|
|
57
|
+
--apply write them; --no-render don't make new records' art or sound
|
|
55
58
|
plaiful midas pricing what MIDAS pays per quest, in your reward kinds (delivered in each quest's rewards)
|
|
56
59
|
plaiful midas pricing set <kind> --base <n> --per-effort <n> price a kind (either option alone keeps the other)
|
|
57
60
|
plaiful midas pricing unset <kind> stop pricing a kind
|
|
@@ -91,7 +94,7 @@ function parse(argv) {
|
|
|
91
94
|
const args = [];
|
|
92
95
|
for (let i = 0; i < argv.length; i += 1) {
|
|
93
96
|
const a = argv[i];
|
|
94
|
-
if (['--json', '--no-browser', '--help', '-h', '--version', '--apply', '--reset', '--rows', '--no-install', '--no-open', '--copies'].includes(a)) flags[a.replace(/^-+/, '')] = true;
|
|
97
|
+
if (['--json', '--no-browser', '--help', '-h', '--version', '--apply', '--reset', '--rows', '--no-install', '--no-open', '--copies', '--no-render'].includes(a)) flags[a.replace(/^-+/, '')] = true;
|
|
95
98
|
else if (['--product', '--api', '--dir', '--dest', '--count', '--base', '--per-effort', '--track', '--series', '--state', '--limit', '--section', '--since'].includes(a)) {
|
|
96
99
|
if (argv[i + 1] === undefined) throw new UsageError(`${a} needs a value`);
|
|
97
100
|
flags[a.slice(2)] = argv[i += 1];
|
|
@@ -202,6 +205,7 @@ function layout(product, docsDir) {
|
|
|
202
205
|
return [
|
|
203
206
|
[`resources/${product}-resources`, 'SmartBuilder agent specs (one markdown file per agent, pasted into SmartBuilder)'],
|
|
204
207
|
[`resources/agents/${product}`, 'agent configs as JSON, for plaiful agents deploy'],
|
|
208
|
+
[`resources/records/${product}`, 'records you write by hand, one <agent>.json per agent, for plaiful records import'],
|
|
205
209
|
[`resources/world/${product}`, 'the narrative scaffold, for plaiful seed world'],
|
|
206
210
|
[`resources/lore/${product}`, 'lore sets, for plaiful seed lore'],
|
|
207
211
|
[`resources/map/${product}`, 'places, for plaiful seed map'],
|
|
@@ -358,7 +362,12 @@ async function docsList(ctx) {
|
|
|
358
362
|
const { data } = await ctx.call('GET', docsRoute());
|
|
359
363
|
const docs = data.docs || [];
|
|
360
364
|
const lines = [`Plaiful docs (live): ${docs.length}. plaiful docs read <doc>`];
|
|
361
|
-
|
|
365
|
+
let section = null;
|
|
366
|
+
for (const d of [...docs].sort((a, b) => (a.order ?? 1e9) - (b.order ?? 1e9))) {
|
|
367
|
+
const s = d.section_title || d.category || 'Docs';
|
|
368
|
+
if (s !== section) { lines.push(`${s}:`); section = s; }
|
|
369
|
+
lines.push(` ${docName(d.key).padEnd(40)} ${day(d.updated_at)} ${d.label || d.title || ''}`);
|
|
370
|
+
}
|
|
362
371
|
ctx.out(lines.join('\n'), data);
|
|
363
372
|
return 0;
|
|
364
373
|
}
|
|
@@ -671,6 +680,46 @@ async function agents(ctx, [sub, name, ...rest]) {
|
|
|
671
680
|
throw new UsageError(`plaiful agents, or agents show | deploy | run | batch | status (not "${sub}")`);
|
|
672
681
|
}
|
|
673
682
|
|
|
683
|
+
/** `plaiful records import <agent> [file]`: records written by hand into the agent's table, saved as the agent saves
|
|
684
|
+
* the ones it makes; a dry run unless --apply. The file: a list of records, or { "records": [...] }. */
|
|
685
|
+
async function records(ctx, [sub, name, file]) {
|
|
686
|
+
if (sub !== 'import') throw new UsageError(`plaiful records import <agent> [file] (not "${sub || ''}")`);
|
|
687
|
+
const r = repo(ctx);
|
|
688
|
+
if (!name) throw new UsageError('which agent? plaiful records import <agent> [file] (default file: resources/records/<product>/<agent>.json)');
|
|
689
|
+
if (!AGENT_NAME.test(name)) throw new UsageError(`"${name}" isn't an agent name (lowercase letters, digits, hyphens)`);
|
|
690
|
+
const f = file || path.join(path.relative(ctx.io.cwd(), r.root) || '.', 'resources', 'records', r.product, `${name}.json`);
|
|
691
|
+
const { json } = readJsonFile(ctx, f);
|
|
692
|
+
const list = Array.isArray(json) ? json : json && Array.isArray(json.records) ? json.records : null;
|
|
693
|
+
if (!list) throw new UsageError(`${f}: give a list of records, or { "records": [...] }`);
|
|
694
|
+
if (!list.length) throw new UsageError(`${f} has no records`);
|
|
695
|
+
const apply = !!ctx.flags.apply;
|
|
696
|
+
const { data } = await ctx.call('POST', agentRoute(r, `/${encodeURIComponent(name)}/import`), { records: list, apply, render: !ctx.flags['no-render'] });
|
|
697
|
+
if (ctx.flags.json) { ctx.out(data); return data.success ? 0 : 1; }
|
|
698
|
+
const lines = [];
|
|
699
|
+
if (!data.success) {
|
|
700
|
+
lines.push(`${data.error || 'the import was refused'}. Fix them and run it again.`);
|
|
701
|
+
for (const e of data.errors || []) lines.push(` ✗ ${e.error}`);
|
|
702
|
+
ctx.out(lines.join('\n'));
|
|
703
|
+
return 1;
|
|
704
|
+
}
|
|
705
|
+
const s = data.summary;
|
|
706
|
+
lines.push(`${name} for ${r.product} (dev, ${data.table_name})${data.key_field ? `, matched on ${data.key_field}` : ''}:`);
|
|
707
|
+
lines.push(`${data.applied ? 'Wrote' : 'Would write'}: ${s.create} new, ${s.update} changed, ${s.unchanged} unchanged.`);
|
|
708
|
+
const shown = data.records.filter((x) => x.action !== 'unchanged').slice(0, 40);
|
|
709
|
+
const label = (x) => (x.key !== null && x.key !== undefined ? x.key : x.uuid);
|
|
710
|
+
for (const x of shown) lines.push(` ${MARK[x.action]} ${x.action === 'create' ? 'new ' : 'change'} ${label(x)}${x.action === 'update' ? ` (${x.changed.join(', ')})` : ''}`);
|
|
711
|
+
const more = s.create + s.update - shown.length;
|
|
712
|
+
if (more > 0) lines.push(` … and ${more} more (--json lists them all)`);
|
|
713
|
+
for (const w of data.warnings || []) lines.push(` ! ${w}`);
|
|
714
|
+
const stale = data.records.filter((x) => x.stale_art).map(label);
|
|
715
|
+
if (stale.length) lines.push(` ! ${stale.length} changed record(s) keep the art or sound made from their old text (${stale.slice(0, 5).join(', ')}${stale.length > 5 ? ', …' : ''}): make it again in the CMS Library.`);
|
|
716
|
+
if (!data.applied) {
|
|
717
|
+
lines.push(s.create + s.update ? `Dry run: nothing written. Write it with: plaiful records import ${name}${file ? ` ${file}` : ''} --apply` : 'Dry run: the table already matches your file.');
|
|
718
|
+
} else if (data.rendering) lines.push(`Making the art or sound for ${data.rendering} new record(s): plaiful assets ${name}`);
|
|
719
|
+
ctx.out(lines.join('\n'));
|
|
720
|
+
return 0;
|
|
721
|
+
}
|
|
722
|
+
|
|
674
723
|
// ── What OVID has: quests, lore, the world ──────────────────────────────────────────────────────────────────────
|
|
675
724
|
|
|
676
725
|
const ovidRoute = (r, rest) => `/partner/${encodeURIComponent(r.product)}/ovid/${rest}`;
|
|
@@ -999,6 +1048,7 @@ const COMMANDS = {
|
|
|
999
1048
|
status: (ctx) => status(ctx),
|
|
1000
1049
|
lists: (ctx, rest) => lists(ctx, rest),
|
|
1001
1050
|
agents: (ctx, rest) => agents(ctx, rest),
|
|
1051
|
+
records: (ctx, rest) => records(ctx, rest),
|
|
1002
1052
|
'midas pricing': (ctx, rest) => midasPricing(ctx, rest),
|
|
1003
1053
|
quests: (ctx, rest) => quests(ctx, rest),
|
|
1004
1054
|
assets: (ctx, rest) => assets(ctx, rest),
|
package/src/mcp.js
CHANGED
|
@@ -58,7 +58,8 @@ const route = (rest = '', query = {}) => {
|
|
|
58
58
|
async function runTool(ctx, name, args = {}) {
|
|
59
59
|
if (name === 'list_docs') {
|
|
60
60
|
const { data } = await ctx.call('GET', route());
|
|
61
|
-
return (data.docs || []).
|
|
61
|
+
return [...(data.docs || [])].sort((a, b) => (a.order ?? 1e9) - (b.order ?? 1e9))
|
|
62
|
+
.map((d) => `${docName(d.key)} | ${d.section_title || d.category || ''} | ${d.title || ''} | updated ${String(d.updated_at || '').slice(0, 10)} | ${d.description || ''}`).join('\n');
|
|
62
63
|
}
|
|
63
64
|
if (name === 'read_doc') {
|
|
64
65
|
if (!args.doc) throw new Error('doc is required');
|