ai-saas-guard 0.1.1 → 0.1.3

package/README.md

@@ -10,6 +10,7 @@
 
 <p align="center">
   <a href="https://github.com/zr9959/ai-saas-guard/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/zr9959/ai-saas-guard/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.npmjs.com/package/ai-saas-guard"><img alt="npm" src="https://img.shields.io/npm/v/ai-saas-guard.svg"></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
   <a href="package.json"><img alt="Node.js >=20" src="https://img.shields.io/badge/node-%3E%3D20-339933.svg"></a>
   <a href="docs/release-quality-knowledge-base.md"><img alt="Release gate documented" src="https://img.shields.io/badge/release%20gate-documented-0f766e.svg"></a>
@@ -40,18 +41,45 @@ It is intentionally evidence-first. Findings include a rule ID, severity, file e
 
 This repository is public on GitHub.
 
-The first GitHub release and Action tag are `v0.1.0`; the npm-ready patch release is `v0.1.1`. The npm package is not published yet, so run the CLI from source for now. If you need stricter supply-chain pinning in CI, pin the GitHub Action to a reviewed commit SHA instead of a mutable tag.
+The CLI is published on npm as `ai-saas-guard`, and the GitHub Action is available through versioned release tags. If you need stricter supply-chain pinning in CI, pin the GitHub Action to a reviewed commit SHA instead of a mutable tag.
 
 | Area | Status |
 | --- | --- |
 | Public GitHub repository | Available |
-| Local CLI from source | Available |
+| npm CLI | Published as `ai-saas-guard` |
+| Local CLI from source | Available for development |
 | JSON and SARIF output | Available |
 | Composite GitHub Action | Available |
-| Versioned Action tags | `v0.1.1` |
-| npm package | Not published yet |
+| Versioned Action tags | `v0.1.3` |
+| npm package | `ai-saas-guard@0.1.3` |
+| npm publishing | Trusted Publisher/OIDC, no long-lived publish token |
 
-## Quick Start From Source
+## Quick Start
+
+Run the published CLI without installing it globally:
+
+```bash
+npx ai-saas-guard@latest scan --root /path/to/your-saas
+```
+
+Run focused checks:
+
+```bash
+npx ai-saas-guard@latest pr-risk --root /path/to/your-saas --base origin/main
+npx ai-saas-guard@latest check-supabase --root /path/to/your-saas
+npx ai-saas-guard@latest check-stripe --root /path/to/your-saas
+npx ai-saas-guard@latest check-mcp --root /path/to/your-saas
+```
+
+Machine-readable output:
+
+```bash
+npx ai-saas-guard@latest scan --root /path/to/your-saas --json
+npx ai-saas-guard@latest scan --root /path/to/your-saas --sarif > ai-saas-guard.sarif
+npx ai-saas-guard@latest scan --root /path/to/your-saas --fail-on high
+```
+
+For local development:
 
 ```bash
 git clone https://github.com/zr9959/ai-saas-guard.git
@@ -70,14 +98,6 @@ node dist/cli.js check-stripe --root /path/to/your-saas
 node dist/cli.js check-mcp --root /path/to/your-saas
 ```
 
-Machine-readable output:
-
-```bash
-node dist/cli.js scan --root /path/to/your-saas --json
-node dist/cli.js scan --root /path/to/your-saas --sarif > ai-saas-guard.sarif
-node dist/cli.js scan --root /path/to/your-saas --fail-on high
-```
-
 ## Example Finding
 
 Terminal output is designed to be useful to a reviewer, not just a scanner dashboard.
@@ -127,11 +147,14 @@ AI-generated PRs often combine unrelated work:
 - review-first checklist
 - suggested PR split
 - required tests or manual verification
+- explicit git-diff diagnostics when a base ref or shallow checkout prevents PR classification
 
 ```bash
 node dist/cli.js pr-risk --root /path/to/your-saas --base origin/main --json
 ```
 
