backlinkflow 0.1.0

package/CREDITS.md

@@ -0,0 +1,63 @@
+# LinkFlow — Sources & Credits
+
+LinkFlow's directory database (`data/directories.yaml`) is an independent,
+deduplicated compilation built by merging factual directory listings (site
+names + submission URLs) from the open-source projects below.
+
+**What we take:** factual data only — site name, submission URL, and (where
+the source provided it) domain authority / price model / status.
+
+**What we write ourselves:** all descriptions/notes are LinkFlow's own
+(never copied verbatim from sources), plus the `auto`, `lang`, `category`,
+and `status` enrichment fields.
+
+Per-entry provenance is embedded in the data itself: entries carry a
+`notes: [from <source>]` marker so any entry can be traced back here.
+
+---
+
+## Sources (11)
+
+| # | Project | License | Used for |
+|---|---------|---------|----------|
+| 1 | [s87343472/backlink-pilot](https://github.com/s87343472/backlink-pilot) | MIT | Base target set (258 sites, richest metadata: `auto`/`status`/`notes`); architecture reference for the automation engine |
+| 2 | [mmccaff/PlacesToPostYourStartup](https://github.com/mmccaff/PlacesToPostYourStartup) | CC0-1.0 | Subreddits + website launch platforms (from the canonical "Ask HN" thread) |
+| 3 | [BossChow/ultimate-submit-list](https://github.com/BossChow/ultimate-submit-list) | no license | Top-100 directory table (names + submit links) |
+| 4 | [theshubh77/awesome-saas-directories](https://github.com/theshubh77/awesome-saas-directories) | CC0-1.0 | SaaS launch platforms + submit links + DR |
+| 5 | [rushout09/directory-submission-sites](https://github.com/rushout09/directory-submission-sites) | GPL-3.0 | 250+ site list (names + URLs only) |
+| 6 | [best-of-ai/ai-directories](https://github.com/best-of-ai/ai-directories) | MIT | AI directories (names + URLs) |
+| 7 | [submitdirectories/submitdirectories](https://github.com/submitdirectories/submitdirectories) | no license | AI/SaaS/Tool/Startup lists with DA + submit URLs |
+| 8 | [nilandev/startup-directories](https://github.com/nilandev/startup-directories) | no license | Startup directories + subreddits |
+| 9 | [mahseema/awesome-saas-directories](https://github.com/mahseema/awesome-saas-directories) | MIT | SaaS directories |
+| 10 | [DirectorySurf/awesome-launch-platforms](https://github.com/DirectorySurf/awesome-launch-platforms) | MIT | Launch platforms |
+| 11 | [volodstaimi/Startup-Launch-List](https://github.com/volodstaimi/Startup-Launch-List) | MIT | 580+ startup directory list (names + URLs) — entries live-verified; dead ones marked `status: dead` |
+
+Also referenced for methodology (not data):
+- [swyxio/launch-cheatsheet](https://github.com/swyxio/launch-cheatsheet) — launch playbooks (archived)
+- [AIDevGTM/gtm-cofounder](https://github.com/AIDevGTM/gtm-cofounder) — GTM strategy skills
+- [naxiaoduo/1000UserGuide](https://github.com/naxiaoduo/1000UserGuide) — original source backlink-pilot's `targets.yaml` derives from
+
+---
+
+## License notes
+
+- **MIT sources** (backlink-pilot, best-of-ai, mahseema, DirectorySurf,
+  Startup-Launch-List): attribution satisfied by this file.
+- **CC0 sources** (mmccaff, theshubh77): public domain; credit retained as
+  good practice.
+- **GPL-3.0 source** (rushout09): only factual names/URLs are incorporated
+  (facts are not copyrightable); no code or creative expression was taken.
+  If you require strict GPL-cleanliness, remove the 4 unique entries from
+  `directory-submission-sites` and regenerate (`linkflow db:regenerate`).
+- **No-license sources** (BossChow, submitdirectories, nilandev): used for
+  factual data only (names + URLs). If your legal review requires it, these
+  can be dropped by removing the corresponding source files from
+  `scripts/sources/` and regenerating.
+
+## Regeneration
+
+`scripts/regenerate-db.py` rebuilds the database from the vendored source
+files in `scripts/sources/`. Delete a source file there → re-run
+`linkflow db:regenerate` → that source's entries are gone.
+
+LinkFlow itself is MIT (see LICENSE).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sankalp Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,320 @@
+<div align="center">
+
+# LinkFlow
+
+**Zero-cost backlink & directory submission engine for indie hackers.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A518-green.svg)](./package.json)
+[![Part of the flow series](https://img.shields.io/badge/flow--series-LinkFlow%20%7C%20SeoFlow%20%7C%20SECflow-blueviolet)](#the-flow-series)
+
+*1,123 vetted directories · AI-tailored submission copy · Playwright browser automation · proof-of-submission reports — no SaaS, no credits, no $79 upsell.*
+
+</div>
+
+---
+
+> **TL;DR** — Submitator, ListingBott, BoringLaunch charge $29–499 to do what LinkFlow does for free: a curated directory list, AI-generated per-directory copy, browser automation, and a status report. The only thing you bring is your own AI endpoint (OmniRoute, OpenAI, or any OpenAI-compatible API). Live-verified. MIT licensed.
+
+**The what:**
+
+| | What it does | How |
+|---|---|---|
+| **Database** | 1,123 directories across 9 categories (SaaS, AI, travel, startup, general, community, reddit, etc.) | Merged from 11 open-source lists, deduped, live-verified |
+| **AI copy** | Per-directory tagline + description matching your site's voice | Your AI endpoint (OpenAI-compatible) |
+| **Automation** | Real browser submissions via Playwright (`--go`) | Headless Chromium + smart field detection |
+| **Proof** | Screenshots + per-directory markdown report | `.linkflow/report.md` + `.linkflow/proofs/*.png` |
+| **Curation** | `db:review` flags dead links / homepage-as-submit | Idempotent regeneration from sources |
+| **Cost** | $0 (you provide the AI endpoint, typically free) | No paid APIs, no SaaS subscription |
+
+---
+
+## Why LinkFlow?
+
+Every paid directory-submission service is the same three things wrapped in a dashboard:
+
+1. **A list of where to submit** — this is open data
+2. **Per-directory copy** — this is a 5-line AI call
+3. **A status report** — this is a JSON file + a markdown table
+
+LinkFlow gives you all three, plus actual browser automation for sites with open forms. The moat is honesty: 876 directories live-verified, 221 marked dead with reason, 26 marked paid. No padding with self-owned link farms. No "AI" that means "Army of Indians."
+
+**vs competitors:**
+
+| | LinkFlow | Submitator | ListingBott | BoringLaunch |
+|---|---|---|---|---|
+| Directories | 1,123 (876 alive) | ~150 | ~250 | ~200 |
+| Cost | $0 | $29–79 | $499 | $249 |
+| Time to submit | 24–48h (with `--go`) | 24–48h | 1 month | 7 days |
+| Your AI endpoint | ✅ | ❌ | ❌ | ❌ |
+| Self-hostable | ✅ | ❌ | ❌ | ❌ |
+| Source list | ✅ CREDITS.md | ❌ proprietary | ❌ | ❌ |
+| Badges handled | manual (v0.3) | ✅ | ✅ | ❌ |
+| Open source | ✅ MIT | ❌ | ❌ | ❌ |
+
+---
+
+## Install
+
+```bash
+# from source
+git clone https://github.com/imsankz/linkflow.git
+cd linkflow && npm install && npm run build
+
+# or (when published)
+npm install -g linkflow
+```
+
+## Quick start
+
+```bash
+# 1. Create config
+linkflow init
+
+# 2. Edit linkflow.config.json + .env.local (AI endpoint)
+#    AI_BASE_URL=http://192.168.0.254:20128/v1  (OmniRoute)
+#    AI_API_KEY=...  AI_MODEL=auto/best-free
+
+# 3. Explore the database
+linkflow stats
+linkflow list --category startup --limit 10
+linkflow search "product hunt"
+
+# 4. Generate AI-tailored submission copy (no submission)
+linkflow payload https://yoursite.com --directory "Future Tools"
+
+# 5. Plan submissions (dry-run — nothing recorded)
+linkflow submit https://yoursite.com --dry-run --limit 10
+
+# 6. Real automation — Playwright browser submits for you
+linkflow submit https://yoursite.com --go --limit 10
+
+# 7. Track + report
+linkflow status
+linkflow report   # → .linkflow/report.md (Submitator-style proof)
+```
+
+## Multiple sites, one tool
+
+LinkFlow is generic — bring your own site config. Each product = one config file:
+
+```bash
+# SaaS product
+linkflow submit https://kreatorlane.com --config examples/linkflow.config.kreatorlane.json --category startup --go --limit 5
+
+# Travel blog
+linkflow submit https://chasingwhereabouts.com --config examples/linkflow.config.chasingwhereabouts.json --category travel --go --limit 5
+```
+
+No hardcoded sites. Examples in `examples/`.
+
+---
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `linkflow list [--category X] [--limit N]` | List directories in the database |
+| `linkflow search <query>` | Search directories by name/notes/URL |
+| `linkflow submit <url> [--dry-run] [--limit N] [--category X] [--go] [--config file.json]` | Generate payloads + submit. `--go` = real Playwright automation |
+| `linkflow payload <url> [--directory X]` | AI-tailored submission copy only |
+| `linkflow status` | Tracker summary (submitted/pending/failed) |
+| `linkflow report` | Regenerate proof-of-submission report |
+| `linkflow stats` | Database stats (counts by category, alive/dead) |
+| `linkflow db:review` | Flag DB quality issues (dead links, homepage-as-submit) |
+| `linkflow db:regenerate` | Rebuild DB from source lists |
+| `linkflow init` | Write config template |
+
+---
+
+## Database
+
+```
+ai: 331   startup: 612   general: 80   travel: 26
+ai-zh: 33  general-zh: 14  community: 13  reddit: 10  awesome: 4
+TOTAL: 1,123  ·  auto-submittable: 183  ·  alive: 876  ·  dead: 221  ·  paid: 26
+```
+
+Every URL was **live-verified** via concurrent HTTP + DNS resolution — 76 truly dead (DNS), 79 with dead submit paths (HTTP 404), 6 connection refused, 29 timeout-confirmed. Soft-errors (402/500/526) are flagged but not killed (may be transient).
+
+**Source coverage** (11 lists, all credited in [CREDITS.md](./CREDITS.md)):
+
+| Source | Stars | Type |
+|---|---|---|
+| [s87343472/backlink-pilot](https://github.com/s87343472/backlink-pilot) | ⭐348 | Base target set (rich metadata) |
+| [mmccaff/PlacesToPostYourStartup](https://github.com/mmccaff/PlacesToPostYourStartup) | ⭐6,881 | Canonical "Ask HN" directory list |
+| [theshubh77/awesome-saas-directories](https://github.com/theshubh77/awesome-saas-directories) | ⭐56 | SaaS launch platforms |
+| [best-of-ai/ai-directories](https://github.com/best-of-ai/ai-directories) | ⭐868 | AI tool directories |
+| [volodstaimi/Startup-Launch-List](https://github.com/volodstaimi/Startup-Launch-List) | ⭐8 | 580+ startup directories |
+| [BossChow/ultimate-submit-list](https://github.com/BossChow/ultimate-submit-list) | ⭐151 | Top-100 directory table |
+| [rushout09/directory-submission-sites](https://github.com/rushout09/directory-submission-sites) | ⭐12 | 250+ free sites |
+| [submitdirectories/submitdirectories](https://github.com/submitdirectories/submitdirectories) | ⭐9 | AI/SaaS/Tool/Startup lists |
+| [nilandev/startup-directories](https://github.com/nilandev/startup-directories) | ⭐26 | Subreddits + directories |
+| [mahseema/awesome-saas-directories](https://github.com/mahseema/awesome-saas-directories) | ⭐242 | SaaS directories |
+| [DirectorySurf/awesome-launch-platforms](https://github.com/DirectorySurf/awesome-launch-platforms) | ⭐252 | Launch platforms |
+
+Per-entry provenance is in the data itself: `notes: [from <source>]` in the YAML.
+
+---
+
+## Configuration
+
+`linkflow.config.json`:
+
+```json
+{
+  "siteName": "My Product",
+  "siteUrl": "https://example.com",
+  "siteDescription": "A short, honest description.",
+  "tags": ["saas", "devtools"],
+  "contentDomain": "SaaS product",
+  "writingSample": "2-3 sentences in your site voice",
+  "ai": {
+    "provider": "openai",
+    "baseUrl": "http://192.168.0.254:20128/v1",
+    "apiKey": "your-omniroute-key",
+    "model": "auto/best-free",
+    "maxCallsPerRun": 20
+  },
+  "pacing": { "minSeconds": 60, "perDay": 10 }
+}
+```
+
+`.env.local` (overrides config):
+
+```bash
+AI_PROVIDER=openai
+AI_BASE_URL=http://192.168.0.254:20128/v1
+AI_API_KEY=sk-...
+AI_MODEL=auto/best-free
+```
+
+Works with any OpenAI-compatible endpoint:
+- [OmniRoute](https://github.com/...) (free, local)
+- OpenAI, Anthropic, Groq, OpenRouter
+- LM Studio, Ollama, vLLM (local)
+- Any custom server
+
+The AI client is **SSE-tolerant** — works with providers that stream even when `stream: false` is requested (OmniRoute).
+
+---
+
+## Database curation
+
+The directory database is the product's moat. `scripts/regenerate-db.py` rebuilds it idempotently from the 11 source lists (annotated `[from <source>]`). `linkflow db:review` flags quality issues.
+
+**Review verdict:**
+- **1,123 entries**, 9 categories — full coverage from all 11 sources
+- **876 verified alive** — every URL live-checked via `scripts/check-urls.py` (concurrent HTTP + DNS verification)
+- **221 verified dead** — marked `status: dead` with reason
+- **26 paid** — carry explicit `status: paid`
+- **183 auto-submittable** (real form adapters via Playwright)
+- **~420 "homepage-as-submit"** flags are alive directories whose real submit pages need discovery — ongoing curation task
+
+**Curation workflow:**
+
+```bash
+python3 scripts/check-urls.py /tmp/linkflow-urls.txt   # live-check all URLs
+python3 scripts/apply-urlcheck.py                      # mark verified-dead in DB
+linkflow db:review                                     # see remaining flags
+linkflow db:regenerate                                 # rebuild from sources (idempotent)
+linkflow stats                                         # confirm counts
+```
+
+---
+
+## The flow series
+
+LinkFlow is the third in a series of zero-cost CLI tools, all MIT, all npm-published:
+
+| Tool | Job | Engines | npm |
+|---|---|---|---|
+| **[SECflow](https://github.com/imsankz/SECflow)** | Security scanning for AI-driven repos | gitleaks, trivy, npm audit, custom regex | [`secflow`](https://www.npmjs.com/package/secflow) |
+| **[SeoFlow](https://github.com/imsankz/seoflow)** | AI-powered SEO pipeline (audit, internal links, content gen, GSC) | GSC, PSI, Pexels, Ubersuggest, 6 LLMs | [`seoflow`](https://www.npmjs.com/package/seoflow) |
+| **[LinkFlow](https://github.com/imsankz/linkflow)** | Backlink & directory submission automation | Your AI endpoint + Playwright | [`linkflow`](https://www.npmjs.com/package/linkflow) (this repo) |
+
+Same DNA across all three: **free engines + your own AI agent as the "smart" layer + npm-published + zero-cost.**
+
+---
+
+## Architecture
+
+```
+linkflow submit <url> --go
+        ↓
+   config loader (linkflow.config.json + .env.local)
+        ↓
+   payload generator (AI + template fallback)
+        ↓
+   database (1,123 directories, 9 categories)
+        ↓
+   for each target:
+        ↓
+   preflight HTTP check ── dead ──→ mark failed
+        ↓
+   launch Chromium ──→ navigate submit URL
+        ↓
+   detect fields (name/url/email/description)
+        ↓
+   site adapter (generic | saashub | ph)
+        ↓
+   fill + submit
+        ↓
+   verify (success message, redirect)
+        ↓
+   screenshot → .linkflow/proofs/
+        ↓
+   record → .linkflow/tracker.json
+        ↓
+   report → .linkflow/report.md
+        ↓
+   pacing → next directory (per-day limit)
+```
+
+```
+src/
+  index.ts                # CLI entry
+  config.ts               # config + .env loader
+  database.ts             # YAML loader + search
+  payload.ts              # AI + template payload gen
+  ai.ts                   # OpenAI-compat client (SSE-tolerant)
+  tracker.ts              # submission history
+  report.ts               # proof-of-submission markdown
+  types.ts                # shared interfaces
+  engine/
+    browser.ts            # Playwright wrapper
+    fields.ts             # smart field detection
+    adapters.ts           # site-specific + generic adapter
+    submit.ts             # orchestration: preflight → fill → verify
+
+data/directories.yaml     # 1,123 vetted directories
+scripts/
+  regenerate-db.py        # idempotent DB rebuild
+  review-db.py            # quality flagger
+  check-urls.py           # live URL checker
+  apply-urlcheck.py       # mark verified-dead
+  sources/                # 18 vendored source files
+examples/                 # 2 example site configs
+```
+
+---
+
+## Roadmap
+
+- [x] **v0.1** — directory DB, AI payloads, tracker, reports
+- [x] **v0.2** — Playwright automation engine (`--go`), site adapters, pacing, proof screenshots
+- [ ] **v0.3** — GitHub awesome-list PR generator, IndexNow pings
+- [ ] **v0.4** — seoflow integration (measure backlinks before/after submission)
+- [ ] **v0.5** — Badge-handling component (the Submitator moat we haven't replicated)
+
+---
+
+## License
+
+MIT (see [LICENSE](./LICENSE)). Source data compiled from 11 open-source projects — see [CREDITS.md](./CREDITS.md) for per-source licenses and provenance.
+
+---
+
+## ☕ Support
+
+LinkFlow is free forever. If it saves you $79 (or 40 hours), [buy me a coffee](https://ko-fi.com/chasingwhereabouts) — it funds more free tools.

package/bin/linkflow.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * LinkFlow CLI launcher.
+ * Resolves the built dist/index.js and runs it as the CLI.
+ */
+import { createRequire } from 'module';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Prefer dist build; fall back to src via tsx if not built (dev mode)
+try {
+  await import(path.join(__dirname, '..', 'dist', 'index.js'));
+} catch (err) {
+  if (err.code === 'ERR_MODULE_NOT_FOUND' || err.code === 'ERR_REQUIRE_ESM') {
+    console.error('LinkFlow: dist not built. Run `npm run build` first.');
+    process.exit(1);
+  }
+  throw err;
+}