ai-saas-guard 0.13.0 → 0.14.0

package/README.md

@@ -73,8 +73,8 @@ The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is availab
 | JSON and SARIF output | Available |
 | Composite GitHub Action | Available |
 | Project config | `.ai-saas-guard.json` rule toggles, severity overrides, and fail thresholds |
-| Versioned Action tags | `v0.13.0`, `v0` |
-| npm package | `ai-saas-guard@0.13.0` |
+| Versioned Action tags | `v0.14.0`, `v0` |
+| npm package | `ai-saas-guard@0.14.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -214,7 +214,7 @@ Hosted uninstall and data deletion behavior is documented in [docs/hosted-uninst
 
 Hosted pricing and packaging boundaries are documented in [docs/hosted-pricing-packaging.md](docs/hosted-pricing-packaging.md). Core local scanning stays useful without an account; hosted plans may add workflow convenience, saved reports, team policy, and optional human review, but they do not gate local CLI scanning.
 
-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, and a worker read-only scan planner that fixes the CLI command, requires repository `contents: read`, and ignores PR-authored repo names, token scopes, and commands. They also cover queue-safe webhook event parsing, bounded check-run summary rendering, idempotent queue cleanup planning, worker checkout cleanup planning, and other service-free helpers exported from `ai-saas-guard/hosted/contracts`.
+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`, 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, and other service-free helpers exported from `ai-saas-guard/hosted/contracts`. PR comments remain a later workflow or paid hosted feature, not part of the hosted MVP contract.
 
 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.
 
