@vttforge/cli 0.0.0 → 0.5.0

package/templates/module-js/README.md

@@ -0,0 +1,57 @@
+# {{TITLE}}
+
+{{DESCRIPTION}}
+
+A Foundry VTT module built on [VTTForge](https://github.com/vttforge/vttforge) — uses `SystemConfig` from `@vttforge/core` for typed settings, ships an example hook listener, and exposes a small public API on `game.modules.get("{{ID}}").api`.
+
+> **Note** — VTTForge is currently in pre-release and not yet published to npm. Dependencies in `package.json` will resolve once VTTForge ships its first public release.
+
+## Quick start
+
+```bash
+pnpm install
+pnpm dev      # vite build --watch + auto-symlinks dist/ into Foundry's Data
+pnpm build    # one-shot build + emits {{ID}}-<version>.zip for foundryvtt.com
+```
+
+`pnpm dev` (`vttforge dev` under the hood) auto-detects your Foundry user-data
+directory on the first run, prompts you to confirm it, and saves the choice to
+`.vttforge/config.json` for next time. Override with `--data-dir <path>` or set
+`FOUNDRY_DATA_DIR` in your environment.
+
+Run Foundry with `--hotReload` to pick up changes without refreshing the page.
+Then enable **{{TITLE}}** in any world.
+
+## What's inside
+
+| Path | Purpose |
+|---|---|
+| `module.json` | Manifest |
+| `scripts/main.mjs` | Entry point — settings registration, hook listeners, public API |
+| `styles/main.css` | Stylesheet, scoped under `.{{ID}}` |
+| `lang/en.json` | Localization strings |
+
+## Public API
+
+The module exposes its API on `game.modules.get("{{ID}}").api`:
+
+```js
+const api = game.modules.get("{{ID}}").api;
+api.greet("world");                   // returns "Hello, world!"
+api.getSetting("showWelcome");        // returns the current value
+```
+
+Extend `scripts/main.mjs` to add real methods — the example exists to show the registration pattern.
+
+## Releasing to Foundry
+
+Tag-push triggers `.github/workflows/release.yml` to build, zip, and attach `{{ID}}-<version>.zip` + `dist/module.json` to a GitHub Release. Point Foundry at the `latest/download/module.json` URL.
+
+```bash
+git tag v0.1.0
+git push --tags
+```
+
+## License
+
+{{LICENSE}} © {{YEAR}} {{AUTHOR}}

package/templates/module-js/_gitignore

@@ -0,0 +1,12 @@
+node_modules
+dist
+.turbo
+.vscode
+.DS_Store
+*.log
+
+# vttforge dev — saved Foundry data-dir path
+.vttforge/
+
+# vttforge build — release artifact
+*.zip

package/templates/module-js/lang/en.json

@@ -0,0 +1,11 @@
+{
+  "{{LOCALE_PREFIX}}": {
+    "Settings": {
+      "showWelcome": {
+        "name": "Show welcome notification",
+        "hint": "Display a one-shot toast when {{TITLE}} loads in a world."
+      }
+    },
+    "Welcome": "{{TITLE}} loaded — try `game.modules.get(\"{{ID}}\").api.greet(\"GM\")` in the console."
+  }
+}

package/templates/module-js/module.json

@@ -0,0 +1,20 @@
+{
+  "id": "{{ID}}",
+  "title": "{{TITLE}}",
+  "description": "{{DESCRIPTION}}",
+  "version": "0.1.0",
+  "compatibility": {
+    "minimum": "{{FOUNDRY_MIN_VERSION}}",
+    "verified": "{{FOUNDRY_VERIFIED_VERSION}}"
+  },
+  "authors": [{ "name": "{{AUTHOR}}" }],
+  "esmodules": ["main.mjs"],
+  "styles": [{ "src": "styles/main.css" }],
+  "languages": [{ "lang": "en", "name": "English", "path": "lang/en.json" }],
+  "flags": {
+    "hotReload": {
+      "extensions": ["css", "json"],
+      "paths": ["styles", "lang"]
+    }
+  }
+}

package/templates/module-js/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{ID}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "{{DESCRIPTION}}",
+  "type": "module",
+  "license": "{{LICENSE}}",
+  "author": "{{AUTHOR}}",
+  "scripts": {
+    "build": "vttforge build",
+    "dev": "vttforge dev"
+  },
+  "dependencies": {
+    "@vttforge/core": "^0.6.0"
+  },
+  "devDependencies": {
+    "@vttforge/cli": "^0.5.0",
+    "@vttforge/vite-plugin": "^0.3.0",
+    "vite": "^8.2.2"
+  },
+  "engines": {
+    "node": ">=26"
+  }
+}

