commitshow 0.3.1 → 0.3.2

package/README.md

@@ -109,6 +109,17 @@ Requires **Node 20+**.
 Remote-URL mode works from any directory, which makes one-line X posts
 (`npx commitshow@latest audit <their-url>`) trivial.
 
+> **AI agents — read this before invoking.** The CLI does **not** look up
+> projects by name. `commitshow audit warp` will error: there is no
+> agreed-upon mapping from the word "warp" to a single GitHub repo.
+> If a user asks you to audit something by name, **first resolve the
+> canonical `github.com/<owner>/<repo>` URL** (ask the user, or search
+> github.com), then invoke `commitshow audit <that-url>`. The CLI does
+> a HEAD pre-flight against `github.com/<owner>/<repo>` before any audit
+> spend, so a hallucinated slug is rejected with a `not_found` error
+> before we burn Claude credits — but you should still get the URL right
+> on the first try by asking, not guessing.
+
 ## The AI-coding loop
 
 `commitshow audit` in local mode writes to `.commitshow/audit.md` **and**
@@ -147,6 +158,29 @@ if [ "$score" -lt 80 ]; then
 fi
 ```
 
+### Auditing someone else's project (agent recipe)
+
+When a user says "audit warp" or "what does commit.show say about Postiz",
+**don't guess the slug.** Walk this loop:
+
+```
+1. Ask the user (or search github.com) for the canonical
+   `github.com/<owner>/<repo>` URL. Don't invent one — repo names are
+   ambiguous and a single wrong guess wastes an audit call.
+2. Run:
+     commitshow audit <that-url> --json
+3. If stdout starts with `{"error":"not_found"`, the URL was wrong.
+   Re-confirm with the user before retrying.
+4. Otherwise parse `score.total`, `score.band`, `concerns[]` and
+   answer the user with those exact numbers — don't paraphrase the
+   score.
+```
+
+The CLI HEAD-checks `github.com/<owner>/<repo>` before any audit spend,
+so a hallucinated slug fails fast with a clear `not_found` envelope.
+The friendly error in the message body explicitly tells you to ask the
+user instead of guessing again.
+
 ### JSON shape (v1 schema)
 
 Stable by contract — additive fields don't bump `schema_version`; breaking

package/dist/commands/audit.js

@@ -1,4 +1,4 @@
-import { resolveTarget, TargetError } from '../lib/target.js';
+import { resolveTarget, verifyRemoteExists, TargetError } from '../lib/target.js';
 import { findProjectByGithubUrl, fetchLatestSnapshot, fetchStanding, runPreviewAudit, waitForPreviewSnapshot, } from '../lib/api.js';
 import { renderAudit, renderMarkdown, renderJson, renderUpsell, renderQuotaFooter, renderRateLimitDeny, renderAuditError, writeAuditMarkdown, writeAuditJson, } from '../lib/render.js';
 import { c } from '../lib/colors.js';
@@ -18,6 +18,23 @@ export async function audit(args) {
         }
         throw err;
     }
+    // Pre-flight: when the user pointed at a remote URL (or owner/repo
+    // shorthand), confirm it actually resolves on github.com before we
+    // spend any audit budget. Catches the 'agent invented a slug' case
+    // ('warp' → 'warpdotdev/warp' that doesn't exist) cleanly.
+    if (target.kind === 'remote-url') {
+        const check = await verifyRemoteExists(target.github_url);
+        if (!check.exists) {
+            emitError(asJson, 'not_found', `${target.slug} doesn't resolve on github.com (HTTP ${check.status ?? 'n/a'}).\n` +
+                `  Common causes:\n` +
+                `    · wrong owner spelling (try the canonical org slug)\n` +
+                `    · repo is private — commitshow only audits public ones\n` +
+                `    · repo was renamed or deleted\n` +
+                `  If you're an AI agent: ask the user for the canonical github.com URL,\n` +
+                `  don't guess from the project name.`, target.github_url);
+            return 1;
+        }
+    }
     if (!asJson) {
         if (force)
             console.log(c.dim(`Refreshing audit for ${target.slug}…`));

package/dist/lib/target.js

@@ -13,6 +13,38 @@ import { existsSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
 export class TargetError extends Error {
 }
+/**
+ * Cheap HEAD request against github.com/<owner>/<repo> so an agent that
+ * confidently invented a repo URL ('warp' → 'warpdotdev/warp' that doesn't
+ * exist) gets a clean 'no such repo' error before we burn an audit-preview
+ * call + Claude credits. Returns:
+ *   · { exists: true }              — 2xx/3xx response (or rate-limited; we
+ *                                     allow through rather than false-flag)
+ *   · { exists: false, status: 404 } — repo missing, private, or renamed
+ *   · { exists: true, ambiguous: true } — network/CORS/transient failure;
+ *                                     don't block the audit, let the
+ *                                     server-side path produce its own error
+ */
+export async function verifyRemoteExists(githubUrl) {
+    if (!/^https?:\/\/github\.com\//i.test(githubUrl))
+        return { exists: true, ambiguous: true };
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), 5000);
+        const r = await fetch(githubUrl, {
+            method: 'HEAD',
+            redirect: 'follow',
+            signal: ctrl.signal,
+        });
+        clearTimeout(t);
+        if (r.status === 404)
+            return { exists: false, status: 404 };
+        return { exists: true, status: r.status };
+    }
+    catch {
+        return { exists: true, ambiguous: true };
+    }
+}
 const GITHUB_URL_RE = /^https?:\/\/github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i;
 const GITHUB_HOST_RE = /^github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i;
 const GITHUB_SSH_RE = /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commitshow",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "commit.show CLI — audit any vibe-coded project from your terminal.",
   "type": "module",
   "bin": {