telstore 0.1.9 → 0.1.10

package/src/cli.js

@@ -1,9 +1,24 @@
 import { basename } from 'node:path'
 import { parseArgs } from 'node:util'
 
+import { deleteCommand } from './shell.js'
+import { archiveName } from './tar.js'
+
+// The shortcuts dispatch by name, not through SUBCOMMANDS: what they return is not a command
+// called `tarc`, it is an upload (or, for `tarx`, a restore) with the line already
+// rewritten into the form that command understands — there is no `runTarc` for SUBCOMMANDS to
+// route to. They still belong in the set below all the same, because SUBCOMMANDS is the list of
+// words telstore will not read as a file name, and a shortcut claims one exactly as a
+// subcommand does.
+const SHORTCUTS = new Map([
+  ['tarc', tarcLine],
+  ['tarx', tarxLine],
+])
+
 const SUBCOMMANDS = new Set([
   'login',
   'logout',
+  'down',
   'list',
   'restore',
   'verify',
@@ -12,9 +27,10 @@ const SUBCOMMANDS = new Set([
   'config',
   'token',
   'help',
+  ...SHORTCUTS.keys(),
 ])
 
-const OPTIONS = {
+export const OPTIONS = {
   chat: { type: 'string' },
   'chunk-size': { type: 'string' },
   'upload-concurrency': { type: 'string' },
@@ -35,6 +51,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|folder|pattern>...   Split files and upload them to Telegram
+  npx telstore <name> -- <command>...     Store what a command writes, under <name>
+  npx telstore tarc <name> <path>...      Archive paths with tar and store the archive
+  npx telstore tarx <backup-id>           Restore a backup and extract it with tar
+  npx telstore restore <id> -- <cmd>...   Restore onto a command instead of a file
   npx telstore list                       List the backups stored in the destination
   npx telstore list --search <text>       List only the backups that text appears in
   npx telstore restore <backup-id>...     Download the chunks and reassemble the files
@@ -43,6 +63,7 @@ Usage:
   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
+  npx telstore down                       Remove everything telstore keeps on this machine
 
 Running on a machine you do not trust:
   npx telstore token                      Print a session token for another machine
@@ -54,6 +75,32 @@ backup. A folder means the files one level inside it, and a pattern means the na
 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.
 
+A name followed by -- makes the backup out of what a command writes, so nothing has to be on
+disk first: npx telstore a.tar -- tar cf - ./a. The manifest goes out only if that command's
+output ended and the command exited 0 — an end after a crash looks exactly like an end after
+success, and running the command is how telstore tells them apart. A backup made this way
+cannot be resumed, so a run that fails, and a Ctrl-C, remove the chunks already sent rather
+than keeping them for a second run there will never be. No shell stands in between: a pipeline
+goes in as -- bash -c 'set -o pipefail; ...', which is also where compression or encryption
+belongs. The pipefail is not decoration — a shell reports the last command's exit status, so
+without it a producer that dies halfway through a pipeline still exits 0 and the manifest goes
+out for a truncated backup.
+
+tarc and tarx are the common case written out once: "npx telstore tarc a.tar.gz ./dir"
+is "npx telstore a.tar.gz -- tar czf - ./dir", and tarx is the same for "restore <id> --
+tar xzf -". telstore prints the long form as it runs, so the shortcut teaches what it is
+short for. tarc always compresses, so it makes the name say so: a.tar becomes a.tar.gz,
+and a name with no tar in it at all gets .tar.gz. --verbose adds tar's own file listing
+to both. For tarx, --out is the directory it extracts into, and tar's own semantics apply
+there: it overwrites files already in it without asking, unlike restore's one-file [y/N]
+prompt — --out is how you aim it somewhere empty instead. Anything beyond archiving
+the paths — -C, --exclude, a pipeline, another compressor — is what -- is still for.
+
+down is logout taken all the way: it removes ~/.telstore entirely — the session, the api_id
+and api_hash, every setting and every resume record — and asks once before it does. It opens
+no connection and deletes nothing from Telegram: the backups stay in the chat, and the session
+stays alive on Telegram's side until you terminate it under Settings → Devices.
+
 restore, verify 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. verify downloads nothing: it asks the chat whether every chunk message is still
@@ -96,7 +143,8 @@ Options apply to one run and are never saved. Use config to change a setting for
                               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                       Upload a batch, or delete, without being asked to confirm.
+  --yes                       Upload a batch, delete, or wipe this machine with down,
+                              without being asked to confirm.
   --verbose                   Show Telegram connection logs for this run.
   -h, --help                  Show this help.
 `
@@ -105,7 +153,54 @@ 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, done = [] } = {}) {
+export function interruptMessage(
+  command,
+  { backupId, done = [], stream = false, again = false, chat = null } = {},
+) {
+  // A backup made from a command is the one upload Ctrl-C cannot leave where it is. The bytes
+  // have gone past and the next run cuts them differently, so a chunk already in the chat is
+  // a chunk no manifest will ever name — which is why this run is asked to remove them and
+  // the process waits, rather than promising the resume the file wording promises.
+  if (command === 'upload' && stream) {
+    // Nothing is in the chat until there is an id to put it under, and a run stopped before
+    // that has nothing for anyone to clean up.
+    if (!backupId) {
+      return '\nStopped before anything was sent.\n'
+    }
+
+    if (again) {
+      // "may still" because this is said while the removal is halfway through and nobody
+      // knows how far it got. `deleteCommand` is what names the chat, and why: a later
+      // `delete` resolves its destination from config, and these ids fired at the wrong peer
+      // destroy whatever happens to carry them there. A null chat here is a Ctrl-C that
+      // landed before the run said where it was sending — the chatless branch documented
+      // beside that function is for exactly this caller.
+      const removal = deleteCommand(backupId, chat)
+
+      return (
+        `\nLeaving now. Backup ${backupId} may still have chunks in the chat with no manifest ` +
+        `pointing at them — run "${removal}" to remove them.\n`
+      )
+    }
+
+    return (
+      `\nStopping. Backup ${backupId} was made from a command and cannot be resumed, so ` +
+      'telstore is removing the chunks it already sent. This takes a moment — press Ctrl-C ' +
+      'again to leave now and clean up by hand.\n'
+    )
+  }
+
+  // The restore direction of the same idea, and the difference is the whole message: a stream
+  // upload has to unwind what it put in the chat, while this one put nothing there. What it
+  // cannot put back is what the command already did with the bytes it was given.
+  if (command === 'restore' && stream) {
+    return (
+      '\nStopped. Nothing in the chat changed and nothing was kept on this machine, but the ' +
+      'command had already been given part of the backup, so whatever it wrote from that is ' +
+      'incomplete. A restore into a command cannot be resumed — run it again from the start.\n'
+    )
+  }
+
   if (command === 'upload') {
     const backup = backupId ? `Backup ${backupId} is saved` : 'Progress is saved'
 
@@ -179,6 +274,18 @@ export function interruptMessage(command, { backupId, done = [] } = {}) {
   return '\nStopped.\n'
 }
 
+// The one `--` this file did not write. protectNegativeChatIds, below, inserts one of its
+// own to rescue a negative chat id from parseArgs, so the position has to be taken off the
+// argv as typed — afterwards the two are indistinguishable, and `config chat -100123` would
+// become a command telstore tries to run.
+function splitAtTerminator(argv) {
+  const at = argv.indexOf('--')
+
+  if (at === -1) return { head: argv, childArgv: null }
+
+  return { head: argv.slice(0, at), childArgv: argv.slice(at + 1) }
+}
+
 // A channel id is negative, and typing it separated by a space is the natural reflex — but
 // 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.
@@ -233,9 +340,80 @@ function filesNamedAfterNote(tokens) {
   return tokens.some((token) => token.kind === 'positional' && token.index > note.index)
 }
 
+// tarc is the long form with the three decisions that never change already made: `c` for
+// create, `z` for gzip, `f -` for "write it to stdout, which is where telstore is listening".
+// The missing `-` is not a hypothetical mistake — this project's own help text and README
+// shipped exactly that omission once, and paid for it with an example that exited 2 instead
+// of writing a backup.
+//
+// An expansion rather than a command of its own: `runStreamUpload` is reached with exactly the
+// argv the `--` form reaches it with, so there is no second upload path, no second rollback
+// and no second guarantee. It also prints that argv, so the shortcut teaches the long form
+// instead of hiding it.
+function tarcLine(rest, values, filesAfterNote) {
+  const [name, ...paths] = rest
+
+  if (name === undefined) {
+    throw new Error(
+      'Missing a name for the backup. tarc stores the archive under a name you choose. ' +
+        'Example: npx telstore tarc a.tar.gz ./a',
+    )
+  }
+
+  // Refused rather than answered with a guess: a rule that read one positional as a name and
+  // two as a name plus a path would make `telstore tarc ./x ./y` archive ./y under the name
+  // ./x, which is the silent wrong answer this project exists to refuse.
+  if (paths.length === 0) {
+    throw new Error(
+      `Nothing to archive: tarc needs the paths to put in ${name}. ` +
+        'Example: npx telstore tarc a.tar.gz ./a',
+    )
+  }
+
+  return {
+    command: 'upload',
+    args: [archiveName(name)],
+    options: values,
+    filesAfterNote,
+    childArgv: ['tar', values.verbose ? 'czvf' : 'czf', '-', ...paths],
+    shortcut: 'tarc',
+  }
+}
+
+// The mirror of tarcLine. `x` for extract, `z` because tarc always compressed, `f -` because
+// the bytes arrive on stdin.
+function tarxLine(rest, values, filesAfterNote) {
+  requireOneBackupId(rest, 'tarx')
+
+  const childArgv = ['tar', values.verbose ? 'xzvf' : 'xzf', '-']
+
+  // Pushed after `-` on purpose, which is the order measured to work on GNU tar 1.35:
+  // `tar xzf - -C ./here`. See the probe table in the spec.
+  if (values.out !== undefined) childArgv.push('-C', values.out)
+
+  return { command: 'restore', args: rest, options: values, filesAfterNote, childArgv, shortcut: 'tarx' }
+}
+
+// One command reads one stream, so a line that names two backups is a line with no answer:
+// extracting two archives into one working directory in sequence is a question nobody asked.
+function requireOneBackupId(ids, what) {
+  if (ids.length === 0) {
+    throw new Error(`Missing backup id. Example: npx telstore ${what} telstore-20260905-7f3a91`)
+  }
+
+  if (ids.length > 1) {
+    throw new Error(
+      `One command reads one stream, so ${what} takes one backup id and got ${ids.length}: ` +
+        `${ids.join(', ')}. Run telstore once per backup.`,
+    )
+  }
+}
+
 export function route(argv) {
+  const { head, childArgv } = splitAtTerminator(argv)
+
   const { values, positionals, tokens } = parseArgs({
-    args: protectNegativeChatIds(argv),
+    args: protectNegativeChatIds(head),
     options: OPTIONS,
     allowPositionals: true,
     tokens: true,
@@ -244,26 +422,103 @@ export function route(argv) {
   const [first, ...rest] = positionals
   const filesAfterNote = filesNamedAfterNote(tokens)
 
+  // --help (or -h, or the `help` subcommand) always wins, terminator or not: someone typing
+  // `telstore --help -- tar cf - ./a` is asking what telstore does, not making a mistake for
+  // one of the checks below to catch.
+  if (values.help || first === 'help') {
+    return { command: 'help', args: [], options: values, filesAfterNote, childArgv, shortcut: null }
+  }
+
+  if (childArgv !== null && childArgv.length === 0) {
+    throw new Error(
+      'Missing the command after --: telstore has nothing to run and store. ' +
+        'Example: npx telstore a.tar -- tar cf - ./a',
+    )
+  }
+
+  // A terminator changes what "no name" and "which command" mean, so it is read before the
+  // ordinary help/chat fallbacks get a chance to answer for it — those apply to a line that
+  // never named a command to run at all.
+  if (childArgv !== null) {
+    // Reached before the generic "takes no command after --" below, because for these two the
+    // reason is different and so is the way out: they are not a subcommand that happens not to
+    // run commands, they are a command already.
+    if (SHORTCUTS.has(first)) {
+      throw new Error(
+        `${first} already is the command it runs, so it cannot be followed by another one. ` +
+          `Drop the -- to use ${first}, or drop ${first} to write the command out yourself.`,
+      )
+    }
+
+    if (first !== undefined && SUBCOMMANDS.has(first)) {
+      // restore is let through rather than refused here, and the binary is what turns it away.
+      // The shape is the spec's stage 2, so the parser keeps it whole — but a refusal that
+      // says "not built yet, restore to a file and pipe that" belongs where the command runs,
+      // beside the alternative it is offering, not in an argument parser.
+      if (first !== 'restore') {
+        throw new Error(
+          `${first} takes no command after --. An upload (npx telstore a.tar -- tar cf - ./a) ` +
+            'and a restore (npx telstore restore <id> -- tar xf -) are the two that run one.',
+        )
+      }
+
+      requireOneBackupId(rest, 'restore')
+
+      // --out places a file, and this path writes none: the bytes go to the command on its
+      // stdin. Left to pass silently it would read as "restore into the command AND write
+      // the file over there", which is not what happens.
+      if (values.out !== undefined) {
+        throw new Error(
+          'A restore into a command writes no file, so --out has nothing to place: the bytes ' +
+            'go to the command on its stdin. Tell the command where to put them instead ' +
+            '(npx telstore restore <id> -- tar xf - -C ./here).',
+        )
+      }
+
+      return { command: first, args: rest, options: values, filesAfterNote, childArgv, shortcut: null }
+    }
+
+    if (positionals.length === 0) {
+      throw new Error(
+        'Missing a name before --. telstore stores what the command writes under a name you ' +
+          'choose, and there is nothing to take one from. Example: npx telstore a.tar -- tar cf - ./a',
+      )
+    }
+
+    if (positionals.length > 1) {
+      throw new Error(
+        `One command produces one stream, so telstore takes one name before -- and got ` +
+          `${positionals.length}: ${positionals.join(', ')}. Run telstore once per backup.`,
+      )
+    }
+
+    return { command: 'upload', args: positionals, options: values, filesAfterNote, childArgv, shortcut: null }
+  }
+
   // `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.chat && !values.help) {
+  // perfectly clear about what they wanted. (values.help already returned above, so reaching
+  // here means it was never set.)
+  if (first === undefined && values.chat) {
     throw new Error(
       `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, filesAfterNote }
+  if (first === undefined) {
+    return { command: 'help', args: [], options: values, filesAfterNote, childArgv, shortcut: null }
   }
 
+  const shortcut = SHORTCUTS.get(first)
+  if (shortcut) return shortcut(rest, values, filesAfterNote)
+
   if (SUBCOMMANDS.has(first)) {
-    return { command: first, args: rest, options: values, filesAfterNote }
+    return { command: first, args: rest, options: values, filesAfterNote, childArgv, shortcut: null }
   }
 
   // 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 }
+  return { command: 'upload', args: positionals, options: values, filesAfterNote, childArgv, shortcut: null }
 }

package/src/client.js

@@ -76,9 +76,15 @@ async function* iterMessagePages(client, peer, { search, what, options }) {
     max = Infinity,
     retryOptions = {},
     stallMs = DEFAULT_STALL_MS,
+    // Where the walk begins, as the id of the message just above the first one wanted. 0 is
+    // "the newest in the chat", which is what list asks for. delete starts at a backup's own
+    // manifest instead when the chat has shown it one: the manifest is the last message a
+    // backup's run sends, so nothing of that backup is newer, and everything posted since is
+    // a page of documents read for nothing.
+    offsetId: startId = 0,
   } = options
 
-  let offsetId = 0
+  let offsetId = startId
   let read = 0
 
   while (read < max) {