package/templates/module-js/scripts/main.mjs

@@ -0,0 +1,65 @@
+/**
+ * {{TITLE}} — entry point.
+ *
+ * Demonstrates the typical Foundry module lifecycle:
+ *
+ * - `Hooks.once("init")` — register settings (here via `SystemConfig` from
+ *   `@vttforge/core` for typed access) and expose the public API on
+ *   `game.modules.get(MODULE_ID).api`.
+ * - `Hooks.once("ready")` — surface a one-shot notification if the user
+ *   opted in via settings.
+ * - `Hooks.on("renderActorSheetV2", ...)` — example hook listener that
+ *   tags any actor sheet with a discreet `.{{ID}}-badge` so you can verify
+ *   the module is actually attached without hunting through devtools.
+ */
+import { SystemConfig } from '@vttforge/core';
+
+const MODULE_ID = '{{ID}}';
+const settings = new SystemConfig(MODULE_ID);
+
+Hooks.once('init', () => {
+  settings.register('showWelcome', {
+    name: '{{LOCALE_PREFIX}}.Settings.showWelcome.name',
+    hint: '{{LOCALE_PREFIX}}.Settings.showWelcome.hint',
+    scope: 'client',
+    config: true,
+    type: Boolean,
+    default: true,
+  });
+
+  const api = {
+    greet(name) {
+      return `Hello, ${name}!`;
+    },
+    getSetting(key) {
+      return settings.get(key);
+    },
+  };
+
+  const moduleHandle = game.modules.get(MODULE_ID);
+  if (moduleHandle) {
+    moduleHandle.api = api;
+  }
+});
+
+Hooks.once('ready', () => {
+  const shouldWelcome = settings.get('showWelcome');
+  if (shouldWelcome) {
+    ui.notifications?.info(game.i18n.localize('{{LOCALE_PREFIX}}.Welcome'));
+  }
+});
+
+Hooks.on('renderActorSheetV2', (_app, element) => {
+  // Decorative: tag the rendered sheet so it's obvious the module is
+  // active. Remove or replace with real behaviour once you start shipping
+  // module features.
+  const header = element.querySelector('.window-header .window-title');
+  if (header && !header.querySelector(`.{{ID}}-badge`)) {
+    const badge = document.createElement('span');
+    badge.className = '{{ID}}-badge';
+    // Double-quoted because `vttforge init` rejects `"` and `\` in the
+    // title — apostrophes in titles like "Daisy's Module" stay intact.
+    badge.textContent = "{{TITLE}}";
+    header.appendChild(badge);
+  }
+});

package/templates/module-js/styles/main.css

@@ -0,0 +1,16 @@
+/**
+ * {{TITLE}} stylesheet.
+ *
+ * Scope all rules under the `.{{ID}}` namespace so they don't leak into
+ * other modules or the host system's sheets. Foundry's CSS cascade is
+ * already layered, but namespacing makes intent explicit.
+ */
+.{{ID}}-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4em;
+  padding: 0.15em 0.5em;
+  border-radius: 4px;
+  background: rgba(0, 0, 0, 0.08);
+  font-size: 0.8em;
+}

package/templates/module-js/vite.config.mjs

@@ -0,0 +1,13 @@
+import vttforge from '@vttforge/vite-plugin';
+import { defineConfig } from 'vite';
+
+/**
+ * Vite config for {{TITLE}}.
+ *
+ * `@vttforge/vite-plugin` owns the build contract for both systems and
+ * modules — `kind: 'module'` tells the plugin to write `dist/module.json`
+ * (instead of `system.json`) and to base chunk URLs at `/modules/{{ID}}/`.
+ */
+export default defineConfig({
+  plugins: [vttforge({ id: '{{ID}}', kind: 'module' })],
+});

