instant-cli 1.0.60 → 1.0.61

package/src/commands/backup/list.ts

@@ -0,0 +1,94 @@
+import chalk from 'chalk';
+import { Effect } from 'effect';
+import { formatFileSize, type AppBackup } from '@instantdb/platform';
+import type { backupListDef, OptsFromCommand } from '../../index.ts';
+import { useBackupsManager } from '../../lib/backups.ts';
+
+export const formatBackupDate = (date: Date) =>
+  `${date.toISOString().replace('T', ' ').slice(0, 16)} UTC`;
+
+// Backup descriptions are user-controlled text headed for the terminal;
+// strip control characters so a crafted value can't inject escape sequences.
+export const stripControlChars = (s: string) => s.replace(/\p{Cc}/gu, '');
+
+// Relative times in both directions: "3 hours ago", "6 days from now".
+export const relativeTime = (date: Date): string => {
+  const diffMs = date.getTime() - Date.now();
+  const abs = Math.abs(diffMs);
+  if (abs < 60_000) return diffMs <= 0 ? 'just now' : 'now';
+  const minutes = Math.round(abs / 60_000);
+  const hours = Math.round(abs / 3_600_000);
+  const days = Math.round(abs / 86_400_000);
+  const [count, unit] =
+    minutes < 60
+      ? [minutes, 'minute']
+      : hours < 24
+        ? [hours, 'hour']
+        : [days, 'day'];
+  const label = `${count} ${unit}${count === 1 ? '' : 's'}`;
+  return diffMs < 0 ? `${label} ago` : `${label} from now`;
+};
+
+// One aligned row per backup, newest first: id first, relative times.
+// `--json` carries the precise values.
+export const renderBackupsTable = (backups: AppBackup[]) =>
+  Effect.gen(function* () {
+    const header = [
+      'ID',
+      'CREATED AT',
+      'DB SIZE',
+      'STORAGE',
+      'EXPIRES AT',
+      'DESCRIPTION',
+    ];
+    const rows = backups.map((backup) => [
+      backup.id,
+      relativeTime(backup.backupAt),
+      backup.dbSize != null ? formatFileSize(backup.dbSize) : '-',
+      backup.filesSize != null ? formatFileSize(backup.filesSize) : '-',
+      backup.expiresAt
+        ? backup.expiresAt.getTime() <= Date.now()
+          ? 'expired'
+          : relativeTime(backup.expiresAt)
+        : '-',
+      backup.description ? stripControlChars(backup.description) : '',
+    ]);
+    const widths = header.map((h, i) =>
+      Math.max(h.length, ...rows.map((row) => row[i].length)),
+    );
+    const line = (cells: string[]) =>
+      cells
+        .map((cell, i) => cell.padEnd(widths[i]))
+        .join('  ')
+        .trimEnd();
+    yield* Effect.log(chalk.dim(line(header)));
+    yield* Effect.log(chalk.dim(widths.map((w) => '-'.repeat(w)).join('  ')));
+    for (const row of rows) {
+      yield* Effect.log(line(row));
+    }
+  });
+
+export const backupListCmd = Effect.fn(function* (
+  opts: OptsFromCommand<typeof backupListDef>,
+) {
+  const backups = yield* useBackupsManager(
+    (m) => m.list(),
+    'Error listing backups',
+  );
+
+  if (opts.json) {
+    yield* Effect.log(JSON.stringify(backups, null, 2));
+    return;
+  }
+
+  if (backups.length === 0) {
+    yield* Effect.log('No backups yet.');
+    return;
+  }
+
+  // The server returns newest first; sort anyway so the table can't lie.
+  const sorted = [...backups].sort(
+    (a, b) => b.backupAt.getTime() - a.backupAt.getTime(),
+  );
+  yield* renderBackupsTable(sorted);
+});

package/src/index.ts

@@ -51,6 +51,8 @@ import { webhooksEventsResendCmd } from './commands/webhooks/events/resend.ts';
 import { emailStatusCmd } from './commands/auth/email/status.ts';
 import { verifyCmd } from './commands/auth/email/verify.ts';
 import { resendEmailCmd } from './commands/auth/email/resend.ts';
+import { backupListCmd } from './commands/backup/list.ts';
+import { backupDownloadCmd } from './commands/backup/download.ts';
 
 export type OptsFromCommand<C> =
   C extends Command<any, infer R, any> ? R : never;
@@ -640,6 +642,64 @@ export const webhooksEventsPayloadDef = webhooksEvents
     );
   });
 
