From 7ffc2a664d6058cbcaefa7183f26146aa984648d Mon Sep 17 00:00:00 2001 From: Matthew Mellor Date: Mon, 9 Mar 2026 21:05:41 -0500 Subject: [PATCH] docs(getting-started): add devrail init distribution and CLI reference Add _redirects file for curl-pipe-bash distribution via devrail.dev/init.sh. Update getting-started guides to lead with devrail init as the primary adoption path, and add a CLI reference page documenting all options. Co-Authored-By: Claude Opus 4.6 --- content/docs/getting-started/_index.md | 27 ++- content/docs/getting-started/cli-reference.md | 172 ++++++++++++++++++ content/docs/getting-started/new-project.md | 98 +++++----- content/docs/getting-started/retrofit.md | 141 +++++++------- static/_redirects | 5 + 5 files changed, 314 insertions(+), 129 deletions(-) create mode 100644 content/docs/getting-started/cli-reference.md create mode 100644 static/_redirects diff --git a/content/docs/getting-started/_index.md b/content/docs/getting-started/_index.md index 8d9d938..e2aeb7a 100644 --- a/content/docs/getting-started/_index.md +++ b/content/docs/getting-started/_index.md @@ -2,10 +2,28 @@ title: "Getting Started" linkTitle: "Getting Started" weight: 10 -description: "Quick start guides for creating new DevRail projects and retrofitting existing repositories." +description: "Get up and running with DevRail in minutes using devrail init." --- -Get up and running with DevRail in minutes. Whether you are starting a brand-new project or adding DevRail standards to an existing repository, the process is straightforward. +Get up and running with DevRail in minutes. The `devrail init` script generates all DevRail configuration files in your project directory with a single command. + +## Quick Start + +```bash +# Run devrail init in your project directory +curl -fsSL https://devrail.dev/init.sh | bash +``` + +This launches an interactive wizard that asks which languages you use, which CI platform you want (GitHub Actions or GitLab CI), and which DevRail layers to install. It generates all configuration files, handles existing file conflicts safely, and is idempotent (safe to re-run). + +For non-interactive use: + +```bash +# Generate everything for a Python project with GitHub Actions +curl -fsSL https://devrail.dev/init.sh | bash -s -- --all --languages python --ci github --yes +``` + +See the [CLI Reference](/docs/getting-started/cli-reference/) for all options. ## Prerequisites @@ -21,14 +39,15 @@ All other tools (linters, formatters, security scanners, test runners) are pre-i ## Choose Your Path -- **[New Project](/docs/getting-started/new-project/)** -- Start a new repository from a DevRail template. All configuration files are pre-set. +- **[New Project](/docs/getting-started/new-project/)** -- Start a new repository with `devrail init` or from a template. - **[Retrofit Existing Project](/docs/getting-started/retrofit/)** -- Add DevRail standards to a repository you already have. - **[Working with AI Agents](/docs/getting-started/agents/)** -- Get AI coding agents to follow DevRail standards in your projects. +- **[CLI Reference](/docs/getting-started/cli-reference/)** -- Full `devrail init` command reference. - **[Compliance Badge](/docs/getting-started/badge/)** -- Add a DevRail compliance badge to your README. ## Verify Your Setup -After setting up DevRail (either path), verify everything works by running: +After setting up DevRail (any path), verify everything works by running: ```bash # Run all DevRail checks (linting, formatting, security, tests) diff --git a/content/docs/getting-started/cli-reference.md b/content/docs/getting-started/cli-reference.md new file mode 100644 index 0000000..e562175 --- /dev/null +++ b/content/docs/getting-started/cli-reference.md @@ -0,0 +1,172 @@ +--- +title: "CLI Reference" +linkTitle: "CLI Reference" +weight: 25 +description: "Complete reference for the devrail init command." +--- + +## Installation + +`devrail init` is a single shell script. No package manager is required — run it directly with `curl`: + +```bash +curl -fsSL https://devrail.dev/init.sh | bash +``` + +Or download it for repeated use: + +```bash +curl -fsSL https://devrail.dev/init.sh -o devrail-init.sh +chmod +x devrail-init.sh +./devrail-init.sh [options] +``` + +## Synopsis + +``` +devrail init [options] +``` + +When run without options, the script launches an interactive wizard that prompts for languages, CI platform, and which adoption layers to install. + +## Options + +| Option | Description | +|---|---| +| `--languages ` | Comma-separated list of languages (e.g., `python,bash,go`) | +| `--ci ` | CI platform: `github`, `gitlab`, or `none` | +| `--all` | Install all 4 layers (agent files, pre-commit, Makefile, CI) | +| `--agents-only` | Install only Layer 1 (agent instruction files) | +| `--yes` | Non-interactive mode; skip existing files without prompting | +| `--force` | Overwrite existing files without prompting | +| `--dry-run` | Show what would be generated without writing any files | +| `--version` | Print the DevRail version and exit | +| `--help` | Print usage information and exit | + +## Supported Languages + +The `--languages` flag accepts any combination of the following: + +| Language | Pre-commit Hooks | Makefile Targets | +|---|---|---| +| `python` | ruff (lint + format) | ruff check, ruff format, pytest | +| `bash` | shellcheck, shfmt | shellcheck, shfmt | +| `terraform` | terraform_fmt, terraform_validate, terraform_tflint, terragrunt_fmt | tflint, terraform fmt | +| `ansible` | ansible-lint | ansible-lint | +| `ruby` | rubocop | rubocop, brakeman, bundler-audit | +| `go` | golangci-lint | golangci-lint, gofumpt, govulncheck | +| `javascript` | eslint, prettier | eslint, prettier, tsc, npm audit | +| `rust` | cargo-fmt, cargo-clippy | cargo fmt, cargo clippy, cargo audit | + +## Adoption Layers + +`devrail init` uses a 4-layer progressive adoption model. In interactive mode, you choose which layers to install. In non-interactive mode, use `--all` for everything or `--agents-only` for just Layer 1. + +### Layer 1: Agent Instruction Files + +Files that tell AI coding agents (Claude Code, Cursor, OpenCode) how to work in your project. + +| File | Purpose | +|---|---| +| `CLAUDE.md` | Claude Code agent instructions | +| `AGENTS.md` | Generic agent instructions | +| `.cursorrules` | Cursor agent instructions | +| `.opencode/agents.yaml` | OpenCode agent instructions | + +### Layer 2: Pre-commit Hooks + +Language-aware `.pre-commit-config.yaml` with hooks for your declared languages, plus conventional commits and gitleaks secret detection. + +### Layer 3: Makefile + Container + +| File | Purpose | +|---|---| +| `Makefile` | Two-layer delegation pattern (host → Docker → container) | +| `DEVELOPMENT.md` | Canonical development standards reference | +| `.editorconfig` | Editor formatting rules | +| `.gitignore` | Standard ignore patterns (appended if exists) | +| `.gitleaksignore` | Gitleaks allowlist | +| `.devrail.yml` | Language declaration and project settings | + +### Layer 4: CI Pipelines + +**GitHub Actions** generates 6 workflow files: + +- `.github/workflows/lint.yml` +- `.github/workflows/format.yml` +- `.github/workflows/test.yml` +- `.github/workflows/security.yml` +- `.github/workflows/scan.yml` +- `.github/workflows/docs.yml` + +Plus `.github/PULL_REQUEST_TEMPLATE.md` and `.github/CODEOWNERS`. + +**GitLab CI** generates: + +- `.gitlab-ci.yml` (single file with parallel check-stage jobs) +- `.gitlab/merge_request_templates/default.md` +- `.gitlab/CODEOWNERS` + +## Conflict Resolution + +When `devrail init` encounters an existing file: + +| Mode | Behavior | +|---|---| +| Interactive (default) | Prompts: **[s]kip**, **[o]verwrite**, or **[b]ackup + overwrite** | +| `--yes` | Skips existing files (safe, preserves your files) | +| `--force` | Overwrites existing files without prompting | + +### Makefile Merge Strategy + +| Scenario | Behavior | +|---|---| +| No existing Makefile | DevRail Makefile written normally | +| Existing Makefile with DevRail markers | Updated in-place between markers | +| Existing non-DevRail Makefile | Backed up to `Makefile.pre-devrail`, DevRail Makefile written, include guidance printed | + +### .gitignore Handling + +DevRail patterns are appended below a `# --- DevRail ---` marker. If the marker already exists, the append is skipped (idempotent). + +## `.devrail.yml` Configuration + +The script reads `.devrail.yml` if it exists, or creates one based on the `--languages` flag or interactive prompts. + +```yaml +# .devrail.yml +languages: + - python + - bash + +fail_fast: false +log_format: json +``` + +## Examples + +```bash +# Interactive mode — walks through all choices +curl -fsSL https://devrail.dev/init.sh | bash + +# Greenfield Python project with GitHub Actions +curl -fsSL https://devrail.dev/init.sh | bash -s -- --all --languages python --ci github --yes + +# Add agent files only to any project +curl -fsSL https://devrail.dev/init.sh | bash -s -- --agents-only --yes + +# Preview what would be generated (dry run) +curl -fsSL https://devrail.dev/init.sh | bash -s -- --all --languages go,rust --ci gitlab --dry-run + +# Multi-language project with GitLab CI +curl -fsSL https://devrail.dev/init.sh | bash -s -- --all --languages python,bash,terraform --ci gitlab --yes + +# Force overwrite all existing files +curl -fsSL https://devrail.dev/init.sh | bash -s -- --all --languages javascript --ci github --force +``` + +## Environment Variables + +| Variable | Default | Description | +|---|---|---| +| `DEVRAIL_VERSION` | `v1` | Container image tag used in generated files | diff --git a/content/docs/getting-started/new-project.md b/content/docs/getting-started/new-project.md index 9c30dbe..218557e 100644 --- a/content/docs/getting-started/new-project.md +++ b/content/docs/getting-started/new-project.md @@ -2,74 +2,57 @@ title: "New Project" linkTitle: "New Project" weight: 10 -description: "Create a new DevRail-compliant project from a GitHub or GitLab template." +description: "Create a new DevRail-compliant project using devrail init or a template." --- -The fastest way to start a DevRail-compliant project is to create a repository from one of the official templates. All DevRail configuration files are included and pre-configured. +## Recommended: `devrail init` -## From GitHub Template - -### Step 1: Create the Repository - -Navigate to the [DevRail GitHub template](https://github.com/devrail-dev/github-repo-template) and click **"Use this template"** to create a new repository in your organization or personal account. - -Alternatively, use the GitHub CLI: +The fastest way to start a new DevRail project is `devrail init`. Run it in an empty directory (or a freshly initialized git repo) and it generates all configuration files: ```bash -# Create a new repository from the DevRail GitHub template -gh repo create my-new-project --template devrail-dev/github-repo-template --public -cd my-new-project -``` - -### Step 2: Configure Your Languages - -Edit `.devrail.yml` to declare which languages your project uses. The Makefile reads this file to determine which tools to run. +mkdir my-new-project && cd my-new-project +git init -```yaml -# .devrail.yml -- declare your project's languages -languages: - - python - - bash +# Interactive mode — prompts for languages and CI platform +curl -fsSL https://devrail.dev/init.sh | bash -fail_fast: false -log_format: json +# Or non-interactive — specify everything up front +curl -fsSL https://devrail.dev/init.sh | bash -s -- --all --languages python,bash --ci github --yes ``` -Supported languages: `python`, `bash`, `terraform`, `ansible`, `ruby`, `go`, `javascript`. List only the languages your project actually uses. +This generates all DevRail files including the Makefile, `.devrail.yml`, pre-commit config, agent instruction files, CI workflows, and documentation. See the [CLI Reference](/docs/getting-started/cli-reference/) for all options. -### Step 3: Install Pre-Commit Hooks +After running `devrail init`: ```bash # Install git hooks for local enforcement make install-hooks -``` -This sets up pre-commit hooks that run formatting checks and secret detection on every commit, plus a pre-push hook that runs `make check` before every push. - -### Step 4: Run Your First Check - -```bash # Run all DevRail checks make check + +# Make your first commit +git add . +git commit -m "feat: initialize project with DevRail standards" ``` -The first run pulls the dev-toolchain Docker image (~1 GB). Subsequent runs use the cached image and complete in under 5 minutes. +## Alternative: From a Template -### Step 5: Make Your First Commit +You can also create a repository directly from one of the official templates. All DevRail configuration files are included and pre-configured. -```bash -# Stage all files -git add . +### From GitHub Template -# Commit using conventional commit format -git commit -m "feat: initialize project with DevRail standards" -``` +Navigate to the [DevRail GitHub template](https://github.com/devrail-dev/github-repo-template) and click **"Use this template"** to create a new repository in your organization or personal account. -The pre-commit hooks run automatically. If any check fails, fix the issue and commit again. +Alternatively, use the GitHub CLI: -## From GitLab Template +```bash +# Create a new repository from the DevRail GitHub template +gh repo create my-new-project --template devrail-dev/github-repo-template --public +cd my-new-project +``` -### Step 1: Create the Project +### From GitLab Template In GitLab, navigate to **New Project > Create from template > Custom** and select the DevRail GitLab template. Enter your project name and create the project. @@ -87,13 +70,12 @@ git add . git commit -m "feat: initialize project with DevRail standards" ``` -### Step 2: Configure Your Languages - -Edit `.devrail.yml` just as described in the GitHub workflow above. The configuration file format is identical across platforms. - -### Step 3: Install Pre-Commit Hooks and Verify +### After Creating from Template ```bash +# Edit .devrail.yml to declare your project's languages +# Configure your languages (see below) + # Install git hooks make install-hooks @@ -101,9 +83,25 @@ make install-hooks make check ``` -## What Is Included in the Template +## Configure Your Languages + +Edit `.devrail.yml` to declare which languages your project uses. The Makefile reads this file to determine which tools to run. + +```yaml +# .devrail.yml -- declare your project's languages +languages: + - python + - bash + +fail_fast: false +log_format: json +``` + +Supported languages: `python`, `bash`, `terraform`, `ansible`, `ruby`, `go`, `javascript`, `rust`. List only the languages your project actually uses. + +## What Is Included -Both templates ship with the following files: +Whether you use `devrail init` or a template, you get the following files: | File | Purpose | |---|---| diff --git a/content/docs/getting-started/retrofit.md b/content/docs/getting-started/retrofit.md index 586af45..017e479 100644 --- a/content/docs/getting-started/retrofit.md +++ b/content/docs/getting-started/retrofit.md @@ -2,105 +2,64 @@ title: "Retrofit Existing Project" linkTitle: "Retrofit" weight: 20 -description: "Add DevRail standards to an existing repository." +description: "Add DevRail standards to an existing repository using devrail init." --- -If you already have a repository and want to adopt DevRail standards, follow this guide to add the necessary configuration files without disrupting your existing code. +If you already have a repository and want to adopt DevRail standards, `devrail init` handles everything — generating configuration files, backing up conflicting files, and merging `.gitignore` patterns. -## Step 1: Copy DevRail Files +## Recommended: `devrail init` -Copy the following files from the DevRail template repository into your project root. You can download them individually or clone the template and copy them over. - -### Required Files - -These files are essential for DevRail to work: +Run `devrail init` in your existing project directory: ```bash -# Download required DevRail files from the GitHub template -# Replace with your preferred method (curl, wget, manual copy) -curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/Makefile -curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/.devrail.yml -curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/.editorconfig -curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/.pre-commit-config.yaml -curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/DEVELOPMENT.md -``` - -| File | Purpose | Can You Skip It? | -|---|---|---| -| `Makefile` | Universal execution interface | No -- required | -| `.devrail.yml` | Language declaration | No -- required | -| `.editorconfig` | Editor formatting rules | No -- required | -| `.pre-commit-config.yaml` | Pre-commit hook config | Recommended | -| `DEVELOPMENT.md` | Canonical standards doc | Recommended | - -### Optional Files +cd my-existing-project -These files enhance the development experience but are not strictly required: +# Interactive mode — choose languages, CI platform, and adoption layers +curl -fsSL https://devrail.dev/init.sh | bash -```bash -# Download optional agent instruction files -curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/CLAUDE.md -curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/AGENTS.md -curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/.cursorrules -mkdir -p .opencode -curl -o .opencode/agents.yaml https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/.opencode/agents.yaml +# Or non-interactive — specify everything up front +curl -fsSL https://devrail.dev/init.sh | bash -s -- --all --languages python,bash --ci github --yes ``` -| File | Purpose | -|---|---| -| `CLAUDE.md` | Claude Code agent instructions | -| `AGENTS.md` | Generic agent instructions | -| `.cursorrules` | Cursor agent instructions | -| `.opencode/agents.yaml` | OpenCode agent instructions | - -## Step 2: Configure `.devrail.yml` +### What Happens to Existing Files -Edit `.devrail.yml` to declare which languages your project uses: +`devrail init` handles conflicts safely: -```yaml -# .devrail.yml -- configure for your project -languages: - - python # Include if your project has Python code - - bash # Include if your project has shell scripts - # - terraform # Include if your project has Terraform configs - # - ansible # Include if your project has Ansible playbooks - -fail_fast: false -log_format: json -``` +| Scenario | Behavior | +|---|---| +| File does not exist | Created normally | +| File already exists (interactive) | Prompts: **[s]kip**, **[o]verwrite**, or **[b]ackup + overwrite** | +| File already exists (`--yes`) | Skipped (preserves your files) | +| File already exists (`--force`) | Overwritten without prompting | +| Existing Makefile (non-DevRail) | Backed up to `Makefile.pre-devrail`, DevRail Makefile written with include guidance | +| Existing Makefile (DevRail markers) | Updated in-place between markers | +| Existing `.gitignore` | DevRail patterns appended below a `# --- DevRail ---` marker (idempotent) | -Only list languages that your project actually uses. The Makefile reads this file to determine which tools to run. +### Progressive Adoption -## Step 3: Review Your `.gitignore` +You do not have to adopt everything at once. `devrail init` supports 4 layers that you can install incrementally: -Make sure your `.gitignore` includes common DevRail patterns. Add these lines if they are not already present: +1. **Agent files only** (`--agents-only`) — CLAUDE.md, AGENTS.md, .cursorrules, .opencode/agents.yaml +2. **Pre-commit hooks** — .pre-commit-config.yaml with language-aware hooks +3. **Makefile + container** — Makefile, DEVELOPMENT.md, .editorconfig, .gitignore, .devrail.yml +4. **CI pipelines** — GitHub Actions workflows or GitLab CI configuration -```gitignore -# DevRail / Editor -.DS_Store -Thumbs.db -*.swp -*.swo -*~ -``` +In interactive mode, you are prompted for each layer. In non-interactive mode, use `--all` for everything or `--agents-only` for just agent files. -## Step 4: Install Pre-Commit Hooks +### After Running `devrail init` ```bash -# Install git hooks for local enforcement -make install-hooks -``` +# Configure your languages in .devrail.yml (if not already set via --languages) +# Edit .devrail.yml to list only the languages your project uses -This command sets up pre-commit hooks for formatting, linting, and secret detection on every commit, plus a pre-push hook that runs `make check` before every push. - -## Step 5: Run Your First Check +# Install git hooks +make install-hooks -```bash # Run all DevRail checks against your existing code make check ``` -Expect some findings on the first run -- your existing code may not match DevRail formatting or linting standards. This is normal. +Expect some findings on the first run — your existing code may not match DevRail formatting or linting standards. This is normal. ### Fixing Findings @@ -113,7 +72,7 @@ make fix For linting issues that cannot be auto-fixed, address them manually following the guidance in the [Standards Reference](/docs/standards/). -## Step 6: Commit DevRail Files +### Commit DevRail Files ```bash # Stage all DevRail configuration files @@ -126,6 +85,38 @@ git add CLAUDE.md AGENTS.md .cursorrules .opencode/agents.yaml git commit -m "chore: add DevRail development standards" ``` +## Alternative: Manual Setup + +If you prefer to copy files manually instead of using `devrail init`, download them from the template repository: + +### Required Files + +```bash +curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/Makefile +curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/.devrail.yml +curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/.editorconfig +curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/.pre-commit-config.yaml +curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/DEVELOPMENT.md +``` + +| File | Purpose | Can You Skip It? | +|---|---|---| +| `Makefile` | Universal execution interface | No -- required | +| `.devrail.yml` | Language declaration | No -- required | +| `.editorconfig` | Editor formatting rules | No -- required | +| `.pre-commit-config.yaml` | Pre-commit hook config | Recommended | +| `DEVELOPMENT.md` | Canonical standards doc | Recommended | + +### Optional Agent Files + +```bash +curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/CLAUDE.md +curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/AGENTS.md +curl -O https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/.cursorrules +mkdir -p .opencode +curl -o .opencode/agents.yaml https://raw.githubusercontent.com/devrail-dev/github-repo-template/main/.opencode/agents.yaml +``` + ## Handling Conflicts with Existing Configuration ### Existing Makefile diff --git a/static/_redirects b/static/_redirects new file mode 100644 index 0000000..83a7539 --- /dev/null +++ b/static/_redirects @@ -0,0 +1,5 @@ +# Cloudflare Pages redirects +# https://developers.cloudflare.com/pages/configuration/redirects/ + +# devrail init — progressive adoption script +/init.sh https://raw.githubusercontent.com/devrail-dev/dev-toolchain/main/scripts/devrail-init.sh 302