ai-saas-guard 0.43.1 → 0.43.3

package/README.md

@@ -174,6 +174,19 @@ For a concise comparison with Semgrep, zizmor, OpenSSF Scorecard, Snyk, and GitH
 
 Choose the path by trust boundary: use the **Local CLI** when code must stay on your machine, the **GitHub Action** when you want repeatable CI evidence, and the **Hosted GitHub App** when reviewers need an automatic Check Run that groups auth, billing, tenant-data, deploy, and test-risk areas before merge.
 
+## Pre-Commercial Feedback
+
+`ai-saas-guard` is looking for privacy-safe design-partner feedback before any public hosted beta decision. The safest path is local:
+
+```bash
+npx --yes ai-saas-guard@latest demo --summary
+npx --yes ai-saas-guard@latest scan --root /path/to/your-low-risk-demo-repo --summary
+```
+
+Public-safe feedback belongs in [issue #93](https://github.com/zr9959/ai-saas-guard/issues/93): package version, path used, stack category, severity counts, rule IDs, what felt confusing/noisy/missing, and whether the report would change a launch or merge decision. Do not share source, raw diffs, PR text, logs, secrets, customer data, private URLs, checkout paths, or credentials.
+
+Downloads, stars, page views, anonymous comments, simulated scans, and internal assumptions do not count as design-partner evidence.
+
 ## Quick Start
 
 Run the published CLI without installing it globally:
@@ -235,20 +248,32 @@ 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.43.1` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.43.1` |
+| npm CLI | `ai-saas-guard@0.43.3` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.43.3` |
 | Outputs | Launch decision queue, 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.43.1`, `v0` |
-| Current release | `0.43.1` hardens hosted rate-limit failure handling, GitHub API URL validation, Check Run reproduction commands, MCP policy templates, and Action summary output while keeping billing disabled |
+| Versioned Action tags | `v0.43.3`, `v0` |
+| Current release | `0.43.3` reduces silent-success false positives for Cloudflare Durable Object stubs, benign null-return parsing/cache reads, configuration fallback parameters, and assertion-rich tests while keeping billing disabled |
 | 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`; public install/privacy notes are in [docs/hosted-install-privacy.md](docs/hosted-install-privacy.md); 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) |
+| Public beta readiness | Blocked on real design-partner feedback, deployed source-checkout proof, full GitHub App deletion proof, and provider monitoring evidence for the source-checkout path |
 | OpenSSF Best Practices | Passing badge, project `12955`; `.bestpractices.json` remains the conservative evidence record |
 | Previous roadmap | v0.36.0 plan is tracked in [docs/v0.36-roadmap.md](docs/v0.36-roadmap.md) |
 
+## Related TIYBAI Tools
+
+Built by [TIYBAI](https://www.tiybai.com/), `ai-saas-guard` stays focused on launch-risk review for AI-built SaaS apps. These adjacent TIYBAI pages are useful for developer workflows without turning this project into a broad cross-promotion surface:
+
+- [TIYBAI Toolbox](https://www.tiybai.com/en/tools) for browser-based utilities that do not require installing a separate desktop app.
+- [JSON Formatter](https://www.tiybai.com/en/tools/developer/json-formatter) for checking structured API responses and config snippets.
+- [JWT Decoder](https://www.tiybai.com/en/tools/developer/jwt-decoder) for inspecting token claims during auth review.
+- [URL Encoder / Decoder](https://www.tiybai.com/en/tools/developer/url-encoder) for checking callback URLs, webhook URLs, and encoded query strings.
+- [AI Metadata Generator](https://www.tiybai.com/en/tools/ai/metadata-generator) for preparing public page metadata before launch.
+- [PageStow](https://plugin.tiybai.com/) for saving browser context, sessions, notes, and tasks locally in Chrome.
+
 ## Example Finding
 
 Terminal output is designed to be useful to a reviewer, not just a scanner dashboard.
@@ -425,7 +450,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.43.1` 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.43.3` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard

package/dist/commands/scan.js

@@ -33,7 +33,7 @@ export async function scanRepository(options) {
         ...deployFindings,
         ...silentSuccessFindings,
         ...actionsReport.findings
-    ]), { stackInventory });
+    ]), { stackInventory, fileCollection: context.fileCollection });
 }
 function createSkippedSupabaseReport(rootDir) {
     return createReport("check-supabase", rootDir, [], {

package/dist/context.d.ts

@@ -1,8 +1,9 @@
-import { type TextFile } from "./utils/files.js";
+import { type FileCollectionDiagnostics, type TextFile } from "./utils/files.js";
 export interface ScanContext {
     rootDir: string;
     files: readonly TextFile[];
     filesByPath: ReadonlyMap<string, TextFile>;
+    fileCollection: FileCollectionDiagnostics;
     getFiles: (predicate?: (file: TextFile) => boolean) => TextFile[];
 }
 export type ScanInput = string | ScanContext;

package/dist/context.js

@@ -1,11 +1,13 @@
-import { collectTextFiles } from "./utils/files.js";
+import { collectTextFilesWithDiagnostics } from "./utils/files.js";
 export async function createScanContext(rootDir) {
-    const files = await collectTextFiles(rootDir);
+    const collection = await collectTextFilesWithDiagnostics(rootDir);
+    const { files } = collection;
     const filesByPath = new Map(files.map((file) => [file.path, file]));
     return {
         rootDir,
         files,
         filesByPath,
+        fileCollection: collection.diagnostics,
         getFiles(predicate) {
             return predicate ? files.filter(predicate) : [...files];
         }

package/dist/hosted/worker.d.ts

@@ -15,6 +15,7 @@ export interface HostedReadOnlyCheckoutCommandResult {
     stdout: string;
 }
 export type HostedReadOnlyCheckoutCommandRunner = (command: HostedReadOnlyCheckoutCommand) => Promise<HostedReadOnlyCheckoutCommandResult> | HostedReadOnlyCheckoutCommandResult;
+export type HostedCheckoutCleanup = (checkoutDir: string) => Promise<void> | void;
 export type HostedInstallationTokenProvider = (input: HostedServiceScanRunnerInput) => Promise<string> | string;
 export interface HostedReadOnlyCheckoutScanRunnerOptions {
     checkoutRoot?: string;
@@ -26,6 +27,7 @@ export interface HostedReadOnlyCheckoutScanRunnerOptions {
     maxOutputBytes?: number;
     installationTokenProvider: HostedInstallationTokenProvider;
     commandRunner?: HostedReadOnlyCheckoutCommandRunner;
+    cleanupCheckout?: HostedCheckoutCleanup;
 }
 export interface HostedSourceCheckoutTrialPlanInput {
     requestedAt: string;

package/dist/hosted/worker.js

@@ -258,13 +258,13 @@ export async function runHostedReadOnlyCheckoutScan(input, options) {
     const maxOutputBytes = clampPositiveInteger(options.maxOutputBytes, HOSTED_WORKER_MAX_OUTPUT_BYTES, HOSTED_WORKER_MAX_OUTPUT_BYTES);
     const fetchDepth = clampPositiveInteger(options.fetchDepth, DEFAULT_FETCH_DEPTH, MAX_FETCH_DEPTH);
     const checkoutRoot = options.checkoutRoot ?? join(tmpdir(), "ai-saas-guard-hosted-checkouts");
+    const cleanupCheckout = options.cleanupCheckout ?? defaultCleanupCheckout;
     const token = await options.installationTokenProvider(input);
     if (typeof token !== "string" || token.trim().length === 0) {
         throw new HostedReadOnlyCheckoutScanError("missing_installation_token");
     }
     await mkdir(checkoutRoot, { recursive: true, mode: 0o700 });
     const checkoutDir = await mkdtemp(join(checkoutRoot, "job-"));
-    let terminalError;
     try {
         await chmod(checkoutDir, 0o700);
         const askpassPath = join(checkoutDir, ".git-askpass.sh");
@@ -297,23 +297,23 @@ export async function runHostedReadOnlyCheckoutScan(input, options) {
         return compactScanRunnerResult(cliResult.stdout);
     }
     catch (error) {
-        terminalError =
-            error instanceof HostedReadOnlyCheckoutScanError
-                ? error
-                : new HostedReadOnlyCheckoutScanError("cli_scan_failed");
+        const terminalError = error instanceof HostedReadOnlyCheckoutScanError
+            ? error
+            : new HostedReadOnlyCheckoutScanError("cli_scan_failed");
         throw terminalError;
     }
     finally {
         try {
-            await rm(checkoutDir, { recursive: true, force: true });
+            await cleanupCheckout(checkoutDir);
         }
         catch {
-            if (!terminalError) {
-                throw new HostedReadOnlyCheckoutScanError("cleanup_failed");
-            }
+            throw new HostedReadOnlyCheckoutScanError("cleanup_failed");
         }
     }
 }
+async function defaultCleanupCheckout(checkoutDir) {
+    await rm(checkoutDir, { recursive: true, force: true });
+}
 function commandSpec(stage, command, args, cwd, env, timeoutMs, maxOutputBytes) {
     return {
         stage,

package/dist/index.d.ts

@@ -13,7 +13,8 @@ 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 { StackCategory, StackEvidence, StackInventory, StackInventoryInput } from "./stackInventory.js";
+export type { StackCategory, StackEvidence, StackInventory, StackInventoryInput, StackInventoryWarning } from "./stackInventory.js";
+export type { FileCollectionDiagnostics, TextFile, TextFileCollection } from "./utils/files.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/report/summary.js

@@ -8,6 +8,9 @@ export function formatSummaryReport(report) {
     lines.push(`Findings: ${summaryText(report)}`);
     lines.push(`Launch gate: ${launchGateVerdict(report)}`);
     lines.push(`Decision queue: ${launchDecisionQuestions(report.findings)[0]}`);
+    const scanCoverage = scanCoverageText(report);
+    if (scanCoverage)
+        lines.push(`Scan coverage: ${scanCoverage}`);
     if (report.findings.length > 0) {
         lines.push("Review trust-boundary findings before deploy/cost hygiene.");
     }
@@ -73,3 +76,43 @@ function summaryText(report) {
         return "0 findings";
     return `${report.summary.total} findings: ${report.summary.critical} critical, ${report.summary.high} high, ${report.summary.medium} medium, ${report.summary.low} low, ${report.summary.info} info`;
 }
+function scanCoverageText(report) {
+    const parts = [];
+    const collection = report.fileCollection;
+    if (collection) {
+        const unreadableFileCount = collection.unreadableFiles.length;
+        const unreadableDirectoryCount = collection.unreadableDirectories.length;
+        const skippedLargeCount = collection.skippedLargeFiles.length;
+        const skippedBudgetCount = collection.skippedBudgetFiles.length;
+        const hasCollectionWarning = unreadableFileCount > 0 ||
+            unreadableDirectoryCount > 0 ||
+            skippedLargeCount > 0 ||
+            skippedBudgetCount > 0 ||
+            collection.maxFilesReached ||
+            collection.maxTotalBytesReached;
+        if (hasCollectionWarning) {
+            parts.push(`${collection.filesScanned} ${plural(collection.filesScanned, "file")} scanned`);
+            if (unreadableFileCount > 0)
+                parts.push(`${unreadableFileCount} unreadable ${plural(unreadableFileCount, "file")}`);
+            if (unreadableDirectoryCount > 0) {
+                parts.push(`${unreadableDirectoryCount} unreadable ${plural(unreadableDirectoryCount, "directory", "directories")}`);
+            }
+            if (skippedLargeCount > 0)
+                parts.push(`${skippedLargeCount} large ${plural(skippedLargeCount, "file")} skipped`);
+            if (skippedBudgetCount > 0)
+                parts.push(`${skippedBudgetCount} budget-skipped ${plural(skippedBudgetCount, "file")}`);
+            if (collection.maxFilesReached)
+                parts.push("file count budget reached");
+            if (collection.maxTotalBytesReached)
+                parts.push("total byte budget reached");
+        }
+    }
+    const malformedPackageCount = report.stackInventory?.warnings.filter((warning) => warning.reason === "invalid_package_json").length ?? 0;
+    if (malformedPackageCount > 0) {
+        parts.push(`${malformedPackageCount} malformed package ${plural(malformedPackageCount, "manifest")}`);
+    }
+    return parts.length > 0 ? parts.join("; ") : undefined;
+}
+function plural(count, singular, pluralValue = `${singular}s`) {
+    return count === 1 ? singular : pluralValue;
+}

package/dist/scanners/gitDiff.js

@@ -84,14 +84,28 @@ export async function classifyPrRisk(options) {
 }
 async function readGitDiff(rootDir, base) {
     if (base) {
+        const tripleDotArgs = ["diff", `${base}...HEAD`];
         try {
-            const { stdout } = await execFileAsync("git", ["diff", `${base}...HEAD`], { cwd: rootDir, maxBuffer: 20 * 1024 * 1024 });
+            const { stdout } = await execFileAsync("git", tripleDotArgs, { cwd: rootDir, maxBuffer: 20 * 1024 * 1024 });
             return { diffText: stdout, diagnostics: [] };
         }
         catch (error) {
+            if (isMergeBaseUnavailableError(error)) {
+                const directDiffArgs = ["diff", `${base}..HEAD`];
+                try {
+                    const { stdout } = await execFileAsync("git", directDiffArgs, { cwd: rootDir, maxBuffer: 20 * 1024 * 1024 });
+                    return { diffText: stdout, diagnostics: [] };
+                }
+                catch (fallbackError) {
+                    return {
+                        diffText: "",
+                        diagnostics: [buildGitDiffFailureFinding(rootDir, ["git", ...directDiffArgs], fallbackError, base)]
+                    };
+                }
+            }
             return {
                 diffText: "",
-                diagnostics: [buildGitDiffFailureFinding(rootDir, ["git", "diff", `${base}...HEAD`], error, base)]
+                diagnostics: [buildGitDiffFailureFinding(rootDir, ["git", ...tripleDotArgs], error, base)]
             };
         }
     }
@@ -146,6 +160,10 @@ function buildGitDiffFailureFinding(rootDir, command, error, base) {
         suggestedFix
     });
 }
+function isMergeBaseUnavailableError(error) {
+    const lowerError = getGitErrorText(error).toLowerCase();
+    return lowerError.includes("no merge base") || lowerError.includes("shallow");
+}
 function buildFetchCommand(base) {
     const remoteRef = /^([^/\s]+)\/(.+)$/.exec(base);
     if (remoteRef)

package/dist/scanners/silentSuccess.js

@@ -10,6 +10,7 @@ const mockDataPattern = /\b(mock|fixture|fixtures|demo|sample|stub|fake)\b/i;
 const bypassPattern = /\b(TODO\s*:?\s*(auth|verify|validation|rate|owner|webhook)|temporary\s+bypass|temp\s+bypass|skip\s+(auth|verification|validation|ownership|webhook)|disable\s+(auth|verification|validation)|SKIP_(AUTH|WEBHOOK|VERIFICATION|VALIDATION)|ALLOW_UNVERIFIED)\b/i;
 const assertionPattern = /\b(expect\s*\(|assert\.|assert\s*\(|t\.is\s*\(|t\.true\s*\(|should\.|toEqual\s*\(|toBe\s*\(|toMatch\s*\()/i;
 const truthyOnlyPattern = /\b(expect\s*\([^)]*\)\.(toBeTruthy|toBeDefined|toBeOk)\s*\(\s*\)|assert\.ok\s*\([^)]*\)|t\.truthy\s*\([^)]*\))/i;
+const strongAssertionPattern = /\b(expect\s*\([^)]*\)\.(?:toEqual|toStrictEqual|toBe|toMatch|toHave|toContain|toThrow|rejects|resolves)\b|assert\.(?:equal|strictEqual|deepEqual|deepStrictEqual|notEqual|notStrictEqual|notDeepEqual|notDeepStrictEqual|match|doesNotMatch|rejects|doesNotReject|throws|doesNotThrow|fail)\s*\(|t\.(?:is|deepEqual|regex|throws|throwsAsync|not)\s*\()/i;
 export async function scanSilentSuccess(input) {
     const context = await resolveScanContext(input);
     const findings = [];
@@ -32,6 +33,8 @@ export async function scanSilentSuccess(input) {
 function scanSwallowedErrors(filePath, content) {
     const findings = [];
     for (const block of findCatchBlocks(content)) {
+        if (isBenignNullCatch(content, block))
+            continue;
         if (fakeSuccessPattern.test(block.text) && !safeFailurePattern.test(block.text)) {
             findings.push(finding({
                 ruleId: "silent-success.swallowed-error",
@@ -88,12 +91,16 @@ function scanProductionMockData(filePath, content) {
 }
 function scanHardcodedFallbacks(filePath, content) {
     const findings = [];
-    const fallbackPattern = /(fallback|mock|demo|sample|stub|fake)[\s\S]{0,180}(Response\.json|NextResponse\.json|success\s*:\s*true|ok\s*:\s*true|active|subscription|entitlement)/gi;
+    const fallbackPattern = /(fallback|mock|demo|sample|stub|fake)[\s\S]{0,220}(Response\.json|NextResponse\.json|success\s*:\s*true|ok\s*:\s*true|status\s*:\s*["']active["']|active\s*:\s*true|subscription\s*:\s*(?:mock|demo|sample|fallback|fake|\{|\[)|entitlement\s*:\s*(?:true|active|\{|\[))/gi;
     for (const match of content.matchAll(fallbackPattern)) {
         const index = match.index ?? 0;
         const window = content.slice(Math.max(0, index - 180), index + match[0].length + 180);
         if (/degraded\s*:\s*true|status\s*:\s*(4|5)\d\d|error\s*:/i.test(window))
             continue;
+        if (isCloudflareDurableObjectStubWindow(window))
+            continue;
+        if (isConfigurationFallbackWindow(window))
+            continue;
         const line = lineNumberForIndex(content, index);
         findings.push(finding({
             ruleId: "silent-success.hardcoded-fallback",
@@ -134,7 +141,7 @@ function scanTestIntegrity(filePath, content) {
         if (body.length === 0 ||
             /^\/\/\s*TODO\b/i.test(body) ||
             !assertionPattern.test(body) ||
-            (truthyOnlyPattern.test(body) && !/\b(toEqual|toStrictEqual|toBe\(|toMatch|toHave|rejects|resolves)\b/i.test(body))) {
+            hasOnlyWeakTruthyAssertions(body)) {
             findings.push(testFinding(filePath, content, testCase.line, "Weak or placeholder test may create fake confidence"));
         }
     }
@@ -167,11 +174,50 @@ function findCatchBlocks(content) {
             continue;
         blocks.push({
             text: content.slice(start, end + 1),
-            line: lineNumberForIndex(content, match.index ?? 0)
+            line: lineNumberForIndex(content, match.index ?? 0),
+            start: match.index ?? 0,
+            end
         });
     }
     return blocks;
 }
+function isBenignNullCatch(content, block) {
+    if (!/\breturn\s+null\s*;?\s*\}/i.test(block.text))
+        return false;
+    if (/(?:Response|NextResponse)\.json|success\s*:\s*true|ok\s*:\s*true|return\s+true\b|subscription\s*:|entitlement\s*:|active\s*:/i.test(block.text)) {
+        return false;
+    }
+    const before = content.slice(Math.max(0, block.start - 520), block.start);
+    const after = content.slice(block.end + 1, block.end + 720);
+    const surrounding = `${before}\n${block.text}\n${after}`;
+    if (/(?:atob|btoa|base64|base64url|decodeURIComponent|TextDecoder|JSON\.parse|\bparse[A-Z]|\bdecode[A-Z]|early\s+data)/i.test(surrounding)) {
+        return true;
+    }
+    if (/(?:STATESTORE|DurableObject|Durable Object|idFromName|stub\.fetch|env\.[A-Z0-9_]+\.get\s*\(|KV\.get|env\.KV|get\s*\([^)]*["']json["']|cache|cached|storage|state)/i.test(surrounding) &&
+        /(?:KV\.get|env\.KV|stub\.fetch|fetch\s*\(|get\s*\()/i.test(after)) {
+        return true;
+    }
+    return false;
+}
+function isCloudflareDurableObjectStubWindow(window) {
+    return (/\bidFromName\s*\(/i.test(window) &&
+        /\benv\.[A-Z0-9_]+\.get\s*\(/i.test(window) &&
+        /\bstub\b/i.test(window));
+}
+function isConfigurationFallbackWindow(window) {
+    return (/\bfunction\b[^{;=]*\([^)]*\bfallback\s*=\s*(?:\{\}|\[\]|null|undefined|[0-9]+|["'][^"']*["'])/i.test(window) &&
+        !/(?:Response|NextResponse)\.json|success\s*:\s*true|ok\s*:\s*true|active\s*:\s*true|status\s*:\s*["']active["']|subscription\s*:\s*(?:mock|demo|sample|fallback|fake|\{|\[)|entitlement\s*:\s*(?:true|active|\{|\[)/i.test(window));
+}
+function hasOnlyWeakTruthyAssertions(body) {
+    if (!truthyOnlyPattern.test(body))
+        return false;
+    if (strongAssertionPattern.test(body))
+        return false;
+    if (/\bassert\.ok\s*\([^)]*(?:[=!]==?|[<>]=?|\.(?:length|size)\b|\.includes\s*\(|\.some\s*\(|\.every\s*\()/i.test(body)) {
+        return false;
+    }
+    return true;
+}
 function findTestBlocks(content) {
     const blocks = [];
     const testPattern = /\b(?:test|it)\s*\(\s*["'`][^"'`]+["'`]\s*,\s*(?:async\s*)?\([^)]*\)\s*=>\s*\{/gi;

package/dist/stackInventory.d.ts

@@ -6,6 +6,10 @@ export interface StackEvidence {
     file: string;
     reason: string;
 }
+export interface StackInventoryWarning {
+    file: string;
+    reason: "invalid_package_json";
+}
 export interface StackInventory {
     frameworks: string[];
     databases: string[];
@@ -15,6 +19,7 @@ export interface StackInventory {
     storage: string[];
     deploy: string[];
     evidence: StackEvidence[];
+    warnings: StackInventoryWarning[];
 }
 export type StackInventoryInput = ScanInput | {
     rootDir: string;

package/dist/stackInventory.js

@@ -22,7 +22,8 @@ function createMutableInventory() {
         payments: new Set(),
         storage: new Set(),
         deploy: new Set(),
-        evidence: []
+        evidence: [],
+        warnings: []
     };
 }
 function addEvidence(inventory, category, tool, file, reason) {
@@ -95,7 +96,11 @@ function detectFromContent(file, inventory) {
     }
 }
 function detectPackageJson(file, inventory) {
-    const dependencies = readPackageDependencies(file.content);
+    const packageInventory = readPackageDependencies(file.content);
+    if (packageInventory.parseError) {
+        inventory.warnings.push({ file: file.path, reason: "invalid_package_json" });
+    }
+    const dependencies = packageInventory.dependencies;
     const has = (name) => dependencies.has(name);
     const hasAny = (names) => names.some((name) => has(name));
     if (has("next"))
@@ -196,10 +201,10 @@ function readPackageDependencies(content) {
             for (const name of Object.keys(values))
                 result.add(name);
         }
-        return result;
+        return { dependencies: result, parseError: false };
     }
     catch {
-        return new Set();
+        return { dependencies: new Set(), parseError: true };
     }
 }
 function detectPythonStack(file, inventory) {
@@ -245,6 +250,7 @@ function finalizeInventory(inventory) {
         payments: [...inventory.payments].sort(),
         storage: [...inventory.storage].sort(),
         deploy: [...inventory.deploy].sort(),
-        evidence: [...inventory.evidence].sort((a, b) => `${a.category}:${a.tool}:${a.file}`.localeCompare(`${b.category}:${b.tool}:${b.file}`))
+        evidence: [...inventory.evidence].sort((a, b) => `${a.category}:${a.tool}:${a.file}`.localeCompare(`${b.category}:${b.tool}:${b.file}`)),
+        warnings: [...inventory.warnings].sort((a, b) => `${a.reason}:${a.file}`.localeCompare(`${b.reason}:${b.file}`))
     };
 }

package/dist/types.d.ts

@@ -40,6 +40,7 @@ export interface BaseReport {
     findings: Finding[];
     summary: Summary;
     stackInventory?: import("./stackInventory.js").StackInventory;
+    fileCollection?: import("./utils/files.js").FileCollectionDiagnostics;
 }
 export interface ShowcaseReport extends BaseReport {
     command: "demo";

package/dist/utils/files.d.ts

@@ -8,10 +8,25 @@ export interface CollectTextFilesOptions {
     maxFiles?: number;
     maxTotalBytes?: number;
 }
+export interface FileCollectionDiagnostics {
+    filesScanned: number;
+    bytesScanned: number;
+    unreadableFiles: string[];
+    unreadableDirectories: string[];
+    skippedLargeFiles: string[];
+    skippedBudgetFiles: string[];
+    maxFilesReached: boolean;
+    maxTotalBytesReached: boolean;
+}
+export interface TextFileCollection {
+    files: TextFile[];
+    diagnostics: FileCollectionDiagnostics;
+}
 export declare const DEFAULT_MAX_TEXT_FILE_BYTES: number;
 export declare const DEFAULT_MAX_TEXT_FILES = 10000;
 export declare const DEFAULT_MAX_TOTAL_TEXT_BYTES: number;
 export declare function collectTextFiles(rootDir: string, options?: CollectTextFilesOptions): Promise<TextFile[]>;
+export declare function collectTextFilesWithDiagnostics(rootDir: string, options?: CollectTextFilesOptions): Promise<TextFileCollection>;
 export declare function lineNumberForIndex(content: string, index: number): number;
 export declare function lineAt(content: string, lineNumber: number): string;
 export declare function toPosix(path: string): string;

package/dist/utils/files.js

@@ -15,6 +15,9 @@ const ignoredDirectories = new Set([
 ]);
 const textFilePattern = /(^|\/)(\.env[^/]*|\.mcp\.json|mcp\.json|claude_desktop_config\.json|Dockerfile)$|\.(cjs|cts|js|jsx|json|mjs|mts|prisma|sql|toml|ts|tsx|yaml|yml|env|md|txt)$/i;
 export async function collectTextFiles(rootDir, options = {}) {
+    return (await collectTextFilesWithDiagnostics(rootDir, options)).files;
+}
+export async function collectTextFilesWithDiagnostics(rootDir, options = {}) {
     const files = [];
     const ignores = await loadIgnoreRules(rootDir);
     const budget = {
@@ -23,22 +26,38 @@ export async function collectTextFiles(rootDir, options = {}) {
         maxTotalBytes: positiveIntegerOrDefault(options.maxTotalBytes, DEFAULT_MAX_TOTAL_TEXT_BYTES),
         collectedBytes: 0
     };
-    await walk(rootDir, rootDir, files, ignores, budget);
-    return files;
+    const diagnostics = createFileCollectionDiagnostics();
+    await walk(rootDir, rootDir, files, ignores, budget, diagnostics);
+    diagnostics.filesScanned = files.length;
+    diagnostics.bytesScanned = budget.collectedBytes;
+    return { files, diagnostics };
 }
-async function walk(rootDir, currentDir, files, ignores, budget) {
-    if (files.length >= budget.maxFiles || budget.collectedBytes >= budget.maxTotalBytes)
+async function walk(rootDir, currentDir, files, ignores, budget, diagnostics) {
+    if (files.length >= budget.maxFiles) {
+        diagnostics.maxFilesReached = true;
+        return;
+    }
+    if (budget.collectedBytes >= budget.maxTotalBytes) {
+        diagnostics.maxTotalBytesReached = true;
         return;
+    }
     let entries;
     try {
         entries = await readdir(currentDir, { withFileTypes: true });
     }
     catch {
+        pushUnique(diagnostics.unreadableDirectories, relativeCollectionPath(rootDir, currentDir));
         return;
     }
     for (const entry of entries) {
-        if (files.length >= budget.maxFiles || budget.collectedBytes >= budget.maxTotalBytes)
+        if (files.length >= budget.maxFiles) {
+            diagnostics.maxFilesReached = true;
             break;
+        }
+        if (budget.collectedBytes >= budget.maxTotalBytes) {
+            diagnostics.maxTotalBytesReached = true;
+            break;
+        }
         if (entry.name === ".DS_Store" || entry.name.startsWith("._"))
             continue;
         const absolutePath = join(currentDir, entry.name);
@@ -48,16 +67,28 @@ async function walk(rootDir, currentDir, files, ignores, budget) {
         if (entry.isDirectory()) {
             if (ignoredDirectories.has(entry.name))
                 continue;
-            await walk(rootDir, absolutePath, files, ignores, budget);
+            await walk(rootDir, absolutePath, files, ignores, budget, diagnostics);
             continue;
         }
         if (!entry.isFile() || !textFilePattern.test(relativePath))
             continue;
-        const fileStat = await stat(absolutePath);
-        if (fileStat.size > budget.maxFileBytes)
+        let fileStat;
+        try {
+            fileStat = await stat(absolutePath);
+        }
+        catch {
+            pushUnique(diagnostics.unreadableFiles, relativePath);
+            continue;
+        }
+        if (fileStat.size > budget.maxFileBytes) {
+            pushUnique(diagnostics.skippedLargeFiles, relativePath);
             continue;
-        if (budget.collectedBytes + fileStat.size > budget.maxTotalBytes)
+        }
+        if (budget.collectedBytes + fileStat.size > budget.maxTotalBytes) {
+            diagnostics.maxTotalBytesReached = true;
+            pushUnique(diagnostics.skippedBudgetFiles, relativePath);
             continue;
+        }
         try {
             files.push({
                 path: relativePath,
@@ -67,10 +98,30 @@ async function walk(rootDir, currentDir, files, ignores, budget) {
             budget.collectedBytes += fileStat.size;
         }
         catch {
+            pushUnique(diagnostics.unreadableFiles, relativePath);
             continue;
         }
     }
 }
+function createFileCollectionDiagnostics() {
+    return {
+        filesScanned: 0,
+        bytesScanned: 0,
+        unreadableFiles: [],
+        unreadableDirectories: [],
+        skippedLargeFiles: [],
+        skippedBudgetFiles: [],
+        maxFilesReached: false,
+        maxTotalBytesReached: false
+    };
+}
+function relativeCollectionPath(rootDir, absolutePath) {
+    return toPosix(relative(rootDir, absolutePath)) || ".";
+}
+function pushUnique(target, value) {
+    if (!target.includes(value))
+        target.push(value);
+}
 export function lineNumberForIndex(content, index) {
     let line = 1;
     for (let position = 0; position < index; position += 1) {

package/docs/CODEX_AGENT_WORKING_RULES.md

@@ -0,0 +1,58 @@
+# Codex Agent Working Rules
+
+This project uses these rules for Codex or other coding agents working in `ai-saas-guard`.
+
+They adapt general agent-coding discipline to this repository's current boundary: pre-commercial evidence work, local-first scanner behavior, strict secret protection, and cleanup after every task.
+
+## 1. Think Before Editing
+
+- Read the handoff docs and the relevant project files before changing anything.
+- State assumptions when they affect risk, scope, deployment, secrets, user data, or release status.
+- If a request has multiple plausible meanings, choose the lowest-risk interpretation when it stays inside the user's explicit goal.
+- Stop and ask only when a reasonable assumption would be destructive, secret-bearing, commercial, or likely to erase user-owned work.
+
+## 2. Keep Changes Narrow
+
+- Every changed line must trace to the user's current request.
+- Do not refactor adjacent code, rewrite docs broadly, reformat unrelated files, or delete pre-existing dead code unless asked.
+- Match local style even when a different style would also work.
+- Prefer documentation/evidence updates over product expansion when the current blocker is missing proof or real feedback.
+
+## 3. Prefer Simpler Proof
+
+- Solve the smallest real problem that moves the gate forward.
+- Do not add configurability, abstractions, dashboards, analytics, paid packaging, or workflows just because they might be useful later.
+- For scanner behavior, prefer focused rules with synthetic fixtures and clear false-positive boundaries.
+- For hosted readiness, do not replace provider evidence with a boolean, assumption, or local-only test.
+
+## 4. Verify Before Claiming
+
+- No success claim without fresh evidence from the current turn.
+- For docs-only changes, run at least `git diff --check` and the smallest relevant test set; run `npm test` when public docs or release-gate docs change.
+- For runtime/scanner changes, run `npm test`, focused scanner checks, and any affected CLI commands.
+- If a command fails, report the exact failing area and fix it before committing or merging.
+
+## 5. Protect Secrets And Evidence
+
+- Never print, commit, rotate, overwrite, or expose secrets, tokens, private keys, cookies, certs, database URLs, customer data, installation tokens, raw webhook payloads, raw diffs, PR text, source, private URLs, checkout paths, or raw provider logs.
+- Do not bulk-delete Cloudflare KV records or remove GitHub App installations unless the user explicitly approves a safe scoped proof.
+- Keep historical rows in `docs/hosted-operations-evidence.md`; append new evidence instead of rewriting history.
+- Keep `.local/` private and ignored.
+
+## 6. Use Risk-Gated Autonomy
+
+- Continue automatically for safe read-only checks, docs updates, tests, PR creation, and cleanup when the user has asked to proceed.
+- Pause only for destructive operations, secret access, GitHub App installation mutation, Cloudflare deployment, KV deletion, npm publishing, or commercialization work.
+- Do not start billing, pricing, paid packaging, marketplace conversion, sales funnel, broad analytics, or customer account work.
+- If the next valid progress requires real users or design partners, record the blocker without fabricating evidence.
+
+## 7. Clean Up Every Time
+
+- Remove temporary files generated under `/tmp` or the repo before finishing.
+- Stop or wait for any test, watch, dev-server, deploy, smoke-test, or GitHub-watch process started during the task.
+- Confirm `git status -sb` and mention any intentional remaining branch/PR state.
+- If README.md changes, check and update `docs/README.zh-CN.md` in the same task.
+
+## Working Test
+
+These rules are working when diffs are small, every claim has verification evidence, public docs stay aligned, no unrelated files are touched, no secrets are exposed, and public beta remains blocked until real design-partner and provider evidence exists.