@dreamdata_io/verify-tracking 0.1.0 → 0.1.2

package/dist/review/open.js

@@ -0,0 +1,53 @@
+/**
+ * Hands the generated dashboard to the operator's browser.
+ *
+ * macOS only, deliberately. `open` is the one launcher this tool's installed
+ * audience has, and a Linux/Windows path would be written blind — those
+ * platforms get the printed path instead, which is what a headless machine
+ * wants anyway.
+ *
+ * Never throws, and never prints: it returns what happened and the caller
+ * decides what to say. That is also what keeps it safe to import from a
+ * module graph the MCP server touches, where stdout belongs to the transport.
+ */
+import { spawn } from "node:child_process";
+import { resolve } from "node:path";
+import { outputRoot } from "../config/user-config.js";
+/**
+ * Recognisable in Finder among the report JSONs, and stable across runs so a
+ * closed tab is reopened by path. No spaces: the same string is a shell
+ * argument, a doc snippet and a file URL.
+ */
+export const DASHBOARD_FILENAME = "dreamdata-tracking-dashboard.html";
+/** Where the dashboard is written, resolved on call — never at module scope. */
+export function dashboardPath() {
+    return resolve(outputRoot(), DASHBOARD_FILENAME);
+}
+/**
+ * Detached and unref'd, so the CLI's `process.exit` neither kills the child
+ * nor waits for it: on POSIX a parent exiting sends no signal, and `open` has
+ * already handed off to LaunchServices by then. `stdio: "ignore"` means the
+ * child physically cannot write to our stdout.
+ */
+function spawnDetachedReal(command, args) {
+    spawn(command, args, { detached: true, stdio: "ignore" }).unref();
+}
+export function openDashboard(options) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const launch = options.spawnDetached ?? spawnDetachedReal;
+    // A build machine has no one to show it to, and popping a browser in CI is
+    // noise at best.
+    if (env.CI)
+        return { kind: "skipped", reason: "disabled" };
+    if (platform !== "darwin")
+        return { kind: "skipped", reason: "unsupported-platform" };
+    try {
+        launch("open", [options.path]);
+        return { kind: "opened" };
+    }
+    catch (err) {
+        return { kind: "failed", detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+//# sourceMappingURL=open.js.map

package/dist/review/open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open.js","sourceRoot":"","sources":["../../src/review/open.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,mCAAmC,CAAC;AAEtE,gFAAgF;AAChF,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC,UAAU,EAAE,EAAE,kBAAkB,CAAC,CAAC;AACnD,CAAC;AAgBD;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,OAAe,EAAE,IAAc;IACxD,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAA6B;IACzD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IACtD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACvC,MAAM,MAAM,GAAG,OAAO,CAAC,aAAa,IAAI,iBAAiB,CAAC;IAE1D,2EAA2E;IAC3E,iBAAiB;IACjB,IAAI,GAAG,CAAC,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC3D,IAAI,QAAQ,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAEtF,IAAI,CAAC;QACH,MAAM,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACtF,CAAC;AACH,CAAC"}

package/dist/version.js

@@ -6,5 +6,5 @@
  * breaks the moment the output layout changes. A literal that the release
  * workflow checks against the git tag is the cheaper guarantee.
  */
-export const VERSION = "0.1.0";
+export const VERSION = "0.1.1";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamdata_io/verify-tracking",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Scrapes a live website with Playwright and asks an AI model whether the Dreamdata Analytics Script is correctly installed.",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,7 @@
   "files": [
     "dist",
     "scripts/install.sh",
+    "verification/review/index.html",
     "README.md",
     "LICENSE"
   ],

package/scripts/install.sh

@@ -38,6 +38,12 @@ NODE_DIST="${VERIFY_TRACKING_NODE_DIST:-https://nodejs.org/dist}"
 # gets the two shims that are the whole user-facing surface.
 PREFIX="${VERIFY_TRACKING_PREFIX:-$HOME/.local/share/verify-tracking}"
 BIN_DIR="${VERIFY_TRACKING_BIN_DIR:-$HOME/.local/bin}"
+# Where runs save their reports and the dashboard. A globally installed CLI
+# otherwise grows a verification/ tree in whatever directory it was run from,
+# which makes "where is my dashboard" depend on the operator's cwd and lets a
+# `cd` silently start a second, separate set.
+CONFIG_FILE="$HOME/.config/verify-tracking/config.env"
+REPORTS_HOME="${VERIFY_TRACKING_REPORTS_HOME:-$HOME/dreamdata-tracking}"
 
 # Kept out of the shared ~/.cache/ms-playwright on purpose: the browser this
 # installer downloaded is then provably the browser the run launches, and an
@@ -71,6 +77,7 @@ command -v tar  >/dev/null 2>&1 || die "tar is required."
 printf 'Installing verify-tracking (%s/%s)\n' "$node_os" "$node_arch"
 say "runtime, packages and browser -> $PREFIX"
 say "commands                      -> $BIN_DIR"
+say "reports and dashboard         -> $REPORTS_HOME"
 
 # ---------------------------------------------------------------------------
 # 1. A Node the tool can run on
@@ -247,7 +254,31 @@ write_shim "verify-tracking" "dist/cli.js"
 write_shim "verify-tracking-mcp" "dist/mcp/server.js"
 
 # ---------------------------------------------------------------------------
-# 5. Sign in to Claude — the one step a human has to finish
+# 5. Where reports are saved
+# ---------------------------------------------------------------------------
+
+# The config file rather than the shim, even though the shim already exports
+# PLAYWRIGHT_BROWSERS_PATH: user-config.ts only fills in variables the
+# environment leaves unset, so a value exported by the shim would beat the
+# operator's own config.env entry and make that documented file silently
+# useless. Written here it sits at the same tier as any other setting, and can
+# be edited afterwards.
+#
+# An existing key is never rewritten — including the `export KEY=` form, which
+# the parser also accepts and resolves first-wins, so appending a second line
+# would announce a directory the CLI then ignores.
+step "Reports folder"
+mkdir -p "$(dirname "$CONFIG_FILE")"
+[ -f "$CONFIG_FILE" ] || : > "$CONFIG_FILE"
+if grep -Eq '^[[:space:]]*(export[[:space:]]+)?VERIFY_TRACKING_OUTPUT_DIR=' "$CONFIG_FILE"; then
+  say "already set in $CONFIG_FILE — leaving it alone"
+else
+  printf 'VERIFY_TRACKING_OUTPUT_DIR=%s\n' "$REPORTS_HOME" >> "$CONFIG_FILE"
+  say "reports and the dashboard will be saved in $REPORTS_HOME"
+fi
+
+# ---------------------------------------------------------------------------
+# 6. Sign in to Claude — the one step a human has to finish
 # ---------------------------------------------------------------------------
 
 # `curl … | sh` leaves this script's own text on stdin, so a child that prompts
@@ -296,19 +327,99 @@ else
 fi
 
 # ---------------------------------------------------------------------------
-# Done
+# 7. PATH
 # ---------------------------------------------------------------------------
 
-printf '\n==> Installed\n'
-"$BIN_DIR/verify-tracking" --version 2>/dev/null | sed 's/^/  /' || true
+# Appended for the operator rather than printed for them to paste. The people
+# this installer is for do not know what a shell profile is, and "now edit
+# ~/.zshrc" is the second place a handover stops.
+#
+# Every profile that already exists gets the line, not just the one implied by
+# $SHELL: a macOS login shell reads ~/.zprofile, an interactive one ~/.zshrc,
+# and bash reads ~/.bash_profile rather than ~/.bashrc — guessing a single file
+# is how the line lands somewhere that is never sourced. A file that does not
+# exist is left uncreated, so this never conjures a profile for a shell the
+# machine does not use.
+#
+# What it cannot do is take effect in the terminal that ran it: this script is
+# a child process, and no child can alter its parent's environment. So the
+# closing lines send the operator to a new terminal window rather than letting
+# them discover that on a `command not found`.
+PATH_LINE="export PATH=\"$BIN_DIR:\$PATH\""
+# BIN_DIR is a path, and a path is not a regex: an unescaped `.` in `.local`
+# would match any character, so a near-miss line could read as a hit. The class
+# is the full ERE metacharacter set, not just the BRE one — grep runs with -E,
+# and a home directory is free to contain a `+` or a `(`.
+bin_dir_re="$(printf '%s' "$BIN_DIR" | sed 's/[].[^$*+?(){}|\/\\]/\\&/g')"
+
+add_to_profile() {
+  profile="$1"
+  [ -f "$profile" ] || return 0
+  # Anchored, and only on an uncommented line: a commented-out or
+  # differently-worded mention must not read as "already configured". BIN_DIR
+  # has to end a PATH component too — as a bare substring, `~/.local/bin` is
+  # also inside `~/.local/bin2`, and a match there would skip a profile that
+  # never had the line.
+  if grep -Eq "^[[:space:]]*export[[:space:]]+PATH=.*${bin_dir_re}([:\"']|\$)" "$profile"; then
+    say "already in $profile"
+    return 0
+  fi
+  # A profile that cannot be written to is a PATH the operator has to set by
+  # hand, not a failed install — under `set -e` an unguarded append would take
+  # the whole run down over a read-only home.
+  if printf '\n# Added by the verify-tracking installer\n%s\n' "$PATH_LINE" >> "$profile" 2>/dev/null; then
+    say "added to $profile"
+  else
+    say "could not write $profile. Add this line to it yourself:"
+    printf '\n    %s\n' "$PATH_LINE"
+  fi
+}
 
+step "PATH"
 case ":${PATH}:" in
-  *":$BIN_DIR:"*) ;;
+  *":$BIN_DIR:"*)
+    say "$BIN_DIR is already on your PATH"
+    ;;
   *)
