telstore 0.1.6 → 0.1.8

package/README.md

@@ -14,6 +14,8 @@ development tools; `login` asks for those, your phone number and the verificatio
 npx telstore login                             # once only
 npx telstore config chat @my_backups           # where backups go, from now on
 npx telstore data.tar                          # split it and send it there
+npx telstore a.tar b.tar c.tar                 # or several: one backup each, one after another
+npx telstore ./backups                         # or a folder: every file one level inside it
 npx telstore list                              # what is already in the destination
 npx telstore restore telstore-20260905-7f3a91
 ```
@@ -23,11 +25,11 @@ npx telstore restore telstore-20260905-7f3a91
 | Command | What it does |
 |---|---|
 | `telstore login` | Log in to Telegram. Add `--token` to log in with a session token instead. |
-| `telstore <file>` | Split the file and upload it. Prints the `backupId` you restore with. |
+| `telstore <file\|folder\|pattern>...` | Split each file and upload it. Prints the `backupId` you restore with. |
 | `telstore list` | The backups stored in the destination, newest first. |
-| `telstore restore <backup-id>` | Download every chunk and reassemble the file. |
-| `telstore delete <backup-id>` | Remove a backup's chunks and manifest from the chat, for good. |
-| `telstore status` | Account, destination, and unfinished backups. |
+| `telstore restore <backup-id>...` | Download every chunk and reassemble the file. Several ids run one after another. |
+| `telstore delete <backup-id>...` | Remove a backup's chunks and manifest from the chat, for good. Several ids are listed and confirmed once. |
+| `telstore status` | Account, destination, and unfinished uploads and restores. |
 | `telstore config` | Show or change settings. |
 | `telstore token` | Print a session token for a machine you do not trust. |
 | `telstore logout` | Remove the locally stored session. |
@@ -35,7 +37,7 @@ npx telstore restore telstore-20260905-7f3a91
 ## Settings
 
 `config` writes; flags do not. A flag applies to the run you typed it on and changes nothing
-on disk, so `--to @elsewhere` sends one backup elsewhere without moving the destination for
+on disk, so `--chat @elsewhere` sends one backup elsewhere without moving the destination for
 the next one.
 
 ```bash
@@ -46,7 +48,7 @@ npx telstore config chunkSize --unset  # back to the default
 
 | Setting | Flag | Default | Meaning |
 |---|---|---|---|
-| `chat` | `--to` | none | `@username`, `-100123…`, or `me` |
+| `chat` | `--chat` | none | `@username`, `-100123…`, or `me` |
 | `chunkSize` | `--chunk-size` | `1800MB` | e.g. `1.8GB`, `500MB`. Ceiling 1950MB. |
 | `uploadConcurrency` | `--upload-concurrency` | `32` | 512KB parts in parallel while uploading, 1–64 |
 | `downloadConcurrency` | `--download-concurrency` | `8` | 8MB slices in parallel while restoring, 1–64 |
@@ -54,7 +56,8 @@ npx telstore config chunkSize --unset  # back to the default
 | `verbose` | `--verbose` | off | Show the Telegram client's own connection logs |
 
 Three flags have no setting behind them: `--out <path>` names where one restore writes,
-`--yes` skips the confirmation `delete` asks, and `--token` takes no value — a token written
+`--yes` skips the confirmation an upload batch and `delete` ask for, and `--token` takes no
+value — a token written
 on the command line would sit in `ps` and in that machine's shell history, so it is pasted at
 a prompt that does not echo.
 
