create-ailk 0.6.1 → 0.8.0

package/templates/tools/lint-architecture.ts

@@ -0,0 +1,315 @@
+#!/usr/bin/env tsx
+/**
+ * Architecture Boundary Linter — enforces this site's `architecture.yaml`.
+ *
+ * `architecture.yaml` is generated by create-ailk from the selected module
+ * set; this file is what makes it more than prose. It walks `apps/` and
+ * `database/` for .ts/.tsx files and reports:
+ *
+ *   - apps do not import apps — any file under `apps/<a>/` (or `database/`)
+ *     importing `apps/<b>/`, by package name or by relative path, whether or
+ *     not architecture.yaml declares either app;
+ *   - `may_not_import_from` / `may_import_from` per declared app;
+ *   - the global and per-app `forbidden_patterns` (with `paths_excluded`);
+ *   - the `namespaces` boundaries inside `database/`, when declared:
+ *     cross-namespace relative imports and cross-namespace Prisma `@relation`
+ *     directives.
+ *
+ * An import target is checked only when it is a workspace present in this
+ * repo (`apps/*`, `database`); `@working-theory/*` libraries install from npm
+ * and are not source here.
+ *
+ * Usage:
+ *   pnpm architecture            # or: tsx tools/lint-architecture.ts
+ *
+ * Exit codes:
+ *   0 — no violations
+ *   1 — violations found (each names the file, the line and the rule)
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+import { parse as parseYaml } from "yaml";
+
+interface ForbiddenPattern {
+  pattern: string;
+  reason: string;
+  paths_excluded?: string[];
+}
+
+interface AppRule {
+  path: string;
+  may_import_from?: string[];
+  may_not_import_from?: string[];
+  forbidden_patterns?: ForbiddenPattern[];
+}
+
+interface ArchConfig {
+  apps?: Record<string, AppRule>;
+  forbidden_patterns?: ForbiddenPattern[];
+  namespaces?: { members?: Record<string, { path: string }> };
+}
+
+interface Violation {
+  file: string;
+  line: number;
+  rule: string;
+  reason: string;
+}
+
+const ROOT = resolve(dirname(process.argv[1] ?? "."), "..");
+const SKIP_DIRS = new Set([
+  "node_modules",
+  "dist",
+  ".next",
+  ".turbo",
+  ".source",
+  "coverage",
+  "generated",
+]);
+const IMPORT_RE =
+  /(?:^|[\n;])\s*(?:import\s+(?:type\s+)?|export\s+(?:type\s+)?(?=[*{]))[^;'"]*?\bfrom\s+['"]([^'"]+)['"]/g;
+const SIDE_EFFECT_IMPORT_RE = /(?:^|[\n;])\s*import\s+['"]([^'"]+)['"]/g;
+const DYNAMIC_IMPORT_RE = /\b(?:import|require)\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+function toPosix(p: string): string {
+  return p.split(sep).join("/");
+}
+
+function rel(abs: string): string {
+  return toPosix(relative(ROOT, abs));
+}
+
+function walk(dir: string, match: RegExp, out: string[] = []): string[] {
+  if (!existsSync(dir)) return out;
+  for (const entry of readdirSync(dir)) {
+    if (SKIP_DIRS.has(entry)) continue;
+    const p = join(dir, entry);
+    if (statSync(p).isDirectory()) walk(p, match, out);
+    else if (match.test(entry) && !entry.endsWith(".d.ts")) out.push(p);
+  }
+  return out;
+}
+
+/** Every workspace in this repo: `apps/<name>` for each app dir, plus `database`. */
+function workspacesOnDisk(): string[] {
+  const out: string[] = [];
+  const appsDir = join(ROOT, "apps");
+  if (existsSync(appsDir)) {
+    for (const entry of readdirSync(appsDir).sort()) {
+      if (statSync(join(appsDir, entry)).isDirectory()) out.push(`apps/${entry}`);
+    }
+  }
+  if (existsSync(join(ROOT, "database"))) out.push("database");
+  return out;
+}
+
+/** Package name → workspace, read from each workspace's own package.json. */
+function packageNames(workspaces: string[]): Map<string, string> {
+  const names = new Map<string, string>();
+  for (const ws of workspaces) {
+    const pkgPath = join(ROOT, ws, "package.json");
+    if (!existsSync(pkgPath)) continue;
+    const name = (JSON.parse(readFileSync(pkgPath, "utf8")) as { name?: unknown })
+      .name;
+    if (typeof name === "string") names.set(name, ws);
+  }
+  return names;
+}
+
+function workspaceOfPath(relPath: string, workspaces: string[]): string | null {
+  for (const ws of workspaces) {
+    if (relPath === ws || relPath.startsWith(`${ws}/`)) return ws;
+  }
+  return null;
+}
+
+function extractImports(content: string): { specifier: string; line: number }[] {
+  const lineOf = (offset: number) => content.slice(0, offset).split("\n").length;
+  const out: { specifier: string; line: number }[] = [];
+  for (const re of [IMPORT_RE, SIDE_EFFECT_IMPORT_RE, DYNAMIC_IMPORT_RE]) {
+    for (const m of content.matchAll(re)) {
+      // The newline/semicolon (and blank lines) the static regexes anchor on
+      // belong to earlier lines; count from the import keyword itself.
+      const lead = Math.max(0, m[0].search(/[^\s;]/));
+      if (m[1]) out.push({ specifier: m[1], line: lineOf((m.index ?? 0) + lead) });
+    }
+  }
+  return out;
+}
+
+function resolveTarget(
+  file: string,
+  specifier: string,
+  workspaces: string[],
+  names: Map<string, string>,
+): string | null {
+  if (specifier.startsWith(".")) {
+    return workspaceOfPath(rel(resolve(dirname(file), specifier)), workspaces);
+  }
+  for (const [name, ws] of names) {
+    if (specifier === name || specifier.startsWith(`${name}/`)) return ws;
+  }
+  return null;
+}
+
+function checkImport(
+  fileWs: string,
+  targetWs: string,
+  cfg: ArchConfig,
+): { rule: string; reason: string } | null {
+  if (targetWs.startsWith("apps/")) {
+    return fileWs.startsWith("apps/")
+      ? {
+          rule: `${fileWs} may not import ${targetWs} — apps do not import apps`,
+          reason:
+            "Apps talk over HTTP (web → api) and MCP (mcp → api); shared code belongs in a package.",
+        }
+      : {
+          rule: `${fileWs} may not import ${targetWs} — the data tier imports no app`,
+          reason: "database/ sits below every app; apps import it, never the reverse.",
+        };
+  }
+  const rule = fileWs.startsWith("apps/")
+    ? cfg.apps?.[fileWs.slice("apps/".length)]
+    : undefined;
+  if (!rule) return null;
+  if (rule.may_not_import_from?.includes(targetWs)) {
+    return {
+      rule: `${fileWs} may_not_import_from ${targetWs}`,
+      reason: "Forbidden by architecture.yaml",
+    };
+  }
+  if (rule.may_import_from?.length && !rule.may_import_from.includes(targetWs)) {
+    return {
+      rule: `${fileWs} may_import_from does not include ${targetWs}`,
+      reason: `Not on ${fileWs}'s allowlist in architecture.yaml`,
+    };
+  }
+  return null;
+}
+
+function isExcluded(relPath: string, globs: string[] | undefined): boolean {
+  return (globs ?? []).some((glob) =>
+    glob.endsWith("/**") ? relPath.startsWith(glob.slice(0, -2)) : relPath === glob,
+  );
+}
+
+function checkForbiddenPattern(
+  file: string,
+  content: string,
+  fp: ForbiddenPattern,
+): Violation[] {
+  if (isExcluded(rel(file), fp.paths_excluded)) return [];
+  const re = new RegExp(fp.pattern);
+  const out: Violation[] = [];
+  content.split("\n").forEach((text, i) => {
+    if (re.test(text)) {
+      out.push({ file, line: i + 1, rule: `forbidden_pattern: ${fp.pattern}`, reason: fp.reason });
+    }
+  });
+  return out;
+}
+
+/** Namespace boundaries inside database/ — imports and Prisma @relation. */
+function checkNamespaces(cfg: ArchConfig): Violation[] {
+  const members = Object.values(cfg.namespaces?.members ?? {}).map((m) => m.path);
+  if (members.length === 0) return [];
+  const nsOf = (relPath: string) => workspaceOfPath(relPath, members);
+  const dbDir = join(ROOT, "database");
+  const out: Violation[] = [];
+
+  for (const file of walk(dbDir, /\.tsx?$/)) {
+    const fromNs = nsOf(rel(file));
+    if (!fromNs) continue;
+    for (const imp of extractImports(readFileSync(file, "utf8"))) {
+      if (!imp.specifier.startsWith(".")) continue;
+      const toNs = nsOf(rel(resolve(dirname(file), imp.specifier)));
+      if (!toNs || toNs === fromNs) continue;
+      out.push({
+        file,
+        line: imp.line,
+        rule: `cross-namespace-import: ${fromNs} may not import ${toNs}`,
+        reason: "Cross-namespace data assembly routes through apps/api.",
+      });
+    }
+  }
+
+  const prismaFiles = walk(dbDir, /\.prisma$/);
+  const modelNs = new Map<string, string>();
+  for (const file of prismaFiles) {
+    const ns = nsOf(rel(file));
+    if (!ns) continue;
+    for (const m of readFileSync(file, "utf8").matchAll(/^\s*model\s+(\w+)\s*\{/gm)) {
+      if (m[1] && !modelNs.has(m[1])) modelNs.set(m[1], ns);
+    }
+  }
+  const relationLine = /^\s*\w+\s+(\w+)(\?|\[\])?\s+@relation\s*\(/;
+  for (const file of prismaFiles) {
+    const fromNs = nsOf(rel(file));
+    if (!fromNs) continue;
+    readFileSync(file, "utf8")
+      .split("\n")
+      .forEach((text, i) => {
+        const model = relationLine.exec(text)?.[1];
+        const toNs = model ? modelNs.get(model) : undefined;
+        if (!toNs || toNs === fromNs) return;
+        out.push({
+          file,
+          line: i + 1,
+          rule: `cross-namespace-prisma-relation: ${fromNs} may not relate to ${toNs}`,
+          reason: `@relation to model '${model}' crosses a namespace boundary.`,
+        });
+      });
+  }
+  return out;
+}
+
+function main(): void {
+  const yamlPath = join(ROOT, "architecture.yaml");
+  if (!existsSync(yamlPath)) {
+    console.error(`architecture: no architecture.yaml at ${ROOT}`);
+    process.exitCode = 1;
+    return;
+  }
+  const cfg = (parseYaml(readFileSync(yamlPath, "utf8")) ?? {}) as ArchConfig;
+  const workspaces = workspacesOnDisk();
+  const names = packageNames(workspaces);
+  const violations: Violation[] = [];
+
+  for (const ws of workspaces) {
+    for (const file of walk(join(ROOT, ws), /\.tsx?$/)) {
+      const content = readFileSync(file, "utf8");
+      for (const imp of extractImports(content)) {
+        const targetWs = resolveTarget(file, imp.specifier, workspaces, names);
+        if (!targetWs || targetWs === ws) continue;
+        const v = checkImport(ws, targetWs, cfg);
+        if (v) violations.push({ file, line: imp.line, ...v });
+      }
+      for (const fp of cfg.forbidden_patterns ?? []) {
+        violations.push(...checkForbiddenPattern(file, content, fp));
+      }
+      const app = ws.startsWith("apps/") ? cfg.apps?.[ws.slice("apps/".length)] : undefined;
+      for (const fp of app?.forbidden_patterns ?? []) {
+        violations.push(...checkForbiddenPattern(file, content, fp));
+      }
+    }
+  }
+  violations.push(...checkNamespaces(cfg));
+
+  if (violations.length === 0) {
+    console.log("architecture: OK");
+    return;
+  }
+  console.error(`architecture: ${violations.length} violation(s)`);
+  for (const v of violations) {
+    console.error(`  ${rel(v.file)}:${v.line}  ${v.rule}`);
+    console.error(`    ${v.reason}`);
+  }
+  // exitCode, not exit(): stderr to a pipe is asynchronous on macOS, and the
+  // hook reads this report through one.
+  process.exitCode = 1;
+}
+
+main();

package/templates/tools/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["*.ts"]
+}

package/versions.json

@@ -1,39 +1,39 @@
 {
-  "@working-theory/admin-ui": "0.26.0",
-  "@working-theory/aeo": "0.26.0",
-  "@working-theory/agent-context": "0.26.0",
+  "@working-theory/admin-ui": "0.28.0",
+  "@working-theory/aeo": "0.28.0",
+  "@working-theory/agent-context": "0.28.0",
   "@working-theory/agent-contract": "0.1.0",
   "@working-theory/agent-memory": "0.0.0",
   "@working-theory/ai": "0.1.0",
-  "@working-theory/analytics": "0.26.0",
-  "@working-theory/api-client": "0.26.0",
+  "@working-theory/analytics": "0.28.0",
+  "@working-theory/api-client": "0.28.0",
   "@working-theory/cda-filesystem": "0.0.0",
-  "@working-theory/cli": "0.26.0",
-  "@working-theory/common": "0.26.0",
+  "@working-theory/cli": "0.28.0",
+  "@working-theory/common": "0.28.0",
   "@working-theory/consent": "0.1.0",
-  "@working-theory/content-adapters": "0.26.0",
-  "@working-theory/content-projection": "0.26.0",
-  "@working-theory/email": "0.26.0",
+  "@working-theory/content-adapters": "0.28.0",
+  "@working-theory/content-projection": "0.28.0",
+  "@working-theory/email": "0.28.0",
   "@working-theory/env": "0.0.0",
-  "@working-theory/eslint-config": "0.26.0",
-  "@working-theory/fumadocs-schema": "0.26.0",
+  "@working-theory/eslint-config": "0.28.0",
+  "@working-theory/fumadocs-schema": "0.28.0",
   "@working-theory/ids": "0.8.0",
-  "@working-theory/jsonld": "0.26.0",
-  "@working-theory/license": "0.26.0",
-  "@working-theory/metadata": "0.26.0",
-  "@working-theory/observability": "0.26.0",
-  "@working-theory/page-renderer": "0.26.0",
-  "@working-theory/schema": "0.26.0",
-  "@working-theory/schema-pack-registry": "0.26.0",
-  "@working-theory/schema-validator": "0.26.0",
-  "@working-theory/sections-registry": "0.26.0",
-  "@working-theory/site-config": "0.26.0",
-  "@working-theory/stripe-client": "0.26.0",
-  "@working-theory/templates": "0.26.0",
-  "@working-theory/theme": "0.26.0",
-  "@working-theory/ui": "0.26.0",
-  "@working-theory/validation": "0.26.0",
-  "@working-theory/web-i18n": "0.26.0",
+  "@working-theory/jsonld": "0.28.0",
+  "@working-theory/license": "0.28.0",
+  "@working-theory/metadata": "0.28.0",
+  "@working-theory/observability": "0.28.0",
+  "@working-theory/page-renderer": "0.28.0",
+  "@working-theory/schema": "0.28.0",
+  "@working-theory/schema-pack-registry": "0.28.0",
+  "@working-theory/schema-validator": "0.28.0",
+  "@working-theory/sections-registry": "0.28.0",
+  "@working-theory/site-config": "0.28.0",
+  "@working-theory/stripe-client": "0.28.0",
+  "@working-theory/templates": "0.28.0",
+  "@working-theory/theme": "0.28.0",
+  "@working-theory/ui": "0.28.0",
+  "@working-theory/validation": "0.28.0",
+  "@working-theory/web-i18n": "0.28.0",
   "@working-theory/billing-client": "0.0.0",
   "@working-theory/branding": "0.0.0",
   "@working-theory/license-client": "0.0.0",
@@ -41,12 +41,12 @@
   "@working-theory/marketing-api-client": "0.0.0",
   "@working-theory/partner-session": "0.0.0",
   "@working-theory/preview-protocol": "0.0.0",
-  "@working-theory/ui-commerce": "0.23.3",
-  "@working-theory/ui-docs-blog": "0.23.3",
-  "@working-theory/ui-scheduling": "0.23.3",
-  "@working-theory/ui-signal-collectors": "0.24.1",
+  "@working-theory/ui-commerce": "0.23.5",
+  "@working-theory/ui-docs-blog": "0.23.5",
+  "@working-theory/ui-scheduling": "0.23.5",
+  "@working-theory/ui-signal-collectors": "0.24.3",
   "@working-theory/web": "0.0.0",
   "@working-theory/api": "1.0.0",
   "@working-theory/mcp": "0.0.0",
-  "@working-theory/database": "0.26.0"
+  "@working-theory/database": "0.28.0"
 }

package/site-templates/simple-service/DESIGN.md

@@ -1,148 +0,0 @@
----
-name: Simple service (Pro) — simple-service
-description: A local-service site: three priced services, online booking, checkout, and the policy pages a paying customer expects.
-colors:
-  bg: "#ffffff"
-  fg: "#000000"
-  surface: "#ffffff"
-  surface-secondary: "#ffffff"
-  border: "#000000"
-  text-muted: "#333333"
-  brand: "#000000"
-  fg-on-brand: "#ffffff"
-  accent: "#000000"
-  bg-dark: "#000000"
-  fg-dark: "#ffffff"
-  border-dark: "#ffffff"
-  brand-dark: "#ffffff"
-typography:
-  display:
-    fontFamily: "system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif"
-    fontSize: "6rem"
-    fontWeight: 400
-    lineHeight: 1
-    letterSpacing: "-0.05em"
-  heading-section:
-    fontFamily: "system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif"
-    fontSize: "2.25rem"
-    fontWeight: 400
-    lineHeight: 1.25
-    letterSpacing: "-0.05em"
-  heading-item:
-    fontSize: "1.25rem"
-    fontWeight: 600
-    lineHeight: 1.375
-  body:
-    fontFamily: "system-ui, -apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif"
-    fontSize: "1.125rem"
-    fontWeight: 400
-    lineHeight: 1.5
-  eyebrow:
-    fontSize: "0.875rem"
-    fontWeight: 600
-    lineHeight: 1.4
-    letterSpacing: "0.05em"
-rounded:
-  button: "0.25rem"
-  card: "0.75rem"
-spacing:
-  section: "4rem"
-  card: "1.5rem"
-  grid: "1.5rem"
-  container: "1280px"
----
-
-<!--
-  Source template: simple-service
-  Version: create-ailk {{CREATE_AILK_VERSION}}
-  Extends: _base — installing this template replaces the base scaffold's
-  DESIGN.md with this file. Its tokens are the base foundation's, unchanged:
-  this template carries no theme of its own.
-
-  The tokens above describe what the site RENDERS today. Colours come from
-  content/_site.mdx (`theme.colors`); type, radius and spacing are platform
-  defaults a site cannot override yet — see "Where this is heading" below.
--->
-
-# Simple service (Pro)
-
-## Overview
-
-A template for a local service business — the reference shape is a lawn-care company. Three priced services, a booking page, a checkout return pair, a customer account, and the returns, cancellation and shipping policies. It runs on the base foundation; the design job is trust and clarity, so nothing competes with the price and the book button.
-
-## Colors
-
-### Primary
-
-**Black** (`brand` `#000000`) fills the primary button; its label is white. The secondary button is white with a black hairline and black label.
-
-### Neutral
-
-Pure white ground (`bg` `#ffffff`), pure black ink for headings (`fg` `#000000`), and near-black `#333333` for body copy — well above AA on white. **Borders are black** (`#000000`): card outlines, the rule under the navigation, the rules between sections and the rule above the footer are all 1px black lines. Cards are white, not tinted (`surface-secondary` is white too). There is no accent colour — `accent` is black.
-
-Dark mode inverts: black ground, white ink, white rules, white primary button with black label.
-
-### Named Rules
-
-- **Rules, not fills.** A container is drawn with a black hairline on the white ground. Grey fills are reserved for image placeholders.
-
-## Typography
-
-System sans throughout; no web font.
-
-### Hierarchy
-
-| Role            | Size     | Weight | Notes                                                                       |
-| --------------- | -------- | ------ | --------------------------------------------------------------------------- |
-| Hero headline   | 6rem     | 400    | Tracking -0.05em, line-height 1                                             |
-| Section heading | 2.25rem  | 400    | Tracking -0.05em — light and tight, not bold                                |
-| Item heading    | 1.25rem  | 600    | Card, feature and step titles                                               |
-| Body            | 1.125rem | 400    | `#333333`, line-height 1.5                                                  |
-| Section label   | 0.875rem | 600    | Uppercase, +0.05em tracking today — the small label above a section heading |
-
-Measured from the rendered scaffold (1440px wide), not transcribed from tokens.
-
-The small label above a section heading is **kept** as part of this foundation's voice (operator-disposed 2026-09-22) and is headed toward the treatment below.
-
-## Layout
-
-Full navigation with the announcement banner; a multi-column footer; the default home. Every page and its sections are listed in `TEMPLATE-MANIFEST.md` in this directory. Shared foundation: a 1280px container, sections at 4rem, card grids at 1.5rem, breakpoints 320 / 768 / 1024 / 1440.
-
-## Shapes
-
-Two radii today: buttons at 0.25rem, cards and outlined boxes at 0.75rem. Headed toward square corners — see below.
-
-## Components
-
-### Buttons
-
-Primary: black fill, white label, 0.25rem corners. Secondary: transparent with a black 1px outline and black label. Both are the library `Button`.
-
-### Cards / Containers
-
-White panels with a black 1px outline, 0.75rem corners, `card` (1.5rem) padding. The one exception today: the "how it works" steps render as dark filled cards (see below).
-
-### Navigation
-
-Full navigation: wordmark left, page links, an outlined and a filled button at the far right, the announcement banner above. A black hairline separates it from the page.
-
-## Where this is heading
-
-The foundation's pinned direction is the pacing of a classic wireframe marketing kit — `standardissue.webflow.io` is the reference for rhythm, type scale, spacing density and section pacing only; no image, copy or code is taken from it. Six parts of that direction cannot be expressed through a site's theme today, so they wait on a platform change rather than being hand-coded. Until they land, this file describes the rendered site above, not these targets.
-
-| Target                                            | Reference value                                                                                                                  | Blocked by                                                                                               |
-| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| Square corners on buttons, cards and inputs       | radius 0                                                                                                                         | A site's `theme:` block accepts colours only — no radius                                                 |
-| Bold, tighter headings                            | hero ~3.6rem and section headings ~2.9rem, both at weight 700 with tracking about -0.02em (today 6rem and 2.25rem at weight 400) | No per-site type-role override                                                                           |
-| Generous section pacing                           | about 10rem between sections, not 4rem                                                                                           | No per-site section-spacing override; `spacious` (6rem) is not author-selectable                         |
-| Section label in sentence case, bold, no tracking | "Core Features", not "CORE FEATURES"                                                                                             | The eyebrow role bakes in uppercase and tracking                                                         |
-| Whitespace between sections, not rules            | no rule between bands                                                                                                            | Section dividers share the one `border` colour with card outlines, so black outlines make black dividers |
-| Outlined steps in "how it works"                  | three plain outlined columns                                                                                                     | The steps section renders dark filled cards; no outlined variant                                         |
-
-## Do's and Don'ts
-
-- **Do** keep every page built from registered sections. If a section you need does not exist, request it rather than writing one-off markup.
-- **Do** change colours in `content/_site.mdx` `theme.colors`; they reach every section.
-- **Don't** add a colour accent. The foundation's one idea is black on white; a brand pass adds colour deliberately, through the theme.
-- **Don't** replace a black rule with a shadow or a grey fill.
-- **Don't** hard-code the "heading toward" values above into a page. They arrive through the platform, or not at all.