visibly-cli 0.1.0

package/bin/visibly.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict'
+
+const { runSetup } = require('../src/setup')
+
+const args = process.argv.slice(2)
+const command = args[0]
+
+if (!command || command === 'help' || command === '--help' || command === '-h') {
+  console.log(`
+  Visibly CLI
+
+  Commands:
+    setup   Instrument your server to track AI bot visits
+
+  Usage:
+    npx visibly setup --domain-id <your-domain-id>
+
+  Options:
+    --domain-id   Your Visibly domain ID (found in the dashboard)
+    --help        Show this help message
+`)
+  process.exit(0)
+}
+
+if (command === 'setup') {
+  // Parse --domain-id flag
+  const domainIdIdx = args.indexOf('--domain-id')
+  const domainId = domainIdIdx !== -1 ? args[domainIdIdx + 1] : null
+
+  runSetup(domainId)
+  process.exit(0)
+}
+
+console.error(`\n  Unknown command: ${command}\n  Run "npx visibly --help" for usage.\n`)
+process.exit(1)

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "visibly-cli",
+  "version": "0.1.0",
+  "description": "Set up Visibly AI bot tracking on your server with one command",
+  "bin": {
+    "visibly": "bin/visibly.js"
+  },
+  "main": "./src/setup.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "visibly",
+    "ai",
+    "seo",
+    "bot-tracking",
+    "llm"
+  ],
+  "license": "MIT"
+}

package/src/detect.js

@@ -0,0 +1,91 @@
+'use strict'
+
+const fs   = require('fs')
+const path = require('path')
+
+/**
+ * Reads package.json from cwd and returns the detected framework.
+ * @returns {'next' | 'express' | 'unknown'}
+ */
+function detectFramework(cwd = process.cwd()) {
+  const pkgPath = path.join(cwd, 'package.json')
+
+  if (!fs.existsSync(pkgPath)) {
+    return 'unknown'
+  }
+
+  let pkg
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
+  } catch {
+    return 'unknown'
+  }
+
+  const deps = {
+    ...pkg.dependencies,
+    ...pkg.devDependencies,
+  }
+
+  // Next.js takes precedence — a custom Express server inside a Next.js app
+  // is still a Next.js project at its core.
+  if (deps['next']) return 'next'
+  if (deps['express']) return 'express'
+  return 'unknown'
+}
+
+/**
+ * Finds the middleware file for a Next.js project.
+ * Returns the path if it exists, or null if it needs to be created.
+ * @returns {{ path: string, exists: boolean }}
+ */
+function findNextMiddleware(cwd = process.cwd()) {
+  const candidates = [
+    'middleware.ts',
+    'middleware.js',
+    'src/middleware.ts',
+    'src/middleware.js',
+  ]
+
+  for (const rel of candidates) {
+    const abs = path.join(cwd, rel)
+    if (fs.existsSync(abs)) return { path: abs, exists: true }
+  }
+
+  // Default creation path: src/middleware.ts if src/ exists, else middleware.ts at root
+  const srcDir = path.join(cwd, 'src')
+  const defaultPath = fs.existsSync(srcDir)
+    ? path.join(srcDir, 'middleware.ts')
+    : path.join(cwd, 'middleware.ts')
+
+  return { path: defaultPath, exists: false }
+}
+
+/**
+ * Finds the Express entry file.
+ * @returns {string | null} absolute path, or null if not found
+ */
+function findExpressEntry(cwd = process.cwd()) {
+  const candidates = [
+    'server.js',
+    'server.ts',
+    'app.js',
+    'app.ts',
+    'index.js',
+    'index.ts',
+    'src/server.js',
+    'src/server.ts',
+    'src/app.js',
+    'src/app.ts',
+    'src/index.js',
+    'src/index.ts',
+  ]
+
+  for (const rel of candidates) {
+    const abs = path.join(cwd, rel)
+    if (fs.existsSync(abs)) return abs
+  }
+
+  return null
+}
+
+module.exports = { detectFramework, findNextMiddleware, findExpressEntry }

package/src/inject-express.js

