ax-grep 0.0.0 → 0.1.1

package/package.json

@@ -1,14 +1,100 @@
 {
   "name": "ax-grep",
-  "version": "0.0.0",
-  "description": "Reserved package name for an accessibility tree extraction utility.",
+  "version": "0.1.1",
+  "description": "A browser-native semantic accessibility tree extractor that runs without DevTools or CDP.",
   "type": "module",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/hmmhmmhm/ax-lite.git"
+  "engines": {
+    "node": ">=18"
   },
+  "packageManager": "pnpm@10.33.4",
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hmmhmmhm/ax-grep.git"
+  },
+  "homepage": "https://github.com/hmmhmmhm/ax-grep#readme",
+  "bugs": {
+    "url": "https://github.com/hmmhmmhm/ax-grep/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js"
+    },
+    "./static": {
+      "types": "./dist/static.d.ts",
+      "import": "./dist/static.js"
+    }
+  },
+  "bin": {
+    "ax-grep": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "skills",
+    "skills.sh"
+  ],
+  "scripts": {
+    "build": "tsup && tsc --noEmit",
+    "check": "tsc --noEmit",
+    "check:processes": "tsx scripts/check-project-processes.ts",
+    "readiness:audit": "tsx scripts/check-agent-readiness.ts",
+    "readiness:real-page-smoke": "tsx scripts/check-real-page-smoke.ts",
+    "readiness:search-smoke": "tsx scripts/check-search-smoke.ts",
+    "readiness:agent-browser-smoke": "tsx scripts/check-agent-browser-smoke.ts",
+    "readiness:agent-browser-text-heavy-smoke": "tsx scripts/check-agent-browser-text-heavy-smoke.ts",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "compare": "tsx scripts/compare.ts",
+    "compare:static": "tsx scripts/compare-static.ts",
+    "compare:tokens": "tsx scripts/compare-token-cost.ts",
+    "benchmark:agent-cost": "tsx scripts/benchmark-agent-cost.ts",
+    "compare:browser:fixture": "tsx scripts/compare-browser-fixture.ts",
+    "compare:gate": "tsx scripts/check-comparison-gates.ts",
+    "compare:sample": "tsx scripts/compare.ts https://example.com https://www.wikipedia.org https://developer.mozilla.org/en-US/docs/Web/Accessibility https://news.ycombinator.com https://github.com/features https://libraries.io/npm/typescript https://www.npmjs.com/package/typescript",
+    "compare:korea": "tsx scripts/compare.ts https://ko.wikipedia.org/wiki/%EB%8C%80%ED%95%9C%EB%AF%BC%EA%B5%AD https://www.hani.co.kr/ https://www.korea.kr/ https://www.yonhapnewstv.co.kr/",
+    "compare:static:fixtures": "tsx scripts/compare-static.ts --target-set agent-fixtures",
+    "compare:static:fixtures:gate": "tsx scripts/check-fixture-static-gate.ts",
+    "compare:static:agent": "tsx scripts/compare-static.ts --target-set agent-executor",
+    "compare:static:korea-social": "tsx scripts/compare-static.ts --target-set korea-social",
+    "compare:tokens:korea-social": "tsx scripts/compare-token-cost.ts --target-set korea-social",
+    "compare:static:china-japan": "tsx scripts/compare-static.ts --target-set china-japan",
+    "compare:tokens:china-japan": "tsx scripts/compare-token-cost.ts --target-set china-japan",
+    "compare:static:diverse": "tsx scripts/compare-static.ts https://www.bbc.com/news https://www.npr.org/2025/03/11/nx-s1-5324543/ntsb-dca-mid-air-collision-american-black-hawk https://www.theguardian.com/international https://www.gov.uk/foreign-travel-advice https://www.nottinghamshire.gov.uk/global-content/how-to-create-accessible-content/how-to-make-web-pages-accessible/checklist-web-page https://books.toscrape.com/ https://old.reddit.com/r/programming/ https://www.reddit.com/r/programming/ https://x.com/NASA https://www.instagram.com/nasa/",
+    "compare:tokens:diverse": "tsx scripts/compare-token-cost.ts https://www.bbc.com/news https://www.npr.org/2025/03/11/nx-s1-5324543/ntsb-dca-mid-air-collision-american-black-hawk https://www.gov.uk/foreign-travel-advice https://books.toscrape.com/ https://old.reddit.com/r/programming/ https://x.com/NASA https://www.instagram.com/nasa/"
+  },
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "semantic-tree",
+    "webview",
+    "agent"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.0.0",
+    "@vitest/coverage-v8": "4.1.8",
+    "agent-browser": "^0.27.0",
+    "puppeteer": "^24.31.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "dependencies": {
+    "domhandler": "^6.0.1",
+    "htmlparser2": "^12.0.0",
+    "js-tiktoken": "^1.0.21"
+  },
+  "optionalDependencies": {
+    "impit": "^0.14.1"
   }
 }

