@gurupanguji

Publish Socials Wrapper Spec

Context

Running Publish Social Snippets currently takes a manual gh workflow run call, an occasional local runner start, and then a separate check to see whether the job finished. The goal is to make that path a single repo-root command without changing the underlying publisher behavior.

This is phase 1. Keep the platform model aligned with scripts/publish_social.py. Do not add CSV parsing or multi-select platform handling. Keep the Pixelfed publish code parked.

Goal

Add a repo-root publish-socials.sh helper that can:

• default to today’s date
• default to main as the workflow ref
• default to the self-hosted runner path
• optionally dispatch the workflow on GitHub-hosted Actions instead
• optionally publish one social platform at a time
• start the local Actions runner only when self-hosted mode is selected and the runner is not already running
• wait for the workflow run to finish and print a concise status summary
• stop the runner after the workflow finishes, regardless of success or failure

Scope

• Add publish-socials.sh at the repository root.
• Add a workflow input for runner mode if needed to support both self-hosted and GitHub-hosted execution.
• Keep --platform single-valued.
• Normalize the simple social aliases the user already thinks in.
• Report the final workflow result in the terminal.

Non-Goals

• Do not add comma-separated or repeated --platform values.
• Do not change the semantics of scripts/publish_social.py.
• Do not unpark Pixelfed.
• Do not add a background daemon, launchd job, or service manager for the runner.
• Do not redesign the social publishing workflow beyond what is needed to switch runner mode and dispatch parameters.

User-Facing Interface

Command shape

• ./publish-socials.sh
• ./publish-socials.sh --date 2026-04-21
• ./publish-socials.sh --ref feature/my-branch
• ./publish-socials.sh --runner github-hosted
• ./publish-socials.sh --platform mastodon

Defaults

• --date defaults to the current day in local time.
• --ref defaults to main.
• --runner defaults to self-hosted.
• --platform is optional. If omitted, the workflow publishes all platforms.

Platform names

Accept one platform name per invocation.

Canonical names:

• mastodon
• bsky
• threads
• twitter
• nostr
• instagram
• pixelfed
• linkedin

Alias handling:

• bsky maps to the workflow’s Bluesky input
• twitter maps to X
• lowercase names are accepted for convenience

Pixelfed stays parked. The wrapper may accept the name, but the publish path remains unchanged and does not unpark that code.

Design

The wrapper should do three things in order:

1. Resolve arguments and normalize the platform name if one was provided.
2. Ensure the self-hosted runner is running when --runner self-hosted is selected.
3. Dispatch the workflow with gh workflow run, then wait for the new run and report the result.

Runner handling should be deliberately simple. The script only needs to know whether the local runner process is already active. If not, it should start ~/dev/gurupanguji.github.io/actions-runner/run.sh, then wait until GitHub reports a matching run. If --runner github-hosted is selected, the wrapper must skip local runner startup entirely.

For workflow status, the wrapper should find the newest matching run for Publish Social Snippets on the requested ref, then watch it until completion. If dispatch succeeds but no run appears, the script should fail loudly and show the dispatch parameters it used. After the run finishes, the wrapper should stop the local runner when it started one for this invocation. That shutdown should happen whether the workflow succeeds, fails, or exits in any other terminal state.

Workflow Contract

The workflow must support two execution modes:

• self-hosted for the local Mac runner
• github-hosted for ubuntu-latest

The wrapper should pass the runner choice through to workflow_dispatch, and the workflow should choose the appropriate runs-on value from that input.

The workflow already accepts date and platform, so the wrapper should reuse those fields instead of inventing a second dispatch path.

Error Handling

• Invalid dates should fail before any dispatch call.
• Invalid refs should fail before any dispatch call.
• Invalid runner modes should fail before any dispatch call.
• Invalid platform names should fail before any dispatch call.
• If the self-hosted runner cannot be started, print the runner path and stop.
• If GitHub-hosted mode is selected, do not touch the local runner process.
• If the workflow run never appears, report that as a dispatch or runner problem instead of returning a false success.
• If the wrapper started the local runner, it must stop that runner after the run completes, even on failure.

Acceptance Criteria

1. ./publish-socials.sh works from the repo root.
2. --date defaults to today when omitted.
3. --ref defaults to main when omitted.
4. --runner self-hosted starts the local runner only if needed.
5. --runner github-hosted skips local runner startup.
6. --platform accepts exactly one social name and maps simple aliases.
7. The workflow run is watched to completion and its final status is printed.
8. The wrapper stops any local runner it started after the workflow completes.
9. Pixelfed remains parked.

File Changes

• Add publish-socials.sh
• Modify .github/workflows/publish_social.yml if runner mode needs to be dispatched explicitly