create-ailk 0.1.0

package/dist/programmatic.js

@@ -0,0 +1,89 @@
+/**
+ * Programmatic API for create-ailk.
+ *
+ * Extracts the core scaffolding logic from cli.ts so it can be exercised
+ * directly in tests and by other consumers without spawning a subprocess.
+ *
+ * The CLI entry point (cli.ts) delegates to scaffoldSync() here; no logic is
+ * duplicated between the CLI and the programmatic surface.
+ *
+ * Usage (async, for MCP tool or external tooling):
+ *   import { scaffold } from './programmatic.js';
+ *   const result = await scaffold({ targetDir: '/tmp/my-site', projectName: 'my-site' });
+ *
+ * Usage (sync, for the CLI):
+ *   import { scaffoldSync } from './programmatic.js';
+ *   const result = scaffoldSync({ targetDir: '/tmp/my-site', projectName: 'my-site' });
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { copyTemplate } from "./copy.js";
+import { validateTarget } from "./validate.js";
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const TEMPLATES_DIR = resolve(PKG_ROOT, "templates");
+const VERSIONS_FILE = resolve(PKG_ROOT, "versions.json");
+function readVersionMap() {
+    if (!existsSync(VERSIONS_FILE)) {
+        // Empty map is a valid state for tests / dev where build-templates has
+        // not been re-run since the last clean.
+        return {};
+    }
+    const raw = readFileSync(VERSIONS_FILE, "utf8");
+    return JSON.parse(raw);
+}
+/**
+ * Count all files recursively under a directory. Used to report filesCreated.
+ */
+function countFiles(dir) {
+    if (!existsSync(dir))
+        return 0;
+    let count = 0;
+    const stack = [dir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                stack.push(`${current}/${entry.name}`);
+            }
+            else {
+                count++;
+            }
+        }
+    }
+    return count;
+}
+/**
+ * Scaffold an AI Launch Kit starter project into targetDir (synchronous).
+ *
+ * Throws ValidationError if targetDir already exists and is non-empty.
+ * Throws Error if the template copy fails for any other reason.
+ */
+export function scaffoldSync(opts) {
+    // Validate target — throws ValidationError on rejection.
+    const targetAbs = validateTarget(opts.targetDir);
+    const projectName = opts.projectName ?? basename(targetAbs);
+    const versions = readVersionMap();
+    copyTemplate({
+        templatesDir: TEMPLATES_DIR,
+        targetDir: targetAbs,
+        versions,
+        markers: {
+            PROJECT_NAME: projectName,
+            COMPANY_NAME: "Your Company",
+            COMPANY_DOMAIN: "example.com",
+        },
+    });
+    const filesCreated = countFiles(targetAbs);
+    return { targetDir: targetAbs, filesCreated };
+}
+/**
+ * Scaffold an AI Launch Kit starter project into targetDir (async wrapper).
+ *
+ * Wraps scaffoldSync for callers that prefer Promise-based APIs. The
+ * underlying I/O is synchronous; the async signature is provided for
+ * compatibility with async callers (e.g. the MCP tool handler via subprocess).
+ */
+export async function scaffold(opts) {
+    return scaffoldSync(opts);
+}

package/dist/substitute.d.ts

@@ -0,0 +1,31 @@
+/**
+ * String-template substitution helpers.
+ *
+ * Two surfaces:
+ *   - substituteWorkspaceVersions — `workspace:*` → `^<semver>` for @working-theory/*
+ *     deps in package.json text. Throws if a `@working-theory/*` entry has no canonical
+ *     version (escalation per spec §5.3).
+ *   - substituteMarkers — replaces every `{{KEY}}` with the matching value
+ *     from the provided map. Markers without a matching entry are left
+ *     unchanged so the user can author their own.
+ *
+ * The package.json substitution operates on text (regex), not on parsed JSON,
+ * to preserve formatting (whitespace, key order, trailing commas) of the
+ * canonical source. Re-serializing JSON would create gratuitous diffs in
+ * scaffolder output and obscure intent.
+ */
+export type WorkspaceVersionMap = Record<string, string>;
+/**
+ * Replaces every `"@working-theory/<pkg>": "workspace:*"` occurrence with the matching
+ * caret-prefixed version from `versions`. Throws when an `@working-theory/*` entry has
+ * no version map entry.
+ *
+ * Non-`@working-theory/*` deps are not touched; non-package.json input is not touched.
+ */
+export declare function substituteWorkspaceVersions(input: string, versions: WorkspaceVersionMap): string;
+export type MarkerMap = Record<string, string>;
+/**
+ * Replaces `{{KEY}}` markers with values from the provided map. Markers
+ * without a matching entry are left as-is (e.g. user-authored placeholders).
+ */
+export declare function substituteMarkers(input: string, markers: MarkerMap): string;

