@appliqation/explorer 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Appliqation Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# Appliqation Explorer
+
+**Runs Appliqation's exploratory-QA workflow (`appq:runman`) headlessly against a live app under test — the same senior-QA heuristics pass a human runs interactively in Claude Code, without a human at the confirmation gate.**
+
+Point it at a URL (or let it resolve one from a project) and a plain-English intent, and it drives a real Playwright browser through surface mapping, a 13-category senior-QA heuristics pass, and mandatory security/network/caching/mobile probes — the exact same methodology Appliqation already serves interactively, just run unattended.
+
+## Why this exists
+
+Every other agent in this family answers a narrow, structured question: does this test case pass (autotest), is there a script for it (scriptgen), can this defect be fixed (defect-fix). None of them go looking for the bugs a scripted test never checks for — accessibility gaps, race conditions, caching bugs, things that only show up when someone actually explores. Appliqation already has this covered as `appq:runman`, but until now the only way to run it was interactively. This is the standalone, unattended client for it.
+
+## The one thing this agent deliberately can't do
+
+`appq:runman`'s own prompt ends a pass by calling `enrich_project_context` with `action=write`, to persist findings (`known_issues`, `high_risk_areas`, `regression_watchlist`) as memory for future passes. **This agent refuses that call.**
+
+When `appq:runman` runs interactively inside Claude Code, a human is present at its Phase 2 confirmation gate and reads the findings report before anything happens next — informal but real supervision over what gets written back as fact for future agents to trust. A standalone, headless invocation has no equivalent: nothing reviews it turn to turn. So this agent holds the conservative default instead: it can read project context (`enrich_project_context` with `action=read` — informs what's worth exploring), but a write attempt is refused at the dispatch layer, in code, before it ever reaches appq — not honored just because the served prompt asks for it. Genuinely read-only end to end; see [`@appliqation/agent-core`](https://github.com/appliqation/appliqation-agent-core)'s `createReadOnlyProjectContextDispatcher`.
+
+## Quick start
+
+```bash
+npm install -g @appliqation/explorer
+npx playwright install chromium
+```
+
+Create a `.env` file (in whatever directory you'll run it from) with:
+
+```
+APPQ_API_KEY=your-appliqation-api-key   # read-only is enough
+ANTHROPIC_API_KEY=your-anthropic-key    # or OPENAI_API_KEY — pick one
+```
+
+```bash
+appliqation-explorer explore \
+  --prompt "Explore the signup flow like a senior QA lead, focus on the phone number field" \
+  --project-id 1349 \
+  --site-url https://stage.example.com
+```
+
+Add `--json`/`--ci` for a structured summary. There's no `--dry-run` — this agent never has real write access to anything, so there's nothing to suppress. The exit code is 0 unless the pass hit its own budget cap and ended early; "found bugs" is never a failure — that's the entire point of running it.
+
+## Configuration
+
+Copy `.env.example` to `.env`. Requires `APPQ_API_KEY` (read-only access is sufficient) and one of `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`. `EXPLORE_MAX_STEPS`/`EXPLORE_MAX_PAGES`/`EXPLORE_MAX_MINUTES` are the workflow's own self-regulated budget (what the model is told to respect); `BUDGET_MAX_*` is a separate, code-enforced backstop set generously above them in case the model doesn't honor its own limits.
+
+## Development
+
+```bash
+git clone https://github.com/appliqation/appliqation-explorer.git
+cd appliqation-explorer
+npm install
+cp .env.example .env   # fill in APPQ_API_KEY (read-only is enough) and one LLM provider key
+npm run dev -- explore --prompt "<text>" [--project-id <id>] [--site-url <url>]
+npm run typecheck
+npm test
+```
+
+See `CLAUDE.md` for a map of this repo if you're working in it with an AI coding assistant.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/cli/audit.js

@@ -0,0 +1,25 @@
+// Extracted out of cli/index.ts so this is testable without triggering that
+// file's top-level program.parseAsync(process.argv) side effect — same
+// reasoning as appliqation-autotest's cli/resolvers.ts.
+import { safeRecord } from '@appliqation/agent-core';
+export async function recordExploreRun(args) {
+    const { sink, startedAt, endedAt, model, usage, prompt, projectId, siteUrl, result } = args;
+    await safeRecord(sink, {
+        agent: 'appliqation-explorer',
+        subcommand: 'explore',
+        startedAt,
+        endedAt,
+        durationMillis: endedAt - startedAt,
+        model,
+        usage,
+        turns: result?.turns,
+        budgetExceeded: result?.budgetExceeded,
+        // Never based on what the report found — budgetExceeded means the pass
+        // ended early, an unrelated failure to explore() throwing outright.
+        exitCode: result ? (result.budgetExceeded ? 1 : 0) : 1,
+        outcome: result
+            ? { prompt, projectId, siteUrl, turns: result.turns, budgetExceeded: result.budgetExceeded, report: result.report }
+            : { prompt, projectId, siteUrl, error: true },
+    });
+}
+//# sourceMappingURL=audit.js.map

package/dist/cli/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/cli/audit.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,uEAAuE;AACvE,wDAAwD;AAExD,OAAO,EAAE,UAAU,EAAoC,MAAM,yBAAyB,CAAC;AAgBvF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAA0B;IAC/D,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC5F,MAAM,UAAU,CAAC,IAAI,EAAE;QACrB,KAAK,EAAE,sBAAsB;QAC7B,UAAU,EAAE,SAAS;QACrB,SAAS;QACT,OAAO;QACP,cAAc,EAAE,OAAO,GAAG,SAAS;QACnC,KAAK;QACL,KAAK;QACL,KAAK,EAAE,MAAM,EAAE,KAAK;QACpB,cAAc,EAAE,MAAM,EAAE,cAAc;QACtC,uEAAuE;QACvE,oEAAoE;QACpE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtD,OAAO,EAAE,MAAM;YACb,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;YACnH,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE;KAChD,CAAC,CAAC;AACL,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// `explore`: run appq's real appq:runman exploratory-QA workflow headlessly
+// against a live target. See src/orchestrator/explore.ts for the actual
+// mechanism; this file is just Commander wiring + result rendering.
+import { Command } from 'commander';
+import { createMcpClient, createAnthropicAdapter, createOpenAiAdapter, createUsageAccumulator } from '@appliqation/agent-core';
+import { config, resolveProvider, resolveModel } from '../config/env.js';
+import { explore } from '../orchestrator/explore.js';
+import { recordExploreRun } from './audit.js';
+import { printJsonSummary, printHumanSummary, exitCodeFor } from './output.js';
+const client = createMcpClient({ origin: config.appqOrigin, apiKey: config.appqApiKey() });
+function buildAdapter() {
+    const provider = resolveProvider();
+    const model = resolveModel();
+    return provider === 'anthropic'
+        ? createAnthropicAdapter(config.anthropicApiKey, model, config.anthropicMaxTokens)
+        : createOpenAiAdapter(config.openaiApiKey, model, config.openaiMaxOutputTokens);
+}
+function logEvent(prefix) {
+    return (e) => {
+        if (e.type === 'assistant') {
+            const text = (e.detail ?? '').trim();
+            if (text)
+                console.error(`${prefix}[thinking] ${text}`);
+        }
+        else if (e.type === 'tool') {
+            const d = e.detail;
+            console.error(`${prefix}[tool] ${d.name} -> ${d.result.slice(0, 300)}`);
+        }
+        else if (e.type === 'log') {
+            console.error(`${prefix}[log] ${e.detail}`);
+        }
+        else if (e.type === 'usage') {
+            const u = e.detail;
+            const cacheNote = u.cacheReadTokens
+                ? ` (${u.cacheReadTokens} from cache)`
+                : u.cacheWriteTokens
+                    ? ` (${u.cacheWriteTokens} written to cache)`
+                    : '';
+            console.error(`${prefix}[usage] in=${u.inputTokens} out=${u.outputTokens}${cacheNote}`);
+        }
+    };
+}
+const program = new Command();
+program
+    .name('appliqation-explorer')
+    .description("Run Appliqation's exploratory-QA workflow (appq:runman) headlessly against a live app under test.");
+program
+    .command('explore')
+    .description("Run appq:runman — surface mapping, a senior-QA heuristics pass, and mandatory security/network/caching/" +
+    'mobile probes — against a real target, always headlessly (interactive: "false", no confirmation gate). ' +
+    'Read-only end to end: offered appq context tools plus enrich_project_context, but its own attempted ' +
+    'action=write persistence at the end of the workflow is refused, not honored — see README.md.')
+    .requiredOption('--prompt <text>', 'plain-English exploration intent — can embed a URL')
+    .option('--project-id <id>', 'appq project id — enables reading persistent project-context memory')
+    .option('--site-url <url>', "override the URL appq:runman would otherwise resolve on its own")
+    .option('--max-steps <n>', 'override EXPLORE_MAX_STEPS for this run')
+    .option('--max-pages <n>', 'override EXPLORE_MAX_PAGES for this run')
+    .option('--max-minutes <n>', 'override EXPLORE_MAX_MINUTES for this run')
+    .option('--json', 'print a single structured JSON summary on stdout instead of a human-readable report')
+    .option('--ci', 'shorthand for --json')
+    .action(async (opts) => {
+    const json = (opts.json ?? false) || (opts.ci ?? false);
+    const adapter = buildAdapter();
+    const projectId = opts.projectId !== undefined ? Number(opts.projectId) : undefined;
+    const startedAt = Date.now();
+    const usage = createUsageAccumulator();
+    const baseLog = logEvent('');
+    let result;
+    try {
+        result = await explore({
+            client,
+            adapter,
+            prompt: opts.prompt,
+            projectId,
+            siteUrl: opts.siteUrl,
+            maxSteps: opts.maxSteps ? Number(opts.maxSteps) : config.exploreMaxSteps,
+            maxPages: opts.maxPages ? Number(opts.maxPages) : config.exploreMaxPages,
+            maxMinutes: opts.maxMinutes ? Number(opts.maxMinutes) : config.exploreMaxMinutes,
+            budget: config.budget,
+            ringBufferCap: config.evidenceRingBufferCap,
+            onEvent: (e) => {
+                baseLog(e);
+                if (e.type === 'usage')
+                    usage.onUsage(e.detail);
+            },
+        });
+    }
+    finally {
+        // Audit write happens whether the run succeeded or threw — see
+        // @appliqation/agent-core's audit/sink.ts: safeRecord() (used
+        // inside recordExploreRun) never lets a failed/unreachable audit
+        // sink affect this process's real outcome, and this finally never
+        // blocks the throw below from propagating unchanged.
+        await recordExploreRun({
+            sink: config.auditSink,
+            startedAt,
+            endedAt: Date.now(),
+            model: resolveModel(),
+            usage: usage.totals(),
+            prompt: opts.prompt,
+            projectId,
+            siteUrl: opts.siteUrl,
+            result,
+        });
+    }
+    const summary = {
+        prompt: opts.prompt,
+        projectId,
+        siteUrl: opts.siteUrl,
+        turns: result.turns,
+        budgetExceeded: result.budgetExceeded,
+        report: result.report,
+    };
+    if (json)
+        printJsonSummary(summary);
+    else
+        printHumanSummary(summary);
+    process.exitCode = exitCodeFor(summary);
+});
+program.parseAsync(process.argv);
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/cli/output.js

@@ -0,0 +1,20 @@
+// --json/--ci's renderer. Unlike appliqation-scriptgen/-defect-fix,
+// "found bugs" is not a failure condition here — that's this agent's whole
+// job. exitCodeFor() is non-zero only when the pass itself didn't
+// complete (budgetExceeded), never based on what the report says it found.
+export function printJsonSummary(summary) {
+    console.log(JSON.stringify(summary, null, 2));
+}
+export function printHumanSummary(summary) {
+    console.log(`\n=== Exploration: "${summary.prompt}" ===\n`);
+    console.log(summary.report);
+    console.log(`\n(${summary.turns} turns, budget exceeded: ${summary.budgetExceeded})`);
+    if (summary.budgetExceeded) {
+        console.log('  Pass ended early on its own budget cap — the report above may be incomplete.');
+    }
+}
+/** 1 only when the pass itself didn't complete — never based on what the report found. */
+export function exitCodeFor(summary) {
+    return summary.budgetExceeded ? 1 : 0;
+}
+//# sourceMappingURL=output.js.map

package/dist/cli/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/cli/output.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,2EAA2E;AAC3E,kEAAkE;AAClE,2EAA2E;AAW3E,MAAM,UAAU,gBAAgB,CAAC,OAAuB;IACtD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAuB;IACvD,OAAO,CAAC,GAAG,CAAC,uBAAuB,OAAO,CAAC,MAAM,SAAS,CAAC,CAAC;IAC5D,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5B,OAAO,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,KAAK,4BAA4B,OAAO,CAAC,cAAc,GAAG,CAAC,CAAC;IACtF,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;QAC3B,OAAO,CAAC,GAAG,CAAC,gFAAgF,CAAC,CAAC;IAChG,CAAC;AACH,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,WAAW,CAAC,OAAuB;IACjD,OAAO,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC"}

package/dist/config/env.js

@@ -0,0 +1,52 @@
+import 'dotenv/config';
+import { DEFAULT_ANTHROPIC_MODEL, DEFAULT_OPENAI_MODEL } from '@appliqation/agent-core/providers';
+import { required, optional } from '@appliqation/agent-core/config';
+import { resolveAuditSink } from '@appliqation/agent-core/audit';
+export const config = {
+    appqOrigin: optional('APPQ_ORIGIN') ?? 'https://appq.appliqation.io',
+    appqApiKey: () => required('APPQ_API_KEY'),
+    anthropicApiKey: optional('ANTHROPIC_API_KEY'),
+    openaiApiKey: optional('OPENAI_API_KEY'),
+    anthropicModel: optional('ANTHROPIC_MODEL'),
+    openaiModel: optional('OPENAI_MODEL'),
+    anthropicMaxTokens: Number(optional('ANTHROPIC_MAX_TOKENS') ?? 8192),
+    openaiMaxOutputTokens: Number(optional('OPENAI_MAX_OUTPUT_TOKENS') ?? 8192),
+    // appq:runman's own self-regulated budget (max_steps/max_pages/max_minutes
+    // args) — what the model is actually told to respect. Defaults match the
+    // workflow's own (RunmanPrompt.php).
+    exploreMaxSteps: Number(optional('EXPLORE_MAX_STEPS') ?? 50),
+    exploreMaxPages: Number(optional('EXPLORE_MAX_PAGES') ?? 12),
+    exploreMaxMinutes: Number(optional('EXPLORE_MAX_MINUTES') ?? 15),
+    // A code-enforced backstop in case the model doesn't honor the
+    // prompt-level limits above — set generously above them, not equal to
+    // them (unlike appliqation-scriptgen's ~infinite maxPages, this agent
+    // really does drive browser_navigate, so the cap has to be real).
+    budget: {
+        maxCalls: Number(optional('BUDGET_MAX_CALLS') ?? 150),
+        maxPages: Number(optional('BUDGET_MAX_PAGES') ?? 40),
+        maxMillis: Number(optional('BUDGET_MAX_MILLIS') ?? 25 * 60 * 1000),
+        maxTurns: Number(optional('BUDGET_MAX_TURNS') ?? 80),
+    },
+    evidenceRingBufferCap: Number(optional('EVIDENCE_RING_BUFFER_CAP') ?? 500),
+    // Observability, entirely opt-in — see @appliqation/agent-core's audit/sink.ts.
+    // Nothing is recorded anywhere unless AUDIT_MONGO_URI or AUDIT_JSONL_PATH is
+    // actually set; resolveAuditSink() falls back to a no-op sink otherwise.
+    auditSink: resolveAuditSink({
+        auditMongoUri: optional('AUDIT_MONGO_URI'),
+        auditMongoDb: optional('AUDIT_MONGO_DB'),
+        auditMongoCollection: optional('AUDIT_MONGO_COLLECTION'),
+        auditJsonlPath: optional('AUDIT_JSONL_PATH'),
+    }),
+};
+export function resolveProvider() {
+    if (config.anthropicApiKey)
+        return 'anthropic';
+    if (config.openaiApiKey)
+        return 'openai';
+    throw new Error('Set ANTHROPIC_API_KEY or OPENAI_API_KEY');
+}
+export function resolveModel() {
+    const provider = resolveProvider();
+    return provider === 'anthropic' ? (config.anthropicModel ?? DEFAULT_ANTHROPIC_MODEL) : (config.openaiModel ?? DEFAULT_OPENAI_MODEL);
+}
+//# sourceMappingURL=env.js.map

package/dist/config/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/config/env.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAClG,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEjE,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,UAAU,EAAE,QAAQ,CAAC,aAAa,CAAC,IAAI,6BAA6B;IACpE,UAAU,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;IAC1C,eAAe,EAAE,QAAQ,CAAC,mBAAmB,CAAC;IAC9C,YAAY,EAAE,QAAQ,CAAC,gBAAgB,CAAC;IACxC,cAAc,EAAE,QAAQ,CAAC,iBAAiB,CAAC;IAC3C,WAAW,EAAE,QAAQ,CAAC,cAAc,CAAC;IACrC,kBAAkB,EAAE,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAC,IAAI,IAAI,CAAC;IACpE,qBAAqB,EAAE,MAAM,CAAC,QAAQ,CAAC,0BAA0B,CAAC,IAAI,IAAI,CAAC;IAE3E,2EAA2E;IAC3E,yEAAyE;IACzE,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC,IAAI,EAAE,CAAC;IAC5D,eAAe,EAAE,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC,IAAI,EAAE,CAAC;IAC5D,iBAAiB,EAAE,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAC,IAAI,EAAE,CAAC;IAEhE,+DAA+D;IAC/D,sEAAsE;IACtE,sEAAsE;IACtE,kEAAkE;IAClE,MAAM,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,GAAG,CAAC;QACrD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;QACpD,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAClE,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;KACrD;IAED,qBAAqB,EAAE,MAAM,CAAC,QAAQ,CAAC,0BAA0B,CAAC,IAAI,GAAG,CAAC;IAE1E,gFAAgF;IAChF,6EAA6E;IAC7E,yEAAyE;IACzE,SAAS,EAAE,gBAAgB,CAAC;QAC1B,aAAa,EAAE,QAAQ,CAAC,iBAAiB,CAAC;QAC1C,YAAY,EAAE,QAAQ,CAAC,gBAAgB,CAAC;QACxC,oBAAoB,EAAE,QAAQ,CAAC,wBAAwB,CAAC;QACxD,cAAc,EAAE,QAAQ,CAAC,kBAAkB,CAAC;KAC7C,CAAC;CACH,CAAC;AAEF,MAAM,UAAU,eAAe;IAC7B,IAAI,MAAM,CAAC,eAAe;QAAE,OAAO,WAAW,CAAC;IAC/C,IAAI,MAAM,CAAC,YAAY;QAAE,OAAO,QAAQ,CAAC;IACzC,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAC;IACnC,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,IAAI,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,oBAAoB,CAAC,CAAC;AACtI,CAAC"}

package/dist/orchestrator/explore.js

@@ -0,0 +1,67 @@
+// Calls appq's real appq:runman workflow through the shared engine, headlessly
+// (interactive: "false" — no human to answer a mid-run confirmation), offering
+// it real browser_* tools plus a read-only appq context allowlist. The
+// workflow's own methodology (7 phases: prerequisites/URL resolution, context
+// gathering, surface mapping, a senior-QA heuristics pass plus mandatory
+// security/network/caching/mobile probes, an evidence-discipline gate, and a
+// findings report) lives entirely server-side — nothing here duplicates it.
+//
+// Deliberately doesn't structurally parse a bug count or severity out of the
+// returned Markdown report — this agent's job is producing a report for a
+// human or appliqation-autopilot to read and reason about, not a pass/fail
+// verdict a pipeline gates on. budgetExceeded (from LoopResult, unchanged) is
+// the only thing that decides the CLI's exit code — see cli/index.ts.
+import { chromium } from 'playwright';
+import { PlaywrightBrowserTools, BROWSER_TOOL_DEFS, fetchAppqToolDefs, createGatedAppqDispatcher, createReadOnlyProjectContextDispatcher, runWorkflow, } from '@appliqation/agent-core';
+import { READONLY_APPQ_TOOLS } from '../tools/safety.js';
+export async function explore(opts) {
+    const appqToolDefs = await fetchAppqToolDefs(opts.client, READONLY_APPQ_TOOLS);
+    // Argument-level gate applied outermost — see @appliqation/agent-core's
+    // tools/projectContext.ts — so this agent's own attempted
+    // enrich_project_context write (appq:runman's own Phase 6 instruction,
+    // meant for an interactive session with a human at the confirmation gate)
+    // is refused before it ever reaches appq, not silently honored just
+    // because nothing is watching this particular invocation.
+    const gatedAppq = createReadOnlyProjectContextDispatcher(createGatedAppqDispatcher(opts.client, READONLY_APPQ_TOOLS));
+    const browser = await chromium.launch();
+    const page = await browser.newPage();
+    try {
+        const browserTools = new PlaywrightBrowserTools(page, opts.ringBufferCap);
+        const dispatch = async (name, args) => {
+            if (name.startsWith('browser_'))
+                return browserTools.dispatch(name, args);
+            return gatedAppq(name, args);
+        };
+        const promptArgs = {
+            prompt: opts.prompt,
+            interactive: 'false',
+            max_steps: opts.maxSteps,
+            max_pages: opts.maxPages,
+            max_minutes: opts.maxMinutes,
+        };
+        if (opts.projectId !== undefined)
+            promptArgs.project_id = opts.projectId;
+        if (opts.siteUrl)
+            promptArgs.site_url = opts.siteUrl;
+        const seedLines = [`Exploration intent: ${opts.prompt}`];
+        if (opts.siteUrl)
+            seedLines.push(`URL under test: ${opts.siteUrl}`);
+        if (opts.projectId !== undefined)
+            seedLines.push(`Project ID: ${opts.projectId}`);
+        seedLines.push('Begin now — start with browser_snapshot.');
+        return await runWorkflow({
+            source: { kind: 'appq', name: 'appq:runman', args: promptArgs },
+            fetchPrompt: opts.client.fetchPrompt,
+            seedMessage: seedLines.join('\n'),
+            tools: [...BROWSER_TOOL_DEFS, ...appqToolDefs],
+            dispatch,
+            adapter: opts.adapter,
+            budget: opts.budget,
+            onEvent: opts.onEvent,
+        });
+    }
+    finally {
+        await browser.close();
+    }
+}
+//# sourceMappingURL=explore.js.map

package/dist/orchestrator/explore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explore.js","sourceRoot":"","sources":["../../src/orchestrator/explore.ts"],"names":[],"mappings":"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"}

package/dist/tools/safety.js

@@ -0,0 +1,24 @@
+// This agent's own domain knowledge of which appq tools it may touch — the
+// enforcement mechanism (assertToolAllowed / the gated dispatcher) lives in
+// @appliqation/agent-core, shared with every sibling agent; only the
+// allowlist content is local. Genuinely read-only end to end, including
+// enrich_project_context: it's offered here because it has a real read
+// mode this agent needs (known_issues/high_risk_areas inform what's worth
+// exploring), but @appliqation/agent-core's createReadOnlyProjectContextDispatcher
+// refuses its action=write mode unconditionally — see cli/index.ts and
+// README.md's Safety section for why this agent, unlike an interactive
+// appq:runman session, never gets to use it.
+export const READONLY_APPQ_TOOLS = new Set([
+    'get_scenario',
+    'get_coverage_analysis',
+    'get_defects',
+    'get_failure_patterns',
+    'get_quality_context',
+    'get_evidence_summary',
+    'get_run_evidence',
+    'search_tests',
+    'get_project_settings',
+    'enrich_project_context',
+    'get_validation_targets',
+]);
+//# sourceMappingURL=safety.js.map

package/dist/tools/safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.js","sourceRoot":"","sources":["../../src/tools/safety.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,4EAA4E;AAC5E,qEAAqE;AACrE,wEAAwE;AACxE,uEAAuE;AACvE,0EAA0E;AAC1E,mFAAmF;AACnF,uEAAuE;AACvE,uEAAuE;AACvE,6CAA6C;AAE7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC;IACzC,cAAc;IACd,uBAAuB;IACvB,aAAa;IACb,sBAAsB;IACtB,qBAAqB;IACrB,sBAAsB;IACtB,kBAAkB;IAClB,cAAc;IACd,sBAAsB;IACtB,wBAAwB;IACxB,wBAAwB;CACzB,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@appliqation/explorer",
+  "version": "0.1.1",
+  "description": "Standalone agent that runs Appliqation's exploratory-QA workflow (appq:runman) headlessly against a live app under test \u2014 the same senior-QA heuristics pass, without a human at the confirmation gate.",
+  "type": "module",
+  "bin": {
+    "appliqation-explorer": "./dist/cli/index.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/cli/index.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src --ext .ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@appliqation/agent-core": "^0.1.0",
+    "commander": "^13.1.0",
+    "dotenv": "^16.4.7",
+    "playwright": "^1.51.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.7"
+  }
+}