@@ -0,0 +1,49 @@
+'use strict'
+
+const fs = require('fs')
+const { expressBlock } = require('./snippets')
+
+const ALREADY_INJECTED_MARKER = '// Visibly bot tracking'
+
+/**
+ * Injects the Visibly tracking middleware into an Express entry file.
+ *
+ * Strategy: find the line where `express()` is called and assigned
+ * (e.g. `const app = express()`) and insert the app.use() block
+ * immediately after it. Falls back to appending at end of file.
+ */
+function injectIntoExpress(filePath) {
+  const source = fs.readFileSync(filePath, 'utf8')
+
+  // Guard: already injected
+  if (source.includes(ALREADY_INJECTED_MARKER)) {
+    return { action: 'already_injected', path: filePath }
+  }
+
+  const lines = source.split('\n')
+
+  // Look for the app initialisation line: `= express()` or `express()`
+  let insertIdx = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (/=\s*express\s*\(/.test(lines[i]) || /^const app\s*=/.test(lines[i])) {
+      insertIdx = i
+      break
+    }
+  }
+
+  const block = expressBlock()
+
+  if (insertIdx === -1) {
+    // Fallback: append at end of file
+    const patched = source.trimEnd() + '\n' + block + '\n'
+    fs.writeFileSync(filePath, patched, 'utf8')
+    return { action: 'appended', path: filePath, warning: 'Could not find Express app initialisation — snippet appended at end of file. Review placement manually.' }
+  }
+
+  // Insert after the found line
+  lines.splice(insertIdx + 1, 0, block)
+  fs.writeFileSync(filePath, lines.join('\n'), 'utf8')
+  return { action: 'injected', path: filePath }
+}
+
+module.exports = { injectIntoExpress }

package/src/inject-next.js

@@ -0,0 +1,71 @@
+'use strict'
+
+const fs   = require('fs')
+const path = require('path')
+const { trackingBlock, nextMiddlewareTemplate } = require('./snippets')
+
+const ALREADY_INJECTED_MARKER = '// Visibly bot tracking'
+
+/**
+ * Creates a brand-new middleware.ts at the given path.
+ * Used when no middleware file exists yet.
+ */
+function createMiddleware(filePath, domainId) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, nextMiddlewareTemplate(domainId), 'utf8')
+  return { action: 'created', path: filePath }
+}
+
+/**
+ * Injects the tracking block into an existing middleware file.
+ *
+ * Strategy: find the last `return NextResponse.next()` or `NextResponse.next()`
+ * call and insert the tracking block immediately before it.
+ * Uses a line-by-line approach so we don't corrupt the rest of the file.
+ */
+function injectIntoMiddleware(filePath) {
+  const source = fs.readFileSync(filePath, 'utf8')
+
+  // Guard: already injected
+  if (source.includes(ALREADY_INJECTED_MARKER)) {
+    return { action: 'already_injected', path: filePath }
+  }
+
+  const lines = source.split('\n')
+
+  // Find the last line that contains `return NextResponse.next()`
+  // We look from the bottom up so we target the final return in the middleware function.
+  let insertIdx = -1
+  let indent = '  '
+
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const trimmed = lines[i].trim()
+    // Match any return statement that involves NextResponse.next():
+    //   return NextResponse.next()
+    //   return response || NextResponse.next()
+    //   return NextResponse.next({ request })
+    if (trimmed.startsWith('return') && trimmed.includes('NextResponse.next(')) {
+      insertIdx = i
+      // Detect indentation from that line
+      const match = lines[i].match(/^(\s+)/)
+      if (match) indent = match[1]
+      break
+    }
+  }
+
+  if (insertIdx === -1) {
+    // Fallback: couldn't find a return statement — append to end of file with a warning
+    const block = trackingBlock('  ')
+    const patched = source.trimEnd() + '\n\n' + block + '\n'
+    fs.writeFileSync(filePath, patched, 'utf8')
+    return { action: 'appended', path: filePath, warning: 'Could not find "return NextResponse.next()" — snippet appended at end of file. Review placement manually.' }
+  }
+
+  // Insert tracking block before the return line
+  const block = trackingBlock(indent)
+  lines.splice(insertIdx, 0, block)
+  fs.writeFileSync(filePath, lines.join('\n'), 'utf8')
+  return { action: 'injected', path: filePath }
+}
+
+module.exports = { createMiddleware, injectIntoMiddleware }