package/dist/substitute.js

@@ -0,0 +1,45 @@
+/**
+ * String-template substitution helpers.
+ *
+ * Two surfaces:
+ *   - substituteWorkspaceVersions — `workspace:*` → `^<semver>` for @working-theory/*
+ *     deps in package.json text. Throws if a `@working-theory/*` entry has no canonical
+ *     version (escalation per spec §5.3).
+ *   - substituteMarkers — replaces every `{{KEY}}` with the matching value
+ *     from the provided map. Markers without a matching entry are left
+ *     unchanged so the user can author their own.
+ *
+ * The package.json substitution operates on text (regex), not on parsed JSON,
+ * to preserve formatting (whitespace, key order, trailing commas) of the
+ * canonical source. Re-serializing JSON would create gratuitous diffs in
+ * scaffolder output and obscure intent.
+ */
+/**
+ * Replaces every `"@working-theory/<pkg>": "workspace:*"` occurrence with the matching
+ * caret-prefixed version from `versions`. Throws when an `@working-theory/*` entry has
+ * no version map entry.
+ *
+ * Non-`@working-theory/*` deps are not touched; non-package.json input is not touched.
+ */
+export function substituteWorkspaceVersions(input, versions) {
+    // Match `"@working-theory/<name>": "workspace:*"` with arbitrary whitespace between
+    // the colon and the value. The captured group is the package name.
+    const re = /"(@working-theory\/[a-z0-9-]+)"(\s*:\s*)"workspace:\*"/g;
+    return input.replace(re, (_match, pkg, sep) => {
+        const v = versions[pkg];
+        if (!v) {
+            throw new Error(`no version found for ${pkg} in canonical workspace map. Update scripts/build-templates.mjs or escalate per spec §5.3.`);
+        }
+        return `"${pkg}"${sep}"^${v}"`;
+    });
+}
+/**
+ * Replaces `{{KEY}}` markers with values from the provided map. Markers
+ * without a matching entry are left as-is (e.g. user-authored placeholders).
+ */
+export function substituteMarkers(input, markers) {
+    return input.replace(/\{\{([A-Z_][A-Z0-9_]*)\}\}/g, (whole, key) => {
+        const value = markers[key];
+        return value !== undefined ? value : whole;
+    });
+}

package/dist/validate.d.ts

@@ -0,0 +1,8 @@
+export declare class ValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates the user-supplied target dir. Returns the resolved absolute path
+ * on success; throws ValidationError on any rejection.
+ */
+export declare function validateTarget(rawTarget: string): string;

package/dist/validate.js

