next-modal-router 0.1.0

package/dist/cli.js

@@ -0,0 +1,547 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import path6 from "path";
+import { pathToFileURL } from "url";
+import { createInterface } from "readline/promises";
+import { stdin, stdout } from "process";
+
+// src/config/types.ts
+var OVERLAY_TYPES = ["modal", "drawer", "sheet", "panel", "custom"];
+
+// src/routing/segments.ts
+var UNSAFE = /(?:^|\/)\.\.?($|\/)|[\\\0]/;
+function normalizeRoute(route) {
+  if (!route.startsWith("/")) throw new Error(`Route "${route}" must begin with "/".`);
+  if (UNSAFE.test(route)) throw new Error(`Route "${route}" contains an unsafe filesystem segment.`);
+  const normalized = `/${route.split("/").filter(Boolean).join("/")}`;
+  return normalized === "/" ? normalized : normalized.replace(/\/$/, "");
+}
+function parseSegment(raw) {
+  if (/^\[\[\.\.\.[^\]/]+\]\]$/.test(raw)) return { raw, kind: "optional-catch-all", name: raw.slice(5, -2), contributesToUrl: true };
+  if (/^\[\.\.\.[^\]/]+\]$/.test(raw)) return { raw, kind: "catch-all", name: raw.slice(4, -1), contributesToUrl: true };
+  if (/^\[[^\]/]+\]$/.test(raw)) return { raw, kind: "dynamic", name: raw.slice(1, -1), contributesToUrl: true };
+  if (/^\([^/]+\)$/.test(raw)) return { raw, kind: "group", name: raw.slice(1, -1), contributesToUrl: false };
+  if (/^@[A-Za-z][\w-]*$/.test(raw)) return { raw, kind: "slot", name: raw.slice(1), contributesToUrl: false };
+  if (!raw || raw.includes("[") || raw.includes("]")) throw new Error(`Invalid route segment "${raw}".`);
+  return { raw, kind: "static", name: raw, contributesToUrl: true };
+}
+function routeSegments(route) {
+  return normalizeRoute(route).split("/").filter(Boolean).map(parseSegment);
+}
+function urlSegments(route) {
+  return routeSegments(route).filter((segment) => segment.contributesToUrl).map((segment) => segment.raw);
+}
+function routeToFileSegments(route) {
+  return routeSegments(route).map((segment) => segment.raw);
+}
+
+// src/config/validate.ts
+function validateConfig(value) {
+  const problems = [];
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return [{ path: "config", message: "Configuration must be an object." }];
+  }
+  const config = value;
+  if (!config.overlays || typeof config.overlays !== "object" || Array.isArray(config.overlays)) {
+    return [{ path: "overlays", message: "An overlays object is required." }];
+  }
+  const targets = /* @__PURE__ */ new Map();
+  for (const [name, raw] of Object.entries(config.overlays)) {
+    const path7 = `overlays.${name}`;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      problems.push({ path: path7, message: "Overlay must be an object." });
+      continue;
+    }
+    const overlay = raw;
+    for (const key of ["route", "source", "closeFallback"]) {
+      if (typeof overlay[key] !== "string" || overlay[key].length === 0) {
+        problems.push({ path: `${path7}.${key}`, message: `${key} is required.` });
+      } else {
+        try {
+          normalizeRoute(overlay[key]);
+        } catch (error) {
+          problems.push({ path: `${path7}.${key}`, message: error.message });
+        }
+      }
+    }
+    if (!overlay.type || !OVERLAY_TYPES.includes(overlay.type)) {
+      problems.push({ path: `${path7}.type`, message: `Expected one of: ${OVERLAY_TYPES.join(", ")}.` });
+    }
+    if (overlay.slot !== void 0 && !/^[A-Za-z][\w-]*$/.test(overlay.slot)) {
+      problems.push({ path: `${path7}.slot`, message: "Slot must start with a letter and contain only letters, numbers, _ or -." });
+    }
+    if (typeof overlay.route === "string" && typeof overlay.slot !== "object") {
+      const key = `${overlay.slot ?? config.defaultSlot ?? "modal"}:${overlay.route}`;
+      const existing = targets.get(key);
+      if (existing) problems.push({ path: path7, message: `Duplicates intercepted target used by ${existing}.` });
+      else targets.set(key, name);
+    }
+  }
+  return problems;
+}
+
+// src/routing/interception.ts
+function calculateInterception(slotOwnerRoute, targetRoute) {
+  const owner = urlSegments(slotOwnerRoute);
+  const target = urlSegments(targetRoute);
+  let common = 0;
+  while (common < owner.length && common < target.length && owner[common] === target[common]) common += 1;
+  const levelsUp = owner.length - common;
+  const relativeTarget = target.slice(common).join("/");
+  if (!relativeTarget) throw new Error(`Target ${normalizeRoute(targetRoute)} cannot equal the slot owner route.`);
+  const marker = levelsUp === 0 ? "(.)" : common === 0 ? "(...)" : "(..)".repeat(levelsUp);
+  return { marker, target: `/${target.join("/")}`, filesystemPath: `${marker}${relativeTarget}`, levelsUp };
+}
+function parseInterceptor(value) {
+  const match = /^(\(\.\)|(?:\(\.\.\))+|\(\.\.\.\))(.+)$/.exec(value.replaceAll("\\", "/"));
+  return match?.[1] && match[2] ? { marker: match[1], target: match[2].replace(/^\//, "") } : null;
+}
+
+// src/cli/analyze.ts
+import path3 from "path";
+
+// src/routing/tree.ts
+import { readdir } from "fs/promises";
+import path from "path";
+var IGNORED = /* @__PURE__ */ new Set(["node_modules", ".next", ".git", "dist", "coverage"]);
+var ROUTE_FILES = /^(?:page|default|layout)\.(?:js|jsx|ts|tsx)$/;
+async function buildRouteTree(root) {
+  const entries = await readdir(root, { withFileTypes: true });
+  const files = entries.filter((entry) => entry.isFile() && ROUTE_FILES.test(entry.name)).map((entry) => entry.name).sort();
+  const directories = entries.filter((entry) => entry.isDirectory() && !IGNORED.has(entry.name));
+  const children = await Promise.all(directories.map((entry) => buildRouteTree(path.join(root, entry.name))));
+  return { name: path.basename(root), absolutePath: root, children: children.sort((a, b) => a.name.localeCompare(b.name)), files };
+}
+function discoverInterceptors(tree) {
+  const results = [];
+  const visit = (node, slot, relative2) => {
+    const activeSlot = node.name.startsWith("@") ? node.name.slice(1) : slot;
+    const next = node === tree ? [] : [...relative2, node.name];
+    const withinSlot = activeSlot ? next.slice(next.findIndex((part) => part === `@${activeSlot}`) + 1) : [];
+    const interceptorIndex = withinSlot.findIndex((part) => parseInterceptor(part));
+    if (activeSlot && interceptorIndex >= 0 && node.files.some((file) => file.startsWith("page."))) {
+      const routeParts = withinSlot.slice(interceptorIndex);
+      const first = parseInterceptor(routeParts[0] ?? "");
+      if (first) results.push({ slot: activeSlot, filesystemPath: routeParts.join("/"), pagePath: node.absolutePath, marker: first.marker, target: [first.target, ...routeParts.slice(1)].join("/") });
+    }
+    for (const child of node.children) visit(child, activeSlot, next);
+  };
+  visit(tree, void 0, []);
+  return results;
+}
+
+// src/cli/project.ts
+import { access, readFile } from "fs/promises";
+import path2 from "path";
+async function exists(file) {
+  try {
+    await access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function findProject(inputCwd) {
+  let cwd = path2.resolve(inputCwd);
+  while (true) {
+    const packageFile = path2.join(cwd, "package.json");
+    if (await exists(packageFile)) {
+      const packageJson = JSON.parse(await readFile(packageFile, "utf8"));
+      const candidates = ["src/app", "app"];
+      for (const candidate of candidates) {
+        const appDir = path2.join(cwd, candidate);
+        if (await exists(appDir)) return { cwd, appDir, appRelative: candidate, packageJson, typescript: await exists(path2.join(cwd, "tsconfig.json")) };
+      }
+      throw new Error(`Found package.json in ${cwd}, but no app/ or src/app/ directory. next-modal-router requires the App Router.`);
+    }
+    const parent = path2.dirname(cwd);
+    if (parent === cwd) break;
+    cwd = parent;
+  }
+  throw new Error(`No Next.js project found from ${path2.resolve(inputCwd)}. Run the command inside an application or pass --cwd.`);
+}
+async function fileExists(file) {
+  return exists(file);
+}
+function dependencyVersion(project, name) {
+  for (const key of ["dependencies", "devDependencies", "peerDependencies"]) {
+    const record = project.packageJson[key];
+    if (record && typeof record === "object" && !Array.isArray(record)) {
+      const value = record[name];
+      if (typeof value === "string") return value;
+    }
+  }
+  return void 0;
+}
+
+// src/cli/analyze.ts
+var PAGE_EXTENSIONS = ["tsx", "ts", "jsx", "js"];
+async function hasRouteFile(directory, base) {
+  return (await Promise.all(PAGE_EXTENSIONS.map((extension) => fileExists(path3.join(directory, `${base}.${extension}`))))).some(Boolean);
+}
+async function analyze(project, config) {
+  const tree = await buildRouteTree(project.appDir);
+  const discovered = discoverInterceptors(tree);
+  const issues = [];
+  const definitions = Object.entries(config?.overlays ?? {});
+  for (const [name, overlay] of definitions) {
+    const slot = overlay.slot ?? config?.defaultSlot ?? "modal";
+    const expected = calculateInterception("/", overlay.route).filesystemPath;
+    const slotDir = path3.join(project.appDir, `@${slot}`);
+    if (!await hasRouteFile(slotDir, "default")) issues.push({ code: "NMR001", severity: "error", overlay: name, path: slotDir, message: `Missing @${slot}/default.tsx.`, suggestion: "Run next-modal-router init or create a default component that returns null." });
+    const found = discovered.find((item) => item.slot === slot && item.target === overlay.route.replace(/^\//, ""));
+    if (!found) issues.push({ code: "NMR002", severity: "error", overlay: name, message: `Missing interceptor @${slot}/${expected}.`, suggestion: `Run next-modal-router add ${name} with the configured route.` });
+    else if (found.filesystemPath !== expected) issues.push({ code: "NMR003", severity: "error", overlay: name, path: found.pagePath, message: `Invalid interception path. Expected ${expected}; found ${found.filesystemPath}.`, suggestion: "Move the interceptor to the expected route-segment depth." });
+    const fullPage = path3.join(project.appDir, ...routeToFileSegments(overlay.route));
+    if (!await hasRouteFile(fullPage, "page")) issues.push({ code: "NMR004", severity: "error", overlay: name, path: fullPage, message: `Missing full-page counterpart for ${overlay.route}.`, suggestion: "Create page.tsx so hard navigation and refresh render a normal page." });
+    const fallback = path3.join(project.appDir, ...routeToFileSegments(overlay.closeFallback));
+    if (!await hasRouteFile(fallback, "page")) issues.push({ code: "NMR005", severity: "warning", overlay: name, path: fallback, message: `Close fallback ${overlay.closeFallback} has no page.`, suggestion: "Create the fallback page or correct closeFallback." });
+  }
+  if (!config) for (const item of discovered) issues.push({ code: "NMR006", severity: "info", path: item.pagePath, message: `Discovered unconfigured overlay @${item.slot}/${item.filesystemPath}.`, suggestion: "Add it to next-modal-router.config.ts for richer validation." });
+  return { valid: !issues.some((issue) => issue.severity === "error"), issues, discovered, checked: definitions.length || discovered.length };
+}
+
+// src/cli/config-loader.ts
+import { access as access2 } from "fs/promises";
+import path4 from "path";
+import { fileURLToPath } from "url";
+import { createJiti } from "jiti";
+var NAMES = ["next-modal-router.config.ts", "next-modal-router.config.mts", "next-modal-router.config.js", "next-modal-router.config.mjs"];
+async function findConfig(cwd) {
+  for (const name of NAMES) {
+    const file = path4.join(cwd, name);
+    try {
+      await access2(file);
+      return file;
+    } catch {
+    }
+  }
+  return void 0;
+}
+async function loadConfig(cwd) {
+  const configPath = await findConfig(cwd);
+  if (!configPath) return {};
+  const builtConfig = fileURLToPath(new URL("./config.js", import.meta.url));
+  const sourceConfig = fileURLToPath(new URL("../config/index.ts", import.meta.url));
+  let configEntry = builtConfig;
+  try {
+    await access2(builtConfig);
+  } catch {
+    configEntry = sourceConfig;
+  }
+  const jiti = createJiti(import.meta.url, { interopDefault: true, alias: { "next-modal-router/config": configEntry } });
+  const loaded = await jiti.import(configPath, { default: true });
+  const problems = validateConfig(loaded);
+  if (problems.length) throw new Error(`Invalid ${path4.basename(configPath)}:
+${problems.map((problem) => `  ${problem.path}: ${problem.message}`).join("\n")}`);
+  return { path: configPath, config: loaded };
+}
+
+// src/cli/files.ts
+import { mkdir, open, rename, rm, writeFile } from "fs/promises";
+import path5 from "path";
+async function applyWrites(writes, options) {
+  const changed = [];
+  for (const write of writes) {
+    await mkdir(path5.dirname(write.path), { recursive: true });
+    let existing = false;
+    try {
+      const handle = await open(write.path, "r");
+      await handle.close();
+      existing = true;
+    } catch {
+    }
+    if (existing && write.skipIfExists && !options.force) continue;
+    if (existing && !options.force && !write.overwrite) throw new Error(`Refusing to overwrite ${write.path}. Re-run with --force only if replacing this file is intentional.`);
+    changed.push(write.path);
+    if (options.dryRun) continue;
+    const temporary = `${write.path}.nmr-${process.pid}.tmp`;
+    await writeFile(temporary, write.content, "utf8");
+    try {
+      await rename(temporary, write.path);
+    } catch (error) {
+      await rm(temporary, { force: true });
+      throw error;
+    }
+  }
+  return changed;
+}
+
+// src/cli/templates.ts
+var DEFAULT_TEMPLATE = `export default function Default() {
+  return null;
+}
+`;
+function pageTemplate(name, type, intercepted) {
+  const title = name.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[-_]/g, " ");
+  if (!intercepted) return `export default function Page() {
+  return (
+    <main>
+      <h1>${title}</h1>
+      <p>This is the full-page route for ${name}.</p>
+    </main>
+  );
+}
+`;
+  return `"use client";
+
+import { Suspense } from "react";
+import { useOverlayRouter } from "next-modal-router";
+
+function ${name.replace(/[^A-Za-z0-9]/g, "")}Overlay() {
+  const overlay = useOverlayRouter();
+
+  return (
+    <section role="dialog" aria-modal="true" aria-labelledby="${name}-title">
+      <h2 id="${name}-title">${title}</h2>
+      <p>Replace this headless ${type} route with your application content.</p>
+      <button type="button" onClick={() => overlay.close()}>Close</button>
+    </section>
+  );
+}
+
+export default function Page() {
+  return <Suspense fallback={null}><${name.replace(/[^A-Za-z0-9]/g, "")}Overlay /></Suspense>;
+}
+`;
+}
+function configTemplate(config) {
+  const entries = Object.entries(config.overlays).map(([name, item]) => `    ${JSON.stringify(name)}: ${formatObject(item, 4)},`).join("\n\n");
+  return `import { defineConfig } from "next-modal-router/config";
+
+export default defineConfig({
+  defaultSlot: ${JSON.stringify(config.defaultSlot ?? "modal")},
+  overlays: {${entries ? `
+${entries}
+  ` : ""}},
+});
+`;
+}
+function formatObject(value, spaces) {
+  const indent = " ".repeat(spaces);
+  return `{
+${Object.entries(value).map(([key, item]) => `${indent}  ${key}: ${JSON.stringify(item)},`).join("\n")}
+${indent}}`;
+}
+
+// src/cli/index.ts
+function parseArguments(argv) {
+  const result = { positionals: [], flags: {} };
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (!result.command && !item.startsWith("-")) {
+      result.command = item;
+      continue;
+    }
+    if (item.startsWith("--")) {
+      const [rawKey, inline] = item.slice(2).split("=", 2);
+      const key = rawKey;
+      const next = argv[index + 1];
+      if (inline !== void 0) result.flags[key] = inline;
+      else if (next && !next.startsWith("-")) {
+        result.flags[key] = next;
+        index += 1;
+      } else result.flags[key] = true;
+    } else result.positionals.push(item);
+  }
+  return result;
+}
+function flag(args, key) {
+  const value = args.flags[key];
+  return typeof value === "string" ? value : void 0;
+}
+function enabled(args, key) {
+  return args.flags[key] === true || args.flags[key] === "true";
+}
+function relative(cwd, file) {
+  return path6.relative(cwd, file) || ".";
+}
+function outputJson(value) {
+  stdout.write(`${JSON.stringify(value, null, 2)}
+`);
+}
+async function commandInit(args) {
+  const project = await findProject(flag(args, "cwd") ?? process.cwd());
+  if (!dependencyVersion(project, "next")) throw new Error("This package does not declare Next.js. Install next before initializing next-modal-router.");
+  const configPath = path6.join(project.cwd, "next-modal-router.config.ts");
+  const defaultSlot = flag(args, "slot") ?? "modal";
+  const writes = [];
+  if (!await fileExists(configPath)) writes.push({ path: configPath, content: configTemplate({ defaultSlot, overlays: {} }) });
+  else if (!enabled(args, "force")) throw new Error(`${relative(project.cwd, configPath)} already exists. Nothing was overwritten.`);
+  else writes.push({ path: configPath, content: configTemplate({ defaultSlot, overlays: {} }) });
+  writes.push({ path: path6.join(project.appDir, `@${defaultSlot}`, "default.tsx"), content: DEFAULT_TEMPLATE, skipIfExists: true });
+  const changed = await applyWrites(writes, { dryRun: enabled(args, "dry-run"), force: enabled(args, "force") });
+  for (const file of changed) stdout.write(`${enabled(args, "dry-run") ? "WOULD CREATE" : "CREATE"} ${relative(project.cwd, file)}
+`);
+  stdout.write(`
+Initialized next-modal-router in ${project.cwd}. Add the @${defaultSlot} slot prop to the layout that owns it.
+`);
+  return 0;
+}
+async function askMissing(args) {
+  const values = {};
+  if (enabled(args, "yes") || enabled(args, "ci") || !stdin.isTTY) return values;
+  const prompt = createInterface({ input: stdin, output: stdout });
+  try {
+    if (!args.positionals[0]) values.name = await prompt.question("Overlay name: ");
+    if (!flag(args, "route")) values.route = await prompt.question("Route: ");
+    if (!flag(args, "source")) values.source = await prompt.question("Source route: ");
+    if (!flag(args, "type")) values.type = await prompt.question("Type (modal/drawer/sheet/panel/custom) [modal]: ") || "modal";
+    if (!flag(args, "slot")) values.slot = await prompt.question("Slot [modal]: ") || "modal";
+    if (!flag(args, "fallback")) values.fallback = await prompt.question("Close fallback: ");
+  } finally {
+    prompt.close();
+  }
+  return values;
+}
+async function commandAdd(args) {
+  const prompted = await askMissing(args);
+  const project = await findProject(flag(args, "cwd") ?? process.cwd());
+  const loaded = await loadConfig(project.cwd);
+  const name = args.positionals[0] ?? prompted.name;
+  const route = flag(args, "route") ?? prompted.route;
+  const source = flag(args, "source") ?? prompted.source;
+  const type = flag(args, "type") ?? prompted.type ?? "modal";
+  const slot = flag(args, "slot") ?? prompted.slot ?? loaded.config?.defaultSlot ?? "modal";
+  const closeFallback = flag(args, "fallback") ?? prompted.fallback ?? source;
+  if (!name || !route || !source || !closeFallback) throw new Error("add requires a name, --route, --source, and --fallback (or an interactive terminal).");
+  if (!/^[A-Za-z][\w-]*$/.test(name)) throw new Error(`Invalid overlay name "${name}". Use letters, numbers, _ or -, beginning with a letter.`);
+  if (!OVERLAY_TYPES.includes(type)) throw new Error(`Unknown overlay type "${type}". Expected: ${OVERLAY_TYPES.join(", ")}.`);
+  const overlay = { route, source, type, slot, closeFallback };
+  const config = loaded.config ?? { defaultSlot: slot, overlays: {} };
+  if (config.overlays[name] && !enabled(args, "force")) throw new Error(`Overlay "${name}" already exists. Use --force to replace its generated files and definition.`);
+  const nextConfig = { ...config, overlays: { ...config.overlays, [name]: overlay } };
+  const problems = validateConfig(nextConfig);
+  if (problems.length) throw new Error(problems.map((problem) => `${problem.path}: ${problem.message}`).join("\n"));
+  const interception = calculateInterception("/", route);
+  const configPath = loaded.path ?? path6.join(project.cwd, "next-modal-router.config.ts");
+  const writes = [
+    { path: path6.join(project.appDir, `@${slot}`, "default.tsx"), content: DEFAULT_TEMPLATE, skipIfExists: true },
+    { path: path6.join(project.appDir, `@${slot}`, ...interception.filesystemPath.split("/"), "page.tsx"), content: pageTemplate(name, type, true) },
+    { path: path6.join(project.appDir, ...routeToFileSegments(route), "page.tsx"), content: pageTemplate(name, type, false), skipIfExists: true },
+    { path: configPath, content: configTemplate(nextConfig), overwrite: Boolean(loaded.path) }
+  ];
+  const changed = await applyWrites(writes, { dryRun: enabled(args, "dry-run"), force: enabled(args, "force") });
+  for (const file of changed) stdout.write(`${enabled(args, "dry-run") ? "WOULD WRITE" : "WRITE"} ${relative(project.cwd, file)}
+`);
+  stdout.write(`
+${name}: ${source} \u2192 ${route} via @${slot}/${interception.filesystemPath}
+`);
+  return 0;
+}
+async function commandCheck(args) {
+  const project = await findProject(flag(args, "cwd") ?? process.cwd());
+  const loaded = await loadConfig(project.cwd);
+  const result = await analyze(project, loaded.config);
+  if (flag(args, "format") === "json") outputJson(result);
+  else {
+    stdout.write(`next-modal-router
+
+Checking ${result.checked} overlay${result.checked === 1 ? "" : "s"}...
+`);
+    if (!result.issues.length) stdout.write("\n\u2713 Everything looks good.\n");
+    for (const issue of result.issues) {
+      const icon = issue.severity === "error" ? "\u2715" : issue.severity === "warning" ? "\u26A0" : "\u2139";
+      stdout.write(`
+${icon} ${issue.code}${issue.overlay ? ` ${issue.overlay}` : ""}
+  ${issue.message}
+`);
+      if (issue.suggestion) stdout.write(`  ${issue.suggestion}
+`);
+      if (enabled(args, "verbose") && issue.path) stdout.write(`  path: ${issue.path}
+`);
+    }
+  }
+  return result.valid ? 0 : 1;
+}
+async function commandDoctor(args) {
+  const project = await findProject(flag(args, "cwd") ?? process.cwd());
+  const loaded = await loadConfig(project.cwd);
+  const result = await analyze(project, loaded.config);
+  const report = { environment: { node: process.version, next: dependencyVersion(project, "next") ?? null, react: dependencyVersion(project, "react") ?? null, appRouter: true, typescript: project.typescript, appDirectory: project.appRelative }, configuration: { path: loaded.path ? relative(project.cwd, loaded.path) : null, overlays: result.checked, valid: result.valid, warnings: result.issues.filter((issue) => issue.severity === "warning").length, errors: result.issues.filter((issue) => issue.severity === "error").length } };
+  if (flag(args, "format") === "json") outputJson(report);
+  else stdout.write(`Environment
+\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+Node             ${report.environment.node}
+Next.js          ${report.environment.next ?? "not declared"}
+React            ${report.environment.react ?? "not declared"}
+App Router       \u2713 (${project.appRelative})
+TypeScript       ${project.typescript ? "\u2713" : "\u2013"}
+
+Configuration
+\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+Config           ${report.configuration.path ?? "not found (discovery mode)"}
+Overlays         ${report.configuration.overlays}
+Warnings         ${report.configuration.warnings}
+Errors           ${report.configuration.errors}
+
+${result.valid ? "Everything looks good." : "Run `next-modal-router check --verbose` for actionable diagnostics."}
+`);
+  return result.valid ? 0 : 1;
+}
+async function commandList(args) {
+  const project = await findProject(flag(args, "cwd") ?? process.cwd());
+  const loaded = await loadConfig(project.cwd);
+  const analysis = await analyze(project, loaded.config);
+  const configured = Object.entries(loaded.config?.overlays ?? {}).map(([name, overlay]) => ({ name, route: overlay.route, source: overlay.source, type: overlay.type, slot: overlay.slot ?? loaded.config?.defaultSlot ?? "modal", origin: "config" }));
+  const known = new Set(configured.map((item) => `${item.slot}:${item.route.replace(/^\//, "")}`));
+  const discovered = analysis.discovered.filter((item) => !known.has(`${item.slot}:${item.target}`)).map((item) => ({ name: item.target, route: `/${item.target}`, source: "unknown", type: "custom", slot: item.slot, origin: "discovered" }));
+  const items = [...configured, ...discovered];
+  if (flag(args, "format") === "json") outputJson(items);
+  else {
+    stdout.write("NAME                 ROUTE                              TYPE      SLOT       ORIGIN\n");
+    for (const item of items) stdout.write(`${item.name.padEnd(21)}${item.route.padEnd(35)}${item.type.padEnd(10)}${item.slot.padEnd(11)}${item.origin}
+`);
+    if (!items.length) stdout.write("No overlays found.\n");
+  }
+  return 0;
+}
+function printHelp() {
+  stdout.write(`next-modal-router
+URL-native overlays for Next.js App Router
+
+Usage:
+  next-modal-router <command> [options]
+
+Commands:
+  init       Create a typed config and default parallel slot
+  add        Generate an overlay interceptor and full-page route
+  check      Validate configured or discovered overlay routes
+  doctor     Inspect project compatibility and configuration
+  list       List configured and discovered overlays
+
+Global options:
+  --cwd <path>       Next.js application directory
+  --format json      Machine-readable output (check, doctor, list)
+  --dry-run          Report writes without changing files (init, add)
+  --force            Replace files owned by the requested operation
+  --ci                Disable prompts and ANSI output
+  --verbose           Include filesystem paths in diagnostics
+`);
+}
+async function run(argv = process.argv.slice(2)) {
+  const args = parseArguments(argv);
+  if (!args.command || args.command === "help" || enabled(args, "help")) {
+    printHelp();
+    return 0;
+  }
+  if (args.command === "init") return commandInit(args);
+  if (args.command === "add") return commandAdd(args);
+  if (args.command === "check") return commandCheck(args);
+  if (args.command === "doctor") return commandDoctor(args);
+  if (args.command === "list") return commandList(args);
+  throw new Error(`Unknown command "${args.command}". Run next-modal-router help.`);
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  run().then((code) => {
+    process.exitCode = code;
+  }).catch((error) => {
+    process.stderr.write(`next-modal-router: ${error instanceof Error ? error.message : String(error)}
+`);
+    process.exitCode = 2;
+  });
+}
+export {
+  run
+};

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+declare const OVERLAY_TYPES: readonly ["modal", "drawer", "sheet", "panel", "custom"];
+type OverlayType = (typeof OVERLAY_TYPES)[number];
+interface OverlayDefinition {
+    route: string;
+    source: string;
+    type: OverlayType;
+    slot?: string;
+    closeFallback: string;
+}
+interface OverlayConfig<T extends Record<string, OverlayDefinition> = Record<string, OverlayDefinition>> {
+    defaultSlot?: string;
+    overlays: T;
+}
+declare function defineConfig<const T extends Record<string, OverlayDefinition>>(config: OverlayConfig<T>): OverlayConfig<T>;
+
+interface ConfigProblem {
+    path: string;
+    message: string;
+}
+declare function validateConfig(value: unknown): ConfigProblem[];
+
+export { type ConfigProblem, OVERLAY_TYPES, type OverlayConfig, type OverlayDefinition, type OverlayType, defineConfig, validateConfig };

package/dist/config.js

@@ -0,0 +1,64 @@
+// src/config/types.ts
+var OVERLAY_TYPES = ["modal", "drawer", "sheet", "panel", "custom"];
+function defineConfig(config) {
+  return config;
+}
+
+// src/routing/segments.ts
+var UNSAFE = /(?:^|\/)\.\.?($|\/)|[\\\0]/;
+function normalizeRoute(route) {
+  if (!route.startsWith("/")) throw new Error(`Route "${route}" must begin with "/".`);
+  if (UNSAFE.test(route)) throw new Error(`Route "${route}" contains an unsafe filesystem segment.`);
+  const normalized = `/${route.split("/").filter(Boolean).join("/")}`;
+  return normalized === "/" ? normalized : normalized.replace(/\/$/, "");
+}
+
+// src/config/validate.ts
+function validateConfig(value) {
+  const problems = [];
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return [{ path: "config", message: "Configuration must be an object." }];
+  }
+  const config = value;
+  if (!config.overlays || typeof config.overlays !== "object" || Array.isArray(config.overlays)) {
+    return [{ path: "overlays", message: "An overlays object is required." }];
+  }
+  const targets = /* @__PURE__ */ new Map();
+  for (const [name, raw] of Object.entries(config.overlays)) {
+    const path = `overlays.${name}`;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      problems.push({ path, message: "Overlay must be an object." });
+      continue;
+    }
+    const overlay = raw;
+    for (const key of ["route", "source", "closeFallback"]) {
+      if (typeof overlay[key] !== "string" || overlay[key].length === 0) {
+        problems.push({ path: `${path}.${key}`, message: `${key} is required.` });
+      } else {
+        try {
+          normalizeRoute(overlay[key]);
+        } catch (error) {
+          problems.push({ path: `${path}.${key}`, message: error.message });
+        }
+      }
+    }
+    if (!overlay.type || !OVERLAY_TYPES.includes(overlay.type)) {
+      problems.push({ path: `${path}.type`, message: `Expected one of: ${OVERLAY_TYPES.join(", ")}.` });
+    }
+    if (overlay.slot !== void 0 && !/^[A-Za-z][\w-]*$/.test(overlay.slot)) {
+      problems.push({ path: `${path}.slot`, message: "Slot must start with a letter and contain only letters, numbers, _ or -." });
+    }
+    if (typeof overlay.route === "string" && typeof overlay.slot !== "object") {
+      const key = `${overlay.slot ?? config.defaultSlot ?? "modal"}:${overlay.route}`;
+      const existing = targets.get(key);
+      if (existing) problems.push({ path, message: `Duplicates intercepted target used by ${existing}.` });
+      else targets.set(key, name);
+    }
+  }
+  return problems;
+}
+export {
+  OVERLAY_TYPES,
+  defineConfig,
+  validateConfig
+};