data-ark 0.1.0 → 0.1.2

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 })
@@ -16,11 +16,11 @@ function createPrompts() {
 }
 
 const LOGIN_ERROR_MESSAGES = {
-  PHONE_NUMBER_INVALID: 'số điện thoại không hợp lệ',
-  PHONE_CODE_INVALID: 'mã xác nhận sai',
-  PHONE_CODE_EXPIRED: 'mã xác nhận đã hết hạn',
-  PASSWORD_HASH_INVALID: 'mật khẩu hai lớp sai',
-  FLOOD_WAIT: 'bị Telegram giới hạn tần suất, cần chờ',
+  PHONE_NUMBER_INVALID: 'invalid phone number',
+  PHONE_CODE_INVALID: 'wrong verification code',
+  PHONE_CODE_EXPIRED: 'verification code expired',
+  PASSWORD_HASH_INVALID: 'wrong two-step password',
+  FLOOD_WAIT: 'rate limited by Telegram, need to wait',
 }
 
 export function describeLoginError(err) {
@@ -33,42 +33,60 @@ 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('Cần api_id và api_hash của riêng bạn. Lấy tại 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()
 
   if (apiIdAnswer !== '' && !/^\d+$/.test(apiIdAnswer)) {
     prompts.close()
-    throw new Error('api_id phải là số nguyên.')
+    throw new Error('api_id must be an integer.')
   }
 
   const apiId = apiIdAnswer === '' ? config.apiId : Number(apiIdAnswer)
-  const apiHash = (await prompts.ask(`api_hash${config.apiHash ? ' [giữ nguyên]' : ''}: `)) || config.apiHash
+  const apiHash = (await prompts.ask(`api_hash${config.apiHash ? ' [keep current]' : ''}: `)) || config.apiHash
 
   if (!apiId || !apiHash) {
     prompts.close()
-    throw new Error('Thiếu api_id hoặc api_hash.')
+    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('Số điện thoại (dạng +84...): '),
-    phoneCode: () => prompts.ask('Mã xác nhận Telegram vừa gửi: '),
-    password: () => prompts.ask('Mật khẩu hai lớp (bỏ trống nếu không bật): '),
-    onError: (err) => console.error(`Lỗi đăng nhập: ${describeLoginError(err)}`),
+    phoneNumber: () => prompts.ask('Phone number (e.g. +1...): '),
+    phoneCode: () => prompts.ask('Verification code Telegram just sent: '),
+    password: () => prompts.ask('Two-step password (leave blank if not enabled): '),
+    onError: (err) => console.error(`Login failed: ${describeLoginError(err)}`),
   })
 
   const me = await client.getMe()
   const session = client.session.save()
-  await client.disconnect()
+  await shutdown(client)
 
   const chatAnswer = (
     await prompts.ask(
-      `Đẩy backup vào chat nào? (@username, -100..., hoặc me)${config.defaultChat ? ` [${config.defaultChat}]` : ''}, Enter để bỏ qua: `,
+      `Which chat should backups go to? (@username, -100..., or me)${config.defaultChat ? ` [${config.defaultChat}]` : ''}, Enter to skip: `,
     )
   ).trim()
 
@@ -82,6 +100,6 @@ export async function runLogin({ configDir = defaultConfigDir(), prompts = creat
 
   await saveConfig(next, configDir)
 
-  console.log(`\nĐã đăng nhập với tài khoản ${me.username ? `@${me.username}` : me.firstName}.`)
-  console.log(`Cấu hình đã lưu vào ${configDir}/config.json`)
+  log(`\nLogged in as ${me.username ? `@${me.username}` : me.firstName}.`)
+  log(`Config saved to ${configDir}/config.json`)
 }

package/src/commands/logout.js

@@ -3,11 +3,11 @@ import { clearSession, defaultConfigDir } from '../config.js'
 export async function runLogout({ configDir = defaultConfigDir() } = {}) {
   await clearSession(configDir)
   console.log(
-    'Đã xoá phiên đăng nhập lưu trên máy này. api_id, api_hash và đích lưu vẫn được giữ lại.',
+    'Removed the session stored on this machine. api_id, api_hash and the destination are kept.',
   )
   console.log(
-    'Lưu ý: lệnh này chỉ xoá bản lưu dưới máy, phiên vẫn còn sống phía Telegram. ' +
-      'Muốn cắt hẳn quyền truy cập, mở Telegram → Settings → Devices (Active sessions) ' +
-      'và thu hồi phiên đó.',
+    'Note: this only deletes the local copy — the session is still alive on Telegram\'s side. ' +
+      'To revoke access for good, open Telegram → Settings → Devices (Active sessions) ' +
+      'and terminate that session.',
   )
 }

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 })
 