@@ -0,0 +1,70 @@
+/**
+ * Target-directory validation for `create-ailk`.
+ *
+ * Spec §2.2 + §5.1 + §5.2:
+ *   - Reject if target exists AND is non-empty.
+ *   - Reject if target arg contains `..` (path traversal guard).
+ *   - Reject if target arg contains a NUL byte (`\0`) — defense-in-depth
+ *     against C-string truncation tricks in any downstream syscall path.
+ *   - Reject filesystem root.
+ *   - Reject when the parent directory does not exist (surface user error).
+ *   - Reject when target points at an existing file (not a directory).
+ *
+ * Note on TOCTOU: validation runs before `copyTemplate` performs writes, so
+ * a concurrent process could in principle populate the target between the
+ * two. Acceptable for a CLI run interactively by the user themselves; if
+ * this scaffolder ever runs in an adversarial multi-tenant context, add a
+ * re-check immediately before write.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+export class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ValidationError";
+    }
+}
+/**
+ * Validates the user-supplied target dir. Returns the resolved absolute path
+ * on success; throws ValidationError on any rejection.
+ */
+export function validateTarget(rawTarget) {
+    if (typeof rawTarget !== "string" || rawTarget.length === 0) {
+        throw new ValidationError("target directory must be a non-empty string");
+    }
+    // Defense-in-depth: reject NUL bytes — they truncate C strings on some
+    // syscalls and have no legitimate use in a directory name.
+    if (rawTarget.includes("\0")) {
+        throw new ValidationError("target path contains NUL byte (`\\0`); this is never legitimate");
+    }
+    // Defense-in-depth: reject `..` segments BEFORE resolution. We compare
+    // path-separator-bracketed segments so a directory literally named "..foo"
+    // is allowed (.. only blocks the parent-traversal segment).
+    const segments = rawTarget.split(/[\\/]/);
+    if (segments.some((s) => s === "..")) {
+        throw new ValidationError(`target path contains \`..\` traversal segment: ${rawTarget}`);
+    }
+    const resolved = isAbsolute(rawTarget)
+        ? rawTarget
+        : resolve(process.cwd(), rawTarget);
+    // Reject filesystem root (e.g. `/`, `C:\`).
+    if (resolved === sep || /^[A-Za-z]:[\\/]?$/.test(resolved)) {
+        throw new ValidationError(`target directory cannot be the filesystem root: ${resolved}`);
+    }
+    // Parent must exist.
+    const parent = dirname(resolved);
+    if (!existsSync(parent)) {
+        throw new ValidationError(`parent directory does not exist: ${parent}. Create it first or choose a different path.`);
+    }
+    if (existsSync(resolved)) {
+        const s = statSync(resolved);
+        if (!s.isDirectory()) {
+            throw new ValidationError(`target exists but is not a directory: ${resolved}`);
+        }
+        const entries = readdirSync(resolved);
+        if (entries.length > 0) {
+            throw new ValidationError(`target directory exists and is not empty: ${resolved}`);
+        }
+    }
+    return resolved;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "create-ailk",
+  "version": "0.1.0",
+  "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "create-ailk": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tailwind-ai/ai-launch-kit.git",
+    "directory": "packages/create-ailk"
+  },
+  "homepage": "https://github.com/tailwind-ai/ai-launch-kit/tree/main/packages/create-ailk#readme",
+  "bugs": {
+    "url": "https://github.com/tailwind-ai/ai-launch-kit/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "ailk",
+    "scaffolder",
+    "create-ailk",
+    "ai-launch-kit"
+  ],
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "tsc -b",
+    "type-check": "tsc --noEmit",
+    "test": "tsc -b && node scripts/build-templates.mjs && jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "build-templates": "node scripts/build-templates.mjs"
+  }
+}

package/templates/.claude/agents/web.md

@@ -0,0 +1,80 @@
+---
+name: web
+description: Frontend specialist for apps/web and any project-local UI components. Use when work touches React components, pages, styles, or visitor-facing UX. Not for api routes or schema work.
+allowed_tools: [Read, Edit, Write, Glob, Grep, Bash, Agent]
+model: sonnet
+---
+
+You are the frontend specialist for this project. You own the
+visitor-facing UX surface — the marketing site, any dashboard pages,
+and any project-local components.
+
+## Scope
+
+- `apps/web/**` — Next.js 16 + React 19 app, Server Components by
+  default.
+- Any project-local component or theme overrides you add alongside
+  `apps/web`.
+
+You consume `@working-theory/ui` and `@working-theory/theme` from npm — those are
+upstream packages; don't try to edit them locally.
+
+## Read before edit
+
+1. `.claude/rules/architecture.md` — confirm what `apps/web` may
+   import. NextAuth handlers are the only API-shaped code allowed in
+   `apps/web`; everything else server-side goes through `apps/api`.
+2. The page or component you're modifying, plus any sibling files in
+   the same directory.
+3. Any project-local theme override file before touching styles —
+   tokens come from `@working-theory/theme` unless you've extended it.
+
+## Verification
+
+```bash
+pnpm --filter ./apps/web type-check
+pnpm --filter ./apps/web build
+```
+
+Run `pnpm preflight` before opening a PR.
+
+## Hand-off rules
+
+- Need a new HTTP endpoint? Don't invent it in `apps/web`. Add the
+  route in `apps/api` (or open an issue if you don't own that surface
+  yet) and consume it via `@working-theory/api-client`.
+- Need a new content type? Add it under `content/<TypeName>/` and
+  reference the schema from `@working-theory/schema`.
+- Need a database read? Wrong layer — `apps/web` does not read the
+  database. Route through `apps/api`.
+
+## Domain conventions
+
+- **Server Components by default.** `'use client'` only when the
+  component needs browser-only APIs (state, refs, browser events).
+  Adding `'use client'` to a file that just renders JSX is the
+  default failure mode — resist it.
+- **Tailwind tokens only.** No raw hex, rgb, or arbitrary colors.
+  Use semantic tokens from `@working-theory/theme` (`bg-canvas`, `text-fg`,
+  `border-border`, etc.). If a token doesn't exist, extend the theme;
+  don't bypass.
+- **Mobile-first responsive.** Default styles target mobile;
+  `md:`/`lg:` modifiers for larger viewports.
+- **MDX rendering** uses `next-mdx-remote/rsc`, never `@next/mdx`
+  (the latter requires runtime config that fights Server Components).
+- **NextAuth handlers** are the only API-shaped code in `apps/web`
+  — they live at `apps/web/app/api/auth/[...nextauth]/route.ts`.
+  Everything else goes to `apps/api`.
+
+## Forbidden
+
+- Importing from `apps/api` or `apps/mcp` — these are peer apps;
+  speak to the API via `@working-theory/api-client`.
+- Importing `@working-theory/database` — `apps/web` does not touch the DB;
+  route through `apps/api`.
+- Importing `stripe`, `resend`, `@react-email/*` directly — wrap
+  through `@working-theory/stripe-client` or `@working-theory/email`, server-side via
+  `apps/api`.
+- Adding a `utils.ts`, `helpers.ts`, `common.ts`, or `misc.ts` file
+  — use a descriptive name.
+- Reformatting unrelated lines. Diff is the contract.

