@plaiful/cli 0.8.0 → 0.10.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 (3) hide show
  1. package/README.md +8 -0
  2. package/package.json +1 -1
  3. package/src/cli.js +159 -7
package/README.md CHANGED
@@ -78,6 +78,14 @@ plaiful world # the world's states and events in story order, an
78
78
  plaiful events script write y1-s2-m1-the-object-ev-the-recovery --wait # OVID writes the event's cinematic (a draft)
79
79
  plaiful events script get y1-s2-m1-the-object-ev-the-recovery # the screenplay page, the versions, Soter's flags
80
80
  plaiful events script export y1-s2-m1-the-object-ev-the-recovery --vo --out recovery-vo.csv # the voice-over sheet
81
+ plaiful events script approve y1-s2-m1-the-object-ev-the-recovery 2 # the version the game gets (--retire withdraws it)
82
+ plaiful events storyboard draw y1-s2-m1-the-object-ev-the-recovery --style ink-wash --wait # a frame per shot
83
+ plaiful events storyboard get y1-s2-m1-the-object-ev-the-recovery --out boards/ # the frames, saved as PNGs
84
+ plaiful events edit y1-s2-m1-the-object-ev-the-recovery --title "The Recovery" # or --description, --order, --directives f.json
85
+ plaiful events delete <eventId> # and quests delete <questId>; --force for official canon
86
+ plaiful lore add the-sundered-wake --narrative "…" # lore reveal|hide <snippetId>, lore remove <setId>
87
+ plaiful world set kessel_well false --reason "raided" # world truth|faction|var add new ones
88
+ plaiful canon event <eventId> official
81
89
  plaiful animation sets # the animation sets you can use (sets show <id>: its states)
82
90
  plaiful animation sets save # save your own sets from resources/animation/roadforge/*.json (sets delete <id>)
