@heroiclands/package-build 0.1.0

package/types/bundle.d.mts

@@ -0,0 +1,60 @@
+/**
+ * The names a top-level statement would declare in global scope.
+ *
+ * Only declaration forms matter: an expression statement or a call declares
+ * nothing. Destructuring patterns are walked, so `const { a, b } = …` reports
+ * both names — a bundler emits those routinely, and missing them would let the
+ * check pass a bundle that does collide.
+ *
+ * @param {object} node - A top-level `Program.body` entry.
+ * @returns {string[]} Declared identifier names, empty when it declares none.
+ */
+export function declaredGlobals(node: object): string[];
+/**
+ * How a manifest declares an entry file.
+ *
+ * @param {object} manifest - The parsed manifest.
+ * @param {string} entry - The entry file's name, as the manifest spells it.
+ * @returns {"esmodules"|"scripts"|"both"|"neither"} Where it is declared.
+ */
+export function entryDeclaration(manifest: object, entry: string): "esmodules" | "scripts" | "both" | "neither";
+/**
+ * Every top-level declaration a source would create in global scope.
+ *
+ * Parses as a **classic script**, which is the only parse under which the
+ * question means anything.
+ *
+ * @param {string} source - The bundle's source text.
+ * @returns {Array<{name: string, line: number, kind: string}>} The declarations.
+ * @throws {SyntaxError} When the source does not parse as a script.
+ */
+export function globalDeclarations(source: string): Array<{
+    name: string;
+    line: number;
+    kind: string;
+}>;
+/**
+ * Check that a manifest and the bundle it points at agree.
+ *
+ * @param {object} opts
+ * @param {object} opts.manifest - The parsed manifest.
+ * @param {string} opts.source - The bundle's source text.
+ * @param {string} opts.entry - The entry file's name, as the manifest spells it.
+ * @param {string} [opts.manifestName] - What to call the manifest in a message.
+ * @returns {{findings: Array<{line?: number, severity: "error", message: string}>,
+ *   declaredAs: "esmodules"|"scripts"|"both"|"neither"}} The findings, empty
+ *   when the two agree, and how the entry was declared.
+ */
+export function checkBundleLoading({ manifest, source, entry, manifestName, }: {
+    manifest: object;
+    source: string;
+    entry: string;
+    manifestName?: string | undefined;
+}): {
+    findings: Array<{
+        line?: number;
+        severity: "error";
+        message: string;
+    }>;
+    declaredAs: "esmodules" | "scripts" | "both" | "neither";
+};

package/types/deploy.d.mts