+const backup = program
+  .command('backup')
+  .description('View and download backups of your app');
+
+export const backupListDef = backup
+  .command('list')
+  .description('List downloadable backups for an app')
+  .option(
+    '-a --app <app-id>',
+    'App ID to list backups for. Defaults to *_INSTANT_APP_ID in .env',
+  )
+  .option('--json', 'Output backups as JSON')
+  .action((opts) => {
+    return runCommandEffect(
+      backupListCmd(opts).pipe(
+        Effect.provide(
+          WithAppLayer({
+            coerce: false,
+            coerceAuth: false,
+            appId: opts.app,
+            allowAdminToken: true,
+          }).pipe(Layer.annotateLogs('silent', !!opts.json)),
+        ),
+      ),
+    );
+  });
+
+export const backupDownloadDef = backup
+  .command('download')
+  .description('Download a backup as a zip file')
+  .argument(
+    '[backup-id]',
+    'Backup ID to download. Defaults to an interactive picker',
+  )
+  .option(
+    '-a --app <app-id>',
+    'App ID to download a backup of. Defaults to *_INSTANT_APP_ID in .env',
+  )
+  .option('--latest', 'Download the most recent backup')
+  .option(
+    '-o --out <path>',
+    'Output zip path. Defaults to instant-backup-<timestamp>.zip',
+  )
+  .action((backupId, opts) => {
+    return runCommandEffect(
+      backupDownloadCmd(backupId, opts).pipe(
+        Effect.provide(
+          WithAppLayer({
+            coerce: false,
+            coerceAuth: false,
+            appId: opts.app,
+            allowAdminToken: true,
+          }),
+        ),
+      ),
+    );
+  });
+
 const authEmail = auth
   .command('email')
   .description('Manage custom magic code email templates');

package/src/lib/backupDownload.ts

