@mauroandre/velojs 0.0.38 → 0.0.39

package/agent/skills/velojs-project-graph/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: velojs-project-graph
+description: "Use `.velojs/graph.json` to understand the project's route tree and module dependency graph before reading any source files. Always consult the graph first when exploring a VeloJS codebase. Generate it with `velojs graph` if missing."
+---
+
+# Project Graph
+
+VeloJS can generate a structural snapshot of your project — the route tree hierarchy, module dependency graph, and convention exports — as a single JSON file at `.velojs/graph.json`. This file gives an AI agent (or any tool) a complete map of the codebase in a few KB, replacing dozens of exploratory file reads.
+
+## When to use
+
+Always. Before reading any source file in a VeloJS project, check `.velojs/graph.json` first. It tells you:
+
+- **Route tree** — full hierarchy of layouts, pages, paths, `isRoot`, and middlewares
+- **Module dependencies** — for every module: what it imports (`imports`) and who imports it (`importedBy`)
+- **Convention exports** — which modules export `loader`, `action_*`, `stream_*`, `socket_*`
+
+## Generating the graph
+
+If `.velojs/graph.json` does not exist, generate it:
+
+```bash
+velojs graph
+```
+
+This runs a fast Babel-based crawl of `app/routes.tsx` and its transitive imports. No build. No Vite. Sub-second. Works even if the project does not compile.
+
+The graph is also regenerated automatically on every `velojs build` (via the `velo:graph` plugin) and on every file change during `velojs dev`.
+
+## Graph structure
+
+```typescript
+interface GraphJson {
+    routes: RouteTreeNode[];
+    modules: Record<string, ModuleInfo>;
+}
+
+interface RouteTreeNode {
+    moduleId: string | null;   // e.g. "pages/Home", null if no module
+    fullPath: string | null;   // e.g. "/admin/users/:id"
+    path: string | null;       // e.g. "/users/:id"
+    isRoot: boolean;           // root layout (renders <html>)
+    middlewares: string[];     // middleware identifiers
+    children: RouteTreeNode[];
+}
+
+interface ModuleInfo {
+    file: string;              // relative path from project root
+    kind: "root" | "layout" | "page" | "unknown";
+    exports: {
+        hasComponent: boolean;
+        hasLoader: boolean;
+        actions: string[];     // e.g. ["save", "delete"]
+        streams: string[];     // e.g. ["progress", "logs"]
+        sockets: string[];     // e.g. ["terminal"]
+    };
+    imports: string[];         // moduleIds this module depends on
+    importedBy: string[];      // moduleIds that depend on this module
+}
+```
+
+## Common queries
+
+### "Which routes use this loader?"
+
+1. Find the loader's module in `modules` → note its `moduleId`
+2. Search `routes` recursively for nodes where `moduleId` matches
+3. The matching node's ancestors are the layouts wrapping it
+
+### "What breaks if I change this file?"
+
+1. Find the module in `modules[moduleId]`
+2. Follow `importedBy` — these modules import it
+3. Transitively follow `importedBy` on those modules
+4. Filter to modules where `kind` is `"page"` to see which pages are affected
+
+### "What actions does this page expose?"
+
+1. Find the page in `modules[moduleId]`
+2. Read `exports.actions` — e.g. `["save", "delete"]`
+3. These are the `action_*` exports callable from the client
+
+### "Where is the auth middleware applied?"
+
+1. Search `routes` recursively for nodes where `middlewares` includes the auth middleware name
+2. The matching nodes and their children are protected
+
+### "Which modules have no tests?"
+
+Compare `modules` keys against the `tests/` directory. Modules with no corresponding test file are candidates for new tests.
+
+## Notes
+
+- External imports (`@mauroandre/velojs`, `preact`, `wouter-preact`) are recorded in `imports` but not crawled
+- `export function action_*` is NOT detected — only `export const action_*` (matches framework behavior)
+- Path-less layouts (no `path` property) have `fullPath: ""` and `path: ""`
+- The graph is regenerated on every build and on file changes during dev — never stale

package/dist/cli.js