@@ -74,6 +77,61 @@ telstore-20260901-9de447  photos.zip  940.3 MB       1  2026-09-01
 2 backups. Restore with: npx telstore restore <backup-id>
 ```
 
+## Several files at once
+
+`telstore a.tar b.tar c.tar` uploads them one after another over a single connection. Each
+file becomes its own backup with its own `backupId`, exactly as three separate runs would
+have produced.
+
+A **folder** stands for the files one level inside it — subfolders are named on screen and
+left alone, hidden files are skipped. A **pattern** stands for the names it matches:
+
+```bash
+npx telstore ./backups            # every file directly inside ./backups
+npx telstore 'logs/*.tar'         # quoted, so telstore matches it rather than the shell
+npx telstore logs/abc*            # unquoted: your shell expands it first, same result
+```
+
+More than one file is listed, added up and confirmed before the first byte goes out:
+
+```
+3 files, 4.20 GB, to https://web.telegram.org/k/#@my_backups
+
+  a.tar  1.20 GB
+  b.tar  2.00 GB
+  c.tar  1.00 GB
+
+Upload these 3 files? [y/N]
+```
+
+`--yes` skips the question; without a terminal to ask in, the run stops and says so rather
+than reading an empty line as "no". Names that do not exist, and a file named twice, are
+refused before anything is sent; a file that fails mid-transfer does not stop the ones after
+it, and the run ends with a line per file and a non-zero exit code:
+
+```
+3 files: 2 uploaded, 1 failed.
+
+  a.tar  telstore-20260905-7f3a91  (12 chunks)
+  b.tar  failed: connection dropped mid-transfer
+  c.tar  telstore-20260905-9de447  (1 chunk)
+```
+
+## Several backups at once
+
+`restore` and `delete` take a list of ids the same way, over one connection, with a summary
+and a non-zero exit code if any of them failed:
+
+```bash
+npx telstore restore telstore-20260905-7f3a91 telstore-20260901-9de447
+npx telstore delete telstore-20260905-7f3a91 telstore-20260901-9de447
+```
+
+With several ids, `restore` writes each file under the name in its own manifest, so `--out`
+— which names exactly one file — is refused rather than quietly used three times. `delete`
+looks every id up first and shows the whole list before asking once; an id that is nowhere to
+be found stops the run before anything is destroyed.
+
 ## Resuming an upload
 
 Progress lives in `~/.telstore/state/` (the 20 most recent), so running the same command
@@ -81,7 +139,18 @@ again skips the finished chunks and keeps the same `backupId`. A resumed backup
 chunk size it started with; passing a `--chunk-size` or a destination that differs from its
 own makes telstore refuse to run rather than re-cut or redirect it silently.
 
-**Restore keeps no state** — `Ctrl-C` mid-restore saves nothing, running again starts over.
+After a batch, run telstore again with **only the files that are left**: the finished ones
+have had their records cleared, so repeating the whole command would upload them a second
+time as new backups. `npx telstore status` lists what is unfinished.
+
+## Resuming a restore
+
+`Ctrl-C` mid-restore keeps the `<target>.partial` file rather than throwing it away. Running
+the same command again hashes each chunk-sized region of it against the manifest, in order,
+and carries on from the first one that does not match — nothing already on disk is trusted
+just because it is there. `npx telstore status` lists unfinished restores alongside
+unfinished uploads, with a resume command for each.
+
 And `delete` has **no undo**: Telegram is the only copy.
 
 ## Running on a machine you do not trust

package/bin/telstore.js

@@ -14,12 +14,18 @@ const SIGINT_EXIT_CODE = 130
 let currentCommand = null
 let currentBackupId = null
 
+// A batch clears each finished item's record as it goes, so by the time Ctrl-C lands these
+// are transfers no second run should touch. Ctrl-C needs their names to say so.
+const finished = []
+
 process.on('SIGINT', () => {
   // A passphrase prompt has stdin in raw mode, and process.exit skips readline's own cleanup.
   // Without this, Ctrl-C hands back a shell that no longer echoes what is typed into it.
   if (process.stdin.isTTY) process.stdin.setRawMode(false)
 
-  process.stderr.write(interruptMessage(currentCommand, { backupId: currentBackupId }))
+  process.stderr.write(
+    interruptMessage(currentCommand, { backupId: currentBackupId, done: finished }),
+  )
   process.exit(SIGINT_EXIT_CODE)
 })
 
@@ -88,13 +94,23 @@ async function main() {
     }
 
     case 'upload': {
-      const { runUpload } = await import('../src/commands/upload.js')
+      const { runUploads } = await import('../src/commands/upload.js')
 
-      await runUpload(parsed.args[0], parsed.options, {
+      const { failed } = await runUploads(parsed.args, parsed.options, {
+        // Only route saw the command line, and an unquoted note is told apart from a plain
+        // missing file by where the words sat on it.
+        filesAfterNote: parsed.filesAfterNote,
         onBackupId: (id) => {
           currentBackupId = id
         },
+        onFileDone: (file) => {
+          if (file.id) finished.push(file)
+        },
       })
+
+      // A batch reports its own failures by name and has already said so on stdout; the exit
+      // code is what carries that out to whatever ran telstore.
+      if (failed > 0) process.exitCode = 1
       return
     }
 
@@ -103,9 +119,18 @@ async function main() {
         throw new Error('Missing backup id. Example: npx telstore restore telstore-20260905-7f3a91')
       }
 
-      const { runRestore } = await import('../src/commands/restore.js')
+      const { runRestores } = await import('../src/commands/restore.js')
+
+      const { failed } = await runRestores(parsed.args, parsed.options, {
+        onBackupId: (id) => {
+          currentBackupId = id
+        },
+        onRestoreDone: (item) => {
+          finished.push(item)
+        },
+      })
 
-      await runRestore(parsed.args[0], parsed.options)
+      if (failed > 0) process.exitCode = 1
       return
     }
 
@@ -114,9 +139,11 @@ async function main() {
         throw new Error('Missing backup id. Example: npx telstore delete telstore-20260905-7f3a91')
       }
 
-      const { runDelete } = await import('../src/commands/delete.js')
+      const { runDeletes } = await import('../src/commands/delete.js')
+
+      const { failed } = await runDeletes(parsed.args, parsed.options)
 
-      await runDelete(parsed.args[0], parsed.options)
+      if (failed > 0) process.exitCode = 1
       return
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "telstore",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Split large files into chunks and store them on Telegram",
   "keywords": [
     "telegram",

package/src/caption.js

@@ -14,6 +14,37 @@ function oneLine(name) {
   return String(name).replace(/\s+/g, ' ').trim()
 }
 
+// Telegram takes 1024 characters in a caption, and the card around the note already spends
+// some of them — a file name alone may be 255. 500 leaves both room to spare.
+export const MAX_NOTE_LENGTH = 500
+
+// A note is written at a shell prompt and read in two places: the manifest body and the card
+// in the chat. Folding it here, once, is what keeps those two from holding slightly different
+// notes and leaving nobody able to say which one was typed.
+export function parseNote(raw) {
+  if (raw === undefined || raw === null) return null
+
+  const note = oneLine(raw)
+
+  if (note === '') {
+    throw new Error(
+      '--note is empty. Write the note itself, or leave the flag off — a backup with a blank ' +
+        'note is one telstore had something to say about and did not.',
+    )
+  }
+
+  if (note.length > MAX_NOTE_LENGTH) {
+    throw new Error(
+      `--note is ${note.length} characters, and a caption has only room for ${MAX_NOTE_LENGTH} ` +
+        'once the rest of the card has had its share. Shorten it: telstore will not cut it ' +
+        'short by itself, because half a note read as a whole one is exactly the kind of ' +
+        'plausible wrong answer this tool exists to refuse.',
+    )
+  }
+
+  return note
+}
+
 function utcMinutes(createdAt) {
   return `${new Date(createdAt).toISOString().slice(0, 16).replace('T', ' ')} UTC`
 }
@@ -22,12 +53,15 @@ export function chunkCaption({ id, number, total }) {
   return `📦 ${id} · ${number}/${total}`
 }
 
-export function manifestCaption({ id, name, size, chunks, createdAt }) {
+export function manifestCaption({ id, name, size, chunks, createdAt, note = null }) {
   return [
     `📄 ${oneLine(name)}`,
     `💾 ${formatBytes(size)} · ${chunks} chunk${chunks === 1 ? '' : 's'}`,
     `🆔 ${id}`,
     `📅 ${utcMinutes(createdAt)}`,
+    // Below the facts telstore knows, above the line that says how to get the file back:
+    // the note is the one part of the card a person wrote, so it reads last of the four.
+    ...(note ? [`📝 ${oneLine(note)}`] : []),
     '',
     `↩ npx telstore restore ${id}`,
     MANIFEST_TAG,
@@ -50,11 +84,15 @@ export function parseManifestCaption(text) {
   const id = marker(lines, '🆔')
   const createdAt = marker(lines, '📅')
 
+  // Every card telstore wrote before --note existed is a complete card, so the note is the
+  // one marker whose absence means "there is no note" rather than "this is not a card".
+  const note = 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 }
+  return { id, name, size: match[1], chunks: Number(match[2]), createdAt, note }
 }

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,11 +32,11 @@ 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 status                     Show the account, the destination and unfinished backups
+  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 uploads and restores
   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,18 +93,65 @@ 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'
     )
   }
 
+  // A restore keeps its .partial now, and the next run proves each chunk in it against the
+  // manifest before trusting a byte — so "running again starts over", which this said while
+  // there was nothing to resume from, would now be false.
   if (command === 'restore') {
-    return '\nStopped. Download progress is not saved, running again starts over.\n'
+    // Finished ids have been renamed to their real names and their records removed, so
+    // repeating the whole command line would meet an overwrite prompt and then download
+    // them again from nothing. Name them and ask for the rest, exactly as a batch upload does.
+    if (done.length > 0) {
+      const width = Math.max(...done.map((item) => basename(item.path).length))
+      const finished = done
+        .map((item) => `  ${basename(item.path).padEnd(width)}  ${item.id}`)
+        .join('\n')
+
+      return (
+        `\nStopped. These are finished and need no second run:\n${finished}\n` +
+        'Run telstore again with only the ids that are left — their .partial files are kept, ' +
+        'so those carry on where they stopped. "npx telstore status" shows what is unfinished.\n'
+      )
+    }
+
+    // With onBackupId firing only once the .partial is open, an id here means there is a
+    // file to carry on from. Without one, this run stopped before it wrote anything, and
+    // saying a .partial was kept would be the same lie this message was rewritten to stop
+    // telling — just from the other side.
+    if (!backupId) {
+      return '\nStopped before anything was written. Run the same command again to start.\n'
+    }
+
+    return (
+      `\nBackup ${backupId} kept its .partial file — run the same command again from this ` +
+      'directory to carry on, or "npx telstore status" to see what is left.\n'
+    )
   }
 
   // A delete has already destroyed messages for good by the time Ctrl-C lands, and the
@@ -107,8 +171,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 +189,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 +206,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 }
 }