psingletary.com / Migration_Toolkit_research.md
Small-Business → AT Protocol Migration Toolkit — Research Brief
0
Migration_Toolkit_research.md
60 lines 6.2 kB View raw View code

Migration_Toolkit_research.md#

Small-Business → AT Protocol Migration Toolkit — Research Brief#

Seed document for a new project chat · Derived from the AT Protocol Ecosystem Repository Analysis (2026-08-12)

1. The Opportunity#

ptharbor is an existence proof: a real small business (Point Harbor Signs) was migrated off Weebly onto a fully AT Protocol–native stack, and its README explicitly frames itself as "a repeatable blueprint for migrating small businesses off Facebook/Instagram/WordPress/Wix to AT Protocol." But every step was manual: hand-ported HTML, hand-run key-generation and deploy scripts, hand-written did:web documents. The toolkit's job is to turn that blueprint into an automated, repeatable pipeline.

2. The Proven Reference Architecture (from ptharbor)#

Layer ptharbor's choice Notes
Website hosting wisp.place (PDS-based static hosting) Site files stored as PDS blobs, signed manifest, CDN cache invalidated via firehose
Identity did:web (did-web/ dir, did.json served at the business domain) Alternative: did:plc
PDS Protobase.at (managed PDS) Business doesn't self-host
Code hosting Tangled (ATProto-native git)
Domain Marque.at (registrar) Optional layer
Site itself Plain static HTML, no framework Ported from Weebly

3. What the Toolkit Must Automate (pipeline stages)#

  1. Scrape/export — pull the existing site from Weebly/Wix/WordPress/Squarespace/Facebook Pages. WordPress has XML export; Wix/Weebly/FB generally require crawling the rendered site.
  2. Static port — normalize scraped output into clean static HTML/CSS; strip builder junk (tracking scripts, builder CSS bloat); rewrite internal links; generate _redirects for old URL structures (wisp.place supports _redirects and .wispignore — confirmed in the wisp.place monorepo).
  3. Identity setup — generate did:web document (did.json) for the business domain, or register a did:plc; produce DNS instructions (_atproto TXT record for handle verification).
  4. PDS provisioning — guided checklist for a managed PDS (Protobase.at or similar) or self-host option; account creation, handle = business domain.
  5. Deploy — push the ported site to wisp.place via wispctl / npm create wisp (both confirmed as the official deploy paths in the wisp.place monorepo).
  6. Repo setup — init a Tangled repo for the site source; optionally emit a .tangled/workflows/deploy.yml Spindle workflow so future pushes auto-deploy (Spindle supports push-triggered YAML pipelines with repo secrets — see Tangled Spindle docs; note: a deploy-to-wisp workflow template does not yet exist publicly and would be a novel contribution).
  7. Verification — post-deploy checks: site up, did.json resolves, handle verifies, redirects work. (Pattern precedent: atprotozoa's audit/ health-check scripts.)
  • Language: TypeScript — the #1 language in the analyzed ecosystem (4/9 repos), and the language of wisp.place's own tooling.
  • Runtime: Bun — used by airglow; fast single-binary CLI story.
  • Form factor: CLI (npx create-atproto-migration style) + a template repo on Tangled. Matches wisp.place's own npm create wisp convention.
  • ATProto access: prefer light/vendorable libs over heavy SDKs for the CLI (ecosystem norm: hand-rolled oauth.js/identity.js; infra projects use real libs — wisp's Rust CLI uses Jacquard). For TS: atcute or @atproto/api for uploadBlob/putRecord calls if not shelling out to wispctl.
  • Scraping: headless fetch + HTML rewriting (e.g. cheerio/linkedom); WordPress XML importer as a fast path.
  • No backend needed — the entire pipeline is local CLI + PDS writes, consistent with the ecosystem's static-first pattern.

5. Known Constraints & Open Questions#

  • wisp.place limits: file-size/blob limits per PDS, manifest size, supported MIME types — need to verify against the wisp.place monorepo source (apps/main-app, cli/); README-level docs confirmed only .wispignore and _redirects.
  • did:web vs did:plc: did:web ties identity to the domain (good for businesses, breaks if domain lapses); did:plc is portable. Toolkit should support both and explain the tradeoff.
  • Scraping legality/ToS: exporting one's own site is fine; automated crawling of Wix/Weebly may hit anti-bot measures — need per-platform export strategies.
  • Dynamic features: contact forms, e-commerce, booking widgets don't port to static hosting. Scope v1 to brochure sites; document escape hatches (formsubmit-style services, or a companion Worker).
  • PDS provisioning API: does Protobase.at expose programmatic account creation, or is this stage necessarily a human checklist? Unverified.
  • Spindle runner availability: Spindle CI requires a self-hosted runner; the auto-deploy stage (§3.6) should degrade gracefully to manual wispctl deploy.

6. Competitive Landscape (from the analysis)#

  • No tool in the analyzed set automates any of this; ptharbor is the only migration artifact and it is fully manual.
  • wisp.place provides deploy tooling (wispctl, npm create wisp) but nothing for sourcing content from legacy platforms.
  • Broader ecosystem: no known "Wix-to-ATProto" tool exists; adjacent prior art is WordPress→static exporters (Simply Static, wp2static) which solve only stage 2.

7. Suggested First Milestones#

  1. M0 — Manual playbook: write the ptharbor process as a step-by-step doc; validates the pipeline before automating.
  2. M1 — wisp-port CLI: scrape URL → clean static bundle → _redirects → wispctl deploy. (Stages 1, 2, 5.)
  3. M2 — Identity module: did:web generator + DNS instruction output + verification checks. (Stages 3, 7.)
  4. M3 — Full create-atproto-migration wizard: interactive CLI covering all 7 stages, Tangled repo + Spindle template emission.
Sign up or login to add to the discussion