@graph8/sdk 0.358.0 → 0.362.0

package/dist/cli.js

@@ -36,8 +36,8 @@ __export(cli_exports, {
 });
 module.exports = __toCommonJS(cli_exports);
 var import_node_child_process = require("child_process");
-var import_node_fs5 = __toESM(require("fs"));
-var import_node_path5 = __toESM(require("path"));
+var import_node_fs6 = __toESM(require("fs"));
+var import_node_path6 = __toESM(require("path"));
 
 // src/agentSetup.ts
 var ALL_TARGETS = ["claude", "codex", "cursor"];
@@ -119,9 +119,9 @@ ${section}
 }
 function planAgentSetup(targets, read, catalog) {
   const plans = [];
-  const add = (target, path6, next) => {
-    const current = read(path6);
-    plans.push({ target, path: path6, content: next, action: current === null ? "create" : current === next ? "unchanged" : "update" });
+  const add = (target, path7, next) => {
+    const current = read(path7);
+    plans.push({ target, path: path7, content: next, action: current === null ? "create" : current === next ? "unchanged" : "update" });
   };
   for (const target of targets) {
     if (target === "claude") add(target, ".claude/skills/graph8-sdk/SKILL.md", claudeSkill(catalog));
@@ -158,7 +158,7 @@ var import_node_fs2 = __toESM(require("fs"));
 var import_node_path2 = __toESM(require("path"));
 
 // src/version.ts
-var SDK_VERSION = "0.358.0";
+var SDK_VERSION = "0.362.0";
 var SDK_CLIENT_ID = `js-sdk/${SDK_VERSION}`;
 
 // src/blocks/registry.ts
@@ -220,11 +220,12 @@ function loadRegistry(blocksRoot) {
         summary: typeof raw.summary === "string" ? raw.summary : "",
         status: raw.status === "planned" ? "planned" : "available",
         blocks: arr(raw.blocks),
-        nav: arr(raw.nav)
+        nav: arr(raw.nav),
+        ...typeof raw.home === "string" ? { home: raw.home } : {}
       });
     }
   }
