create-ailk 0.1.0 → 0.2.0

package/dist/surfaces.js

@@ -0,0 +1,532 @@
+/**
+ * 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.
+ */
+/** Template-relative prefix every `apps/web` route directory sits under. */
+const ROUTE_ROOT = "apps/web/app/[locale]";
+/**
+ * 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 const CORE_SURFACE_PATHS = [
+    "/",
+    "/about",
+    "/contact",
+    "/faq",
+    "/thanks/{slug}",
+];
+/** Template-relative route directories that are always copied. */
+export const CORE_ROUTE_DIRS = [
+    `${ROUTE_ROOT}/about`,
+    `${ROUTE_ROOT}/contact`,
+    `${ROUTE_ROOT}/faq`,
+    `${ROUTE_ROOT}/thanks`,
+    // #5014 — ships unconditionally in every scaffold today (SNAPSHOT_DIRS
+    // copies all of apps/web verbatim, no `--surfaces` gating on this route),
+    // so joining CORE_ROUTE_DIRS only makes the REGISTRY match what already
+    // ships — it does not change what a fresh scaffold carries.
+    `${ROUTE_ROOT}/sign-in`,
+];
+/**
+ * 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 const NON_ROUTE_DIRS = new Set([
+    "__tests__",
+    "components",
+]);
+/**
+ * The gateable surface vocabulary, sorted by id (the sort IS the emitted
+ * `available:` order — keep it alphabetical so the derivation stays
+ * byte-deterministic).
+ */
+export const GATEABLE_SURFACES = [
+    {
+        id: "blog",
+        routes: [`${ROUTE_ROOT}/blog`],
+        content: ["apps/web/content/<locale>/blog"],
+        navLabelKey: "blog",
+    },
+    {
+        id: "careers",
+        routes: [`${ROUTE_ROOT}/careers`],
+        content: ["content/<locale>/CareersList", "content/<locale>/JobPosting"],
+    },
+    {
+        id: "case-studies",
+        routes: [`${ROUTE_ROOT}/case-studies`],
+        content: [
+            "content/<locale>/CaseStudiesList",
+            "content/<locale>/CaseStudy",
+        ],
+    },
+    {
+        id: "clients",
+        routes: [`${ROUTE_ROOT}/clients`],
+        content: ["content/<locale>/ClientsList"],
+    },
+    {
+        id: "courses",
+        routes: [`${ROUTE_ROOT}/courses`],
+        content: ["content/<locale>/CoursesList", "content/<locale>/Course"],
+    },
+    {
+        // Dev-only Server-Action ↔ MCP parity harness (`/dev/purchase`). Explicitly
+        // not customer-visible navigation; it has no place in a scaffold by default.
+        id: "dev",
+        routes: [`${ROUTE_ROOT}/dev`],
+        content: [],
+    },
+    {
+        id: "docs",
+        routes: [`${ROUTE_ROOT}/docs`],
+        content: ["apps/web/content/<locale>/docs"],
+        navLabelKey: "docs",
+    },
+    {
+        id: "downloads",
+        routes: [`${ROUTE_ROOT}/downloads`],
+        content: ["content/<locale>/DownloadsList"],
+    },
+    {
+        id: "events",
+        routes: [`${ROUTE_ROOT}/events`],
+        content: ["content/<locale>/EventsList", "content/<locale>/Event"],
+    },
+    {
+        // API-backed (the flow engine); no MDX of its own.
+        id: "flows",
+        routes: [`${ROUTE_ROOT}/flows`],
+        content: [],
+    },
+    {
+        id: "how-to",
+        routes: [`${ROUTE_ROOT}/how-to`],
+        content: ["content/<locale>/HowTo"],
+    },
+    {
+        id: "integrations",
+        routes: [`${ROUTE_ROOT}/integrations`],
+        content: [
+            "content/<locale>/IntegrationsList",
+            "content/<locale>/Integration",
+        ],
+    },
+    {
+        // A single HomePage-typed landing (`HomePage/launch-service.mdx` upstream);
+        // no content directory of its own.
+        id: "launch-service",
+        routes: [`${ROUTE_ROOT}/launch-service`],
+        content: [],
+    },
+    {
+        id: "partners",
+        routes: [`${ROUTE_ROOT}/partners`],
+        content: ["content/<locale>/PartnersList", "content/<locale>/Partner"],
+    },
+    {
+        id: "products",
+        routes: [`${ROUTE_ROOT}/products`],
+        content: ["content/<locale>/ProductsList", "content/<locale>/Product"],
+    },
+    {
+        id: "projects",
+        routes: [`${ROUTE_ROOT}/projects`],
+        content: ["content/<locale>/ProjectsList", "content/<locale>/Project"],
+    },
+    {
+        id: "resources",
+        routes: [`${ROUTE_ROOT}/resources`],
+        content: [
+            "content/<locale>/ResourcesHub",
+            "content/<locale>/ResourceDetail",
+        ],
+    },
+    {
+        // The `scheduling` MODULE's presentation tier — the booking page and the
+        // confirmation page the module OWNS (`/schedule` + `/schedule/confirmed`,
+        // one directory, so one entry gates both). API-backed like `flows`: the
+        // booker reads its slots from apps/api's `/v1/schedule/*` routes and the
+        // event name from `SCHEDULING_CAL_LINK`, so there is no MDX of its own.
+        id: "schedule",
+        routes: [`${ROUTE_ROOT}/schedule`],
+        content: [],
+        navLabelKey: "schedule",
+    },
+    {
+        id: "services",
+        routes: [`${ROUTE_ROOT}/services`],
+        content: ["content/<locale>/ServicesList", "content/<locale>/Service"],
+    },
+    {
+        id: "software",
+        routes: [`${ROUTE_ROOT}/software`],
+        content: ["content/<locale>/SoftwareProduct"],
+    },
+    {
+        id: "tech-articles",
+        routes: [`${ROUTE_ROOT}/tech-articles`],
+        content: ["content/<locale>/TechArticle"],
+    },
+    {
+        id: "testimonials",
+        routes: [`${ROUTE_ROOT}/testimonials`],
+        content: ["content/<locale>/TestimonialsList"],
+    },
+    {
+        id: "use-cases",
+        routes: [`${ROUTE_ROOT}/use-cases`],
+        content: ["content/<locale>/UseCasesList"],
+    },
+    {
+        id: "whitepapers",
+        routes: [`${ROUTE_ROOT}/whitepapers`],
+        content: ["content/<locale>/Whitepaper"],
+    },
+];
+/** The recognized `--surfaces` vocabulary, sorted. */
+export const RECOGNIZED_SURFACES = GATEABLE_SURFACES.map((s) => s.id);
+/**
+ * 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 const MODULE_SURFACES = {
+    marketing: [],
+    docs: ["docs"],
+    "multi-tenant": ["flows"],
+    scheduling: ["schedule"],
+};
+/** Thrown on an unrecognized surface id. Mirrors parse-args' ParseError shape. */
+export class SurfaceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SurfaceError";
+    }
+}
+/**
+ * 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 function parseSurfaces(raw) {
+    if (raw === undefined)
+        return [];
+    const requested = raw
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    for (const s of requested) {
+        if (!RECOGNIZED_SURFACES.includes(s)) {
+            throw new SurfaceError(`unknown surface "${s}". Recognized: ${RECOGNIZED_SURFACES.join(", ")}`);
+        }
+    }
+    return [...new Set(requested)].sort();
+}
+/**
+ * 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 function resolveSurfaces(modules = ["marketing"], explicit = []) {
+    const set = new Set();
+    for (const m of modules) {
+        const contributed = MODULE_SURFACES[m.trim().toLowerCase()];
+        // Defensive: parse-args rejects an unknown module first. Skip rather than
+        // throw a second, differently-worded error for the same bad input.
+        if (contributed === undefined)
+            continue;
+        for (const s of contributed)
+            set.add(s);
+    }
+    for (const s of explicit) {
+        if (!RECOGNIZED_SURFACES.includes(s)) {
+            throw new SurfaceError(`unknown surface "${s}". Recognized: ${RECOGNIZED_SURFACES.join(", ")}`);
+        }
+        set.add(s);
+    }
+    return [...set].sort();
+}
+/**
+ * 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 function excludedRoutePaths(enabled) {
+    const on = new Set(enabled);
+    const out = [];
+    for (const surface of GATEABLE_SURFACES) {
+        if (on.has(surface.id))
+            continue;
+        out.push(...surface.routes);
+    }
+    return out.sort();
+}
+/**
+ * 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 function excludedContentPaths(enabled) {
+    const on = new Set(enabled);
+    const out = [];
+    for (const surface of GATEABLE_SURFACES) {
+        if (on.has(surface.id))
+            continue;
+        out.push(...surface.content);
+    }
+    return out.sort();
+}
+/**
+ * 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 const ROUTE_SINCE = {
+    about: "0.0.0",
+    "blog/[[...slug]]": "0.0.0",
+    careers: "0.0.0",
+    "careers/[slug]": "0.0.0",
+    "case-studies": "0.0.0",
+    "case-studies/[slug]": "0.0.0",
+    clients: "0.0.0",
+    contact: "0.0.0",
+    courses: "0.0.0",
+    "courses/[slug]": "0.0.0",
+    "dev/purchase": "0.0.0",
+    "docs/[[...slug]]": "0.0.0",
+    downloads: "0.0.0",
+    events: "0.0.0",
+    "events/[slug]": "0.0.0",
+    faq: "0.0.0",
+    "flows/[slug]": "0.0.0",
+    "flows/[slug]/results/[payload]": "0.14.0",
+    "flows/[slug]/start": "0.18.0",
+    "how-to": "0.0.0",
+    "how-to/[slug]": "0.0.0",
+    integrations: "0.0.0",
+    "integrations/[slug]": "0.0.0",
+    "launch-service": "0.0.0",
+    partners: "0.0.0",
+    "partners/[slug]": "0.0.0",
+    products: "0.0.0",
+    "products/[slug]": "0.0.0",
+    projects: "0.0.0",
+    "projects/[slug]": "0.0.0",
+    // #5048 — the founder-application reference mount. It carries the client
+    // wrapper only and no `page.tsx`: a route needs a question set, and a
+    // question set is the SITE's content. A scaffolded site adds its own route
+    // beside this file and passes its own config.
+    "projects/apply": "0.18.0",
+    resources: "0.0.0",
+    "resources/[slug]": "0.0.0",
+    schedule: "0.0.0",
+    "schedule/confirmed": "0.0.0",
+    services: "0.0.0",
+    "services/[slug]": "0.0.0",
+    software: "0.0.0",
+    "software/[slug]": "0.0.0",
+    "tech-articles": "0.0.0",
+    "tech-articles/[slug]": "0.0.0",
+    testimonials: "0.0.0",
+    "thanks/[slug]": "0.14.0",
+    "use-cases": "0.0.0",
+    whitepapers: "0.0.0",
+    "whitepapers/[slug]": "0.0.0",
+    // #5014 — the (authed) route GROUP: layout.tsx + sign-in-gate.tsx sit
+    // directly under "(authed)" (a Next.js route group — its parens are not a
+    // URL segment); account/ and waitlist/ are its two syncable sub-trees.
+    // None of these are attributable to a historical release the way the
+    // "0.0.0 = predates the manifest" entries above are, but they are also not
+    // genuinely new at HEAD — this run resolves them to the CURRENT fixed-group
+    // version (0.18.0) per the correction recorded on Epic #5076 (the issue's
+    // own text cites a stale 0.15.0), the same "attach at today's version"
+    // choice #5048's "projects/apply" entry already made for the same reason.
+    "(authed)": "0.18.0",
+    "(authed)/account": "0.18.0",
+    "(authed)/waitlist": "0.18.0",
+    "(authed)/waitlist/[experimentId]": "0.18.0",
+    "(authed)/waitlist/[experimentId]/signups/[leadId]": "0.18.0",
+    "sign-in": "0.18.0",
+};
+/**
+ * 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 function surfaceForRouteDir(routeDir) {
+    const topSegment = routeDir.split("/")[0];
+    if (topSegment === "(authed)")
+        return "authed";
+    const top = `${ROUTE_ROOT}/${topSegment}`;
+    if (CORE_ROUTE_DIRS.includes(top))
+        return "core";
+    return GATEABLE_SURFACES.find((s) => s.routes.includes(top))?.id;
+}
+/**
+ * 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 const ROUTE_DEPENDENCIES = {
+    "sign-in": ["apps/web/lib/auth-env.ts", "apps/web/lib/site-brand.tsx"],
+    "(authed)": ["apps/web/auth.ts", "apps/web/lib/auth-env.ts"],
+    "(authed)/account": [
+        "apps/web/lib/account-config.ts",
+        "apps/web/lib/server-api.ts",
+        `${ROUTE_ROOT}/(authed)/waitlist/components/ForbiddenState.tsx`,
+        `${ROUTE_ROOT}/(authed)/waitlist/format.ts`,
+    ],
+    "(authed)/waitlist": ["apps/web/lib/server-api.ts"],
+};
+/**
+ * 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 const ROUTE_MESSAGE_NAMESPACES = {
+    "sign-in": ["signIn"],
+    "(authed)/account": ["account"],
+    "(authed)/waitlist": ["waitlistDashboard.gate"],
+};
+/** Template-relative path of the generated site-nav registry. */
+export 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 function renderNavConfig(enabled) {
+    const on = new Set(enabled);
+    const linked = GATEABLE_SURFACES.filter((s) => s.navLabelKey !== undefined && on.has(s.id));
+    const entries = [
+        '  { labelKey: "home", path: "/" },',
+        ...linked.map((s) => `  { labelKey: "${s.navLabelKey}", path: "/${s.id}" },`),
+    ];
+    // The emitted file imports the consumer's `NavItem` type from the UI package.
+    // Assembled from fragments so THIS source file never contains the literal
+    // import string: `tools/lint-architecture.ts` matches on source text, so a
+    // literal would read as create-ailk importing @working-theory/ui and fail the
+    // boundary lint. Same technique module-architecture.ts uses for its own
+    // forbidden-pattern data (NO_UPSTREAM_IMPORT_PATTERN).
+    const navItemImport = [
+        "import type { NavItem } ",
+        "from ",
+        '"@working-theory/ui";',
+    ].join("");
+    return `// nav-config.ts — site-nav registry.
+//
+// GENERATED by create-ailk from the declared route surfaces. Every entry here
+// points at a route this site actually carries — the nav is regenerated with
+// the surface set so it can never link a page that was not scaffolded.
+//
+// Adding a link: scaffold the page (the \`scaffold-page\` skill), then add an
+// entry below with a \`labelKey\` that exists in the \`nav\` namespace of
+// \`apps/web/messages/<locale>.json\`. Paths are locale-agnostic — Nav prefixes
+// them with the active locale at render.
+${navItemImport}
+
+export const navItems: NavItem[] = [
+${entries.join("\n")}
+];
+`;
+}

