feat(share): Add surge.sh artifact deployment and --share flag to deliver-artifact.py by ramsani · Pull Request #17 · ramsani/html-explainer

ramsani · 2026-05-16T23:25:14Z

feat(share): Add surge.sh artifact deployment

What

Implements the Share & Deploy mechanism from Issue #12.

Adds two new files and modifies one existing file:

scripts/deploy-share.py (new): Standalone deployment tool using surge.sh
- Takes an HTML artifact path and deploys it to a public URL
- Returns URL with --json flag: {url, artifact, deployed_at, expires_at}
- Logs all deploys to ~/.claude/html-explainer/deploy-log.json
- Works without API keys (anonymous surge.sh deploys)
- Timeout: 120 seconds; graceful failure with JSON error if surge unavailable
scripts/deliver-artifact.py (modified): Adds --share and --share-url-output flags
- --share: calls deploy-share.py after artifact approval, logs share_url in metadata JSON
- --share-url-output <path>: writes the deployed URL to a file
- Backward compatible: all existing args unchanged
tests/test_share_deploy.py (new): Validates the feature
- test_deploy_share_help(): verifies --help works
- test_deliver_artifact_share_flag_exists(): verifies --share and --share-url-output in help
- test_deploy_share_json_flag(): tests JSON output (accepts graceful failure in CI)

Why

The html-explainer workflow previously terminated at the local file system. Every artifact lived at ~/.claude/html-explainer/outputs/ and was invisible to stakeholders without CLI access.

The deploy mechanism closes this gap:

Stakeholders (PMs, designers, clients) can now self-serve artifact access via a generated URL, with no additional user friction.

Acceptance Criteria (from #12)

python scripts/deploy-share.py <artifact.html> returns a valid public URL (or graceful JSON error)
--share flag on deliver-artifact.py triggers publish and logs URL in metadata
Deploy log (deploy-log.json) tracks all published artifacts with timestamp and URL
Works without API keys (anonymous surge.sh)
Tests validate the feature
Backward compatible with existing deliver-artifact.py usage

Testing

# Verify deploy-share.py help
python scripts/deploy-share.py --help

# Verify --share flag in deliver-artifact.py
python scripts/deliver-artifact.py --help | grep share

# Run tests
python tests/test_share_deploy.py

# Smoke test (requires npx surge):
echo "<!doctype html><html><body>test</body></html>" > /tmp/test.html
python scripts/deploy-share.py /tmp/test.html --json
# Expected: {success: true, url: "https://...surge.sh", ...}

Closes #12

…fact.py

ramsani added 3 commits May 16, 2026 16:24

feat(share): add deploy-share.py using surge.sh for artifact sharing

968dbe4

feat(share): add --share and --share-url-output flags to deliver-arti…

210c733

…fact.py

feat(share): add test_share_deploy.py

425f4fa

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(share): Add surge.sh artifact deployment and --share flag to deliver-artifact.py#17

feat(share): Add surge.sh artifact deployment and --share flag to deliver-artifact.py#17
ramsani wants to merge 3 commits into
mainfrom
feature/share-and-deploy

ramsani commented May 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

ramsani commented May 16, 2026