Metadata-Version: 2.4
Name: fufu-cloud-cli
Version: 0.9.6
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: jmespath==1.1.0
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"
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`、`bq-fufu`。這是 AWS、Google Cloud、Azure 與 Cloudflare 的**明確子集**，
只供 FUFU mock 環境使用；不會把部署轉送到正式雲端。

0.9.6 新增 AWS Lambda Event／DryRun、configuration 更新、JMESPath `--query`、
json／text／yaml 輸出、SQS FIFO／batch、SSM path／history、DynamoDB Binary
及 CloudWatch Logs。需要配套後端；Event 202 只表示持久化接受，並非 handler
執行完成。仍無完整 AWS CLI 自動分頁、table、Layers／Image／aliases 或全量 IAM。

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，避免沿用
Python 預設識別而遇到 Cloudflare HTTP 403／1010。識別標頭不取代 credential
或 IAM；HTTPS 驗證、禁止重新導向與不使用環境代理的行為保留。

0.8.0 包含資源配額、分段傳輸、Terraform 核心子集與 Cloudflare 靜態部署／R2。需要同步更新服務端；CLI 安裝成功不表示任意 FUFU 服務端都已有這些能力。

## Cloudflare 前端部署與 R2

```bash
pip install 'fufu-cloud-cli==0.9.6'
export FUFU_CLOUDFLARE_CREDENTIAL_FILE=/run/secrets/fufu-cloudflare.json
wrangler-fufu capabilities
wrangler-fufu pages project create frontend --production-branch main
npm run build
wrangler-fufu pages deploy dist --project-name frontend --branch main
wrangler-fufu pages deployment list --project-name frontend
wrangler-fufu deploy --assets dist --name frontend-assets
wrangler-fufu r2 bucket create frontend-files
wrangler-fufu r2 object put frontend-files/example.txt --file example.txt --remote
```

支援 Wrangler JSON、JSONC、TOML，以及 `--config`、`--cwd`、`--env`。Pages 使用
`pages_build_output_dir`；Workers Static Assets 使用 `assets.directory`，SPA 可明確設定
`assets.not_found_handling = "single-page-application"`。正式與預覽網址分開，正式部署完整
上傳且校驗通過才切换入口；Pages 可用 `pages deployment rollback ID --project-name NAME` 回滾。

這些命令提供真正的靜態 HTTP hosting，**不執行 Workers JavaScript 或 Pages Functions**。
KV、D1、Durable Objects、Queues、Cron、自訂網域、SSR 與全球 CDN 快取未實作；
相關配置會被拒絕。API credential、S3 endpoint 與帳號識別使用 FUFU 值。
目前不讀取官方 `CLOUDFLARE_API_TOKEN`；使用 FUFU credential JSON，避免誤用正式金鑰。

R2 支援 bucket／object、分段上傳、範圍下載、CORS、預設私人及可開關公開開發網址。
原生 boto3／AWS S3 SDK 可使用 credential JSON 中的 `r2_endpoint`、`r2_access_key_id`、
`r2_secret_access_key`，region 為 `auto` 且使用 path-style addressing。
SDK checksum 配置使用 `WHEN_REQUIRED`；SigV4、預簽 PUT／GET、Content-MD5、
基本自訂 metadata 與 multipart 已支援。未支援條件寫入、CopyObject、版本／生命週期、
自訂加密，以及 Cache-Control／Content-Encoding 等寫入 metadata；會明確回錯，不靜默忽略。
沒有 Cloudflare Terraform provider 相容層。

静態檔案上限 25 MiB／每次最多 100,000 檔；R2 物件上限 5 TiB、S3 單次或分段上限
5 GiB、最多 10,000 段。可用磁碟、請求逾時與併發容量仍會限制實際可接受大小。
公開部署前拒絕私人路徑、符號連結與已知 credential 格式；此檢查不是所有機密的偵測器。
FUFU 沒有 CDN 快取，入口回覆 `Cache-Control: no-store`，不模擬一次成功的 cache purge。

## 安裝

需要 Python 3.10 以上。Python 套件預設包含 YAML 相依套件：

```bash
pip install fufu-cloud-cli
fufu --version
```

npm registry 尚未發布；以下是 registry 可用後的安裝語法。目前可安裝經驗收
的 npm tarball。npm 版本需要 Node.js 18 以上，以及已安裝的 Python 3.10 以上；各入口
呼叫相同的 Python CLI。0.8.0 的 npm 建置包內附純 Python YAML／TOML parser，沒有安裝腳本，
不會自行下載 Python 或執行 pip。

```bash
npm install fufu-cloud-cli
npx --no-install fufu --version
npx --no-install aws-fufu --help
```

全域安裝可使用 `npm install -g fufu-cloud-cli`。預設 Python 指令為 `python3`；
若名稱不同，將 `FUFU_PYTHON` 設成可信 Python 執行檔的路徑。
本機 Docker backend 只支援 Linux 與本機 Unix socket。API backend
不需要安裝 Docker；其他作業系統仍須另外驗證其 Python 與網路環境。

## 憑證與 CI

目前版本另提供 `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.9.0 起納入 CLI，
仍需要配套服務端；不能把套件安裝成功當成支援驗收。

