@gmickel/gno 1.32.0 → 1.34.0

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/publish.ts

@@ -4,7 +4,8 @@
  * @module src/cli/commands/publish
  */
 
-import { mkdir, writeFile } from "node:fs/promises";
+// node:fs/promises — directory creation has no Bun-native equivalent.
+import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import { join } from "node:path";
 
@@ -12,10 +13,15 @@ import type {
   PublishArtifact,
   PublishVisibility,
 } from "../../publish/artifact";
+import type { PublishAssetEgressSummary } from "../../publish/attachment-resolver";
 import type { SanitizeWarning } from "../../publish/obsidian-sanitize";
 
 import { resolveDownloadsDir } from "../../core/user-dirs";
-import { derivePublishArtifactFilename, slugify } from "../../publish/artifact";
+import {
+  derivePublishArtifactFilename,
+  serializePublishArtifact,
+  slugify,
+} from "../../publish/artifact";
 import { exportPublishArtifact } from "../../publish/export-service";
 import { formatSanitizeWarnings } from "../../publish/obsidian-sanitize";
 import { initStore } from "./shared";
@@ -37,6 +43,7 @@ export type PublishExportResult =
       success: true;
       data: {
         artifact: PublishArtifact;
+        assetSummary: PublishAssetEgressSummary;
         outPath: string;
         preview?: string;
         uploadUrl: string;
@@ -64,6 +71,15 @@ export async function buildDefaultPublishExportPath(
   );
 }
 
+/** Write exactly the canonical byte sequence used by upload-size accounting. */
+export async function writePublishArtifactFile(
+  outPath: string,
+  artifact: PublishArtifact
+): Promise<void> {
+  await mkdir(dirname(outPath), { recursive: true });
+  await Bun.write(outPath, serializePublishArtifact(artifact));
+}
+
 export async function publishExport(
   target: string,
   options: PublishExportOptions
@@ -79,7 +95,7 @@ export async function publishExport(
   const { collections, store } = initResult;
 
   try {
-    const { artifact, warnings } = await exportPublishArtifact({
+    const { artifact, assetSummary, warnings } = await exportPublishArtifact({
       collections,
       options: {
         routeSlug: options.slug,
@@ -104,6 +120,7 @@ export async function publishExport(
         success: true,
         data: {
           artifact,
+          assetSummary,
           outPath: "",
           preview,
           uploadUrl: "https://gno.sh/studio",
@@ -116,13 +133,13 @@ export async function publishExport(
     const outPath =
       options.out?.trim() || (await buildDefaultPublishExportPath(artifact));
 
-    await mkdir(dirname(outPath), { recursive: true });
-    await writeFile(outPath, JSON.stringify(artifact, null, 2));
+    await writePublishArtifactFile(outPath, artifact);
 
     return {
       success: true,
       data: {
         artifact,
+        assetSummary,
         outPath,
         uploadUrl: "https://gno.sh/studio",
         warnings,
@@ -159,19 +176,37 @@ export function formatPublishExport(
     return JSON.stringify(result.data, null, 2);
   }
 
-  const { artifact, outPath, preview, uploadUrl, warningsDisplay } =
-    result.data;
+  const {
+    artifact,
+    assetSummary,
+    outPath,
+    preview,
+    uploadUrl,
+    warningsDisplay,
+  } = result.data;
   const space = artifact.spaces[0];
   const warningsSection =
     warningsDisplay.length > 0
       ? ["", "Preprocessor notes:", ...warningsDisplay]
       : [];
+  const assetSection = [
+    "",
+    "Asset summary:",
+    `  assets=${assetSummary.assetCount} refs=${assetSummary.referenceCount} external=${assetSummary.externalCount}`,
+    `  rawBytes=${assetSummary.rawBytes} encodedBytes=${assetSummary.encodedBytes} finalBytes=${assetSummary.finalUploadBytes}`,
+    `  dedupSavedBytes=${assetSummary.dedupSavedBytes} unresolved=${assetSummary.diagnostics.length}`,
+    ...assetSummary.diagnostics.map(
+      (diagnostic) =>
+        `  [${diagnostic.code}] ${diagnostic.noteSlug}: ${diagnostic.sourceRef} — ${diagnostic.message}`
+    ),
+  ];
 
   if (preview !== undefined) {
     return [
       `Preview (no file written) — ${space?.sourceType ?? "artifact"}`,
       `Route slug: ${space?.routeSlug ?? slugify(artifact.source)}`,
       `Visibility: ${space?.visibility ?? "public"}`,
+      ...assetSection,
       ...warningsSection,
       "",
       "─── sanitized markdown ───",
@@ -185,6 +220,7 @@ export function formatPublishExport(
     `Visibility: ${space?.visibility ?? "public"}`,
     `Filename: ${derivePublishArtifactFilename(artifact)}`,
     `Next: open ${uploadUrl} and drop ${outPath} into the upload zone.`,
+    ...assetSection,
     ...warningsSection,
   ].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")