telstore 0.1.5 → 0.1.7

package/src/cli.js

@@ -1,3 +1,4 @@
+import { basename } from 'node:path'
 import { parseArgs } from 'node:util'
 
 const SUBCOMMANDS = new Set([
@@ -13,11 +14,12 @@ const SUBCOMMANDS = new Set([
 ])
 
 const OPTIONS = {
-  to: { type: 'string' },
+  chat: { type: 'string' },
   'chunk-size': { type: 'string' },
   'upload-concurrency': { type: 'string' },
   'download-concurrency': { type: 'string' },
   out: { type: 'string' },
+  note: { type: 'string' },
   limit: { type: 'string' },
   verbose: { type: 'boolean' },
   unset: { type: 'boolean' },
@@ -30,10 +32,10 @@ export const HELP = `telstore — split large files into chunks and store them o
 
 Usage:
   npx telstore login                      Log in to Telegram, only needed once
-  npx telstore <file>                     Split a file and upload it to Telegram
+  npx telstore <file|folder|pattern>...   Split files and upload them to Telegram
   npx telstore list                       List the backups stored in the destination
-  npx telstore restore <backup-id>        Download the chunks and reassemble the file
-  npx telstore delete <backup-id>         Remove a backup's chunks and manifest from the chat
+  npx telstore restore <backup-id>...     Download the chunks and reassemble the files
+  npx telstore delete <backup-id>...      Remove backups' chunks and manifests from the chat
   npx telstore status                     Show the account, the destination and unfinished backups
   npx telstore config                     Show every setting and where its value comes from
   npx telstore logout                     Remove the saved session
@@ -42,6 +44,15 @@ Running on a machine you do not trust:
   npx telstore token                      Print a session token for another machine
   npx telstore login --token              Log in there by pasting one, session stays sealed
 
+Several files in one run go one after another over a single connection, each becoming its own
+backup. A folder means the files one level inside it, and a pattern means the names it matches
+— the shell usually expands those itself, so quote one to hand it to telstore intact. More than
+one file is listed and confirmed before the first byte goes out. Run telstore again with only
+the files that are left to carry on after an interruption.
+
+restore and delete take several ids the same way: one connection, one line each, and an exit
+code that reports any that failed. delete shows everything it is about to destroy and asks once.
+
 Settings:
   npx telstore config <name>              Print one setting's value
   npx telstore config <name> <value>      Change it for good
@@ -55,19 +66,25 @@ Settings:
   verbose              Show Telegram connection logs, default false.
 
 Options apply to one run and are never saved. Use config to change a setting for good.
-  --to <chat>                 Destination for this run only.
+  --chat <chat>               Destination for this run only.
   --chunk-size <n>            Chunk size for this run only. An unfinished backup keeps the
                               size it started with.
   --upload-concurrency <n>    512KB parts in parallel while uploading, this run only.
   --download-concurrency <n>  8MB slices in parallel while restoring, this run only.
   --out <path>                Where to write the restored file. Defaults to the basename in
-                              the manifest.
+                              the manifest, and works with one backup id only.
+  --note <text>               A note to store with the upload. It goes into the manifest and
+                              onto the manifest message, where Telegram's own search can find
+                              it, and every file of a batch gets the same one. A note with
+                              spaces in it has to be quoted — --note "march archive" — or the
+                              shell hands the words after the first to telstore as more files
+                              to upload.
   --limit <n>                 How many backups list shows this run.
   --token                     Log in by pasting a session token. It takes no value on
                               purpose: a token written on the command line would sit in
                               "ps" for the whole life of the command, and stay in that
                               machine's shell history afterwards.
-  --yes                       Delete without asking to confirm first.
+  --yes                       Upload a batch, or delete, without being asked to confirm.
   --verbose                   Show Telegram connection logs for this run.
   -h, --help                  Show this help.
 `
@@ -76,10 +93,27 @@ Options apply to one run and are never saved. Use config to change a setting for
 // finished chunk to a state file, restore has not. Naming the backup matters because the
 // id is what `status` lists and what a later `restore` needs — the chunks are already in
 // the chat under that id, whether or not this run ever finishes.
-export function interruptMessage(command, { backupId } = {}) {
+export function interruptMessage(command, { backupId, done = [] } = {}) {
   if (command === 'upload') {
     const backup = backupId ? `Backup ${backupId} is saved` : 'Progress is saved'
 
+    // A batch is where "run the same command again" turns into a lie: the files it already
+    // finished have had their records cleared, so repeating the whole line would upload them
+    // a second time under new ids. Name them, and ask for the ones that are left instead.
+    if (done.length > 0) {
+      const width = Math.max(...done.map((file) => basename(file.path).length))
+      const finished = done
+        .map((file) => `  ${basename(file.path).padEnd(width)}  ${file.id}`)
+        .join('\n')
+
+      return (
+        `\n${backup}. These are finished and need no second run:\n${finished}\n` +
+        'Run telstore again with only the files that are left — repeating the whole command ' +
+        'would upload the finished ones again as new backups. "npx telstore status" shows ' +
+        'what is unfinished.\n'
+      )
+    }
+
     return (
       `\n${backup} — run the same command again to continue, ` +
       'or "npx telstore status" to see what is left.\n'
@@ -107,8 +141,8 @@ export function interruptMessage(command, { backupId } = {}) {
 // parseArgs rejects anything starting with a dash as an option, and reports it as one:
 // `config chat -100123` fails with "Unknown option '-1'", naming a flag nobody typed.
 //
-// Two shapes need rescuing, and they are rescued differently. As a flag value, `--to -100123`
-// is joined into `--to=-100123`; only a bare negative integer qualifies, so `--to --verbose`
+// Two shapes need rescuing, and they are rescued differently. As a flag value, `--chat -100123`
+// is joined into `--chat=-100123`; only a bare negative integer qualifies, so `--chat --verbose`
 // still reports the missing value instead of eating the next flag. As a positional —
 // `config chat -100123` — there is nothing to join it to, so `--` goes in front and the rest
 // of the line is handed over verbatim. That is greedy on purpose: a flag written after the
@@ -125,8 +159,8 @@ function protectNegativeChatIds(argv) {
       return safe
     }
 
-    if (argv[i] === '--to' && /^-\d+$/.test(argv[i + 1] ?? '')) {
-      safe.push(`--to=${argv[i + 1]}`)
+    if (argv[i] === '--chat' && /^-\d+$/.test(argv[i + 1] ?? '')) {
+      safe.push(`--chat=${argv[i + 1]}`)
       i += 1
       continue
     }
@@ -142,33 +176,52 @@ function protectNegativeChatIds(argv) {
   return safe
 }
 
+// An unquoted note is gone by the time node starts: the shell hands `--note ghi chu` over as
+// three arguments and nothing can put the quotes back. The one trace it leaves is its own
+// tail — every word after the first sits here as a positional, after the flag — and upload
+// needs that to tell the mistake from a plain missing file. The shape of the command line is
+// already this file's business, so the observation is made here rather than guessed at later.
+//
+// The last --note is the one parseArgs kept, so it is the one whose position counts.
+function filesNamedAfterNote(tokens) {
+  const note = tokens.findLast((token) => token.kind === 'option' && token.name === 'note')
+
+  if (!note) return false
+
+  return tokens.some((token) => token.kind === 'positional' && token.index > note.index)
+}
+
 export function route(argv) {
-  const { values, positionals } = parseArgs({
+  const { values, positionals, tokens } = parseArgs({
     args: protectNegativeChatIds(argv),
     options: OPTIONS,
     allowPositionals: true,
+    tokens: true,
   })
 
   const [first, ...rest] = positionals
+  const filesAfterNote = filesNamedAfterNote(tokens)
 
-  // `telstore --to @chan` with no file used to mean "remember this destination". Flags no
+  // `telstore --chat @chan` with no file used to mean "remember this destination". Flags no
   // longer write anything, so that line now asks for a run that has nothing to upload —
   // say where the destination actually lives instead of printing help at someone who was
   // perfectly clear about what they wanted.
-  if (first === undefined && values.to && !values.help) {
+  if (first === undefined && values.chat && !values.help) {
     throw new Error(
-      `Nothing to upload. To change the destination for good, run "npx telstore config chat ${values.to}". ` +
-        'To use it for one run, pass --to alongside a file or a command.',
+      `Nothing to upload. To change the destination for good, run "npx telstore config chat ${values.chat}". ` +
+        'To use it for one run, pass --chat alongside a file or a command.',
     )
   }
 
   if (values.help || first === undefined || first === 'help') {
-    return { command: 'help', args: [], options: values }
+    return { command: 'help', args: [], options: values, filesAfterNote }
   }
 
   if (SUBCOMMANDS.has(first)) {
-    return { command: first, args: rest, options: values }
+    return { command: first, args: rest, options: values, filesAfterNote }
   }
 
-  return { command: 'upload', args: [first], options: values }
+  // Every positional, not just the first: `telstore a b c` used to upload `a` and drop the
+  // rest without a word, which is the one thing this project never does.
+  return { command: 'upload', args: positionals, options: values, filesAfterNote }
 }

package/src/commands/delete.js

@@ -120,7 +120,7 @@ export async function runDelete(backupId, options = {}, deps = {}) {
     if (!manifestMessage && !record) {
       throw new Error(
         `No backup ${backupId} found in ${chatName(chat)}, and no unfinished record of it on ` +
-          'this machine. Check the id with "npx telstore list", or use --to to point at the ' +
+          'this machine. Check the id with "npx telstore list", or use --chat to point at the ' +
           'right chat.',
       )
     }
@@ -248,3 +248,198 @@ export async function runDelete(backupId, options = {}, deps = {}) {
     )
   }
 }
+
+
+// `telstore delete a b c` is three deletes, and the question that guards them is asked once —
+// which means it has to be able to say what all three are. So the batch looks every id up
+// before it asks: the manifest for the finished ones, the local record for the unfinished, and
+// an id that neither knows about refuses the whole run rather than half of it. runDelete then
+// does exactly what it does alone, having already been told the answer.
+export async function runDeletes(backupIds, options = {}, deps = {}) {
+  const {
+    connect = realConnect,
+    disconnect = (client) => client.destroy(),
+    configDir = defaultConfigDir(),
+    searchManifest = findManifestMessage,
+    readMessageBytes = realReadMessageBytes,
+    confirm = askConfirm,
+    interactive = () => Boolean(process.stdin.isTTY),
+    writeErr = (line) => process.stderr.write(line),
+    log: writeLog = (line) => console.log(line),
+    silent = false,
+  } = deps
+
+  // One id keeps its own wording, its own question and its own thrown error.
+  if (backupIds.length === 1) {
+    const result = await runDelete(backupIds[0], options, deps)
+    return { results: [result], failed: 0 }
+  }
+
+  const duplicate = backupIds.find((id, index) => backupIds.indexOf(id) !== index)
+
+  if (duplicate) {
+    throw new Error(
+      `${duplicate} is named twice. Deleting one backup twice does nothing the first pass ` +
+        'did not already do — name it once.',
+    )
+  }
+
+  const config = await loadConfig(configDir)
+
+  assertLoggedIn(config)
+
+  const { values: settings } = resolveSettings(options, config, { file: configFile(configDir) })
+  const chat = requireChat(settings)
+
+  const log = silent ? () => {} : writeLog
+  const warn = silent ? () => {} : writeErr
+
+  let shared = null
+  const perId = {
+    ...deps,
+    connect: async (theirConfig, connectOptions) =>
+      (shared ??= await connect(theirConfig, connectOptions)),
+    disconnect: async () => {},
+  }
+
+  const results = []
+
+  try {
+    const client = await perId.connect(config, { verbose: settings.verbose })
+    const rows = []
+    const unknown = []
+
+    for (const backupId of backupIds) {
+      const message = await searchManifest(client, chat, backupId)
+      const records = await findStates(backupId, configDir)
+
+      if (!message && records.length === 0) {
+        unknown.push(backupId)
+        continue
+      }
+
+      // A manifest too damaged to read is exactly the backup somebody is here to remove, so
+      // it costs the row its name and size, not the run. runDelete refuses the ones that
+      // cannot name their message ids, which is the check that actually protects anything.
+      let manifest = null
+
+      if (message) {
+        try {
+          manifest = parseManifestJson(await readMessageBytes(client, message))
+        } catch {
+          manifest = null
+        }
+      }
+
+      rows.push({ id: backupId, manifest, record: records[0] ?? null })
+    }
+
+    if (unknown.length > 0) {
+      throw new Error(
+        `Nothing was deleted: ${unknown.join(', ')} — not found in ${chatName(chat)}, and no ` +
+          'local record of it on this machine either. Check the ids with "npx telstore list".',
+      )
+    }
+
+    if (!options.yes) {
+      if (!interactive()) {
+        throw new Error(
+          `${backupIds.length} backups to delete, and no terminal to confirm that in. Run ` +
+            'again with --yes to delete them without being asked.',
+        )
+      }
+
+      for (const line of listingLines(rows, chat)) log(line)
+
+      if (
+        !(await confirm(
+          `The chunks cannot be recovered. Delete all ${backupIds.length}? [y/N] `,
+        ))
+      ) {
+        throw new Error('Cancelled on request.')
+      }
+    }
+
+    for (const [index, backupId] of backupIds.entries()) {
+      if (index > 0) log('')
+      log(`[${index + 1}/${backupIds.length}] ${backupId}`)
+
+      try {
+        // The question was asked about the whole list a moment ago; asking again per backup
+        // would be asking the same thing three times.
+        results.push(await runDelete(backupId, { ...options, yes: true }, perId))
+      } catch (err) {
+        results.push({ id: backupId, error: err.message })
+        warn(`\n${backupId} failed: ${err.message}\n`)
+      }
+    }
+  } finally {
+    if (shared) {
+      await closeQuietly(shared, disconnect, (err) =>
+        warn(`\nWarning: could not close the Telegram connection: ${err.message}\n`),
+      )
+    }
+  }
+
+  const failed = results.filter((result) => result.error).length
+
+  log('')
+  for (const line of summaryLines(results, failed)) log(line)
+
+  return { results, failed }
+}
+
+// What is about to be destroyed, spelled out before the one question that authorises it. An
+// unfinished backup has no manifest to describe it, so its own record speaks for it.
+function listingLines(rows, chat) {
+  const described = rows.map(({ id, manifest, record }) => ({
+    id,
+    name: manifest
+      ? describeName(manifest.name)
+      : `${describeName(record?.state?.path)} (unfinished)`,
+    size: manifest ? describeSize(manifest.size) : UNKNOWN,
+    chunks: plural(countChunks(manifest, record), 'chunk'),
+  }))
+
+  const width = (key) => Math.max(...described.map((row) => row[key].length))
+  const [idWidth, nameWidth, sizeWidth] = [width('id'), width('name'), width('size')]
+
+  return [
+    `Deleting ${rows.length} backups from ${describeChat(chat)}`,
+    '',
+    ...described.map(
+      (row) =>
+        `  ${row.id.padEnd(idWidth)}  ${row.name.padEnd(nameWidth)}  ` +
+        `${row.size.padStart(sizeWidth)}  ${row.chunks}`,
+    ),
+    '',
+  ]
+}
+
+function countChunks(manifest, record) {
+  if (Array.isArray(manifest?.chunks)) return manifest.chunks.length
+
+  const done = record?.state?.done
+
+  return typeof done === 'object' && done !== null ? Object.keys(done).length : 0
+}
+
+// Every id gets a line whether it worked or not: one missing from this list would be a backup
+// nobody could tell the fate of.
+function summaryLines(results, failed) {
+  const width = Math.max(...results.map((result) => result.id.length))
+  const deleted = results.length - failed
+
+  return [
+    `${results.length} backups: ${deleted} deleted, ${failed} failed.`,
+    '',
+    ...results.map((result) => {
+      const id = result.id.padEnd(width)
+
+      return result.error
+        ? `  ${id}  failed: ${result.error}`
+        : `  ${id}  ${plural(result.chunks, 'chunk message')} removed` +
+            (result.manifestDeleted ? ' with its manifest' : '')
+    }),
+  ]
+}

package/src/commands/list.js

@@ -18,8 +18,18 @@ const COLUMNS = [
   { header: 'SIZE', key: 'size', right: true },
   { header: 'CHUNKS', key: 'chunks', right: true },
   { header: 'CREATED', key: 'created' },
+  { header: 'NOTE', key: 'note' },
 ]
 
+// The table is read at a glance, and the note is the one field with no shape at all — 500
+// characters of it would push every column off the side. The whole note is still in the
+// manifest and on the card in the chat, which is where anyone reading it properly will look.
+const NOTE_WIDTH = 40
+
+function shorten(note) {
+  return note.length > NOTE_WIDTH ? `${note.slice(0, NOTE_WIDTH - 1)}…` : note
+}
+
 // 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.
@@ -44,7 +54,14 @@ function toRow(message) {
   const card = parseManifestCaption(message.caption)
 
   if (!card) {
-    return { id, name: UNKNOWN, size: UNKNOWN, chunks: UNKNOWN, created: utcDay(message.date) }
+    return {
+      id,
+      name: UNKNOWN,
+      size: UNKNOWN,
+      chunks: UNKNOWN,
+      created: utcDay(message.date),
+      note: UNKNOWN,
+    }
   }
 
   return {
@@ -53,23 +70,30 @@ function toRow(message) {
     size: card.size,
     chunks: String(card.chunks),
     created: card.createdAt.slice(0, 10),
+    note: card.note ? shorten(card.note) : UNKNOWN,
   }
 }
 
 function renderTable(rows) {
-  const widths = COLUMNS.map((column) =>
+  // Most people never write a note, and a column of dashes tells them nothing they did not
+  // already know while costing every other column the width it takes.
+  const columns = COLUMNS.filter(
+    (column) => column.key !== 'note' || rows.some((row) => row.note !== UNKNOWN),
+  )
+
+  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])))
+      .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]))),
+    line(columns.map((column) => column.header)),
+    ...rows.map((row) => line(columns.map((column) => row[column.key]))),
   ]
 }
 

package/src/commands/restore.js

@@ -9,6 +9,7 @@ import {
 } from '../client.js'
 import { askConfirm } from '../confirm.js'
 import { configFile, defaultConfigDir, loadConfig } from '../config.js'
+import { assertLoggedIn } from '../session.js'
 import { requireChat, resolveSettings } from '../settings.js'
 import { downloadToFile } from '../downloader.js'
 import { parseManifest } from '../manifest.js'
@@ -102,7 +103,7 @@ export async function runRestore(backupId, options = {}, deps = {}) {
     if (!manifestMessage) {
       throw new Error(
         `No manifest found for ${backupId} in ${chat}. ` +
-          'Check the backup id, or use --to to point at the right chat.',
+          'Check the backup id, or use --chat to point at the right chat.',
       )
     }
 
@@ -216,3 +217,119 @@ export async function runRestore(backupId, options = {}, deps = {}) {
     )
   }
 }
+
+
+// `telstore restore a b c` is three restores, not one download: each backup keeps its own
+// manifest, its own name and its own verification, so a batch is what running the command
+// three times would have produced minus two logins. As with uploads, the connection is shared
+// through the deps seam, which leaves runRestore the only caller of connect.
+export async function runRestores(backupIds, options = {}, deps = {}) {
+  const {
+    connect = realConnect,
+    disconnect = (client) => client.destroy(),
+    configDir = defaultConfigDir(),
+    writeErr = (line) => process.stderr.write(line),
+    log: writeLog = (line) => console.log(line),
+    silent = false,
+  } = deps
+
+  // One id must read exactly as it did before this existed: --out still works, the error still
+  // reaches the caller, and nothing prints a summary of a list with one thing in it.
+  if (backupIds.length === 1) {
+    const { path: target, size } = await runRestore(backupIds[0], options, deps)
+    return { results: [{ id: backupIds[0], path: target, size }], failed: 0 }
+  }
+
+  // Everything knowable before the first byte arrives is settled here, so a batch never stops
+  // halfway over something that was already visible on the command line.
+  if (options.out !== undefined) {
+    throw new Error(
+      `--out names one file, and this run restores ${backupIds.length} backups. Leave it off ` +
+        'to write each one under the name in its own manifest, or restore them one command at ' +
+        'a time to choose the names yourself.',
+    )
+  }
+
+  const duplicate = backupIds.find((id, index) => backupIds.indexOf(id) !== index)
+
+  if (duplicate) {
+    throw new Error(
+      `${duplicate} is named twice. Restoring one backup twice would write the same file ` +
+        'over itself — name it once.',
+    )
+  }
+
+  const config = await loadConfig(configDir)
+
+  // Once for the batch. Reported from inside the loop, "Not logged in" would arrive once per
+  // id, each time as though that particular backup were the problem.
+  assertLoggedIn(config)
+
+  const { values: settings } = resolveSettings(options, config, { file: configFile(configDir) })
+  requireChat(settings)
+
+  const log = silent ? () => {} : writeLog
+  const warn = silent ? () => {} : writeErr
+
+  let shared = null
+  const perId = {
+    ...deps,
+    connect: async (theirConfig, connectOptions) =>
+      (shared ??= await connect(theirConfig, connectOptions)),
+    disconnect: async () => {},
+  }
+
+  const results = []
+
+  try {
+    for (const [index, backupId] of backupIds.entries()) {
+      if (index > 0) log('')
+      log(`[${index + 1}/${backupIds.length}] ${backupId}`)
+
+      try {
+        const { path: target, size } = await runRestore(backupId, options, perId)
+        results.push({ id: backupId, path: target, size })
+      } catch (err) {
+        // A backup whose chunks are gone says nothing about the next one, and the summary at
+        // the end would arrive an hour after the bar of the following id started scrolling
+        // over it — so it is named here, and again down there, and carried out as exit code 1.
+        results.push({ id: backupId, error: err.message })
+        warn(`\n${backupId} failed: ${err.message}\n`)
+      }
+    }
+  } finally {
+    if (shared) {
+      await closeQuietly(shared, disconnect, (err) =>
+        warn(`\nWarning: could not close the Telegram connection: ${err.message}\n`),
+      )
+    }
+  }
+
+  const failed = results.filter((result) => result.error).length
+
+  log('')
+  for (const line of summaryLines(results, failed)) log(line)
+
+  return { results, failed }
+}
+
+// Every id gets a line whether it worked or not: one missing from this list would be a backup
+// nobody could tell the fate of.
+function summaryLines(results, failed) {
+  const width = Math.max(...results.map((result) => result.id.length))
+  const restored = results.length - failed
+
+  const lines = [
+    `${results.length} backups: ${restored} restored, ${failed} failed.`,
+    '',
+    ...results.map((result) => {
+      const id = result.id.padEnd(width)
+
+      return result.error
+        ? `  ${id}  failed: ${result.error}`
+        : `  ${id}  ${result.path} (${formatBytes(result.size)})`
+    }),
+  ]
+
+  return lines
+}

package/src/commands/status.js

@@ -34,12 +34,12 @@ function shellArg(text) {
 
 // runUpload refuses to send the rest of a backup to a different chat, so the command has to
 // name the one the chunks are already in — unless the destination in force is that chat
-// anyway, where --to would just be noise. Not knowing the destination counts as not matching:
-// leaving --to out would be a guess about where a backup already in progress went.
+// anyway, where --chat would just be noise. Not knowing the destination counts as not matching:
+// leaving --chat out would be a guess about where a backup already in progress went.
 function resumeCommand(state, destination) {
   const matches = destination !== null && state.chat === String(destination)
 
-  return `npx telstore ${shellArg(state.path)}${matches ? '' : ` --to ${shellArg(state.chat)}`}`
+  return `npx telstore ${shellArg(state.path)}${matches ? '' : ` --chat ${shellArg(state.chat)}`}`
 }
 
 // Why a resume is off the table, in the words of the thing the user would have to fix. The
@@ -162,7 +162,7 @@ export async function runStatus(options = {}, deps = {}) {
 
   log(row('Unfinished', `${states.length} backup${states.length === 1 ? '' : 's'}`))
 
-  // The destination is what decides whether the resume command needs a --to. A row that
+  // The destination is what decides whether the resume command needs a --chat. A row that
   // failed to parse leaves nothing to compare against, which is not the same as a match.
   const destination = settings?.chat ?? null