@thelol3882/sapar 0.0.0-stage → 0.3.0

package/dist/cli/index.js

@@ -0,0 +1,1335 @@
+#!/usr/bin/env node
+
+// src/cli/prompt.ts
+import { createInterface } from "readline/promises";
+function createPrompter() {
+  let readline;
+  return {
+    async ask(question, defaultAnswer) {
+      readline ??= createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await readline.question(`${question} [${defaultAnswer}] `);
+      return answer.trim() || defaultAnswer;
+    },
+    close: () => readline?.close()
+  };
+}
+
+// src/cli/help.ts
+var GENERAL_HELP = `Usage: sapar <command> [options]
+
+Commands:
+  init     Create sapar.json, a sample definitions file, and a provider
+  add      Copy UI components into your project
+  check    Verify that every tour anchor exists in your source
+
+Run \`sapar <command> --help\` for details.
+
+Options:
+  -h, --help     Show help
+  -v, --version  Show the version`;
+var INIT_HELP = `Usage: sapar init [options]
+
+Detects your setup, writes sapar.json, <toursDir>/definitions.ts, anchors.ts and
+SaparProvider.tsx, then copies the TourCard component. Existing files are kept.
+Written files are formatted with your project's Prettier when it has a config.
+
+Options:
+  --cwd <dir>               Project root (default: current directory)
+  --yes                     Accept detected values without asking
+  --framework <name>        next | expo | react
+  --style <name>            tailwind | mantine | native
+  --source <name>           memory | http | rtk
+  --import-base <specifier> Package name or alias of a copied src folder
+  --components-dir <dir>    Where components are copied
+  --tours-dir <dir>         Where definitions, anchors and the provider go
+  --no-format               Do not format the written files with Prettier
+  --force                   Overwrite existing files`;
+var ADD_HELP = `Usage: sapar add [names...] [options]
+
+Copies components from the template set of your style into componentsDir.
+Names are case-insensitive; kebab-case works (whats-new-panel).
+Copied files are formatted with your project's Prettier when it has a config.
+
+Options:
+  --cwd <dir>      Project root (default: current directory)
+  --all            Copy every component
+  --list           List the available components
+  --style <name>   Use another template set than sapar.json
+  --no-format      Do not format the copied files with Prettier
+  --force          Overwrite existing files`;
+var CHECK_HELP = `Usage: sapar check [options]
+
+Reads tour definitions and anchor declarations from your source and fails when
+a step points at an anchor that does not exist on a platform the tour targets.
+Needs the \`typescript\` package.
+
+Options:
+  --cwd <dir>        Project root (default: current directory)
+  --format <format>  text | json (default: text)
+  --strict           Treat warnings as errors
+  --verbose          Also list declared anchors that no tour uses`;
+
+// src/cli/commands/add.ts
+import { join as join5 } from "path";
+
+// src/cli/args.ts
+import { resolve } from "path";
+import { parseArgs } from "util";
+
+// src/cli/errors.ts
+var CliError = class extends Error {
+};
+
+// src/cli/args.ts
+function parseCommandArgs(args, options) {
+  try {
+    return parseArgs({ args: [...args], options, allowPositionals: true });
+  } catch (error) {
+    throw new CliError(error instanceof Error ? error.message : String(error));
+  }
+}
+function resolveCwd(context, cwdFlag) {
+  return cwdFlag === void 0 ? context.cwd : resolve(context.cwd, cwdFlag);
+}
+
+// src/cli/config.ts
+import { join } from "path";
+
+// src/cli/fs.ts
+import { mkdir, readFile, stat, writeFile } from "fs/promises";
+import { dirname } from "path";
+
+// src/cli/paths.ts
+import * as nodePath from "path";
+function toForwardSlashes(path, { sep } = nodePath) {
+  return path.split(sep).join("/");
+}
+function displayPath(from, to, pathModule = nodePath) {
+  return toForwardSlashes(pathModule.relative(from, to), pathModule);
+}
+function displayJoin(segments, pathModule = nodePath) {
+  return toForwardSlashes(pathModule.join(...segments), pathModule);
+}
+
+// src/cli/fs.ts
+function isNotFound(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+async function statOrUndefined(path) {
+  try {
+    return await stat(path);
+  } catch (error) {
+    if (isNotFound(error)) return void 0;
+    throw error;
+  }
+}
+async function pathExists(path) {
+  return await statOrUndefined(path) !== void 0;
+}
+async function isDirectory(path) {
+  return (await statOrUndefined(path))?.isDirectory() ?? false;
+}
+async function writeFileSafely(path, content, force) {
+  const existed = await pathExists(path);
+  if (existed && !force) return { path, outcome: "skipped" };
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, content);
+  return { path, outcome: existed ? "overwritten" : "created" };
+}
+async function readJsonObject(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (isNotFound(error)) return void 0;
+    throw error;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new CliError(`${toForwardSlashes(path)} is not valid JSON.`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new CliError(`${toForwardSlashes(path)} must contain a JSON object.`);
+  }
+  return Object.fromEntries(Object.entries(parsed));
+}
+
+// src/cli/config.ts
+var FRAMEWORKS = ["next", "expo", "react"];
+var STYLES = ["tailwind", "mantine", "native"];
+var SOURCES = ["memory", "http", "rtk"];
+var PLATFORMS = ["web", "native"];
+var CONFIG_FILE = "sapar.json";
+var platformOf = (framework) => framework === "expo" ? "native" : "web";
+var isPlatform = (value) => PLATFORMS.includes(value);
+function parseChoice(label, value, choices) {
+  const match = choices.find((choice) => choice === value);
+  if (match === void 0) throw new CliError(`Invalid ${label}: expected one of ${choices.join(", ")}, got "${value}".`);
+  return match;
+}
+function readChoice(raw, field, choices) {
+  return parseChoice(`"${field}" in ${CONFIG_FILE}`, String(raw[field]), choices);
+}
+function readString(raw, field) {
+  const value = raw[field];
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new CliError(`"${field}" in ${CONFIG_FILE} must be a non-empty string.`);
+  }
+  return value;
+}
+function readRoots(platforms, platform) {
+  const roots = platforms[platform] ?? [];
+  if (!Array.isArray(roots) || roots.some((root) => typeof root !== "string")) {
+    throw new CliError(`"platforms.${platform}" in ${CONFIG_FILE} must be an array of directories.`);
+  }
+  return roots.map(String);
+}
+function readPlatforms(raw) {
+  const { platforms } = raw;
+  if (typeof platforms !== "object" || platforms === null || Array.isArray(platforms)) {
+    throw new CliError(`"platforms" in ${CONFIG_FILE} must be an object such as { "web": ["src"], "native": [] }.`);
+  }
+  const roots = Object.fromEntries(Object.entries(platforms));
+  return { web: readRoots(roots, "web"), native: readRoots(roots, "native") };
+}
+function assertStyleMatchesFramework(framework, style) {
+  if (framework === "expo" !== (style === "native")) {
+    throw new CliError('The "native" style goes with the "expo" framework, and only with it.');
+  }
+}
+function validateConfig(raw) {
+  const framework = readChoice(raw, "framework", FRAMEWORKS);
+  const style = readChoice(raw, "style", STYLES);
+  assertStyleMatchesFramework(framework, style);
+  return {
+    framework,
+    style,
+    source: readChoice(raw, "source", SOURCES),
+    componentsDir: readString(raw, "componentsDir"),
+    toursDir: readString(raw, "toursDir"),
+    importBase: readString(raw, "importBase"),
+    platforms: readPlatforms(raw)
+  };
+}
+async function readConfig(cwd) {
+  const raw = await readJsonObject(join(cwd, CONFIG_FILE));
+  if (raw === void 0) throw new CliError(`No ${CONFIG_FILE} in ${toForwardSlashes(cwd)}. Run \`sapar init\` first.`);
+  return validateConfig(raw);
+}
+function writeConfig(cwd, config, force) {
+  return writeFileSafely(join(cwd, CONFIG_FILE), `${JSON.stringify(config, null, 4)}
+`, force);
+}
+
+// src/cli/format.ts
+import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { createRequire } from "module";
+import { join as join2 } from "path";
+
+// src/cli/report.ts
+var plural = (count, noun) => `${count} ${noun}${count === 1 ? "" : "s"}`;
+function formatFinding({ code, message, file, line }) {
+  const location = file === void 0 ? "" : `${file}${line === void 0 ? "" : `:${line}`}  `;
+  return `  ${location}${message} [${code}]`;
+}
+function formatSection(title, findings) {
+  return findings.length === 0 ? [] : [`${title} (${findings.length})`, ...findings.map(formatFinding), ""];
+}
+function formatSummary({ errors, warnings, stats }) {
+  const problems = errors.length + warnings.length === 0 ? "No problems found." : `Found ${plural(errors.length, "error")} and ${plural(warnings.length, "warning")}.`;
+  return `${problems} Scanned ${plural(stats.files, "file")} and ${plural(stats.tours, "tour")}.`;
+}
+function formatCheckText(report) {
+  return [
+    ...formatSection("Errors", report.errors),
+    ...formatSection("Warnings", report.warnings),
+    ...formatSection("Info", report.info),
+    formatSummary(report)
+  ].join("\n");
+}
+var formatCheckJson = (report) => JSON.stringify(report, null, 2);
+function formatWrites(cwd, records) {
+  return records.map(({ path, outcome }) => {
+    const note = outcome === "skipped" ? " (already exists; use --force to overwrite)" : "";
+    return `${outcome.padEnd(11)} ${displayPath(cwd, path)}${note}`;
+  }).join("\n");
+}
+
+// src/cli/format.ts
+var FORMATTED_HINT = "formatted with Prettier";
+var UNFORMATTED_HINT = "no Prettier config found; files use 4-space indentation and single quotes";
+function isPrettier(value) {
+  return typeof value === "object" && value !== null && "resolveConfig" in value && typeof value.resolveConfig === "function" && "format" in value && typeof value.format === "function";
+}
+function loadProjectPrettier(cwd) {
+  try {
+    const module = createRequire(join2(cwd, "package.json"))("prettier");
+    return isPrettier(module) ? module : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function formatFile(prettier, path) {
+  const config = await prettier.resolveConfig(path);
+  if (config === null) return "unconfigured";
+  const source = await readFile2(path, "utf8");
+  await writeFile2(path, await prettier.format(source, { ...config, filepath: path }));
+  return "formatted";
+}
+async function tryFormatFile(prettier, cwd, path, context) {
+  try {
+    return await formatFile(prettier, path);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    context.stderr(`warning: could not format ${displayPath(cwd, path)}: ${reason}`);
+    return "failed";
+  }
+}
+function hintFor(results) {
+  if (results.includes("formatted")) return FORMATTED_HINT;
+  return results.includes("failed") ? void 0 : UNFORMATTED_HINT;
+}
+async function formatWrittenFiles(cwd, records, context) {
+  const paths = records.filter(({ outcome }) => outcome !== "skipped").map(({ path }) => path);
+  if (paths.length === 0) return void 0;
+  const prettier = loadProjectPrettier(cwd);
+  const results = [];
+  for (const path of paths) {
+    results.push(prettier === void 0 ? "unconfigured" : await tryFormatFile(prettier, cwd, path, context));
+  }
+  return hintFor(results);
+}
+async function reportWrites(cwd, records, context, format) {
+  const hint = format ? await formatWrittenFiles(cwd, records, context) : void 0;
+  return [formatWrites(cwd, records), hint].filter(Boolean).join("\n");
+}
+
+// src/cli/packageInfo.ts
+import { dirname as dirname2, join as join3 } from "path";
+import { fileURLToPath } from "url";
+async function findPackageRoot(directory) {
+  if (await isDirectory(join3(directory, "templates"))) return directory;
+  const parent = dirname2(directory);
+  if (parent === directory) throw new CliError("Cannot locate the package templates directory.");
+  return findPackageRoot(parent);
+}
+async function readPackageInfo() {
+  const root = await findPackageRoot(dirname2(fileURLToPath(import.meta.url)));
+  const manifest = await readJsonObject(join3(root, "package.json"));
+  const { name, version } = manifest ?? {};
+  if (typeof name !== "string" || typeof version !== "string") {
+    throw new CliError(`${toForwardSlashes(join3(root, "package.json"))} has no name and version.`);
+  }
+  return { root, name, version };
+}
+
+// src/cli/templates.ts
+import { readdir, readFile as readFile3 } from "fs/promises";
+import { join as join4 } from "path";
+
+// src/cli/imports.ts
+var TEMPLATE_IMPORT = /(from\s+)(['"])\.\.\/\.\.\/src\/(\w+)\2/g;
+var AFTER_COPYING_NOTE = /^\/\/ After copying, change these imports.*\r?\n/m;
+function importSpecifier(entry, importBase, packageName) {
+  if (importBase !== packageName) return `${importBase}/${entry}`;
+  return entry === "core" ? packageName : `${packageName}/${entry}`;
+}
+function rewriteTemplateImports(source, importBase, packageName) {
+  return source.replace(AFTER_COPYING_NOTE, "").replace(
+    TEMPLATE_IMPORT,
+    (_match, from, quote, entry) => `${from}${quote}${importSpecifier(entry, importBase, packageName)}${quote}`
+  );
+}
+
+// src/cli/suggest.ts
+var MAX_SUGGESTIONS = 3;
+function editDistance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let row = 1; row <= a.length; row++) {
+    const current = [row];
+    for (let column = 1; column <= b.length; column++) {
+      const substitution = previous[column - 1] + (a[row - 1] === b[column - 1] ? 0 : 1);
+      current.push(Math.min(substitution, previous[column] + 1, current[column - 1] + 1));
+    }
+    previous = current;
+  }
+  return previous[b.length];
+}
+function distanceBetween(target, candidate) {
+  const [shorter, longer] = target.length <= candidate.length ? [target, candidate] : [candidate, target];
+  return longer.includes(shorter) ? 0 : editDistance(target, candidate);
+}
+function closestMatches(target, candidates) {
+  const maxDistance = Math.max(2, Math.floor(target.length / 3));
+  return [...candidates].map((candidate) => ({ candidate, distance: distanceBetween(target.toLowerCase(), candidate.toLowerCase()) })).filter(({ distance }) => distance <= maxDistance).sort((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate)).slice(0, MAX_SUGGESTIONS).map(({ candidate }) => candidate);
+}
+function didYouMean(suggestions) {
+  return suggestions.length > 0 ? `Did you mean ${suggestions.map((key) => `"${key}"`).join(" or ")}?` : "";
+}
+
+// src/cli/templates.ts
+var TEMPLATE_DIRECTORIES = { tailwind: "tailwind", mantine: "mantine", native: "expo" };
+var TEMPLATE_FILE = /^(?!.*\.test\.)(.+)\.tsx$/;
+var templateDirectory = ({ root }, style) => join4(root, "templates", TEMPLATE_DIRECTORIES[style]);
+async function listTemplates(packageInfo, style) {
+  let files = [];
+  try {
+    files = await readdir(templateDirectory(packageInfo, style));
+  } catch (error) {
+    if (!isNotFound(error)) throw error;
+  }
+  const names = files.flatMap((file) => TEMPLATE_FILE.exec(file)?.[1] ?? []).sort();
+  if (names.length === 0) throw new CliError(`No templates are available for the "${style}" style.`);
+  return names;
+}
+var comparable = (name) => name.replace(/[-_]/g, "").toLowerCase();
+function matchTemplateName(requested, available) {
+  const match = available.find((name) => comparable(name) === comparable(requested));
+  if (match !== void 0) return match;
+  const message = [`Unknown component "${requested}".`, didYouMean(closestMatches(requested, available)), `Available: ${available.join(", ")}.`];
+  throw new CliError(message.filter(Boolean).join(" "));
+}
+function matchTemplateNames(requested, available) {
+  return [...new Set(requested.map((name) => matchTemplateName(name, available)))];
+}
+async function copyTemplates(options) {
+  const { packageInfo, style, names, destination, importBase, force } = options;
+  const records = [];
+  for (const name of names) {
+    const source = await readFile3(join4(templateDirectory(packageInfo, style), `${name}.tsx`), "utf8");
+    const content = rewriteTemplateImports(source, importBase, packageInfo.name);
+    records.push(await writeFileSafely(join4(destination, `${name}.tsx`), content, force));
+  }
+  return records;
+}
+
+// src/cli/commands/add.ts
+async function addCommand(args, context) {
+  const { values, positionals } = parseCommandArgs(args, {
+    cwd: { type: "string" },
+    all: { type: "boolean" },
+    list: { type: "boolean" },
+    force: { type: "boolean" },
+    style: { type: "string" },
+    "no-format": { type: "boolean" }
+  });
+  const cwd = resolveCwd(context, values.cwd);
+  const config = await readConfig(cwd);
+  const style = values.style === void 0 ? config.style : parseChoice("style", values.style, STYLES);
+  const packageInfo = await readPackageInfo();
+  const available = await listTemplates(packageInfo, style);
+  if (values.list) {
+    context.stdout(available.join("\n"));
+    return 0;
+  }
+  const names = values.all ? available : matchTemplateNames(positionals, available);
+  if (names.length === 0) {
+    throw new CliError(`Name the components to add, or use --all. Available: ${available.join(", ")}.`);
+  }
+  const records = await copyTemplates({
+    packageInfo,
+    style,
+    names,
+    destination: join5(cwd, config.componentsDir),
+    importBase: config.importBase,
+    force: values.force ?? false
+  });
+  context.stdout(await reportWrites(cwd, records, context, !values["no-format"]));
+  return 0;
+}
+
+// src/core/routes.ts
+function isValidRoutePattern(pattern) {
+  if (!pattern) return false;
+  if (pattern === "*") return true;
+  const body = pattern.endsWith("/*") ? pattern.slice(0, -2) : pattern;
+  return !body.includes("*");
+}
+
+// src/core/define.ts
+var KEY_PATTERN = /^[a-z0-9_]+(\.[a-z0-9_]+)*$/;
+
+// src/cli/analyze.ts
+var at = ({ file, line }) => ({ file, line });
+var describeTour = (tour) => tour.key ? `tour "${tour.key.value}"` : "a tour";
+function keyedPlaces(file, located) {
+  return located.map(({ value, line }) => ({ key: value, file, line }));
+}
+function groupBy(items, keyOf) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const group = groups.get(keyOf(item));
+    if (group) group.push(item);
+    else groups.set(keyOf(item), [item]);
+  }
+  return [...groups.values()];
+}
+var perPlatform = (build) => ({
+  web: build("web"),
+  native: build("native")
+});
+function declarationsOn(scan, platform) {
+  const places = scan.files.filter((file) => file.platforms.includes(platform)).flatMap((file) => keyedPlaces(file.path, file.anchorUses));
+  return new Map(groupBy(places, ({ key }) => key).map((group) => [group[0].key, group]));
+}
+function buildAnalysis(scan, config) {
+  return {
+    scan,
+    config,
+    tours: scan.files.flatMap((file) => file.tours.map((tour) => ({ ...tour, file: file.path }))),
+    catalogue: scan.files.flatMap((file) => keyedPlaces(file.path, file.catalogue)),
+    uses: scan.files.flatMap((file) => keyedPlaces(file.path, file.anchorUses)),
+    declarations: perPlatform((platform) => declarationsOn(scan, platform)),
+    filesByPlatform: perPlatform((platform) => scan.files.filter((file) => file.platforms.includes(platform)).length)
+  };
+}
+function targetedPlatforms(tour, config) {
+  return tour.platforms?.filter(isPlatform) ?? PLATFORMS.filter((platform) => config.platforms[platform].length > 0);
+}
+function occurrence(file, description, located, context = "") {
+  return located ? [{ key: located.value, file, line: located.line, description, context }] : [];
+}
+function tourKeyOccurrences({ tours }) {
+  return tours.flatMap((tour) => {
+    const context = ` in ${describeTour(tour)}`;
+    return [
+      ...occurrence(tour.file, "tour key", tour.key),
+      ...tour.steps.flatMap((step) => [
+        ...occurrence(tour.file, "step key", step.key, context),
+        ...occurrence(tour.file, "step anchor", step.anchor, context)
+      ])
+    ];
+  });
+}
+function invalidKeyFindings(analysis) {
+  const occurrences = [
+    ...tourKeyOccurrences(analysis),
+    ...analysis.catalogue.map((entry) => ({ ...entry, description: "catalogue anchor", context: "" })),
+    ...analysis.uses.map((use) => ({ ...use, description: "declared anchor", context: "" }))
+  ];
+  return occurrences.filter(({ key }) => !KEY_PATTERN.test(key)).map((entry) => ({
+    code: "key_invalid",
+    message: `Invalid ${entry.description} "${entry.key}"${entry.context}: use lowercase letters, digits and underscores, dot-separated.`,
+    ...at(entry)
+  }));
+}
+function invalidRouteFindings({ tours }) {
+  return tours.flatMap((tour) => [
+    ...occurrence(tour.file, "trigger route", tour.triggerRoute, ` of ${describeTour(tour)}`),
+    ...tour.steps.flatMap((step) => occurrence(tour.file, "step route", step.route, ` in ${describeTour(tour)}`))
+  ]).filter(({ key }) => !isValidRoutePattern(key)).map((entry) => ({
+    code: "route_invalid",
+    message: `Invalid ${entry.description} "${entry.key}"${entry.context}: use a path, a prefix ending in /*, or *.`,
+    ...at(entry)
+  }));
+}
+function duplicateFindings(code, what, places) {
+  return groupBy(places, ({ key }) => key).filter((group) => group.length > 1).flatMap(
+    ([first, ...repeats]) => repeats.map((repeat) => ({
+      code,
+      message: `Duplicate ${what}: "${repeat.key}" (first at ${first.file}:${first.line}).`,
+      ...at(repeat)
+    }))
+  );
+}
+function duplicateTourFindings({ tours }) {
+  const places = tours.flatMap((tour) => occurrence(tour.file, "tour key", tour.key));
+  return duplicateFindings("tour_duplicate", "tour key", places);
+}
+function duplicateStepFindings({ tours }) {
+  return tours.flatMap(
+    (tour) => duplicateFindings(
+      "step_duplicate",
+      `step key in ${describeTour(tour)}`,
+      tour.steps.flatMap((step) => occurrence(tour.file, "step key", step.key))
+    )
+  );
+}
+function missingAnchorFinding(analysis, tour, anchor, platform) {
+  const declaredHere = analysis.declarations[platform];
+  const elsewhere = PLATFORMS.filter((other) => other !== platform && analysis.declarations[other].has(anchor.value));
+  const suggestions = closestMatches(anchor.value, declaredHere.keys());
+  const message = [
+    `In ${describeTour(tour)}: anchor "${anchor.value}" is not declared on ${platform}.`,
+    elsewhere.length > 0 ? `It is declared on ${elsewhere.join(", ")}.` : "",
+    didYouMean(suggestions)
+  ];
+  return { code: "anchor_missing", message: message.filter(Boolean).join(" "), file: tour.file, line: anchor.line, suggestions };
+}
+function missingAnchorFindings(analysis) {
+  return analysis.tours.flatMap(
+    (tour) => targetedPlatforms(tour, analysis.config).filter((platform) => analysis.filesByPlatform[platform] > 0).flatMap(
+      (platform) => tour.steps.flatMap(
+        ({ anchor }) => anchor && !analysis.declarations[platform].has(anchor.value) ? [missingAnchorFinding(analysis, tour, anchor, platform)] : []
+      )
+    )
+  );
+}
+function uncataloguedFindings({ catalogue, uses }) {
+  const known = new Set(catalogue.map(({ key }) => key));
+  if (known.size === 0) return [];
+  return uses.filter(({ key }) => !known.has(key)).map((use) => {
+    const suggestions = closestMatches(use.key, known);
+    const message = `Anchor "${use.key}" is declared here but missing from defineAnchors([...]). ${didYouMean(suggestions)}`;
+    return { code: "anchor_uncatalogued", message: message.trim(), ...at(use), suggestions };
+  });
+}
+function missingRootFindings({ scan }) {
+  return scan.missingRoots.map((root) => ({
+    code: "source_root_missing",
+    message: `Scan root "${root}" from sapar.json is not a directory.`
+  }));
+}
+function unreadableFindings({ scan }) {
+  return scan.files.flatMap(
+    (file) => file.unverifiable.map(({ value, line }) => ({ code: "value_unverifiable", message: value, file: file.path, line }))
+  );
+}
+function undeclaredCatalogueFindings({ catalogue, uses }) {
+  const used = new Set(uses.map(({ key }) => key));
+  return catalogue.filter(({ key }) => !used.has(key)).map((entry) => ({
+    code: "anchor_undeclared",
+    message: `Anchor "${entry.key}" is in defineAnchors([...]) but no element declares it.`,
+    ...at(entry)
+  }));
+}
+function duplicateDeclarationFindings({ declarations }) {
+  return PLATFORMS.flatMap(
+    (platform) => duplicateFindings("anchor_duplicate", `anchor on ${platform}`, [...declarations[platform].values()].flat())
+  );
+}
+function platformFindings({ scan, config, tours, filesByPlatform }) {
+  if (scan.files.length === 0) {
+    return [
+      {
+        code: "nothing_scanned",
+        message: 'Scanned 0 files, so sapar check did not verify anything. Check "platforms" and "toursDir" in sapar.json.'
+      }
+    ];
+  }
+  const explicitTargets = new Set(tours.flatMap((tour) => tour.platforms ?? []));
+  return PLATFORMS.filter(
+    (platform) => filesByPlatform[platform] === 0 && (config.platforms[platform].length > 0 || explicitTargets.has(platform))
+  ).map((platform) => ({
+    code: "platform_unverified",
+    message: config.platforms[platform].length === 0 ? `"platforms.${platform}" in sapar.json has no scan roots, so tours targeting ${platform} were not verified.` : `No source files found under ${config.platforms[platform].join(", ")}, so nothing was verified for ${platform}.`
+  }));
+}
+function unusedAnchorFindings({ tours, uses }) {
+  const inTours = new Set(tours.flatMap((tour) => tour.steps.flatMap((step) => step.anchor?.value ?? [])));
+  return groupBy(uses, ({ key }) => key).filter(([first]) => !inTours.has(first.key)).map(([first]) => ({
+    code: "anchor_unused",
+    message: `Anchor "${first.key}" is declared but no tour uses it.`,
+    ...at(first)
+  }));
+}
+function analyze(scan, config, { verbose }) {
+  const analysis = buildAnalysis(scan, config);
+  return {
+    errors: [
+      ...missingRootFindings(analysis),
+      ...invalidKeyFindings(analysis),
+      ...invalidRouteFindings(analysis),
+      ...duplicateTourFindings(analysis),
+      ...duplicateStepFindings(analysis),
+      ...missingAnchorFindings(analysis),
+      ...uncataloguedFindings(analysis)
+    ],
+    warnings: [
+      ...platformFindings(analysis),
+      ...undeclaredCatalogueFindings(analysis),
+      ...duplicateDeclarationFindings(analysis),
+      ...unreadableFindings(analysis)
+    ],
+    info: verbose ? unusedAnchorFindings(analysis) : [],
+    stats: {
+      files: scan.files.length,
+      filesByPlatform: analysis.filesByPlatform,
+      tours: analysis.tours.length,
+      anchorsDeclared: analysis.uses.length,
+      anchorsCatalogued: analysis.catalogue.length
+    }
+  };
+}
+
+// src/cli/scan/project.ts
+import { readFile as readFile4 } from "fs/promises";
+import { join as join7 } from "path";
+
+// src/cli/scan/ast.ts
+function lineOf({ sourceFile }, node) {
+  return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+}
+function visit(typescript, node, callback) {
+  callback(node);
+  typescript.forEachChild(node, (child) => visit(typescript, child, callback));
+}
+function calleeName({ typescript }, call) {
+  return typescript.isIdentifier(call.expression) ? call.expression.text : void 0;
+}
+
+// src/cli/scan/constants.ts
+function withoutWrappers(typescript, node) {
+  let current = node;
+  while (typescript.isParenthesizedExpression(current) || typescript.isAsExpression(current) || typescript.isSatisfiesExpression(current)) {
+    current = current.expression;
+  }
+  return current;
+}
+function literalString(typescript, node) {
+  const unwrapped = withoutWrappers(typescript, node);
+  return typescript.isStringLiteralLike(unwrapped) ? unwrapped.text : void 0;
+}
+function collectStringConstants(typescript, sourceFile) {
+  const constants = /* @__PURE__ */ new Map();
+  for (const statement of sourceFile.statements) {
+    if (!typescript.isVariableStatement(statement)) continue;
+    if (!(statement.declarationList.flags & typescript.NodeFlags.Const)) continue;
+    for (const { name, initializer } of statement.declarationList.declarations) {
+      const value = initializer && literalString(typescript, initializer);
+      if (typescript.isIdentifier(name) && value !== void 0) constants.set(name.text, value);
+    }
+  }
+  return constants;
+}
+function createSourceContext(typescript, path, text) {
+  const sourceFile = typescript.createSourceFile(path, text, typescript.ScriptTarget.Latest);
+  return { typescript, sourceFile, constants: collectStringConstants(typescript, sourceFile) };
+}
+function stringValue({ typescript, constants }, node) {
+  if (node === void 0) return void 0;
+  const unwrapped = withoutWrappers(typescript, node);
+  if (typescript.isIdentifier(unwrapped)) return constants.get(unwrapped.text);
+  return literalString(typescript, unwrapped);
+}
+
+// src/cli/scan/anchors.ts
+var ANCHOR_HOOK = /^use\w*Anchor$/;
+var ANCHOR_ATTRIBUTE = "data-sapar";
+function isLogicalOperator({ typescript }, kind) {
+  const { AmpersandAmpersandToken, BarBarToken, QuestionQuestionToken } = typescript.SyntaxKind;
+  return kind === AmpersandAmpersandToken || kind === BarBarToken || kind === QuestionQuestionToken;
+}
+function literalsIn(context, node) {
+  const { typescript } = context;
+  const literal = stringValue(context, node);
+  if (literal !== void 0) return [literal];
+  if (node === void 0) return [];
+  if (typescript.isParenthesizedExpression(node)) return literalsIn(context, node.expression);
+  if (typescript.isConditionalExpression(node)) {
+    return [...literalsIn(context, node.whenTrue), ...literalsIn(context, node.whenFalse)];
+  }
+  if (typescript.isBinaryExpression(node) && isLogicalOperator(context, node.operatorToken.kind)) {
+    return [...literalsIn(context, node.left), ...literalsIn(context, node.right)];
+  }
+  return [];
+}
+function keysDeclaredBy(context, node) {
+  const { typescript } = context;
+  if (typescript.isCallExpression(node) && ANCHOR_HOOK.test(calleeName(context, node) ?? "")) {
+    return literalsIn(context, node.arguments[0]);
+  }
+  if (typescript.isJsxAttribute(node) && typescript.isIdentifier(node.name) && node.name.text === ANCHOR_ATTRIBUTE) {
+    const { initializer } = node;
+    return literalsIn(context, initializer && typescript.isJsxExpression(initializer) ? initializer.expression : initializer);
+  }
+  return [];
+}
+function findAnchorUses(context) {
+  const uses = [];
+  visit(context.typescript, context.sourceFile, (node) => {
+    keysDeclaredBy(context, node).forEach((key) => uses.push({ value: key, line: lineOf(context, node) }));
+  });
+  return uses;
+}
+
+// src/cli/scan/definitions.ts
+var STATIC_VALUE_HINT = " (use a string literal or a const declared in this file).";
+function noteUnverifiable(collector, node, explanation) {
+  collector.unverifiable.push({ value: explanation, line: lineOf(collector, node) });
+}
+function propertyValue(collector, object, name) {
+  const { typescript } = collector;
+  for (const property of object.properties) {
+    if (!typescript.isPropertyAssignment(property) && !typescript.isShorthandPropertyAssignment(property)) continue;
+    const propertyName = property.name;
+    const isMatch = (typescript.isIdentifier(propertyName) || typescript.isStringLiteralLike(propertyName)) && propertyName.text === name;
+    if (!isMatch) continue;
+    return typescript.isPropertyAssignment(property) ? property.initializer : property.name;
+  }
+  return void 0;
+}
+function readString2(collector, node, description) {
+  if (node === void 0) return void 0;
+  const value = stringValue(collector, node);
+  if (value === void 0) {
+    noteUnverifiable(collector, node, `The ${description} is not a string literal, so it was not verified${STATIC_VALUE_HINT}`);
+    return void 0;
+  }
+  return { value, line: lineOf(collector, node) };
+}
+function readStringProperty(collector, object, name, description) {
+  return readString2(collector, propertyValue(collector, object, name), description);
+}
+function readArray(collector, node, description) {
+  if (node === void 0) return [];
+  if (!collector.typescript.isArrayLiteralExpression(node)) {
+    noteUnverifiable(collector, node, `The ${description} is not an array literal, so it was not verified.`);
+    return [];
+  }
+  return node.elements;
+}
+function readStrings(collector, node, description) {
+  return readArray(collector, node, description).flatMap(
+    (element) => readString2(collector, element, `${description} entry`)?.value ?? []
+  );
+}
+function readStep(collector, node) {
+  if (!collector.typescript.isObjectLiteralExpression(node)) {
+    noteUnverifiable(collector, node, "A step is not an object literal, so it was not verified.");
+    return void 0;
+  }
+  return {
+    key: readStringProperty(collector, node, "key", "step key"),
+    anchor: readStringProperty(collector, node, "anchor", "step anchor"),
+    route: readStringProperty(collector, node, "route", "step route")
+  };
+}
+function readTriggerRoute(collector, trigger) {
+  if (trigger === void 0 || !collector.typescript.isObjectLiteralExpression(trigger)) return void 0;
+  return readStringProperty(collector, trigger, "route", "trigger route");
+}
+function readTour(collector, call) {
+  const [input] = call.arguments;
+  if (input === void 0 || !collector.typescript.isObjectLiteralExpression(input)) {
+    noteUnverifiable(collector, call, "defineTour() is not called with an object literal, so it was not verified.");
+    return void 0;
+  }
+  const platformsValue = propertyValue(collector, input, "platforms");
+  return {
+    line: lineOf(collector, call),
+    key: readStringProperty(collector, input, "key", "tour key"),
+    triggerRoute: readTriggerRoute(collector, propertyValue(collector, input, "trigger")),
+    platforms: platformsValue && readStrings(collector, platformsValue, "platforms"),
+    steps: readArray(collector, propertyValue(collector, input, "steps"), "steps").flatMap(
+      (step) => readStep(collector, step) ?? []
+    )
+  };
+}
+function readCatalogue(collector, call) {
+  return readArray(collector, call.arguments[0], "defineAnchors() argument").flatMap(
+    (element) => readString2(collector, element, "anchor key") ?? []
+  );
+}
+function findDefinitions(context) {
+  const collector = { ...context, unverifiable: [] };
+  const findings = { catalogue: [], tours: [], unverifiable: collector.unverifiable };
+  visit(context.typescript, context.sourceFile, (node) => {
+    if (!context.typescript.isCallExpression(node)) return;
+    const callee = calleeName(context, node);
+    if (callee === "defineAnchors") findings.catalogue.push(...readCatalogue(collector, node));
+    const tour = callee === "defineTour" ? readTour(collector, node) : void 0;
+    if (tour !== void 0) findings.tours.push(tour);
+  });
+  return findings;
+}
+
+// src/cli/scan/files.ts
+import { readdir as readdir2 } from "fs/promises";
+import { join as join6, resolve as resolve2 } from "path";
+var SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "coverage"]);
+var SOURCE_FILE = /\.[cm]?[jt]sx?$/;
+var TEST_FILE = /\.test\./;
+function isScannedDirectory(name) {
+  return !name.startsWith(".") && !SKIPPED_DIRECTORIES.has(name);
+}
+async function listSourceFiles(directory) {
+  const entries = (await readdir2(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name));
+  const nested = await Promise.all(
+    entries.map(async (entry) => {
+      const path = join6(directory, entry.name);
+      if (entry.isDirectory()) return isScannedDirectory(entry.name) ? listSourceFiles(path) : [];
+      const isSource = entry.isFile() && SOURCE_FILE.test(entry.name) && !TEST_FILE.test(entry.name);
+      return isSource ? [path] : [];
+    })
+  );
+  return nested.flat();
+}
+function scanRoots(config) {
+  return [
+    ...PLATFORMS.flatMap((platform) => config.platforms[platform].map((directory) => ({ directory, platform }))),
+    { directory: config.toursDir }
+  ];
+}
+async function discoverSourceFiles(cwd, config) {
+  const platformsByFile = /* @__PURE__ */ new Map();
+  const missingRoots = [];
+  for (const { directory, platform } of scanRoots(config)) {
+    const absolute = resolve2(cwd, directory);
+    if (!await isDirectory(absolute)) {
+      missingRoots.push(directory);
+      continue;
+    }
+    for (const file of await listSourceFiles(absolute)) {
+      const platforms = platformsByFile.get(file) ?? /* @__PURE__ */ new Set();
+      if (platform !== void 0) platforms.add(platform);
+      platformsByFile.set(file, platforms);
+    }
+  }
+  const files = [...platformsByFile].map(([file, platforms]) => ({
+    path: displayPath(cwd, file),
+    platforms: [...platforms]
+  }));
+  return { files, missingRoots };
+}
+
+// src/cli/scan/project.ts
+async function scanFile(typescript, cwd, path) {
+  const text = await readFile4(join7(cwd, path), "utf8");
+  const context = createSourceContext(typescript, path, text);
+  return { anchorUses: findAnchorUses(context), ...findDefinitions(context) };
+}
+async function scanProject(typescript, cwd, config) {
+  const { files: discovered, missingRoots } = await discoverSourceFiles(cwd, config);
+  const files = [];
+  for (const file of discovered) {
+    files.push({ ...file, ...await scanFile(typescript, cwd, file.path) });
+  }
+  return { files, missingRoots };
+}
+
+// src/cli/commands/check.ts
+var OUTPUT_FORMATS = ["text", "json"];
+async function loadTypescript() {
+  try {
+    const module = await import("typescript");
+    return module.default ?? module;
+  } catch {
+    throw new CliError("`sapar check` needs the `typescript` package. Install it as a dev dependency: pnpm add -D typescript");
+  }
+}
+var failed = ({ errors, warnings }, strict) => errors.length > 0 || strict && warnings.length > 0;
+async function checkCommand(args, context) {
+  const { values } = parseCommandArgs(args, {
+    cwd: { type: "string" },
+    format: { type: "string", default: "text" },
+    strict: { type: "boolean" },
+    verbose: { type: "boolean" }
+  });
+  const format = parseChoice("format", values.format, OUTPUT_FORMATS);
+  const cwd = resolveCwd(context, values.cwd);
+  const config = await readConfig(cwd);
+  const scan = await scanProject(await loadTypescript(), cwd, config);
+  const report = analyze(scan, config, { verbose: values.verbose ?? false });
+  context.stdout(format === "json" ? formatCheckJson(report) : formatCheckText(report));
+  return failed(report, values.strict ?? false) ? 1 : 0;
+}
+
+// src/cli/commands/init.ts
+import { join as join10 } from "path";
+
+// src/cli/detect.ts
+import { join as join8 } from "path";
+var DEPENDENCY_FIELDS = ["dependencies", "devDependencies"];
+function dependencyNames(manifest) {
+  return DEPENDENCY_FIELDS.flatMap((field) => {
+    const entries = manifest[field];
+    return typeof entries === "object" && entries !== null ? Object.keys(entries) : [];
+  });
+}
+async function readProject(cwd) {
+  const manifest = await readJsonObject(join8(cwd, "package.json"));
+  if (manifest === void 0) throw new CliError(`No package.json in ${toForwardSlashes(cwd)}. Run this from your project root.`);
+  return {
+    dependencies: new Set(dependencyNames(manifest)),
+    hasSrcDir: await isDirectory(join8(cwd, "src"))
+  };
+}
+function detectFramework({ dependencies }) {
+  if (dependencies.has("next")) return "next";
+  if (dependencies.has("expo")) return "expo";
+  return "react";
+}
+function detectStyle({ dependencies }, framework) {
+  if (framework === "expo") return "native";
+  return dependencies.has("@mantine/core") ? "mantine" : "tailwind";
+}
+function detectSource({ dependencies }) {
+  return dependencies.has("@reduxjs/toolkit") ? "rtk" : "memory";
+}
+function defaultDirectories({ hasSrcDir }) {
+  const base = hasSrcDir ? "src/" : "";
+  return { componentsDir: `${base}components/tours`, toursDir: `${base}tours` };
+}
+function defaultPlatforms({ hasSrcDir }, framework) {
+  const roots = [hasSrcDir ? "src" : "."];
+  const platform = platformOf(framework);
+  return { web: platform === "web" ? roots : [], native: platform === "native" ? roots : [] };
+}
+
+// src/cli/scaffold.ts
+import { join as join9 } from "path";
+var HTTP_BASE_URLS = { web: "/api/tours", native: "https://api.example.com/tours" };
+function generateDefinitions(config, specifier) {
+  return `import { defineAnchors, defineTour } from '${specifier("core")}';
+
+export const anchors = defineAnchors(['welcome.header']);
+
+export const welcomeTour = defineTour({
+    key: 'welcome',
+    title: 'Welcome',
+    platforms: ['${platformOf(config.framework)}'],
+    steps: [
+        { key: 'hello', title: 'Welcome aboard', body: 'A quick look around.' },
+        {
+            key: 'header',
+            anchor: 'welcome.header',
+            title: 'Your header',
+            body: 'Tours can point at any element you mark with an anchor.',
+        },
+    ],
+});
+
+export const tours = [welcomeTour];
+`;
+}
+function generateAnchors(config, specifier) {
+  const anchorEntry = platformOf(config.framework) === "native" ? "expo" : "web";
+  return `import type { AnchorKey } from '${specifier("core")}';
+import { useTourAnchor } from '${specifier(anchorEntry)}';
+import type { anchors } from './definitions';
+
+/** Mark the element a step points at: \`<button {...useAnchor('welcome.header')} />\`. */
+export function useAnchor(key: AnchorKey<typeof anchors>) {
+    return useTourAnchor(key);
+}
+`;
+}
+function memorySetup(config, specifier) {
+  const isExpo = config.framework === "expo";
+  const storage = isExpo ? { named: { module: specifier("expo"), names: ["asyncStorageStore"] }, expression: "asyncStorageStore(AsyncStorage)" } : { named: { module: specifier("web"), names: ["localStorageStore"] }, expression: "localStorageStore()" };
+  return {
+    named: [{ module: specifier("core"), names: ["memorySource"] }, storage.named],
+    otherImports: [
+      ...isExpo ? [`import AsyncStorage from '@react-native-async-storage/async-storage';`] : [],
+      `import { tours } from './definitions';`
+    ],
+    moduleScope: [],
+    reactHooks: ["useMemo"],
+    insideComponent: [
+      "// A string key, so a `new Date(...)` passed on every render does not recreate the source.",
+      "const registeredAtIso = registeredAt === undefined ? undefined : new Date(registeredAt).toISOString();",
+      "// A new user is a new source on purpose: each gets their own namespace and grace period.",
+      "const source = useMemo(",
+      "    () =>",
+      "        memorySource({",
+      "            tours,",
+      `            storage: ${storage.expression},`,
+      "            namespace: `app.sapar.${userId}`,",
+      "            registeredAt: registeredAtIso,",
+      "        }),",
+      "    [userId, registeredAtIso],",
+      ");"
+    ],
+    componentProps: [
+      { name: "userId", type: "string" },
+      { name: "registeredAt?", type: "Date | string" }
+    ]
+  };
+}
+function httpSetup(config, specifier) {
+  const baseUrl = HTTP_BASE_URLS[platformOf(config.framework)];
+  return {
+    named: [{ module: specifier("core"), names: ["httpSource"] }],
+    otherImports: [],
+    moduleScope: [`const source = httpSource({ baseUrl: '${baseUrl}' });`],
+    insideComponent: [],
+    reactHooks: [],
+    componentProps: []
+  };
+}
+function rtkSetup(specifier) {
+  return {
+    named: [{ module: specifier("rtk"), names: ["createSaparRtk"] }],
+    otherImports: ["// TODO: point this at your RTK Query api slice", `import { baseApi } from '@/store/api';`],
+    moduleScope: ["const toursRtk = createSaparRtk(baseApi);"],
+    insideComponent: ["const source = toursRtk.useSaparSource();"],
+    reactHooks: [],
+    componentProps: []
+  };
+}
+function sourceSetup(config, specifier) {
+  if (config.source === "http") return httpSetup(config, specifier);
+  if (config.source === "rtk") return rtkSetup(specifier);
+  return memorySetup(config, specifier);
+}
+function providerSetup(config, specifier) {
+  if (config.framework === "next") {
+    return {
+      named: [{ module: specifier("next"), names: ["NextSaparProvider"] }],
+      moduleScope: [],
+      tag: "NextSaparProvider",
+      props: "source={source}"
+    };
+  }
+  if (config.framework === "expo") {
+    return {
+      named: [{ module: specifier("expo-router"), names: ["ExpoSaparProvider"] }],
+      moduleScope: [],
+      tag: "ExpoSaparProvider",
+      props: "source={source}"
+    };
+  }
+  return {
+    named: [
+      { module: specifier("react"), names: ["SaparProvider"] },
+      { module: specifier("web"), names: ["createWebAdapter"] }
+    ],
+    moduleScope: [
+      [
+        "// TODO: use your router here, and pass `route` to <SaparProvider> to enable route triggers",
+        "const adapter = createWebAdapter({",
+        `    navigate: (route) => window.history.pushState(null, '', route),`,
+        "    currentRoute: () => window.location.pathname,",
+        "});"
+      ].join("\n")
+    ],
+    tag: "SaparProvider",
+    props: "source={source} adapter={adapter}"
+  };
+}
+function renderNamedImports(imports) {
+  const namesByModule = /* @__PURE__ */ new Map();
+  for (const { module, names } of imports) namesByModule.set(module, [...namesByModule.get(module) ?? [], ...names]);
+  return [...namesByModule].map(([module, names]) => `import { ${names.sort().join(", ")} } from '${module}';`);
+}
+var indent = (lines) => lines.map((line) => `    ${line}`);
+function renderComponentParameters(props) {
+  const all = [...props, { name: "children", type: "ReactNode" }];
+  const names = all.map(({ name }) => name.replace("?", "")).join(", ");
+  const types = all.map(({ name, type }) => `${name}: ${type}`).join("; ");
+  return `{ ${names} }: { ${types} }`;
+}
+function reactImport(hooks) {
+  return hooks.length === 0 ? "import type { ReactNode } from 'react';" : `import { ${hooks.join(", ")}, type ReactNode } from 'react';`;
+}
+function generateProvider(config, specifier) {
+  const provider = providerSetup(config, specifier);
+  const source = sourceSetup(config, specifier);
+  const directive = config.framework === "next" ? ["'use client';", ""] : [];
+  const imports = [
+    reactImport(source.reactHooks),
+    ...renderNamedImports([...provider.named, ...source.named]),
+    ...source.otherImports
+  ];
+  const moduleScope = [...provider.moduleScope, ...source.moduleScope];
+  return `${[
+    ...directive,
+    ...imports,
+    "",
+    ...moduleScope.flatMap((block) => [block, ""]),
+    `export function AppSaparProvider(${renderComponentParameters(source.componentProps)}) {`,
+    ...indent(source.insideComponent),
+    ...indent([
+      "return (",
+      `    <${provider.tag} ${provider.props}>{children}</${provider.tag}>`,
+      ");"
+    ]),
+    "}"
+  ].join("\n")}
+`;
+}
+function scaffoldFiles(config, packageName) {
+  const specifier = (entry) => importSpecifier(entry, config.importBase, packageName);
+  return [
+    { path: join9(config.toursDir, "definitions.ts"), content: generateDefinitions(config, specifier) },
+    { path: join9(config.toursDir, "anchors.ts"), content: generateAnchors(config, specifier) },
+    { path: join9(config.toursDir, "SaparProvider.tsx"), content: generateProvider(config, specifier) }
+  ];
+}
+
+// src/cli/commands/init.ts
+var STARTER_COMPONENT = "TourCard";
+function parseText(raw) {
+  if (raw.trim() === "") throw new CliError("The value cannot be empty.");
+  return raw.trim();
+}
+var choiceSetting = (label, choices, flag, detected) => ({
+  question: `${label} (${choices.join("/")})`,
+  flag,
+  detected,
+  parse: (raw) => parseChoice(label, raw, choices)
+});
+async function resolveSetting({ question, flag, detected, parse }, context, prompt) {
+  if (flag !== void 0) return parse(flag);
+  if (prompt === void 0) return detected;
+  for (; ; ) {
+    try {
+      return parse(await prompt(question, detected));
+    } catch (error) {
+      if (!(error instanceof CliError)) throw error;
+      context.stderr(error.message);
+    }
+  }
+}
+async function resolveConfig(flags, cwd, packageName, context, prompt) {
+  const project = await readProject(cwd);
+  const framework = await resolveSetting(
+    choiceSetting("framework", FRAMEWORKS, flags.framework, detectFramework(project)),
+    context,
+    prompt
+  );
+  const style = await resolveSetting(
+    choiceSetting("style", STYLES, flags.style, detectStyle(project, framework)),
+    context,
+    prompt
+  );
+  const source = await resolveSetting(
+    choiceSetting("source", SOURCES, flags.source, detectSource(project)),
+    context,
+    prompt
+  );
+  const importBase = await resolveSetting(
+    { question: "import base", flag: flags.importBase, detected: packageName, parse: parseText },
+    context,
+    prompt
+  );
+  const directories = defaultDirectories(project);
+  const componentsDir = await resolveSetting(
+    { question: "components dir", flag: flags.componentsDir, detected: directories.componentsDir, parse: parseText },
+    context,
+    prompt
+  );
+  const toursDir = await resolveSetting(
+    { question: "tours dir", flag: flags.toursDir, detected: directories.toursDir, parse: parseText },
+    context,
+    prompt
+  );
+  assertStyleMatchesFramework(framework, style);
+  return {
+    framework,
+    style,
+    source,
+    componentsDir,
+    toursDir,
+    importBase,
+    platforms: defaultPlatforms(project, framework)
+  };
+}
+function nextSteps(config) {
+  const providerPath = displayJoin([config.toursDir, "SaparProvider.tsx"]);
+  const providerStep = {
+    rtk: `Point the baseApi import in ${providerPath} at your RTK Query slice, and mount <AppSaparProvider /> inside the Redux <Provider>.`,
+    http: `Mount <AppSaparProvider /> from ${providerPath} near the root of your app.`,
+    memory: `Mount <AppSaparProvider userId={...} registeredAt={...} /> from ${providerPath} near the root of your app: pass the signed-in user's id (it namespaces their saved progress) and when they registered (it enables the new-user grace period).`
+  }[config.source];
+  return [
+    "",
+    "Next steps:",
+    `  1. ${providerStep}`,
+    `  2. Render <${STARTER_COMPONENT} /> from ${config.componentsDir} inside it.`,
+    `  3. Mark the element a step points at with useAnchor('welcome.header') from ${displayJoin([config.toursDir, "anchors"])}.`,
+    "  4. Run `sapar check` in CI to catch anchors that go missing."
+  ].join("\n");
+}
+async function initCommand(args, context) {
+  const { values } = parseCommandArgs(args, {
+    cwd: { type: "string" },
+    yes: { type: "boolean" },
+    force: { type: "boolean" },
+    framework: { type: "string" },
+    style: { type: "string" },
+    source: { type: "string" },
+    "import-base": { type: "string" },
+    "components-dir": { type: "string" },
+    "tours-dir": { type: "string" },
+    "no-format": { type: "boolean" }
+  });
+  const cwd = resolveCwd(context, values.cwd);
+  const force = values.force ?? false;
+  const packageInfo = await readPackageInfo();
+  const config = await resolveConfig(
+    {
+      framework: values.framework,
+      style: values.style,
+      source: values.source,
+      importBase: values["import-base"],
+      componentsDir: values["components-dir"],
+      toursDir: values["tours-dir"]
+    },
+    cwd,
+    packageInfo.name,
+    context,
+    values.yes ? void 0 : context.prompt
+  );
+  const records = [await writeConfig(cwd, config, force)];
+  for (const file of scaffoldFiles(config, packageInfo.name)) {
+    records.push(await writeFileSafely(join10(cwd, file.path), file.content, force));
+  }
+  records.push(
+    ...await copyTemplates({
+      packageInfo,
+      style: config.style,
+      names: [STARTER_COMPONENT],
+      destination: join10(cwd, config.componentsDir),
+      importBase: config.importBase,
+      force
+    })
+  );
+  context.stdout(`${await reportWrites(cwd, records, context, !values["no-format"])}
+${nextSteps(config)}`);
+  return 0;
+}
+
+// src/cli/main.ts
+var COMMANDS = /* @__PURE__ */ new Map([
+  ["init", { run: initCommand, help: INIT_HELP }],
+  ["add", { run: addCommand, help: ADD_HELP }],
+  ["check", { run: checkCommand, help: CHECK_HELP }]
+]);
+var isHelpFlag = (arg) => arg === "--help" || arg === "-h";
+async function dispatch(argv, context) {
+  const [name, ...args] = argv;
+  if (name === "--version" || name === "-v") {
+    context.stdout((await readPackageInfo()).version);
+    return 0;
+  }
+  if (isHelpFlag(name)) {
+    context.stdout(GENERAL_HELP);
+    return 0;
+  }
+  const command = name === void 0 ? void 0 : COMMANDS.get(name);
+  if (command === void 0) {
+    context.stderr(name === void 0 ? GENERAL_HELP : `Unknown command "${name}".
+
+${GENERAL_HELP}`);
+    return 1;
+  }
+  if (args.some(isHelpFlag)) {
+    context.stdout(command.help);
+    return 0;
+  }
+  return command.run(args, context);
+}
+async function runCli(argv, context) {
+  try {
+    return await dispatch(argv, context);
+  } catch (error) {
+    if (!(error instanceof CliError)) throw error;
+    context.stderr(`error: ${error.message}`);
+    return 1;
+  }
+}
+
+// src/cli/index.ts
+var prompter = process.stdin.isTTY ? createPrompter() : void 0;
+process.exitCode = await runCli(process.argv.slice(2), {
+  cwd: process.cwd(),
+  stdout: (line) => process.stdout.write(`${line}
+`),
+  stderr: (line) => process.stderr.write(`${line}
+`),
+  ...prompter && { prompt: prompter.ask }
+}).finally(() => prompter?.close());