@gmickel/gno 1.33.0 → 1.34.1

package/src/cli/commands/audit.ts

@@ -0,0 +1,231 @@
+/** Read-only knowledge-integrity audit CLI adapter. */
+
+// node:fs/promises provides atomic filesystem structure operations with no Bun equivalent.
+import { chmod, mkdtemp, rename, rmdir, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+import type {
+  AuditCategory,
+  AuditReport,
+  AuditRunResult,
+} from "../../core/audit";
+import type { WorkspaceAuditProgress } from "../../core/audit-workspace";
+
+import { getIndexDbPath } from "../../app/constants";
+import { loadConfig } from "../../config";
+import {
+  auditExitCode,
+  AUDIT_CATEGORIES,
+  serializeAuditReportCanonical,
+} from "../../core/audit";
+import { runWorkspaceAudit } from "../../core/audit-workspace";
+import { normalizeTag, validateTag } from "../../core/tags";
+import { normalizeCollectionName } from "../../core/validation";
+import { SqliteAdapter } from "../../store/sqlite/adapter";
+
+export interface AuditCommandOptions {
+  category?: string;
+  configPath?: string;
+  indexName?: string;
+  collections?: string[];
+  paths?: string[];
+  tags?: string[];
+  maxFindings?: number;
+  maxAgeDays?: number;
+  orphanRoots?: string[];
+  orphanIgnorePrefixes?: string[];
+  signal?: AbortSignal;
+  onProgress?: (progress: WorkspaceAuditProgress) => void | Promise<void>;
+}
+
+export type AuditCommandResult =
+  | { success: true; report: AuditReport; exitCode: number }
+  | { success: false; error: string; invalid: boolean };
+
+const resolveCategories = (
+  value: string | undefined
+): AuditCategory[] | null => {
+  const normalized = (value ?? "all").trim().toLowerCase();
+  if (normalized === "all") return [...AUDIT_CATEGORIES];
+  return (AUDIT_CATEGORIES as readonly string[]).includes(normalized)
+    ? [normalized as AuditCategory]
+    : null;
+};
+
+const invalidPositiveInteger = (value: number | undefined): boolean =>
+  value !== undefined && (!Number.isSafeInteger(value) || value < 1);
+
+const AUDIT_SCOPE_FILTER_MAX_ITEMS = 256;
+
+const oversizedScopeFilter = (
+  options: AuditCommandOptions
+): "collections" | "paths" | "tags" | null => {
+  for (const name of ["collections", "paths", "tags"] as const) {
+    if ((options[name]?.length ?? 0) > AUDIT_SCOPE_FILTER_MAX_ITEMS) {
+      return name;
+    }
+  }
+  return null;
+};
+
+export const audit = async (
+  options: AuditCommandOptions
+): Promise<AuditCommandResult> => {
+  const categories = resolveCategories(options.category);
+  if (!categories) {
+    return {
+      success: false,
+      invalid: true,
+      error: "category must be links, provenance, freshness, or all",
+    };
+  }
+  if (invalidPositiveInteger(options.maxFindings)) {
+    return {
+      success: false,
+      invalid: true,
+      error: "maxFindings must be a positive integer",
+    };
+  }
+  if (invalidPositiveInteger(options.maxAgeDays)) {
+    return {
+      success: false,
+      invalid: true,
+      error: "maxAgeDays must be a positive integer",
+    };
+  }
+  const oversizedFilter = oversizedScopeFilter(options);
+  if (oversizedFilter) {
+    return {
+      success: false,
+      invalid: true,
+      error: `${oversizedFilter} must contain at most ${AUDIT_SCOPE_FILTER_MAX_ITEMS} values`,
+    };
+  }
+  const configResult = await loadConfig(options.configPath);
+  if (!configResult.ok) {
+    return { success: false, invalid: true, error: configResult.error.message };
+  }
+  const config = configResult.value;
+  const requestedCollections = (options.collections ?? []).map(
+    normalizeCollectionName
+  );
+  const requestedTags = (options.tags ?? []).map(normalizeTag);
+  const invalidTag = requestedTags.find((tag) => !validateTag(tag));
+  if (invalidTag) {
+    return {
+      success: false,
+      invalid: true,
+      error: `Invalid tag: "${invalidTag}"`,
+    };
+  }
+  const knownCollections = new Set(
+    config.collections.map((collection) => collection.name)
+  );
+  const missingCollection = requestedCollections.find(
+    (collection) => !knownCollections.has(collection)
+  );
+  if (missingCollection) {
+    return {
+      success: false,
+      invalid: true,
+      error: `Collection not found: ${missingCollection}`,
+    };
+  }
+  const dbPath = getIndexDbPath(options.indexName);
+  if (!(await Bun.file(dbPath).exists())) {
+    return {
+      success: false,
+      invalid: false,
+      error: `Index database not found: ${dbPath}. Run gno index first.`,
+    };
+  }
+  const store = new SqliteAdapter();
+  const opened = store.openReadOnly(dbPath);
+  if (!opened.ok) {
+    return { success: false, invalid: false, error: opened.error.message };
+  }
+  try {
+    const result: AuditRunResult = await runWorkspaceAudit({
+      store,
+      config,
+      collections: config.collections,
+      indexName: options.indexName ?? "default",
+      categories,
+      collectionFilters: requestedCollections,
+      pathFilters: options.paths,
+      tagFilters: requestedTags,
+      maxFindings: options.maxFindings,
+      agePolicy:
+        options.maxAgeDays === undefined
+          ? undefined
+          : { maxAgeDays: options.maxAgeDays },
+      orphanRoots: options.orphanRoots,
+      orphanIgnorePrefixes: options.orphanIgnorePrefixes,
+      signal: options.signal,
+      onProgress: options.onProgress,
+    });
+    if (!result.ok) {
+      return { success: false, invalid: true, error: result.error };
+    }
+    return {
+      success: true,
+      report: result.report,
+      exitCode: auditExitCode(result.exit),
+    };
+  } finally {
+    await store.close();
+  }
+};
+
+export const formatAuditReport = (
+  report: AuditReport,
+  options: { json?: boolean } = {}
+): string => {
+  if (options.json) return serializeAuditReportCanonical(report);
+  const lines = [
+    `Audit: ${report.status}`,
+    `Categories: ${report.scope.categories.join(", ")}`,
+    `Rules: ${report.counts.rules.total} (${report.counts.rules.fail} failed, ${report.counts.rules.unavailable} unavailable, ${report.counts.rules.inconclusive} inconclusive)`,
+    `Findings: ${report.counts.findings.total}${report.counts.findings.truncated ? ` (${report.counts.findings.returned} shown)` : ""}`,
+    `Examined: ${report.counts.examined.documents} document/rule observations`,
+    `Duration: ${report.durationMs}ms`,
+  ];
+  for (const finding of report.findings) {
+    const location = finding.location ? ` ${finding.location}` : "";
+    lines.push(
+      `- [${finding.severity}] ${finding.ruleId}: ${finding.subject}${location} — ${finding.message}`
+    );
+  }
+  for (const rule of report.rules) {
+    if (
+      rule.status === "skip" ||
+      rule.status === "unavailable" ||
+      rule.status === "inconclusive"
+    ) {
+      lines.push(`- [${rule.status}] ${rule.ruleId}: ${rule.message}`);
+    }
+  }
+  return lines.join("\n");
+};
+
+export const writeAuditReport = async (
+  path: string,
+  report: AuditReport,
+  options: { json?: boolean } = {}
+): Promise<void> => {
+  const temporaryDirectory = await mkdtemp(
+    join(dirname(path), `.${basename(path)}-`)
+  );
+  const temporaryPath = join(temporaryDirectory, "report");
+  try {
+    await Bun.write(temporaryPath, `${formatAuditReport(report, options)}\n`, {
+      createPath: false,
+      mode: 0o600,
+    });
+    await chmod(temporaryPath, 0o600);
+    await rename(temporaryPath, path);
+  } finally {
+    await unlink(temporaryPath).catch(() => undefined);
+    await rmdir(temporaryDirectory).catch(() => undefined);
+  }
+};

package/src/cli/commands/models/pull.ts

@@ -10,6 +10,7 @@ import type { DownloadProgress, ModelType } from "../../../llm/types";
 import { getModelsCachePath } from "../../../app/constants";
 import { loadConfig } from "../../../config";
 import { ModelCache } from "../../../llm/cache";
+import { isHttpRerankUri } from "../../../llm/httpRerank";
 import { getActivePreset } from "../../../llm/registry";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -46,6 +47,7 @@ export interface ModelPullResult {
   error?: string;
   path?: string;
   skipped?: boolean;
+  skipReason?: "cached" | "external";
 }
 
 export interface ModelsPullResult {
@@ -117,6 +119,20 @@ export async function modelsPull(
     const uri =
       type === "expand" ? (preset.expand ?? preset.gen) : preset[type];
 
+    // HTTP rerankers are services, not model artifacts. They are loaded
+    // directly by LlmAdapter and must never enter the local model cache path.
+    if (type === "rerank" && isHttpRerankUri(uri)) {
+      results.push({
+        type,
+        uri,
+        ok: true,
+        skipped: true,
+        skipReason: "external",
+      });
+      skipped += 1;
+      continue;
+    }
+
     // Check if already cached (skip unless --force)
     if (!options.force) {
       const isCached = await cache.isCached(uri);
@@ -128,6 +144,7 @@ export async function modelsPull(
           ok: true,
           path: path ?? undefined,
           skipped: true,
+          skipReason: "cached",
         });
         skipped += 1;
         continue;
@@ -176,13 +193,17 @@ export async function modelsPull(
  */
 export function formatModelsPull(result: ModelsPullResult): string {
   const lines: string[] = [];
+  let externalSkipped = 0;
   const label = (type: ModelType) =>
     type === "gen" ? "answer" : type === "expand" ? "expand" : type;
 
   for (const r of result.results) {
     if (r.ok) {
       if (r.skipped) {
-        lines.push(`${label(r.type)}: skipped (already cached)`);
+        if (r.skipReason === "external") externalSkipped += 1;
+        const reason =
+          r.skipReason === "external" ? "external endpoint" : "already cached";
+        lines.push(`${label(r.type)}: skipped (${reason})`);
       } else {
         lines.push(`${label(r.type)}: downloaded`);
       }
@@ -196,10 +217,18 @@ export function formatModelsPull(result: ModelsPullResult): string {
     lines.push(`${result.failed} model(s) failed to download.`);
   } else if (result.skipped === result.results.length) {
     lines.push("");
-    lines.push("All models already cached. Use --force to re-download.");
+    lines.push(
+      externalSkipped > 0
+        ? "No model downloads needed."
+        : "All models already cached. Use --force to re-download."
+    );
   } else {
     lines.push("");
-    lines.push("All models downloaded successfully.");
+    lines.push(
+      externalSkipped > 0
+        ? "All downloadable models downloaded successfully."
+        : "All models downloaded successfully."
+    );
   }
 
   return lines.join("\n");

package/src/cli/errors.ts

@@ -9,7 +9,12 @@
 // Error Types
 // ─────────────────────────────────────────────────────────────────────────────
 
-export type CliErrorCode = "VALIDATION" | "RUNTIME" | "NOT_RUNNING";
+export type CliErrorCode =
+  | "VALIDATION"
+  | "RUNTIME"
+  | "NOT_RUNNING"
+  | "AUDIT_FINDINGS"
+  | "AUDIT_PARTIAL";
 
 export interface CliErrorOptions {
   details?: Record<string, unknown>;
@@ -62,13 +67,15 @@ export class CliError extends Error {
 // Exit Codes
 // ─────────────────────────────────────────────────────────────────────────────
 
-export function exitCodeFor(err: CliError): 1 | 2 | 3 {
+export function exitCodeFor(err: CliError): 1 | 2 | 3 | 4 | 5 {
   if (err.code === "VALIDATION") {
     return 1;
   }
   if (err.code === "NOT_RUNNING") {
     return 3;
   }
+  if (err.code === "AUDIT_FINDINGS") return 4;
+  if (err.code === "AUDIT_PARTIAL") return 5;
   return 2;
 }
 

package/src/cli/program.ts

@@ -1539,6 +1539,118 @@ function wireOnboardingCommands(program: Command): void {
       }
     );
 
+  // audit - Read-only workspace integrity report
+  program
+    .command("audit [category]")
+    .description("Run read-only workspace integrity audits")
+    .option(
+      "-c, --collection <name>",
+      "collection scope (repeatable)",
+      collectRepeatableValue,
+      []
+    )
+    .option(
+      "--path <prefix>",
+      "collection-relative path prefix (repeatable)",
+      collectRepeatableValue,
+      []
+    )
+    .option(
+      "--tag <tag>",
+      "require tag (repeatable, AND semantics)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--max-findings <count>", "maximum returned findings", Number)
+    .option("--max-age-days <days>", "explicit age review signal", Number)
+    .option(
+      "--orphan-root <uri>",
+      "URI excluded from orphan findings (repeatable)",
+      collectRepeatableValue,
+      []
+    )
+    .option(
+      "--orphan-ignore-prefix <prefix>",
+      "path prefix excluded from orphan findings (repeatable)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--output <path>", "also write the rendered report to a file")
+    .option("--no-progress", "disable progress on stderr")
+    .option("--json", "JSON output")
+    .action(
+      async (
+        category: string | undefined,
+        cmdOpts: Record<string, unknown>
+      ) => {
+        const { audit, formatAuditReport, writeAuditReport } =
+          await import("./commands/audit");
+        const globals = getGlobals();
+        const json = getFormat(cmdOpts) === "json";
+        const showProgress =
+          cmdOpts.progress !== false &&
+          !globals.quiet &&
+          !json &&
+          process.stderr.isTTY;
+        const controller = new AbortController();
+        const abort = (): void => controller.abort();
+        process.once("SIGINT", abort);
+        try {
+          const result = await audit({
+            category,
+            configPath: globals.config,
+            indexName: globals.index,
+            collections: cmdOpts.collection as string[],
+            paths: cmdOpts.path as string[],
+            tags: cmdOpts.tag as string[],
+            maxFindings: cmdOpts.maxFindings as number | undefined,
+            maxAgeDays: cmdOpts.maxAgeDays as number | undefined,
+            orphanRoots: cmdOpts.orphanRoot as string[],
+            orphanIgnorePrefixes: cmdOpts.orphanIgnorePrefix as string[],
+            signal: controller.signal,
+            onProgress: showProgress
+              ? ({ phase, completed, total }) => {
+                  process.stderr.write(
+                    `\rAudit ${phase}: ${completed}/${Math.max(total, 1)}`
+                  );
+                }
+              : undefined,
+          });
+          if (!result.success) {
+            throw new CliError(
+              result.invalid ? "VALIDATION" : "RUNTIME",
+              result.error
+            );
+          }
+          const rendered = formatAuditReport(result.report, { json });
+          process.stdout.write(`${rendered}\n`);
+          if (cmdOpts.output) {
+            await writeAuditReport(cmdOpts.output as string, result.report, {
+              json,
+            });
+          }
+          if (result.exitCode === 2) {
+            throw new CliError("RUNTIME", "Audit runtime failure", {
+              silent: true,
+            });
+          }
+          if (result.exitCode === 4) {
+            throw new CliError("AUDIT_FINDINGS", "Audit findings present", {
+              silent: true,
+            });
+          }
+          if (result.exitCode === 5) {
+            throw new CliError("AUDIT_PARTIAL", "Audit evidence is partial", {
+              silent: true,
+            });
+          }
+        } finally {
+          if (showProgress) process.stderr.write("\n");
+          process.removeListener("SIGINT", abort);
+        }
+      }
+    );
+
   // status - Show index status
   program
     .command("status")