fufu-cloud-cli 0.9.3__tar.gz → 0.9.5__tar.gz

{fufu_cloud_cli-0.9.3 → fufu_cloud_cli-0.9.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fufu-cloud-cli
-Version: 0.9.3
+Version: 0.9.5
 Summary: FUFU Cloud CLI for tenant-scoped mock cloud development and deployment
 License-Expression: LicenseRef-Proprietary
 Requires-Python: >=3.10
@@ -14,15 +14,46 @@ Provides-Extra: test
 Requires-Dist: boto3==1.40.66; extra == "test"
 Provides-Extra: terraform
 Requires-Dist: python-hcl2==7.3.1; extra == "terraform"
+Provides-Extra: gcp
+Requires-Dist: google-cloud-bigquery==3.38.0; extra == "gcp"
+Requires-Dist: google-cloud-tasks==2.20.0; extra == "gcp"
+Requires-Dist: google-cloud-logging==3.12.1; extra == "gcp"
 Dynamic: license-file
 
 # FUFU Cloud CLI
 
-以五個指令操作 FUFU Cloud 的租戶隔離開發環境：`fufu`、`aws-fufu`、
-`gcloud-fufu`、`az-fufu`、`wrangler-fufu`。這是 AWS、Google Cloud、Azure 與 Cloudflare 的**明確子集**，
+以六個指令操作 FUFU Cloud 的租戶隔離開發環境：`fufu`、`aws-fufu`、
+`gcloud-fufu`、`az-fufu`、`wrangler-fufu`、`bq-fufu`。這是 AWS、Google Cloud、Azure 與 Cloudflare 的**明確子集**，
 只供 FUFU mock 環境使用；不會把部署轉送到正式雲端。
 
-0.9.3 新增 gcloud 常用輸出投影、資源清單篩選／排序／limit、Cloud Run 設定與環境變數更新、Service Account 查詢／停用／啟用，以及 Pub/Sub attributes、分頁和 message ACK deadline。這些行為已用官方 gcloud、小用量真實 GCP 與隔離 Docker 驗收；不表示完整 Google IAM、SDK／ADC 或自動擴縮相容。新增後端能力需要同步更新 FUFU Console 和 compute worker。
+0.9.5 新增 `gcloud-fufu scheduler`、`tasks`、`logging` 與 `bq-fufu`。
+支援同租戶已登錄 HTTP 應用的排程／背景任務、BigQuery dataset／table、
+insertAll／SELECT 與持久化日誌。`fufu_cloud_cli.gcp_sdk` 提供官方 Python
+BigQuery、Cloud Tasks、Logging SDK 的明確 REST factory；可用 `[gcp]` extra
+安裝已驗收相依。需要對應的新後端，並非透明 ADC 或所有 Google SDK 替換。
+
+`fufu infrastructure` 提供 14 類 typed configuration mock。Compute Engine、
+Cloud SQL、App Engine、DNS、VPC、Artifact Registry、Cloud Build、Gemini、
+VM Manager、Eventarc 等設定不會啟動 VM／SQL／registry／網路／推論。
+UI 顯示僅設定，CLI stderr 保留 MOCK ONLY，不因輸出投影而隱藏。
+新服務尚未接入 Terraform／OpenTofu／Pulumi；單機背景投遞不是雲端 HA。
+
+```bash
+gcloud-fufu scheduler jobs list
+gcloud-fufu tasks queues list
+bq-fufu query --use_legacy_sql=false 'SELECT 1 AS ready'
+gcloud-fufu logging read 'severity>=ERROR'
+fufu infrastructure catalog
+```
+
+BigQuery 是 tenant emulator 的 GoogleSQL 子集，無 DML／DDL、load/export、
+外部表與效能／費用等價。Logging 保留每租戶最新 10,000 筆，不自動收集所有
+容器 stdout。Tasks 每 queue 每秒最多 1 次、每租戶 2 個同時投遞；耗盡 task
+留待檢查，與官方刪除策略不同。新的 dependency flow 不代表完整應用都能遷移。
+
+0.9.4 新增 GCS generation／metageneration 條件、`storage objects describe/update/list`、8 KiB 自訂 metadata 與二進位 `cat`。競爭寫入、過期條件、CLI metadata 和官方 gcloud 輸出欄位已對照驗收；不相符條件回傳 `PRECONDITION_FAILED`／HTTP 412。新功能需要同步更新 FUFU Console、GCS 儲存映像和 Cloud Shell。儲存升級前須停寫並備份完整 volume；新 metadata 格式可讀舊資料，回滾須還原升級前備份。
+
+0.9.3 的常用輸出投影、清單篩選／排序／limit、Cloud Run 設定更新、Service Account 啟停及 Pub/Sub attributes／ACK deadline 持續保留。僅明列子集經過官方 gcloud、小用量真實 GCP 與隔離 Docker 驗收；不表示完整 Google IAM、SDK／ADC 或自動擴縮相容。
 
 0.9.1 統一所有 CLI API 請求的 `User-Agent: fufu-cloud-cli`，涵蓋物件傳輸、
 Cloudflare 靜態檔案部署、IaC 遠端 state 與 Cloud Shell session，避免沿用
@@ -34,7 +65,7 @@ Python 預設識別而遇到 Cloudflare HTTP 403／1010。識別標頭不取代
 ## Cloudflare 前端部署與 R2
 
 ```bash
-pip install 'fufu-cloud-cli==0.9.3'
+pip install 'fufu-cloud-cli==0.9.5'
 export FUFU_CLOUDFLARE_CREDENTIAL_FILE=/run/secrets/fufu-cloudflare.json
 wrangler-fufu capabilities
 wrangler-fufu pages project create frontend --production-branch main
@@ -78,7 +109,8 @@ pip install fufu-cloud-cli
 fufu --version
 ```
 
-npm 版本需要 Node.js 18 以上，以及已安裝的 Python 3.10 以上；各入口
+npm registry 尚未發布；以下是 registry 可用後的安裝語法。目前可安裝經驗收
+的 npm tarball。npm 版本需要 Node.js 18 以上，以及已安裝的 Python 3.10 以上；各入口
 呼叫相同的 Python CLI。0.8.0 的 npm 建置包內附純 Python YAML／TOML parser，沒有安裝腳本，
 不會自行下載 Python 或執行 pip。
 
@@ -95,12 +127,12 @@ npx --no-install aws-fufu --help
 
 ## 憑證與 CI
 
-目前工作樹另提供 `fufu tofu`、`fufu pulumi`、`fufu state`。
+目前版本另提供 `fufu tofu`、`fufu pulumi`、`fufu state`。
 Terraform／OpenTofu 可選擇租戶遠端 HTTP state，具備鎖、加密、版本與
 復原；需配套 Console API 和平台金鑰。Pulumi 使用固定官方 Node.js SDK，
 已驗收 SQS、SSM String、Pub/Sub topic／pull subscription，採獨立本機
-DIY backend，秘密欄位需外部 passphrase。這些新能力尚未包含在已發布
-的 0.8.0，不能把套件安裝成功當成支援驗收。
+DIY backend，秘密欄位需外部 passphrase。這些能力從 0.9.0 起納入 CLI，
+仍需要配套服務端；不能把套件安裝成功當成支援驗收。
 
 此工作樹也提供 `fufu terraform`：以官方 AWS／Google Terraform provider
 管理 Lambda ZIP、Cloud Run v2、IAM 與服務入口的明列子集，並使用獨立的
@@ -110,9 +142,9 @@ GCS／S3、Functions Gen 1／Gen 2 等一般 CLI 能力
 不表示官方 Terraform 資源已相容。正式環境使用正常 Terraform、正式認證
 與獨立 state，不可直接搬用 FUFU state。
 
-後續開發版另接入 SQS queue、SSM String parameter、Pub/Sub topic／pull
+目前版本另接入 SQS queue、SSM String parameter、Pub/Sub topic／pull
 subscription；新增能力需要配套的 Console 與 Pub/Sub 後端更新，不能從
-已發布的 0.8.0 安裝成功就推定已具備。`gcloud-fufu pubsub` 提供建立、
+CLI 安裝成功就推定服務端已具備。`gcloud-fufu pubsub` 提供建立、
 查詢、更新、刪除、publish／pull／ack 子集；不支援 push、ordering、
 exactly-once、Function trigger 或保留期限保證。
 
@@ -205,7 +237,8 @@ CLI 無法判斷任意原始碼或 ZIP 內的資料是否可以分享。
 | Cloud Run | 已核准 HTTP 容器或 API 自動建置 Python ASGI 來源；支援配置後的 HTTPS 入口、Invoker policy；無 autoscaling、traffic splitting、Jobs |
 | Cloud Run functions / Functions Gen 1 | Python 3.12 HTTP 函式；Gen 1 為相同 HTTP runtime 的模擬子集，無背景事件 |
 | AWS Lambda | Python 3.10 / 3.12 ZIP、同步 invoke、程式碼更新、BUFFERED Function URL；ZIP 50 MiB／解壓 250 MiB，同步 payload 6 MiB |
-| GCS / S3 | bucket 與 object 子集；分段上傳／串流下載，受主機磁碟限制；已驗證超過 1 GiB，無 versioning / signed URL |
+| GCS | bucket／object 子集、分段上傳／串流下載／binary cat、generation／metageneration 條件、metadata describe/update、前綴分頁；8 KiB custom metadata；無 versioning、signed URL、bucket IAM、一般 SDK 或 GCS IaC 資源 |
+| S3 | bucket 與 object 子集；分段上傳／串流下載，受主機磁碟限制；已驗證超過 1 GiB，無 versioning / signed URL |
 | DynamoDB / SQS / SSM | 明列資料操作；無完整交易、Streams、FIFO 或 KMS / SecureString |
 | AWS IAM / GCP IAM | 租戶內 role / service account / policy 子集；default deny、限定 session；無原生雲端全量 IAM 語義 |
 | API Gateway / Serverless profile | 簡化 HTTP Lambda proxy 和明確來源清單；不執行 plugins / CloudFormation |

fufu_cloud_cli-0.9.3/src/fufu_cloud_cli.egg-info/PKG-INFO → fufu_cloud_cli-0.9.5/README.md

@@ -1,28 +1,37 @@
-Metadata-Version: 2.4
-Name: fufu-cloud-cli
-Version: 0.9.3
-Summary: FUFU Cloud CLI for tenant-scoped mock cloud development and deployment
-License-Expression: LicenseRef-Proprietary
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: PyYAML==6.0.3
-Requires-Dist: tomli==2.2.1; python_version < "3.11"
-Provides-Extra: yaml
-Requires-Dist: PyYAML==6.0.3; extra == "yaml"
-Provides-Extra: test
-Requires-Dist: boto3==1.40.66; extra == "test"
-Provides-Extra: terraform
-Requires-Dist: python-hcl2==7.3.1; extra == "terraform"
-Dynamic: license-file
-
 # FUFU Cloud CLI
 
-以五個指令操作 FUFU Cloud 的租戶隔離開發環境：`fufu`、`aws-fufu`、
-`gcloud-fufu`、`az-fufu`、`wrangler-fufu`。這是 AWS、Google Cloud、Azure 與 Cloudflare 的**明確子集**，
+以六個指令操作 FUFU Cloud 的租戶隔離開發環境：`fufu`、`aws-fufu`、
+`gcloud-fufu`、`az-fufu`、`wrangler-fufu`、`bq-fufu`。這是 AWS、Google Cloud、Azure 與 Cloudflare 的**明確子集**，
 只供 FUFU mock 環境使用；不會把部署轉送到正式雲端。
 
-0.9.3 新增 gcloud 常用輸出投影、資源清單篩選／排序／limit、Cloud Run 設定與環境變數更新、Service Account 查詢／停用／啟用，以及 Pub/Sub attributes、分頁和 message ACK deadline。這些行為已用官方 gcloud、小用量真實 GCP 與隔離 Docker 驗收；不表示完整 Google IAM、SDK／ADC 或自動擴縮相容。新增後端能力需要同步更新 FUFU Console 和 compute worker。
+0.9.5 新增 `gcloud-fufu scheduler`、`tasks`、`logging` 與 `bq-fufu`。
+支援同租戶已登錄 HTTP 應用的排程／背景任務、BigQuery dataset／table、
+insertAll／SELECT 與持久化日誌。`fufu_cloud_cli.gcp_sdk` 提供官方 Python
+BigQuery、Cloud Tasks、Logging SDK 的明確 REST factory；可用 `[gcp]` extra
+安裝已驗收相依。需要對應的新後端，並非透明 ADC 或所有 Google SDK 替換。
+
+`fufu infrastructure` 提供 14 類 typed configuration mock。Compute Engine、
+Cloud SQL、App Engine、DNS、VPC、Artifact Registry、Cloud Build、Gemini、
+VM Manager、Eventarc 等設定不會啟動 VM／SQL／registry／網路／推論。
+UI 顯示僅設定，CLI stderr 保留 MOCK ONLY，不因輸出投影而隱藏。
+新服務尚未接入 Terraform／OpenTofu／Pulumi；單機背景投遞不是雲端 HA。
+
+```bash
+gcloud-fufu scheduler jobs list
+gcloud-fufu tasks queues list
+bq-fufu query --use_legacy_sql=false 'SELECT 1 AS ready'
+gcloud-fufu logging read 'severity>=ERROR'
+fufu infrastructure catalog
+```
+
+BigQuery 是 tenant emulator 的 GoogleSQL 子集，無 DML／DDL、load/export、
+外部表與效能／費用等價。Logging 保留每租戶最新 10,000 筆，不自動收集所有
+容器 stdout。Tasks 每 queue 每秒最多 1 次、每租戶 2 個同時投遞；耗盡 task
+留待檢查，與官方刪除策略不同。新的 dependency flow 不代表完整應用都能遷移。
+
+0.9.4 新增 GCS generation／metageneration 條件、`storage objects describe/update/list`、8 KiB 自訂 metadata 與二進位 `cat`。競爭寫入、過期條件、CLI metadata 和官方 gcloud 輸出欄位已對照驗收；不相符條件回傳 `PRECONDITION_FAILED`／HTTP 412。新功能需要同步更新 FUFU Console、GCS 儲存映像和 Cloud Shell。儲存升級前須停寫並備份完整 volume；新 metadata 格式可讀舊資料，回滾須還原升級前備份。
+
+0.9.3 的常用輸出投影、清單篩選／排序／limit、Cloud Run 設定更新、Service Account 啟停及 Pub/Sub attributes／ACK deadline 持續保留。僅明列子集經過官方 gcloud、小用量真實 GCP 與隔離 Docker 驗收；不表示完整 Google IAM、SDK／ADC 或自動擴縮相容。
 
 0.9.1 統一所有 CLI API 請求的 `User-Agent: fufu-cloud-cli`，涵蓋物件傳輸、
 Cloudflare 靜態檔案部署、IaC 遠端 state 與 Cloud Shell session，避免沿用
@@ -34,7 +43,7 @@ Python 預設識別而遇到 Cloudflare HTTP 403／1010。識別標頭不取代
 ## Cloudflare 前端部署與 R2
 
 ```bash
-pip install 'fufu-cloud-cli==0.9.3'
+pip install 'fufu-cloud-cli==0.9.5'
 export FUFU_CLOUDFLARE_CREDENTIAL_FILE=/run/secrets/fufu-cloudflare.json
 wrangler-fufu capabilities
 wrangler-fufu pages project create frontend --production-branch main
@@ -78,7 +87,8 @@ pip install fufu-cloud-cli
 fufu --version
 ```
 
-npm 版本需要 Node.js 18 以上，以及已安裝的 Python 3.10 以上；各入口
+npm registry 尚未發布；以下是 registry 可用後的安裝語法。目前可安裝經驗收
+的 npm tarball。npm 版本需要 Node.js 18 以上，以及已安裝的 Python 3.10 以上；各入口
 呼叫相同的 Python CLI。0.8.0 的 npm 建置包內附純 Python YAML／TOML parser，沒有安裝腳本，
 不會自行下載 Python 或執行 pip。
 
@@ -95,12 +105,12 @@ npx --no-install aws-fufu --help
 
 ## 憑證與 CI
 
-目前工作樹另提供 `fufu tofu`、`fufu pulumi`、`fufu state`。
+目前版本另提供 `fufu tofu`、`fufu pulumi`、`fufu state`。
 Terraform／OpenTofu 可選擇租戶遠端 HTTP state，具備鎖、加密、版本與
 復原；需配套 Console API 和平台金鑰。Pulumi 使用固定官方 Node.js SDK，
 已驗收 SQS、SSM String、Pub/Sub topic／pull subscription，採獨立本機
-DIY backend，秘密欄位需外部 passphrase。這些新能力尚未包含在已發布
-的 0.8.0，不能把套件安裝成功當成支援驗收。
+DIY backend，秘密欄位需外部 passphrase。這些能力從 0.9.0 起納入 CLI，
+仍需要配套服務端；不能把套件安裝成功當成支援驗收。
 
 此工作樹也提供 `fufu terraform`：以官方 AWS／Google Terraform provider
 管理 Lambda ZIP、Cloud Run v2、IAM 與服務入口的明列子集，並使用獨立的
@@ -110,9 +120,9 @@ GCS／S3、Functions Gen 1／Gen 2 等一般 CLI 能力
 不表示官方 Terraform 資源已相容。正式環境使用正常 Terraform、正式認證
 與獨立 state，不可直接搬用 FUFU state。
 
-後續開發版另接入 SQS queue、SSM String parameter、Pub/Sub topic／pull
+目前版本另接入 SQS queue、SSM String parameter、Pub/Sub topic／pull
 subscription；新增能力需要配套的 Console 與 Pub/Sub 後端更新，不能從
-已發布的 0.8.0 安裝成功就推定已具備。`gcloud-fufu pubsub` 提供建立、
+CLI 安裝成功就推定服務端已具備。`gcloud-fufu pubsub` 提供建立、
 查詢、更新、刪除、publish／pull／ack 子集；不支援 push、ordering、
 exactly-once、Function trigger 或保留期限保證。
 
@@ -205,7 +215,8 @@ CLI 無法判斷任意原始碼或 ZIP 內的資料是否可以分享。
 | Cloud Run | 已核准 HTTP 容器或 API 自動建置 Python ASGI 來源；支援配置後的 HTTPS 入口、Invoker policy；無 autoscaling、traffic splitting、Jobs |
 | Cloud Run functions / Functions Gen 1 | Python 3.12 HTTP 函式；Gen 1 為相同 HTTP runtime 的模擬子集，無背景事件 |
 | AWS Lambda | Python 3.10 / 3.12 ZIP、同步 invoke、程式碼更新、BUFFERED Function URL；ZIP 50 MiB／解壓 250 MiB，同步 payload 6 MiB |
-| GCS / S3 | bucket 與 object 子集；分段上傳／串流下載，受主機磁碟限制；已驗證超過 1 GiB，無 versioning / signed URL |
+| GCS | bucket／object 子集、分段上傳／串流下載／binary cat、generation／metageneration 條件、metadata describe/update、前綴分頁；8 KiB custom metadata；無 versioning、signed URL、bucket IAM、一般 SDK 或 GCS IaC 資源 |
+| S3 | bucket 與 object 子集；分段上傳／串流下載，受主機磁碟限制；已驗證超過 1 GiB，無 versioning / signed URL |
 | DynamoDB / SQS / SSM | 明列資料操作；無完整交易、Streams、FIFO 或 KMS / SecureString |
 | AWS IAM / GCP IAM | 租戶內 role / service account / policy 子集；default deny、限定 session；無原生雲端全量 IAM 語義 |
 | API Gateway / Serverless profile | 簡化 HTTP Lambda proxy 和明確來源清單；不執行 plugins / CloudFormation |

{fufu_cloud_cli-0.9.3 → fufu_cloud_cli-0.9.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fufu-cloud-cli"
-version = "0.9.3"
+version = "0.9.5"
 description = "FUFU Cloud CLI for tenant-scoped mock cloud development and deployment"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -16,6 +16,7 @@ license-files = ["LICENSE"]
 yaml = ["PyYAML==6.0.3"]
 test = ["boto3==1.40.66"]
 terraform = ["python-hcl2==7.3.1"]
+gcp = ["google-cloud-bigquery==3.38.0", "google-cloud-tasks==2.20.0", "google-cloud-logging==3.12.1"]
 
 [project.scripts]
 fufu = "fufu_cloud_cli.cli:main"
@@ -23,6 +24,7 @@ aws-fufu = "fufu_cloud_cli.cli:aws_main"
 gcloud-fufu = "fufu_cloud_cli.cli:gcloud_main"
 az-fufu = "fufu_cloud_cli.cli:az_main"
 wrangler-fufu = "fufu_cloud_cli.cli:wrangler_main"
+bq-fufu = "fufu_cloud_cli.cli:bq_main"
 
 [tool.setuptools.packages.find]
 where = ["src"]

{fufu_cloud_cli-0.9.3 → fufu_cloud_cli-0.9.5}/src/fufu_cloud_cli/__init__.py

@@ -1,3 +1,3 @@
 """FUFU CLI 與本機部署工具；相容範圍見 capabilities.json。"""
 
-__version__ = "0.9.3"
+__version__ = "0.9.5"

{fufu_cloud_cli-0.9.3 → fufu_cloud_cli-0.9.5}/src/fufu_cloud_cli/__main__.py

@@ -3,7 +3,7 @@ import sys
 from .cli import entry
 
 if __name__ == "__main__":
-    if len(sys.argv) > 1 and sys.argv[1] in {"fufu", "aws-fufu", "gcloud-fufu", "az-fufu"}:
+    if len(sys.argv) > 1 and sys.argv[1] in {"fufu", "aws-fufu", "gcloud-fufu", "az-fufu", "wrangler-fufu", "bq-fufu"}:
         entry(sys.argv[1], sys.argv[2:])
     else:
         entry("fufu", sys.argv[1:])

{fufu_cloud_cli-0.9.3 → fufu_cloud_cli-0.9.5}/src/fufu_cloud_cli/api_backend.py

@@ -185,7 +185,7 @@ class ApiClient:
         except HTTPError as exc:
             status = exc.code
             exc.close()
-            codes = {401: "AUTHENTICATION_FAILED", 403: "ACCESS_DENIED", 404: "RESOURCE_NOT_FOUND", 409: "RESOURCE_CONFLICT", 410: "UPLOAD_EXPIRED", 413: "PAYLOAD_LIMIT", 429: "RATE_LIMITED", 507: "STORAGE_CAPACITY"}
+            codes = {401: "AUTHENTICATION_FAILED", 403: "ACCESS_DENIED", 404: "RESOURCE_NOT_FOUND", 409: "RESOURCE_CONFLICT", 410: "UPLOAD_EXPIRED", 412: "PRECONDITION_FAILED", 413: "PAYLOAD_LIMIT", 429: "RATE_LIMITED", 507: "STORAGE_CAPACITY"}
             if status == 507: raise FufuError('STORAGE_CAPACITY', 'FUFU 主機磁碟容量不足；這是目前可用空間的限制，並非雲端物件大小上限。') from None
             raise FufuError(codes.get(status, "API_REQUEST_FAILED"), f"FUFU API 拒絕請求（HTTP {status}）；未輸出憑證或原始回應。") from None
         except (URLError, TimeoutError, ConnectionError) as exc:
@@ -211,7 +211,8 @@ class ApiClient:
                 return json.loads(response.read(65537))
         except HTTPError as error:
             status = error.code; error.close()
-            raise FufuError('OBJECT_TRANSFER_FAILED', f'物件傳輸未完成（HTTP {status}）；未覆寫下載目的地。') from None
+            code = 'PRECONDITION_FAILED' if self.provider == 'gcp' and status == 412 else 'OBJECT_TRANSFER_FAILED'
+            raise FufuError(code, f'物件傳輸未完成（HTTP {status}）；未覆寫下載目的地。') from None
 
     def close(self):
         if self.token and self.owns_token:
@@ -243,6 +244,9 @@ def storage_path(value):
 
 
 def remote_command(provider, argv, Parser):
+    if provider == 'gcp' and argv[:1] == ['storage']:
+        from .gcs import command
+        return command(argv[1:], Parser)
     p = Parser(prog={"aws": "aws-fufu", "gcp": "gcloud-fufu", "azure": "az-fufu"}[provider],
                description="FUFU API 憑證與租戶資源操作子集；無原生雲端 IAM／部署相容承諾。")
     roots = p.add_subparsers(dest="service", required=True)

fufu_cloud_cli-0.9.5/src/fufu_cloud_cli/bigquery.py

@@ -0,0 +1,92 @@
+"""bq command subset. Uses the same IAM-enforced BigQuery API as the console."""
+import json
+import sys
+from pathlib import Path
+from .api_backend import ApiClient
+from .errors import require
+from .gcp_infra import call
+
+
+def reference(value, project):
+    if ':' in value: selected, value = value.split(':', 1)
+    else: selected = project
+    require(selected == project, 'ACCESS_DENIED', 'BigQuery project 必須符合 credential scope。')
+    parts = value.split('.')
+    require(len(parts) <= 2 and all(parts), 'INVALID_RESOURCE', '請使用 project:dataset.table。')
+    return {'projectId': project, 'datasetId': parts[0], **({'tableId': parts[1]} if len(parts) == 2 else {})}
+
+
+def schema(value):
+    path = Path(value)
+    if path.is_file():
+        require(path.stat().st_size <= 1024**2, 'PAYLOAD_LIMIT', 'Schema 檔案超過 1 MiB。')
+        result = json.loads(path.read_text())
+        return result if isinstance(result, dict) else {'fields': result}
+    return {'fields': [{'name': name, 'type': kind.upper()} for name, kind in (field.split(':', 1) for field in value.split(','))]}
+
+
+def command(argv, Parser):
+    # bq permits global flags before or after the command.
+    project = location = None; clean = []; i = 0
+    while i < len(argv):
+        flag, sep, inline = argv[i].partition('=')
+        if flag in {'--project_id', '--location', '--format'}:
+            value = inline if sep else (argv[i + 1] if i + 1 < len(argv) else '')
+            require(value and not value.startswith('--'), 'INVALID_ARGUMENT', '全域參數缺少值。')
+            if flag == '--project_id': project = value
+            elif flag == '--location': location = value
+            else: require(value in {'json', 'prettyjson'}, 'UNSUPPORTED_FORMAT', 'bq-fufu 輸出支援 json 與 prettyjson。')
+            i += 1 if sep else 2
+        elif flag in {'--quiet', '-q', '--headless'}: i += 1
+        else: clean.append(argv[i]); i += 1
+    p = Parser(prog='bq-fufu', description='BigQuery dataset/table、insertAll 與 SELECT 子集。未支援 load jobs、DML/DDL、external tables 或成本估算。')
+    actions = p.add_subparsers(dest='action', required=True)
+    for action in ['mk', 'ls', 'show', 'rm', 'head']:
+        q = actions.add_parser(action)
+        q.add_argument('resource', nargs='?' if action == 'ls' else None)
+        q.add_argument('--dataset', '-d', action='store_true'); q.add_argument('--table', '-t', action='store_true')
+        if action == 'mk': q.add_argument('schema', nargs='?'); q.add_argument('--description')
+        if action == 'rm': q.add_argument('--recursive', '-r', action='store_true'); q.add_argument('--force', '-f', action='store_true')
+        if action in {'head', 'ls'}: q.add_argument('--max_results', '-n', type=int, default=100); q.add_argument('--page_token')
+    q = actions.add_parser('query'); q.add_argument('query'); q.add_argument('--use_legacy_sql', choices=['false'], default='false'); q.add_argument('--nouse_legacy_sql', action='store_true'); q.add_argument('--parameter', action='append', default=[]); q.add_argument('--max_rows', type=int, default=100)
+    q = actions.add_parser('insert'); q.add_argument('resource'); q.add_argument('file')
+    a = p.parse_args(clean)
+    sys.stderr.write('FUFU BigQuery subset: tenant emulator; unsupported SQL and job types fail explicitly.\n')
+    with ApiClient('gcp', read_only=a.action in {'ls', 'show', 'head'}) as api:
+        selected = api.whoami()['projectId']
+        require(project is None or project == selected, 'ACCESS_DENIED', 'BigQuery project 必須符合 credential scope。')
+        if a.action == 'query':
+            params = {'projectId': selected, 'query': a.query, 'useLegacySql': False, 'maxResults': a.max_rows}
+            if location: params['location'] = location
+            if a.parameter:
+                params['parameterMode'] = 'NAMED'; params['queryParameters'] = []
+                for value in a.parameter:
+                    parts = value.split(':', 2); require(len(parts) == 3, 'INVALID_ARGUMENT', 'parameter 請使用 name:type:value。')
+                    name, kind, data = parts
+                    params['queryParameters'].append({'name': name, 'parameterType': {'type': kind.upper() or 'STRING'}, 'parameterValue': {'value': data}})
+            return call(api, 'bigquery', 'queries.query', params)
+        ref = reference(a.resource, selected) if a.resource else {'projectId': selected}
+        table = 'tableId' in ref
+        if getattr(a, 'dataset', False): require(not table, 'INVALID_RESOURCE', 'Dataset 命令不可傳入 table。')
+        if getattr(a, 'table', False): require(table, 'INVALID_RESOURCE', 'Table 命令需要 dataset.table。')
+        group = 'tables' if table else 'datasets'
+        if a.action == 'mk':
+            require(not table or a.schema, 'INVALID_ARGUMENT', 'Table 建立需要 schema。')
+            value = {'tableReference' if table else 'datasetReference': ref}
+            if table: value['schema'] = schema(a.schema)
+            elif location: value['location'] = location
+            if a.description is not None: value['description'] = a.description
+            return call(api, 'bigquery', group + '.insert', {'projectId': selected, **({'datasetId': ref['datasetId']} if table else {}), 'table' if table else 'dataset': value})
+        if a.action == 'rm': return call(api, 'bigquery', group + '.delete', {**ref, **({'deleteContents': a.recursive} if not table else {})})
+        if a.action == 'show': return call(api, 'bigquery', group + '.get', ref)
+        if a.action in {'ls', 'head'}:
+            require(a.action != 'head' or table, 'INVALID_RESOURCE', 'head 需要 table。')
+            require(a.action != 'ls' or not table, 'INVALID_RESOURCE', 'ls 請指定 dataset。')
+            op = 'tabledata.list' if table else 'tables.list' if 'datasetId' in ref else 'datasets.list'
+            return call(api, 'bigquery', op, {**ref, 'maxResults': a.max_results, **({'pageToken': a.page_token} if a.page_token else {})})
+        require(table, 'INVALID_RESOURCE', 'insert 需要 table。')
+        file = Path(a.file); require(file.is_file() and file.stat().st_size <= 10 * 1024**2, 'PAYLOAD_LIMIT', 'NDJSON 檔案超過 10 MiB。')
+        rows = [{'json': json.loads(line)} for line in file.read_text().splitlines() if line.strip()]
+        result = call(api, 'bigquery', 'tabledata.insertAll', {**ref, 'rows': rows})
+        require(not result.get('insertErrors'), 'BIGQUERY_INSERT_FAILED', 'BigQuery 拒絕部分資料列；請檢查 schema。')
+        return result