@@ -0,0 +1,145 @@
+import { createWriteStream } from 'node:fs';
+import { open, rename, unlink } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { once } from 'node:events';
+import { get as httpGet, type IncomingMessage } from 'node:http';
+import { get as httpsGet } from 'node:https';
+import { Readable, Writable, type Duplex } from 'node:stream';
+import zlib from 'node:zlib';
+import type {
+  AppBackup,
+  BackupArchiveWriter,
+  BackupDownloadProgress,
+  BackupDownloadResult,
+  BackupsManager,
+} from '@instantdb/platform';
+
+export type {
+  BackupDownloadProgress,
+  BackupDownloadResult,
+} from '@instantdb/platform';
+
+// zstd landed in node:zlib in 22.15 / 23.8; on older Nodes the property is
+// absent, so feature-detect instead of assuming the type declarations match
+// the runtime.
+const createZstdDecompress: (() => Duplex) | undefined = (
+  zlib as { createZstdDecompress?: () => Duplex }
+).createZstdDecompress;
+
+function fetchStream(
+  url: string,
+  signal: AbortSignal,
+): Promise<IncomingMessage> {
+  return new Promise((resolve, reject) => {
+    const get = url.startsWith('https:') ? httpsGet : httpGet;
+    const req = get(url, { signal }, resolve);
+    req.on('error', reject);
+  });
+}
+
+// .pipe doesn't forward errors, so a source failure would otherwise leave the
+// destination (and the zip writer reading from it) hanging forever.
+function pipe(src: Readable, dst: Duplex): Duplex {
+  src.on('error', (e) => dst.destroy(e));
+  return src.pipe(dst);
+}
+
+// Fetches a presigned URL with node:http(s), decompressing explicitly: the
+// entity shards are served with `Content-Encoding: zstd` and Node doesn't
+// auto-decompress that. downloadBackupToFile refuses to run without zstd
+// support, so the assertion below can't fire.
+async function fetchBody(
+  url: string,
+  signal: AbortSignal,
+): Promise<ReadableStream<Uint8Array>> {
+  const res = await fetchStream(url, signal);
+  if (res.statusCode !== 200) {
+    res.resume();
+    throw new Error(`HTTP ${res.statusCode}`);
+  }
+  const encoding = res.headers['content-encoding'];
+  let stream: Readable = res;
+  if (encoding === 'zstd') {
+    stream = pipe(stream, createZstdDecompress!());
+  } else if (encoding === 'gzip') {
+    stream = pipe(stream, zlib.createGunzip());
+  } else if (encoding) {
+    res.destroy();
+    throw new Error(`Unsupported content encoding: ${encoding}`);
+  }
+  return Readable.toWeb(stream) as ReadableStream<Uint8Array>;
+}
+
+async function createZipWriter(
+  sink: WritableStream<Uint8Array>,
+  signal: AbortSignal,
+): Promise<BackupArchiveWriter> {
+  // Loaded on demand so every other CLI command skips parsing it.
+  const { ZipWriter } = await import('@zip.js/zip.js');
+  // zip64: without it any archive whose central-directory offset passes 4GB
+  // writes a wrapped 32-bit offset and the zip is unreadable.
+  return new ZipWriter(sink, { zip64: true, signal });
+}
+
+/**
+ * Downloads a backup into a zip file at `outPath` via the shared
+ * `BackupsManager.downloadArchive` pipeline, supplying the Node-specific
+ * pieces:
+ * presigned URLs are fetched with node:http(s) and decompressed explicitly,
+ * and the archive streams to disk with backpressure so memory stays flat
+ * regardless of backup size.
+ *
+ * Writes to `<outPath>.partial` and renames on success; a failed or aborted
+ * download removes the partial file.
+ */
+export async function downloadBackupToFile(opts: {
+  manager: BackupsManager;
+  backup: AppBackup;
+  outPath: string;
+  signal: AbortSignal;
+  onProgress: (progress: BackupDownloadProgress) => void;
+}): Promise<BackupDownloadResult> {
+  // The entity shards are served with `Content-Encoding: zstd`; fail before
+  // writing anything if this Node can't decompress them.
+  if (!createZstdDecompress) {
+    throw new Error(
+      'Downloading backups requires Node 22.15 or newer (for zstd support).',
+    );
+  }
+
+  // Randomized so a stale partial or a concurrent download of the same
+  // backup can't collide; 'wx' turns any remaining collision into an error
+  // instead of silently truncating another run's file.
+  const partialPath = `${opts.outPath}.partial-${randomBytes(4).toString('hex')}`;
+  const fileStream = createWriteStream(partialPath, { flags: 'wx' });
+  const awaitFileClosed = async () => {
+    if (!fileStream.closed) await once(fileStream, 'close');
+  };
+  try {
+    const result = await opts.manager.downloadArchive({
+      backup: opts.backup,
+      fetchBody,
+      sink: Writable.toWeb(fileStream) as WritableStream<Uint8Array>,
+      createWriter: createZipWriter,
+      signal: opts.signal,
+      onProgress: opts.onProgress,
+    });
+    await awaitFileClosed();
+    // Flush to disk before the rename so a crash right after can't leave a
+    // complete-looking zip with unwritten tails.
+    const fh = await open(partialPath, 'r+');
+    try {
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    await rename(partialPath, opts.outPath);
+    return result;
+  } catch (e) {
+    // The pipeline already aborted the sink; wait for the fd to close, then
+    // discard the partial file on disk.
+    await awaitFileClosed().catch(() => {});
+    await unlink(partialPath).catch(() => {});
+    throw e;
+  }
+}

package/src/lib/backups.ts

@@ -0,0 +1,33 @@
+import { Effect } from 'effect';
+import type { BackupsManager } from '@instantdb/platform';
+import { CurrentApp } from '../context/currentApp.ts';
+import { PlatformApiError } from '../context/platformApi.ts';
+import { getAuthedPlatformApi } from './platformApi.ts';
+
+export const useBackupsManager = <R>(
+  fun: (manager: BackupsManager) => Promise<R>,
+  errorMessage?: string,
+) =>
+  Effect.gen(function* () {
+    const api = yield* getAuthedPlatformApi;
+    const { appId } = yield* CurrentApp;
+    return yield* Effect.tryPromise({
+      try: () => fun(api.backups(appId)),
+      catch: (e) =>
+        new PlatformApiError({
+          message: errorMessage ?? 'Error using backups api',
+          cause: e,
+        }),
+    });
+  });
+
+/**
+ * Yields a `BackupsManager` instance scoped to the current app. Use when you
+ * need to hold on to the manager outside an Effect (e.g. to drive the
+ * long-running download pipeline).
+ */
+export const buildBackupsManager = Effect.gen(function* () {
+  const api = yield* getAuthedPlatformApi;
+  const { appId } = yield* CurrentApp;
+  return api.backups(appId);
+});

package/src/lib/platformApi.ts

@@ -0,0 +1,11 @@
+import { Effect } from 'effect';
+import { PlatformApi as InstantPlatformApi } from '@instantdb/platform';
+import { AuthToken } from '../context/authToken.ts';
+import { getBaseUrl } from './config.ts';
+
+export const getAuthedPlatformApi = Effect.gen(function* () {
+  const apiURI = yield* getBaseUrl;
+  const authToken = yield* AuthToken;
+  const token = yield* authToken.getAuthToken;
+  return new InstantPlatformApi({ apiURI, auth: { token } });
+});

package/src/lib/webhooks.ts

@@ -1,22 +1,13 @@
 import { Effect } from 'effect';
 import {
-  PlatformApi as InstantPlatformApi,
   type WebhookAction,
   type WebhookEventInfo,
   type WebhooksManager,
 } from '@instantdb/platform';
-import { AuthToken } from '../context/authToken.ts';
 import { CurrentApp } from '../context/currentApp.ts';
 import { PlatformApiError } from '../context/platformApi.ts';
 import { BadArgsError } from '../errors.ts';
-import { getBaseUrl } from './http.ts';
-
-const getAuthedPlatformApi = Effect.gen(function* () {
-  const apiURI = yield* getBaseUrl;
-  const authToken = yield* AuthToken;
-  const token = yield* authToken.getAuthToken;
-  return new InstantPlatformApi({ apiURI, auth: { token } });
-});
+import { getAuthedPlatformApi } from './platformApi.ts';
 
 export const WEBHOOK_ACTIONS: readonly WebhookAction[] = [
   'create',

package/src/ui/lib.ts

@@ -372,7 +372,7 @@ let terminateHandler:
   | undefined;
 
 export function onTerminate(
-  callback: (stdin: ReadStream, stdout: WriteStream) => void | undefined,
+  callback: ((stdin: ReadStream, stdout: WriteStream) => void) | undefined,
 ) {
   terminateHandler = callback;
 }