@vttforge/cli 0.0.0 → 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,364 @@
+# @vttforge/cli
+
+## 0.5.1
+
+### Patch Changes
+
+- 57af020: Ship the template pins that were already corrected.
+  
+  The templates under `templates/*` name the `@vttforge/*` ranges a scaffolded project starts with. Those pins were kept current in the repo — a guard has caught a stale one eight times — but they were only ever corrected *in the repo*. The templates ride inside this package's tarball, and this package was never released alongside the bumps, so nothing reached anyone.
+  
+  `pnpm create vttforge` has been scaffolding `@vttforge/core@^0.6.0` while core shipped 0.10.0. A new project could not see sheet registration, text enrichers, or `BaseDocumentSheet`, and its lockfile would resolve a core four minors old.
+  
+  Templates now pin `@vttforge/core@^0.10.0` and `@vttforge/vite-plugin@^0.4.0`.
+  
+  The guard also learned the second half: if a release bumps a package the templates pin, it has to include `@vttforge/cli`, or the corrected pin sits in the repo and ships to nobody.
+
+## 0.5.0
+
+### Minor Changes
+
+- 3eb8c96: `vttforge init` can now run without a terminal.
+  
+  Five values — id, title, description, author, license — were always asked for, with no flag to supply them. Clack prompts read from stdin, so with none attached the scaffolder hung: no error, no output, nothing to debug. That ruled out CI and scripts, and meant nothing could test the scaffolder through its own entry point.
+  
+  Each now has a flag, and `--yes` (`-y`) takes the default for anything not passed. A run with no terminal assumes `--yes`, so CI needs no extra flag.
+  
+  ```bash
+  vttforge init pdf-character-sheet --type module --lang ts \
+    --title "PDF Character Sheet" --license Apache-2.0 --yes
+  ```
+  
+  The directory name is the one thing with no sensible default. Without a terminal to ask, the run stops and says so.
+
+### Patch Changes
+
+- 11187a0: Say what the scaffolded schemas mean.
+  
+  The generated number fields declared `required: true` but left `nullable` alone, so they still accepted `null` — and now that the types say so, that shows up as an error the author has to think about. They set `nullable: false`.
+  
+  The six ability scores share one spec instead of repeating it six times.
+- 353633c: Build each ability score from a factory rather than one shared options object.
+  
+  A field keeps a reference to the options it was handed, and some field classes write back into that object. Six fields sharing one object is safe for the field this template uses, but it is not a habit to teach in code people copy and adapt.
+- c24b2e9: Point the templates at the core version this release publishes.
+  
+  The `ColorField` and presence fixes take `@vttforge/core` to 0.6.0, and a
+  caret pins the minor on a 0.x version, so the templates' `^0.5.0` would not
+  have matched.
+
+## 0.4.0
+
+### Minor Changes
+
+- 17a6b8c: Redraw only the sheets a template change actually affects.
+  
+  A sheet declares its templates in `static PARTS`, so the mapping is on the
+  open window itself — no build-time graph needed. Each part names a primary
+  `template` and may list further `templates`, which is where a partial it
+  pulls in appears. Only the affected parts re-render, so scroll position and
+  focus survive everywhere else. When nothing claims the file the whole screen
+  still redraws, because a partial can be reached without any part naming it.
+  
+  The watcher now also skips a file whose content did not change. Vite rewrites
+  its entire output on every build, so a filesystem event alone means "the
+  bundler ran", not "the developer edited this" — and without this the language
+  file gets resent untouched on every save, and the JSON path redraws every open
+  window, undoing the scoping on the file that did change.
+  
+  Measured in a running world with 21 applications open: editing one sheet
+  template went from 35 renders to 1.
+
+## 0.3.0
+
+### Minor Changes
+
+- 5b72b4b: `vttforge dev` now applies saves in place, without a page refresh.
+  
+  It opens a small WebSocket, links `@vttforge/dev-module` into Foundry's
+  modules directory, and watches the build output — sending a payload per
+  changed CSS, template or language file.
+  
+  The socket is hand-written rather than pulled from a package. The CLI ships
+  to every consumer, so each dependency is one they install too, and what is
+  needed here is a narrow slice of the protocol: accept the upgrade, send
+  unmasked text frames, notice when a client leaves.
+  
+  Watching `dist/` rather than hooking into Vite keeps this correct across
+  bundler versions, and gives the served path directly — `dist/` is what
+  Foundry mounts.
+  
+  Failing to start the bridge costs hot reload, not the dev loop. A busy port
+  or a missing companion package prints why and carries on watching.
+  
+  New: `--hmr-port` to move the bridge off 31313.
+
+### Patch Changes
+
+- 1fb967d: Close the three soundness gaps `vttforge audit` shipped with, and a fourth
+  found while fixing them.
+  
+  - `filePathFields` is an object whose keys are the field paths, not a flat
+    array. Reading it as an array dropped every correctly declared path, so
+    rule 004 reported declared fields as missing.
+  - Modules register subtypes as `<moduleId>.<type>` while the manifest
+    declares the bare key. The two were compared verbatim, so no module
+    registration ever matched its own declaration.
+  - Rule 007 searched every schema in the project for the token attribute.
+    Token bars read `actor.system`, so an Item model declaring the same path
+    satisfied the check on a system whose bars were in fact broken. The
+    narrowing applies only when Actor registrations are known; with none
+    found the rule falls back to the previous behaviour.
+  - Registrations through bracket notation were invisible to the scanner
+    entirely — which is the only form modules can use, since a dot in the key
+    rules out property access.
+- c90357e: Point the templates at the CLI version this release publishes.
+  
+  The templates asked for `@vttforge/cli@^0.2.0` while the release takes it to
+  0.3.0. A caret pins the minor on a 0.x version, so that range would not have
+  matched — every project scaffolded after the release would ask for a version
+  the release had just superseded.
+
+## 0.2.0
+
+### Minor Changes
+
+- 9462144: Require Node 26.
+
+  The floor moves from `>=22.14.0` to `>=26.0.0` across every package and the
+  four scaffolding templates, and the bundler target for the Node-side
+  packages moves from `node22` to `node26`.
+
+  Node 22 entered maintenance in October 2025 and receives security fixes
+  only. Node 26 becomes the active LTS line on 2026-10-28.
+
+  This is breaking for anyone on Node 22 or 24. It is marked `minor` rather
+  than `major` on purpose: these packages are still on 0.x, where a minor
+  signals the break, and a major would push every package to 1.0.0 — a claim
+  of API stability that has not been audited, on packages two of which are
+  still stubs.
+
+  The templates move to the versions this release publishes. On 0.x a caret
+  pins the minor, so their old ranges would not have matched.
+
+  CI now pins Node through `actions/setup-node` instead of inheriting whatever
+  the runner image ships, so the version the packages declare is the version
+  they are tested on. It was not before: the workflow took the image's Node,
+  and nothing enforced the declared floor because `engine-strict` is not set.
+
+## 0.1.1
+
+### Patch Changes
+
+- 5f03da9: Move to citty 0.2 and cover argument parsing with tests.
+
+  citty 0.2 is ESM-only, drops its runtime dependencies, and rewrites the
+  parser on top of `node:util.parseArgs`. Parsing behaviour is unchanged for
+  every flag this CLI defines — negation, aliases, positionals, `--flag=value`
+  and boolean defaults all produce identical results on 0.1.6 and 0.2.2.
+
+  The command tree moves from `bin.ts` to `cli.ts`, leaving the bin as the
+  launch only. The definitions were unreachable from tests before, because a
+  module that calls `runMain` on import runs the CLI. They are now covered,
+  including `--no-install` and `--no-git`, which would have made the
+  scaffolder install dependencies for someone who asked it not to had the
+  parser rewrite changed them.
+
+## 0.1.0
+
+### Minor Changes
+
+- 139802c: feat(cli): ship `vttforge audit` — scan for seven v13 footguns
+
+  Closes the third and final slice of Track 1. `vttforge audit [path]` scans
+  a system or module project root and reports findings against the
+  `VTTF-AUDIT-NNN` catalog of v13 manifest + code footguns.
+
+  **Rules implemented:**
+
+  | ID               | Severity | Scope             | What it catches                                                                                                                                                                                                                                                                                                                                         |
+  | ---------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | `VTTF-AUDIT-001` | HIGH     | manifest          | `flags.hotReload` as array (v12) or missing required `extensions` key. Silently disables HMR.                                                                                                                                                                                                                                                           |
+  | `VTTF-AUDIT-002` | MEDIUM   | manifest          | Top-level `gridDistance` / `gridUnits` (v12) instead of `grid: {type, distance, units, diagonals}` (v13). Auto-migrates today, removed in v14.                                                                                                                                                                                                          |
+  | `VTTF-AUDIT-003` | LOW      | manifest          | `styles: ["foo.css"]` (string array) instead of `[{src, layer?}]` (v13). Auto-migrates but loses cascade-layer control.                                                                                                                                                                                                                                 |
+  | `VTTF-AUDIT-004` | MEDIUM   | manifest + source | `HTMLField` / `FilePathField` declared in TypeDataModel schema but missing from `documentTypes.<Doc>.<subtype>.htmlFields` / `.filePathFields`. Server only sanitises declared paths → XSS risk on undeclared. Subtype-aware via `CONFIG.*.dataModels` + `registerSystem({ actorDataModels })` parsing; full-path matching through SchemaField nesting. |
+  | `VTTF-AUDIT-005` | MEDIUM   | source            | `class X extends TypeDataModel` without a `prepareBaseData()` method. Active Effects apply between base and derived; consumers see uninitialised fields. Checked per class.                                                                                                                                                                             |
+  | `VTTF-AUDIT-006` | LOW      | source            | `_addDataFieldMigrations()` override on a TypeDataModel subclass. Real API is `static migrateData(source)` calling singular `super._addDataFieldMigration(...)`.                                                                                                                                                                                        |
+  | `VTTF-AUDIT-007` | MEDIUM   | manifest + source | `primaryTokenAttribute` / `secondaryTokenAttribute` doesn't resolve to a `SchemaField({ value, max })` at the exact dot-path. Nested paths like `attributes.hp` are traversed.                                                                                                                                                                          |
+
+  **CLI surface:**
+
+  ```bash
+  vttforge audit                  # scan cwd, print markdown
+  vttforge audit ./my-project     # scan a different path
+  vttforge audit --json           # machine-readable JSON for CI piping
+  vttforge audit --strict         # exit 1 on any finding (default: HIGH only)
+  ```
+
+  **Exit codes:**
+  - `0` — clean, or only MEDIUM/LOW findings (advisory mode)
+  - `1` — at least one HIGH finding, or any finding in `--strict`
+
+  Uses `process.exitCode` (not `process.exit`) so piped JSON reports aren't
+  truncated on failing CI runs.
+
+  **Implementation notes:**
+  - Pure read-only — never modifies the source tree.
+  - Regex-based source scanning. The trade-off is occasional false negatives
+    on heavily-formatted code; an AST dependency (TypeScript compiler) would
+    add ~30MB to the CLI for seven pattern checks. Rule 007's
+    `SchemaField({value, max})` detection uses a balanced-brace scan plus a
+    depth-tracking top-level-key extractor to correctly distinguish
+    SchemaField siblings from nested constructor options.
+  - Rule 005 distinguishes `extends TypeDataModel` (direct, flagged) from
+    `extends BaseTypeDataModel()` (VTTForge factory, safe) via the `\b`
+    word boundary, and is checked per class so a sibling subclass without
+    the hook doesn't hide behind a sibling that has it.
+  - Rule 004 takes the FULL schema path through enclosing SchemaField
+    wrappers and matches exactly against declared paths (with `system.`
+    prefix stripped — Foundry convention).
+
+  **Tests:** 247 passing (+13 new test files, ~110 new test cases). Integration
+  suite scaffolds each of the four templates and runs the audit against the
+  output — they must report zero findings, otherwise either a template
+  regressed or the audit grew a false positive.
+
+- 09de435: feat(cli): ship `vttforge dev` and `vttforge build`
+
+  `@vttforge/cli` graduates from "scaffold-only" to a full local dev loop.
+
+  **`vttforge dev`** — single-process dev experience for system/module work:
+  1. Runs `vite build` once to populate `dist/` and emit the manifest.
+  2. Reads the manifest, detects whether the project is a system or module.
+  3. Resolves the Foundry user-data directory via a four-step chain:
+     `--data-dir` flag → `FOUNDRY_DATA_DIR` env → project's
+     `.vttforge/config.json` → OS default with interactive first-run
+     prompt that saves the choice. OS detection honors `XDG_DATA_HOME`
+     on Linux and `%LOCALAPPDATA%` on Windows.
+  4. Drops a symlink at `<dataRoot>/Data/<systems|modules>/<id>` pointing
+     at the project's `dist/`. Cross-platform — `junction` on Windows so
+     the call succeeds without Developer Mode or admin elevation; safety
+     rails refuse to overwrite real files/directories.
+  5. Spawns `vite build --watch` with inherited stdio, blocks until
+     SIGINT/SIGTERM, then cleans up the symlink and kills vite.
+
+  When Foundry runs with `--hotReload`, file saves trigger live reload
+  without a browser refresh — chokidar follows the symlink and Foundry's
+  built-in dispatcher swaps CSS/HBS/JSON in place. No additional client
+  wiring needed in this release.
+
+  **`vttforge build`** — produces a foundryvtt.com-ready release zip:
+  1. Cleans `dist/`, runs `vite build` in production mode.
+  2. Reads the manifest for `id` + `version`.
+  3. Emits `<id>-<version>.zip` at the project root with contents at the
+     zip root (no wrapper folder), pulling in `LICENSE`, `README.md`, and
+     `CHANGELOG.md` from the project root when present and not already
+     inside `dist/`.
+
+  **Templates updated** — all four (system-ts, system-js, module-ts,
+  module-js) now ship `pnpm dev` / `pnpm build` aliased to the new
+  commands, drop the manual `ln -s` instructions, and gain
+  `@vttforge/cli` as a devDependency. The release workflow continues to
+  invoke vite directly so URL injection happens after build but before
+  zipping; it now validates tag-derived version strings and passes every
+  GitHub-supplied value via `env:` instead of inline interpolation to
+  close a command-injection vector that a malicious tag push could
+  otherwise exploit.
+
+  **Internals exposed** — `runDev`, `runBuild`, `emitReleaseZip`,
+  `setupDevSymlink`, `resolveFoundryDataDir`, `createLink`/`removeLink`,
+  `readManifest`, and `emitZip` are all importable from `@vttforge/cli`
+  for consumers building higher-level tooling.
+
+  **Dependencies** — adds `archiver` (zip emission) pinned to `^7` since
+  archiver v8 went ESM-only with renamed exports that DefinitelyTyped
+  hasn't caught up to yet.
+
+- eb1c41d: feat(cli): ship the `vttforge init` scaffolder + four built-in templates
+
+  `@vttforge/cli` now provides a real, interactive scaffolder. `vttforge init`
+  (or `pnpm create vttforge` via the new `create-vttforge` package) walks the
+  user through naming the project, picking system/module + TypeScript/JavaScript,
+  and writing a complete VTTForge starter into a new directory.
+
+  **Bin commands:**
+  - `vttforge init [name]` — interactive scaffolder. Honors `--type`, `--lang`,
+    `--no-install`, `--no-git` flags; everything else is prompted for via
+    `@clack/prompts`. Detects the calling package manager via
+    `npm_config_user_agent` (pnpm / npm / bun / yarn) and offers to run
+    `<pm> install` after writing files. Optionally initializes a git repo
+    with an initial commit.
+  - `vttforge dev`, `vttforge build`, `vttforge audit` — reserved subcommands
+    that print a discoverable next-step message until their real
+    implementations land in a later release.
+
+  **Four built-in templates** under `packages/cli/templates/`:
+  - `system-ts` / `system-js` — realistic Foundry v13+ system that mirrors
+    the reference `examples/simple-system`. Ships `CharacterData` + `GearData`
+    TypeDataModels, `CharacterSheet` + `GearSheet` extending `BaseActorSheet`
+    / `BaseItemSheet`, a `createMigrationRunner` with one example migration,
+    Handlebars templates for both sheets, the four v13 manifest shapes
+    (`grid`, `styles: [{src}]`, `flags.hotReload` at the root of `flags`,
+    per-subtype `htmlFields`), and a tagged-release GitHub Actions workflow
+    that builds + zips + publishes to a GitHub Release.
+  - `module-ts` / `module-js` — minimal but realistic module. Registers a
+    client-scope setting via `SystemConfig` from `@vttforge/core`, listens on
+    `renderActorSheetV2` to tag the rendered sheet with a discreet badge,
+    exposes a tiny API on `game.modules.get(id).api`, and ships the same
+    tag-driven release workflow.
+
+  **New package — `create-vttforge`** — thin wrapper around `@vttforge/cli init`
+  that enables the `pnpm create vttforge my-system` / `npm create vttforge@latest my-system`
+  UX familiar from the `create-vite` / `create-next-app` ecosystem.
+
+  44 unit tests cover the substitution logic, the package-manager detector, and
+  a per-template integration suite that scaffolds every variant into a temporary
+  directory and asserts shape (no leftover placeholders, valid manifest,
+  expected files). Templates are excluded from biome and vitest scanning since
+  they contain `{{PLACEHOLDER}}` strings that aren't valid TypeScript/JSON until
+  substitution.
+
+- 4d34985: Move to Vite 8.
+
+  The plugin's `vite` peer range now reads `^8.2.2`, so a project still on
+  Vite 6 or 7 will not satisfy it. The four `vttforge init` templates move
+  with it, which keeps a freshly scaffolded project free of a peer conflict.
+
+  The plugin itself needed no code change — it uses only the `config` hook
+  and the `Plugin` and `UserConfig` types, all unchanged across the two
+  majors.
+
+### Patch Changes
+
+- 6e36de2: Move the release-zip writer to archiver 8.
+
+  Archiver 8 is ESM-only and dropped its default export, so the old
+  `archiver('zip', options)` factory call is gone. The writer now builds the
+  named `ZipArchive` class directly. Same options, same output: package
+  contents sit at the zip root with no wrapper folder, and LICENSE, README
+  and CHANGELOG still ride along from the project root when present.
+
+- edd88fe: Move the prompts to `@clack/prompts` 1.x, and fix a validator that let a
+  missing package id through.
+
+  Clack 1.x hands validators `string | undefined` instead of `string`, since
+  it calls them before anything is typed. Widening the signatures surfaced a
+  latent bug in the package-id check: it called `RegExp.test` on the raw
+  value, and an undefined value coerces to the string `"undefined"`, which
+  matches the allowed pattern. A missing id therefore passed validation. The
+  check now coalesces first.
+
+  The three validators are exported and covered by tests. They were only
+  reachable through the interactive prompt before, so nothing exercised them.
+
+- 4ba725c: Point the scaffolding templates at the versions this release publishes.
+
+  The templates asked for `@vttforge/core@^0.3.0` and
+  `@vttforge/vite-plugin@^0.1.0`. On a 0.x version a caret pins the minor, so
+  `^0.3.0` means `>=0.3.0 <0.4.0` — and this release takes core to 0.4.0 and
+  the plugin to 0.2.0. Left alone, every project scaffolded after the release
+  would ask for versions the release had just superseded.
+
+## 0.0.1
+
+Initial placeholder release — package name reserved on npm. Implementation lands in v0.3.0.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fabricio Cavalcante de Souza and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,11 +1,39 @@
 # @vttforge/cli
 