+If `--base` cannot be resolved, `pr-risk` emits `pr-risk.diff-unavailable` instead of silently reporting a clean or empty diff. In GitHub Actions, use `actions/checkout` with `fetch-depth: 0` when you need merge-base comparison against `origin/main`.
+
 ## Commands
 
 | Command | Purpose |
@@ -162,7 +185,7 @@ jobs:
       - uses: actions/checkout@v6.0.2
         with:
           fetch-depth: 0
-      - uses: zr9959/ai-saas-guard@v0.1.1
+      - uses: zr9959/ai-saas-guard@v0.1.3
         with:
           command: pr-risk
           root: ${{ github.workspace }}
@@ -173,7 +196,7 @@ jobs:
 For SARIF upload:
 
 ```yaml
-      - uses: zr9959/ai-saas-guard@v0.1.1
+      - uses: zr9959/ai-saas-guard@v0.1.3
         with:
           command: scan
           format: sarif
@@ -183,7 +206,7 @@ For SARIF upload:
           sarif_file: ai-saas-guard.sarif
 ```
 
-For maximum reproducibility, replace `v0.1.1` with the full commit SHA from the release notes.
+For maximum reproducibility, replace `v0.1.3` with the full commit SHA from the release notes.
 
 ## Ignore File
 
@@ -257,7 +280,6 @@ Open-source core:
 
 Near-term priorities:
 
-- npm trusted publishing and provenance
 - PR comment summary mode
 - configurable severity and rule toggles
 - expanded Supabase RLS fixtures
@@ -282,4 +304,4 @@ Please read [SECURITY.md](SECURITY.md) before reporting vulnerabilities. Do not
 
 ## npm Publishing
 
