ai-saas-guard 0.29.0 → 0.29.2

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  ai-saas-guard is a local-first launch gate for AI-built Next.js, Supabase, Stripe, Vercel, and MCP SaaS apps. It focuses on auth, billing, data access, secrets, MCP, and deploy decisions, plus CI and fake-success paths, so you know what to review before launch or merge. It runs locally, reads your repo only, and does not upload code.
+  A local-first launch gate for AI-built Next.js, Supabase, Stripe, Vercel, GitHub Actions, and MCP SaaS apps. It focuses on auth, billing, data access, secrets, MCP, and deploy paths, then turns risky files into a short review queue before launch or merge. It runs locally, reads your repo only, and does not upload code.
 </p>
 
 <p align="center">
@@ -27,9 +27,11 @@
 
 ---
 
-## The Launch Problem
+## Before You Invite Users
 
-AI can make a SaaS look finished while the real launch blockers sit in trust-boundary code. These are the failures that hurt after real users arrive:
+AI can make a SaaS look finished: 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.
+
+These are the failures that hurt after real users arrive:
 
 - one customer can see or change another customer's data
 - Stripe grants access from an unsigned, duplicated, missing, or failed webhook path
@@ -42,23 +44,56 @@ AI can make a SaaS look finished while the real launch blockers sit in trust-bou
 
 `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.
 
+## 60-Second Local Check
+
+Run it against your app without installing anything globally:
+
+```bash
+npx ai-saas-guard@latest scan --root /path/to/your-saas
+```
+
+For an AI-heavy pull request:
+
+```bash
+npx ai-saas-guard@latest pr-risk --root /path/to/your-saas --base origin/main --markdown
+```
+
+You get rule IDs, severity, file evidence, why it matters, how to verify it manually, and a concrete fix direction. The scanner is deterministic, read-only, and does not call an LLM.
+
+## Try The Demo Fixtures
+
+Want to see the report before scanning your own repo?
+
+```bash
+git clone https://github.com/zr9959/ai-saas-guard.git
+cd ai-saas-guard
+npx ai-saas-guard@latest scan --root examples/demo-risky-saas
+npx ai-saas-guard@latest scan --root examples/demo-safe-saas
+```
+
+The risky demo currently returns 19 intentional findings across Stripe, Supabase, silent-success paths, Next/Vercel deploy hints, and GitHub Actions. The safe demo returns 0 findings for the same broad surfaces with safer static patterns. See [docs/demo-quickstart.md](docs/demo-quickstart.md).
+
 ## See The Output
 
 The report is designed to be read before launch or before merging an AI-heavy PR. A longer copy-paste example is in [docs/sample-launch-report.md](docs/sample-launch-report.md).
 
 ```text
 Launch Gate: review before launch
-4 findings: 1 high, 3 medium
+19 findings: 2 critical, 6 high, 7 medium, 3 low, 1 info
 
-HIGH stripe.webhook.missing-signature
+CRITICAL stripe.webhook.missing-signature
 File: app/api/stripe/webhook/route.ts
 Why: billing access can be granted from a webhook path that does not verify Stripe signatures.
 Verify: replay a webhook with an invalid signature and confirm the route rejects it.
 Fix: read the raw body, call stripe.webhooks.constructEvent, and make event handling idempotent.
 
