@doxbrix/doxloop 0.1.5 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doxbrix/doxloop",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "A local-first documentation agent CLI for Codex, Claude Code, and Gemini.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -18,13 +18,22 @@
   "files": [
     "dist",
     "assets",
+    "contracts",
     "docs",
+    "scripts/test-auto-screenshot.mjs",
     "skills/doxloop-authoring",
     "skills/doxloop-doxbrix",
     "README.md",
     "CHANGELOG.md",
     "SECURITY.md",
-    "LICENSE"
+    "LICENSE",
+    "!dist/**/*.map",
+    "!assets/marketing/**",
+    "!assets/social/**",
+    "vendor/doxbrix-import/dist",
+    "vendor/doxbrix-import/LICENSE",
+    "vendor/doxbrix-import/UPSTREAM.json",
+    "vendor/doxbrix-import/README.md"
   ],
   "exports": {
     "./generator-api": {
@@ -42,25 +51,39 @@
   },
   "scripts": {
     "build": "pnpm run build:core && pnpm run build:generators",
-    "build:core": "rm -rf dist && tsc -p tsconfig.json && node scripts/prepare-dist.mjs",
+    "build:core": "rm -rf dist && pnpm run build:importer && tsc -p tsconfig.json && vite build --config vite.ui.config.ts && node scripts/prepare-dist.mjs",
     "build:generators": "pnpm --filter './packages/*' run build",
-    "dev": "tsx src/cli.ts",
-    "typecheck": "tsc --noEmit && pnpm --filter './packages/*' run typecheck",
-    "pretest": "pnpm run build",
+    "dev": "pnpm run build:importer && tsx src/cli.ts",
+    "typecheck": "pnpm run build:importer && tsc --noEmit && tsc --noEmit -p tsconfig.ui.json && pnpm --filter './packages/*' run typecheck",
+    "build:test": "pnpm run build:importer && tsc -p tsconfig.json && pnpm run build:generators",
+    "pretest": "pnpm run build:test",
     "test": "vitest run",
+    "test:generator": "node scripts/ci-generator-smoke.mjs",
+    "test:screenshot": "node scripts/test-auto-screenshot.mjs",
+    "test:e2e": "playwright test",
     "eval:agents": "pnpm run build && node scripts/run-authoring-evals.mjs",
     "check": "pnpm run typecheck && pnpm run test && pnpm run validate:skill && pnpm run check:boundary",
     "release:local": "node scripts/release-local.mjs",
     "validate:skill": "node scripts/validate-skills.mjs",
     "check:boundary": "node scripts/check-boundary.mjs",
-    "prepack": "pnpm run check && pnpm run build && pnpm run check:boundary"
+    "prepack": "pnpm run check && pnpm run build && pnpm run check:boundary",
+    "test:existing-sites": "node scripts/ci-existing-sites.mjs",
+    "test:python-boundary": "node scripts/ci-python-sandbox.mjs",
+    "build:importer": "tsc -p vendor/doxbrix-import/tsconfig.json"
   },
   "dependencies": {
+    "@playwright/mcp": "0.0.79",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "axe-core": "^4.13.0",
     "chokidar": "^4.0.3",
     "cross-spawn": "^7.0.6",
     "fflate": "^0.8.2",
     "gray-matter": "^4.0.3",
-    "highlight.js": "^11.11.1"
+    "highlight.js": "^11.11.1",
+    "pixelmatch": "^7.1.0",
+    "pngjs": "^7.0.0",
+    "yaml": "^2.8.1"
   },
   "devDependencies": {
     "@doxbrix/doxloop-generator-docusaurus": "workspace:*",
@@ -73,20 +96,28 @@
     "@doxbrix/doxloop-generator-starlight": "workspace:*",
     "@doxbrix/doxloop-generator-static": "workspace:*",
     "@doxbrix/doxloop-generator-vitepress": "workspace:*",
+    "@playwright/test": "^1.62.1",
+    "@preact/preset-vite": "^2.10.2",
     "@types/cross-spawn": "^6.0.6",
     "@types/node": "^22.15.3",
+    "@types/pngjs": "^6.0.5",
+    "preact": "^10.27.2",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
+    "vite": "^7.3.1",
     "vitest": "^3.1.2"
   },
   "engines": {
-    "node": ">=20.12.0"
+    "node": ">=22.13.0"
   },
   "packageManager": "pnpm@10.33.0",
-  "main": "index.js",
-  "directories": {
-    "doc": "docs"
-  },
-  "keywords": [],
-  "author": ""
+  "keywords": [
+    "documentation",
+    "documentation-maintenance",
+    "cli",
+    "markdown",
+    "docusaurus",
+    "mkdocs"
+  ],
+  "author": "Doxbrix"
 }

