sanduary 1.0.0

package/.devcontainer/Dockerfile

@@ -0,0 +1,72 @@
+# Dev Container用Dockerfile
+# Node.js 22 + Docker CLI + Playwright
+
+FROM node:22-bookworm
+
+# Docker CLI インストール（ホストのDockerを操作するため）
+RUN apt-get update && apt-get install -y \
+    ca-certificates \
+    curl \
+    gnupg \
+    lsb-release \
+    && mkdir -p /etc/apt/keyrings \
+    && curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null \
+    && apt-get update \
+    && apt-get install -y docker-ce-cli docker-compose-plugin \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# 開発に便利なツール
+RUN apt-get update && apt-get install -y \
+    git \
+    vim \
+    jq \
+    zip \
+    less \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# ロケール設定（マルチバイト文字対応）
+RUN apt-get update && apt-get install -y \
+    locales \
+    && sed -i -e 's/# ja_JP.UTF-8 UTF-8/ja_JP.UTF-8 UTF-8/' /etc/locale.gen \
+    && sed -i -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen \
+    && locale-gen \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV LANG=ja_JP.UTF-8
+
+# Playwright依存ライブラリ
+RUN apt-get update && apt-get install -y \
+    libatk1.0-0 \
+    libatk-bridge2.0-0 \
+    libcups2 \
+    libxkbcommon0 \
+    libatspi2.0-0 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxfixes3 \
+    libxrandr2 \
+    libgbm1 \
+    libasound2 \
+    libnspr4 \
+    libnss3 \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# グローバルnpmパッケージ
+RUN npm install -g npm@10.9.0
+
+# プロジェクト名のビルド引数（デフォルト: project）
+ARG PROJECT_NAME=project
+
+# ワークスペースディレクトリをnodeユーザーの所有で作成
+RUN mkdir -p /workspaces/${PROJECT_NAME} && chown node:node /workspaces/${PROJECT_NAME}
+
+# 作業ディレクトリ
+WORKDIR /workspaces/${PROJECT_NAME}
+
+# nodeユーザーに切り替え
+USER node

package/.devcontainer/devcontainer.base.json

@@ -0,0 +1,15 @@
+{
+  "service": "devcontainer",
+  "dockerComposeFile": ["docker-compose.yml"],
+  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
+  "workspaceMount": "",
+  "updateRemoteUserUID": true,
+  "initializeCommand": "echo 'PROJECT_ROOT='$(pwd) > .devcontainer/.env && echo 'PROJECT_NAME='$(basename $(pwd)) >> .devcontainer/.env && echo 'GIT_ORIGIN_URL='$(git remote get-url origin 2>/dev/null || echo '') >> .devcontainer/.env && [ -f ~/.claude-sandbox-credentials.json ] || echo '{}' > ~/.claude-sandbox-credentials.json && [ -f ~/.claude-sandbox.json ] || echo '{}' > ~/.claude-sandbox.json",
+  "postCreateCommand": "git init && git remote add origin \"${GIT_ORIGIN_URL:-/host-project}\" && git fetch && git checkout $(git -C /host-project branch --show-current) && echo 'alias claude=\"npx claude --dangerously-skip-permissions\"' >> ~/.bashrc",
+  "shutdownAction": "stopCompose",
+  "remoteUser": "node",
+  "remoteEnv": {
+    "LANG": "ja_JP.UTF-8",
+    "LC_ALL": "ja_JP.UTF-8"
+  }
+}

package/.devcontainer/devcontainer.json

@@ -0,0 +1,17 @@
+{
+  "service": "devcontainer",
+  "dockerComposeFile": [
+    "docker-compose.yml"
+  ],
+  "workspaceFolder": "/workspaces/${PROJECT_NAME:-project}",
+  "workspaceMount": "",
+  "updateRemoteUserUID": true,
+  "initializeCommand": "echo 'PROJECT_ROOT='$(pwd) > .devcontainer/.env && echo 'PROJECT_NAME='$(basename $(pwd)) >> .devcontainer/.env && [ -f ~/.claude-sandbox-credentials.json ] || echo '{}' > ~/.claude-sandbox-credentials.json && [ -f ~/.claude-sandbox.json ] || echo '{}' > ~/.claude-sandbox.json",
+  "postCreateCommand": "git init && git remote add origin \"${GIT_ORIGIN_URL:-/host-project}\" && git fetch && git checkout $(git -C /host-project branch --show-current) && echo 'alias claude=\"npx claude --dangerously-skip-permissions\"' >> ~/.bashrc",
+  "shutdownAction": "stopCompose",
+  "remoteUser": "node",
+  "remoteEnv": {
+    "LANG": "ja_JP.UTF-8",
+    "LC_ALL": "ja_JP.UTF-8"
+  }
+}

