dirpush 0.0.0 → 0.1.1

package/src/listings.ts

@@ -0,0 +1,64 @@
+/** Is a submitted listing publicly live? Used by `submissions check`. */
+
+const UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130 Safari/537.36";
+// Some directories publish the page before approval ("the approval team will review it").
+const NOT_YET = /will review it|pending (approval|review)|awaiting (approval|review)|under review/i;
+
+export const isLive = (body: string, host: string) => body.includes(host) && !NOT_YET.test(body);
+
+/** Path segment naming the product: "ledgerline", "ledgerline-com", "ledgerline-1234" — not "ledgerlinex". */
+export const matchesSlug = (url: string, slugs: string[]) => {
+  const path = (() => { try { return new URL(url).pathname.toLowerCase(); } catch { return ""; } })();
+  return path.split("/").some((seg) => slugs.some((s) => seg === s || seg.startsWith(`${s}-`)));
+};
+
+export const locs = (xml: string) => [...xml.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/g)].map((m) => m[1]!.replace(/&amp;/g, "&"));
+
+const get = (url: string) =>
+  fetch(url, { redirect: "follow", headers: { "user-agent": UA }, signal: AbortSignal.timeout(20_000) })
+    .then(async (r) => ({ status: r.status, body: r.ok ? await r.text() : "" }))
+    .catch((e: Error) => ({ status: 0, body: "", error: e.message }));
+
+/** Listing URL from the directory's sitemap(s), for directories with no known URL pattern. */
+export async function findInSitemap(site: string, slugs: string[]) {
+  const origin = new URL(site).origin;
+  const robots = (await get(`${origin}/robots.txt`)).body;
+  const queue = [...robots.matchAll(/^sitemap:\s*(\S+)/gim)].map((m) => m[1]!);
+  if (!queue.length) queue.push(`${origin}/sitemap.xml`);
+  // ponytail: fetches at most 30 sitemap files per directory; huge directories may hide the listing deeper.
+  for (let i = 0; i < queue.length && i < 30; i++) {
+    const xml = (await get(queue[i]!)).body;
+    const urls = locs(xml);
+    if (/<sitemapindex/i.test(xml)) queue.push(...urls);
+    else {
+      const hit = urls.find((u) => matchesSlug(u, slugs));
+      if (hit) return hit;
+    }
+  }
+}
+
+/** Rendered page in a throwaway anonymous browser: client-rendered pages and sites that serve fetch a different page. */
+function render(url: string, session: string) {
+  const ab = (...args: string[]) => Bun.spawnSync(["agent-browser", "--session", session, ...args], { stderr: "pipe", timeout: 60_000 });
+  if (ab("open", url).exitCode) return;
+  ab("wait", "2000");
+  const out = ab("eval", `JSON.stringify([location.href, document.body.innerText + [...document.querySelectorAll("a[href]")].map(a => a.href).join(" ")])`);
+  try {
+    let v = JSON.parse(out.stdout.toString());
+    if (typeof v === "string") v = JSON.parse(v);
+    return { finalUrl: v[0] as string, body: v[1] as string };
+  } catch {}
+}
+
+export async function checkListing(url: string, host: string, slugs: string[], session: string) {
+  const res = await get(url);
+  if (isLive(res.body, host)) return { live: true, how: "fetch" };
+  if (res.status === 404 || res.status === 410) return { live: false, how: `not yet (${res.status})` };
+  // Fetch saw no listing (bot wall, JS-only page, soft 404) → look like a person.
+  const page = render(url, session);
+  // A redirect to the homepage can still show the product in a "recent" list; that's not its listing.
+  const live = !!page && matchesSlug(page.finalUrl, slugs) && isLive(page.body, host);
+  return { live, how: live ? "browser" : `not yet (${res.status || ("error" in res && res.error)}, browser: ${page ? "no listing" : "failed"})` };
+}
+
+export const closeBrowser = (session: string) => Bun.spawnSync(["agent-browser", "--session", session, "close"], { stderr: "ignore" });

package/src/manual.ts