@@ -0,0 +1,148 @@
+/**
+ * Normalise a stage argument.
+ *
+ * @param {unknown} stageArg - Whatever the caller was given.
+ * @returns {string} The trimmed, lowercased stage name, `""` when absent.
+ */
+export function resolveStage(stageArg: unknown): string;
+/**
+ * Where a package installs beneath a Foundry data root.
+ *
+ * Foundry keeps systems and modules in sibling trees under `Data`, and the leaf
+ * is the package id — the same id the manifest declares and every compendium
+ * UUID starts with. Deriving it here is what lets one deploy serve a system and
+ * a module without either naming its own path.
+ *
+ * @param {"systems"|"modules"} packageKind - Which tree it installs into.
+ * @param {string} packageId - The Foundry package id.
+ * @returns {string[]} Path segments beneath the data root.
+ */
+export function packageSubpath(packageKind: "systems" | "modules", packageId: string): string[];
+/**
+ * Whether a destination names a remote host rather than a local directory.
+ *
+ * A remote target is `[user@]host:/path`. The colon is what distinguishes it —
+ * **except on Windows, where `C:\Foundry\Data` also has one**. A bare drive
+ * letter followed by a separator is therefore read as local; without that, a
+ * Windows developer's perfectly ordinary path is parsed as a host called `C`
+ * and the deploy fails trying to open an SSH connection to it.
+ *
+ * @param {string} target - The configured destination.
+ * @returns {boolean} True when it should be deployed over SFTP.
+ */
+export function isRemoteTarget(target: string): boolean;
+/**
+ * Parse a `[user@]host:/path` remote target into its parts.
+ *
+ * @param {string} target - The remote destination.
+ * @returns {{username: string|undefined, host: string, remotePath: string}}
+ */
+export function parseRemote(target: string): {
+    username: string | undefined;
+    host: string;
+    remotePath: string;
+};
+/**
+ * Locate the SSH agent endpoint, cross-platform.
+ *
+ * Precedence: an explicit per-stage override (use `"pageant"` for PuTTY, or a
+ * named-pipe path), then `$SSH_AUTH_SOCK`, then the Windows OpenSSH agent's
+ * default named pipe. `undefined` when no agent is available, at which point a
+ * caller falls back to a key file.
+ *
+ * @param {NodeJS.ProcessEnv} env - The environment to read.
+ * @param {string} stageUpper - Uppercased stage name, e.g. `"QA"`.
+ * @param {string} [prefix] - Fallback variable prefix for a shared override.
+ * @returns {string|undefined} The agent endpoint.
+ */
+export function resolveAgent(env: NodeJS.ProcessEnv, stageUpper: string, prefix?: string): string | undefined;
+/**
+ * Assemble an `ssh2-sftp-client` connection config for a stage.
+ *
+ * Defaults to the SSH agent so no secret is read from disk. An explicit key
+ * *path* — not a secret — is the escape hatch; no passphrase or password is
+ * read from the environment, deliberately, so none ends up in a `.env` file.
+ *
+ * @param {string} stageUpper - Uppercased stage name, e.g. `"QA"`.
+ * @param {{username: string|undefined, host: string}} remote - Parsed target.
+ * @param {object} [opts]
+ * @param {NodeJS.ProcessEnv} [opts.env] - The environment to read.
+ * @param {string} [opts.prefix] - Fallback variable prefix.
+ * @returns {Promise<object>} The connection config.
+ */
+export function buildConnection(stageUpper: string, remote: {
+    username: string | undefined;
+    host: string;
+}, { env, prefix }?: {
+    env?: NodeJS.ProcessEnv | undefined;
+    prefix?: string | undefined;
+}): Promise<object>;
+/**
+ * Mirror the staged build into a local directory via a staged, atomic swap.
+ *
+ * The live destination is never mutated in place — see the module header for
+ * why that matters under a running server.
+ *
+ * @param {string} srcAbs - The staged tree.
+ * @param {string} destDir - Where the package installs.
+ * @returns {Promise<void>}
+ */
+export function deployLocal(srcAbs: string, destDir: string): Promise<void>;
+/**
+ * Mirror the staged build into a remote directory over SFTP, with the same
+ * staged swap {@link deployLocal} performs.
+ *
+ * `ssh2-sftp-client` is imported here rather than at module scope so that the
+ * pure helpers above — and a local deploy — cost nothing to import.
+ *
+ * @param {object} conn - Connection config from {@link buildConnection}.
+ * @param {string} srcAbs - The staged tree.
+ * @param {string} remoteDir - Where the package installs on the host.
+ * @param {object} [opts]
+ * @param {(uploaded: string) => void} [opts.onUpload] - Per-file progress.
+ * @returns {Promise<void>}
+ */
+export function deployRemote(conn: object, srcAbs: string, remoteDir: string, { onUpload }?: {
+    onUpload?: ((uploaded: string) => void) | undefined;
+}): Promise<void>;
+/**
+ * Deploy a staged package to one stage, choosing the transport from the
+ * configured destination.
+ *
+ * @param {object} opts
+ * @param {string} opts.stage - `dev` / `qa` / `prod` / `test`.
+ * @param {string} opts.source - The staged tree.
+ * @param {"systems"|"modules"} opts.packageKind - Which Foundry tree.
+ * @param {string} opts.packageId - The Foundry package id.
+ * @param {NodeJS.ProcessEnv} [opts.env] - The environment to read.
+ * @param {string} [opts.prefix] - Fallback variable prefix for SFTP overrides.
+ * @param {(message: string) => void} [opts.log] - Progress reporting.
+ * @returns {Promise<{stage: string, destination: string, remote: boolean}>}
+ * @throws {Error} On an unknown stage, or one with no destination configured.
+ */
+export function deployStage({ stage, source, packageKind, packageId, env, prefix, log, }: {
+    stage: string;
+    source: string;
+    packageKind: "systems" | "modules";
+    packageId: string;
+    env?: NodeJS.ProcessEnv | undefined;
+    prefix?: string | undefined;
+    log?: ((message: string) => void) | undefined;
+}): Promise<{
+    stage: string;
+    destination: string;
+    remote: boolean;
+}>;
+/**
+ * The environment variable naming each stage's Foundry data root.
+ *
+ * The set is a shared convention rather than one repository's: every
+ * HeroicLands package deploys to the same four stages, and a `test` root is
+ * what the end-to-end harness seeds its throwaway world into.
+ */
+export const STAGE_ENV_MAP: Readonly<{
+    dev: "FOUNDRYVTT_DEV_DATA";
+    qa: "FOUNDRYVTT_QA_DATA";
+    prod: "FOUNDRYVTT_PROD_DATA";
+    test: "FOUNDRYVTT_TEST_DATA";
+}>;

