@vitronai/alethia 0.8.5 → 0.9.0

package/examples/.claude/workflows/smoke.js

@@ -0,0 +1,22 @@
+export const meta = {
+  name: 'alethia:smoke',
+  description: 'Quick smoke test — navigate to a URL and assert the page loads',
+  phases: [
+    { title: 'Smoke' },
+  ],
+}
+
+// Pass args: { url: "http://localhost:3000", checks: "assert the dashboard heading is visible" }
+const a = (typeof args === 'string' ? JSON.parse(args) : args) || {}
+const url = a.url || 'http://localhost:3000'
+const checks = a.checks || 'assert the page is visible'
+
+log(`Smoke test → ${url}`)
+
+phase('Smoke')
+const result = await agent(
+  `Call alethia_tell with the following instructions and return the step results:\nnavigate to ${url}\n${checks}`,
+  { label: 'smoke', phase: 'Smoke' }
+)
+
+return { url, result }

package/examples/README.md

@@ -0,0 +1,65 @@
+# Examples
+
+Copy-paste integration examples for adding Alethia to your project.
+
+## Claude Code commands
+
+The `.claude/commands/` folder contains project-level slash commands for Claude Code. Copy any of these into your own project's `.claude/commands/` directory and they'll appear as `/command-name` in Claude Code when that project is open.
+
+| Command | What it does |
+|---------|-------------|
+| `/smoke` | Quick navigate + assert the page loaded |
+| `/audit` | Full WCAG + NIST compliance audit → signed evidence pack |
+| `/safety-check` | Prove the EA1 gate blocks every destructive action on a page |
+| `/bootstrap` | Scan a page with `propose_tests` and run each suggested block |
+| `/multi-page` | Smoke test multiple pages in parallel |
+| `/regression` | Run a fixed assertion suite — fail on any regression |
+
+**Install:**
+```bash
+# From the root of your project:
+mkdir -p .claude/commands
+curl -O --output-dir .claude/commands \
+  https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/examples/.claude/commands/smoke.md \
+  https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/examples/.claude/commands/audit.md \
+  https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/examples/.claude/commands/safety-check.md \
+  https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/examples/.claude/commands/bootstrap.md \
+  https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/examples/.claude/commands/multi-page.md \
+  https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/examples/.claude/commands/regression.md
+```
+
+Or just copy the files manually. They're plain Markdown — edit the default URL or port to match your stack.
+
+## Claude Code workflows
+
+The `.claude/workflows/` folder contains named workflow scripts for the Claude Code `Workflow()` tool. Copy any of these into your own project's `.claude/workflows/` directory and Claude Code can run them with `Workflow({ name: "alethia:<name>" })` or via the `/workflows` panel.
+
+| Workflow | What it does |
+|----------|-------------|
+| `alethia:smoke` | Navigate to a URL and assert the page loads |
+| `alethia:full-audit` | WCAG + NIST audits in parallel → signed evidence pack |
+| `alethia:safety-gate` | EA1 per-action block/allow report |
+| `alethia:bootstrap` | `propose_tests` → run each block sequentially |
+| `alethia:multi-page` | Smoke test multiple pages in parallel via `alethia_tell_parallel` |
+| `alethia:regression` | Fixed assertion suite — returns pass/fail + evidence hash |
+
+All workflows accept a `url` arg (default: `http://localhost:3000`). See each file's header comment for the full args schema.
+
+**Install:**
+```bash
+# From the root of your project:
+mkdir -p .claude/workflows
+curl -O --output-dir .claude/workflows \
+  https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/examples/.claude/workflows/smoke.js \
+  https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/examples/.claude/workflows/full-audit.js \
+  https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/examples/.claude/workflows/safety-gate.js \
+  https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/examples/.claude/workflows/bootstrap.js \
+  https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/examples/.claude/workflows/multi-page.js \
+  https://raw.githubusercontent.com/vitron-ai/alethia-mcp/main/examples/.claude/workflows/regression.js
+```
+
+## GitHub Actions
+
+`github-actions.yml` is a drop-in CI workflow that runs your `.alethia` test files on every push and pull request. Save it as `.github/workflows/alethia.yml` and adjust the "Start your app" step to match your stack.
+
+See the file header for full setup instructions.

package/examples/github-actions.yml