package/src/setup.js

@@ -0,0 +1,122 @@
+'use strict'
+
+const fs   = require('fs')
+const path = require('path')
+const { detectFramework, findNextMiddleware, findExpressEntry } = require('./detect')
+const { createMiddleware, injectIntoMiddleware } = require('./inject-next')
+const { injectIntoExpress } = require('./inject-express')
+const { manualSnippet } = require('./snippets')
+
+const ENV_KEY = 'VISIBLY_DOMAIN_ID'
+
+/**
+ * Writes or updates VISIBLY_DOMAIN_ID in .env.local.
+ * Creates the file if it doesn't exist.
+ * Updates the existing line if the key is already present.
+ */
+function writeEnvLocal(domainId, cwd = process.cwd()) {
+  const envPath = path.join(cwd, '.env.local')
+  const line = `${ENV_KEY}=${domainId}`
+
+  if (!fs.existsSync(envPath)) {
+    fs.writeFileSync(envPath, line + '\n', 'utf8')
+    return { action: 'created', path: envPath }
+  }
+
+  let contents = fs.readFileSync(envPath, 'utf8')
+
+  if (contents.includes(ENV_KEY)) {
+    // Replace existing line
+    contents = contents.replace(new RegExp(`^${ENV_KEY}=.*$`, 'm'), line)
+    fs.writeFileSync(envPath, contents, 'utf8')
+    return { action: 'updated', path: envPath }
+  }
+
+  // Append to end (ensure trailing newline before appending)
+  if (!contents.endsWith('\n')) contents += '\n'
+  fs.writeFileSync(envPath, contents + line + '\n', 'utf8')
+  return { action: 'appended', path: envPath }
+}
+
+/**
+ * Main setup command.
+ * @param {string} domainId
+ * @param {{ cwd?: string }} options
+ */
+function runSetup(domainId, { cwd = process.cwd() } = {}) {
+  if (!domainId) {
+    console.error('\nError: --domain-id is required.\n')
+    console.error('  Usage: npx visibly setup --domain-id <your-domain-id>\n')
+    process.exit(1)
+  }
+
+  console.log('\n  Setting up Visibly bot tracking...\n')
+
+  const framework = detectFramework(cwd)
+
+  // ── Next.js ────────────────────────────────────────────────────────────────
+  if (framework === 'next') {
+    const { path: mwPath, exists } = findNextMiddleware(cwd)
+
+    let result
+    if (exists) {
+      result = injectIntoMiddleware(mwPath)
+    } else {
+      result = createMiddleware(mwPath, domainId)
+    }
+
+    const relPath = path.relative(cwd, result.path)
+
+    if (result.action === 'already_injected') {
+      console.log(`  ✓ Tracking already present in ${relPath} — no changes made.`)
+    } else if (result.action === 'created') {
+      console.log(`  ✓ Created ${relPath}`)
+    } else if (result.action === 'injected') {
+      console.log(`  ✓ Injected tracking into ${relPath}`)
+    } else if (result.action === 'appended') {
+      console.log(`  ✓ Appended tracking to ${relPath}`)
+      if (result.warning) console.log(`  ⚠ ${result.warning}`)
+    }
+
+    const envResult = writeEnvLocal(domainId, cwd)
+    console.log(`  ✓ ${envResult.action === 'created' ? 'Created' : 'Updated'} .env.local with ${ENV_KEY}`)
+
+    console.log('\n  Done! Deploy your site to start recording bot visits.\n')
+    return
+  }
+
+  // ── Express ────────────────────────────────────────────────────────────────
+  if (framework === 'express') {
+    const entryPath = findExpressEntry(cwd)
+
+    if (!entryPath) {
+      console.log('  Express detected but entry file not found.')
+      console.log(manualSnippet(domainId))
+      process.exit(0)
+    }
+
+    const result = injectIntoExpress(entryPath)
+    const relPath = path.relative(cwd, result.path)
+
+    if (result.action === 'already_injected') {
+      console.log(`  ✓ Tracking already present in ${relPath} — no changes made.`)
+    } else if (result.action === 'injected') {
+      console.log(`  ✓ Injected tracking into ${relPath}`)
+    } else if (result.action === 'appended') {
+      console.log(`  ✓ Appended tracking to ${relPath}`)
+      if (result.warning) console.log(`  ⚠ ${result.warning}`)
+    }
+
+    const envResult = writeEnvLocal(domainId, cwd)
+    console.log(`  ✓ ${envResult.action === 'created' ? 'Created' : 'Updated'} .env.local with ${ENV_KEY}`)
+
+    console.log('\n  Done! Deploy your site to start recording bot visits.\n')
+    return
+  }
+
+  // ── Unknown / fallback ─────────────────────────────────────────────────────
+  console.log('  Framework not detected automatically.')
+  console.log(manualSnippet(domainId))
+}
+
+module.exports = { runSetup }