package/types/index.d.mts

@@ -0,0 +1,7 @@
+export * as manifest from "./manifest.mjs";
+export * as bundle from "./bundle.mjs";
+export * as stage from "./stage.mjs";
+export * as release from "./release.mjs";
+export * as deploy from "./deploy.mjs";
+export * as lang from "./lang.mjs";
+export * as text from "./text.mjs";

package/types/lang.d.mts

@@ -0,0 +1,44 @@
+/**
+ * Every `[prefixKey, leafKey]` pair where `prefixKey` is a strict dotted prefix
+ * of `leafKey` and both are present as keys — the exact shape that makes
+ * `foundry.utils.expandObject` throw.
+ *
+ * @param {Record<string, unknown>} json - The parsed, flat localization object.
+ * @returns {[string, string][]} The colliding `[prefix, leaf]` pairs.
+ */
+export function findPrefixCollisions(json: Record<string, unknown>): [string, string][];
+/**
+ * Validate one localization file's source text.
+ *
+ * Findings are returned in file order where a position is known, so a caller
+ * that prints them walks the file top to bottom.
+ *
+ * @param {string} raw - The file's contents.
+ * @returns {LangFinding[]} Every finding, empty when the file is shippable.
+ */
+export function validateLangSource(raw: string): LangFinding[];
+/**
+ * A single finding, in the fields the shared diagnostic format takes.
+ *
+ * `file` is deliberately absent: these functions are handed source text, not a
+ * path, so the caller — which knows where the text came from — supplies it.
+ */
+export type LangFinding = {
+    /**
+     * - 1-based line, omitted when it cannot be
+     * established honestly.
+     */
+    line?: number | undefined;
+    /**
+     * - 1-based column, omitted likewise.
+     */
+    column?: number | undefined;
+    /**
+     * - How the finding should be treated.
+     */
+    severity: "error" | "warning";
+    /**
+     * - What is wrong, in one sentence.
+     */
+    message: string;
+};

package/types/manifest.d.mts