-    printf '\n  %s is not on your PATH. Add it, then reopen your terminal:\n\n' "$BIN_DIR"
-    printf "    echo 'export PATH=\"%s:\$PATH\"' >> ~/.zshrc\n" "$BIN_DIR"
+    for profile in "$HOME/.zshrc" "$HOME/.zprofile" "$HOME/.bashrc" "$HOME/.bash_profile"; do
+      add_to_profile "$profile"
+    done
+    # Nothing to append to means nothing was appended — print the line rather
+    # than claim a PATH change that did not happen.
+    if [ -f "$HOME/.zshrc" ] || [ -f "$HOME/.zprofile" ] \
+       || [ -f "$HOME/.bashrc" ] || [ -f "$HOME/.bash_profile" ]; then
+      :
+    else
+      say "no shell profile found. Add this line to yours:"
+      printf '\n    %s\n' "$PATH_LINE"
+    fi
     ;;
 esac
 
-printf '\n  Try it:\n\n    verify-tracking --url https://example.com --quick --no-save-report\n'
-printf '\n  Uninstall:\n\n    rm -rf %s %s/verify-tracking %s/verify-tracking-mcp\n\n' "$PREFIX" "$BIN_DIR" "$BIN_DIR"
+# ---------------------------------------------------------------------------
+# Done
+# ---------------------------------------------------------------------------
+
+printf '\n==> Installed\n'
+"$BIN_DIR/verify-tracking" --version 2>/dev/null | sed 's/^/  /' || true
+
+printf '\n  Reports and dashboard:\n\n    %s\n' "$REPORTS_HOME"
+printf '\n  Try it, from a new terminal window:\n\n    verify-tracking --slug dreamdata_io --url https://dreamdata.io/\n'
+
+# Claimed only where a browser can actually appear: --dashboard skips opening
+# one on a machine with nobody in front of it, and an installer that announces
+# a window that never arrives sends the operator looking for it.
+if [ -r /dev/tty ]; then
+  printf '\n  A browser window is opening with your dashboard. Type an account slug\n'
+  printf '  and a URL there to build your command, then open a new terminal window\n'
+  printf '  and run it.\n'
+fi
+# The reports folder is the operator's data and is deliberately left out: an
+# `rm -rf` line someone pastes without reading must not take their work with it.
+printf '\n  Uninstall (your reports folder is left in place):\n\n    rm -rf %s %s/verify-tracking %s/verify-tracking-mcp\n\n' "$PREFIX" "$BIN_DIR" "$BIN_DIR"
+
+# Opening the dashboard is the last thing, and never a reason to fail: it also
+# builds the page, so an operator who is looking at the empty state is reading
+# the instructions for their first check. It prints its own path, and skips the
+# browser on a machine with nobody in front of it.
+"$BIN_DIR/verify-tracking" --dashboard >/dev/null 2>&1 || true