semantic-release-steam 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Scherer
+
+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

@@ -0,0 +1,111 @@
+# semantic-release-steam
+
+A [semantic-release](https://github.com/semantic-release/semantic-release) plugin that publishes a built Steam Workshop item via [SteamCMD](https://developer.valvesoftware.com/wiki/SteamCMD).
+
+Originally extracted from the [RimworldCosmere](https://github.com/RimworldCosmere/RimworldCosmere) project's release pipeline. Generic enough to publish any Steam Workshop item for any Steam app, not just RimWorld.
+
+## What it does
+
+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
+
+On `publish`:
+- Compiles a Steam Workshop description from each mod's `README.md` (markdown -> BBCode via [steamdown](https://github.com/steamdown/steamdown))
+- Stages mod content into a temp dir, respecting `.steamignore`
+- Generates a `workshop.vdf` with `appid`, `publishedfileid`, `contentfolder`, `description`, and `changenote`
+- Invokes `steamcmd +login $STEAM_USERNAME +workshop_build_item ... +quit`
+
+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.)
+
+## Install
+
+```bash
+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)
+
+## Configuration
+
+In `.releaserc.json` / `release.config.mjs`:
+
+```js
+export default {
+  branches: ["main", { name: "beta", prerelease: true }],
+  plugins: [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "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}",
+        mods: [
+          {
+            name: "MyMod",
+            path: "MyMod",
+            workshopIds: { stable: "1234567890", beta: "1234567891" }
+          }
+        ]
+      }
+    ]
+  ]
+};
+```
+
+### Plugin options
+
+| 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`. |
+| `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']`. |
+
+### 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. |
+| `STEAMCMD_PATH` | Optional. Path to `steamcmd.sh` / `steamcmd.exe`. Defaults to `~/steamcmd/steamcmd.sh`. |
+
+## 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.
+
+For each branch target (e.g. `stable`, `beta`):
+
+1. Build your mod content locally.
+2. Stage it into a temp dir, generate a `workshopitem` VDF (without `publishedfileid`), and run `steamcmd +login $STEAM_USERNAME +workshop_build_item path/to/workshop.vdf +quit`.
+3. Note the `publishedfileid` printed by SteamCMD.
+4. Add the ID to your release config under `mods[*].workshopIds.<target>`.
+
+After that, every push to `main` / `beta` will trigger an update via this plugin.
+
+## 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)`.
+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.
+5. Writes the BBCode into the workshop item description field.
+
+If a mod has no `README.md`, the description defaults to `"No description available."`.
+
+## License
+
+MIT - see [LICENSE](./LICENSE).

package/index.mjs

@@ -0,0 +1,74 @@
+import { resolve } from 'node:path';
+import { verifySteamPublishConfig } from './lib/config.mjs';
+import { buildSteamDescription } from './lib/description.mjs';
+import { writeCompiledReadme } from './lib/readme.mjs';
+import { stageModContent } from './lib/stage-content.mjs';
+import { uploadWorkshopItem } from './lib/steamcmd.mjs';
+
+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,
+  });
+}
+
+export async function publish(pluginConfig, context) {
+  const state = await verifySteamPublishConfig({
+    env: context.env,
+    branchName: context.branch.name,
+    branchTargets: pluginConfig.branchTargets,
+    mods: pluginConfig.mods,
+    steamConfigPath: context.env.STEAM_CONFIG_VDF,
+    appId: pluginConfig.appId,
+  });
+
+  if (!state.shouldPublish) {
+    return undefined;
+  }
+
+  const cwd = context.cwd ?? process.cwd();
+  const buildDescription = context.buildSteamDescription ?? buildSteamDescription;
+  const stageContent = context.stageModContent ?? stageModContent;
+  const uploadItem = context.uploadWorkshopItem ?? uploadWorkshopItem;
+  const compileReadme = 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({
+      modPath,
+      header: pluginConfig.descriptionHeader ?? '',
+      footer: pluginConfig.descriptionFooter ?? '',
+      assetDirNameTransform: pluginConfig.assetDirNameTransform,
+    });
+    const stagePath = await stageContent({ modPath });
+    const description = await buildDescription({
+      modPath,
+      assetBaseUrl,
+    });
+
+    await uploadItem({
+      steamCmdPath: context.env.STEAMCMD_PATH ?? '~/steamcmd/steamcmd.sh',
+      steamUsername: context.env.STEAM_USERNAME,
+      steamConfigPath: context.env.STEAM_CONFIG_VDF,
+      appId: pluginConfig.appId,
+      stagePath,
+      publishedFileId: mod.workshopIds[state.target],
+      changenote: context.nextRelease.notes || context.nextRelease.version,
+      description,
+      logger: context.logger,
+    });
+
+    context.logger.log(`Published ${mod.name} to ${state.target} workshop item ${mod.workshopIds[state.target]}`);
+  }
+
+  return undefined;
+}
+
+export default { verifyConditions, publish };

