@qulib/core 0.1.0

package/README.md

@@ -0,0 +1,146 @@
+# @qulib/core
+
+**@qulib/core** is the TypeScript-first Qulib package for analyzing deployed web apps (and optionally a local repo) and surfacing honest quality gaps.
+
+## Install
+
+```bash
+npm install @qulib/core
+```
+
+## CLI (from npm)
+
+```bash
+npx @qulib/core analyze --url https://example.com
+```
+
+Use `npx playwright install chromium` the first time you scan (Playwright is a dependency).
+
+## Programmatic API
+
+```ts
+import { analyzeApp, type HarnessConfig } from '@qulib/core';
+
+const config: HarnessConfig = {
+  maxPagesToScan: 20,
+  maxDepth: 3,
+  minPagesForConfidence: 3,
+  timeoutMs: 30000,
+  retryCount: 2,
+  llmTokenBudget: 4000,
+  testGenerationLimit: 10,
+  readOnlyMode: true,
+  requireHumanReview: true,
+  failOnConsoleError: false,
+  explorer: 'playwright',
+  defaultAdapter: 'playwright',
+  adapters: ['playwright', 'cypress-e2e'],
+};
+
+const result = await analyzeApp({
+  url: 'https://example.com',
+  config,
+  writeArtifacts: false,
+});
+
+console.log(result.releaseConfidence, result.gapAnalysis);
+```
+
+## Repository
+
+Source and issues: **[github.com/TapeshN/qulib](https://github.com/TapeshN/qulib)**.
+
+## Monorepo context
+
+This package is part of **[Qulib](https://github.com/TapeshN/qulib)** ([repo README](../../README.md)). Install dependencies from the repository root: `npm install`. Build all packages: `npm run build` (from root).
+
+## Current capabilities
+
+- CLI `analyze` flow: `observe` → `think` → `act`.
+- Playwright explorer: route discovery, **axe-core** (WCAG 2.0 A/AA), sampled internal link HEAD checks.
+- Optional **authenticated** crawling via `auth` in config (`form-login` or Playwright `storage-state`).
+- Repo scanner: routes, tests, Cypress structure.
+- Gap engine: deterministic gaps, **release confidence** with a low-page coverage floor, coverage warnings.
+- Reports: `output/report.json` and `output/report.md` when not using **`--ephemeral`**.
+- State under `.scan-state/` unless **`--ephemeral`** (no disk writes; full JSON on stdout).
+- **`npm run clean`** removes generated `output/` and `.scan-state/` and restores `.gitkeep` placeholders.
+
+## Tech stack
+
+TypeScript (strict, NodeNext), Commander, Zod, Playwright, @axe-core/playwright, fast-glob; optional Anthropic API for scenario generation.
+
+## Layout
+
+```text
+src/
+  adapters/      # test rendering adapters
+  analyze.ts     # programmatic API (also used by @qulib/mcp)
+  cli/           # CLI entry
+  harness/       # state + decision logging
+  llm/           # LLM contracts
+  phases/        # observe / think / act
+  reporters/     # JSON + Markdown reports
+  schemas/       # Zod schemas
+  tools/         # explorers, auth, gap engine, repo scanner
+```
+
+Repo rules: see [`CLAUDE.md`](../../CLAUDE.md).
+
+## Configuration
+
+Default file: **`qulib.config.ts`** in this package directory (or pass **`--config <path>`** relative to the process working directory).
+
+Optional `auth` for authenticated scanning — see commented example in `qulib.config.ts`. For local credentials, use a separate file (e.g. `qulib.test-auth.config.ts`, gitignored at the repo root) and point `--config` at it.
+
+Use the same **origin** for `--url` as the app uses after login so same-origin links are discovered during the crawl.
+
+## Scripts (from `packages/core`)
+
+- `npm run dev` — CLI via `tsx` (append subcommands, e.g. `npm run dev -- clean`)
+- `npm run analyze -- --url <url> [--repo <path>] [--config <file>] [--ephemeral]`
+- `npm run clean` — reset `output/` and `.scan-state/` here
+- `npm run build` — compile to `dist/`
+
+From the **repository root**:
+
+- `npm run analyze -w @qulib/core -- --url <url> …`
+- `npm run clean` — runs core clean via workspace
+
+Binary name after publish: **`qulib`** (see `package.json` `bin`).
+
+## Usage examples
+
+```bash
+cd packages/core
+
+# app only
+npm run analyze -- --url http://localhost:3000
+
+# app + repo
+npm run analyze -- --url http://localhost:3000 --repo ../your-app
+
+# local auth config (keep out of git)
+npm run analyze -- --config ../../qulib.test-auth.config.ts --url https://example.com
+
+# ephemeral: JSON on stdout, logs on stderr
+npm run analyze -- --url https://example.com --ephemeral > report.bundle.json
+
+npm run clean
+```
+
+## Playwright browsers
+
+```bash
+npx playwright install chromium
+```
+
+## Output and state (cwd = `packages/core` when you `cd` here)
+
+**Ephemeral:** stdout prints one JSON object: `gapAnalysis`, `discoveredRoutes`, `repoInventory`, `decisionLog`.
+
+**Persistent:**
+
+- `.scan-state/discovered-routes.json`, `gap-analysis.json`, `decision-log.json`, and `repo-inventory.json` when `--repo` is set
+- `output/report.json`, `output/report.md`
+
+For more options (`repoPath`, loading config from disk), see `src/analyze.ts` in the repository.

package/bin/qulib.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const cliPath = resolve(__dirname, '../src/cli/index.ts');
+
+const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+const child = spawn(npxCmd, ['tsx', cliPath, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+
+child.on('exit', (code) => {
+  process.exit(code ?? 1);
+});

package/dist/adapters/adapter-factory.d.ts

@@ -0,0 +1,5 @@
+import type { AdapterType } from '../schemas/config.schema.js';
+import type { TestAdapter } from './adapter.interface.js';
+export declare function createAdapter(type: AdapterType): TestAdapter;
+export declare function createAdapters(types: AdapterType[]): TestAdapter[];
+//# sourceMappingURL=adapter-factory.d.ts.map

package/dist/adapters/adapter-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-factory.d.ts","sourceRoot":"","sources":["../../src/adapters/adapter-factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAM1D,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,WAAW,CAa5D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAElE"}

package/dist/adapters/adapter-factory.js

@@ -0,0 +1,21 @@
+import { PlaywrightAdapter } from './playwright-adapter.js';
+import { CypressE2EAdapter } from './cypress-e2e-adapter.js';
+import { CypressComponentAdapter } from './cypress-component-adapter.js';
+import { ApiAdapter } from './api-adapter.js';
+export function createAdapter(type) {
+    switch (type) {
+        case 'playwright':
+            return new PlaywrightAdapter();
+        case 'cypress-e2e':
+            return new CypressE2EAdapter();
+        case 'cypress-component':
+            return new CypressComponentAdapter();
+        case 'api':
+            return new ApiAdapter();
+        default:
+            throw new Error(`Unknown adapter type: ${type}`);
+    }
+}
+export function createAdapters(types) {
+    return types.map(createAdapter);
+}

package/dist/adapters/adapter.interface.d.ts

@@ -0,0 +1,7 @@
+import type { NeutralScenario, GeneratedTest } from '../schemas/gap-analysis.schema.js';
+export interface TestAdapter {
+    readonly adapterType: string;
+    render(scenario: NeutralScenario): GeneratedTest;
+    renderAll(scenarios: NeutralScenario[]): GeneratedTest[];
+}
+//# sourceMappingURL=adapter.interface.d.ts.map

package/dist/adapters/adapter.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.interface.d.ts","sourceRoot":"","sources":["../../src/adapters/adapter.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAExF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa,CAAC;IACjD,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE,CAAC;CAC1D"}

package/dist/adapters/adapter.interface.js

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

package/dist/adapters/api-adapter.d.ts

@@ -0,0 +1,8 @@
+import type { TestAdapter } from './adapter.interface.js';
+import type { NeutralScenario, GeneratedTest } from '../schemas/gap-analysis.schema.js';
+export declare class ApiAdapter implements TestAdapter {
+    readonly adapterType = "api";
+    render(scenario: NeutralScenario): GeneratedTest;
+    renderAll(scenarios: NeutralScenario[]): GeneratedTest[];
+}
+//# sourceMappingURL=api-adapter.d.ts.map

package/dist/adapters/api-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/api-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAExF,qBAAa,UAAW,YAAW,WAAW;IAC5C,QAAQ,CAAC,WAAW,SAAS;IAE7B,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IAIhD,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE;CAGzD"}

package/dist/adapters/api-adapter.js

@@ -0,0 +1,9 @@
+export class ApiAdapter {
+    adapterType = 'api';
+    render(scenario) {
+        throw new Error('Not implemented');
+    }
+    renderAll(scenarios) {
+        throw new Error('Not implemented');
+    }
+}

package/dist/adapters/cypress-component-adapter.d.ts

@@ -0,0 +1,8 @@
+import type { TestAdapter } from './adapter.interface.js';
+import type { NeutralScenario, GeneratedTest } from '../schemas/gap-analysis.schema.js';
+export declare class CypressComponentAdapter implements TestAdapter {
+    readonly adapterType = "cypress-component";
+    render(scenario: NeutralScenario): GeneratedTest;
+    renderAll(scenarios: NeutralScenario[]): GeneratedTest[];
+}
+//# sourceMappingURL=cypress-component-adapter.d.ts.map

package/dist/adapters/cypress-component-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cypress-component-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/cypress-component-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAExF,qBAAa,uBAAwB,YAAW,WAAW;IACzD,QAAQ,CAAC,WAAW,uBAAuB;IAE3C,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IAIhD,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE;CAGzD"}

package/dist/adapters/cypress-component-adapter.js

@@ -0,0 +1,9 @@
+export class CypressComponentAdapter {
+    adapterType = 'cypress-component';
+    render(scenario) {
+        throw new Error('Not implemented');
+    }
+    renderAll(scenarios) {
+        throw new Error('Not implemented');
+    }
+}

package/dist/adapters/cypress-e2e-adapter.d.ts

@@ -0,0 +1,8 @@
+import type { TestAdapter } from './adapter.interface.js';
+import type { NeutralScenario, GeneratedTest } from '../schemas/gap-analysis.schema.js';
+export declare class CypressE2EAdapter implements TestAdapter {
+    readonly adapterType = "cypress-e2e";
+    render(scenario: NeutralScenario): GeneratedTest;
+    renderAll(scenarios: NeutralScenario[]): GeneratedTest[];
+}
+//# sourceMappingURL=cypress-e2e-adapter.d.ts.map

package/dist/adapters/cypress-e2e-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cypress-e2e-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/cypress-e2e-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAExF,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,WAAW,iBAAiB;IAErC,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IAIhD,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE;CAGzD"}

package/dist/adapters/cypress-e2e-adapter.js

@@ -0,0 +1,9 @@
+export class CypressE2EAdapter {
+    adapterType = 'cypress-e2e';
+    render(scenario) {
+        throw new Error('Not implemented');
+    }
+    renderAll(scenarios) {
+        throw new Error('Not implemented');
+    }
+}

package/dist/adapters/playwright-adapter.d.ts

@@ -0,0 +1,8 @@
+import type { TestAdapter } from './adapter.interface.js';
+import type { NeutralScenario, GeneratedTest } from '../schemas/gap-analysis.schema.js';
+export declare class PlaywrightAdapter implements TestAdapter {
+    readonly adapterType = "playwright";
+    render(scenario: NeutralScenario): GeneratedTest;
+    renderAll(scenarios: NeutralScenario[]): GeneratedTest[];
+}
+//# sourceMappingURL=playwright-adapter.d.ts.map

package/dist/adapters/playwright-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-adapter.d.ts","sourceRoot":"","sources":["../../src/adapters/playwright-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAExF,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,WAAW,gBAAgB;IAEpC,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IAIhD,SAAS,CAAC,SAAS,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE;CAGzD"}

package/dist/adapters/playwright-adapter.js

@@ -0,0 +1,9 @@
+export class PlaywrightAdapter {
+    adapterType = 'playwright';
+    render(scenario) {
+        throw new Error('Not implemented');
+    }
+    renderAll(scenarios) {
+        throw new Error('Not implemented');
+    }
+}

package/dist/analyze.d.ts

@@ -0,0 +1,20 @@
+import type { HarnessConfig } from './schemas/config.schema.js';
+import type { GapAnalysis } from './schemas/gap-analysis.schema.js';
+import type { RouteInventory } from './schemas/route-inventory.schema.js';
+import type { RepoAnalysis } from './schemas/repo-analysis.schema.js';
+import type { DecisionLogEntry } from './schemas/decision-log.schema.js';
+export interface AnalyzeOptions {
+    url: string;
+    repoPath?: string;
+    config: HarnessConfig;
+    writeArtifacts?: boolean;
+}
+export interface AnalyzeResult {
+    releaseConfidence: number;
+    gapAnalysis: GapAnalysis;
+    routeInventory: RouteInventory;
+    repoInventory: RepoAnalysis | null;
+    decisionLog: DecisionLogEntry[];
+}
+export declare function analyzeApp(options: AnalyzeOptions): Promise<AnalyzeResult>;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAKzE,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,WAAW,CAAC;IACzB,cAAc,EAAE,cAAc,CAAC;IAC/B,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,WAAW,EAAE,gBAAgB,EAAE,CAAC;CACjC;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAmBhF"}

package/dist/analyze.js

@@ -0,0 +1,21 @@
+import { observe } from './phases/observe.js';
+import { think } from './phases/think.js';
+import { act } from './phases/act.js';
+export async function analyzeApp(options) {
+    const writeArtifacts = options.writeArtifacts ?? false;
+    const decisionLog = [];
+    const artifacts = {
+        writeArtifacts,
+        decisionMemory: decisionLog,
+    };
+    const observed = await observe(options.url, options.repoPath, options.config, artifacts);
+    const analysis = await think(observed, options.config, artifacts);
+    await act(analysis, options.config, artifacts);
+    return {
+        releaseConfidence: analysis.releaseConfidence,
+        gapAnalysis: analysis,
+        routeInventory: observed.routes,
+        repoInventory: observed.repo,
+        decisionLog,
+    };
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}

package/dist/cli/index.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+import { HarnessConfigSchema } from '../schemas/config.schema.js';
+import { analyzeApp } from '../analyze.js';
+const program = new Command();
+const AnalyzeUrlSchema = z.string().url();
+async function loadConfigFile(relativePath) {
+    const configPath = resolve(process.cwd(), relativePath);
+    const configModule = await import(pathToFileURL(configPath).href);
+    return HarnessConfigSchema.parse(configModule.default);
+}
+function redactConfigForLog(config) {
+    const base = { ...config };
+    if (config.auth?.type === 'form-login') {
+        base.auth = {
+            ...config.auth,
+            credentials: {
+                username: config.auth.credentials.username,
+                password: '***',
+            },
+        };
+    }
+    return base;
+}
+async function runAnalyze(options) {
+    const validatedUrl = AnalyzeUrlSchema.parse(options.url);
+    const mode = options.repo ? 'url-repo' : 'url-only';
+    const config = await loadConfigFile(options.configFile ?? 'qulib.config.ts');
+    const ephemeral = options.ephemeral ?? false;
+    const writeArtifacts = !ephemeral;
+    if (ephemeral) {
+        console.error('[qulib] Ephemeral mode: no disk writes; full result JSON on stdout');
+    }
+    else {
+        console.log('[qulib] Detected mode:', mode);
+        console.log('[qulib] Active config:', redactConfigForLog(config));
+    }
+    const result = await analyzeApp({
+        url: validatedUrl,
+        repoPath: options.repo,
+        config,
+        writeArtifacts,
+    });
+    if (ephemeral) {
+        console.log(JSON.stringify({
+            gapAnalysis: result.gapAnalysis,
+            discoveredRoutes: result.routeInventory,
+            repoInventory: result.repoInventory,
+            decisionLog: result.decisionLog,
+        }, null, 2));
+    }
+}
+program
+    .name('qulib')
+    .description('Qulib — QA harness')
+    .version('0.1.0');
+program
+    .command('clean')
+    .description('Remove all generated reports and scan state')
+    .action(async () => {
+    const fs = await import('node:fs/promises');
+    const targets = ['output', '.scan-state'];
+    for (const target of targets) {
+        try {
+            await fs.rm(target, { recursive: true, force: true });
+            console.log(`[qulib] removed ${target}/`);
+        }
+        catch (err) {
+            console.error(`[qulib] failed to remove ${target}/: ${String(err)}`);
+        }
+    }
+    await fs.mkdir('output', { recursive: true });
+    await fs.writeFile('output/.gitkeep', 'This folder is generated by `qulib analyze`. It contains report.json, report.md,\nand a `generated/` subfolder with test scaffolds. Run `qulib clean` to reset.\n', 'utf8');
+    await fs.mkdir('.scan-state', { recursive: true });
+    await fs.writeFile('.scan-state/.gitkeep', '', 'utf8');
+    console.log('[qulib] clean complete');
+});
+program
+    .command('analyze')
+    .description('Analyze an app for quality gaps')
+    .requiredOption('--url <url>', 'Base URL of the app to analyze')
+    .option('--repo <path>', 'Path to the app repo')
+    .option('--prd <path>', 'Path to a PRD markdown file')
+    .option('--config <file>', 'Path to config file (relative to cwd)', 'qulib.config.ts')
+    .option('--adapter <type>', 'Override default test adapter (playwright, cypress-e2e, cypress-component, api)', 'playwright')
+    .option('--ephemeral', 'Do not write to disk — return full report as JSON on stdout (use for MCP/CI)', false)
+    .action(async (options) => {
+    await runAnalyze({
+        url: options.url,
+        repo: options.repo,
+        configFile: options.config,
+        ephemeral: options.ephemeral,
+    });
+});
+program.parseAsync().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error('[qulib] Analyze failed:', message);
+    process.exit(1);
+});

package/dist/harness/decision-logger.d.ts

@@ -0,0 +1,7 @@
+import type { DecisionLogEntry } from '../schemas/decision-log.schema.js';
+export type LogDecisionOptions = {
+    persist?: boolean;
+    memory?: DecisionLogEntry[];
+};
+export declare function logDecision(entry: DecisionLogEntry, options?: LogDecisionOptions): Promise<void>;
+//# sourceMappingURL=decision-logger.d.ts.map

package/dist/harness/decision-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-logger.d.ts","sourceRoot":"","sources":["../../src/harness/decision-logger.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAK1E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC7B,CAAC;AAEF,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwDtG"}

package/dist/harness/decision-logger.js

@@ -0,0 +1,68 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { DecisionLogEntrySchema } from '../schemas/decision-log.schema.js';
+const LOG_FILE = join(process.cwd(), '.scan-state', 'decision-log.json');
+const STATE_DIR = join(process.cwd(), '.scan-state');
+export async function logDecision(entry, options) {
+    const persist = options?.persist !== false;
+    const memory = options?.memory;
+    try {
+        const validation = DecisionLogEntrySchema.safeParse(entry);
+        if (!validation.success) {
+            console.warn(`Failed to log decision entry to ${LOG_FILE}: validation issues ${JSON.stringify(validation.error.issues)}`);
+            return;
+        }
+        if (memory) {
+            memory.push(validation.data);
+        }
+        if (!persist) {
+            return;
+        }
+        await mkdir(STATE_DIR, { recursive: true });
+        let log = [];
+        if (existsSync(LOG_FILE)) {
+            try {
+                const raw = await readFile(LOG_FILE, 'utf8');
+                const parsed = JSON.parse(raw);
+                if (!Array.isArray(parsed)) {
+                    console.warn(`Failed to log decision entry to ${LOG_FILE}: file is not a JSON array; resetting log`);
+                }
+                else {
+                    const validatedEntries = [];
+                    for (const item of parsed) {
+                        const itemValidation = DecisionLogEntrySchema.safeParse(item);
+                        if (itemValidation.success) {
+                            validatedEntries.push(itemValidation.data);
+                        }
+                        else {
+                            console.warn(`Invalid existing entry skipped in ${LOG_FILE}: ${JSON.stringify(itemValidation.error.issues)}`);
+                        }
+                    }
+                    log = validatedEntries;
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`Failed to read existing decision log at ${LOG_FILE}: ${message}`);
+            }
+        }
+        log.push(validation.data);
+        await writeFile(LOG_FILE, JSON.stringify(log, null, 2), 'utf8');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`Failed to log decision entry to ${LOG_FILE}: ${message}`);
+    }
+}
+/*
+Manual smoke test:
+
+await logDecision({
+  timestamp: new Date().toISOString(),
+  phase: 'observe',
+  decision: 'Started crawl',
+  reason: 'Initial discovery pass',
+  metadata: { url: 'https://example.com' },
+});
+*/

package/dist/harness/run-options.d.ts

@@ -0,0 +1,6 @@
+import type { DecisionLogEntry } from '../schemas/decision-log.schema.js';
+export type RunArtifactsOptions = {
+    writeArtifacts: boolean;
+    decisionMemory?: DecisionLogEntry[];
+};
+//# sourceMappingURL=run-options.d.ts.map

package/dist/harness/run-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-options.d.ts","sourceRoot":"","sources":["../../src/harness/run-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,MAAM,MAAM,mBAAmB,GAAG;IAChC,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,gBAAgB,EAAE,CAAC;CACrC,CAAC"}

package/dist/harness/run-options.js

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

package/dist/harness/state-manager.d.ts

@@ -0,0 +1,6 @@
+import type { ZodSchema } from 'zod';
+export declare class StateManager {
+    readState<T>(filename: string, schema: ZodSchema<T>): Promise<T>;
+    writeState<T>(filename: string, data: T, schema: ZodSchema<T>): Promise<void>;
+}
+//# sourceMappingURL=state-manager.d.ts.map

package/dist/harness/state-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-manager.d.ts","sourceRoot":"","sources":["../../src/harness/state-manager.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAIrC,qBAAa,YAAY;IACjB,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA8BhE,UAAU,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAiBpF"}

package/dist/harness/state-manager.js

@@ -0,0 +1,64 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { ZodError } from 'zod';
+const STATE_DIR = join(process.cwd(), '.scan-state');
+export class StateManager {
+    async readState(filename, schema) {
+        await mkdir(STATE_DIR, { recursive: true });
+        const filepath = join(STATE_DIR, filename);
+        if (!existsSync(filepath)) {
+            throw new Error(`State file missing: ${filename} (${filepath})`);
+        }
+        let parsedJson;
+        try {
+            const raw = await readFile(filepath, 'utf8');
+            parsedJson = JSON.parse(raw);
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw new Error(`Invalid JSON in state file ${filename}: ${error.message}`);
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to read state file ${filename}: ${message}`);
+        }
+        try {
+            return schema.parse(parsedJson);
+        }
+        catch (error) {
+            if (error instanceof ZodError) {
+                throw new Error(`Schema validation failed for state file ${filename}: ${JSON.stringify(error.issues)}`);
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to validate state file ${filename}: ${message}`);
+        }
+    }
+    async writeState(filename, data, schema) {
+        const filepath = join(STATE_DIR, filename);
+        let validatedData;
+        try {
+            validatedData = schema.parse(data);
+        }
+        catch (error) {
+            if (error instanceof ZodError) {
+                throw new Error(`Schema validation failed for state file ${filename}: ${JSON.stringify(error.issues)}`);
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Failed to validate state data for ${filename}: ${message}`);
+        }
+        await mkdir(STATE_DIR, { recursive: true });
+        await writeFile(filepath, JSON.stringify(validatedData, null, 2), 'utf8');
+    }
+}
+/*
+Manual smoke test:
+
+import { z } from 'zod';
+
+const manager = new StateManager();
+const DemoSchema = z.object({ count: z.number().int() });
+
+await manager.writeState('demo.json', { count: 1 }, DemoSchema);
+const loaded = await manager.readState('demo.json', DemoSchema);
+console.log(loaded.count); // 1
+*/

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { analyzeApp } from './analyze.js';
+export type { AnalyzeOptions, AnalyzeResult } from './analyze.js';
+export type { HarnessConfig, AuthConfig, RouteInventory, GapAnalysis, RepoAnalysis, } from './schemas/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClE,YAAY,EACV,aAAa,EACb,UAAU,EACV,cAAc,EACd,WAAW,EACX,YAAY,GACb,MAAM,oBAAoB,CAAC"}