@stacksjs/stx 0.2.94 → 0.2.96

package/dist/docs.js

@@ -1,2 +1,567 @@
-// @bun
-import{an as a,bn as b,cn as c,dn as d,en as e,fn as f,gn as g,hn as h,in as i,jn as j,kn as k,ln as l}from"./chunk-50vqeesm.js";import"./chunk-w01y57f5.js";import"./chunk-x1hjv24z.js";import"./chunk-0g4gece6.js";import"./chunk-nap11ntr.js";import"./chunk-03c26pjz.js";import"./chunk-13yz561y.js";import"./chunk-nanw7yhz.js";import"./chunk-ghrx0hn1.js";import"./chunk-82t27pvd.js";import"./chunk-fhawx87n.js";import"./chunk-gc84b1d2.js";import"./chunk-yr1gdceh.js";import"./chunk-baa7h4yz.js";import"./chunk-kdxa9epn.js";import"./chunk-g2hekckm.js";import"./chunk-x39sfpvm.js";import"./chunk-tr0z0e1g.js";import"./chunk-4j188175.js";import"./chunk-eds0f8f1.js";import"./chunk-dyjnn5k8.js";import"./chunk-8fgwhhb8.js";import"./chunk-tj6zfxeb.js";import"./chunk-7xcfy2fn.js";import"./chunk-9yz5d003.js";import"./chunk-fms20x0n.js";import"./chunk-fe7r1mq1.js";import"./chunk-rb1e4cnb.js";import"./chunk-j4s5qwd7.js";import"./chunk-b0cyc09a.js";import"./chunk-0tatqxj2.js";import"./chunk-bykjk6vj.js";import"./chunk-7b0xdy5h.js";import"./chunk-ywkrxp2h.js";import"./chunk-y25pr13j.js";import"./chunk-q6h6yvzb.js";import"./chunk-qdc3aav1.js";import"./chunk-6wn85hn6.js";import"./chunk-qd5461tt.js";import"./chunk-77tga15w.js";import"./chunk-rv002yn0.js";import"./chunk-hke99a0v.js";import"./chunk-mwbng54r.js";import"./chunk-wxvyj65q.js";import"./chunk-yw2fzq86.js";import"./chunk-mrehzhxv.js";import"./chunk-1zgsgk4b.js";import"./chunk-48cw2nde.js";import"./chunk-jjvp4t5w.js";import"./chunk-94g3cahw.js";import"./chunk-ht4j68cs.js";import"./chunk-fch9tk1k.js";import"./chunk-cz25azze.js";import"./chunk-q60knhjf.js";import"./chunk-hrampcrj.js";import"./chunk-t37dp99j.js";import"./chunk-5kt3ay7x.js";import"./chunk-95w08s8v.js";import"./chunk-ceg2c2q2.js";import"./chunk-04mvcmcr.js";import"./chunk-n46a5g1g.js";import"./chunk-vv9wfz1c.js";import"./chunk-dzw95th7.js";import"./chunk-46mkpbkk.js";import"./chunk-3rh7va1z.js";import"./chunk-2xen423s.js";import"./chunk-cp3kwv17.js";import"./chunk-hpqr9e3x.js";import"./chunk-adqh2m9z.js";import"./chunk-8qbax8xn.js";import"./chunk-x64kb787.js";import"./chunk-gcf5v18y.js";import"./chunk-pc31m5x5.js";import"./chunk-3jm3snz8.js";export{f as generateTemplatesDocs,k as generateDocs,g as generateDirectivesDocs,e as generateComponentsDocs,c as generateComponentDoc,h as formatDocsAsMarkdown,j as formatDocsAsJson,i as formatDocsAsHtml,d as findComponentFiles,a as extractComponentProps,b as extractComponentDescription,l as docsCommand};
+import fs from "node:fs";
+import path from "node:path";
+import { config } from "./config.js";
+import { fileExists } from "./utils.js";
+export async function extractComponentProps(componentPath) {
+  try {
+    const scriptMatch = (await Bun.file(componentPath).text()).match(/<script\b[^>]*>([\s\S]*?)<\/script>/i);
+    if (!scriptMatch)
+      return [];
+    const scriptContent = scriptMatch[1], props = [], propRegex = /\/\*\*\s*([\s\S]*?)\s*\*\/\s*(?:(?:const|let|var)\s*)?(?:([\w$]+)\s*=|module\.exports\.([\w$]+)\s*=|\s*([\w$]+)\s*:)/g;
+    let match;
+    while ((match = propRegex.exec(scriptContent)) !== null) {
+      const commentBlock = match[1], propName = match[2] || match[3] || match[4];
+      if (!propName)
+        continue;
+      const propDoc = { name: propName }, typeMatch = commentBlock.match(/@type\s+\{([^}]+)\}/i);
+      if (typeMatch)
+        propDoc.type = typeMatch[1].trim();
+      if (commentBlock.match(/@required/i))
+        propDoc.required = !0;
+      const defaultMatch = commentBlock.match(/@default\s+(.+?)(?:\s+|$)/i);
+      if (defaultMatch)
+        propDoc.default = defaultMatch[1].trim();
+      const descLines = commentBlock.split(`
+`).map((line) => line.trim().replace(/^\*\s*/, "")).filter((line) => !line.startsWith("@") && line.length > 0);
+      propDoc.description = descLines.join(" ").trim();
+      props.push(propDoc);
+    }
+    if (props.length === 0) {
+      const exportsMatch = scriptContent.match(/module\.exports\s*=\s*\{([^}]+)\}/i);
+      if (exportsMatch) {
+        const propLines = exportsMatch[1].split(",").map((line) => line.trim()).filter(Boolean);
+        for (const propLine of propLines) {
+          const [propName] = propLine.split(":").map((part) => part.trim());
+          if (propName)
+            props.push({ name: propName });
+        }
+      }
+    }
+    return props;
+  } catch (error) {
+    console.error(`Error extracting props from ${componentPath}:`, error);
+    return [];
+  }
+}
+export async function extractComponentDescription(componentPath) {
+  try {
+    const content = await Bun.file(componentPath).text(), commentMatch = content.match(/^\s*<!--\s*([\s\S]*?)\s*-->/) || content.match(/^\s*\/\*\*\s*([\s\S]*?)\s*\*\//);
+    if (commentMatch)
+      return commentMatch[1].split(`
+`).map((line) => line.trim().replace(/^\*\s*/, "")).join(" ").trim();
+    return "";
+  } catch {
+    return "";
+  }
+}
+export async function generateComponentDoc(componentPath, isWebComponent = !1, webComponentTag) {
+  const name = path.basename(componentPath, ".stx"), props = await extractComponentProps(componentPath), description = await extractComponentDescription(componentPath);
+  let example = "";
+  if (isWebComponent && webComponentTag)
+    example = `<${webComponentTag}></${webComponentTag}>`;
+  else {
+    const propsExample = props.map((prop) => {
+      if (prop.type === "boolean")
+        return `:${prop.name}="true"`;
+      return `${prop.name}="value"`;
+    }).join(`
+  `);
+    example = `<${name}
+  ${propsExample}
+/>`;
+  }
+  return {
+    name,
+    path: componentPath,
+    description,
+    props,
+    example,
+    isWebComponent,
+    tag: webComponentTag
+  };
+}
+export async function findComponentFiles(componentsDir) {
+  try {
+    if (!await fileExists(componentsDir)) {
+      console.warn(`Components directory does not exist: ${componentsDir}`);
+      return [];
+    }
+    const entries = await fs.promises.readdir(componentsDir, { withFileTypes: !0 }), componentFiles = [];
+    for (const entry of entries) {
+      const entryPath = path.join(componentsDir, entry.name);
+      if (entry.isDirectory()) {
+        const subComponents = await findComponentFiles(entryPath);
+        componentFiles.push(...subComponents);
+      } else if (entry.isFile() && entry.name.endsWith(".stx"))
+        componentFiles.push(entryPath);
+    }
+    return componentFiles;
+  } catch (error) {
+    console.error(`Error finding component files in ${componentsDir}:`, error);
+    return [];
+  }
+}
+export async function generateComponentsDocs(componentsDir, webComponentsConfig) {
+  try {
+    if (!await fileExists(componentsDir))
+      return [];
+    const componentFiles = await findComponentFiles(componentsDir), componentDocs = [], webComponentsMap = new Map;
+    if (webComponentsConfig?.components?.length)
+      for (const component of webComponentsConfig.components)
+        webComponentsMap.set(component.file, component);
+    for (const componentFile of componentFiles) {
+      const webComponent = webComponentsMap.get(componentFile), isWebComponent = !!webComponent, webComponentTag = webComponent?.tag, doc = await generateComponentDoc(componentFile, isWebComponent, webComponentTag);
+      componentDocs.push(doc);
+    }
+    return componentDocs;
+  } catch (error) {
+    console.error("Error generating component docs:", error);
+    return [];
+  }
+}
+export async function generateTemplatesDocs(templatesDir) {
+  try {
+    if (!await fileExists(templatesDir))
+      return [];
+    const entries = await fs.promises.readdir(templatesDir, { withFileTypes: !0 }), templateDocs = [];
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".stx"))
+        continue;
+      const templatePath = path.join(templatesDir, entry.name), content = await Bun.file(templatePath).text(), name = path.basename(templatePath, ".stx"), descriptionMatch = content.match(/^\s*<!--\s*([\s\S]*?)\s*-->/) || content.match(/^\s*\/\*\*\s*([\s\S]*?)\s*\*\//), description = descriptionMatch ? descriptionMatch[1].split(`
+`).map((line) => line.trim().replace(/^\*\s*/, "")).join(" ").trim() : "", componentRegex = /@component\(\s*['"]([^'"]+)['"]/g, componentTags = /<([A-Z][a-zA-Z0-9]*|[a-z]+-[a-z0-9-]+)(?:\s[^>]*)?\/?>|\{\{\s*slot\s*\}\}/g, components = new Set;
+      let match;
+      while ((match = componentRegex.exec(content)) !== null)
+        components.add(match[1]);
+      while ((match = componentTags.exec(content)) !== null)
+        if (match[1] && match[1] !== "slot")
+          components.add(match[1]);
+      const directiveRegex = /@([a-z]+)(?:\s*\(|\s+|$)/g, directives = new Set;
+      while ((match = directiveRegex.exec(content)) !== null)
+        directives.add(match[1]);
+      templateDocs.push({
+        name,
+        path: templatePath,
+        description,
+        components: [...components],
+        directives: [...directives]
+      });
+    }
+    return templateDocs;
+  } catch (error) {
+    console.error("Error generating template docs:", error);
+    return [];
+  }
+}
+export async function generateDirectivesDocs(customDirectives = []) {
+  try {
+    const directiveDocs = [
+      {
+        name: "if",
+        description: "Conditionally render content based on a condition",
+        hasEndTag: !0,
+        example: `@if(user.isLoggedIn)
+  <p>Welcome, {{ user.name }}!</p>
+@endif`
+      },
+      {
+        name: "else",
+        description: "Provides an alternative if a condition is not met",
+        hasEndTag: !1,
+        example: `@if(user.isLoggedIn)
+  <p>Welcome back!</p>
+@else
+  <p>Please log in</p>
+@endif`
+      },
+      {
+        name: "elseif",
+        description: "Provides an alternative condition",
+        hasEndTag: !1,
+        example: `@if(score > 90)
+  <p>A</p>
+@elseif(score > 80)
+  <p>B</p>
+@elseif(score > 70)
+  <p>C</p>
+@endif`
+      },
+      {
+        name: "unless",
+        description: "Conditionally render content if a condition is false",
+        hasEndTag: !0,
+        example: `@unless(user.isLoggedIn)
+  <p>Please log in</p>
+@endunless`
+      },
+      {
+        name: "for",
+        description: "Loop through an array or object",
+        hasEndTag: !0,
+        example: `@for(item of items)
+  <li>{{ item.name }}</li>
+@endfor`
+      },
+      {
+        name: "while",
+        description: "Loop while a condition is true",
+        hasEndTag: !0,
+        example: `@while(page < totalPages)
+  <p>Page {{ page }}</p>
+@endwhile`
+      },
+      {
+        name: "component",
+        description: "Include a component in the template",
+        hasEndTag: !1,
+        example: '@component("alert", { type: "warning", title: "Warning", message: "This is a warning" })'
+      },
+      {
+        name: "include",
+        description: "Include a partial template",
+        hasEndTag: !1,
+        example: '@include("partials/header")'
+      },
+      {
+        name: "raw",
+        description: "Display content without processing expressions",
+        hasEndTag: !0,
+        example: `@raw
+  {{ This will be displayed as-is }}
+@endraw`
+      },
+      {
+        name: "translate",
+        description: "Translate a string using the i18n system",
+        hasEndTag: !1,
+        example: '@translate("welcome.message", { name: user.name })'
+      },
+      {
+        name: "t",
+        description: "Short alias for translate directive",
+        hasEndTag: !1,
+        example: '@t("welcome.message", { name: user.name })'
+      }
+    ];
+    for (const directive of customDirectives)
+      directiveDocs.push({
+        name: directive.name,
+        description: directive.description || "",
+        hasEndTag: directive.hasEndTag || !1,
+        example: ""
+      });
+    return directiveDocs;
+  } catch (error) {
+    console.error("Error generating directive docs:", error);
+    return [];
+  }
+}
+export function formatDocsAsMarkdown(componentDocs = [], templateDocs = [], directiveDocs = [], extraContent) {
+  let markdown = `# stx Documentation
+
+`;
+  if (extraContent)
+    markdown += `${extraContent}
+
+`;
+  if (componentDocs.length > 0) {
+    markdown += `## Components
+
+`;
+    for (const doc of componentDocs) {
+      markdown += `### ${doc.name}
+
+`;
+      if (doc.description)
+        markdown += `${doc.description}
+
+`;
+      if (doc.isWebComponent)
+        markdown += `**Web Component Tag:** \`${doc.tag}\`
+
+`;
+      if (doc.props.length > 0) {
+        markdown += `#### Properties
+
+`;
+        markdown += `| Name | Type | Required | Default | Description |
+`;
+        markdown += `| ---- | ---- | -------- | ------- | ----------- |
+`;
+        for (const prop of doc.props)
+          markdown += `| ${prop.name} | ${prop.type || "any"} | ${prop.required ? "Yes" : "No"} | ${prop.default || "-"} | ${prop.description || "-"} |
+`;
+        markdown += `
+`;
+      }
+      if (doc.example) {
+        markdown += `#### Example
+
+`;
+        markdown += "```html\n";
+        markdown += doc.example;
+        markdown += "\n```\n\n";
+      }
+    }
+  }
+  if (templateDocs.length > 0) {
+    markdown += `## Templates
+
+`;
+    for (const doc of templateDocs) {
+      markdown += `### ${doc.name}
+
+`;
+      if (doc.description)
+        markdown += `${doc.description}
+
+`;
+      if (doc.components && doc.components.length > 0)
+        markdown += `**Components Used:** ${doc.components.join(", ")}
+
+`;
+      if (doc.directives && doc.directives.length > 0)
+        markdown += `**Directives Used:** ${doc.directives.join(", ")}
+
+`;
+    }
+  }
+  if (directiveDocs.length > 0) {
+    markdown += `## Directives
+
+`;
+    markdown += `| Directive | Description | Has End Tag |
+`;
+    markdown += `| --------- | ----------- | ----------- |
+`;
+    for (const doc of directiveDocs)
+      markdown += `| @${doc.name} | ${doc.description || "-"} | ${doc.hasEndTag ? "Yes" : "No"} |
+`;
+    markdown += `
+`;
+    for (const doc of directiveDocs)
+      if (doc.example) {
+        markdown += `### @${doc.name}
+
+`;
+        markdown += `${doc.description || ""}
+
+`;
+        markdown += `#### Example
+
+`;
+        markdown += "```html\n";
+        markdown += doc.example;
+        markdown += "\n```\n\n";
+      }
+  }
+  return markdown;
+}
+export function formatDocsAsHtml(componentDocs = [], templateDocs = [], directiveDocs = [], extraContent) {
+  let html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>stx Documentation</title>
+  <style>
+    body {
+      font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
+      line-height: 1.6;
+      color: #333;
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 2rem;
+    }
+    h1, h2, h3, h4 { margin-top: 2rem; }
+    table {
+      border-collapse: collapse;
+      width: 100%;
+      margin: 1rem 0;
+    }
+    th, td {
+      text-align: left;
+      padding: 0.5rem;
+      border-bottom: 1px solid #ddd;
+    }
+    th { border-bottom: 2px solid #ddd; }
+    pre {
+      background: #f5f5f5;
+      padding: 1rem;
+      border-radius: 4px;
+      overflow-x: auto;
+    }
+    code {
+      background: #f5f5f5;
+      padding: 0.2rem 0.4rem;
+      border-radius: 4px;
+      font-size: 0.9em;
+    }
+  </style>
+</head>
+<body>
+  <h1>stx Documentation</h1>
+  `;
+  if (extraContent)
+    html += `<div>${extraContent}</div>`;
+  if (componentDocs.length > 0) {
+    html += "<h2>Components</h2>";
+    for (const doc of componentDocs) {
+      html += `<h3>${doc.name}</h3>`;
+      if (doc.description)
+        html += `<p>${doc.description}</p>`;
+      if (doc.isWebComponent)
+        html += `<p><strong>Web Component Tag:</strong> <code>${doc.tag}</code></p>`;
+      if (doc.props.length > 0) {
+        html += "<h4>Properties</h4>";
+        html += `<table>
+          <thead>
+            <tr>
+              <th>Name</th>
+              <th>Type</th>
+              <th>Required</th>
+              <th>Default</th>
+              <th>Description</th>
+            </tr>
+          </thead>
+          <tbody>`;
+        for (const prop of doc.props)
+          html += `<tr>
+            <td>${prop.name}</td>
+            <td>${prop.type || "any"}</td>
+            <td>${prop.required ? "Yes" : "No"}</td>
+            <td>${prop.default || "-"}</td>
+            <td>${prop.description || "-"}</td>
+          </tr>`;
+        html += "</tbody></table>";
+      }
+      if (doc.example) {
+        html += "<h4>Example</h4>";
+        html += `<pre><code>${doc.example.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;")}</code></pre>`;
+      }
+    }
+  }
+  if (templateDocs.length > 0) {
+    html += "<h2>Templates</h2>";
+    for (const doc of templateDocs) {
+      html += `<h3>${doc.name}</h3>`;
+      if (doc.description)
+        html += `<p>${doc.description}</p>`;
+      if (doc.components && doc.components.length > 0)
+        html += `<p><strong>Components Used:</strong> ${doc.components.join(", ")}</p>`;
+      if (doc.directives && doc.directives.length > 0)
+        html += `<p><strong>Directives Used:</strong> ${doc.directives.join(", ")}</p>`;
+    }
+  }
+  if (directiveDocs.length > 0) {
+    html += "<h2>Directives</h2>";
+    html += `<table>
+      <thead>
+        <tr>
+          <th>Directive</th>
+          <th>Description</th>
+          <th>Has End Tag</th>
+        </tr>
+      </thead>
+      <tbody>`;
+    for (const doc of directiveDocs)
+      html += `<tr>
+        <td>@${doc.name}</td>
+        <td>${doc.description || "-"}</td>
+        <td>${doc.hasEndTag ? "Yes" : "No"}</td>
+      </tr>`;
+    html += "</tbody></table>";
+    for (const doc of directiveDocs)
+      if (doc.example) {
+        html += `<h3>@${doc.name}</h3>`;
+        html += `<p>${doc.description || ""}</p>`;
+        html += "<h4>Example</h4>";
+        html += `<pre><code>${doc.example.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;")}</code></pre>`;
+      }
+  }
+  html += "</body></html>";
+  return html;
+}
+export function formatDocsAsJson(componentDocs = [], templateDocs = [], directiveDocs = [], extraContent) {
+  return JSON.stringify({
+    components: componentDocs,
+    templates: templateDocs,
+    directives: directiveDocs,
+    extraContent: extraContent || ""
+  }, null, 2);
+}
+export async function generateDocs(options) {
+  try {
+    const { componentsDir, templatesDir, webComponentsConfig, customDirectives, config: docConfig } = options;
+    if (!docConfig.enabled)
+      return !1;
+    const outputDir = docConfig.outputDir || "docs";
+    await fs.promises.mkdir(outputDir, { recursive: !0 });
+    console.log("Generating documentation...");
+    if (componentsDir)
+      console.log(`Components directory: ${componentsDir}`);
+    if (templatesDir)
+      console.log(`Templates directory: ${templatesDir}`);
+    console.log(`Output directory: ${outputDir}`);
+    let componentDocs = [];
+    if (docConfig.components !== !1 && componentsDir) {
+      console.log("Generating component documentation...");
+      componentDocs = await generateComponentsDocs(componentsDir, webComponentsConfig);
+      console.log(`Found ${componentDocs.length} components`);
+    }
+    let templateDocs = [];
+    if (docConfig.templates !== !1 && templatesDir) {
+      console.log("Generating template documentation...");
+      templateDocs = await generateTemplatesDocs(templatesDir);
+      console.log(`Found ${templateDocs.length} templates`);
+    }
+    let directiveDocs = [];
+    if (docConfig.directives !== !1) {
+      console.log("Generating directive documentation...");
+      directiveDocs = await generateDirectivesDocs(customDirectives);
+      console.log(`Found ${directiveDocs.length} directives`);
+    }
+    const format = docConfig.format || "markdown", extraContent = docConfig.extraContent;
+    let docContent = "", extension = "";
+    switch (format) {
+      case "markdown":
+        docContent = formatDocsAsMarkdown(componentDocs, templateDocs, directiveDocs, extraContent);
+        extension = "md";
+        break;
+      case "html":
+        docContent = formatDocsAsHtml(componentDocs, templateDocs, directiveDocs, extraContent);
+        extension = "html";
+        break;
+      case "json":
+        docContent = formatDocsAsJson(componentDocs, templateDocs, directiveDocs, extraContent);
+        extension = "json";
+        break;
+      default:
+        throw Error(`Unsupported documentation format: ${format}`);
+    }
+    const outputPath = path.join(outputDir, `stx-docs.${extension}`);
+    await Bun.write(outputPath, docContent);
+    console.log(`Documentation generated: ${outputPath}`);
+    return !0;
+  } catch (error) {
+    console.error("Error generating documentation:", error);
+    return !1;
+  }
+}
+export async function docsCommand(options) {
+  const docsConfig = {
+    enabled: !0,
+    outputDir: options.output || "docs",
+    format: options.format || "markdown",
+    components: options.components !== !1,
+    templates: options.templates !== !1,
+    directives: options.directives !== !1,
+    extraContent: options.extraContent
+  }, componentsDir = options.componentsDir || config.componentsDir, templatesDir = options.templatesDir || ".";
+  return generateDocs({
+    componentsDir,
+    templatesDir,
+    webComponentsConfig: config.webComponents,
+    customDirectives: config.customDirectives,
+    config: docsConfig
+  });
+}

