ai-saas-guard 0.34.0 → 0.35.1

package/README.md

@@ -31,7 +31,19 @@
 
 AI-built SaaS can look ready before it is ready: login works, checkout opens, the dashboard loads, and tests are green. The launch risk is usually hidden in trust-boundary code that decides who gets access, who pays, what data they can see, and whether failures are visible.
 
-Start with the 30-second copy-paste demo: `npx ai-saas-guard@latest demo --summary`. No signup, no code upload, no LLM call. See the [terminal screenshot](docs/demo-terminal-screenshot.svg), [saved output](docs/demo-terminal-output.txt), [compare with alternatives](docs/launch-gate-positioning.md), and the [30-second cold-start review](docs/cold-start-review.md).
+Start with the 30-second copy-paste demo: `npx ai-saas-guard@latest demo --summary`. No signup, no code upload, no LLM call. See the saved output and [compare with alternatives](docs/launch-gate-positioning.md). Then run the same launch gate against your repo in about three minutes:
+
+```bash
+npx ai-saas-guard@latest scan --root /path/to/your-saas --summary
+```
+
+The output is meant to answer three practical questions before you invite users:
+
+- **Can a real user get access they should not have?** Check auth, tenant ownership, Supabase RLS, and Stripe entitlement paths first.
+- **Can the app claim success when something failed?** Check swallowed errors, fake success responses, hardcoded fallback data, and skipped tests.
+- **Can launch infrastructure do too much damage?** Check exposed env vars, overpowered workflows, MCP tools, deploy gaps, and missing request evidence.
+
+See the [terminal screenshot](docs/demo-terminal-screenshot.svg), [saved output](docs/demo-terminal-output.txt), and the [30-second cold-start review](docs/cold-start-review.md).
 
 These are the failures that hurt after real users arrive:
 
@@ -46,6 +58,18 @@ These are the failures that hurt after real users arrive:
 
 `ai-saas-guard` gives you a short local review queue for those risks. It does not prove the app is secure, certify a release, or replace human review. It tells founders, solo builders, small teams, and reviewers what deserves attention first.
 
+## What To Do With The Result
+
+Treat the report as a launch review queue, not a scorecard. Fix or manually prove the highest trust-boundary findings before spending time on low-severity hygiene.
+
+| If you see | Do this first |
+| --- | --- |
+| Critical/high auth, billing, RLS, tenant, webhook, or silent-success findings | Reproduce the manual proof step in staging and confirm the path fails closed |
+| Medium deploy, env, request ID, MCP, or Actions hygiene findings | Decide whether the launch path needs the control now or can be tracked after critical paths are closed |
+| Low/info hints | Clean them up after the user-access, payment, and data-access paths are understood |
+
+For a realistic risky app, scan [examples/case-study-ai-saas](examples/case-study-ai-saas) or read [docs/case-study-ai-saas.md](docs/case-study-ai-saas.md).
+
 ## 30-Second Copy-Paste Demo
 
 No signup, no code upload, no LLM call:
@@ -138,6 +162,14 @@ One command returns a launch-readiness report with:
 
 For a concise comparison with Semgrep, zizmor, OpenSSF Scorecard, Snyk, and GitHub code scanning, see [docs/launch-gate-positioning.md](docs/launch-gate-positioning.md).
 
+## Three Ways To Use It
+
+| Path | Best for | Status |
+| --- | --- | --- |
+| Local CLI | Private code, first local launch review, founder or reviewer workflow | Published on npm; local-first, read-only, no code upload, no LLM calls |
+| GitHub Action | CI review queue, SARIF upload, PR summary artifacts, controlled fail thresholds | Available through `zr9959/ai-saas-guard@v0` and fixed version tags |
+| Hosted GitHub App | Future hosted Check Run experience for selected repositories | Limited trial gate only; not the complete hosted SaaS, not a public hosted scanner |
+
 ## Quick Start
 
 Run the published CLI without installing it globally:
@@ -199,18 +231,19 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | Area | Status |
 | --- | --- |
 | Public GitHub repository | Available |
-| npm CLI | `ai-saas-guard@0.34.0` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.34.0` |
+| npm CLI | `ai-saas-guard@0.35.1` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.35.1` |
 | Outputs | Short summary, terminal, JSON, SARIF, and PR-focused markdown |
 | Project config | `.ai-saas-guard.json` rule toggles, severity overrides, suppressions, and fail thresholds |
 | Privacy model | Local-first, read-only scan commands, no LLM calls, no code upload |
-| Versioned Action tags | `v0.34.0`, `v0` |
-| Current release | `0.34.0` adds a visual demo screenshot, tightens first-run demo output, adds a concise competitor-positioning line, and improves hosted Check Run reviewer checklist wording |
+| Versioned Action tags | `v0.35.1`, `v0` |
+| Current release | `0.35.1` updates the case-study fixture to a patched Next.js release so GitHub Dependabot no longer reports known Next.js advisories for the packaged example |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 | Repository trust hardening | Strict branch protection, Dependabot, CodeQL, fast-check fuzzing, signed release provenance assets, private vulnerability reporting, secret scanning, and push protection |
 | Cloudflare hosted ingress | Deployed at `https://ai-saas-guard-hosted.zr9959.workers.dev`; signed GitHub App webhook delivery and compact Check Run smoke now pass in staging |
 | Hosted GitHub App staging | Private App `ai-saas-guard-hosted` (`3834787`) installed on `zr9959/ai-saas-guard`; hosted operations evidence is in [docs/hosted-operations-evidence.md](docs/hosted-operations-evidence.md) |
 | OpenSSF Best Practices | Passing badge, project `12955`; `.bestpractices.json` remains the conservative evidence record |
+| Next roadmap | v0.36.0 plan is tracked in [docs/v0.36-roadmap.md](docs/v0.36-roadmap.md) |
 
 ## Example Finding
 
