semantic-release-steam 2.1.3 → 2.2.0

package/README.md

@@ -43,6 +43,10 @@ Set these variables in your release environment:
 - `STEAM_USERNAME`
 - `STEAM_CONFIG_VDF` or `STEAM_CONFIG_VDF_B64`
 - `STEAMCMD_PATH` if SteamCMD isn't at `~/steamcmd/steamcmd.sh`
+- `STEAM_PASSWORD` or `STEAM_REFRESH_TOKEN`, only if any mod sets `tags` - these set Steam
+  Workshop browse tags over a separate login, since SteamCMD itself has no way to set them.
+  `STEAM_REFRESH_TOKEN` skips the Steam Guard prompt; `STEAM_PASSWORD` needs one approval tap
+  per publish.
 
 SteamCMD must have a saved login in its `config/config.vdf`. See the [SteamCMD Workshop upload guide](https://partner.steamgames.com/doc/features/workshop/implementation#SteamCmdIntegration) for the item setup and VDF format.
 
@@ -57,6 +61,121 @@ The plugin updates Workshop items. Create each item before your first release, t
 - [GitHub Actions setup](https://semantic-release.gitbook.io/semantic-release/recipes/ci-configurations/github-actions)
 - [Steam Workshop implementation guide](https://partner.steamgames.com/doc/features/workshop/implementation)
 
+## Recovering a missed tag update
+
+If a publish uploads through SteamCMD but fails before the tag step finishes (a missed Steam
+Guard tap, a dropped connection), retag the item without a new release:
+
+```bash
+npx semantic-release-steam-apply-tags --config release.config.mjs.json --target main
+```
+
+`--config` points at a JSON file holding just this plugin's own options (`appId`,
+`branchTargets`, `mods`), not the full `release.config.mjs`. Write it once, for example with
+`node -e "console.log(JSON.stringify(require('./release.config.mjs').default.plugins[0][1]))" > release.config.mjs.json`.
+
+`--target` is the git branch name, resolved through the same `branchTargets` map as a normal
+publish.
+
+## Running these by hand from GitHub Actions
+
+Add `workflow_dispatch` to the workflow that runs `semantic-release`, alongside its existing
+trigger:
+
+```yaml
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+```
+
+`semantic-release` still decides whether a release is needed. A manual run with no new
+commits logs "no release published" and exits clean.
+
+Tag recovery needs its own workflow, since it takes a branch name as input instead of reading
+the one that triggered the run:
+
+```yaml
+name: apply-tags
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: Branch name, resolved through branchTargets like a normal publish
+        required: true
+
+jobs:
+  apply-tags:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+      - run: npm ci
+      - run: npx semantic-release-steam-apply-tags --config release.config.mjs.json --target "${{ github.event.inputs.target }}"
+        env:
+          STEAM_USERNAME: ${{ secrets.STEAM_USERNAME }}
+          STEAM_CONFIG_VDF_B64: ${{ secrets.STEAM_CONFIG_VDF_B64 }}
+          STEAM_PASSWORD: ${{ secrets.STEAM_PASSWORD }}
+```
+
+Run it from the repo's Actions tab and pick the branch. It retags the item without touching
+SteamCMD or cutting a release.
+
+## Forcing a release
+
+`semantic-release` reads commit messages to decide the version bump. It has no flag for
+forcing one. To force a release on demand, push an empty commit with a conventional-commit
+message, then run `semantic-release` in the same job:
+
+```yaml
+name: force-release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Release type to force
+        required: true
+        type: choice
+        options: [patch, minor, major]
+      message:
+        description: Commit message, written into the changelog
+        required: true
+
+jobs:
+  force-release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+      - run: npm ci
+      - run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          case "${{ inputs.bump }}" in
+            patch) type=fix ;;
+            minor) type=feat ;;
+            major) type='feat!' ;;
+          esac
+          git commit --allow-empty -m "$type: ${{ inputs.message }}"
+          git push
+      - run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          STEAM_USERNAME: ${{ secrets.STEAM_USERNAME }}
+          STEAM_CONFIG_VDF_B64: ${{ secrets.STEAM_CONFIG_VDF_B64 }}
+          STEAM_PASSWORD: ${{ secrets.STEAM_PASSWORD }}
+```
+
+Run `semantic-release` in this same job instead of relying on the push above to trigger your
+normal release workflow. A push made with the default `GITHUB_TOKEN` doesn't trigger other
+workflows, so the push-based workflow would never run.
+
 ## License
 
 [MIT](./LICENSE)

package/bin/apply-tags.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { verifySteamPublishConfig } from '../lib/config.mjs';
+import { applyWorkshopTags } from '../lib/workshop-tags.mjs';
+
+function parseArgs(argv) {
+  const args = { config: null, target: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--config') args.config = argv[i + 1];
+    if (argv[i] === '--target') args.target = argv[i + 1];
+  }
+  return args;
+}
+
+function resolveTags(mod, target) {
+  return mod.metadata?.[target]?.tags ?? mod.tags;
+}
+
+export async function run({
+  argv = process.argv.slice(2),
+  env = process.env,
+  logger = console,
+  readConfig = path => readFile(path, 'utf8'),
+  verifyConfig = verifySteamPublishConfig,
+  applyTags = applyWorkshopTags,
+} = {}) {
+  const { config: configPath, target: branchName } = parseArgs(argv);
+  if (!configPath || !branchName) {
+    throw new Error('usage: semantic-release-steam-apply-tags --config <file> --target <branch>');
+  }
+
+  const pluginConfig = JSON.parse(await readConfig(configPath));
+
+  const hasBranchTargets = pluginConfig.branchTargets && typeof pluginConfig.branchTargets === 'object'
+    && !Array.isArray(pluginConfig.branchTargets);
+  const hasMods = Array.isArray(pluginConfig.mods);
+  if (!hasBranchTargets || !hasMods) {
+    throw new Error(
+      `Config file "${configPath}" must contain "branchTargets" (an object) and "mods" (an array) - ` +
+        'the same options you pass to the semantic-release-steam plugin, not the full release.config.mjs. ' +
+        `Found top-level keys: [${Object.keys(pluginConfig).join(', ')}].`,
+    );
+  }
+
+  const state = await verifyConfig({
+    env,
+    branchName,
+    branchTargets: pluginConfig.branchTargets,
+    mods: pluginConfig.mods,
+    appId: pluginConfig.appId,
+  });
+
+  if (!state.shouldPublish) {
+    throw new Error(`Branch "${branchName}" has no configured target in branchTargets.`);
+  }
+
+  const mods = state.mods.map(mod => ({
+    name: mod.name,
+    publishedFileId: mod.workshopIds[state.target],
+    tags: resolveTags(mod, state.target),
+  }));
+
+  await applyTags({
+    steamUsername: env.STEAM_USERNAME,
+    steamPassword: env.STEAM_PASSWORD,
+    steamRefreshToken: env.STEAM_REFRESH_TOKEN,
+    appId: pluginConfig.appId,
+    mods,
+    logger,
+  });
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  run().catch(error => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/index.mjs

@@ -4,6 +4,7 @@ import { buildSteamDescription } from './lib/description.mjs';
 import { compileReadme, writeCompiledReadme } from './lib/readme.mjs';
 import { stageModContent } from './lib/stage-content.mjs';
 import { uploadWorkshopItem } from './lib/steamcmd.mjs';
+import { applyWorkshopTags } from './lib/workshop-tags.mjs';
 
 function isDryRun(context) {
   return Boolean(context?.options?.dryRun);
@@ -27,6 +28,7 @@ function resolveOverrides(context) {
     uploadItem: context.uploadWorkshopItem ?? uploadWorkshopItem,
     compile: context.compileReadme ?? compileReadme,
     writeCompiled: context.writeCompiledReadme ?? writeCompiledReadme,
+    applyTags: context.applyWorkshopTags ?? applyWorkshopTags,
   };
 }
 
@@ -83,6 +85,8 @@ export async function publish(pluginConfig, context) {
     ? pluginConfig.assetBaseUrlTemplate.replace('{branch}', context.branch.name)
     : '';
 
+  const taggableMods = [];
+
   for (const mod of state.mods) {
     const modPath = resolve(cwd, mod.path);
     const markdown = await compileModReadme(pluginConfig, modPath, overrides);
@@ -117,6 +121,7 @@ export async function publish(pluginConfig, context) {
       steamCmdPath: context.env.STEAMCMD_PATH ?? '~/steamcmd/steamcmd.sh',
       steamUsername: context.env.STEAM_USERNAME,
       steamConfigPath: state.steamConfigPath,
+      steamHome: state.steamHome,
       appId: pluginConfig.appId,
       stagePath,
       publishedFileId,
@@ -132,6 +137,18 @@ export async function publish(pluginConfig, context) {
     });
 
     context.logger.log(`Published ${mod.name} to ${state.target} workshop item ${publishedFileId}`);
+    taggableMods.push({ name: mod.name, publishedFileId, tags: metadata.tags });
+  }
+
+  if (!dryRun) {
+    await overrides.applyTags({
+      steamUsername: context.env.STEAM_USERNAME,
+      steamPassword: context.env.STEAM_PASSWORD,
+      steamRefreshToken: context.env.STEAM_REFRESH_TOKEN,
+      appId: pluginConfig.appId,
+      mods: taggableMods,
+      logger: context.logger,
+    });
   }
 
   return undefined;

package/lib/config.mjs

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, writeFile, symlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
@@ -49,11 +49,15 @@ export async function resolveSteamConfigPath(env) {
 
   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')}`);
+    const home = join(tmpdir(), `semantic-release-steam-${randomBytes(6).toString('hex')}`);
+    const steamDir = join(home, '.steam');
+    const dir = join(steamDir, 'config');
     await mkdir(dir, { recursive: true });
+    await symlink(steamDir, join(steamDir, 'root'));
+    await symlink(steamDir, join(steamDir, 'steam'));
     const path = join(dir, 'config.vdf');
     await writeFile(path, buffer);
-    return path;
+    return { path, home };
   }
 
   return null;
@@ -81,13 +85,16 @@ export async function verifySteamPublishConfig({
     );
   }
 
-  const steamConfigPath = await resolveSteamConfigPath(env);
-  if (!steamConfigPath) {
+  const resolvedConfig = await resolveSteamConfigPath(env);
+  if (!resolvedConfig) {
     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 steamConfig = typeof resolvedConfig === 'string'
+    ? { path: resolvedConfig, home: null }
+    : resolvedConfig;
 
   if (!Array.isArray(mods) || mods.length === 0) {
     throw new Error('mods is required and must contain at least one entry');
@@ -132,5 +139,21 @@ export async function verifySteamPublishConfig({
     );
   }
 
-  return { shouldPublish: true, target, mods: publishable, steamConfigPath };
+  const needsTagCredentials = publishable.some(
+    mod => (mod.metadata?.[target]?.tags ?? mod.tags)?.length > 0,
+  );
+  if (needsTagCredentials && !env.STEAM_PASSWORD && !env.STEAM_REFRESH_TOKEN) {
+    throw new Error(
+      'STEAM_PASSWORD or STEAM_REFRESH_TOKEN is required when a mod configures tags. ' +
+        'Set one of them, or remove tags to skip the Workshop tags step.',
+    );
+  }
+
+  return {
+    shouldPublish: true,
+    target,
+    mods: publishable,
+    steamConfigPath: steamConfig.path,
+    steamHome: steamConfig.home,
+  };
 }

package/lib/steamcmd.mjs

@@ -39,6 +39,7 @@ export async function uploadWorkshopItem({
   steamCmdPath,
   steamUsername,
   steamConfigPath,
+  steamHome,
   stagePath,
   publishedFileId,
   changenote,
@@ -82,6 +83,7 @@ export async function uploadWorkshopItem({
       env: {
         ...process.env,
         STEAM_CONFIG_VDF: steamConfigPath,
+        ...(steamHome ? { HOME: steamHome } : {}),
       },
     });
 

package/lib/workshop-tags.mjs

@@ -0,0 +1,195 @@
+const LOGIN_TIMEOUT_MS = 120_000;
+const CONNECT_TIMEOUT_MS = 30_000;
+const UPDATE_TIMEOUT_MS = 30_000;
+const LOGOFF_TIMEOUT_MS = 5_000;
+const VERIFY_ATTEMPTS = 3;
+const VERIFY_RETRY_DELAY_MS = 2_000;
+
+const GUARD_TYPE_DEVICE_CONFIRMATION = 4;
+const GUARD_TYPE_EMAIL_CONFIRMATION = 5;
+
+export function canPollForGuardApproval(validActions) {
+  return (validActions ?? []).some(
+    action => action.type === GUARD_TYPE_DEVICE_CONFIRMATION || action.type === GUARD_TYPE_EMAIL_CONFIRMATION,
+  );
+}
+
+async function loginWithPassword({ steamUsername, steamPassword, logger }) {
+  const { LoginSession, EAuthTokenPlatformType } = await import('steam-session');
+  const session = new LoginSession(EAuthTokenPlatformType.SteamClient);
+  session.loginTimeout = LOGIN_TIMEOUT_MS;
+
+  const startResult = await session.startWithCredentials({
+    accountName: steamUsername,
+    password: steamPassword,
+  });
+
+  if (startResult.actionRequired) {
+    if (!canPollForGuardApproval(startResult.validActions)) {
+      throw new Error(
+        'Steam Guard on this account needs an email or mobile authenticator code, which STEAM_PASSWORD ' +
+          'cannot approve automatically. Use STEAM_REFRESH_TOKEN instead, or enable app-based confirmation.',
+      );
+    }
+    logger.log('Approve the Steam Guard prompt on your phone to publish Workshop tags.');
+  }
+
+  await /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
+    session.once('authenticated', () => resolve());
+    session.once('timeout', () => reject(new Error('Steam Guard approval timed out')));
+    session.once('error', reject);
+  }));
+
+  return session.refreshToken;
+}
+
+export function connectWithTimeout(user, timeoutMs, trigger) {
+  return new Promise((resolve, reject) => {
+    const settle = (fn, value) => {
+      clearTimeout(timer);
+      user.removeAllListeners('loggedOn');
+      user.removeAllListeners('error');
+      fn(value);
+    };
+    const timer = setTimeout(() => {
+      user.logOff();
+      settle(reject, new Error('Steam CM connection timed out'));
+    }, timeoutMs);
+    user.once('loggedOn', () => settle(resolve));
+    user.once('error', err => settle(reject, err));
+    trigger();
+  });
+}
+
+async function connectToCM(refreshToken) {
+  const SteamUser = (await import('steam-user')).default;
+  const user = new SteamUser({ autoRelogin: false });
+
+  await connectWithTimeout(user, CONNECT_TIMEOUT_MS, () => user.logOn({ refreshToken }));
+
+  const died = new Promise((_resolve, reject) => {
+    user.on('error', reject);
+    user.on('disconnected', eresult => reject(new Error(`Steam CM session disconnected (eresult ${eresult})`)));
+  });
+
+  return { user, died };
+}
+
+async function sendTagUpdate(user, { appid, publishedfileid, tags }) {
+  const SteamUser = (await import('steam-user')).default;
+  const Schema = (await import('steam-user/protobufs/generated/_load.js')).default;
+
+  return /** @type {Promise<void>} */ (new Promise((resolve, reject) => {
+    const body = Schema.CPublishedFile_Update_Request.encode({ appid, publishedfileid, tags }).finish();
+    const timer = setTimeout(() => reject(new Error('PublishedFile.Update#1 timed out')), UPDATE_TIMEOUT_MS);
+
+    user._send(
+      { msg: SteamUser.EMsg.ServiceMethodCallFromClient, proto: { target_job_name: 'PublishedFile.Update#1' } },
+      Buffer.from(body),
+      (_body, header) => {
+        clearTimeout(timer);
+        const eresult = header?.proto?.eresult;
+        if (eresult !== SteamUser.EResult.OK) {
+          reject(new Error(`PublishedFile.Update#1 for ${publishedfileid} returned eresult ${eresult}`));
+          return;
+        }
+        resolve();
+      },
+    );
+  }));
+}
+
+function fetchPublishedTags(user, publishedfileid, expectedTags) {
+  return new Promise((resolve, reject) => {
+    user.getPublishedFileDetails([publishedfileid], (err, results) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      const actual = (results[publishedfileid]?.tags ?? []).map(t => (t.tag ?? t).toLowerCase()).sort();
+      const expected = expectedTags.map(t => t.toLowerCase()).sort();
+      resolve({ matches: JSON.stringify(actual) === JSON.stringify(expected), actual });
+    });
+  });
+}
+
+export async function verifyPublishedTags(
+  user,
+  publishedfileid,
+  expectedTags,
+  attempts = VERIFY_ATTEMPTS,
+  delayMs = VERIFY_RETRY_DELAY_MS,
+) {
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const result = await fetchPublishedTags(user, publishedfileid, expectedTags);
+    if (result.matches || attempt === attempts) {
+      return result;
+    }
+    await new Promise(resolve => setTimeout(resolve, delayMs));
+  }
+  return undefined;
+}
+
+export function logOffAndWait(user, timeoutMs = LOGOFF_TIMEOUT_MS) {
+  return /** @type {Promise<void>} */ (new Promise(resolve => {
+    if (!user.steamID) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(resolve, timeoutMs);
+    user.once('disconnected', () => { clearTimeout(timer); resolve(); });
+    user.logOff();
+  }));
+}
+
+export async function applyWorkshopTags({
+  steamUsername,
+  steamPassword,
+  steamRefreshToken,
+  appId,
+  mods,
+  logger,
+  login = loginWithPassword,
+  connect = connectToCM,
+  disconnect = logOffAndWait,
+  sendUpdate = sendTagUpdate,
+  verify = verifyPublishedTags,
+}) {
+  const taggedMods = mods.filter(mod => Array.isArray(mod.tags) && mod.tags.length > 0);
+  if (taggedMods.length === 0) {
+    return;
+  }
+
+  const refreshToken = steamRefreshToken || await login({ steamUsername, steamPassword, logger });
+  const { user, died } = await connect(refreshToken);
+
+  const tagged = [];
+  try {
+    for (const mod of taggedMods) {
+      await Promise.race([
+        sendUpdate(user, { appid: appId, publishedfileid: mod.publishedFileId, tags: mod.tags }),
+        died,
+      ]);
+
+      const result = await Promise.race([verify(user, mod.publishedFileId, mod.tags), died]);
+      if (!result.matches) {
+        throw new Error(
+          `Workshop tags for "${mod.name}" did not verify after the update. ` +
+            `Sent [${mod.tags.join(', ')}], Steam now reports [${result.actual.join(', ')}].`,
+        );
+      }
+
+      tagged.push(mod.name);
+    }
+  } catch (error) {
+    const untagged = taggedMods.slice(tagged.length).map(mod => mod.name);
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Workshop tag update failed: ${message} Tagged: [${tagged.join(', ')}]. ` +
+        `Still untagged on Workshop: [${untagged.join(', ')}].`,
+      { cause: error },
+    );
+  } finally {
+    await disconnect(user);
+  }
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "semantic-release-steam",
-  "version": "2.1.3",
+  "version": "2.2.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",
+  "bin": {
+    "semantic-release-steam-apply-tags": "./bin/apply-tags.mjs"
+  },
   "exports": {
     ".": {
       "types": "./index.d.ts",
@@ -16,6 +19,7 @@
   "files": [
     "index.mjs",
     "index.d.ts",
+    "bin/",
     "lib/",
     "schema/",
     "LICENSE",
@@ -62,14 +66,16 @@
     }
   },
   "dependencies": {
-    "@steamdown/core": "^1.0.0-beta.2"
+    "@steamdown/core": "^1.0.0-beta.2",
+    "steam-session": "^1.9.4",
+    "steam-user": "^5.3.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.0.0",
-    "@types/node": "^20.0.0",
-    "eslint": "^9.0.0",
-    "globals": "^15.0.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.6.1",
+    "eslint": "^10.10.0",
+    "globals": "^17.12.0",
     "semantic-release": "^25.0.0",
-    "typescript": "^5.5.0"
+    "typescript": "^7.0.2"
   }
 }