uro-cli 0.20.0__tar.gz → 0.22.0__tar.gz

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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: uro-cli
3
- Version: 0.20.0
3
+ Version: 0.22.0
4
4
  Summary: Uro Engine reference client — play, dry-run, and dev tools against the engine
5
5
  Project-URL: Homepage, https://github.com/cupskeee/uro
6
6
  Project-URL: Repository, https://github.com/cupskeee/uro
@@ -12,8 +12,8 @@ Requires-Python: >=3.12
12
12
  Requires-Dist: python-dotenv>=1.0
13
13
  Requires-Dist: rich>=13.9
14
14
  Requires-Dist: typer>=0.27.2
15
- Requires-Dist: uro-core[llm,postgres]==0.20.0
16
- Requires-Dist: uro-server==0.20.0
15
+ Requires-Dist: uro-core[llm,postgres]==0.22.0
16
+ Requires-Dist: uro-server==0.22.0
17
17
  Requires-Dist: websockets>=16.1
18
18
  Description-Content-Type: text/markdown
19
19
 
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "uro-cli"
3
- version = "0.20.0"
3
+ version = "0.22.0"
4
4
  description = "Uro Engine reference client — play, dry-run, and dev tools against the engine"
5
5
  license = "MIT"
6
6
  license-files = ["LICENSE"]
@@ -13,8 +13,8 @@ requires-python = ">=3.12"
13
13
  # pair a new uro-cli with an old uro-core; `just release` bumps all three together, and the
14
14
  # `{workspace = true}` sources make a drifted pin fail `uv sync` locally.