package/templates/.claude/rules/architecture.md

@@ -0,0 +1,62 @@
+# Architecture Discipline
+
+## The boundary
+
+`apps/web`, `apps/api`, and `apps/mcp` are **peer apps**. They share
+code via published `@working-theory/*` packages. They do not import from each
+other.
+
+## Why this matters
+
+- The agent surface (`apps/api`, `apps/mcp`) is a co-equal product, not
+  a bolt-on. Coupling apps means changing the agent surface forces
+  changes to the visitor-facing UX.
+- Each app deploys independently. Cross-app imports prevent that.
+- Reading any one app should make sense without reference to the
+  others. If it doesn't, you're carrying coupling that will hurt later.
+
+## How to apply
+
+- Need to share code between apps? Find an existing `@working-theory/*` package
+  that fits, or open an issue upstream at
+  <https://github.com/tailwind-ai/ai-launch-kit> requesting a new one.
+  Do not vendor a copy.
+- Need types shared across apps? Use `@working-theory/validation` (Zod schemas)
+  or `@working-theory/schema` (schema.org types).
+- Need an HTTP call from `apps/web` to `apps/api`? Use
+  `@working-theory/api-client`. Don't import API route handlers directly.
+- Need database access? Only `apps/api` and `apps/mcp` import
+  `@working-theory/database`. `apps/web` never reads the database directly — it
+  goes through the HTTP API.
+- Cross-cutting integrations (auth, payments, email, analytics) go
+  through their wrapper packages: `@working-theory/auth-client`,
+  `@working-theory/stripe-client`, `@working-theory/email`, `@working-theory/analytics`. Never
+  import `next-auth`, `stripe`, `resend`, etc. directly.
+
+## What you can verify, what you can't
+
+- Static imports across boundaries are easy to spot in code review and
+  with most TypeScript tooling.
+- Runtime `fetch` calls to internal-only endpoints are NOT enforced by
+  any tool. Treat `apps/api` like a third-party HTTP API even when
+  you control both ends — version the contract, validate the response.
+- Dynamic `import()` with a runtime-constructed path is also
+  unenforced. Don't use it to evade the boundary.
+
+## Escalation
+
+If a task seems to require crossing a boundary: stop and write a short
+note in `docs/` capturing what you wanted to do and why the boundary
+gets in the way. Don't add the cross-import. Either the boundary moves
+(and you have a record of why) or the task changes shape — both are
+better than a quiet violation.
+
+## Forbidden patterns
+
+These never appear in source code:
+
+- `sk_live_*`, `pk_live_*` — live Stripe keys live in your deployment
+  platform's secrets store, never in source files or `.env`.
+- Direct vendor SDK imports outside the wrapper packages
+  (`import 'stripe'` outside `@working-theory/stripe-client`, etc.).
+- Hardcoded production database URLs in committed files.

