cssprobe-cli 0.1.0

package/dist/engine/renderer.js

@@ -0,0 +1,159 @@
+"use strict";
+// Renderer — pure functions: Snapshot + Finding[] → Markdown or JSON.
+// No browser or filesystem access.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderMarkdown = renderMarkdown;
+exports.renderJSON = renderJSON;
+// ─── Node rendering (DOM tree) ───
+function renderNode(node, indent) {
+    const lines = [];
+    if (!node)
+        return lines;
+    const cls = node.classes.length ? `.${node.classes.join('.')}` : '';
+    const id = node.id ? `#${node.id}` : '';
+    const repeat = node.repeat ? ` \u00D7${node.repeat}` : '';
+    const m = node.metrics;
+    const s = node.shape || {};
+    const flag = [];
+    if (node.flags.overflowsViewport)
+        flag.push('\u26A0viewport-overflow');
+    if (node.flags.overflowsParent)
+        flag.push('\u26A0parent-overflow');
+    if (m.clientHeight === 0 && m.offsetHeight === 0)
+        flag.push('\u26A0collapsed(0px)');
+    if (node.flags.scrollable)
+        flag.push('\u2714scrollable');
+    if (node.flags.hasScrollY && !node.flags.scrollable) {
+        flag.push(`\u26A0overflow(${m.scrollHeight}>${m.clientHeight})but-overflow=${node.props.overflowY}`);
+    }
+    if (node.containingBlockModifiers.length) {
+        flag.push(`CB:${node.containingBlockModifiers.join(' ')}`);
+    }
+    const styleHint = node.inlineStyle ? ` style="${node.inlineStyle}"` : '';
+    const h = node.props.height;
+    const heightStr = h === 'auto' ? `auto\u2192${m.offsetHeight}px` : `${h}`;
+    const w = node.props.width;
+    const widthStr = w === 'auto' ? `auto\u2192${m.clientWidth}px` : `${w}`;
+    const mhStr = node.declared && node.declared['max-height'] ? ` maxH:${node.declared['max-height'].map(x => x.value).join(';')}` : '';
+    const shapeStr = s.role ? `[${s.role}${s.scrollTag ? ' ' + s.scrollTag : ''} h:${s.heightStrategy} w:${s.widthStrategy}]` : '';
+    lines.push(`${'  '.repeat(indent)}<${node.tag}${id}${cls}${styleHint}${repeat}> ${shapeStr} [${node.props.position},${node.props.display},h:${heightStr},w:${widthStr}${mhStr}] rect(${m.rect.width}\u00D7${m.rect.height}) bottom=${m.rectBottom} scroll=${m.clientHeight}/${m.scrollHeight}` +
+        (flag.length ? ` ${flag.join(' ')}` : '') +
+        (node.text ? ` \u300C${node.text.slice(0, 30)}\u300D` : ''));
+    for (const child of node.children) {
+        lines.push(...renderNode(child, indent + 1));
+    }
+    return lines;
+}
+function renderAncestors(chain) {
+    return chain.map(a => {
+        const dh = a.declared && a.declared.height ? a.declared.height.map(x => `${x.selector}\u2192${x.value}`).join('; ') : 'auto';
+        const dw = a.declared && a.declared.width ? a.declared.width.map(x => `${x.selector}\u2192${x.value}`).join('; ') : 'auto';
+        const mh = a.declared && a.declared['max-height'] ? a.declared['max-height'].map(x => `${x.selector}\u2192${x.value}`).join('; ') : null;
+        const maxPart = mh ? ` max-height:${mh}` : '';
+        const s = a.shape || {};
+        const shapeStr = s.role ? `[${s.role}${s.scrollTag ? ' ' + s.scrollTag : ''} h:${s.heightStrategy} w:${s.widthStrategy}]` : '';
+        return `${a.label} ${shapeStr} [${a.props.position},${a.props.display}] h:${dh}${maxPart} w:${dw} \u2192 ${a.metrics.clientWidth}\u00D7${a.metrics.offsetHeight}` +
+            (a.containingBlockModifiers.length ? ` CB:${a.containingBlockModifiers.join(' ')}` : '') +
+            (a.inlineStyle ? ` style="${a.inlineStyle}"` : '');
+    });
+}
+// ─── Findings rendering ───
+const CONF_BADGE = {
+    DEFINITE: 'DEFINITE',
+    INDEFINITE: 'INDEFINITE',
+    UNVERIFIABLE: 'UNVERIFIABLE',
+};
+function renderFindings(findings) {
+    const lines = [];
+    lines.push('## Findings');
+    if (findings.length === 0) {
+        lines.push('- 无异常发现');
+        return lines;
+    }
+    for (const f of findings) {
+        const badge = `[${CONF_BADGE[f.confidence]}]`;
+        const loc = f.location ? ` @ ${f.location}` : '';
+        lines.push(`- ${f.level === 'error' ? '\u26A0' : f.level === 'warning' ? '\u26A0' : '\u2714'} ${f.message} ${badge}${loc}`);
+        for (const ev of f.evidence.slice(0, 3)) {
+            if (ev.type === 'computed') {
+                lines.push(`    - computed ${ev.property}: ${ev.value}`);
+            }
+            else if (ev.type === 'declared') {
+                lines.push(`    - declared ${ev.property}: ${ev.value} (${ev.source || '?'})${ev.accessible ? '' : ' [inaccessible]'}`);
+            }
+        }
+    }
+    return lines;
+}
+function confidenceSummary(findings) {
+    const counts = findings.reduce((acc, f) => {
+        acc[f.confidence] = (acc[f.confidence] || 0) + 1;
+        return acc;
+    }, {});
+    const parts = [
+        `DEFINITE ${counts.DEFINITE || 0}`,
+        `INDEFINITE ${counts.INDEFINITE || 0}`,
+        `UNVERIFIABLE ${counts.UNVERIFIABLE || 0}`,
+    ];
+    return parts.join(' | ');
+}
+// ─── Markdown ───
+function renderMarkdown(snapshot, findings) {
+    const lines = [];
+    const vp = snapshot.viewport ? `${snapshot.viewport.width}\u00D7${snapshot.viewport.height}` : 'unknown';
+    lines.push('# cssprobe-cli report');
+    lines.push(`viewport: ${vp} | root: ${snapshot.rootSelector} | nodes: ${snapshot.nodeCount}`);
+    lines.push(`confidence: ${confidenceSummary(findings)}`);
+    if (snapshot.error) {
+        lines.push('');
+        lines.push(`\u26A0 ${snapshot.error}`);
+        if (snapshot.candidates && snapshot.candidates.length) {
+            lines.push(`Similar nodes: ${snapshot.candidates.join(', ')}`);
+        }
+        return lines.join('\n');
+    }
+    lines.push('');
+    lines.push(`## Ancestor chain (root\u2192${snapshot.upTo})`);
+    lines.push('```');
+    lines.push(...renderAncestors(snapshot.ancestors));
+    lines.push('```');
+    lines.push('');
+    lines.push(`## DOM tree (${snapshot.downDepth} levels deep)`);
+    lines.push('```');
+    lines.push(...renderNode(snapshot.tree, 0));
+    lines.push('```');
+    lines.push('');
+    lines.push(...renderFindings(findings));
+    if (snapshot.crossOriginBlocked && snapshot.crossOriginBlocked > 0) {
+        lines.push('');
+        lines.push('## Cross-origin limitation');
+        lines.push(`\u26A0 ${snapshot.crossOriginBlocked} stylesheet(s) blocked by browser security (SecurityError). Declared values from these sheets are marked UNVERIFIABLE \u2014 computed values from getComputedStyle() are still accurate.`);
+        if (snapshot.blockedSheetUrls && snapshot.blockedSheetUrls.length > 0) {
+            lines.push(`Blocked: ${snapshot.blockedSheetUrls.join(', ')}`);
+        }
+    }
+    return lines.join('\n');
+}
+// ─── JSON ───
+function renderJSON(snapshot, findings) {
+    const counts = findings.reduce((acc, f) => {
+        acc[f.confidence] = (acc[f.confidence] || 0) + 1;
+        return acc;
+    }, {});
+    return {
+        meta: {
+            rootSelector: snapshot.rootSelector,
+            viewport: snapshot.viewport,
+            nodeCount: snapshot.nodeCount,
+            crossOriginBlocked: snapshot.crossOriginBlocked,
+            blockedSheetUrls: snapshot.blockedSheetUrls,
+        },
+        snapshot: snapshot.error ? { error: snapshot.error, candidates: snapshot.candidates } : snapshot,
+        findings,
+        summary: {
+            total: findings.length,
+            confidence: { DEFINITE: counts.DEFINITE || 0, INDEFINITE: counts.INDEFINITE || 0, UNVERIFIABLE: counts.UNVERIFIABLE || 0 },
+        },
+    };
+}
+//# sourceMappingURL=renderer.js.map

