@indigoai-us/hq-cli 5.75.0 → 5.77.0

package/src/commands/files.ts

@@ -512,6 +512,100 @@ export function registerFilesCommand(program: Command): Command {
       },
     );
 
+  files
+    .command("versions <path>")
+    .description(
+      "List prior content versions and delete markers for one exact vault key. Use --personal for your personal vault.",
+    )
+    .option(
+      "--personal",
+      "Target your own personal vault instead of a company vault (mutually exclusive with --company)",
+    )
+    .action(async (path: string, opts: { personal?: boolean }) => {
+      try {
+        const companySlug = files.opts().company as string | undefined;
+        const personal = opts.personal === true;
+        assertRecoveryScope(personal, companySlug);
+        await runFilesVersions({ key: path, personal, companySlug });
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  files
+    .command("restore <path>")
+    .description(
+      "Restore a prior version or undelete an exact vault key. Prompts before overwriting unless --yes. Use --personal for your personal vault.",
+    )
+    .option(
+      "--personal",
+      "Target your own personal vault instead of a company vault (mutually exclusive with --company)",
+    )
+    .option("--version <id>", "Content version ID to restore")
+    .option("-y, --yes", "Skip the overwrite confirmation prompt (for scripts)")
+    .action(
+      async (
+        path: string,
+        opts: { personal?: boolean; yes?: boolean; version?: string },
+      ) => {
+        try {
+          const companySlug = files.opts().company as string | undefined;
+          const personal = opts.personal === true;
+          assertRecoveryScope(personal, companySlug);
+          await runFilesRestore({
+            key: path,
+            versionId: opts.version,
+            yes: opts.yes === true,
+            personal,
+            companySlug,
+          });
+        } catch (err) {
+          console.error(
+            chalk.red("Error:"),
+            err instanceof Error ? err.message : String(err),
+          );
+          process.exit(1);
+        }
+      },
+    );
+
+  files
+    .command("trash")
+    .description(
+      "List deleted vault keys retained as tombstones. Use --personal for your personal vault.",
+    )
+    .option(
+      "--personal",
+      "Target your own personal vault instead of a company vault (mutually exclusive with --company)",
+    )
+    .option("--prefix <prefix>", "Literal key prefix to filter tombstones")
+    .option("--cursor <cursor>", "Continue from an opaque tombstone cursor")
+    .action(
+      async (opts: { personal?: boolean; prefix?: string; cursor?: string }) => {
+        try {
+          const companySlug = files.opts().company as string | undefined;
+          const personal = opts.personal === true;
+          assertRecoveryScope(personal, companySlug);
+          await runFilesTrash({
+            prefix: opts.prefix ?? "",
+            cursor: opts.cursor,
+            personal,
+            companySlug,
+          });
+        } catch (err) {
+          console.error(
+            chalk.red("Error:"),
+            err instanceof Error ? err.message : String(err),
+          );
+          process.exit(1);
+        }
+      },
+    );
+
   // Return the `files` Commander group so callers (src/index.ts) can attach
   // additional subcommands (e.g. `hq files browse`/`hq files cat` from
   // files-browse.ts) onto the same group without re-creating it.
@@ -1034,3 +1128,319 @@ export async function runFilesDelete(
     );
   }
 }
+
+// ---------------------------------------------------------------------------
+// Version history + recovery commands
+// ---------------------------------------------------------------------------
+
+export interface FileVersionRow {
+  versionId: string;
+  isLatest: boolean;
+  lastModified: string;
+  size: number;
+  isDeleteMarker?: boolean;
+}
+
+export interface FilesVersionsResponse {
+  key: string;
+  versions: FileVersionRow[];
+  computedAt: string;
+}
+
+export interface FileTombstoneRow {
+  key: string;
+  deletedAt: string;
+  deletedBy: string;
+  deletedPrefix: string;
+}
+
+export interface FilesTrashResponse {
+  companyUid?: string;
+  personal?: true;
+  tombstones: FileTombstoneRow[];
+  cursor?: string | null;
+  truncated: boolean;
+  computedAt: string;
+}
+
+export interface FilesRestoreResponse {
+  key: string;
+  wasDeleted: boolean;
+  restoredFromVersionId: string;
+  newVersionId: string;
+}
+
+export class FilesRecoveryHttpError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+    public readonly code?: string,
+  ) {
+    super(message);
+    this.name = "FilesRecoveryHttpError";
+  }
+}
+
+function assertRecoveryScope(personal: boolean, companySlug: string | undefined): void {
+  if (personal && companySlug) {
+    throw new Error("Pass either --personal or --company, not both.");
+  }
+}
+
+function assertExactRecoveryKey(key: string): void {
+  if (!key || key.includes("*")) {
+    throw new Error(
+      "Restore and version history require one exact, wildcard-free vault key.",
+    );
+  }
+}
+
+function quoteRecoveryShellArg(value: string): string {
+  return "'" + value.replace(/'/g, "'\\''") + "'";
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return String(bytes) + " B";
+  if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + " KiB";
+  if (bytes < 1024 * 1024 * 1024) {
+    return (bytes / (1024 * 1024)).toFixed(1) + " MiB";
+  }
+  return (bytes / (1024 * 1024 * 1024)).toFixed(1) + " GiB";
+}
+
+/** Render the exact-key version history, including S3 delete markers. */
+export function formatFilesVersionsTable(rows: FileVersionRow[]): string {
+  if (rows.length === 0) {
+    return "No version history exists for that key.";
+  }
+
+  const cols = ["VERSION", "TYPE", "LATEST", "MODIFIED", "SIZE"];
+  const data = rows.map((row) => [
+    row.versionId,
+    row.isDeleteMarker ? "delete marker" : "content",
+    row.isLatest ? "yes" : "",
+    row.lastModified,
+    row.isDeleteMarker ? "—" : formatBytes(row.size),
+  ]);
+  const widths = cols.map((col, index) =>
+    Math.max(col.length, ...data.map((row) => row[index].length)),
+  );
+  const renderRow = (row: string[]): string =>
+    row.map((cell, index) => cell.padEnd(widths[index])).join("  ");
+  return [
+    chalk.bold(renderRow(cols)),
+    chalk.dim(renderRow(widths.map((width) => "─".repeat(width)))),
+    ...data.map(renderRow),
+  ].join("\n");
+}
+
+/** Render durable delete tombstones without implying the objects still exist. */
+export function formatFilesTrashTable(rows: FileTombstoneRow[]): string {
+  if (rows.length === 0) {
+    return "Trash is empty.";
+  }
+
+  const cols = ["KEY", "DELETED", "DELETED BY", "DELETE PREFIX"];
+  const data = rows.map((row) => [
+    row.key,
+    row.deletedAt,
+    row.deletedBy,
+    row.deletedPrefix,
+  ]);
+  const widths = cols.map((col, index) =>
+    Math.max(col.length, ...data.map((row) => row[index].length)),
+  );
+  const renderRow = (row: string[]): string =>
+    row.map((cell, index) => cell.padEnd(widths[index])).join("  ");
+  return [
+    chalk.bold(renderRow(cols)),
+    chalk.dim(renderRow(widths.map((width) => "─".repeat(width)))),
+    ...data.map(renderRow),
+  ].join("\n");
+}
+
+function throwRecoveryHttpError(
+  status: number,
+  body: Record<string, string>,
+  statusText: string,
+): never {
+  throw new FilesRecoveryHttpError(
+    status,
+    body.message ?? body.error ?? statusText,
+    body.code,
+  );
+}
+
+function formatFilesRecoveryError(err: FilesRecoveryHttpError, key?: string): string {
+  if (err.status === 401) {
+    return "Not authenticated — please run hq login";
+  }
+  if (err.status === 403) {
+    return key
+      ? "Not authorized to modify '" + key + "' — you need write access on it"
+      : "Not authorized to view this vault path";
+  }
+  if (err.code === "FILES_RESTORE_VERSION_NOT_FOUND") {
+    return "That version is unavailable or is a delete marker.";
+  }
+  if (err.code === "FILES_RESTORE_NO_PRIOR_VERSION") {
+    return "There is no prior content version to restore.";
+  }
+  if (err.code === "FILES_RESTORE_NO_RECOVERABLE_VERSION") {
+    return "There is no recoverable content version for this key.";
+  }
+  if (err.status === 400) {
+    return "Invalid request: " + err.message;
+  }
+  if (err.status >= 500) {
+    return "Server error: " + err.message;
+  }
+  return err.message || "Request failed (" + String(err.status) + ")";
+}
+
+interface RecoveryScope {
+  token: string;
+  companyUid?: string;
+  personal: boolean;
+}
+
+async function resolveRecoveryScope(params: {
+  personal: boolean;
+  companySlug: string | undefined;
+}): Promise<RecoveryScope> {
+  assertRecoveryScope(params.personal, params.companySlug);
+  const token = await ensureCognitoToken();
+  if (params.personal) {
+    return { token, personal: true };
+  }
+  return {
+    token,
+    personal: false,
+    companyUid: await getCompanyUid(token, params.companySlug),
+  };
+}
+
+export async function runFilesVersions(params: {
+  key: string;
+  personal: boolean;
+  companySlug: string | undefined;
+}): Promise<FilesVersionsResponse> {
+  assertExactRecoveryKey(params.key);
+  const scope = await resolveRecoveryScope(params);
+  const res = await vaultApiFetch({
+    token: scope.token,
+    path: "/v1/files/versions",
+    query: scope.personal
+      ? { personal: "1", key: params.key }
+      : { company: scope.companyUid!, key: params.key },
+  });
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throwRecoveryHttpError(res.status, body, res.statusText);
+  }
+  const data = (await res.json()) as FilesVersionsResponse;
+  console.log(chalk.green("Versions for '" + data.key + "':"));
+  console.log(formatFilesVersionsTable(data.versions));
+  return data;
+}
+
+export async function runFilesRestore(
+  params: {
+    key: string;
+    versionId?: string;
+    yes: boolean;
+    personal: boolean;
+    companySlug: string | undefined;
+  },
+  deps: { confirm?: ConfirmFn } = {},
+): Promise<FilesRestoreResponse | undefined> {
+  assertExactRecoveryKey(params.key);
+  if (params.versionId !== undefined && params.versionId.trim() === "") {
+    throw new Error("versionId must not be empty.");
+  }
+
+  const confirm = deps.confirm ?? realConfirm;
+  if (!params.yes) {
+    const ok = await confirm(
+      params.personal
+        ? "Restore '" + params.key + "' in your personal vault? This overwrites current content."
+        : "Restore '" + params.key + "'? This overwrites current content in the shared vault.",
+    );
+    if (!ok) {
+      console.log(chalk.dim("Aborted — nothing was restored."));
+      return undefined;
+    }
+  }
+
+  const scope = await resolveRecoveryScope(params);
+  const body: Record<string, unknown> = scope.personal
+    ? { personal: true, key: params.key }
+    : { company: scope.companyUid, key: params.key };
+  if (params.versionId !== undefined) body.versionId = params.versionId;
+  const res = await vaultApiFetch({
+    token: scope.token,
+    path: "/v1/files/restore",
+    method: "POST",
+    body,
+  });
+  if (!res.ok) {
+    const errBody = (await res.json().catch(() => ({}))) as Record<string, string>;
+    const err = new FilesRecoveryHttpError(
+      res.status,
+      errBody.message ?? errBody.error ?? res.statusText,
+      errBody.code,
+    );
+    throw new Error(formatFilesRecoveryError(err, params.key));
+  }
+  const data = (await res.json()) as FilesRestoreResponse;
+  const verb = data.wasDeleted ? "Undeleted" : "Restored";
+  console.log(
+    chalk.green(
+      verb + " '" + data.key + "' from version '" + data.restoredFromVersionId + "'.",
+    ),
+  );
+  console.log(chalk.dim("New version: " + data.newVersionId));
+  return data;
+}
+
+export async function runFilesTrash(params: {
+  prefix: string;
+  cursor?: string;
+  personal: boolean;
+  companySlug: string | undefined;
+}): Promise<FilesTrashResponse> {
+  if (params.prefix.includes("*")) {
+    throw new Error("Trash prefix must be literal; wildcard expansion is not supported.");
+  }
+  const scope = await resolveRecoveryScope(params);
+  const query: Record<string, string> = scope.personal
+    ? { personal: "1" }
+    : { company: scope.companyUid! };
+  if (params.prefix) query.prefix = params.prefix;
+  if (params.cursor) query.cursor = params.cursor;
+  const res = await vaultApiFetch({
+    token: scope.token,
+    path: "/v1/files/tombstones",
+    query,
+  });
+  if (!res.ok) {
+    const body = (await res.json().catch(() => ({}))) as Record<string, string>;
+    throwRecoveryHttpError(res.status, body, res.statusText);
+  }
+  const data = (await res.json()) as FilesTrashResponse;
+  console.log(formatFilesTrashTable(data.tombstones));
+  if (data.truncated && data.cursor) {
+    let continuation = "hq files";
+    if (params.companySlug) {
+      continuation += " --company " + quoteRecoveryShellArg(params.companySlug);
+    }
+    continuation += " trash";
+    if (params.personal) continuation += " --personal";
+    if (params.prefix) {
+      continuation += " --prefix " + quoteRecoveryShellArg(params.prefix);
+    }
+    continuation += " --cursor " + quoteRecoveryShellArg(data.cursor);
+    console.log(chalk.dim("More results: " + continuation));
+  }
+  return data;
+}

