kaabalah 6.8.0 → 6.8.1

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/dist/cli.js CHANGED
@@ -21288,7 +21288,7 @@ var import_config3 = require("dotenv/config");
21288
21288
  // package.json
21289
21289
  var package_default = {
21290
21290
  name: "kaabalah",
21291
- version: "6.8.0",
21291
+ version: "6.8.1",
21292
21292
  description: "The de-facto library for any esoteric calculations and tooling",
21293
21293
  engines: {
21294
21294
  node: ">=18.18.0"
@@ -21511,11 +21511,19 @@ var COMMANDS = [
21511
21511
  },
21512
21512
  {
21513
21513
  name: "tarot:spread",
21514
- description: "Look up multiple tarot cards by name or number",
21515
- args: [{ name: "cards", type: "string", required: true, description: "Card names or numbers, space-separated (quote multi-word names)" }],
21516
- flags: [],
21514
+ description: "Look up multiple tarot cards by name or number, or draw a named spread with --spread-id",
21515
+ args: [{ name: "cards", type: "string", required: false, description: "Card names or numbers, space-separated (quote multi-word names)" }],
21516
+ flags: [
21517
+ { name: "list", type: "boolean", default: false, description: "List built-in spread IDs and requirements" },
21518
+ { name: "spread-id", type: "string", description: "Draw a built-in spread by ID (e.g. quick-insight, celtic-cross, event-reading)" },
21519
+ { name: "inverted", type: "boolean", default: false, description: "Include inverted cards when drawing a named spread" },
21520
+ { name: "inquirer-gender", type: "string", description: 'Required by event-reading; must be "man" or "woman"' }
21521
+ ],
21517
21522
  examples: [
21518
21523
  'kaabalah tarot:spread "Two of Cups" "The Chariot" 7',
21524
+ "kaabalah tarot:spread --list",
21525
+ "kaabalah tarot:spread --spread-id=celtic-cross --json",
21526
+ "kaabalah tarot:spread --spread-id=event-reading --inquirer-gender=woman --json",
21519
21527
  "kaabalah tarot:spread --input-json=- --json --compact < cards.json"
21520
21528
  ]
21521
21529
  },
@@ -27056,6 +27064,18 @@ var ARKANNUS = buildDefaultArkannus(RAW_ARKANNUS);
27056
27064
  var MAJOR_ARCANA_CARDS = ARKANNUS.filter(
27057
27065
  (card) => card.type === "major" && majorArcana.includes(card.tarotCardFilename)
27058
27066
  );
27067
+ var TAROT_SPREAD_MINOR_RANKS = [
27068
+ "ace",
27069
+ "2",
27070
+ "3",
27071
+ "4",
27072
+ "5",
27073
+ "6",
27074
+ "7",
27075
+ "8",
27076
+ "9",
27077
+ "10"
27078
+ ];
27059
27079
  var EVENT_INNER_SLOT_KEYS = [
27060
27080
  "inner-1",
27061
27081
  "inner-2",
@@ -27705,8 +27725,432 @@ var TAROT_SPREADS = [
27705
27725
  var TAROT_SPREAD_BY_ID = new Map(
27706
27726
  TAROT_SPREADS.map((spread) => [spread.spreadId, spread])
27707
27727
  );
27728
+ function cloneCardConstraint(constraint) {
27729
+ if (!constraint) {
27730
+ return void 0;
27731
+ }
27732
+ return {
27733
+ allowedTypes: constraint.allowedTypes ? [...constraint.allowedTypes] : void 0,
27734
+ requiredRank: constraint.requiredRank,
27735
+ allowedCardFilenames: constraint.allowedCardFilenames ? [...constraint.allowedCardFilenames] : void 0,
27736
+ excludedCardFilenames: constraint.excludedCardFilenames ? [...constraint.excludedCardFilenames] : void 0
27737
+ };
27738
+ }
27739
+ function cloneSlotDefinition(slot) {
27740
+ return {
27741
+ ...slot,
27742
+ validationRules: cloneCardConstraint(slot.validationRules),
27743
+ manualSelectionRules: cloneCardConstraint(slot.manualSelectionRules),
27744
+ drawRules: cloneCardConstraint(slot.drawRules),
27745
+ metadata: slot.metadata ? { ...slot.metadata } : void 0
27746
+ };
27747
+ }
27748
+ function cloneSpreadDefinition(spread) {
27749
+ return {
27750
+ ...spread,
27751
+ contextRequirements: spread.contextRequirements ? [...spread.contextRequirements] : void 0,
27752
+ slots: spread.slots.map(cloneSlotDefinition),
27753
+ specialRules: spread.specialRules?.inquirerCard ? {
27754
+ inquirerCard: {
27755
+ slotKey: spread.specialRules.inquirerCard.slotKey,
27756
+ sourceSlotKeys: [...spread.specialRules.inquirerCard.sourceSlotKeys],
27757
+ cardNumbersByGender: {
27758
+ ...spread.specialRules.inquirerCard.cardNumbersByGender
27759
+ }
27760
+ }
27761
+ } : void 0
27762
+ };
27763
+ }
27764
+ function getTarotDeckCardByNumber(cardNumber) {
27765
+ return TAROT_CARD_BY_NUMBER.get(cardNumber);
27766
+ }
27767
+ function getTarotSpreadRuleForValidation(slot) {
27768
+ return slot.validationRules ?? slot.drawRules ?? slot.manualSelectionRules;
27769
+ }
27770
+ function getTarotSpreadRuleForDraw(slot) {
27771
+ return slot.drawRules ?? slot.validationRules ?? slot.manualSelectionRules;
27772
+ }
27773
+ function getTarotMinorRank(card) {
27774
+ if (card.type !== "minor") {
27775
+ return void 0;
27776
+ }
27777
+ const rank = card.tarotCardFilename.split("_")[0];
27778
+ return TAROT_SPREAD_MINOR_RANKS.includes(rank) ? rank : void 0;
27779
+ }
27780
+ function matchesTarotSpreadConstraint(card, constraint) {
27781
+ if (!constraint) {
27782
+ return true;
27783
+ }
27784
+ if (constraint.allowedTypes && !constraint.allowedTypes.includes(card.type)) {
27785
+ return false;
27786
+ }
27787
+ if (constraint.allowedCardFilenames && !constraint.allowedCardFilenames.includes(card.tarotCardFilename)) {
27788
+ return false;
27789
+ }
27790
+ if (constraint.excludedCardFilenames && constraint.excludedCardFilenames.includes(card.tarotCardFilename)) {
27791
+ return false;
27792
+ }
27793
+ if (constraint.requiredRank) {
27794
+ return getTarotMinorRank(card) === constraint.requiredRank;
27795
+ }
27796
+ return true;
27797
+ }
27798
+ function randomIndex(length, rng) {
27799
+ if (length <= 0) {
27800
+ throw new Error("Cannot draw from an empty pool.");
27801
+ }
27802
+ const raw = rng();
27803
+ if (!Number.isFinite(raw)) {
27804
+ throw new Error("Tarot spread RNG must return a finite number.");
27805
+ }
27806
+ const normalized = Math.min(Math.max(raw, 0), 1 - Number.EPSILON);
27807
+ return Math.floor(normalized * length);
27808
+ }
27809
+ function withSpreadCardOrientation(card, includeInverted, rng) {
27810
+ return {
27811
+ ...card,
27812
+ isInverted: includeInverted ? rng() < 0.5 : false
27813
+ };
27814
+ }
27815
+ function resolveTarotSpreadSelectionCard(card, slot, tarotCard) {
27816
+ return {
27817
+ ...card,
27818
+ slot,
27819
+ card: {
27820
+ ...tarotCard,
27821
+ isInverted: card.isInverted ?? false
27822
+ }
27823
+ };
27824
+ }
27825
+ function sortResolvedTarotSpreadCards(resolvedCards) {
27826
+ return [...resolvedCards].sort((left, right) => {
27827
+ if (left.slot.order !== right.slot.order) {
27828
+ return left.slot.order - right.slot.order;
27829
+ }
27830
+ return left.card.number - right.card.number;
27831
+ });
27832
+ }
27833
+ function validateEventInquirerCard(spread, resolvedCards, context, errors) {
27834
+ const inquirerRule = spread.specialRules?.inquirerCard;
27835
+ if (!inquirerRule) {
27836
+ return;
27837
+ }
27838
+ if (!context?.inquirerGender) {
27839
+ return;
27840
+ }
27841
+ const inquirerCardNumber = inquirerRule.cardNumbersByGender[context.inquirerGender];
27842
+ const sourceCards = resolvedCards.filter(
27843
+ (card) => inquirerRule.sourceSlotKeys.includes(card.slotKey)
27844
+ );
27845
+ const inquirerCards = resolvedCards.filter(
27846
+ (card) => card.slotKey === inquirerRule.slotKey
27847
+ );
27848
+ if (inquirerCards.length !== 1) {
27849
+ return;
27850
+ }
27851
+ const sourceContainsGenderCard = sourceCards.some(
27852
+ (card) => card.card.number === inquirerCardNumber
27853
+ );
27854
+ const totalGenderCardCount = [...sourceCards, ...inquirerCards].filter(
27855
+ (card) => card.card.number === inquirerCardNumber
27856
+ ).length;
27857
+ if (totalGenderCardCount !== 1) {
27858
+ errors.push({
27859
+ code: "INVALID_INQUIRER_CARD",
27860
+ slotKey: inquirerRule.slotKey,
27861
+ cardNumber: inquirerCardNumber,
27862
+ message: "Event Reading must contain the gendered inquirer card exactly once across the major arcana band and inquirer slot."
27863
+ });
27864
+ return;
27865
+ }
27866
+ if (!sourceContainsGenderCard && inquirerCards[0].card.number !== inquirerCardNumber) {
27867
+ errors.push({
27868
+ code: "INVALID_INQUIRER_CARD",
27869
+ slotKey: inquirerRule.slotKey,
27870
+ cardNumber: inquirerCards[0].card.number,
27871
+ message: "When the inquirer card was not drawn in the seven major slots, it must occupy the Inquirer slot."
27872
+ });
27873
+ }
27874
+ }
27875
+ function pickTarotCardFromPool(pool, constraint, rng) {
27876
+ const candidateIndexes = pool.reduce((indexes, card, index) => {
27877
+ if (matchesTarotSpreadConstraint(card, constraint)) {
27878
+ indexes.push(index);
27879
+ }
27880
+ return indexes;
27881
+ }, []);
27882
+ if (candidateIndexes.length === 0) {
27883
+ throw new Error("Unable to draw a tarot card that satisfies the spread rule.");
27884
+ }
27885
+ const pickedIndex = candidateIndexes[randomIndex(candidateIndexes.length, rng)];
27886
+ const [pickedCard] = pool.splice(pickedIndex, 1);
27887
+ return pickedCard;
27888
+ }
27889
+ function buildResolvedDrawnCard(slot, card, includeInverted, rng) {
27890
+ const drawnCard = withSpreadCardOrientation(card, includeInverted, rng);
27891
+ return {
27892
+ slotKey: slot.slotKey,
27893
+ cardNumber: drawnCard.number,
27894
+ isInverted: drawnCard.isInverted ?? false,
27895
+ slot,
27896
+ card: drawnCard
27897
+ };
27898
+ }
27899
+ function drawDefaultTarotSpread(spread, includeInverted, rng) {
27900
+ const deckPool = [...ARKANNUS];
27901
+ const drawnCards = [];
27902
+ for (const slot of spread.slots.slice().sort((left, right) => left.order - right.order)) {
27903
+ const drawRule = getTarotSpreadRuleForDraw(slot);
27904
+ for (let index = 0; index < slot.maxCards; index += 1) {
27905
+ const card = pickTarotCardFromPool(deckPool, drawRule, rng);
27906
+ drawnCards.push(
27907
+ buildResolvedDrawnCard(slot, card, includeInverted, rng)
27908
+ );
27909
+ }
27910
+ }
27911
+ return drawnCards;
27912
+ }
27913
+ function drawEventReadingSpread(spread, includeInverted, rng, context) {
27914
+ const inquirerRule = spread.specialRules?.inquirerCard;
27915
+ if (!inquirerRule || !context?.inquirerGender) {
27916
+ throw new Error(
27917
+ "Event Reading draw requires `context.inquirerGender`."
27918
+ );
27919
+ }
27920
+ const slotsByKey = new Map(
27921
+ spread.slots.map((slot) => [slot.slotKey, slot])
27922
+ );
27923
+ const outerPool = ARKANNUS.filter(
27924
+ (card) => card.type === "minor" || card.type === "daat+royalship"
27925
+ );
27926
+ const majorPool = ARKANNUS.filter((card) => card.type === "major");
27927
+ const drawnCards = [];
27928
+ for (const slot of spread.slots.filter((candidate) => candidate.metadata?.groupKey === "outer").sort((left, right) => left.order - right.order)) {
27929
+ const card = pickTarotCardFromPool(outerPool, getTarotSpreadRuleForDraw(slot), rng);
27930
+ drawnCards.push(buildResolvedDrawnCard(slot, card, includeInverted, rng));
27931
+ }
27932
+ for (const slotKey of inquirerRule.sourceSlotKeys) {
27933
+ const slot = slotsByKey.get(slotKey);
27934
+ if (!slot) {
27935
+ throw new Error(`Missing Event Reading slot definition for ${slotKey}.`);
27936
+ }
27937
+ const card = pickTarotCardFromPool(majorPool, getTarotSpreadRuleForDraw(slot), rng);
27938
+ drawnCards.push(buildResolvedDrawnCard(slot, card, includeInverted, rng));
27939
+ }
27940
+ const genderedInquirerCardNumber = inquirerRule.cardNumbersByGender[context.inquirerGender];
27941
+ const sourceContainsGenderedCard = drawnCards.some(
27942
+ (card) => inquirerRule.sourceSlotKeys.includes(card.slotKey) && card.card.number === genderedInquirerCardNumber
27943
+ );
27944
+ const inquirerSlot = slotsByKey.get(inquirerRule.slotKey);
27945
+ if (!inquirerSlot) {
27946
+ throw new Error(
27947
+ `Missing Event Reading slot definition for ${inquirerRule.slotKey}.`
27948
+ );
27949
+ }
27950
+ if (!sourceContainsGenderedCard) {
27951
+ const genderedCardIndex = majorPool.findIndex(
27952
+ (card) => card.number === genderedInquirerCardNumber
27953
+ );
27954
+ if (genderedCardIndex < 0) {
27955
+ throw new Error(
27956
+ "Unable to assign the Event Reading inquirer card from the remaining major arcana."
27957
+ );
27958
+ }
27959
+ const [genderedCard] = majorPool.splice(genderedCardIndex, 1);
27960
+ drawnCards.push(
27961
+ buildResolvedDrawnCard(inquirerSlot, genderedCard, includeInverted, rng)
27962
+ );
27963
+ } else {
27964
+ const replacement = pickTarotCardFromPool(
27965
+ majorPool,
27966
+ getTarotSpreadRuleForDraw(inquirerSlot),
27967
+ rng
27968
+ );
27969
+ drawnCards.push(
27970
+ buildResolvedDrawnCard(inquirerSlot, replacement, includeInverted, rng)
27971
+ );
27972
+ }
27973
+ return drawnCards;
27974
+ }
27975
+ function listTarotSpreads() {
27976
+ return TAROT_SPREADS.map(cloneSpreadDefinition);
27977
+ }
27978
+ function getTarotSpread(spreadId) {
27979
+ const spread = TAROT_SPREAD_BY_ID.get(spreadId);
27980
+ return spread ? cloneSpreadDefinition(spread) : void 0;
27981
+ }
27982
+ function validateTarotSpreadSelection(input) {
27983
+ const spread = TAROT_SPREAD_BY_ID.get(input.spreadId);
27984
+ const errors = [];
27985
+ if (!spread) {
27986
+ return {
27987
+ ok: false,
27988
+ isComplete: false,
27989
+ errors: [
27990
+ {
27991
+ code: "UNKNOWN_SPREAD",
27992
+ message: `Unknown tarot spread: ${input.spreadId}.`
27993
+ }
27994
+ ],
27995
+ resolvedCards: []
27996
+ };
27997
+ }
27998
+ const slotsByKey = new Map(
27999
+ spread.slots.map((slot) => [slot.slotKey, slot])
28000
+ );
28001
+ const seenCardNumbers = /* @__PURE__ */ new Set();
28002
+ const resolvedCards = [];
28003
+ for (const selectedCard of input.cards) {
28004
+ const slot = slotsByKey.get(selectedCard.slotKey);
28005
+ if (!slot) {
28006
+ errors.push({
28007
+ code: "UNKNOWN_SLOT",
28008
+ slotKey: selectedCard.slotKey,
28009
+ message: `Unknown slot for ${spread.label}: ${selectedCard.slotKey}.`
28010
+ });
28011
+ continue;
28012
+ }
28013
+ const tarotCard = getTarotDeckCardByNumber(selectedCard.cardNumber);
28014
+ if (!tarotCard) {
28015
+ errors.push({
28016
+ code: "CARD_NOT_FOUND",
28017
+ slotKey: selectedCard.slotKey,
28018
+ cardNumber: selectedCard.cardNumber,
28019
+ message: `Unknown tarot card number: ${selectedCard.cardNumber}.`
28020
+ });
28021
+ continue;
28022
+ }
28023
+ if (seenCardNumbers.has(tarotCard.number)) {
28024
+ errors.push({
28025
+ code: "DUPLICATE_CARD",
28026
+ slotKey: selectedCard.slotKey,
28027
+ cardNumber: tarotCard.number,
28028
+ message: `Tarot card ${tarotCard.number} is duplicated across the spread.`
28029
+ });
28030
+ continue;
28031
+ }
28032
+ seenCardNumbers.add(tarotCard.number);
28033
+ resolvedCards.push(
28034
+ resolveTarotSpreadSelectionCard(selectedCard, slot, tarotCard)
28035
+ );
28036
+ }
28037
+ let isComplete = true;
28038
+ for (const slot of spread.slots) {
28039
+ const slotCards = resolvedCards.filter(
28040
+ (selectedCard) => selectedCard.slotKey === slot.slotKey
28041
+ );
28042
+ if (slotCards.length < slot.minCards) {
28043
+ isComplete = false;
28044
+ if (!input.allowPartial) {
28045
+ errors.push({
28046
+ code: "MISSING_REQUIRED_CARDS",
28047
+ slotKey: slot.slotKey,
28048
+ message: `${spread.label} requires ${slot.minCards} card(s) for ${slot.label}.`
28049
+ });
28050
+ }
28051
+ }
28052
+ if (slotCards.length > slot.maxCards) {
28053
+ isComplete = false;
28054
+ errors.push({
28055
+ code: "TOO_MANY_CARDS",
28056
+ slotKey: slot.slotKey,
28057
+ message: `${spread.label} allows at most ${slot.maxCards} card(s) for ${slot.label}.`
28058
+ });
28059
+ }
28060
+ const validationRule = getTarotSpreadRuleForValidation(slot);
28061
+ for (const slotCard of slotCards) {
28062
+ if (validationRule?.allowedTypes && !validationRule.allowedTypes.includes(slotCard.card.type)) {
28063
+ errors.push({
28064
+ code: "INVALID_CARD_TYPE",
28065
+ slotKey: slot.slotKey,
28066
+ cardNumber: slotCard.card.number,
28067
+ message: `${slot.label} does not accept ${slotCard.card.type} cards.`
28068
+ });
28069
+ }
28070
+ if (validationRule?.requiredRank && getTarotMinorRank(slotCard.card) !== validationRule.requiredRank) {
28071
+ errors.push({
28072
+ code: "INVALID_CARD_RANK",
28073
+ slotKey: slot.slotKey,
28074
+ cardNumber: slotCard.card.number,
28075
+ message: `${slot.label} requires a ${validationRule.requiredRank} minor arcana card.`
28076
+ });
28077
+ }
28078
+ if (validationRule?.allowedCardFilenames && !validationRule.allowedCardFilenames.includes(slotCard.card.tarotCardFilename)) {
28079
+ errors.push({
28080
+ code: "DISALLOWED_CARD",
28081
+ slotKey: slot.slotKey,
28082
+ cardNumber: slotCard.card.number,
28083
+ message: `${slotCard.card.tarotCard} is not allowed in ${slot.label}.`
28084
+ });
28085
+ }
28086
+ if (validationRule?.excludedCardFilenames && validationRule.excludedCardFilenames.includes(slotCard.card.tarotCardFilename)) {
28087
+ errors.push({
28088
+ code: "DISALLOWED_CARD",
28089
+ slotKey: slot.slotKey,
28090
+ cardNumber: slotCard.card.number,
28091
+ message: `${slotCard.card.tarotCard} is excluded from ${slot.label}.`
28092
+ });
28093
+ }
28094
+ }
28095
+ }
28096
+ if (spread.contextRequirements?.includes("inquirerGender") && !input.context?.inquirerGender) {
28097
+ isComplete = false;
28098
+ errors.push({
28099
+ code: "MISSING_CONTEXT",
28100
+ message: `${spread.label} requires \`context.inquirerGender\`.`
28101
+ });
28102
+ }
28103
+ validateEventInquirerCard(spread, resolvedCards, input.context, errors);
28104
+ const sortedResolvedCards = sortResolvedTarotSpreadCards(resolvedCards);
28105
+ return {
28106
+ ok: errors.length === 0,
28107
+ isComplete,
28108
+ spread: cloneSpreadDefinition(spread),
28109
+ resolvedCards: sortedResolvedCards,
28110
+ errors
28111
+ };
28112
+ }
28113
+ function drawTarotSpread(options) {
28114
+ const spread = TAROT_SPREAD_BY_ID.get(options.spreadId);
28115
+ if (!spread) {
28116
+ throw new Error(`Unknown tarot spread: ${options.spreadId}.`);
28117
+ }
28118
+ const rng = options.rng ?? Math.random;
28119
+ const includeInverted = options.includeInverted ?? false;
28120
+ const drawnCards = spread.spreadId === "event-reading" ? drawEventReadingSpread(spread, includeInverted, rng, options.context) : drawDefaultTarotSpread(spread, includeInverted, rng);
28121
+ const validation = validateTarotSpreadSelection({
28122
+ spreadId: spread.spreadId,
28123
+ cards: drawnCards.map((card) => ({
28124
+ slotKey: card.slotKey,
28125
+ cardNumber: card.cardNumber,
28126
+ isInverted: card.isInverted
28127
+ })),
28128
+ context: options.context
28129
+ });
28130
+ if (!validation.ok) {
28131
+ throw new Error(
28132
+ `Generated an invalid tarot spread selection for ${spread.label}: ${validation.errors.map((error) => error.message).join(" ")}`
28133
+ );
28134
+ }
28135
+ return {
28136
+ spread: cloneSpreadDefinition(spread),
28137
+ deckId: options.deckId ?? "rider-waite",
28138
+ context: options.context,
28139
+ cards: sortResolvedTarotSpreadCards(drawnCards)
28140
+ };
28141
+ }
27708
28142
 
27709
28143
  // src/cli/commands/tarot.ts
28144
+ var TAROT_INQUIRER_GENDERS = /* @__PURE__ */ new Set(["man", "woman"]);
28145
+ function summarizeTarotSpreads() {
28146
+ return listTarotSpreads().map((spread) => ({
28147
+ spreadId: spread.spreadId,
28148
+ label: spread.label,
28149
+ description: spread.description,
28150
+ slots: spread.slots.length,
28151
+ contextRequirements: spread.contextRequirements ?? []
28152
+ }));
28153
+ }
27710
28154
  function findCardsByQuery(query) {
27711
28155
  const num = Number.parseInt(query, 10);
27712
28156
  if (!Number.isNaN(num)) {
@@ -27777,7 +28221,79 @@ function cmdTarotCard(query, flags) {
27777
28221
  printCard(card);
27778
28222
  }
27779
28223
  }
27780
- function cmdTarotSpread(cardQueries, flags) {
28224
+ function parseTarotSpreadContext(flags, context) {
28225
+ const flagGender = getFlagString(flags, "inquirer-gender");
28226
+ const inputGender = context && typeof context === "object" && "inquirerGender" in context ? context.inquirerGender : void 0;
28227
+ const gender = flagGender ?? (typeof inputGender === "string" ? inputGender : void 0);
28228
+ if (!gender) {
28229
+ return void 0;
28230
+ }
28231
+ if (!TAROT_INQUIRER_GENDERS.has(gender)) {
28232
+ exitWithError("INVALID_ARGUMENT", 'Tarot spread context.inquirerGender must be "man" or "woman".', flags);
28233
+ }
28234
+ return { inquirerGender: gender };
28235
+ }
28236
+ function printSpreadDraw(result) {
28237
+ console.log(`
28238
+ ${result.spread.label}`);
28239
+ console.log(`Spread: ${result.spread.spreadId}`);
28240
+ if (result.context?.inquirerGender) {
28241
+ console.log(`Inquirer: ${result.context.inquirerGender}`);
28242
+ }
28243
+ console.log();
28244
+ for (const card of result.cards) {
28245
+ const inverted = card.isInverted ? " (INVERTED)" : "";
28246
+ console.log(
28247
+ ` ${card.slot.order}. ${card.slot.label}: #${String(card.card.number).padStart(2, "0")} ${card.card.tarotCard}${inverted}`
28248
+ );
28249
+ console.log(` ${card.card.meaning}`);
28250
+ }
28251
+ console.log();
28252
+ }
28253
+ function cmdTarotNamedSpread(spreadId, flags, options) {
28254
+ const spread = getTarotSpread(spreadId);
28255
+ if (!spread) {
28256
+ exitWithError("INVALID_ARGUMENT", `Unknown tarot spread: ${spreadId}.`, flags);
28257
+ }
28258
+ const context = parseTarotSpreadContext(flags, options.context);
28259
+ try {
28260
+ const result = drawTarotSpread({
28261
+ spreadId: spread.spreadId,
28262
+ includeInverted: getFlagBool(flags, "inverted"),
28263
+ context
28264
+ });
28265
+ if (isJsonMode(flags)) {
28266
+ outputJson(result, flags);
28267
+ return;
28268
+ }
28269
+ printSpreadDraw(result);
28270
+ } catch (err) {
28271
+ exitWithError("INVALID_ARGUMENT", err instanceof Error ? err.message : String(err), flags);
28272
+ }
28273
+ }
28274
+ function cmdTarotSpread(cardQueries, flags, options = {}) {
28275
+ if (getFlagBool(flags, "list")) {
28276
+ const spreads = summarizeTarotSpreads();
28277
+ if (isJsonMode(flags)) {
28278
+ outputJson(spreads, flags);
28279
+ return;
28280
+ }
28281
+ console.log("\nTarot spreads\n");
28282
+ for (const spread of spreads) {
28283
+ const requirements = spread.contextRequirements.length > 0 ? ` | requires: ${spread.contextRequirements.join(", ")}` : "";
28284
+ console.log(` ${spread.spreadId.padEnd(22)} ${spread.label} (${spread.slots} slots)${requirements}`);
28285
+ if (spread.description) {
28286
+ console.log(` ${spread.description}`);
28287
+ }
28288
+ }
28289
+ console.log();
28290
+ return;
28291
+ }
28292
+ const spreadId = getFlagString(flags, "spread-id") ?? options.spreadId;
28293
+ if (spreadId) {
28294
+ cmdTarotNamedSpread(spreadId, flags, options);
28295
+ return;
28296
+ }
27781
28297
  const results = [];
27782
28298
  for (const query of cardQueries) {
27783
28299
  const { cards } = findCardsByQuery(query);
@@ -28771,11 +29287,17 @@ async function runCli(argv) {
28771
29287
  cmdTarotCard((inputPayload?.query != null ? String(inputPayload.query) : void 0) ?? args.slice(1).join(" "), flags);
28772
29288
  return;
28773
29289
  case "tarot:spread": {
29290
+ const spreadId = inputPayload?.spreadId != null ? String(inputPayload.spreadId) : void 0;
29291
+ const hasSpreadIdFlag = typeof flags["spread-id"] === "string" && flags["spread-id"].length > 0;
29292
+ const shouldListSpreads = flags.list === true;
28774
29293
  const cardQueries = Array.isArray(inputPayload?.cards) ? inputPayload.cards.map(String) : args.slice(1);
28775
- if (cardQueries.length === 0) {
29294
+ if (cardQueries.length === 0 && !hasSpreadIdFlag && !spreadId && !shouldListSpreads) {
28776
29295
  exitWithError("MISSING_ARGUMENT", "Usage: kaabalah tarot:spread <card1> [card2] ...", flags);
28777
29296
  }
28778
- cmdTarotSpread(cardQueries, flags);
29297
+ cmdTarotSpread(cardQueries, flags, {
29298
+ spreadId,
29299
+ context: inputPayload?.context
29300
+ });
28779
29301
  return;
28780
29302
  }
28781
29303
  case "ifa":