package/dist/engine/types.d.ts

@@ -0,0 +1,130 @@
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Metrics {
+    rect: Rect;
+    rectBottom: number;
+    rectRight: number;
+    offsetHeight: number;
+    clientHeight: number;
+    scrollHeight: number;
+    clientWidth: number;
+    scrollWidth: number;
+}
+export interface Flags {
+    overflowsViewport: boolean;
+    overflowsParent: boolean;
+    hasScrollY: boolean;
+    hasScrollX: boolean;
+    scrollable: boolean;
+}
+/** A declared value found in a stylesheet rule, with provenance. */
+export interface DeclaredValue {
+    selector: string;
+    value: string;
+    href: string;
+    /** Whether the owning stylesheet was readable (cross-origin sheets are not). */
+    accessible: boolean;
+}
+export interface NodeProps {
+    position: string;
+    display: string;
+    height: string;
+    width: string;
+    minHeight: string;
+    maxHeight: string;
+    overflowY: string;
+    overflowX: string;
+    boxSizing: string;
+    flexDirection: string;
+    flexGrow: string;
+    flexShrink: string;
+    flexBasis: string;
+    minWidth?: string;
+    opacity?: string;
+    visibility?: string;
+    zIndex?: string;
+    margin?: string;
+    padding?: string;
+    transform?: string;
+    filter?: string;
+    perspective?: string;
+    willChange?: string;
+    contain?: string;
+    [key: string]: string | undefined;
+}
+export interface ShapeInfo {
+    role: string;
+    scrollTag: string;
+    heightStrategy: string;
+    widthStrategy: string;
+    isFlexChild: boolean;
+}
+export interface TreeNode {
+    tag: string;
+    id: string | null;
+    classes: string[];
+    inlineStyle: string | null;
+    text: string;
+    props: NodeProps;
+    declared: Record<string, DeclaredValue[]>;
+    shape: ShapeInfo;
+    metrics: Metrics;
+    flags: Flags;
+    containingBlockModifiers: string[];
+    children: TreeNode[];
+    repeat?: number;
+}
+export interface AncestorNode {
+    label: string;
+    props: NodeProps;
+    metrics: Metrics;
+    flags: Flags;
+    declared: Record<string, DeclaredValue[]>;
+    shape: ShapeInfo;
+    containingBlockModifiers: string[];
+    inlineStyle: string | null;
+}
+export interface CollectConfig {
+    rootSelector: string;
+    upTo: string;
+    downDepth: number;
+    maxNodes: number;
+}
+export interface ViewportSize {
+    width: number;
+    height: number;
+}
+export interface Snapshot {
+    rootSelector: string;
+    upTo: string;
+    downDepth: number;
+    maxNodes: number;
+    nodeCount: number;
+    viewport: ViewportSize;
+    ancestors: AncestorNode[];
+    tree: TreeNode | null;
+    crossOriginBlocked: number;
+    blockedSheetUrls: string[];
+    error?: string;
+    candidates?: string[];
+}
+export type Confidence = 'DEFINITE' | 'INDEFINITE' | 'UNVERIFIABLE';
+export interface Evidence {
+    type: 'computed' | 'declared' | 'pattern';
+    property?: string;
+    value?: string;
+    source?: string;
+    accessible?: boolean;
+}
+export interface Finding {
+    id: string;
+    level: 'info' | 'warning' | 'error';
+    message: string;
+    confidence: Confidence;
+    evidence: Evidence[];
+    location?: string;
+}