-MEDIUM supabase.rls.tenant-predicate-missing
-File: supabase/migrations/20260524_accounts.sql
-Verify: sign in as user A and user B; confirm neither can SELECT or UPDATE the other's rows.
+HIGH silent-success.swallowed-error
+File: app/api/billing/checkout/route.ts
+Verify: force the upstream billing call to fail and confirm the route returns an error, not fake success.
+
+MEDIUM deploy.next.missing-security-headers
+File: app/api/billing/checkout/route.ts
+Verify: inspect production response headers for auth, billing, and API pages.
 ```
 
 ## What You Get
@@ -85,28 +120,6 @@ One command returns a launch-readiness report with:
 | Are tools and CI overpowered? | MCP side-effect classes, local policy/receipt templates, GitHub Actions permissions, concurrency, checkout depth, action pinning |
 | Can reviewers trust the PR? | `pr-risk` ranking for auth, billing, RLS, deploy, API, storage, tests, silent-success paths, missing spec context, and large AI diffs |
 
-## Current Status
-
-This repository is public on GitHub.
-
-The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is available through versioned release tags. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag for controlled upgrades, or a reviewed commit SHA for stricter supply-chain pinning.
-
-| Area | Status |
-| --- | --- |
-| Public GitHub repository | Available |
-| npm CLI | `ai-saas-guard@0.29.0` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.29.0` |
-| Outputs | 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.29.0`, `v0` |
-| Current release | `0.29.0` hosted Node checkout platform composition, Clerk unsafe metadata rule, Prisma tenant-scope rule, Vercel cron guard rule, sample launch report, and Marketplace wrapper decision |
-| 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 |
-
 ## Quick Start
 
 Run the published CLI without installing it globally:
@@ -157,6 +170,28 @@ node dist/cli.js check-mcp --root /path/to/your-saas
 node dist/cli.js check-actions --root /path/to/your-saas
 ```
 
+## Current Status
+
+This repository is public on GitHub.
+
+The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is available through versioned release tags. Use `v0` for the latest compatible pre-1.0 Action, a specific release tag for controlled upgrades, or a reviewed commit SHA for stricter supply-chain pinning.
+
+| Area | Status |
+| --- | --- |
+| Public GitHub repository | Available |
+| npm CLI | `ai-saas-guard@0.29.2` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` or fixed tag `v0.29.2` |
+| Outputs | 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.29.2`, `v0` |
+| Current release | `0.29.2` publishes public risky/safe demo fixtures, a demo quickstart, quickstart feedback template, and refreshed first-run README guidance |
+| 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 |
+
 ## Example Finding
 
 Terminal output is designed to be useful to a reviewer, not just a scanner dashboard.
@@ -317,7 +352,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.29.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.29.2` for controlled upgrades, or pin a reviewed commit SHA for stricter supply-chain control:
 
 ```yaml
 name: ai-saas-guard

package/action.yml

@@ -8,11 +8,11 @@ inputs:
     required: false
     default: scan
   root:
-    description: Repository path to scan.
+    description: "Repository path to scan. Usually github.workspace."
     required: false
     default: ${{ github.workspace }}
   format:
-    description: "Output format: terminal, json, sarif, or markdown."
+    description: "Output format: terminal, json, sarif, or markdown. Use markdown for PR summaries and sarif for code scanning."
     required: false
     default: terminal
   fail-on:
@@ -20,15 +20,15 @@ inputs:
     required: false
     default: none
   base:
-    description: Base ref for pr-risk.
+    description: "Base ref for pr-risk. Use origin/main with actions/checkout fetch-depth: 0."
     required: false
     default: ""
   config:
-    description: Optional ai-saas-guard JSON config path.
+    description: "Optional ai-saas-guard JSON config path, relative to the workflow workspace or root."
     required: false
     default: ""
   output:
-    description: Optional path to write output while also keeping the command exit code.
+    description: "Optional path to write output while also keeping the command exit code."
     required: false
     default: ""
 
@@ -56,7 +56,7 @@ runs:
         INPUT_CONFIG: ${{ inputs.config }}
         INPUT_OUTPUT: ${{ inputs.output }}
       run: |
-        set -o pipefail
+        set -euo pipefail
 
         case "${INPUT_COMMAND}" in
           scan|check-supabase|check-stripe|check-mcp|check-actions|pr-risk) ;;
@@ -82,6 +82,16 @@ runs:
             ;;
         esac
 
