cssprobe-cli 0.1.0

package/docs/guide/installation.md

@@ -0,0 +1,230 @@
+# Installation Guide for LLM Agents
+
+You are an AI agent (opencode, Claude Code, Codex, Cursor, etc.). This guide is written for you. Do not make the human read it.
+
+## Quick Prompt (for humans to copy-paste)
+
+If a human pasted this to you, follow the instructions below:
+
+> Install and configure `cssprobe-cli` using the guide at `docs/guide/installation.md`. Then run `cssprobe-cli inspect <url> <selector>` to analyze the CSS layout of any page.
+
+---
+
+## What You're Installing
+
+`cssprobe-cli` is a CLI that lets you (the agent) inspect the runtime CSS of any web page — layout, scroll behavior, overflow, colors, backgrounds, fonts — all from the command line. It launches a real browser, captures computed styles and DOM structure, and produces a structured report with confidence levels.
+
+Humans should not type these commands. You should.
+
+---
+
+## Step 1: Install the Package
+
+```bash
+npm install -g cssprobe-cli
+```
+
+Or run without installing (slower but zero setup):
+
+```bash
+npx cssprobe-cli inspect https://example.com ".content"
+```
+
+Verify:
+
+```bash
+which cssprobe-cli && cssprobe-cli --version
+```
+
+If `command not found`, your Node.js global bin isn't on `PATH`:
+
+```bash
+export PATH="$(npm root -g)/../bin:$PATH"
+```
+
+---
+
+## Step 2: Install Browser
+
+cssprobe-cli uses Playwright to launch a real browser. Install Chromium:
+
+```bash
+npx playwright install chromium
+```
+
+Verify:
+
+```bash
+cssprobe-cli inspect https://example.com "body" --json | head -5
+```
+
+JSON output = it works. `Browser not installed` = run the install command above.
+
+---
+
+## Step 3: Basic Usage
+
+### Inspect a Public Page
+
+```bash
+# With explicit selector
+cssprobe-cli inspect https://example.com ".main-content"
+
+# Auto-detect root element
+cssprobe-cli inspect https://example.com
+
+# Local HTML file
+cssprobe-cli inspect ./test.html ".container"
+```
+
+### JSON Output (for programmatic consumption)
+
+```bash
+cssprobe-cli inspect https://example.com ".content" --json
+cssprobe-cli --json inspect https://example.com ".content" | jq '.findings[] | {id, confidence, message}'
+```
+
+---
+
+## Step 4: Login-Protected Pages
+
+Many pages require authentication. cssprobe-cli supports three approaches:
+
+### Option A: Import Cookies from Browser Export
+
+1. Export cookies from your browser in Netscape format (e.g., using "EditThisCookie" extension or browser dev tools)
+2. Import into cssprobe-cli:
+
+```bash
+cssprobe-cli state-import cookies.txt --out ~/.cssprobe-cli/states/mysite.json
+```
+
+3. Use the state file:
+
+```bash
+cssprobe-cli inspect https://mysite.com/page ".target" --state ~/.cssprobe-cli/states/mysite.json
+```
+
+### Option B: Interactive Login
+
+```bash
+cssprobe-cli login https://mysite.com
+# Browser opens → complete login manually → press Enter
+# State saved to ~/.cssprobe-cli/states/mysite.com.json
+```
+
+Then use:
+
+```bash
+cssprobe-cli inspect https://mysite.com/page ".target" --state ~/.cssprobe-cli/states/mysite.com.json
+```
+
+### Option C: Merge Cookies into Existing State
+
+```bash
+cssprobe-cli state-import new-cookies.txt --merge existing-state.json --out updated.json
+```
+
+---
+
+## Step 5: Understand the Output
+
+### Markdown Report (default)
+
+```
+# cssprobe-cli report
+viewport: 1280×720 | root: .container | nodes: 18
+confidence: DEFINITE 8 | INDEFINITE 0 | UNVERIFIABLE 1
+
+## Ancestor chain (root→html)
+...
+
+## DOM tree (6 levels deep)
+...
+
+## Findings
+- ⚠ all heights are % or missing [UNVERIFIABLE] @ div.container
+- ✔ div.modal-body scrollable (scrollHeight 2040 > clientHeight 576) [DEFINITE]
+- ⚠ div.content overflows parent [DEFINITE]
+```
+
+### Confidence Levels
+
+| Level | Meaning |
+|-------|---------|
+| **DEFINITE** | Based on computed values (facts) or accessible declared values |
+| **INDEFINITE** | Declared value uses `%` — resolves at runtime |
+| **UNVERIFIABLE** | Declared value missing or from blocked cross-origin stylesheet |
+
+### JSON Output
+
+```json
+{
+  "meta": { "rootSelector": ".container", "viewport": {...}, "nodeCount": 18 },
+  "snapshot": { "ancestors": [...], "tree": {...} },
+  "findings": [
+    { "id": "anchor-missing", "level": "warning", "confidence": "UNVERIFIABLE", "message": "..." },
+    { "id": "scrollable", "level": "info", "confidence": "DEFINITE", "message": "..." }
+  ],
+  "summary": { "total": 9, "confidence": { "DEFINITE": 8, "INDEFINITE": 0, "UNVERIFIABLE": 1 } }
+}
+```
+
+---
+
+## Common Failures Agents Face
+
+**"Browser not installed"**
+→ Run `npx playwright install chromium`.
+
+**"File not found"**
+→ Check the URL or file path. Local files need to exist on disk.
+
+**"Could not auto-detect a root element"**
+→ Provide an explicit selector: `cssprobe-cli inspect <url> <selector>`
+
+**"No valid cookies found"**
+→ Cookie file must be Netscape format (tab-separated: `domain\tflag\tpath\tsecure\texpires\tname\tvalue`).
+
+**"collector bundle not found"**
+→ Run `npm run build` in the cssprobe-cli project directory.
+
+**Cross-origin stylesheet blocked**
+→ This is expected. Declared values from blocked sheets are marked UNVERIFIABLE. Computed values from getComputedStyle() are still accurate.
+
+**Page needs login**
+→ Use `cssprobe-cli login <url>` for interactive login, or `cssprobe-cli state-import cookies.txt` to import cookies.
+
+---
+
+## Environment Variables (Skip Config)
+
+```bash
+export CSSPROBE_BROWSER=chromium
+export CSSPROBE_DEPTH=6
+export CSSPROBE_HEADED=true
+export CSSPROBE_PROFILE=default
+```
+
+Priority (highest to lowest):
+1. CLI flags: `--browser`, `--depth`, `--headed`
+2. Environment variables: `CSSPROBE_BROWSER`, `CSSPROBE_DEPTH`, `CSSPROBE_HEADED`
+3. Config file: `~/.cssprobe-clirc`
+
+---
+
+## The One-Liner
+
+For agents that trust copy-paste:
+
+```bash
+npm install -g cssprobe-cli && npx playwright install chromium && cssprobe-cli inspect https://example.com "body"
+```
+
+---
+
+## Done
+
+You now have programmatic control over CSS inspection. Analyze layout, detect overflow, check scroll behavior, verify anchors — all from a terminal an agent can automate.
+
+If something breaks: check that Chromium is installed first. 90% of issues are missing browsers. The other 10% are wrong selectors.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "cssprobe-cli",
+  "version": "0.1.0",
+  "description": "Runtime CSS probe — inspect layout, colors, backgrounds, fonts and more in a live browser. AI agents and shell automation.",
+  "keywords": [
+    "css",
+    "inspect",
+    "layout",
+    "dom",
+    "forensics",
+    "debug",
+    "browser",
+    "agent",
+    "automation"
+  ],
+  "homepage": "https://github.com/mack-peng/cssprobe-cli#readme",
+  "repository": "github:mack-peng/cssprobe-cli",
+  "license": "MIT",
+  "author": "strikingly",
+  "main": "dist/index.js",
+  "bin": {
+    "cssprobe-cli": "./bin/cssprobe-cli.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "AGENTS.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.js",
+    "typecheck": "tsc --noEmit",
+    "test": "npx tsx --test tests/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "playwright-core": "^1.48.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.24.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.5.0"
+  }
+}