@vttforge/cli 0.0.0 → 0.5.1

package/dist/index.d.mts

@@ -0,0 +1,496 @@
+import { ChildProcess } from "node:child_process";
+//#region src/audit/types.d.ts
+/**
+ * Shared types for the `vttforge audit` rule engine.
+ *
+ * The audit catalog covers seven v13 footguns from the VTTForge audit
+ * spec. Each rule produces zero or more `RuleResult` entries; the
+ * orchestrator aggregates them into an `AuditReport` which the reporter
+ * renders as JSON or markdown.
+ *
+ * The CLI never touches the source tree — audit is purely read-only.
+ */
+type Severity = 'HIGH' | 'MEDIUM' | 'LOW';
+interface RuleResult {
+  /** Stable identifier — used by users to suppress / pin / look up specific rules. */
+  ruleId: string;
+  /** Human title. Shown in markdown report headers. */
+  title: string;
+  severity: Severity;
+  /** Absolute or project-relative path of the file the finding refers to. */
+  filePath: string;
+  /** Optional line number (1-based) inside `filePath`. */
+  line?: number;
+  /** One-line description of what was found. */
+  message: string;
+  /** Optional follow-up describing how to fix it. */
+  remediation?: string;
+}
+interface AuditReport {
+  /** Project root the audit ran against. */
+  cwd: string;
+  /** ISO timestamp of when the run started. */
+  startedAt: string;
+  /** Findings, ordered by severity then by ruleId. */
+  findings: ReadonlyArray<RuleResult>;
+  /** Per-severity tallies, for exit-code logic and report headers. */
+  counts: {
+    HIGH: number;
+    MEDIUM: number;
+    LOW: number;
+  };
+}
+/** Severity rank for sorting (HIGH first). */
+declare const SEVERITY_RANK: Record<Severity, number>;
+/**
+ * A rule is a plain function over the project root. Manifest rules parse
+ * `system.json` / `module.json`; source rules walk `scripts/` / `src/`.
+ * Rules return their own findings — the orchestrator stitches them
+ * together. Pure functions over the filesystem so tests inject tmp dirs.
+ */
+type RuleFn = (cwd: string) => Promise<RuleResult[]> | RuleResult[];
+//#endregion
+//#region src/audit/index.d.ts
+interface RunAuditOptions {
+  cwd: string;
+}
+declare function runAudit(options: RunAuditOptions): Promise<AuditReport>;
+//#endregion
+//#region src/audit/manifest-rules.d.ts
+/**
+ * Entry point: run every manifest rule against every manifest at the
+ * project root.
+ */
+declare function runManifestRules(cwd: string): Promise<RuleResult[]>;
+//#endregion
+//#region src/audit/reporter.d.ts
+type ReportFormat = 'json' | 'markdown';
+declare function formatReport(report: AuditReport, format: ReportFormat): string;
+//#endregion
+//#region src/audit/source-rules.d.ts
+/** Entry point: gather everything once, then dispatch to the per-file rules. */
+declare function runSourceRules(cwd: string): Promise<RuleResult[]>;
+//#endregion
+//#region src/commands/audit.d.ts
+interface AuditOptions {
+  /** Project root to scan. Defaults to `process.cwd()`. */
+  cwd?: string;
+  /** Output format. Default: 'markdown'. */
+  format?: ReportFormat;
+  /**
+   * When true, MEDIUM and LOW findings also trigger a non-zero exit.
+   * Default false — HIGH-only is the canonical "block CI" line.
+   */
+  strict?: boolean;
+  /** Custom writer (tests). Defaults to process.stdout.write. */
+  write?: (chunk: string) => void;
+}
+interface AuditResult {
+  report: AuditReport;
+  /** Suggested exit code under the current strictness setting. */
+  exitCode: 0 | 1;
+}
+declare function runAuditCommand(options?: AuditOptions): Promise<AuditResult>;
+//#endregion
+//#region src/manifest.d.ts
+/**
+ * Read a built manifest (`dist/system.json` or `dist/module.json`).
+ *
+ * The vite plugin emits the manifest into `dist/` during build, so the CLI
+ * commands that come after a build (dev's initial symlink, build's release
+ * zip) read from there rather than walking source. This file is intentionally
+ * tiny — we extract just the fields the CLI cares about and surface the
+ * rest as `raw` for any consumer that wants more.
+ */
+type PackageType = 'system' | 'module';
+interface FoundryManifest {
+  /** Manifest id — folder name Foundry serves the package under. */
+  id: string;
+  /** Semver-ish version string from the manifest. */
+  version: string;
+  /** Detected from which filename was present in dist/. */
+  type: PackageType;
+  /** Full parsed JSON for callers that need extra fields (compatibility, etc.). */
+  raw: Record<string, unknown>;
+}
+/**
+ * Locate and parse the Foundry manifest inside the given dist directory.
+ * Prefers `system.json`, falls back to `module.json` (a single dist can't
+ * be both — the vite plugin emits exactly one based on the project type).
+ *
+ * Throws if neither file exists, required fields are missing/non-string,
+ * or the id/version contain characters that would let downstream `join()`
+ * calls escape their intended directory.
+ */
+declare function readManifest(distDir: string): Promise<FoundryManifest>;
+//#endregion
+//#region src/commands/build.d.ts
+interface BuildOptions {
+  /** Override the project root. Defaults to `process.cwd()`. */
+  cwd?: string;
+}
+/**
+ * Internal building block exposed for tests: assumes dist/ is already
+ * populated (vite has run, manifest is present) and just emits the zip.
+ */
+declare function emitReleaseZip(opts: {
+  cwd: string;
+}): Promise<{
+  zipFile: string;
+  byteSize: number;
+  manifest: FoundryManifest;
+}>;
+declare function runBuild(options?: BuildOptions): Promise<void>;
+//#endregion
+//#region src/commands/dev.d.ts
+interface DevOptions {
+  /** Override the project root. Defaults to `process.cwd()`. */
+  cwd?: string;
+  /** `--data-dir` flag value. Skips env/config/prompt lookup when set. */
+  dataDir?: string;
+  /** Port for the hot reload bridge. */
+  hmrPort?: number;
+}
+declare function runDev(options?: DevOptions): Promise<void>;
+/**
+ * Internal building block exposed for tests: given an already-built `dist/`
+ * (vite has run, manifest is present) and a resolved Foundry data dir,
+ * create the symlink and return the target path + manifest. Skips the
+ * vite spawn and the signal-loop, so tests can drive the orchestration
+ * deterministically.
+ */
+declare function setupDevSymlink(opts: {
+  cwd: string;
+  dataRoot: string;
+}): Promise<{
+  target: string;
+  manifest: Awaited<ReturnType<typeof readManifest>>;
+  childProcess?: ChildProcess;
+}>;
+/**
+ * Tear down a dev symlink iff it still points at the expected source.
+ * Refuses to remove a symlink that another `vttforge dev` session (or a
+ * manual `ln -s`) has since redirected — that link doesn't belong to us
+ * and removing it would silently disconnect their setup.
+ */
+declare function cleanupDevSymlink(opts: {
+  target: string;
+  expectedSource: string;
+}): Promise<void>;
+//#endregion
+//#region src/commands/init.d.ts
+/**
+ * `vttforge init` — interactive scaffolder.
+ *
+ * Honors CLI flags first, prompts for everything missing, then copies the
+ * matching template into the destination directory. Optionally `git init`s
+ * and runs the detected package manager's install command at the end.
+ */
+interface InitOptions {
+  name?: string;
+  type?: 'system' | 'module';
+  lang?: 'ts' | 'js';
+  /** Manifest id. Defaults to a slug of the directory name. */
+  id?: string;
+  /** Human-readable title shown in Foundry's setup screens. */
+  title?: string;
+  /** One-line description for the manifest. */
+  description?: string;
+  /** Author name for the manifest. Defaults to the local git author. */
+  author?: string;
+  /** SPDX license id written to package.json. */
+  license?: string;
+  /**
+   * Take the default for anything not supplied instead of asking.
+   *
+   * Required to scaffold without a terminal — a prompt with nothing to read
+   * from waits forever, which is no way to fail.
+   */
+  yes?: boolean;
+  noInstall?: boolean;
+  noGit?: boolean;
+  /** Override the working directory (test hook). Defaults to `process.cwd()`. */
+  cwd?: string;
+}
+interface ResolvedInitOptions extends Required<Omit<InitOptions, 'cwd' | 'id' | 'title' | 'description' | 'author' | 'license' | 'yes'>> {
+  cwd: string;
+  dest: string;
+  id: string;
+  title: string;
+  description: string;
+  author: string;
+  license: string;
+  foundryMinVersion: string;
+  foundryVerifiedVersion: string;
+  templateVariant: TemplateVariant;
+}
+type TemplateVariant = 'system-ts' | 'system-js' | 'module-ts' | 'module-js';
+/**
+ * Thrown when the scaffolder cannot continue — bad input, an existing
+ * destination, a cancelled prompt, etc. `runInit` propagates these instead
+ * of calling `process.exit`, so library consumers (tests, other CLIs) can
+ * catch and recover. The `vttforge` bin wraps `runInit` in a top-level
+ * handler that prints the message and exits with code 1.
+ */
+declare class ScaffoldError extends Error {
+  constructor(message: string);
+}
+declare function runInit(options?: InitOptions): Promise<void>;
+//#endregion
+//#region src/foundry-data-dir.d.ts
+/**
+ * Foundry user-data directory discovery + persistence.
+ *
+ * Foundry stores worlds, systems, and modules under a single user-data
+ * directory (`Data/` lives at its root). `vttforge dev` needs to know where
+ * that is so it can symlink the built `dist/` into `Data/systems/<id>/` or
+ * `Data/modules/<id>/` and let Foundry pick it up.
+ *
+ * Precedence (top wins):
+ *   1. Explicit `--data-dir` flag passed to the command
+ *   2. `FOUNDRY_DATA_DIR` env var (useful in Docker/CI)
+ *   3. `<project>/.vttforge/config.json :: foundryDataDir`
+ *   4. OS default + interactive prompt that saves to (3) for next time
+ *
+ * The OS-default detection treats `XDG_DATA_HOME` (Linux) and `%LOCALAPPDATA%`
+ * (Windows) as part of the OS convention, not as Foundry-specific overrides.
+ *
+ * Everything here is pure — `platform`, `env`, and `home` flow through
+ * options so tests can drive every branch without monkey-patching globals.
+ */
+/** Shape persisted to `<project>/.vttforge/config.json`. */
+interface VTTForgeConfig {
+  foundryDataDir?: string;
+}
+/**
+ * Return the OS-default Foundry user-data directory, or `null` on unknown
+ * platforms / missing platform-specific env vars. Does NOT check existence —
+ * callers prompt the user when the suggested path doesn't resolve.
+ */
+declare function autoDetectFoundryDataDir(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv, home?: string): string | null;
+/**
+ * Heuristic: a path looks like a Foundry user-data root if it contains a
+ * `Data/` subdirectory (canonical Foundry layout) OR if it already contains
+ * `systems/` or `modules/` (the path is already the Data folder itself).
+ */
+declare function looksLikeFoundryDataDir(path: string): boolean;
+/** Absolute path to the project-local config file (whether or not it exists). */
+declare function configPath(cwd: string): string;
+/** Load `<cwd>/.vttforge/config.json` if it exists and is valid JSON. */
+declare function loadConfig(cwd: string): Promise<VTTForgeConfig | null>;
+/** Persist `<cwd>/.vttforge/config.json`. Creates the `.vttforge/` dir as needed. */
+declare function saveConfig(cwd: string, config: VTTForgeConfig): Promise<void>;
+/**
+ * Resolve the packages directory (`Data/systems/` or `Data/modules/`) under
+ * the given Foundry user-data root. Accepts the path Foundry itself runs
+ * with (the user-data folder, which contains `Data/`) OR the `Data/` folder
+ * directly — both are common in muscle memory.
+ *
+ * The returned path is not guaranteed to exist yet; callers `mkdir -p` it
+ * before creating the symlink.
+ */
+declare function foundryPackagesDir(dataRoot: string, type: 'system' | 'module'): string;
+interface ResolveDataDirOptions {
+  /** Project root — also where `.vttforge/config.json` is read/written. */
+  cwd: string;
+  /** `--data-dir` flag value. Skips persistence and prompting when present. */
+  override?: string;
+  /**
+   * Interactive prompt for the first run. Receives the OS-default path
+   * (may be `null` on unknown platforms) and resolves with the chosen path,
+   * or `null` if the user cancelled. When undefined, the function refuses
+   * to ask and throws — appropriate for non-TTY contexts (CI, scripts).
+   */
+  prompt?: (autoDetected: string | null) => Promise<string | null>;
+  /** Override `process.platform` (tests). */
+  platform?: NodeJS.Platform;
+  /** Override `process.env` (tests). */
+  env?: NodeJS.ProcessEnv;
+  /** Override `os.homedir()` (tests). */
+  home?: string;
+}
+/**
+ * Walk the precedence chain and return the chosen Foundry user-data path.
+ * Saves the user's choice to the project config on first interactive run so
+ * subsequent invocations skip the prompt.
+ */
+declare function resolveFoundryDataDir(opts: ResolveDataDirOptions): Promise<string>;
+//#endregion
+//#region src/package-manager.d.ts
+/**
+ * Detect which package manager invoked the CLI so we can run the right
+ * `install` command after scaffolding.
+ *
+ * Strategy: read `npm_config_user_agent`, which pnpm/npm/bun/yarn all set when
+ * they spawn a child process (including `pnpm dlx`, `pnpm create`, etc.).
+ * Falls back to `pnpm` because that's the VTTForge house default and the
+ * most common Foundry-developer choice — but any concrete signal in the
+ * environment wins over the default.
+ */
+type PackageManager = 'pnpm' | 'npm' | 'bun' | 'yarn';
+declare function detectPackageManager(env?: NodeJS.ProcessEnv): PackageManager;
+declare function installCommand(pm: PackageManager): string;
+/**
+ * Detect a project's package manager by looking at which lockfile it
+ * ships. `dev` and `build` need this — by the time the user runs
+ * `vttforge dev`, npm_config_user_agent reflects whatever shell launched
+ * the binary (often nothing in a global install), not how the project
+ * was bootstrapped. The lockfile is the project's own contract.
+ *
+ * Falls back to {@link detectPackageManager} for fresh checkouts that
+ * haven't been installed yet.
+ */
+declare function detectProjectPackageManager(cwd: string, env?: NodeJS.ProcessEnv): PackageManager;
+/**
+ * Argument vector to invoke `vite` (or any other locally-installed CLI)
+ * via the project's package manager. We always shell out through `<pm>
+ * exec` so the call works regardless of the linker's choices — Yarn 4
+ * Plug'n'Play, pnpm's symlinked layout, npm's flattened node_modules,
+ * Bun's symlinked node_modules. Each manager exposes a uniform "run a
+ * locally-resolved binary in the project's dependency graph" command.
+ */
+declare function execInvocation(pm: PackageManager, bin: string): [string, string[]];
+//#endregion
+//#region src/scaffold.d.ts
+/**
+ * Template copy with `{{var}}` placeholder substitution.
+ *
+ * Templates live under `packages/cli/templates/<variant>/` and are shipped
+ * inside the published tarball (see the `files` array in package.json).
+ * Each file is read, substituted, and written to the destination directory
+ * preserving the relative path. Directories are created lazily on first
+ * write.
+ *
+ * We intentionally avoid Handlebars or any other template engine — the
+ * substitution surface is small (a flat string-to-string map), and bundling
+ * a dependency for ten lines of regex would be wasteful in a tool whose
+ * value is being fast to invoke.
+ */
+interface ScaffoldVars {
+  ID: string;
+  TITLE: string;
+  DESCRIPTION: string;
+  AUTHOR: string;
+  LICENSE: string;
+  FOUNDRY_MIN_VERSION: string;
+  FOUNDRY_VERIFIED_VERSION: string;
+  LOCALE_PREFIX: string;
+  YEAR: string;
+}
+interface ScaffoldOptions {
+  /** Absolute path to the template root (e.g. `<cli-pkg>/templates/system-ts`). */
+  templateDir: string;
+  /** Absolute path to the destination directory. Created if it doesn't exist. */
+  destDir: string;
+  /** Variables to substitute into `{{NAME}}` placeholders inside template files. */
+  vars: ScaffoldVars;
+}
+/**
+ * Replace `{{NAME}}` placeholders in `content` using the `vars` map.
+ * Unknown placeholders are passed through unchanged so partially-templated
+ * files (e.g. a snippet that contains `{{handlebarsLikeSyntax}}` as literal
+ * content) still scaffold without surprises.
+ */
+declare function substitute(content: string, vars: ScaffoldVars): string;
+declare function scaffold({ templateDir, destDir, vars }: ScaffoldOptions): Promise<void>;
+/**
+ * Resolve the templates directory relative to this module's file URL. tsdown
+ * emits `dist/scaffold.mjs`, so `import.meta.url` points there at runtime;
+ * we walk up two segments to land at the package root, then descend into
+ * `templates/`.
+ */
+declare function templatesRoot(): string;
+//#endregion
+//#region src/symlink.d.ts
+/**
+ * Cross-platform symlink helpers for `vttforge dev`.
+ *
+ * The dev loop drops a symlink from Foundry's `Data/<systems|modules>/<id>/`
+ * back to the project's `dist/` so Foundry serves freshly-built files as
+ * vite writes them. The win32 path matters: with `type: 'junction'` the
+ * operation works on standard Windows shells without Developer Mode, while
+ * `type: 'dir'` requires admin. We never silently fall back to copying —
+ * Foundry's HMR relies on live file mutation, and a copy snapshot defeats
+ * the loop. If the symlink fails, we surface the platform-specific fix.
+ */
+interface CreateLinkOptions {
+  /**
+   * Overwrite an existing symlink that points elsewhere. Real files and
+   * directories are never overwritten — that path needs explicit user
+   * action outside the tool.
+   */
+  overwrite?: boolean;
+}
+/**
+ * Read a symlink target. Returns the absolute path the link points at, or
+ * `null` if `path` doesn't exist or isn't a symlink. Relative symlink
+ * targets are resolved against the link's own directory (matches the
+ * semantics callers expect when comparing to a known absolute source).
+ */
+declare function readLinkTarget(path: string): Promise<string | null>;
+/**
+ * Create a symlink at `target` pointing to `source`. Win32 uses `'junction'`
+ * so the call succeeds without elevation; everywhere else uses `'dir'`.
+ *
+ * Idempotency:
+ *   - target already points to source → no-op
+ *   - target points elsewhere → throws unless `options.overwrite`
+ *   - target is a real file/dir → throws unconditionally
+ */
+declare function createLink(target: string, source: string, options?: CreateLinkOptions): Promise<void>;
+/**
+ * Remove a symlink at `path`. No-ops when the path doesn't exist. Throws
+ * when the path exists but isn't a symlink — we never unlink real files
+ * or directories.
+ */
+declare function removeLink(path: string): Promise<void>;
+//#endregion
+//#region src/vite-runner.d.ts
+declare class ViteNotInstalledError extends Error {
+  constructor(message: string);
+}
+/** Spawn args for invoking the user's vite (e.g. `["pnpm", ["exec", "vite"]]`). */
+declare function resolveViteInvocation(cwd: string): [string, string[]];
+/** Run `vite build` once and wait for it to exit. Throws on non-zero exit. */
+declare function runViteBuildOnce(cwd: string): Promise<void>;
+/**
+ * Spawn `vite build --watch` and return the child process. The caller is
+ * responsible for waiting on it and tearing it down (the dev command kills
+ * it on SIGINT).
+ */
+declare function spawnViteWatch(cwd: string): ChildProcess;
+//#endregion
+//#region src/zip.d.ts
+/**
+ * Emit a foundryvtt.com-compatible release zip.
+ *
+ * foundryvtt.com expects the package contents at the zip root (no wrapper
+ * folder), so `unzip release.zip` produces `system.json`, `scripts/`, etc.
+ * directly. The vite build output already matches that layout, so we feed
+ * `dist/` straight into archiver with `false` as the second arg to disable
+ * the wrap-with-source-dir-name default.
+ *
+ * Optional extras (LICENSE / README / CHANGELOG) ride along when present at
+ * the project root and not already inside `dist/`. We never duplicate.
+ */
+interface EmitZipOptions {
+  /** Directory whose contents go into the zip at root. */
+  sourceDir: string;
+  /** Output zip path. Parent directory must exist. */
+  outFile: string;
+  /** Filenames (relative to extrasFrom) to add at the zip root if present. */
+  extras?: string[];
+  /** Where to look for `extras`. Required when `extras` is non-empty. */
+  extrasFrom?: string;
+}
+interface EmitZipResult {
+  outFile: string;
+  byteSize: number;
+}
+declare function emitZip(opts: EmitZipOptions): Promise<EmitZipResult>;
+//#endregion
+//#region src/index.d.ts
+declare const VTTFORGE_CLI_VERSION = "0.1.0";
+//#endregion
+export { type AuditOptions, type AuditReport, type AuditResult, type BuildOptions, type CreateLinkOptions, type DevOptions, type EmitZipOptions, type EmitZipResult, type FoundryManifest, type InitOptions, type PackageManager, type PackageType, type ReportFormat, type ResolveDataDirOptions, type ResolvedInitOptions, type RuleFn, type RuleResult, SEVERITY_RANK, ScaffoldError, type ScaffoldOptions, type ScaffoldVars, type Severity, type TemplateVariant, VTTFORGE_CLI_VERSION, type VTTForgeConfig, ViteNotInstalledError, autoDetectFoundryDataDir, cleanupDevSymlink, configPath, createLink, detectPackageManager, detectProjectPackageManager, emitReleaseZip, emitZip, execInvocation, formatReport, foundryPackagesDir, installCommand, loadConfig, looksLikeFoundryDataDir, readLinkTarget, readManifest, removeLink, resolveFoundryDataDir, resolveViteInvocation, runAudit, runAuditCommand, runBuild, runDev, runInit, runManifestRules, runSourceRules, runViteBuildOnce, saveConfig, scaffold, setupDevSymlink, spawnViteWatch, substitute, templatesRoot };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { A as installCommand, C as ViteNotInstalledError, D as detectPackageManager, E as spawnViteWatch, F as SEVERITY_RANK, I as runSourceRules, L as runManifestRules, M as runAuditCommand, N as formatReport, O as detectProjectPackageManager, P as runAudit, S as emitZip, T as runViteBuildOnce, _ as createLink, a as substitute, b as emitReleaseZip, c as runDev, d as configPath, f as foundryPackagesDir, g as saveConfig, h as resolveFoundryDataDir, i as scaffold, j as readManifest, k as execInvocation, l as setupDevSymlink, m as looksLikeFoundryDataDir, n as ScaffoldError, o as templatesRoot, p as loadConfig, r as runInit, s as cleanupDevSymlink, t as VTTFORGE_CLI_VERSION, u as autoDetectFoundryDataDir, v as readLinkTarget, w as resolveViteInvocation, x as runBuild, y as removeLink } from "./src-CWhUNM__.mjs";
+export { SEVERITY_RANK, ScaffoldError, VTTFORGE_CLI_VERSION, ViteNotInstalledError, autoDetectFoundryDataDir, cleanupDevSymlink, configPath, createLink, detectPackageManager, detectProjectPackageManager, emitReleaseZip, emitZip, execInvocation, formatReport, foundryPackagesDir, installCommand, loadConfig, looksLikeFoundryDataDir, readLinkTarget, readManifest, removeLink, resolveFoundryDataDir, resolveViteInvocation, runAudit, runAuditCommand, runBuild, runDev, runInit, runManifestRules, runSourceRules, runViteBuildOnce, saveConfig, scaffold, setupDevSymlink, spawnViteWatch, substitute, templatesRoot };