package/lib/config.mjs

@@ -0,0 +1,37 @@
+export function resolveBranchTarget(branchName, branchTargets) {
+  return branchTargets[branchName] ?? null;
+}
+
+export async function verifySteamPublishConfig({
+  env,
+  branchName,
+  branchTargets,
+  mods,
+  steamConfigPath,
+  appId,
+}) {
+  const target = resolveBranchTarget(branchName, branchTargets);
+  if (!target) {
+    return { shouldPublish: false, target: null, mods: [] };
+  }
+
+  if (!appId) {
+    throw new Error('appId is required for Steam publishing (pass it in pluginConfig)');
+  }
+
+  if (!env.STEAM_USERNAME) {
+    throw new Error('STEAM_USERNAME is required for Steam publishing');
+  }
+
+  if (!steamConfigPath) {
+    throw new Error('Steam config.vdf path is required for Steam publishing');
+  }
+
+  const targetMods = mods.filter(mod => mod.workshopIds?.[target]);
+
+  if (targetMods.length === 0) {
+    return { shouldPublish: false, target, mods: [] };
+  }
+
+  return { shouldPublish: true, target, mods: targetMods };
+}

package/lib/description.mjs

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

package/lib/readme.mjs

@@ -0,0 +1,67 @@
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
+
+const defaultAssetDirNameTransform = modPath => [
+  basename(modPath).toLowerCase(),
+  'fallback',
+];
+
+async function replaceFallbackAssets(markdown, modPath, assetDirNameTransform) {
+  const repoRoot = resolve(modPath, '..');
+  const transform = assetDirNameTransform ?? defaultAssetDirNameTransform;
+  const assetDirs = transform(modPath);
+
+  for (const assetDir of assetDirs) {
+    const assetPath = join(repoRoot, '.github', 'assets', assetDir);
+
+    try {
+      const entries = await readdir(assetPath);
+      let nextMarkdown = markdown;
+
+      for (const entry of entries) {
+        const fallbackNames = new Set([
+          entry,
+          entry.replaceAll('_', ' '),
+          entry.replaceAll(' ', '_'),
+        ]);
+
+        for (const fallbackName of fallbackNames) {
+          nextMarkdown = nextMarkdown.replaceAll(
+            `../.github/assets/fallback/${fallbackName}`,
+            `../.github/assets/${assetDir}/${entry}`,
+          );
+        }
+      }
+
+      markdown = nextMarkdown;
+    } catch {
+      continue;
+    }
+  }
+
+  return markdown;
+}
+
+const zeroWidthSpace = '\u200B';
+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 markdown = `${header}${separator}${template}${separator}${footer}`;
+  return await replaceFallbackAssets(markdown, modPath, assetDirNameTransform);
+}
+
+export async function writeCompiledReadme({ modPath, header, footer, assetDirNameTransform }) {
+  const markdown = await compileReadme({ modPath, header, footer, assetDirNameTransform });
+  await mkdir(modPath, { recursive: true });
+  await writeFile(join(modPath, 'README.md'), markdown);
+  return markdown;
+}
+
+export function rewriteAssetLinksForSteam(markdown, assetBaseUrl) {
+  if (!assetBaseUrl) {
+    return markdown;
+  }
+
+  return markdown.replaceAll('../.github/assets/', `${assetBaseUrl}/.github/assets/`);
+}

package/lib/stage-content.mjs

@@ -0,0 +1,25 @@
+import { access, mkdtemp } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+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');
+  } catch {
+  }
+
+  args.push(`${modPath}/`, stagePath);
+  await execFileAsync('rsync', args);
+
+  return stagePath;
+}