package/dist/sync-routes.d.ts

@@ -0,0 +1,92 @@
+import type { WorkspaceVersionMap } from "./substitute.js";
+export interface SyncRoutesOptions {
+    /**
+     * The already-scaffolded repo (absolute or relative). Must exist, be a
+     * directory, and contain `architecture.yaml` — the same validation as
+     * `syncArchitectureSync`.
+     */
+    targetDir: string;
+    /** The template tree to sync FROM (the package's `templates/` dir). */
+    templatesDir: string;
+    /**
+     * Workspace version map for `copyTemplate`. Route dirs carry no package.json,
+     * so it never applies; passed for fidelity with the scaffold path.
+     */
+    versions: WorkspaceVersionMap;
+    /** Copy the missing routes into the target. Default false = check only. */
+    apply?: boolean;
+}
+/** One route directory the report names. */
+export interface RouteReport {
+    /** ROUTE_ROOT-relative, `/`-separated. */
+    route: string;
+    /** `"core"`, `"authed"` (the `(authed)` route group, #5014), or a gateable surface's id. */
+    surface: string;
+    /** The `ROUTE_SINCE` release line that first carried the route. */
+    since: string;
+    /** `ROUTE_DEPENDENCIES[route]`, when declared — see that export for the contract. */
+    dependencies: readonly string[];
+    /** `ROUTE_MESSAGE_NAMESPACES[route]`, when declared. */
+    messageNamespaces: readonly string[];
+}
+export interface SyncRoutesResult {
+    /** Resolved absolute path to the synced directory. */
+    targetDir: string;
+    /** In-scope template route dirs examined. */
+    checked: number;
+    /** Template route dirs absent from the target, sorted by route. */
+    missing: RouteReport[];
+    /** Route dirs present but with a direct file absent or changed, sorted. */
+    modified: RouteReport[];
+    /** Route dirs copied this run (the missing list when applying, else empty). */
+    applied: string[];
+    /**
+     * `ROUTE_DEPENDENCIES` files, of any route in `missing`, absent from the
+     * target — copied when `apply` is set (never overwriting), else reported
+     * only. Sorted, deduplicated.
+     */
+    missingDependencies: string[];
+    /** Dependency files copied this run. Sorted. */
+    appliedDependencies: string[];
+    /**
+     * `ROUTE_MESSAGE_NAMESPACES` dot-paths, of any route in `missing`, absent
+     * from the target's `messages/en.json`. CHECK-ONLY — never copied (see
+     * `ROUTE_MESSAGE_NAMESPACES`'s own doc for why). Sorted, deduplicated.
+     */
+    missingMessageNamespaces: string[];
+    /** Gateable surface ids the target does not carry, sorted. */
+    skippedSurfaces: string[];
+}
+/**
+ * The template's route directories, ROUTE_ROOT-relative and sorted.
+ *
+ * A route directory is a directory under ROUTE_ROOT (not the root itself)
+ * that directly holds at least one regular file, is not inside a
+ * `NON_ROUTE_DIRS` tree (`__tests__`, `components`), and whose top segment
+ * the registry recognizes (`surfaceForRouteDir`).
+ */
+export declare function listTemplateRouteDirs(templatesDir: string): string[];
+/**
+ * Compare an already-scaffolded repo's route tree with the template's and,
+ * when `apply` is set, copy in the route dirs it is missing.
+ *
+ * Throws Error on a missing target, a non-directory target, a directory with
+ * no `architecture.yaml`, or a template route dir without a `ROUTE_SINCE`
+ * entry; the CLI's top-level catch turns that into a `[create-ailk] <message>`
+ * stderr write + exit 1.
+ */
+export declare function syncRoutes(opts: SyncRoutesOptions): SyncRoutesResult;
+/** Render the report the CLI prints after a run. Ends with a newline. */
+export declare function formatSyncRoutesReport(result: SyncRoutesResult, apply: boolean): string;
+export interface SyncRoutesArgs {
+    /** Positional target directory; undefined = the caller's cwd. */
+    target: string | undefined;
+    apply: boolean;
+    help: boolean;
+}
+export declare const SYNC_ROUTES_HELP = "create-ailk sync-routes \u2014 copy template routes an existing site is missing.\n\nUsage:\n  create-ailk sync-routes [<target-dir>] [--apply]\n\nArguments:\n  <target-dir>             An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n\nOptions:\n  --apply                  Copy the missing route directories into the target.\n                           Without it the command only reports: exit 1 when a\n                           route is missing, 0 when in sync.\n  --help, -h               Print this message.\n\nChecks every core route plus the routes of each surface the site carries; a\nsurface gated off at scaffold time is skipped, not drift. A route the site has\nchanged locally is reported and never overwritten. Nothing is ever deleted.\n";
+/**
+ * Parse the argv AFTER the `sync-routes` word. Strict `node:util` parseArgs,
+ * like `parseCliArgs`; at most one positional.
+ */
+export declare function parseSyncRoutesArgs(argv: string[]): SyncRoutesArgs;