+        if [ ! -d "${INPUT_ROOT}" ]; then
+          echo "Root path does not exist or is not a directory: ${INPUT_ROOT}" >&2
+          exit 2
+        fi
+
+        if [ -n "${INPUT_CONFIG}" ] && [ ! -f "${INPUT_CONFIG}" ] && [ ! -f "${INPUT_ROOT%/}/${INPUT_CONFIG}" ]; then
+          echo "Config file not found: ${INPUT_CONFIG}" >&2
+          exit 2
+        fi
+
         args=("${INPUT_COMMAND}" "--root" "${INPUT_ROOT}")
 
         if [ "${INPUT_FORMAT}" = "json" ]; then
@@ -105,6 +115,7 @@ runs:
         fi
 
         if [ -n "${INPUT_OUTPUT}" ]; then
+          mkdir -p -- "$(dirname -- "${INPUT_OUTPUT}")"
           node "${GITHUB_ACTION_PATH}/dist/cli.js" "${args[@]}" | tee -- "${INPUT_OUTPUT}"
         else
           node "${GITHUB_ACTION_PATH}/dist/cli.js" "${args[@]}"

package/docs/README.zh-CN.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  ai-saas-guard 是面向 AI 构建的 Next.js、Supabase、Stripe、Vercel 和 MCP SaaS 的本地优先上线 gate。它会优先指出 auth、billing、data access、secrets、MCP、deploy、CI 和“假成功”路径里最值得人工 review 的改动，让你在上线前知道该先看哪里。它本地运行、只读仓库、不上传代码。
+  面向 AI 构建的 Next.js、Supabase、Stripe、Vercel、GitHub Actions 和 MCP SaaS 的本地优先上线 gate。它聚焦 auth、billing、data access、secrets、MCP 和 deploy，把仓库里最容易出事的风险路径变成一份短 review 队列，让你在上线前或合并 PR 前知道该先看哪里。它本地运行、只读仓库、不上传代码。
 </p>
 
 <p align="center">
@@ -26,9 +26,11 @@
 
 ---
 
-## 它解决什么问题
+## 邀请真实用户前先看这里
 
-AI 能很快把一个 SaaS 做到“看起来能用”。真正危险的是上线后才暴露的信任边界问题：
+AI 能很快把一个 SaaS 做到“看起来能用”：能登录、能打开 checkout、dashboard 能加载、测试也是绿的。真正危险的是信任边界代码，它决定谁有权限、谁付了钱、谁能看哪些数据，以及服务失败时会不会被悄悄伪装成成功。
+
+这些问题通常会在真实用户来了以后才变痛：
 
 - 一个用户能看到或修改另一个客户的数据
 - Stripe webhook 因为未签名、重复、漏处理失败事件而错误开通权限
@@ -41,23 +43,56 @@ AI 能很快把一个 SaaS 做到“看起来能用”。真正危险的是上
 
 `ai-saas-guard` 是面向这个时刻的本地优先、review-first 上线预检工具。它不会证明你的应用绝对安全，也不是渗透测试、认证或完整安全审计。它的目标是给 founder、独立开发者、小团队和 reviewer 一份短而有证据的清单，告诉你上线或合并 PR 前最该先看哪里。
 
