fufu-cloud-cli 0.5.0__py3-none-any.whl

fufu_cloud_cli/manifest.py

@@ -0,0 +1,120 @@
+"""嚴格解析 Cloud Run Knative Service 子集，未支援欄位一律拒絕。"""
+
+import json
+import re
+from pathlib import Path
+
+from .errors import FufuError, require
+
+NAME = re.compile(r"[a-z][a-z0-9-]{0,31}\Z")
+ENV_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
+RESERVED = {"PORT", "K_SERVICE", "K_REVISION", "K_CONFIGURATION", "FUNCTION_TARGET",
+            "FUFU_HANDLER",
+            "FUNCTION_SIGNATURE_TYPE", "AWS_LAMBDA_FUNCTION_NAME", "AWS_REGION",
+            "AWS_DEFAULT_REGION", "AWS_EC2_METADATA_DISABLED"}
+
+
+def name(value):
+    require(isinstance(value, str) and NAME.fullmatch(value), "INVALID_NAME",
+            "名稱限小寫英文開頭、數字與連字號，最多 32 字元。")
+    return value
+
+
+def fields(value, allowed, location):
+    require(isinstance(value, dict), "INVALID_MANIFEST", f"{location} 必須是物件。")
+    require(not (value.keys() - set(allowed)), "UNSUPPORTED_CONFIG",
+            f"{location} 含未支援欄位；請參閱支援矩陣。")
+    return value
+
+
+def environment(value):
+    require(isinstance(value, dict) and len(value) <= 64, "INVALID_ENV", "環境變數格式或數量不符。")
+    for k, v in value.items():
+        require(isinstance(k, str) and ENV_NAME.fullmatch(k) and k not in RESERVED and not k.startswith('FUFU_'),
+                "INVALID_ENV", "環境變數名稱無效或屬於保留欄位。")
+        require(isinstance(v, str) and "\x00" not in v and len(v) <= 32768,
+                "INVALID_ENV", "環境變數值格式不符。")
+    return value
+
+
+def load(path):
+    path = Path(path)
+    require(path.is_file() and path.stat().st_size <= 1048576,
+            "INVALID_MANIFEST", "描述檔必須存在且不超過 1 MiB。")
+    try:
+        text = path.read_text(encoding="utf-8")
+        def unique_json(pairs):
+            result = {}
+            for key, value in pairs:
+                require(key not in result, "INVALID_MANIFEST", "JSON 不接受重複鍵。")
+                result[key] = value
+            return result
+
+        try:
+            document = json.loads(text, object_pairs_hook=unique_json)
+        except json.JSONDecodeError:
+            try:
+                import yaml
+            except ImportError as exc:
+                raise FufuError("YAML_DEPENDENCY_MISSING", "YAML 需要安裝 fufu-cloud-cli[yaml]；JSON 無額外相依。") from exc
+
+            class UniqueLoader(yaml.SafeLoader):
+                pass
+
+            def mapping(loader, node, deep=False):
+                result = {}
+                for key_node, value_node in node.value:
+                    key = loader.construct_object(key_node, deep=deep)
+                    if not isinstance(key, str) or key in result:
+                        raise FufuError("INVALID_MANIFEST", "YAML 不接受非字串鍵或重複鍵。")
+                    result[key] = loader.construct_object(value_node, deep=deep)
+                return result
+
+            UniqueLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, mapping)
+            document = yaml.load(text, Loader=UniqueLoader)
+        return parse(document)
+    except FufuError:
+        raise
+    except Exception as exc:
+        raise FufuError("INVALID_MANIFEST", "無法解析描述檔；原始設定不會輸出。") from exc
+
+
+def parse(d):
+    fields(d, {"apiVersion", "kind", "metadata", "spec"}, "root")
+    require(d.get("apiVersion") == "serving.knative.dev/v1" and d.get("kind") == "Service",
+            "UNSUPPORTED_CONFIG", "目前只支援 serving.knative.dev/v1 Service 的明列子集。")
+    metadata = fields(d.get("metadata"), {"name"}, "metadata")
+    service = name(metadata.get("name"))
+    spec = fields(d.get("spec"), {"template"}, "spec")
+    template = fields(spec.get("template"), {"spec"}, "spec.template")
+    pod = fields(template.get("spec"), {"containers", 'serviceAccountName'}, "spec.template.spec")
+    role = pod.get('serviceAccountName')
+    require(role is None or (isinstance(role, str) and len(role) <= 256 and '@' in role), 'INVALID_ROLE', 'serviceAccountName 必須是有效的帳戶 email。')
+    containers = pod.get("containers")
+    require(isinstance(containers, list) and len(containers) == 1,
+            "UNSUPPORTED_CONFIG", "目前只支援單一 HTTP 容器。")
+    c = fields(containers[0], {"image", "ports", "env"}, "container")
+    image = c.get("image")
+    require(isinstance(image, str) and image and len(image) <= 256 and not image.startswith("-"),
+            "INVALID_IMAGE", "必須提供已存在於本機的映像。")
+    ports = c.get("ports", [{"containerPort": 8080}])
+    require(isinstance(ports, list) and len(ports) == 1, "UNSUPPORTED_CONFIG", "僅支援一個 HTTP port。")
+    p = fields(ports[0], {"containerPort"}, "ports")
+    port = p.get("containerPort")
+    require(type(port) is int and 1024 <= port <= 65535, "INVALID_PORT", "本機容器 port 範圍為 1024–65535。")
+    env = {}
+    items = c.get("env", [])
+    require(isinstance(items, list), "INVALID_ENV", "env 必須是陣列。")
+    for item in items:
+        fields(item, {"name", "value"}, "env")
+        k = item.get("name")
+        require(isinstance(k, str) and k not in env, "INVALID_ENV", "環境變數名稱重複或無效。")
+        env[k] = item.get("value")
+    environment(env)
+    return {"name": service, "image": image, "port": port, "env": env, **({'role': role} if role else {})}
+
+
+def public_plan(spec):
+    return {"backend": "local-docker", "kind": "cloud-run-http", "name": spec["name"],
+            "port": spec["port"], "environment_names": sorted(spec["env"]),
+            "checks": "strict-supported-subset", "image_resolution": "at-deploy"}