此工作樹也提供 `fufu terraform`：以官方 AWS／Google Terraform provider
管理 Lambda ZIP、Cloud Run v2、IAM 與服務入口的明列子集，並使用獨立的
FUFU state。Terraform 需另行安裝，Python 使用 `fufu-cloud-cli[terraform]`
extra；npm 使用的 Python 也需要該 extra 的相依套件。使用 0.8.0 以上版本。
GCS／S3、Functions Gen 1／Gen 2 等一般 CLI 能力
不表示官方 Terraform 資源已相容。正式環境使用正常 Terraform、正式認證
與獨立 state，不可直接搬用 FUFU state。

目前版本另接入 SQS queue、SSM String parameter、Pub/Sub topic／pull
subscription；新增能力需要配套的 Console 與 Pub/Sub 後端更新，不能從
CLI 安裝成功就推定服務端已具備。`gcloud-fufu pubsub` 提供建立、
查詢、更新、刪除、publish／pull／ack 子集；不支援 push、ordering、
exactly-once、Function trigger 或保留期限保證。

向 FUFU Cloud 管理者取得該租戶、該 provider 的專用 credential JSON。
CLI 不附預設帳號、共用金鑰或可用的租戶憑證，也不讀取 `.env`、瀏覽器
Cookie 或正式雲端登入工作階段。

在 CI 的秘密管理功能中注入 credential 檔案，並設定：

```bash
export FUFU_BACKEND=api
export FUFU_AWS_CREDENTIAL_FILE=/run/secrets/fufu-aws.json
export FUFU_GCP_CREDENTIAL_FILE=/run/secrets/fufu-gcp.json
export FUFU_AZURE_CREDENTIAL_FILE=/run/secrets/fufu-azure.json
export FUFU_CLOUDFLARE_CREDENTIAL_FILE=/run/secrets/fufu-cloudflare.json

fufu auth whoami --provider aws
aws-fufu sts get-caller-identity
gcloud-fufu auth list
az-fufu account show
wrangler-fufu whoami
```

credential 內含 FUFU endpoint。`FUFU_ENDPOINT` 可明確覆寫目的地：僅限
你信任且獲授權接收 credential 的 FUFU 服務。正式網路需使用 HTTPS；
只有 loopback 允許 HTTP。TLS 憑證驗證保持開啟，不跟隨重新導向，
不繼承系統 HTTP proxy。

一般命令交換短期權杖並在結束時嘗試撤銷。`fufu auth assume-role`
可建立受限 session 檔，檔案以排他方式建立且權限為 `0600`；請勿提交。
FUFU credential 與 session 檔仍屬秘密，必須由作業系統和 CI 控制存取。
原生雲端的 GitHub auth actions、OIDC 和 OAuth 不直接相容。
Lambda Function URL 的 AWS_IAM 支援長效 FUFU access key 的 SigV4 header signing；管理 API 仍使用 FUFU token。

## 部署與支援範圍

