@nebulacomponents/citable 0.1.0 → 1.2.0

package/schemas/finding.schema.json

@@ -3,54 +3,184 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Finding",
   "type": "object",
-  "required": ["finding_id", "detector_id", "run_id", "timestamp", "discipline", "subject", "observation", "classification", "remediation", "verification", "status"],
+  "required": [
+    "finding_id",
+    "detector_id",
+    "run_id",
+    "timestamp",
+    "discipline",
+    "subject",
+    "observation",
+    "classification",
+    "remediation",
+    "verification",
+    "status"
+  ],
   "properties": {
-    "finding_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },
-    "detector_id": { "$ref": "citable://schemas/common.defs.json#/definitions/id" },
-    "run_id": { "type": "string" },
-    "timestamp": { "type": "string" },
-    "discipline": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": ["seo", "aeo", "geo"] } },
+    "finding_id": {
+      "$ref": "citable://schemas/common.defs.json#/definitions/id"
+    },
+    "detector_id": {
+      "$ref": "citable://schemas/common.defs.json#/definitions/id"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    },
+    "discipline": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string",
+        "enum": [
+          "seo",
+          "aeo",
+          "geo",
+          "agent-readiness"
+        ]
+      }
+    },
     "subject": {
       "type": "object",
-      "required": ["type", "identifier"],
+      "required": [
+        "type",
+        "identifier"
+      ],
       "properties": {
-        "type": { "type": "string", "enum": ["url", "page", "source_file", "registry_entry", "site", "schema_block", "link", "crawler", "claim", "evidence", "entity", "prompt", "query", "experiment", "run"] },
-        "identifier": { "type": "string" },
-        "url": { "type": "string" },
-        "source_file": { "type": "string" },
-        "source_location": { "type": "string" },
-        "rendered_selector": { "type": "string" }
+        "type": {
+          "type": "string",
+          "enum": [
+            "url",
+            "page",
+            "source_file",
+            "registry_entry",
+            "site",
+            "schema_block",
+            "link",
+            "crawler",
+            "claim",
+            "evidence",
+            "entity",
+            "prompt",
+            "query",
+            "experiment",
+            "run",
+            "file"
+          ]
+        },
+        "identifier": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        },
+        "source_file": {
+          "type": "string"
+        },
+        "source_location": {
+          "type": "string"
+        },
+        "rendered_selector": {
+          "type": "string"
+        }
       }
     },
     "observation": {
       "type": "object",
-      "required": ["summary", "evidence"],
+      "required": [
+        "summary",
+        "evidence"
+      ],
       "properties": {
-        "summary": { "type": "string", "minLength": 1 },
-        "evidence": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "evidence": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
         "captured_value": {},
         "expected_value": {}
       }
     },
     "classification": {
       "type": "object",
-      "required": ["finding_type", "severity", "confidence", "deterministic", "impact"],
+      "required": [
+        "finding_type",
+        "severity",
+        "confidence",
+        "deterministic",
+        "impact"
+      ],
       "properties": {
-        "finding_type": { "type": "string", "enum": ["deterministic_observation", "evidence_backed_semantic_finding", "probabilistic_inference", "strategic_hypothesis", "experiment_result", "untestable_condition"] },
-        "severity": { "type": "string", "enum": ["critical", "high", "medium", "low", "informational", "experimental"] },
-        "confidence": { "type": "string", "enum": ["confirmed", "high", "medium", "low", "unknown"] },
-        "deterministic": { "type": "boolean" },
+        "finding_type": {
+          "type": "string",
+          "enum": [
+            "deterministic_observation",
+            "evidence_backed_semantic_finding",
+            "probabilistic_inference",
+            "strategic_hypothesis",
+            "experiment_result",
+            "untestable_condition"
+          ]
+        },
+        "severity": {
+          "type": "string",
+          "enum": [
+            "critical",
+            "high",
+            "medium",
+            "low",
+            "informational",
+            "experimental"
+          ]
+        },
+        "confidence": {
+          "type": "string",
+          "enum": [
+            "confirmed",
+            "high",
+            "medium",
+            "low",
+            "unknown"
+          ]
+        },
+        "deterministic": {
+          "type": "boolean"
+        },
         "impact": {
           "type": "object",
           "properties": {
-            "retrieval": { "$ref": "#/definitions/impactLevel" },
-            "ranking": { "$ref": "#/definitions/impactLevel" },
-            "citation": { "$ref": "#/definitions/impactLevel" },
-            "representation": { "$ref": "#/definitions/impactLevel" },
-            "legal": { "$ref": "#/definitions/impactLevel" },
-            "reputational": { "$ref": "#/definitions/impactLevel" },
-            "conversion": { "$ref": "#/definitions/impactLevel" },
-            "maintainability": { "$ref": "#/definitions/impactLevel" }
+            "retrieval": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "ranking": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "citation": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "representation": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "legal": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "reputational": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "conversion": {
+              "$ref": "#/definitions/impactLevel"
+            },
+            "maintainability": {
+              "$ref": "#/definitions/impactLevel"
+            }
           }
         }
       }
@@ -58,44 +188,117 @@
     "reasoning": {
       "type": "object",
       "properties": {
-        "applicable_requirement": { "type": "string" },
-        "explanation": { "type": "string" },
-        "assumptions": { "type": "array", "items": { "type": "string" } },
-        "limitations": { "type": "array", "items": { "type": "string" } }
+        "applicable_requirement": {
+          "type": "string"
+        },
+        "explanation": {
+          "type": "string"
+        },
+        "assumptions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "limitations": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
       }
     },
     "remediation": {
       "type": "object",
-      "required": ["preferred"],
+      "required": [
+        "preferred"
+      ],
       "properties": {
-        "preferred": { "type": "string" },
-        "alternatives": { "type": "array", "items": { "type": "string" } },
-        "unsafe_shortcuts": { "type": "array", "items": { "type": "string" } },
-        "owner": { "type": ["string", "null"] },
-        "review_required": { "type": "boolean" }
+        "preferred": {
+          "type": "string"
+        },
+        "alternatives": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "unsafe_shortcuts": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "owner": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "review_required": {
+          "type": "boolean"
+        }
       }
     },
     "verification": {
       "type": "object",
-      "required": ["method"],
+      "required": [
+        "method"
+      ],
       "properties": {
-        "method": { "type": "string" },
-        "expected_result": { "type": "string" },
-        "detector_to_rerun": { "type": "string" }
+        "method": {
+          "type": "string"
+        },
+        "expected_result": {
+          "type": "string"
+        },
+        "detector_to_rerun": {
+          "type": "string"
+        }
       }
     },
     "status": {
       "type": "object",
-      "required": ["state"],
+      "required": [
+        "state"
+      ],
       "properties": {
-        "state": { "type": "string", "enum": ["open", "acknowledged", "in_remediation", "resolved", "accepted_risk", "false_positive"] },
-        "first_seen": { "type": "string" },
-        "last_seen": { "type": "string" },
-        "resolved_at": { "type": ["string", "null"] }
+        "state": {
+          "type": "string",
+          "enum": [
+            "open",
+            "acknowledged",
+            "in_remediation",
+            "resolved",
+            "accepted_risk",
+            "false_positive"
+          ]
+        },
+        "first_seen": {
+          "type": "string"
+        },
+        "last_seen": {
+          "type": "string"
+        },
+        "resolved_at": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
       }
     }
   },
   "definitions": {
-    "impactLevel": { "type": "string", "enum": ["none", "low", "medium", "high", "unknown"] }
+    "impactLevel": {
+      "type": "string",
+      "enum": [
+        "none",
+        "low",
+        "medium",
+        "high",
+        "unknown"
+      ]
+    }
   }
