magic-pocket-cli 0.2.0__py3-none-any.whl

pocket_cli/django_cli.py

@@ -0,0 +1,412 @@
+import importlib.util
+import json
+import os
+import shutil
+import warnings
+import webbrowser
+from pathlib import Path
+from subprocess import run
+
+import click
+from django.core.management.utils import get_random_secret_key
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+from pocket.context import Context
+from pocket.django import django_installed
+from pocket.django.utils import get_storages
+from pocket.utils import echo
+from pocket_cli.resources.awscontainer import AwsContainer
+
+
+@click.group()
+def django():
+    pass
+
+
+@django.command()
+def init():
+    jinja2_env = Environment(
+        loader=PackageLoader("pocket_cli"),
+        autoescape=select_autoescape(),
+        keep_trailing_newline=True,
+    )
+    project_name = Path(".").resolve().name
+    with open("pocket.toml", "w") as f:
+        f.write(jinja2_env.get_template(name="init/pocket_simple.toml").render())
+        echo.success("Update: pocket.toml")
+    with open("pocket.Dockerfile", "w") as f:
+        f.write(jinja2_env.get_template(name="init/pocket.Dockerfile").render())
+        echo.success("Update: pocket.Dockerfile")
+    if importlib.util.find_spec("environ") is not None:
+        with open(f"{project_name}/settings.py", "w") as f:
+            echo.success("Update: settings.py")
+            f.write(
+                jinja2_env.get_template(name="init/django-settings.py").render(
+                    project_name=project_name
+                )
+            )
+        _update_dotenv(jinja2_env)
+    else:
+        echo.warning("django-environ is not installed")
+        echo.warning("`settings.py` and `.env` file will be updated with it.")
+
+
+def _update_dotenv(jinja2_env):
+    dotenv_path = Path(".env")
+    dotenv_content = jinja2_env.get_template(name="init/django-dotenv.env").render(
+        secret_key=get_random_secret_key()
+    )
+    echo.info("You may need to update .env file")
+    if click.confirm("Do you want to check the content?", default=True):
+        echo.info(dotenv_content)
+    if not click.confirm("Do you want to create .env file?"):
+        return
+    if dotenv_path.exists():
+        echo.warning(".env file already exists")
+        if not click.confirm("Do you want to overwrite .env file?"):
+            echo.warning("ensure you have correct values in .env file")
+            echo.info("sample .env file:")
+            echo.info(dotenv_content)
+            return
+        elif click.confirm("Log the deleting .env?", default=True):
+            echo.info(dotenv_path.read_text())
+            echo.danger("The contnet above was deleted")
+    with open(dotenv_path, "w") as f:
+        f.write(dotenv_content)
+        echo.success("Update: .env")
+
+
+@django.command()
+@click.option("--stage", envvar="POCKET_DEPLOY_STAGE", prompt=True)
+@click.option("--openpath")
+@click.option(
+    "--yes", "-y", is_flag=True, default=False, help="確認プロンプトをスキップ"
+)
+@click.option(
+    "--skip-check-existing",
+    is_flag=True,
+    default=False,
+    help="neon/tidb/upstash の存在確認 API を skip し COMPLETED 扱いで deploy",
+)
+def deploy(stage: str, openpath, yes, skip_check_existing):
+    from pocket_cli.cli.deploy_cli import deploy as pocket_deploy
+
+    # pocket deploy を実行（インフラ + SPA フロントエンド）
+    ctx = click.Context(pocket_deploy)
+    ctx.invoke(
+        pocket_deploy,
+        stage=stage,
+        openpath=None,
+        skip_frontend=False,
+        skip_check_existing=skip_check_existing,
+    )
+    _django_post_deploy(stage, yes=yes, openpath=openpath)
+
+
+def _django_post_deploy(stage: str, *, yes: bool, openpath):
+    """deploy / promote 共通の Django 固有後処理 (collectstatic + migrate + URL)。"""
+    context = Context.from_toml(stage=stage)
+    if yes or click.confirm("deploystatic?", default=True):
+        collectstatic_locally(stage)
+        upload_collected_staticfiles(stage)
+    handler = _get_management_command_handler(context)
+    if yes or click.confirm("migrate?", default=True):
+        res = handler.invoke(json.dumps({"command": "migrate", "args": []}))
+        handler.show_logs(res)
+    from pocket_cli.cli.deploy_cli import _get_deploy_url
+
+    url = _get_deploy_url(context)
+    if url:
+        echo.success(f"url: {url}")
+        if openpath:
+            webbrowser.open(url + "/" + openpath)
+
+
+@django.command()
+@click.option("--stage", envvar="POCKET_DEPLOY_STAGE", prompt=True)
+@click.option("--commit-hash", required=True, help="昇格する image の git commit hash")
+@click.option("--openpath")
+@click.option(
+    "--yes", "-y", is_flag=True, default=False, help="確認プロンプトをスキップ"
+)
+@click.option(
+    "--skip-check-existing",
+    is_flag=True,
+    default=False,
+    help="neon/tidb/upstash の存在確認 API を skip し COMPLETED 扱いで deploy",
+)
+def promote(stage: str, commit_hash, openpath, yes, skip_check_existing):
+    """build 済みの :<commit-hash> image へ stage を向けて deploy する (再ビルドなし)。
+
+    `pocket django build` で push した image に :<stage> タグを移し、インフラ/Lambda
+    を更新する。image build は行わない (build once の昇格)。静的アセットは deploy 時
+    と同様にローカルでビルドして upload する。
+    """
+    from pocket_cli.cli.deploy_cli import promote as pocket_promote
+
+    ctx = click.Context(pocket_promote)
+    ctx.invoke(
+        pocket_promote,
+        stage=stage,
+        commit_hash=commit_hash,
+        openpath=None,
+        skip_frontend=False,
+        skip_check_existing=skip_check_existing,
+    )
+    _django_post_deploy(stage, yes=yes, openpath=openpath)
+
+
+@django.command()
+@click.option("--stage", envvar="POCKET_DEPLOY_STAGE", prompt=True)
+@click.option(
+    "--allow-dirty",
+    is_flag=True,
+    default=False,
+    help="working tree が dirty でも build する (ローカル検証用)",
+)
+def build(stage: str, allow_dirty: bool):
+    """現在の作業ツリーを build し、git commit hash をタグにして ECR へ push する。
+
+    deploy はしない (build once)。`pocket django promote --commit-hash <sha>` で
+    このイメージへ昇格する。タグは COMMIT_HASH 環境変数があればそれを、なければ
+    `git rev-parse HEAD` を使う。
+
+    commit hash = image 内容 の同一性が前提のため、working tree が dirty の場合は
+    エラーになる (--allow-dirty で回避可能)。
+    """
+    from pocket.context import get_commit_hash, is_working_tree_dirty
+    from pocket_cli.cli.aws_auth import check_aws_credentials
+    from pocket_cli.cli.deploy_cli import build_image
+
+    check_aws_credentials()
+    if not allow_dirty and is_working_tree_dirty():
+        raise click.ClickException(
+            "working tree に未コミットの変更があります。build once では"
+            " commit hash と image 内容の一致が前提のため、commit してから"
+            " build してください (--allow-dirty で回避できますが、その image の"
+            " 昇格は推奨しません)。"
+        )
+    try:
+        tag = get_commit_hash()
+    except RuntimeError as e:
+        raise click.ClickException(str(e))
+    context = Context.from_toml(stage=stage)
+    target = build_image(context, tag=tag)
+    echo.success("built and pushed: %s" % target)
+
+
+def _get_management_command_handler(context: Context, key: str | None = None):
+    if not context.awscontainer:
+        raise Exception("awscontainer is not configured for this stage")
+    ac = AwsContainer(context.awscontainer)
+    if key:
+        warnings.warn(
+            "Do not use key to get management command handler",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return ac.handlers[key]
+    target_command = "pocket.django.lambda_handlers.management_command_handler"
+    for key, handler_context in context.awscontainer.handlers.items():
+        if handler_context.command == target_command:
+            return ac.handlers[key]
+    print("management command handler not found")
+    raise Exception("Add management command handler for this stage")
+
+
+class DeploystaticConfigError(Exception):
+    pass
+
+
+def get_deploystatic_local_storage(stage: str):
+    stage_storages = get_storages(stage=stage)
+    if "staticfiles" not in stage_storages:
+        raise Exception("staticfiles storage not found in the stage %s" % stage)
+    storage = stage_storages["staticfiles"]
+    _SFS = "django.contrib.staticfiles.storage.StaticFilesStorage"
+    _MSFS = "django.contrib.staticfiles.storage.ManifestStaticFilesStorage"
+    if storage["BACKEND"] in [_SFS, _MSFS]:
+        # deploy_hash モード等で既にローカル backend が返されている
+        local_backend = storage["BACKEND"]
+    elif storage["BACKEND"] in [
+        "storages.backends.s3boto3.S3StaticStorage",
+        "pocket.django.storages.CloudFrontS3StaticStorage",
+    ]:
+        local_backend = _SFS
+    elif storage["BACKEND"] in [
+        "storages.backends.s3boto3.S3ManifestStaticStorage",
+        "pocket.django.storages.CloudFrontS3ManifestStaticStorage",
+    ]:
+        local_backend = _MSFS
+    else:
+        raise DeploystaticConfigError(
+            "BACKEND %s is not supported" % storage["BACKEND"]
+        )
+    local_build_static_root = Path.cwd() / "pocket_cache" / "static_build" / stage
+    return {
+        "BACKEND": local_backend,
+        "OPTIONS": {"location": str(local_build_static_root)},
+    }
+
+
+def can_deploystatic(stage: str):
+    try:
+        get_deploystatic_local_storage(stage)
+        return True
+    except DeploystaticConfigError:
+        return False
+
+
+def set_staticfiles_override_env(storage):
+    if os.environ.get("POCKET_STATICFILES_BACKEND_OVERRIDE"):
+        raise Exception("POCKET_STATICFILES_BACKEND_OVERRIDE is already set")
+    if os.environ.get("POCKET_STATICFILES_LOCATION_OVERRIDE"):
+        raise Exception("POCKET_STATICFILES_LOCATION_OVERRIDE is already set")
+    os.environ["POCKET_STATICFILES_BACKEND_OVERRIDE"] = storage["BACKEND"]
+    os.environ["POCKET_STATICFILES_LOCATION_OVERRIDE"] = storage["OPTIONS"]["location"]
+
+
+def clear_staticfiles_override_env():
+    os.environ.pop("POCKET_STATICFILES_BACKEND_OVERRIDE", None)
+    os.environ.pop("POCKET_STATICFILES_LOCATION_OVERRIDE", None)
+
+
+def upload_collected_staticfiles(stage: str):
+    from pocket.django.utils import get_static_storage_s3_options
+
+    s3_options = get_static_storage_s3_options(stage=stage)
+    local_storage = get_deploystatic_local_storage(stage)
+    s3_bucket_name = s3_options["bucket_name"]
+    s3_location = s3_options["location"]
+    echo.info("Bucket: %s" % s3_bucket_name)
+    echo.info("Location: %s" % s3_location)
+    echo.info("Uploading static files...")
+    run(
+        "aws s3 sync %s s3://%s/%s/ --delete"
+        % (local_storage["OPTIONS"]["location"], s3_bucket_name, s3_location),
+        shell=True,
+        check=True,
+    )
+
+
+def _build_python_command(args: list[str]) -> list[str]:
+    """プロジェクトのPythonでコマンドを実行するためのコマンドリストを構築する。
+
+    uv があれば uv run python を使い、
+    なければ python3 / python にフォールバック。
+    """
+    if shutil.which("uv"):
+        return ["uv", "run", "python", *args]
+    for name in ("python3", "python"):
+        if shutil.which(name):
+            return [name, *args]
+    raise FileNotFoundError(
+        "pythonが見つかりません。uvまたはpythonをインストールしてください。"
+    )
+
+
+def _get_project_dir(stage: str) -> str | None:
+    """pocket.toml の awscontainer.django.project_dir を取得する"""
+    context = Context.from_toml(stage=stage)
+    if context.awscontainer and context.awscontainer.django:
+        return context.awscontainer.django.project_dir
+    return None
+
+
+def collectstatic_locally(stage: str):
+    local_storage = get_deploystatic_local_storage(stage)
+    echo.info("collectstatic to %s..." % local_storage["OPTIONS"]["location"])
+    set_staticfiles_override_env(local_storage)
+    cmd = _build_python_command(["manage.py", "collectstatic", "--noinput"])
+    project_dir = _get_project_dir(stage)
+    run(cmd, check=True, cwd=project_dir)
+    clear_staticfiles_override_env()
+
+
+@django.command()
+@click.option("--stage", envvar="POCKET_DEPLOY_STAGE", prompt=True)
+@click.option("--skip-collectstatic", is_flag=True, default=False)
+def deploystatic(stage: str, skip_collectstatic: bool):
+    if not skip_collectstatic:
+        collectstatic_locally(stage)
+    upload_collected_staticfiles(stage)
+
+
+@django.command(
+    context_settings={
+        "ignore_unknown_options": True,
+    },
+)
+@click.option("--stage", envvar="POCKET_DEPLOY_STAGE", prompt=True)
+@click.argument("command")
+@click.argument("args", nargs=-1)
+@click.option("--handler")
+@click.option("--timeout-seconds", type=int)
+def manage(stage, command, args, handler, timeout_seconds):
+    if not django_installed:
+        raise Exception("django is not installed")
+    context = Context.from_toml(stage=stage)
+    handler = _get_management_command_handler(context, key=handler)
+    res = handler.invoke(json.dumps({"command": command, "args": args}))
+    if timeout_seconds:
+        handler.show_logs(res, timeout_seconds)
+    else:
+        handler.show_logs(res)
+
+
+@django.command()
+@click.option("--stage", envvar="POCKET_DEPLOY_STAGE", prompt=True)
+@click.option(
+    "--yes", "-y", is_flag=True, default=False, help="確認プロンプトをスキップ"
+)
+def resetdb(stage: str, yes: bool):
+    """データベースの public スキーマをリセットする
+
+    Lambda 経由で DROP SCHEMA public CASCADE; CREATE SCHEMA public; を実行し、
+    全テーブルを削除してマイグレーションをやり直せる状態にする。
+    """
+    echo.danger("stage '%s' のデータベースをリセットします。" % stage)
+    echo.danger("全テーブルとデータが削除されます。")
+    if not yes:
+        click.confirm("本当に実行しますか？", abort=True)
+
+    context = Context.from_toml(stage=stage)
+    handler = _get_management_command_handler(context)
+    res = handler.invoke(json.dumps({"command": "pocket_resetdb", "args": []}))
+    handler.show_logs(res)
+    echo.success("データベースをリセットしました。")
+    echo.info("pocket django manage --stage %s migrate を実行してください。" % stage)
+
+
+@django.group()
+def storage():
+    pass
+
+
+def _check_upload_backends(from_storage, to_storage):
+    if from_storage["BACKEND"] != "django.core.files.storage.FileSystemStorage":
+        raise Exception("Upload from only support FileSystemStorage")
+    if to_storage["BACKEND"] != "storages.backends.s3boto3.S3Boto3Storage":
+        raise Exception("Upload to only support S3Boto3Storage")
+
+
+@storage.command()
+@click.option("--stage", envvar="POCKET_DEPLOY_STAGE", prompt=True)
+@click.option("--delete", is_flag=True, default=False)
+@click.option("--dryrun", is_flag=True, default=False)
+@click.argument("storage")
+def upload(storage, stage, delete, dryrun):
+    from_storage = get_storages()[storage]
+    to_storage = get_storages(stage=stage)[storage]
+    _check_upload_backends(from_storage, to_storage)
+    from_location = from_storage["OPTIONS"]["location"]
+    to_backet_name = to_storage["OPTIONS"]["bucket_name"]
+    to_location = to_storage["OPTIONS"]["location"]
+    cmd = "aws s3 sync %s s3://%s/%s" % (from_location, to_backet_name, to_location)
+    cmd += ' --exclude ".*" --exclude "*/.*"'
+    if delete:
+        cmd += " --delete"
+    if dryrun:
+        cmd += " --dryrun"
+    print(cmd)
+    run(cmd, shell=True, check=True)

pocket_cli/mediator.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import base64
+import secrets
+from typing import TYPE_CHECKING, Literal
+
+from pocket.utils import echo
+from pocket_cli.resources.neon import Neon, NeonResourceIsNotReady
+from pocket_cli.resources.tidb import TiDb, TiDbResourceIsNotReady
+from pocket_cli.resources.upstash import Upstash, UpstashResourceIsNotReady
+
+if TYPE_CHECKING:
+    from pocket.context import Context
+    from pocket.settings import ManagedSecretSpec
+
+
+class Mediator:
+    """Do some tasks that requires access to mulple resources."""
+
+    ErrorLevel = Literal["ignore", "warning", "raise"]
+
+    def __init__(self, context: Context) -> None:
+        self.context = context
+
+    def _conditional_error(self, level: ErrorLevel, msg: str):
+        if level == "ignore":
+            return
+        elif level == "warning":
+            echo.warning(msg)
+            return
+        else:
+            raise Exception(msg)
+
+    def create_pocket_managed_secrets(
+        self, exists: ErrorLevel = "warning", failed: ErrorLevel = "raise"
+    ):
+        if self.context.awscontainer is None:
+            return
+        if (sc := self.context.awscontainer.secrets) is None:
+            return
+        generated: dict[str, str | dict[str, str]] = {}
+        for key, managed_secret in sc.managed.items():
+            if key not in sc.pocket_store.secrets:
+                value = self._generate_secret(managed_secret)
+                if value is None:
+                    msg = "Secret generation for %s is failed." % key
+                    self._conditional_error(failed, msg)
+                else:
+                    generated[key] = value
+            else:
+                msg = (
+                    "%s is already created. "
+                    "Use rotate-pocket-managed if you want to refresh the secrets" % key
+                )
+                self._conditional_error(exists, msg)
+        if generated:
+            new_pocket_secrets = sc.pocket_store.secrets.copy() | generated
+            sc.pocket_store.update_secrets(new_pocket_secrets)
+
+    def ensure_pocket_managed_secrets(self):
+        self.create_pocket_managed_secrets(exists="ignore")
+        self._cleanup_orphaned_secrets()
+        if self.context.awscontainer and self.context.awscontainer.secrets:
+            sc = self.context.awscontainer.secrets
+            if hasattr(sc, "pocket_store"):
+                del sc.pocket_store
+            if hasattr(sc, "allowed_sm_resources"):
+                del sc.allowed_sm_resources
+            if hasattr(sc, "allowed_ssm_resources"):
+                del sc.allowed_ssm_resources
+
+    def _cleanup_orphaned_secrets(self):
+        """SSM/SM にあるが managed 定義にないシークレットを削除する"""
+        if self.context.awscontainer is None:
+            return
+        if (sc := self.context.awscontainer.secrets) is None:
+            return
+        stored_keys = set(sc.pocket_store.secrets.keys())
+        managed_keys = set(sc.managed.keys())
+        orphaned = stored_keys - managed_keys
+        if not orphaned:
+            return
+        echo.warning(
+            "managed 定義にないシークレットを削除します: %s"
+            % ", ".join(sorted(orphaned))
+        )
+        # managed に含まれるキーだけ残して再書き込み
+        cleaned = {
+            k: v for k, v in sc.pocket_store.secrets.items() if k in managed_keys
+        }
+        sc.pocket_store.delete_secrets()
+        if cleaned:
+            sc.pocket_store.update_secrets(cleaned)
+
+    def _generate_secret(self, spec: ManagedSecretSpec):
+        if spec.type == "auto_database_url":
+            return self._get_auto_database_url()
+        elif spec.type == "password":
+            return self._generate_password(spec.options)
+        elif spec.type == "neon_database_url":
+            return self._get_neon_database_url()
+        elif spec.type == "tidb_database_url":
+            return self._get_tidb_database_url()
+        elif spec.type == "rds_database_url":
+            return self._get_rds_database_url()
+        elif spec.type == "upstash_redis_url":
+            return self._get_upstash_redis_url()
+        elif spec.type == "rsa_pem_base64":
+            return self._generate_rsa_pem()
+        elif spec.type == "cloudfront_signing_key":
+            return self._generate_rsa_pem()
+        elif spec.type == "spa_token_secret":
+            return secrets.token_hex(32)
+        else:
+            raise RuntimeError("Unknown secret type: %s" % spec.type)
+
+    def _generate_rsa_pem(self) -> dict[str, str]:
+        try:
+            from cryptography.hazmat.primitives import serialization
+            from cryptography.hazmat.primitives.asymmetric import rsa
+        except ModuleNotFoundError:
+            echo.warning("cryptography is not installed.")
+            echo.warning("Please install cryptography to generate RSA key pair.")
+            echo.warning("rye add cryptography")
+            raise
+        private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+        pem_private_key = private_key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.TraditionalOpenSSL,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+        pem_public_key = private_key.public_key().public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+        return {
+            "pem": base64.b64encode(pem_private_key).decode("utf-8"),
+            "pub": base64.b64encode(pem_public_key).decode("utf-8"),
+        }
+
+    def _generate_password(self, options):
+        length = options.get("length", 16)
+        if not isinstance(length, int):
+            raise Exception("length must be integer")
+        chars = options.get(
+            # default is compatible with Django's SECRET_KEY
+            "chars",
+            "abcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(-_=+)",
+        )
+        if not isinstance(chars, str):
+            raise Exception("chars must be string")
+        return "".join(secrets.choice(chars) for _ in range(length))
+
+    def _get_neon_database_url(self):
+        if not self.context.neon:
+            raise Exception("neon is not configured. Please set neon in pocket.toml")
+        try:
+            return Neon(self.context.neon).database_url
+        except NeonResourceIsNotReady:
+            echo.warning("neon database is not ready")
+            return None
+
+    def _get_upstash_redis_url(self):
+        if not self.context.upstash:
+            raise RuntimeError(
+                "upstash is not configured. Please set upstash in pocket.toml"
+            )
+        try:
+            return Upstash(self.context.upstash).redis_url
+        except UpstashResourceIsNotReady:
+            echo.warning("upstash redis is not ready")
+            return None
+
+    def _get_auto_database_url(self):
+        """pocket.toml の DB 設定を自動検出して DATABASE_URL を生成する"""
+        dbs = []
+        if self.context.neon:
+            dbs.append("neon")
+        if self.context.tidb:
+            dbs.append("tidb")
+        if self.context.rds:
+            dbs.append("rds")
+        if len(dbs) == 0:
+            raise RuntimeError(
+                "auto_database_url: DB が設定されていません。"
+                "[neon], [tidb], [rds] のいずれかを pocket.toml に追加してください。"
+            )
+        if len(dbs) > 1:
+            raise RuntimeError(
+                "auto_database_url: 複数の DB が設定されています: %s。"
+                "neon_database_url, tidb_database_url, rds_database_url "
+                "のいずれかを明示的に指定してください。" % ", ".join(dbs)
+            )
+        db = dbs[0]
+        if db == "neon":
+            return self._get_neon_database_url()
+        if db == "tidb":
+            return self._get_tidb_database_url()
+        # rds: runtime の _set_rds_database_url に委譲
+        return self._get_rds_database_url()
+
+    def _get_rds_database_url(self):
+        """RDS の DATABASE_URL は runtime で動的構築されるため、
+
+        deploy 時には marker 値を返す。
+        runtime の _set_rds_database_url が POCKET_RDS_SECRET_ARN から
+        実際の DATABASE_URL を上書きする。
+        """
+        if not self.context.rds:
+            raise RuntimeError("rds is not configured. Please set rds in pocket.toml")
+        return "__rds_runtime__"
+
+    def _get_tidb_database_url(self):
+        if not self.context.tidb:
+            raise RuntimeError("tidb is not configured. Please set tidb in pocket.toml")
+        try:
+            return TiDb(self.context.tidb).database_url
+        except TiDbResourceIsNotReady:
+            echo.warning("tidb database is not ready")
+            return None

pocket_cli/resources/aws/builders/__init__.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from pocket.context import BuildContext
+
+
+class Builder(Protocol):
+    def build_and_push(
+        self,
+        *,
+        target: str,
+        dockerfile_path: str,
+        platform: str,
+    ) -> None: ...
+
+    def delete(self) -> None:
+        """ビルドバックエンドのリソースを削除（不要なら何もしない）"""
+        ...
+
+
+def create_builder(
+    build_context: BuildContext,
+    *,
+    region: str,
+    resource_prefix: str,
+    state_bucket: str,
+    permissions_boundary: str | None = None,
+) -> Builder:
+    backend = build_context.backend
+
+    if backend == "docker":
+        from pocket_cli.resources.aws.builders.docker import DockerBuilder
+
+        return DockerBuilder(region=region)
+
+    if backend == "codebuild":
+        from pocket_cli.resources.aws.builders.codebuild import CodeBuildBuilder
+
+        return CodeBuildBuilder(
+            region=region,
+            resource_prefix=resource_prefix,
+            state_bucket=state_bucket,
+            compute_type=build_context.compute_type,
+            permissions_boundary=permissions_boundary,
+        )
+
+    if backend == "depot":
+        from pocket_cli.resources.aws.builders.depot import DepotBuilder
+
+        return DepotBuilder(
+            region=region,
+            project_id=build_context.depot_project_id,
+        )
+
+    raise ValueError(f"不明なビルドバックエンド: {backend}")