evershield 0.1.0 → 0.3.0

package/README.md

@@ -7,10 +7,9 @@
 **Shield everything, everywhere.** Find what your web app exposes to the
 browser before attackers do.
 
-> Status: pre-release. Layer 1 (built-artifact scan) and layer 2
-> (privilege-differential response audit) work today. Layer 3 is next;
-> follow the [roadmap](docs/design.md#roadmap) or open an issue to help
-> shape it.
+> Status: pre-release. All three layers work: built-artifact scan,
+> privilege-differential response audit, and rendered-surface audit. Follow
+> the [roadmap](docs/design.md#roadmap) or open an issue to help shape it.
 
 ## Why
 
@@ -43,6 +42,12 @@ npx evershield scan ./dist --format json --fail-on medium --min-confidence low
 
 # SARIF for code scanning, written to a file
 npx evershield scan ./dist --format sarif --output evershield.sarif
+
+# mobile and desktop app packages: everything inside ships to the device
+npx evershield scan app-release.apk   # Android (.apk, .aab), incl. Hermes bytecode and DEX strings
+npx evershield scan MyApp.ipa         # iOS: main.jsbundle and the app executable's strings
+npx evershield scan app.asar          # Electron
+npx evershield scan ./dist            # an Expo / React Native export (*.hbc, *.bundle)
 ```
 
 Exit code `0` means nothing blocking, `1` means findings at or above the
@@ -58,6 +63,37 @@ confidence, is in [docs/rules.md](docs/rules.md):
 - `artifact/sensitive-env-name`: `SERVICE_ROLE`, `*_SECRET`, `DATABASE_URL`, …
 - `artifact/internal-endpoint`: private IPs, `.internal` hosts, dev fallbacks
 
+## Leave reverse engineers empty-handed
+
+Tools like [REA](https://github.com/morluto/rea) cannot be blocked: they run
+in the attacker's own browser, on their own copy of your app. What you
+control is what they get. `recon` shows it from their side and fails the
+build while anything is worth taking:
+
+```bash
+npx evershield recon ./dist               # or an .apk, .ipa, .asar
+npx evershield recon ./dist --rea         # also run REA itself and check each finding against its output
+```
+
+```
+Worth taking: 2 blocking, 3 total
+✖ [critical/high] Stripe secret key shipped in assets/index.js  · REA: recovered
+✖ [high/high] Source map shipped: assets/index.js.map  · REA: not checked
+• [medium/medium] Private IP address in assets/index.js: 10.0.3.7  · REA: recovered
+
+Map (informational: any tool reconstructs this from shipped code; keep server-side checks on it)
+  hosts: api.example.com (12)
+  API paths: /api/report, /api/user
+  source maps: 1 file(s), 2 original source(s), 2 with full content
+
+Verdict: 2 item(s) worth taking. Anyone running a reverse-engineering tool on this target gets them.
+```
+
+The map is what no build can hide (routes, hosts, field names); recon lists
+it so you know which endpoints need server-side authorization. With `--rea`,
+values are compared in memory and never printed. Pair it with `audit` and
+`surface` for what each plan receives at runtime.
+
 ## Audit what each plan actually receives
 
 Layer 2 calls your own API as each identity you configure and compares the
@@ -96,9 +132,50 @@ names mark them as a higher tier's (`premium_*`, `pro_only`, `internal_*`),
 credential-like fields in any response, and endpoints that answer every
 identity identically. The audit only ever talks to `baseUrl`.
 
+## Find paywalls that only hide
+
+Layer 3 opens your pages in a headless browser as each identity and reports
+content that is in the page but hidden: blurred, `display: none`, clipped,
+or tucked into a `data-*` attribute, an inline script or `localStorage`.
+
+```json
+{
+  "surface": {
+    "baseUrl": "https://staging.example.com",
+    "tiers": ["free", "pro"],
+    "identities": {
+      "free": { "storageState": "${EVERSHIELD_FREE_STATE}" },
+      "pro":  { "storageState": "${EVERSHIELD_PRO_STATE}" }
+    },
+    "pages": [{ "path": "/report/demo" }]
+  }
+}
+```
+
+```bash
+npm install --save-dev playwright && npx playwright install chromium
+EVERSHIELD_FREE_STATE=free.json EVERSHIELD_PRO_STATE=pro.json npx evershield surface
+```
+
+The key rule compares tiers: text the Pro page shows that the Free page
+also contains, hidden, is a cosmetic paywall. Tabs and menus hidden for
+everyone never trigger it. See [the surface rules](docs/rules.md#layer-3-surface)
+and [configuration](docs/configuration.md#surface-layer-3).
+
 ## In CI
 
-The GitHub Action scans your build and uploads the result to the Security
+Fastest path: run this in your project root.
+
+```bash
+npx evershield init
+```
+
+It detects the framework (Next.js, Vite, Astro, SvelteKit, Nuxt, CRA), the
+build directory and package manager, and writes `evershield.config.json`
+and `.github/workflows/evershield.yml`. Existing files are left alone
+unless you pass `--force`.
+
+Or write the workflow yourself. The GitHub Action scans your build and uploads the result to the Security
 tab as code-scanning alerts:
 
 ```yaml
@@ -123,6 +200,18 @@ Inputs: `path` (required), `fail-on`, `min-confidence`, `config`, `adapter`,
 `sarif-file`, `upload-sarif`, `version`. The step fails when evershield
 exits 1 (blocking findings) or 2 (error), after the SARIF upload.
 
+## In Claude Code
+
+```
+/plugin marketplace add inviy/evershield
+/plugin install evershield@evershield
+```
+
+The plugin adds an `evershield` skill (Claude checks the server-side
+boundary whenever it touches response fields, plan branches, public env
+vars or `public/`) and an `/evershield` command that builds and scans the
+project.
+
 ## Allowlisting with a reason
 
 Known-safe matches go in `evershield.config.json`, each with a reason:
@@ -143,6 +232,30 @@ evershield refuses a config whose ignores have no `reason`, and reports how
 many findings the config removed. Details in
 [docs/configuration.md](docs/configuration.md).
 
+## Measured on real code
+
+Every rule change runs against a [false-positive corpus](docs/corpus.md): 42
+pinned npm packages that ship to browsers (React, Vue, Firebase, Supabase,
+Auth0, Sentry, Stripe.js, PostHog, three.js, pdf.js and more) plus 10 default
+apps from Next.js, Vite, SvelteKit, Astro and Expo (Hermes bytecode)
+generators, built as deployed. **False positives at the default gate: 0**
+across 8,886 files and 175 MiB.
+The one blocking finding is a true positive (a development build with an
+inline source map). The first run found 8 false positives, all in
+auth0-spa-js; fixing them is how the rules got here.
+
+## Tested against REA
+
+[experiments/rea](experiments/rea/README.md) points
+[REA](https://github.com/morluto/rea) at a deliberately leaky app and at the
+same app fixed with evershield. REA recovered all five leaks from the leaky
+build (a secret key, an internal address, source via source maps, blurred
+Pro data in the DOM, Pro fields in a free response); evershield flagged all
+five; after the fix REA recovered none and evershield reported nothing.
+evershield does not hide your app from REA. It makes sure there is nothing
+in it worth taking, and `evershield recon --rea` checks that against REA
+itself on every build.
+
 ## Principles
 
 - **Defensive only.** It audits targets you own, listed in your config.

package/dist/cli.js

@@ -3,6 +3,10 @@ import path from "node:path";
 import { parseArgs } from "node:util";
 import { runAudit } from "./audit/run.js";
 import { applyIgnores, ConfigError, loadConfig } from "./config.js";
+import { runInit } from "./init.js";
+import { runRecon } from "./recon.js";
+import { renderReconJson, renderReconSarif, renderReconText } from "./report/recon.js";
+import { runSurface } from "./surface/run.js";
 import { VERSION } from "./index.js";
 import { CONFIDENCES, DEFAULT_GATE, isBlocking, renderJson, renderText, SEVERITIES } from "./report/index.js";
 import { renderSarif } from "./report/sarif.js";
@@ -12,13 +16,25 @@ const HELP = `evershield ${VERSION}
 Shield everything, everywhere.
 
 Usage:
-  evershield scan <dir> [options]   Layer 1: scan a built web artifact directory
+  evershield init [--force]         Detect your framework and write evershield.config.json
+                                    and a GitHub workflow that scans every pull request
+  evershield scan <dir|app> [options]
+                                    Layer 1: scan a built web directory, or an app package
+                                    (.apk, .aab, .ipa, Electron .asar)
+  evershield recon <dir|app> [--rea] [--rea-bin <path>]
+                                    The attacker's view: what reverse-engineering tools such
+                                    as REA recover from a build or app package. Fails when
+                                    anything is worth taking; --rea checks each finding
+                                    against REA's own output
   evershield audit [options]        Layer 2: call configured endpoints as each identity
                                     and compare what they receive (needs config "audit")
+  evershield surface [options]      Layer 3: open configured pages as each identity in a
+                                    headless browser and find content that is present but
+                                    hidden (needs config "surface" and Playwright)
   evershield --version              Print version
   evershield --help                 Show this help
 
-Options (both commands):
+Options (scan, audit, surface):
   --format <text|json|sarif>        Output format (default: text)
   --output <file>                   Write the report to a file; stdout gets a one-line summary
   --config <file>                   Config file (default: ./evershield.config.json if present)
@@ -116,7 +132,34 @@ export async function run(argv) {
     if (command === "--version" || command === "-v" || command === "version") {
         return { code: 0, stdout: `${VERSION}\n`, stderr: "" };
     }
-    if (command !== "scan" && command !== "audit") {
+    if (command === "init") {
+        const unknown = rest.filter((arg) => arg !== "--force");
+        if (unknown.length > 0)
+            return usageError(`init: unexpected argument "${unknown[0]}"`);
+        try {
+            const { detection, written, skipped } = await runInit(process.cwd(), { force: rest.includes("--force") });
+            const lines = [
+                `evershield init · detected ${detection.framework} · build output ${detection.buildDir} · ${detection.packageManager}`,
+                ...written.map((file) => `  created  ${file}`),
+                ...skipped.map((file) => `  skipped  ${file} (exists; use --force to overwrite)`),
+                "",
+                "Next:",
+                `  1. Build, then try it locally:  npx evershield scan ${detection.buildDir}`,
+                "  2. Commit the workflow; every pull request is scanned and findings appear in the Security tab.",
+                "  3. Known-safe matches go in evershield.config.json under \"ignore\", each with a reason.",
+            ];
+            if (detection.framework === "unknown") {
+                lines.push("", `Could not detect a framework; edit the build step and path in .github/workflows/evershield.yml.`);
+            }
+            return { code: 0, stdout: `${lines.join("\n")}\n`, stderr: "" };
+        }
+        catch (error) {
+            return failure("init", error);
+        }
+    }
+    if (command === "recon")
+        return reconCommand(rest);
+    if (command !== "scan" && command !== "audit" && command !== "surface") {
         return usageError(`unknown command "${command}"`);
     }
     const options = parseCommonOptions(rest);
@@ -138,7 +181,27 @@ export async function run(argv) {
         }
     }
     if (options.positionals.length > 0)
-        return usageError(`audit: unexpected argument "${options.positionals[0]}"`);
+        return usageError(`${command}: unexpected argument "${options.positionals[0]}"`);
+    if (command === "surface") {
+        try {
+            const { config, source } = await loadConfig(options.configPath);
+            if (config.surface === undefined) {
+                throw new ConfigError(source === null
+                    ? "surface needs a config file with a \"surface\" block (see docs/configuration.md)"
+                    : `${source} has no "surface" block (see docs/configuration.md)`);
+            }
+            const gate = gateFor(options, config);
+            const surfaced = await runSurface(config.surface);
+            if (surfaced.snapshotsEvaluated === 0) {
+                throw new Error(`no page could be evaluated, so nothing was audited:\n  ${surfaced.warnings.join("\n  ")}`);
+            }
+            const { kept, ignored } = applyIgnores(surfaced.findings, config.ignore);
+            return await finish({ ...surfaced, findings: kept, ignored: ignored.length }, gate, options);
+        }
+        catch (error) {
+            return failure("surface", error);
+        }
+    }
     try {
         const { config, source } = await loadConfig(options.configPath);
         if (config.audit === undefined) {
@@ -159,3 +222,49 @@ export async function run(argv) {
         return failure("audit", error);
     }
 }
+async function reconCommand(rest) {
+    const args = [...rest];
+    let reaBin;
+    const reaAt = args.indexOf("--rea");
+    if (reaAt >= 0) {
+        args.splice(reaAt, 1);
+        reaBin = "rea";
+    }
+    const binAt = args.indexOf("--rea-bin");
+    if (binAt >= 0) {
+        const value = args[binAt + 1];
+        if (value === undefined || value.startsWith("--"))
+            return usageError("recon: --rea-bin needs a path");
+        args.splice(binAt, 2);
+        reaBin = value;
+    }
+    const options = parseCommonOptions(args);
+    if ("code" in options)
+        return options;
+    const target = options.positionals[0];
+    if (target === undefined)
+        return usageError("recon: missing <dir|app>");
+    try {
+        const { config } = await loadConfig(options.configPath);
+        const gate = gateFor(options, config);
+        const result = await runRecon(target, {
+            ...(options.adapter === undefined ? {} : { adapter: options.adapter }),
+            ...(reaBin === undefined ? {} : { reaBin }),
+        });
+        const { kept, ignored } = applyIgnores(result.findings, config.ignore);
+        const keptSet = new Set(kept);
+        const filtered = { ...result, findings: kept, items: result.items.filter((item) => keptSet.has(item.finding)), ignored: ignored.length };
+        const blocking = kept.filter((finding) => isBlocking(finding, gate)).length;
+        // A requested REA check that could not run is not a pass.
+        const code = result.rea.status === "failed" ? 2 : blocking > 0 ? 1 : 0;
+        const rendered = options.format === "json" ? renderReconJson(filtered, gate) : options.format === "sarif" ? renderReconSarif(filtered, gate) : renderReconText(filtered, gate);
+        const stderr = result.rea.status === "failed" ? `evershield recon: ${result.rea.detail ?? "REA failed"}\n` : "";
+        if (options.outputPath === undefined)
+            return { code, stdout: rendered, stderr };
+        await writeFile(path.resolve(options.outputPath), rendered);
+        return { code, stdout: `evershield recon: ${filtered.items.length} item(s), ${blocking} blocking · ${options.format} report written to ${options.outputPath}\n`, stderr };
+    }
+    catch (error) {
+        return failure("recon", error);
+    }
+}

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import type { AuditConfig } from "./audit/types.ts";
 import type { Finding } from "./index.ts";
+import type { SurfaceConfig } from "./surface/types.ts";
 import { type Gate } from "./report/index.ts";
 export interface IgnoreRule {
     /** Rule id to ignore, or "*" for any rule. */
@@ -16,6 +17,8 @@ export interface Config {
     ignore: IgnoreRule[];
     /** Layer 2 settings; `evershield audit` requires this block. */
     audit?: AuditConfig;
+    /** Layer 3 settings; `evershield surface` requires this block. */
+    surface?: SurfaceConfig;
 }
 export declare const DEFAULT_CONFIG_FILE = "evershield.config.json";
 export declare class ConfigError extends Error {

package/dist/config.js

@@ -72,6 +72,8 @@ export function parseConfig(raw, source) {
     }
     if (raw.audit !== undefined)
         config.audit = parseAuditConfig(raw.audit, `${source}: audit`);
+    if (raw.surface !== undefined)
+        config.surface = parseSurfaceConfig(raw.surface, `${source}: surface`);
     return config;
 }
 const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
@@ -90,9 +92,7 @@ function parseHeaders(raw, where) {
     }
     return headers;
 }
-function parseAuditConfig(raw, where) {
-    if (!isRecord(raw))
-        throw new ConfigError(`${where} must be an object`);
+function parseBaseUrl(raw, where) {
     if (typeof raw.baseUrl !== "string")
         throw new ConfigError(`${where}.baseUrl is required`);
     let base;
@@ -104,6 +104,30 @@ function parseAuditConfig(raw, where) {
     }
     if (base.protocol !== "http:" && base.protocol !== "https:")
         throw new ConfigError(`${where}.baseUrl must be http or https`);
+    return base;
+}
+function parseTiers(raw, where, identities) {
+    if (!Array.isArray(raw.tiers) || raw.tiers.length === 0 || !raw.tiers.every((tier) => typeof tier === "string")) {
+        throw new ConfigError(`${where}.tiers must list identity names from least to most privileged`);
+    }
+    const tiers = raw.tiers;
+    for (const tier of tiers) {
+        if (identities[tier] === undefined)
+            throw new ConfigError(`${where}.tiers names "${tier}" which is not in identities`);
+    }
+    return tiers;
+}
+function parseTimeout(raw, where) {
+    if (raw.timeoutMs === undefined)
+        return undefined;
+    if (typeof raw.timeoutMs !== "number" || raw.timeoutMs <= 0)
+        throw new ConfigError(`${where}.timeoutMs must be a positive number`);
+    return raw.timeoutMs;
+}
+function parseAuditConfig(raw, where) {
+    if (!isRecord(raw))
+        throw new ConfigError(`${where} must be an object`);
+    const base = parseBaseUrl(raw, where);
     if (!isRecord(raw.identities) || Object.keys(raw.identities).length === 0) {
         throw new ConfigError(`${where}.identities must define at least one identity`);
     }
@@ -116,14 +140,7 @@ function parseAuditConfig(raw, where) {
             identity.headers = parseHeaders(value.headers, `${where}.identities.${name}.headers`);
         identities[name] = identity;
     }
-    if (!Array.isArray(raw.tiers) || raw.tiers.length === 0 || !raw.tiers.every((tier) => typeof tier === "string")) {
-        throw new ConfigError(`${where}.tiers must list identity names from least to most privileged`);
-    }
-    const tiers = raw.tiers;
-    for (const tier of tiers) {
-        if (identities[tier] === undefined)
-            throw new ConfigError(`${where}.tiers names "${tier}" which is not in identities`);
-    }
+    const tiers = parseTiers(raw, where, identities);
     if (!Array.isArray(raw.endpoints) || raw.endpoints.length === 0)
         throw new ConfigError(`${where}.endpoints must list at least one endpoint`);
     const endpoints = raw.endpoints.map((entry, index) => {
@@ -164,13 +181,98 @@ function parseAuditConfig(raw, where) {
         return endpoint;
     });
     const audit = { baseUrl: base.origin, tiers, identities, endpoints };
-    if (raw.timeoutMs !== undefined) {
-        if (typeof raw.timeoutMs !== "number" || raw.timeoutMs <= 0)
-            throw new ConfigError(`${where}.timeoutMs must be a positive number`);
-        audit.timeoutMs = raw.timeoutMs;
-    }
+    const timeoutMs = parseTimeout(raw, where);
+    if (timeoutMs !== undefined)
+        audit.timeoutMs = timeoutMs;
     return audit;
 }
+const ENV_REF_PRESENT = /\$\{[A-Z_][A-Z0-9_]*\}/;
+function parseStringList(value, where) {
+    if (!(Array.isArray(value) && value.every((item) => typeof item === "string" && item.length > 0))) {
+        throw new ConfigError(`${where} must be an array of non-empty strings`);
+    }
+    return value;
+}
+function parseSurfaceConfig(raw, where) {
+    if (!isRecord(raw))
+        throw new ConfigError(`${where} must be an object`);
+    const base = parseBaseUrl(raw, where);
+    if (!isRecord(raw.identities) || Object.keys(raw.identities).length === 0) {
+        throw new ConfigError(`${where}.identities must define at least one identity`);
+    }
+    const identities = {};
+    for (const [name, value] of Object.entries(raw.identities)) {
+        const at = `${where}.identities.${name}`;
+        if (!isRecord(value))
+            throw new ConfigError(`${at} must be an object`);
+        const identity = {};
+        if (value.headers !== undefined)
+            identity.headers = parseHeaders(value.headers, `${at}.headers`);
+        if (value.cookies !== undefined) {
+            if (!isRecord(value.cookies))
+                throw new ConfigError(`${at}.cookies must be an object of cookie name → value`);
+            identity.cookies = {};
+            for (const [cookie, cookieValue] of Object.entries(value.cookies)) {
+                if (typeof cookieValue !== "string" || !ENV_REF_PRESENT.test(cookieValue)) {
+                    throw new ConfigError(`${at}.cookies.${cookie} must reference an environment variable such as "\${EVERSHIELD_PRO_SESSION}"; literal credentials are not allowed in config`);
+                }
+                identity.cookies[cookie] = cookieValue;
+            }
+        }
+        if (value.storageState !== undefined) {
+            if (typeof value.storageState !== "string" || value.storageState.length === 0)
+                throw new ConfigError(`${at}.storageState must be a file path`);
+            identity.storageState = value.storageState;
+        }
+        identities[name] = identity;
+    }
+    const tiers = parseTiers(raw, where, identities);
+    if (!Array.isArray(raw.pages) || raw.pages.length === 0)
+        throw new ConfigError(`${where}.pages must list at least one page`);
+    const pages = raw.pages.map((entry, index) => {
+        const at = `${where}.pages[${index}]`;
+        if (!isRecord(entry))
+            throw new ConfigError(`${at} must be an object`);
+        if (typeof entry.path !== "string" || !entry.path.startsWith("/"))
+            throw new ConfigError(`${at}.path must start with "/" (relative to baseUrl)`);
+        const page = { path: entry.path };
+        if (entry.waitFor !== undefined) {
+            if (typeof entry.waitFor !== "string" || entry.waitFor.length === 0)
+                throw new ConfigError(`${at}.waitFor must be a CSS selector`);
+            page.waitFor = entry.waitFor;
+        }
+        if (entry.expect !== undefined) {
+            if (!isRecord(entry.expect))
+                throw new ConfigError(`${at}.expect must be an object keyed by identity`);
+            page.expect = {};
+            for (const [identity, expectation] of Object.entries(entry.expect)) {
+                if (identities[identity] === undefined)
+                    throw new ConfigError(`${at}.expect.${identity} is not a defined identity`);
+                if (!isRecord(expectation))
+                    throw new ConfigError(`${at}.expect.${identity} must be an object`);
+                const parsed = {};
+                if (expectation.absentText !== undefined)
+                    parsed.absentText = parseStringList(expectation.absentText, `${at}.expect.${identity}.absentText`);
+                if (expectation.absentSelectors !== undefined) {
+                    parsed.absentSelectors = parseStringList(expectation.absentSelectors, `${at}.expect.${identity}.absentSelectors`);
+                }
+                page.expect[identity] = parsed;
+            }
+        }
+        return page;
+    });
+    const surface = { baseUrl: base.origin, tiers, identities, pages };
+    const timeoutMs = parseTimeout(raw, where);
+    if (timeoutMs !== undefined)
+        surface.timeoutMs = timeoutMs;
+    if (raw.minTextLength !== undefined) {
+        if (typeof raw.minTextLength !== "number" || !Number.isInteger(raw.minTextLength) || raw.minTextLength < 4) {
+            throw new ConfigError(`${where}.minTextLength must be an integer of at least 4`);
+        }
+        surface.minTextLength = raw.minTextLength;
+    }
+    return surface;
+}
 /**
  * Load the config file. An explicit path must exist; the default file is
  * optional. Returns the source path alongside, for messages.
@@ -226,8 +328,9 @@ function matches(rule, finding) {
     const first = finding.evidence[0];
     if (rule.path !== undefined) {
         // For file evidence the glob matches the file path; for response
-        // evidence it matches "METHOD /path" so one entry can cover an endpoint.
-        const subject = first?.kind === "file" ? first.path : first?.kind === "response" ? first.endpoint : undefined;
+        // evidence it matches "METHOD /path" so one entry can cover an endpoint;
+        // DOM evidence matches the page path.
+        const subject = first?.kind === "file" ? first.path : first?.kind === "response" ? first.endpoint : first?.kind === "dom" ? new URL(first.url).pathname : undefined;
         if (subject === undefined || !globToRegExp(rule.path).test(subject))
             return false;
     }

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * every layer reports in, so CLI, GitHub Action and MCP surfaces can share
  * one finding model from day one. See docs/design.md for the rationale.
  */
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.3.0";
 /** How sure evershield is that a finding is real. Drives exit codes and CI gating. */
 export type Confidence = "high" | "medium" | "low";
 /** How bad it is if the finding is real. */
@@ -29,6 +29,7 @@ export type Evidence = {
     kind: "dom";
     url: string;
     selector: string;
+    identity?: string;
     excerpt?: string;
 };
 export interface Finding {

package/dist/index.js

@@ -5,4 +5,4 @@
  * every layer reports in, so CLI, GitHub Action and MCP surfaces can share
  * one finding model from day one. See docs/design.md for the rationale.
  */
-export const VERSION = "0.1.0";
+export const VERSION = "0.3.0";

package/dist/init.d.ts

@@ -0,0 +1,21 @@
+export interface Detection {
+    framework: "nextjs" | "vite" | "astro" | "create-react-app" | "nuxt" | "sveltekit" | "unknown";
+    /** Build output directory relative to the project root. */
+    buildDir: string;
+    packageManager: "pnpm" | "yarn" | "bun" | "npm";
+    /** Shell command that produces the build directory. */
+    buildCommand: string;
+    /** package.json pins a version in "packageManager"; pnpm/action-setup fails without it unless told one. */
+    packageManagerPinned?: boolean;
+}
+export declare function detectProject(root: string): Promise<Detection>;
+export declare function renderWorkflow(detection: Detection): string;
+export declare function renderConfig(): string;
+export interface InitResult {
+    detection: Detection;
+    written: string[];
+    skipped: string[];
+}
+export declare function runInit(root: string, options?: {
+    force?: boolean;
+}): Promise<InitResult>;