package/lib/steamcmd.mjs

@@ -0,0 +1,80 @@
+import { writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createWorkshopVdf } from './vdf.mjs';
+
+const defaultExecFileAsync = promisify(execFile);
+
+function expandHomePath(path) {
+  if (!path?.startsWith('~/')) {
+    return path;
+  }
+
+  return join(homedir(), path.slice(2));
+}
+
+function formatSteamCmdError(error) {
+  const prefix = error?.code === 'ETIMEDOUT'
+    ? 'SteamCMD upload timed out'
+    : 'SteamCMD upload failed';
+  const stdout = error?.stdout ? `\nstdout:\n${error.stdout}` : '';
+  const stderr = error?.stderr ? `\nstderr:\n${error.stderr}` : '';
+
+  return new Error(`${prefix}: ${error.message}${stdout}${stderr}`);
+}
+
+export async function uploadWorkshopItem({
+  steamCmdPath,
+  steamUsername,
+  steamConfigPath,
+  stagePath,
+  publishedFileId,
+  changenote,
+  description,
+  appId,
+  execFileAsync = defaultExecFileAsync,
+  logger,
+}) {
+  if (!appId) {
+    throw new Error('appId is required for uploadWorkshopItem');
+  }
+
+  const vdfPath = join(stagePath, 'workshop.vdf');
+  await writeFile(vdfPath, createWorkshopVdf({
+    appId,
+    publishedFileId,
+    contentFolder: stagePath,
+    changenote,
+    description,
+  }));
+
+  try {
+    const result = await execFileAsync(expandHomePath(steamCmdPath), [
+      '+@ShutdownOnFailedCommand', '1',
+      '+@NoPromptForPassword', '1',
+      '+login', steamUsername,
+      '+workshop_build_item', join(stagePath, 'workshop.vdf'),
+      '+quit',
+    ], {
+      timeout: 120000,
+      env: {
+        ...process.env,
+        STEAM_CONFIG_VDF: steamConfigPath,
+      },
+    });
+
+    if (logger && result?.stdout) {
+      logger.log(result.stdout);
+    }
+
+    if (logger && result?.stderr) {
+      logger.log(result.stderr);
+    }
+  } catch (error) {
+    throw formatSteamCmdError(error);
+  }
+
+  return vdfPath;
+}

package/lib/vdf.mjs

@@ -0,0 +1,23 @@
+function escapeVdfValue(value) {
+  return String(value ?? '').replaceAll('"', '\\"');
+}
+
+export function createWorkshopVdf({
+  appId,
+  publishedFileId,
+  contentFolder,
+  changenote,
+  description,
+}) {
+  return [
+    '"workshopitem"',
+    '{',
+    `  "appid" "${escapeVdfValue(appId)}"`,
+    `  "publishedfileid" "${escapeVdfValue(publishedFileId)}"`,
+    `  "contentfolder" "${escapeVdfValue(contentFolder)}"`,
+    `  "changenote" "${escapeVdfValue(changenote)}"`,
+    `  "description" "${escapeVdfValue(description)}"`,
+    '}',
+    '',
+  ].join('\n');
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "semantic-release-steam",
+  "version": "1.0.0",
+  "description": "semantic-release plugin that publishes a Steam Workshop item from a built mod directory.",
+  "type": "module",
+  "main": "index.mjs",
+  "exports": {
+    ".": "./index.mjs",
+    "./lib/*": "./lib/*"
+  },
+  "files": [
+    "index.mjs",
+    "lib/",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "test:check-config": "node tests/run-config-check.mjs"
+  },
+  "keywords": [
+    "semantic-release",
+    "semantic-release-plugin",
+    "steam",
+    "steam-workshop",
+    "steamcmd",
+    "release",
+    "publish"
+  ],
+  "author": "Aaron Scherer <aequasi@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CryptikLemur/semantic-release-steam.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CryptikLemur/semantic-release-steam/issues"
+  },
+  "homepage": "https://github.com/CryptikLemur/semantic-release-steam#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "semantic-release": ">=22.0.0"
+  },
+  "peerDependenciesMeta": {
+    "semantic-release": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "semantic-release": "^25.0.0",
+    "@semantic-release/git": "^10.0.0"
+  }
+}