@ia-qa/qa-discovery 0.1.0

package/dist/cli-ai/index.js

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = exports.CLASSIFICATION_FILENAME = exports.CLASSIFICATION_SCHEMA = void 0;
+exports.main = main;
+exports.runClassify = runClassify;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const self_healing_1 = require("@ia-qa/self-healing");
+const config_1 = require("../config");
+const citations_1 = require("../citations");
+const classify_1 = require("../ai/classify");
+Object.defineProperty(exports, "CLASSIFICATION_FILENAME", { enumerable: true, get: function () { return classify_1.CLASSIFICATION_FILENAME; } });
+Object.defineProperty(exports, "CLASSIFICATION_SCHEMA", { enumerable: true, get: function () { return classify_1.CLASSIFICATION_SCHEMA; } });
+const taxonomy_1 = require("../taxonomy");
+const overviewFile_1 = require("../overviewFile");
+/**
+ * `ia-qa-discover-ai` — the optional, BYOK classification layer.
+ *
+ * A separate binary for the same reason `ia-qa-heal-ai` is one: the
+ * deterministic verbs must behave identically whether or not anyone has a key,
+ * and a flag on `scan` would blur that. `scan` never calls a model; this reads
+ * what `scan` already wrote, offline, and adds a layer a human reviews.
+ *
+ * It produces no verdict and gates nothing. Every claim it keeps cites a path
+ * into the capture that was resolved and checked; every claim it drops says why.
+ */
+const VERSION = require('../../package.json').version;
+const HELP = `ia-qa-discover-ai — optional BYOK classification for a discovery capture
+
+What each entry point your app exposes is FOR, and how sensitive what it handles
+is. Reads .ia-qa-discovery/capture/ offline — it never opens a browser and never
+touches your application. Your key, your model, your machine.
+
+Every classification carries a sentence you read and a path into the capture that
+this tool resolves and checks before keeping it. A claim that cites nothing, cites
+something that does not exist, or misdescribes what it cites, is DROPPED and the
+drop is reported. That check proves the premise, never the conclusion: only you
+can say whether the reading follows.
+
+Nothing here is a gate. \`ia-qa-discover\` works fully without a key.
+
+Usage:
+  ia-qa-discover-ai classify              Classify every entry point in the capture.
+                                            --page <name>  just this page
+                                            --json         machine-readable output
+                                            --dry-run      show what would be sent, call nothing
+  ia-qa-discover-ai models                List the providers and models you can configure
+  ia-qa-discover-ai version               Print the installed version
+  ia-qa-discover-ai help                  Show this help
+
+Configure it in ${config_1.CONFIG_DIR}/config.json:
+
+  "ai": {
+    "provider": "anthropic",
+    "model": "claude-haiku-4-5",
+    "apiKey": { "source": "env", "key": "ANTHROPIC_API_KEY" }
+  }
+
+The key itself never goes in that file — only the name of the variable holding it.
+
+Global:
+  --config <dir>   Resolve ${config_1.CONFIG_DIR}/ under <dir> instead of the current directory
+`;
+exports.HELP = HELP;
+/**
+ * Read the `ai` block and resolve its key. Returns null — having already
+ * explained itself and set exit code 2 — rather than throwing, because every
+ * failure here is a configuration problem the user can act on.
+ */
+async function resolveAi() {
+    if (!(0, config_1.configExists)()) {
+        console.error(`❌ No ${config_1.CONFIG_DIR}/config.json here.\n` +
+            `   Run \`ia-qa-discover scan <url> --save\` first: this tool classifies a capture,\n` +
+            `   it does not make one.`);
+        process.exitCode = 2;
+        return null;
+    }
+    const ai = (0, config_1.loadConfig)().ai;
+    if (!ai) {
+        console.error(`❌ No "ai" block in ${config_1.CONFIG_DIR}/config.json, so there is no model to call.\n\n` +
+            `   Add one:\n` +
+            `     "ai": { "provider": "anthropic", "model": "claude-haiku-4-5",\n` +
+            `             "apiKey": { "source": "env", "key": "ANTHROPIC_API_KEY" } }\n\n` +
+            `   \`ia-qa-discover-ai models\` lists what you can put there.\n` +
+            `   The deterministic \`ia-qa-discover\` works fully without any of this.`);
+        process.exitCode = 2;
+        return null;
+    }
+    const provider = (0, self_healing_1.findProvider)(ai.provider ?? '');
+    if (!provider) {
+        console.error(`❌ Unknown ai.provider "${ai.provider}". Use one of: ${self_healing_1.AI_PROVIDERS.map((p) => p.id).join(', ')}.\n` +
+            `   Run \`ia-qa-discover-ai models\` to see them with their models.`);
+        process.exitCode = 2;
+        return null;
+    }
+    if (!ai.model) {
+        console.error(`❌ ai.model is required — pin one, so two runs are comparable. See \`ia-qa-discover-ai models\`.`);
+        process.exitCode = 2;
+        return null;
+    }
+    if (!ai.apiKey) {
+        console.error(`❌ ai.apiKey is required. It is a REFERENCE, never the key itself:\n` +
+            `     "apiKey": { "source": "env", "key": "${provider.keyEnv}" }`);
+        process.exitCode = 2;
+        return null;
+    }
+    // The common case — an env var — is handled here rather than delegated,
+    // because `resolveSecret`'s own message is written for the other package: it
+    // names `ia-qa-heal`, its CLI path and `.ia-qa/config.json`, and sending
+    // someone here to a different tool's config is worse than no help at all.
+    // Everything else (AWS SSM) still delegates: one secret path, not two.
+    if (ai.apiKey.source === 'env' && !process.env[ai.apiKey.key]) {
+        console.error(`❌ Environment variable "${ai.apiKey.key}" is not set, so there is no key to call ${provider.label} with.\n\n` +
+            `   This CLI reads process.env only — it never loads .env files, so a key that lives\n` +
+            `   only in .env will not be seen. Put it in the environment first:\n` +
+            `     npx dotenv-cli -- ia-qa-discover-ai classify\n\n` +
+            `   The value never belongs in ${config_1.CONFIG_DIR}/config.json, which holds references only.`);
+        process.exitCode = 2;
+        return null;
+    }
+    try {
+        const apiKey = await (0, self_healing_1.resolveSecret)(ai.apiKey);
+        return { provider: provider.id, model: ai.model, apiKey };
+    }
+    catch (e) {
+        console.error(`❌ ${e instanceof Error ? e.message : String(e)}`);
+        process.exitCode = 2;
+        return null;
+    }
+}
+function flag(args, name) {
+    const i = args.indexOf(name);
+    if (i === -1)
+        return undefined;
+    const next = args[i + 1];
+    if (!next || next.startsWith('-'))
+        throw new Error(`${name} needs a value.`);
+    return next;
+}
+async function runClassify(args) {
+    const json = args.includes('--json');
+    const dryRun = args.includes('--dry-run');
+    const only = flag(args, '--page');
+    const index = (0, citations_1.loadCaptureIndex)();
+    if (index.pages.size === 0) {
+        console.error(`❌ No capture in ${path.relative(process.cwd(), (0, config_1.captureDir)()) || (0, config_1.captureDir)()}.\n` +
+            `   Run \`ia-qa-discover scan\` first.`);
+        process.exitCode = 2;
+        return;
+    }
+    const pages = [...index.pages.values()].filter((p) => !only || p.page === only);
+    if (pages.length === 0) {
+        console.error(`❌ No page "${only}" in the capture. Have: ${[...index.pages.keys()].join(', ')}`);
+        process.exitCode = 2;
+        return;
+    }
+    const withEntryPoints = pages.filter((p) => (0, classify_1.entryPointsOf)(p).length > 0);
+    if (dryRun) {
+        // What would be sent, and to whom — before any key is even resolved.
+        console.log(`Would classify ${withEntryPoints.length} page(s) with entry points, of ${pages.length} captured:`);
+        for (const p of withEntryPoints)
+            console.log(`  ${p.page}  —  ${(0, classify_1.entryPointsOf)(p).length} entry point(s)`);
+        const skipped = pages.length - withEntryPoints.length;
+        if (skipped > 0)
+            console.log(`  (${skipped} page(s) take no input and would not be sent at all)`);
+        // Naming the destination is the whole point of a dry run: someone runs it to
+        // decide whether these strings may go, and "to whom" is half that decision.
+        const declared = ((0, config_1.configExists)() ? (0, config_1.loadConfig)().ai : undefined) ?? {};
+        const provider = (0, self_healing_1.findProvider)(declared.provider ?? '');
+        if (provider)
+            console.log((0, classify_1.egressNotice)(provider.id, declared.model ?? '(no model set)', withEntryPoints.length, true));
+        console.log(`Nothing was called. Drop --dry-run to run it.`);
+        return;
+    }
+    const ai = await resolveAi();
+    if (!ai)
+        return;
+    if (!json) {
+        console.log(`🤖 ${ai.provider}/${ai.model} · ${withEntryPoints.length} page(s) with entry points · ${taxonomy_1.TAXONOMY_VERSION}`);
+        console.log(`   Reading the capture offline. Your app is not touched.`);
+    }
+    // "Offline" above means no browser, and on its own it reads as "nothing leaves".
+    // stderr in every mode, `--json` included — a security announcement, not decoration.
+    console.error((0, classify_1.egressNotice)(ai.provider, ai.model, withEntryPoints.length));
+    const perPage = {};
+    for (const page of withEntryPoints) {
+        const result = await (0, classify_1.classifyPage)(page, index, { provider: ai.provider, model: ai.model, apiKey: ai.apiKey });
+        perPage[page.page] = result;
+        if (!json) {
+            if (result.failed) {
+                console.log(`  ${page.page.padEnd(22)} ✘ ${result.failed.reason}`);
+            }
+            else {
+                const bits = [`${result.kept.length} classified`];
+                if (result.refused.length > 0)
+                    bits.push(`${result.refused.length} refused`);
+                if (result.dropped.length > 0)
+                    bits.push(`${result.dropped.length} dropped`);
+                console.log(`  ${page.page.padEnd(22)} ${bits.join(' · ')}`);
+            }
+        }
+    }
+    // A call that did not happen is not a page with nothing on it. Reported before
+    // any total, and it sets a non-zero exit: with an invalid key this used to
+    // print "0 classified · 0 refused · 0 dropped", exit 0, and write a file —
+    // indistinguishable from an app that genuinely has nothing to classify.
+    const failures = Object.entries(perPage).filter(([, r]) => r.failed);
+    if (failures.length > 0) {
+        console.error(`\n❌ ${failures.length} of ${withEntryPoints.length} page(s) could not be classified at all:`);
+        for (const [name, r] of failures.slice(0, 5))
+            console.error(`   ${name}: ${r.failed.reason}`);
+        if (failures.length > 5)
+            console.error(`   …and ${failures.length - 5} more.`);
+        console.error(`   Nothing is wrong with your app or your capture — the model call did not succeed.`);
+        process.exitCode = 2;
+        if (failures.length === withEntryPoints.length) {
+            // Nothing to WRITE — a document of failures would overwrite a previous good
+            // classification with the record of a bad key. But not writing is not a
+            // reason to say nothing: `--json` promised stdout a document, and an empty
+            // stdout with exit 2 is indistinguishable from a crashed process. So the
+            // failures go out on stdout, and only the file is skipped.
+            if (json) {
+                console.log(JSON.stringify({ schema: classify_1.CLASSIFICATION_SCHEMA, taxonomyVersion: taxonomy_1.TAXONOMY_VERSION, classifiedAt: new Date().toISOString(), model: `${ai.provider}/${ai.model}`, totals: { kept: 0, refused: 0, dropped: 0 }, pages: perPage, written: false }, null, 2));
+            }
+            return;
+        }
+    }
+    const kept = Object.values(perPage).flatMap((r) => r.kept);
+    const refused = Object.values(perPage).flatMap((r) => r.refused);
+    const dropped = Object.values(perPage).flatMap((r) => r.dropped);
+    const document = {
+        schema: classify_1.CLASSIFICATION_SCHEMA,
+        taxonomyVersion: taxonomy_1.TAXONOMY_VERSION,
+        classifiedAt: new Date().toISOString(),
+        model: `${ai.provider}/${ai.model}`,
+        totals: { kept: kept.length, refused: refused.length, dropped: dropped.length },
+        pages: perPage,
+    };
+    const file = path.join((0, config_1.baseDir)(), config_1.CONFIG_DIR, classify_1.CLASSIFICATION_FILENAME);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(document, null, 2) + '\n', 'utf8');
+    // `classification.json` is not where anyone looks. `_overview.md` is, and
+    // `scan` wrote it before this classification existed — so it is rewritten
+    // here, which is also the only moment the classification is NOT stale.
+    // A refusal is reported, never swallowed: an overview silently left at its
+    // previous content is a report that disagrees with the file beside it.
+    const refreshed = (0, overviewFile_1.refreshOverview)();
+    if (!refreshed.ok)
+        console.error(`\n⚠  _overview.md was not updated: ${refreshed.reason}`);
+    if (json) {
+        console.log(JSON.stringify({ ...document, overview: refreshed.ok ? refreshed.file : null }, null, 2));
+        return;
+    }
+    console.log(`\n${kept.length} classified · ${refused.length} refused · ${dropped.length} dropped`);
+    // The security work this unlocks, deterministically — the point of classifying
+    // at all. Deduplicated across entry points: one tool per reason, not per field.
+    const tools = new Map();
+    for (const k of kept) {
+        for (const t of k.securityTools ?? []) {
+            if (!tools.has(t.tool))
+                tools.set(t.tool, new Set());
+            tools.get(t.tool).add(k.entryPoint.split('#')[0].replace(/^pages\//, '').replace(/\.json$/, ''));
+        }
+    }
+    if (tools.size > 0) {
+        console.log(`\n🔐 Security checks this selects (they already exist on the ia-qa.com MCP):`);
+        for (const [tool, pagesFor] of tools) {
+            console.log(`   ${tool.padEnd(24)} for ${[...pagesFor].join(', ')}`);
+        }
+    }
+    if (refused.length > 0) {
+        console.log(`\n${refused.length} entry point(s) the model would not label. That is an answer, not a gap —` +
+            `\nthe evidence did not support any category. They need a person, not a retry.`);
+    }
+    if (dropped.length > 0) {
+        console.log(`\n${dropped.length} classification(s) dropped because their evidence did not check out:`);
+        for (const d of dropped.slice(0, 5))
+            console.log(`   ${(d.classification.entryPoint ?? '?')} — ${d.reason}`);
+        if (dropped.length > 5)
+            console.log(`   …and ${dropped.length - 5} more (see the JSON).`);
+    }
+    console.log(`\nWritten to ${file}`);
+    console.log(`Every kept claim cites the capture. Read the "why" and the evidence before acting on it.`);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const ci = argv.indexOf('--config');
+    if (ci !== -1) {
+        const dir = argv[ci + 1];
+        if (!dir || dir.startsWith('-'))
+            throw new Error('--config needs a directory argument.');
+        (0, config_1.setBaseDir)(dir);
+        argv.splice(ci, 2);
+    }
+    const [command, ...rest] = argv;
+    switch (command) {
+        case 'classify':
+            await runClassify(rest);
+            break;
+        case 'models':
+            console.log((0, self_healing_1.renderModelList)());
+            break;
+        case 'version':
+        case '--version':
+        case '-v':
+            console.log(VERSION);
+            break;
+        case 'help':
+        case '--help':
+        case '-h':
+        case undefined:
+            console.log(HELP);
+            break;
+        default:
+            console.error(`Unknown command "${command}".\n\n${HELP}`);
+            process.exit(1);
+    }
+}
+/** Only when this file IS the process — so the dispatch stays importable, and testable. */
+if (require.main === module) {
+    main().catch((err) => {
+        console.error(`\n❌ ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/cli-ai/index.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,112 @@
+import type { SecretRef } from '@ia-qa/self-healing';
+/**
+ * Configuration for `@ia-qa/qa-discovery` — `.ia-qa-discovery/config.json`.
+ *
+ * Deliberately a SIBLING of `@ia-qa/self-healing`'s `.ia-qa/`, never nested
+ * inside it: the two tools' local state never overlaps, so a project can run
+ * both without either one reading the other's files by accident.
+ */
+export interface CaptureConfig {
+    /** Observe API/network calls per page. Default true. */
+    network?: boolean;
+    /** Fraction of pages (0-1) a call must appear on to be promoted as shared. Default 0.6. */
+    networkThreshold?: number;
+    /** Click one level of disclosures per page and capture what they reveal. Default false. */
+    deep?: boolean;
+    /** Query param names whose VALUE is kept when normalizing a captured API call. Everything else keeps only the key name. */
+    safeQueryParams?: string[];
+}
+/**
+ * A page the user declares, because a crawl cannot find it.
+ *
+ * Discovery follows `<a href>`. An app that navigates programmatically (React
+ * Router's `useNavigate()`, a button with an onClick handler) exposes no href,
+ * so a crawl reaches exactly the entry URL — measured on a real app: 11 routes,
+ * zero `<Link>`, one page found. Declaring the routes is the deterministic way
+ * out, and they are usually sitting in the router file in plain sight.
+ *
+ * Declared pages are scanned IN ADDITION to whatever the crawl finds, deduped
+ * by path — so declaring some does not turn the crawl off.
+ */
+export interface DeclaredPage {
+    /** Filename for the capture. Defaults to a slug of the URL path. */
+    name?: string;
+    /** Path or absolute URL, resolved against `baseUrl`. */
+    url: string;
+}
+export interface DiscoveryConfig {
+    baseUrl: string;
+    /** Routes a crawl cannot discover on its own. See `DeclaredPage`. */
+    pages?: DeclaredPage[];
+    /** Path to an existing Playwright storageState file (e.g. from self-healing's `login`, or a project's own globalSetup). Never written by this package. */
+    session?: string;
+    locale?: string;
+    crawl?: {
+        maxDepth?: number;
+        maxPages?: number;
+        reveal?: boolean;
+        strictHost?: boolean;
+        /** Read sitemap.xml (robots.txt fallback) as a page source. Default true. */
+        sitemap?: boolean;
+    };
+    capture?: CaptureConfig;
+    /**
+     * Optional BYOK config for . Its absence means the AI layer
+     * is inert and every deterministic verb behaves exactly as it does today.
+     *  is a REFERENCE (env var name / SSM parameter), never the value:
+     * config.json is meant to be committed.
+     */
+    ai?: {
+        provider: string;
+        /** Pinned, so two runs are comparable. */
+        model: string;
+        apiKey: SecretRef;
+    };
+}
+export declare const CONFIG_DIR = ".ia-qa-discovery";
+export declare const CAPTURE_DIRNAME = "capture";
+export declare const HISTORY_FILENAME = "history.jsonl";
+/**
+ * A browser session saved by `ia-qa-discover login`, in Playwright
+ * `storageState` shape. It holds live cookies: whoever has this file is logged
+ * in as that user. It is the one artefact in `.ia-qa-discovery/` that is a
+ * secret — never uploaded anywhere, and `login` writes
+ * `.ia-qa-discovery/.gitignore` so a commit cannot carry it.
+ */
+export declare const SESSION_FILENAME = "session.json";
+/** Set the base dir (the `--config <dir>` flag). `null` clears it back to the default. */
+export declare function setBaseDir(dir: string | null): void;
+export declare function baseDir(): string;
+export declare function configPath(cwd?: string): string;
+export declare function captureDir(cwd?: string): string;
+export declare function historyPath(cwd?: string): string;
+export declare function loadConfig(cwd?: string): DiscoveryConfig;
+export declare function saveConfig(config: DiscoveryConfig, cwd?: string): string;
+export declare function configExists(cwd?: string): boolean;
+export declare function sessionPath(cwd?: string): string;
+export type SessionSource = 'flag' | 'env' | 'config' | 'login';
+export interface SessionChoice {
+    file: string;
+    source: SessionSource;
+}
+/**
+ * Which session file to *write* — `login`'s target. Same precedence as
+ * reading, minus the existence check: pointing `session` at a path is also a
+ * way of saying where you want it kept, so `login` refreshes THAT file rather
+ * than leaving a second one beside it for `scan` to have to choose between.
+ */
+export declare function sessionTarget(config: Pick<DiscoveryConfig, 'session'> | undefined, explicit?: string, cwd?: string): SessionChoice;
+/**
+ * The session to *read*, or null when there is none to read.
+ *
+ * A session the user NAMED — a flag, an env var, a config field — that cannot
+ * be used is a hard error, never a silent fall-through. Ignoring it would
+ * capture the login page under the names of their real pages and exit 0, which
+ * is the false green this whole package must avoid. The default location is
+ * different: absent simply means nobody has run `login` yet.
+ *
+ * The shape check is deliberately shallow — `cookies` is enough to tell a
+ * storageState from a config file pasted by mistake. The file is a secret: it
+ * is never read for anything else, never logged, never sent anywhere.
+ */
+export declare function resolveSession(config: Pick<DiscoveryConfig, 'session'> | undefined, explicit?: string, cwd?: string): SessionChoice | null;