package/dist/engine/types.js

@@ -0,0 +1,4 @@
+"use strict";
+// ─── Shared types: contract between collector (browser), analyzer (node), renderer (node) ───
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/help.json

@@ -0,0 +1,107 @@
+{
+  "global": "Usage: cssprobe-cli <command> [args] [options]\n\n\nInspection:\n  inspect <url> [selector]    inspect the runtime css of a page (layout, scroll, colors, fonts, backgrounds)\n  login <url>                 open browser for interactive login, then save state for later use\n  state-import [file]         import cookies from netscape format file into a playwright state file\n\nConfiguration:\n  config-show                 show current configuration\n  config-set <key> <value>    set a configuration value\n  config-list                 list all profiles\n  config-use <name>           switch active profile\n  config-new <name>           create a new profile\n  config-path                 show configuration file path\n\nAgent Skills:\n  skill-install               install agent skill for cssprobe-cli (teaches agents how to use the cli)\n  skill-uninstall             remove agent skill for cssprobe-cli\n\nGlobal options:\n  --help [command]            print help\n  --json                      output response as JSON\n  --raw                       output only the result value\n  --version                   print version\n  -p, --profile <name>        use named profile (or CSSPROBE_PROFILE env)",
+  "commands": {
+    "inspect": {
+      "help": "cssprobe-cli inspect <url> [selector]\n\nInspect the runtime CSS of a page (layout, scroll, colors, fonts, backgrounds)\n\nArguments:\n  <url>                       url, file:// path, or local html file path\n  [selector]                  css selector for the root element (auto-detected if omitted)\nOptions:\n  --json                      output structured json instead of markdown\n  --headed                    show the browser window\n  --browser                   browser engine (default chromium)\n  --zoom                      run 1x/0.5x viewport diagnosis\n  --depth                     dom tree depth (default 6)\n  --max-nodes                 node count cap (default 60)\n  --up-to                     ancestor stop tag (default html)\n  --state                     path to saved state file (cookies + localstorage)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "json": "boolean",
+        "headed": "boolean",
+        "browser": "string",
+        "zoom": "boolean",
+        "depth": "string",
+        "max-nodes": "string",
+        "up-to": "string",
+        "state": "string"
+      },
+      "args": [
+        "url",
+        "selector"
+      ]
+    },
+    "login": {
+      "help": "cssprobe-cli login <url>\n\nOpen browser for interactive login, then save state for later use\n\nArguments:\n  <url>                       url, file:// path, or local html file path\nOptions:\n  --browser                   browser engine (default chromium)\n  --out                       output state file path (default: ~/.cssprobe-cli/states/<domain>.json)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "browser": "string",
+        "out": "string"
+      },
+      "args": [
+        "url"
+      ]
+    },
+    "state-import": {
+      "help": "cssprobe-cli state-import [file]\n\nImport cookies from Netscape format file into a Playwright state file\n\nArguments:\n  [file]                      netscape cookie file path (reads from stdin if omitted)\nOptions:\n  --out                       output state file path (default: ~/.cssprobe-cli/states/imported.json)\n  --merge                     existing state file to merge into\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "out": "string",
+        "merge": "string"
+      },
+      "args": [
+        "file"
+      ]
+    },
+    "config-show": {
+      "help": "cssprobe-cli config-show \n\nShow current configuration\n\nOptions:\n  --profile                   profile name",
+      "flags": {
+        "profile": "string"
+      },
+      "args": []
+    },
+    "config-set": {
+      "help": "cssprobe-cli config-set <key> <value>\n\nSet a configuration value\n\nArguments:\n  <key>                       config key (browser, depth, headed)\n  <value>                     config value\nOptions:\n  --profile                   profile name",
+      "flags": {
+        "profile": "string"
+      },
+      "args": [
+        "key",
+        "value"
+      ]
+    },
+    "config-list": {
+      "help": "cssprobe-cli config-list \n\nList all profiles\n",
+      "flags": {},
+      "args": []
+    },
+    "config-use": {
+      "help": "cssprobe-cli config-use <name>\n\nSwitch active profile\n\nArguments:\n  <name>                      profile name",
+      "flags": {},
+      "args": [
+        "name"
+      ]
+    },
+    "config-new": {
+      "help": "cssprobe-cli config-new <name>\n\nCreate a new profile\n\nArguments:\n  <name>                      profile name",
+      "flags": {},
+      "args": [
+        "name"
+      ]
+    },
+    "config-path": {
+      "help": "cssprobe-cli config-path \n\nShow configuration file path\n",
+      "flags": {},
+      "args": []
+    },
+    "skill-install": {
+      "help": "cssprobe-cli skill-install \n\nInstall Agent Skill for cssprobe-cli (teaches agents how to use the CLI)\n\nOptions:\n  --target                    agent target: auto, all, opencode, claude, codex, cursor, hermes, gemini (default: auto)\n  --local                     install to current directory instead of home\n  --path                      custom base directory (overrides home/current)\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "target": "string",
+        "local": "boolean",
+        "path": "string"
+      },
+      "args": []
+    },
+    "skill-uninstall": {
+      "help": "cssprobe-cli skill-uninstall \n\nRemove Agent Skill for cssprobe-cli\n\nOptions:\n  --target                    agent target: auto, all, opencode, claude, codex, cursor, hermes, gemini (default: auto)\n  --local                     remove from current directory instead of home\n  --path                      custom base directory\n\nGlobal options:\n  --json                      output as JSON\n  --profile, -p <name>        use named profile",
+      "flags": {
+        "target": "string",
+        "local": "boolean",
+        "path": "string"
+      },
+      "args": []
+    }
+  },
+  "booleanOptions": [
+    "json",
+    "headed",
+    "zoom",
+    "local"
+  ]
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { program } from './cli/program';

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.program = void 0;
+var program_1 = require("./cli/program");
+Object.defineProperty(exports, "program", { enumerable: true, get: function () { return program_1.program; } });
+//# sourceMappingURL=index.js.map