+## 60 秒本地检查
+
+无需全局安装，直接扫你的应用：
+
+```bash
+npx ai-saas-guard@latest scan --root /path/to/your-saas
+```
+
+如果是 AI 生成的大 PR：
+
+```bash
+npx ai-saas-guard@latest pr-risk --root /path/to/your-saas --base origin/main --markdown
+```
+
+你会得到 rule ID、severity、文件证据、为什么重要、如何人工验证，以及具体修复方向。扫描是 deterministic、只读的，不调用 LLM。
+
+## 先试公开 demo
+
+如果你还不想先扫自己的私有仓库，可以先跑公开 fixture：
+
+```bash
+git clone https://github.com/zr9959/ai-saas-guard.git
+cd ai-saas-guard
+npx ai-saas-guard@latest scan --root examples/demo-risky-saas
+npx ai-saas-guard@latest scan --root examples/demo-safe-saas
+```
+
+risky demo 当前会故意触发 19 个 finding，覆盖 Stripe、Supabase、silent-success、Next/Vercel deploy 提示和 GitHub Actions。safe demo 在同类风险面上使用更安全的静态写法，当前返回 0 个 finding。说明见 [demo-quickstart.md](demo-quickstart.md)。
+
 ## 输出长什么样
 
 报告是给上线前或合并 AI 大 PR 前快速阅读的。更完整的可复制样例见 [docs/sample-launch-report.md](sample-launch-report.md)。
 
 ```text
 Launch Gate: review before launch
-4 findings: 1 high, 3 medium
+19 findings: 2 critical, 6 high, 7 medium, 3 low, 1 info
 
-HIGH stripe.webhook.missing-signature
+CRITICAL stripe.webhook.missing-signature
 File: app/api/stripe/webhook/route.ts
 Why: billing access can be granted from a webhook path that does not verify Stripe signatures.
 Verify: replay a webhook with an invalid signature and confirm the route rejects it.
 Fix: read the raw body, call stripe.webhooks.constructEvent, and make event handling idempotent.
 
-MEDIUM supabase.rls.tenant-predicate-missing
-File: supabase/migrations/20260524_accounts.sql
-Verify: sign in as user A and user B; confirm neither can SELECT or UPDATE the other's rows.
+HIGH silent-success.swallowed-error
+File: app/api/billing/checkout/route.ts
+Verify: force the upstream billing call to fail and confirm the route returns an error, not fake success.
+
+MEDIUM deploy.next.missing-security-headers
+File: app/api/billing/checkout/route.ts
+Verify: inspect production response headers for auth, billing, and API pages.
 ```
 
 ## 你会得到什么
@@ -84,28 +119,6 @@ Verify: sign in as user A and user B; confirm neither can SELECT or UPDATE the o
 | 工具和 CI 权限是不是过大？ | MCP side-effect 分类、本地 policy/receipt 模板、GitHub Actions 权限、concurrency、checkout depth、Action pinning |
 | reviewer 能不能看懂 AI PR？ | `pr-risk` 对 auth、billing、RLS、deploy、API、storage、测试、silent-success、缺 spec context 和大型 diff 排序 |
 
-## 当前状态
-
-这个仓库是公开 GitHub 仓库。
-
-CLI 已发布到 npm：`ai-saas-guard@0.29.0`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.29.0`。
-
-| 模块 | 状态 |
-| --- | --- |
-| 公开 GitHub 仓库 | 已可用 |
-| npm CLI | `ai-saas-guard@0.29.0` |
-| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.29.0` |
-| 输出格式 | Terminal、JSON、SARIF 和 PR markdown |
-| 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖、suppressions 和 fail threshold |
-| 隐私模型 | 本地优先、只读扫描、不调用 LLM、不上传代码 |
-| 当前版本 | `0.29.0` hosted Node checkout platform 组合入口、Clerk unsafe metadata 规则、Prisma tenant-scope 规则、Vercel cron guard 规则、sample launch report 和 Marketplace wrapper 决策 |
-| Action 标签 | `v0.29.0`、`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` 继续作为保守证据记录 |
-
 ## 快速开始
 
 无需全局安装，直接运行：
