@pylonsync/create-pylon 0.19.1 → 0.20.0

package/templates/directory/functions/seedDemo.ts

@@ -0,0 +1,43 @@
+import { mutation } from "@pylonsync/functions";
+import { emailMatchesOwner } from "../lib/owner";
+import { DEMO_SUBMISSIONS, demoDataEnabled } from "../lib/demo";
+
+// seedDemo — owner-only, development-only. Fills an empty review queue with the
+// fictional submissions in lib/demo.ts, so the curator dashboard has entries.
+//
+// It writes nothing unless demo data is on (lib/demo.ts: PYLON_DEMO_DATA, else
+// a `pylon dev` process), so `pylon start`, Docker, and Pylon Cloud deploys do
+// not get demo rows. It also writes nothing once any Submission exists.
+// Submissions carry submitter emails (PII), so only the signed-in owner can run
+// it, like the rest of the curator surface.
+export default mutation<Record<string, never>, { seeded: boolean }>({
+  auth: "user",
+  async handler(ctx) {
+    const me = await ctx.db.get("User", ctx.auth.userId);
+    if (!emailMatchesOwner(me?.email as string | undefined, ctx.env.PYLON_OWNER_EMAIL)) {
+      throw ctx.error("POLICY_DENIED", "Only the owner can seed the review queue.");
+    }
+    if (!demoDataEnabled(ctx.env)) return { seeded: false };
+
+    await ctx.db.advisoryLock("directory_seed_demo");
+    const existing = await ctx.db.unsafe.list("Submission");
+    if (existing.length > 0) return { seeded: false };
+
+    const nowMs = Date.now();
+    for (const s of DEMO_SUBMISSIONS) {
+      await ctx.db.unsafe.insert("Submission", {
+        submitterName: s.submitterName,
+        submitterEmail: s.submitterEmail,
+        name: s.name,
+        tagline: s.tagline,
+        url: s.url,
+        category: s.category,
+        tags: s.tags,
+        description: s.description || null,
+        status: s.status,
+        createdAt: new Date(nowMs - s.hoursAgo * 3_600_000).toISOString(),
+      });
+    }
+    return { seeded: true };
+  },
+});

package/templates/directory/lib/demo.ts

