@navieo/cli 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# @navieo/cli
+
+CLI tool for Navieo — scan your codebase, generate sitemaps, and sync with the Navieo backend.
+
+## Installation
+
+```bash
+npm install -g @navieo/cli
+```
+
+Or run directly with npx:
+
+```bash
+npx @navieo/cli <command>
+```
+
+## Commands
+
+### `navieo init`
+
+Scan your codebase and generate an initial sitemap with a docs folder.
+
+```bash
+navieo init [--dir <path>]
+```
+
+- Detects your framework (Next.js App Router, Pages Router, Vite)
+- Scans routes and extracts interactive elements
+- Creates `navieo/sitemap.navieo.json` and `navieo/docs/`
+
+### `navieo generate`
+
+Re-scan the codebase and update the existing sitemap, merging new routes with existing data.
+
+```bash
+navieo generate [--dir <path>]
+```
+
+### `navieo sync`
+
+Upload your sitemap and documentation to the Navieo backend.
+
+```bash
+navieo sync [--dir <path>] [--key <apiKey>] [--endpoint <url>]
+```
+
+## Configuration
+
+Create a `.navieorc` file in your project root:
+
+```json
+{
+  "apiKey": "your-api-key",
+  "endpoint": "https://api.navieo.io"
+}
+```
+
+Or set the `NAVIEO_API_KEY` environment variable.
+
+## Requirements
+
+- Node.js >= 18
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,880 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/index.ts
+var import_commander = require("commander");
+
+// src/commands/init.ts
+var import_fs5 = __toESM(require("fs"));
+var import_path4 = __toESM(require("path"));
+var import_picocolors = __toESM(require("picocolors"));
+
+// src/scanners/framework.ts
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+function detectFramework(projectRoot) {
+  const nextConfigExists = ["next.config.js", "next.config.mjs", "next.config.ts"].some(
+    (f) => import_fs.default.existsSync(import_path.default.join(projectRoot, f))
+  );
+  if (nextConfigExists) {
+    const hasAppDir = import_fs.default.existsSync(import_path.default.join(projectRoot, "app"));
+    const hasPagesDir = import_fs.default.existsSync(import_path.default.join(projectRoot, "pages"));
+    const hasSrcAppDir = import_fs.default.existsSync(import_path.default.join(projectRoot, "src", "app"));
+    const hasSrcPagesDir = import_fs.default.existsSync(import_path.default.join(projectRoot, "src", "pages"));
+    if (hasAppDir || hasSrcAppDir) {
+      return {
+        name: "nextjs-app",
+        appDir: hasSrcAppDir ? "src/app" : "app",
+        pagesDir: null,
+        componentsDir: resolveComponentsDir(projectRoot)
+      };
+    }
+    if (hasPagesDir || hasSrcPagesDir) {
+      return {
+        name: "nextjs-pages",
+        appDir: null,
+        pagesDir: hasSrcPagesDir ? "src/pages" : "pages",
+        componentsDir: resolveComponentsDir(projectRoot)
+      };
+    }
+    return {
+      name: "nextjs-app",
+      appDir: "app",
+      pagesDir: null,
+      componentsDir: resolveComponentsDir(projectRoot)
+    };
+  }
+  const viteConfigExists = ["vite.config.ts", "vite.config.js"].some(
+    (f) => import_fs.default.existsSync(import_path.default.join(projectRoot, f))
+  );
+  if (viteConfigExists) {
+    return {
+      name: "vite",
+      appDir: null,
+      pagesDir: null,
+      componentsDir: resolveComponentsDir(projectRoot)
+    };
+  }
+  return {
+    name: "unknown",
+    appDir: null,
+    pagesDir: null,
+    componentsDir: resolveComponentsDir(projectRoot)
+  };
+}
+function resolveComponentsDir(projectRoot) {
+  const candidates = [
+    "components",
+    "src/components",
+    "app/components",
+    "src/app/components"
+  ];
+  for (const candidate of candidates) {
+    if (import_fs.default.existsSync(import_path.default.join(projectRoot, candidate))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+// src/scanners/routes.ts
+var import_fs2 = __toESM(require("fs"));
+var import_path2 = __toESM(require("path"));
+var import_glob = require("glob");
+var import_parser = require("@babel/parser");
+var import_traverse = __toESM(require("@babel/traverse"));
+function scanRoutes(projectRoot, framework) {
+  if (framework.name === "nextjs-app" && framework.appDir) {
+    return scanNextjsAppRouter(projectRoot, framework.appDir);
+  }
+  if (framework.name === "nextjs-pages" && framework.pagesDir) {
+    return scanNextjsPagesRouter(projectRoot, framework.pagesDir);
+  }
+  return [];
+}
+function scanNextjsAppRouter(projectRoot, appDir) {
+  const absAppDir = import_path2.default.join(projectRoot, appDir);
+  const pageFiles = import_glob.glob.sync("**/page.{tsx,jsx,ts,js}", {
+    cwd: absAppDir,
+    ignore: ["**/node_modules/**"]
+  });
+  const routes = [];
+  const tsconfigPaths = loadTsconfigPaths(projectRoot);
+  for (const pageFile of pageFiles) {
+    const fullPagePath = import_path2.default.join(absAppDir, pageFile);
+    const routePath = filePathToRoute(pageFile);
+    if (routePath.startsWith("/api")) continue;
+    let code;
+    try {
+      code = import_fs2.default.readFileSync(fullPagePath, "utf-8");
+    } catch {
+      continue;
+    }
+    if (isRedirectOnly(code)) continue;
+    const title = extractTitle(code, routePath);
+    const importedFiles = resolveImports(code, fullPagePath, projectRoot, tsconfigPaths);
+    routes.push({
+      path: routePath,
+      filePath: fullPagePath,
+      title,
+      description: `${title} page`,
+      importedFiles
+    });
+  }
+  return routes.sort((a, b) => a.path.localeCompare(b.path));
+}
+function scanNextjsPagesRouter(projectRoot, pagesDir) {
+  const absPagesDir = import_path2.default.join(projectRoot, pagesDir);
+  const pageFiles = import_glob.glob.sync("**/*.{tsx,jsx,ts,js}", {
+    cwd: absPagesDir,
+    ignore: [
+      "**/node_modules/**",
+      "_app.*",
+      "_document.*",
+      "_error.*",
+      "api/**"
+    ]
+  });
+  const routes = [];
+  const tsconfigPaths = loadTsconfigPaths(projectRoot);
+  for (const pageFile of pageFiles) {
+    const fullPagePath = import_path2.default.join(absPagesDir, pageFile);
+    const routePath = pagesFilePathToRoute(pageFile);
+    let code;
+    try {
+      code = import_fs2.default.readFileSync(fullPagePath, "utf-8");
+    } catch {
+      continue;
+    }
+    const title = extractTitle(code, routePath);
+    const importedFiles = resolveImports(code, fullPagePath, projectRoot, tsconfigPaths);
+    routes.push({
+      path: routePath,
+      filePath: fullPagePath,
+      title,
+      description: `${title} page`,
+      importedFiles
+    });
+  }
+  return routes.sort((a, b) => a.path.localeCompare(b.path));
+}
+function filePathToRoute(filePath) {
+  let route = filePath.replace(/\/page\.(tsx|jsx|ts|js)$/, "").replace(/page\.(tsx|jsx|ts|js)$/, "");
+  route = route.replace(/\([^)]+\)\/?/g, "");
+  route = "/" + route.replace(/\/$/, "");
+  if (route === "/") return "/";
+  return route;
+}
+function pagesFilePathToRoute(filePath) {
+  let route = filePath.replace(/\.(tsx|jsx|ts|js)$/, "");
+  route = route.replace(/\/index$/, "").replace(/^index$/, "");
+  return "/" + route || "/";
+}
+function isRedirectOnly(code) {
+  const hasRedirectImport = /import\s+.*redirect.*from\s+['"]next\/navigation['"]/.test(code);
+  const hasRedirectCall = /\bredirect\s*\(/.test(code);
+  const hasMinimalJSX = (code.match(/<[A-Za-z]/g) || []).length <= 1;
+  return hasRedirectImport && hasRedirectCall && hasMinimalJSX;
+}
+function extractTitle(code, routePath) {
+  let ast;
+  try {
+    ast = (0, import_parser.parse)(code, {
+      sourceType: "module",
+      plugins: ["jsx", "typescript"],
+      errorRecovery: true
+    });
+  } catch {
+    return titleFromPath(routePath);
+  }
+  let foundTitle = null;
+  (0, import_traverse.default)(ast, {
+    // Look for: export const metadata = { title: "..." }
+    ExportNamedDeclaration(path7) {
+      const decl = path7.node.declaration;
+      if (decl?.type === "VariableDeclaration") {
+        for (const declarator of decl.declarations) {
+          if (declarator.id?.type === "Identifier" && declarator.id.name === "metadata" && declarator.init?.type === "ObjectExpression") {
+            for (const prop of declarator.init.properties) {
+              if (prop.type === "ObjectProperty" && prop.key?.type === "Identifier" && prop.key.name === "title" && prop.value?.type === "StringLiteral") {
+                foundTitle = prop.value.value;
+              }
+            }
+          }
+        }
+      }
+    },
+    // Look for: <h1>Title Text</h1> or <h2>Title Text</h2>
+    JSXOpeningElement(path7) {
+      if (foundTitle) return;
+      const node = path7.node;
+      if (node.name?.type !== "JSXIdentifier") return;
+      if (node.name.name !== "h1" && node.name.name !== "h2") return;
+      const parent = path7.parent;
+      if (parent?.type !== "JSXElement") return;
+      const textParts = [];
+      for (const child of parent.children || []) {
+        if (child.type === "JSXText") {
+          const trimmed = child.value.trim();
+          if (trimmed) textParts.push(trimmed);
+        }
+        if (child.type === "JSXExpressionContainer" && child.expression?.type === "StringLiteral") {
+          textParts.push(child.expression.value);
+        }
+      }
+      if (textParts.length > 0 && node.name.name === "h1") {
+        foundTitle = textParts.join(" ");
+      } else if (textParts.length > 0 && !foundTitle) {
+        foundTitle = textParts.join(" ");
+      }
+    }
+  });
+  return foundTitle || titleFromPath(routePath);
+}
+function titleFromPath(routePath) {
+  if (routePath === "/") return "Home";
+  const segments = routePath.split("/").filter(Boolean);
+  const last = segments[segments.length - 1];
+  if (last.startsWith("[") && last.endsWith("]")) {
+    const paramName = last.slice(1, -1);
+    return capitalize(paramName) + " Detail";
+  }
+  return capitalize(last);
+}
+function capitalize(s) {
+  return s.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+function resolveImports(code, sourceFilePath, projectRoot, tsconfigPaths) {
+  let ast;
+  try {
+    ast = (0, import_parser.parse)(code, {
+      sourceType: "module",
+      plugins: ["jsx", "typescript"],
+      errorRecovery: true
+    });
+  } catch {
+    return [];
+  }
+  const imports = [];
+  (0, import_traverse.default)(ast, {
+    ImportDeclaration(path7) {
+      const source = path7.node.source.value;
+      if (!source.startsWith(".") && !source.startsWith("@/") && !source.startsWith("~/")) {
+        return;
+      }
+      const resolved = resolveImportPath(source, sourceFilePath, projectRoot, tsconfigPaths);
+      if (resolved && import_fs2.default.existsSync(resolved)) {
+        imports.push(resolved);
+      }
+    }
+  });
+  return imports;
+}
+function resolveImportPath(importSource, sourceFilePath, projectRoot, tsconfigPaths) {
+  let resolvedBase;
+  if (importSource.startsWith("@/") || importSource.startsWith("~/")) {
+    const prefix = importSource.startsWith("@/") ? "@/*" : "~/*";
+    const mappings = tsconfigPaths[prefix];
+    if (!mappings || mappings.length === 0) {
+      resolvedBase = import_path2.default.join(projectRoot, importSource.slice(2));
+    } else {
+      const mappingBase = mappings[0].replace("*", "");
+      resolvedBase = import_path2.default.join(projectRoot, mappingBase, importSource.slice(2));
+    }
+  } else {
+    resolvedBase = import_path2.default.resolve(import_path2.default.dirname(sourceFilePath), importSource);
+  }
+  const extensions = [".tsx", ".ts", ".jsx", ".js"];
+  for (const ext of extensions) {
+    const candidate = resolvedBase + ext;
+    if (import_fs2.default.existsSync(candidate)) return candidate;
+  }
+  for (const ext of extensions) {
+    const candidate = import_path2.default.join(resolvedBase, "index" + ext);
+    if (import_fs2.default.existsSync(candidate)) return candidate;
+  }
+  if (import_fs2.default.existsSync(resolvedBase)) return resolvedBase;
+  return null;
+}
+function loadTsconfigPaths(projectRoot) {
+  const tsconfigPath = import_path2.default.join(projectRoot, "tsconfig.json");
+  if (!import_fs2.default.existsSync(tsconfigPath)) return {};
+  try {
+    const raw = import_fs2.default.readFileSync(tsconfigPath, "utf-8");
+    const stripped = raw.replace(/\/\/.*$/gm, "").replace(/\/\*[\s\S]*?\*\//g, "");
+    const config = JSON.parse(stripped);
+    return config.compilerOptions?.paths || {};
+  } catch {
+    return {};
+  }
+}
+
+// src/scanners/elements.ts
+var import_fs3 = __toESM(require("fs"));
+var import_parser2 = require("@babel/parser");
+var import_traverse2 = __toESM(require("@babel/traverse"));
+function scanElements(filePaths) {
+  const elementsMap = /* @__PURE__ */ new Map();
+  for (const filePath of filePaths) {
+    if (!import_fs3.default.existsSync(filePath)) continue;
+    let code;
+    try {
+      code = import_fs3.default.readFileSync(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+    const fileElements = extractElementsFromCode(code);
+    for (const el of fileElements) {
+      const existing = elementsMap.get(el.id);
+      if (!existing || selectorScore(el.selector) > selectorScore(existing.selector)) {
+        elementsMap.set(el.id, el);
+      }
+    }
+  }
+  return Array.from(elementsMap.values());
+}
+function extractElementsFromCode(code) {
+  const elements = [];
+  let ast;
+  try {
+    ast = (0, import_parser2.parse)(code, {
+      sourceType: "module",
+      plugins: ["jsx", "typescript"],
+      errorRecovery: true
+    });
+  } catch {
+    return elements;
+  }
+  (0, import_traverse2.default)(ast, {
+    JSXOpeningElement(path7) {
+      const node = path7.node;
+      const attrs = node.attributes;
+      const tag = getTagName(node);
+      if (!tag) return;
+      const testId = getStaticPropValue(attrs, "data-testid");
+      if (!testId) return;
+      const ariaLabel = getStaticPropValue(attrs, "aria-label");
+      const elType = mapTagToType(tag);
+      const text = ariaLabel || humanize(testId);
+      const cssSelector = buildCssSelector(tag, testId);
+      elements.push({
+        id: testId,
+        type: elType,
+        text,
+        selector: {
+          testId,
+          cssSelector,
+          ...ariaLabel ? { ariaLabel } : {}
+        },
+        description: `${humanize(testId)} ${elType}`
+      });
+    }
+  });
+  return elements;
+}
+function getTagName(node) {
+  if (node.name?.type === "JSXIdentifier") {
+    return node.name.name;
+  }
+  if (node.name?.type === "JSXMemberExpression") {
+    return `${node.name.object?.name || ""}.${node.name.property?.name || ""}`;
+  }
+  return null;
+}
+function getStaticPropValue(attrs, propName) {
+  for (const attr of attrs) {
+    if (attr.type !== "JSXAttribute") continue;
+    const attrName = attr.name?.type === "JSXIdentifier" ? attr.name.name : attr.name?.type === "JSXNamespacedName" ? `${attr.name.namespace?.name}:${attr.name.name?.name}` : null;
+    if (attrName !== propName) continue;
+    if (attr.value?.type === "StringLiteral") {
+      return attr.value.value;
+    }
+    if (attr.value?.type === "JSXExpressionContainer" && attr.value.expression?.type === "StringLiteral") {
+      return attr.value.expression.value;
+    }
+    return null;
+  }
+  return null;
+}
+function mapTagToType(tag) {
+  const lower = tag.toLowerCase();
+  if (lower === "button") return "button";
+  if (tag === "Link" || lower === "a") return "link";
+  if (lower === "input" || lower === "textarea") return "input";
+  if (lower === "select") return "select";
+  return "text";
+}
+function buildCssSelector(tag, testId) {
+  const htmlTag = tag === "Link" ? "a" : tag.toLowerCase();
+  const nonSpecificTags = ["div", "section", "span", "main", "nav", "header", "footer", "article", "aside"];
+  if (nonSpecificTags.includes(htmlTag) || htmlTag.includes(".")) {
+    return `[data-testid='${testId}']`;
+  }
+  return `${htmlTag}[data-testid='${testId}']`;
+}
+function humanize(testId) {
+  return testId.split(/[-_]/).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function selectorScore(selector) {
+  let score = 0;
+  if (selector.testId) score += 1;
+  if (selector.ariaLabel) score += 1;
+  if (selector.cssSelector) score += 1;
+  if (selector.text) score += 1;
+  return score;
+}
+
+// src/utils/config.ts
+var import_fs4 = __toESM(require("fs"));
+var import_path3 = __toESM(require("path"));
+var CONFIG_FILENAME = ".navieorc";
+var DEFAULT_ENDPOINT = "https://api.navieo.io";
+function loadConfig(projectRoot) {
+  let fileConfig = {};
+  const configPath = import_path3.default.join(projectRoot, CONFIG_FILENAME);
+  if (import_fs4.default.existsSync(configPath)) {
+    try {
+      const raw = import_fs4.default.readFileSync(configPath, "utf-8");
+      fileConfig = JSON.parse(raw);
+    } catch {
+    }
+  }
+  return {
+    apiKey: process.env.NAVIEO_API_KEY || fileConfig.apiKey,
+    endpoint: process.env.NAVIEO_ENDPOINT || fileConfig.endpoint || DEFAULT_ENDPOINT,
+    appId: fileConfig.appId
+  };
+}
+function saveConfig(projectRoot, config) {
+  const configPath = import_path3.default.join(projectRoot, CONFIG_FILENAME);
+  import_fs4.default.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+function resolveProjectRoot(startDir) {
+  let dir = startDir || process.cwd();
+  while (true) {
+    if (import_fs4.default.existsSync(import_path3.default.join(dir, "package.json"))) {
+      return dir;
+    }
+    const parent = import_path3.default.dirname(dir);
+    if (parent === dir) {
+      return startDir || process.cwd();
+    }
+    dir = parent;
+  }
+}
+
+// src/commands/init.ts
+var GETTING_STARTED_TEMPLATE = `# Getting Started
+
+## Overview
+Describe what your application does and its main features.
+
+## Navigation
+Explain how users navigate between the main sections of your app.
+`;
+async function initCommand(options) {
+  const projectRoot = resolveProjectRoot(import_path4.default.resolve(options.dir));
+  const navieoDir = import_path4.default.join(projectRoot, "navieo");
+  const docsDir = import_path4.default.join(navieoDir, "docs");
+  const sitemapPath = import_path4.default.join(navieoDir, "sitemap.navieo.json");
+  if (import_fs5.default.existsSync(navieoDir)) {
+    console.log(
+      import_picocolors.default.yellow("Warning:") + " navieo/ folder already exists. Use " + import_picocolors.default.cyan("navieo generate") + " to re-scan and update the existing sitemap."
+    );
+    return;
+  }
+  console.log(import_picocolors.default.bold("Initializing Navieo...\n"));
+  const framework = detectFramework(projectRoot);
+  console.log(import_picocolors.default.green("\u2713") + ` Detected framework: ${import_picocolors.default.cyan(framework.name)}`);
+  const routes = scanRoutes(projectRoot, framework);
+  console.log(import_picocolors.default.green("\u2713") + ` Found ${import_picocolors.default.cyan(String(routes.length))} routes`);
+  let totalElements = 0;
+  const sitemapRoutes = routes.map((route) => {
+    const filesToScan = [route.filePath, ...route.importedFiles];
+    const elements = scanElements(filesToScan);
+    totalElements += elements.length;
+    return {
+      path: route.path,
+      title: route.title,
+      description: route.description,
+      elements
+    };
+  });
+  console.log(import_picocolors.default.green("\u2713") + ` Found ${import_picocolors.default.cyan(String(totalElements))} interactive elements`);
+  const sitemap = {
+    appId: import_path4.default.basename(projectRoot),
+    framework: framework.name.replace("-app", "").replace("-pages", ""),
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    routes: sitemapRoutes,
+    flows: [],
+    docs: []
+  };
+  import_fs5.default.mkdirSync(navieoDir, { recursive: true });
+  import_fs5.default.writeFileSync(sitemapPath, JSON.stringify(sitemap, null, 2) + "\n", "utf-8");
+  console.log(import_picocolors.default.green("\u2713") + ` Generated ${import_picocolors.default.cyan("navieo/sitemap.navieo.json")}`);
+  import_fs5.default.mkdirSync(docsDir, { recursive: true });
+  const gettingStartedPath = import_path4.default.join(docsDir, "getting-started.md");
+  if (!import_fs5.default.existsSync(gettingStartedPath)) {
+    import_fs5.default.writeFileSync(gettingStartedPath, GETTING_STARTED_TEMPLATE, "utf-8");
+    console.log(import_picocolors.default.green("\u2713") + ` Created ${import_picocolors.default.cyan("navieo/docs/getting-started.md")}`);
+  }
+  const configPath = import_path4.default.join(projectRoot, ".navieorc");
+  if (!import_fs5.default.existsSync(configPath)) {
+    saveConfig(projectRoot, {
+      endpoint: "https://api.navieo.io",
+      appId: import_path4.default.basename(projectRoot)
+    });
+    console.log(import_picocolors.default.green("\u2713") + ` Created ${import_picocolors.default.cyan(".navieorc")}`);
+  }
+  console.log(
+    "\n" + import_picocolors.default.bold("Next steps:") + `
+  1. Review and adjust ${import_picocolors.default.cyan("navieo/sitemap.navieo.json")}
+  2. Write documentation in ${import_picocolors.default.cyan("navieo/docs/")}
+  3. Add your API key to ${import_picocolors.default.cyan(".navieorc")} or set ${import_picocolors.default.cyan("NAVIEO_API_KEY")} env var
+  4. Run: ${import_picocolors.default.cyan("navieo sync")}
+`
+  );
+}
+
+// src/commands/sync.ts
+var import_fs6 = __toESM(require("fs"));
+var import_path5 = __toESM(require("path"));
+var import_glob2 = require("glob");
+var import_picocolors2 = __toESM(require("picocolors"));
+
+// src/utils/markdown.ts
+function parseMarkdownDoc(relativePath, content) {
+  const lines = content.split("\n");
+  let title = "";
+  const sections = [];
+  let currentHeading = "";
+  let currentContent = [];
+  for (const line of lines) {
+    const h1Match = line.match(/^#\s+(.+)$/);
+    if (h1Match && !title) {
+      title = h1Match[1].trim();
+      continue;
+    }
+    const h2Match = line.match(/^##\s+(.+)$/);
+    if (h2Match) {
+      if (currentHeading) {
+        sections.push({
+          heading: currentHeading,
+          content: currentContent.join("\n").trim()
+        });
+      }
+      currentHeading = h2Match[1].trim();
+      currentContent = [];
+      continue;
+    }
+    if (currentHeading) {
+      currentContent.push(line);
+    }
+  }
+  if (currentHeading) {
+    sections.push({
+      heading: currentHeading,
+      content: currentContent.join("\n").trim()
+    });
+  }
+  if (sections.length === 0 && title) {
+    const afterTitle = content.replace(/^#\s+.+\n?/, "").trim();
+    if (afterTitle) {
+      sections.push({
+        heading: "Overview",
+        content: afterTitle
+      });
+    }
+  }
+  return {
+    path: relativePath,
+    title: title || relativePath.replace(/\.md$/, ""),
+    sections
+  };
+}
+
+// src/utils/api.ts
+async function syncToBackend(endpoint, apiKey, sitemap) {
+  const url = `${endpoint.replace(/\/$/, "")}/api/sitemap`;
+  if (!url.startsWith("https://") && !url.startsWith("http://localhost")) {
+    console.warn(
+      "WARNING: Syncing to a non-HTTPS endpoint. Your API key may be exposed in transit."
+    );
+  }
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey
+    },
+    body: JSON.stringify({ sitemap })
+  });
+  if (!response.ok) {
+    if (response.status === 401) {
+      return {
+        success: false,
+        error: "Invalid API key. Check your .navieorc or NAVIEO_API_KEY env var."
+      };
+    }
+    let errorMessage;
+    try {
+      const body2 = await response.json();
+      errorMessage = body2.error || `Server returned ${response.status}`;
+    } catch {
+      errorMessage = `Server returned ${response.status}: ${response.statusText}`;
+    }
+    return { success: false, error: errorMessage };
+  }
+  const body = await response.json();
+  return {
+    success: true,
+    appId: body.appId,
+    routeCount: body.routeCount,
+    docCount: body.docCount,
+    chunkCount: body.chunkCount,
+    embedded: body.embedded
+  };
+}
+
+// src/commands/sync.ts
+async function syncCommand(options) {
+  const projectRoot = resolveProjectRoot(import_path5.default.resolve(options.dir));
+  const navieoDir = import_path5.default.join(projectRoot, "navieo");
+  const sitemapPath = import_path5.default.join(navieoDir, "sitemap.navieo.json");
+  const config = loadConfig(projectRoot);
+  const apiKey = options.key || config.apiKey;
+  const endpoint = options.endpoint || config.endpoint || "https://api.navieo.io";
+  if (!apiKey) {
+    console.error(
+      import_picocolors2.default.red("Error:") + ` No API key found.
+  Set ${import_picocolors2.default.cyan("NAVIEO_API_KEY")} environment variable, or
+  Add ${import_picocolors2.default.cyan('"apiKey"')} to ${import_picocolors2.default.cyan(".navieorc")}, or
+  Use ${import_picocolors2.default.cyan("--key <apiKey>")} flag
+`
+    );
+    process.exit(1);
+  }
+  if (!import_fs6.default.existsSync(sitemapPath)) {
+    console.error(
+      import_picocolors2.default.red("Error:") + ` ${import_picocolors2.default.cyan("navieo/sitemap.navieo.json")} not found.
+  Run ${import_picocolors2.default.cyan("navieo init")} first to generate the sitemap.
+`
+    );
+    process.exit(1);
+  }
+  let sitemap;
+  try {
+    const raw = import_fs6.default.readFileSync(sitemapPath, "utf-8");
+    sitemap = JSON.parse(raw);
+  } catch (err) {
+    console.error(import_picocolors2.default.red("Error:") + " Failed to parse sitemap.navieo.json");
+    process.exit(1);
+  }
+  console.log(
+    import_picocolors2.default.green("\u2713") + ` Loaded sitemap: ${import_picocolors2.default.cyan(String(sitemap.routes?.length ?? 0))} routes, ${import_picocolors2.default.cyan(String(sitemap.flows?.length ?? 0))} flows`
+  );
+  const docsDir = import_path5.default.join(navieoDir, "docs");
+  if (import_fs6.default.existsSync(docsDir)) {
+    const mdFiles = import_glob2.glob.sync("*.md", { cwd: docsDir });
+    const parsedDocs = mdFiles.map((mdFile) => {
+      const content = import_fs6.default.readFileSync(import_path5.default.join(docsDir, mdFile), "utf-8");
+      return parseMarkdownDoc(`docs/${mdFile}`, content);
+    });
+    sitemap.docs = parsedDocs;
+    const totalSections = parsedDocs.reduce((sum, doc) => sum + doc.sections.length, 0);
+    console.log(
+      import_picocolors2.default.green("\u2713") + ` Loaded ${import_picocolors2.default.cyan(String(parsedDocs.length))} doc files (${import_picocolors2.default.cyan(String(totalSections))} sections)`
+    );
+  }
+  console.log(`
+Syncing to ${import_picocolors2.default.cyan(endpoint)}...`);
+  try {
+    const result = await syncToBackend(endpoint, apiKey, sitemap);
+    if (!result.success) {
+      console.error(import_picocolors2.default.red("Error:") + ` ${result.error}`);
+      process.exit(1);
+    }
+    console.log(
+      import_picocolors2.default.green("\u2713") + ` Synced successfully
+  Routes: ${import_picocolors2.default.cyan(String(result.routeCount))} | Docs: ${import_picocolors2.default.cyan(String(result.docCount))} | Chunks: ${import_picocolors2.default.cyan(String(result.chunkCount))} | Embedded: ${result.embedded ? import_picocolors2.default.green("true") : import_picocolors2.default.yellow("false")}
+`
+    );
+  } catch (err) {
+    if (err.cause?.code === "ECONNREFUSED") {
+      console.error(
+        import_picocolors2.default.red("Error:") + ` Could not connect to ${import_picocolors2.default.cyan(endpoint)}.
+  Is the backend running? Try: ${import_picocolors2.default.cyan("pnpm dev:backend")}
+`
+      );
+    } else {
+      console.error(import_picocolors2.default.red("Error:") + ` ${err.message || err}`);
+    }
+    process.exit(1);
+  }
+}
+
+// src/commands/generate.ts
+var import_fs7 = __toESM(require("fs"));
+var import_path6 = __toESM(require("path"));
+var import_picocolors3 = __toESM(require("picocolors"));
+async function generateCommand(options) {
+  const projectRoot = resolveProjectRoot(import_path6.default.resolve(options.dir));
+  const navieoDir = import_path6.default.join(projectRoot, "navieo");
+  const sitemapPath = import_path6.default.join(navieoDir, "sitemap.navieo.json");
+  console.log(import_picocolors3.default.bold("Re-scanning codebase...\n"));
+  let existingSitemap = null;
+  if (import_fs7.default.existsSync(sitemapPath)) {
+    try {
+      const raw = import_fs7.default.readFileSync(sitemapPath, "utf-8");
+      existingSitemap = JSON.parse(raw);
+    } catch {
+      console.log(import_picocolors3.default.yellow("Warning:") + " Could not parse existing sitemap. Starting fresh.");
+    }
+  }
+  const framework = detectFramework(projectRoot);
+  console.log(import_picocolors3.default.green("\u2713") + ` Detected framework: ${import_picocolors3.default.cyan(framework.name)}`);
+  const scannedRoutes = scanRoutes(projectRoot, framework);
+  console.log(import_picocolors3.default.green("\u2713") + ` Scanned ${import_picocolors3.default.cyan(String(scannedRoutes.length))} routes`);
+  const newRoutes = scannedRoutes.map((route) => {
+    const filesToScan = [route.filePath, ...route.importedFiles];
+    const elements = scanElements(filesToScan);
+    return {
+      path: route.path,
+      title: route.title,
+      description: route.description,
+      elements
+    };
+  });
+  let mergedRoutes;
+  let stats = { newRoutes: 0, updatedRoutes: 0, preservedRoutes: 0 };
+  if (existingSitemap) {
+    const result = mergeRoutes(existingSitemap.routes || [], newRoutes);
+    mergedRoutes = result.routes;
+    stats = result.stats;
+  } else {
+    mergedRoutes = newRoutes;
+    stats.newRoutes = newRoutes.length;
+  }
+  const sitemap = {
+    appId: existingSitemap?.appId || import_path6.default.basename(projectRoot),
+    framework: framework.name.replace("-app", "").replace("-pages", ""),
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    routes: mergedRoutes,
+    flows: existingSitemap?.flows || [],
+    docs: existingSitemap?.docs || []
+  };
+  import_fs7.default.mkdirSync(navieoDir, { recursive: true });
+  import_fs7.default.writeFileSync(sitemapPath, JSON.stringify(sitemap, null, 2) + "\n", "utf-8");
+  const totalElements = mergedRoutes.reduce((sum, r) => sum + (r.elements?.length || 0), 0);
+  console.log(
+    import_picocolors3.default.green("\u2713") + ` Found ${import_picocolors3.default.cyan(String(totalElements))} interactive elements`
+  );
+  console.log(
+    "\n" + import_picocolors3.default.green("\u2713") + " Updated " + import_picocolors3.default.cyan("navieo/sitemap.navieo.json") + `
+  New routes: ${import_picocolors3.default.cyan(String(stats.newRoutes))} | Updated: ${import_picocolors3.default.cyan(String(stats.updatedRoutes))} | Preserved: ${import_picocolors3.default.cyan(String(stats.preservedRoutes))}
+  Flows: ${import_picocolors3.default.cyan(String(sitemap.flows?.length ?? 0))} (preserved) | Docs: ${import_picocolors3.default.cyan(String(sitemap.docs?.length ?? 0))} (preserved)
+`
+  );
+}
+function mergeRoutes(oldRoutes, newRoutes) {
+  const oldRouteMap = new Map(oldRoutes.map((r) => [r.path, r]));
+  const newRouteMap = new Map(newRoutes.map((r) => [r.path, r]));
+  const mergedRoutes = [];
+  let newCount = 0;
+  let updatedCount = 0;
+  let preservedCount = 0;
+  for (const newRoute of newRoutes) {
+    const oldRoute = oldRouteMap.get(newRoute.path);
+    if (oldRoute) {
+      mergedRoutes.push({
+        path: newRoute.path,
+        title: oldRoute.title !== `${capitalize2(newRoute.path.split("/").pop() || "")} page` ? oldRoute.title : newRoute.title,
+        description: isPlaceholderDescription(oldRoute.description) ? newRoute.description : oldRoute.description,
+        elements: mergeElements(oldRoute.elements || [], newRoute.elements || [])
+      });
+      updatedCount++;
+    } else {
+      mergedRoutes.push(newRoute);
+      newCount++;
+    }
+  }
+  for (const oldRoute of oldRoutes) {
+    if (!newRouteMap.has(oldRoute.path)) {
+      mergedRoutes.push(oldRoute);
+      preservedCount++;
+    }
+  }
+  return {
+    routes: mergedRoutes.sort((a, b) => a.path.localeCompare(b.path)),
+    stats: { newRoutes: newCount, updatedRoutes: updatedCount, preservedRoutes: preservedCount }
+  };
+}
+function mergeElements(oldElements, newElements) {
+  const oldMap = new Map(oldElements.map((e) => [e.id, e]));
+  const newMap = new Map(newElements.map((e) => [e.id, e]));
+  const merged = [];
+  for (const newEl of newElements) {
+    const oldEl = oldMap.get(newEl.id);
+    if (oldEl) {
+      merged.push({
+        id: newEl.id,
+        type: newEl.type,
+        text: oldEl.text !== humanize2(oldEl.id) ? oldEl.text : newEl.text,
+        selector: newEl.selector,
+        // Source code is truth for selectors
+        description: isPlaceholderElementDescription(oldEl.description, oldEl.id) ? newEl.description : oldEl.description
+      });
+    } else {
+      merged.push(newEl);
+    }
+  }
+  for (const oldEl of oldElements) {
+    if (!newMap.has(oldEl.id)) {
+      merged.push(oldEl);
+    }
+  }
+  return merged;
+}
+function isPlaceholderDescription(desc) {
+  return /^\w[\w\s]+ page$/i.test(desc);
+}
+function isPlaceholderElementDescription(desc, id) {
+  const humanized = humanize2(id);
+  return desc === `${humanized} button` || desc === `${humanized} link` || desc === `${humanized} input` || desc === `${humanized} select` || desc === `${humanized} text`;
+}
+function humanize2(testId) {
+  return testId.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+function capitalize2(s) {
+  return s.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+
+// src/index.ts
+var program = new import_commander.Command();
+program.name("navieo").description("CLI for Navieo \u2014 scan, generate, and sync sitemaps").version("1.0.0");
+program.command("init").description("Scan codebase and generate initial sitemap + docs folder").option("-d, --dir <path>", "Project root directory", ".").action(initCommand);
+program.command("sync").description("Upload sitemap + docs to Navieo backend").option("-d, --dir <path>", "Project root directory", ".").option("-k, --key <apiKey>", "API key (overrides .navieorc and env)").option("-e, --endpoint <url>", "Backend URL (overrides .navieorc)").action(syncCommand);
+program.command("generate").description("Re-scan codebase and update existing sitemap").option("-d, --dir <path>", "Project root directory", ".").action(generateCommand);
+program.parse();

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@navieo/cli",
+  "version": "1.0.0",
+  "description": "CLI tool for Navieo — scan, generate, and sync sitemaps",
+  "bin": {
+    "navieo": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "tsup"
+  },
+  "dependencies": {
+    "commander": "^12",
+    "@babel/parser": "^7",
+    "@babel/traverse": "^7",
+    "picocolors": "^1",
+    "glob": "^11"
+  },
+  "devDependencies": {
+    "@navieo/types": "workspace:*",
+    "@babel/types": "^7",
+    "tsup": "^8",
+    "typescript": "^5",
+    "@types/node": "^20",
+    "@types/babel__traverse": "^7"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Navieo-org/navieo-sdk.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/Navieo-org/navieo-sdk/tree/main/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/Navieo-org/navieo-sdk/issues"
+  },
+  "keywords": ["navieo", "cli", "sitemap", "documentation", "onboarding", "product-tour"]
+}