package/scripts/test-auto-screenshot.mjs

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process'
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises'
+import { isAbsolute, join, resolve } from 'node:path'
+import process from 'node:process'
+import { agentArguments } from '../dist/author.js'
+import {
+  checkScreenCaptureBrowser,
+  screenCaptureProvider,
+} from '../dist/screen-capture-provider.js'
+
+const options = parseArguments(process.argv.slice(2))
+const workspace = resolve(options.output)
+const captureDirectory = join(workspace, '.doxloop', 'capture-output')
+const screenshot = join(workspace, 'standalone-capture.png')
+const logFile = join(workspace, 'agent.log')
+const resultFile = join(workspace, 'result.json')
+const target = new URL(options.route, options.url).href
+
+await mkdir(captureDirectory, { recursive: true })
+await rm(screenshot, { force: true })
+await rm(resultFile, { force: true })
+
+const readiness = await checkScreenCaptureBrowser()
+if (!readiness.available) fail(readiness.message)
+
+let response
+try {
+  response = await fetch(target, { signal: AbortSignal.timeout(10_000) })
+} catch (error) {
+  fail(`Application is not reachable at ${target}: ${error instanceof Error ? error.message : String(error)}`)
+}
+if (!response.ok) fail(`Application returned HTTP ${response.status} at ${target}.`)
+
+const provider = screenCaptureProvider(workspace, {
+  baseUrl: options.url,
+  screenshots: {
+    policy: 'required',
+    viewport: { width: options.width, height: options.height },
+  },
+})
+const prompt = `This is a standalone Doxloop screenshot smoke test.
+
+Use only the doxloop_capture browser tools for browser work.
+1. Navigate to ${target}.
+2. Wait until the page is stable.
+3. Inspect the browser snapshot and identify the visible page heading or primary landmark.
+4. Save one PNG screenshot with browser_take_screenshot using exactly this filename: standalone-capture.png
+5. Do not modify the application and do not create any other files.
+6. In your final response, report the visible heading and confirm the screenshot filename.
+
+The test fails unless browser_take_screenshot is called and the PNG exists.`
+const args = agentArguments(options.agent, prompt, {
+  mode: 'create',
+  nonInteractive: true,
+  captureProvider: provider,
+  captureRequired: true,
+})
+
+process.stdout.write(`Testing ${options.agent} screenshot capture at ${target}\n`)
+process.stdout.write(`Output: ${workspace}\n`)
+
+const execution = await run(options.agent, args, workspace, options.timeoutMinutes)
+await writeFile(logFile, execution.output, 'utf8')
+
+if (execution.exitCode !== 0) {
+  await writeResult(false, `Agent exited with status ${execution.exitCode}.`)
+  fail(`Agent exited with status ${execution.exitCode}. See ${logFile}`)
+}
+
+let bytes
+try {
+  bytes = await readFile(screenshot)
+} catch {
+  await writeResult(false, 'The agent completed without producing the PNG.')
+  fail(`The agent completed, but no screenshot was created at ${screenshot}. See ${logFile}`)
+}
+const pngSignature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+if (bytes.length < 1_024 || !bytes.subarray(0, 8).equals(pngSignature)) {
+  await writeResult(false, `The output is not a valid non-empty PNG (${bytes.length} bytes).`)
+  fail(`Invalid screenshot output at ${screenshot}.`)
+}
+
+const details = await stat(screenshot)
+await writeResult(true, `Captured a valid ${details.size}-byte PNG.`)
+process.stdout.write(`PASS: captured ${details.size} bytes at ${screenshot}\n`)
+
+async function writeResult(passed, message) {
+  await writeFile(resultFile, `${JSON.stringify({
+    passed,
+    agent: options.agent,
+    target,
+    screenshot: 'standalone-capture.png',
+    message,
+  }, null, 2)}\n`, 'utf8')
+}
+
+function run(command, args, cwd, timeoutMinutes) {
+  return new Promise((resolveRun, rejectRun) => {
+    const child = spawn(command, args, { cwd, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] })
+    let output = ''
+    const append = (chunk, destination) => {
+      const text = chunk.toString()
+      output += text
+      destination.write(text)
+    }
+    child.stdout.on('data', (chunk) => append(chunk, process.stdout))
+    child.stderr.on('data', (chunk) => append(chunk, process.stderr))
+    child.once('error', rejectRun)
+    child.once('exit', (code, signal) => {
+      clearTimeout(timer)
+      resolveRun({ exitCode: signal ? 1 : code ?? 1, output })
+    })
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM')
+    }, timeoutMinutes * 60_000)
+  })
+}
+
+function parseArguments(args) {
+  const parsed = {
+    agent: 'codex',
+    url: 'http://127.0.0.1:4317',
+    route: '/',
+    output: join('.doxloop', 'screenshot-smoke'),
+    width: 1440,
+    height: 900,
+    timeoutMinutes: 5,
+  }
+  for (let index = 0; index < args.length; index += 1) {
+    const key = args[index]
+    if (key === '--') continue
+    if (key === '--help') usage(0)
+    const value = args[index + 1]
+    if (!value || value.startsWith('--')) usage(1, `Missing value for ${key}.`)
+    if (key === '--agent' && (value === 'codex' || value === 'claude')) parsed.agent = value
+    else if (key === '--url') parsed.url = new URL(value).href
+    else if (key === '--route') parsed.route = value
+    else if (key === '--output') parsed.output = isAbsolute(value) ? value : resolve(value)
+    else if (key === '--width') parsed.width = positiveInteger(value, key)
+    else if (key === '--height') parsed.height = positiveInteger(value, key)
+    else if (key === '--timeout-minutes') parsed.timeoutMinutes = positiveInteger(value, key)
+    else usage(1, `Unknown or invalid option: ${key} ${value}`)
+    index += 1
+  }
+  return parsed
+}
+
+function positiveInteger(value, option) {
+  const number = Number(value)
+  if (!Number.isInteger(number) || number <= 0) usage(1, `${option} must be a positive integer.`)
+  return number
+}
+
+function usage(code, message) {
+  if (message) process.stderr.write(`${message}\n\n`)
+  process.stderr.write(`Usage: pnpm test:screenshot -- [options]\n\n`)
+  process.stderr.write(`  --agent codex|claude       Agent to test (default: codex)\n`)
+  process.stderr.write(`  --url URL                  Application base URL\n`)
+  process.stderr.write(`  --route PATH               Route to capture (default: /)\n`)
+  process.stderr.write(`  --output DIRECTORY         Isolated test output directory\n`)
+  process.stderr.write(`  --width PIXELS             Viewport width (default: 1440)\n`)
+  process.stderr.write(`  --height PIXELS            Viewport height (default: 900)\n`)
+  process.stderr.write(`  --timeout-minutes MINUTES  Agent timeout (default: 5)\n`)
+  process.exit(code)
+}
+
+function fail(message) {
+  process.stderr.write(`FAIL: ${message}\n`)
+  process.exit(1)
+}