package/templates/.claude/rules/preserve-existing-style.md

@@ -0,0 +1,51 @@
+# Preserve Existing Style
+
+When editing existing files, preserve their existing formatting. Do
+**not** reformat, reflow, reorganize imports, change quote style,
+change indentation, or rearrange whitespace on lines that aren't
+materially changing as part of your task.
+
+Your diff should contain only the lines you deliberately touched. A
+20-line functional change should produce a ~20-line diff, not a
+900-line diff with 880 lines of formatting churn.
+
+## Why
+
+Formatting churn:
+
+- Obscures real changes during code review.
+- Creates noise in `git blame` / `git log`.
+- Triggers unnecessary merge conflicts.
+- Violates the spirit of "behavior must not change unless the
+  acceptance criteria say so" — even if runtime behavior is identical,
+  the meaning to a human reader has changed.
+
+## How to apply
+
+- **Before committing:** run `git diff --stat`. If the delta is
+  wildly larger than the work you did, investigate before pushing.
+- **If your editor runs a formatter on save:** disable it for the
+  session, configure it to match the existing style, or revert
+  formatting-only lines before committing.
+- **If quotes, semicolons, or import grouping differ from the
+  existing file:** match the existing file, not your editor's
+  defaults.
+- **The diff is the contract.** A reviewer should see only the lines
+  you meant to change.
+
+## Not covered by this rule
+
+- Deliberate cleanup (removing dead code, inlining single-use
+  helpers, collapsing redundant abstraction) is fine when it's the
+  point of the task and called out in the PR.
+- Net-new files set their own style, subject to the project's
+  existing conventions.
+- A task whose acceptance criteria explicitly say "reformat file X"
+  (rare).
+
+## Escalation
+
+If you believe the existing style is genuinely wrong and want to
+change it: stop. Note it in the PR description and propose the
+reformat as a separate PR. Do not unilaterally reformat the codebase
+as a side effect of an unrelated task.

package/templates/.claude/skills/README.md

@@ -0,0 +1,43 @@
+# Skills
+
+Skills are reusable Claude Code workflows scoped to this project. Each
+lives in its own subdirectory with a `SKILL.md` describing when to use
+it and how it works.
+
+The seven OSS skills below are the canonical AI Launch Kit workflows.
+Their status reflects what's available at the upstream
+<https://github.com/tailwind-ai/ai-launch-kit> repository today. Issue
+numbers in the table refer to that upstream repo (the
+`tailwind-ai/ai-launch-kit#N` form makes the link explicit), not your
+local project's issues.
+
+## Status
+
+| Skill                | Purpose                                                | Status                                               |
+| -------------------- | ------------------------------------------------------ | ---------------------------------------------------- |
+| `suggest-site-pages` | Generic page-type suggestions by category              | coming soon — issue #361 (tailwind-ai/ai-launch-kit) |
+| `scaffold-page`      | Generate a page with the appropriate schema.org type   | coming soon — issue #362 (tailwind-ai/ai-launch-kit) |
+| `scaffold-commerce`  | Sell stuff: external store link or direct payments     | coming soon — issue #363 (tailwind-ai/ai-launch-kit) |
+| `scaffold-auth`      | Wire up an auth flow against `@working-theory/auth-client`       | coming soon — issue #364 (tailwind-ai/ai-launch-kit) |
+| `audit-site`         | Run `ailk audit` and explain the results               | coming soon — issue #365 (tailwind-ai/ai-launch-kit) |
+| `add-schema`         | Add Product / Service / FAQ schema to an existing page | coming soon — issue #366 (tailwind-ai/ai-launch-kit) |
+| `provision-config`   | Generate `vercel.json` and environment templates       | coming soon — issue #367 (tailwind-ai/ai-launch-kit) |
+
+## How a skill ships
+
+When a skill is built upstream, this directory will contain a
+subdirectory of the same name, each holding:
+
+- `SKILL.md` — when to invoke, what it produces, what it requires.
+- Any supporting prompt fragments, code templates, or reference
+  files the skill loads at runtime.
+
+Until then, the workflows the skills will perform can still be done
+by hand or by asking Claude Code directly.
+
+## Adding your own
+
+To add a project-specific skill, create a folder here with a
+`SKILL.md` describing it. Claude Code will discover it automatically
+on session start. See the upstream `@working-theory/*` repository for examples
+of the format.