@@ -0,0 +1,122 @@
+/**
+ * Which artifact a template file builds.
+ *
+ * Inferred from the template's own name so the usual case takes no
+ * configuration: a repository that ships `system.template.json` is a system,
+ * and one that ships `module.template.json` is a module. That is the same pair
+ * `@heroiclands/content-build` resolves a package manifest from, so the two
+ * cannot disagree about what a repository is.
+ *
+ * @param {string} templatePath - Path to the manifest template.
+ * @returns {"system"|"module"} The artifact name.
+ * @throws {TypeError} When the name identifies neither kind — a template called
+ *   something else leaves nothing to infer from, and guessing would silently
+ *   emit a manifest Foundry never looks for.
+ */
+export function artifactFromTemplate(templatePath: string): "system" | "module";
+/**
+ * The repository's web address, from whatever spelling `package.json` carries.
+ *
+ * npm accepts several: a plain `https://` URL, the `git+https://…​.git` form npm
+ * itself writes, and a trailing slash either way. Foundry fetches
+ * `<url>/releases/latest/download/<artifact>.json` literally, so a `git+` prefix
+ * or a `.git` suffix left in place yields a 404 on every update check — with no
+ * error anywhere, because nothing fetches that URL until a user's Foundry does.
+ * `sohl-kethira-basic` declares the `git+…​.git` form today.
+ *
+ * @param {string|{url?: string}} repository - `package.json`'s `repository`
+ *   field, in either object or shorthand-string form.
+ * @returns {string} The normalised `https://` URL, with no trailing slash.
+ * @throws {TypeError} When no URL can be read. A manifest with no addresses is
+ *   worse than a missing one: Foundry installs it and never offers an update.
+ */
+export function normalizeRepoUrl(repository: string | {
+    url?: string;
+}): string;
+/**
+ * The four addresses a Foundry manifest advertises.
+ *
+ * `manifest` deliberately points at **`releases/latest`** rather than at this
+ * version: it is the URL an *installed* package re-fetches to discover that a
+ * newer one exists, so pinning it to the version being built would freeze every
+ * install at that release forever. `download` points at this exact version,
+ * because that is the archive this manifest describes.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoUrl - Normalised repository URL.
+ * @param {string} opts.version - The version being built.
+ * @param {"system"|"module"} opts.artifact - Which artifact is shipped.
+ * @returns {{url: string, bugs: string, manifest: string, download: string}}
+ */
+export function releaseUrls({ repoUrl, version, artifact }: {
+    repoUrl: string;
+    version: string;
+    artifact: "system" | "module";
+}): {
+    url: string;
+    bugs: string;
+    manifest: string;
+    download: string;
+};
+/**
+ * Stamp a manifest template with the facts that must not be transcribed.
+ *
+ * Pure: the template is not mutated, and the result is a new object.
+ *
+ * `flags` is merged **per namespace**, not wholesale, so a template may carry
+ * its own keys under the same namespace and keep them. A caller supplies
+ * whatever its package needs there — the credits journal's UUID, the settings
+ * sidebar's links — because those are facts about one package, not about being
+ * a Foundry package.
+ *
+ * @param {object} template - The parsed manifest template.
+ * @param {object} opts
+ * @param {string} opts.version - The version being built.
+ * @param {string} opts.repoUrl - Normalised repository URL.
+ * @param {"system"|"module"} opts.artifact - Which artifact is shipped.
+ * @param {Record<string, object>} [opts.flags] - Namespaced flags to merge.
+ * @returns {object} The stamped manifest.
+ */
+export function stampManifest(template: object, { version, repoUrl, artifact, flags }: {
+    version: string;
+    repoUrl: string;
+    artifact: "system" | "module";
+    flags?: Record<string, object> | undefined;
+}): object;
+/**
+ * Read a manifest template, stamp it, and write the result into the stage.
+ *
+ * The only export here that touches disk. Everything it decides is decided by
+ * the pure functions above, so the rules stay testable without a filesystem.
+ *
+ * @param {object} opts
+ * @param {string} opts.templatePath - The manifest template to read.
+ * @param {object} opts.packageJson - The parsed `package.json`, which owns the
+ *   version and the repository address.
+ * @param {string} opts.outDir - Directory to write the manifest into, created
+ *   if absent.
+ * @param {"system"|"module"} [opts.artifact] - Overrides the artifact inferred
+ *   from the template's name.
+ * @param {Record<string, object>} [opts.flags] - Namespaced flags to merge.
+ * @returns {Promise<{path: string, manifest: object}>} Where it was written,
+ *   and what was written.
+ */
+export function writeFoundryManifest({ templatePath, packageJson, outDir, artifact, flags, }: {
+    templatePath: string;
+    packageJson: object;
+    outDir: string;
+    artifact?: "module" | "system" | undefined;
+    flags?: Record<string, object> | undefined;
+}): Promise<{
+    path: string;
+    manifest: object;
+}>;
+/**
+ * The two package kinds Foundry defines, as the artifact name each one's
+ * manifest and release archive are called.
+ *
+ * A system ships `system.json` / `system.zip`; a module ships `module.json` /
+ * `module.zip`. Foundry fetches those exact names, so the pair is not a naming
+ * convention this project is free to choose.
+ */
+export const ARTIFACTS: readonly string[];