-  return { blocks, stacks };
+  return { blocks, stacks, stacksRoot: stacksDir };
 }
 function findBlock(reg, id) {
   return reg.blocks.find((b) => b.id === id);
@@ -262,8 +263,19 @@ function searchStacks(reg, text) {
   if (!needle) return [];
   return reg.stacks.filter((s) => [s.id, s.title, s.summary].some((x) => x.toLowerCase().includes(needle)));
 }
+function screenNames(b) {
+  return b.components.map((c) => c.name).filter((n) => n.endsWith("Screen"));
+}
 function blockSummary(b) {
-  return { id: b.id, title: b.title, summary: b.summary, dependsOn: b.dependsOn, components: b.components.map((c) => c.name) };
+  const screens = screenNames(b);
+  return {
+    id: b.id,
+    title: b.title,
+    summary: b.summary,
+    dependsOn: b.dependsOn,
+    components: b.components.map((c) => c.name),
+    ...screens.length ? { screens } : {}
+  };
 }
 function stackStatus(reg, s) {
   const missing = s.blocks.filter((id) => !findBlock(reg, id));
@@ -280,7 +292,8 @@ function catalogSection(reg) {
   const lines = ["### graph8 blocks", "", "Ready-made, copy-in UI + hooks per graph8 feature. Pick from this list instead of reading every README:", ""];
   for (const b of reg.blocks) {
     const deps = b.dependsOn.length ? ` (needs ${b.dependsOn.join(", ")})` : "";
-    lines.push(`- block \`${b.id}\`: ${b.summary}${deps}`);
+    const screens = screenNames(b);
+    lines.push(`- block \`${b.id}\`: ${b.summary}${deps}${screens.length ? ` Screens (start here): ${screens.join(", ")}.` : ""}`);
   }
   for (const s of reg.stacks) {
     const { missing } = stackStatus(reg, s);
@@ -715,6 +728,8 @@ function stackProblem(reg, stack) {
     ].join("\n");
   }
   const seen = /* @__PURE__ */ new Set();
+  const homeIssue = homeProblem(stack);
+  if (homeIssue) return homeIssue;
   for (const n of stack.nav) {
     const block = findBlock(reg, n.block);
     if (!stack.blocks.includes(n.block)) return `stack "${stack.id}" nav "${n.label}" uses block "${n.block}" which the stack does not include.`;
@@ -722,31 +737,77 @@ function stackProblem(reg, stack) {
     if (/[\[\]]/.test(n.path)) return `stack "${stack.id}" nav "${n.label}" uses ${n.path}: dynamic segments cannot be a sidebar link.`;
     if (seen.has(n.path)) return `stack "${stack.id}" has two nav entries at ${n.path}.`;
     seen.add(n.path);
+    if (n.page && (!reg.stacksRoot || !import_node_fs3.default.existsSync(import_node_path3.default.join(reg.stacksRoot, stack.id, n.page)))) {
+      return `stack "${stack.id}" nav "${n.label}" uses page ${n.page}, which does not exist under stacks/${stack.id}/.`;
+    }
   }
   return null;
 }
+function homeProblem(stack) {
+  if (!stack.home) return null;
+  if (!stack.nav.some((n) => n.path === stack.home)) return `stack "${stack.id}" has home ${stack.home}, which is not one of its nav paths.`;
+  if (stack.home !== "/" && stack.nav.some((n) => n.path === "/")) return `stack "${stack.id}" has home ${stack.home} but also a nav entry at "/": drop one.`;
+  return null;
+}
+function stackPageFile(reg, stack, n) {
+  return n.page && reg.stacksRoot ? import_node_path3.default.join(reg.stacksRoot, stack.id, n.page) : null;
+}
+function homeRedirect(stack) {
+  if (stack.home) return stack.home === "/" ? null : stack.home;
+  return stack.nav.length && !stack.nav.some((n) => n.path === "/") ? stack.nav[0].path : null;
+}
 function renderPages(reg, stack, templates) {
   const pageTpl = import_node_fs3.default.readFileSync(import_node_path3.default.join(templates, "_pages", "route-page.tsx.tmpl"), "utf8");
   const files = stack.nav.map((n) => {
     const block = findBlock(reg, n.block);
     const comp = block.components.find((c) => c.name === n.component);
-    const content = render(pageTpl, {
+    const custom = stackPageFile(reg, stack, n);
+    const vars = {
       stackId: stack.id,
       block: block.id,
       blockDir: `components/g8/${block.dir}`,
       component: n.component,
       importPath: componentImportPath(block, comp.file),
       propsJson: JSON.stringify(n.props ?? {}, null, 2)
-    });
-    return { rel: pageFileFor(n.path), content };
+    };
+    return { rel: pageFileFor(n.path), content: render(custom ? import_node_fs3.default.readFileSync(custom, "utf8") : pageTpl, vars) };
   });
-  if (stack.nav.length && !stack.nav.some((n) => n.path === "/")) {
+  const to = homeRedirect(stack);
+  if (to) {
     const redirect = import_node_fs3.default.readFileSync(import_node_path3.default.join(templates, "_pages", "redirect-page.tsx.tmpl"), "utf8");
-    files.push({ rel: "app/page.tsx", content: render(redirect, { firstPathJson: JSON.stringify(stack.nav[0].path) }) });
+    files.push({ rel: "app/page.tsx", content: render(redirect, { firstPathJson: JSON.stringify(to) }) });
   }
   return files;
 }
-function peerDependenciesFor(blocks, io) {
+function navUsesExtras(stack) {
+  return stack.nav.some((n) => n.icon || n.group || n.description);
+}
+function navParts(stack) {
+  if (!navUsesExtras(stack)) {
+    return { navImports: "", navType: "{ label: string; path: string }[]", navJson: JSON.stringify(stack.nav.map((n) => ({ label: n.label, path: n.path })), null, 2) };
+  }
+  const icons = [...new Set(stack.nav.flatMap((n) => n.icon ? [n.icon] : []))].sort();
+  const named = [...icons, "type LucideIcon"].join(", ");
+  const items = stack.nav.map((n) => ({
+    label: n.label,
+    path: n.path,
+    ...n.icon ? { icon: `__ICON__${n.icon}` } : {},
+    ...n.group ? { group: n.group } : {},
+    ...n.description ? { description: n.description } : {}
+  }));
+  return {
+    navImports: [
+      `import { ${named} } from "lucide-react";`,
+      "",
+      "export type NavItem = { label: string; path: string; icon?: LucideIcon; group?: string; description?: string };",
+      "",
+      ""
+    ].join("\n"),
+    navType: "NavItem[]",
+    navJson: JSON.stringify(items, null, 2).replace(/"__ICON__(\w+)"/g, "$1")
+  };
+}
+function peerDependenciesFor(blocks, io, stack) {
   const peers = {};
   for (const b of blocks) for (const [name, range] of Object.entries(b.peerDependencies)) peers[name] ??= range;
   const usesUi = blocks.some((b) => walk(b.root).some((f) => /\.(tsx?|jsx?)$/.test(f) && /["']@graph8\/sdk\/ui["'/]/.test(import_node_fs3.default.readFileSync(import_node_path3.default.join(b.root, f), "utf8"))));
@@ -754,8 +815,17 @@ function peerDependenciesFor(blocks, io) {
     const sdk = JSON.parse(import_node_fs3.default.readFileSync(io.sdkPackageJson, "utf8"));
     for (const [name, range] of Object.entries(sdk.peerDependencies ?? {})) peers[name] ??= range;
   }
+  if (navUsesExtras(stack)) peers["lucide-react"] ??= lucideRange(io);
   return peers;
 }
+function lucideRange(io) {
+  try {
+    const sdk = JSON.parse(import_node_fs3.default.readFileSync(io.sdkPackageJson ?? "", "utf8"));
+    return sdk.peerDependencies?.["lucide-react"] ?? ">=0.400.0";
+  } catch {
+    return ">=0.400.0";
+  }
+}
 function mergedPackageJson(rendered, peers) {
   const pkg = JSON.parse(rendered);
   for (const [name, range] of Object.entries(peers)) pkg.dependencies[name] ??= range;
@@ -773,14 +843,14 @@ function planCreate(reg, stack, appName, pm, io) {
     stackId: stack.id,
     title: stack.title,
     titleJson: JSON.stringify(stack.title),
-    navJson: JSON.stringify(stack.nav.map((n) => ({ label: n.label, path: n.path })), null, 2),
+    ...navParts(stack),
     devCommand,
     screens: stack.nav.map((n) => `- ${n.label}: \`${n.path}\` (${n.block} block, \`${n.component}\`)`).join("\n") || "- (none yet: add a block with `npx @graph8/sdk add <block>`)"
   };
   const files = [];
   for (const rel of walk(templates).filter((f) => !f.startsWith("_pages/"))) {
     let content = render(import_node_fs3.default.readFileSync(import_node_path3.default.join(templates, rel), "utf8"), vars);
-    if (rel === "package.json.tmpl") content = mergedPackageJson(content, peerDependenciesFor(blocks, io));
+    if (rel === "package.json.tmpl") content = mergedPackageJson(content, peerDependenciesFor(blocks, io, stack));
     files.push({ rel: outputName(rel), content });
   }
   files.push(...renderPages(reg, stack, templates));
@@ -859,8 +929,8 @@ function finish(opts, reg, stack, blocks, abs, pm, io, cwd) {
 }
 
 // src/blocks/doctor.ts
-var import_node_fs4 = __toESM(require("fs"));
-var import_node_path4 = __toESM(require("path"));
+var import_node_fs5 = __toESM(require("fs"));
+var import_node_path5 = __toESM(require("path"));
 
 // src/generated/billable.ts
 var BILLABLE_ROUTES = {
@@ -1680,7 +1750,7 @@ function warnIfTargetOrgIgnored(apiKey, headers) {
     );
   }
 }
-async function request(baseUrl, path6, apiKey, opts = {}) {
+async function request(baseUrl, path7, apiKey, opts = {}) {
   const {
     method = "GET",
     body,
@@ -1693,7 +1763,7 @@ async function request(baseUrl, path6, apiKey, opts = {}) {
     fetchImpl = fetch,
     sleepImpl = defaultSleep
   } = opts;
-  const url = baseUrl.replace(/\/+$/, "") + path6 + buildQuery(query);
+  const url = baseUrl.replace(/\/+$/, "") + path7 + buildQuery(query);
   const finalHeaders = {
     "Content-Type": "application/json",
     Authorization: `Bearer ${apiKey}`,
@@ -5173,14 +5243,89 @@ function createApiClient(apiKey, apiUrl) {
   return client;
 }
 
+// src/blocks/flows.ts
+var import_node_fs4 = __toESM(require("fs"));
+var import_node_path4 = __toESM(require("path"));
+var IMPORT_RE2 = /(?:^|\n)\s*(?:import|export)\s[^'"`;]*?from\s*["']([^"']+)["']|(?:^|\n)\s*import\s*["']([^"']+)["']|import\(\s*["']([^"']+)["']\s*\)/g;
+var EXTENSIONS = ["", ".tsx", ".ts", "/index.tsx", "/index.ts"];
+function specifiers(source) {
+  return [...source.matchAll(IMPORT_RE2)].map((m) => m[1] ?? m[2] ?? m[3]);
+}
+function resolveFile(base) {
+  for (const ext of EXTENSIONS) {
+    const candidate = base + ext;
+    if (import_node_fs4.default.existsSync(candidate) && import_node_fs4.default.statSync(candidate).isFile()) return candidate;
+  }
+  return null;
+}
+function resolveImport(spec, from, reg) {
+  if (spec.startsWith(".")) return resolveFile(import_node_path4.default.resolve(import_node_path4.default.dirname(from), spec));
+  const g8 = /^@\/g8\/([^/]+)\/(.+)$/.exec(spec);
+  if (!g8) return null;
+  const owner = findBlock(reg, g8[1]);
+  if (owner) return resolveFile(import_node_path4.default.join(owner.root, "components", g8[2])) ?? resolveFile(import_node_path4.default.join(owner.root, g8[2]));
+  const foundation = findBlock(reg, "foundation");
+  return foundation ? resolveFile(import_node_path4.default.join(foundation.root, g8[1], g8[2])) : null;
+}
+function resolveInstalled(spec, reg) {
+  const m = /^@\/components\/g8\/([^/]+)\/(.+)$/.exec(spec);
+  const block = m && reg.blocks.find((b) => b.dir === m[1]);
+  if (!m || !block) return null;
+  const files = [...block.components, ...block.hooks, ...block.lib].map((x) => x.file);
+  const hit = files.find((f) => (installedRel(f) ?? f).replace(/\.(tsx|ts|jsx|js)$/, "") === m[2]);
+  return hit ? import_node_path4.default.join(block.root, hit) : null;
+}
+function seeds(reg, stack) {
+  const out = [];
+  for (const n of stack.nav) {
+    const comp = findBlock(reg, n.block)?.components.find((c) => c.name === n.component);
+    const block = findBlock(reg, n.block);
+    if (!block || !comp) continue;
+    const pageFile = n.page && reg.stacksRoot ? import_node_path4.default.join(reg.stacksRoot, stack.id, n.page) : null;
+    if (!pageFile || !import_node_fs4.default.existsSync(pageFile)) {
+      out.push(import_node_path4.default.join(block.root, comp.file));
+      continue;
+    }
+    const source = import_node_fs4.default.readFileSync(pageFile, "utf8");
+    if (source.includes("{{importPath}}")) out.push(import_node_path4.default.join(block.root, comp.file));
+    for (const spec of specifiers(source)) {
+      const hit = resolveInstalled(spec, reg);
+      if (hit) out.push(hit);
+    }
+  }
+  return out;
+}
+function reachedFiles(reg, stack) {
+  const seen = /* @__PURE__ */ new Set();
+  const queue = seeds(reg, stack);
+  while (queue.length) {
+    const file = queue.pop();
+    if (seen.has(file)) continue;
+    seen.add(file);
+    if (!/\.(tsx?|jsx?)$/.test(file)) continue;
+    for (const spec of specifiers(import_node_fs4.default.readFileSync(file, "utf8"))) {
+      const next = resolveImport(spec, file, reg);
+      if (next && !seen.has(next)) queue.push(next);
+    }
+  }
+  return seen;
+}
+function unreachedComponents(reg, stack) {
+  const reached = reachedFiles(reg, stack);
+  const blocks = resolveWithDeps(reg, stack.blocks).filter((b) => b.id !== "foundation" && stack.blocks.includes(b.id));
+  return blocks.flatMap((b) => b.components.filter((c) => !reached.has(import_node_path4.default.join(b.root, c.file))).map((c) => ({ block: b.id, component: c.name })));
+}
+
 // src/blocks/doctor.ts
-var DOCTOR_USAGE = `Usage: npx @graph8/sdk doctor [--stack <id>] [--blocks a,b] [--dir <path>]
+var DOCTOR_USAGE = `Usage: npx @graph8/sdk doctor [--stack <id>] [--blocks a,b] [--dir <path>] [--strict]
 
 Check that this project is ready for graph8 blocks:
   - G8_API_KEY (env or .env.local) is valid
   - the key's scopes cover the blocks you chose
   - the organization's subscription is active
   - a checklist of in-app setup each block needs
+With --stack it also lists "Flows": block components that no page of the stack reaches
+(a warning; --strict makes them fail the run).
 With no --stack/--blocks, the blocks recorded in graph8.json are checked.
 Optional G8_API_URL points at a non-default API. Exit code 0 when all checks
 pass, 1 otherwise.`;
@@ -5200,6 +5345,7 @@ ${DOCTOR_USAGE}`);
     if (flag === "--stack") o.stack = value();
     else if (flag === "--blocks") o.blocks.push(...value().split(",").map((s) => s.trim()).filter(Boolean));
     else if (flag === "--dir") o.dir = value();
+    else if (arg === "--strict") o.strict = true;
     else throw new Error(`unknown option ${arg}
 
 ${DOCTOR_USAGE}`);
@@ -5218,9 +5364,9 @@ function parseEnvFile(text) {
 function readSetting(name, root, env) {
   if (env[name]) return env[name];
   for (const f of [".env.local"]) {
-    const file = import_node_path4.default.join(root, f);
-    if (import_node_fs4.default.existsSync(file)) {
-      const v = parseEnvFile(import_node_fs4.default.readFileSync(file, "utf8"))[name];
+    const file = import_node_path5.default.join(root, f);
+    if (import_node_fs5.default.existsSync(file)) {
+      const v = parseEnvFile(import_node_fs5.default.readFileSync(file, "utf8"))[name];
       if (v) return v;
     }
   }
@@ -5241,7 +5387,7 @@ function selectBlocks(opts, reg, root) {
   }
   if (!ids.length) {
     try {
-      const ledger = JSON.parse(import_node_fs4.default.readFileSync(import_node_path4.default.join(root, "graph8.json"), "utf8"));
+      const ledger = JSON.parse(import_node_fs5.default.readFileSync(import_node_path5.default.join(root, "graph8.json"), "utf8"));
       ids = Object.keys(ledger.blocks ?? {});
     } catch {
       ids = [];
@@ -5255,7 +5401,7 @@ function errorText(e, key) {
   return `${status ? `HTTP ${status}: ` : ""}${msg}`.split(key).join("[redacted]");
 }
 async function runDoctor(opts, reg, io, cwd) {
-  const root = import_node_path4.default.resolve(cwd, opts.dir);
+  const root = import_node_path5.default.resolve(cwd, opts.dir);
   let blocks;
   try {
     blocks = selectBlocks(opts, reg, root);
@@ -5281,6 +5427,7 @@ async function runDoctor(opts, reg, io, cwd) {
     await checkKey(call, blocks, key, line);
     await checkSubscription(call, key, line);
   }
+  if (opts.stack) printFlows(opts, reg, io.out, line);
   printChecklist(blocks, io.out);
   io.out(failed ? "\nSome checks failed." : "\nAll checks passed.");
   return failed ? 1 : 0;
@@ -5318,6 +5465,18 @@ async function checkSubscription(call, key, line) {
     else line(false, `could not read subscription status (${errorText(e, key)})`);
   }
 }
+function printFlows(opts, reg, out, line) {
+  const stack = reg.stacks.find((s) => s.id === opts.stack);
+  if (!stack) return;
+  const missing = unreachedComponents(reg, stack);
+  out("\nFlows (block components a page of this stack reaches):");
+  if (!missing.length) return line(true, "every component of the stack's blocks is reachable from a page");
+  for (const m of missing) {
+    const text = `(${m.block}) ${m.component} is not reached by any page of "${stack.id}": wire it into a page or a Screen slot`;
+    if (opts.strict) line(false, text);
+    else out(`warn  ${text}`);
+  }
+}
 function printChecklist(blocks, out) {
   const items = blocks.flatMap((b) => b.prerequisites.filter((p) => p.where === "app").map((p) => ({ block: b.id, p })));
   if (!items.length) return;
@@ -5349,7 +5508,7 @@ Run a command with --help for its options.
 
 ${INIT_AGENT_USAGE}`;
 function registryFor(io) {
-  const root = io.blocksRoot ?? process.env.G8_BLOCKS_DIR ?? import_node_path5.default.resolve(__dirname, "..", "blocks");
+  const root = io.blocksRoot ?? process.env.G8_BLOCKS_DIR ?? import_node_path6.default.resolve(__dirname, "..", "blocks");
   return loadRegistry(root);
 }
 function defaultSpawn(cmd, args, cwd) {
@@ -5362,6 +5521,7 @@ function printCatalog(blocks, stacks, io, empty) {
   if (blocks.length) io.out("Blocks");
   for (const b of blocks) {
     io.out(`  ${b.id}  ${b.summary}`);
+    if (b.screens?.length) io.out(`      screens (start here): ${b.screens.join(", ")}`);
     if (b.dependsOn.length) io.out(`      depends on: ${b.dependsOn.join(", ")}`);
   }
   if (stacks.length) io.out(`${blocks.length ? "\n" : ""}Stacks`);
@@ -5413,13 +5573,13 @@ function runCreateCommand(rest, io) {
   if (wantsHelp(rest)) return io.out(CREATE_USAGE), 0;
   try {
     const opts = parseCreateArgs(rest);
-    const packageRoot = import_node_path5.default.resolve(__dirname, "..");
+    const packageRoot = import_node_path6.default.resolve(__dirname, "..");
     const cio = {
       out: io.out,
       err: io.err,
       spawn: io.spawn ?? defaultSpawn,
-      templatesRoot: io.templatesRoot ?? process.env.G8_TEMPLATES_DIR ?? import_node_path5.default.join(packageRoot, "templates"),
-      sdkPackageJson: import_node_path5.default.join(packageRoot, "package.json"),
+      templatesRoot: io.templatesRoot ?? process.env.G8_TEMPLATES_DIR ?? import_node_path6.default.join(packageRoot, "templates"),
+      sdkPackageJson: import_node_path6.default.join(packageRoot, "package.json"),
       userAgent: io.userAgent ?? process.env.npm_config_user_agent
     };
     return runCreate(opts, registryFor(io), cio, io.cwd);
@@ -5465,8 +5625,8 @@ ${USAGE}`);
     return 1;
   }
   const read = (rel) => {
-    const full = import_node_path5.default.join(io.cwd, rel);
-    return import_node_fs5.default.existsSync(full) ? import_node_fs5.default.readFileSync(full, "utf8") : null;
+    const full = import_node_path6.default.join(io.cwd, rel);
+    return import_node_fs6.default.existsSync(full) ? import_node_fs6.default.readFileSync(full, "utf8") : null;
   };
   let plans;
   try {
@@ -5477,9 +5637,9 @@ ${USAGE}`);
   }
   for (const plan of plans) {
     if (!options.dryRun && plan.action !== "unchanged") {
-      const full = import_node_path5.default.join(io.cwd, plan.path);
-      import_node_fs5.default.mkdirSync(import_node_path5.default.dirname(full), { recursive: true });
-      import_node_fs5.default.writeFileSync(full, plan.content, "utf8");
+      const full = import_node_path6.default.join(io.cwd, plan.path);
+      import_node_fs6.default.mkdirSync(import_node_path6.default.dirname(full), { recursive: true });
+      import_node_fs6.default.writeFileSync(full, plan.content, "utf8");
     }
     io.out(`${options.dryRun ? "would " : ""}${plan.action === "unchanged" ? "keep" : plan.action} ${plan.path}  (${plan.target})`);
   }

package/dist/index.browser.js

@@ -991,7 +991,7 @@ var EXTERNAL_ROUTES = {
 };
 
 // src/version.ts
-var SDK_VERSION = "0.358.0";
+var SDK_VERSION = "0.362.0";
 var SDK_CLIENT_ID = `js-sdk/${SDK_VERSION}`;
 
 // src/http.ts