package/templates/module-ts/.github/workflows/release.yml

@@ -0,0 +1,92 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Resolve version from tag
+        id: version
+        env:
+          REF: ${{ github.ref_name }}
+        run: |
+          version="${REF#v}"
+          # Git allows surprising characters in tag names. Reject anything
+          # that isn't a strict semver-ish identifier so downstream node -e
+          # / shell interpolations can't be turned into command injection
+          # by a malicious tag push.
+          if ! [[ "$version" =~ ^[0-9A-Za-z._+-]+$ ]]; then
+            echo "Refusing tag with unsafe characters: $version" >&2
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - run: pnpm install
+
+      - name: Sync manifest version
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          node -e "const fs=require('node:fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));p.version=process.env.VERSION;fs.writeFileSync('package.json',JSON.stringify(p,null,2)+'\n');"
+
+      # We invoke vite directly (not `pnpm build` → `vttforge build`) because
+      # the release workflow needs to:
+      #   1. Run vite build → emit dist/module.json
+      #   2. Patch manifest/download URLs into dist/module.json
+      #   3. Zip dist/ → release artifact (so the zipped manifest carries URLs)
+      # `vttforge build` zips at step 1, which would freeze the un-patched
+      # manifest. Eventually the vite-plugin will support env-driven URL
+      # injection and this dance disappears.
+      - run: pnpm exec vite build
+
+      - name: Inject release URLs into manifest
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          REPO: ${{ github.repository }}
+          PKG_ID: '{{ID}}'
+        run: |
+          node -e "const fs=require('node:fs');const path='dist/module.json';const m=JSON.parse(fs.readFileSync(path,'utf8'));const r=process.env.REPO;const v=process.env.VERSION;const id=process.env.PKG_ID;m.manifest=\`https://github.com/\${r}/releases/latest/download/module.json\`;m.download=\`https://github.com/\${r}/releases/download/v\${v}/\${id}-\${v}.zip\`;fs.writeFileSync(path,JSON.stringify(m,null,2)+'\n');"
+
+      - name: Build release zip
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          PKG_ID: '{{ID}}'
+        run: |
+          cd dist
+          zip -r "../${PKG_ID}-${VERSION}.zip" .
+
+      - name: Create GitHub Release
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          PKG_ID: '{{ID}}'
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            ${{ env.PKG_ID }}-${{ env.VERSION }}.zip
+            dist/module.json
+          generate_release_notes: true
+          body: |
+            ## Foundry installation
+
+            Install via Foundry's setup wizard with this manifest URL:
+
+            ```
+            https://github.com/${{ github.repository }}/releases/latest/download/module.json
+            ```

package/templates/module-ts/README.md