@@ -0,0 +1,145 @@
+// Demo review queue for local development.
+//
+// The curator's first dashboard load in `pylon dev` fills an empty Submission
+// table with fictional tool submissions (functions/seedDemo.ts), so the queue
+// has entries to approve or reject. A deploy does not seed: `demoDataEnabled`
+// is true only when PYLON_DEMO_DATA is on, or when it is unset and the process
+// runs under `pylon dev`. Set PYLON_DEMO_DATA=0 to turn it off in development too.
+//
+// The starter listings (functions/seedListings.ts) are different: they are the
+// directory's own content from lib/site.config.ts, so they seed everywhere.
+
+const ON = new Set(["1", "true", "yes", "on"]);
+const OFF = new Set(["0", "false", "no", "off"]);
+
+/**
+ * True when demo rows may be written. An explicit PYLON_DEMO_DATA wins.
+ * Otherwise it needs both PYLON_DEV_MODE on and PYLON_DEV_WATCH_DIR set. Only
+ * `pylon dev` sets PYLON_DEV_WATCH_DIR; `pylon start` and the Docker image do
+ * not, and the image turns PYLON_DEV_MODE on by default, so dev mode alone is
+ * not proof of a local machine.
+ */
+export function demoDataEnabled(env: Record<string, string | undefined>): boolean {
+  const explicit = env.PYLON_DEMO_DATA?.trim().toLowerCase();
+  if (explicit && ON.has(explicit)) return true;
+  if (explicit && OFF.has(explicit)) return false;
+  const dev = env.PYLON_DEV_MODE?.trim().toLowerCase();
+  const devMode = dev === "1" || dev === "true";
+  return devMode && Boolean(env.PYLON_DEV_WATCH_DIR?.trim());
+}
+
+export interface DemoSubmission {
+  submitterName: string;
+  submitterEmail: string;
+  name: string;
+  tagline: string;
+  url: string;
+  category: string;
+  tags: string;
+  description: string;
+  status: "new" | "approved" | "rejected";
+  /** Hours before the seed runs. */
+  hoursAgo: number;
+}
+
+// Fictional tools and submitters. The two "approved" rows name starter
+// listings from lib/site.config.ts, so every approved submission is live.
+// Starter listings added from config have no submission row.
+export const DEMO_SUBMISSIONS: DemoSubmission[] = [
+  {
+    submitterName: "Nadia Haddad",
+    submitterEmail: "nadia@example.com",
+    name: "Querybird",
+    tagline: "Explain plans for Postgres, drawn as a tree you can click through.",
+    url: "https://example.com/querybird",
+    category: "Database",
+    tags: "postgres, performance",
+    description: "Paste a query, get the plan with the slow node marked. Runs in the browser; nothing leaves your machine.",
+    status: "new",
+    hoursAgo: 2,
+  },
+  {
+    submitterName: "Owen Reilly",
+    submitterEmail: "owen@example.com",
+    name: "Flagpost",
+    tagline: "Feature flags stored in your own database, with a small admin UI.",
+    url: "https://example.com/flagpost",
+    category: "DevOps",
+    tags: "feature flags, self-hosted",
+    description: "One table, one SDK call, and an admin page you mount in your app.",
+    status: "new",
+    hoursAgo: 9,
+  },
+  {
+    submitterName: "Hana Sato",
+    submitterEmail: "hana@example.com",
+    name: "Palettier",
+    tagline: "Generate accessible color scales from one brand color.",
+    url: "https://example.com/palettier",
+    category: "Design",
+    tags: "color, accessibility, tokens",
+    description: "Every step is checked for WCAG contrast against white and black. Exports CSS variables and a Figma file.",
+    status: "new",
+    hoursAgo: 26,
+  },
+  {
+    submitterName: "Felix Wagner",
+    submitterEmail: "felix@example.com",
+    name: "Logline",
+    tagline: "Structured logs you can search from the terminal.",
+    url: "https://example.com/logline",
+    category: "DevOps",
+    tags: "logging, cli",
+    description: "Pipe JSON logs in, then filter with a short query language. Keeps a week of history on disk.",
+    status: "new",
+    hoursAgo: 40,
+  },
+  {
+    submitterName: "Isabel Cruz",
+    submitterEmail: "isabel@example.com",
+    name: "Promptdeck",
+    tagline: "Version and diff the prompts your app sends to a model.",
+    url: "https://example.com/promptdeck",
+    category: "AI",
+    tags: "llm, prompts, versioning",
+    description: "Each prompt change gets a version and a side-by-side diff of outputs on your saved test inputs.",
+    status: "new",
+    hoursAgo: 55,
+  },
+  {
+    submitterName: "Ruth Castillo",
+    submitterEmail: "ruth@example.com",
+    name: "Brineway",
+    tagline: "S3-compatible object storage at the edge.",
+    url: "https://example.com/brineway",
+    category: "Hosting",
+    tags: "storage, edge, s3",
+    description: "",
+    status: "approved",
+    hoursAgo: 150,
+  },
+  {
+    submitterName: "Daniel Park",
+    submitterEmail: "daniel@example.com",
+    name: "Countwell",
+    tagline: "Privacy-first product analytics you can self-host.",
+    url: "https://example.com/countwell",
+    category: "Analytics",
+    tags: "analytics, privacy",
+    description: "",
+    status: "approved",
+    hoursAgo: 210,
+  },
+  {
+    submitterName: "Luca Romano",
+    submitterEmail: "luca@example.com",
+    name: "Best AI Tools 2026",
+    tagline: "A list of 500 AI tools.",
+    url: "https://example.com/best-ai-tools",
+    category: "AI",
+    tags: "list",
+    description: "",
+    status: "rejected",
+    hoursAgo: 96,
+  },
+];

package/templates/directory/lib/directory.ts

@@ -43,3 +43,30 @@ export function parseTags(tags?: string | null): string[] {
     .map((t) => t.trim())
     .filter(Boolean);
 }
+
+// A tool's mark in the list: its initials on a tinted square. The tint comes
+// from a hash of the name, so a tool keeps its color across reloads and
+// servers without storing anything. Swap in real logos by adding a `logoUrl`
+// field if your directory has them.
+const MARK_TONES = [
+  { bg: "#e0e7ff", fg: "#3730a3" },
+  { bg: "#dcfce7", fg: "#166534" },
+  { bg: "#fef3c7", fg: "#92400e" },
+  { bg: "#fce7f3", fg: "#9d174d" },
+  { bg: "#e0f2fe", fg: "#075985" },
+  { bg: "#ede9fe", fg: "#5b21b6" },
+  { bg: "#ffedd5", fg: "#9a3412" },
+  { bg: "#f1f5f9", fg: "#334155" },
+] as const;
+
+export function monogram(name: string): { letters: string; bg: string; fg: string } {
+  const words = name.trim().split(/\s+/).filter(Boolean);
+  const letters =
+    words.length >= 2
+      ? (words[0][0] + words[1][0]).toUpperCase()
+      : (words[0] ?? "?").slice(0, 2).replace(/^./, (c) => c.toUpperCase());
+  let h = 0;
+  for (const ch of name.trim().toLowerCase()) h = (h * 31 + ch.charCodeAt(0)) >>> 0;
+  const tone = MARK_TONES[h % MARK_TONES.length];
+  return { letters, bg: tone.bg, fg: tone.fg };
+}

