@aiaiai-pt/martha-cli 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-06-09
+
+### Added — #522 bulk-ingest observability + management
+- `document-sync sources status <id>` — ingestion progress for a source: counts by status (pending / ingesting / ready / error), recent drain rate, naive ETA, and the top grouped error reasons. `--window-minutes` tunes the rate window; JSON mode emits the raw summary.
+- `documents retry --collection <id-or-slug-or-name> --status error [--yes]` — re-drive a collection's failed documents (subtree-scoped). Bounded + idempotent: flips matching docs back to `pending` for the ingestion reconciler to re-drive through the per-tenant quota gate at its capped rate (no thundering herd). Non-TTY requires `--yes`; JSON mode emits the result. `--status pending` re-drives stuck-pending docs.
+
 ### Added — #407 connections command (service-account Drive auth)
 - `martha connections create|list|update|test|delete` — manage Vault-backed integration connections from the CLI (previously admin-UI / raw-curl only). `create` mirrors `POST /api/admin/connections`; `update` mirrors `PUT`.
 - Service-account Google Drive: `martha connections create --integration google_drive --auth-type service_account --credential-value @sa-key.json --config '{"subject":"...","scopes":[...]}'` reads enterprise Shared Drives without CASA (#407). The SA key shape (`type`, `client_email`) is validated before submit; `--credential-value` accepts `@file` / `-` (stdin) / literal.

package/dist/index.js

@@ -14136,11 +14136,79 @@ ${source_default.bold(`Sources (${result.sources.length} chunks):`)}`);
       }
     }
   });
+  cmd.command("retry").description("Re-drive ingestion for a collection's errored documents. Bounded " + "and idempotent — flips matching docs back to pending; the " + "ingestion reconciler re-drives them at its capped rate (no herd).").requiredOption("--collection <ref>", "Collection id, slug, or name").option("--status <status>", "Which docs to retry: error | pending", "error").option("--yes", "Skip confirmation (required in non-interactive mode)").action(async (opts) => {
+    if (!["error", "pending"].includes(opts.status)) {
+      throw new CLIError("--status must be one of: error, pending", 4 /* Validation */);
+    }
+    const ctx = getCtx();
+    const collection = await resolveCollection(ctx, opts.collection);
+    if (!opts.yes) {
+      if (!process.stdin.isTTY) {
+        throw new CLIError("Cannot confirm in non-interactive mode. Use --yes to retry.", 1 /* Error */);
+      }
+      const ok = await confirm(`Retry ${opts.status} documents in '${collection.name}'?`);
+      if (!ok) {
+        if (isJson()) {
+          console.log(JSON.stringify({ reset_count: 0, cancelled: true }));
+        } else {
+          console.log("Cancelled.");
+        }
+        return;
+      }
+    }
+    const result = await ctx.api.post(`/api/admin/collections/${encodeURIComponent(collection.id)}/retry-ingestion`, undefined, { params: { status: opts.status } });
+    if (isJson()) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(source_default.green(`Re-drove ${result.reset_count} ${opts.status} document(s) in ` + `'${collection.name}'. The ingestion reconciler will pick them ` + `up within ~1 min (rate-limited by the per-tenant quota).`));
+  });
 }
 
 // src/commands/document-sync.ts
 init_errors();
 var VALID_MODES = ["polling", "evented", "manual"];
+function formatEta(seconds) {
+  if (seconds === null || seconds === undefined)
+    return "—";
+  if (seconds < 60)
+    return "<1m";
+  const mins = Math.round(seconds / 60);
+  if (mins < 60)
+    return `${mins}m`;
+  const hours = Math.floor(mins / 60);
+  const rem = mins % 60;
+  return rem ? `${hours}h ${rem}m` : `${hours}h`;
+}
+function progressBar(ready, total, width = 24) {
+  if (total <= 0)
+    return source_default.dim("·".repeat(width));
+  const filled = Math.min(width, Math.round(ready / total * width));
+  return source_default.green("█".repeat(filled)) + source_default.dim("░".repeat(width - filled));
+}
+function printIngestionStatus(sourceId, s) {
+  const c = s.counts;
+  const pct = s.total > 0 ? Math.round(c.ready / s.total * 100) : 0;
+  console.log(source_default.bold(`
+Ingestion status — source ${sourceId}`));
+  console.log(source_default.dim("-".repeat(48)));
+  console.log(`  ${progressBar(c.ready, s.total)}  ${pct}%  (${c.ready}/${s.total} ready)`);
+  console.log(`  ${source_default.yellow("pending")}   ${String(c.pending).padStart(6)}` + `   ${source_default.cyan("ingesting")} ${String(c.ingesting).padStart(6)}`);
+  console.log(`  ${source_default.green("ready")}     ${String(c.ready).padStart(6)}` + `   ${source_default.red("error")}     ${String(c.error).padStart(6)}`);
+  if (c.other > 0) {
+    console.log(`  ${source_default.dim("other")}     ${String(c.other).padStart(6)}`);
+  }
+  console.log(source_default.dim("-".repeat(48)));
+  console.log(`  Drain rate : ${source_default.cyan(s.drain_rate_per_min.toFixed(1))}/min` + source_default.dim(` (last ${s.drain_window_minutes}m, ${s.completed_in_window} completed)`));
+  console.log(`  ETA        : ${source_default.cyan(formatEta(s.eta_seconds))}`);
+  if (s.top_errors.length > 0) {
+    console.log(source_default.dim("-".repeat(48)));
+    console.log(source_default.bold("  Top errors:"));
+    for (const e of s.top_errors) {
+      console.log(`    ${source_default.red(String(e.count).padStart(4))}  ${e.reason}`);
+    }
+  }
+}
 function registerDocumentSyncCommands(program2) {
   const cmd = program2.command("document-sync").description("Manage durable document sync sources (Google Drive, etc.)");
   function getCtx() {
@@ -14269,6 +14337,19 @@ No google_drive sources found.`));
       console.log(source_default.green(`Started ${op} for source ${sourceId} ` + `(workflow=${resp.workflow_id}, status=${resp.status})`));
     });
   }
+  sources.command("status <source_id>").description("Show ingestion progress for a source: counts by status, drain " + "rate, ETA, and top error reasons.").option("--window-minutes <n>", "Drain-rate window in minutes (1–1440)", "15").action(async (sourceId, opts) => {
+    const windowMinutes = Number.parseInt(opts.windowMinutes, 10);
+    if (!Number.isFinite(windowMinutes) || windowMinutes < 1 || windowMinutes > 1440) {
+      throw new CLIError("--window-minutes must be an integer between 1 and 1440.", 4 /* Validation */);
+    }
+    const ctx = getCtx();
+    const summary = await ctx.api.get(`/api/admin/document-sync/sources/${encodeURIComponent(sourceId)}/status`, { params: { window_minutes: String(windowMinutes) } });
+    if (isJson()) {
+      console.log(JSON.stringify(summary, null, 2));
+      return;
+    }
+    printIngestionStatus(sourceId, summary);
+  });
 }
 
 // src/commands/approvals.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/martha-cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Terminal-first client for the Martha AI platform",
   "homepage": "https://docs.martha.nomadriver.co",
   "repository": {