@@ -0,0 +1,26 @@
+import type { Db } from "./db";
+import * as J from "./jobs";
+import { loadDirectories, normalizeUrl } from "./registry";
+
+/**
+ * Records a listing the human made outside the agents. `target` is a registry id or any URL: a URL that
+ * matches a registry directory's site maps to it, anything else is tracked under its domain.
+ */
+export async function addManualSubmission(db: Db, productId: string, target: string, outcome: J.Outcome, listingUrl?: string) {
+  if (!["pending", "live", "rejected"].includes(outcome)) throw new Error("outcome must be pending, live or rejected");
+  const dirs = await loadDirectories();
+  let subject = dirs.find((d) => d.id === target)?.id;
+  if (!subject) {
+    let domain: string;
+    try {
+      domain = normalizeUrl(target).domain;
+    } catch {
+      throw new Error(`${target} is neither a registry directory id nor a URL`);
+    }
+    const matches = dirs.filter((d) => normalizeUrl(d.website).domain === domain).map((d) => d.id);
+    if (matches.length > 1) throw new Error(`${domain} matches several directories (${matches.join(", ")}); pass the id`);
+    subject = matches[0] ?? domain;
+  }
+  const job = J.enqueue(db, "submission", subject, productId);
+  return { ...J.recordManual(db, job.id, outcome, listingUrl?.trim() || undefined), inRegistry: dirs.some((d) => d.id === subject) };
+}

package/src/product-approvals.ts

@@ -0,0 +1,31 @@
+import { and, desc, eq, inArray } from "drizzle-orm";
+import type { Db } from "./db";
+import { productApprovals } from "./db/schema";
+
+export function requestProductApproval(db: Db, input: { productId: string; action: string; message: string }) {
+  const existing = db.select().from(productApprovals)
+    .where(and(eq(productApprovals.productId, input.productId), eq(productApprovals.action, input.action), inArray(productApprovals.status, ["pending", "approved"])))
+    .orderBy(desc(productApprovals.id)).get();
+  if (existing) return existing;
+  return db.insert(productApprovals).values({ ...input, status: "pending" }).returning().get();
+}
+
+export function resolveProductApproval(db: Db, id: number, status: "approved" | "rejected") {
+  const row = db.update(productApprovals).set({ status, resolvedAt: Date.now() })
+    .where(and(eq(productApprovals.id, id), eq(productApprovals.status, "pending"))).returning().get();
+  if (!row) throw new Error(`product approval ${id} is not pending`);
+  return row;
+}
+
+export function approvedProductAction(db: Db, productId: string, action: string) {
+  return db.select().from(productApprovals)
+    .where(and(eq(productApprovals.productId, productId), eq(productApprovals.action, action), eq(productApprovals.status, "approved")))
+    .orderBy(desc(productApprovals.id)).get();
+}
+
+export function consumeProductApproval(db: Db, id: number) {
+  const row = db.update(productApprovals).set({ status: "used", resolvedAt: Date.now() })
+    .where(and(eq(productApprovals.id, id), eq(productApprovals.status, "approved"))).returning().get();
+  if (!row) throw new Error(`product approval ${id} is not approved`);
+  return row;
+}

package/src/public.ts

