@vttforge/cli 0.0.0 → 0.5.1

package/templates/system-ts/scripts/main.ts

@@ -0,0 +1,82 @@
+/**
+ * {{TITLE}} — entry point.
+ *
+ * `registerSystem` from `@vttforge/core` replaces the ~60-line
+ * `Hooks.once("init", ...)` block most systems copy-paste from each other:
+ * data model registration, document class swap, initiative formula, sheet
+ * registration, settings, and the `Hooks.once("ready", ...)` migration
+ * gate are all wired by one call.
+ */
+import './foundry-globals.js';
+import { registerSystem, SystemConfig, VttfError } from '@vttforge/core';
+import { CharacterData } from './data/character-data.js';
+import { GearData } from './data/gear-data.js';
+import { migrations } from './migrations.js';
+import { CharacterSheet } from './sheets/character-sheet.js';
+import { GearSheet } from './sheets/gear-sheet.js';
+
+const SYSTEM_ID = '{{ID}}';
+
+const settings = new SystemConfig(SYSTEM_ID);
+
+try {
+  registerSystem({
+    id: SYSTEM_ID,
+    actorDataModels: { character: CharacterData },
+    itemDataModels: { gear: GearData },
+    combat: {
+      initiative: { formula: '1d20 + @abilities.dex.mod', decimals: 2 },
+    },
+    onAfterInit: () => {
+      settings.register('showTutorial', {
+        name: '{{LOCALE_PREFIX}}.Settings.showTutorial.name',
+        hint: '{{LOCALE_PREFIX}}.Settings.showTutorial.hint',
+        scope: 'client',
+        config: true,
+        type: Boolean,
+        default: true,
+      });
+
+      // Register the schemaVersion setting so migrations.run() has somewhere
+      // to read and write the version flag.
+      migrations.register();
+
+      const { Actors, Items } = foundry.documents.collections;
+      Actors.unregisterSheet('core', foundry.applications.sheets.ActorSheetV2);
+      Actors.registerSheet(SYSTEM_ID, CharacterSheet, {
+        types: ['character'],
+        makeDefault: true,
+        label: '{{LOCALE_PREFIX}}.Sheet.Character.title',
+      });
+      Items.unregisterSheet('core', foundry.applications.sheets.ItemSheetV2);
+      Items.registerSheet(SYSTEM_ID, GearSheet, {
+        types: ['gear'],
+        makeDefault: true,
+        label: '{{LOCALE_PREFIX}}.Sheet.Gear.title',
+      });
+    },
+    onReady: async () => {
+      if (!game.user?.isGM) return;
+      try {
+        const ran = await migrations.run();
+        if (ran.length > 0) {
+          // biome-ignore lint/suspicious/noConsole: console.info is the only Foundry-portable info logger
+          console.info(`[${SYSTEM_ID}] applied migrations:`, ran.join(', '));
+        }
+      } catch (err) {
+        if (err instanceof VttfError) {
+          ui.notifications?.error(`[${err.code}] ${err.message} — see ${err.docsUrl}`, {
+            permanent: true,
+          });
+        }
+        throw err;
+      }
+    },
+  });
+} catch (err) {
+  if (err instanceof VttfError) {
+    // biome-ignore lint/suspicious/noConsole: bootstrap-time failures must surface
+    console.error(`[${err.code}] ${err.message} — see ${err.docsUrl}`);
+  }
+  throw err;
+}

package/templates/system-ts/scripts/migrations.ts

@@ -0,0 +1,43 @@
+/**
+ * Migration registry for {{TITLE}}.
+ *
+ * Each entry is idempotent — safe to re-run if a prior pass failed
+ * mid-sequence. `createMigrationRunner` reads the version flag declared in
+ * `system.json` (`flags.{{ID}}.needsMigrationVersion`), runs every
+ * migration whose version is newer than what's stored in the world's
+ * `schemaVersion` setting, and persists the new high-water mark on success.
+ */
+import { createMigrationRunner } from '@vttforge/core';
+
+const SYSTEM_ID = '{{ID}}';
+
+/**
+ * v0.1.0 — first real schema. Add real migration logic here as soon as the
+ * first breaking schema change ships. Until then, this is a no-op example
+ * that proves the runner end-to-end.
+ */
+async function migrateToV0_1_0(): Promise<void> {
+  // Iterate world documents and rewrite legacy fields here. Example:
+  //
+  //   const actors = game.actors?.filter((a) => a.type === 'character') ?? [];
+  //   for (const actor of actors) {
+  //     const legacy = actor.system?.bio;
+  //     if (typeof legacy !== 'string') continue;
+  //     await actor.update({
+  //       'system.biography': legacy,
+  //       '-=system.bio': null,
+  //     });
+  //   }
+}
+
+export const migrations = createMigrationRunner({
+  systemId: SYSTEM_ID,
+  compatibleVersion: '0.0.0',
+  migrations: [
+    {
+      version: '0.1.0',
+      description: 'initial schema — placeholder for first breaking change',
+      fn: migrateToV0_1_0,
+    },
+  ],
+});