-Command-line tool to scaffold and build FoundryVTT systems and modules.
+VTTForge CLI — scaffolding, dev loop, and release builds for Foundry VTT v13+ systems and modules.
 
-> 🚧 **Placeholder release.** This is a reserved name on the npm registry. The first usable version is coming soon.
+## Commands
 
-Track progress and contribute at **https://github.com/vttforge/vttforge**.
+```bash
+vttforge init <name> [--type system|module] [--lang ts|js] [--no-install] [--no-git]
+vttforge dev  [--foundry-data <path>]
+vttforge build
+```
 
----
+- `vttforge init` — interactive scaffolder. Asks for package id, title, author, license, Foundry compatibility version, and writes a runnable system/module starter into `<name>/`. Detects the calling package manager (`pnpm`, `npm`, `bun`, `yarn`) via `npm_config_user_agent` and offers to install deps + `git init`. Equivalent UX from `pnpm create vttforge <name>` via the `create-vttforge` package.
+- `vttforge dev` — one-shot `vite build`, then symlink `dist/` into your Foundry user-data directory under `Data/<systems|modules>/<id>/`, then `vite build --watch` with inherited stdio. Cleans up the symlink on `Ctrl-C`. First run prompts for the Foundry data dir and saves the choice to `.vttforge/config.json`; subsequent runs skip the prompt. Override with `--foundry-data <path>` (alias: `--data-dir`) or set `FOUNDRY_DATA_DIR` in your environment.
+- `vttforge build` — production `vite build` followed by `<id>-<version>.zip` emission at the project root. Pulls `LICENSE`, `README.md`, and `CHANGELOG.md` from the project root into the zip when present.
 