package/src/commands/mcp-registration.ts

@@ -1071,7 +1071,8 @@ function restoreSafely(realTarget: string, backupDir: string): boolean {
 //
 // SECRET SAFETY (the hard rule from the PRD authModel / US-002 AC):
 //   - `${secret:NAME}` resolves ONLY here, at emit, via the injected
-//     {@link SecretResolver} (production = the AES-256-GCM `secrets-cache.ts`).
+//     {@link SecretResolver}. Production injects values returned by a fresh
+//     server authorization; the encrypted disk cache is never a value fallback.
 //   - The RESOLVED value lands in `~/.claude.json` — a 0600 user-global file that
 //     is NOT synced/committed — because the runtime needs the real header to work.
 //   - The resolved value is REDACTED from every return value and never echoed; we
@@ -1105,11 +1106,10 @@ export interface McpManifest {
 /**
  * Resolve a `${secret:NAME}` reference to its plaintext value, or return `null`
  * when the secret is unavailable (un-minted / TTL-expired / no company context).
- * Production binds this to `secrets-cache.ts` (`readCache(companyUid, NAME)`,
- * AES-256-GCM, 0600, 5-min TTL); TESTS inject a pure map so they NEVER read the
- * real encrypted cache. Returning `null` for a referenced secret is a hard error
- * at emit (we refuse to write a broken header), distinct from a name with no
- * reference at all.
+ * Production binds this to an in-memory map populated by a fresh vault `/load`
+ * authorization response; tests inject a pure map. Returning `null` for a
+ * referenced secret is a hard error at emit (we refuse to write a broken
+ * header), distinct from a name with no reference at all.
  */
 export type SecretResolver = (name: string) => string | null;
 
@@ -1146,9 +1146,9 @@ export function resolveSecretRefs(
     const resolved = resolve(name);
     if (resolved === null || resolved === undefined) {
       throw new McpManifestError(
-        `cannot resolve \${secret:${name}} at emit — the secret is not in the cache ` +
-          '(mint it via the pack onboarding / `hq run`, then re-install). HQ refuses to ' +
-          'write a half-resolved header.',
+        `cannot resolve \${secret:${name}} at emit — the secret was not available ` +
+          'after online vault authorization (check login, company scope, and access, ' +
+          'then re-install). HQ refuses to write a half-resolved header.',
       );
     }
     if (resolved.length > 0) secretSink.add(resolved);