15
15
  dependencies = [
16
- "uro-core[postgres,llm]==0.20.0",
17
- "uro-server==0.20.0",
16
+ "uro-core[postgres,llm]==0.22.0",
17
+ "uro-server==0.22.0",
18
18
  "typer>=0.27.2",
19
19
  "rich>=13.9",
20
20
  "websockets>=16.1",
@@ -18,11 +18,12 @@ from typing import Any
18
18
  import typer
19
19
  from dotenv import find_dotenv, load_dotenv
20
20
  from uro_core.adapters.postgres.store import PostgresEventStore
21
+ from uro_core.pipeline.encounter import ChoiceRefused, TurnChoice
21
22
  from uro_core.pipeline.engine import BeatMechanics, BeatResult, Engine
22
23
  from uro_core.ports.model_registry import ROLES
23
24
  from uro_core.providers.router import ProviderRouter
24
25
  from uro_core.rulesets import registry
25
- from uro_core.rulesets.base import CharSpec, Ruleset
26
+ from uro_core.rulesets.base import CharSpec, CharSpecError, Ruleset
26
27
  from uro_core.rulesets.rng import Rng
27
28
  from uro_core.timeline.gear import starting_gear
28
29
  from uro_core.timeline.models import FORK_TIME_SKIP, World
@@ -211,6 +212,48 @@ async def _time_skip_ruleset(pick: Awaitable[Ruleset]) -> Ruleset | None:
211
212
  return None
212
213
 
213
214
 
215
+ def _json_option(raw: str | None, flag: str) -> dict[str, Any] | None:
216
+ """A JSON-object option (`--spec`, `--ruleset-config`): inline JSON, or `@path` to a file."""
217
+ if raw is None:
218
+ return None
219
+ try:
220
+ text = Path(raw[1:]).read_text() if raw.startswith("@") else raw
221
+ value = json.loads(text)
222
+ except (OSError, ValueError) as exc:
223
+ typer.echo(f"{flag}: not a JSON object ({exc})", err=True)
224
+ raise typer.Exit(2) from exc
225
+ if not isinstance(value, dict):
226
+ typer.echo(f"{flag}: not a JSON object", err=True)
227
+ raise typer.Exit(2)
228
+ return value
229
+
230
+
231
+ def _json_list_option(raw: str | None, flag: str) -> list[Any] | None:
232
+ """A JSON-array option (`--holdings`): inline JSON, or `@path` to a file."""
233
+ if raw is None:
234
+ return None
235
+ try:
236
+ value = json.loads(Path(raw[1:]).read_text() if raw.startswith("@") else raw)
237
+ except (OSError, ValueError) as exc:
238
+ typer.echo(f"{flag}: not a JSON list ({exc})", err=True)
239
+ raise typer.Exit(2) from exc
240
+ if not isinstance(value, list):
241
+ typer.echo(f"{flag}: not a JSON list", err=True)
242
+ raise typer.Exit(2)
243
+ return value
244
+
245
+
246
+ def _echo_refused(exc: Exception) -> None:
247
+ """A refused start, join or build, with each spec problem on its own line (D-112)."""
248
+ if isinstance(exc, CharSpecError):
249
+ typer.echo("the character can't be built:", err=True)
250
+ for p in exc.problems:
251
+ where = ".".join(str(x) for x in p.loc)
252
+ typer.echo(f" {where + ': ' if where else ''}{p.message}", err=True)
253
+ else:
254
+ typer.echo(f"error: {exc.args[0] if exc.args else exc}", err=True)
255
+
256
+
214
257
  def _build_pc_sheet(ruleset: Ruleset) -> dict[str, Any]:
215
258
  """A default character sheet from the world's bound ruleset (with the world's settings), so
216
259
  every PC can be checked (docs/06) — a PbtA world mints a PbtA sheet."""
@@ -496,7 +539,7 @@ def world_backfill(
496
539
  # policy, when the database answers (D-108 review)
497
540
  makes_people = await _play_creates_actors()
498
541
  before = check_sufficiency(pack, play_creates_actors=makes_people)
499
- if before.grade == "runnable":
542
+ if before.grade == "runnable" and pack.characters:
500
543
  typer.echo("pack is already runnable — nothing to backfill")
501
544
  return
502
545
  async with _metered(build_router(provider, model)) as router:
@@ -659,15 +702,33 @@ def play(
659
702
  break
660
703
  if not intent:
661
704
  continue
705
+ if intent.startswith("/choose "): # D-113: /choose <id> <json answer>
706
+ from uro_core.characters import ChoiceError, answer_character_choice
707
+
708
+ cid, _, raw = intent[8:].strip().partition(" ")
709
+ try:
710
+ view = await answer_character_choice(
711
+ store, campaign, PARTICIPANT, cid, json.loads(raw) if raw else {}
712
+ )
713
+ left = ", ".join(c.id for c in view.choices) or "none"
714
+ typer.echo(f" · answered {cid}; choices left: {left}")
715
+ except (ValueError, CharSpecError, ChoiceError, KeyError) as exc:
716
+ _echo_refused(exc)
717
+ continue
718
+ choice = parse_act(intent) # D-112: `/act <kind> [target]` on a fight turn
719
+ if intent.startswith("/act") and choice is None:
720
+ typer.echo("usage: /act <action> [target]", err=True)
721
+ continue
662
722
  try:
663
723
  results: list[BeatResult] = []
664
724
  mechanics: list[BeatMechanics] = []
665
725
  async for chunk in engine.run_beat_stream(
666
726
  campaign,
667
727
  PARTICIPANT,
668
- intent,
728
+ intent[4:].strip() if choice is not None else intent,
669
729
  on_result=results.append,
670
730
  on_mechanics=mechanics.append,
731
+ action=TurnChoice.model_validate(choice) if choice else None,
671
732
  ):
672
733
  if mechanics: # the rules' answer, before the story (D-100)
673
734
  m = mechanics.pop()
@@ -683,6 +744,12 @@ def play(
683
744
  typer.echo(line)
684
745
  if results:
685
746
  day = results[0].world_day
747
+ except ChoiceRefused as exc:
748
+ sys.stdout.write("\n")
749
+ for line in refusal_lines(
750
+ str(exc), [a.model_dump() for a in exc.legal_actions]
751
+ ):
752
+ typer.echo(line, err=True)
686
753
  except Exception as exc:
687
754
  sys.stdout.write("\n")
688
755
  typer.echo(f"beat failed ({exc}); nothing was saved — try again.", err=True)
@@ -701,9 +768,28 @@ def _details(result: BeatResult) -> dict[str, Any]:
701
768
  "world_day": result.world_day,
702
769
  "created": [c.model_dump() for c in result.created],
703
770
  "threads_changed": [t.model_dump() for t in result.threads_changed],
771
+ "encounter": result.encounter.model_dump() if result.encounter is not None else None,
772
+ "choices": [c.model_dump() for c in result.choices],
704
773
  }
705
774
 
706
775
 
776
+ def parse_act(line: str) -> dict[str, Any] | None:
777
+ """`/act <kind> [target]` as an encounter action (D-112), or None when it isn't one."""
778
+ parts = line.split()
779
+ if len(parts) < 2 or parts[0] != "/act":
780
+ return None
781
+ return {"kind": parts[1], "target_id": parts[2] if len(parts) > 2 else None}
782
+
783
+
784
+ def refusal_lines(reason: str, legal: list[dict[str, Any]]) -> list[str]:
785
+ """A refused fight-turn action and what may be done instead (D-112)."""
786
+ lines = [f" ! {reason}"]
787
+ for a in legal:
788
+ targets = f" <{'|'.join(a.get('targets') or [])}>" if a.get("targets") else ""
789
+ lines.append(f" /act {a['kind']}{targets}")
790
+ return lines
791
+
792
+
707
793
  def mechanics_lines(details: dict[str, Any]) -> list[str]:
708
794
  """Each check's outcome and a fight — what the rules decided (shown before the narration
709
795
  when the server sends `beat_checks`, D-100)."""
@@ -730,6 +816,14 @@ def beat_detail_lines(
730
816
  for t in details.get("threads_changed") or []: # D-103: any plot whose state moved
731
817
  moved = f"{t['from_state']} → {t['to_state']}" if t["from_state"] else t["to_state"]
732
818
  lines.append(f" ~ plot {moved}: {t['stakes']}")
819
+ if mine: # D-113: choices the ruleset left on the player's own character
820
+ for c in details.get("choices") or []:
821
+ lines.append(f" ? {c['id']}: {c['prompt']} — `uro character choose` or /choose")
822
+ wait = details.get("encounter") # D-112: the fight waits on a player's choice
823
+ if wait:
824
+ who = f" (player {wait['participant_id']})" if wait.get("participant_id") else ""
825
+ lines.append(f" · the fight waits on {wait['actor_id']}{who}:")
826
+ lines += refusal_lines("", wait.get("legal_actions") or [])[1:]
733
827
  created = details.get("created") or []
734
828
  if created:
735
829
  lines.append(" + new: " + ", ".join(f"{c['name']} ({c['kind']})" for c in created))
@@ -887,7 +981,8 @@ def serve(
887
981
  )
888
982
  typer.echo(f" LLM: {llm_source}")
889
983
  for t, p in tokens.items():
890
- typer.echo(f" token {t!r} → {p}")
984
+ role = " (operator)" if t in admin_tokens else ""
985
+ typer.echo(f" token {_mask_token(t)} → {p}{role}")
891
986
  if cors_origin:
892
987
  typer.echo(f" CORS: allowing {', '.join(cors_origin)}")
893
988
  if nats_url:
@@ -895,6 +990,14 @@ def serve(
895
990
  uvicorn.run(fastapi_app, host=host, port=port, log_level="warning")
896
991
 
897
992
 
993
+ def _mask_token(token: str) -> str:
994
+ """A token as the startup lines show it: enough to tell tokens apart, never the secret itself.
995
+ A terminal's scrollback and a process log are read by more people than the token's holder."""
996
+ if len(token) < 12:
997
+ return f"**** ({len(token)} chars)"
998
+ return f"{token[:4]}…{token[-2:]} ({len(token)} chars)"
999
+
1000
+
898
1001
  @app.command()
899
1002
  def connect(
900
1003
  campaign_id: str,
@@ -938,12 +1041,14 @@ def connect(
938
1041
  "not_your_turn",
939
1042
  "proposal_opened",
940
1043
  "intent_rejected",
1044
+ "encounter_action_refused", # D-112: a fight waits on a different choice
941
1045
  }
942
1046
  # intent id → (its text, set when it settles). The server echoes the id as
943
1047
  # `intent_id`, so another player's identical text never settles ours. Only a server
944
1048
  # that has never echoed one (an older one) is matched by text; once one has, a frame
945
1049
  # without an id is another client's.
946
1050
  pending: dict[str, tuple[str, asyncio.Event]] = {}
1051
+ asked: set[str] = set() # the ids of this client's `choose` frames (D-113)
947
1052
  echoes = False
948
1053
  seen_day: int | None = None # the day the last beat_committed showed
949
1054
  checked: set[str] = set() # intents whose beat_checks were already printed
@@ -1027,6 +1132,21 @@ def connect(
1027
1132
  typer.echo(
1028
1133
  f"\n ✗ beat failed ({msg.get('intent', '')!r}): {msg['error']}"
1029
1134
  )
1135
+ elif kind == "choice_answered" and str(msg.get("intent_id")) in asked:
1136
+ left = ", ".join(c["id"] for c in msg.get("choices") or []) or "none"
1137
+ typer.echo(f" · answered {msg.get('choice_id')}; choices left: {left}")
1138
+ elif kind == "choice_refused" and str(msg.get("intent_id")) in asked:
1139
+ typer.echo(f" ! {msg.get('reason')}")
1140
+ elif kind == "encounter_action_refused" and ours:
1141
+ # every seat hears it; only the player who acted is shown it (review)
1142
+ for line in refusal_lines(
1143
+ msg["reason"], msg.get("legal_actions") or []
1144
+ ):
1145
+ typer.echo(line)
1146
+ if msg.get("waiting_on"): # D-114: it is another character's move
1147
+ typer.echo(f" (the fight waits on {msg['waiting_on']})")
1148
+ elif kind == "encounter_abandoned": # D-114: the game closed the fight
1149
+ typer.echo(" · the fight was closed, undecided")
1030
1150
  elif kind == "intent_rejected":
1031
1151
  typer.echo(
1032
1152
  f" ✗ [{msg['participant_id']}] intent rejected: {msg['text']!r}"
@@ -1050,6 +1170,26 @@ def connect(
1050
1170
  break
1051
1171
  if intent in ("/quit", "/exit"):
1052
1172
  break
1173
+ if intent.startswith("/choose "): # D-113: /choose <id> <json answer>
1174
+ cid, _, raw = intent[8:].strip().partition(" ")
1175
+ try:
1176
+ ans = json.loads(raw) if raw.strip() else {}
1177
+ except ValueError:
1178
+ typer.echo("usage: /choose <choice_id> <json answer>")
1179
+ continue
1180
+ cid_req = uuid.uuid4().hex
1181
+ asked.add(cid_req)
1182
+ await ws.send(
1183
+ json.dumps(
1184
+ {
1185
+ "type": "choose",
1186
+ "choice_id": cid,
1187
+ "answer": ans,
1188
+ "id": cid_req,
1189
+ }
1190
+ )
1191
+ )
1192
+ continue
1053
1193
  if intent.startswith("/say "): # non-canon table-talk (D-38)
1054
1194
  await ws.send(json.dumps({"type": "table_talk", "text": intent[5:]}))
1055
1195
  elif intent.startswith("/vote "): # non-canon consensus vote (D-38)
@@ -1057,8 +1197,16 @@ def connect(
1057
1197
  elif intent:
1058
1198
  rid = uuid.uuid4().hex
1059
1199
  settled = asyncio.Event()
1060
- pending[rid] = (intent, settled)
1061
- await ws.send(json.dumps({"type": "intent", "text": intent, "id": rid}))
1200
+ act = parse_act(intent) # D-112: `/act <kind> [target]`, a fight turn
1201
+ if act is None and intent.split()[0] == "/act":
1202
+ typer.echo("usage: /act <action> [target]")
1203
+ continue
1204
+ text = intent[4:].strip() if act is not None else intent
1205
+ pending[rid] = (text, settled)
1206
+ frame: dict[str, Any] = {"type": "intent", "text": text, "id": rid}
1207
+ if act is not None:
1208
+ frame["action"] = act
1209
+ await ws.send(json.dumps(frame))
1062
1210
  waiting = asyncio.ensure_future(settled.wait())
1063
1211
  # a slow beat (a reasoning model's extraction) still settles well
1064
1212
  # inside this; past it, or if the server goes away, the prompt returns
@@ -1586,13 +1734,23 @@ def chronicle(
1586
1734
  else:
1587
1735
  w = await _world_or_exit(store, world)
1588
1736
  branch_id = (await _branch_or_exit(store, w, branch)).branch_id
1589
- beats = await store.recent_beats(branch_id, limit)
1737
+ records = await store.beat_records(branch_id, limit)
1590
1738
  finally:
1591
1739
  await store.close()
1592
- if not beats:
1740
+ if not records:
1593
1741
  typer.echo("(no beats yet)")
1594
- for beat in beats:
1742
+ for record in records: # each beat's words, then what its commit said (D-115)
1743
+ beat = record.beat
1595
1744
  typer.echo(f"> [{beat.participant_id}] {beat.intent_text}")
1745
+ for check in record.checks:
1746
+ typer.echo(f" · {check.affordance}: {check.outcome}")
1747
+ if record.mode == "encounter":
1748
+ typer.echo(" · a fight")
1749
+ if record.created:
1750
+ made = ", ".join(f"{c.name} ({c.kind})" for c in record.created)
1751
+ typer.echo(f" + new: {made}")
1752
+ for t in record.threads_changed:
1753
+ typer.echo(f" ~ plot {t.from_state or 'new'} → {t.to_state}: {t.stakes}")
1596
1754
  typer.echo(f"{beat.narration}\n")
1597
1755
 
1598
1756
  _run_async(_run)
@@ -1712,6 +1870,53 @@ def rules_validate(path: str) -> None:
1712
1870
  )
1713
1871
 
1714
1872
 
1873
+ @ruleset_app.command("describe")
1874
+ def ruleset_describe(
1875
+ ruleset_id: str = typer.Argument(..., help="A ruleset id, as `uro ruleset list` shows them."),
1876
+ config: Path | None = typer.Option( # noqa: B008
1877
+ None,
1878
+ "--config",
1879
+ help="The settings to describe it under: a .toml or .json file (what a world's "
1880
+ "`[ruleset.config]` or a campaign's settings would hold). Default: its defaults.",
1881
+ ),
1882
+ as_json: bool = typer.Option(False, "--json", help="Everything, as JSON."),
1883
+ ) -> None:
1884
+ """One ruleset as it stands under given settings (D-114): the checks it offers and what a
1885
+ character spec may say. For a ruleset whose game is its settings (uro-composable; examples in
1886
+ examples/definitions/), this is how to read the game."""
1887
+ import tomllib
1888
+
1889
+ from uro_core.characters import ruleset_info
1890
+
1891
+ settings: dict[str, Any] | None = None
1892
+ if config is not None:
1893
+ try:
1894
+ text = config.read_text()
1895
+ settings = tomllib.loads(text) if config.suffix == ".toml" else json.loads(text)
1896
+ except (OSError, ValueError) as exc:
1897
+ typer.echo(f"can't read {config}: {exc}", err=True)
1898
+ raise typer.Exit(1) from exc
1899
+ try:
1900
+ info = ruleset_info(registry.resolve(ruleset_id, "", settings))
1901
+ except (KeyError, ValueError) as exc:
1902
+ typer.echo(str(exc.args[0]) if exc.args else str(exc), err=True)
1903
+ raise typer.Exit(1) from exc
1904
+ if as_json:
1905
+ typer.echo(json.dumps(info, indent=2))
1906
+ return
1907
+ typer.echo(f"{info['id']}@{info['version']}")
1908
+ spec = info["spec_schema"]
1909
+ closed = spec.get("additionalProperties") is False
1910
+ keys = ", ".join(spec.get("properties", {})) or ("(nothing to choose)" if closed else "(any)")
1911
+ typer.echo(f" spec: {keys}")
1912
+ if not info["affordances"]:
1913
+ typer.echo(" no checks: every beat is narration")
1914
+ for a in info["affordances"]:
1915
+ triggers = f" [{', '.join(a['trigger_categories'])}]" if a["trigger_categories"] else ""
1916
+ fight = " (starts a fight)" if a["starts_encounter"] else ""
1917
+ typer.echo(f" {a['id']}: {a['description']}{triggers}{fight}")
1918
+
1919
+
1715
1920
  @ruleset_app.command("list")
1716
1921
  def ruleset_list() -> None:
1717
1922
  """The rulesets a world can declare (`\\[ruleset] id` in world.toml): the built-ins and
@@ -1723,10 +1928,15 @@ def ruleset_list() -> None:
1723
1928
  rs = registry.resolve(rid)
1724
1929
  sheet = ", ".join(rs.sheet_schema().get("properties", {}))
1725
1930
  settings = rs.config_schema().get("properties", {})
1931
+ from uro_core.rulesets.base import spec_schema_of
1932
+
1933
+ spec_keys = ", ".join(spec_schema_of(rs).get("properties", {}))
1726
1934
  except Exception as exc:
1727
1935
  typer.echo(f"{rid} (can't list with default settings: {exc})")
1728
1936
  continue
1729
1937
  typer.echo(f"{rs.id}@{rs.version} sheet: {sheet}")
1938
+ if spec_keys: # what `--spec` may hold (D-112)
1939
+ typer.echo(f" spec: {spec_keys}")
1730
1940
  for key, spec in settings.items():
1731
1941
  what = spec.get("description", "")
1732
1942
  typer.echo(f" {key:<24} default {spec.get('default')!s:<5} {what}")
@@ -2007,13 +2217,36 @@ def campaign_new(
2007
2217
  branch_name: str = typer.Option(
2008
2218
  None, "--branch-name", help="with --own-branch: the new branch's name (default play-…)"
2009
2219
  ),
2220
+ spec: str = typer.Option(
2221
+ None, "--spec", help="the PC's build as JSON, or @file.json (the ruleset's spec, D-112)"
2222
+ ),
2223
+ ruleset_id: str = typer.Option(
2224
+ None, "--ruleset", help="this campaign's own ruleset (D-112; default: inherit)"
2225
+ ),
2226
+ ruleset_config: str = typer.Option(
2227
+ None, "--ruleset-config", help="this campaign's own settings as JSON, or @file.json"
2228
+ ),
2229
+ encounters: str = typer.Option(
2230
+ "auto", "--encounters", help="auto (a fight is one beat) | turns (pick each action)"
2231
+ ),
2232
+ holdings: str = typer.Option(
2233
+ None, "--holdings", help="what the PC starts holding: JSON [{name, data?}] or @file (D-113)"
2234
+ ),
2235
+ character: str = typer.Option(
2236
+ None, "--character", help="begin as a character the world suggests (`world characters`)"
2237
+ ),
2010
2238
  ) -> None:
2011
2239
  """Start a campaign on a branch, binding a PC (adopt an existing actor, or create one).
2012
- With --own-branch it gets a branch of its own, so it can later be removed alone (D-99)."""
2240
+ With --own-branch it gets a branch of its own, so it can later be removed alone (D-99).
2241
+ --ruleset / --ruleset-config give the campaign its own game (D-112); otherwise a fork plays
2242
+ the story it came from's, and any other branch its world's."""
2013
2243
 
2014
2244
  async def _run() -> None:
2015
- if (adopt is None) == (pc is None):
2016
- typer.echo("provide exactly one of --adopt <actor_id> or --pc <name>", err=True)
2245
+ if (adopt is None) == (pc is None and character is None):
2246
+ typer.echo(
2247
+ "provide exactly one of --adopt <actor_id> or --pc <name> (or --character)",
2248
+ err=True,
2249
+ )
2017
2250
  raise typer.Exit(1)
2018
2251
  store = build_store()
2019
2252
  await connect_store(store)
@@ -2037,33 +2270,29 @@ def campaign_new(
2037
2270
  typer.echo(f"error: {exc}", err=True)
2038
2271
  raise typer.Exit(1) from exc
2039
2272
  try: # from here on, a failure removes the playthrough's fork (D-100 review)
2040
- # Bind the WORLD's declared ruleset (docs/06, D-30): a PbtA world's campaign is
2041
- # played under uro_pbta, not the hard-coded default. ('' → registry default.)
2042
- pin = await store.world_ruleset(b.branch_id)
2043
- # with the world's settings
2044
- rs = await registry.resolve_for_branch(store, b.branch_id)
2045
- # Every PC needs a sheet so the mechanics gate can check it. A fresh PC gets one; an
2046
- # adopted actor is sheeted only if it lacks one (a re-adopted PC keeps its sheet).
2047
- pc_sheet = None
2048
- if pc is not None or (
2049
- adopt is not None and await store.get_sheet(b.branch_id, adopt) is None
2050
- ):
2051
- pc_sheet = _build_pc_sheet(rs)
2052
- ruleset_id = rs.id
2053
- campaign = await store.start_campaign(
2054
- w.world_id,
2055
- b.branch_id,
2056
- participant_id=participant,
2057
- adopt_actor_id=adopt,
2058
- new_pc_name=pc,
2059
- pc_sheet=pc_sheet,
2060
- starting_items=(
2061
- await starting_gear(store, b.branch_id) if pc is not None else None
2062
- ),
2063
- ruleset_id=ruleset_id,
2064
- ruleset_version=pin.version,
2065
- seed=seed,
2066
- )
2273
+ # The campaign's game and its PC's build (D-112), through the one core path the
2274
+ # server uses: the named ruleset, else a fork's story's, else the world's.
2275
+ from uro_core.characters import start_campaign
2276
+
2277
+ try:
2278
+ campaign = await start_campaign(
2279
+ store,
2280
+ w.world_id,
2281
+ b.branch_id,
2282
+ participant_id=participant,
2283
+ adopt_actor_id=adopt,
2284
+ new_pc_name=pc,
2285
+ spec=_json_option(spec, "--spec"),
2286
+ ruleset_id=ruleset_id,
2287
+ ruleset_config=_json_option(ruleset_config, "--ruleset-config"),
2288
+ seed=seed,
2289
+ encounters=encounters,
2290
+ holdings=_json_list_option(holdings, "--holdings"),
2291
+ character=character,
2292
+ )
2293
+ except (CharSpecError, ValueError, KeyError) as exc:
2294
+ _echo_refused(exc)
2295
+ raise typer.Exit(1) from exc
2067
2296
  except BaseException:
2068
2297
  if own_branch: # nothing half-made: the playthrough's fork goes too
2069
2298
  await store.delete_branch(b.branch_id)
@@ -2077,6 +2306,51 @@ def campaign_new(
2077
2306
  _run_async(_run)
2078
2307
 
2079
2308
 
2309
+ @campaign_app.command("encounter")
2310
+ def campaign_encounter(
2311
+ campaign_id: str,
2312
+ participant: str = typer.Option(None, "--participant", help="whose fight (default: any)"),
2313
+ abandon: bool = typer.Option(
2314
+ False,
2315
+ "--abandon",
2316
+ help="end the fight without deciding it (D-114): sheets stay as they are",
2317
+ ),
2318
+ ) -> None:
2319
+ """The fight waiting on a player's choice in a campaign that plays fights turn by turn
2320
+ (D-112): whose turn it is and the actions to send (`/act` in `uro play`/`uro connect`).
2321
+ `--abandon` closes it undecided: nobody wins, is wounded or looted."""
2322
+
2323
+ async def _run() -> None:
2324
+ store = build_store()
2325
+ await connect_store(store)
2326
+ try:
2327
+ c = await _campaign_or_exit(store, campaign_id)
2328
+ engine = Engine(
2329
+ store,
2330
+ build_router("stub", None),
2331
+ ruleset=await registry.resolve_for_campaign(store, c),
2332
+ )
2333
+ try:
2334
+ if abandon:
2335
+ ended = await engine.abandon_fight(c, participant)
2336
+ typer.echo(f"abandoned {ended}" if ended else "(no fight was open)")
2337
+ return
2338
+ wait = await engine.fight_status(c, participant)
2339
+ except ChoiceRefused as exc:
2340
+ typer.echo(f"error: {exc}", err=True)
2341
+ raise typer.Exit(1) from exc
2342
+ finally:
2343
+ await store.close()
2344
+ if wait is None:
2345
+ typer.echo("(no fight is waiting on a choice)")
2346
+ return
2347
+ typer.echo(f"the fight {wait.encounter_id} waits on {wait.actor_id}:")
2348
+ for line in refusal_lines("", [a.model_dump() for a in wait.legal_actions])[1:]:
2349
+ typer.echo(line)
2350
+
2351
+ _run_async(_run)
2352
+
2353
+
2080
2354
  @campaign_app.command("time-skip")
2081
2355
  def campaign_time_skip(
2082
2356
  campaign_id: str,
@@ -2174,14 +2448,26 @@ def campaign_join(
2174
2448
  participant: str = typer.Option(..., "--participant", help="joining participant id"),
2175
2449
  adopt: str = typer.Option(None, "--adopt", help="adopt an existing actor as this PC"),
2176
2450
  pc: str = typer.Option(None, "--pc", help="create a fresh PC with this name"),
2451
+ spec: str = typer.Option(
2452
+ None, "--spec", help="the PC's build as JSON, or @file.json (the ruleset's spec, D-112)"
2453
+ ),
2454
+ holdings: str = typer.Option(
2455
+ None, "--holdings", help="what the PC starts holding: JSON [{name, data?}] or @file (D-113)"
2456
+ ),
2457
+ character: str = typer.Option(
2458
+ None, "--character", help="begin as a character the world suggests (`world characters`)"
2459
+ ),
2177
2460
  ) -> None:
2178
2461
  """Seat an ADDITIONAL participant on a live campaign, binding their OWN PC (docs/08, OQ-7) —
2179
2462
  the party-join path. Round-robin free-roam then rotates turns across the party (`uro serve`
2180
2463
  with multiple --token spins up a PartyArbiter)."""
2181
2464
 
2182
2465
  async def _run() -> None:
2183
- if (adopt is None) == (pc is None):
2184
- typer.echo("provide exactly one of --adopt <actor_id> or --pc <name>", err=True)
2466
+ if (adopt is None) == (pc is None and character is None):
2467
+ typer.echo(
2468
+ "provide exactly one of --adopt <actor_id> or --pc <name> (or --character)",
2469
+ err=True,
2470
+ )
2185
2471
  raise typer.Exit(1)
2186
2472
  store = build_store()
2187
2473
  await connect_store(store)
@@ -2190,23 +2476,23 @@ def campaign_join(
2190
2476
  if campaign is None:
2191
2477
  typer.echo(f"no such campaign: {campaign_id}", err=True)
2192
2478
  raise typer.Exit(1)
2193
- # Sheet a fresh PC (or an adopted actor lacking one) from the campaign's bound ruleset.
2194
- pc_sheet = None
2195
- if pc is not None or (
2196
- adopt is not None and await store.get_sheet(campaign.branch_id, adopt) is None
2197
- ):
2198
- pc_sheet = _build_pc_sheet(await registry.resolve_for_campaign(store, campaign))
2199
- actor = await store.bind_pc(
2200
- campaign_id,
2201
- participant,
2202
- adopt_actor_id=adopt,
2203
- new_pc_name=pc,
2204
- pc_sheet=pc_sheet,
2205
- starting_items=(
2206
- await starting_gear(store, campaign.branch_id) if pc is not None else None
2207
- ),
2208
- ruleset_id=campaign.ruleset_id,
2209
- )
2479
+ # Sheet the PC from --spec under the campaign's game (D-112), as the server does.
2480
+ from uro_core.characters import join_campaign
2481
+
2482
+ try:
2483
+ actor = await join_campaign(
2484
+ store,
2485
+ campaign,
2486
+ participant_id=participant,
2487
+ adopt_actor_id=adopt,
2488
+ new_pc_name=pc,
2489
+ spec=_json_option(spec, "--spec"),
2490
+ holdings=_json_list_option(holdings, "--holdings"),
2491
+ character=character,
2492
+ )
2493
+ except (CharSpecError, ValueError, KeyError) as exc:
2494
+ _echo_refused(exc)
2495
+ raise typer.Exit(1) from exc
2210
2496
  finally:
2211
2497
  await store.close()
2212
2498
  typer.echo(f"joined: participant {participant!r} → PC {actor}")
@@ -2214,6 +2500,261 @@ def campaign_join(
2214
2500
  _run_async(_run)
2215
2501
 
2216
2502
 
2503
+ character_app = typer.Typer(
2504
+ no_args_is_help=True,
2505
+ help="A participant's character: preview a build, show it, rebuild it before play (D-112).",
2506
+ )
2507
+ app.add_typer(character_app, name="character")
2508
+
2509
+
2510
+ @world_app.command("characters")
2511
+ def world_characters(world: str) -> None:
2512
+ """The player characters a world's author suggests (D-113): start as one with
2513
+ `campaign new --character <id>`."""
2514
+
2515
+ async def _run() -> None:
2516
+ store = build_store()
2517
+ await connect_store(store)
2518
+ try:
2519
+ w = await _world_or_exit(store, world)
2520
+ suggested = await store.world_characters(w.main_branch_id)
2521
+ finally:
2522
+ await store.close()
2523
+ if not suggested:
2524
+ typer.echo("(the world suggests no characters)")
2525
+ for c in suggested:
2526
+ tag = "" if c.get("provenance", "author") == "author" else f" [{c['provenance']}]"
2527
+ typer.echo(
2528
+ f"{c['id']} {c['name']}{tag}" + (f" — {c['line']}" if c.get("line") else "")
2529
+ )
2530
+
2531
+ _run_async(_run)
2532
+
2533
+
2534
+ @character_app.command("show")
2535
+ def character_show(
2536
+ campaign_id: str,
2537
+ participant: str = typer.Option(PARTICIPANT, "--participant", help="whose character"),
2538
+ ) -> None:
2539
+ """A participant's character: name, sheet, what it holds, and whether its build is open."""
2540
+
2541
+ async def _run() -> None:
2542
+ from uro_core.characters import own_character
2543
+
2544
+ store = build_store()
2545
+ await connect_store(store)
2546
+ try:
2547
+ c = await _campaign_or_exit(store, campaign_id)
2548
+ try:
2549
+ view = await own_character(store, c, participant)
2550
+ except KeyError as exc:
2551
+ typer.echo(f"error: {exc.args[0]}", err=True)
2552
+ raise typer.Exit(1) from exc
2553
+ finally:
2554
+ await store.close()
2555
+ state = "open until the first beat" if view.build_open else f"frozen: {view.frozen_reason}"
2556
+ typer.echo(f"{view.name} [{view.actor_id}] ruleset {view.ruleset} build {state}")
2557
+ typer.echo(json.dumps(view.sheet, indent=2, sort_keys=True))
2558
+ for c in view.choices: # D-113: what the ruleset left for this player to decide
2559
+ typer.echo(f" ? {c.id}: {c.prompt}")
2560
+ for o in c.options:
2561
+ typer.echo(f" {json.dumps(o, sort_keys=True)}")
2562
+ for h in view.holdings:
2563
+ typer.echo(
2564
+ f" holds {h['name']} [{h['item_id']}]" + (f" {h['data']}" if h["data"] else "")
2565
+ )
2566
+
2567
+ _run_async(_run)
2568
+
2569
+
2570
+ @character_app.command("preview")
2571
+ def character_preview(
2572
+ target: str = typer.Argument(..., help="a world (a new campaign's game) or a campaign id"),
2573
+ spec: str = typer.Option(None, "--spec", help="the build as JSON, or @file.json"),
2574
+ branch: str = typer.Option("main", "--branch", help="for a world: the branch to start on"),
2575
+ ruleset_id: str = typer.Option(None, "--ruleset", help="for a world: a campaign's own ruleset"),
2576
+ ruleset_config: str = typer.Option(
2577
+ None, "--ruleset-config", help="for a world: a campaign's own settings as JSON"
2578
+ ),
2579
+ ) -> None:
2580
+ """The sheet a build would make, or the ruleset's problems with it. Writes nothing."""
2581
+
2582
+ async def _run() -> None:
2583
+ from uro_core.characters import preview_character
2584
+
2585
+ store = build_store()
2586
+ await connect_store(store)
2587
+ try:
2588
+ data = _json_option(spec, "--spec")
2589
+ campaign = await store.get_campaign(target)
2590
+ try:
2591
+ if campaign is not None:
2592
+ preview = await preview_character(
2593
+ store, branch_id=campaign.branch_id, spec=data, campaign=campaign
2594
+ )
2595
+ else:
2596
+ w = await _world_or_exit(store, target)
2597
+ b = await store.get_branch_by_name(w.world_id, branch)
2598
+ if b is None:
2599
+ typer.echo(f"no such branch: {branch}", err=True)
2600
+ raise typer.Exit(1)
2601
+ preview = await preview_character(
2602
+ store,
2603
+ branch_id=b.branch_id,
2604
+ spec=data,
2605
+ ruleset_id=ruleset_id,
2606
+ ruleset_config=_json_option(ruleset_config, "--ruleset-config"),
2607
+ )
2608
+ except (ValueError, KeyError) as exc:
2609
+ _echo_refused(exc)
2610
+ raise typer.Exit(1) from exc
2611
+ finally:
2612
+ await store.close()
2613
+ left = (preview.guidance or {}).get("left") or []
2614
+ if not preview.ok:
2615
+ _echo_refused(CharSpecError(preview.problems))
2616
+ if left: # D-114: the ruleset's own count of what the build still wants
2617
+ typer.echo(f"still to do: {json.dumps(left)}", err=True)
2618
+ raise typer.Exit(1)
2619
+ typer.echo(f"ok ({preview.ruleset}):")
2620
+ typer.echo(json.dumps(preview.sheet, indent=2, sort_keys=True))
2621
+ if left:
2622
+ typer.echo(f"still to do: {json.dumps(left)}")
2623
+
2624
+ _run_async(_run)
2625
+
2626
+
2627
+ @character_app.command("propose")
2628
+ def character_propose(
2629
+ target: str = typer.Argument(..., help="a world (a new campaign's game) or a campaign id"),
2630
+ description: str = typer.Argument(..., help="the player's words for their character"),
2631
+ provider: str = typer.Option("openai", help="stub | local | openai | anthropic"),
2632
+ model: str = typer.Option(None, help="model id for the worldsmith role"),
2633
+ branch: str = typer.Option("main", "--branch", help="for a world: the branch to start on"),
2634
+ ruleset_id: str = typer.Option(None, "--ruleset", help="for a world: a campaign's own ruleset"),
2635
+ ruleset_config: str = typer.Option(
2636
+ None, "--ruleset-config", help="for a world: a campaign's own settings as JSON"
2637
+ ),
2638
+ ) -> None:
2639
+ """Propose a build from a description through the model, checked like a preview (D-112). Saves
2640
+ nothing: pass the printed spec to `campaign new|join --spec`."""
2641
+
2642
+ async def _run() -> None:
2643
+ from uro_core.characters import propose_character
2644
+ from uro_core.errors import ProviderError
2645
+
2646
+ store = build_store()
2647
+ await connect_store(store)
2648
+ try:
2649
+ campaign = await store.get_campaign(target)
2650
+ if campaign is not None:
2651
+ branch_id = campaign.branch_id
2652
+ else:
2653
+ w = await _world_or_exit(store, target)
2654
+ b = await store.get_branch_by_name(w.world_id, branch)
2655
+ if b is None:
2656
+ typer.echo(f"no such branch: {branch}", err=True)
2657
+ raise typer.Exit(1)
2658
+ branch_id = b.branch_id
2659
+ router = build_router(provider, model)
2660
+ router.recorder = store.record_llm_call
2661
+ try:
2662
+ proposal = await propose_character(
2663
+ store,
2664
+ router,
2665
+ branch_id=branch_id,
2666
+ description=description,
2667
+ campaign=campaign,
2668
+ ruleset_id=ruleset_id,
2669
+ ruleset_config=_json_option(ruleset_config, "--ruleset-config"),
2670
+ )
2671
+ except (ProviderError, ValueError, KeyError) as exc:
2672
+ _echo_refused(exc)
2673
+ raise typer.Exit(1) from exc
2674
+ finally:
2675
+ await store.close()
2676
+ typer.echo(
2677
+ f"{'ok' if proposal.ok else 'not buildable'} ({proposal.ruleset})"
2678
+ + (f": {proposal.name}" if proposal.name else "")
2679
+ )
2680
+ typer.echo(json.dumps(proposal.spec, indent=2, sort_keys=True))
2681
+ if not proposal.ok:
2682
+ _echo_refused(CharSpecError(proposal.problems))
2683
+ raise typer.Exit(1)
2684
+
2685
+ _run_async(_run)
2686
+
2687
+
2688
+ @character_app.command("choose")
2689
+ def character_choose(
2690
+ campaign_id: str,
2691
+ choice_id: str,
2692
+ answer: str = typer.Argument(..., help='the answer as JSON, e.g. \'{"ability": "CON"}\''),
2693
+ participant: str = typer.Option(PARTICIPANT, "--participant", help="whose character"),
2694
+ ) -> None:
2695
+ """Answer a choice the ruleset left on a character (D-113): `uro character show` lists them."""
2696
+
2697
+ async def _run() -> None:
2698
+ from uro_core.characters import ChoiceError, answer_character_choice
2699
+
2700
+ store = build_store()
2701
+ await connect_store(store)
2702
+ try:
2703
+ c = await _campaign_or_exit(store, campaign_id)
2704
+ try:
2705
+ view = await answer_character_choice(
2706
+ store, c, participant, choice_id, _json_option(answer, "answer") or {}
2707
+ )
2708
+ except (CharSpecError, ChoiceError, KeyError) as exc:
2709
+ _echo_refused(exc)
2710
+ raise typer.Exit(1) from exc
2711
+ finally:
2712
+ await store.close()
2713
+ left = ", ".join(ch.id for ch in view.choices) or "none"
2714
+ typer.echo(f"answered; choices left: {left}")
2715
+
2716
+ _run_async(_run)
2717
+
2718
+
2719
+ @character_app.command("rebuild")
2720
+ def character_rebuild(
2721
+ campaign_id: str,
2722
+ participant: str = typer.Option(PARTICIPANT, "--participant", help="whose character"),
2723
+ spec: str = typer.Option(None, "--spec", help="the new build as JSON, or @file.json"),
2724
+ name: str = typer.Option(None, "--name", help="a new name"),
2725
+ holdings: str = typer.Option(
2726
+ None, "--holdings", help="replace the chosen holdings: JSON [{name, data?}] or @file"
2727
+ ),
2728
+ ) -> None:
2729
+ """Replace a character's build, name and/or chosen holdings before the story starts (until the
2730
+ first beat after it was bound); after that only play changes a character."""
2731
+
2732
+ async def _run() -> None:
2733
+ from uro_core.characters import CharacterFrozen, rebuild_character
2734
+
2735
+ store = build_store()
2736
+ await connect_store(store)
2737
+ try:
2738
+ c = await _campaign_or_exit(store, campaign_id)
2739
+ try:
2740
+ view = await rebuild_character(
2741
+ store,
2742
+ c,
2743
+ participant,
2744
+ spec=_json_option(spec, "--spec"),
2745
+ name=name,
2746
+ holdings=_json_list_option(holdings, "--holdings"),
2747
+ )
2748
+ except (CharSpecError, CharacterFrozen, KeyError) as exc:
2749
+ _echo_refused(exc)
2750
+ raise typer.Exit(1) from exc
2751
+ finally:
2752
+ await store.close()
2753
+ typer.echo(f"rebuilt: {view.name} [{view.actor_id}]")
2754
+
2755
+ _run_async(_run)
2756
+
2757
+
2217
2758
  @app.command("dry-run")
2218
2759
  def dry_run(
2219
2760
  campaign_id: str,
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes