ai-saas-guard 0.11.0 → 0.12.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.11.0`, `v0` |
-| npm package | `ai-saas-guard@0.11.0` |
+| Versioned Action tags | `v0.12.0`, `v0` |
+| npm package | `ai-saas-guard@0.12.0` |
 | npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
 ## Quick Start
@@ -214,13 +214,13 @@ 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, builds trusted scan identity, authorizes selected-repository scope, and defaults to check-run-only output. 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, plus a durable scan queue planner that reuses queued, running, and completed jobs for the same trusted scan key. 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`.
 
 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 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 pure pre-implementation hosted contract helpers and tests for webhook intake order, webhook verification, installation token scoping, queue idempotency, compact reports, and retention limits. These helpers do not implement or deploy a hosted service.
+The repository also includes pure pre-implementation hosted contract helpers and tests for webhook intake order, webhook verification, installation token scoping, durable queue idempotency, compact reports, and retention limits. These helpers do not implement or deploy a hosted service.
 
 Users should prefer the local CLI for private repositories, offline review, or no-account workflows where hosted code processing is not acceptable.
 
@@ -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.11.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.12.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.11.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.11.0`。
+CLI 已发布到 npm：`ai-saas-guard@0.12.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.12.0`。
 
 | 模块 | 状态 |
 | --- | --- |
@@ -66,8 +66,8 @@ CLI 已发布到 npm：`ai-saas-guard@0.11.0`。GitHub Action 支持 `v0` 浮动
 | Markdown PR summary | 已可用 |
 | GitHub Action | 已可用 |
 | 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖和 fail threshold |
-| 当前版本 | `0.11.0` |
-| Action 标签 | `v0.11.0`、`v0` |
+| 当前版本 | `0.12.0` |
+| Action 标签 | `v0.12.0`、`v0` |
 | npm 发布 | GitHub Actions Trusted Publisher/OIDC，无需长期 npm token |
 
 ## 快速开始
@@ -253,6 +253,7 @@ jobs:
 已经实现的 hosted 预实现纯契约包括：
 
 - pull request webhook intake planner：先验签，再解析 payload、生成可信 identity、校验 selected-repository scope，并默认只走 check-run-only 输出
+- durable scan queue planner：同一个 trusted scan key 的 queued/running/completed job 会复用，不重复排 worker，也不会把源码、diff、secret 或 PR 正文放进队列 payload
 - webhook event parser
 - check-run summary renderer
 - queue cleanup planner

package/dist/hosted/contracts.d.ts

@@ -114,6 +114,57 @@ export interface HostedScanJobDecision {
     shouldCreatePrComment: boolean;
 }
 export type HostedQueueJobStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
+export interface HostedScanQueueRecord {
+    key: string;
+    identity: HostedScanIdentity;
+    status: HostedQueueJobStatus;
+    attempt: number;
+    deliveryIds: string[];
+    createdAt: string;
+    updatedAt: string;
+    reportId?: string;
+}
+export interface HostedScanQueuePayload {
+    key: string;
+    identity: HostedScanIdentity;
+    deliveryId: string;
+    attempt: number;
+    requestedAt: string;
+    source: "github_pull_request";
+}
+export interface HostedScanQueueUpsertInput {
+    identity: HostedScanIdentity;
+    deliveryId: string;
+    requestedAt: string;
+    queue: Map<string, HostedScanQueueRecord>;
+    manualRerun?: boolean;
+    rawSource?: string;
+    rawDiff?: string;
+    secretValues?: string[];
+    untrustedPrText?: string;
+    customerPayload?: unknown;
+}
+export interface HostedScanQueueUpsertDecision {
+    key: string;
+    idempotent: true;
+    created: boolean;
+    reusedExistingJob: boolean;
+    existingStatus?: HostedQueueJobStatus;
+    attempt: number;
+    queueRecord: HostedScanQueueRecord;
+    queuePayload: HostedScanQueuePayload;
+    shouldEnqueueWorker: boolean;
+    shouldReuseCompletedReport: boolean;
+    shouldCreateCheckRun: boolean;
+    shouldCreatePrComment: false;
+    privacy: {
+        includesRawSource: false;
+        includesRawDiffs: false;
+        includesSecrets: false;
+        includesUntrustedPrText: false;
+        includesCustomerPayloads: false;
+    };
+}
 export type HostedQueueCleanupTrigger = "repository_removed" | "installation_deleted" | "repeated_cleanup";
 export interface HostedQueueCleanupJobState {
     key: string;
@@ -303,6 +354,7 @@ export declare function parseHostedPullRequestEvent(input: HostedPullRequestEven
 export declare function authorizeInstallationTokenScope(input: InstallationScopeInput): InstallationScopeDecision;
 export declare function getHostedScanIdempotencyKey(identity: HostedScanIdentity): string;
 export declare function upsertHostedScanJob(queue: Map<string, HostedScanJobState>, input: HostedScanJobInput): HostedScanJobDecision;
+export declare function planHostedScanQueueUpsert(input: HostedScanQueueUpsertInput): HostedScanQueueUpsertDecision;
 export declare function getHostedQueueCleanupIdempotencyKey(input: {
     trigger: HostedQueueCleanupTrigger;
     installationId: number;

package/dist/hosted/contracts.js

@@ -222,6 +222,76 @@ export function upsertHostedScanJob(queue, input) {
         shouldCreatePrComment: false
     };
 }
+export function planHostedScanQueueUpsert(input) {
+    const key = getHostedScanIdempotencyKey(input.identity);
+    const existing = input.queue.get(key);
+    if (!existing) {
+        const record = {
+            key,
+            identity: input.identity,
+            status: "queued",
+            attempt: 1,
+            deliveryIds: [input.deliveryId],
+            createdAt: input.requestedAt,
+            updatedAt: input.requestedAt
+        };
+        input.queue.set(key, record);
+        return {
+            key,
+            idempotent: true,
+            created: true,
+            reusedExistingJob: false,
+            attempt: record.attempt,
+            queueRecord: { ...record, deliveryIds: [...record.deliveryIds] },
+            queuePayload: createHostedScanQueuePayload(record, input.deliveryId, input.requestedAt),
+            shouldEnqueueWorker: true,
+            shouldReuseCompletedReport: false,
+            shouldCreateCheckRun: true,
+            shouldCreatePrComment: false,
+            privacy: hostedScanQueuePrivacy()
+        };
+    }
+    if (!existing.deliveryIds.includes(input.deliveryId)) {
+        existing.deliveryIds.push(input.deliveryId);
+    }
+    const existingStatus = existing.status;
+    if (input.manualRerun) {
+        existing.attempt += 1;
+        existing.status = "queued";
+        existing.updatedAt = input.requestedAt;
+        return {
+            key,
+            idempotent: true,
+            created: false,
+            reusedExistingJob: false,
+            existingStatus,
+            attempt: existing.attempt,
+            queueRecord: cloneHostedScanQueueRecord(existing),
+            queuePayload: createHostedScanQueuePayload(existing, input.deliveryId, input.requestedAt),
+            shouldEnqueueWorker: true,
+            shouldReuseCompletedReport: false,
+            shouldCreateCheckRun: true,
+            shouldCreatePrComment: false,
+            privacy: hostedScanQueuePrivacy()
+        };
+    }
+    existing.updatedAt = input.requestedAt;
+    return {
+        key,
+        idempotent: true,
+        created: false,
+        reusedExistingJob: true,
+        existingStatus,
+        attempt: existing.attempt,
+        queueRecord: cloneHostedScanQueueRecord(existing),
+        queuePayload: createHostedScanQueuePayload(existing, input.deliveryId, input.requestedAt),
+        shouldEnqueueWorker: false,
+        shouldReuseCompletedReport: existingStatus === "completed",
+        shouldCreateCheckRun: false,
+        shouldCreatePrComment: false,
+        privacy: hostedScanQueuePrivacy()
+    };
+}
 export function getHostedQueueCleanupIdempotencyKey(input) {
     return ["queue-cleanup", input.trigger, input.installationId, input.repositoryId ?? "all"].join(":");
 }
@@ -441,6 +511,32 @@ function hostedWebhookIntakePrivacy() {
         includesCustomerPayloads: false
     };
 }
+function createHostedScanQueuePayload(record, deliveryId, requestedAt) {
+    return {
+        key: record.key,
+        identity: record.identity,
+        deliveryId,
+        attempt: record.attempt,
+        requestedAt,
+        source: "github_pull_request"
+    };
+}
+function cloneHostedScanQueueRecord(record) {
+    return {
+        ...record,
+        identity: { ...record.identity },
+        deliveryIds: [...record.deliveryIds]
+    };
+}
+function hostedScanQueuePrivacy() {
+    return {
+        includesRawSource: false,
+        includesRawDiffs: false,
+        includesSecrets: false,
+        includesUntrustedPrText: false,
+        includesCustomerPayloads: false
+    };
+}
 function parseJsonPayload(payload) {
     try {
         return JSON.parse(Buffer.isBuffer(payload) ? payload.toString("utf8") : payload);

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.11.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.12.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
 
 ## PR Summary
 

package/docs/hosted-preimplementation-contracts.md

@@ -26,6 +26,27 @@ Privacy boundaries:
 
 The exported helper is `planHostedPullRequestWebhookIntake`. It is intentionally service-free: callers still need a real webhook server, queue provider, installation token lookup, worker checkout, scanner execution, compact report storage, and GitHub Checks API writer before any hosted environment exists.
 
+## Durable Scan Queue Planner
+
+The durable scan queue planner defines how the future hosted service should create or reuse scan jobs once a signed pull request webhook has produced trusted scan identity. It is a pure planner only: it does not connect to a queue provider, run a worker, fetch source, write reports, or call GitHub APIs.
+
+Default behavior:
+
+- compute the same logical scan key from installation ID, repository ID, pull request number, head SHA, and scanner version
+- create one queued job when no matching job exists
+- reuse existing queued, running, or completed jobs for duplicate deliveries
+- reuse completed compact reports instead of enqueueing duplicate worker work
+- allow manual reruns to increment `attempt` while keeping the same logical scan key
+- keep the first hosted slice check-run-only; PR comments remain disabled
+
+Queue payload boundaries:
+
+- include only scan identity, job key, delivery ID, attempt, requested time, and source
+- do not include raw source, raw diffs, secret values, untrusted PR text, webhook payload bodies, customer payloads, private URLs, or worker checkout paths
+- return safe queue metadata that can be stored by a durable queue without leaking source code
+
+The exported helper is `planHostedScanQueueUpsert`. It is intended to be the queue-provider-independent contract for the first real hosted queue implementation.
+
 ## Webhook Event Parser
 
 The webhook event parser runs after webhook signature verification. It converts a reduced GitHub `pull_request` webhook payload into a queue-safe scan request identity.
@@ -164,6 +185,10 @@ Automated tests must cover:
 - signed pull request webhook intake verifies signatures before JSON parsing or queueing
 - accepted pull request webhook intake queues one check-run-only scan request from trusted fields
 - rejected installation scope stops before repository fetch planning
+- durable scan queue planning creates one queued job for a new trusted scan key
+- duplicate deliveries reuse queued, running, and completed jobs without enqueueing duplicate worker work
+- completed duplicate jobs reuse compact reports
+- manual reruns increment attempt without changing the logical scan key
 - accepted pull request events build the expected trusted scan identity
 - unsupported actions are rejected
 - draft pull requests are rejected by default

package/docs/npm-publishing.md

@@ -5,10 +5,10 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.11.0`
+- Current version: `0.12.0`
 - npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
 - First npm-published version: `0.1.1`