@@ -144,6 +157,28 @@ npm run build
 node dist/cli.js scan --root /path/to/your-saas
 ```
 
+## 当前状态
+
+这个仓库是公开 GitHub 仓库。
+
+CLI 已发布到 npm：`ai-saas-guard@0.29.2`。GitHub Action 支持 `v0` 浮动标签，也支持固定版本标签，例如 `v0.29.2`。
+
+| 模块 | 状态 |
+| --- | --- |
+| 公开 GitHub 仓库 | 已可用 |
+| npm CLI | `ai-saas-guard@0.29.2` |
+| GitHub Action | `zr9959/ai-saas-guard@v0` 或固定标签 `v0.29.2` |
+| 输出格式 | Terminal、JSON、SARIF 和 PR markdown |
+| 项目配置 | `.ai-saas-guard.json` 支持规则开关、severity 覆盖、suppressions 和 fail threshold |
+| 隐私模型 | 本地优先、只读扫描、不调用 LLM、不上传代码 |
+| 当前版本 | `0.29.2` 发布公开 risky/safe demo fixtures、demo quickstart、quickstart 反馈模板，并刷新首次试用 README 指引 |
+| Action 标签 | `v0.29.2`、`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` 继续作为保守证据记录 |
+
 ## 主要命令
 
 | 命令 | 用途 |

package/docs/demo-quickstart.md

@@ -0,0 +1,60 @@
+# Demo Quickstart
+
+Use these public fixtures when you want to understand `ai-saas-guard` before pointing it at a private repository.
+
+## Risky Demo
+
+```bash
+npx ai-saas-guard@latest scan --root examples/demo-risky-saas
+```
+
+The risky demo intentionally includes unsigned Stripe webhook handling, a silent-success billing fallback, broad Supabase RLS, and overpowered GitHub Actions permissions.
+
+Expected summary:
+
+```text
+19 findings: 2 critical, 6 high, 7 medium, 3 low, 1 info
+```
+
+The first findings should point at trust-boundary files such as:
+
+- `app/api/stripe/webhook/route.ts` for missing Stripe signature verification and idempotency
+- `supabase/migrations/001_accounts.sql` for broad RLS and missing tenant predicates
+- `app/api/billing/checkout/route.ts` for a silent-success billing fallback
+- `.github/workflows/ci.yml` for launch-related workflow hygiene hints
+
+For local development from this repository checkout:
+
+```bash
+npm ci
+npm run build
+node dist/cli.js scan --root examples/demo-risky-saas
+```
+
+## Safe Demo
+
+```bash
+npx ai-saas-guard@latest scan --root examples/demo-safe-saas
+```
+
+The safe demo keeps the same broad surfaces but uses safer static patterns: Stripe signature verification and idempotency hints, scoped RLS, security headers, documented env variables, request IDs, and bounded GitHub Actions permissions.
+
+Expected summary:
+
+```text
+0 findings
+```
+
+For local development from this repository checkout:
+
+```bash
+node dist/cli.js scan --root examples/demo-safe-saas
+```
+
+## What To Look For
+
+- Every finding has a rule ID, severity, file evidence, why it matters, a manual verification step, and a fix direction.
+- The risky demo is intentionally noisy enough to show the report shape.
+- The safe demo is intentionally small; it is not a complete SaaS template and does not certify a real app.
+
+Do not paste real API keys, customer data, private source code, webhook secrets, or production URLs into public issues when sharing output.

package/docs/github-action.md

@@ -2,7 +2,9 @@
 
 `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.28.1` 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.29.0` or a reviewed commit SHA when reproducibility is more important than automatic minor updates.
+
+The Action runs the same local scanner inside the GitHub-hosted runner. It reads the checked-out repository, does not call an LLM, and does not upload source code. For `pr-risk`, always use `actions/checkout` with `fetch-depth: 0` so the base branch comparison is available.
 
 ## PR Summary
 

package/docs/npm-publishing.md

@@ -5,11 +5,11 @@
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current published version: `0.29.0`
+- Current published version: `0.29.2`
 - 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.29.0`
+- GitHub Release: `v0.29.2`
 - 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.29.0`.
+1. Create and review a release tag such as `v0.29.2`.
 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/examples/demo-risky-saas/.github/workflows/ci.yml

@@ -0,0 +1,13 @@
+name: Risky demo CI
+
+on:
+  pull_request:
+
+permissions: write-all
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6.0.2
+      - run: npm test

package/examples/demo-risky-saas/README.md