-VTTForge is an independent, community-developed project. It is not affiliated with, endorsed by, or sponsored by Foundry Gaming LLC. "Foundry Virtual Tabletop", "Foundry VTT", and "FVTT" are trademarks of Foundry Gaming LLC.
+## Library exports
+
+`@vttforge/cli` also exposes its internals for consumers building higher-level tooling:
+
+```ts
+import {
+  runInit, runDev, runBuild,
+  scaffold, substitute, templatesRoot,
+  resolveFoundryDataDir, foundryPackagesDir,
+  readManifest, emitZip,
+  createLink, removeLink, readLinkTarget,
+  resolveViteInvocation, runViteBuildOnce, spawnViteWatch,
+  detectPackageManager, detectProjectPackageManager, execInvocation, installCommand,
+} from '@vttforge/cli';
+```
+
+## Foundry-aware HMR
+
+Run Foundry with `--hotReload` (e.g. `foundryvtt --hotReload`) and `vttforge dev` becomes a live-reload loop without further setup: Foundry's built-in chokidar watcher follows the symlink, and its dispatcher swaps CSS / Handlebars / JSON files in place when vite re-emits them.
+
+## Stack
+
+Citty (commands) + Clack (prompts) + Archiver (zip).

package/dist/bin.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/bin.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import { M as runAuditCommand, c as runDev, n as ScaffoldError, r as runInit, t as VTTFORGE_CLI_VERSION, x as runBuild } from "./src-CWhUNM__.mjs";
+import { defineCommand, runMain } from "citty";
+//#region src/cli.ts
+/**
+* vttforge command tree.
+*
+* Kept apart from `bin.ts`, which only runs it. Argument definitions are the
+* CLI's contract with its users — `--no-install` skipping the install, an
+* alias resolving to its canonical name — and a module that calls `runMain`
+* on import cannot be reached by a test. Exporting the commands from here
+* lets the suite parse real argv against the real definitions.
+*/
+const init = defineCommand({
+	meta: {
+		name: "init",
+		description: "Scaffold a new Foundry VTT system or module from a VTTForge template"
+	},
+	args: {
+		name: {
+			type: "positional",
+			description: "Directory name for the new system/module (also the default manifest id)",
+			required: false
+		},
+		type: {
+			type: "string",
+			description: "Package type: system | module"
+		},
+		lang: {
+			type: "string",
+			description: "Language: ts | js"
+		},
+		id: {
+			type: "string",
+			description: "Manifest id (defaults to a slug of the directory name)"
+		},
+		title: {
+			type: "string",
+			description: "Human-readable title shown in Foundry setup screens"
+		},
+		description: {
+			type: "string",
+			description: "One-line description for the manifest"
+		},
+		author: {
+			type: "string",
+			description: "Author name for the manifest (defaults to the git author)"
+		},
+		license: {
+			type: "string",
+			description: "SPDX license id (default MIT)"
+		},
+		yes: {
+			type: "boolean",
+			alias: "y",
+			default: false,
+			description: "Accept defaults for anything not passed, without prompting"
+		},
+		install: {
+			type: "boolean",
+			default: true,
+			description: "Install dependencies after scaffold (use --no-install to skip)"
+		},
+		git: {
+			type: "boolean",
+			default: true,
+			description: "Initialize a git repository after scaffold (use --no-git to skip)"
+		}
+	},
+	async run({ args }) {
+		try {
+			await runInit({
+				name: typeof args.name === "string" ? args.name : void 0,
+				type: typeof args.type === "string" ? args.type : void 0,
+				lang: typeof args.lang === "string" ? args.lang : void 0,
+				id: typeof args.id === "string" ? args.id : void 0,
+				title: typeof args.title === "string" ? args.title : void 0,
+				description: typeof args.description === "string" ? args.description : void 0,
+				author: typeof args.author === "string" ? args.author : void 0,
+				license: typeof args.license === "string" ? args.license : void 0,
+				yes: args.yes === true,
+				noInstall: args.install === false,
+				noGit: args.git === false
+			});
+		} catch (err) {
+			if (!(err instanceof ScaffoldError)) console.error(err instanceof Error ? err.message : String(err));
+			process.exit(1);
+		}
+	}
+});
+const dev = defineCommand({
+	meta: {
+		name: "dev",
+		description: "Symlink dist/ into Foundry Data and run vite build --watch"
+	},
+	args: {
+		"foundry-data": {
+			type: "string",
+			alias: "data-dir",
+			description: "Override the Foundry user-data directory (skips env / config / first-run prompt)"
+		},
+		"hmr-port": {
+			type: "string",
+			description: "Port for the hot reload bridge (default 31313)"
+		}
+	},
+	async run({ args }) {
+		const explicit = (typeof args["foundry-data"] === "string" ? args["foundry-data"] : void 0) ?? (typeof args["data-dir"] === "string" ? args["data-dir"] : void 0);
+		const rawPort = typeof args["hmr-port"] === "string" ? args["hmr-port"] : void 0;
+		const hmrPort = rawPort === void 0 ? void 0 : Number(rawPort);
+		if (hmrPort !== void 0 && !Number.isInteger(hmrPort)) {
+			console.error(`--hmr-port expects a whole number, got \`${rawPort}\`.`);
+			process.exit(1);
+		}
+		try {
+			await runDev({
+				dataDir: explicit,
+				hmrPort
+			});
+		} catch (err) {
+			console.error(err instanceof Error ? err.message : String(err));
+			process.exit(1);
+		}
+	}
+});
+const build = defineCommand({
+	meta: {
+		name: "build",
+		description: "Run vite build (production) and emit <id>-<version>.zip for foundryvtt.com"
+	},
+	async run() {
+		try {
+			await runBuild();
+		} catch (err) {
+			console.error(err instanceof Error ? err.message : String(err));
+			process.exit(1);
+		}
+	}
+});
+const audit = defineCommand({
+	meta: {
+		name: "audit",
+		description: "Scan a system/module project for the seven v13 manifest + code footguns"
+	},
+	args: {
+		path: {
+			type: "positional",
+			description: "Project root to scan (defaults to the current directory)",
+			required: false
+		},
+		json: {
+			type: "boolean",
+			default: false,
+			description: "Emit a machine-readable JSON report instead of markdown"
+		},
+		strict: {
+			type: "boolean",
+			default: false,
+			description: "Exit non-zero on any finding (default: only HIGH triggers a non-zero exit)"
+		}
+	},
+	async run({ args }) {
+		try {
+			const result = await runAuditCommand({
+				cwd: typeof args.path === "string" ? args.path : void 0,
+				format: args.json === true ? "json" : "markdown",
+				strict: args.strict === true
+			});
+			if (result.exitCode !== 0) process.exitCode = result.exitCode;
+		} catch (err) {
+			console.error(err instanceof Error ? err.message : String(err));
+			process.exitCode = 1;
+		}
+	}
+});
+const main = defineCommand({
+	meta: {
+		name: "vttforge",
+		version: VTTFORGE_CLI_VERSION,
+		description: "VTTForge CLI — scaffold, dev, build for Foundry v13+ systems and modules"
+	},
+	subCommands: {
+		init,
+		dev,
+		build,
+		audit
+	}
+});
+//#endregion
+//#region src/bin.ts
+/**
+* vttforge bin — the executable entry.
+*
+* Nothing but the launch. The command tree lives in `cli.ts` so tests can
+* import it without running the CLI.
+*/
+runMain(main);
+//#endregion
+export {};
+
+//# sourceMappingURL=bin.mjs.map