package/templates/system-ts/scripts/sheets/character-sheet.ts

@@ -0,0 +1,202 @@
+/**
+ * CharacterSheet — tabbed character sheet built on `BaseActorSheet()` from
+ * `@vttforge/core`. Demonstrates the full boilerplate-elimination surface:
+ *
+ * - `static TABS` — `context.tabs.<group>` auto-populated by BaseActorSheet
+ *   (no manual `_prepareTabs` call).
+ * - `static DRAG_DROP` — wires `foundry.applications.ux.DragDrop` on first
+ *   render with `isEditable`-gated permissions.
+ * - Typed `onDropItem(item, event)` — pre-resolves UUIDs, rejects
+ *   non-`gear` items with a notification, lets `gear` flow through to
+ *   Foundry's default `_onDropItem` by returning `undefined`.
+ */
+import { BaseActorSheet } from '@vttforge/core';
+
+const SYSTEM_ID = '{{ID}}';
+
+interface AbilityViewModel {
+  key: string;
+  label: string;
+  value: number;
+  mod: number;
+}
+
+interface GearViewModel {
+  id: string;
+  name: string;
+  img: string;
+  kind: string;
+  quantity: number;
+  weight: number;
+  description: string;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: typed sheet bases ship in a later @vttforge/types release
+const Base = BaseActorSheet() as any;
+
+export class CharacterSheet extends Base {
+  static DEFAULT_OPTIONS = foundry.utils.mergeObject(
+    Base.DEFAULT_OPTIONS,
+    {
+      id: '{{ID}}-character',
+      classes: ['{{ID}}', 'sheet', 'actor', 'character'],
+      window: {
+        title: '{{LOCALE_PREFIX}}.Sheet.Character.title',
+        icon: 'fa-solid fa-user',
+      },
+      position: { width: 640, height: 700 },
+      actions: {
+        rollAbility: CharacterSheet._onRollAbility,
+        createGear: CharacterSheet._onCreateGear,
+        deleteItem: CharacterSheet._onDeleteItem,
+      },
+    },
+    { inplace: false },
+  );
+
+  static PARTS = {
+    sheet: {
+      template: `systems/${SYSTEM_ID}/templates/actor/character-sheet.hbs`,
+    },
+  };
+
+  static TABS = {
+    primary: {
+      tabs: [
+        {
+          id: 'abilities',
+          group: 'primary',
+          label: '{{LOCALE_PREFIX}}.Sheet.Tabs.abilities',
+          icon: 'fa-solid fa-dumbbell',
+        },
+        {
+          id: 'inventory',
+          group: 'primary',
+          label: '{{LOCALE_PREFIX}}.Sheet.Tabs.inventory',
+          icon: 'fa-solid fa-sack',
+        },
+        {
+          id: 'spells',
+          group: 'primary',
+          label: '{{LOCALE_PREFIX}}.Sheet.Tabs.spells',
+          icon: 'fa-solid fa-wand-magic-sparkles',
+        },
+        {
+          id: 'biography',
+          group: 'primary',
+          label: '{{LOCALE_PREFIX}}.Sheet.Tabs.biography',
+          icon: 'fa-solid fa-feather',
+        },
+      ],
+      initial: 'abilities',
+    },
+  };
+
+  static DRAG_DROP = [
+    {
+      dragSelector: '.sh-item[draggable=true]',
+      dropSelector: '.sh-body',
+    },
+  ];
+
+  // biome-ignore lint/suspicious/noExplicitAny: see @vttforge/types follow-up
+  async _prepareContext(options: any) {
+    const context = await super._prepareContext(options);
+    const actor = (this as unknown as { document: any }).document;
+    const system = actor.system;
+    const abilityLabels: Record<string, string> = {
+      str: '{{LOCALE_PREFIX}}.Ability.str',
+      dex: '{{LOCALE_PREFIX}}.Ability.dex',
+      con: '{{LOCALE_PREFIX}}.Ability.con',
+      int: '{{LOCALE_PREFIX}}.Ability.int',
+      wis: '{{LOCALE_PREFIX}}.Ability.wis',
+      cha: '{{LOCALE_PREFIX}}.Ability.cha',
+    };
+    context.actor = actor;
+    context.system = system;
+    context.isEditable = (this as unknown as { isEditable: boolean }).isEditable;
+    context.abilities = Object.entries(system.abilities ?? {}).map(
+      ([key, data]): AbilityViewModel => {
+        const ability = data as { value?: number; mod?: number } | number;
+        const value = typeof ability === 'number' ? ability : (ability?.value ?? 10);
+        const mod = typeof ability === 'number' ? 0 : (ability?.mod ?? 0);
+        return {
+          key,
+          label: game.i18n.localize(abilityLabels[key] ?? key),
+          value,
+          mod,
+        };
+      },
+    );
+    context.gear = actor.items
+      .filter((item: { type: string }) => item.type === 'gear')
+      .map(
+        (item: {
+          id: string;
+          name: string;
+          img: string;
+          system?: { kind?: string; quantity?: number; weight?: number; description?: string };
+        }): GearViewModel => ({
+          id: item.id,
+          name: item.name,
+          img: item.img,
+          kind: item.system?.kind ?? 'stowed',
+          quantity: item.system?.quantity ?? 1,
+          weight: item.system?.weight ?? 0,
+          description: item.system?.description ?? '',
+        }),
+      );
+    context.enrichedBiography = await foundry.applications.ux.TextEditor.implementation.enrichHTML(
+      system.biography ?? '',
+      { relativeTo: actor, secrets: actor.isOwner },
+    );
+    return context;
+  }
+
+  /** Reject non-gear drops with a notification; let gear fall through. */
+  // biome-ignore lint/suspicious/noExplicitAny: see @vttforge/types follow-up
+  async onDropItem(item: any, _event: unknown): Promise<false | undefined> {
+    if (item?.type !== 'gear') {
+      ui.notifications?.warn(
+        game.i18n.format('{{LOCALE_PREFIX}}.Sheet.Drop.rejected', { type: item?.type ?? 'unknown' }),
+      );
+      return false;
+    }
+    return undefined;
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: see @vttforge/types follow-up
+  static async _onRollAbility(this: any, _event: Event, target: HTMLElement) {
+    const key = target?.dataset?.ability;
+    if (!key) return;
+    const actor = this.document;
+    const mod = actor.system.abilities?.[key]?.mod ?? 0;
+    const roll = new Roll(`1d20 + ${mod}`, actor.getRollData());
+    await roll.evaluate();
+    await roll.toMessage({
+      speaker: ChatMessage.getSpeaker({ actor }),
+      flavor: game.i18n.format('{{LOCALE_PREFIX}}.Sheet.Roll.flavor', {
+        ability: game.i18n.localize(`{{LOCALE_PREFIX}}.Ability.${key}`),
+      }),
+    });
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: see @vttforge/types follow-up
+  static async _onCreateGear(this: any, _event: Event, _target: HTMLElement) {
+    const cls = CONFIG.Item.documentClass;
+    const parent = this.document;
+    await cls.create(
+      { name: game.i18n.localize('{{LOCALE_PREFIX}}.Sheet.NewGearName'), type: 'gear' },
+      { parent, renderSheet: true },
+    );
+  }
+
+  // biome-ignore lint/suspicious/noExplicitAny: see @vttforge/types follow-up
+  static async _onDeleteItem(this: any, _event: Event, target: HTMLElement) {
+    const row = target?.closest('[data-item-id]') as HTMLElement | null;
+    const id = row?.dataset?.itemId;
+    if (!id) return;
+    const item = this.document.items.get(id);
+    await item?.delete();
+  }
+}

package/templates/system-ts/scripts/sheets/gear-sheet.ts

@@ -0,0 +1,68 @@
+/**
+ * GearSheet — minimal Item sheet built on `BaseItemSheet()` from
+ * `@vttforge/core`. Single PART, single TABS group, no DRAG_DROP — exercises
+ * the mirror surface of BaseActorSheet on ItemSheetV2.
+ */
+import { BaseItemSheet } from '@vttforge/core';
+
+const SYSTEM_ID = '{{ID}}';
+
+// biome-ignore lint/suspicious/noExplicitAny: typed sheet bases ship in a later @vttforge/types release
+const Base = BaseItemSheet() as any;
+
+export class GearSheet extends Base {
+  static DEFAULT_OPTIONS = foundry.utils.mergeObject(
+    Base.DEFAULT_OPTIONS,
+    {
+      id: '{{ID}}-gear',
+      classes: ['{{ID}}', 'sheet', 'item', 'gear'],
+      window: {
+        title: '{{LOCALE_PREFIX}}.Sheet.Gear.title',
+        icon: 'fa-solid fa-sack',
+      },
+      position: { width: 480, height: 420 },
+    },
+    { inplace: false },
+  );
+
+  static PARTS = {
+    sheet: {
+      template: `systems/${SYSTEM_ID}/templates/item/gear-sheet.hbs`,
+    },
+  };
+
+  static TABS = {
+    primary: {
+      tabs: [
+        {
+          id: 'details',
+          group: 'primary',
+          label: '{{LOCALE_PREFIX}}.Sheet.Tabs.details',
+          icon: 'fa-solid fa-list',
+        },
+        {
+          id: 'description',
+          group: 'primary',
+          label: '{{LOCALE_PREFIX}}.Sheet.Tabs.description',
+          icon: 'fa-solid fa-feather',
+        },
+      ],
+      initial: 'details',
+    },
+  };
+
+  // biome-ignore lint/suspicious/noExplicitAny: see @vttforge/types follow-up
+  async _prepareContext(options: any) {
+    const context = await super._prepareContext(options);
+    const item = (this as unknown as { document: any }).document;
+    context.item = item;
+    context.system = item.system;
+    context.isEditable = (this as unknown as { isEditable: boolean }).isEditable;
+    context.enrichedDescription =
+      await foundry.applications.ux.TextEditor.implementation.enrichHTML(
+        item.system?.description ?? '',
+        { relativeTo: item, secrets: item.isOwner },
+      );
+    return context;
+  }
+}