@gurupanguji

Publish Socials Wrapper Implementation Plan

For agentic workers: implement this plan in order. Keep the branch isolated. Do not touch unrelated content, especially existing snippet edits.

Goal: Add a repo-root helper that dispatches Publish Social Snippets, starts the self-hosted runner when needed, and reports the workflow result.

Architecture: Keep the wrapper thin. Let it normalize arguments, manage the local runner process, and orchestrate gh workflow run plus run watching. Keep the actual publishing behavior inside the existing workflow and Python publisher.

Phase 1 Rules:

• Single --platform value only.
• No CSV parsing.
• No scripts/publish_social.py platform rewrite.
• Pixelfed stays parked.

---

Task 1: Add the repo-root wrapper

Files:

• Add: publish-socials.sh

• Step 1: Create a shell wrapper with strict argument parsing
  • Support --date, --ref, --runner, and --platform.
  • Default --date to today.
  • Default --ref to main.
  • Default --runner to self-hosted.
  • Reject unknown flags.
• Step 2: Normalize platform aliases
  • Accept one value only.
  • Normalize bsky to the workflow’s Bluesky name.
  • Normalize twitter to X.
  • Pass through mastodon, threads, instagram, linkedin, nostr, and pixelfed.
  • Fail fast on anything else.
• Step 3: Start the local runner only when self-hosted mode is selected
  • Check whether ~/dev/gurupanguji.github.io/actions-runner/run.sh is already active.
  • If not active, start it in the background.
  • Wait for the runner to become visible before dispatching the workflow.
  • Do nothing runner-related in github-hosted mode.
• Step 4: Dispatch the workflow and capture the run
  • Run gh workflow run "Publish Social Snippets" --repo gurupanguji/gurupanguji.github.io --ref <ref> -f date=<date>.
  • Pass -f platform=<single-platform> only when a platform is specified.
  • Wait for the matching workflow run to appear.
  • Watch the run until it finishes.
  • Print the run URL and final conclusion.
  • Stop the local runner after the run finishes, whether the workflow succeeded or failed, if the wrapper started it for this invocation.

---

Task 2: Wire runner mode through the workflow

Files:

• Modify: .github/workflows/publish_social.yml

• Step 1: Add a dispatch input for runner mode
  • Keep the input name aligned with the wrapper flag.
  • Default it to self-hosted behavior.
• Step 2: Select runs-on from the dispatch input
  • Use self-hosted when the wrapper asks for the local runner.
  • Use GitHub-hosted when the wrapper asks for that path.
  • Keep the existing publish steps unchanged.
• Step 3: Preserve the existing date and platform dispatch inputs
  • Do not introduce a second platform flow.
  • Do not change the publisher’s parking of Pixelfed.

---

Task 3: Verify the wrapper behavior

Files:

• Add: publish-socials.sh

• Modify: .github/workflows/publish_social.yml

• Step 1: Verify shell syntax
  • Run shellcheck if available.
  • At minimum, run bash -n publish-socials.sh.
• Step 2: Verify dispatch wiring
  • Check that the workflow file still parses.
  • Confirm the new runner input is present.
• Step 3: Exercise the wrapper in dry or partial form
  • Confirm default argument resolution.
  • Confirm alias normalization.
  • Confirm runner selection logic.
  • Confirm the script reports a clear error when the platform name is invalid.
  • Confirm self-hosted mode starts and then stops the local runner around a completed run.
• Step 4: Review the diff for scope drift
  • Ensure no unrelated snippet or content changes are included.