@nightowne/tas-cli 3.0.0 → 3.0.2

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to TAS (Telegram as Storage) will be documented in this file.
 
+## [3.0.2] - 2026-09-25
+
+### Fixed — Apple Silicon install recovery
+- **Optional native source recovery** — if the legacy optional addon fails before TAS can patch it on arm64, postinstall restores only its source without lifecycle scripts, then rebuilds it against the user's installed macFUSE library. Failed rebuilds still leave every non-mount TAS command usable.
+
+## [3.0.1] - 2026-09-25
+
+### Fixed — current macFUSE mount support (#4)
+- **System macFUSE build** — TAS no longer accepts the bundled OSXFUSE 3 library. On macOS it detects `/Library/Filesystems/macfuse.fs`, selects the installed `libfuse` headers and library, and rebuilds the optional `fuse-native` addon for the active CPU.
+- **Apple Silicon support path** — the rebuilt addon uses macFUSE's supported v2 API surface rather than the legacy binary with no arm64 slice. TAS never installs, replaces, or removes a FUSE kernel extension.
+- **Strict runtime guard** — TAS inspects the loaded native addon and refuses mount if it still links to `libosxfuse` or lacks a system-macFUSE build. `tas doctor` then performs the real mount → readdir → unmount smoke test.
+- **Install guidance** — macOS requires current macFUSE and Xcode Command Line Tools before TAS is installed. A failed native build leaves push, pull, sync, and share available while mount stays disabled.
+
 ## [3.0.0] - 2026-09-24
 
 ### Fixed — FUSE and path correctness

package/FAQ.md

@@ -30,4 +30,4 @@ No. Each chunk has one owning bot. TAS records that bot so reads and deletes rou
 
 ## Does mount work on macOS?
 
-Not in this release. The current `fuse-native@2.x` dependency targets obsolete OSXFUSE APIs and is not validated against current macFUSE or Apple Silicon. Linux users should run `tas doctor` for a real native FUSE smoke test.
+Yes with current macFUSE, Xcode Command Line Tools, and a locally rebuilt native addon. TAS never installs or replaces macFUSE; its install hook selects the system `libfuse` and compiles the optional addon for the active CPU. Run `tas doctor` before use. If the real mount/readdir/unmount smoke test does not pass, do not mount data.

package/QUICKSTART.md

@@ -44,4 +44,4 @@ Multi-bot mode distributes chunks. It is not redundancy, quota assurance, ban pr
 
 ## Mount support
 
-`tas mount` is supported only on validated Linux/libfuse hosts in this release. Run `tas doctor` first; it performs a real mount/readdir/unmount smoke test. macOS mount is disabled until TAS has a maintained current-macFUSE backend and macOS CI.
+`tas mount` needs a native FUSE runtime. On Linux install `fuse` and `libfuse-dev`. On macOS install current macFUSE and Xcode Command Line Tools before installing TAS; TAS rebuilds its optional native addon against the installed macFUSE library. Run `tas doctor` first and mount only when its real mount/readdir/unmount smoke test passes.

package/README.md

@@ -18,7 +18,7 @@
   <a href="https://github.com/ixchio/tas/network/members"><img src="https://img.shields.io/github/forks/ixchio/tas?style=social" alt="GitHub Forks"></a>
   <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?logo=node.js" alt="Node.js >= 18">
   <img src="https://img.shields.io/badge/encryption-AES--256--GCM-blueviolet?logo=shield" alt="AES-256-GCM">
-  <img src="https://img.shields.io/badge/tests-97%20passing-success" alt="97 Tests Passing">
+  <img src="https://img.shields.io/badge/tests-101%20passing-success" alt="101 Tests Passing">
 </p>
 
 <p align="center">
@@ -113,7 +113,7 @@ cp report.pdf ~/cloud/       # Drop files in — auto-encrypted and uploaded
 tas unmount ~/cloud          # Clean unmount when done
 ```
 
-> **Linux only for this release:** install `fuse`/`libfuse-dev`, then run `tas doctor` for a real mount → readdir → unmount smoke test. macOS mount is explicitly unsupported because `fuse-native@2.x` targets obsolete OSXFUSE APIs and is not validated with current macFUSE or Apple Silicon. Push, pull, sync, and share still work on macOS.
+> **Native FUSE is verified, not assumed:** Linux needs `fuse`/`libfuse-dev`. macOS uses current macFUSE and rebuilds the optional native addon against the installed system library on first install. Install Xcode Command Line Tools before TAS, then run `tas doctor`; mount is available only when its real mount → readdir → unmount smoke test passes.
 
 ---
 
@@ -193,7 +193,7 @@ tas doctor
 # ✓ Database: 42 files, 1.3 GB total across 28 chunks
 # ✓ Disk space: 50 GB free (32% used)
 # ✓ Encryption: AES-256-GCM · PBKDF2-SHA512 · 600,000 iterations (OWASP 2025)
-# ✓ FUSE runtime: mount → readdir → unmount passed (Linux)
+# ✓ FUSE runtime: mount → readdir → unmount passed
 # ✓ Telegram connectivity: 2/2 bots OK
 # ✨ All systems go!
 ```