package/dist/doctor.js

@@ -1,2 +1,123 @@
-// @bun
-import{mn as a,nn as b,on as c}from"./chunk-xcb0pbr6.js";import"./chunk-3jm3snz8.js";export{b as runDoctor,c as formatDoctorReport,a as findPantryPackage};
+import fs from "node:fs";
+import path from "node:path";
+function mtimeMs(p) {
+  try {
+    return fs.statSync(p).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+function ago(ms, now) {
+  const s = Math.max(0, Math.round((now - ms) / 1000));
+  if (s < 60)
+    return `${s}s ago`;
+  if (s < 3600)
+    return `${Math.round(s / 60)}m ago`;
+  return `${Math.round(s / 3600)}h ago`;
+}
+function defaultResolve(specifier, from) {
+  try {
+    return globalThis.Bun?.resolveSync(specifier, from) ?? null;
+  } catch {
+    return null;
+  }
+}
+export function findPantryPackage(cwd, name = "stx") {
+  let dir = path.resolve(cwd);
+  for (let i = 0;i < 10; i++) {
+    const candidate = path.join(dir, "pantry", "@stacksjs", name);
+    if (fs.existsSync(candidate))
+      return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return null;
+}
+export async function runDoctor(options = {}) {
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd(), resolve = options.resolve ?? defaultResolve, now = Date.now(), checks = [], stxEntry = resolve("@stacksjs/stx", cwd);
+  checks.push(stxEntry ? { name: "@stacksjs/stx resolves to", status: "ok", detail: stxEntry } : { name: "@stacksjs/stx resolves to", status: "info", detail: "not resolvable from here (running inside the stx repo, or not installed)" });
+  const pluginEntry = resolve("bun-plugin-stx", cwd);
+  if (pluginEntry)
+    checks.push({ name: "bun-plugin-stx resolves to", status: "ok", detail: pluginEntry });
+  const pantry = findPantryPackage(cwd, "stx");
+  if (!pantry)
+    checks.push({ name: "pantry", status: "info", detail: "no pantry/@stacksjs/stx found \u2014 standard install (nothing to rebuild)" });
+  else {
+    const srcSignals = path.join(pantry, "src/signals.ts"), distEntry = [path.join(pantry, "dist/index.js"), path.join(pantry, "dist/signals.js")].find((p) => fs.existsSync(p)) || null, srcMtime = mtimeMs(srcSignals), distMtime = distEntry ? mtimeMs(distEntry) : null;
+    if (srcMtime == null)
+      checks.push({ name: "pantry dist freshness", status: "info", detail: `found pantry at ${pantry} but no src/signals.ts to compare` });
+    else if (distMtime == null)
+      checks.push({
+        name: "pantry dist freshness",
+        status: "error",
+        detail: "pantry has src but no built dist \u2014 the dev server will resolve nothing (or a stale copy elsewhere)",
+        fix: `cd ${pantry} && bun build.ts`
+      });
+    else if (distMtime < srcMtime) {
+      const lagS = Math.round((srcMtime - distMtime) / 1000);
+      checks.push({
+        name: "pantry dist freshness",
+        status: "error",
+        detail: `dist (${ago(distMtime, now)}) is OLDER than src/signals.ts (${ago(srcMtime, now)}) by ${lagS}s \u2014 your edit isn't built`,
+        fix: `cd ${pantry} && bun build.ts`
+      });
+    } else
+      checks.push({ name: "pantry dist freshness", status: "ok", detail: `dist rebuilt after src (src ${ago(srcMtime, now)}, dist ${ago(distMtime, now)})` });
+    const nm = path.join(cwd, "node_modules/@stacksjs/stx");
+    let lst = null;
+    try {
+      lst = fs.lstatSync(nm);
+    } catch {
+      lst = null;
+    }
+    if (!lst)
+      checks.push({ name: "node_modules \u2192 pantry", status: "info", detail: "node_modules/@stacksjs/stx not present (not installed here)" });
+    else if (lst.isSymbolicLink()) {
+      let target = null;
+      try {
+        target = fs.realpathSync(nm);
+      } catch {}
+      const pantryReal = (() => {
+        try {
+          return fs.realpathSync(pantry);
+        } catch {
+          return pantry;
+        }
+      })();
+      checks.push(target === pantryReal ? { name: "node_modules \u2192 pantry", status: "ok", detail: "symlinked to pantry" } : { name: "node_modules \u2192 pantry", status: "warn", detail: `symlinked to ${target || "(dangling)"}, not pantry` });
+    } else
+      checks.push({
+        name: "node_modules \u2192 pantry",
+        status: "warn",
+        detail: "is a real directory, NOT symlinked to pantry \u2014 edits to pantry src/dist won't be resolved",
+        fix: "rm -rf node_modules/@stacksjs/stx && ln -s ../../pantry/@stacksjs/stx node_modules/@stacksjs/stx"
+      });
+  }
+  checks.push({
+    name: "dev runtime cache",
+    status: "info",
+    detail: "cleared automatically on source edits by the dev watcher (clearDevCaches, #1745 item C)"
+  });
+  if (options.generateRuntime)
+    try {
+      const len = options.generateRuntime().length;
+      checks.push(len > 1000 ? { name: "signals runtime", status: "ok", detail: `generated ${len.toLocaleString()} chars` } : { name: "signals runtime", status: "warn", detail: `generated only ${len} chars \u2014 suspiciously short` });
+    } catch (e) {
+      checks.push({ name: "signals runtime", status: "error", detail: `failed to generate: ${e.message}` });
+    }
+  return { checks, ok: !checks.some((c) => c.status === "error") };
+}
+export function formatDoctorReport(report) {
+  const icon = { ok: "\u2713", warn: "\u26A0", error: "\u2717", info: "\xB7" }, lines = ["stx runtime resolution:"];
+  for (const c of report.checks) {
+    lines.push(`  ${icon[c.status]} ${c.name}: ${c.detail}`);
+    if (c.fix)
+      lines.push(`     \u2192 ${c.fix}`);
+  }
+  lines.push("");
+  lines.push(report.ok ? "\u2713 All framework-runtime layers are aligned." : "\u2717 A runtime layer is stale \u2014 see the fixes above.");
+  return lines.join(`
+`);
+}