postgame

CLI + local web UI for content creators to cross-post videos to YouTube, TikTok, and Instagram — with optional physics overlays, split-screen composition, and scraping-driven content generation.

Status: alpha — under active construction.

Install

npm install -g @muk2/postgame
# or one-off without installing:
npx @muk2/postgame --help

After install the binary is just postgame:

postgame --help

(The unscoped postgame name on npm is taken by a similar package; we publish under the @muk2 scope.)

Usage

postgame serve                 # boot the local web UI on http://localhost:3000
postgame account add youtube   # OAuth flow for a new account
postgame status                # show scheduler + queue health
postgame upload <file> --accounts 1,2,3 --at "2026-05-17T10:00"
postgame --help

What it does

Three flows in one tool:

1. Bring your own video — upload a finished clip → optionally add a physics-animated bottom panel → cross-post + schedule across platforms.
2. Generate from scratch — pick a content config (preset or custom) → app scrapes source clips, renders a physics scene, composes split-screen → cross-post + schedule.
3. Just cross-post — upload finished video, schedule across YouTube / TikTok / Instagram simultaneously with per-account isolation.

Requirements

• Node.js 22 LTS
• ffmpeg (auto-installed via @ffmpeg-installer/ffmpeg if missing from PATH)
• yt-dlp (auto-installed via yt-dlp-exec if missing from PATH)

Development

git clone http://100.113.110.34:3001/Muk/postgame.git
cd postgame
npm install
npm run typecheck && npm run lint && npm test

Workspace layout:

packages/
  shared/   types, db schema, oauth helpers
  server/   Hono REST API + scheduler + queue + pipelines
  client/   React + Vite SPA
  cli/      commander entry, bundles client dist

Branching

main  ←  dev  ←  feat/*  |  fix/*  |  chore/*

• All work goes on a feat/, fix/, or chore/ branch off dev.
• Open a PR to dev, get CI green, merge.
• When dev is ready to ship, open a PR dev → main and merge (fast-forward if possible).
• release.yml only fires on v* tag pushes — pushes to main don't publish.

Cutting a release

The publishable package is @muk2/postgame at packages/cli/. The workspace root (postgame-monorepo) is private. The release pipeline reads the version out of packages/cli/package.json — not the root.

Before tagging

On main, after a dev → main merge:

1. Smoke-test the build locally:

   npm install
   npm run typecheck && npm run lint && npm test
   npm run build         # full chain: tsc -b, copy-migrations, client vite, cli esbuild bundle

   If any step fails, fix on a branch off dev and re-merge before tagging.

2. Bump the version (use the helper — it keeps packages/cli/package.json and the root in sync and creates the matching tag):

   npm run release -- patch         # 0.1.1 → 0.1.2
   npm run release -- minor         # 0.1.1 → 0.2.0
   npm run release -- major         # 0.1.1 → 1.0.0
   npm run release -- 0.2.0-beta.1  # or an explicit version

   This writes both package.json files, makes the chore(release): X.Y.Z commit, and runs git tag vX.Y.Z.

3. Push commit and tag together:

   git push origin main --follow-tags

What the tag push triggers

release.yml runs:

1. actions/checkout + actions/setup-node@v4 (caches ~/.npm via Forgejo Actions cache)
2. npm ci
3. Verifies ${tag} (minus v) equals packages/cli/package.json version — fails the run otherwise
4. npm run typecheck && npm run lint && npm test
5. npm run build — produces packages/cli/dist/index.js (the bundled CLI), packages/cli/dist/migrations/, and packages/cli/dist/client-dist/
6. npm publish --access public --provenance=false from packages/cli/

If publish fails the workflow posts an issue titled CI publish diagnostic — <sha> with the actual npm error.

What must be in place to publish

| Item | How to set | Why | |---|---|---| | NPM_TOKEN repo secret | Forgejo repo → Settings → Actions → Secrets, value is an npm "Automation" or granular write-enabled token | Auth for npm publish | | packages/cli/package.json "private" is NOT true | (already not present) | npm refuses to publish private packages | | Tag matches packages/cli/package.json version | npm run release handles this | Workflow gates on it | | Lockfile in sync with package.json files | npm install after editing any package.json; commit package-lock.json | npm ci fails on drift |

Common pitfalls (each has burned us in the past)

• Lockfile drift. After bumping a dep or renaming a workspace package, run npm install and commit package-lock.json. CI's npm ci fails fast with EUSAGE if the lockfile and package.json disagree.
• Tag without version bump. Pushing v0.1.2 without first running npm run release -- 0.1.2 will fail the verify step. The fix is to either delete the bad tag (git push origin --delete vX.Y.Z) and re-tag after bumping, or to bump + push the missing commit.
• host.docker.internal in workflows. Don't use it — the Forgejo act_runner can't resolve it reliably. Use the mac-mini's Tailscale IP (http://100.113.110.34:3001) directly.
• Workspace .npmrc is ignored. Don't put npm auth in packages/cli/.npmrc — npm 7+ explicitly ignores it. The workflow writes $HOME/.npmrc instead.

Hot-fix path (skipping dev)

If main is broken and you need to ship a fix immediately:

1. Branch off main directly: git checkout -b hotfix/X main
2. Make the fix, push, open a PR to main (not dev).
3. After merge, run the same npm run release -- patch flow.
4. Then fast-forward dev to main so feature branches inherit the fix: git push origin main:dev.

License

MIT — see LICENSE.