0.9.0 的配套後端新增 AWS／GCP Secrets Manager、GCP 部署秘密參照、
Cloud Run SSE／WebSocket、HTTP Functions SSE，以及目前運行版本的身分續期。
服務端須配置私有加密金鑰；未配置時會明確拒絕秘密操作。

```bash
aws-fufu secretsmanager create-secret --name app-key --secret-string file://./dev-secret.txt
aws-fufu secretsmanager get-secret-value --secret-id app-key --out-file ./private-result.txt
gcloud-fufu secrets create app-key --data-file ./dev-secret.txt
gcloud-fufu run deploy example --source ./prepared-asgi.zip \
  --service-account "$WORKLOAD_SERVICE_ACCOUNT" --set-secrets APP_KEY=app-key:1
```

秘密值只由受控檔案或 `--secret-env VARIABLE` 輸入；讀取需指定私有新檔案，
不會輸出到終端。Cloud Run／Functions 的 service account 需 Secret Accessor
權限。支援 `--update-secrets`、`--clear-secrets` 和 Knative `secretKeyRef`。
這是本機加密版本管理子集：AWS 為 UTF-8 SecretString，單值最大 64 KiB；
無 KMS、rotation、跨區域複寫、排程刪除與復原。立即刪除或銷毀後，加密
備份與既有容器可能仍持有舊值。CLI metadata 採 FUFU 共用形狀，並非完整
官方 JSON；GCP runtime 使用明確 helper，無全量 Google SDK／ADC 替換。
新的秘密資源與 Terraform／OpenTofu／Pulumi 參照尚未接通。

Cloud Run 串流回應不設原本的 32 MiB 緩衝上限，仍受服務期限及容量限制。
HTTP Functions Gen 1／Gen 2 支援 SSE、無 WebSocket；Gen 2 保留較寬鬆的
32 MiB response，而官方 streaming response 是 10 MB。Lambda 仍為 buffered。
公網 DNS、TLS、WAF 及 CDN 期限須另外驗證。

```bash
fufu capabilities
fufu capabilities --remote --provider gcp --require cloud-run-http
gcloud-fufu run deploy example --image approved-image:tag
gcloud-fufu run deploy example --source ./prepared-asgi.zip --entry-point main:app
gcloud-fufu functions deploy example-function --gen2 \
  --runtime python312 --source ./function --entry-point handler --trigger-http
aws-fufu lambda list-functions
```

自訂映像需先由 FUFU 管理者準備及核准。API 模式的 Cloud Run `--source`
接受已封裝 Uvicorn 與相依套件的 Python 3.12 ASGI ZIP／乾淨目錄，自動離線建置、
檢查映像並核准到目前租戶；不需要主機 SSH 或每次人工核准。
`--entry-point module:app` 是 FUFU 擴充旗標，預設 `main:app`。
目前來源版本的 FUFU 配方上限為 ZIP 512 MiB、解壓縮 2 GiB、100000 個檔案；不接受隱藏檔、Dockerfile、
自訂安裝設定或非空 requirements.txt。相依套件需在 CI 封裝，服務端不執行安裝 hook。
這是固定 ASGI 配方，不提供完整 Cloud Build 或 registry API。
成功回應包含 `build.status`、`imageDigest` 與來源包雜湊；自動核准映像
僅供該租戶目前服務使用，取代或刪除最後一個引用後不再開放重用。

Function 來源會上傳指定目錄中的
Python 與 requirements 檔；Lambda 會上傳指定的 ZIP。請使用只含必要程式碼的
目錄或 ZIP，先移除硬編碼秘密、個人資料與不需要的檔案。
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、configuration、RequestResponse／Event／DryRun、BUFFERED Function URL；ZIP 50 MiB／解壓 250 MiB，同步 6 MiB／Event 1 MiB；Event 為單機持久化重試，無 destinations／DLQ 或正式 autoscaling |
| 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 | 明列資料操作、Binary、FIFO group／dedup／batch、SSM 版本／path／history；無交易／TTL／Streams、SQS 背景 poller／DLQ／加密、KMS／SecureString |
| CloudWatch Logs | group／stream、put/get/filter events、retention 設定、CLI／UI／boto3；無 stdout 自動收集、Insights、subscriptions 或 retention 刪除保證 |
| AWS IAM / GCP IAM | 租戶內 role / service account / policy 子集；default deny、限定 session；無原生雲端全量 IAM 語義 |
| API Gateway / Serverless profile | 簡化 HTTP Lambda proxy 和明確來源清單；不執行 plugins / CloudFormation |
| Azure | account 與資源群組目錄；尚無 Azure Functions 或其他 Azure runtime |
| EC2 / ECS / App Engine 等 | 部分只有 mock 目錄；不能視為執行中的 VM、Task 或應用 |

