@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 CHANGED
@@ -1,25 +1,57 @@
1
1
  # The Plaiful CLI
2
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`.
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
- ## Install
6
+ ## Part 1: for your team
8
7
 
9
- Node 18 or later:
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 --version
22
+ plaiful login
14
23
  ```
15
24
 
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`.
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
- **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.
42
+ ### Keys for coding agents and CI
21
43
 
22
- ## Use
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
- ## Keys for agents and CI
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
- ## Tests
124
+ ### For Plaiful staff
80
125
 
81
- The end-to-end tests run this CLI against the partner API handler:
82
- `lambda/functions/partner-api/__tests__/partner-api.test.js`.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plaiful/cli",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "The Plaiful CLI: work on your Plaiful product from your game repo, with no AWS access",
5
5
  "bin": {
6
6
  "plaiful": "bin/plaiful.js"
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
- for (const d of docs) lines.push(` ${docName(d.key).padEnd(40)} ${day(d.updated_at)} ${d.title || ''}`);
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 || []).map((d) => `${docName(d.key)} | ${d.title || ''} | updated ${String(d.updated_at || '').slice(0, 10)} | ${d.description || ''}`).join('\n');
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');