create-ailk 0.1.0 → 0.2.0

package/dist/surfaces.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Route-surface registry — which public routes a scaffolded site carries.
+ *
+ * A SURFACE is one public route surface of the presentation tier (see
+ * architecture.yaml `composition_model`): a hub route plus the detail route and
+ * content directories that feed it. The registry is the single source of the
+ * surface vocabulary, in the same spirit as `module-architecture.ts` is the
+ * single source of the module→architecture-slice mapping — a code registry, not
+ * N hand-maintained template trees.
+ *
+ * Two tiers:
+ *
+ *   - CORE_SURFACE_PATHS — the routes every AILK site has regardless of what
+ *     the business is (`/`, `/about`, `/contact`, `/faq`, `/thanks/{slug}`).
+ *     Always scaffolded, never gateable.
+ *   - GATEABLE_SURFACES — everything else. A surface is scaffolded ONLY when
+ *     the declared architecture carries it; otherwise its route directories are
+ *     skipped by `copyTemplate` and the routes are ABSENT from the scaffold,
+ *     not present-and-placeholdering (spec #4154 D1).
+ *
+ * The default (`--modules marketing`) enables NO gateable surface: every one of
+ * them is a claim about the business that the scaffolder cannot make. The path
+ * from there is the `suggest-site-pages` → `scaffold-page` skill pair that
+ * already ships in `templates/.claude/skills/`.
+ *
+ * Zero runtime dependencies — create-ailk is a published, standalone CLI.
+ *
+ * Deliberately imports nothing from `parse-args.ts`: that module imports THIS
+ * one (for the `--surfaces` vocabulary in its help text), so a back-import
+ * would close a cycle. The module vocabulary is re-stated here as the keys of
+ * `MODULE_SURFACES`, and `__tests__/surface-gating.test.ts` asserts those keys
+ * equal `RECOGNIZED_MODULES` so the two cannot drift.
+ */
+/**
+ * Route paths (site-relative, for the record written into `architecture.yaml`)
+ * that every scaffold carries.
+ *
+ * `/thanks/{slug}` is a DETAIL route only — `app/[locale]/thanks/` holds just
+ * `[slug]/page.tsx`, there is no `/thanks` hub — and it is the completion target
+ * `/contact`'s forms hand off to, so it travels with core rather than standing
+ * alone as a gateable surface. It ships no starter content: a confirmation page
+ * is authored per form, when the form exists.
+ */
+export declare const CORE_SURFACE_PATHS: readonly string[];
+/** Template-relative route directories that are always copied. */
+export declare const CORE_ROUTE_DIRS: readonly string[];
+/**
+ * Directory names skipped by `listTemplateRouteDirs`'s walker even though they
+ * hold direct files — co-located helper trees, never routes of their own.
+ * `__tests__` is the original member; `components` is `#5014`'s addition
+ * (`(authed)/waitlist/components/`) — a route dir's own subtree copy already
+ * brings either kind along, so registering them as independent syncable units
+ * would be both redundant and, for `components`, unresolvable (no page/route
+ * file, so no `ROUTE_SINCE` entry would ever be correct for it).
+ */
+export declare const NON_ROUTE_DIRS: ReadonlySet<string>;
+/** One gateable public route surface. */
+export interface Surface {
+    /** Surface id — the `--surfaces` vocabulary. Kebab-case, matches the route segment. */
+    id: string;
+    /** Template-relative route directories this surface owns (hub + detail). */
+    routes: string[];
+    /**
+     * Content directories this surface's routes read, template-relative with a
+     * `<locale>` placeholder. Empty for API-backed or content-free surfaces.
+     * Informational: it documents what feeds the surface and backs the by-hand
+     * prune an adopting site does. A fresh scaffold ships no content for a
+     * gateable surface (see D3).
+     */
+    content: string[];
+    /**
+     * Key in the `nav` translations namespace for this surface's site-nav entry,
+     * when it has one. Only surfaces with a label key appear in the generated
+     * `nav-config.ts`; the rest are reachable but not linked until the site owner
+     * adds an entry (and its label) themselves.
+     */
+    navLabelKey?: string;
+}
+/**
+ * The gateable surface vocabulary, sorted by id (the sort IS the emitted
+ * `available:` order — keep it alphabetical so the derivation stays
+ * byte-deterministic).
+ */
+export declare const GATEABLE_SURFACES: readonly Surface[];
+/** The recognized `--surfaces` vocabulary, sorted. */
+export declare const RECOGNIZED_SURFACES: readonly string[];
+/**
+ * Surfaces each recognized module contributes.
+ *
+ * `marketing` (the default) contributes NONE — a default scaffold is core-only.
+ * `docs` mounts the Fumadocs presentation surface; `multi-tenant` brings the
+ * flow-stepper surface with its API-backed engine; `scheduling` brings the
+ * booking page and the confirmation page the module owns.
+ */
+export declare const MODULE_SURFACES: Record<string, readonly string[]>;
+/** Thrown on an unrecognized surface id. Mirrors parse-args' ParseError shape. */
+export declare class SurfaceError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a surface CSV (the `--surfaces` value) into a validated, normalized,
+ * sorted, deduped list.
+ *
+ * Splits on `,`, trims + lowercases each entry, drops empties, and validates
+ * each against RECOGNIZED_SURFACES. An absent flag (or an all-empty value)
+ * yields the empty list — the caller composes it with the module-derived set.
+ *
+ * @throws SurfaceError on an unrecognized surface id, naming the vocabulary.
+ */
+export declare function parseSurfaces(raw: string | undefined): string[];
+/**
+ * Resolve the enabled gateable-surface set from the selected modules plus any
+ * explicitly requested surfaces.
+ *
+ * The result is a sorted, deduped set — the same (modules, explicit) input
+ * always yields the same output, so both the copied tree and the derived
+ * `architecture.yaml` stay byte-deterministic.
+ */
+export declare function resolveSurfaces(modules?: string[], explicit?: string[]): string[];
+/**
+ * The template-relative route directories to SKIP when copying the template —
+ * every gateable surface not in `enabled`.
+ *
+ * Paths are emitted with forward slashes (the template tree's own separator);
+ * `copy.ts` normalizes the walked path before matching so the comparison holds
+ * on Windows too.
+ */
+export declare function excludedRoutePaths(enabled: string[]): string[];
+/**
+ * The content directories belonging to gateable surfaces that are NOT enabled,
+ * with `<locale>` left in place for the caller to expand.
+ *
+ * Consumed by the sync-mode drift report so an already-scaffolded site is told
+ * about orphan content as well as orphan routes — orphan content is not inert:
+ * `/sitemap.xml` and `/llms.txt` enumerate the content adapter, so content whose
+ * route has been removed would advertise URLs that 404.
+ */
+export declare function excludedContentPaths(enabled: string[]): string[];
+/**
+ * Route manifest (#4986): every template route directory, keyed relative to
+ * ROUTE_ROOT (`apps/web/app/[locale]`), → the `@working-theory/*` fixed-group
+ * release line (`.changeset/config.json` `fixed`) that first carried it — the
+ * version a consumer pins, so `sync-routes` can say "added in 0.14.0".
+ * create-ailk's own version is changesets-ignored and is NOT the axis.
+ *
+ * A route directory is a directory under ROUTE_ROOT that directly holds at
+ * least one file, excluding `__tests__` trees, whose top segment the registry
+ * recognizes (CORE_ROUTE_DIRS or a gateable surface's `routes`). Adding a
+ * route directory to the template REQUIRES an entry here —
+ * `__tests__/sync-routes.test.ts` fails otherwise.
+ *
+ * `0.0.0` = predates the manifest; the first release that carried it is not
+ * recoverable (history was squashed, no tags). Only the recommender routes
+ * (#4891, 0.14.0) are attributable.
+ */
+export declare const ROUTE_SINCE: Readonly<Record<string, string>>;
+/**
+ * Surface id of the registry that owns `routeDir` (ROUTE_ROOT-relative): the
+ * string `"core"` for CORE_ROUTE_DIRS, `"authed"` for the `(authed)` route
+ * GROUP (#5014 — syncable like core, but reported under its own identity
+ * rather than conflated with CORE_ROUTE_DIRS's always-copied set, since it is
+ * a route GROUP rather than a route directory of its own), a gateable
+ * surface's id, or undefined when the top segment is outside the registry
+ * entirely.
+ */
+export declare function surfaceForRouteDir(routeDir: string): string | undefined;
+/**
+ * Non-route consumer-side files a route's own source imports, that a sync
+ * must ALSO bring along so `--apply` never leaves a route that cannot
+ * compile (#5014's third clause). Template-relative, `/`-separated, keyed by
+ * the same route string `ROUTE_SINCE` uses. `sync-routes` copies a listed
+ * file only when the target does not already have it — it never overwrites,
+ * the same rule routes themselves follow.
+ *
+ * `(authed)/account` depending on two files INSIDE `(authed)/waitlist`
+ * (`ForbiddenState.tsx`, `format.ts`) is real, found by reading the account
+ * page's own imports, not guessed from the issue text: the account page
+ * renders a shared "forbidden" empty state and shared count/date formatters
+ * that the waitlist dashboard also uses, rather than duplicating them.
+ */
+export declare const ROUTE_DEPENDENCIES: Readonly<Record<string, readonly string[]>>;
+/**
+ * i18n message namespaces (dot-path into `apps/web/messages/<locale>.json`) a
+ * route needs (#5014's third clause). CHECK-ONLY: a consumer's `messages/`
+ * file already exists in every scaffold (it is not itself route-gated) and
+ * may carry the site owner's own edits, so `sync-routes` reports a missing
+ * namespace rather than attempting to merge JSON keys into it — a blind merge
+ * risks corrupting hand-authored translations. Adding the namespace is left
+ * to the site owner, same as any other reported gap.
+ */
+export declare const ROUTE_MESSAGE_NAMESPACES: Readonly<Record<string, readonly string[]>>;
+/** Template-relative path of the generated site-nav registry. */
+export declare const NAV_CONFIG_PATH = "apps/web/lib/nav-config.ts";
+/**
+ * Render `apps/web/lib/nav-config.ts` for an enabled surface set.
+ *
+ * The site nav is NOT content-derived — it is a static list the layout renders
+ * into the header and the footer. Left as the template ships it, a gated
+ * scaffold would link `/docs` and `/blog` on every page while neither route
+ * exists: two dead links, sitewide, by default. So the nav follows the declared
+ * surface set for the same reason the route tree does.
+ *
+ * Only surfaces carrying a `navLabelKey` are linked, because a nav entry needs
+ * a translated label and the template's `nav` namespace ships keys for exactly
+ * `home`, `docs`, and `blog`. Emitting an entry whose `labelKey` has no
+ * translation would trade a dead link for a missing-message error.
+ *
+ * Deterministic: entries follow GATEABLE_SURFACES order (alphabetical by id),
+ * after the always-present home entry.
+ */
+export declare function renderNavConfig(enabled: string[]): string;