fufu_cloud_cli/remote_compute.py

@@ -0,0 +1,93 @@
+"""Authenticated compute transport. No Docker calls execute on the CI runner."""
+import base64
+import io
+import json
+import time
+import zipfile
+from pathlib import Path
+from urllib.parse import urlencode
+
+from .api_backend import ApiClient, segment
+from .errors import FufuError, require
+
+MAX_ARCHIVE = 6 * 1024**2
+KIND_PROVIDER = {"cloud-run-http": "gcp", "cloud-run-functions-http": "gcp",
+                 "cloud-functions-gen1-http": "gcp", "aws-lambda-sync": "aws"}
+
+
+def source_archive(source):
+    root = Path(source).resolve()
+    require(root.is_dir() and (root / "main.py").is_file(), "INVALID_SOURCE", "HTTP Function 來源需包含 main.py。")
+    data = io.BytesIO()
+    count, total = 0, 0
+    with zipfile.ZipFile(data, "w", zipfile.ZIP_DEFLATED) as archive:
+        for p in sorted(root.rglob("*")):
+            relative = p.relative_to(root)
+            if any(v.startswith('.') or v in {'__pycache__', 'node_modules'} for v in relative.parts):
+                continue
+            require(not p.is_symlink(), "INVALID_SOURCE", "Function 來源不可含符號連結。")
+            if not p.is_file():
+                continue
+            require(p.suffix == '.py' or p.name == 'requirements.txt', "UNSUPPORTED_SOURCE", "HTTP Function 來源只接受 Python 與 requirements.txt。")
+            count += 1
+            total += p.stat().st_size
+            require(count <= 1000 and total <= 32 * 1024**2, "SOURCE_LIMIT", "Function 來源超過上限。")
+            archive.write(p, relative.as_posix())
+    require(data.tell() <= MAX_ARCHIVE, "SOURCE_LIMIT", "Function ZIP 上限為 6 MiB。")
+    return base64.b64encode(data.getvalue()).decode()
+
+
+def lambda_archive(path):
+    p = Path(path)
+    require(p.is_file() and 0 < p.stat().st_size <= MAX_ARCHIVE, "SOURCE_LIMIT", "遠端 Lambda ZIP 上限為 6 MiB。")
+    return base64.b64encode(p.read_bytes()).decode()
+
+
+class RemoteBackend:
+    def __init__(self, kind):
+        require(kind in KIND_PROVIDER, "CAPABILITY_NOT_SUPPORTED", "此類型尚無遠端 compute。")
+        self.provider = KIND_PROVIDER[kind]
+
+    def wait(self, api, operation, timeout=600):
+        require(isinstance(operation, dict) and isinstance(operation.get('id'), str), "INVALID_RESPONSE", "部署 Operation 無效。")
+        deadline = time.monotonic() + timeout
+        while operation.get('status') in {'PENDING', 'RUNNING'}:
+            require(time.monotonic() < deadline, "DEPLOYMENT_WAIT_TIMEOUT", "等待部署超過期限；部署可能仍在執行，請查詢服務狀態。")
+            time.sleep(min(0.5, max(0, deadline - time.monotonic())))
+            operation = api.request('GET', '/compute/operations/' + segment(operation['id']))
+        if operation.get('status') != 'SUCCEEDED':
+            error = operation.get('error', {})
+            raise FufuError(error.get('code', 'DEPLOYMENT_FAILED'), error.get('message', '遠端部署未成功。'))
+        return operation['result']
+
+    def deploy(self, *, kind, service, image=None, port=8080, env=None, startup_timeout=30,
+               replace=True, require_existing=False, archive=None, runtime=None, handler=None, preserve_environment=False, role=None):
+        body = dict(kind=kind, name=service, port=port, env=env or {}, startup_timeout=startup_timeout,
+                    replace=replace, require_existing=require_existing, preserve_environment=preserve_environment)
+        if image is not None:
+            body['image'] = image
+        if archive is not None:
+            body.update(archive=archive, runtime=runtime, handler=handler)
+        if role: body['role'] = role
+        with ApiClient(self.provider) as api:
+            operation = api.request('POST', '/compute/deploy', body)
+            return self.wait(api, operation)
+
+    def describe(self, kind, service):
+        with ApiClient(self.provider, read_only=True) as api:
+            return api.request('GET', '/compute/services/' + segment(kind) + '/' + segment(service))
+
+    def listing(self, kind):
+        with ApiClient(self.provider, read_only=True) as api:
+            return api.request('GET', '/compute/services?' + urlencode({'kind': kind}))['services']
+
+    def delete(self, kind, service):
+        with ApiClient(self.provider) as api:
+            return self.wait(api, api.request('DELETE', '/compute/services/' + segment(kind) + '/' + segment(service)), timeout=120)
+
+    def invoke(self, kind, service, payload, *, path='/', timeout=15):
+        require(1 <= timeout <= 15, 'INVALID_TIMEOUT', '遠端呼叫期限須介於 1–15 秒。')
+        with ApiClient(self.provider) as api:
+            response = api.request('POST', '/compute/services/' + segment(kind) + '/' + segment(service) + '/invoke',
+                                   {'payload': base64.b64encode(payload).decode(), 'path': path, 'timeout': timeout})
+            return response['status'], base64.b64decode(response['payload'], validate=True), response.get('function_error')