@@ -0,0 +1,57 @@
+# {{TITLE}}
+
+{{DESCRIPTION}}
+
+A Foundry VTT module built on [VTTForge](https://github.com/vttforge/vttforge) — uses `SystemConfig` from `@vttforge/core` for typed settings, ships an example hook listener, and exposes a small public API on `game.modules.get("{{ID}}").api`.
+
+> **Note** — VTTForge is currently in pre-release and not yet published to npm. Dependencies in `package.json` will resolve once VTTForge ships its first public release.
+
+## Quick start
+
+```bash
+pnpm install
+pnpm dev      # vite build --watch + auto-symlinks dist/ into Foundry's Data
+pnpm build    # one-shot build + emits {{ID}}-<version>.zip for foundryvtt.com
+```
+
+`pnpm dev` (`vttforge dev` under the hood) auto-detects your Foundry user-data
+directory on the first run, prompts you to confirm it, and saves the choice to
+`.vttforge/config.json` for next time. Override with `--data-dir <path>` or set
+`FOUNDRY_DATA_DIR` in your environment.
+
+Run Foundry with `--hotReload` to pick up changes without refreshing the page.
+Then enable **{{TITLE}}** in any world.
+
+## What's inside
+
+| Path | Purpose |
+|---|---|
+| `module.json` | Manifest |
+| `scripts/main.ts` | Entry point — settings registration, hook listeners, public API |
+| `styles/main.css` | Stylesheet, scoped under `.{{ID}}` |
+| `lang/en.json` | Localization strings |
+
+## Public API
+
+The module exposes its API on `game.modules.get("{{ID}}").api`:
+
+```ts
+const api = game.modules.get("{{ID}}").api;
+api.greet("world");                   // returns "Hello, world!"
+api.getSetting("showWelcome");        // returns the current value
+```
+
+Extend `scripts/main.ts` to add real methods — the example exists to show the registration pattern.
+
+## Releasing to Foundry
+
+Tag-push triggers `.github/workflows/release.yml` to build, zip, and attach `{{ID}}-<version>.zip` + `dist/module.json` to a GitHub Release. Point Foundry at the `latest/download/module.json` URL.
+
+```bash
+git tag v0.1.0
+git push --tags
+```
+
+## License
+
+{{LICENSE}} © {{YEAR}} {{AUTHOR}}

package/templates/module-ts/_gitignore

@@ -0,0 +1,12 @@
+node_modules
+dist
+.turbo
+.vscode
+.DS_Store
+*.log
+
+# vttforge dev — saved Foundry data-dir path
+.vttforge/
+
+# vttforge build — release artifact
+*.zip

package/templates/module-ts/lang/en.json

@@ -0,0 +1,11 @@
+{
+  "{{LOCALE_PREFIX}}": {
+    "Settings": {
+      "showWelcome": {
+        "name": "Show welcome notification",
+        "hint": "Display a one-shot toast when {{TITLE}} loads in a world."
+      }
+    },
+    "Welcome": "{{TITLE}} loaded — try `game.modules.get(\"{{ID}}\").api.greet(\"GM\")` in the console."
+  }
+}

package/templates/module-ts/module.json

@@ -0,0 +1,20 @@
+{
+  "id": "{{ID}}",
+  "title": "{{TITLE}}",
+  "description": "{{DESCRIPTION}}",
+  "version": "0.1.0",
+  "compatibility": {
+    "minimum": "{{FOUNDRY_MIN_VERSION}}",
+    "verified": "{{FOUNDRY_VERIFIED_VERSION}}"
+  },
+  "authors": [{ "name": "{{AUTHOR}}" }],
+  "esmodules": ["main.mjs"],
+  "styles": [{ "src": "styles/main.css" }],
+  "languages": [{ "lang": "en", "name": "English", "path": "lang/en.json" }],
+  "flags": {
+    "hotReload": {
+      "extensions": ["css", "json"],
+      "paths": ["styles", "lang"]
+    }
+  }
+}

package/templates/module-ts/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{ID}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "{{DESCRIPTION}}",
+  "type": "module",
+  "license": "{{LICENSE}}",
+  "author": "{{AUTHOR}}",
+  "scripts": {
+    "build": "vttforge build",
+    "dev": "vttforge dev",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@vttforge/core": "^0.6.0"
+  },
+  "devDependencies": {
+    "@vttforge/cli": "^0.5.0",
+    "@vttforge/vite-plugin": "^0.3.0",
+    "typescript": "^5.4.0",
+    "vite": "^8.2.2"
+  },
+  "engines": {
+    "node": ">=26"
+  }
+}

package/templates/module-ts/scripts/foundry-globals.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal Foundry runtime globals.
+ *
+ * These declarations let the scaffold compile cleanly without an external
+ * type package. Replace with `fvtt-types` (community-maintained, pinned to
+ * a known-working commit SHA) or `@vttforge/types` (coming in a later
+ * VTTForge release) for full type coverage.
+ */
+
+declare global {
+  // biome-ignore lint/suspicious/noExplicitAny: stub declarations only
+  const game: any;
+  // biome-ignore lint/suspicious/noExplicitAny: stub declarations only
+  const CONFIG: any;
+  // biome-ignore lint/suspicious/noExplicitAny: stub declarations only
+  const Hooks: any;
+  // biome-ignore lint/suspicious/noExplicitAny: stub declarations only
+  const ui: any;
+  // biome-ignore lint/suspicious/noExplicitAny: stub declarations only
+  const foundry: any;
+}
+
+export {};

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