@@ -0,0 +1,62 @@
+# Drop-in GitHub Actions workflow for running an Alethia E2E test suite.
+# Save as `.github/workflows/alethia.yml` in your repo and adjust the
+# `Start your app` step to match your stack.
+#
+# How it works:
+#   1. Install the @vitronai/alethia bridge globally. The bridge auto-installs
+#      the signed runtime on first use (Ed25519-verified, no signup).
+#   2. Start your app in the background.
+#   3. `alethia run tests/...` drives the runtime headless and exits 0/1
+#      based on whether every step passed. CI environments are auto-detected
+#      so the cockpit window stays hidden.
+#
+# Test files (.alethia) are plain text — same NLP your agents already use.
+
+name: E2E (Alethia)
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  alethia:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      # Pin a specific runtime version for reproducible CI. Drop this if you
+      # always want the latest signed release on the default branch.
+      - name: Install Alethia bridge
+        run: npm install -g @vitronai/alethia
+
+      # Replace this with how YOUR app boots. Common patterns:
+      #   npm run start &              # most Node apps
+      #   docker compose up -d         # containerized stacks
+      #   python -m http.server 3000 & # static sites
+      - name: Start your app
+        run: |
+          npm ci
+          npm run build
+          npm start &
+          npx wait-on http://localhost:3000 --timeout 60000
+
+      - name: Run Alethia E2E suite
+        run: |
+          for test in tests/e2e/*.alethia; do
+            echo "::group::$test"
+            alethia run "$test"
+            echo "::endgroup::"
+          done
+        env:
+          # Pin runtime version for reproducible CI runs. Remove to always
+          # fetch the latest signed release.
+          # ALETHIA_RUNTIME_VERSION: '0.7.1'
+          # The bridge auto-detects CI and runs headless; this is just for
+          # belt-and-suspenders if you set CI=false somewhere.
+          ALETHIA_HEADLESS: '1'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vitronai/alethia",
-  "version": "0.8.5",
+  "version": "0.9.0",
   "description": "MIT-licensed MCP bridge to the Alethia runtime — the patent-pending zero-IPC E2E test runtime for AI agents. 2-5x faster than Playwright MCP. Signed evidence packs, EA1 fail-closed safety gate, WCAG + NIST 800-53 audits built in. Local-first, zero telemetry. Auto-installs on first use.",
   "type": "module",
   "main": "dist/index.js",
@@ -12,13 +12,14 @@
     "dist",
     "demo",
     "skills",
+    "examples",
     "LICENSE",
     "README.md"
   ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "test": "node --test bridge-tests/*.test.mjs",
+    "test": "themis test --isolation process",
     "prepublishOnly": "npm run build && npm test"
   },
   "keywords": [
@@ -42,7 +43,7 @@
     "fail-closed",
     "vitron"
   ],
-  "author": "vitron.ai <gatekeeper@vitron.ai>",
+  "author": "vitron.ai <team@vitron.ai>",
   "license": "MIT",
   "homepage": "https://github.com/vitron-ai/alethia",
   "repository": {
@@ -52,6 +53,7 @@
   "bugs": {
     "url": "https://github.com/vitron-ai/alethia-mcp/issues"
   },
+  "mcpName": "io.github.vitron-ai/alethia",
   "publishConfig": {
     "access": "public"
   },
@@ -59,7 +61,8 @@
     "node": ">=18"
   },
   "devDependencies": {
-    "typescript": "^5.9.3",
-    "@types/node": "^25.2.3"
+    "@types/node": "^25.2.3",
+    "@vitronai/themis": "^1.3.0",
+    "typescript": "^5.9.3"
   }
 }

package/skills/alethia/SKILL.md

@@ -166,9 +166,35 @@ On any `alethia_tell` failure, the response includes:
 
 Read these before retrying. Most failures are phrasing mismatches, not real bugs — the suggested fix usually works.
 
-## Escape hatches (use sparingly)
+## Dev feedback loop (eval as a DOM oracle)
 
-- **`alethia_eval({ expression })`** — raw JavaScript in the page context. For cases where NLP can't express what you need (counting elements, reading computed styles, triggering React's native input setter). Runs in the target page, not the host.
+During active frontend development, `alethia_eval` is more reliable than screenshots for catching bugs in real time. Screenshots can serve a cached frame; eval always returns live values from the current DOM.
+
+**The pattern:** write code → navigate → eval the DOM → get exact values → correct → repeat.
+
+```javascript
+// Did the CSS actually apply?
+alethia_eval({ expression: "getComputedStyle(document.querySelector('.hero-title')).fontSize" })
+// → "32px"
+
+// Is the layout correct?
+alethia_eval({ expression: "getComputedStyle(document.querySelector('.sidebar')).justifyContent" })
+// → "flex-start"
+
+// How wide is the element actually rendering?
+alethia_eval({ expression: "document.querySelector('.card').offsetWidth" })
+// → 320
+
+// Count elements to verify a list rendered
+alethia_eval({ expression: "document.querySelectorAll('.product-card').length" })
+// → 6
+```
+
+Use eval for **ground truth** (computed values, layout dimensions, element counts, React state). Use `alethia_screenshot` for **visual verification** (does it look right, are things positioned correctly on screen). When a CSS bug is suspected, reach for eval first — it returns exact values in milliseconds without any caching ambiguity.
+
+## Escape hatches
+
+- **`alethia_eval({ expression })`** — raw JavaScript in the page context. Runs in the target page, not the host. See "Dev feedback loop" above for the primary use case; also useful for triggering React's native input setter when NLP typing doesn't fire onChange.
 - **`alethia_screenshot()`** — PNG of the current page, for visual verification.
 - **`alethia_activate_kill_switch` / `alethia_reset_kill_switch`** — emergency halt and resume. Blocks all tool calls until reset.