package/types/release.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Zip the staged tree and place the manifest beside the archive.
+ *
+ * **Waits for the output stream to close, not merely for the archive to
+ * finalize.** `finalize()` resolves once archiver has finished *appending*
+ * entries, which is before the bytes have necessarily reached disk; returning
+ * there can hand a later step — an upload, a checksum — a truncated file. The
+ * failure is timing-dependent, so it survives every run that happens to be
+ * fast enough, which is what makes it worth being explicit about.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.stageDir] - The staged package tree.
+ * @param {string} [opts.outDir] - Where the release assets are written.
+ * @param {"system"|"module"} [opts.artifact] - Which artifact is shipped.
+ *   Determines both asset names.
+ * @returns {Promise<{zip: string, manifest: string, bytes: number,
+ *   version: string}>} The two paths written, the archive's size, and the
+ *   version the manifest declares.
+ * @throws {Error} When the stage has no manifest — there is nothing to release,
+ *   and an archive without one installs as nothing.
+ */
+export function packRelease({ stageDir, outDir, artifact, }?: {
+    stageDir?: string | undefined;
+    outDir?: string | undefined;
+    artifact?: "module" | "system" | undefined;
+}): Promise<{
+    zip: string;
+    manifest: string;
+    bytes: number;
+    version: string;
+}>;

package/types/stage.d.mts

@@ -0,0 +1,84 @@
+/**
+ * A source that does not exist, described for a human.
+ *
+ * Pure, and separate from the copying, so the whole list is reported at once.
+ * Discovering missing sources one exception at a time means one fix, one
+ * rebuild, one more exception.
+ *
+ * @param {ReadonlyArray<readonly [string, string]>} entries - `[source, dest]`
+ *   pairs, sources relative to `cwd` or absolute.
+ * @param {string} [cwd] - Resolved against this. Defaults to the process cwd.
+ * @returns {string[]} Every source that is absent, in the order listed.
+ */
+export function missingSources(entries: ReadonlyArray<readonly [string, string]>, cwd?: string): string[];
+/**
+ * Recursively copy `src` to `dest`.
+ *
+ * `transform(sourcePath)` may return a string to write **instead of** a byte
+ * copy; returning `null` or `undefined` falls back to copying the bytes. That
+ * is what lets a repository theme its icons, rewrite a config, or stamp a file
+ * as it stages it, without this function knowing anything about why.
+ *
+ * @param {string} src - Source file or directory.
+ * @param {string} dest - Destination path.
+ * @param {object} [opts]
+ * @param {(sourcePath: string) => string|null|undefined} [opts.transform] -
+ *   Per-file transform.
+ * @returns {number} How many files were written.
+ */
+export function copyTree(src: string, dest: string, { transform }?: {
+    transform?: ((sourcePath: string) => string | null | undefined) | undefined;
+}): number;
+/**
+ * Copy every listed source into the stage, refusing to start if any is absent.
+ *
+ * **The guard is the point.** A listed path that does not exist is an error,
+ * not a silent skip: a missing `lang/` ships a package with no localization and
+ * nothing said so, and a missing `templates/` ships one whose every sheet fails
+ * to render. Both are indistinguishable from a successful build in the log.
+ *
+ * The check runs over the whole list *before* anything is copied, so a bad list
+ * leaves no half-populated stage behind.
+ *
+ * @param {ReadonlyArray<readonly [string, string]>} entries - `[source, dest]`
+ *   pairs.
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] - Sources and destinations resolve against this.
+ * @param {(sourcePath: string) => string|null|undefined} [opts.transform] -
+ *   Per-file transform, applied to every entry.
+ * @returns {{entries: number, files: number}} What was staged.
+ * @throws {Error} When any source is missing, naming all of them.
+ */
+export function stageAssets(entries: ReadonlyArray<readonly [string, string]>, { cwd, transform }?: {
+    cwd?: string | undefined;
+    transform?: ((sourcePath: string) => string | null | undefined) | undefined;
+}): {
+    entries: number;
+    files: number;
+};
+/**
+ * Remove the build artefacts a repository regenerates.
+ *
+ * A directory that is already gone is not an error — the command has to be safe
+ * to run repeatedly, and "clean when already clean" is the ordinary case.
+ *
+ * @param {string} root - Repository root; every directory resolves against it.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.extra] - Directories beyond
+ *   {@link BUILD_ARTIFACT_DIRS} that this repository also regenerates.
+ * @param {boolean} [opts.includeNodeModules] - Also remove `node_modules`, the
+ *   `distclean` case.
+ * @returns {string[]} The directories removed, as listed.
+ */
+export function cleanBuildArtifacts(root: string, { extra, includeNodeModules }?: {
+    extra?: readonly string[] | undefined;
+    includeNodeModules?: boolean | undefined;
+}): string[];
+/**
+ * Directories every HeroicLands repository regenerates and none commits.
+ *
+ * A repository adds its own — `sohl-thalorna` also clears the Hugo output
+ * beneath `site/` — but these four are common to all of them because they come
+ * from the shared toolchain rather than from any one package's layout.
+ */
+export const BUILD_ARTIFACT_DIRS: readonly string[];