-- GitHub Release: `v0.11.0`
+- GitHub Release: `v0.12.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.11.0`.
+1. Create and review a release tag such as `v0.12.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

@@ -57,9 +57,9 @@ 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, 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, 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, scan queue idempotency, compact reports, and retention limits
+- 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
 - CODEOWNERS for source, tests, docs, workflows, Action, and package metadata
 - JSON output
@@ -113,7 +113,8 @@ GitHub Project:
 
 Current issue set:
 
-- Open hosted MVP roadmap issues: #24 webhook intake, #25 idempotent queue contract, #26 read-only worker checkout, #27 Check summaries, #28 retention/uninstall cleanup, and #29 hosted operational release gate.
+- Closed hosted MVP issue: #24 webhook intake.
+- Open hosted MVP roadmap issues: #25 idempotent queue contract, #26 read-only worker checkout, #27 Check summaries, #28 retention/uninstall cleanup, and #29 hosted operational release gate.
 
 CI:
 
@@ -125,7 +126,7 @@ CI:
 Publishing:
 
 - npm package: `ai-saas-guard`
-- Current release line: `v0.11.0`
+- Current release line: `v0.12.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.11.0",
+  "version": "0.12.0",
   "description": "Repo-local launch-readiness scanner for AI-built SaaS apps.",
   "type": "module",
   "homepage": "https://github.com/zr9959/ai-saas-guard#readme",