semantic-release-steam 1.0.1 → 2.1.0

package/README.md

@@ -8,14 +8,15 @@ Originally extracted from the [RimworldCosmere](https://github.com/RimworldCosme
 
 On `verifyConditions`:
 - Validates that the current branch maps to a configured workshop target (e.g. `main` -> `stable`, `beta` -> `beta`)
-- Checks that `STEAM_USERNAME`, `STEAM_CONFIG_VDF`, and `appId` are present
-- Verifies that at least one configured mod has a workshop ID for the resolved target
+- Checks that `STEAM_USERNAME`, a Steam `config.vdf` source (`STEAM_CONFIG_VDF` path or `STEAM_CONFIG_VDF_B64` contents), and `appId` are present
+- Throws clearly if a mod has no `workshopIds`, if a target key looks misspelled (with a "did you mean" suggestion), or if no mod is publishable for the resolved target
 
 On `publish`:
-- Compiles a Steam Workshop description from each mod's `README.md` (markdown -> BBCode via [steamdown](https://github.com/steamdown/steamdown))
+- Compiles a Steam Workshop description from each mod's `README.template.md` (markdown -> BBCode via [`@steamdown/core`](https://www.npmjs.com/package/@steamdown/core))
 - Stages mod content into a temp dir, respecting `.steamignore`
-- Generates a `workshop.vdf` with `appid`, `publishedfileid`, `contentfolder`, `description`, and `changenote`
+- Generates a `workshop.vdf` with `appid`, `publishedfileid`, `contentfolder`, `description`, `changenote`, plus optional `title`, `previewfile`, `visibility`, and `tags`
 - Invokes `steamcmd +login $STEAM_USERNAME +workshop_build_item ... +quit`
+- Honors `semantic-release --dry-run`: logs the intended action without invoking SteamCMD
 
 The plugin assumes you have already created the workshop item once manually via SteamCMD. It updates existing workshop items by their `publishedfileid` - it does NOT create them. (See "First publish" below.)
 
@@ -26,38 +27,48 @@ npm install -D semantic-release-steam
 ```
 
 You'll also need:
-- [SteamCMD](https://developer.valvesoftware.com/wiki/SteamCMD) on `PATH` (or set `STEAMCMD_PATH`)
-- [steamdown](https://www.npmjs.com/package/@steamdown/cli) installed globally for the markdown -> BBCode conversion: `npm install -g @steamdown/cli`
-- A pre-authenticated `config.vdf` from SteamCMD (login once interactively, then base64-encode the resulting file into `STEAM_CONFIG_VDF_B64` for CI)
+- [SteamCMD](https://developer.valvesoftware.com/wiki/SteamCMD) on `PATH` (or set `STEAMCMD_PATH`). On GitHub Actions, [`buildalon/setup-steamcmd@v1`](https://github.com/marketplace/actions/setup-steamcmd) handles this.
+- `rsync` (preinstalled on `ubuntu-latest` runners and macOS).
+- A pre-authenticated `config.vdf` from SteamCMD (login once interactively, then base64-encode the resulting file).
+
+> [!NOTE]
+> As of v2, the markdown-to-BBCode conversion is bundled as a library dependency. You no longer need to `npm install -g @steamdown/cli`.
 
 ## Configuration
 
-In `.releaserc.json` / `release.config.mjs`:
+In `release.config.mjs`:
 
 ```js
 export default {
-  branches: ["main", { name: "beta", prerelease: true }],
+  branches: ['main', { name: 'beta', prerelease: true }],
   plugins: [
-    "@semantic-release/commit-analyzer",
-    "@semantic-release/release-notes-generator",
+    '@semantic-release/commit-analyzer',
+    '@semantic-release/release-notes-generator',
     [
-      "semantic-release-steam",
+      'semantic-release-steam',
       {
-        appId: "294100",
-        branchTargets: { main: "stable", beta: "beta" },
-        descriptionHeader: "## My Mod\n\n",
-        descriptionFooter: "\n\n---\n\nReport issues on GitHub.",
-        assetBaseUrlTemplate: "https://raw.githubusercontent.com/me/my-mod/{branch}",
+        appId: '294100',
+        branchTargets: { main: 'stable', beta: 'beta' },
+        descriptionHeader: '## My Mod\n\n',
+        descriptionFooter: '\n\n---\n\nReport issues on GitHub.',
+        assetBaseUrlTemplate: 'https://raw.githubusercontent.com/me/my-mod/{branch}',
+        uploadTimeoutMs: 600000,
         mods: [
           {
-            name: "MyMod",
-            path: "MyMod",
-            workshopIds: { stable: "1234567890", beta: "1234567891" }
-          }
-        ]
-      }
-    ]
-  ]
+            name: 'MyMod',
+            path: 'MyMod',
+            workshopIds: { stable: '1234567890', beta: '1234567891' },
+            title: 'My Mod',
+            tags: ['QoL', 'Utility'],
+            visibility: 0,
+            metadata: {
+              beta: { title: '[BETA] My Mod' },
+            },
+          },
+        ],
+      },
+    ],
+  ],
 };
 ```
 
@@ -66,21 +77,108 @@ export default {
 | Option | Required | Description |
 |---|---|---|
 | `appId` | Yes | Steam app ID (e.g. `294100` for RimWorld). |
-| `branchTargets` | Yes | Map of git branch name to workshop visibility tag. Branches not in the map are skipped. |
-| `mods` | Yes | Array of `{ name, path, workshopIds }`. `workshopIds` is keyed by the values in `branchTargets`. |
+| `branchTargets` | Yes | Map of git branch name to workshop target key. Branches not in the map are skipped (silently). |
+| `mods` | Yes | Array of [mod config](#mod-config). |
 | `descriptionHeader` | No | String prepended to each mod's compiled README before BBCode conversion. |
 | `descriptionFooter` | No | String appended to each mod's compiled README. |
-| `assetBaseUrlTemplate` | No | A URL template with `{branch}` placeholder. Asset paths matching `../.github/assets/` in the README are rewritten to absolute URLs against this base before BBCode conversion (so workshop pages don't 404 on relative asset references). |
-| `assetDirNameTransform` | No | Function `(modPath) => string[]` returning an ordered list of asset subdirectory names to try inside `<repoRoot>/.github/assets/<dir>/` for fallback substitution. Default: `[basename(modPath).toLowerCase(), 'fallback']`. |
+| `assetBaseUrlTemplate` | No | URL template with `{branch}` placeholder. Asset paths matching `../.github/assets/` in the README are rewritten to absolute URLs against this base. |
+| `assetDirNameTransform` | No | Either an array of subdirectory names under `.github/assets/` (literals or glob patterns), or a function `(modPath) => string[]` returning the ordered list. Default: `[basename(modPath).toLowerCase(), 'fallback']`. |
+| `outputReadme` | No | If `true`, also write the compiled markdown to `<modPath>/README.md` (v1 behavior). Default `false` — the compiled README stays in memory. |
+| `uploadTimeoutMs` | No | Max time in ms to wait for SteamCMD. Default `600000` (10 min). |
+| `verbose` | No | Log SteamCMD stdout/stderr at info level. Default `false` (debug level). |
+
+### Mod config
+
+| Field | Required | Description |
+|---|---|---|
+| `name` | Yes | Human-readable name, used in logs. |
+| `path` | Yes | Mod content directory, relative to the semantic-release cwd. |
+| `workshopIds` | Yes | Map of branch-target key (from `branchTargets`) to Steam Workshop `publishedfileid`. |
+| `title` | No | Workshop item title. Only written into the VDF if set. |
+| `previewfile` | No | Path to a preview image (jpg/png). Only written if set. |
+| `visibility` | No | `0` = public, `1` = friends-only, `2` = private, `3` = unlisted. |
+| `tags` | No | Workshop tag array. |
+| `metadata` | No | Per-target overrides. Keys must match values from `branchTargets`. Per-target fields win over mod-level defaults. |
+
+Workshop fields (`title`, `previewfile`, `visibility`, `tags`) are only emitted into the VDF when set, so manual edits made in the Steam workshop UI are preserved across publishes for fields you don't manage in config.
 
 ### Required environment variables
 
 | Var | Purpose |
 |---|---|
-| `STEAM_USERNAME` | Steam account username with workshop publish permission for the configured `appId`. |
-| `STEAM_CONFIG_VDF` | Path to a pre-authenticated `config.vdf` (the file SteamCMD writes after a successful interactive login). For CI, decode `STEAM_CONFIG_VDF_B64` into a temp file and pass its path. |
+| `STEAM_USERNAME` | Steam account username with workshop publish permission. |
+| `STEAM_CONFIG_VDF` | Path to a pre-authenticated `config.vdf`. |
+| `STEAM_CONFIG_VDF_B64` | Alternative to `STEAM_CONFIG_VDF`: base64-encoded contents of `config.vdf`. The plugin decodes it to a temp file. |
 | `STEAMCMD_PATH` | Optional. Path to `steamcmd.sh` / `steamcmd.exe`. Defaults to `~/steamcmd/steamcmd.sh`. |
 
+At least one of `STEAM_CONFIG_VDF` or `STEAM_CONFIG_VDF_B64` must be set. If both are set, the path wins.
+
+> [!IMPORTANT]
+> SteamCMD reads its auth from `$STEAM_DIR/config/config.vdf` (the install dir's config directory). Setting `STEAM_CONFIG_VDF` only tells the plugin where to find the file; you still need to put a copy at the path SteamCMD expects. See the GitHub Actions example below for the standard pattern.
+
+## GitHub Actions example
+
+A copy-pasteable workflow that runs semantic-release with the Steam plugin:
+
+```yaml
+name: release
+
+on:
+  push:
+    branches: [main, beta]
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install
+        run: npm ci
+
+      - name: Set up SteamCMD
+        uses: buildalon/setup-steamcmd@v1
+
+      - name: Restore Steam config
+        env:
+          STEAM_CONFIG_VDF_B64: ${{ secrets.STEAM_CONFIG_VDF_B64 }}
+        run: |
+          mkdir -p "$STEAM_DIR/config"
+          printf '%s' "$STEAM_CONFIG_VDF_B64" | base64 -d > "$STEAM_DIR/config/config.vdf"
+          echo "STEAM_CONFIG_VDF=$STEAM_DIR/config/config.vdf" >> "$GITHUB_ENV"
+
+      - name: Steam login preflight
+        env:
+          STEAM_USERNAME: ${{ secrets.STEAM_USERNAME }}
+        run: |
+          "$STEAM_CMD/steamcmd.sh" +@ShutdownOnFailedCommand 1 +@NoPromptForPassword 1 +login "$STEAM_USERNAME" +quit
+
+      - name: Run semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          STEAM_USERNAME: ${{ secrets.STEAM_USERNAME }}
+          STEAM_CONFIG_VDF: ${{ env.STEAM_CONFIG_VDF }}
+          STEAMCMD_PATH: ${{ env.STEAM_CMD }}/steamcmd.sh
+        run: npx semantic-release
+```
+
+The two secrets you need:
+- `STEAM_USERNAME` — your Steam account username
+- `STEAM_CONFIG_VDF_B64` — `base64 -w 0 ~/Steam/config/config.vdf` from a machine where you've successfully logged in with `steamcmd +login <user> +quit`
+
 ## First publish
 
 semantic-release-steam UPDATES existing workshop items - it does not create them. Before the plugin can run, each mod needs a `publishedfileid` per branch target.
@@ -92,19 +190,77 @@ For each branch target (e.g. `stable`, `beta`):
 3. Note the `publishedfileid` printed by SteamCMD.
 4. Add the ID to your release config under `mods[*].workshopIds.<target>`.
 
+For RimWorld specifically, the easier path is to publish the mod once via the in-game workshop publisher, then copy the workshop ID into your config.
+
 After that, every push to `main` / `beta` will trigger an update via this plugin.
 
+## Example `.steamignore`
+
+Place at the root of each mod's `path` to exclude files from the upload. Patterns use rsync exclude syntax, plus gitignore-style `!` negation to re-include something a broader pattern would exclude. Later patterns win over earlier ones (gitignore semantics), so put negations after the patterns they override.
+
+```
+# Keep .run/ even though dotfiles below are excluded
+.*
+!.run/
+
+# Source control
+.git
+.gitignore
+.gitattributes
+
+# Docs and templates (the workshop description comes from README.template.md, not these)
+README.md
+README.template.md
+*.md
+
+# Build inputs (the staged dir should contain only runtime artifacts)
+Source/
+src/
+*.csproj
+*.sln
+
+# CI and local dev clutter
+.github/
+.vscode/
+.idea/
+node_modules/
+
+# OS junk
+.DS_Store
+Thumbs.db
+```
+
 ## How the README gets compiled into a workshop description
 
 Each mod is expected to have a `README.template.md`. The plugin:
 
-1. Concatenates `descriptionHeader + zeroWidthSeparator + template + zeroWidthSeparator + descriptionFooter` into `README.md` at the mod root.
-2. Runs an asset fallback substitution: any `../.github/assets/fallback/<name>` reference is replaced with `../.github/assets/<modspecificdir>/<name>` if a matching file exists, where `<modspecificdir>` comes from `assetDirNameTransform(modPath)`.
+1. Concatenates `descriptionHeader + zeroWidthSeparator + template + zeroWidthSeparator + descriptionFooter`.
+2. Runs an asset fallback substitution: any `../.github/assets/fallback/<name>` reference is replaced with `../.github/assets/<modspecificdir>/<name>` if a matching file exists. `<modspecificdir>` is resolved from `assetDirNameTransform`.
 3. Rewrites `../.github/assets/` paths to absolute URLs using `assetBaseUrlTemplate` (so Steam's BBCode renderer can fetch them).
-4. Pipes the result through `steamdown` to convert Markdown to Steam BBCode.
+4. Pipes the result through `@steamdown/core` to convert Markdown to Steam BBCode.
 5. Writes the BBCode into the workshop item description field.
 
-If a mod has no `README.md`, the description defaults to `"No description available."`.
+If a mod has no `README.template.md` (and `outputReadme` is off, leaving no `README.md` to fall back on), the description defaults to `"No description available."`.
+
+By default the compiled markdown stays in memory and never touches your repo. Set `outputReadme: true` if you want the compiled `README.md` written to `<modPath>/README.md` (e.g. so `@semantic-release/git` can commit it).
+
+## Upgrading from 1.x
+
+Breaking changes in 2.0:
+
+- **`@steamdown/cli` is no longer required.** The plugin now uses `@steamdown/core` directly. Remove `npm install -g @steamdown/cli` from your CI.
+- **`README.md` is no longer written into each mod dir by default.** If you relied on this (e.g. committing it via `@semantic-release/git`), set `outputReadme: true`.
+- **Misconfigurations now throw instead of silently skipping.** Specifically: a mod with empty `workshopIds`, a mod missing the target key when no other mod has it either, or a misspelled target key (caught via did-you-mean).
+- **Default upload timeout raised from 2 to 10 minutes.** Set `uploadTimeoutMs` to override.
+
+New in 2.0:
+
+- `STEAM_CONFIG_VDF_B64` env var accepted alongside `STEAM_CONFIG_VDF`.
+- Optional workshop metadata: `title`, `previewfile`, `visibility`, `tags`. Per-mod defaults with per-target overrides via `mod.metadata[target]`.
+- `assetDirNameTransform` accepts an array (literal or glob) in addition to a function.
+- `semantic-release --dry-run` is honored.
+- `verbose` option to surface SteamCMD output at info level.
+- TypeScript declaration file shipped (`index.d.ts`) and JSON schema (`schema/plugin-config.json`).
 
 ## License
 

package/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * semantic-release plugin that publishes Steam Workshop items via SteamCMD.
+ *
+ * @packageDocumentation
+ */
+
+/** Steam Workshop visibility flag (matches workshop_build_item VDF spec). */
+export type WorkshopVisibility = 0 | 1 | 2 | 3;
+
+/** Workshop metadata that can be set per-mod or per-target. */
+export interface WorkshopMetadata {
+  /** Workshop item title. Only emitted if set. */
+  title?: string;
+  /** Path to a preview image (jpg/png), relative to the mod path or absolute. Only emitted if set. */
+  previewfile?: string;
+  /** 0 = public, 1 = friends-only, 2 = private, 3 = unlisted. Only emitted if set. */
+  visibility?: WorkshopVisibility;
+  /** Workshop tags. Only emitted if set. */
+  tags?: string[];
+}
+
+export interface ModConfig extends WorkshopMetadata {
+  /** Human-readable mod name, used in logs. */
+  name: string;
+  /** Mod content directory, relative to the semantic-release cwd. */
+  path: string;
+  /** Map of branch-target name -> Steam Workshop publishedfileid. Keys must match values from `branchTargets`. */
+  workshopIds: Record<string, string>;
+  /** Per-target metadata overrides. Values here win over the mod-level defaults. */
+  metadata?: Record<string, WorkshopMetadata>;
+}
+
+/**
+ * Returns an ordered list of subdirectory names under `<repo>/.github/assets/` to try
+ * when resolving fallback asset paths. Tried in order until one matches.
+ */
+export type AssetDirNameTransform =
+  | string[]
+  | ((modPath: string) => string[]);
+
+export interface PluginConfig {
+  /** Steam app ID (e.g. "294100" for RimWorld). */
+  appId: string;
+  /**
+   * Map of git branch name -> workshop target key. Branches not in the map are silently skipped
+   * (semantic-release will still run other plugins). The target key is used to look up the
+   * `workshopIds` entry for each mod.
+   */
+  branchTargets: Record<string, string>;
+  /** One or more mods to publish. */
+  mods: ModConfig[];
+
+  /** String prepended to each mod's compiled README before BBCode conversion. */
+  descriptionHeader?: string;
+  /** String appended to each mod's compiled README. */
+  descriptionFooter?: string;
+  /**
+   * URL template with `{branch}` placeholder. Asset paths matching `../.github/assets/`
+   * in the README are rewritten to absolute URLs against this base before BBCode conversion.
+   */
+  assetBaseUrlTemplate?: string;
+  /**
+   * Resolves the ordered list of asset subdirectory names to try inside `<repo>/.github/assets/`
+   * for fallback substitution. Default: `[basename(modPath).toLowerCase(), 'fallback']`.
+   *
+   * - Function form receives the absolute mod path and returns dir names.
+   * - Array form is a static list. Entries containing glob characters (`*?[`) are resolved as
+   *   globs against `<repo>/.github/assets/`; other entries are used as literal subdirectory names.
+   */
+  assetDirNameTransform?: AssetDirNameTransform;
+
+  /**
+   * Write the compiled README to `<modPath>/README.md` (the v1 behavior). Default `false`:
+   * the compiled markdown is kept in memory and never touches the user's repo.
+   *
+   * Enable only if you previously relied on the side-effect (e.g. to commit README.md via
+   * `@semantic-release/git`).
+   */
+  outputReadme?: boolean;
+  /** Max time in ms to wait for SteamCMD to finish. Default 600000 (10 min). */
+  uploadTimeoutMs?: number;
+  /**
+   * Log SteamCMD stdout/stderr at info level. Default `false` (debug level).
+   * Useful for diagnosing CI failures.
+   */
+  verbose?: boolean;
+}
+
+/** Minimal slice of semantic-release's context object that this plugin reads. */
+export interface PluginContext {
+  branch: { name: string };
+  cwd?: string;
+  env: Record<string, string | undefined>;
+  nextRelease: { version: string; notes?: string };
+  logger: {
+    log: (msg: string, ...args: unknown[]) => void;
+    error?: (msg: string, ...args: unknown[]) => void;
+    debug?: (msg: string, ...args: unknown[]) => void;
+  };
+  options?: { dryRun?: boolean };
+}
+
+export function verifyConditions(pluginConfig: PluginConfig, context: PluginContext): Promise<void>;
+export function publish(pluginConfig: PluginConfig, context: PluginContext): Promise<void>;
+
+declare const _default: { verifyConditions: typeof verifyConditions; publish: typeof publish };
+export default _default;

package/index.mjs

@@ -1,17 +1,30 @@
 import { resolve } from 'node:path';
 import { verifySteamPublishConfig } from './lib/config.mjs';
 import { buildSteamDescription } from './lib/description.mjs';
-import { writeCompiledReadme } from './lib/readme.mjs';
+import { compileReadme, writeCompiledReadme } from './lib/readme.mjs';
 import { stageModContent } from './lib/stage-content.mjs';
 import { uploadWorkshopItem } from './lib/steamcmd.mjs';
 
+function isDryRun(context) {
+  return Boolean(context?.options?.dryRun);
+}
+
+function resolveModMetadata(mod, target) {
+  const override = mod.metadata?.[target] ?? {};
+  return {
+    title: override.title ?? mod.title,
+    previewfile: override.previewfile ?? mod.previewfile,
+    visibility: override.visibility ?? mod.visibility,
+    tags: override.tags ?? mod.tags,
+  };
+}
+
 export async function verifyConditions(pluginConfig, context) {
   await verifySteamPublishConfig({
     env: context.env,
     branchName: context.branch.name,
     branchTargets: pluginConfig.branchTargets,
     mods: pluginConfig.mods,
-    steamConfigPath: context.env.STEAM_CONFIG_VDF,
     appId: pluginConfig.appId,
   });
 }
@@ -22,7 +35,6 @@ export async function publish(pluginConfig, context) {
     branchName: context.branch.name,
     branchTargets: pluginConfig.branchTargets,
     mods: pluginConfig.mods,
-    steamConfigPath: context.env.STEAM_CONFIG_VDF,
     appId: pluginConfig.appId,
   });
 
@@ -31,41 +43,76 @@ export async function publish(pluginConfig, context) {
   }
 
   const cwd = context.cwd ?? process.cwd();
+  const dryRun = isDryRun(context);
   const buildDescription = context.buildSteamDescription ?? buildSteamDescription;
   const stageContent = context.stageModContent ?? stageModContent;
   const uploadItem = context.uploadWorkshopItem ?? uploadWorkshopItem;
-  const compileReadme = context.writeCompiledReadme ?? writeCompiledReadme;
+  const compile = context.compileReadme ?? compileReadme;
+  const writeCompiled = context.writeCompiledReadme ?? writeCompiledReadme;
   const assetBaseUrl = pluginConfig.assetBaseUrlTemplate
     ? pluginConfig.assetBaseUrlTemplate.replace('{branch}', context.branch.name)
     : '';
 
   for (const mod of state.mods) {
     const modPath = resolve(cwd, mod.path);
-    await compileReadme({
+
+    const compileArgs = {
       modPath,
       header: pluginConfig.descriptionHeader ?? '',
       footer: pluginConfig.descriptionFooter ?? '',
       assetDirNameTransform: pluginConfig.assetDirNameTransform,
-    });
-    const stagePath = await stageContent({ modPath });
+    };
+
+    let markdown;
+    if (pluginConfig.outputReadme) {
+      markdown = await writeCompiled(compileArgs);
+    } else {
+      markdown = await compile(compileArgs);
+    }
+
     const description = await buildDescription({
       modPath,
+      markdown,
       assetBaseUrl,
     });
 
+    const metadata = resolveModMetadata(mod, state.target);
+    const publishedFileId = mod.workshopIds[state.target];
+    const changenote = context.nextRelease.notes || context.nextRelease.version;
+
+    if (dryRun) {
+      context.logger.log(
+        `[dry-run] would publish ${mod.name} to ${state.target} workshop item ${publishedFileId} ` +
+          `(changenote: ${context.nextRelease.version}, description: ${description.length} chars` +
+          (metadata.title ? `, title: "${metadata.title}"` : '') +
+          (metadata.visibility !== undefined ? `, visibility: ${metadata.visibility}` : '') +
+          (metadata.tags?.length ? `, tags: [${metadata.tags.join(', ')}]` : '') +
+          ')',
+      );
+      continue;
+    }
+
+    const stagePath = await stageContent({ modPath });
+
     await uploadItem({
       steamCmdPath: context.env.STEAMCMD_PATH ?? '~/steamcmd/steamcmd.sh',
       steamUsername: context.env.STEAM_USERNAME,
-      steamConfigPath: context.env.STEAM_CONFIG_VDF,
+      steamConfigPath: state.steamConfigPath,
       appId: pluginConfig.appId,
       stagePath,
-      publishedFileId: mod.workshopIds[state.target],
-      changenote: context.nextRelease.notes || context.nextRelease.version,
+      publishedFileId,
+      changenote,
       description,
+      title: metadata.title,
+      previewfile: metadata.previewfile,
+      visibility: metadata.visibility,
+      tags: metadata.tags,
+      timeoutMs: pluginConfig.uploadTimeoutMs,
+      verbose: pluginConfig.verbose,
       logger: context.logger,
     });
 
-    context.logger.log(`Published ${mod.name} to ${state.target} workshop item ${mod.workshopIds[state.target]}`);
+    context.logger.log(`Published ${mod.name} to ${state.target} workshop item ${publishedFileId}`);
   }
 
   return undefined;

package/lib/config.mjs

@@ -1,18 +1,74 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
 export function resolveBranchTarget(branchName, branchTargets) {
   return branchTargets[branchName] ?? null;
 }
 
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  const prev = new Array(b.length + 1);
+  const curr = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prev[j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    for (let j = 0; j <= b.length; j++) prev[j] = curr[j];
+  }
+  return prev[b.length];
+}
+
+function suggestKey(target, available) {
+  if (!available.length) return null;
+  const ranked = available
+    .map(key => ({ key, distance: levenshtein(target, key) }))
+    .sort((a, b) => a.distance - b.distance);
+  const best = ranked[0];
+  if (best.distance <= Math.max(2, Math.floor(target.length / 3))) {
+    return best.key;
+  }
+  return null;
+}
+
+/**
+ * Resolves the path to the SteamCMD config.vdf based on env.
+ * Accepts either STEAM_CONFIG_VDF (a path) or STEAM_CONFIG_VDF_B64 (base64-encoded contents
+ * that get decoded to a temp file). Returns the resolved path.
+ */
+export async function resolveSteamConfigPath(env) {
+  if (env.STEAM_CONFIG_VDF && env.STEAM_CONFIG_VDF.trim().length > 0) {
+    return env.STEAM_CONFIG_VDF;
+  }
+
+  if (env.STEAM_CONFIG_VDF_B64 && env.STEAM_CONFIG_VDF_B64.trim().length > 0) {
+    const buffer = Buffer.from(env.STEAM_CONFIG_VDF_B64, 'base64');
+    const dir = join(tmpdir(), `semantic-release-steam-${randomBytes(6).toString('hex')}`);
+    await mkdir(dir, { recursive: true });
+    const path = join(dir, 'config.vdf');
+    await writeFile(path, buffer);
+    return path;
+  }
+
+  return null;
+}
+
 export async function verifySteamPublishConfig({
   env,
   branchName,
   branchTargets,
   mods,
-  steamConfigPath,
   appId,
 }) {
   const target = resolveBranchTarget(branchName, branchTargets);
   if (!target) {
-    return { shouldPublish: false, target: null, mods: [] };
+    return { shouldPublish: false, target: null, mods: [], steamConfigPath: null };
   }
 
   if (!appId) {
@@ -20,18 +76,61 @@ export async function verifySteamPublishConfig({
   }
 
   if (!env.STEAM_USERNAME) {
-    throw new Error('STEAM_USERNAME is required for Steam publishing');
+    throw new Error(
+      'STEAM_USERNAME is required for Steam publishing (set the env var to your Steam account username)',
+    );
   }
 
+  const steamConfigPath = await resolveSteamConfigPath(env);
   if (!steamConfigPath) {
-    throw new Error('Steam config.vdf path is required for Steam publishing');
+    throw new Error(
+      'Steam config.vdf path is required for Steam publishing. ' +
+        'Set STEAM_CONFIG_VDF=/path/to/config.vdf, or STEAM_CONFIG_VDF_B64=<base64 of config.vdf contents>.',
+    );
   }
 
-  const targetMods = mods.filter(mod => mod.workshopIds?.[target]);
+  if (!Array.isArray(mods) || mods.length === 0) {
+    throw new Error('mods is required and must contain at least one entry');
+  }
+
+  const publishable = [];
+  const skipped = [];
+
+  for (const mod of mods) {
+    const ids = mod.workshopIds ?? {};
+    const keys = Object.keys(ids);
+
+    if (keys.length === 0) {
+      throw new Error(
+        `Mod "${mod.name}" has no workshopIds set. Each mod must declare at least one workshop ID per branch target.`,
+      );
+    }
+
+    if (ids[target]) {
+      publishable.push(mod);
+      continue;
+    }
+
+    const suggestion = suggestKey(target, keys);
+    if (suggestion) {
+      throw new Error(
+        `Mod "${mod.name}" is missing a workshop ID for target "${target}". ` +
+          `Did you mean "${suggestion}"? Found keys: [${keys.join(', ')}].`,
+      );
+    }
+
+    skipped.push({ name: mod.name, keys });
+  }
 
-  if (targetMods.length === 0) {
-    return { shouldPublish: false, target, mods: [] };
+  if (publishable.length === 0) {
+    const detail = skipped
+      .map(s => `${s.name} (has: [${s.keys.join(', ')}])`)
+      .join('; ');
+    throw new Error(
+      `No mods are publishable for target "${target}". ` +
+        `Add a workshopIds["${target}"] entry to at least one mod. Mods checked: ${detail}.`,
+    );
   }
 
-  return { shouldPublish: true, target, mods: targetMods };
+  return { shouldPublish: true, target, mods: publishable, steamConfigPath };
 }

package/lib/description.mjs

@@ -1,43 +1,41 @@
 import { access, readFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { join } from 'node:path';
-import { spawn } from 'node:child_process';
+import { parse, render } from '@steamdown/core';
 import { rewriteAssetLinksForSteam } from './readme.mjs';
 
-export async function buildSteamDescription({ modPath, assetBaseUrl = '' }) {
-  const readmePath = join(modPath, 'README.md');
+const FALLBACK_DESCRIPTION = 'No description available.';
 
-  try {
-    await access(readmePath, constants.F_OK);
-  } catch {
-    return 'No description available.';
+export function renderSteamBBCode(markdown) {
+  if (!markdown || markdown.trim().length === 0) {
+    return FALLBACK_DESCRIPTION;
   }
 
-  const markdown = rewriteAssetLinksForSteam(await readFile(readmePath, 'utf8'), assetBaseUrl);
+  const [tree, context] = parse(markdown);
+  const rendered = render(tree, context);
 
-  return await new Promise((resolve, reject) => {
-    const child = spawn('steamdown', [], { stdio: ['pipe', 'pipe', 'pipe'] });
-    let stdout = '';
-    let stderr = '';
+  if (!rendered || rendered.trim().length === 0) {
+    return FALLBACK_DESCRIPTION;
+  }
+
+  return rendered;
+}
 
-    child.stdout.on('data', chunk => {
-      stdout += chunk;
-    });
+export async function buildSteamDescription({ modPath, assetBaseUrl = '', markdown }) {
+  let source = markdown;
 
-    child.stderr.on('data', chunk => {
-      stderr += chunk;
-    });
+  if (source == null) {
+    const readmePath = join(modPath, 'README.md');
 
-    child.on('error', reject);
-    child.on('close', code => {
-      if (code === 0) {
-        resolve(stdout || 'No description available.');
-        return;
-      }
+    try {
+      await access(readmePath, constants.F_OK);
+    } catch {
+      return FALLBACK_DESCRIPTION;
+    }
 
-      reject(new Error(stderr || `steamdown exited with code ${code}`));
-    });
+    source = await readFile(readmePath, 'utf8');
+  }
 
-    child.stdin.end(markdown);
-  });
+  const rewritten = rewriteAssetLinksForSteam(source, assetBaseUrl);
+  return renderSteamBBCode(rewritten);
 }

package/lib/readme.mjs

@@ -6,10 +6,64 @@ const defaultAssetDirNameTransform = modPath => [
   'fallback',
 ];
 
+const GLOB_CHARS = /[*?[]/;
+
+function isGlobPattern(value) {
+  return typeof value === 'string' && GLOB_CHARS.test(value);
+}
+
+async function listAssetSubdirs(assetsRoot) {
+  try {
+    const entries = await readdir(assetsRoot, { withFileTypes: true });
+    return entries.filter(e => e.isDirectory()).map(e => e.name);
+  } catch {
+    return [];
+  }
+}
+
+function matchGlob(pattern, candidates) {
+  const re = new RegExp(
+    '^' +
+      pattern
+        .replace(/[.+^${}()|\\]/g, '\\$&')
+        .replace(/\*\*/g, '[__DOUBLESTAR__]')
+        .replace(/\*/g, '[^/]*')
+        .replace(/\?/g, '[^/]')
+        .replace(/\[__DOUBLESTAR__\]/g, '.*') +
+      '$',
+  );
+  return candidates.filter(c => re.test(c));
+}
+
+async function resolveAssetDirs(transform, modPath, repoRoot) {
+  if (typeof transform === 'function') {
+    return transform(modPath);
+  }
+
+  if (Array.isArray(transform)) {
+    const assetsRoot = join(repoRoot, '.github', 'assets');
+    const subdirs = transform.some(isGlobPattern) ? await listAssetSubdirs(assetsRoot) : [];
+    const resolved = [];
+
+    for (const entry of transform) {
+      if (isGlobPattern(entry)) {
+        for (const match of matchGlob(entry, subdirs)) {
+          if (!resolved.includes(match)) resolved.push(match);
+        }
+      } else {
+        if (!resolved.includes(entry)) resolved.push(entry);
+      }
+    }
+
+    return resolved;
+  }
+
+  return defaultAssetDirNameTransform(modPath);
+}
+
 async function replaceFallbackAssets(markdown, modPath, assetDirNameTransform) {
   const repoRoot = resolve(modPath, '..');
-  const transform = assetDirNameTransform ?? defaultAssetDirNameTransform;
-  const assetDirs = transform(modPath);
+  const assetDirs = await resolveAssetDirs(assetDirNameTransform, modPath, repoRoot);
 
   for (const assetDir of assetDirs) {
     const assetPath = join(repoRoot, '.github', 'assets', assetDir);
@@ -42,11 +96,12 @@ async function replaceFallbackAssets(markdown, modPath, assetDirNameTransform) {
   return markdown;
 }
 
-const zeroWidthSpace = '\u200B';
+const zeroWidthSpace = '​';
+const stripBom = /^/;
 const separator = `\n${zeroWidthSpace}\n\n`;
 
 export async function compileReadme({ modPath, header, footer, assetDirNameTransform }) {
-  const template = (await readFile(join(modPath, 'README.template.md'), 'utf8')).replace(/^\uFEFF/, '');
+  const template = (await readFile(join(modPath, 'README.template.md'), 'utf8')).replace(stripBom, '');
   const markdown = `${header}${separator}${template}${separator}${footer}`;
   return await replaceFallbackAssets(markdown, modPath, assetDirNameTransform);
 }

package/lib/stage-content.mjs

@@ -1,5 +1,4 @@
-import { access, mkdtemp } from 'node:fs/promises';
-import { constants } from 'node:fs';
+import { mkdtemp, readFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { execFile } from 'node:child_process';
@@ -7,14 +6,39 @@ import { promisify } from 'node:util';
 
 const execFileAsync = promisify(execFile);
 
+function buildFilterArgs(content) {
+  const rules = [];
+
+  for (const raw of content.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) {
+      continue;
+    }
+    if (line.startsWith('!')) {
+      const pattern = line.slice(1).trim();
+      if (pattern) {
+        rules.push(`+ ${pattern}`);
+      }
+      continue;
+    }
+    rules.push(`- ${line}`);
+  }
+
+  // .steamignore is last-match-wins (gitignore semantics); rsync filters are
+  // first-match-wins, so reverse the rule order to preserve precedence.
+  rules.reverse();
+
+  return rules.map((rule) => `--filter=${rule}`);
+}
+
 export async function stageModContent({ modPath }) {
   const stagePath = await mkdtemp(join(tmpdir(), 'steam-release-'));
   const ignorePath = join(modPath, '.steamignore');
   const args = ['-av'];
 
   try {
-    await access(ignorePath, constants.F_OK);
-    args.push(`--exclude-from=${ignorePath}`, '--exclude=.steamignore');
+    const content = await readFile(ignorePath, 'utf8');
+    args.push('--exclude=.steamignore', ...buildFilterArgs(content));
   } catch {
   }
 

package/lib/steamcmd.mjs

@@ -7,6 +7,8 @@ import { createWorkshopVdf } from './vdf.mjs';
 
 const defaultExecFileAsync = promisify(execFile);
 
+export const DEFAULT_UPLOAD_TIMEOUT_MS = 600_000;
+
 function expandHomePath(path) {
   if (!path?.startsWith('~/')) {
     return path;
@@ -25,6 +27,14 @@ function formatSteamCmdError(error) {
   return new Error(`${prefix}: ${error.message}${stdout}${stderr}`);
 }
 
+function logSteamCmdOutput(logger, verbose, stream, text) {
+  if (!logger || !text) return;
+  const sink = verbose
+    ? (logger.log ?? (() => {}))
+    : (logger.debug ?? logger.log ?? (() => {}));
+  sink.call(logger, `[steamcmd:${stream}] ${text.trimEnd()}`);
+}
+
 export async function uploadWorkshopItem({
   steamCmdPath,
   steamUsername,
@@ -34,6 +44,12 @@ export async function uploadWorkshopItem({
   changenote,
   description,
   appId,
+  title,
+  previewfile,
+  visibility,
+  tags,
+  timeoutMs = DEFAULT_UPLOAD_TIMEOUT_MS,
+  verbose = false,
   execFileAsync = defaultExecFileAsync,
   logger,
 }) {
@@ -48,6 +64,10 @@ export async function uploadWorkshopItem({
     contentFolder: stagePath,
     changenote,
     description,
+    title,
+    previewfile,
+    visibility,
+    tags,
   }));
 
   try {
@@ -58,20 +78,15 @@ export async function uploadWorkshopItem({
       '+workshop_build_item', join(stagePath, 'workshop.vdf'),
       '+quit',
     ], {
-      timeout: 120000,
+      timeout: timeoutMs,
       env: {
         ...process.env,
         STEAM_CONFIG_VDF: steamConfigPath,
       },
     });
 
-    if (logger && result?.stdout) {
-      logger.log(result.stdout);
-    }
-
-    if (logger && result?.stderr) {
-      logger.log(result.stderr);
-    }
+    logSteamCmdOutput(logger, verbose, 'stdout', result?.stdout);
+    logSteamCmdOutput(logger, verbose, 'stderr', result?.stderr);
   } catch (error) {
     throw formatSteamCmdError(error);
   }

package/lib/vdf.mjs

@@ -2,22 +2,57 @@ function escapeVdfValue(value) {
   return String(value ?? '').replaceAll('"', '\\"');
 }
 
+function appendOptional(lines, key, value) {
+  if (value === undefined || value === null || value === '') return;
+  lines.push(`  "${key}" "${escapeVdfValue(value)}"`);
+}
+
+function appendTags(lines, tags) {
+  if (!tags || !Array.isArray(tags) || tags.length === 0) return;
+  lines.push('  "tags"');
+  lines.push('  {');
+  for (let i = 0; i < tags.length; i++) {
+    lines.push(`    "${i}" "${escapeVdfValue(tags[i])}"`);
+  }
+  lines.push('  }');
+}
+
+/**
+ * Creates a workshop.vdf for `steamcmd +workshop_build_item`.
+ *
+ * Required: appId, publishedFileId, contentFolder.
+ * Optional and only emitted when set: changenote, description, title, previewfile, visibility, tags.
+ */
 export function createWorkshopVdf({
   appId,
   publishedFileId,
   contentFolder,
   changenote,
   description,
+  title,
+  previewfile,
+  visibility,
+  tags,
 }) {
-  return [
+  const lines = [
     '"workshopitem"',
     '{',
     `  "appid" "${escapeVdfValue(appId)}"`,
     `  "publishedfileid" "${escapeVdfValue(publishedFileId)}"`,
     `  "contentfolder" "${escapeVdfValue(contentFolder)}"`,
-    `  "changenote" "${escapeVdfValue(changenote)}"`,
-    `  "description" "${escapeVdfValue(description)}"`,
-    '}',
-    '',
-  ].join('\n');
+  ];
+
+  appendOptional(lines, 'changenote', changenote);
+  appendOptional(lines, 'description', description);
+  appendOptional(lines, 'title', title);
+  appendOptional(lines, 'previewfile', previewfile);
+  if (visibility !== undefined && visibility !== null) {
+    appendOptional(lines, 'visibility', String(visibility));
+  }
+  appendTags(lines, tags);
+
+  lines.push('}');
+  lines.push('');
+
+  return lines.join('\n');
 }

package/package.json

@@ -1,16 +1,23 @@
 {
   "name": "semantic-release-steam",
-  "version": "1.0.1",
+  "version": "2.1.0",
   "description": "semantic-release plugin that publishes a Steam Workshop item from a built mod directory.",
   "type": "module",
   "main": "index.mjs",
+  "types": "./index.d.ts",
   "exports": {
-    ".": "./index.mjs",
-    "./lib/*": "./lib/*"
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.mjs"
+    },
+    "./lib/*": "./lib/*",
+    "./schema/plugin-config.json": "./schema/plugin-config.json"
   },
   "files": [
     "index.mjs",
+    "index.d.ts",
     "lib/",
+    "schema/",
     "LICENSE",
     "README.md"
   ],
@@ -20,7 +27,9 @@
   },
   "scripts": {
     "test": "node --test tests/*.test.mjs",
-    "test:check-config": "node tests/run-config-check.mjs"
+    "test:check-config": "node tests/run-config-check.mjs",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit"
   },
   "keywords": [
     "semantic-release",
@@ -52,8 +61,16 @@
       "optional": false
     }
   },
+  "dependencies": {
+    "@steamdown/core": "^1.0.0-beta.2"
+  },
   "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^20.0.0",
+    "eslint": "^9.0.0",
+    "globals": "^15.0.0",
     "semantic-release": "^25.0.0",
-    "@semantic-release/git": "^10.0.0"
+    "@semantic-release/git": "^10.0.0",
+    "typescript": "^5.5.0"
   }
 }

package/schema/plugin-config.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/cryptiklemur/semantic-release-steam/schema/plugin-config.json",
+  "title": "semantic-release-steam plugin config",
+  "description": "Configuration for the semantic-release-steam plugin.",
+  "type": "object",
+  "required": ["appId", "branchTargets", "mods"],
+  "additionalProperties": false,
+  "properties": {
+    "appId": {
+      "type": "string",
+      "description": "Steam app ID (e.g. \"294100\" for RimWorld)."
+    },
+    "branchTargets": {
+      "type": "object",
+      "description": "Map of git branch name to workshop target key. Branches not in the map are skipped.",
+      "additionalProperties": { "type": "string" }
+    },
+    "mods": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/ModConfig" }
+    },
+    "descriptionHeader": { "type": "string" },
+    "descriptionFooter": { "type": "string" },
+    "assetBaseUrlTemplate": {
+      "type": "string",
+      "description": "URL template with {branch} placeholder for rewriting relative asset paths."
+    },
+    "assetDirNameTransform": {
+      "description": "Either a list of asset subdirectory names (literals or globs) to try under .github/assets/, or a function returning the list. Functions are only valid in .mjs/.cjs configs.",
+      "oneOf": [
+        {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      ]
+    },
+    "outputReadme": {
+      "type": "boolean",
+      "default": false,
+      "description": "Write the compiled README to <modPath>/README.md (v1 behavior). Default false."
+    },
+    "uploadTimeoutMs": {
+      "type": "integer",
+      "minimum": 1000,
+      "default": 600000,
+      "description": "Max time in ms to wait for SteamCMD to finish. Default 600000 (10 min)."
+    },
+    "verbose": {
+      "type": "boolean",
+      "default": false,
+      "description": "Log SteamCMD stdout/stderr at info level."
+    }
+  },
+  "definitions": {
+    "WorkshopMetadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "title": { "type": "string" },
+        "previewfile": { "type": "string" },
+        "visibility": {
+          "type": "integer",
+          "enum": [0, 1, 2, 3],
+          "description": "0=public, 1=friends-only, 2=private, 3=unlisted"
+        },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "ModConfig": {
+      "type": "object",
+      "required": ["name", "path", "workshopIds"],
+      "additionalProperties": false,
+      "allOf": [{ "$ref": "#/definitions/WorkshopMetadata" }],
+      "properties": {
+        "name": { "type": "string" },
+        "path": { "type": "string" },
+        "workshopIds": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Map of branch-target name to Steam Workshop publishedfileid."
+        },
+        "title": { "type": "string" },
+        "previewfile": { "type": "string" },
+        "visibility": { "type": "integer", "enum": [0, 1, 2, 3] },
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "metadata": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/definitions/WorkshopMetadata" },
+          "description": "Per-target metadata overrides. Keys must match values from branchTargets."
+        }
+      }
+    }
+  }
+}