@@ -0,0 +1,71 @@
+/**
+ * {{TITLE}} — entry point.
+ *
+ * Demonstrates the typical Foundry module lifecycle:
+ *
+ * - `Hooks.once("init")` — register settings (here via `SystemConfig` from
+ *   `@vttforge/core` for typed access) and expose the public API on
+ *   `game.modules.get(MODULE_ID).api`.
+ * - `Hooks.once("ready")` — surface a one-shot notification if the user
+ *   opted in via settings.
+ * - `Hooks.on("renderActorSheetV2", ...)` — example hook listener that
+ *   tags any actor sheet with a discreet `.{{ID}}-badge` so you can verify
+ *   the module is actually attached without hunting through devtools.
+ */
+import './foundry-globals.js';
+import { SystemConfig } from '@vttforge/core';
+
+const MODULE_ID = '{{ID}}';
+const settings = new SystemConfig(MODULE_ID);
+
+interface ModuleApi {
+  greet(name: string): string;
+  getSetting<T>(key: string): T;
+}
+
+Hooks.once('init', () => {
+  settings.register('showWelcome', {
+    name: '{{LOCALE_PREFIX}}.Settings.showWelcome.name',
+    hint: '{{LOCALE_PREFIX}}.Settings.showWelcome.hint',
+    scope: 'client',
+    config: true,
+    type: Boolean,
+    default: true,
+  });
+
+  const api: ModuleApi = {
+    greet(name: string): string {
+      return `Hello, ${name}!`;
+    },
+    getSetting<T>(key: string): T {
+      return settings.get(key) as T;
+    },
+  };
+
+  const moduleHandle = game.modules.get(MODULE_ID);
+  if (moduleHandle) {
+    moduleHandle.api = api;
+  }
+});
+
+Hooks.once('ready', () => {
+  const shouldWelcome = settings.get<boolean>('showWelcome');
+  if (shouldWelcome) {
+    ui.notifications?.info(game.i18n.localize('{{LOCALE_PREFIX}}.Welcome'));
+  }
+});
+
+Hooks.on('renderActorSheetV2', (_app: unknown, element: HTMLElement) => {
+  // Decorative: tag the rendered sheet so it's obvious the module is
+  // active. Remove or replace with real behaviour once you start shipping
+  // module features.
+  const header = element.querySelector('.window-header .window-title');
+  if (header && !header.querySelector(`.{{ID}}-badge`)) {
+    const badge = document.createElement('span');
+    badge.className = '{{ID}}-badge';
+    // Double-quoted because `vttforge init` rejects `"` and `\` in the
+    // title — apostrophes in titles like "Daisy's Module" stay intact.
+    badge.textContent = "{{TITLE}}";
+    header.appendChild(badge);
+  }
+});

package/templates/module-ts/styles/main.css

@@ -0,0 +1,16 @@
+/**
+ * {{TITLE}} stylesheet.
+ *
+ * Scope all rules under the `.{{ID}}` namespace so they don't leak into
+ * other modules or the host system's sheets. Foundry's CSS cascade is
+ * already layered, but namespacing makes intent explicit.
+ */
+.{{ID}}-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4em;
+  padding: 0.15em 0.5em;
+  border-radius: 4px;
+  background: rgba(0, 0, 0, 0.08);
+  font-size: 0.8em;
+}

package/templates/module-ts/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": false
+  },
+  "include": ["scripts/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/module-ts/vite.config.mjs

@@ -0,0 +1,13 @@
+import vttforge from '@vttforge/vite-plugin';
+import { defineConfig } from 'vite';
+
+/**
+ * Vite config for {{TITLE}}.
+ *
+ * `@vttforge/vite-plugin` owns the build contract for both systems and
+ * modules — `kind: 'module'` tells the plugin to write `dist/module.json`
+ * (instead of `system.json`) and to base chunk URLs at `/modules/{{ID}}/`.
+ */
+export default defineConfig({
+  plugins: [vttforge({ id: '{{ID}}', kind: 'module', entry: 'scripts/main.ts' })],
+});