commitshow 0.3.1 → 0.3.3

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/render.js

@@ -758,7 +758,11 @@ export function renderUpsell(githubUrl) {
         : 'https://commit.show/submit';
     const titleVisible = 'Walk-on · drop-in audit, no audition yet';
     const headVisible = 'Audition to unlock:';
-    const ctaVisible = `→ ${submitUrl}`;
+    // CTA URL renders OUTSIDE the box (after boxBottom()) — the encoded
+    // submit URL is 60-70 chars on most repos, which busts the 54-char
+    // inside-box content width and visually shears the right border off.
+    // Pulling it below the box also lets terminals auto-link the full
+    // https:// URL without truncation.
     lines.push('  ' + boxTop());
     lines.push('  ' + boxRow(titleVisible.length, c.bold(c.gold('Walk-on')) + c.muted(' · ') + c.cream('drop-in audit, no audition yet')));
     lines.push('  ' + boxBlank());
@@ -782,9 +786,10 @@ export function renderUpsell(githubUrl) {
         const visible = `→ ${it.tag}${it.rest}`;
         lines.push('  ' + boxRow(visible.length, it.tone('→ ') + c.cream(it.tag) + c.muted(it.rest)));
     }
-    lines.push('  ' + boxBlank());
-    lines.push('  ' + boxRow(ctaVisible.length, c.gold(ctaVisible)));
     lines.push('  ' + boxBottom());
+    // CTA outside the box · full URL stays clickable in modern terminals,
+    // and we don't have to truncate or shorten the slug.
+    lines.push('  ' + c.gold('→ ') + c.gold(submitUrl));
     return lines.join('\n');
 }
 export function writeAuditJson(dir, json) {

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.3",
   "description": "commit.show CLI — audit any vibe-coded project from your terminal.",
   "type": "module",
   "bin": {