foglift-sensor 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# Foglift Sensor CLI
+
+Install the Foglift Sensor in a code-built site with the publishable workspace
+identifier from Foglift AI Traffic (it is a capability identifier, not a secret
+API key):
+
+```bash
+npx foglift-sensor@latest init --token PUBLIC_WORKSPACE_ID
+```
+
+The CLI detects Next.js or Cloudflare Workers, installs the stable
+`@foglift/tracker` runtime, and composes around the existing request boundary or
+Worker code. For Next.js 16 it preserves and exports `proxy`; for older Next.js
+projects it keeps the `middleware` convention. Root/`src` placement and static
+custom `pageExtensions` are respected. The original source is preserved
+byte-for-byte in a neighboring `*.foglift-original.*` file and is never replaced
+on a later run.
+
+The tracker sends the request hostname with the workspace capability. Foglift
+accepts an event only when both identify the same workspace; a hostname alone
+cannot write analytics. If the URL cannot be inferred from package metadata, pass
+`--url https://example.com`.
+
+Equivalent one-shot commands:
+
+```bash
+pnpm dlx foglift-sensor@latest init --token PUBLIC_WORKSPACE_ID
+yarn dlx foglift-sensor@latest init --token PUBLIC_WORKSPACE_ID
+```
+
+After deploying the patched site, verify a recognized crawler request in
+[Foglift AI Traffic](https://foglift.io/app/data/crawlers).

package/dist/chunk-TUBJ5Q45.js

@@ -0,0 +1,336 @@
+// src/installer.ts
+import {
+  existsSync,
+  readFileSync,
+  renameSync,
+  writeFileSync
+} from "fs";
+import { randomBytes } from "crypto";
+import { basename, dirname, extname, join, relative, resolve } from "path";
+var SENSOR_MARKER = "Foglift Sensor installer \u2014 generated file";
+var TRACKER_PACKAGE = "@foglift/tracker@latest";
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function packageHas(root, dependency) {
+  const manifest = readJson(join(root, "package.json"));
+  if (!manifest) return false;
+  return ["dependencies", "devDependencies", "peerDependencies"].some((field) => {
+    const values = manifest[field];
+    return Boolean(values && typeof values === "object" && dependency in values);
+  });
+}
+function parseWranglerEntry(root) {
+  for (const name of ["wrangler.jsonc", "wrangler.json", "wrangler.toml"]) {
+    const path = join(root, name);
+    if (!existsSync(path)) continue;
+    const source = readFileSync(path, "utf8");
+    if (name.endsWith(".toml")) {
+      const match = source.match(/^\s*main\s*=\s*["']([^"']+)["']/m);
+      return { source: name, entry: match?.[1] ?? "src/index.ts" };
+    }
+    const withoutComments = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "").replace(/,\s*([}\]])/g, "$1");
+    try {
+      const parsed = JSON.parse(withoutComments);
+      return {
+        source: name,
+        entry: typeof parsed.main === "string" ? parsed.main : "src/index.ts"
+      };
+    } catch {
+      return { source: name, entry: "src/index.ts" };
+    }
+  }
+  return null;
+}
+function detectCodeStack(cwd) {
+  const root = resolve(cwd);
+  const manifest = readJson(join(root, "package.json"));
+  const dependencies = {
+    ...manifest?.dependencies ?? {},
+    ...manifest?.devDependencies ?? {}
+  };
+  if ("next" in dependencies) return { kind: "nextjs", source: "package.json" };
+  const wrangler = parseWranglerEntry(root);
+  if (wrangler) return { kind: "cloudflare", ...wrangler };
+  const packageSignals = [
+    ["remix", "@remix-run/node"],
+    ["nuxt", "nuxt"],
+    ["sveltekit", "@sveltejs/kit"],
+    ["astro", "astro"],
+    ["express", "express"]
+  ];
+  for (const [kind, dependency] of packageSignals) {
+    if (dependency in dependencies) return { kind, source: "package.json" };
+  }
+  return { kind: "unknown", source: null };
+}
+function runtimeInstallCommand(cwd) {
+  if (existsSync(join(cwd, "pnpm-lock.yaml"))) {
+    return { command: "pnpm", args: ["add", TRACKER_PACKAGE] };
+  }
+  if (existsSync(join(cwd, "yarn.lock"))) {
+    return { command: "yarn", args: ["add", TRACKER_PACKAGE] };
+  }
+  return { command: "npm", args: ["install", TRACKER_PACKAGE] };
+}
+function normalizeProjectUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  try {
+    const url = new URL(value.includes("://") ? value : `https://${value}`);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    return `${url.protocol}//${url.hostname.toLowerCase()}`;
+  } catch {
+    return null;
+  }
+}
+function inferProjectUrl(cwd) {
+  const fromEnv = normalizeProjectUrl(
+    process.env.FOGLIFT_SENSOR_URL ?? process.env.VERCEL_PROJECT_PRODUCTION_URL
+  );
+  if (fromEnv) return fromEnv;
+  const manifest = readJson(join(cwd, "package.json"));
+  return normalizeProjectUrl(manifest?.homepage);
+}
+async function verifySensorEvent(input) {
+  const targetOrigin = normalizeProjectUrl(input.url);
+  if (!targetOrigin) throw new Error("A valid deployed http(s) URL is required for verification");
+  const nonce = input.nonce ?? randomBytes(16).toString("hex");
+  if (!/^[a-f0-9]{32}$/.test(nonce)) throw new Error("Invalid verification nonce");
+  const fetcher = input.fetcher ?? fetch;
+  const probeUrl = `${targetOrigin}/.well-known/foglift-sensor/${nonce}`;
+  const probe = await fetcher(probeUrl, {
+    headers: { "User-Agent": "FogliftSensorVerify/1.0 GPTBot" },
+    redirect: "manual",
+    signal: AbortSignal.timeout(1e4)
+  });
+  const fogliftOrigin = (input.fogliftOrigin ?? "https://foglift.io").replace(/\/$/, "");
+  const statusUrl = new URL("/api/v1/sensor-install/verify", fogliftOrigin);
+  statusUrl.searchParams.set("domain", new URL(targetOrigin).hostname);
+  statusUrl.searchParams.set("nonce", nonce);
+  const attempts = Math.max(1, Math.min(input.attempts ?? 15, 30));
+  const wait = input.wait ?? ((milliseconds) => new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds)));
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (attempt > 0) await wait(1e3);
+    const status = await fetcher(statusUrl.toString(), {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!status.ok) throw new Error(`Foglift verification returned ${status.status}`);
+    const body = await status.json();
+    if (body.observed === true) {
+      return { observed: true, nonce, probeStatus: probe.status };
+    }
+  }
+  return { observed: false, nonce, probeStatus: probe.status };
+}
+function sidecarPath(entry) {
+  const extension = extname(entry);
+  return join(dirname(entry), `${basename(entry, extension)}.foglift-original${extension}`);
+}
+function importPath(from, target) {
+  const extension = extname(target);
+  const withoutExtension = target.slice(0, -extension.length);
+  const path = relative(dirname(from), withoutExtension).replaceAll("\\", "/");
+  return path.startsWith(".") ? path : `./${path}`;
+}
+function trackerOptions(token, next) {
+  const fields = [token ? `siteToken: ${JSON.stringify(token)}` : null, next ? `next: ${next}` : null].filter(Boolean);
+  return `{ ${fields.join(", ")} }`;
+}
+function nextWrapper(entry, original, token, convention) {
+  if (!original) {
+    return `// ${SENSOR_MARKER}
+import { trackAITraffic } from "@foglift/tracker/nextjs";
+
+export const ${convention} = trackAITraffic(${trackerOptions(token)});
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
+};
+`;
+  }
+  const specifier = importPath(entry, original);
+  const candidate = `preservedModule.${convention} ?? preservedModule.default`;
+  return `// ${SENSOR_MARKER}
+import { trackAITraffic, type NextMiddleware } from "@foglift/tracker/nextjs";
+import * as existingModule from ${JSON.stringify(specifier)};
+
+const preservedModule = existingModule as Record<string, unknown>;
+const existingMiddlewareCandidate = ${candidate};
+
+if (typeof existingMiddlewareCandidate !== "function") {
+  throw new Error("Foglift Sensor could not find the preserved ${convention} export");
+}
+const existingMiddleware = existingMiddlewareCandidate as NextMiddleware;
+
+export * from ${JSON.stringify(specifier)};
+export const ${convention} = trackAITraffic(${trackerOptions(token, "existingMiddleware")});
+`;
+}
+function cloudflareWrapper(entry, original, token) {
+  const specifier = importPath(entry, original);
+  return `// ${SENSOR_MARKER}
+import { trackAITrafficWorker } from "@foglift/tracker/cloudflare";
+import existingWorker from ${JSON.stringify(specifier)};
+
+if (!existingWorker || typeof existingWorker.fetch !== "function") {
+  throw new Error("Foglift Sensor requires a default Worker object with a fetch handler");
+}
+
+const existingFetch = existingWorker.fetch.bind(existingWorker);
+const sensorFetch = trackAITrafficWorker(${trackerOptions(token, "existingFetch")});
+
+export default {
+  ...existingWorker,
+  fetch: sensorFetch,
+};
+`;
+}
+function containsMarker(path) {
+  return existsSync(path) && readFileSync(path, "utf8").includes(SENSOR_MARKER);
+}
+function preserveAndWrite(entry, wrapper) {
+  const original = sidecarPath(entry);
+  if (existsSync(original)) {
+    throw new Error(`Refusing to replace existing preserved file: ${original}`);
+  }
+  const temporary = `${entry}.foglift-tmp`;
+  writeFileSync(temporary, wrapper, { flag: "wx" });
+  try {
+    renameSync(entry, original);
+    renameSync(temporary, entry);
+  } catch (error) {
+    if (existsSync(original) && !existsSync(entry)) renameSync(original, entry);
+    throw error;
+  }
+  return [entry, original];
+}
+function fallbackInstructions() {
+  return [
+    "Foglift did not recognize a supported code adapter.",
+    "For nginx, mirror recognized crawler requests to https://foglift.io/api/v1/crawler-analytics and forward the original Host header.",
+    "For generic middleware, report recognized crawler requests from the server and preserve the original request hostname.",
+    "Open https://foglift.io/docs/sensor for the safe, compose-without-replacing examples."
+  ].join("\n");
+}
+function nextMajorVersion(root) {
+  const manifest = readJson(join(root, "package.json"));
+  const dependencies = {
+    ...manifest?.dependencies ?? {},
+    ...manifest?.devDependencies ?? {}
+  };
+  const version = dependencies.next;
+  if (typeof version !== "string") return null;
+  const match = version.match(/(?:^|[^0-9])(\d+)(?:\.|$)/);
+  return match ? Number.parseInt(match[1], 10) : null;
+}
+function configuredPageExtensions(root) {
+  for (const name of [
+    "next.config.ts",
+    "next.config.mts",
+    "next.config.cts",
+    "next.config.js",
+    "next.config.mjs",
+    "next.config.cjs"
+  ]) {
+    const path = join(root, name);
+    if (!existsSync(path)) continue;
+    const source = readFileSync(path, "utf8");
+    const array = source.match(/\bpageExtensions\s*:\s*\[([\s\S]*?)\]/)?.[1];
+    if (!array) return [];
+    return Array.from(array.matchAll(/["'`]([^"'`]+)["'`]/g), (match) => match[1]).filter(
+      (extension) => !extension.includes("/") && /(?:^|\.)(?:[cm]?[jt]sx?)$/.test(extension)
+    );
+  }
+  return [];
+}
+function conventionFileNames(convention, pageExtensions) {
+  const configured = pageExtensions.map((extension) => `${convention}.${extension}`);
+  return [...configured, `${convention}.ts`, `${convention}.js`, `${convention}.mjs`];
+}
+function nextEntry(root) {
+  const pageExtensions = configuredPageExtensions(root);
+  const preferredConvention = (nextMajorVersion(root) ?? 0) >= 16 ? "proxy" : "middleware";
+  const conventionOrder = preferredConvention === "proxy" ? ["proxy", "middleware"] : ["middleware", "proxy"];
+  for (const convention of conventionOrder) {
+    for (const name of conventionFileNames(convention, pageExtensions)) {
+      for (const prefix of ["", "src/"]) {
+        const path = join(root, `${prefix}${name}`);
+        if (existsSync(path)) return { entry: path, convention };
+      }
+    }
+  }
+  const sourceRoot = existsSync(join(root, "src/app")) || existsSync(join(root, "src/pages"));
+  const fileName = conventionFileNames(preferredConvention, pageExtensions)[0];
+  return {
+    entry: join(root, sourceRoot ? "src" : "", fileName),
+    convention: preferredConvention
+  };
+}
+function applySensorInstall(input) {
+  const root = resolve(input.cwd);
+  const stack = detectCodeStack(root);
+  const url = normalizeProjectUrl(input.url) ?? inferProjectUrl(root);
+  if (!["nextjs", "cloudflare"].includes(stack.kind)) {
+    return {
+      kind: stack.kind,
+      changedFiles: [],
+      fallback: `${stack.kind === "unknown" ? "" : `Detected ${stack.kind}.
+`}${fallbackInstructions()}`,
+      url
+    };
+  }
+  if (!input.token?.trim()) {
+    throw new Error("A public workspace token is required. Pass --token PUBLIC_WORKSPACE_ID.");
+  }
+  const supportedStack = stack;
+  const nextBoundary = supportedStack.kind === "nextjs" ? nextEntry(root) : null;
+  const entry = supportedStack.kind === "nextjs" ? nextBoundary.entry : join(root, supportedStack.entry);
+  if (containsMarker(entry)) {
+    return { kind: supportedStack.kind, changedFiles: [], url };
+  }
+  if (!packageHas(root, "@foglift/tracker")) {
+    const install = runtimeInstallCommand(root);
+    input.execute(install.command, install.args, root);
+  }
+  if (supportedStack.kind === "nextjs") {
+    if (!existsSync(entry)) {
+      writeFileSync(
+        entry,
+        nextWrapper(entry, null, input.token, nextBoundary.convention),
+        { flag: "wx" }
+      );
+      return { kind: "nextjs", changedFiles: [entry], url };
+    }
+    const original2 = sidecarPath(entry);
+    return {
+      kind: "nextjs",
+      changedFiles: preserveAndWrite(
+        entry,
+        nextWrapper(entry, original2, input.token, nextBoundary.convention)
+      ),
+      url
+    };
+  }
+  if (!existsSync(entry)) {
+    throw new Error(`Cloudflare Worker entry not found: ${relative(root, entry)}`);
+  }
+  const original = sidecarPath(entry);
+  return {
+    kind: "cloudflare",
+    changedFiles: preserveAndWrite(entry, cloudflareWrapper(entry, original, input.token)),
+    url
+  };
+}
+
+export {
+  detectCodeStack,
+  runtimeInstallCommand,
+  inferProjectUrl,
+  verifySensorEvent,
+  applySensorInstall
+};

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+declare function run(argv?: string[]): Promise<number>;
+
+export { run };

package/dist/cli.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import {
+  applySensorInstall,
+  verifySensorEvent
+} from "./chunk-TUBJ5Q45.js";
+
+// src/cli.ts
+import { spawnSync } from "child_process";
+function valueAfter(args, flag) {
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : void 0;
+}
+var execute = (command, args, cwd) => {
+  const result = spawnSync(command, args, { cwd, stdio: "inherit" });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(" ")} failed with exit ${result.status ?? "unknown"}`);
+  }
+};
+async function run(argv = process.argv.slice(2)) {
+  if (argv[0] !== "init") {
+    console.error("Usage: npx foglift-sensor@latest init --token PUBLIC_WORKSPACE_ID [--url https://example.com]");
+    return 1;
+  }
+  const result = applySensorInstall({
+    cwd: process.cwd(),
+    execute,
+    url: valueAfter(argv, "--url"),
+    token: valueAfter(argv, "--token")
+  });
+  if (result.fallback) {
+    console.log(result.fallback);
+    return 0;
+  }
+  if (result.changedFiles.length === 0) {
+    console.log(`Foglift Sensor is already composed with this ${result.kind} project.`);
+  } else {
+    console.log(`Foglift Sensor composed with ${result.kind}.`);
+    for (const file of result.changedFiles) console.log(`- ${file}`);
+  }
+  if (argv.includes("--verify")) {
+    if (!result.url) {
+      console.error("Verification needs --url https://your-deployed-site.example");
+      return 1;
+    }
+    const verification = await verifySensorEvent({ url: result.url });
+    if (!verification.observed) {
+      console.error("Foglift did not observe the new Sensor event. Deploy the patched site, then retry with --verify.");
+      return 2;
+    }
+    console.log(`Foglift Sensor verified (probe HTTP ${verification.probeStatus}; event persisted).`);
+  } else {
+    console.log("After deployment, rerun this command with --verify to prove a new persisted event.");
+  }
+  console.log(`AI Traffic: ${result.url ? `https://foglift.io/app/data/crawlers?site=${encodeURIComponent(result.url)}` : "https://foglift.io/app/data/crawlers"}`);
+  return 0;
+}
+run().then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});
+export {
+  run
+};

package/dist/installer.d.ts

@@ -0,0 +1,48 @@
+type DetectedCodeStack = {
+    kind: "nextjs";
+    source: "package.json";
+} | {
+    kind: "cloudflare";
+    source: string;
+    entry: string;
+} | {
+    kind: "remix" | "nuxt" | "sveltekit" | "astro" | "express";
+    source: "package.json";
+} | {
+    kind: "unknown";
+    source: null;
+};
+type CommandExecutor = (command: string, args: string[], cwd: string) => void;
+type SensorInstallResult = {
+    kind: DetectedCodeStack["kind"];
+    changedFiles: string[];
+    fallback?: string;
+    url: string | null;
+};
+type SensorVerificationResult = {
+    observed: boolean;
+    nonce: string;
+    probeStatus: number;
+};
+declare function detectCodeStack(cwd: string): DetectedCodeStack;
+declare function runtimeInstallCommand(cwd: string): {
+    command: string;
+    args: string[];
+};
+declare function inferProjectUrl(cwd: string): string | null;
+declare function verifySensorEvent(input: {
+    url: string;
+    fetcher?: typeof fetch;
+    nonce?: string;
+    attempts?: number;
+    wait?: (milliseconds: number) => Promise<void>;
+    fogliftOrigin?: string;
+}): Promise<SensorVerificationResult>;
+declare function applySensorInstall(input: {
+    cwd: string;
+    execute: CommandExecutor;
+    token?: string;
+    url?: string;
+}): SensorInstallResult;
+
+export { type CommandExecutor, type DetectedCodeStack, type SensorInstallResult, type SensorVerificationResult, applySensorInstall, detectCodeStack, inferProjectUrl, runtimeInstallCommand, verifySensorEvent };

package/dist/installer.js

@@ -0,0 +1,14 @@
+import {
+  applySensorInstall,
+  detectCodeStack,
+  inferProjectUrl,
+  runtimeInstallCommand,
+  verifySensorEvent
+} from "./chunk-TUBJ5Q45.js";
+export {
+  applySensorInstall,
+  detectCodeStack,
+  inferProjectUrl,
+  runtimeInstallCommand,
+  verifySensorEvent
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "foglift-sensor",
+  "version": "0.1.0",
+  "description": "Install the Foglift Sensor in a code-built site with one command.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "foglift-sensor": "dist/cli.js"
+  },
+  "main": "./dist/installer.js",
+  "types": "./dist/installer.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/installer.d.ts",
+      "import": "./dist/installer.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/cli.ts src/installer.ts --format esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "foglift",
+    "sensor",
+    "ai-crawler",
+    "nextjs",
+    "cloudflare",
+    "cli"
+  ],
+  "author": "Foglift <watson@foglift.io>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/banant2/Foglift.git"
+  },
+  "homepage": "https://foglift.io/sensor",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0"
+  }
+}