data-ark 0.1.1 → 0.1.2

package/README.md

@@ -7,6 +7,9 @@ Split large files into 1.8GB chunks, store them on Telegram, and restore them in
 ```bash
 npx data-ark login                        # once only
 npx data-ark data.tar --to @my_backups    # the destination is remembered
+npx data-ark --to @my_backups             # only change the destination, upload nothing
+npx data-ark status                       # account, destination, unfinished backups
+npx data-ark list                         # what is already stored in the destination
 npx data-ark data.tar                     # from the second run on
 npx data-ark restore ark-20260905-7f3a91
 ```
@@ -22,10 +25,46 @@ data-ark signs in with your own Telegram account (MTProto), not a bot. That is a
 
 | Flag | Default | Meaning |
 |---|---|---|
-| `--to <chat>` | the remembered destination | `@username`, `-100123…`, or `me` |
+| `--to <chat>` | the remembered destination | `@username`, `-100123…`, or `me`. `upload` and `status` remember it; `list` and `restore` only look there. A negative channel id works either way: `--to -100123…` or `--to=-100123…` |
 | `--chunk-size <n>` | `1800MB` | e.g. `1.8GB`, `500MB`. Hard ceiling 1950MB. |
 | `--concurrency <n>` | `8` | 512KB parts sent in parallel. An integer from 1 to 64. |
 | `--out <path>` | the basename from the manifest | Where to write the restored file; relative paths resolve against the current directory |
+| `--limit <n>` | `20` | How many backups `list` shows, newest first |
+| `--verbose` | off | Show the Telegram client's own connection logs, hidden by default so they do not break up the progress bar |
+
+## What the chat looks like
+
+Every chunk goes up as a document captioned `📦 <backupId> · 3/12`, and the manifest that
+follows carries a summary card:
+
+```
+🗄 data.tar
+━━━━━━━━━━━━━━━
+💾 21.4 GB · 12 chunks
+🆔 ark-20260905-7f3a91
+📅 2026-09-05 16:40 UTC
+
+↩ npx data-ark restore ark-20260905-7f3a91
+#dataark
+```
+
+`npx data-ark list` reads those cards straight out of the chat — one search, no downloads —
+and lays them out as a table:
+
+```
+Destination  https://web.telegram.org/k/#@my_backups
+
+BACKUP ID            FILE            SIZE  CHUNKS  CREATED
+ark-20260905-7f3a91  data.tar     21.4 GB      12  2026-09-05
+ark-20260901-9de447  photos.zip  940.3 MB       1  2026-09-01
+
+2 backups. Restore with: npx data-ark restore <backup-id>
+```
+
+A backup uploaded before the card existed still gets a row, with dashes where the caption
+says nothing — `list` reports what the chat holds and never fills gaps with guesses.
+`--to` here only chooses which chat to look at; it does not move the destination the way
+`status --to` does.
 
 ## How it works
 

package/bin/data-ark.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 import { route, HELP } from '../src/cli.js'
 import { runLogin } from '../src/commands/login.js'
+import { runList } from '../src/commands/list.js'
 import { runLogout } from '../src/commands/logout.js'
 import { runRestore } from '../src/commands/restore.js'
+import { runSetDestination } from '../src/commands/set-destination.js'
+import { runStatus } from '../src/commands/status.js'
 import { runUpload } from '../src/commands/upload.js'
 
 const SIGINT_EXIT_CODE = 130