package/dist/installer/index.d.ts

@@ -0,0 +1,3 @@
+export { buildSkillMd, buildPitfallsMd } from './skill-template';
+export { ALL_TARGETS, getTarget, listTargetIds, resolveTargetFlag } from './targets/registry';
+export type { AgentTarget, Location, TargetId, WriteResult } from './targets/types';

package/dist/installer/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTargetFlag = exports.listTargetIds = exports.getTarget = exports.ALL_TARGETS = exports.buildPitfallsMd = exports.buildSkillMd = void 0;
+var skill_template_1 = require("./skill-template");
+Object.defineProperty(exports, "buildSkillMd", { enumerable: true, get: function () { return skill_template_1.buildSkillMd; } });
+Object.defineProperty(exports, "buildPitfallsMd", { enumerable: true, get: function () { return skill_template_1.buildPitfallsMd; } });
+var registry_1 = require("./targets/registry");
+Object.defineProperty(exports, "ALL_TARGETS", { enumerable: true, get: function () { return registry_1.ALL_TARGETS; } });
+Object.defineProperty(exports, "getTarget", { enumerable: true, get: function () { return registry_1.getTarget; } });
+Object.defineProperty(exports, "listTargetIds", { enumerable: true, get: function () { return registry_1.listTargetIds; } });
+Object.defineProperty(exports, "resolveTargetFlag", { enumerable: true, get: function () { return registry_1.resolveTargetFlag; } });
+//# sourceMappingURL=index.js.map

package/dist/installer/skill-template.d.ts

@@ -0,0 +1,9 @@
+/**
+ * cssprobe-cli-cli Agent Skill templates.
+ *
+ * Installed into agent-specific skill directories via `cssprobe-cli-cli skill-install`.
+ * Teaches agents how to use cssprobe-cli-cli for runtime CSS inspection — layout,
+ * scroll, overflow, colors, backgrounds, fonts — with confidence levels.
+ */
+export declare function buildSkillMd(): string;
+export declare function buildPitfallsMd(): string;