@@ -0,0 +1,25 @@
+# Risky Demo SaaS
+
+This is a tiny public fixture that intentionally contains common AI-built SaaS launch risks.
+
+Run from the repository root:
+
+```bash
+node dist/cli.js scan --root examples/demo-risky-saas
+```
+
+Or with the published package:
+
+```bash
+npx ai-saas-guard@latest scan --root examples/demo-risky-saas
+```
+
+Expected themes:
+
+- unsigned Stripe webhook handling
+- silent-success billing fallback
+- broad Supabase RLS policy
+- over-broad GitHub Actions permissions
+- stale PR workflow risk
+
+This fixture uses inert placeholder code only. It does not contain real secrets, customer data, or production URLs.

package/examples/demo-risky-saas/app/api/billing/checkout/route.ts

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

package/examples/demo-risky-saas/app/api/stripe/webhook/route.ts

@@ -0,0 +1,14 @@
+export async function POST(req: Request) {
+  const event = await req.json();
+
+  if (event.type === "checkout.session.completed") {
+    await grantAccess(event.data.object.customer);
+    return Response.json({ success: true });
+  }
+
+  return Response.json({ ok: true });
+}
+
+async function grantAccess(customerId: string) {
+  console.log("granting access", customerId);
+}

package/examples/demo-risky-saas/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "ai-saas-guard-demo-risky-saas",
+  "private": true,
+  "type": "module"
+}

package/examples/demo-risky-saas/supabase/migrations/001_accounts.sql

@@ -0,0 +1,14 @@
+create table public.accounts (
+  id uuid primary key,
+  tenant_id uuid not null,
+  user_id uuid not null,
+  plan text not null
+);
+
+alter table public.accounts enable row level security;
+
+create policy "public read accounts"
+on public.accounts
+for select
+to public
+using (true);

package/examples/demo-safe-saas/.env.example

@@ -0,0 +1,3 @@
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_KEY=
+NEXT_PUBLIC_SUPABASE_URL=

package/examples/demo-safe-saas/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: Safe demo CI
+
+on:
+  pull_request:
+    paths-ignore:
+      - "docs/**"
+      - "*.md"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
+        with:
+          node-version: 20
+      - run: test -n "${STRIPE_SECRET_KEY:-}"
+      - run: npm ci
+      - run: npx ai-saas-guard pr-risk --base origin/main
+      - run: npm test

package/examples/demo-safe-saas/README.md

@@ -0,0 +1,17 @@
+# Safe Demo SaaS
+
+This is a tiny public fixture with safer launch-readiness patterns for the same broad surfaces as the risky demo.
+
+Run from the repository root:
+
+```bash
+node dist/cli.js scan --root examples/demo-safe-saas
+```
+
+Expected result:
+
+```text
+No heuristic launch-readiness risks found by this command.
+```
+
+The fixture is intentionally small. It is not a complete SaaS template and does not prove a real app is secure.

package/examples/demo-safe-saas/app/api/stripe/webhook/route.ts