package/skills/ax-grep-cli/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: ax-grep-cli
+description: Use ax-grep as a CLI-first page search and page-check tool before opening a browser. Best for agents that need compact semantic trees, source links, hidden app signals, forms, tables, citations, and browser handoff guidance.
+---
+
+# ax-grep CLI
+
+Use `ax-grep` before browser automation when a subagent needs to inspect a
+search result, URL, HTML file, or captured page.
+
+## First Command
+
+```sh
+ax-grep "https://example.com" --agent
+```
+
+If `ax-grep` is not on `PATH`, use the npm executable:
+
+```sh
+npx --yes ax-grep@latest "https://example.com" --agent
+```
+
+For smaller context:
+
+```sh
+ax-grep "https://example.com" --agent-brief
+```
+
+## Search
+
+```sh
+ax-grep --search "official docs pricing" --agent
+```
+
+Use the returned `agent.*CommandArgs` fields when continuing. They are JSON argv
+arrays in execution order. Use `agent.*Command` when you need a shell string.
+
+## Agent Policy
+
+- Prefer `--agent` or `--agent-brief` over raw text output for subagents.
+- Read `agent.executor`, `agent.handoff`, `agent.next`, `agent.readTargets`,
+  and any returned `agent.sourceChoices` or `agent.resultChoices` before
+  deciding.
+- If `agent.executor.decision` is `return`, answer from the referenced
+  `readFrom` payload instead of opening a browser.
+- If a URL follow-up is needed, run the provided `commandArgs` one command at a
+  time.
+- Escalate to browser automation only when `needsBrowserHtml`,
+  `needsBrowserInteraction`, or the executor/handoff fields say it is needed.
+- Do not run multiple browser-backed checks in parallel.
+
+## Useful Patterns
+
+Inspect a result and open the best match in one step:
+
+```sh
+ax-grep --search "site:example.com api reference" --open-result best --agent
+```
+
+If an engine rejects `best`, open the top ranked result directly:
+
+```sh
+ax-grep --search "site:example.com api reference" --open-result 1 --agent
+```
+
+Check a page for specific terms:
+
+```sh
+ax-grep "https://example.com/docs" --find "rate limit" --find "authentication" --agent
+```
+
+Read static HTML from another tool:
+
+```sh
+curl -fsSL "https://example.com" | ax-grep --stdin --agent
+```
+
+## What ax-grep Sees
+
+`ax-grep --agent` can expose:
+
+- semantic headings, landmarks, links, buttons, forms, tables, and lists
+- source-like links and ranked search choices
+- JSON-LD schema facts, metadata, policies, topics, provenance, and citations
+- hydration URLs, API endpoints, runtime hints, app config, and mobile hints
+- recommended next commands and browser handoff reasons
+
+Treat the full JSON payload as source of truth; top-level shortcuts are for
+fast routing.

package/skills.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+set -eu
+
+skill_name="ax-grep-cli"
+target_root="${CODEX_HOME:-"$HOME/.codex"}/skills"
+target_dir="$target_root/$skill_name"
+script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" 2>/dev/null && pwd)
+local_skill="$script_dir/skills/$skill_name/SKILL.md"
+remote_skill="${AX_GREP_SKILL_URL:-https://raw.githubusercontent.com/hmmhmmhm/ax-grep/main/skills/ax-grep-cli/SKILL.md}"
+
+mkdir -p "$target_dir"
+
+if [ -f "$local_skill" ]; then
+  cp "$local_skill" "$target_dir/SKILL.md"
+elif command -v curl >/dev/null 2>&1; then
+  curl -fsSL "$remote_skill" -o "$target_dir/SKILL.md"
+elif command -v wget >/dev/null 2>&1; then
+  wget -qO "$target_dir/SKILL.md" "$remote_skill"
+else
+  echo "Could not find local skill file, curl, or wget." >&2
+  exit 1
+fi
+
+echo "Installed $skill_name skill to $target_dir"

package/index.js

@@ -1 +0,0 @@
-export {};