fufu_cloud_cli/runtime/functions/Dockerfile

@@ -0,0 +1,6 @@
+FROM python:3.12-slim@sha256:57cd7c3a7a273101a6485ba99423ee568157882804b1124b4dd04266317710de
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
+RUN python -m pip install --index-url https://pypi.org/simple --disable-pip-version-check --no-cache-dir --retries 1 --timeout 20 functions-framework==3.10.2
+WORKDIR /app
+USER 10001:10001
+EXPOSE 8080

fufu_cloud_cli/runtime/ingress/Dockerfile

@@ -0,0 +1,6 @@
+FROM python:3.12-slim@sha256:57cd7c3a7a273101a6485ba99423ee568157882804b1124b4dd04266317710de
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
+COPY --chown=10001:10001 --chmod=644 proxy.py /proxy.py
+USER 10001:10001
+EXPOSE 8080
+CMD ["python", "/proxy.py"]

fufu_cloud_cli/runtime/ingress/proxy.py

@@ -0,0 +1,49 @@
+"""固定目的地的本機 ingress；不依 HTTP header、URL 或 payload 選擇 upstream。"""
+
+import os
+import select
+import socket
+import socketserver
+import threading
+import time
+
+TARGET = (os.environ["FUFU_UPSTREAM_HOST"], int(os.environ["FUFU_UPSTREAM_PORT"]))
+SLOTS = threading.BoundedSemaphore(32)
+
+
+class Proxy(socketserver.BaseRequestHandler):
+    def handle(self):
+        if not SLOTS.acquire(blocking=False):
+            return
+        try:
+            with socket.create_connection(TARGET, timeout=3) as upstream:
+                self.request.settimeout(5)
+                upstream.settimeout(5)
+                deadline = time.monotonic() + 180
+                while time.monotonic() < deadline:
+                    readable, _, _ = select.select([self.request, upstream], [], [], 15)
+                    if not readable:
+                        return
+                    for source in readable:
+                        body = source.recv(65536)
+                        if not body:
+                            return
+                        (upstream if source is self.request else self.request).sendall(body)
+        except OSError:
+            return
+        finally:
+            SLOTS.release()
+
+
+class Server(socketserver.ThreadingTCPServer):
+    allow_reuse_address = True
+    daemon_threads = True
+    request_queue_size = 32
+
+    def handle_error(self, *args):
+        pass
+
+
+if __name__ == "__main__":
+    with Server(("0.0.0.0", 8080), Proxy) as server:
+        server.serve_forever(poll_interval=0.25)