@@ -318,6 +351,8 @@ The hosted production adapter layer is documented in [docs/hosted-production-ada
 
 The hosted read-only checkout worker is exported from `ai-saas-guard/hosted/worker`. It creates a temporary checkout from trusted GitHub App identity, uses a runtime installation token only through git askpass, removes askpass material before the CLI phase, rejects mutated command/checkout/token-scope plans, runs the fixed `ai-saas-guard pr-risk --json` command with bounded timeout/output, converts CLI JSON into compact findings, and deletes the checkout after success or failure. It does not return source, diffs, secrets, checkout paths, PR-authored commands, or installation tokens.
 
+The read-only checkout scan gate is exported as `evaluateHostedReadOnlyCheckoutScanGate` from `ai-saas-guard/hosted/worker`. It records whether the real worker path observed trusted git stages, CLI scan, compact report storage, Check Run publication, checkout cleanup, token removal before CLI, and bounded timeout/output settings before a hosted trial can proceed.
+
 The hosted Node/container app skeleton is documented in [docs/hosted-node-container-app.md](docs/hosted-node-container-app.md). It exports `createHostedHttpApp`, `createInMemoryHostedAppPlatform`, `createHostedNodeCheckoutAppPlatform`, and `planHostedNodeContainerDeployment` from `ai-saas-guard/hosted/app`. It adds a safe `/healthz` route, signed `/github/webhook` ingress, one-job worker tick, in-memory provider adapters for tests, a concrete read-only checkout worker composition with visible timeout/output safety budgets, and deployment-plan validation for secret manager, queue, compact report store, worker sandbox, and GitHub Checks publisher references. It still does not deploy or expose a public hosted service by itself.
 
 The hosted staging deployment planner is documented in [docs/hosted-staging-deployment.md](docs/hosted-staging-deployment.md). It exports `planHostedProviderBinding`, `planHostedStagingDeployment`, and `planHostedGitHubAppPromotion` from `ai-saas-guard/hosted/staging`. It composes real provider references, the Node/container deployment plan, hosted operational release-gate evidence, and GitHub App deployment planning so staging and production promotion stay blocked until the required queue, store, worker sandbox, Check Run publisher, logs, metrics, rollback, and incident-response references are present. It still does not call a cloud provider, create a GitHub App, or expose a public hosted service by itself.
@@ -336,8 +371,14 @@ Hosted pricing and packaging boundaries are documented in [docs/hosted-pricing-p
 
 Hosted pre-implementation pure contracts are documented in [docs/hosted-preimplementation-contracts.md](docs/hosted-preimplementation-contracts.md). They now include a pull request webhook intake planner that verifies signatures before parsing or queueing, a durable scan queue planner that reuses queued, running, and completed jobs for the same trusted scan key, a worker read-only scan planner that fixes the CLI command and requires repository `contents: read`, a concrete Node read-only checkout scan runner, and a Check Run publication planner that requires repository `checks: write` and builds bounded check-only payloads from compact reports. They also cover queue-safe webhook event parsing, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, a retention/deletion cleanup planner, an operational release gate evaluator, the production adapter plans needed for GitHub App auth and bounded worker execution, the Node/container app skeleton needed for real provider wiring, the staging deployment planner needed before production GitHub App promotion, the local staging harness needed to rehearse webhook replay, persistence, publication, and cleanup without cloud calls, and the deployed worker staging evidence helper needed to evaluate public HTTPS health, deployed cleanup, and log-boundary evidence without storing raw hosted data. The service runtime composes these contracts behind replaceable adapters. PR comments remain a later workflow or paid hosted feature, not part of the hosted MVP contract.
 
+The limited hosted GitHub App trial gate is exported as `createHostedGitHubAppTrialGate` from `ai-saas-guard/hosted/contracts`. It keeps trial use scoped to selected repositories and requires Check Run publication, compact report storage, worker cleanup, and safe log-boundary evidence before treating a small trial as ready. It does not claim the complete hosted SaaS is available.
+
 A public hosted compact report schema fixture is available at [examples/hosted-compact-report.json](examples/hosted-compact-report.json). It is synthetic and public-safe: compact evidence only, no raw source, raw diffs, secrets, webhook payload bodies, customer payloads, private URLs, or worker checkout paths.
 
+The case-study fixture in [examples/case-study-ai-saas](examples/case-study-ai-saas) and [docs/case-study-ai-saas.md](docs/case-study-ai-saas.md) shows a more realistic AI-built SaaS shape across auth-adjacent routes, billing, Stripe, Supabase, Next/Vercel, and GitHub Actions.
+
+For large repositories, `createLocalScanResourceBudget` exposes the conservative local scan budget: bounded text files, per-file bytes, total bytes, ignored build/dependency directories, no code upload, and no LLM calls.
+
 The proposed hosted app permission boundary is intentionally narrow: repository contents read, pull requests read, checks write, and metadata read for the first version. Optional PR comments require repository policy opt-in, and broad permissions such as administration, deployments, Actions write, and repository secrets are out of scope.
 
 The repository also includes hosted contract helpers and runtime tests for webhook intake order, webhook verification, installation token scoping, durable queue idempotency, compact reports, retention limits, uninstall cleanup, repeated cleanup idempotency, scoped deletion planning, operational release gate blocking, provider-independent hosted service orchestration, and GitHub App deployment planning. These helpers do not deploy a public hosted service.
@@ -374,7 +415,7 @@ Use `suppressions` for narrower false-positive handling when one rule is noisy o
 
 ## GitHub Action
 
-The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.34.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
+The repo includes a composite Action. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag such as `v0.35.1` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard

package/dist/hosted/contracts.d.ts

@@ -453,6 +453,54 @@ export interface HostedCheckRunPublicationPlan {
         modelTraining: "disabled";
     };
 }
+export type HostedGitHubAppTrialGateBlockedReason = "trial_repository_limit_exceeded" | "trial_repository_not_selected" | "check_run_publication_missing" | "compact_report_missing" | "worker_cleanup_missing" | "safe_log_boundary_rejected";
+export interface HostedGitHubAppTrialGateInput {
+    requestedAt: string;
+    appName: string;
+    installationId: number;
+    selectedRepositoryIds: number[];
+    trialRepositoryIds: number[];
+    completedCheckRuns: Array<{
+        repositoryId: number;
+        pullRequestNumber: number;
+        headSha: string;
+        conclusion: HostedCheckRunConclusion;
+        compactReportStored: boolean;
+        checkRunPublished: boolean;
+        workerCleanupVerified: boolean;
+    }>;
+    safeLogBoundary: {
+        accepted: boolean;
+        sampleCount: number;
+        blockedReasons: string[];
+    };
+    maxTrialRepositories?: number;
+    rawSource?: string;
+    rawDiff?: string;
+    secretValues?: string[];
+    customerPayload?: unknown;
+}
+export interface HostedGitHubAppTrialGate {
+    readyForTrial: boolean;
+    blockedReasons: HostedGitHubAppTrialGateBlockedReason[];
+    requestedAt: string;
+    scope: {
+        appName: string;
+        installationId: number;
+        trialRepositoryIds: number[];
+        maxTrialRepositories: number;
+    };
+    checkRunsReady: boolean;
+    safeLogBoundaryReady: boolean;
+    requiredNextProof: string[];
+    privacy: {
+        includesRawSource: false;
+        includesRawDiffs: false;
+        includesSecrets: false;
+        includesCustomerPayloads: false;
+        claimsCompleteHostedSaas: false;
+    };
+}
 export type HostedDeletionTrigger = "repository_removed" | "installation_deleted" | "repeated_cleanup";
 export interface HostedDeletionPlanInput {
     trigger: HostedDeletionTrigger;
@@ -690,6 +738,7 @@ export declare function resolveHostedRetentionDays(input?: {
 export declare function createCompactHostedReport(input: CompactHostedReportInput): CompactHostedReport;
 export declare function createHostedCheckRunSummary(input: HostedCheckRunSummaryInput): HostedCheckRunSummary;
 export declare function planHostedCheckRunPublication(input: HostedCheckRunPublicationInput): HostedCheckRunPublicationPlan;
+export declare function createHostedGitHubAppTrialGate(input: HostedGitHubAppTrialGateInput): HostedGitHubAppTrialGate;
 export declare function getHostedDeletionIdempotencyKey(input: {
     trigger: HostedDeletionTrigger;
     installationId: number;

package/dist/hosted/contracts.js

@@ -559,6 +559,59 @@ export function planHostedCheckRunPublication(input) {
         privacy: hostedCheckRunPublicationPrivacy()
     };
 }
+export function createHostedGitHubAppTrialGate(input) {
+    const maxTrialRepositories = input.maxTrialRepositories ?? 3;
+    const selectedRepositoryIds = new Set(input.selectedRepositoryIds);
+    const blockedReasons = [];
+    const trialRepositoryLimitExceeded = input.trialRepositoryIds.length > maxTrialRepositories;
+    const trialRepositoryNotSelected = input.trialRepositoryIds.some((repositoryId) => !selectedRepositoryIds.has(repositoryId));
+    const matchingRuns = input.completedCheckRuns.filter((run) => input.trialRepositoryIds.includes(run.repositoryId));
+    const checkRunPublicationMissing = matchingRuns.length === 0 || matchingRuns.some((run) => !run.checkRunPublished);
+    const compactReportMissing = matchingRuns.length === 0 || matchingRuns.some((run) => !run.compactReportStored);
+    const workerCleanupMissing = matchingRuns.length === 0 || matchingRuns.some((run) => !run.workerCleanupVerified);
+    const safeLogBoundaryRejected = !input.safeLogBoundary.accepted || input.safeLogBoundary.sampleCount <= 0;
+    if (trialRepositoryLimitExceeded)
+        blockedReasons.push("trial_repository_limit_exceeded");
+    if (trialRepositoryNotSelected)
+        blockedReasons.push("trial_repository_not_selected");
+    if (checkRunPublicationMissing)
+        blockedReasons.push("check_run_publication_missing");
+    if (compactReportMissing)
+        blockedReasons.push("compact_report_missing");
+    if (workerCleanupMissing)
+        blockedReasons.push("worker_cleanup_missing");
+    if (safeLogBoundaryRejected)
+        blockedReasons.push("safe_log_boundary_rejected");
+    return {
+        readyForTrial: blockedReasons.length === 0,
+        blockedReasons,
+        requestedAt: input.requestedAt,
+        scope: {
+            appName: input.appName,
+            installationId: input.installationId,
+            trialRepositoryIds: [...input.trialRepositoryIds].sort((a, b) => a - b),
+            maxTrialRepositories
+        },
+        checkRunsReady: matchingRuns.length > 0 &&
+            !checkRunPublicationMissing &&
+            !compactReportMissing &&
+            !workerCleanupMissing,
+        safeLogBoundaryReady: !safeLogBoundaryRejected,
+        requiredNextProof: [
+            "Install only on selected trial repositories.",
+            "Publish one bounded Check Run from compact report data only.",
+            "Verify worker checkout cleanup after success and failure.",
+            "Sample logs and confirm raw source, raw diffs, secrets, customer payloads, and tokens are absent."
+        ],
+        privacy: {
+            includesRawSource: false,
+            includesRawDiffs: false,
+            includesSecrets: false,
+            includesCustomerPayloads: false,
+            claimsCompleteHostedSaas: false
+        }
+    };
+}
 export function getHostedDeletionIdempotencyKey(input) {
     return [input.trigger, input.installationId, input.repositoryId ?? "all"].join(":");
 }

package/dist/hosted/worker.d.ts

@@ -1,5 +1,6 @@
 import type { HostedServiceScanRunner, HostedServiceScanRunnerInput, HostedServiceScanRunnerResult } from "./service.js";
 export type HostedReadOnlyCheckoutCommandStage = "git_init" | "git_remote_add" | "git_fetch_head" | "git_fetch_base" | "git_checkout" | "cli_scan";
+export type HostedReadOnlyCheckoutScanGateBlockedReason = `missing_command_stage_${HostedReadOnlyCheckoutCommandStage}` | "compact_report_missing" | "check_run_missing" | "checkout_cleanup_missing" | "token_boundary_missing" | "output_budget_exceeded" | "timeout_budget_exceeded";
 export interface HostedReadOnlyCheckoutCommand {
     stage: HostedReadOnlyCheckoutCommandStage;
     command: string;
@@ -26,6 +27,39 @@ export interface HostedReadOnlyCheckoutScanRunnerOptions {
     installationTokenProvider: HostedInstallationTokenProvider;
     commandRunner?: HostedReadOnlyCheckoutCommandRunner;
 }
+export interface HostedReadOnlyCheckoutScanGateInput {
+    requestedAt: string;
+    jobKey: string;
+    commandStages: HostedReadOnlyCheckoutCommandStage[];
+    summaryCounts: Record<string, number>;
+    compactFindingCount: number;
+    compactReportStored: boolean;
+    checkRunPublished: boolean;
+    checkoutDeleted: boolean;
+    tokenRemovedBeforeCli: boolean;
+    maxOutputBytes: number;
+    timeoutMs: number;
+    rawSource?: string;
+    rawDiff?: string;
+    checkoutPath?: string;
+    installationToken?: string;
+}
+export interface HostedReadOnlyCheckoutScanGate {
+    readyForHostedTrial: boolean;
+    blockedReasons: HostedReadOnlyCheckoutScanGateBlockedReason[];
+    requestedAt: string;
+    jobKey: string;
+    summaryCounts: Record<string, number>;
+    compactFindingCount: number;
+    commandStagesObserved: HostedReadOnlyCheckoutCommandStage[];
+    privacy: {
+        includesRawSource: false;
+        includesRawDiffs: false;
+        includesPrivateCheckoutPath: false;
+        includesInstallationToken: false;
+        claimsCompleteHostedSaas: false;
+    };
+}
 export type HostedReadOnlyCheckoutScanSafeReason = "invalid_worker_plan" | "invalid_repository_full_name" | "invalid_clone_base_url" | "missing_installation_token" | "git_init_failed" | "git_remote_add_failed" | "git_fetch_head_failed" | "git_fetch_base_failed" | "git_checkout_failed" | "cli_scan_failed" | "invalid_cli_output" | "cleanup_failed";
 export declare class HostedReadOnlyCheckoutScanError extends Error {
     readonly safeReason: HostedReadOnlyCheckoutScanSafeReason;
@@ -40,4 +74,5 @@ export declare class HostedReadOnlyCheckoutScanError extends Error {
     constructor(safeReason: HostedReadOnlyCheckoutScanSafeReason);
 }
 export declare function createHostedReadOnlyCheckoutScanRunner(options: HostedReadOnlyCheckoutScanRunnerOptions): HostedServiceScanRunner;
+export declare function evaluateHostedReadOnlyCheckoutScanGate(input: HostedReadOnlyCheckoutScanGateInput): HostedReadOnlyCheckoutScanGate;
 export declare function runHostedReadOnlyCheckoutScan(input: HostedServiceScanRunnerInput, options: HostedReadOnlyCheckoutScanRunnerOptions): Promise<HostedServiceScanRunnerResult>;

package/dist/hosted/worker.js

@@ -28,6 +28,52 @@ export class HostedReadOnlyCheckoutScanError extends Error {
 export function createHostedReadOnlyCheckoutScanRunner(options) {
     return (input) => runHostedReadOnlyCheckoutScan(input, options);
 }
+export function evaluateHostedReadOnlyCheckoutScanGate(input) {
+    const requiredStages = [
+        "git_init",
+        "git_remote_add",
+        "git_fetch_head",
+        "git_fetch_base",
+        "git_checkout",
+        "cli_scan"
+    ];
+    const observedStages = new Set(input.commandStages);
+    const blockedReasons = [];
+    for (const stage of requiredStages) {
+        if (!observedStages.has(stage))
+            blockedReasons.push(`missing_command_stage_${stage}`);
+    }
+    if (!input.compactReportStored)
+        blockedReasons.push("compact_report_missing");
+    if (!input.checkRunPublished)
+        blockedReasons.push("check_run_missing");
+    if (!input.checkoutDeleted)
+        blockedReasons.push("checkout_cleanup_missing");
+    if (!input.tokenRemovedBeforeCli)
+        blockedReasons.push("token_boundary_missing");
+    if (input.maxOutputBytes > HOSTED_WORKER_MAX_OUTPUT_BYTES) {
+        blockedReasons.push("output_budget_exceeded");
+    }
+    if (input.timeoutMs > HOSTED_WORKER_MAX_TIMEOUT_MS) {
+        blockedReasons.push("timeout_budget_exceeded");
+    }
+    return {
+        readyForHostedTrial: blockedReasons.length === 0,
+        blockedReasons,
+        requestedAt: input.requestedAt,
+        jobKey: input.jobKey,
+        summaryCounts: { ...input.summaryCounts },
+        compactFindingCount: input.compactFindingCount,
+        commandStagesObserved: input.commandStages.filter((stage, index, stages) => stages.indexOf(stage) === index),
+        privacy: {
+            includesRawSource: false,
+            includesRawDiffs: false,
+            includesPrivateCheckoutPath: false,
+            includesInstallationToken: false,
+            claimsCompleteHostedSaas: false
+        }
+    };
+}
 export async function runHostedReadOnlyCheckoutScan(input, options) {
     const { plan } = input;
     const { checkout, cli } = plan;

package/dist/index.d.ts

@@ -9,7 +9,9 @@ export { applyGuardConfig, defaultConfigFileName, loadGuardConfig } from "./conf
 export { createScanContext } from "./context.js";
 export { getRuleMetadata, RULE_CATALOG } from "./rules/catalog.js";
 export { formatSummaryReport } from "./report/summary.js";
+export { createLocalScanResourceBudget } from "./performance.js";
 export type { BaseReport, CommandName, Evidence, Finding, ActionsReport, McpOptions, McpPolicyTemplate, McpReport, McpServerInventory, McpSideEffect, PrRiskFile, PrRiskReport, ScanOptions, ShowcaseReport, StripeReport, SupabaseOptions, SupabaseDoctorReport, SupabaseReport } from "./types.js";
 export type { ScanContext, ScanInput } from "./context.js";
 export type { FindingSuppression, GuardConfig, RuleConfigValue } from "./config.js";
 export type { RuleMetadata, RuleStability } from "./rules/catalog.js";
+export type { LocalScanResourceBudget, LocalScanResourceBudgetInput } from "./performance.js";

package/dist/index.js

@@ -9,3 +9,4 @@ export { applyGuardConfig, defaultConfigFileName, loadGuardConfig } from "./conf
 export { createScanContext } from "./context.js";
 export { getRuleMetadata, RULE_CATALOG } from "./rules/catalog.js";
 export { formatSummaryReport } from "./report/summary.js";
+export { createLocalScanResourceBudget } from "./performance.js";

package/dist/performance.d.ts

@@ -0,0 +1,21 @@
+export interface LocalScanResourceBudgetInput {
+    repositoryKind?: string;
+    maxFiles?: number;
+    maxTotalBytes?: number;
+    maxFileBytes?: number;
+}
+export interface LocalScanResourceBudget {
+    repositoryKind: string;
+    localFirst: true;
+    deterministic: true;
+    uploadsCode: false;
+    callsLlm: false;
+    limits: {
+        maxFiles: number;
+        maxTotalBytes: number;
+        maxFileBytes: number;
+    };
+    ignoredDirectories: string[];
+    operatorNote: string;
+}
+export declare function createLocalScanResourceBudget(input?: LocalScanResourceBudgetInput): LocalScanResourceBudget;

package/dist/performance.js

@@ -0,0 +1,23 @@
+import { DEFAULT_MAX_TEXT_FILE_BYTES, DEFAULT_MAX_TEXT_FILES, DEFAULT_MAX_TOTAL_TEXT_BYTES } from "./utils/files.js";
+export function createLocalScanResourceBudget(input = {}) {
+    return {
+        repositoryKind: input.repositoryKind ?? "ai-built-saas",
+        localFirst: true,
+        deterministic: true,
+        uploadsCode: false,
+        callsLlm: false,
+        limits: {
+            maxFiles: positiveIntegerOrDefault(input.maxFiles, DEFAULT_MAX_TEXT_FILES),
+            maxTotalBytes: positiveIntegerOrDefault(input.maxTotalBytes, DEFAULT_MAX_TOTAL_TEXT_BYTES),
+            maxFileBytes: positiveIntegerOrDefault(input.maxFileBytes, DEFAULT_MAX_TEXT_FILE_BYTES)
+        },
+        ignoredDirectories: [".git", ".next", ".turbo", "coverage", "dist", "build", "node_modules", "out"],
+        operatorNote: "This keeps local scans bounded for large AI SaaS repositories without uploading code or calling an LLM."
+    };
+}
+function positiveIntegerOrDefault(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const normalized = Math.floor(value);
+    return Number.isFinite(normalized) && normalized > 0 ? normalized : fallback;
+}

package/docs/README.zh-CN.md

@@ -41,8 +41,32 @@ AI 构建的 SaaS 很容易“看起来已经能上线”：能登录、能打
 - Next/Vercel 生产环境缺 env 文档、security headers、request ID 或成本风险提示
 - AI 生成的大 PR 把 auth、billing、data、deploy 或测试改动藏在“普通改动”里
 
+先用 30 秒 demo 看输出：`npx ai-saas-guard@latest demo --summary`。不用注册、不上传代码、不调用 LLM。然后用大约 3 分钟扫自己的仓库：
+
+```bash
+npx ai-saas-guard@latest scan --root /path/to/your-saas --summary
+```
+
+输出会先回答三个上线前最实际的问题：
+
+- **真实用户会不会拿到不该有的权限？** 先看 auth、tenant ownership、Supabase RLS 和 Stripe entitlement。
+- **服务失败时会不会假装成功？** 先看 swallowed error、fake success、hardcoded fallback data 和跳过的测试。
+- **上线基础设施是不是权限太大？** 再看 env 暴露、过宽 workflow、MCP tool、deploy gap 和 request evidence。
+
 `ai-saas-guard` 是面向这个时刻的本地优先、review-first 上线预检工具。它不会证明你的应用绝对安全，也不是渗透测试、认证或完整安全审计。它的目标是给 founder、独立开发者、小团队和 reviewer 一份短而有证据的清单，告诉你上线或合并 PR 前最该先看哪里。
 
+## 看到结果后该怎么处理
+
+把报告当成上线 review 队列，而不是分数。先处理或人工验证最高风险的信任边界 finding，再处理低级别 hygiene。
+
+| 如果看到 | 先做什么 |
+| --- | --- |
+| Critical/high 的 auth、billing、RLS、tenant、webhook 或 silent-success finding | 在 staging 复现 manual proof，确认风险路径会 fail closed |
+| Medium 的 deploy、env、request ID、MCP 或 Actions hygiene finding | 判断这个上线路径现在是否必须补控制，还是可以在 critical 路径关闭后跟进 |
+| Low/info 提示 | 等 user access、payment、data access 路径都清楚后再清理 |
+
+想看一个更像真实项目的风险样例，可以扫描 [examples/case-study-ai-saas](../examples/case-study-ai-saas) 或阅读 [case-study-ai-saas.md](case-study-ai-saas.md)。
+
 ## 30 秒复制粘贴 demo
 
 不需要注册、不上传代码、不调用 LLM：
@@ -135,6 +159,14 @@ Next steps
 
 如果想看它和 Semgrep、zizmor、OpenSSF Scorecard、Snyk、GitHub code scanning 的边界区别，见 [launch-gate-positioning.md](launch-gate-positioning.md)。
 
+## 三种使用路径
+
+| 路径 | 适合什么场景 | 当前状态 |
+| --- | --- | --- |
+| 本地 CLI | 私有代码、本机首次上线 review、founder 或 reviewer 自查 | 已发布到 npm；本地优先、只读、不上传代码、不调用 LLM |
+| GitHub Action | CI 里的 review queue、SARIF、PR summary artifact、可控 fail threshold | 可通过 `zr9959/ai-saas-guard@v0` 或固定版本标签使用 |
+| Hosted GitHub App | 未来面向 selected repositories 的 hosted Check Run 体验 | 目前只是 limited trial gate，不是完整 hosted SaaS，也不是公开 hosted scanner |
+
 ## 快速开始
 
 无需全局安装，直接运行：
@@ -179,23 +211,24 @@ node dist/cli.js scan --root /path/to/your-saas
 
 这个仓库是公开 GitHub 仓库。
 
-CLI 已发布到 npm：`ai-saas-guard@0.34.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.34.0`。
+CLI 已发布到 npm：`ai-saas-guard@0.35.1`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.35.1`。
 
 | 模块 | 状态 |
 | --- | --- |
 | 公开 GitHub 仓库 | 已可用 |
-| npm CLI | `ai-saas-guard@0.34.0` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.34.0` |
+| npm CLI | `ai-saas-guard@0.35.1` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.35.1` |
 | 输出格式 | 短 summary、Terminal、JSON、SARIF 和 PR markdown |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖、suppressions 和 fail threshold |
 | 隐私模型 | 本地优先、只读扫描、不调用 LLM、不上传代码 |
-| 当前版本 | `0.34.0` 增加可视化 demo 截图、优化首次 demo 输出、补充更精简的竞品定位说明，并强化 hosted Check Run reviewer checklist |
-| Action 标签 | `v0.34.0`、`v0` |
+| 当前版本 | `0.35.1` 将 case-study fixture 升级到已修补的 Next.js 版本，避免 GitHub Dependabot 对包内示例继续报告已知 Next.js advisories |
+| Action 标签 | `v0.35.1`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 | 仓库可信度加固 | 严格 branch protection、Dependabot、CodeQL、fast-check fuzzing、signed release provenance assets、private vulnerability reporting、secret scanning 和 push protection |
 | Cloudflare hosted ingress | 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`；签名 GitHub App webhook delivery 和 compact Check Run staging smoke 已通过 |
 | Hosted GitHub App staging | 私有 App `ai-saas-guard-hosted`（`3834787`）已安装到 `zr9959/ai-saas-guard`；hosted operations evidence 见 [docs/hosted-operations-evidence.md](hosted-operations-evidence.md) |
 | OpenSSF Best Practices | 已获得 passing badge，项目 `12955`；`.bestpractices.json` 继续作为保守证据记录 |
+| 下一版路线 | v0.36.0 计划见 [v0.36-roadmap.md](v0.36-roadmap.md) |
 
 ## 主要命令
 
@@ -375,10 +408,14 @@ GitHub Marketplace wrapper 决策见 [docs/github-marketplace-wrapper-decision.m
 - GitHub App deployment planner：`ai-saas-guard/hosted/github-app` 导出 `planHostedGitHubAppDeployment`，生成 first slice 最小权限 manifest，并在 release gate、公开 HTTPS URL、container digest、secret 引用、原始 secret 输入、permission 或 event 不安全时阻止创建
 - Hosted production adapter layer：`ai-saas-guard/hosted/production-adapters` 导出 `createHostedGitHubAppJwt`、`planHostedGitHubInstallationTokenRequest` 和 `planHostedProductionWorkerExecution`，用于 GitHub App RS256 JWT、selected-repository installation token 请求规划、worker/check-run 分离 token scope、固定只读 worker 命令、timeout/output 预算、compact JSON-only 输出，以及 success/failure/timeout/cancellation 的 cleanup 规划；它本身仍然不部署公开 hosted 服务
 - Hosted Node/container app skeleton：`ai-saas-guard/hosted/app` 导出 `createHostedHttpApp`、`createInMemoryHostedAppPlatform`、`createHostedNodeCheckoutAppPlatform` 和 `planHostedNodeContainerDeployment`，提供安全 `/healthz`、签名 `/github/webhook` ingress、单 job worker tick、测试用 in-memory provider adapters、真实 read-only checkout worker 组合入口、可见 timeout/output 安全预算，以及 secret manager、queue、compact report store、worker sandbox、GitHub Checks publisher 的部署引用校验；它本身仍然不部署或暴露公开 hosted 服务
+- Read-only checkout scan gate：`ai-saas-guard/hosted/worker` 导出 `evaluateHostedReadOnlyCheckoutScanGate`，要求真实 worker 路径证明 trusted git stages、CLI scan、compact report storage、Check Run publication、checkout cleanup、CLI 前 token removal 以及 timeout/output budgets 都满足后，才能进入 hosted trial
 - Hosted staging deployment planner：`ai-saas-guard/hosted/staging` 导出 `planHostedProviderBinding`、`planHostedStagingDeployment` 和 `planHostedGitHubAppPromotion`，把真实 provider 引用、Node/container deployment plan、hosted operational release-gate evidence 和 GitHub App deployment planning 组合起来；缺少 queue、store、worker sandbox、Check Run publisher、logs、metrics、rollback 或 incident-response 引用时，会阻止 staging exposure 和 production promotion；它本身仍然不会调用云平台、创建 GitHub App 或暴露公开 hosted 服务
 - Hosted staging harness：`ai-saas-guard/hosted/staging-harness` 导出 `createFileBackedHostedStagingHarness`、`createHostedStagingHarnessEvidence`、`createHostedStagingReleaseEvidenceBundle`、`evaluateHostedStagingReleaseEvidenceBundle` 和 `validateHostedLogBoundary`，可以在本地用 file-backed queue、compact report、Check Run request 和 worker sandbox 跑通签名 webhook replay、worker tick 和 cleanup 校验，把 success/failure cleanup probes 与 log-boundary samples 转成 release-gate evidence，并直接执行 hosted release gate 判断；它只是 staging 演练工具，不会调用云平台、创建 GitHub App、写真实 Check Run 或暴露公开 hosted 服务
 - Deployed worker staging evidence：`ai-saas-guard/hosted/deployed-staging` 导出 `createHostedDeployedWorkerStagingEvidenceAutomation`、`createHostedDeployedWorkerStagingEvidenceBundle` 和 `evaluateHostedDeployedWorkerStagingReleaseGate`，先验证 safe log samples，再把 public HTTPS health、signed webhook replay、deployed worker cleanup 以及外部 CI/scan/rollback evidence 转成 hosted release gate evidence；它不会部署云资源，也不会宣称 production hosted exposure
 - Cloudflare hosted ingress：`hosted/cloudflare-worker` 已部署到 `https://ai-saas-guard-hosted.zr9959.workers.dev`，提供 `/healthz`、`/github/app/manifest-callback` 和签名 `/github/webhook` intake；Worker 已具备 compact pull request identity、file/category risk signal 和 Check Run metadata 路径；staging GitHub App ID 为 `3834787`，installation ID 为 `135085075`；真实 GitHub App webhook delivery 和 Check Run smoke 已通过；完整 source checkout worker deployment、monitoring、rollback 和 incident-response evidence 仍需要通过 hosted operational release gate
+- Hosted GitHub App limited trial gate：`ai-saas-guard/hosted/contracts` 导出 `createHostedGitHubAppTrialGate`，确保 trial 只作用于 selected repositories，并要求 Check Run publication、compact report、worker cleanup 和 safe log-boundary evidence；它不宣称完整 hosted SaaS 已可用
+- Case-study fixture：`examples/case-study-ai-saas` 和 [case-study-ai-saas.md](case-study-ai-saas.md) 展示一个更接近真实 AI SaaS 的 auth、billing、Supabase、Next/Vercel 和 GitHub Actions 风险组合
+- Resource budget：`createLocalScanResourceBudget` 暴露大仓库本地扫描的保守预算：文件数、单文件字节、总字节、忽略 build/dependency 目录、不上传代码、不调用 LLM
 - webhook event parser
 - check-run summary renderer
 - Check Run publication planner：要求 repository `checks: write`，只从 compact report 生成有长度上限的 Check Run payload，包含 review categories、优先 review 文件、verification steps 和本地 CLI 复现命令；MVP 不发 PR comment

package/docs/case-study-ai-saas.md

@@ -0,0 +1,21 @@
+# AI SaaS Case Study Fixture
+
+`examples/case-study-ai-saas` is a synthetic case study for a realistic AI-built SaaS shape: auth-adjacent API routes, billing checkout, Stripe webhook, Supabase RLS, Next/Vercel config, and GitHub Actions.
+
+The fixture is intentionally not safe to launch. It helps readers see why a local-first launch gate is useful even when an app appears to have the expected product surfaces.
+
+Expected findings include:
+
+- missing Stripe webhook signature verification
+- silent-success billing fallback
+- broad Supabase RLS policy
+- missing Next/Vercel security headers
+- broad GitHub Actions permissions
+
+Use it locally:
+
+```bash
+npx ai-saas-guard@latest scan --root examples/case-study-ai-saas --summary
+```
+
+This fixture is public-safe and synthetic. It is not a SaaS starter template, pentest target, certification artifact, or full audit.

package/docs/hosted-preimplementation-contracts.md

@@ -91,6 +91,19 @@ Privacy boundaries:
 
 - do not return temporary checkout paths, raw source, raw diffs, evidence snippets, secrets, customer payloads, PR-authored commands, PR-authored repository names, or installation tokens
 - do not persist source checkout contents beyond the worker run
+
+The read-only checkout scan gate turns a real worker observation into a small release/trial decision. The exported helper is `evaluateHostedReadOnlyCheckoutScanGate`.
+
+It requires:
+
+- trusted git setup, fetch, checkout, and CLI scan stages
+- compact report storage
+- bounded Check Run publication
+- checkout cleanup
+- installation token removal before the CLI phase
+- timeout and output budgets within the hosted worker limits
+
+It returns only compact counts, observed stages, blocked reasons, and privacy flags. It does not return raw source, raw diffs, checkout paths, or installation tokens.
 - rely on the deployment sandbox for network egress restrictions around the CLI phase; the runner itself removes GitHub credentials before invoking the CLI
 
 The exported helper is `createHostedReadOnlyCheckoutScanRunner`.
@@ -266,6 +279,21 @@ Privacy boundaries:
 
 The exported helper is `planHostedCheckRunPublication`. It is intended to be the GitHub-API-independent contract for the first real Check Run writer. PR comments remain an explicit later workflow or paid hosted feature, not part of this MVP contract.
 
+## Hosted GitHub App Limited Trial Gate
+
+The limited trial gate decides whether the hosted GitHub App can be tried on a small selected-repository set. The exported helper is `createHostedGitHubAppTrialGate`.
+
+It requires:
+
+- trial repositories are a subset of selected GitHub App repositories
+- the trial repository count stays under the configured cap
+- compact Check Runs were published
+- compact reports were stored
+- worker cleanup was verified
+- safe log-boundary samples were accepted
+
+It does not install a GitHub App, call GitHub, run workers, or claim the complete hosted SaaS is ready. It is a deterministic gate for small controlled trials.
+
 ## Queue Cleanup Planner
 
 The queue cleanup planner turns repository removal, installation deletion, and repeated cleanup events into a safe cancellation plan for hosted scan jobs. It is a pure planner only: it does not connect to a queue provider, mutate jobs, delete worker files, call GitHub, or retry work.

package/docs/npm-publishing.md

@@ -5,11 +5,11 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current published version: `0.34.0`
+- Current published version: `0.35.1`
 - Next source candidate: none
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.34.0`
+- GitHub Release: `v0.35.1`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions, `zr9959/ai-saas-guard`, workflow `npm-publish.yml`, allowed action `npm publish`
 - Long-lived npm publish token: not required
@@ -18,7 +18,7 @@
 
 Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.34.0`.
+1. Create and review a release tag such as `v0.35.1`.
 2. Publish from the GitHub Release or run the `Publish npm` workflow manually with `ref` set to that tag.
 3. Keep `permissions.id-token: write` in the workflow so npm can exchange the GitHub Actions OIDC identity for a short-lived publish credential.
 4. Run `npm publish --access public` from the workflow. Trusted publishing automatically generates provenance for this public package from this public repository.

package/docs/v0.36-roadmap.md

@@ -0,0 +1,38 @@
+# v0.36.0 Roadmap
+
+This is the next practical release plan after v0.35.0. It keeps the product focused on a local-first launch gate for AI-built SaaS apps.
+
+## Goals
+
+- Make the first real scan easier to understand for a founder or reviewer.
+- Improve report usefulness without turning the tool into a general pentest, certification, or CI analytics platform.
+- Keep the CLI deterministic, local-first, read-only, and free of LLM calls.
+
+## Planned Work
+
+1. **Markdown report polish**
+   - Tighten the top summary, manual proof steps, and fix-direction wording.
+   - Make CI artifacts easier to read without opening JSON or SARIF.
+
+2. **PR comment readiness**
+   - Prepare a compact PR summary format suitable for GitHub Action artifacts and future Check Runs.
+   - Keep it deterministic and file-evidence based.
+
+3. **Risk sorting clarity**
+   - Explain why auth, billing, tenant data, webhook, RLS, and silent-success findings are ranked above cosmetic changes.
+   - Keep the ranking simple and inspectable.
+
+4. **Fixture coverage**
+   - Expand the case-study fixture only where it demonstrates real launch-risk patterns.
+   - Keep positive and negative examples small enough to review quickly.
+
+5. **Resource guardrails**
+   - Continue measuring large-repo scan limits, ignored directories, output size, and cleanup behavior.
+   - Avoid background services or persistent local processes for normal CLI use.
+
+## Non-Goals
+
+- No code upload.
+- No LLM review.
+- No hosted scanner claims until the hosted GitHub App path is fully gated and documented.
+- No pentest, full audit, or certification positioning.

package/examples/case-study-ai-saas/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: npm test

package/examples/case-study-ai-saas/README.md

@@ -0,0 +1,13 @@
+# Case Study AI SaaS Fixture
+
+This synthetic fixture looks like a small AI-built SaaS with auth, billing, Supabase, Vercel/Next.js deploy config, and GitHub Actions.
+
+It is intentionally risky:
+
+- billing checkout swallows provider failure and returns fake success
+- Stripe webhook does not verify signatures
+- Supabase RLS policy is broad
+- Next.js config lacks production security headers
+- GitHub Actions grants broad permissions
+
+It is not a complete SaaS template and does not contain real secrets.

package/examples/case-study-ai-saas/app/api/billing/checkout/route.ts

@@ -0,0 +1,11 @@
+export async function POST() {
+  try {
+    return Response.json({ checkoutUrl: await createCheckoutSession() });
+  } catch {
+    return Response.json({ success: true, checkoutUrl: "/billing/demo-success" });
+  }
+}
+
+async function createCheckoutSession() {
+  throw new Error("provider unavailable");
+}

package/examples/case-study-ai-saas/app/api/projects/[projectId]/route.ts

@@ -0,0 +1,8 @@
+export async function GET(_request: Request, context: { params: { projectId: string } }) {
+  return Response.json({
+    project: {
+      id: context.params.projectId,
+      tenantId: "demo-tenant"
+    }
+  });
+}

package/examples/case-study-ai-saas/app/api/stripe/webhook/route.ts

@@ -0,0 +1,13 @@
+export async function POST(request: Request) {
+  const event = await request.json();
+
+  if (event.type === "checkout.session.completed") {
+    await grantEntitlement(event.data.object.customer);
+  }
+
+  return Response.json({ received: true });
+}
+
+async function grantEntitlement(customerId: string) {
+  console.log("grant", customerId);
+}

package/examples/case-study-ai-saas/next.config.js

@@ -0,0 +1,10 @@
+module.exports = {
+  images: {
+    remotePatterns: [
+      {
+        protocol: "https",
+        hostname: "**"
+      }
+    ]
+  }
+};

package/examples/case-study-ai-saas/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "case-study-ai-saas",
+  "private": true,
+  "scripts": {
+    "build": "next build",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "next": "15.5.18",
+    "stripe": "17.0.0"
+  }
+}

package/examples/case-study-ai-saas/supabase/migrations/001_projects.sql

@@ -0,0 +1,12 @@
+create table public.projects (
+  id uuid primary key,
+  tenant_id uuid not null,
+  name text not null
+);
+
+alter table public.projects enable row level security;
+
+create policy "ai generated broad select"
+on public.projects
+for select
+using (true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.34.0",
+  "version": "0.35.1",
   "description": "Local-first CLI that catches launch blockers in AI-built Next.js/Supabase/Stripe SaaS apps.",
   "readmeFilename": "README.md",
   "type": "module",