package/.devcontainer/docker-compose.yml

@@ -0,0 +1,26 @@
+services:
+  devcontainer:
+    platform: linux/amd64
+    build:
+      context: .
+      dockerfile: Dockerfile
+      args:
+        PROJECT_NAME: ${PROJECT_NAME:-project}
+    group_add:
+      - ${DOCKER_GID:-999}
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ${PROJECT_ROOT:-..}:/host-project
+      - ${HOME}/.claude:/home/node/.claude
+      - ${HOME}/.claude-sandbox.json:/home/node/.claude.json
+      - ${HOME}/.claude-sandbox-credentials.json:/home/node/.claude/.credentials.json
+      - ${HOME}/.gitconfig:/home/node/.gitconfig
+    working_dir: /workspaces/${PROJECT_NAME:-project}
+    command: sleep infinity
+    environment:
+      LANG: ja_JP.UTF-8
+      LC_ALL: ja_JP.UTF-8
+      GIT_CONFIG_COUNT: 1
+      GIT_CONFIG_KEY_0: safe.directory
+      GIT_CONFIG_VALUE_0: /workspaces/${PROJECT_NAME:-project}
+      GIT_ORIGIN_URL: ${GIT_ORIGIN_URL:-/host-project}

package/.devcontainer/sample.devcontainer.override.json

@@ -0,0 +1,31 @@
+{
+  "name": "sandbox",
+  "dockerComposeFile": ["docker-compose.override.yml"],
+  "postCreateCommand": "npm ci && npx prisma generate",
+  "postStartCommand": "npx prisma migrate deploy",
+  "forwardPorts": [3000, 3306],
+  "portsAttributes": {
+    "3000": {
+      "label": "Frontend",
+      "onAutoForward": "notify"
+    },
+    "3306": {
+      "label": "Database",
+      "onAutoForward": "silent"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": ["Prisma.prisma"],
+      "settings": {
+        "[prisma]": {
+          "editor.defaultFormatter": "Prisma.prisma"
+        }
+      }
+    }
+  },
+  "remoteEnv": {
+    "DATABASE_URL": "mysql://root:password@db:3306/sandbox",
+    "NODE_ENV": "development"
+  }
+}

package/.devcontainer/sample.docker-compose.override.yml

@@ -0,0 +1,24 @@
+services:
+  devcontainer:
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      DATABASE_URL: mysql://root:password@db:3306/sandbox
+      NODE_ENV: development
+
+  db:
+    image: mysql:8.0
+    environment:
+      MYSQL_ROOT_PASSWORD: password
+      MYSQL_DATABASE: "sandbox"
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    volumes:
+      - db_data:/var/lib/mysql
+
+volumes:
+  db_data:

package/.devcontainer/templates/devcontainer.override.template.json

@@ -0,0 +1,31 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "dockerComposeFile": ["docker-compose.override.yml"],
+  "postCreateCommand": "npm ci && npx prisma generate",
+  "postStartCommand": "npx prisma migrate deploy",
+  "forwardPorts": [3000, 3306],
+  "portsAttributes": {
+    "3000": {
+      "label": "Frontend",
+      "onAutoForward": "notify"
+    },
+    "3306": {
+      "label": "Database",
+      "onAutoForward": "silent"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": ["Prisma.prisma"],
+      "settings": {
+        "[prisma]": {
+          "editor.defaultFormatter": "Prisma.prisma"
+        }
+      }
+    }
+  },
+  "remoteEnv": {
+    "DATABASE_URL": "mysql://root:password@db:3306/{{PROJECT_NAME}}",
+    "NODE_ENV": "development"
+  }
+}

package/.devcontainer/templates/docker-compose.override.template.yml

