🔗 Share & Deploy: One-command publish to public URL for stakeholder access #12

🎯 Feature: Share & Deploy Mechanism

Context

The html-explainer workflow currently terminates at the local file system. A generated artifact lives at ~/.claude/html-explainer/outputs/ and is visible only to the user who generated it. This is the missing link in the value chain:

intent → evidence → visual artifact → LOCAL FILE (dead end) ❌
intent → evidence → visual artifact → PUBLIC URL → stakeholder review ✅

Every time a stakeholder needs to see an artifact, the user must manually attach it, screenshot it, or share it via another channel. This friction discourages use and undermines the value of the tool.

Problem

• Stakeholders (PMs, designers, reviewers, clients) cannot self-serve artifact access
• Generated HTML artifacts live in local storage, invisible to anyone without CLI access
• The tool serves the individual user, not the collaborative workflow

What This Resolves

• One command to publish an artifact to a public URL: deploy-share.py <artifact.html>
• Returns a stable URL valid for at least 30 days
• Zero configuration — no API keys, no cloud account setup, no complex auth
• Works for both single files and the local memory index

Proposed Approach

Tool: scripts/deploy-share.py

A standalone script that:

1. Takes an HTML artifact path as input (or the outputs index directory)
2. Uses surge.sh (via npx surge) as the deploy target — pre-installed in Claude Code environments, no auth required for anonymous deploys with a generated subdomain
3. Returns the public URL
4. Logs the deploy to a ~/.claude/html-explainer/deploy-log.json for tracking

Fallback: If npx surge is unavailable, use a simple HTTP upload to a configurable endpoint (env var HTML_EXPLAINER_UPLOAD_URL).

Integration with deliver-artifact.py:

• Add --share flag to deliver-artifact.py that calls deploy-share.py after approval
• The share URL is appended to the artifact metadata and logged

Design constraints:

• Anonymous deploys use generated subdomains (e.g., lucid-semantics-1234.surge.sh)
• No persistent accounts required
• URLs expire after 30 days by default (surge.sh behavior); document this
• The deploy log captures: timestamp, artifact path, URL, expiry estimate

API Contract:

python scripts/deploy-share.py ~/.claude/html-explainer/outputs/artifacts/replaceable/my-artifact.html
# Output: {"url": "https://lucid-semantics-1234.surge.sh", "artifact": "...", "deployed_at": "...", "expires_at": "..."}

Acceptance Criteria

• python scripts/deploy-share.py <artifact.html> returns a valid public URL within 10 seconds
• The published URL renders the artifact correctly in a browser (no auth, no CORS issues)
• --share flag on deliver-artifact.py triggers publish and logs the URL
• Deploy log (deploy-log.json) tracks all published artifacts with timestamp and URL
• Works without any API keys or authenticated accounts
• scripts/validate-runtime.sh passes with the new tool callable
• Smoke test: creates test artifact, deploys it, verifies URL returns HTTP 200

Quality Verification

Create a test artifact, deploy it, and verify the URL is reachable. The smoke test runs as part of CI on every PR.

Labels

enhancement, high-priority, share-and-collaborate

Milestone

v1.1 — Collaboration-ready artifacts