fufu_cloud_cli/runtime_sdk.py

@@ -0,0 +1,114 @@
+"""Opt-in FUFU SDK transport. AWS request serialization stays in botocore.
+
+The bridge uses a tenant-bound workload token, not AWS SigV4. Unsupported
+operations fail explicitly. It never falls back to a real cloud endpoint.
+"""
+import base64
+import io
+import json
+import os
+from urllib.error import HTTPError
+from urllib.parse import urlsplit
+from urllib.request import Request, ProxyHandler, HTTPRedirectHandler, build_opener
+
+
+class FufuCapabilityError(RuntimeError):
+    pass
+
+
+class NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):
+        return None
+
+
+def encode(value):
+    if isinstance(value, (bytes, bytearray)):
+        return {"__fufu_bytes": base64.b64encode(value).decode()}
+    if hasattr(value, 'read'):
+        data = value.read(6 * 1024**2 + 1)
+        if len(data) > 6 * 1024**2:
+            raise FufuCapabilityError('FUFU object exceeds 6 MiB')
+        return encode(data)
+    if isinstance(value, dict):
+        return {k: encode(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [encode(v) for v in value]
+    return value
+
+
+def rpc(service, operation, params):
+    endpoint = os.environ.get('FUFU_RUNTIME_ENDPOINT', '')
+    parsed = urlsplit(endpoint)
+    if parsed.scheme != 'http' or parsed.hostname != 'fufu-api' or parsed.port != 8080 or parsed.path not in {'/api/runtime/aws', '/api/runtime/gcp'} or parsed.query or parsed.fragment:
+        raise FufuCapabilityError('FUFU runtime gateway is not configured')
+    token = os.environ.get('FUFU_WORKLOAD_TOKEN')
+    if not token:
+        raise FufuCapabilityError('FUFU workload credential is required')
+    data = json.dumps({'service': service, 'operation': operation, 'params': encode(params)}, allow_nan=False).encode()
+    if len(data) > 9 * 1024**2:
+        raise FufuCapabilityError('FUFU SDK payload exceeds limit')
+    req = Request(endpoint, data=data, headers={'Content-Type': 'application/json', 'Authorization': 'Bearer ' + token}, method='POST')
+    try:
+        with build_opener(ProxyHandler({}), NoRedirect()).open(req, timeout=10) as response:
+            body = response.read(9 * 1024**2 + 1)
+            if len(body) > 9 * 1024**2:
+                raise FufuCapabilityError('FUFU SDK response exceeds limit')
+            return json.loads(body)
+    except HTTPError as exc:
+        # Error payload contains only the safe AWS error name, never backend details.
+        status = exc.code
+        try:
+            body = json.loads(exc.read(4096))
+        except (ValueError, OSError):
+            body = {}
+        finally:
+            exc.close()
+        code = body.get('code') or ('AccessDeniedException' if status in {401, 403} else 'FufuUnsupportedCapability' if status == 422 else 'FufuServiceError')
+        if service in {'dynamodb', 's3', 'sqs', 'ssm'}:
+            from botocore.exceptions import ClientError
+            raise ClientError({'Error': {'Code': code, 'Message': 'FUFU SDK request failed; see the documented capability subset'}, 'ResponseMetadata': {'HTTPStatusCode': status}}, operation) from None
+        raise FufuCapabilityError('FUFU runtime request rejected (HTTP %s)' % status) from None
+
+
+_installed = False
+
+
+def install():
+    global _installed
+    if _installed or not os.environ.get('FUFU_RUNTIME_ENDPOINT'):
+        return
+    import botocore.session
+    from botocore.awsrequest import AWSResponse
+    from botocore.response import StreamingBody
+    original = botocore.session.Session.create_client
+
+    def create_client(session, service_name, *args, **kwargs):
+        if service_name not in {'dynamodb', 's3', 'sqs', 'ssm'}:
+            raise FufuCapabilityError('FUFU SDK service is not implemented: ' + service_name)
+        kwargs['aws_access_key_id'] = 'FUFU_WORKLOAD'
+        kwargs['aws_secret_access_key'] = 'fufu-transport-does-not-use-sigv4'
+        kwargs['endpoint_url'] = 'http://fufu-api:8080'
+        client = original(session, service_name, *args, **kwargs)
+        def no_presign(*args, **kwargs):
+            raise FufuCapabilityError('FUFU presigned URLs are not implemented')
+        client.generate_presigned_url = no_presign
+        if hasattr(client, 'generate_presigned_post'): client.generate_presigned_post = no_presign
+
+        def capture(params, context, **unused):
+            # Keep the reference: later botocore/boto3 parameter handlers transform it.
+            context['fufu_params'] = params
+
+        def call(model, context, **unused):
+            result = rpc(service_name, model.name, context['fufu_params'])
+            if service_name == 's3' and isinstance(result.get('Body'), dict):
+                data = base64.b64decode(result['Body']['__fufu_bytes'], validate=True)
+                result['Body'] = StreamingBody(io.BytesIO(data), len(data))
+            result['ResponseMetadata'] = {'HTTPStatusCode': 200, 'HTTPHeaders': {'x-fufu-mode': 'simplified'}, 'RetryAttempts': 0}
+            return AWSResponse('http://fufu-api', 200, {}, None), result
+
+        client.meta.events.register('before-parameter-build', capture)
+        client.meta.events.register('before-call', call)
+        return client
+
+    botocore.session.Session.create_client = create_client
+    _installed = True

fufu_cloud_cli/serverless.py

@@ -0,0 +1,214 @@
+"""Explicit Serverless source/profile adapter; never runs provider plugins.
+
+The source YAML supplies selected handler paths and HTTP events. A FUFU profile
+replaces environment, IAM and infrastructure explicitly. A plan reports every
+omitted function and control-plane simplification before deployment.
+"""
+import ast
+import base64
+import io
+import json
+import os
+import re
+import zipfile
+from pathlib import Path
+from .api_backend import ApiClient
+from .control import AWS_OPERATIONS
+from .errors import FufuError, require
+from .manifest import environment, fields, name
+from .remote_compute import RemoteBackend
+
+ACKNOWLEDGEMENTS = {'selected-functions-only', 'replace-environment', 'replace-iam-and-resources',
+                    'fixed-runtime-limits', 'no-serverless-plugins', 'mock-cognito-authorizer'}
+
+
+def load_document(path):
+    p = Path(path)
+    require(p.is_file() and p.stat().st_size <= 1024**2, 'INVALID_CONFIG', '部署描述檔必須存在且不超過 1 MiB。')
+    try: import yaml
+    except ImportError: raise FufuError('YAML_DEPENDENCY_MISSING', '請安裝 fufu-cloud-cli[yaml] 以解析 Serverless YAML。') from None
+    class Loader(yaml.SafeLoader): pass
+    def mapping(loader, node, deep=False):
+        result = {}
+        for k, v in node.value:
+            key = loader.construct_object(k, deep=deep)
+            require(isinstance(key, str) and key not in result, 'INVALID_CONFIG', '設定含重複鍵或非字串鍵。')
+            result[key] = loader.construct_object(v, deep=deep)
+        return result
+    Loader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, mapping)
+    try: value = yaml.load(p.read_text(), Loader=Loader)
+    except FufuError: raise
+    except Exception: raise FufuError('INVALID_CONFIG', '無法解析 YAML／JSON；未輸出原始設定。') from None
+    require(isinstance(value, dict), 'INVALID_CONFIG', '部署描述檔必須是物件。')
+    return value
+
+
+def substitute(value, values):
+    if isinstance(value, str):
+        for key, replacement in values.items(): value = value.replace('${' + key + '}', replacement)
+        require('${' not in value, 'UNRESOLVED_VARIABLE', 'FUFU profile 只接受 stage、account、region、project 變數。')
+        return value
+    if isinstance(value, list): return [substitute(v, values) for v in value]
+    if isinstance(value, dict): return {k: substitute(v, values) for k, v in value.items()}
+    return value
+
+
+def package(root, include, handler):
+    require(isinstance(include, list) and 0 < len(include) <= 1000, 'INVALID_PACKAGE', '每個 Function 必須明確列出來源檔；不會自動打包 custom 設定與 credential。')
+    files = []; total = 0
+    for relative in include:
+        require(isinstance(relative, str) and not Path(relative).is_absolute() and '..' not in Path(relative).parts, 'INVALID_PACKAGE', '來源路徑必須位於專案內。')
+        p = root / relative
+        require(p.is_file() and not p.is_symlink() and p.resolve().is_relative_to(root) and p.suffix == '.py', 'INVALID_PACKAGE', '內建來源模式只打包明確列出的 Python；相依套件需另行提供 ZIP。')
+        total += p.stat().st_size
+        require(total <= 16 * 1024**2, 'SOURCE_LIMIT', '原始碼超過 16 MiB。')
+        files.append((p, relative))
+    module = handler.rsplit('.', 1)[0].replace('.', '/') + '.py'
+    require(module in include, 'INVALID_HANDLER', '來源列表缺少 handler 模組。')
+    # Reject unresolved local imports in the simple source package. Third-party
+    # imports are runtime dependencies; they must be provided in a supplied ZIP.
+    for p, _ in files:
+        for node in ast.walk(ast.parse(p.read_text())):
+            imports = [node.module] if isinstance(node, ast.ImportFrom) and node.module else [n.name for n in node.names] if isinstance(node, ast.Import) else []
+            for imported in imports:
+                if (root / imported.replace('.', '/')).is_dir() or (root / (imported.replace('.', '/') + '.py')).exists():
+                    require(any(v.startswith(imported.replace('.', '/') + '/') or v == imported.replace('.', '/') + '.py' for v in include), 'MISSING_DEPENDENCY', '來源列表缺少本機相依模組；請提供完整來源清單或預先打包的 ZIP。')
+    data = io.BytesIO()
+    with zipfile.ZipFile(data, 'w', zipfile.ZIP_DEFLATED) as z:
+        for p, relative in files: z.writestr(relative, p.read_bytes())
+    require(data.tell() <= 6 * 1024**2, 'SOURCE_LIMIT', 'Lambda ZIP 上限為 6 MiB。')
+    return base64.b64encode(data.getvalue()).decode()
+
+
+def plan(config, profile_path, stage):
+    source = load_document(config); profile = load_document(profile_path); root = Path(config).resolve().parent
+    fields(profile, {'version', 'functions', 'roles', 'resources', 'acknowledgeSimplifications', 'apiName'}, 'FUFU profile')
+    require(profile.get('version') == 1 and set(profile.get('acknowledgeSimplifications', [])) == ACKNOWLEDGEMENTS,
+            'ACKNOWLEDGEMENT_REQUIRED', 'Profile 必須明示所有必要簡化；請核對 acknowledgeSimplifications。')
+    require(source.get('provider', {}).get('name') == 'aws', 'UNSUPPORTED_PROVIDER', 'Serverless adapter 目前支援 AWS。')
+    name(stage)
+    definitions = source.get('functions', {}); selected = profile.get('functions', {})
+    require(isinstance(definitions, dict) and isinstance(selected, dict) and 0 < len(selected) <= 8, 'RESOURCE_LIMIT', '明確選擇 1–8 個 Function；未選取者不會被部署。')
+    require(isinstance(profile.get('apiName', 'chatbot-fufu'), str) and re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.+=,@-]{0,127}', profile.get('apiName', 'chatbot-fufu')), 'INVALID_NAME', 'API 名稱無效。')
+    require(isinstance(profile.get('roles'), dict), 'INVALID_ROLE', 'roles 必須是物件。')
+    prepared = []; routes = {}; source_hashes = {}; ignored_functions = {}
+    for key, options in selected.items():
+        require(key in definitions, 'FUNCTION_NOT_FOUND', 'Profile 選取了不存在的 Function。')
+        fields(options, {'name', 'include', 'artifact', 'environment', 'environmentFrom', 'role'}, 'function profile')
+        spec = definitions[key]
+        require(isinstance(spec, dict), 'UNSUPPORTED_FUNCTION', 'Function 定義必須是物件。')
+        ignored_functions[key] = sorted(set(spec) - {'handler', 'runtime', 'events'})
+        handler = spec.get('handler', '').replace('/', '.')
+        require(re.fullmatch(r'[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)+', handler), 'UNSUPPORTED_FUNCTION', '目前只支援 Python handler；image Function 需使用其他部署入口。')
+        runtime = spec.get('runtime', source['provider'].get('runtime'))
+        require(runtime in {'python3.10', 'python3.12'}, 'UNSUPPORTED_RUNTIME', '目前 Lambda runtime 支援 Python 3.10／3.12。')
+        physical = name(options.get('name'))
+        require(physical not in [f['name'] for f in prepared], 'DUPLICATE_NAME', 'Function 的實體名稱不可重複。')
+        require(isinstance(options.get('role'), str) and options['role'] in profile.get('roles', {}), 'INVALID_ROLE', 'Function 必須引用 profile 中明確配置的 role。')
+        require(bool(options.get('include')) != bool(options.get('artifact')), 'INVALID_PACKAGE', 'include 與 artifact 必須擇一。')
+        if options.get('artifact'):
+            artifact = root / options['artifact']
+            require(artifact.resolve().is_relative_to(root) and artifact.is_file() and not artifact.is_symlink() and artifact.stat().st_size <= 6 * 1024**2,
+                    'INVALID_PACKAGE', '預先打包的 ZIP 必須位於專案內且不超過 6 MiB。')
+            archive = base64.b64encode(artifact.read_bytes()).decode()
+        else: archive = package(root, options['include'], handler)
+        env = options.get('environment', {})
+        require(isinstance(env, dict), 'INVALID_ENV', 'environment 必須是物件。')
+        environment(substitute(env, {'stage': stage, 'account': '000000000000', 'region': 'ap-northeast-1', 'project': 'fufu-project'}))
+        from_env = options.get('environmentFrom', {})
+        require(isinstance(from_env, dict) and not (env.keys() & from_env.keys()), 'INVALID_ENV', 'environmentFrom 與 environment 不可重複。')
+        for target, entry in from_env.items():
+            fields(entry, {'env', 'ssm'}, 'environmentFrom')
+            require(len(entry) == 1 and isinstance(next(iter(entry.values())), str), 'INVALID_ENV', 'environmentFrom 使用 env 或 ssm 擇一。')
+        environment({target: 'validated-reference' for target in from_env})
+        http_routes = []
+        for event in spec.get('events', []):
+            require(isinstance(event, dict) and set(event) == {'http'}, 'UNSUPPORTED_EVENT', '選取的 Function 目前只匯入 HTTP events；SQS 請用 event-source-mapping 明確接線。')
+            http = event['http']
+            fields(http, {'path', 'method', 'cors', 'authorizer', 'private'}, 'HTTP event')
+            require(not http.get('private'), 'UNSUPPORTED_EVENT', 'API key／usage plan 尚未實作。')
+            require(isinstance(http.get('path'), str) and http.get('method', '').lower() in {'get','post','put','patch','delete','options','head'}, 'INVALID_EVENT', 'HTTP route 無效。')
+            route = '/' + http['path'].lstrip('/'); method = http['method'].lower()
+            require(method not in routes.setdefault(route, {}), 'DUPLICATE_ROUTE', 'HTTP route 重複。')
+            routes[route][method] = physical; http_routes.append({'path': route, 'method': method})
+        import hashlib
+        source_hashes[key] = hashlib.sha256(base64.b64decode(archive)).hexdigest()
+        prepared.append({'key': key, 'name': physical, 'handler': handler, 'runtime': runtime, 'archive': archive,
+                         'environment': env, 'environmentFrom': from_env, 'role': options['role'], 'http': http_routes})
+    for role_name, role in profile.get('roles', {}).items():
+        require(re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.-]{0,63}', role_name), 'INVALID_ROLE', 'Role 名稱無效。')
+        fields(role, {'AssumeRolePolicyDocument', 'PolicyDocument'}, 'role')
+        require(set(role) == {'AssumeRolePolicyDocument', 'PolicyDocument'}, 'INVALID_ROLE', 'Role 必須提供 trust 與 policy。')
+    resources = profile.get('resources', [])
+    require(isinstance(resources, list) and len(resources) <= 32, 'RESOURCE_LIMIT', '最多 32 個明確的資料資源。')
+    for item in resources:
+        fields(item, {'service', 'operation', 'params'}, 'resource')
+        require((item.get('service'), item.get('operation')) in {('dynamodb','CreateTable'),('s3api','CreateBucket'),('sqs','CreateQueue')}, 'UNSUPPORTED_RESOURCE', '自動部署只建立 DynamoDB、S3、SQS；其他設定請用原生命令。')
+        fields(item.get('params'), AWS_OPERATIONS[item['service']][item['operation']].split(), 'resource params')
+    public = {'mode': 'simplified', 'adapter': 'explicit-serverless-profile', 'stage': stage,
+              'selectedFunctions': [{'key': f['key'], 'name': f['name'], 'handler': f['handler'], 'runtime': f['runtime'], 'role': f['role'], 'environmentNames': sorted(set(f['environment']) | set(f['environmentFrom'])), 'http': f['http']} for f in prepared],
+              'notDeployed': sorted(set(definitions) - set(selected)), 'sourceSha256': source_hashes,
+              'ignoredSourceFields': {'provider': sorted(set(source['provider']) - {'name', 'runtime'}), 'functions': ignored_functions,
+                                     'root': sorted(set(source) - {'provider', 'functions'})},
+              'simplifications': sorted(ACKNOWLEDGEMENTS), 'resourceCount': len(resources), 'authorizer': 'MOCK: authenticated tenant owner claims'}
+    return public, prepared, profile, routes
+
+
+def deploy(config, profile_path, stage):
+    public, functions, profile, routes = plan(config, profile_path, stage)
+    backend = RemoteBackend('aws-lambda-sync')
+    with ApiClient('aws') as api:
+        who = api.whoami(); values = {'stage': stage, 'account': who['accountId'], 'region': who['region'], 'project': 'unused'}
+        call = lambda service, operation, params: api.request('POST', '/control/native', {'service': 's3' if service == 's3api' else service, 'operation': operation, 'params': params})
+        # Resolve every source environment and role locally before any mutation.
+        for f in functions:
+            env = substitute(f['environment'], values)
+            for key, ref in f['environmentFrom'].items():
+                if 'env' in ref:
+                    require(ref['env'] in os.environ, 'MISSING_ENV', 'Profile 所需的受控環境變數未注入。')
+                    env[key] = os.environ[ref['env']]
+                else: env[key] = call('ssm', 'GetParameter', {'Name': substitute(ref['ssm'], values)})['Parameter']['Value']
+            f['env'] = environment(env)
+        roles = substitute(profile['roles'], values)
+        resources = substitute(profile.get('resources', []), values)
+        capabilities = api.request('GET', '/compute/capabilities')
+        existing = api.request('GET', '/compute/services?kind=aws-lambda-sync')['services']
+        require(len({x['name'] for x in existing} | {x['name'] for x in functions}) <= capabilities['maxServices'], 'RESOURCE_LIMIT', '目前租戶沒有足夠的 Function 容量。')
+        role_names = {r['RoleName'] for r in call('iam', 'ListRoles', {})['Roles']}
+        for role_name, role in roles.items():
+            if role_name not in role_names: call('iam', 'CreateRole', {'RoleName': role_name, 'AssumeRolePolicyDocument': role['AssumeRolePolicyDocument']})
+            else:
+                previous = call('iam', 'GetRole', {'RoleName': role_name})['Role']['AssumeRolePolicyDocument']
+                require(previous == role['AssumeRolePolicyDocument'], 'ROLE_CONFLICT', '既有 role trust 與 profile 不同；未覆寫 trust。')
+            call('iam', 'PutRolePolicy', {'RoleName': role_name, 'PolicyName': 'fufu-deployment', 'PolicyDocument': role['PolicyDocument']})
+        for item in resources:
+            try: call(item['service'], item['operation'], item['params'])
+            except FufuError as e:
+                if e.code != 'RESOURCE_CONFLICT': raise
+                if item['service'] == 'dynamodb':
+                    table = call('dynamodb', 'DescribeTable', {'TableName': item['params']['TableName']})['Table']
+                    require(table['KeySchema'] == item['params']['KeySchema'] and sorted(table['AttributeDefinitions'], key=lambda x:x['AttributeName']) == sorted(item['params']['AttributeDefinitions'], key=lambda x:x['AttributeName']), 'RESOURCE_CONFLICT', '既有 DynamoDB schema 與 profile 不同。')
+                elif item['service'] != 's3api': raise
+        deployed = []
+        for f in functions:
+            body = {k: f[k] for k in ['name','handler','runtime','archive']}
+            body.update(kind='aws-lambda-sync', role=f"arn:aws:iam::{who['accountId']}:role/{f['role']}", env=f['env'], replace=True)
+            operation = api.request('POST', '/compute/deploy', body)
+            deployed.append(backend.wait(api, operation))
+        gateway = None
+        if routes:
+            paths = {p: {m: {'responses': {}, 'x-amazon-apigateway-integration': {'type':'aws_proxy','httpMethod':'POST','payloadFormatVersion':'1.0', 'uri':f"arn:aws:lambda:{who['region']}:{who['accountId']}:function:{fn}"}} for m,fn in methods.items()} for p,methods in routes.items()}
+            api_name = profile.get('apiName', 'chatbot-fufu'); prior = api.request('GET', '/control/apis')['Items']
+            require(sum(x['name'] == api_name for x in prior) <= 1, 'API_CONFLICT', 'API 名稱存在多個部署。')
+            previous_id = next((x['id'] for x in prior if x['name'] == api_name), None)
+            gateway = api.request('POST', '/control/apis', {'document': {'openapi':'3.0.1','info':{'title':api_name,'version':'1'},'paths':paths,'x-fufu-authorizer':'tenant-owner-claims-mock'}, **({'id':previous_id} if previous_id else {})})
+    return {'plan': public, 'deployed': deployed, 'gateway': gateway, 'status': 'SUCCEEDED', 'fullApplicationDeployed': False}
+
+
+def command(argv, Parser):
+    p = Parser(prog='aws-fufu serverless', description='明確 profile 的 Serverless 來源轉接；不呼叫正式雲端或執行 Serverless plugins。')
+    s = p.add_subparsers(dest='action', required=True)
+    for action in ['plan', 'deploy']:
+        q = s.add_parser(action); q.add_argument('--config', default='serverless.yml'); q.add_argument('--fufu-config', required=True); q.add_argument('--stage', default='fufu')
+    a = p.parse_args(argv)
+    return plan(a.config, a.fufu_config, a.stage)[0] if a.action == 'plan' else deploy(a.config, a.fufu_config, a.stage)