package/types/text.d.mts

@@ -0,0 +1,51 @@
+/**
+ * Locating a literal inside an arbitrary text file.
+ *
+ * A build check reports a **finding**, and a finding is only actionable if it
+ * says where it is (#1668). Most findings are *about* a string the check
+ * matched — a key, a marker, a caption — so its position is one string search
+ * away, and making that search is the difference between a finding that can be
+ * opened and one that has to be hunted for.
+ *
+ * `@heroiclands/content-build` owns the diagnostic **format**, and its
+ * `positionInBody` maps an offset within a parsed content note back to its
+ * file. That is a different job: the checks here read localization files,
+ * manifests, source and bundles — none of which are notes. So this module
+ * carries the generic operation, and nothing carries it twice.
+ *
+ * Plain ESM with no filesystem access, so it is unit-testable.
+ *
+ * @module
+ */
+/**
+ * Where a literal sits in a text.
+ *
+ * @param {string} text - The file's contents.
+ * @param {string} needle - The literal to locate.
+ * @param {number} [occurrence] - Which occurrence, 1-based. Repeats of the same
+ *   literal are otherwise indistinguishable, which is the symptom the
+ *   diagnostic format exists to remove.
+ * @returns {{line: number, column: number}|undefined} 1-based position, or
+ *   `undefined` when the literal is not there. A caller that gets `undefined`
+ *   reports the file alone rather than a position that is not the problem.
+ */
+export function locateInText(text: string, needle: string, occurrence?: number): {
+    line: number;
+    column: number;
+} | undefined;
+/**
+ * Where a literal sits, as spreadable diagnostic fields.
+ *
+ * Keeps the drop-rather-than-guess rule in one place: an unfound literal
+ * contributes no position at all, rather than `undefined` fields that read as a
+ * bug or a `1:1` that sends the reader to the top of the file.
+ *
+ * @param {string} text - The file's contents.
+ * @param {string} needle - The literal to locate.
+ * @param {number} [occurrence] - Which occurrence, 1-based.
+ * @returns {{line?: number, column?: number}} Spreadable position fields.
+ */
+export function positionOf(text: string, needle: string, occurrence?: number): {
+    line?: number;
+    column?: number;
+};