chien-dev (dev-environment-setup)

English | 繁體中文

chien-dev is a standardized development environment scaffolder. It supports both DevContainer (Docker) and Virtual Machine (Multipass) backends to help you provision and manage isolated development setups with ease.

---

Features

• Dual Backend Support: Seamlessly toggle between Docker (DevContainer) and Virtual Machine (Multipass).
• Interactive Setup: Customize OS, languages, and services through a friendly CLI.
• Smart Resource Detection: Automatically suggests VM configurations based on host CPU/RAM/Disk.
• SSH Security: Automated SSH key management for VMs.
• Doctor Check: Built-in health checks for ports and dependencies.

---

Demo

---

Usage

1. Installation (Global)

The easiest way to install chien-dev globally is via our install script:

curl -fsSL https://raw.githubusercontent.com/pong1013/dev-environment-setup/main/install.sh | bash

(The script will automatically detect your OS and prompt to install missing dependencies like Docker or Multipass).

2. Before Start

If you skipped the automatic dependency installation, please manually install:

• Docker Desktop (for Container mode)
• Multipass (optional, for VM mode)

3. First-time Flow

chien-dev doctor
chien-dev create <NAME>
chien-dev start <NAME> --project /abs/path/to/repo
chien-dev status

Detailed Command Behavior

• chien-dev help: Show command usage and examples.
• chien-dev create <name>: Create a named environment (interactive or via env vars).
• chien-dev start <name> --project /path: Start environment and mount project to /workspace (alias: -p; defaults to the current directory when omitted).
• chien-dev status [name]: Show all statuses or a specific environment's info.
• chien-dev shell <name>: Enter workspace container bash (Container mode) or show SSH instructions (VM mode).
• chien-dev stop <name>: Stop the environment.
• chien-dev clean <name>: Remove a stopped environment and its generated files. Cleanup is refused while the environment is running.
• chien-dev update: Compare the running Git installation's commit with the canonical GitHub main commit. If behind, ask before a fast-forward update. Updating requires an interactive terminal and a clean installation checkout on local main; unsafe or unavailable checks fail without updating. There is no non-interactive update or --yes option.

Non-interactive Mode (CI/CD Ready)

Pass any option below to skip prompts:

# Create a VM environment
chien-dev create my-node --env vm --cpus 4 --memory 4G --disk 20G

# Create a Container with specific languages
chien-dev create my-dev --langs go,node --db postgres

Option	Values	Default
--env, -e	devcontainer, vm	devcontainer
--os, -o	22.04, 24.04	22.04
--langs, -l	go, node, python, java, php	none
--frontend, -f	react, vue, none	none
--db, -d	postgres, mysql, mongodb	none
--broker, -b	redis, rabbitmq, kafka	none
--cpus, -c	CPU count for VM mode	2
--memory, -m	Memory size for VM mode	2G
--disk, -s	Disk size for VM mode	10G

---

Testing Your Environment

After chien-dev start <NAME>, you can verify the setup:

# For Container Mode:
chien-dev shell <NAME>
go version     # (or node --version, etc.)

# For VM Mode:
# Run the SSH command shown in 'chien-dev status'
ssh ubuntu@<VM_IP>

---

Structure & Extension

• scripts/commands/: CLI command handlers.
• scripts/generators/: Configuration renderers (container_render.sh, vm_render.sh).
• scripts/modules/: Shared logic for docker.sh, vm.sh, and network.sh.

Development Harness

Repository conventions live in AGENTS.md, and task-specific AI workflows live under .agents/skills/. Running the full developer verification requires Ruby 2.6 or newer with its standard YAML library.

This diagram shows the repository's development harness architecture. The gated AI feature workflow follows the process maintained in pong1013/ai-workflow; refer to that repository for the workflow itself.

make verify         # Bash syntax, regression tests, and Skill structure
make harness-audit TRUSTED=1  # Sanitized, read-only Codex Harness review

make verify is also run automatically for pushes and pull requests.

Only run harness-audit after reviewing and trusting the checkout. It sends Codex an allowlisted, redacted snapshot from an isolated temporary directory; ignored files, secret-like paths, symlinks, and paths outside the allowlist are excluded. The best-effort redactor covers common secret assignments, credential-bearing URLs (including database URLs), and Authorization headers. The Codex read-only sandbox prevents repository writes, but it is not a confidentiality boundary.

---

License

Distributed under the MIT License.