-The package name is prepared but not published yet. See [docs/npm-publishing.md](docs/npm-publishing.md) for the GitHub Actions provenance workflow and the required `NPM_TOKEN` or trusted-publisher setup.
+The package is published as [`ai-saas-guard`](https://www.npmjs.com/package/ai-saas-guard). See [docs/npm-publishing.md](docs/npm-publishing.md) for the GitHub Actions Trusted Publisher workflow, provenance notes, and first-publish token history.

package/dist/rules/catalog.js

@@ -195,6 +195,13 @@ export const RULE_CATALOG = {
         why: "AI-generated PRs often bury trust-boundary changes inside larger diffs.",
         stability: "default"
     },
+    "pr-risk.diff-unavailable": {
+        ruleId: "pr-risk.diff-unavailable",
+        severity: "info",
+        title: "Git diff could not be read",
+        why: "PR classification can be misleading when the requested base ref or Git history is unavailable.",
+        stability: "default"
+    },
     "pr-risk.no-diff": {
         ruleId: "pr-risk.no-diff",
         severity: "info",

package/dist/scanners/gitDiff.js

@@ -14,10 +14,13 @@ const categoryWeights = {
     "large AI-generated/refactor-like diff": 18
 };
 export async function classifyPrRisk(options) {
-    const diffText = options.diffText ?? (await readGitDiff(options.rootDir, options.base));
+    const diffResult = options.diffText === undefined
+        ? await readGitDiff(options.rootDir, options.base)
+        : { diffText: options.diffText, diagnostics: [] };
+    const { diffText } = diffResult;
     const files = parseDiffFiles(diffText);
     const categories = new Set();
-    const findings = [];
+    const findings = [...diffResult.diagnostics];
     for (const file of files) {
         for (const category of file.categories) {
             categories.add(category);
@@ -44,7 +47,7 @@ export async function classifyPrRisk(options) {
             suggestedFix: "Split unrelated UI/refactor work away from trust-boundary changes and add focused tests before merge."
         }));
     }
-    if (diffText.trim().length === 0) {
+    if (diffText.trim().length === 0 && diffResult.diagnostics.length === 0) {
         findings.push(finding({
             ruleId: "pr-risk.no-diff",
             title: "No git diff found",
@@ -68,13 +71,17 @@ async function readGitDiff(rootDir, base) {
     if (base) {
         try {
             const { stdout } = await execFileAsync("git", ["diff", `${base}...HEAD`], { cwd: rootDir, maxBuffer: 20 * 1024 * 1024 });
-            return stdout;
+            return { diffText: stdout, diagnostics: [] };
         }
-        catch {
-            return "";
+        catch (error) {
+            return {
+                diffText: "",
+                diagnostics: [buildGitDiffFailureFinding(rootDir, ["git", "diff", `${base}...HEAD`], error, base)]
+            };
         }
     }
     const parts = [];
+    const failures = [];
     for (const args of [
         ["diff", "--cached"],
         ["diff"]
@@ -83,11 +90,62 @@ async function readGitDiff(rootDir, base) {
             const { stdout } = await execFileAsync("git", args, { cwd: rootDir, maxBuffer: 20 * 1024 * 1024 });
             parts.push(stdout);
         }
-        catch {
-            continue;
+        catch (error) {
+            failures.push({ args: ["git", ...args], error });
         }
     }
-    return parts.join("\n");
+    if (parts.length === 0 && failures.length > 0) {
+        return {
+            diffText: "",
+            diagnostics: [buildGitDiffFailureFinding(rootDir, failures[0].args, failures[0].error)]
+        };
+    }
+    return { diffText: parts.join("\n"), diagnostics: [] };
+}
+function buildGitDiffFailureFinding(rootDir, command, error, base) {
+    const errorText = redactRootPath(getGitErrorText(error), rootDir);
+    const lowerError = errorText.toLowerCase();
+    let suggestedVerification = "Run `git status` and confirm the target path is inside a Git repository.";
+    let suggestedFix = "Run `pr-risk` from a Git checkout, or pass explicit diff text through the API.";
+    if (base) {
+        suggestedVerification = `Run \`${buildFetchCommand(base)}\`, then \`git rev-parse --verify ${base}\` to confirm the base ref exists locally.`;
+        suggestedFix = "Fetch the branch or pass an existing local base ref, for example `--base origin/main`.";
+    }
+    if (base && (lowerError.includes("no merge base") || lowerError.includes("shallow"))) {
+        suggestedVerification = "Run `git rev-parse --is-shallow-repository` and confirm CI checks out full history before `pr-risk`.";
+        suggestedFix = "Use `fetch-depth: 0` in `actions/checkout`, or run `git fetch --unshallow` before invoking `pr-risk`.";
+    }
+    return finding({
+        ruleId: "pr-risk.diff-unavailable",
+        title: base ? `Could not read git diff for base ${base}` : "Could not read git diff",
+        severity: "info",
+        evidence: [
+            {
+                file: ".",
+                match: command.join(" "),
+                snippet: errorText.slice(0, 500)
+            }
+        ],
+        why: "PR risk classification needs a readable git diff, but the git command failed for the target repository.",
+        suggestedVerification,
+        suggestedFix
+    });
+}
+function buildFetchCommand(base) {
+    const remoteRef = /^([^/\s]+)\/(.+)$/.exec(base);
+    if (remoteRef)
+        return `git fetch ${remoteRef[1]} ${remoteRef[2]}`;
+    return `git fetch origin ${base}`;
+}
+function redactRootPath(text, rootDir) {
+    return rootDir ? text.replaceAll(rootDir, ".") : text;
+}
+function getGitErrorText(error) {
+    const candidate = error;
+    return [candidate.stderr, candidate.stdout, candidate.message]
+        .filter((value) => Boolean(value?.trim()))
+        .join("\n")
+        .trim() || "git diff exited with a non-zero status.";
 }
 function parseDiffFiles(diffText) {
     const files = [];

package/docs/npm-publishing.md

@@ -1,31 +1,29 @@
 # npm Publishing
 
-`ai-saas-guard` is prepared for npm publication, but the package is not published yet.
+`ai-saas-guard` is published on npm and should be released only from reviewed GitHub tags.
 
 ## Current State
 
 - Package name: `ai-saas-guard`
-- Current version: `0.1.1`
-- npm registry state: not published at the time of this document update
-- GitHub Release: `v0.1.0`
+- Current version: `0.1.3`
+- npm registry state: published at <https://www.npmjs.com/package/ai-saas-guard>
+- First npm-published version: `0.1.1`
+- GitHub Release: `v0.1.3`
 - 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
 
 ## Preferred Path
 
-Use GitHub Actions with npm provenance:
+Use GitHub Actions with npm Trusted Publisher/OIDC:
 
-1. Create an npm automation token with publish rights for this package.
-2. Add it to this GitHub repository as `NPM_TOKEN`.
-3. Run the `Publish npm` workflow manually with `ref` set to `v0.1.1`.
-4. After the first publish succeeds, configure npm Trusted Publisher for future releases:
-   - Provider: GitHub Actions
-   - Organization or user: `zr9959`
-   - Repository: `ai-saas-guard`
-   - Workflow filename: `npm-publish.yml`
-   - Allowed action: `npm publish`
-5. Once trusted publishing is verified, remove or rotate any long-lived npm publish token.
+1. Create and review a release tag such as `v0.1.3`.
+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.
+5. Keep npm package publishing access set to require 2FA and disallow traditional tokens. Trusted publishers continue to work because they use OIDC instead of npm auth tokens.
 
-The workflow sets `id-token: write` and runs `npm publish --provenance --access public`, so token-based first publish can include provenance and future trusted-publisher publishes can use OIDC.
+The first npm publish used a temporary granular access token because npm requires a 2FA-bypass token until trusted publishing is configured. That temporary automation token and the GitHub `NPM_TOKEN` secret were removed after the Trusted Publisher migration.
 
 ## Release Gate
 

package/docs/project-handoff.md

@@ -45,9 +45,11 @@ Implemented surfaces:
 - MCP config side-effect and secret-bearing risk inventory
 - Next/Vercel deploy and runtime footguns
 - PR diff risk triage for auth, billing, RLS, env, tests removed, and large mixed diffs
+- PR diff diagnostics when a base ref or shallow checkout prevents comparison
 - JSON output
 - SARIF output
 - composite GitHub Action wrapper
+- npm publishing through GitHub Actions Trusted Publisher/OIDC
 
 Existing commands:
 
@@ -111,6 +113,14 @@ CI:
 - Uses `permissions: contents: read`
 - Latest verified run after setup succeeded
 
+Publishing:
+
+- npm package: `ai-saas-guard`
+- Current release line: `v0.1.3`
+- 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.
+
 ## Repository Boundaries
 
 Allowed in this public repository:
@@ -133,14 +143,13 @@ Not allowed:
 
 Recommended order:
 
-1. Prepare npm publishing plan with trusted publishing/provenance.
-2. Add GitHub Action release packaging and example workflow.
-3. Add PR comment summary mode.
-4. Add configurable severity and rule toggles.
-5. Expand Supabase RLS fixtures and ownership patterns.
-6. Write Stripe webhook replay cookbook.
-7. Add SARIF upload workflow example.
-8. Improve false-positive suppression and rule stability labels.
+1. Add PR comment summary mode.
+2. Add configurable severity and rule toggles.
+3. Expand Supabase RLS fixtures and ownership patterns.
+4. Write Stripe webhook replay cookbook.
+5. Add SARIF upload workflow example.
+6. Improve false-positive suppression and rule stability labels.
+7. Add a GitHub App design note for the potential hosted layer.
 
 For every feature, keep the scanner evidence-first:
 

package/docs/rules.md

@@ -61,6 +61,7 @@ Rule metadata is centralized in `src/rules/catalog.ts` and covered by tests so S
 | Rule ID | Severity | Why it exists |
 | --- | --- | --- |
 | `pr-risk.sensitive-surface` | medium/high | Highlights files reviewers should inspect before cosmetic or refactor files. |
+| `pr-risk.diff-unavailable` | info | Explains when the requested base ref or Git history prevents PR diff classification. |
 | `pr-risk.no-diff` | info | Explains that PR classification needs a diff. |
 
 ## Adding Rules

package/package.json

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