@@ -254,7 +254,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.13.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.14.0` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard

package/README.zh-CN.md

@@ -55,7 +55,7 @@ AI 能很快把一个 SaaS 从想法做成可运行的产品。真正难的是
 
 这个仓库是公开 GitHub 仓库。
 
-CLI 已发布到 npm：`ai-saas-guard@0.13.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.13.0`。
+CLI 已发布到 npm：`ai-saas-guard@0.14.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.14.0`。
 
 | 模块 | 状态 |
 | --- | --- |
@@ -66,8 +66,8 @@ CLI 已发布到 npm：`ai-saas-guard@0.13.0`。GitHub Action 支持 `v0` 浮动
 | Markdown PR summary | 已可用 |
 | GitHub Action | 已可用 |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖和 fail threshold |
-| 当前版本 | `0.13.0` |
-| Action 标签 | `v0.13.0`、`v0` |
+| 当前版本 | `0.14.0` |
+| Action 标签 | `v0.14.0`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 
 ## 快速开始
@@ -257,11 +257,12 @@ jobs:
 - worker read-only scan planner：只用 trusted identity 规划临时 worker checkout，要求 repository `contents: read`，固定运行 `ai-saas-guard pr-risk --json`，并忽略 PR 正文里的 repo 名、token scope 或命令
 - 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
 - queue cleanup planner
 - worker checkout cleanup planner
 - hosted compact report fixture：[examples/hosted-compact-report.json](examples/hosted-compact-report.json)
 
-这些 helper 不会启动服务、不会调用 GitHub API、不会请求 installation token、不会写 check run，也不会上传源码。
+这些 helper 不会启动服务、不会调用 GitHub API、不会请求 installation token、不会真实写 check run、不会发 PR comment，也不会上传源码。
 
 ## 它不是什么
 

package/dist/hosted/contracts.d.ts

@@ -388,6 +388,71 @@ export interface HostedCheckRunSummary {
         modelTraining: "disabled";
     };
 }
+export type HostedCheckRunPublicationRejectReason = InstallationScopeRejectReason | "checks_write_permission_required";
+export interface HostedCheckRunPublicationInput {
+    identity: HostedScanIdentity;
+    report: CompactHostedReport;
+    jobKey: string;
+    requestedAt: string;
+    installationId: number;
+    selectedRepositoryIds: number[];
+    removedRepositoryIds?: number[];
+    installationTokenPermissions: {
+        checks?: string;
+    };
+    failOnSeverity?: HostedCheckRunSeverityThreshold;
+    maxMarkdownChars?: number;
+    rawSource?: string;
+    rawDiff?: string;
+    secretValues?: string[];
+    untrustedPrText?: string;
+    customerPayload?: unknown;
+}
+export interface HostedCheckRunApiPayload {
+    name: "AI SaaS Guard";
+    head_sha: string;
+    status: "completed";
+    conclusion: HostedCheckRunConclusion;
+    external_id: string;
+    output: {
+        title: string;
+        summary: string;
+        text: string;
+        annotations: HostedCheckRunAnnotation[];
+    };
+}
+export interface HostedCheckRunPublicationPlan {
+    accepted: boolean;
+    reason?: HostedCheckRunPublicationRejectReason;
+    jobKey: string;
+    requestedAt: string;
+    operation?: "create";
+    shouldWriteCheckRun: boolean;
+    shouldCreatePrComment: false;
+    shouldCallGitHubApi: false;
+    installationTokenScope?: {
+        installationId: number;
+        repositoryId: number;
+        permissions: {
+            checks: "write";
+        };
+        selectedRepositoryOnly: true;
+    };
+    request?: {
+        method: "POST";
+        endpoint: string;
+        payload: HostedCheckRunApiPayload;
+    };
+    privacy: {
+        includesRawSource: false;
+        includesRawDiffs: false;
+        includesSecrets: false;
+        includesCustomerPayloads: false;
+        includesUntrustedPrText: false;
+        createsPrComment: false;
+        modelTraining: "disabled";
+    };
+}
 export type HostedDeletionTrigger = "repository_removed" | "installation_deleted" | "repeated_cleanup";
 export interface HostedDeletionPlanInput {
     trigger: HostedDeletionTrigger;
@@ -443,6 +508,7 @@ export declare function resolveHostedRetentionDays(input?: {
 }): number;
 export declare function createCompactHostedReport(input: CompactHostedReportInput): CompactHostedReport;
 export declare function createHostedCheckRunSummary(input: HostedCheckRunSummaryInput): HostedCheckRunSummary;
+export declare function planHostedCheckRunPublication(input: HostedCheckRunPublicationInput): HostedCheckRunPublicationPlan;
 export declare function getHostedDeletionIdempotencyKey(input: {
     trigger: HostedDeletionTrigger;
     installationId: number;

package/dist/hosted/contracts.js

@@ -494,6 +494,56 @@ export function createHostedCheckRunSummary(input) {
         }
     };
 }
+export function planHostedCheckRunPublication(input) {
+    const scopeDecision = authorizeInstallationTokenScope({
+        identity: input.identity,
+        installationId: input.installationId,
+        selectedRepositoryIds: input.selectedRepositoryIds,
+        removedRepositoryIds: input.removedRepositoryIds
+    });
+    if (!scopeDecision.authorized) {
+        return rejectHostedCheckRunPublication(input, scopeDecision.reason ?? "repository_not_installed");
+    }
+    if (input.installationTokenPermissions.checks !== "write") {
+        return rejectHostedCheckRunPublication(input, "checks_write_permission_required");
+    }
+    const summary = createHostedCheckRunSummary({
+        report: input.report,
+        failOnSeverity: input.failOnSeverity,
+        maxMarkdownChars: input.maxMarkdownChars
+    });
+    return {
+        accepted: true,
+        jobKey: input.jobKey,
+        requestedAt: input.requestedAt,
+        operation: "create",
+        shouldWriteCheckRun: true,
+        shouldCreatePrComment: false,
+        shouldCallGitHubApi: false,
+        installationTokenScope: {
+            installationId: input.identity.installationId,
+            repositoryId: input.identity.repositoryId,
+            permissions: { checks: "write" },
+            selectedRepositoryOnly: true
+        },
+        request: {
+            method: "POST",
+            endpoint: `/repos/${input.identity.repositoryFullName}/check-runs`,
+            payload: {
+                name: summary.name,
+                head_sha: input.identity.headSha,
+                status: "completed",
+                conclusion: summary.conclusion,
+                external_id: input.jobKey,
+                output: {
+                    ...summary.output,
+                    annotations: summary.annotations
+                }
+            }
+        },
+        privacy: hostedCheckRunPublicationPrivacy()
+    };
+}
 export function getHostedDeletionIdempotencyKey(input) {
     return [input.trigger, input.installationId, input.repositoryId ?? "all"].join(":");
 }
@@ -627,6 +677,29 @@ function hostedWorkerReadOnlyScanPrivacy() {
         acceptsCommandFromPrText: false
     };
 }
+function rejectHostedCheckRunPublication(input, reason) {
+    return {
+        accepted: false,
+        reason,
+        jobKey: input.jobKey,
+        requestedAt: input.requestedAt,
+        shouldWriteCheckRun: false,
+        shouldCreatePrComment: false,
+        shouldCallGitHubApi: false,
+        privacy: hostedCheckRunPublicationPrivacy()
+    };
+}
+function hostedCheckRunPublicationPrivacy() {
+    return {
+        includesRawSource: false,
+        includesRawDiffs: false,
+        includesSecrets: false,
+        includesCustomerPayloads: false,
+        includesUntrustedPrText: false,
+        createsPrComment: false,
+        modelTraining: HOSTED_PRIVACY_DEFAULTS.modelTraining
+    };
+}
 function parseJsonPayload(payload) {
     try {
         return JSON.parse(Buffer.isBuffer(payload) ? payload.toString("utf8") : payload);
@@ -683,6 +756,8 @@ function formatCheckRunTitle(totalFindings, conclusion, failOnSeverity) {
     return `AI SaaS Guard found ${totalFindings} finding${totalFindings === 1 ? "" : "s"} to review`;
 }
 function formatCheckRunMarkdown(report, conclusion, localCliCommand) {
+    const categories = getHostedCheckRunCategories(report);
+    const filesToReview = getHostedCheckRunFiles(report);
     const findingLines = report.evidence.length === 0
         ? ["No findings in the compact hosted report."]
         : [
@@ -702,6 +777,17 @@ function formatCheckRunMarkdown(report, conclusion, localCliCommand) {
         "Summary:",
         ...severityOrder.map((severity) => `- ${capitalize(severity)}: ${report.summaryCounts[severity] ?? 0}`),
         "",
+        "Review categories:",
+        ...(categories.length === 0 ? ["- None"] : categories.map((category) => `- ${category}`)),
+        "",
+        "Files to review first:",
+        ...(filesToReview.length === 0 ? ["- None"] : filesToReview.map((file) => `- ${file}`)),
+        "",
+        "Verification steps:",
+        "- Review each listed file before release or merge.",
+        "- Reproduce locally with the CLI command above.",
+        "- Treat findings as review prompts; confirm behavior with app-specific tests.",
+        "",
         "Findings:",
         ...findingLines
     ].join("\n");
@@ -738,6 +824,27 @@ function annotationLevelForSeverity(severity) {
 function formatFindingLocation(finding) {
     return `${finding.file}${finding.line === undefined ? "" : `:${finding.line}`}`;
 }
+function getHostedCheckRunCategories(report) {
+    const categories = report.evidence.map((finding) => categoryForRuleId(finding.ruleId));
+    return [...new Set(categories)];
+}
+function categoryForRuleId(ruleId) {
+    const prefix = ruleId.split(".")[0] ?? "review";
+    const categoryNames = {
+        api: "API routes",
+        deploy: "Deploy config",
+        mcp: "MCP tools",
+        pr: "Pull request risk",
+        "pr-risk": "Pull request risk",
+        secrets: "Secrets and env",
+        stripe: "Stripe billing",
+        supabase: "Supabase data access"
+    };
+    return categoryNames[prefix] ?? capitalize(prefix);
+}
+function getHostedCheckRunFiles(report) {
+    return [...new Set(report.evidence.map((finding) => finding.file))].slice(0, 10);
+}
 function escapeMarkdownTableCell(value) {
     return value.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
 }

package/docs/github-action.md

@@ -2,7 +2,7 @@
 
 `ai-saas-guard` ships as a composite GitHub Action for pull request and code scanning workflows.
 
-Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.13.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
+Use `zr9959/ai-saas-guard@v0` for the latest compatible pre-1.0 Action. Use a specific tag such as `v0.14.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
 
 ## PR Summary
 

