@patchstack/connect 0.5.16 → 0.5.17

package/AGENT-INSTALL.md

@@ -240,7 +240,9 @@ Handle it in this order:
 
    **Bun-managed projects:** `bun run` does not execute npm-style `pre`/`post` scripts, so wire the build script directly instead: `"build": "patchstack-connect scan && <existing build command> && patchstack-connect mark-build"`.
 
-3. **Verify the Patchstack Connector** — a floating control whose form follows the site's claim state: while the site is unclaimed it is a one-time "Connect this website" panel. It is part of the install and on by default; do not ask whether to add it. `scan` installs it automatically into a plain HTML shell **or a JSX root** (Next, Remix, React Router, TanStack Start, Gatsby), and `mark-build` carries it into built HTML. Only when `scan` reported that it found no editable shell at all — a root whose head mechanism is not a plain script tag, e.g. Nuxt's `useHead` or an Astro layout — add the one-liner it printed to the root layout yourself, just before `</body>` (never a JS entry point), reading `siteUuid` from `.patchstackrc.json`. On those same roots the widget also needs the production marker above the tag — `scan` adds it automatically to a JSX root, and prints it to paste when it finds no anchor. A server-rendered site without the marker serves the build-mode claim flow to its visitors:
+   **Checking a build yourself:** run it through the package manager (`npm run build`), never the framework's own CLI (`astro build`, `vite build`, `next build`). Calling the CLI directly skips the `prebuild`/`postbuild` hooks, so the build is not scanned, not marked and not reported, and it tells you nothing about what the deployed build will carry.
+
+3. **Verify the Patchstack Connector** — a floating control whose form follows the site's claim state: while the site is unclaimed it is a one-time "Connect this website" panel. It is part of the install and on by default; do not ask whether to add it. `scan` installs it automatically into a plain HTML shell, **a JSX root** (Next, Remix, React Router, TanStack Start, Gatsby) **or an Astro layout**, and `mark-build` carries it into built HTML. Only when `scan` reported that it found no editable shell at all — a root whose head mechanism is not a plain script tag, e.g. Nuxt's `useHead` — add the one-liner it printed to the root layout yourself, just before `</body>` (never a JS entry point), reading `siteUuid` from `.patchstackrc.json`. On those same roots the widget also needs the production marker above the tag — `scan` adds it automatically to a JSX root or Astro layout, and prints it to paste when it finds no anchor. A server-rendered site without the marker serves the build-mode claim flow to its visitors:
 
    ```html
    <script src="https://cdn.patchstack.com/patchstack-widget.js" data-site-uuid="<SITE_UUID>" defer></script>
@@ -304,7 +306,7 @@ It is server-only. Never put it in the widget tag, client bundles, or public env
    and `mark-build` only read and write files; `scan` and `mark-build` also report the dependency
    manifest they read.
 
-5. **Commit** `.patchstackrc.json`, the updated `package.json`, the guard/framework source changes, and the layout/HTML file carrying the widget tag (and the production marker, when `scan` wrote one into a JSX root), so every developer and CI run reports to the same site.
+5. **Commit** `.patchstackrc.json`, the updated `package.json`, the guard/framework source changes, and the layout/HTML file carrying the widget tag (and the production marker, when `scan` wrote one into a JSX root or Astro layout), so every developer and CI run reports to the same site.
 
    **Do not commit `.patchstackrc.local.json`.** That file holds the API key issued at provision; the scan writes it and adds it to `.gitignore`, and tells you if it could not. `.patchstackrc.json` holds only the site UUID and settings, and the UUID is public by design — it ships in the widget tag in served HTML.
 
@@ -746,7 +748,7 @@ Remove only the pieces that are actually present — check for each first. If no
 5. **Signal Patchstack that the package is being removed**: run `npx @patchstack/connect uninstall` (while the package is still installed and `.patchstackrc.json` still exists). If the site was never claimed, this deletes its anonymous record on Patchstack; if the site is claimed, it is only flagged — the record stays until its owner removes it in the dashboard. A failed signal must not stop the uninstall; continue with the remaining steps.
 6. **Uninstall the package** with the manager matching the lockfile: `npm uninstall` / `pnpm remove` / `yarn remove` / `bun remove` `@patchstack/connect`. Don't hand-edit `node_modules` or the lockfile.
 7. **Delete `.patchstackrc.json` and `.patchstackrc.local.json`** (the second holds the API key and is git-ignored, so it is present locally even when the repo shows nothing), remove the `.gitignore` entry setup added for it, and remove `PATCHSTACK_SITE_UUID`, `PATCHSTACK_API_KEY` (and public-prefixed variants like `NEXT_PUBLIC_PATCHSTACK_SITE_UUID`) from env files and CI variables.
-8. **Commit** the changes. Reporting stops immediately. On HTML shells the `window.__PATCHSTACK_PROD__` flag that `mark-build` stamped on production builds lives only in build output — the next build simply won't contain it (rebuild if build output is committed). On JSX roots `scan` wrote the same marker into source; remove that managed `#region patchstack` block (or the hand-pasted equivalent) with the widget tag in step 2.
+8. **Commit** the changes. Reporting stops immediately. On HTML shells the `window.__PATCHSTACK_PROD__` flag that `mark-build` stamped on production builds lives only in build output — the next build simply won't contain it (rebuild if build output is committed). On JSX roots and Astro layouts `scan` wrote the same marker into source; remove that managed `#region patchstack` block (or the hand-pasted equivalent) with the widget tag in step 2.
 
 The `uninstall` signal is the only account-side effect local removal can have: it deletes an *unclaimed* (anonymous) record and merely flags a *claimed* one. A claimed site keeps using a site slot until its owner removes it in the dashboard at https://app.patchstack.com — end your report by telling the user this, alongside the site UUID from step 1. Never attempt to authenticate or remove a claimed site on the user's behalf.
 