package/dist/bin.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.mjs","names":[],"sources":["../src/cli.ts","../src/bin.ts"],"sourcesContent":["/**\n * vttforge command tree.\n *\n * Kept apart from `bin.ts`, which only runs it. Argument definitions are the\n * CLI's contract with its users — `--no-install` skipping the install, an\n * alias resolving to its canonical name — and a module that calls `runMain`\n * on import cannot be reached by a test. Exporting the commands from here\n * lets the suite parse real argv against the real definitions.\n */\nimport { defineCommand } from 'citty';\nimport { runAuditCommand } from './commands/audit.js';\nimport { runBuild } from './commands/build.js';\nimport { runDev } from './commands/dev.js';\nimport { runInit, ScaffoldError } from './commands/init.js';\nimport { VTTFORGE_CLI_VERSION } from './index.js';\n\nexport const init = defineCommand({\n  meta: {\n    name: 'init',\n    description: 'Scaffold a new Foundry VTT system or module from a VTTForge template',\n  },\n  args: {\n    name: {\n      type: 'positional',\n      description: 'Directory name for the new system/module (also the default manifest id)',\n      required: false,\n    },\n    type: {\n      type: 'string',\n      description: 'Package type: system | module',\n    },\n    lang: {\n      type: 'string',\n      description: 'Language: ts | js',\n    },\n    id: {\n      type: 'string',\n      description: 'Manifest id (defaults to a slug of the directory name)',\n    },\n    title: {\n      type: 'string',\n      description: 'Human-readable title shown in Foundry setup screens',\n    },\n    description: {\n      type: 'string',\n      description: 'One-line description for the manifest',\n    },\n    author: {\n      type: 'string',\n      description: 'Author name for the manifest (defaults to the git author)',\n    },\n    license: {\n      type: 'string',\n      description: 'SPDX license id (default MIT)',\n    },\n    // Without a terminal there is nothing for a prompt to read, so it waits\n    // forever. This flag takes the defaults instead — and the scaffolder\n    // also assumes it when stdin is not a TTY, so CI need not pass it.\n    yes: {\n      type: 'boolean',\n      alias: 'y',\n      default: false,\n      description: 'Accept defaults for anything not passed, without prompting',\n    },\n    // Citty parses `--no-X` as `args.X === false`, so define affirmative\n    // flags with a true default. `--no-install` then yields `install: false`\n    // which we forward as `noInstall: true`.\n    install: {\n      type: 'boolean',\n      default: true,\n      description: 'Install dependencies after scaffold (use --no-install to skip)',\n    },\n    git: {\n      type: 'boolean',\n      default: true,\n      description: 'Initialize a git repository after scaffold (use --no-git to skip)',\n    },\n  },\n  async run({ args }) {\n    try {\n      await runInit({\n        name: typeof args.name === 'string' ? args.name : undefined,\n        type: typeof args.type === 'string' ? (args.type as 'system' | 'module') : undefined,\n        lang: typeof args.lang === 'string' ? (args.lang as 'ts' | 'js') : undefined,\n        id: typeof args.id === 'string' ? args.id : undefined,\n        title: typeof args.title === 'string' ? args.title : undefined,\n        description: typeof args.description === 'string' ? args.description : undefined,\n        author: typeof args.author === 'string' ? args.author : undefined,\n        license: typeof args.license === 'string' ? args.license : undefined,\n        yes: args.yes === true,\n        noInstall: args.install === false,\n        noGit: args.git === false,\n      });\n    } catch (err) {\n      // ScaffoldError already surfaced its message via `p.cancel`; anything\n      // else is a real crash worth showing. Either way the bin exits 1.\n      if (!(err instanceof ScaffoldError)) {\n        console.error(err instanceof Error ? err.message : String(err));\n      }\n      process.exit(1);\n    }\n  },\n});\n\nexport const dev = defineCommand({\n  meta: {\n    name: 'dev',\n    description: 'Symlink dist/ into Foundry Data and run vite build --watch',\n  },\n  args: {\n    'foundry-data': {\n      type: 'string',\n      alias: 'data-dir',\n      description:\n        'Override the Foundry user-data directory (skips env / config / first-run prompt)',\n    },\n    'hmr-port': {\n      type: 'string',\n      description: 'Port for the hot reload bridge (default 31313)',\n    },\n  },\n  async run({ args }) {\n    // Citty surfaces aliases under the canonical name. Belt-and-suspenders:\n    // accept either spelling so older docs and muscle memory keep working.\n    const explicit =\n      (typeof args['foundry-data'] === 'string' ? args['foundry-data'] : undefined) ??\n      (typeof args['data-dir'] === 'string' ? args['data-dir'] : undefined);\n    // A non-numeric port is the user's typo, not a reason to fall back to a\n    // port they did not ask for — say so and stop.\n    const rawPort = typeof args['hmr-port'] === 'string' ? args['hmr-port'] : undefined;\n    const hmrPort = rawPort === undefined ? undefined : Number(rawPort);\n    if (hmrPort !== undefined && !Number.isInteger(hmrPort)) {\n      console.error(`--hmr-port expects a whole number, got \\`${rawPort}\\`.`);\n      process.exit(1);\n    }\n    try {\n      await runDev({ dataDir: explicit, hmrPort });\n    } catch (err) {\n      console.error(err instanceof Error ? err.message : String(err));\n      process.exit(1);\n    }\n  },\n});\n\nexport const build = defineCommand({\n  meta: {\n    name: 'build',\n    description: 'Run vite build (production) and emit <id>-<version>.zip for foundryvtt.com',\n  },\n  async run() {\n    try {\n      await runBuild();\n    } catch (err) {\n      console.error(err instanceof Error ? err.message : String(err));\n      process.exit(1);\n    }\n  },\n});\n\nexport const audit = defineCommand({\n  meta: {\n    name: 'audit',\n    description: 'Scan a system/module project for the seven v13 manifest + code footguns',\n  },\n  args: {\n    path: {\n      type: 'positional',\n      description: 'Project root to scan (defaults to the current directory)',\n      required: false,\n    },\n    json: {\n      type: 'boolean',\n      default: false,\n      description: 'Emit a machine-readable JSON report instead of markdown',\n    },\n    strict: {\n      type: 'boolean',\n      default: false,\n      description: 'Exit non-zero on any finding (default: only HIGH triggers a non-zero exit)',\n    },\n  },\n  async run({ args }) {\n    try {\n      const result = await runAuditCommand({\n        cwd: typeof args.path === 'string' ? args.path : undefined,\n        format: args.json === true ? 'json' : 'markdown',\n        strict: args.strict === true,\n      });\n      // Set exitCode instead of calling process.exit so any pending stdout\n      // writes (the JSON / markdown report) get flushed before the process\n      // tears down. process.exit(1) would truncate large reports on the\n      // exact runs CI needs them intact.\n      if (result.exitCode !== 0) process.exitCode = result.exitCode;\n    } catch (err) {\n      console.error(err instanceof Error ? err.message : String(err));\n      process.exitCode = 1;\n    }\n  },\n});\n\nexport const main = defineCommand({\n  meta: {\n    name: 'vttforge',\n    version: VTTFORGE_CLI_VERSION,\n    description: 'VTTForge CLI — scaffold, dev, build for Foundry v13+ systems and modules',\n  },\n  subCommands: {\n    init,\n    dev,\n    build,\n    audit,\n  },\n});\n","#!/usr/bin/env node\n/**\n * vttforge bin — the executable entry.\n *\n * Nothing but the launch. The command tree lives in `cli.ts` so tests can\n * import it without running the CLI.\n */\nimport { runMain } from 'citty';\nimport { main } from './cli.js';\n\nrunMain(main);\n"],"mappings":"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"}