package/templates/directory/lib/site.config.ts

@@ -36,8 +36,11 @@ export type SeedListing = {
 };
 
 export type DirectoryConfig = BaseConfig & {
-  // The page opens with the brand name, this one line, and the search box.
+  // The page opens with a headline, one line of description, and the search
+  // box. The nav already shows the brand name, so the headline says what the
+  // directory holds.
   intro: {
+    headline: string;
     description: string;
     ctaLabel: string;
     searchPlaceholder: string;
@@ -83,29 +86,31 @@ export const siteConfig: DirectoryConfig = {
   },
 
   intro: {
+    headline: "Developer tools, checked by hand.",
     description:
-      "A hand-checked directory of developer tools. Search, filter by category, and upvote. No account needed.",
+      "Every entry is reviewed before it goes live. Search, filter by category, and upvote. No account needed.",
     ctaLabel: "Submit a tool",
     searchPlaceholder: "search: database, deploy, auth",
   },
 
   categories: ["Database", "Hosting", "Auth", "AI", "Analytics", "Design", "Productivity", "DevOps"],
 
-  // Fictional-but-plausible starter entries across categories. Replace with your
-  // own; `votes` seeds the leaderboard so "Top voted" isn't a flat list.
+  // Fictional starter entries across categories. The names are made up so no
+  // entry reads as a real product. Replace them with your own; `votes` seeds the
+  // leaderboard so "Top voted" isn't a flat list.
   seedListings: [
-    { name: "Quill", tagline: "Postgres with a realtime sync engine baked in.", url: "https://example.com/quill", category: "Database", tags: "postgres, realtime, sync", votes: 342, featured: true },
-    { name: "Tigris Store", tagline: "S3-compatible object storage at the edge.", url: "https://example.com/tigris", category: "Hosting", tags: "storage, edge, s3", votes: 218 },
-    { name: "Gatekeep", tagline: "Drop-in auth: passkeys, OAuth, and magic links.", url: "https://example.com/gatekeep", category: "Auth", tags: "auth, passkeys, oauth", votes: 287, featured: true },
-    { name: "Loom AI", tagline: "Self-hostable LLM gateway with caching + routing.", url: "https://example.com/loom", category: "AI", tags: "llm, gateway, cache", votes: 401, featured: true },
-    { name: "Pulse", tagline: "Privacy-first product analytics you can self-host.", url: "https://example.com/pulse", category: "Analytics", tags: "analytics, privacy", votes: 174 },
-    { name: "Frame", tagline: "A design-token pipeline from Figma to code.", url: "https://example.com/frame", category: "Design", tags: "design, tokens, figma", votes: 132 },
-    { name: "Cadence", tagline: "Background jobs + cron with a visual dashboard.", url: "https://example.com/cadence", category: "DevOps", tags: "jobs, cron, queue", votes: 209 },
-    { name: "Inbox Zero", tagline: "Transactional email with a real templating story.", url: "https://example.com/inbox", category: "Productivity", tags: "email, templates", votes: 96 },
-    { name: "Shipyard", tagline: "Preview deploys for every PR, in seconds.", url: "https://example.com/shipyard", category: "Hosting", tags: "deploy, ci, preview", votes: 263 },
-    { name: "Vector Vault", tagline: "Managed vector search without the ops.", url: "https://example.com/vectorvault", category: "AI", tags: "vector, search, rag", votes: 188 },
-    { name: "Schema", tagline: "Type-safe migrations that review themselves.", url: "https://example.com/schema", category: "Database", tags: "migrations, types", votes: 151 },
-    { name: "Watchtower", tagline: "Uptime + error tracking in one calm dashboard.", url: "https://example.com/watchtower", category: "DevOps", tags: "monitoring, errors", votes: 144 },
+    { name: "Tidepool DB", tagline: "Postgres with a realtime sync engine baked in.", url: "https://example.com/tidepool", category: "Database", tags: "postgres, realtime, sync", votes: 342, featured: true },
+    { name: "Brineway", tagline: "S3-compatible object storage at the edge.", url: "https://example.com/brineway", category: "Hosting", tags: "storage, edge, s3", votes: 218 },
+    { name: "Keyloft", tagline: "Drop-in auth: passkeys, OAuth, and magic links.", url: "https://example.com/keyloft", category: "Auth", tags: "auth, passkeys, oauth", votes: 287, featured: true },
+    { name: "Relaygate", tagline: "Self-hostable LLM gateway with caching + routing.", url: "https://example.com/relaygate", category: "AI", tags: "llm, gateway, cache", votes: 401, featured: true },
+    { name: "Countwell", tagline: "Privacy-first product analytics you can self-host.", url: "https://example.com/countwell", category: "Analytics", tags: "analytics, privacy", votes: 174 },
+    { name: "Tokenmill", tagline: "A design-token pipeline from Figma to code.", url: "https://example.com/tokenmill", category: "Design", tags: "design, tokens, figma", votes: 132 },
+    { name: "Cronhollow", tagline: "Background jobs + cron with a visual dashboard.", url: "https://example.com/cronhollow", category: "DevOps", tags: "jobs, cron, queue", votes: 209 },
+    { name: "Letterpane", tagline: "Transactional email with a real templating story.", url: "https://example.com/letterpane", category: "Productivity", tags: "email, templates", votes: 96 },
+    { name: "Branchlight", tagline: "Preview deploys for every PR, in seconds.", url: "https://example.com/branchlight", category: "Hosting", tags: "deploy, ci, preview", votes: 263 },
+    { name: "Nearfield", tagline: "Managed vector search without the ops.", url: "https://example.com/nearfield", category: "AI", tags: "vector, search, rag", votes: 188 },
+    { name: "Migratory", tagline: "Type-safe migrations that review themselves.", url: "https://example.com/migratory", category: "Database", tags: "migrations, types", votes: 151 },
+    { name: "Lookoutly", tagline: "Uptime + error tracking in one calm dashboard.", url: "https://example.com/lookoutly", category: "DevOps", tags: "monitoring, errors", votes: 144 },
   ],
 
   submit: {

package/templates/directory/tests/directory.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { monogram } from "../lib/directory";
+import { DEMO_SUBMISSIONS, demoDataEnabled } from "../lib/demo";
+import { siteConfig } from "../lib/site.config";
+
+describe("monogram", () => {
+  test("two words give two initials; one word gives its first two letters", () => {
+    expect(monogram("Tidepool DB").letters).toBe("TD");
+    expect(monogram("Keyloft").letters).toBe("Ke");
+  });
+  test("the tint is stable for a name", () => {
+    expect(monogram("Keyloft")).toEqual(monogram("Keyloft"));
+    expect(monogram("  Keyloft ")).toEqual(monogram("Keyloft"));
+  });
+});
+
+describe("starter content", () => {
+  test("the page headline is not the brand name the nav already shows", () => {
+    expect(siteConfig.intro.headline).not.toBe(siteConfig.brand.name);
+  });
+  test("starter tools avoid names of well-known real products", () => {
+    const real = ["Loom", "Inbox Zero", "Quill", "Shipyard", "Tigris", "Cadence", "Watchtower", "Pulse", "Frame", "Schema"];
+    for (const l of siteConfig.seedListings) {
+      for (const r of real) expect(l.name.toLowerCase()).not.toContain(r.toLowerCase());
+    }
+  });
+});
+
+describe("demo queue", () => {
+  test("only under `pylon dev` unless PYLON_DEMO_DATA says otherwise", () => {
+    expect(demoDataEnabled({ PYLON_DEV_MODE: "1", PYLON_DEV_WATCH_DIR: "/src/app" })).toBe(true);
+    // The Docker base image turns dev mode on by default; without `pylon dev` it must not seed.
+    expect(demoDataEnabled({ PYLON_DEV_MODE: "true" })).toBe(false);
+    expect(demoDataEnabled({ PYLON_DEV_MODE: "false" })).toBe(false);
+    expect(demoDataEnabled({})).toBe(false);
+    expect(demoDataEnabled({ PYLON_DEV_MODE: "1", PYLON_DEV_WATCH_DIR: "/src/app", PYLON_DEMO_DATA: "no" })).toBe(false);
+  });
+  test("approved demo submissions match live starter listings; categories are valid", () => {
+    const names = new Set(siteConfig.seedListings.map((l) => l.name));
+    for (const s of DEMO_SUBMISSIONS) {
+      if (s.status === "approved") expect(names.has(s.name)).toBe(true);
+      expect(siteConfig.categories).toContain(s.category);
+    }
+    expect(DEMO_SUBMISSIONS.filter((s) => s.status === "new").length).toBeGreaterThan(3);
+  });
+});