@@ -0,0 +1,24 @@
+/**
+ * The registry is shared and published: it must say what a directory is like, never what one product or one
+ * operator did there. These helpers drop whole sentences that mention a workspace product, an operator, or
+ * internal tooling.
+ */
+const INTERNAL = /workspace\/|\bdata\/|permissions?\.yaml|add_backlink|money\.spend|external\.\w|per (your|the user'?s?) instruction|\bvault\b|launch work|bun launch|agent-browser|scripts\/ab|LAUNCH_\w+|@gmail\.com|automatic review (rejected|blocked)|evidence: data/i;
+
+export function scrubber(productWords: string[]) {
+  const names = productWords.filter((w) => w.length >= 3).map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  const product = names.length ? new RegExp(`\\b(${names.join("|")})\\b`, "i") : null;
+  const bad = (s: string) => INTERNAL.test(s) || (product?.test(s) ?? false);
+  /** Keeps every sentence (or markdown line) that says nothing about a specific product or operator. */
+  const text = (t: string) => (t.split(/(?<=[.!?])\s+|\n/).some(bad) ? clean(t) : t);
+  const clean = (t: string) =>
+    t
+      .split("\n")
+      .map((line) => line.split(/(?<=[.!?])\s+/).filter((s) => !bad(s)).join(" "))
+      .filter((line, i, all) => line.trim() !== "" || (i > 0 && all[i - 1]!.trim() !== "" && !/^\s*[-*]\s*$/.test(all[i - 1]!)))
+      .filter((line) => !/^\s*[-*]\s*$/.test(line))
+      .join("\n")
+      .replace(/\n{3,}/g, "\n\n")
+      .trim();
+  return { text, bad };
+}

package/src/ratings.ts

@@ -0,0 +1,71 @@
+import { desc, inArray } from "drizzle-orm";
+import type { Db } from "./db";
+import { domainRatings } from "./db/schema";
+
+/** Ahrefs' free Domain Rating endpoint. Bring your own key via AHREFS_API_KEY; never a flag or file. */
+const ENDPOINT = "https://api.ahrefs.com/v3/public/domain-rating-free";
+const BATCH_SIZE = 80;
+export const RATING_TTL = 7 * 24 * 60 * 60 * 1000;
+
+export function ratingDomain(website: string): string {
+  try {
+    return new URL(website.includes("://") ? website : `https://${website}`).hostname.replace(/^www\./, "").toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+// A list hosted on a platform (a GitHub repo, a Notion page) would inherit the platform's DR, which says nothing about the list.
+const PLATFORM = /^(github\.com|gitlab\.com|[\w-]+\.notion\.site|notion\.so|medium\.com|[\w-]+\.substack\.com|reddit\.com|docs\.google\.com)$/;
+export const platformHosted = (website: string) => PLATFORM.test(ratingDomain(website));
+
+/** Every reading per domain, newest first. */
+export function ratingHistory(db: Db, websites: string[]) {
+  const domains = [...new Set(websites.map(ratingDomain).filter(Boolean))];
+  const rows = domains.length
+    ? db.select().from(domainRatings).where(inArray(domainRatings.domain, domains)).orderBy(desc(domainRatings.measuredAt)).all()
+    : [];
+  const byDomain = new Map(domains.map((d) => [d, [] as { measuredAt: number; rating: number }[]]));
+  for (const r of rows) byDomain.get(r.domain)!.push({ measuredAt: r.measuredAt, rating: r.rating });
+  return byDomain;
+}
+
+export function recordRating(db: Db, domain: string, rating: number, measuredAt: number) {
+  db.insert(domainRatings).values({ domain, rating, measuredAt }).onConflictDoNothing().run();
+}
+
+type Fetch = (url: string, init: RequestInit) => Promise<Response>;
+
+/** Measures every domain not read in the last week (or all with `force`). One POST per batch of 80. */
+export async function refreshRatings(
+  db: Db,
+  websites: string[],
+  { apiKey, force = false, now = Date.now(), fetcher = fetch as Fetch }: { apiKey: string; force?: boolean; now?: number; fetcher?: Fetch },
+) {
+  const history = ratingHistory(db, websites);
+  const due = [...history].filter(([, h]) => force || !h[0] || now - h[0].measuredAt >= RATING_TTL).map(([d]) => d);
+  const measured: Record<string, number> = {};
+  for (let i = 0; i < due.length; i += BATCH_SIZE) {
+    const chunk = due.slice(i, i + BATCH_SIZE);
+    const res = await fetcher(`${ENDPOINT}?output=json`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json", "Content-Type": "application/json" },
+      body: JSON.stringify({ targets: chunk, version: "dr3" }),
+      redirect: "manual",
+      signal: AbortSignal.timeout(15000),
+    });
+    if (!res.ok) {
+      await res.body?.cancel();
+      throw new Error(res.status === 401 || res.status === 403 ? "Ahrefs rejected AHREFS_API_KEY" : `Ahrefs returned HTTP ${res.status}`);
+    }
+    const data = (await res.json()) as { domain_rating?: { targets?: { target?: unknown; domain_rating?: unknown }[] } };
+    for (const entry of data.domain_rating?.targets ?? []) {
+      const domain = typeof entry.target === "string" ? ratingDomain(entry.target) : "";
+      const value = entry.domain_rating;
+      if (!chunk.includes(domain) || typeof value !== "number" || !(value >= 0 && value <= 100)) continue;
+      recordRating(db, domain, value, now);
+      measured[domain] = value;
+    }
+  }
+  return { checked: due.length, skipped: history.size - due.length, measured };
+}

package/src/registry-updates.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { Directory, loadDirectories, loadDirectory, writeDirectory } from "./registry";
+
+/** Where `registry updates` looks unless LAUNCH_REGISTRY_URL or --url says otherwise. Built by scripts/build-site.ts and redeployed monthly. */
+export const DEFAULT_REGISTRY_URL = "https://dirpush.com/registry.json";
+export const registrySource = () => process.env.LAUNCH_REGISTRY_URL ?? DEFAULT_REGISTRY_URL;
+
+/** The published registry: every verified directory plus its playbook. Built by scripts/build-registry.ts. */
+export const RegistryFile = z.object({
+  revision: z.string(),
+  generatedAt: z.string(),
+  directories: z.array(z.object({ directory: Directory, playbook: z.string().nullable() })),
+});
+export type RegistryFile = z.infer<typeof RegistryFile>;
+
+export async function buildRegistryFile(): Promise<RegistryFile> {
+  const dirs = (await loadDirectories()).sort((a, b) => a.id.localeCompare(b.id));
+  const directories = await Promise.all(dirs.map((d) => loadDirectory(d.id)));
+  const digest = new Bun.CryptoHasher("sha256").update(JSON.stringify(directories)).digest("hex");
+  return { revision: digest.slice(0, 16), generatedAt: new Date().toISOString(), directories };
+}
+
+/** `source`: an https URL or a local path to a registry.json. */
+export async function fetchRegistryFile(source: string) {
+  const text = /^https?:\/\//.test(source)
+    ? await fetch(source, { signal: AbortSignal.timeout(30000) }).then((r) => {
+        if (!r.ok) throw new Error(`registry download failed: HTTP ${r.status}`);
+        return r.text();
+      })
+    : await Bun.file(source).text();
+  return RegistryFile.parse(JSON.parse(text));
+}
+
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+
+/**
+ * Compares the published registry with the local one. A local entry verified more recently than the
+ * published copy is kept: that is a correction you made and haven't reported yet.
+ */
+export async function registryUpdates(remote: RegistryFile, apply = false) {
+  const local = new Map((await loadDirectories()).map((d) => [d.id, d]));
+  const added: string[] = [], changed: string[] = [], localNewer: string[] = [];
+  for (const { directory, playbook } of remote.directories) {
+    const mine = local.get(directory.id);
+    local.delete(directory.id);
+    if (!mine) added.push(directory.id);
+    else if (mine.verification.checked_at > directory.verification.checked_at) localNewer.push(directory.id);
+    else if (!same(mine, directory) || !same((await loadDirectory(directory.id)).playbook, playbook)) changed.push(directory.id);
+    else continue;
+    if (apply && !localNewer.includes(directory.id)) await writeDirectory(directory, playbook ?? undefined);
+  }
+  // Removed upstream: reported, never deleted, so nothing you rely on disappears silently.
+  return { revision: remote.revision, generatedAt: remote.generatedAt, applied: apply, added, changed, localNewer, onlyLocal: [...local.keys()].sort() };
+}

package/src/registry.ts

@@ -0,0 +1,101 @@
+import { cpSync, mkdirSync, readdirSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { HOME, PKG } from "./db";
+import { CLASSIFICATIONS } from "./db/schema";
+import { DIRECTORY_KINDS } from "./directory-kinds";
+
+/**
+ * Your copy of the registry. An installed package seeds ~/.dirpush/registry from the one it ships, once; after that
+ * `registry updates --apply` keeps it current, and edits never touch the package.
+ */
+export const REGISTRY = process.env.LAUNCH_REGISTRY ?? join(HOME, "registry/directories");
+if (!process.env.LAUNCH_REGISTRY && HOME !== PKG && !existsSync(REGISTRY)) cpSync(join(PKG, "registry/directories"), REGISTRY, { recursive: true });
+
+export const Directory = z.object({
+  id: z.string().regex(/^[a-z0-9-]+$/),
+  name: z.string(),
+  website: z.url(),
+  submission_url: z.url().nullable(),
+  cost: z.object({
+    classification: z.enum(CLASSIFICATIONS).exclude(["UNVERIFIED", "DEAD", "NOT_RELEVANT"]),
+    notes: z.string().optional(),
+  }),
+  audience: z.array(z.string()).default([]),
+  authentication: z.object({ required: z.boolean(), signup_allowed: z.boolean(), methods: z.array(z.string()).default([]) }),
+  submission: z.object({
+    url_first: z.boolean(),
+    fields: z.array(z.object({ name: z.string(), required: z.boolean(), limit: z.number().optional() })).default([]),
+    conditions: z.array(z.string()).default([]), // e.g. "backlink required", "manual review"
+  }),
+  autofetch: z.object({ supported: z.boolean(), expected: z.array(z.string()).default([]) }),
+  media: z.object({
+    logo: z.boolean(),
+    screenshots: z.object({ supported: z.boolean(), max: z.number().optional() }),
+  }),
+  // What kind of site this really is. Only "listing" is a plain directory submission; the rest need a human decision or timing.
+  kind: z.enum(Object.keys(DIRECTORY_KINDS) as [keyof typeof DIRECTORY_KINDS, ...(keyof typeof DIRECTORY_KINDS)[]]).optional(),
+  // Set when the site's bot check rejects the automated browser outright (why/where). Such directories are for the human.
+  human_only: z.string().nullable().optional(),
+  // Free-tier wait before a listing goes live, as the site states it ("instant", "3-4 months").
+  review_time: z.string().optional(),
+  // Where a listing appears once live, {slug} = product name lowercased; lets a plain script check pending listings.
+  listing_url_pattern: z.string().optional(),
+  // Measured by `registry audit` (no AI): what a listing's link is worth, read off real listing pages.
+  link: z
+    .object({
+      rel: z.enum(["dofollow", "nofollow", "ugc", "sponsored", "mixed", "unknown"]),
+      method: z.enum(["own_listing", "sample_listing", "platform_rule", "none"]),
+      evidence: z.string().nullable(),
+      samples: z.number(),
+      noindex: z.boolean().nullable(),
+      claimed: z.enum(["dofollow", "nofollow"]).nullable(),
+      bot_check: z.enum(["recaptcha", "turnstile", "hcaptcha", "math", "none", "unknown"]),
+      checked_at: z.string(),
+      // Why rel is still "unknown" after a real attempt: shown on the site instead of a bare "not measured".
+      unmeasured: z.enum(["no_listings", "no_outbound_link", "bot_wall", "login_required", "site_down"]).optional(),
+    })
+    .optional(),
+  verification: z.object({
+    status: z.literal("verified"),
+    checked_at: z.string(),
+    by: z.string().optional(),
+    sources: z.array(z.string()).default([]),
+  }),
+});
+export type Directory = z.infer<typeof Directory>;
+
+export function normalizeUrl(raw: string) {
+  const u = new URL(raw.trim().includes("://") ? raw.trim() : `https://${raw.trim()}`);
+  u.hash = "";
+  const domain = u.hostname.toLowerCase().replace(/^www\./, "");
+  return { domain, url: u.toString() };
+}
+
+export async function loadDirectories(): Promise<Directory[]> {
+  if (!existsSync(REGISTRY)) return [];
+  const ids = readdirSync(REGISTRY).filter((d) => existsSync(join(REGISTRY, d, "directory.yaml")));
+  return Promise.all(ids.map(async (id) => Directory.parse(Bun.YAML.parse(await Bun.file(join(REGISTRY, id, "directory.yaml")).text()))));
+}
+
+export async function loadDirectory(id: string) {
+  const dir = join(REGISTRY, id);
+  if (!existsSync(join(dir, "directory.yaml"))) throw new Error(`no such directory: ${id}`);
+  const directory = Directory.parse(Bun.YAML.parse(await Bun.file(join(dir, "directory.yaml")).text()));
+  const playbook = existsSync(join(dir, "playbook.md")) ? await Bun.file(join(dir, "playbook.md")).text() : null;
+  return { directory, playbook };
+}
+
+export async function writeDirectory(d: Directory, playbook?: string) {
+  const dir = join(REGISTRY, d.id);
+  mkdirSync(dir, { recursive: true });
+  await Bun.write(join(dir, "directory.yaml"), Bun.YAML.stringify(Directory.parse(d), null, 2));
+  if (playbook) await Bun.write(join(dir, "playbook.md"), playbook);
+}
+
+export function removeDirectory(id: string) {
+  const dir = join(REGISTRY, id);
+  if (!/^[a-z0-9-]+$/.test(id) || !existsSync(dir)) return false;
+  rmSync(dir, { recursive: true });
+  return true;
+}

package/src/review.ts

@@ -0,0 +1,58 @@
+import { and, eq } from "drizzle-orm";
+import type { Db } from "./db";
+import { galleries, jobs, productApprovals, registryChanges, todos } from "./db/schema";
+import { logEvent, unblock } from "./jobs";
+
+/** Human decisions, shared by the CLI and the dashboard. */
+export function reviewGallery(db: Db, revision: number, status: "approved" | "rejected") {
+  const row = db
+    .update(galleries)
+    .set({ status })
+    .where(and(eq(galleries.revision, revision), eq(galleries.status, "proposed")))
+    .returning()
+    .get();
+  if (!row) throw new Error(`gallery revision ${revision} is not awaiting review`);
+  logEvent(db, null, `gallery_${status}`, "human", { revision });
+  // Jobs parked on this product's gallery go back to the queue; the agent reads the decision.
+  const waiting = db
+    .select({ id: jobs.id })
+    .from(jobs)
+    .where(and(eq(jobs.productId, row.productId), eq(jobs.status, "blocked"), eq(jobs.blockType, "gallery_approval")))
+    .all();
+  for (const j of waiting) unblock(db, j.id, `gallery revision ${revision} ${status}`);
+  return row;
+}
+
+/** Accepting only marks the proposal; an agent applies it to registry/directories/<id>/directory.yaml. */
+export function reviewRegistryChange(db: Db, id: number, status: "accepted" | "rejected") {
+  const row = db
+    .update(registryChanges)
+    .set({ status })
+    .where(and(eq(registryChanges.id, id), eq(registryChanges.status, "proposed")))
+    .returning()
+    .get();
+  if (!row) throw new Error(`registry change ${id} is not awaiting review`);
+  logEvent(db, null, `registry_change_${status}`, "human", { changeId: id, directoryId: row.directoryId });
+  return row;
+}
+
+export function reviewProductApproval(db: Db, id: number, status: "approved" | "rejected") {
+  const row = db.update(productApprovals).set({ status, resolvedAt: Date.now() })
+    .where(and(eq(productApprovals.id, id), eq(productApprovals.status, "pending"))).returning().get();
+  if (!row) throw new Error(`product approval ${id} is not pending`);
+  logEvent(db, null, `product_approval_${status}`, "human", { approvalId: row.id, productId: row.productId, action: row.action });
+  return row;
+}
+
+export function addTodo(db: Db, todo: { productId?: string; jobId?: string; message: string; url?: string }) {
+  const row = db.insert(todos).values(todo).returning().get();
+  logEvent(db, todo.jobId ?? null, "todo_added", null, { todo: row.id, message: todo.message });
+  return row;
+}
+
+export function closeTodo(db: Db, id: number) {
+  const row = db.update(todos).set({ status: "done" }).where(and(eq(todos.id, id), eq(todos.status, "open"))).returning().get();
+  if (!row) throw new Error(`todo ${id} is not open`);
+  logEvent(db, row.jobId, "todo_done", "human", { todo: id });
+  return row;
+}

package/src/server.ts

@@ -0,0 +1,186 @@
+import { desc, eq, sql } from "drizzle-orm";
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { HOME, openDb, PKG } from "./db";
+import { events, galleries, jobs, productApprovals, registryChanges, todos } from "./db/schema";
+import * as J from "./jobs";
+import { loadDirectories, loadDirectory } from "./registry";
+import { addManualSubmission } from "./manual";
+import { platformHosted, ratingDomain, ratingHistory, refreshRatings } from "./ratings";
+import { fetchRegistryFile, registrySource, registryUpdates } from "./registry-updates";
+import { closeTodo, reviewGallery, reviewProductApproval, reviewRegistryChange } from "./review";
+import { loadIdentity, loadPermissions, loadProduct, productIds, WORKSPACE } from "./workspace";
+import index from "./web/index.html";
+
+/** Local dashboard: observability + human decisions. Agents use the CLI, not this. */
+export function serve(port: number, hostname = "127.0.0.1") {
+  const db = openDb();
+  const safe = (fn: () => unknown) => async () => {
+    try {
+      return Response.json(await fn());
+    } catch (e) {
+      return Response.json({ error: (e as Error).message }, { status: 400 });
+    }
+  };
+  const body = async (req: Request) => ((await req.json().catch(() => ({}))) ?? {}) as Record<string, string | undefined>;
+  /** Read-only files confined to `root` (screenshots for review and evidence). */
+  const files = (root: string, prefix: string) => (req: Request) => {
+    const path = resolve(root, decodeURIComponent(new URL(req.url).pathname.slice(prefix.length)));
+    if (!path.startsWith(resolve(root) + sep)) return new Response("forbidden", { status: 403 });
+    return new Response(Bun.file(path));
+  };
+  const EVIDENCE = join(HOME, "data/evidence");
+  const optional = async <T>(fn: () => Promise<T>) => fn().catch((e: Error) => ({ error: e.message }));
+
+  const server = Bun.serve({
+    port,
+    hostname,
+    development: process.env.NODE_ENV !== "production",
+    routes: {
+      "/": index,
+      "/api/overview": safe(() => ({
+        jobs: db.select({ kind: jobs.kind, status: jobs.status, n: sql<number>`count(*)` }).from(jobs).groupBy(jobs.kind, jobs.status).all(),
+        outcomes: db
+          .select({ outcome: jobs.outcome, n: sql<number>`count(*)` })
+          .from(jobs)
+          .where(eq(jobs.kind, "submission"))
+          .groupBy(jobs.outcome)
+          .all(),
+        activity: db.select().from(events).orderBy(desc(events.at)).limit(60).all(),
+      })),
+      "/api/actions": safe(() => ({
+        blocked: db.select().from(jobs).where(eq(jobs.status, "blocked")).all(),
+        unknown: db.select().from(jobs).where(eq(jobs.status, "unknown")).all(),
+        failed: db.select().from(jobs).where(eq(jobs.status, "failed")).all(),
+        galleries: db.select().from(galleries).where(eq(galleries.status, "proposed")).all(),
+        productApprovals: db.select().from(productApprovals).where(eq(productApprovals.status, "pending")).all(),
+        registryChanges: db.select().from(registryChanges).where(eq(registryChanges.status, "proposed")).all(),
+        todos: db.select().from(todos).where(eq(todos.status, "open")).all(),
+      })),
+      "/api/todos/:id/done": { POST: (req) => safe(() => closeTodo(db, Number(req.params.id)))() },
+      "/api/jobs": (req) =>
+        safe(() => {
+          const kind = new URL(req.url).searchParams.get("kind");
+          return db.select().from(jobs).where(eq(jobs.kind, kind === "research" ? "research" : "submission")).orderBy(desc(jobs.updatedAt)).all();
+        })(),
+      "/api/meta": safe(() => ({ registrySource: registrySource(), ahrefs: Boolean(process.env.AHREFS_API_KEY?.trim()) })),
+      // Latest DR per directory domain plus full history per product (newest first).
+      "/api/ratings": safe(async () => {
+        const products = (await Promise.all(productIds().map((id) => loadProduct(id).then((p) => ({ id, url: p.url })).catch(() => null)))).filter((p) => p !== null);
+        const directories = await loadDirectories();
+        const all = ratingHistory(db, [...products.map((p) => p.url), ...directories.map((d) => d.website)]);
+        return {
+          products: Object.fromEntries(products.map((p) => [p.id, all.get(ratingDomain(p.url)) ?? []])),
+          directories: Object.fromEntries(directories.map((d) => [d.id, platformHosted(d.website) ? null : all.get(ratingDomain(d.website))?.[0]?.rating ?? null])),
+        };
+      }),
+      "/api/ratings/refresh": {
+        POST: () =>
+          safe(async () => {
+            const apiKey = process.env.AHREFS_API_KEY?.trim();
+            if (!apiKey) throw new Error("Set AHREFS_API_KEY in the environment you start the dashboard from.");
+            const urls = (await Promise.all(productIds().map((id) => loadProduct(id).then((p) => p.url).catch(() => null)))).filter((u): u is string => !!u);
+            return refreshRatings(db, urls, { apiKey });
+          })(),
+      },
+      // Compares the published registry with the local one; { apply: true } writes the updates.
+      "/api/registry/updates": {
+        POST: async (req) => {
+          const { apply } = (await req.json().catch(() => ({}))) as { apply?: boolean };
+          return safe(async () => ({ source: registrySource(), checkedAt: Date.now(), ...(await registryUpdates(await fetchRegistryFile(registrySource()), apply === true)) }))();
+        },
+      },
+      "/api/jobs/:id": (req) =>
+        safe(async () => {
+          const job = db.select().from(jobs).where(eq(jobs.id, req.params.id)).get();
+          if (!job) throw new Error(`no such job: ${req.params.id}`);
+          const dir = join(EVIDENCE, job.id);
+          return {
+            job,
+            events: J.jobEvents(db, job.id),
+            evidence: /^[\w-]+$/.test(job.id) && existsSync(dir) ? readdirSync(dir).filter((f) => /\.(png|jpe?g|webp)$/i.test(f)).sort() : [],
+            directory: job.kind === "submission" ? (await optional(() => loadDirectory(job.subject).then((d) => d.directory))) : null,
+          };
+        })(),
+      "/api/jobs/:id/unblock": {
+        POST: async (req) => {
+          const { note, approve } = await body(req);
+          return safe(() => J.unblock(db, req.params.id, note?.trim() || (approve ? "approved" : "resolved via dashboard"), Date.now(), approve === "yes"))();
+        },
+      },
+      "/api/jobs/:id/outcome": {
+        POST: async (req) => {
+          const { outcome, listingUrl } = await body(req);
+          if (outcome !== "live" && outcome !== "rejected" && outcome !== "pending") return Response.json({ error: "outcome must be live, rejected or pending" }, { status: 400 });
+          return safe(() => J.setOutcome(db, req.params.id, outcome, listingUrl?.trim() || undefined))();
+        },
+      },
+      // Opens plain Chrome on Google's sign-in page (scripts/google-login). Same-origin only: another site
+      // in the browser must not be able to pop this open.
+      "/api/google-login": {
+        POST: (req) => {
+          if ((req.headers.get("sec-fetch-site") ?? "same-origin") !== "same-origin") return new Response("forbidden", { status: 403 });
+          Bun.spawn([join(PKG, "scripts/google-login")], { cwd: PKG, env: { ...process.env, LAUNCH_HOME: HOME }, stdout: "ignore", stderr: "ignore" }).unref();
+          return Response.json({ ok: true });
+        },
+      },
+      // Raises the agents' Chrome on the worker's tab (scripts/show-browser). Same-origin only, as above.
+      "/api/show-browser": {
+        POST: async (req) => {
+          if ((req.headers.get("sec-fetch-site") ?? "same-origin") !== "same-origin") return new Response("forbidden", { status: 403 });
+          const p = Bun.spawn([join(PKG, "scripts/show-browser")], { cwd: PKG, env: { ...process.env, LAUNCH_HOME: HOME }, stdout: "ignore", stderr: "ignore" });
+          return (await p.exited) === 0 ? Response.json({ ok: true }) : Response.json({ error: "agent browser is not open" }, { status: 409 });
+        },
+      },
+      // Runs `submissions check` (plain fetch, no AI) for one job or all pending ones; marks live listings.
+      "/api/submissions/check": {
+        POST: async (req) => {
+          const { job } = (await req.json().catch(() => ({}))) as { job?: string };
+          const p = Bun.spawn([process.execPath, join(PKG, "src/cli.ts"), "submissions", "check", ...(job ? [job] : [])], { cwd: PKG, env: { ...process.env, LAUNCH_HOME: HOME }, stdout: "pipe", stderr: "ignore" });
+          const out = await new Response(p.stdout).text();
+          return Response.json({ results: JSON.parse(out.slice(out.indexOf("["))) });
+        },
+      },
+      // A listing the human made themselves, from the dashboard: { product, target, outcome, listingUrl }.
+      "/api/submissions/add": {
+        POST: async (req) => {
+          const { product, target, outcome, listingUrl } = await body(req);
+          return safe(async () => addManualSubmission(db, (await loadProduct(product)).id, target ?? "", (outcome ?? "pending") as J.Outcome, listingUrl))();
+        },
+      },
+      // "I submitted it myself" on an existing job.
+      "/api/jobs/:id/manual": {
+        POST: async (req) => {
+          const { outcome, listingUrl } = await body(req);
+          return safe(() => J.recordManual(db, req.params.id, (outcome ?? "pending") as J.Outcome, listingUrl?.trim() || undefined))();
+        },
+      },
+      "/api/jobs/:id/requeue": { POST: (req) => safe(() => J.requeue(db, req.params.id))() },
+      "/api/galleries/:rev/:decision": {
+        POST: (req) => safe(() => reviewGallery(db, Number(req.params.rev), req.params.decision === "approve" ? "approved" : "rejected"))(),
+      },
+      "/api/registry-changes/:id/:decision": {
+        POST: (req) => safe(() => reviewRegistryChange(db, Number(req.params.id), req.params.decision === "accept" ? "accepted" : "rejected"))(),
+      },
+      "/api/product-approvals/:id/:decision": {
+        POST: (req) => safe(() => reviewProductApproval(db, Number(req.params.id), req.params.decision === "approve" ? "approved" : "rejected"))(),
+      },
+      "/api/registry": safe(() => loadDirectories()),
+      "/api/registry/:id": (req) => safe(() => loadDirectory(req.params.id))(),
+      "/api/products": safe(() => Promise.all(productIds().map((id) => optional(() => loadProduct(id)).then((p) => ({ id, ...p }))))),
+      // Workspace-wide: who agents sign up as and what they may do.
+      "/api/settings": safe(async () => ({ identity: await optional(() => loadIdentity()), permissions: await optional(() => loadPermissions()) })),
+      "/api/products/:id": (req) =>
+        safe(async () => ({
+          product: await optional(() => loadProduct(req.params.id)),
+          galleries: db.select().from(galleries).where(eq(galleries.productId, req.params.id)).orderBy(desc(galleries.revision)).all(),
+        }))(),
+      // Screenshots for gallery review. Confined to the workspace directory.
+      "/workspace/*": files(WORKSPACE, "/workspace/"),
+      // Agent screenshots per job: data/evidence/<job-id>/*.png
+      "/evidence/*": files(EVIDENCE, "/evidence/"),
+    },
+  });
+  console.log(`dirpush dashboard: ${server.url}`);
+  return server;
+}