@@ -0,0 +1,89 @@
+import Stripe from "stripe";
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+
+export async function POST(req: Request) {
+  const requestId = req.headers.get("x-request-id") ?? crypto.randomUUID();
+  await rateLimit(req);
+  const body = await req.text();
+  const signature = req.headers.get("stripe-signature");
+  const event = stripe.webhooks.constructEvent(
+    body,
+    signature!,
+    process.env.STRIPE_WEBHOOK_KEY!
+  );
+  const tenant_id = await resolveTenantForStripeCustomer(event.data.object.customer);
+
+  console.info("stripe webhook received", { requestId, eventId: event.id, tenant_id });
+
+  if (await hasProcessedEvent(event.id)) {
+    return new Response("ok");
+  }
+
+  switch (event.type) {
+    case "checkout.session.completed":
+      await syncEntitlement(event.data.object.customer);
+      break;
+    case "invoice.payment_failed":
+      await markPastDue(event.data.object.customer);
+      break;
+    case "invoice.payment_action_required":
+      await requestPaymentAction(event.data.object.customer);
+      break;
+    case "customer.subscription.updated":
+      await syncSubscription(event.data.object);
+      break;
+    case "customer.subscription.deleted":
+      await revokeEntitlement(event.data.object.customer);
+      break;
+    case "charge.refunded":
+      await reviewRefund(event.data.object.customer);
+      break;
+    default:
+      break;
+  }
+
+  await recordProcessedEvent(event.id);
+  return new Response("ok");
+}
+
+async function hasProcessedEvent(eventId: string) {
+  return eventId.length === 0;
+}
+
+async function rateLimit(req: Request) {
+  console.log(req.headers.get("x-forwarded-for") ?? "local");
+}
+
+async function resolveTenantForStripeCustomer(customerId: unknown) {
+  console.log(customerId);
+  return String(customerId);
+}
+
+async function recordProcessedEvent(eventId: string) {
+  console.log(eventId);
+}
+
+async function syncEntitlement(customerId: string) {
+  console.log(customerId);
+}
+
+async function markPastDue(customerId: string) {
+  console.log(customerId);
+}
+
+async function requestPaymentAction(customerId: string) {
+  console.log(customerId);
+}
+
+async function syncSubscription(subscription: unknown) {
+  console.log(subscription);
+}
+
+async function revokeEntitlement(customerId: string) {
+  console.log(customerId);
+}
+
+async function reviewRefund(customerId: string) {
+  console.log(customerId);
+}

package/examples/demo-safe-saas/app/api/tenant/[tenantId]/route.ts

@@ -0,0 +1,18 @@
+export async function POST(request: Request) {
+  const requestId = request.headers.get("x-request-id") ?? crypto.randomUUID();
+  await rateLimit(request);
+  const payload = await request.json();
+
+  console.info("tenant update", { requestId, tenantId: payload.tenantId });
+  await updateTenantBilling(payload.tenantId, process.env.STRIPE_SECRET_KEY);
+
+  return Response.json({ ok: true, requestId });
+}
+
+async function updateTenantBilling(tenantId: string, stripeKey?: string) {
+  console.log(tenantId, Boolean(stripeKey));
+}
+
+async function rateLimit(request: Request) {
+  console.log(request.headers.get("x-forwarded-for") ?? "local");
+}

package/examples/demo-safe-saas/app/dashboard/[tenantId]/page.tsx

@@ -0,0 +1,11 @@
+import Image from "next/image";
+import Link from "next/link";
+
+export default function TenantDashboard() {
+  return (
+    <>
+      <Image src="https://cdn.example.com/logo.png" width={240} height={120} alt="" />
+      <Link prefetch={false} href="/dashboard/settings">Open settings</Link>
+    </>
+  );
+}

package/examples/demo-safe-saas/next.config.js

@@ -0,0 +1,22 @@
+module.exports = {
+  async headers() {
+    return [
+      {
+        source: "/(.*)",
+        headers: [
+          { key: "X-Frame-Options", value: "DENY" },
+          { key: "X-Content-Type-Options", value: "nosniff" },
+          { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" }
+        ]
+      }
+    ];
+  },
+  images: {
+    remotePatterns: [
+      {
+        protocol: "https",
+        hostname: "cdn.example.com"
+      }
+    ]
+  }
+};

package/examples/demo-safe-saas/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "ai-saas-guard-demo-safe-saas",
+  "private": true,
+  "type": "module"
+}

package/examples/demo-safe-saas/supabase/migrations/001_projects.sql

@@ -0,0 +1,18 @@
+create table public.projects (
+  id uuid primary key,
+  user_id uuid not null,
+  name text
+);
+
+alter table public.projects enable row level security;
+
+create policy "users read own projects"
+on public.projects
+for select
+using (auth.uid() = user_id);
+
+create policy "users write own projects"
+on public.projects
+for all
+using (auth.uid() = user_id)
+with check (auth.uid() = user_id);

package/package.json

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