create-ailk 0.6.1 → 0.8.0

package/templates/.claude/skills/upgrade-plan/scripts/upgrade-plan.ts

@@ -0,0 +1,527 @@
+/**
+ * upgrade-plan — the helper behind the `/upgrade-plan` skill.
+ *
+ * Reads the paid options' prices from ONE public surface — the schema.org
+ * `Offer` JSON-LD on https://ailaunchkit.ai/pricing — at run time, reads this
+ * site's own modules / template / shape / design from files the scaffold
+ * already carries, and recommends exactly one option from a price-free rule
+ * table (levels per the AI Launch Kit product vocabulary). It holds no price of
+ * its own, caches nothing, and writes nothing.
+ *
+ * Run from the project root:
+ *
+ *   pnpm exec tsx .claude/skills/upgrade-plan/scripts/upgrade-plan.ts [--need X] [--url U | --html-file F] [--root R]
+ *
+ * Prints one JSON object. Exit 0 whether the page was priced, unpriced or
+ * unreachable (each is a reported state); exit 2 on a usage error.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export const PRICING_URL = "https://ailaunchkit.ai/pricing";
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+export type OptionId = "free" | "pro" | "pro-plus" | "agency" | "commerce" | "saas" | "saas-usage";
+
+export interface OptionInfo {
+  id: OptionId;
+  name: string;
+  adds: string;
+  requires: string;
+  /** Normalized names (see `normalizeName`) an `Offer` may carry for this option. */
+  aliases: string[];
+}
+
+/** The seven options, always listed, in this order. Names and structure only — no figure. */
+export const OPTIONS: readonly OptionInfo[] = [
+  {
+    id: "free",
+    name: "Free",
+    adds: "The open-source base: the website, its API and MCP server, and the marketing module.",
+    requires: "Nothing — no licence key.",
+    aliases: ["free", "oss"],
+  },
+  {
+    id: "pro",
+    name: "Pro",
+    adds: "The paid modules for one site — docs and blog, scheduling, signal collectors and the Admin app — kept current.",
+    requires: "A licence key for the site.",
+    aliases: ["pro"],
+  },
+  {
+    id: "pro-plus",
+    name: "Pro Plus",
+    adds: "Everything in Pro, plus the multi-tenant module (organizations, workspaces, members).",
+    requires: "A licence key for the site.",
+    aliases: ["pro plus"],
+  },
+  {
+    id: "agency",
+    name: "Agency",
+    adds: "A reseller agreement for building sites for clients — not a bigger level.",
+    requires: "Each client site is then licensed at Pro or Pro Plus.",
+    aliases: ["agency"],
+  },
+  {
+    id: "commerce",
+    name: "Commerce",
+    adds: "The commerce add-on: checkout, payment links, hosted invoices, subscriptions and the customer portal, through your own Stripe account.",
+    requires: "Any paid level (Pro or Pro Plus).",
+    aliases: ["commerce", "commerce add-on"],
+  },
+  {
+    id: "saas",
+    name: "SaaS",
+    adds: "Commerce plus plans, trials, coupons and entitlements mapped to feature flags — for a product that bills its tenants.",
+    requires: "Pro Plus.",
+    aliases: ["saas"],
+  },
+  {
+    id: "saas-usage",
+    name: "SaaS with Usage",
+    adds: "SaaS plus usage metering, prepaid credits, overage and spend limits.",
+    requires: "Pro Plus.",
+    aliases: ["saas with usage", "saas-usage"],
+  },
+];
+
+export const NEEDS = ["agency", "sell", "saas", "usage", "docs", "scheduling", "multi-tenant"] as const;
+export type Need = (typeof NEEDS)[number];
+
+export interface Offer {
+  name: string;
+  price?: string;
+  priceCurrency?: string;
+  unitText?: string;
+  url?: string;
+}
+
+export interface Price {
+  price: string;
+  priceCurrency?: string;
+  unitText?: string;
+  url?: string;
+}
+
+export interface Site {
+  modules: string[];
+  template: string | null;
+  shape: string | null;
+  design: string | null;
+  sellsSomething: boolean;
+  commerceInstalled: boolean;
+  licenseKeySet: boolean;
+}
+
+export interface Recommendation {
+  rule: "R1" | "R2" | "R3" | "R4" | "R5" | "R6" | "R7";
+  option: string;
+  parts: OptionId[];
+  reason: string;
+}
+
+export interface PlanOption {
+  id: OptionId;
+  name: string;
+  adds: string;
+  requires: string;
+  prices: Price[];
+  status: "published" | "not published on the pricing page";
+}
+
+export interface Plan {
+  pricing: {
+    status: "ok" | "unreachable" | "unpublished";
+    /** The link shown to the human — always the public pricing page. */
+    url: string;
+    /** The URL actually fetched (differs only under `--url`). */
+    fetchedUrl: string;
+    reason?: string;
+  };
+  options: PlanOption[];
+  alsoPublished: Offer[];
+  site: Site;
+  recommendation: Recommendation & { link: string };
+}
+
+// ── Offers ────────────────────────────────────────────────────────────────
+
+const LD_JSON_BLOCK = /<script[^>]*type\s*=\s*["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi;
+
+function str(v: unknown): string | undefined {
+  if (typeof v === "string" && v.length > 0) return v;
+  if (typeof v === "number" && Number.isFinite(v)) return String(v);
+  return undefined;
+}
+
+function isOffer(node: Record<string, unknown>): boolean {
+  const t = node["@type"];
+  return t === "Offer" || (Array.isArray(t) && t.includes("Offer"));
+}
+
+function toOffer(node: Record<string, unknown>, parentName: string | undefined): Offer | null {
+  const name = str(node.name) ?? parentName;
+  if (name === undefined) return null;
+  const specs = Array.isArray(node.priceSpecification) ? node.priceSpecification : [node.priceSpecification];
+  const spec = specs.find((s): s is Record<string, unknown> => typeof s === "object" && s !== null);
+  const offer: Offer = { name };
+  const price = str(node.price) ?? str(spec?.price);
+  const priceCurrency = str(node.priceCurrency) ?? str(spec?.priceCurrency);
+  const unitText = str(spec?.unitText);
+  const url = str(node.url);
+  if (price !== undefined) offer.price = price;
+  if (priceCurrency !== undefined) offer.priceCurrency = priceCurrency;
+  if (unitText !== undefined) offer.unitText = unitText;
+  if (url !== undefined) offer.url = url;
+  return offer;
+}
+
+function collectOffers(node: unknown, parentName: string | undefined, out: Offer[]): void {
+  if (Array.isArray(node)) {
+    for (const item of node) collectOffers(item, parentName, out);
+    return;
+  }
+  if (typeof node !== "object" || node === null) return;
+  const obj = node as Record<string, unknown>;
+  if (isOffer(obj)) {
+    const offer = toOffer(obj, parentName);
+    if (offer !== null) out.push(offer);
+    // An offer may carry others (an `addOn`, an `itemOffered` chain) — walk them too.
+    for (const value of Object.values(obj)) collectOffers(value, offer?.name ?? parentName, out);
+    return;
+  }
+  const ownName = str(obj.name) ?? parentName;
+  for (const value of Object.values(obj)) collectOffers(value, ownName, out);
+}
+
+/** Every `Offer` node in the page's `application/ld+json` blocks, in document order. */
+export function parseOffers(html: string): Offer[] {
+  const out: Offer[] = [];
+  for (const match of html.matchAll(LD_JSON_BLOCK)) {
+    let data: unknown;
+    try {
+      data = JSON.parse(match[1] ?? "");
+    } catch {
+      continue; // a block that fails to parse is skipped, not fatal
+    }
+    collectOffers(data, undefined, out);
+  }
+  return out;
+}
+
+/** Lower-case, drop a parenthetical and a product prefix, collapse whitespace. */
+export function normalizeName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/\([^)]*\)/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .replace(/^(ailk|ai launch kit) /, "");
+}
+
+function matchOption(offer: Offer): OptionInfo | undefined {
+  const n = normalizeName(offer.name);
+  return OPTIONS.find((o) => o.aliases.includes(n));
+}
+
+// ── The site ──────────────────────────────────────────────────────────────
+
+function readText(path: string): string | null {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function readJson(path: string): Record<string, unknown> | null {
+  const text = readText(path);
+  if (text === null) return null;
+  try {
+    const data: unknown = JSON.parse(text);
+    return typeof data === "object" && data !== null ? (data as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+function listMdx(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listMdx(full));
+    else if (entry.isFile() && entry.name.endsWith(".mdx")) out.push(full);
+  }
+  return out;
+}
+
+/** True when the file's frontmatter carries a TOP-LEVEL `price:` that is a real figure. */
+function hasTopLevelPrice(mdx: string): boolean {
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(mdx);
+  if (fm === null) return false;
+  const line = /^price:[ \t]*(.*)$/m.exec(fm[1] ?? "");
+  if (line === null) return false;
+  const value = (line[1] ?? "").trim().replace(/^["']|["']$/g, "");
+  return !value.includes("{") && /^\d+(\.\d+)?$/.test(value);
+}
+
+/** What this scaffold records about itself. Each field from its own source; nothing inferred. */
+export function readSite(root: string, env: Record<string, string | undefined> = process.env): Site {
+  const arch = readText(join(root, "architecture.yaml"));
+  const modulesLine = arch === null ? null : /^# Modules:[ \t]*(.*)$/m.exec(arch);
+  const modules =
+    modulesLine === null
+      ? []
+      : (modulesLine[1] ?? "")
+          .split(",")
+          .map((m) => m.trim())
+          .filter((m) => m.length > 0);
+
+  let template: string | null = null;
+  const provenance = readJson(join(root, ".ailk-template.json"));
+  if (provenance !== null) {
+    template = str(provenance.template) ?? null;
+  } else {
+    const design = readText(join(root, "DESIGN.md"));
+    const source = design === null ? null : /Source template:[ \t]*(\S+)/.exec(design);
+    const value = source?.[1];
+    if (value !== undefined && !value.startsWith("_base")) template = value;
+  }
+
+  // The scaffold's roster of record (#6658 D7); a scaffold from before it
+  // carries the same JSON at its root under the template's own file name.
+  const manifest =
+    readJson(join(root, ".ailk-site-manifest.json")) ?? readJson(join(root, "TEMPLATE-MANIFEST.json"));
+  const shape = str(manifest?.shape) ?? null;
+  const designName = str(manifest?.design) ?? null;
+
+  const sellsSomething = listMdx(join(root, "content")).some((f) => hasTopLevelPrice(readText(f) ?? ""));
+  const commerceInstalled = existsSync(join(root, ".claude", "skills", "scaffold-commerce"));
+  // Presence only: the value is reduced to a boolean here and never kept.
+  const key = env.AILK_LICENSE_KEY;
+  const licenseKeySet = typeof key === "string" && key.length > 0;
+
+  return { modules, template, shape, design: designName, sellsSomething, commerceInstalled, licenseKeySet };
+}
+
+// ── The recommendation ────────────────────────────────────────────────────
+
+const PRO_MODULES = ["docs-blog", "scheduling", "signal-collectors", "workspace"];
+
+/** One recommendation from a price-free rule table; the first matching rule wins. */
+export function recommend(site: Site, need?: Need): Recommendation {
+  const has = (m: string): boolean => site.modules.includes(m);
+  const multiTenant = has("multi-tenant") || need === "multi-tenant";
+
+  if (need === "agency") {
+    return {
+      rule: "R1",
+      option: "Agency",
+      parts: ["agency"],
+      reason: "You build sites for clients; each client site is then Pro or Pro Plus.",
+    };
+  }
+  if (need === "usage") {
+    return {
+      rule: "R2",
+      option: "Pro Plus + SaaS with Usage",
+      parts: ["pro-plus", "saas-usage"],
+      reason: "You want to meter your own product's usage; SaaS with Usage requires Pro Plus.",
+    };
+  }
+  if (need === "saas") {
+    return {
+      rule: "R3",
+      option: "Pro Plus + SaaS",
+      parts: ["pro-plus", "saas"],
+      reason: "You want to bill your own tenants on plans; SaaS requires Pro Plus.",
+    };
+  }
+  if (multiTenant && !sells(site, need)) {
+    return {
+      rule: "R4",
+      option: "Pro Plus",
+      parts: ["pro-plus"],
+      reason: has("multi-tenant")
+        ? "This site uses the multi-tenant module, which needs Pro Plus."
+        : "You need multi-tenant (organizations and workspaces), which needs Pro Plus.",
+    };
+  }
+  if (sells(site, need)) {
+    const why = has("commerce")
+      ? "This site uses the commerce module"
+      : site.commerceInstalled
+        ? "This site has the commerce skill installed"
+        : site.sellsSomething
+          ? "This site already has priced pages but no commerce module"
+          : "You want to take payments on this site";
+    return multiTenant
+      ? {
+          rule: "R5",
+          option: "Pro Plus + Commerce",
+          parts: ["pro-plus", "commerce"],
+          reason: `${why}; the Commerce add-on sits on a paid level, and multi-tenant needs Pro Plus.`,
+        }
+      : {
+          rule: "R5",
+          option: "Pro + Commerce",
+          parts: ["pro", "commerce"],
+          reason: `${why}; the Commerce add-on sits on a paid level, and Pro is the first one.`,
+        };
+  }
+  const proModules = site.modules.filter((m) => PRO_MODULES.includes(m));
+  if (proModules.length > 0 || need === "docs" || need === "scheduling") {
+    const named = proModules.length > 0 ? proModules.join(", ") : need === "docs" ? "docs-blog" : "scheduling";
+    return {
+      rule: "R6",
+      option: "Pro",
+      parts: ["pro"],
+      reason: `${proModules.length > 0 ? "This site uses" : "You want"} ${named}, which Pro covers.`,
+    };
+  }
+  return {
+    rule: "R7",
+    option: "Free",
+    parts: ["free"],
+    reason:
+      "This site is marketing only with nothing priced, so what it uses today is covered by Free; Pro adds a kept-current foundation and the paid modules.",
+  };
+}
+
+function sells(site: Site, need?: Need): boolean {
+  return site.modules.includes("commerce") || site.commerceInstalled || need === "sell" || site.sellsSomething;
+}
+
+// ── The plan ──────────────────────────────────────────────────────────────
+
+async function fetchPage(
+  url: string,
+  fetchImpl: typeof fetch,
+  timeoutMs: number,
+): Promise<{ html: string } | { error: string }> {
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<{ error: string }>((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve({ error: `timed out after ${timeoutMs} ms` });
+    }, timeoutMs);
+  });
+  const attempt = (async (): Promise<{ html: string } | { error: string }> => {
+    try {
+      const res = await fetchImpl(url, { signal: controller.signal, redirect: "follow" });
+      if (!res.ok) return { error: `HTTP status ${res.status}` };
+      return { html: await res.text() };
+    } catch (err) {
+      return { error: err instanceof Error ? err.message : String(err) };
+    }
+  })();
+  try {
+    return await Promise.race([attempt, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function buildPlan(opts: {
+  root: string;
+  need?: Need;
+  url?: string;
+  html?: string;
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+}): Promise<Plan> {
+  const fetchedUrl = opts.url ?? PRICING_URL;
+  let html: string | undefined = opts.html;
+  let reason: string | undefined;
+  if (html === undefined) {
+    const page = await fetchPage(fetchedUrl, opts.fetch ?? fetch, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    if ("html" in page) html = page.html;
+    else reason = page.error;
+  }
+
+  const offers = html === undefined ? [] : parseOffers(html);
+  const prices = new Map<OptionId, Price[]>(OPTIONS.map((o) => [o.id, []]));
+  const alsoPublished: Offer[] = [];
+  for (const offer of offers) {
+    const option = matchOption(offer);
+    if (option === undefined || offer.price === undefined) {
+      if (option === undefined) alsoPublished.push(offer);
+      continue;
+    }
+    const { name: _name, ...price } = offer;
+    prices.get(option.id)?.push({ ...price, price: offer.price });
+  }
+
+  const options: PlanOption[] = OPTIONS.map((o) => {
+    const p = prices.get(o.id) ?? [];
+    return {
+      id: o.id,
+      name: o.name,
+      adds: o.adds,
+      requires: o.requires,
+      prices: p,
+      status: p.length > 0 ? "published" : "not published on the pricing page",
+    };
+  });
+
+  const site = readSite(opts.root);
+  const rec = recommend(site, opts.need);
+  const link = prices.get(rec.parts[0] ?? "free")?.find((p) => p.url !== undefined)?.url ?? PRICING_URL;
+
+  const priced = options.some((o) => o.prices.length > 0) || alsoPublished.some((o) => o.price !== undefined);
+  const status = html === undefined ? "unreachable" : priced ? "ok" : "unpublished";
+  return {
+    pricing: { status, url: PRICING_URL, fetchedUrl, ...(reason !== undefined ? { reason } : {}) },
+    options,
+    alsoPublished,
+    site,
+    recommendation: { ...rec, link },
+  };
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────────
+
+const USAGE =
+  "usage: upgrade-plan.ts [--need agency|sell|saas|usage|docs|scheduling|multi-tenant] [--url U | --html-file F] [--root R]";
+
+function usageError(message: string): never {
+  process.stderr.write(`${message}\n${USAGE}\n`);
+  process.exit(2);
+}
+
+async function main(argv: string[]): Promise<void> {
+  const opts: { root: string; need?: Need; url?: string; html?: string } = { root: process.cwd() };
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    const value = argv[i + 1];
+    if (flag !== "--need" && flag !== "--url" && flag !== "--html-file" && flag !== "--root") {
+      usageError(`unknown argument: ${flag}`);
+    }
+    if (value === undefined || value.startsWith("--")) usageError(`${flag} needs a value`);
+    i++;
+    if (flag === "--need") {
+      if (!(NEEDS as readonly string[]).includes(value)) usageError(`unknown need: ${value}`);
+      opts.need = value as Need;
+    } else if (flag === "--url") {
+      opts.url = value;
+    } else if (flag === "--html-file") {
+      const text = readText(value);
+      if (text === null) usageError(`cannot read ${value}`);
+      opts.html = text;
+    } else {
+      opts.root = value;
+    }
+  }
+  if (opts.url !== undefined && opts.html !== undefined) usageError("--url and --html-file are exclusive");
+  const plan = await buildPlan(opts);
+  process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+}
+
+if (/upgrade-plan\.ts$/.test(process.argv[1] ?? "")) {
+  main(process.argv.slice(2)).catch((err: unknown) => {
+    process.stderr.write(`upgrade-plan: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+  });
+}

package/templates/.github/workflows/ci.yml

@@ -43,6 +43,11 @@ jobs:
 
       - run: pnpm lint
 
+      # The boundary lint architecture.yaml declares — the same check the
+      # PostToolUse hook in .claude/settings.json and `pnpm preflight` run
+      # locally.
+      - run: pnpm architecture
+
       - run: pnpm test
 
       - run: pnpm build

package/templates/CLAUDE.md

@@ -24,7 +24,8 @@ The full rule lives at `.claude/rules/architecture.md`. Summary:
 
 - `apps/*` are peer apps. They do not import from each other.
 - `apps/web` does not read the database — it goes through `apps/api` via
-  the published HTTP client.
+  the published HTTP client. The one exception is the Better Auth adapter
+  (`apps/web/lib/prisma-for-auth.ts`, typed in `apps/web/auth.ts`).
 - Vendor SDKs (Stripe, Resend, NextAuth, Prisma) are wrapped in their
   respective `@working-theory/*` packages. Don't import them directly in your code.
 - New page types live under `content/<TypeName>/` and consume the schema
@@ -34,6 +35,11 @@ Crossing one of these is an architecture decision, not a workaround. If
 you think you need to, stop and write a short note in `docs/` explaining
 why before you change the boundary.
 
+`architecture.yaml` records these boundaries for your module set, and
+`pnpm architecture` (`tools/lint-architecture.ts`) enforces it. A
+PostToolUse hook in `.claude/settings.json` runs it after every Edit or
+Write and reports a violation in-session; `pnpm preflight` and CI run it too.
+
 ## Resource map
 
 Where to find the rule, surface, or fact you need.
@@ -49,7 +55,7 @@ Where to find the rule, surface, or fact you need.
 | Environment variables and what they unlock     | `.env.example`                                                 |
 | Per-page-type content shape                    | `content/<TypeName>/*.mdx` frontmatter                         |
 | Deploy targets                                 | `apps/web/vercel.json`, `apps/api/vercel.json`                 |
-| Verification before push                       | `pnpm preflight` (architecture + types + lint + tests + build) |
+| Verification before push                       | `pnpm preflight` (architecture + types + lint + build)         |
 
 If a question doesn't fit any row above, add the answer to this table
 when you find it. Future-you will thank present-you.