package/docs/hosted-preimplementation-contracts.md

@@ -117,6 +117,7 @@ Default behavior:
 - include review-first language that tells readers to verify findings before release
 - state that the result is not a full security audit, pentest, or certification
 - include a local CLI link through the exact `npx ai-saas-guard@<version> pr-risk --root .` command
+- include review categories, files to review first, and verification steps
 - cap check-run text with bounded Markdown so oversized reports cannot create unbounded API payloads
 
 Privacy boundaries:
@@ -126,6 +127,27 @@ Privacy boundaries:
 - do not include raw source, raw diffs, secret values, webhook payload bodies, customer payloads, or private URLs
 - preserve `modelTraining: disabled`
 
+## Check-Run Publication Planner
+
+The check-run publication planner turns a compact hosted report into a GitHub Checks API request plan. It is a pure planner only: it does not call GitHub, request installation tokens, write check runs, post PR comments, fetch repositories, or store report data.
+
+Default behavior:
+
+- authorize the same installation and selected-repository scope before planning a Check Run write
+- require installation token permissions to include repository `checks: write`
+- create a Check Run payload for the trusted head SHA
+- use conservative conclusions from the summary renderer: `success` for no findings, `neutral` for review-needed findings, and `failure` only when a configured policy threshold is met
+- include bounded Markdown, annotations, categories, verification steps, and the local CLI reproduction command
+- keep PR comments disabled for the MVP
+
+Privacy boundaries:
+
+- plan a Check Run from compact report fields only
+- do not include raw source, raw diffs, secret values, untrusted PR text, webhook payload bodies, customer payloads, private URLs, or worker checkout paths
+- do not create issue comments, review comments, or PR comments
+
+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.
+
 ## 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.