package/src/snippets.js

@@ -0,0 +1,75 @@
+'use strict'
+
+const BOT_PATTERN = 'GPTBot|ClaudeBot|anthropic-ai|PerplexityBot|Google-Extended|ChatGPT-User'
+
+/**
+ * The 4-line tracking block injected into existing middleware files.
+ * Indented with 2 spaces to match typical Next.js middleware style.
+ */
+function trackingBlock(indent = '  ') {
+  return [
+    `${indent}// Visibly bot tracking — added by npx visibly setup`,
+    `${indent}const _vua = request.headers.get('user-agent') ?? ''`,
+    `${indent}if (/${BOT_PATTERN}/.test(_vua))`,
+    `${indent}  fetch(\`https://visibly.io/api/bot-visit/\${process.env.VISIBLY_DOMAIN_ID}\`, { method: 'POST', headers: { 'user-agent': _vua } })`,
+    `${indent}// end Visibly`,
+  ].join('\n')
+}
+
+/**
+ * Full middleware.ts template — used when no middleware.ts exists yet.
+ */
+function nextMiddlewareTemplate(domainId) {
+  return `import { NextRequest, NextResponse } from 'next/server'
+
+export function middleware(request: NextRequest) {
+  // Visibly bot tracking — added by npx visibly setup
+  const _vua = request.headers.get('user-agent') ?? ''
+  if (/${BOT_PATTERN}/.test(_vua))
+    fetch(\`https://visibly.io/api/bot-visit/${domainId}\`, { method: 'POST', headers: { 'user-agent': _vua } })
+  // end Visibly
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+}
+`
+}
+
+/**
+ * Express middleware block injected after app initialisation.
+ */
+function expressBlock() {
+  return `
+// Visibly bot tracking — added by npx visibly setup
+app.use((req, _res, next) => {
+  const _vua = req.headers['user-agent'] || ''
+  if (/${BOT_PATTERN}/.test(_vua))
+    fetch(\`https://visibly.io/api/bot-visit/\${process.env.VISIBLY_DOMAIN_ID}\`, { method: 'POST', headers: { 'user-agent': _vua } })
+  next()
+})
+// end Visibly`
+}
+
+/**
+ * Manual snippet printed when framework is not detected.
+ */
+function manualSnippet(domainId) {
+  return `
+Framework not detected automatically. Add this to your server's request handler:
+
+  // Fire-and-forget — no await, no latency impact
+  const ua = <incoming user-agent header>
+  if (/${BOT_PATTERN}/.test(ua))
+    fetch('https://visibly.io/api/bot-visit/${domainId}', {
+      method: 'POST',
+      headers: { 'user-agent': ua }
+    })
+
+Your domain ID is already embedded above — no further configuration needed.
+`
+}
+
+module.exports = { trackingBlock, nextMiddlewareTemplate, expressBlock, manualSnippet }