83
91
  plaiful animation run creature crew-portrait --all # a set on an agent's records: one sprite sheet per state
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plaiful/cli",
3
- "version": "0.8.0",
3
+ "version": "0.10.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
@@ -41,12 +41,29 @@ const HELP = `plaiful ${version}: work on your Plaiful product from your game re
41
41
  plaiful quests show <id> one quest: its graph, steps, reward hint and price (--json: the whole record)
42
42
  plaiful lore the lore sets, with known / hidden snippet counts
43
43
  plaiful lore show <setId> one set's snippets
44
+ plaiful lore add <setId> --narrative "…" add a snippet at the end of a set (--hint, --title, --rarity, --known)
45
+ plaiful lore reveal <snippetId> make a snippet known to the world; lore hide <snippetId> hide it again
46
+ plaiful lore remove <setId> delete a set and its snippets (--force for official canon)
44
47
  plaiful world the world's states and state events in story order, and the clock
48
+ plaiful world truth <id> --statement "…" add a world truth (--category foundational|cultural|historical|
49
+ cosmological|political|hidden_truth, --scope)
50
+ plaiful world faction <id> --name "…" add a faction (--description, --type, --homeland)
51
+ plaiful world var <id> <value> add a world variable (--description); world set <id> <value> --reason "…" set it
52
+ plaiful events edit <eventId> change an event (--title, --description, --category, --order <n>,
53
+ --directives <file.json>; --force for official canon)
54
+ plaiful events delete <eventId> delete an event and the events under it (--force for official canon)
55
+ plaiful quests delete <questId> delete a quest and its bindings (--force for official canon)
56
+ plaiful canon event|quest <id> official|draft|rejected set its canon status
45
57
  plaiful events script write <eventId> ask OVID for a cinematic script for a state event (a new draft version;
46
58
  --note "<what to change>", --wait to wait for it, --force to start over)
47
59
  plaiful events script get <eventId> [version] the script as a screenplay page, its versions and the last request
48
60
  plaiful events script export <eventId> [version] --fountain|--vo the screenplay (Fountain) or the voice-over
49
61
  sheet (CSV); --out <file> to write it to a file
62
+ plaiful events script approve <eventId> <version> approve a version: the one the game gets (--retire to withdraw
63
+ it; --force for an official-canon event)
64
+ plaiful events storyboard draw <eventId> [version] --style <style> draw the script's storyboard, a frame per
65
+ shot (--aspect 16:9|4:3|1:1|9:16|21:9, --frame <id> to redraw one, --wait)
66
+ plaiful events storyboard get <eventId> [version] the frames and their captions (--out <dir> saves the images)
50
67
  plaiful lists your product's SSM lists (NPC roles, SmartBuilder list values, ...)
51
68
  plaiful lists get <name> one list (a name in your namespace, e.g. shop_type, or the full /path)
52
69
  plaiful lists set <name> <values...> write a list (values as words, or one comma-separated argument)
@@ -107,8 +124,8 @@ function parse(argv) {
107
124
  const args = [];
108
125
  for (let i = 0; i < argv.length; i += 1) {
109
126
  const a = argv[i];
110
- if (['--json', '--no-browser', '--help', '-h', '--version', '--apply', '--reset', '--rows', '--no-install', '--no-open', '--copies', '--no-render', '--wait', '--force', '--fountain', '--vo', '--all'].includes(a)) flags[a.replace(/^-+/, '')] = true;
111
- else if (['--product', '--api', '--dir', '--dest', '--count', '--base', '--per-effort', '--track', '--series', '--state', '--limit', '--section', '--since', '--note', '--out', '--style'].includes(a)) {
127
+ if (['--json', '--no-browser', '--help', '-h', '--version', '--apply', '--reset', '--rows', '--no-install', '--no-open', '--copies', '--no-render', '--wait', '--force', '--fountain', '--vo', '--all', '--retire', '--known'].includes(a)) flags[a.replace(/^-+/, '')] = true;
128
+ else if (['--product', '--api', '--dir', '--dest', '--count', '--base', '--per-effort', '--track', '--series', '--state', '--limit', '--section', '--since', '--note', '--out', '--style', '--aspect', '--frame', '--title', '--description', '--category', '--order', '--directives', '--narrative', '--hint', '--rarity', '--statement', '--name', '--reason', '--type', '--homeland', '--scope'].includes(a)) {
112
129
  if (argv[i + 1] === undefined) throw new UsageError(`${a} needs a value`);
113
130
  flags[a.slice(2)] = argv[i += 1];
114
131
  } else if (a.startsWith('--')) throw new UsageError(`unknown option ${a}`);
@@ -740,6 +757,10 @@ const priceText = (p) => (p && Object.keys(p).length ? Object.entries(p).map(([k
740
757
 
741
758
  async function quests(ctx, [sub, id]) {
742
759
  const r = repo(ctx);
760
+ if (sub === 'delete') {
761
+ if (!id) throw new UsageError('which quest? plaiful quests delete <questId>');
762
+ return ovidEdit(ctx, 'delete_quest', { quest_id: id }, `Deleted quest ${id}.`);
763
+ }
743
764
  if (sub === 'show') {
744
765
  if (!id) throw new UsageError('which quest? plaiful quests show <id>');
745
766
  const { data } = await ctx.call('GET', ovidRoute(r, `quests/${encodeURIComponent(id)}`));
@@ -756,7 +777,7 @@ async function quests(ctx, [sub, id]) {
756
777
  ctx.out(lines.join('\n'), data);
757
778
  return 0;
758
779
  }
759
- if (sub) throw new UsageError(`plaiful quests, or quests show <id> (not "${sub}")`);
780
+ if (sub) throw new UsageError(`plaiful quests, or quests show | delete <id> (not "${sub}")`);
760
781
  const qs = new URLSearchParams();
761
782
  if (ctx.flags.track) qs.set('track', ctx.flags.track);
762
783
  if (ctx.flags.series) qs.set('series', ctx.flags.series);
@@ -776,6 +797,7 @@ async function quests(ctx, [sub, id]) {
776
797
 
777
798
  async function lore(ctx, [sub, id]) {
778
799
  const r = repo(ctx);
800
+ if (['add', 'reveal', 'hide', 'remove'].includes(sub)) return loreEdit(ctx, sub, id);
779
801
  if (sub === 'show') {
780
802
  if (!id) throw new UsageError('which set? plaiful lore show <setId>');
781
803
  const { data } = await ctx.call('GET', ovidRoute(r, `lore/${encodeURIComponent(id)}`));
@@ -784,7 +806,7 @@ async function lore(ctx, [sub, id]) {
784
806
  ctx.out(lines.join('\n'), data);
785
807
  return 0;
786
808
  }
787
- if (sub) throw new UsageError(`plaiful lore, or lore show <setId> (not "${sub}")`);
809
+ if (sub) throw new UsageError(`plaiful lore, or lore show | add | reveal | hide | remove (not "${sub}")`);
788
810
  const { data } = await ctx.call('GET', ovidRoute(r, 'lore'));
789
811
  const lines = [`${r.product}'s lore in dev: ${data.sets.length} sets`];