@@ -0,0 +1,24 @@
+services:
+  devcontainer:
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      DATABASE_URL: mysql://root:password@db:3306/{{PROJECT_NAME}}
+      NODE_ENV: development
+
+  db:
+    image: mysql:8.0
+    environment:
+      MYSQL_ROOT_PASSWORD: password
+      MYSQL_DATABASE: "{{PROJECT_NAME}}"
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    volumes:
+      - db_data:/var/lib/mysql
+
+volumes:
+  db_data:

package/README.md

@@ -0,0 +1,289 @@
+# sanduary
+
+A secure development sandbox environment for AI agents - providing safe, isolated workspaces for AI coding assistants like Claude Code through Docker DevContainers.
+
+## Overview
+
+**sanduary** (sanctuary + sandbox) creates disposable, secure development environments where AI agents can safely execute code, install packages, and perform development tasks without affecting your host system. Each session runs in an isolated Docker container that is automatically cleaned up when you exit.
+
+## Features
+
+- **Isolated Environments**: Each session runs in a dedicated Docker DevContainer
+- **Dynamic Configuration**: Supports project-specific DevContainer overrides
+- **Auto-Cleanup**: Containers are automatically removed after session ends
+- **Git Integration**: Seamlessly works with your existing Git repositories
+- **Customizable**: Extend base configuration with override files
+- **Vulnerability Reduction**: Generate DevContainer files on-demand instead of committing to Git
+
+## Installation
+
+### Global Installation (Recommended)
+
+Install globally to use across multiple projects:
+
+```bash
+npm install -g sanduary
+```
+
+This allows any team member to generate their own DevContainer configuration without tracking potentially vulnerable configuration files in Git.
+
+### Project-Local Installation
+
+For advanced use cases, install as a project dependency:
+
+```bash
+npm install --save-dev sanduary
+```
+
+Then add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "sdy init"
+  }
+}
+```
+
+This automatically sets up the sandbox environment when developers run `npm install`, providing quick DevContainer setup without committing configuration files.
+
+## Quick Start
+
+### 1. Initialize DevContainer Configuration
+
+Navigate to your project directory and initialize the DevContainer files:
+
+```bash
+cd your-project
+sdy init
+```
+
+This creates `.devcontainer/` directory with base configuration files.
+
+**Important**: Add `.devcontainer/` to your `.gitignore` to keep configuration local:
+
+```gitignore
+# DevContainer - generated by sanduary
+.devcontainer/
+```
+
+### 2. Start the Sandbox Environment
+
+Launch the DevContainer (default command):
+
+```bash
+sdy run
+# or simply
+sdy
+```
+
+The container will:
+- Build and start automatically
+- Execute any `postCreateCommand` and `postStartCommand` from `devcontainer.json`
+- Connect you to an interactive bash session
+- Clean up automatically when you exit
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `sdy init` | Initialize DevContainer configuration files in current project |
+| `sdy run` | Start the DevContainer sandbox (default) |
+| `sdy` | Alias for `sdy run` |
+
+## Configuration
+
+### Base Configuration
+
+After running `sdy init`, you'll have:
+
+```
+.devcontainer/
+├── devcontainer.base.json       # Base DevContainer settings
+├── devcontainer.json            # Main configuration file
+├── docker-compose.yml           # Docker Compose settings
+├── Dockerfile                   # Container image definition
+└── templates/
+    ├── devcontainer.override.template.json
+    └── docker-compose.override.template.yml
+```
+
+**Note**: These files should NOT be committed to Git. Each developer generates their own configuration via `sdy init`.
+
+### Override Files
+
+Customize your sandbox environment by creating override files:
+
+#### DevContainer Override
+
+Create `.devcontainer/devcontainer.override.json`:
+
+```json
+{
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode"
+      ]
+    }
+  },
+  "postCreateCommand": "npm install"
+}
+```
+
+#### Docker Compose Override
+
+Create `.devcontainer/docker-compose.override.yml`:
+
+```yaml
+services:
+  devcontainer:
+    environment:
+      - NODE_ENV=development
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./custom-data:/data
+```
+
+### Configuration Files
+
+The following files are automatically created in your home directory:
+
+- `~/.claude-sandbox.json` - General sandbox settings
+- `~/.claude-sandbox-credentials.json` - Authentication credentials
+
+## Git Management Best Practices
+
+### What to Commit
+
+✅ **DO commit**:
+- `package.json` (with sanduary as dependency)
+- `.gitignore` (with `.devcontainer/` excluded)
+- Project source code and assets
+
+### What NOT to Commit
+
+❌ **DO NOT commit**:
+- `.devcontainer/` directory and its contents
+- `devcontainer.json`
+- `docker-compose.yml`
+- `Dockerfile`
+
+### Why?
+
+1. **Security**: DevContainer configurations can contain sensitive settings or expose vulnerabilities
+2. **Flexibility**: Each developer can customize their environment without affecting others
+3. **Version Control**: Configuration generation is handled by sanduary versions, not Git history
+
+### Sample `.gitignore`
+
+```gitignore
+# DevContainer - generated by sanduary
+.devcontainer/
+
+# Dependency directories
+node_modules/
+```
+
+## Workflow Examples
+
+### Team Collaboration
+
+1. **Project Setup** (once per project):
+```bash
+# Add sanduary to project
+npm install --save-dev sanduary
+
+# Update .gitignore
+echo ".devcontainer/" >> .gitignore
+
+# Commit
+git add package.json .gitignore
+git commit -m "feat: add sanduary for DevContainer management"
+```
+
+2. **New Developer Setup**:
+```bash
+# Clone project
+git clone <repo-url>
+cd <project>
+
+# Install dependencies (automatically runs sdy init via postinstall)
+npm install
+
+# Start sandbox
+sdy
+```
+
+3. **Existing Developer**:
+```bash
+# Pull latest changes
+git pull
+
+# Update dependencies if needed
+npm install
+
+# Start sandbox
+sdy
+```
+
+### Global Installation Workflow
+
+1. **One-time Setup**:
+```bash
+# Install globally
+npm install -g sanduary
+```
+
+2. **Per-project Usage**:
+```bash
+cd your-project
+
+# Initialize (only needed once per project)
+sdy init
+
+# Start sandbox (anytime)
+sdy
+```
+
+## How It Works
+
+1. **Dynamic Naming**: Each session gets a unique project name (`sandbox-XXXX`)
+2. **Git-Aware**: Automatically detects project root via Git
+3. **Docker Compose**: Uses Docker Compose for container orchestration
+4. **Lifecycle Hooks**: Executes `postCreateCommand` and `postStartCommand` from DevContainer config
+5. **Auto-Cleanup**: Containers and volumes are removed on exit via cleanup trap
+
+## Use Cases
+
+- **AI Agent Sandboxing**: Safe environment for Claude Code and similar AI assistants
+- **Dependency Testing**: Test package installations without polluting host
+- **Code Experimentation**: Try risky changes in isolated environment
+- **Multi-Project Development**: Switch between different project configurations easily
+- **Onboarding**: New team members get consistent development environments instantly
+
+## Requirements
+
+- Docker Engine
+- Node.js and npm (for installation)
+- Git (for project detection)
+- `jq` (for JSON parsing)
+
+## Environment Variables
+
+The following environment variables are automatically set during execution:
+
+- `PROJECT_ROOT`: Git repository root directory
+- `PROJECT_NAME`: Unique sandbox instance name
+- `GIT_ORIGIN_URL`: Set to `/host-project` when launched via `sdy`
+
+## License
+
+ISC
+
+## Links
+
+- [GitHub Repository](https://github.com/yamadamasahiro/sanduary)
+- [Report Issues](https://github.com/yamadamasahiro/sanduary/issues)

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "sanduary",
+  "version": "1.0.0",
+  "description": "Development sandbox environment for AI agents - A secure sanctuary for running AI coding assistants in Docker DevContainers",
+  "keywords": [
+    "devcontainer",
+    "docker",
+    "sandbox",
+    "ai",
+    "agent",
+    "claude",
+    "development",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yamadamasahiro/sanduary.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yamadamasahiro/sanduary/issues"
+  },
+  "homepage": "https://github.com/yamadamasahiro/sanduary#readme",
+  "scripts": {},
+  "bin": {
+    "sdy": "scripts/sandbox.sh"
+  },
+  "files": [
+    "scripts/",
+    ".devcontainer/"
+  ],
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "main": "index.js",
+  "devDependencies": {
+    "@anthropic-ai/claude-code": "^2.0.72"
+  },
+  "author": "",
+  "license": "ISC"
+}

package/scripts/postinstall.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+const fs = require('fs')
+const path = require('path')
+const yaml = require('js-yaml')
+
+const INIT_CWD = process.env.INIT_CWD || process.cwd()
+const SANDBOX_DEVCONTAINER_PATH =
+  '../packages/infrastructure/sandbox/.devcontainer'
+
+// 連結すべきフィールド（deepMergeではなく && で連結）
+const CONCAT_FIELDS = ['postCreateCommand', 'postStartCommand']
+
+// テンプレートディレクトリ
+const templatesDir = path.join(__dirname, '../.devcontainer/templates')
+
+// パス
+const devcontainerDir = path.join(INIT_CWD, '.devcontainer')
+const baseJsonPath = path.join(
+  __dirname,
+  '../.devcontainer/devcontainer.base.json',
+)
+const overrideJsonPath = path.join(
+  devcontainerDir,
+  'devcontainer.override.json',
+)
+const outputJsonPath = path.join(devcontainerDir, 'devcontainer.json')
+
+// Docker Compose パス
+const baseComposePath = path.join(
+  __dirname,
+  '../.devcontainer/docker-compose.yml',
+)
+const overrideComposePath = path.join(
+  devcontainerDir,
+  'docker-compose.override.yml',
+)
+const outputComposePath = path.join(devcontainerDir, 'docker-compose.yml')
+
+// Dockerfile パス
+const sourceDockerfilePath = path.join(__dirname, '../.devcontainer/Dockerfile')
+const outputDockerfilePath = path.join(devcontainerDir, 'Dockerfile')
+
+// ディレクトリ作成
+fs.mkdirSync(devcontainerDir, { recursive: true })
+
+/**
+ * 深いマージを行う関数
+ * - 配列はconcatで結合
+ * - オブジェクトは再帰的にマージ
+ * - プリミティブ値はoverrideが優先
+ */
+function deepMerge(base, override) {
+  if (override === undefined) {
+    return base
+  }
+  if (base === undefined) {
+    return override
+  }
+
+  // 両方が配列の場合はconcat
+  if (Array.isArray(base) && Array.isArray(override)) {
+    return [...base, ...override]
+  }
+
+  // 両方がオブジェクトの場合は再帰マージ
+  if (
+    typeof base === 'object' &&
+    base !== null &&
+    typeof override === 'object' &&
+    override !== null &&
+    !Array.isArray(base) &&
+    !Array.isArray(override)
+  ) {
+    const result = { ...base }
+    for (const key of Object.keys(override)) {
+      result[key] = deepMerge(base[key], override[key])
+    }
+    return result
+  }
+
+  // それ以外はoverrideが優先
+  return override
+}
+
+/**
+ * 特定のフィールドを連結する関数
+ * CONCAT_FIELDSに指定されたフィールドは && で連結
+ */
+function applyConcatFields(merged, base, override) {
+  for (const field of CONCAT_FIELDS) {
+    if (base[field] && override[field]) {
+      merged[field] = `${base[field]} && ${override[field]}`
+    }
+  }
+  return merged
+}
+
+/**
+ * テンプレートからファイルを作成する関数
+ * PROJECT_NAMEプレースホルダーを置換
+ */
+function createFromTemplate(templatePath, outputPath) {
+  if (fs.existsSync(templatePath)) {
+    const projectName = path.basename(INIT_CWD)
+    let templateContent = fs.readFileSync(templatePath, 'utf8')
+    templateContent = templateContent.replace(/\{\{PROJECT_NAME\}\}/g, projectName)
+    fs.writeFileSync(outputPath, templateContent)
+    console.log(`Created from template: ${outputPath}`)
+    return true
+  }
+  return false
+}
+
+// =====================================
+// devcontainer.json の生成
+// =====================================
+
+// base.jsonを読み込み
+const base = JSON.parse(fs.readFileSync(baseJsonPath, 'utf8'))
+
+// overrideファイルが存在しない場合、サンプルテンプレートを作成（sample.接頭辞付き）
+const overrideJsonTemplate = path.join(templatesDir, 'devcontainer.override.template.json')
+const sampleOverrideJsonPath = path.join(devcontainerDir, 'sample.devcontainer.override.json')
+if (!fs.existsSync(overrideJsonPath) && !fs.existsSync(sampleOverrideJsonPath)) {
+  createFromTemplate(overrideJsonTemplate, sampleOverrideJsonPath)
+}
+
+// override.jsonを読み込み（存在しない場合は空オブジェクト）
+let override = {}
+if (fs.existsSync(overrideJsonPath)) {
+  override = JSON.parse(fs.readFileSync(overrideJsonPath, 'utf8'))
+}
+
+// dockerComposeFileをマージ
+const baseDockerComposeFiles = (base.dockerComposeFile || []).map(
+  (file) => `${SANDBOX_DEVCONTAINER_PATH}/${file}`,
+)
+const overrideDockerComposeFiles = override.dockerComposeFile || []
+
+// オブジェクトをマージ（override が優先、深いマージで remoteEnv 等も正しくマージ）
+const merged = deepMerge(base, override)
+
+// CONCAT_FIELDSは && で連結（deepMergeではoverrideが優先されるため、ここで連結処理）
+applyConcatFields(merged, base, override)
+
+// dockerComposeFileは配列を結合（ただしdocker-compose.ymlを生成するのでそれを参照）
+merged.dockerComposeFile = ['docker-compose.yml']
+
+// 出力
+fs.writeFileSync(outputJsonPath, JSON.stringify(merged, null, 2) + '\n')
+
+console.log(`Generated: ${outputJsonPath}`)
+
+// =====================================
+// docker-compose.yml の生成
+// =====================================
+
+// base docker-compose.ymlを読み込み
+const baseComposeContent = fs.readFileSync(baseComposePath, 'utf8')
+const baseCompose = yaml.load(baseComposeContent)
+
+// overrideファイルが存在しない場合、サンプルテンプレートを作成（sample.接頭辞付き）
+const overrideComposeTemplate = path.join(templatesDir, 'docker-compose.override.template.yml')
+const sampleOverrideComposePath = path.join(devcontainerDir, 'sample.docker-compose.override.yml')
+if (!fs.existsSync(overrideComposePath) && !fs.existsSync(sampleOverrideComposePath)) {
+  createFromTemplate(overrideComposeTemplate, sampleOverrideComposePath)
+}
+
+// override docker-compose.ymlを読み込み（存在しない場合は空オブジェクト）
+let overrideCompose = {}
+if (fs.existsSync(overrideComposePath)) {
+  const overrideComposeContent = fs.readFileSync(overrideComposePath, 'utf8')
+  overrideCompose = yaml.load(overrideComposeContent)
+}
+
+// 深いマージを実行
+const mergedCompose = deepMerge(baseCompose, overrideCompose)
+
+// build.contextとbuild.dockerfileのパスを調整（ローカルのDockerfileを参照）
+if (
+  mergedCompose.services &&
+  mergedCompose.services.devcontainer &&
+  mergedCompose.services.devcontainer.build
+) {
+  mergedCompose.services.devcontainer.build.context = '.'
+  mergedCompose.services.devcontainer.build.dockerfile = 'Dockerfile'
+}
+
+// YAMLとして出力（変数展開を維持するため、quotingOptionsを設定）
+const outputYaml = yaml.dump(mergedCompose, {
+  lineWidth: -1, // 行の折り返しを無効化
+  quotingType: '"',
+  forceQuotes: false,
+  noRefs: true,
+})
+
+fs.writeFileSync(outputComposePath, outputYaml)
+
+console.log(`Generated: ${outputComposePath}`)
+
+// =====================================
+// Dockerfile のコピー
+// =====================================
+
+fs.copyFileSync(sourceDockerfilePath, outputDockerfilePath)
+
+console.log(`Copied: ${outputDockerfilePath}`)

package/scripts/sandbox.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+set -e
+
+# スクリプトの実際のパスを取得（シンボリックリンクを解決）
+SCRIPT_PATH="$(realpath "$0")"
+SCRIPT_DIR="$(dirname "$SCRIPT_PATH")"
+PACKAGE_ROOT="$(dirname "$SCRIPT_DIR")"
+
+COMMAND="${1:-run}"
+
+case "$COMMAND" in
+    init)
+        node "$SCRIPT_DIR/postinstall.js"
+        ;;
+    run)
+        # プロジェクトルートをgitから取得
+        PROJECT_ROOT="$(git rev-parse --show-toplevel)"
+        export PROJECT_ROOT
+
+        DEVCONTAINER_DIR="$PROJECT_ROOT/.devcontainer"
+        DEVCONTAINER_JSON="$PROJECT_ROOT/.devcontainer/devcontainer.json"
+
+        # ランダムなプロジェクト名を生成（sandbox-XXXX形式）
+        PROJECT_NAME="sandbox-$(head -c 4 /dev/urandom | xxd -p)"
+        export PROJECT_NAME
+
+        cd "$DEVCONTAINER_DIR"
+
+        # 認証ファイルが存在しない場合は空のJSONを作成
+        CREDENTIALS_FILE="$HOME/.claude-sandbox-credentials.json"
+        if [ ! -f "$CREDENTIALS_FILE" ]; then
+            echo '{}' > "$CREDENTIALS_FILE"
+        fi
+
+        # .claude-sandbox.jsonが存在しない場合は空のJSONを作成
+        CLAUDE_JSON="$HOME/.claude-sandbox.json"
+        if [ ! -f "$CLAUDE_JSON" ]; then
+            echo '{}' > "$CLAUDE_JSON"
+        fi
+
+        # 終了時のcleanup関数
+        cleanup() {
+            echo ""
+            echo "Stopping Dev Container..."
+            docker compose -p "$PROJECT_NAME" down -v --remove-orphans 2>/dev/null || true
+        }
+
+        # 終了時に必ずcleanupを実行
+        trap cleanup EXIT
+
+        echo "Starting Dev Container (project: $PROJECT_NAME)..."
+        docker compose -p "$PROJECT_NAME" up -d
+
+        # コンテナが起動するまで待機
+        echo "Waiting for container to be ready..."
+        sleep 5
+
+        # コンテナIDを取得
+        CONTAINER_ID=$(docker compose -p "$PROJECT_NAME" ps -q devcontainer)
+
+        # devcontainer.jsonからコマンドを読み取って実行
+        POST_CREATE_CMD=$(jq -r '.postCreateCommand // empty' "$DEVCONTAINER_JSON")
+        POST_START_CMD=$(jq -r '.postStartCommand // empty' "$DEVCONTAINER_JSON")
+
+        # ワークディレクトリを設定
+        WORKSPACE_DIR="/workspaces/$PROJECT_NAME"
+
+        if [ -n "$POST_CREATE_CMD" ]; then
+            echo "Running postCreateCommand..."
+            # sandbox.sh経由の場合はGIT_ORIGIN_URLを/host-projectに設定
+            docker exec -w "$WORKSPACE_DIR" -e GIT_ORIGIN_URL=/host-project "$CONTAINER_ID" bash -c "$POST_CREATE_CMD"
+        fi
+
+        if [ -n "$POST_START_CMD" ]; then
+            echo "Running postStartCommand..."
+            docker exec -w "$WORKSPACE_DIR" "$CONTAINER_ID" bash -c "$POST_START_CMD"
+        fi
+
+        # ランダムな色コードを生成（31-36: 赤、緑、黄、青、マゼンタ、シアン）
+        COLORS=(31 32 33 34 35 36)
+        RANDOM_COLOR=${COLORS[$RANDOM % ${#COLORS[@]}]}
+
+        # カスタムPS1を設定してbashを起動
+        echo "Connecting to Dev Container..."
+        docker exec -it -w "$WORKSPACE_DIR" "$CONTAINER_ID" bash -c "export PS1='\[\e[${RANDOM_COLOR}m\]\h\[\e[0m\]:\w# '; exec bash" || true
+        ;;
+    *)
+        echo "Usage: sandbox [init|run]"
+        echo "  init  - Initialize devcontainer files"
+        echo "  run   - Start Dev Container (default)"
+        exit 1
+        ;;
+esac