@@ -47,13 +50,25 @@ async function main() {
       return
 
     case 'login':
-      await runLogin()
+      await runLogin({ verbose: parsed.options.verbose })
       return
 
     case 'logout':
       await runLogout()
       return
 
+    case 'list':
+      await runList(parsed.options)
+      return
+
+    case 'status':
+      await runStatus(parsed.options)
+      return
+
+    case 'set-destination':
+      await runSetDestination(parsed.options)
+      return
+
     case 'upload':
       await runUpload(parsed.args[0], parsed.options)
       return

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "data-ark",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Split large files into chunks and store them on Telegram",
   "keywords": [
     "telegram",

package/src/caption.js

@@ -0,0 +1,63 @@
+import { formatBytes } from './progress.js'
+
+// Captions are plain text on purpose. Telegram would render bold through a parse mode,
+// but that turns every file name into something that has to be escaped correctly, and
+// the fake client the tests talk to would never notice a mistake there.
+
+const DIVIDER = '━'.repeat(15)
+
+// The hashtag is what `list` searches for, and it lives on the manifest alone: chunk
+// captions stay out of that search so a twelve-chunk backup is one hit, not thirteen.
+export const MANIFEST_TAG = '#dataark'
+
+// A file name may legally contain a newline or a tab, and either one would push the
+// rest of the card down a row and take its shape apart.
+function oneLine(name) {
+  return String(name).replace(/\s+/g, ' ').trim()
+}
+
+function utcMinutes(createdAt) {
+  return `${new Date(createdAt).toISOString().slice(0, 16).replace('T', ' ')} UTC`
+}
+
+export function chunkCaption({ id, number, total }) {
+  return `📦 ${id} · ${number}/${total}`
+}
+
+export function manifestCaption({ id, name, size, chunks, createdAt }) {
+  return [
+    `🗄 ${oneLine(name)}`,
+    DIVIDER,
+    `💾 ${formatBytes(size)} · ${chunks} chunk${chunks === 1 ? '' : 's'}`,
+    `🆔 ${id}`,
+    `📅 ${utcMinutes(createdAt)}`,
+    '',
+    `↩ npx data-ark restore ${id}`,
+    MANIFEST_TAG,
+  ].join('\n')
+}
+
+function marker(lines, emoji) {
+  const found = lines.find((line) => line.startsWith(`${emoji} `))
+  return found ? found.slice(emoji.length + 1).trim() : null
+}
+
+// list reads what the chat shows, and a caption is text a person can edit. Anything that
+// does not carry the whole card is reported as unknown rather than half-guessed: a backup
+// listed with invented numbers is worse than one listed with dashes.
+export function parseManifestCaption(text) {
+  const lines = String(text ?? '').split('\n')
+
+  const name = marker(lines, '🗄')
+  const totals = marker(lines, '💾')
+  const id = marker(lines, '🆔')
+  const createdAt = marker(lines, '📅')
+
+  if (!name || !totals || !id || !createdAt) return null
+
+  const match = /^(.+) · (\d+) chunks?$/.exec(totals)
+
+  if (!match) return null
+
+  return { id, name, size: match[1], chunks: Number(match[2]), createdAt }
+}

package/src/chunking.js

@@ -36,6 +36,12 @@ export function parseSize(input) {
   return bytes
 }
 
+// How many chunks a file of this size splits into. planChunks builds them and parseManifest
+// checks them against this same rule, so the layout has one definition, not three.
+export function countChunks(fileSize, chunkSize) {
+  return Math.ceil(fileSize / chunkSize)
+}
+
 export function planChunks(fileSize, chunkSize) {
   if (fileSize <= 0) {
     throw new Error('File is empty, nothing to upload.')

package/src/cli.js

@@ -1,12 +1,14 @@
 import { parseArgs } from 'node:util'
 
-const SUBCOMMANDS = new Set(['login', 'logout', 'restore', 'help'])
+const SUBCOMMANDS = new Set(['login', 'logout', 'list', 'restore', 'status', 'help'])
 
 const OPTIONS = {
   to: { type: 'string' },
   'chunk-size': { type: 'string' },
   concurrency: { type: 'string' },
   out: { type: 'string' },
+  limit: { type: 'string' },
+  verbose: { type: 'boolean' },
   help: { type: 'boolean', short: 'h' },
 }
 
@@ -15,26 +17,64 @@ export const HELP = `data-ark — split large files into chunks and store them o
 Usage:
   npx data-ark login                        Log in to Telegram, only needed once
   npx data-ark <file>                       Split a file and upload it to Telegram
+  npx data-ark list                         List the backups stored in the destination
   npx data-ark restore <backup-id>          Download the chunks and reassemble the file
+  npx data-ark status                       Show the account, the destination and unfinished backups
+  npx data-ark --to <chat>                  Set the destination without uploading anything
   npx data-ark logout                       Remove the saved session
 
 Options:
-  --to <chat>            Destination: @username, -100123..., or me. Remembered for next time.
+  --to <chat>            Destination: @username, -100123..., or me. upload and status
+                         remember it; list and restore only look there.
   --chunk-size <n>       Size of each chunk, default 1800MB. Examples: 1.8GB, 500MB.
   --concurrency <n>      512KB parts sent in parallel, default 8, max 64.
   --out <path>           Where to write the restored file. Defaults to the basename in the manifest.
+  --limit <n>            How many backups list shows, default 20.
+  --verbose              Show Telegram connection logs, hidden by default.
   -h, --help             Show this help.
 `
 
+// A channel id is negative, and typing it separated by a space is the natural reflex —
+// but parseArgs rejects any value starting with a dash as ambiguous. Join the pair itself
+// so `--to -100123` works like `--to=-100123`. Only a bare negative integer qualifies, so
+// `--to --verbose` still reports the missing value instead of eating the next flag, and
+// everything after `--` is left alone because it is no longer an option there.
+function joinNegativeChatId(argv) {
+  const joined = []
+
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--') {
+      joined.push(...argv.slice(i))
+      return joined
+    }
+
+    if (argv[i] === '--to' && /^-\d+$/.test(argv[i + 1] ?? '')) {
+      joined.push(`--to=${argv[i + 1]}`)
+      i += 1
+      continue
+    }
+
+    joined.push(argv[i])
+  }
+
+  return joined
+}
+
 export function route(argv) {
   const { values, positionals } = parseArgs({
-    args: argv,
+    args: joinNegativeChatId(argv),
     options: OPTIONS,
     allowPositionals: true,
   })
 
   const [first, ...rest] = positionals
 
+  // `data-ark --to @chan` with no file is not a malformed upload, it is someone changing
+  // where the next upload goes. Help would be an unhelpful answer to a clear request.
+  if (first === undefined && values.to && !values.help) {
+    return { command: 'set-destination', args: [], options: values }
+  }
+
   if (values.help || first === undefined || first === 'help') {
     return { command: 'help', args: [], options: values }
   }

package/src/client.js

@@ -1,6 +1,16 @@
-import { TelegramClient } from 'telegram'
+import { Api, TelegramClient } from 'telegram'
+import { Logger } from 'telegram/extensions/index.js'
+import { LogLevel } from 'telegram/extensions/Logger.js'
 import { StringSession } from 'telegram/sessions/index.js'
 
+// GramJS narrates its version, every connection and every disconnect at info level, and
+// those timestamped lines land in the middle of the progress bar. The client reads this
+// logger before it prints anything, so LogLevel.NONE silences all of it; --verbose asks
+// for the running commentary back when a connection needs diagnosing.
+export function createLogger(verbose) {
+  return new Logger(verbose ? LogLevel.INFO : LogLevel.NONE)
+}
+
 export function normalizeChatTarget(input) {
   const text = String(input).trim()
 
@@ -15,6 +25,71 @@ export function normalizeChatTarget(input) {
   return text
 }
 
+// Telegram's web client addresses a chat by putting the raw target in the fragment, which
+// covers both a negative channel id and an @username. Saved Messages is the exception: it
+// is reached by the account's own id, which data-ark does not know, so it gets no link
+// rather than a guessed one that lands somewhere else.
+export function chatUrl(chat) {
+  const text = String(chat)
+
+  if (text === 'me') return null
+
+  return `https://web.telegram.org/k/#${text}`
+}
+
+// How a destination is spoken about. "me" is a target, not a name someone would recognise
+// in a sentence, so every command that mentions a chat in prose goes through here.
+export function chatName(chat) {
+  return String(chat) === 'me' ? 'Saved Messages' : String(chat)
+}
+
+// A destination is worth more as something clickable than as a raw id, but Saved Messages
+// has no link to give, so it is named instead of being dressed up as one.
+export function describeChat(chat) {
+  const url = chatUrl(chat)
+
+  return url ?? `${chat} (${chatName(chat)})`
+}
+
+// The name Telegram shows under a document lives in an attribute, not on the message.
+export function documentFileName(message) {
+  const attributes = message?.media?.document?.attributes ?? []
+  const named = attributes.find((a) => a instanceof Api.DocumentAttributeFilename)
+  return named?.fileName ?? null
+}
+
+// The one place data-ark searches a chat. Both callers want documents and nothing else,
+// and getMessages is preferred over a raw Api.messages.Search because it handles offsets,
+// hashes and pagination itself, so we don't hand-build easily mistyped fields. The raw
+// message is kept alongside the flat fields because downloading needs it whole.
+export async function searchDocuments(client, peer, { search, limit }) {
+  const messages = await client.getMessages(peer, {
+    search,
+    filter: new Api.InputMessagesFilterDocument(),
+    limit,
+  })
+
+  return messages.map((message) => ({
+    id: message.id,
+    fileName: documentFileName(message),
+    caption: message.message ?? '',
+    date: message.date,
+    message,
+  }))
+}
+
+// Every command ends by putting the connection down, and a failure there must never
+// swallow the real error already on its way up. Commands that print progress hand in an
+// onWarn to say so; the quieter ones let it pass, because a connection that will not
+// close cleanly says nothing about the work that already succeeded.
+export async function closeQuietly(client, disconnect, onWarn) {
+  try {
+    await disconnect(client)
+  } catch (err) {
+    if (onWarn) onWarn(err)
+  }
+}
+
 export function requireChat(options, config) {
   const raw = options.to ?? config.defaultChat
 
@@ -34,12 +109,13 @@ export function assertLoggedIn(config) {
   }
 }
 
-export async function connect(config) {
+export async function connect(config, { verbose = false } = {}) {
   assertLoggedIn(config)
 
   const client = new TelegramClient(new StringSession(config.session), config.apiId, config.apiHash, {
     connectionRetries: 5,
     floodSleepThreshold: 60,
+    baseLogger: createLogger(verbose),
   })
 
   await client.connect()

package/src/commands/list.js

@@ -0,0 +1,136 @@
+import { MANIFEST_TAG, parseManifestCaption } from '../caption.js'
+import {
+  assertLoggedIn,
+  chatName,
+  closeQuietly,
+  connect as realConnect,
+  describeChat,
+  requireChat,
+  searchDocuments,
+} from '../client.js'
+import { defaultConfigDir, loadConfig } from '../config.js'
+
+export const DEFAULT_LIMIT = 20
+
+const UNKNOWN = '—'
+const GAP = '  '
+
+const COLUMNS = [
+  { header: 'BACKUP ID', key: 'id' },
+  { header: 'FILE', key: 'name' },
+  { header: 'SIZE', key: 'size', right: true },
+  { header: 'CHUNKS', key: 'chunks', right: true },
+  { header: 'CREATED', key: 'created' },
+]
+
+// Telegram indexes the tag the manifest caption carries, so one search returns one hit
+// per backup instead of one per chunk. What comes back is still whatever the server
+// decided to match, which is why the caller filters on the file name afterwards.
+async function realSearchManifests(client, peer, limit) {
+  return await searchDocuments(client, peer, { search: MANIFEST_TAG, limit })
+}
+
+function backupIdFromFileName(fileName) {
+  return fileName.replace(/\.manifest\.json$/, '')
+}
+
+function utcDay(unixSeconds) {
+  return new Date(unixSeconds * 1000).toISOString().slice(0, 10)
+}
+
+// The card is text in a chat, which means a person can edit or predate it. The id is the
+// one field restore cannot be wrong about, so it always comes from the file name data-ark
+// wrote; the caption only decorates. A card that cannot be read back leaves the rest
+// unknown, because inventing it would describe a backup that does not exist.
+function toRow(message) {
+  const id = backupIdFromFileName(message.fileName)
+  const card = parseManifestCaption(message.caption)
+
+  if (!card) {
+    return { id, name: UNKNOWN, size: UNKNOWN, chunks: UNKNOWN, created: utcDay(message.date) }
+  }
+
+  return {
+    id,
+    name: card.name,
+    size: card.size,
+    chunks: String(card.chunks),
+    created: card.createdAt.slice(0, 10),
+  }
+}
+
+function renderTable(rows) {
+  const widths = COLUMNS.map((column) =>
+    Math.max(column.header.length, ...rows.map((row) => row[column.key].length)),
+  )
+
+  const line = (cells) =>
+    cells
+      .map((cell, i) => (COLUMNS[i].right ? cell.padStart(widths[i]) : cell.padEnd(widths[i])))
+      .join(GAP)
+      .trimEnd()
+
+  return [
+    line(COLUMNS.map((column) => column.header)),
+    ...rows.map((row) => line(COLUMNS.map((column) => row[column.key]))),
+  ]
+}
+
+function parseLimit(raw) {
+  if (raw === undefined) return DEFAULT_LIMIT
+
+  const limit = Number(raw)
+
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new Error(`Invalid --limit: "${raw}". Must be a whole number of backups, 1 or more.`)
+  }
+
+  return limit
+}
+
+export async function runList(options = {}, deps = {}) {
+  const {
+    configDir = defaultConfigDir(),
+    connect = realConnect,
+    disconnect = (client) => client.destroy(),
+    searchManifests = realSearchManifests,
+    log = (line) => console.log(line),
+  } = deps
+
+  const limit = parseLimit(options.limit)
+  const config = await loadConfig(configDir)
+  // Ask about the login before the destination: telling someone who has never logged in
+  // to pick a chat sends them off after the wrong thing.
+  assertLoggedIn(config)
+  // Unlike status, --to here means "look over there", not "send there from now on":
+  // listing another chat should not quietly redirect the next upload.
+  const chat = requireChat(options, config)
+
+  const client = await connect(config, { verbose: options.verbose })
+
+  let found
+  try {
+    found = await searchManifests(client, chat, limit)
+  } finally {
+    await closeQuietly(client, disconnect)
+  }
+
+  log(`Destination  ${describeChat(chat)}`)
+  log('')
+
+  const rows = found
+    .filter((message) => message.fileName?.endsWith('.manifest.json'))
+    .map(toRow)
+
+  if (rows.length === 0) {
+    log(`No backups found in ${chatName(chat)}. Upload one with: npx data-ark <file>`)
+    return rows
+  }
+
+  for (const line of renderTable(rows)) log(line)
+
+  log('')
+  log(`${rows.length} backup${rows.length === 1 ? '' : 's'}. Restore with: npx data-ark restore <backup-id>`)
+
+  return rows
+}

package/src/commands/login.js

@@ -5,7 +5,7 @@ import { TelegramClient } from 'telegram'
 import { StringSession } from 'telegram/sessions/index.js'
 
 import { loadConfig, saveConfig, defaultConfigDir } from '../config.js'
-import { normalizeChatTarget } from '../client.js'
+import { createLogger, normalizeChatTarget } from '../client.js'
 
 function createPrompts() {
   const rl = readline.createInterface({ input: stdin, output: stdout })
@@ -33,10 +33,25 @@ export function describeLoginError(err) {
   return `${description} (${message})`
 }
 
-export async function runLogin({ configDir = defaultConfigDir(), prompts = createPrompts() } = {}) {
+// GramJS starts an update loop the moment a client connects, and that loop only stops when
+// destroy() marks the client destroyed. disconnect() alone leaves it pinging a socket that is
+// already closed: every ping fails with "Error: TIMEOUT" and asks the sender to reconnect,
+// printed straight over the destination question login asks after signing in. Every other
+// command shuts down the same way, and login is the seam tests need to reach it.
+const createTelegramClient = (apiId, apiHash, options) =>
+  new TelegramClient(new StringSession(''), apiId, apiHash, options)
+
+export async function runLogin({
+  configDir = defaultConfigDir(),
+  prompts = createPrompts(),
+  verbose = false,
+  createClient = createTelegramClient,
+  shutdown = (client) => client.destroy(),
+  log = (line) => console.log(line),
+} = {}) {
   const config = await loadConfig(configDir)
 
-  console.log('You need your own api_id and api_hash. Get them at https://my.telegram.org → API development tools.\n')
+  log('You need your own api_id and api_hash. Get them at https://my.telegram.org → API development tools.\n')
 
   const apiIdAnswer = (await prompts.ask(`api_id${config.apiId ? ` [${config.apiId}]` : ''}: `)).trim()
 
@@ -53,7 +68,10 @@ export async function runLogin({ configDir = defaultConfigDir(), prompts = creat
     throw new Error('Missing api_id or api_hash.')
   }
 
-  const client = new TelegramClient(new StringSession(''), apiId, apiHash, { connectionRetries: 5 })
+  const client = createClient(apiId, apiHash, {
+    connectionRetries: 5,
+    baseLogger: createLogger(verbose),
+  })
 
   await client.start({
     phoneNumber: () => prompts.ask('Phone number (e.g. +1...): '),
@@ -64,7 +82,7 @@ export async function runLogin({ configDir = defaultConfigDir(), prompts = creat
 
   const me = await client.getMe()
   const session = client.session.save()
-  await client.disconnect()
+  await shutdown(client)
 
   const chatAnswer = (
     await prompts.ask(
@@ -82,6 +100,6 @@ export async function runLogin({ configDir = defaultConfigDir(), prompts = creat
 
   await saveConfig(next, configDir)
 
-  console.log(`\nLogged in as ${me.username ? `@${me.username}` : me.firstName}.`)
-  console.log(`Config saved to ${configDir}/config.json`)
+  log(`\nLogged in as ${me.username ? `@${me.username}` : me.firstName}.`)
+  log(`Config saved to ${configDir}/config.json`)
 }

package/src/commands/restore.js

@@ -3,32 +3,17 @@ import path from 'node:path'
 import readline from 'node:readline/promises'
 import { stdin, stdout } from 'node:process'
 
-import { Api } from 'telegram'
-
-import { connect as realConnect, requireChat } from '../client.js'
+import { closeQuietly, connect as realConnect, requireChat, searchDocuments } from '../client.js'
 import { defaultConfigDir, loadConfig } from '../config.js'
 import { downloadToFile } from '../downloader.js'
 import { manifestFileName, parseManifest } from '../manifest.js'
 import { createProgress, formatBytes } from '../progress.js'
 
-function documentFileName(message) {
-  const attributes = message?.media?.document?.attributes ?? []
-  const named = attributes.find((a) => a instanceof Api.DocumentAttributeFilename)
-  return named?.fileName ?? null
-}
-
 async function realSearchManifest(client, peer, backupId) {
   const wanted = manifestFileName(backupId)
+  const found = await searchDocuments(client, peer, { search: backupId, limit: 100 })
 
-  // Use client.getMessages instead of a raw Api.messages.Search: it handles offsets,
-  // hashes and pagination itself, so we don't hand-build easily mistyped fields.
-  const messages = await client.getMessages(peer, {
-    search: backupId,
-    filter: new Api.InputMessagesFilterDocument(),
-    limit: 100,
-  })
-
-  return messages.find((m) => documentFileName(m) === wanted) ?? null
+  return found.find((doc) => doc.fileName === wanted)?.message ?? null
 }
 
 async function realReadMessageBytes(client, message) {
@@ -87,7 +72,7 @@ export async function runRestore(backupId, options = {}, deps = {}) {
   const log = silent ? () => {} : (line) => console.log(line)
   const warn = silent ? () => {} : writeErr
 
-  const client = await connect(config)
+  const client = await connect(config, { verbose: options.verbose })
 
   try {
     const manifestMessage = await searchManifest(client, chat, backupId)
@@ -136,13 +121,12 @@ export async function runRestore(backupId, options = {}, deps = {}) {
           )
         }
 
-        const progress = silent
-          ? { advance: () => {}, finish: () => {} }
-          : createProgress({
-              total: chunk.size,
-              label: `Chunk ${chunk.i + 1}/${manifest.chunks.length}`,
-              write: writeErr,
-            })
+        // warn is already the no-op when silent, and createProgress draws through nothing else.
+        const progress = createProgress({
+          total: chunk.size,
+          label: `Chunk ${chunk.i + 1}/${manifest.chunks.length}`,
+          write: warn,
+        })
 
         const { sha256, size } = await downloadChunk(
           client,
@@ -188,11 +172,8 @@ export async function runRestore(backupId, options = {}, deps = {}) {
 
     return { path: target, size: manifest.size }
   } finally {
-    // A failing disconnect must not swallow the real error already on its way up.
-    try {
-      await disconnect(client)
-    } catch (err) {
-      warn(`\nWarning: could not close the Telegram connection: ${err.message}\n`)
-    }
+    await closeQuietly(client, disconnect, (err) =>
+      warn(`\nWarning: could not close the Telegram connection: ${err.message}\n`),
+    )
   }
 }

package/src/commands/set-destination.js

@@ -0,0 +1,15 @@
+import { normalizeChatTarget } from '../client.js'
+import { defaultConfigDir, loadConfig, saveConfig } from '../config.js'
+
+export async function runSetDestination(options = {}, deps = {}) {
+  const { configDir = defaultConfigDir(), log = (line) => console.log(line) } = deps
+
+  // Normalize before touching the config: an unusable destination must not be written,
+  // or the next upload fails with an error about a value the user never really set.
+  const chat = normalizeChatTarget(options.to)
+  const config = await loadConfig(configDir)
+
+  await saveConfig({ ...config, defaultChat: String(chat) }, configDir)
+
+  log(`Destination set to ${chat}. It will be used for the next upload.`)
+}

package/src/commands/status.js

@@ -0,0 +1,93 @@
+import path from 'node:path'
+
+import { countChunks } from '../chunking.js'
+import { assertLoggedIn, closeQuietly, connect as realConnect, describeChat } from '../client.js'
+import { defaultConfigDir, loadConfig } from '../config.js'
+import { runSetDestination } from './set-destination.js'
+import { formatBytes } from '../progress.js'
+import { listStates } from '../state.js'
+
+const LABEL_WIDTH = 'Destination'.length + 2
+
+function row(label, value) {
+  return `${label.padEnd(LABEL_WIDTH)}${value}`
+}
+
+function describeAccount(me) {
+  const name = [me.firstName, me.lastName].filter(Boolean).join(' ')
+  const handle = me.username ? ` (@${me.username})` : ''
+
+  return `${name || me.username || me.phone || 'unknown'}${handle}`
+}
+
+// The account line is the only part that needs Telegram, and it is also the only part that
+// can fail. Whatever it costs, it must not take the rest of the report down with it: the
+// unfinished backups are exactly what someone runs status to see after a session expires.
+async function accountLine(config, options, deps) {
+  const { connect, disconnect } = deps
+
+  try {
+    assertLoggedIn(config)
+  } catch (err) {
+    return err.message
+  }
+
+  let client
+  try {
+    client = await connect(config, { verbose: options.verbose })
+  } catch (err) {
+    return err.message
+  }
+
+  try {
+    return describeAccount(await client.getMe())
+  } catch (err) {
+    return `could not be read: ${err.message}`
+  } finally {
+    await closeQuietly(client, disconnect)
+  }
+}
+
+export async function runStatus(options = {}, deps = {}) {
+  const {
+    configDir = defaultConfigDir(),
+    connect = realConnect,
+    disconnect = (client) => client.destroy(),
+    log = (line) => console.log(line),
+  } = deps
+
+  // `status --to @chan` reads as one request: point somewhere new, then show me where I am.
+  // Setting it first is also what makes the Destination line below tell the current truth.
+  if (options.to) {
+    await runSetDestination(options, { configDir, log: () => {} })
+  }
+
+  const config = await loadConfig(configDir)
+
+  log(row('Account', await accountLine(config, options, { connect, disconnect })))
+  log(
+    row(
+      'Destination',
+      config.defaultChat
+        ? describeChat(config.defaultChat)
+        : 'none set — pass --to @my_backups to set one',
+    ),
+  )
+
+  const states = await listStates(configDir)
+
+  if (states.length === 0) {
+    log(row('Unfinished', 'none'))
+    return
+  }
+
+  log(row('Unfinished', `${states.length} backup${states.length === 1 ? '' : 's'}`))
+
+  for (const state of states) {
+    const total = countChunks(state.size, state.chunkSize)
+    const done = Object.keys(state.done ?? {}).length
+
+    log(`  ${state.id}  ${path.basename(state.path)}  ${done}/${total} chunks  ${formatBytes(state.size)}`)
+    log(`  → ${describeChat(state.chat)}`)
+  }
+}

package/src/commands/upload.js

@@ -12,7 +12,8 @@ import {
   parseSize,
   planChunks,
 } from '../chunking.js'
-import { connect as realConnect, requireChat } from '../client.js'
+import { chunkCaption, manifestCaption } from '../caption.js'
+import { closeQuietly, connect as realConnect, describeChat, requireChat } from '../client.js'
 import { defaultConfigDir, loadConfig, saveConfig } from '../config.js'
 import {
   buildManifest,
@@ -22,27 +23,32 @@ import {
   serializeManifest,
 } from '../manifest.js'
 import { createProgress, formatBytes, formatDuration } from '../progress.js'
-import { clearState, loadState, markChunkDone, saveState, stateDir, stateKey } from '../state.js'
+import { clearState, loadState, markChunkDone, saveState, stateFile, stateKey } from '../state.js'
 import { uploadRange } from '../uploader.js'
 
 // Above this threshold the wait must be spelled out, per spec §8.
 const LONG_WAIT_MS = 60_000
 
-async function realSendChunk(client, peer, { inputFile, fileName, caption }) {
+// Chunks and manifests differ only in where the bytes come from. Everything Telegram is
+// told about them — document, not preview; this exact file name — is decided once.
+async function sendDocument(client, peer, { file, fileName, caption }) {
   return await client.sendFile(peer, {
-    file: inputFile,
+    file,
     caption,
     forceDocument: true,
     attributes: [new Api.DocumentAttributeFilename({ fileName })],
   })
 }
 
+async function realSendChunk(client, peer, { inputFile, fileName, caption }) {
+  return await sendDocument(client, peer, { file: inputFile, fileName, caption })
+}
+
 async function realSendManifest(client, peer, { bytes, fileName, caption }) {
-  return await client.sendFile(peer, {
+  return await sendDocument(client, peer, {
     file: new CustomFile(fileName, bytes.length, '', bytes),
+    fileName,
     caption,
-    forceDocument: true,
-    attributes: [new Api.DocumentAttributeFilename({ fileName })],
   })
 }
 
@@ -93,11 +99,11 @@ export async function runUpload(filePath, options = {}, deps = {}) {
   const resuming = Boolean(state) && state.chunkSize === chunkSize
 
   if (resuming && state.chat !== String(chat)) {
-    const stateFile = path.join(stateDir(configDir), `${key}.json`)
+    const file = stateFile(key, configDir)
     throw new Error(
       `This unfinished backup is going to ${state.chat}, but the current command targets ${chat} — ` +
         `a single backup cannot be split across two destinations. Run again without --to to keep ` +
-        `sending to ${state.chat}, or delete ${stateFile} and run again to start a new backup in ${chat}.`,
+        `sending to ${state.chat}, or delete ${file} and run again to start a new backup in ${chat}.`,
     )
   }
 
@@ -140,9 +146,9 @@ export async function runUpload(filePath, options = {}, deps = {}) {
 
   log(`Backup ${state.id}`)
   log(`File   ${absPath} (${formatBytes(stat.size)}, ${chunks.length} chunks)`)
-  log(`To     ${chat}\n`)
+  log(`To     ${describeChat(chat)}\n`)
 
-  const client = await connect(config)
+  const client = await connect(config, { verbose: options.verbose })
 
   try {
     for (const chunk of chunks) {
@@ -154,13 +160,12 @@ export async function runUpload(filePath, options = {}, deps = {}) {
       const fileName = chunkFileName(state.id, chunk.i)
       const handle = await fs.open(absPath, 'r')
 
-      const progress = silent
-        ? { advance: () => {}, finish: () => {} }
-        : createProgress({
-            total: chunk.length,
-            label: `Chunk ${chunk.i + 1}/${chunks.length}`,
-            write: writeErr,
-          })
+      // warn is already the no-op when silent, and createProgress draws through nothing else.
+      const progress = createProgress({
+        total: chunk.length,
+        label: `Chunk ${chunk.i + 1}/${chunks.length}`,
+        write: warn,
+      })
 
       try {
         const { inputFile, sha256 } = await uploadRange(client, handle.fd, {
@@ -178,7 +183,7 @@ export async function runUpload(filePath, options = {}, deps = {}) {
         const message = await sendChunk(client, chat, {
           inputFile,
           fileName,
-          caption: `#dataark ${state.id} ${chunk.i + 1}/${chunks.length}`,
+          caption: chunkCaption({ id: state.id, number: chunk.i + 1, total: chunks.length }),
         })
 
         state = await markChunkDone(
@@ -218,7 +223,13 @@ export async function runUpload(filePath, options = {}, deps = {}) {
     await sendManifest(client, chat, {
       bytes: serializeManifest(manifest),
       fileName: manifestFileName(state.id),
-      caption: `#dataark ${state.id} manifest`,
+      caption: manifestCaption({
+        id: manifest.id,
+        name: manifest.name,
+        size: manifest.size,
+        chunks: manifest.chunks.length,
+        createdAt: manifest.createdAt,
+      }),
     })
 
     await clearState(key, configDir)
@@ -227,11 +238,8 @@ export async function runUpload(filePath, options = {}, deps = {}) {
 
     return { id: state.id, chunks: chunks.length }
   } finally {
-    // A failing disconnect must not swallow the real error already on its way up.
-    try {
-      await disconnect(client)
-    } catch (err) {
-      warn(`\nWarning: could not close the Telegram connection: ${err.message}\n`)
-    }
+    await closeQuietly(client, disconnect, (err) =>
+      warn(`\nWarning: could not close the Telegram connection: ${err.message}\n`),
+    )
   }
 }

package/src/config.js

@@ -26,16 +26,21 @@ export async function loadConfig(dir = defaultConfigDir()) {
   }
 }
 
-export async function saveConfig(config, dir = defaultConfigDir()) {
-  await fs.mkdir(dir, { recursive: true, mode: 0o700 })
+// Config and state are both small JSON files holding something that must survive a crash
+// mid-write: write beside the target, then rename, which is atomic on the same filesystem.
+export async function writeJsonAtomic(file, value) {
+  await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 })
 
-  const file = path.join(dir, FILE_NAME)
   const tmp = `${file}.tmp`
 
-  await fs.writeFile(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
+  await fs.writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 })
   await fs.rename(tmp, file)
 }
 
+export async function saveConfig(config, dir = defaultConfigDir()) {
+  await writeJsonAtomic(path.join(dir, FILE_NAME), config)
+}
+
 export async function clearSession(dir = defaultConfigDir()) {
   const config = await loadConfig(dir)
   delete config.session

package/src/manifest.js

@@ -1,5 +1,7 @@
 import { randomBytes } from 'node:crypto'
 
+import { countChunks } from './chunking.js'
+
 export const MANIFEST_VERSION = 1
 
 export function newBackupId(now = new Date(), randomHex = () => randomBytes(3).toString('hex')) {
@@ -61,7 +63,7 @@ export function parseManifest(input) {
     }
   })
 
-  const expectedChunks = Math.ceil(manifest.size / manifest.chunkSize)
+  const expectedChunks = countChunks(manifest.size, manifest.chunkSize)
   if (manifest.chunks.length !== expectedChunks) {
     throw new Error(`Manifest is missing ${expectedChunks - manifest.chunks.length} chunk(s).`)
   }

package/src/progress.js

@@ -52,9 +52,15 @@ export function createProgress({
   const startedAt = now()
   let done = 0
   let lastDrawnAt = startedAt
+  let widestLine = 0
 
+  // \r only moves the cursor home, it does not erase. A redraw that is shorter than the one
+  // before it (a shrinking ETA, a speed that changes unit) would leave the previous tail on
+  // screen, so pad every line out to the widest one drawn so far.
   function draw(suffix) {
-    write(`\r${renderProgress({ done, total, elapsedMs: now() - startedAt, label })}${suffix}`)
+    const line = renderProgress({ done, total, elapsedMs: now() - startedAt, label })
+    widestLine = Math.max(widestLine, line.length)
+    write(`\r${line.padEnd(widestLine)}${suffix}`)
   }
 
   return {

package/src/state.js

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto'
 import { promises as fs } from 'node:fs'
 import path from 'node:path'
 
-import { defaultConfigDir } from './config.js'
+import { defaultConfigDir, writeJsonAtomic } from './config.js'
 
 export function stateDir(configDir = defaultConfigDir()) {
   return path.join(configDir, 'state')
@@ -12,7 +12,7 @@ export function stateKey(absPath, size, mtimeMs) {
   return createHash('sha1').update(`${absPath}:${size}:${mtimeMs}`).digest('hex')
 }
 
-function stateFile(key, configDir) {
+export function stateFile(key, configDir = defaultConfigDir()) {
   return path.join(stateDir(configDir), `${key}.json`)
 }
 
@@ -27,14 +27,7 @@ export async function loadState(key, configDir = defaultConfigDir()) {
 }
 
 export async function saveState(key, state, configDir = defaultConfigDir()) {
-  const dir = stateDir(configDir)
-  await fs.mkdir(dir, { recursive: true, mode: 0o700 })
-
-  const file = stateFile(key, configDir)
-  const tmp = `${file}.tmp`
-
-  await fs.writeFile(tmp, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 })
-  await fs.rename(tmp, file)
+  await writeJsonAtomic(stateFile(key, configDir), state)
 }
 
 export async function markChunkDone(key, state, i, entry, configDir = defaultConfigDir()) {
@@ -50,3 +43,27 @@ export async function clearState(key, configDir = defaultConfigDir()) {
     if (err.code !== 'ENOENT') throw err
   }
 }
+
+// status needs every unfinished backup at once. A state file that cannot be read is skipped
+// rather than fatal, for the same reason loadState returns null: one corrupt file must not
+// hide the other backups still waiting to be finished.
+export async function listStates(configDir = defaultConfigDir()) {
+  let names
+  try {
+    names = await fs.readdir(stateDir(configDir))
+  } catch (err) {
+    if (err.code === 'ENOENT') return []
+    throw err
+  }
+
+  const states = []
+
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue
+
+    const state = await loadState(name.slice(0, -'.json'.length), configDir)
+    if (state) states.push(state)
+  }
+
+  return states
+}

package/src/uploader.js

@@ -16,7 +16,10 @@ const read = promisify(readCallback)
 export const LARGE_FILE_THRESHOLD = 10 * 1024 * 1024
 
 async function readExactly(fd, length, position) {
-  const buffer = Buffer.alloc(length)
+  // allocUnsafe skips zero-filling 512KB per part — about 0.4s of memset per 1800MB chunk,
+  // on the same thread that drives the in-flight requests. Safe only because the loop below
+  // either fills every byte or throws: no uninitialised byte can reach a request or the hash.
+  const buffer = Buffer.allocUnsafe(length)
   let filled = 0
 
   while (filled < length) {