790
812
  for (const st of data.sets) lines.push(` ${st.lore_set_id} ${st.title || ''} ${st.snippets} snippets (${st.known} known, ${st.hidden} hidden)${st.source === 'plaiful-seed' ? '' : st.source ? ` from ${st.source}` : ''}`);
@@ -792,7 +814,11 @@ async function lore(ctx, [sub, id]) {
792
814
  return 0;
793
815
  }
794
816
 
795
- async function world(ctx) {
817
+ async function world(ctx, [sub, ...rest] = []) {
818
+ if (sub) {
819
+ if (!['truth', 'faction', 'var', 'set'].includes(sub)) throw new UsageError(`plaiful world, or world truth | faction | var | set (not "${sub}")`);
820
+ return worldEdit(ctx, sub, rest);
821
+ }
796
822
  const r = repo(ctx);
797
823
  const { data } = await ctx.call('GET', ovidRoute(r, 'world'));
798
824
  const c = data.clock;
@@ -807,6 +833,66 @@ async function world(ctx) {
807
833
  return 0;
808
834
  }
809
835
 
836
+ // ── OVID's edits (shared/ovid/edit-ops.js, the list OVID's chat tools use) ──────────────────────────────────────
837
+
838
+ /** A value typed on the command line: true / false, a number, or the word itself. */
839
+ const typedValue = (v) => (v === 'true' ? true : v === 'false' ? false : v !== '' && !Number.isNaN(Number(v)) ? Number(v) : v);
840
+
841
+ async function ovidEdit(ctx, op, params, done) {
842
+ const r = repo(ctx);
843
+ const { data } = await ctx.call('POST', ovidRoute(r, 'edit'), { op, ...params, ...(ctx.flags.force ? { force: true } : {}) });
844
+ ctx.out(`${done}${data.message ? ` (${data.message})` : ''}`, data);
845
+ return 0;
846
+ }
847
+
848
+ async function eventsEdit(ctx, [eventId]) {
849
+ if (!eventId) throw new UsageError('which event? plaiful events edit <eventId> --title "…" (plaiful world lists them)');
850
+ const params = { event_id: eventId };
851
+ for (const [flag, key] of [['title', 'title'], ['description', 'description'], ['category', 'category']]) if (ctx.flags[flag] !== undefined) params[key] = ctx.flags[flag];
852
+ if (ctx.flags.order !== undefined) params.sort_order = Number(ctx.flags.order);
853
+ if (ctx.flags.directives) params.directives = readJsonFile(ctx, ctx.flags.directives).json;
854
+ if (Object.keys(params).length === 1) throw new UsageError('what to change? --title, --description, --category, --order or --directives <file.json>');
855
+ return ovidEdit(ctx, 'update_event', params, `Updated ${eventId}.`);
856
+ }
857
+
858
+ async function eventsDelete(ctx, [eventId]) {
859
+ if (!eventId) throw new UsageError('which event? plaiful events delete <eventId>');
860
+ return ovidEdit(ctx, 'delete_event', { event_id: eventId }, `Deleted ${eventId} and the events under it.`);
861
+ }
862
+
863
+ async function loreEdit(ctx, sub, id) {
864
+ if (!id) throw new UsageError(`plaiful lore ${sub} <${sub === 'add' || sub === 'remove' ? 'setId' : 'snippetId'}>`);
865
+ if (sub === 'add') {
866
+ if (!ctx.flags.narrative) throw new UsageError('--narrative "…" is required: the lore itself');
867
+ return ovidEdit(ctx, 'add_lore_snippet', { lore_set_id: id, narrative: ctx.flags.narrative, hint: ctx.flags.hint, title: ctx.flags.title, rarity: ctx.flags.rarity, ...(ctx.flags.known ? { world_known: true } : {}) }, `Added a snippet to ${id}.`);
868
+ }
869
+ if (sub === 'reveal') return ovidEdit(ctx, 'reveal_lore', { snippet_id: id }, `${id} is known to the world now.`);
870
+ if (sub === 'hide') return ovidEdit(ctx, 'hide_lore', { snippet_id: id }, `${id} is hidden again (players keep what they found).`);
871
+ return ovidEdit(ctx, 'remove_lore_set', { lore_set_id: id }, `Removed ${id} and its snippets.`);
872
+ }
873
+
874
+ async function worldEdit(ctx, sub, [id, value]) {
875
+ if (sub === 'truth') {
876
+ if (!id || !ctx.flags.statement) throw new UsageError('plaiful world truth <id> --statement "…"');
877
+ return ovidEdit(ctx, 'add_truth', { truth_id: id, statement: ctx.flags.statement, category: ctx.flags.category, scope: ctx.flags.scope }, `Added truth ${id}.`);
878
+ }
879
+ if (sub === 'faction') {
880
+ if (!id || !ctx.flags.name) throw new UsageError('plaiful world faction <id> --name "…"');
881
+ return ovidEdit(ctx, 'add_faction', { faction_id: id, name: ctx.flags.name, description: ctx.flags.description, type: ctx.flags.type, homeland: ctx.flags.homeland }, `Added faction ${id}.`);
882
+ }
883
+ if (!id || value === undefined) throw new UsageError(`plaiful world ${sub} <id> <value>${sub === 'set' ? ' --reason "…"' : ''}`);
884
+ if (sub === 'var') return ovidEdit(ctx, 'add_world_variable', { variable_id: id, value: typedValue(value), description: ctx.flags.description }, `Added world variable ${id} = ${value}.`);
885
+ if (!ctx.flags.reason) throw new UsageError('--reason "…" is required: why the world changed');
886
+ return ovidEdit(ctx, 'set_world_variable', { variable_id: id, value: typedValue(value), reason: ctx.flags.reason }, `Set ${id} = ${value}.`);
887
+ }
888
+
889
+ async function canon(ctx, [kind, id, status]) {
890
+ if (!['event', 'quest'].includes(kind) || !id || !['official', 'draft', 'rejected'].includes(status)) {
891
+ throw new UsageError('plaiful canon event|quest <id> official|draft|rejected');
892
+ }
893
+ return ovidEdit(ctx, 'set_canon_status', { kind, id, status }, `${kind} ${id} is ${status} now.`);
894
+ }
895
+
810
896
  // ── Event scripts: OVID's cinematic for a state event ────────────────────────────────────────────────────────────
811
897
 
812
898
  const SCRIPT_WAIT_MS = 5 * 60 * 1000;
@@ -831,7 +917,7 @@ function scriptHeader(data) {
831
917
 
832
918
  async function eventsScript(ctx, [sub, eventId, version]) {
833
919
  const r = repo(ctx);
834
- if (!['write', 'get', 'export'].includes(sub)) throw new UsageError(`plaiful events script write | get | export <eventId> (not "${sub || ''}")`);
920
+ if (!['write', 'get', 'export', 'approve'].includes(sub)) throw new UsageError(`plaiful events script write | get | export | approve <eventId> (not "${sub || ''}")`);
835
921
  if (!eventId) throw new UsageError(`which event? plaiful events script ${sub} <eventId> (plaiful world lists them)`);
836
922
  if (version !== undefined && !/^\d+$/.test(version)) throw new UsageError(`the version is a number (not "${version}")`);
837
923
  const route = ovidRoute(r, `events/${encodeURIComponent(eventId)}/script`);
@@ -841,6 +927,12 @@ async function eventsScript(ctx, [sub, eventId, version]) {
841
927
  if (version) qs.set('version', version);
842
928
  return (await ctx.call('GET', `${route}${qs.toString() ? `?${qs}` : ''}`)).data;
843
929
  };
930
+ if (sub === 'approve') {
931
+ if (!version) throw new UsageError(`which version? plaiful events script approve ${eventId} <version> (plaiful events script get ${eventId} lists them)`);
932
+ const { data } = await ctx.call('POST', `${route}/approve`, { version: Number(version), ...(ctx.flags.retire ? { retire: true } : {}), ...(ctx.flags.force ? { force: true } : {}) });
933
+ ctx.out(data.status === 'approved' ? `Approved ${eventId} v${version}: the game gets this version.` : `Retired ${eventId} v${version}.`, data);
934
+ return 0;
935
+ }
844
936
  if (sub === 'write') {
845
937
  if (version !== undefined) throw new UsageError('write makes a new version; it takes no version number');
846
938
  const { data } = await ctx.call('POST', route, { ...(ctx.flags.note ? { note: ctx.flags.note } : {}), ...(ctx.flags.force ? { force: true } : {}) });
@@ -885,6 +977,62 @@ async function eventsScript(ctx, [sub, eventId, version]) {
885
977
  return 0;
886
978
  }
887
979
 
980
+ // ── Storyboards (SPRITE_ANIMATION.md §13) ──────────────────────────────────────────────────────────────────────
981
+
982
+ const frameLines = (board) => (board.frames || []).map((f) => ` ${f.id.padEnd(6)} ${String(f.framing || '').padEnd(8)} ${(f.caption || '').split('\n')[0].slice(0, 90)}`);
983
+
984
+ async function eventsStoryboard(ctx, [sub, eventId, version]) {
985
+ const r = repo(ctx);
986
+ if (!['draw', 'get'].includes(sub)) throw new UsageError(`plaiful events storyboard draw | get <eventId> (not "${sub || ''}")`);
987
+ if (!eventId) throw new UsageError(`which event? plaiful events storyboard ${sub} <eventId>`);
988
+ if (version !== undefined && !/^\d+$/.test(version)) throw new UsageError(`the version is a number (not "${version}")`);
989
+ const route = ovidRoute(r, `events/${encodeURIComponent(eventId)}/storyboard`);
990
+ const read = async (v) => (await ctx.call('GET', `${route}${v ? `?version=${v}` : ''}`)).data;
991
+ if (sub === 'draw') {
992
+ if (!ctx.flags.style) throw new UsageError('--style <style> is required: the image style to draw in');
993
+ const { data } = await ctx.call('POST', route, { style: ctx.flags.style, ...(version ? { version: Number(version) } : {}),
994
+ ...(ctx.flags.aspect ? { aspect: ctx.flags.aspect } : {}), ...(ctx.flags.frame ? { only: [ctx.flags.frame] } : {}) });
995
+ const lines = [`Drawing ${eventId} v${data.version}: ${ctx.flags.frame ? `frame ${ctx.flags.frame}` : `${data.frames.length} frames`} (job ${data.job_id}).`];
996
+ if ((data.cast_without_art || []).length) lines.push(` no art to match for ${data.cast_without_art.join(', ')}: drawn from the script's words`);
997
+ if (!ctx.flags.wait) {
998
+ lines.push(`It takes a few minutes: plaiful events storyboard get ${eventId} ${data.version}`);
999
+ ctx.out(lines.join('\n'), data);
1000
+ return 0;
1001
+ }
1002
+ const until = Date.now() + SCRIPT_WAIT_MS * 2;
1003
+ let now = null;
1004
+ while (Date.now() < until) {
1005
+ await ctx.io.sleep(SCRIPT_POLL_MS);
1006
+ now = await read(data.version);
1007
+ if (now.storyboard && now.storyboard.job_id === data.job_id) break;
1008
+ }
1009
+ const done = now && now.storyboard && now.storyboard.job_id === data.job_id;
1010
+ lines.push(done ? `Done: ${now.storyboard.frames.length} frames.` : 'Still drawing; plaiful events storyboard get shows it when it lands.');
1011
+ if (done) lines.push(...frameLines(now.storyboard));
1012
+ ctx.out(lines.join('\n'), now || data);
1013
+ return done ? 0 : 1;
1014
+ }
1015
+ const data = await read(version);
1016
+ if (!data.storyboard) {
1017
+ ctx.out(`${eventId} v${data.version}: no storyboard yet${data.job ? ` (one was started ${data.job.at})` : ''}: plaiful events storyboard draw ${eventId} --style <style>`, data);
1018
+ return 0;
1019
+ }
1020
+ const lines = [`${eventId} v${data.version}: ${data.storyboard.frames.length} frames, style ${data.storyboard.style_ref}, ${data.storyboard.aspect}`, ...frameLines(data.storyboard)];
1021
+ if (ctx.flags.out) {
1022
+ const dir = path.resolve(ctx.io.cwd(), ctx.flags.out);
1023
+ fs.mkdirSync(dir, { recursive: true });
1024
+ for (const f of data.storyboard.frames) {
1025
+ if (!f.url) continue;
1026
+ const res = await ctx.io.fetch(f.url, { method: 'GET', headers: {} });
1027
+ if (!res.ok) throw new ApiError(res.status, { error: `couldn't download ${f.id}` });
1028
+ fs.writeFileSync(path.join(dir, `${f.id}.png`), Buffer.from(await res.arrayBuffer()));
1029
+ }
1030
+ lines.push(`saved the frames to ${dir}`);
1031
+ }
1032
+ ctx.out(lines.join('\n'), data);
1033
+ return 0;
1034
+ }
1035
+
888
1036
  // ── What the agents made ────────────────────────────────────────────────────────────────────────────────────────
889
1037
 
890
1038
  const countsText = (a) => `${a.records} records: ${a.made} made, ${a.pending} pending, ${a.failed} failed, ${a.none} none yet${a.truncated ? ' (first 2000)' : ''}`;
@@ -1208,8 +1356,12 @@ const COMMANDS = {
1208
1356
  quests: (ctx, rest) => quests(ctx, rest),
1209
1357
  assets: (ctx, rest) => assets(ctx, rest),
1210
1358
  lore: (ctx, rest) => lore(ctx, rest),
1211
- world: (ctx) => world(ctx),
1359
+ world: (ctx, rest) => world(ctx, rest),
1360
+ 'events edit': (ctx, rest) => eventsEdit(ctx, rest),
1361
+ 'events delete': (ctx, rest) => eventsDelete(ctx, rest),
1362
+ canon: (ctx, rest) => canon(ctx, rest),
1212
1363
  'events script': (ctx, rest) => eventsScript(ctx, rest),
1364
+ 'events storyboard': (ctx, rest) => eventsStoryboard(ctx, rest),
1213
1365
  'animation sets': (ctx, rest) => animationSets(ctx, rest),
1214
1366
  'animation run': (ctx, rest) => animationRun(ctx, rest),
1215
1367
  upload: (ctx, files) => upload(ctx, files),