-}
+}

package/src/cli/index.js

@@ -10,6 +10,7 @@ import { inspect } from '../commands/inspect.js';
 import { schemaCommand } from '../commands/schemaCmd.js';
 import { compareSnapshots } from '../commands/compareSnapshots.js';
 import { isInstallerCommand, runInstallerCommand } from '../installer/index.js';
+import { selfUpgradeCommand } from '../commands/selfUpgrade.js';
 
 const HELP = `citable — SEO / AEO / GEO audit, remediation, validation, and governance
 
@@ -31,6 +32,7 @@ Commands
   schema                    Validate deployed JSON-LD and propose registry-derived schema
   validate [mode]           registries (default) | claims | evidence | schema | links
   compare-snapshots [a b]   Regression diff between two audit runs
+  self-upgrade              Check for a newer version and upgrade the npx cache
 
 Options
   --target <dir|url>        Built output directory or deployed URL to audit
@@ -115,6 +117,11 @@ export async function main(argv = process.argv.slice(2), options = {}) {
         if (r.summary.regression_critical_or_high > 0) process.exitCode = 1;
         break;
       }
+      case 'self-upgrade': {
+        const output = await selfUpgradeCommand(argv.slice(1));
+        console.log(output);
+        break;
+      }
       case undefined:
         console.log(HELP);
         break;

package/src/commands/selfUpgrade.js

@@ -0,0 +1,146 @@
+/**
+ * self-upgrade command
+ *
+ * Checks npm for the latest @nebulacomponents/citable version and upgrades
+ * the running npx cache if a newer version is available.
+ *
+ * Usage:
+ *   npx @nebulacomponents/citable self-upgrade
+ *   npx @nebulacomponents/citable self-upgrade --check   (check only, no upgrade)
+ *   npx @nebulacomponents/citable self-upgrade --json    (machine-readable output)
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const PACKAGE_NAME = '@nebulacomponents/citable';
+const REGISTRY = 'https://registry.npmjs.org';
+const FETCH_TIMEOUT_MS = 10_000;
+
+/**
+ * Fetch the latest published version from the npm registry.
+ * Uses Node's built-in fetch (Node 22+); no extra dependencies.
+ *
+ * @returns {Promise<string>} latest semver string
+ */
+async function fetchLatestVersion() {
+  const url = `${REGISTRY}/${encodeURIComponent(PACKAGE_NAME)}/latest`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      headers: { Accept: 'application/json' },
+      signal: controller.signal,
+    });
+    if (!res.ok) throw new Error(`registry returned ${res.status}`);
+    const data = await res.json();
+    if (!data.version) throw new Error('no version field in registry response');
+    return data.version;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Compare two semver strings. Returns:
+ *   1  if a > b
+ *   0  if a === b
+ *  -1  if a < b
+ */
+function compareSemver(a, b) {
+  const parse = (v) => v.replace(/^v/, '').split('.').map(Number);
+  const [aMaj, aMin, aPatch] = parse(a);
+  const [bMaj, bMin, bPatch] = parse(b);
+  if (aMaj !== bMaj) return aMaj > bMaj ? 1 : -1;
+  if (aMin !== bMin) return aMin > bMin ? 1 : -1;
+  if (aPatch !== bPatch) return aPatch > bPatch ? 1 : -1;
+  return 0;
+}
+
+/**
+ * Re-execute the current command via npx at the new version.
+ * Used to trigger the npx cache refresh as a side-effect.
+ */
+function triggerNpxRefresh(latestVersion) {
+  // npx --yes ensures no prompt; @version pins to latest
+  const result = spawnSync(
+    'npx',
+    ['--yes', `${PACKAGE_NAME}@${latestVersion}`, '--version'],
+    { stdio: 'pipe', timeout: 60_000 },
+  );
+  return result.status === 0;
+}
+
+export async function selfUpgradeCommand(args) {
+  const checkOnly = args.includes('--check');
+  const jsonOutput = args.includes('--json');
+
+  // Resolve current version from our own package.json
+  let currentVersion;
+  try {
+    const req = createRequire(import.meta.url);
+    const pkgPath = path.resolve(fileURLToPath(import.meta.url), '../../../package.json');
+    currentVersion = req(pkgPath).version;
+  } catch {
+    const err = { ok: false, error: 'could not read local package.json version' };
+    if (jsonOutput) return JSON.stringify(err, null, 2);
+    return `error: ${err.error}`;
+  }
+
+  // Fetch latest from registry
+  let latestVersion;
+  try {
+    latestVersion = await fetchLatestVersion();
+  } catch (err) {
+    const result = { ok: false, current: currentVersion, error: `registry fetch failed: ${err.message}` };
+    if (jsonOutput) return JSON.stringify(result, null, 2);
+    return `error: ${result.error}\nCurrent version: ${currentVersion}`;
+  }
+
+  const cmp = compareSemver(latestVersion, currentVersion);
+
+  if (cmp <= 0) {
+    // Already current or ahead (local dev)
+    const result = { ok: true, current: currentVersion, latest: latestVersion, status: 'current' };
+    if (jsonOutput) return JSON.stringify(result, null, 2);
+    return `citable ${currentVersion} is already up to date (latest: ${latestVersion})`;
+  }
+
+  // Update available
+  if (checkOnly) {
+    const result = { ok: true, current: currentVersion, latest: latestVersion, status: 'update-available' };
+    if (jsonOutput) return JSON.stringify(result, null, 2);
+    return [
+      `Update available: ${currentVersion} → ${latestVersion}`,
+      `Run: npx ${PACKAGE_NAME}@latest self-upgrade`,
+    ].join('\n');
+  }
+
+  // Perform upgrade: warm the npx cache at the new version
+  const refreshed = triggerNpxRefresh(latestVersion);
+
+  const result = {
+    ok: refreshed,
+    current: currentVersion,
+    latest: latestVersion,
+    status: refreshed ? 'upgraded' : 'upgrade-failed',
+  };
+
+  if (jsonOutput) return JSON.stringify(result, null, 2);
+
+  if (refreshed) {
+    return [
+      `citable upgraded: ${currentVersion} → ${latestVersion}`,
+      `Run your next command with:  npx ${PACKAGE_NAME}@latest <command>`,
+      `Or pin globally:             npm install -g ${PACKAGE_NAME}@latest`,
+    ].join('\n');
+  }
+
+  return [
+    `Upgrade attempt failed (npx returned non-zero).`,
+    `Current: ${currentVersion}  Latest: ${latestVersion}`,
+    `Manual upgrade:  npx ${PACKAGE_NAME}@${latestVersion} <command>`,
+  ].join('\n');
+}

package/src/crawler/fetch.js

@@ -2,28 +2,61 @@
  * Fetch a URL capturing status, headers, body, and redirect chain.
  * Used only when the operator supplies a deployed target and fetching is permitted.
  */
-export async function fetchUrl(url, { userAgent = 'CitableAudit/0.1', maxRedirects = 10, timeoutMs = 20000 } = {}) {
+export async function fetchUrl(url, { userAgent = 'CitableAudit/0.1', maxRedirects = 10, timeoutMs = 20000, maxRetries = 3, retryDelayMs = 1000 } = {}) {
   const chain = [];
   let current = url;
+  
   for (let i = 0; i <= maxRedirects; i++) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     let res;
-    try {
-      res = await fetch(current, {
-        redirect: 'manual',
-        headers: { 'user-agent': userAgent },
-        signal: controller.signal,
-      });
-    } finally {
-      clearTimeout(timer);
+    let lastError;
+    
+    // Retry loop for transient failures
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        res = await fetch(current, {
+          redirect: 'manual',
+          headers: { 'user-agent': userAgent },
+          signal: controller.signal,
+        });
+        lastError = null;
+        break; // Success, break retry loop
+      } catch (err) {
+        lastError = err;
+        // Only retry on network errors or 5xx, not on 4xx
+        if (err.name === 'AbortError') {
+          throw err; // Timeout, don't retry
+        }
+        // Exponential backoff with jitter
+        const delay = retryDelayMs * Math.pow(2, attempt) + Math.random() * retryDelayMs;
+        if (attempt < maxRetries - 1) {
+          await new Promise(resolve => setTimeout(resolve, delay));
+        }
+      } finally {
+        clearTimeout(timer);
+      }
     }
+    
+    if (lastError) {
+      throw lastError;
+    }
+    
     const headers = Object.fromEntries(res.headers.entries());
     if (res.status >= 300 && res.status < 400 && headers.location) {
       chain.push({ url: current, status: res.status, location: headers.location });
       current = new URL(headers.location, current).href;
       continue;
     }
+    
+    // Retry on 5xx with one less attempt (already used retry loop above)
+    if (res.status >= 500 && i < maxRedirects) {
+      // Treat 5xx as transient, add to chain and retry same URL
+      chain.push({ url: current, status: res.status, location: null, error: 'server error' });
+      await new Promise(resolve => setTimeout(resolve, retryDelayMs));
+      continue;
+    }
+    
     const body = await res.text();
     return { url: current, requestedUrl: url, status: res.status, headers, body, redirectChain: chain };
   }