-  // Dùng client.getMessages thay vì raw Api.messages.Search: nó tự lo offset,
-  // hash và phân trang, nên không phải tự dựng các trường dễ sai kiểu.
-  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) {
@@ -44,17 +29,17 @@ export async function realDownloadChunk(client, message, handle, offset, onProgr
   return await downloadToFile(client, message, handle.fd, { offset, onProgress })
 }
 
-// manifest.name đến từ dữ liệu tải về Telegram — không tin nó khi tự chọn đường
-// dẫn. path.basename chặn được "../../x" nhưng vẫn trả về "..", "." hay "" cho
-// vài tên bệnh: path.resolve('..') là thư mục cha, nên file .partial hàng GB sẽ
-// nằm ngoài thư mục hiện tại và chỉ vỡ ra ở bước rename.
+// manifest.name comes from data downloaded off Telegram — don't trust it when picking
+// a path ourselves. path.basename stops "../../x" but still returns "..", "." or "" for
+// a few pathological names: path.resolve('..') is the parent directory, so a multi-GB
+// .partial file would land outside the current directory and only blow up at rename.
 function safeOutName(name) {
   const base = path.basename(String(name ?? ''))
 
   if (base === '' || base === '.' || base === '..') {
     throw new Error(
-      `Tên file trong manifest ("${name}") không dùng được làm tên file. ` +
-        'Chạy lại kèm --out <đường-dẫn> để tự chỉ định nơi ghi.',
+      `The name in the manifest ("${name}") cannot be used as a file name. ` +
+        'Run again with --out <path> to choose where to write.',
     )
   }
 
@@ -65,7 +50,7 @@ async function askConfirm(question) {
   const rl = readline.createInterface({ input: stdin, output: stdout })
   const answer = await rl.question(question)
   rl.close()
-  return /^(c|y)/i.test(answer.trim())
+  return /^y/i.test(answer.trim())
 }
 
 export async function runRestore(backupId, options = {}, deps = {}) {
@@ -87,25 +72,25 @@ 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)
 
     if (!manifestMessage) {
       throw new Error(
-        `Không tìm thấy manifest của ${backupId} trong ${chat}. ` +
-          'Kiểm tra lại backup id, hoặc dùng --to để trỏ đúng chat.',
+        `No manifest found for ${backupId} in ${chat}. ` +
+          'Check the backup id, or use --to to point at the right chat.',
       )
     }
 
     const manifest = parseManifest(await readMessageBytes(client, manifestMessage))
-    // Khi người dùng tự chỉ định --out thì tôn trọng nguyên văn đường dẫn đó.
+    // When the user passes --out, respect that path verbatim.
     const target = path.resolve(options.out ?? safeOutName(manifest.name))
     const partial = `${target}.partial`
 
-    // Chỉ ENOENT mới có nghĩa là "chưa có file". Lỗi quyền hay lỗi I/O mà bị coi
-    // là vắng mặt thì data-ark sẽ ghi đè file của người dùng mà không hỏi.
+    // Only ENOENT means "no file yet". Treating a permission or I/O error as absence
+    // would have data-ark overwrite the user's file without asking.
     let exists = true
     try {
       await fs.stat(target)
@@ -114,12 +99,12 @@ export async function runRestore(backupId, options = {}, deps = {}) {
       exists = false
     }
 
-    if (exists && !(await confirm(`${target} đã tồn tại. Ghi đè? [c/K] `))) {
-      throw new Error('Đã huỷ theo yêu cầu.')
+    if (exists && !(await confirm(`${target} already exists. Overwrite? [y/N] `))) {
+      throw new Error('Cancelled on request.')
     }
 
     log(`Backup ${manifest.id}`)
-    log(`File   ${target} (${formatBytes(manifest.size)}, ${manifest.chunks.length} chunk)\n`)
+    log(`File   ${target} (${formatBytes(manifest.size)}, ${manifest.chunks.length} chunks)\n`)
 
     const handle = await fs.open(partial, 'w+')
 
@@ -131,18 +116,17 @@ export async function runRestore(backupId, options = {}, deps = {}) {
 
         if (!message) {
           throw new Error(
-            `Thiếu chunk ${chunk.i + 1}/${manifest.chunks.length}: message ${chunk.msgId} không còn trong ${chat}. ` +
-              'Backup này không khôi phục được.',
+            `Missing chunk ${chunk.i + 1}/${manifest.chunks.length}: message ${chunk.msgId} is no longer in ${chat}. ` +
+              'This backup cannot be restored.',
           )
         }
 
-        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,
@@ -156,13 +140,13 @@ export async function runRestore(backupId, options = {}, deps = {}) {
 
         if (size !== chunk.size) {
           throw new Error(
-            `Chunk ${chunk.i + 1} có ${size} byte, manifest ghi ${chunk.size} byte — không khớp.`,
+            `Chunk ${chunk.i + 1} has ${size} bytes, the manifest records ${chunk.size} bytes — mismatch.`,
           )
         }
 
         if (sha256 !== chunk.sha256) {
           throw new Error(
-            `Chunk ${chunk.i + 1} có sha256 không khớp manifest. File tải về giữ ở ${partial} để kiểm tra.`,
+            `Chunk ${chunk.i + 1} has a sha256 that does not match the manifest. The download is kept at ${partial} for inspection.`,
           )
         }
       }
@@ -170,28 +154,26 @@ export async function runRestore(backupId, options = {}, deps = {}) {
       await handle.close()
     }
 
-    // Chốt chặn cuối: mọi chunk khớp sha256 mà file vẫn sai độ dài thì bố cục đã
-    // lệch ở đâu đó. Thà báo lỗi còn hơn đổi tên một file sai thành file thật.
+    // Last line of defence: if every chunk matched its sha256 and the file is still the
+    // wrong length, the layout went wrong somewhere. Better to fail than to rename a
+    // wrong file into the real one.
     const written = await fs.stat(partial)
 
     if (written.size !== manifest.size) {
       throw new Error(
-        `File ghép xong có ${written.size} byte, manifest ghi ${manifest.size} byte — không khớp. ` +
-          `File tải về giữ ở ${partial} để kiểm tra.`,
+        `The assembled file has ${written.size} bytes, the manifest records ${manifest.size} bytes — mismatch. ` +
+          `The download is kept at ${partial} for inspection.`,
       )
     }
 
     await fs.rename(partial, target)
 
-    log(`\nXong. Đã ghi ${formatBytes(manifest.size)} vào ${target}`)
+    log(`\nDone. Wrote ${formatBytes(manifest.size)} to ${target}`)
 
     return { path: target, size: manifest.size }
   } finally {
-    // Ngắt kết nối hỏng thì cũng không được nuốt mất lỗi thật đang bay lên.
-    try {
-      await disconnect(client)
-    } catch (err) {
-      warn(`\nCảnh báo: không đóng được kết nối Telegram: ${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)}`)
+  }
+}