`fufu capabilities` 是隨版支援清單；`--remote` 另外查詢服務端能力。
`implemented` 代表明列子集已接入，`partial`、`mock-only`、`unsupported`
均不代表完整服務可用。未支援命令、旗標、YAML 欄位會拒絕，CI 應檢查退出碼。

## YAML / JSON

Cloud Run manifest 支援 `serving.knative.dev/v1`、`kind: Service`、
`metadata.name`、單一 container 的 image / port / env，以及明列的 service account。
服務 metadata.annotations 支援 `run.googleapis.com/ingress`（all／internal）與
`run.googleapis.com/invoker-iam-disabled`（字串 true／false）。
`fufu plan --file service.yaml` 可在不部署的情況下檢查設定；plan 僅列出環境變數名稱。
相同設定可用 JSON。其他正式雲端欄位需要顯式調整，不能宣稱所有設定無痛相容。

## 隱私與執行邊界

0.7.0 新增服務公開存取。需由平台配置 DNS、HTTPS 入口與 WAF 放行，
`publicAccess.status=ready` 表示入口已配置；仍應由 CI 實際 HTTP 呼叫確認外部可達。

```bash
gcloud-fufu run services update example --allow-unauthenticated --ingress all
gcloud-fufu run services get-iam-policy example
gcloud-fufu run services update example --no-allow-unauthenticated
gcloud-fufu auth print-identity-token --audiences https://app-SERVICE_ID.example.com
aws-fufu lambda create-function-url-config --function-name example --auth-type AWS_IAM
aws-fufu lambda get-function-url-config --function-name example
```

UI 與 CLI 共用同一份服務政策。Cloud Run 與 HTTP Functions 的匿名政策使用
`allUsers` 與對應 Invoker 角色。Lambda `NONE` 必須另加 `lambda:InvokeFunctionUrl`
（`--function-url-auth-type NONE`）和 `lambda:InvokeFunction`
（`--invoked-via-function-url`）兩項資源權限；只設定 NONE 不會自動開放呼叫。
入口支援有界限的普通 HTTP：Lambda 請求與回應各 6 MiB、Gen 1 各 10 MiB、Run／Gen 2 各 32 MiB。
依服務設定等待，期限上限分別為 900／540／3600 秒；外部 CDN 期限另計。每服務每分鐘 6000 次，另有主機容量背壓。
不支援 SSE、WebSocket、串流、STS 暫時金鑰、presigned URL 或真實 VPC。
GCP ID token 由 FUFU 的 RS256 issuer 簽發，綁定精確 audience，15 分鐘後過期；不接受 Google ID token。
`print-identity-token` 明確輸出秘密，應直接放入受控變數，避免 CI 日誌或 shell tracing。

- 套件沒有遙測、廣告、背景更新或安裝時網路腳本。
- API 請求只使用明確提供的 FUFU endpoint 和 credential；不掃描使用者家目錄。
- `whoami` 會輸出目前租戶、provider 與 scope；查詢／invoke 會輸出所要求的資料。
  請將 CI 日誌視為可能包含應用資料，不把敏感查詢結果公開。
- 本機部署會操作 Docker。明確執行 runtime prepare 或 function build 時，
  可能下載固定映像或安裝應用 requirements；不可信 requirements 仍可執行建置程式。
- FUFU 服務端的租戶隔離、IAM、日誌保存與資料保護由服務端負責。
  CLI 的本機檢查不等於對任何遠端部署作永久安全保證。

本套件目前保留著作權，未授予開源授權。套件公開可下載與原始碼採用開源授權
是不同事項；第三方 YAML parser 依其 MIT 授權散布。