package/README.md

@@ -123,8 +123,8 @@ patchstack-connect scan   [options]                Scan the lockfile and POST to
                                                    one and Connect persists it. After a
                                                    successful post, adds/updates the Patchstack
                                                    Connector tag in the root HTML shell. Also adds the
-                                                   production marker to a JSX root shell, before the
-                                                   post (opt out of both with "widget": false in
+                                                   production marker to a JSX root or Astro layout,
+                                                   before the post (opt out of both with "widget": false in
                                                    .patchstackrc.json)
 patchstack-connect setup  [options]                Run scan, manage the widget, and idempotently
                                                    install + verify runtime protection and wire
@@ -376,14 +376,14 @@ The Patchstack Connector is a floating control whose form follows the site's cla
   <script src="https://cdn.patchstack.com/patchstack-widget.js" data-site-uuid="<SITE_UUID>" defer data-patchstack-connect-widget="true"></script>
   ```
 
-- **`scan`** installs the widget tag into a plain HTML shell, and — where there is none — into a JSX root (`src/routes/__root.tsx`, `app/layout.tsx`, …), just before `</body>`. The same tag serves both: JSX reads `defer` as a boolean attribute and passes `data-*` through. A server-rendered app has no HTML shell at all, so without this its published site carries no widget and Patchstack never hears from the live page.
+- **`scan`** installs the widget tag into a plain HTML shell, and — where there is none — into a JSX root (`src/routes/__root.tsx`, `app/layout.tsx`, …) or an Astro layout (`src/layouts/Layout.astro`, `Base.astro`, or the first layout that closes `</body>`), just before `</body>`. The same tag serves both: JSX reads `defer` as a boolean attribute and passes `data-*` through. A server-rendered app has no HTML shell at all, so without this its published site carries no widget and Patchstack never hears from the live page.
 - **`scan`** also adds the production marker when the root shell is JSX rather than HTML (`src/routes/__root.tsx`, `app/layout.tsx`, …), above the widget tag and guarded by the framework's production expression. A server-rendered app emits no built HTML for `mark-build` to stamp, so without it the widget reads the published site as build mode and shows the claim flow to visitors instead of the report form.
 
-  Re-runs update the tag in place (the `data-patchstack-connect-widget` attribute marks it as managed by Connect); a pre-existing manual widget tag is left untouched. `--dry-run` never edits anything; a failed post still skips the widget tag (it needs the site UUID) but the production marker may already have been written, since it runs before the post. Projects whose root layout is code rather than HTML (Next.js, Nuxt, Astro, …) get the exact snippet and target file printed instead — `guide` shows framework-specific placement.
+  Re-runs update the tag in place (the `data-patchstack-connect-widget` attribute marks it as managed by Connect); a pre-existing manual widget tag is left untouched. `--dry-run` never edits anything; a failed post still skips the widget tag (it needs the site UUID) but the production marker may already have been written, since it runs before the post. Projects whose root layout is code that Connect does not edit (Nuxt, …) get the exact snippet and target file printed instead — `guide` shows framework-specific placement.
 
 - **`mark-build`** ensures the same tag in built HTML output, covering builds whose source shell Connect couldn't edit, and stamps `window.__PATCHSTACK_PROD__` so the widget hides the claim/login UI on the published site (owners reach it by appending `#patchstack` to the live URL). It then reports what it did — `stamped`, `withheld`, `no-pages` for a server-rendered build, or `no-output` — alongside the same manifest `scan` sent before the bundler ran, so the dashboard can say why a published app is or is not reporting its build. That report is the second half of one build, not a second build: Patchstack keeps one copy of the manifest and reads the two together. It is sent only for a site that is already registered, and never carries the site's address or name, which `mark-build` does not resolve. The marker says the page is the live site, so **only a production build carries it**: the environment is read the same way `scan` reads it (the build platform's own tier or branch name, then the hosted builder the project belongs to), and a local or preview build gets the widget tag, no marker, and any marker an earlier build left behind removed. Publishing a static build by hand from your machine is the case that needs `--production` (or `PATCHSTACK_ENVIRONMENT=production`), because nothing in that environment can say the build is a deployment.
 
-- **Opting out:** persist `"widget": false` in `.patchstackrc.json` to disable both the widget tag and the production marker (dependency scanning only). Without it, the next successful scan re-adds the managed tag, and the next scan re-adds the marker on a JSX root.
+- **Opting out:** persist `"widget": false` in `.patchstackrc.json` to disable both the widget tag and the production marker (dependency scanning only). Without it, the next successful scan re-adds the managed tag, and the next scan re-adds the marker on a JSX root or Astro layout.
 
 ## Programmatic API
 

package/dist/cli.js

@@ -2985,8 +2985,9 @@ function productionGate(framework) {
   const mapped = framework !== null ? PRODUCTION_GATES[framework] : void 0;
   return mapped ?? DEFAULT_PRODUCTION_GATE;
 }
-function hasJsxShell(framework) {
-  return framework !== null && JSX_SHELL_FRAMEWORKS.has(framework);
+var ASTRO = "astro";
+function hasEditableShell(framework) {
+  return framework !== null && (JSX_SHELL_FRAMEWORKS.has(framework) || framework === ASTRO);
 }
 function buildSourceMarkerSnippet(framework, checksum = null) {
   const gate = productionGate(framework);
@@ -2994,6 +2995,11 @@ function buildSourceMarkerSnippet(framework, checksum = null) {
   if (checksum !== null && checksum !== "") {
     statements.push(`window.__PATCHSTACK_BUILD__=${JSON.stringify(checksum)};`);
   }
+  if (framework === ASTRO) {
+    return `{${gate} && (
+  <script is:inline ${MARKER_ATTR}="true">${statements.join("")}</script>
+)}`;
+  }
   return `{${gate} && (
   <script
     ${MARKER_ATTR}="true"
@@ -3005,8 +3011,9 @@ var PROD_MARKER_GLOBAL = "__PATCHSTACK_PROD__";
 var REGION_OPEN = "{/* #region patchstack (managed by patchstack-connect \u2014 do not edit) */}";
 var REGION_CLOSE = "{/* #endregion patchstack */}";
 var REGION_RE = /[ \t]*\{\/\* #region patchstack[\s\S]*?#endregion patchstack \*\/\}\n?/g;
-function findJsxShellAnchor(source, tagName) {
+function findJsxShellAnchor(source, tagName, from = 0) {
   const candidates = new RegExp(`^([ \\t]*)<${tagName}(?=[\\s/>])`, "gm");
+  candidates.lastIndex = from;
   let candidate;
   while ((candidate = candidates.exec(source)) !== null) {
     let quote = null;
@@ -3060,8 +3067,14 @@ function findJsxShellAnchor(source, tagName) {
   }
   return null;
 }
+function astroTemplateStart(source) {
+  const open2 = /^\s*---[ \t]*\r?\n/.exec(source);
+  if (open2 === null) return 0;
+  const close = /^---[ \t]*$/m.exec(source.slice(open2[0].length));
+  return close === null ? 0 : open2[0].length + close.index + close[0].length;
+}
 function ensureMarkerInJsxShell(source, framework, checksum = null) {
-  if (!hasJsxShell(framework)) {
+  if (!hasEditableShell(framework)) {
     return { source, action: "unsupported" };
   }
   const stripped = source.replace(REGION_RE, "");
@@ -3069,8 +3082,9 @@ function ensureMarkerInJsxShell(source, framework, checksum = null) {
     return { source: stripped, action: "manual" };
   }
   const block = (indent) => [REGION_OPEN, ...buildSourceMarkerSnippet(framework, checksum).split("\n"), REGION_CLOSE].map((line) => `${indent}${line}`).join("\n");
+  const from = framework === ASTRO ? astroTemplateStart(stripped) : 0;
   for (const tagName of ["head", "body"]) {
-    const anchor = findJsxShellAnchor(stripped, tagName);
+    const anchor = findJsxShellAnchor(stripped, tagName, from);
     if (anchor === null) continue;
     const indent = `${anchor.indent}  `;
     const remainder = stripped.slice(anchor.end);
@@ -5765,7 +5779,7 @@ var WIDGET_FILE_CANDIDATES = {
   "react-router": ["app/root.tsx", "src/root.tsx"],
   "tanstack-start": ["src/routes/__root.tsx", "app/routes/__root.tsx"],
   sveltekit: ["src/app.html"],
-  astro: ["src/layouts/Layout.astro"],
+  astro: ["src/layouts/Layout.astro", "src/layouts/Base.astro", "src/layouts/BaseLayout.astro"],
   gatsby: ["src/html.js"]
 };
 var GENERIC_WIDGET_FILES = ["index.html", "public/index.html"];
@@ -5909,6 +5923,24 @@ function resolveWidgetFileHint(cwd, framework) {
       return candidate;
     }
   }
+  return framework === "astro" ? findAstroDocumentLayout(cwd) : null;
+}
+function findAstroDocumentLayout(cwd) {
+  const dir = path12.join("src", "layouts");
+  let names;
+  try {
+    names = readdirSync5(path12.join(cwd, dir)).filter((name) => name.endsWith(".astro")).sort();
+  } catch {
+    return null;
+  }
+  for (const name of names) {
+    try {
+      if (/<\/body>/i.test(readFileSync11(path12.join(cwd, dir, name), "utf8"))) {
+        return path12.posix.join("src", "layouts", name);
+      }
+    } catch {
+    }
+  }
   return null;
 }
 async function collectGuideState(cwd) {
@@ -6095,7 +6127,7 @@ function guideMissing(state, known = {}) {
   if (needsSourceProductionMarker(state) && !state.productionMarkerWired) {
     const gate = productionGate(state.framework);
     missing.push(
-      hasJsxShell(state.framework) ? {
+      hasEditableShell(state.framework) ? {
         text: "Your live app does not tell Patchstack it is live yet",
         hint: [`Run: npx @patchstack/connect scan (it edits ${state.widgetFileHint})`],
         detail: [`Or add inside <head>:`, ...buildSourceMarkerSnippet(state.framework).split("\n").map((line) => `  ${line}`)]
@@ -10304,7 +10336,7 @@ function reportSourceWidget(siteUuid, framework, report) {
     });
   };
   try {
-    const hint = hasJsxShell(framework) ? resolveWidgetFileHint(process.cwd(), framework) : null;
+    const hint = hasEditableShell(framework) ? resolveWidgetFileHint(process.cwd(), framework) : null;
     const jsxShell = hint !== null && !hint.toLowerCase().endsWith(".html") ? hint : null;
     const result = ensureSourceWidget(process.cwd(), siteUuid, jsxShell);
     switch (result.action) {
@@ -10351,7 +10383,7 @@ function reportSourceMarker(framework, checksum, report) {
       case "unsupported":
         report.missing.push({
           text: "Your live app does not tell Patchstack it is live yet",
-          hint: hasJsxShell(framework) ? [`Add this inside <head> in ${shell}:`, ...buildSourceMarkerSnippet(framework).split("\n").map((line) => `  ${line}`)] : [
+          hint: hasEditableShell(framework) ? [`Add this inside <head> in ${shell}:`, ...buildSourceMarkerSnippet(framework).split("\n").map((line) => `  ${line}`)] : [
             `Add this inside <head> in ${shell}, only when ${productionGate(framework)}:`,
             "  <script>window.__PATCHSTACK_PROD__=true;</script>"
           ]