feat(fs): add filesystem operations for TiDB Cloud FS

docs/fs.md

@@ -0,0 +1,338 @@
+# TiDB Cloud FS (ticloud fs) User Guide
+
+**TiDB Cloud FS** is a managed file storage service provided by TiDB Cloud that offers a unified filesystem abstraction for TiDB instances. You can store, read, and manage files in TiDB Cloud just like a local filesystem, with advanced capabilities such as SQL queries, a secret vault, and FUSE mount support.
+
+**`ticloud fs`** is the command group in the TiDB Cloud CLI for operating TiDB Cloud FS, supporting upload/download, directory browsing, SQL execution, secret management, and FUSE mount.
+
+---
+
+## Prerequisites: Associate a TiDB Instance
+
+FS data storage depends on a specific TiDB instance. Depending on the type of instance you have, you need to bind its ID to the CLI configuration and complete a one-time FS initialization (`init`).
+
+### Using Serverless TiDB
+
+If you already have a **TiDB Cloud Serverless** cluster (created via the [TiDB Cloud Web Console](https://tidbcloud.com/) or the `ticloud serverless create` command), configure it as follows:
+
+1. **Configure Authentication**
+
+   Serverless clusters are managed by the TiDB Cloud platform, so you must provide valid platform credentials to access their FS service. Choose one of the following methods:
+
+   - **OAuth Login (Recommended)**
+
+     ```bash
+     ticloud auth login
+     ```
+
+   - **API Key Authentication**
+
+     ```bash
+     ticloud config set public-key <your-public-key>
+     ticloud config set private-key <your-private-key>
+     ```
+
+2. **Configure cluster-id**
+
+   ```bash
+   ticloud config set fs.cluster-id <your-serverless-cluster-id>
+   ```
+
+3. **Initialize FS**
+
+   ```bash
+   ticloud fs init --user root --password <your-password>
+   ```
+
+   > Every new Serverless cluster must run `init` before using FS for the first time to provision the FS tenant.
+
+### Using Zero TiDB
+
+If you are using a **TiDB Zero** instance, configure it as follows. If you are not familiar with TiDB Zero, visit [https://zero.tidbcloud.com/](https://zero.tidbcloud.com/) to learn more.
+
+1. **Configure zero-instance-id**
+
+   ```bash
+   ticloud config set fs.zero-instance-id <your-zero-instance-id>
+   ```
+
+   TiDB Zero uses an independent deployment and access model. You **do not** need to run `ticloud auth login` or configure `public-key` / `private-key`.
+
+2. **Initialize FS**
+
+   ```bash
+   ticloud fs init --user root --password <your-password>
+   ```
+
+   > Like Serverless, every new Zero instance must run `init` once to provision the FS tenant.
+
+---
+
+## Path Format
+
+FS uses the `:/` prefix to denote remote paths:
+
+- `:/` — Remote root directory
+- `:/path/to/file.txt` — Remote file path
+
+---
+
+## Subcommand Manual
+
+### Initialization and Configuration
+
+Before performing any file operations, you must create an FS tenant for the associated database. This step only needs to be performed once.
+
+#### `ticloud fs init`
+
+Initialize the FS tenant for the currently associated database. This must be run before using FS for the first time on a new database.
+
+```bash
+ticloud fs init --user root --password secret
+```
+
+### Basic File Operations
+
+`ticloud fs` provides a set of Unix-like filesystem commands for managing remote files and directories. You can upload, download, browse, and delete files as if they were local.
+
+#### `ticloud fs ls`
+
+List remote directory contents. Supports `-l` for detailed view.
+
+```bash
+# List root directory
+ticloud fs ls :/
+
+# List a folder with size details
+ticloud fs ls -l :/myfolder
+```
+
+#### `ticloud fs cat`
+
+Display remote file contents, similar to the Unix `cat` command. Useful for quickly viewing text files.
+
+```bash
+ticloud fs cat :/readme.txt
+```
+
+#### `ticloud fs cp`
+
+Copy files. Supports local↔remote, remote↔remote, stdin upload, and resuming large file transfers.
+
+```bash
+# Upload a local file to remote
+ticloud fs cp local.txt :/remote/
+
+# Download a remote file to current directory
+ticloud fs cp :/remote/file.txt .
+
+# Upload from stdin via pipe
+echo "hello" | ticloud fs cp - :/file.txt
+
+# Resume a large file upload (useful for unstable networks)
+ticloud fs cp --resume large.zip :/remote/
+```
+
+#### `ticloud fs mkdir`
+
+Create a remote directory. Supports nested paths.
+
+```bash
+ticloud fs mkdir :/mydir
+```
+
+#### `ticloud fs mv`
+
+Move or rename remote files/directories.
+
+```bash
+ticloud fs mv :/oldname :/newname
+```
+
+#### `ticloud fs rm`
+
+Delete remote files or empty directories.
+
+```bash
+ticloud fs rm :/file.txt
+```
+
+#### `ticloud fs stat`
+
+View remote file or directory metadata, such as size and modification time.
+
+```bash
+ticloud fs stat :/file.txt
+```
+
+### Search and Query
+
+In addition to basic file operations, `ticloud fs` supports searching file contents and executing SQL queries directly on remote storage, making it easy to locate information or perform data analysis.
+
+#### `ticloud fs grep`
+
+Search for matching content in remote files. Supports `--limit` to restrict the number of results.
+
+```bash
+ticloud fs grep "TODO" :/project --limit 20
+```
+
+#### `ticloud fs find`
+
+Find remote files by criteria. Supports `-name`, `-size`, `-newer` filters, similar to the Unix `find` command.
+
+```bash
+# Find by file extension
+ticloud fs find :/ -name "*.go"
+
+# Find files larger than 1MB
+ticloud fs find :/ -size +1M
+```
+
+#### `ticloud fs sql`
+
+Execute SQL queries against the FS backend for structured queries on stored data.
+
+```bash
+ticloud fs sql -q "SELECT 1"
+```
+
+### Secret Management
+
+TiDB Cloud FS includes a built-in secret vault for securely storing sensitive information such as database connection strings and API keys. You can manage these secrets via subcommands, and issue scoped capability tokens for third-party agents.
+
+#### `ticloud fs secret set`
+
+Create or update a secret. Field values can be set directly, read from a file (`@file`), or read from stdin (`-`).
+
+```bash
+# Set fields directly
+ticloud fs secret set myapp DATABASE_URL=mysql://...
+
+# Read a field from file and password from stdin
+ticloud fs secret set myapp key=@secret.txt password=-
+```
+
+#### `ticloud fs secret get`
+
+Read a secret or a specific field. Supports `--json` and `--env` output formats.
+
+```bash
+# Read the entire secret
+ticloud fs secret get myapp
+
+# Read a specific field and output as JSON
+ticloud fs secret get myapp/password --json
+```
+
+#### `ticloud fs secret exec`
+
+Execute a command with secret fields injected as environment variables. Commonly used in local scripts or CI pipelines to securely use secrets.
+
+```bash
+ticloud fs secret exec myapp -- ./run.sh
+```
+
+#### `ticloud fs secret ls`
+
+List all secrets. Supports `--json` output.
+
+```bash
+ticloud fs secret ls
+```
+
+#### `ticloud fs secret rm`
+
+Delete a specific secret.
+
+```bash
+ticloud fs secret rm myapp
+```
+
+#### `ticloud fs secret grant`
+
+Issue a scoped capability token for a specific agent, restricting access to certain secrets. Requires `--agent` and `--ttl`.
+
+```bash
+ticloud fs secret grant --agent myagent --ttl 1h myapp/password
+```
+
+#### `ticloud fs secret revoke`
+
+Revoke an issued capability token, invalidating it immediately.
+
+```bash
+ticloud fs secret revoke tok_abc123
+```
+
+#### `ticloud fs secret audit`
+
+Query the secret audit log to track who accessed which secrets and when. Supports filtering by `--secret`, `--agent`, `--since`, and limiting results with `--limit`.
+
+```bash
+# View the latest 50 audit events
+ticloud fs secret audit --limit 50
+
+# View audit events for a secret in the last 24 hours
+ticloud fs secret audit --secret myapp --since 24h
+```
+
+### Interactive Shell
+
+If you need to execute multiple FS commands frequently, you can use the interactive shell to avoid typing the full command prefix each time.
+
+#### `ticloud fs shell`
+
+Launch the interactive FS Shell. Supports commands such as `cd`, `pwd`, `ls`, `cat`, `cp`, `mkdir`, `mv`, `rm`, `sql`, `stat`, `help`, `exit`. The prompt is `ticloud:fs>`.
+
+```bash
+ticloud fs shell
+```
+
+### FUSE Mount
+
+Via FUSE mount, you can map the remote FS to a local directory and access it using the system file manager or standard command-line tools.
+
+#### `ticloud fs mount`
+
+Mount the remote FS to a local directory. The current version defaults to read-only. Supports `--debug` (enable debug logging) and `--allow-other` (allow other users to access).
+
+```bash
+ticloud fs mount /mnt/tidbcloud
+```
+
+#### `ticloud fs umount`
+
+Unmount the local mount point, safely disconnecting from the remote FS.
+
+```bash
+ticloud fs umount /mnt/tidbcloud
+```
+
+---
+
+## Configuration Quick Reference
+
+| Property | Description | Default |
+|----------|-------------|---------|
+| `fs.cluster-id` | Associated Serverless cluster ID | — |
+| `fs.zero-instance-id` | Associated Zero instance ID | — |
+| `fs-endpoint` | FS server endpoint | `https://fs.tidbapi.com/` |
+| `public-key` / `private-key` | API Key authentication for Serverless | — |
+
+You can also override these via environment variables:
+
+- `TICLOUD_FS_ENDPOINT` — overrides `fs-endpoint`
+- `TICLOUD_FS_CLUSTER_ID` — overrides `fs.cluster-id`
+- `TICLOUD_FS_ZERO_INSTANCE_ID` — overrides `fs.zero-instance-id`
+
+---
+
+## FAQ
+
+**Q: Running `ticloud fs ls :/` returns `tenant not found`?**
+
+A: The associated database has not been initialized for FS yet. Please run `ticloud fs init --user <user> --password <password>` to complete initialization.
+
+**Q: Serverless cluster returns 401 Unauthorized?**
+
+A: Please confirm you have completed `ticloud auth login` or correctly configured `public-key` / `private-key`.

go.mod

@@ -17,6 +17,7 @@ require (
 	github.com/go-resty/resty/v2 v2.11.0
 	github.com/go-sql-driver/mysql v1.8.1
 	github.com/google/go-github/v49 v49.0.0
+	github.com/hanwen/go-fuse/v2 v2.9.0
 	github.com/hashicorp/go-version v1.6.0
 	github.com/icholy/digest v0.1.22
 	github.com/juju/errors v1.0.0
@@ -124,3 +125,5 @@ require (
 )
 
 replace github.com/tidbcloud/tidbcloud-cli/pkg => ./pkg
+
+replace github.com/golang-module/carbon/v2 => github.com/dromara/carbon/v2 v2.3.12

go.sum

@@ -269,6 +269,8 @@ github.com/docker/go-connections v0.5.0 h1:USnMq7hx7gwdVZq1L49hLXaFtUdTADjXGp+uj
 github.com/docker/go-connections v0.5.0/go.mod h1:ov60Kzw0kKElRwhNs9UlUHAE/F9Fe6GLaXnqyDdmEXc=
 github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
 github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
+github.com/dromara/carbon/v2 v2.3.12 h1:Fj9164o0w5jfcqDjvEOZSYdoajsBxpslm7PvhATcokc=
+github.com/dromara/carbon/v2 v2.3.12/go.mod h1:HNsedGzXGuNciZImYP2OMnpiwq/vhIstR/vn45ib5cI=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/dvsekhvalnov/jose2go v1.7.0 h1:bnQc8+GMnidJZA8zc6lLEAb4xNrIqHwO+9TzqvtQZPo=
@@ -341,8 +343,6 @@ github.com/golang-jwt/jwt/v4 v4.5.0 h1:7cYmW1XlMY7h7ii7UhUyChSgS5wUJEnm9uZVTGqOW
 github.com/golang-jwt/jwt/v4 v4.5.0/go.mod h1:m21LjoU+eqJr34lmDMbreY2eSTRJ1cv77w39/MY0Ch0=
 github.com/golang-jwt/jwt/v5 v5.2.1 h1:OuVbFODueb089Lh128TAcimifWaLhJwVflnrgM17wHk=
 github.com/golang-jwt/jwt/v5 v5.2.1/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
-github.com/golang-module/carbon/v2 v2.3.12 h1:VC1DwN1kBwJkh5MjXmTFryjs5g4CWyoM8HAHffZPX/k=
-github.com/golang-module/carbon/v2 v2.3.12/go.mod h1:HNsedGzXGuNciZImYP2OMnpiwq/vhIstR/vn45ib5cI=
 github.com/golang-sql/civil v0.0.0-20220223132316-b832511892a9 h1:au07oEsX2xN0ktxqI+Sida1w446QrXBRJ0nee3SNZlA=
 github.com/golang-sql/civil v0.0.0-20220223132316-b832511892a9/go.mod h1:8vg3r2VgvsThLBIFL93Qb5yWzgyZWhEmBwUJWevAkK0=
 github.com/golang-sql/sqlexp v0.1.0 h1:ZCD6MBpcuOVfGVqsEmY5/4FtYiKz6tSyUv9LPEDei6A=
@@ -386,6 +386,8 @@ github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c h1:6rhixN/i8
 github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c/go.mod h1:NMPJylDgVpX0MLRlPy15sqSwOFv/U1GZ2m21JhFfek0=
 github.com/hailocab/go-hostpool v0.0.0-20160125115350-e80d13ce29ed h1:5upAirOpQc1Q53c0bnx2ufif5kANL7bfZWcc6VJWJd8=
 github.com/hailocab/go-hostpool v0.0.0-20160125115350-e80d13ce29ed/go.mod h1:tMWxXQ9wFIaZeTI9F+hmhFiGpFmhOHzyShyFUhRm0H4=
+github.com/hanwen/go-fuse/v2 v2.9.0 h1:0AOGUkHtbOVeyGLr0tXupiid1Vg7QB7M6YUcdmVdC58=
+github.com/hanwen/go-fuse/v2 v2.9.0/go.mod h1:yE6D2PqWwm3CbYRxFXV9xUd8Md5d6NG0WBs5spCswmI=
 github.com/hashicorp/go-cleanhttp v0.5.2 h1:035FKYIWjmULyFRBKPs8TBQoi0x6d9G4xc9neXJWAZQ=
 github.com/hashicorp/go-cleanhttp v0.5.2/go.mod h1:kO/YDlP8L1346E6Sodw+PrpBSV4/SoxCXGY6BqNFT48=
 github.com/hashicorp/go-retryablehttp v0.7.7 h1:C8hUCYzor8PIfXHa4UrZkU4VvK8o9ISHxT2Q8+VepXU=
@@ -518,6 +520,8 @@ github.com/mithrandie/ternary v1.1.1 h1:k/joD6UGVYxHixYmSR8EGgDFNONBMqyD373xT4QR
 github.com/mithrandie/ternary v1.1.1/go.mod h1:0D9Ba3+09K2TdSZO7/bFCC0GjSXetCvYuYq0u8FY/1g=
 github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
 github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
+github.com/moby/sys/mountinfo v0.7.2 h1:1shs6aH5s4o5H2zQLn796ADW1wMrIwHsyJ2v9KouLrg=
+github.com/moby/sys/mountinfo v0.7.2/go.mod h1:1YOa8w8Ih7uW0wALDUgT1dTTSBrZ+HiBLGws92L2RU4=
 github.com/moby/term v0.5.0 h1:xt8Q1nalod/v7BqbG21f8mQPqH+xAaC9C3N3wfWbVP0=
 github.com/moby/term v0.5.0/go.mod h1:8FzsFHVUBGZdbDsJw/ot+X+d5HLUbvklYLJ9uGfcI3Y=
 github.com/mtibben/percent v0.2.1 h1:5gssi8Nqo8QU/r2pynCm+hBQHpkB/uNK7BJCFogWdzs=