@@ -223,7 +245,11 @@ Automated tests must cover:
 - untrusted PR text cannot override trusted identity
 - check-run summary renderer conclusions stay success, neutral, or failure based on explicit compact-report rules
 - bounded Markdown truncates large check-run text and points readers to the local CLI
+- rendered summaries include categories, files to review first, and verification steps
 - rendered summaries do not expose raw source, raw diffs, secret values, or customer payloads
+- check-run publication planning requires repository `checks: write` permissions
+- check-run publication planning creates bounded Check Run payloads from compact reports only
+- check-run publication planning keeps PR comments disabled
 - queue cleanup planner cancels only matching repository-scoped queued work
 - queue cleanup planner handles installation-scoped cleanup without touching other installations
 - idempotent repeated cleanup preserves terminal jobs and does not create duplicate cancellation work

package/docs/npm-publishing.md

@@ -5,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.13.0`
+- Current version: `0.14.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.13.0`
+- GitHub Release: `v0.14.0`
 - 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
@@ -17,7 +17,7 @@
 
 Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create and review a release tag such as `v0.13.0`.
+1. Create and review a release tag such as `v0.14.0`.
 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/project-handoff.md

@@ -1,6 +1,6 @@
 # Project Handoff
 
-Last updated: 2026-05-23
+Last updated: 2026-05-24
 
 Use this public-safe document when moving `ai-saas-guard` into a new GitHub-facing ChatGPT/Codex Project or a new conversation.
 
@@ -57,7 +57,7 @@ Implemented surfaces:
 - hosted operational release gate document requiring hosted CI, webhook replay, dependency and container scanning, privacy and retention verification, worker cleanup, monitoring and alerting, manual rollback, and incident response evidence before exposure
 - hosted uninstall and data deletion document defining repository removal, full app uninstall, compact report deletion, queue cancellation, audit record retention, repeated cleanup idempotency, and user-facing deletion wording
 - hosted pricing and packaging document defining open-source CLI boundaries, free/public repo hosted behavior, private repo hosted behavior, PR comments, saved reports, team policy, optional Launch Review, and no pentest/certification/full-audit claims
-- hosted pre-implementation contracts document, hosted compact report fixture, and pure helpers for pull request webhook intake planning, durable scan queue upsert planning, worker read-only scan planning, queue-safe pull request event parsing from trusted GitHub event fields, bounded check-run summary rendering, idempotent queue cleanup planning, and worker checkout cleanup planning
+- hosted pre-implementation contracts document, hosted compact report fixture, and pure helpers for pull request webhook intake planning, durable scan queue upsert planning, worker read-only scan planning, Check Run publication planning, queue-safe pull request event parsing from trusted GitHub event fields, bounded check-run summary rendering, idempotent queue cleanup planning, and worker checkout cleanup planning
 - implementation-ready hosted GitHub App permission contract for required permissions, optional PR comment permissions, selected repository installation, and out-of-scope broad permissions
 - pure hosted GitHub App contract helpers and tests for webhook intake order, webhook verification, installation token scoping, durable scan queue idempotency, compact reports, and retention limits
 - GitHub issue templates for bug reports, false positives, false negatives, rule requests, and public-safe security reports
@@ -115,19 +115,20 @@ Current issue set:
 
 - Closed hosted MVP issue: #24 webhook intake.
 - Closed hosted MVP issue: #25 idempotent queue contract.
-- Open hosted MVP roadmap issues: #26 read-only worker checkout, #27 Check summaries, #28 retention/uninstall cleanup, and #29 hosted operational release gate.
+- Closed hosted MVP issue: #26 read-only worker checkout.
+- Open hosted MVP roadmap issues: #27 Check summaries, #28 retention/uninstall cleanup, and #29 hosted operational release gate.
 
 CI:
 
 - Workflow: `.github/workflows/ci.yml`
 - Runs on pull requests and pushes to `main`
 - Uses `permissions: contents: read`
-- Latest verified run for the hosted durable queue contract release succeeded
+- Latest verified run for the hosted read-only worker plan release succeeded
 
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.13.0`
+- Current release line: `v0.14.0`
 - Publish workflow: `.github/workflows/npm-publish.yml`
 - Trusted Publisher: GitHub Actions for `zr9959/ai-saas-guard`, workflow `npm-publish.yml`
 - Long-lived npm publish tokens should not be required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-saas-guard",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",