@@ -319,7 +319,7 @@ Reliability mechanisms implemented by TAS (not an SLA):
 | **Resume Uploads** | Network-stage chunks are staged on disk and persisted in `pending_uploads`; `tas resume` continues them |
 | **Index Recovery** | Authenticated encrypted remote manifest; `tas index rebuild` restores file/chunk ownership |
 | **Graceful Shutdown** | SIGINT/SIGTERM handled; staged chunks and SQLite WAL reduce partial-state risk |
-| **Self-Diagnostics** | Checks config/database/chunk limits, all bots, and a real Linux FUSE smoke mount |
+| **Self-Diagnostics** | Checks config/database/chunk limits, all bots, and a real native FUSE smoke mount |
 
 ---
 
@@ -351,7 +351,7 @@ tas bot add|list|enable|disable|remove  # 🤖 Manage experimental bot pool
 <summary><strong>Mount & Sync</strong></summary>
 
 ```bash
-# FUSE Mount (Linux only in this release)
+# FUSE Mount (Linux/libfuse or macOS/current macFUSE)
 tas mount <path>                  # Mount Telegram storage as a local folder
 tas unmount <path>                # Clean unmount
 
@@ -462,7 +462,7 @@ Use TAS only at your own risk, do not use multiple bots to evade limits, follow
 | 📌 **Not a replacement for backups** | Telegram can purge old messages. Use TAS alongside, not instead of, real backup solutions. |
 | 📌 **19 MiB payload chunks** | Hosted Bot API uploads permit more, but `getFile` documents only 20 MB downloads. TAS stays below the read limit. |
 | 📌 **Multi-bot is experimental** | It distributes chunks and preserves ownership mapping; it is not redundancy or ban protection. |
-| 📌 **FUSE = Linux only for now** | macOS mount is disabled until a maintained modern macFUSE backend and macOS CI exist. |
+| 📌 **macOS needs a native build** | Install current macFUSE and Xcode Command Line Tools before installing TAS. `tas doctor` must pass its real FUSE smoke test before you mount data. |
 | 📌 **Recovery needs config** | `index.db` can be rebuilt from the encrypted manifest only if `config.json`, password, manifest message, and owning bot survive. |
 | 📌 **No versioning (yet)** | Overwriting a file replaces the previous version. |
 | 📌 **Internet required** | Telegram-backed — offline access requires files pulled locally first. |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nightowne/tas-cli",
-  "version": "3.0.0",
-  "description": "Experimental local-first encrypted file transport over Telegram bots with resumable chunks, index recovery, and Linux FUSE mount",
+  "version": "3.0.2",
+  "description": "Experimental local-first encrypted file transport over Telegram bots with resumable chunks, index recovery, and FUSE mount",
   "type": "module",
   "main": "src/index.js",
   "bin": {
@@ -11,7 +11,8 @@
     "start": "node src/cli.js",
     "init": "node src/cli.js init",
     "test": "node --test tests/*.test.js",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "postinstall": "node src/fuse/macfuse.cjs"
   },
   "keywords": [
     "telegram",

package/src/cli.js

@@ -814,7 +814,7 @@ program
 // ============== MOUNT COMMAND ==============
 program
     .command('mount <mountpoint>')
-    .description('🔥 Mount Telegram storage as a local folder (Linux FUSE only)')
+    .description('🔥 Mount Telegram storage as a local folder (Linux FUSE or current macFUSE)')
     .option('-p, --password <password>', 'Encryption password (uses TAS_PASSWORD env var if not provided)')
     .action(async (mountpoint, options) => {
         console.log(chalk.cyan('\n🗂️  Mounting Telegram as filesystem...\n'));
@@ -872,7 +872,7 @@ program
             console.log(chalk.dim('\nNote: FUSE requires libfuse to be installed:'));
             console.log(chalk.dim('  Ubuntu/Debian: sudo apt install fuse libfuse-dev'));
             console.log(chalk.dim('  Fedora: sudo dnf install fuse fuse-devel'));
-            console.log(chalk.dim('  macOS: TAS mount is currently unsupported (push/pull/sync still work)\n'));
+            console.log(chalk.dim('  macOS: install current macFUSE and Xcode Command Line Tools, then reinstall TAS\n'));
             process.exit(1);
         }
     });
@@ -890,16 +890,17 @@ program
         try {
             const { execFileSync } = await import('child_process');
 
-            // Use fusermount on Linux, umount on macOS
+            // Match fuse-native's platform unmount mechanism without invoking a shell.
             const isMac = process.platform === 'darwin';
-            const executable = isMac ? 'umount' : 'fusermount';
-            const args = isMac ? [absMount] : ['-u', absMount];
+            const executable = isMac ? 'diskutil' : 'fusermount';
+            const args = isMac ? ['unmount', 'force', absMount] : ['-u', absMount];
             execFileSync(executable, args, { stdio: 'pipe' });
 
             spinner.succeed(`Unmounted ${chalk.green(absMount)}`);
         } catch (err) {
             spinner.fail(`Unmount failed: ${err.message}`);
-            console.log(chalk.dim('\nTry: fusermount -u ' + absMount));
+            const retry = process.platform === 'darwin' ? `diskutil unmount force ${absMount}` : `fusermount -u ${absMount}`;
+            console.log(chalk.dim('\nTry: ' + retry));
             process.exit(1);
         }
     });

package/src/fuse/macfuse.cjs

@@ -0,0 +1,265 @@
+'use strict'
+
+// Modern macFUSE integration for fuse-native 2.x.
+//
+// fuse-native bundles an OSXFUSE 3 dylib on Darwin. That dylib has no arm64
+// slice and its setup helper installs an obsolete kernel extension. We never
+// install or load it. Instead, when macFUSE is already installed by the user,
+// the TAS postinstall hook rebuilds fuse-native against that system library.
+
+const childProcess = require('child_process')
+const fs = require('fs')
+const path = require('path')
+
+const MACFUSE_BUNDLE = '/Library/Filesystems/macfuse.fs'
+
+const LIBRARY_CANDIDATES = [
+  '/usr/local/lib/libfuse.dylib',
+  '/opt/homebrew/lib/libfuse.dylib',
+  '/usr/local/lib/libfuse.2.dylib',
+  '/opt/homebrew/lib/libfuse.2.dylib',
+  '/Library/Frameworks/macfUSE.framework/Versions/Current/lib/libfuse.dylib',
+  '/Library/Frameworks/macfUSE.framework/lib/libfuse.dylib'
+]
+
+const INCLUDE_ROOTS = [
+  '/usr/local/include',
+  '/opt/homebrew/include',
+  '/Library/Frameworks/macfUSE.framework/Headers'
+]
+
+function findMacFuseInstallation ({ exists = fs.existsSync } = {}) {
+  if (!exists(MACFUSE_BUNDLE)) {
+    return {
+      ready: false,
+      reason: 'current macFUSE is not installed at /Library/Filesystems/macfuse.fs'
+    }
+  }
+
+  const library = LIBRARY_CANDIDATES.find(exists)
+  if (!library) {
+    return {
+      ready: false,
+      reason: 'macFUSE is installed but its libfuse.dylib was not found'
+    }
+  }
+
+  const include = findIncludeDirectory(exists)
+  if (!include) {
+    return {
+      ready: false,
+      reason: 'macFUSE is installed but its FUSE development headers were not found'
+    }
+  }
+
+  return { ready: true, bundle: MACFUSE_BUNDLE, library, include }
+}
+
+function findIncludeDirectory (exists) {
+  for (const root of INCLUDE_ROOTS) {
+    for (const candidate of [
+      path.join(root, 'fuse.h'),
+      path.join(root, 'osxfuse', 'fuse.h'),
+      path.join(root, 'fuse', 'fuse.h')
+    ]) {
+      if (exists(candidate)) return path.dirname(candidate)
+    }
+  }
+  return null
+}
+
+function getFuseNativeDirectory (packageRoot) {
+  try {
+    return path.dirname(require.resolve('fuse-native/package.json', { paths: [packageRoot] }))
+  } catch {
+    return null
+  }
+}
+
+function getDarwinLibraryDirectory (packageRoot) {
+  try {
+    return path.dirname(require.resolve('fuse-shared-library-darwin/package.json', { paths: [packageRoot] }))
+  } catch {
+    return null
+  }
+}
+
+function installOptionalFuseNative (packageRoot) {
+  const npmCli = process.env.npm_execpath
+  if (!npmCli) return { ok: false, reason: 'npm did not provide its install executable' }
+
+  const install = childProcess.spawnSync(
+    process.execPath,
+    [npmCli, 'install', 'fuse-native@2.2.6', '--no-save', '--ignore-scripts', '--no-package-lock'],
+    {
+      cwd: packageRoot,
+      stdio: 'inherit',
+      env: { ...process.env, npm_config_ignore_scripts: 'true' }
+    }
+  )
+  if (install.status !== 0) return { ok: false, reason: 'could not restore optional fuse-native source' }
+  return { ok: true }
+}
+
+function validateMacFuseNativeBinding ({
+  packageRoot = path.resolve(__dirname, '..', '..'),
+  exists = fs.existsSync,
+  execFileSync = childProcess.execFileSync
+} = {}) {
+  const installation = findMacFuseInstallation({ exists })
+  if (!installation.ready) return installation
+
+  const fuseNativeDir = getFuseNativeDirectory(packageRoot)
+  if (!fuseNativeDir) {
+    return { ready: false, reason: 'fuse-native is not installed' }
+  }
+
+  const addon = path.join(fuseNativeDir, 'build', 'Release', 'fuse.node')
+  if (!exists(addon)) {
+    return {
+      ready: false,
+      reason: 'the macFUSE native addon was not rebuilt from source; reinstall TAS after installing Xcode Command Line Tools'
+    }
+  }
+
+  let linkedLibraries
+  try {
+    linkedLibraries = execFileSync('/usr/bin/otool', ['-L', addon], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+  } catch {
+    return { ready: false, reason: 'could not inspect the macFUSE native addon' }
+  }
+
+  if (linkedLibraries.includes('libosxfuse')) {
+    return { ready: false, reason: 'the legacy OSXFUSE binary is still loaded; reinstall TAS to rebuild against macFUSE' }
+  }
+  if (!linkedLibraries.includes('libfuse')) {
+    return { ready: false, reason: 'the native addon is not linked to macFUSE libfuse' }
+  }
+
+  return { ready: true, ...installation, addon }
+}
+
+function macFuseAdapterSource () {
+  return `'use strict'
+const path = require('path')
+const macfuse = require(path.join(__dirname, '..', '..', 'src', 'fuse', 'macfuse.cjs'))
+const installation = macfuse.findMacFuseInstallation()
+
+function unavailable () {
+  return new Error('Current macFUSE is required for TAS mount: ' + installation.reason)
+}
+
+module.exports = {
+  get lib () {
+    if (!installation.ready) throw unavailable()
+    return installation.library
+  },
+  get include () {
+    if (!installation.ready) throw unavailable()
+    return installation.include
+  },
+  beforeMount (cb) { process.nextTick(cb || (() => {})) },
+  beforeUnmount (cb) { process.nextTick(cb || (() => {})) },
+  configure (cb) { process.nextTick(() => (cb || (() => {}))(installation.ready ? null : unavailable())) },
+  unconfigure (cb) { process.nextTick(() => (cb || (() => {}))(new Error('TAS never installs or removes macFUSE'))) },
+  isConfigured (cb) { process.nextTick(() => cb(null, installation.ready)) }
+}
+`
+}
+
+function patchFuseSource (fuseNativeDir) {
+  const sourcePath = path.join(fuseNativeDir, 'fuse-native.c')
+  const source = fs.readFileSync(sourcePath, 'utf8')
+  const oldDefine = '#define FUSE_USE_VERSION 29'
+  const newDefine = '#ifdef __APPLE__\n#define FUSE_USE_VERSION 26\n#else\n#define FUSE_USE_VERSION 29\n#endif'
+
+  if (source.includes(newDefine)) return
+  if (!source.includes(oldDefine)) throw new Error('Unsupported fuse-native source layout')
+  fs.writeFileSync(sourcePath, source.replace(oldDefine, newDefine))
+}
+
+function addLibraryRpath (addon, library) {
+  const result = childProcess.spawnSync(
+    '/usr/bin/install_name_tool',
+    ['-add_rpath', path.dirname(library), addon],
+    { stdio: 'ignore' }
+  )
+  // A duplicate rpath produces a nonzero exit code and is already safe.
+  return result.status === 0 || result.status === 1
+}
+
+function installMacFuseAdapter ({
+  packageRoot = path.resolve(__dirname, '..', '..'),
+  platform = process.platform,
+  log = console
+} = {}) {
+  if (platform !== 'darwin') return { skipped: true, reason: 'not macOS' }
+
+  const installation = findMacFuseInstallation()
+  if (!installation.ready) {
+    log.warn(`[tas] macOS FUSE was not built: ${installation.reason}`)
+    return { skipped: true, ...installation }
+  }
+
+  let fuseNativeDir = getFuseNativeDirectory(packageRoot)
+  let darwinLibraryDir = getDarwinLibraryDirectory(packageRoot)
+  if (!fuseNativeDir || !darwinLibraryDir) {
+    // The legacy optional addon can fail to build on arm64 before our root
+    // postinstall runs. Restore its source without lifecycle scripts, then
+    // patch and rebuild it against the system macFUSE library below.
+    const restored = installOptionalFuseNative(packageRoot)
+    if (!restored.ok) {
+      log.warn(`[tas] macOS FUSE was not built: ${restored.reason}`)
+      return { ready: false, reason: restored.reason }
+    }
+    fuseNativeDir = getFuseNativeDirectory(packageRoot)
+    darwinLibraryDir = getDarwinLibraryDirectory(packageRoot)
+  }
+  if (!fuseNativeDir || !darwinLibraryDir) {
+    const reason = 'optional fuse-native dependencies are not installed'
+    log.warn(`[tas] macOS FUSE was not built: ${reason}`)
+    return { ready: false, reason }
+  }
+
+  try {
+    fs.writeFileSync(path.join(darwinLibraryDir, 'index.js'), macFuseAdapterSource())
+    patchFuseSource(fuseNativeDir)
+
+    const npmCli = process.env.npm_execpath
+    if (!npmCli) throw new Error('npm did not provide its rebuild executable')
+
+    const rebuild = childProcess.spawnSync(
+      process.execPath,
+      [npmCli, 'rebuild', 'fuse-native', '--build-from-source', '--foreground-scripts'],
+      {
+        cwd: packageRoot,
+        stdio: 'inherit',
+        env: { ...process.env, npm_config_build_from_source: 'true' }
+      }
+    )
+    if (rebuild.status !== 0) throw new Error('fuse-native could not compile against macFUSE')
+
+    const addon = path.join(fuseNativeDir, 'build', 'Release', 'fuse.node')
+    addLibraryRpath(addon, installation.library)
+
+    const status = validateMacFuseNativeBinding({ packageRoot })
+    if (!status.ready) throw new Error(status.reason)
+    log.log(`[tas] macFUSE native addon rebuilt for ${process.arch}`)
+    return status
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    log.warn(`[tas] macOS FUSE was not built: ${reason}`)
+    return { ready: false, reason }
+  }
+}
+
+module.exports = {
+  MACFUSE_BUNDLE,
+  findMacFuseInstallation,
+  getFuseNativeDirectory,
+  installOptionalFuseNative,
+  validateMacFuseNativeBinding,
+  installMacFuseAdapter
+}
+
+if (require.main === module) installMacFuseAdapter()

package/src/fuse/mount.js

@@ -9,6 +9,7 @@ import path from 'path';
 import fs from 'fs';
 import os from 'os';
 import { pipeline } from 'stream/promises';
+import macFuse from './macfuse.cjs';
 
 let Fuse;
 try {
@@ -47,10 +48,8 @@ function withTimeout(promise, ms, label) {
 /** Verify the native FUSE stack, not merely that the JS module imports. */
 export async function checkFuseRuntime() {
     if (process.platform === 'darwin') {
-        return {
-            supported: false,
-            reason: 'macOS mount is unsupported: fuse-native 2.x targets obsolete OSXFUSE APIs and current macFUSE/Apple Silicon is not validated'
-        };
+        const macStatus = macFuse.validateMacFuseNativeBinding();
+        if (!macStatus.ready) return { supported: false, reason: macStatus.reason };
     }
     if (!Fuse) return { supported: false, reason: 'fuse-native is not installed or failed to load' };
 
@@ -94,10 +93,13 @@ export async function checkFuseRuntime() {
 export class TelegramFS {
     constructor(options) {
         if (process.platform === 'darwin') {
-            throw new Error(
-                'TAS mount is currently unsupported on macOS. fuse-native 2.x targets obsolete OSXFUSE APIs ' +
-                'and is not compatible with current macFUSE on Apple Silicon. Use push/pull/sync/share instead.'
-            );
+            const macStatus = macFuse.validateMacFuseNativeBinding();
+            if (!macStatus.ready) {
+                throw new Error(
+                    'TAS mount needs current macFUSE plus a rebuilt native addon: ' + macStatus.reason +
+                    '. Install Xcode Command Line Tools, reinstall TAS, then run tas doctor.'
+                );
+            }
         }
         if (!Fuse) {
             throw new Error(