@@ -1,43 +1,44 @@
-import { spawnSync as n } from "node:child_process";
-import { resolve as l } from "node:path";
-const i = process.argv.slice(2), c = i[0], d = (e, t = []) => {
-  const s = n(e, t, {
+import { spawnSync as a } from "node:child_process";
+import { join as n, resolve as u } from "node:path";
+import p from "node:fs";
+const r = process.argv.slice(2), c = r[0], v = (e, s = []) => {
+  const t = a(e, s, {
     stdio: "inherit",
     cwd: process.cwd()
   });
-  process.exit(s.status ?? 0);
-}, p = () => {
-  d("npx", ["vite", ...i.slice(1)]);
-}, u = (e) => {
-  const t = Date.now().toString(36), s = {
+  process.exit(t.status ?? 0);
+}, g = () => {
+  v("npx", ["vite", ...r.slice(1)]);
+}, h = (e) => {
+  const s = Date.now().toString(36), t = {
     ...process.env,
-    VELO_BUILD_HASH: t,
+    VELO_BUILD_HASH: s,
     ...e ? { VELO_STATIC: "1" } : {}
   };
   console.log("Building client...");
-  const o = n("npx", ["vite", "build"], {
+  const o = a("npx", ["vite", "build"], {
     stdio: "inherit",
     cwd: process.cwd(),
-    env: s
+    env: t
   });
   o.status !== 0 && (console.error("Client build failed. Aborting."), process.exit(o.status ?? 1)), console.log("Building server...");
-  const r = n("npx", ["vite", "build", "--mode", "server"], {
+  const i = a("npx", ["vite", "build", "--mode", "server"], {
     stdio: "inherit",
     cwd: process.cwd(),
-    env: s
+    env: t
   });
-  r.status !== 0 && (console.error("Server build failed. Aborting."), process.exit(r.status ?? 1)), console.log("Build complete!"), e && v();
-}, v = async () => {
+  i.status !== 0 && (console.error("Server build failed. Aborting."), process.exit(i.status ?? 1)), console.log("Build complete!"), e && w();
+}, w = async () => {
   process.env.NODE_ENV = "production", process.env.VELO_STATIC = "1";
-  const t = await import(l(process.cwd(), "dist/server.js")), s = t.default, o = t.routes;
-  (!s || !o) && (console.error("Failed to load app or routes from dist/server.js"), process.exit(1));
-  const { generateStatic: r } = await import("./static.js");
-  await r(s, o);
-}, m = () => {
+  const s = await import(u(process.cwd(), "dist/server.js")), t = s.default, o = s.routes;
+  (!t || !o) && (console.error("Failed to load app or routes from dist/server.js"), process.exit(1));
+  const { generateStatic: i } = await import("./static.js");
+  await i(t, o);
+}, b = () => {
   process.env.NODE_ENV = "production";
-  const e = l(process.cwd(), "dist/server.js");
-  d("node", [e]);
-}, a = () => {
+  const e = u(process.cwd(), "dist/server.js");
+  v("node", [e]);
+}, d = () => {
   console.log(`
 VeloJS CLI
 
@@ -50,6 +51,7 @@ Commands:
   build            Build for production (client + server)
   build --static   Build as static site (HTML + JSON)
   start            Start production server
+  graph [app-dir]   Generate .velojs/graph.json (route tree + dependency graph)
 
 Examples:
   velojs init my-app
@@ -57,30 +59,39 @@ Examples:
   velojs build
   velojs build --static
   velojs start
+  velojs graph
+  velojs graph src/app
 `);
 };
 switch (c) {
   case "init": {
     const { runInit: e } = await import("./init.js");
-    await e(i[1]);
+    await e(r[1]);
     break;
   }
   case "dev":
-    p();
+    g();
     break;
   case "build": {
-    const e = i.includes("--static");
-    u(e);
+    const e = r.includes("--static");
+    h(e);
     break;
   }
   case "start":
-    m();
+    b();
     break;
+  case "graph": {
+    const { buildGraph: e } = await import("./graph.js"), s = process.cwd(), t = r[1] && !r[1].startsWith("-") ? r[1] : null, o = n(s, t ?? "app"), i = e(o), l = n(s, ".velojs");
+    p.mkdirSync(l, { recursive: !0 });
+    const m = n(l, "graph.json");
+    p.writeFileSync(m, JSON.stringify(i, null, 2)), console.log("Graph written to .velojs/graph.json");
+    break;
+  }
   case "help":
   case "--help":
   case "-h":
-    a();
+    d();
     break;
   default:
-    c && console.error(`Unknown command: ${c}`), a(), process.exit(1);
+    c && console.error(`Unknown command: ${c}`), d(), process.exit(1);
 }

package/dist/graph.d.ts

@@ -0,0 +1,37 @@
+/**
+ * VeloJS Project Graph
+ *
+ * Builds a structural JSON snapshot of the project — route tree hierarchy,
+ * module dependency graph, and convention exports — from source code alone.
+ * No Vite, no dev server, no build. Used by `velojs graph` and by the
+ * `velo:graph` Vite plugin.
+ */
+export interface RouteTreeNode {
+    moduleId: string | null;
+    fullPath: string | null;
+    path: string | null;
+    isRoot: boolean;
+    middlewares: string[];
+    children: RouteTreeNode[];
+}
+export interface ModuleExports {
+    hasComponent: boolean;
+    hasLoader: boolean;
+    actions: string[];
+    streams: string[];
+    sockets: string[];
+}
+export interface ModuleInfo {
+    file: string;
+    kind: "root" | "layout" | "page" | "unknown";
+    exports: ModuleExports;
+    imports: string[];
+    importedBy: string[];
+}
+export interface GraphJson {
+    routes: RouteTreeNode[];
+    modules: Record<string, ModuleInfo>;
+}
+export declare function detectExports(filePath: string): ModuleExports;
+export declare function buildRouteTree(code: string): RouteTreeNode[];
+export declare function buildGraph(appDir: string): GraphJson;

package/dist/graph.js

@@ -0,0 +1,202 @@
+import y from "node:fs";
+import E from "node:path";
+import { parse as T } from "@babel/parser";
+import w from "@babel/traverse";
+import * as a from "@babel/types";
+const g = typeof w == "function" ? w : w.default, W = /export\s+(const|function)\s+Component/, _ = /export\s+(const|function)\s+loader/, b = /export\s+const\s+action_(\w+)/g, k = /export\s+const\s+stream_(\w+)/g, M = /export\s+const\s+socket_(\w+)/g;
+function A(i) {
+  let e;
+  try {
+    e = y.readFileSync(i, "utf-8");
+  } catch {
+    return {
+      hasComponent: !1,
+      hasLoader: !1,
+      actions: [],
+      streams: [],
+      sockets: []
+    };
+  }
+  const s = [];
+  let o;
+  const u = new RegExp(b.source, "g");
+  for (; (o = u.exec(e)) !== null; )
+    s.push(o[1]);
+  const t = [], c = new RegExp(k.source, "g");
+  for (; (o = c.exec(e)) !== null; )
+    t.push(o[1]);
+  const n = [], r = new RegExp(M.source, "g");
+  for (; (o = r.exec(e)) !== null; )
+    n.push(o[1]);
+  return {
+    hasComponent: W.test(e),
+    hasLoader: _.test(e),
+    actions: s,
+    streams: t,
+    sockets: n
+  };
+}
+function C(i) {
+  const e = T(i, {
+    sourceType: "module",
+    plugins: ["typescript", "jsx"]
+  }), s = /* @__PURE__ */ new Map();
+  g(e, {
+    ImportDeclaration(u) {
+      const t = u.node.source.value;
+      for (const c of u.node.specifiers)
+        a.isImportNamespaceSpecifier(c) && s.set(c.local.name, t);
+    }
+  });
+  let o = null;
+  return g(e, {
+    ExportDefaultDeclaration(u) {
+      const t = u.node.declaration;
+      a.isArrayExpression(t) ? o = t : (a.isTSSatisfiesExpression(t) || a.isTSAsExpression(t)) && a.isArrayExpression(t.expression) && (o = t.expression);
+    }
+  }), { imports: s, arrayNode: o };
+}
+function L(i, e) {
+  if (!i) return null;
+  const s = e.get(i);
+  return s ? s.replace(/^\.\//, "").replace(/\.(tsx?|jsx?|js)$/, "") : null;
+}
+function O(i, e, s) {
+  const o = [];
+  for (const u of i) {
+    if (!a.isObjectExpression(u)) continue;
+    let t = "", c = e, n = null, r = null, d = !1;
+    const x = [], m = u.properties.filter(
+      (l) => a.isObjectProperty(l)
+    );
+    for (const l of m) {
+      const j = l.key, I = a.isIdentifier(j) ? j.name : null;
+      if (I === "path" && a.isStringLiteral(l.value) && (t = l.value.value, t && !t.startsWith("/") ? c = e + "/" + t : c = e + t), I === "module" && a.isIdentifier(l.value) && (n = l.value.name), I === "children" && a.isArrayExpression(l.value) && (r = l.value), I === "isRoot" && a.isBooleanLiteral(l.value) && (d = l.value.value), I === "middlewares" && a.isArrayExpression(l.value))
+        for (const R of l.value.elements)
+          R && a.isIdentifier(R) && x.push(R.name);
+    }
+    const f = L(n, s), h = !r && t === "/" ? e || "/" : c, p = r ? O(r.elements, c, s) : [];
+    o.push({
+      moduleId: f,
+      fullPath: f ? h : null,
+      path: f ? t : null,
+      isRoot: d,
+      middlewares: x,
+      children: p
+    });
+  }
+  return o;
+}
+function D(i) {
+  const { imports: e, arrayNode: s } = C(i);
+  return s ? O(s.elements, "", e) : [];
+}
+const S = [".tsx", ".ts", ".jsx", ".js"];
+function F(i, e, s) {
+  if (e.startsWith(".") && (e.endsWith(".js") || e.endsWith(".jsx") || e.endsWith(".ts") || e.endsWith(".tsx"))) {
+    const o = E.dirname(i), t = E.resolve(o, e).replace(/\.(tsx?|jsx?|js)$/, "");
+    for (const n of S) {
+      const r = t + n;
+      if (y.existsSync(r)) return r;
+    }
+    const c = [t];
+    for (const n of c)
+      if (y.existsSync(n) && y.statSync(n).isDirectory())
+        for (const r of S) {
+          const d = E.join(n, "index" + r);
+          if (y.existsSync(d)) return d;
+        }
+    return null;
+  }
+  return null;
+}
+function N(i, e) {
+  const s = E.relative(e, i);
+  return s.startsWith("..") ? null : s.replace(/\.(tsx?|jsx?|js)$/, "");
+}
+function B(i, e) {
+  const s = /* @__PURE__ */ new Map(), o = /* @__PURE__ */ new Set();
+  function u(t) {
+    if (o.has(t)) return;
+    o.add(t);
+    const c = N(t, e);
+    if (!c) return;
+    let n;
+    try {
+      n = y.readFileSync(t, "utf-8");
+    } catch {
+      return;
+    }
+    const r = [], d = T(n, {
+      sourceType: "module",
+      plugins: ["typescript", "jsx"]
+    });
+    g(d, {
+      ImportDeclaration(x) {
+        const m = x.node.source.value;
+        if (m.startsWith(".")) {
+          const f = F(
+            t,
+            m
+          );
+          if (f) {
+            const v = N(
+              f,
+              e
+            );
+            v && (r.push(v), u(f));
+          }
+        } else
+          r.push(m);
+      }
+    }), s.set(c, { file: t, imports: r });
+  }
+  return u(i), { modules: s };
+}
+function q(i) {
+  const e = E.join(i, "routes.tsx");
+  let s;
+  try {
+    s = y.readFileSync(e, "utf-8");
+  } catch {
+    return { routes: [], modules: {} };
+  }
+  const o = D(s), { modules: u } = B(
+    e,
+    i
+  ), t = {}, c = /* @__PURE__ */ new Map();
+  for (const [n, r] of u) {
+    let d = "unknown";
+    const x = (h) => {
+      for (const p of h) {
+        if (p.moduleId === n)
+          return p.isRoot ? "root" : p.children.length > 0 ? "layout" : "page";
+        const l = x(p.children);
+        if (l) return l;
+      }
+      return null;
+    }, m = x(o);
+    m && (d = m);
+    const f = r.file, v = A(f);
+    for (const h of r.imports) {
+      c.has(h) || c.set(h, []);
+      const p = c.get(h);
+      p.includes(n) || p.push(n);
+    }
+    t[n] = {
+      file: E.relative(process.cwd(), f),
+      kind: d,
+      exports: v,
+      imports: r.imports,
+      importedBy: []
+    };
+  }
+  for (const [n, r] of Object.entries(t))
+    r.importedBy = c.get(n) ?? [];
+  return { routes: o, modules: t };
+}
+export {
+  q as buildGraph,
+  D as buildRouteTree,
+  A as detectExports
+};

package/dist/init.js

@@ -7,6 +7,15 @@ function m() {
   return JSON.parse(t.readFileSync(e, "utf-8")).version;
 }
 const u = {
+  ".gitignore": `# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Project graph
+.velojs/
+`,
   "package.json": `{
     "name": "my-velojs-app",
     "version": "0.1.0",
@@ -139,22 +148,22 @@ a:hover {
 `
 };
 async function x(o) {
-  const e = o ? s.resolve(process.cwd(), o) : process.cwd(), r = s.basename(e);
+  const e = o ? s.resolve(process.cwd(), o) : process.cwd(), n = s.basename(e);
   t.existsSync(e) ? t.readdirSync(e).filter(
-    (n) => !n.startsWith(".") && n !== "node_modules"
+    (r) => !r.startsWith(".") && r !== "node_modules"
   ).length > 0 && (console.error(
-    `Error: Directory "${r}" is not empty. Use an empty directory.`
+    `Error: Directory "${n}" is not empty. Use an empty directory.`
   ), process.exit(1)) : t.mkdirSync(e, { recursive: !0 });
-  for (const [a, n] of Object.entries(u)) {
+  for (const [a, r] of Object.entries(u)) {
     const p = s.join(e, a), l = s.dirname(p);
     t.existsSync(l) || t.mkdirSync(l, { recursive: !0 });
-    const c = a === "package.json" ? n.replace("my-velojs-app", r) : n;
+    const c = a === "package.json" ? r.replace("my-velojs-app", n) : r;
     t.writeFileSync(p, c);
   }
   console.log(`
-Project created in ${o ? r : "current directory"}!
+Project created in ${o ? n : "current directory"}!
 `), console.log(`Next steps:
-`), o && console.log(`  cd ${r}`), console.log("  npm install"), console.log(`  npx velojs dev
+`), o && console.log(`  cd ${n}`), console.log("  npm install"), console.log(`  npx velojs dev
 `);
 }
 export {