diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3ba9c7b8..07d8d72c 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -10,6 +10,7 @@ **Target Runtimes**: Fish 3.6+, PowerShell 5.1+/7+, Bash, Chezmoi 2.69+ **Key Features**: + - Fish shell configuration (Linux/macOS/WSL) - PowerShell profiles (Windows) - Vim, Tmux, Git configurations @@ -293,10 +294,10 @@ PowerShell on Windows may load scripts without UTF-8 BOM encoding, causing multi | --------- | ----------- | | ✅ | `[OK]` | | ❌ | `[FAIL]` | -| ⚠️ | `[WARN]` | -| 🔍 🚀 📊 | `>>` | +| ⚠️ | `[WARN]` | +| 🔍 🚀 📊 | `>>` | | ━━━━━━ | `========` | -| ⏱️ | `[SKIP]` | +| ⏱️ | `[SKIP]` | **Emoji is fine in**: `.fish`, `.sh`, `.md`, and other UTF-8 native files. Only `.ps1` files are affected. diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 9bbfc454..181c89ec 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -1,3 +1,4 @@ +--- name: CI # PR-only (plus dispatch). Branch protection makes the merge commit @@ -5,7 +6,8 @@ name: CI # duplicate work. See DevSecNinja/.github docs/workflow-trigger-conventions.md. on: pull_request: - branches: [main] + branches: + - main workflow_dispatch: concurrency: @@ -113,7 +115,7 @@ jobs: - name: Set lowercase repository owner id: lowercase - run: echo "owner=$(echo '${{ github.repository_owner }}' | tr '[:upper:]' '[:lower:]')" >> $GITHUB_OUTPUT + run: echo "owner=$(echo '${{ github.repository_owner }}' | tr '[:upper:]' '[:lower:]')" >> "$GITHUB_OUTPUT" - name: Log in to GitHub Container Registry uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0 @@ -284,7 +286,10 @@ jobs: test-light-server: name: Test Light Server Installation runs-on: ubuntu-latest - needs: [validate, test-install, test-coder-install] + needs: + - validate + - test-install + - test-coder-install timeout-minutes: 20 permissions: contents: read @@ -313,7 +318,10 @@ jobs: test-dev-server: name: Test Dev Server Installation runs-on: ubuntu-latest - needs: [validate, test-install, test-coder-install] + needs: + - validate + - test-install + - test-coder-install timeout-minutes: 30 permissions: contents: read @@ -580,4 +588,4 @@ jobs: with: files: test-results.xml check_name: 'Pester Test Results' - comment_mode: off + comment_mode: 'off' diff --git a/.github/workflows/devcontainer-prebuild.yaml b/.github/workflows/devcontainer-prebuild.yaml index a3c0cde3..3dc8edaf 100644 --- a/.github/workflows/devcontainer-prebuild.yaml +++ b/.github/workflows/devcontainer-prebuild.yaml @@ -1,8 +1,10 @@ +--- name: Prebuild Devcontainer on: push: - branches: [main] + branches: + - main # Tag pushes (v*) build a release-pinned multi-arch manifest list tagged # as :vX.Y.Z, plus a build-provenance attestation for the manifest digest. # Source must be the tagged commit so the @@ -17,7 +19,8 @@ on: - 'script/devcontainer-image-size.sh' - '.github/workflows/devcontainer-prebuild.yaml' pull_request: - branches: [main] + branches: + - main paths: - '.devcontainer/**' - 'home/**' @@ -62,7 +65,7 @@ jobs: - name: Set lowercase repository owner id: lowercase - run: echo "owner=$(echo '${{ github.repository_owner }}' | tr '[:upper:]' '[:lower:]')" >> $GITHUB_OUTPUT + run: echo "owner=$(echo '${{ github.repository_owner }}' | tr '[:upper:]' '[:lower:]')" >> "$GITHUB_OUTPUT" - name: Log in to GitHub Container Registry uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0 @@ -199,7 +202,7 @@ jobs: - name: Set lowercase repository owner id: lowercase - run: echo "owner=$(echo '${{ github.repository_owner }}' | tr '[:upper:]' '[:lower:]')" >> $GITHUB_OUTPUT + run: echo "owner=$(echo '${{ github.repository_owner }}' | tr '[:upper:]' '[:lower:]')" >> "$GITHUB_OUTPUT" - name: Determine release context id: release diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e9231727..7c7f8be1 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,14 +1,17 @@ +--- name: Docs on: push: - branches: [main] + branches: + - main paths: - docs/** - mkdocs.yml - .github/workflows/docs.yml pull_request: - branches: [main] + branches: + - main paths: - docs/** - mkdocs.yml diff --git a/.github/workflows/mirror-base-image.yaml b/.github/workflows/mirror-base-image.yaml index 48cf6b2d..f462c880 100644 --- a/.github/workflows/mirror-base-image.yaml +++ b/.github/workflows/mirror-base-image.yaml @@ -32,7 +32,8 @@ on: workflow_dispatch: # Re-mirror immediately whenever Renovate bumps the pinned upstream digest. push: - branches: [main] + branches: + - main paths: - '.github/workflows/mirror-base-image.yaml' @@ -87,7 +88,7 @@ jobs: SOURCE: ${{ matrix.source }} MIRROR_REPO: ${{ matrix.mirror-repo }} TAG: ${{ matrix.tag }} - run: | + run: |- set -euo pipefail mirror="ghcr.io/${OWNER}/${MIRROR_REPO}" @@ -131,4 +132,3 @@ jobs: echo "- Source: \`${SOURCE}\`" echo "- Mirror: \`${mirror}:${TAG}@${ghcr_digest}\`" } >> "$GITHUB_STEP_SUMMARY" - diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 602028bd..1873e683 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -99,6 +99,9 @@ jobs: # CHANGELOG slice as plain markdown. gh release view "${TAG}" --repo "${REPO}" --json body --jq '.body' >/tmp/release-notes.md # Append the log.sh consumption + provenance verification block. + # The single-quoted printf lines print a shell snippet whose $tmp and + # $HOME must stay literal, so SC2016 doesn't apply. + # shellcheck disable=SC2016 { printf '\n\n---\n\n' printf '## log.sh distribution\n\n' diff --git a/.github/workflows/sign-powershell.yml b/.github/workflows/sign-powershell.yml index b7ba2ff7..877824b2 100644 --- a/.github/workflows/sign-powershell.yml +++ b/.github/workflows/sign-powershell.yml @@ -1,3 +1,4 @@ +--- name: Sign PowerShell Scripts on: @@ -6,7 +7,7 @@ on: - main paths: - '**.ps1' - - '!**.ps1.tmpl' # Exclude templates - they change after chezmoi processing + - '!**.ps1.tmpl' # Exclude templates - they change after chezmoi processing workflow_dispatch: concurrency: @@ -85,18 +86,6 @@ jobs: Merging this PR replaces the direct push the workflow used to perform, which is blocked by branch protection on `main`. - - name: Comment on PR - if: steps.check_changes.outputs.changes == 'true' && github.event_name == 'pull_request' - uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 - with: - script: | - github.rest.issues.createComment({ - issue_number: context.issue.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: '✅ PowerShell scripts have been signed. Please pull the latest changes after merge.' - }) - # --- Page on main-branch script-signing failure (homelab IRM pager) --- notify-irm: name: Notify Grafana IRM diff --git a/.github/workflows/sync-develop.yaml b/.github/workflows/sync-develop.yaml index 8e678d39..d10c82bf 100644 --- a/.github/workflows/sync-develop.yaml +++ b/.github/workflows/sync-develop.yaml @@ -68,6 +68,6 @@ jobs: - name: Report failure if: failure() - run: | + run: |- echo "❌ Failed to sync develop branch" echo "May require manual intervention if there are merge conflicts" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fc7943ba..f328b98d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,6 +55,7 @@ vim dot_config/fish/functions/mynewfunction.fish ### Testing Changes The CI pipeline runs automatically on push and will: + - 🎯 Run lefthook hooks (formatting, linting) - ✅ Validate all shell script syntax - ✅ Check Fish configuration files diff --git a/README.md b/README.md index 0ac11a13..ee7f94e6 100644 --- a/README.md +++ b/README.md @@ -24,12 +24,14 @@ Modern dotfiles repository managed with [Chezmoi](https://chezmoi.io/), featurin The dotfiles repository provides several variables that can be used in templates and scripts: ### User Information + - `firstname` / `lastname` / `name` - Your name (prompted on first run) - `username` - System username (prompted on first run) - `email` - Your email address (prompted on first run) - `githubUsername` - Your GitHub username (auto-detected from email or git remote) ### Environment Detection + - `codespaces` - Running in GitHub Codespaces (`true`/`false`) - `devcontainer` - Running in a dev container (`true`/`false`) - `wsl` - Running in Windows Subsystem for Linux (`true`/`false`) @@ -37,6 +39,7 @@ The dotfiles repository provides several variables that can be used in templates - `installType` - Installation mode (`light` or `full`) ### Windows Enterprise (Windows and WSL) + - `isEntraIDJoined` - Device is Entra ID (Azure AD) joined (`true`/`false`) - `isIntuneJoined` - Device is Intune (MDM) enrolled (`true`/`false`) - `isEntraRegistered` - Device is Entra ID registered/workplace joined (`true`/`false`) @@ -46,6 +49,7 @@ The dotfiles repository provides several variables that can be used in templates - `isWork` - Device is joined to a `*Microsoft` tenant (`true`/`false`) These variables are automatically exposed as environment variables in your shell: + - **PowerShell**: `$env:CHEZMOI_*` (e.g., `$env:CHEZMOI_IS_ENTRA_ID_JOINED`, `$env:CHEZMOI_ENTRA_ID_TENANT_NAME`) - **Bash/Zsh**: `$CHEZMOI_*` (e.g., `$CHEZMOI_IS_ENTRA_ID_JOINED`, `$CHEZMOI_ENTRA_ID_TENANT_NAME`) - **Fish**: `$CHEZMOI_*` (e.g., `$CHEZMOI_IS_ENTRA_ID_JOINED`, `$CHEZMOI_ENTRA_ID_TENANT_NAME`) @@ -187,6 +191,7 @@ For more information, see the [Coder Dotfiles Documentation](https://coder.com/d This repository includes a complete [DevContainer](https://containers.dev/) configuration for Visual Studio Code and GitHub Codespaces. The devcontainer provides a fully configured development environment with: **Pre-installed Features:** + - 🍺 Homebrew package manager - 📦 Git LFS (Large File Storage) - 💻 PowerShell with Pester testing framework @@ -194,12 +199,14 @@ This repository includes a complete [DevContainer](https://containers.dev/) conf - 🐙 GitHub CLI **Automatic Setup:** + - ✅ Dotfiles automatically installed via `postCreateCommand` - ✅ Fish shell configured as default terminal - ✅ All configurations applied and verified - ✅ VSCode extensions pre-installed (GitHub Copilot, Pester) **Prebuilt Images:** + - 🚀 Prebuilt devcontainer images are automatically built and published to GitHub Container Registry - 🏗️ Images are rebuilt weekly and on every devcontainer configuration change - ⚡ CI workflows use prebuilt images for faster test execution @@ -253,10 +260,12 @@ The CI pipeline automatically tests the complete devcontainer deployment, includ ### Personal Information On first run, Chezmoi will prompt for: + - **Name**: Used in Git commits - **Email**: Used in Git commits To re-enter this information: + ```bash chezmoi init --data=false ``` @@ -302,6 +311,7 @@ lefthook run pre-commit --all-files ``` Hooks will automatically run on `git commit`. The checks include: + - 🐚 Shell script linting (shellcheck) - 🎨 Shell script formatting (shfmt) - 🔧 Executable bit enforcement on shell scripts @@ -378,11 +388,13 @@ On Windows, Microsoft Surface Laptop models always have the hardware power button set to **Do nothing** for both AC and battery power. The mode is auto-detected based on: + - Hostname patterns (SVLDEV* = full, SVL* = light) - Environment (codespaces, devcontainer, CI = light) - Default = full mode To change modes: + ```bash chezmoi init --data=false ``` diff --git a/STRUCTURE.md b/STRUCTURE.md index 1f789706..2eb6b4c7 100644 --- a/STRUCTURE.md +++ b/STRUCTURE.md @@ -6,15 +6,15 @@ Quick reference guide for the dotfiles repository structure and Chezmoi naming c Chezmoi uses special prefixes in filenames to determine how files are managed: -| Prefix | Target | Example | -|--------|--------|---------| -| `dot_` | `.` (hidden file) | `dot_vimrc` → `~/.vimrc` | -| `private_` | File with 0600 permissions | `private_ssh_config` | -| `executable_` | File with +x permissions | `executable_script.sh` | -| `run_once_` | Script that runs once | `run_once_install.sh` | -| `run_onchange_` | Script that runs on change | `run_onchange_update.sh` | -| `run_` | Script that runs every apply | `run_backup.sh` | -| `.tmpl` | Template file | `config.tmpl` (processes Chezmoi templates) | +| Prefix | Target | Example | +| --------------- | ---------------------------- | ------------------------------------------- | +| `dot_` | `.` (hidden file) | `dot_vimrc` → `~/.vimrc` | +| `private_` | File with 0600 permissions | `private_ssh_config` | +| `executable_` | File with +x permissions | `executable_script.sh` | +| `run_once_` | Script that runs once | `run_once_install.sh` | +| `run_onchange_` | Script that runs on change | `run_onchange_update.sh` | +| `run_` | Script that runs every apply | `run_backup.sh` | +| `.tmpl` | Template file | `config.tmpl` (processes Chezmoi templates) | ## 📁 Directory Structure @@ -121,6 +121,7 @@ chezmoi add --template ~/.local/bin/script.sh ### Script Execution Order Scripts run in this order: + 1. `run_once_before_*` - Before applying dotfiles (runs once) 2. Apply dotfiles 3. `run_once_after_*` - After applying dotfiles (runs once) @@ -136,16 +137,16 @@ Numerical prefixes ensure order: `00-`, `01-`, `02-`, etc. Each package manager in `home/.chezmoidata/packages.yaml` supports an `uninstall` list alongside its installation lists: -| Configuration key | Uninstall entries | -| --- | --- | -| `packages.windows.winget.uninstall` | Exact WinGet IDs, e.g. `Vendor.Application` | -| `packages.windows.powershell_modules.uninstall` | PowerShellGet module names | -| `packages.linux.apt.uninstall` | APT names, optionally `name:architecture` | -| `packages.linux.dnf.uninstall` | RPM package names | -| `packages.linux.brew.uninstall` | Homebrew formula names | -| `packages.darwin.brew.formulas.uninstall` | Homebrew formula names | -| `packages.darwin.brew.cask.uninstall` | Homebrew cask names | -| `packages.darwin.brew.app-store.uninstall` | `{name, id}` entries, like the installation lists | +| Configuration key | Uninstall entries | +| ----------------------------------------------- | ------------------------------------------------- | +| `packages.windows.winget.uninstall` | Exact WinGet IDs, e.g. `Vendor.Application` | +| `packages.windows.powershell_modules.uninstall` | PowerShellGet module names | +| `packages.linux.apt.uninstall` | APT names, optionally `name:architecture` | +| `packages.linux.dnf.uninstall` | RPM package names | +| `packages.linux.brew.uninstall` | Homebrew formula names | +| `packages.darwin.brew.formulas.uninstall` | Homebrew formula names | +| `packages.darwin.brew.cask.uninstall` | Homebrew cask names | +| `packages.darwin.brew.app-store.uninstall` | `{name, id}` entries, like the installation lists | These lists apply in **both light and full modes**, regardless of `useYubiKey`. Move retired entries out of `light`, `full`, and `yubikey` before listing them @@ -284,23 +285,23 @@ chezmoi init --data=false ### Unix/Linux/macOS/WSL -| Source File | Target Location | -|-------------|----------------| -| `dot_vimrc` | `~/.vimrc` | -| `dot_tmux.conf` | `~/.tmux.conf` | +| Source File | Target Location | +| ----------------------------- | ---------------------------- | +| `dot_vimrc` | `~/.vimrc` | +| `dot_tmux.conf` | `~/.tmux.conf` | | `dot_config/fish/config.fish` | `~/.config/fish/config.fish` | -| `dot_config/git/config.tmpl` | `~/.config/git/config` | -| `run_once_*.sh.tmpl` | Executed once, not copied | +| `dot_config/git/config.tmpl` | `~/.config/git/config` | +| `run_once_*.sh.tmpl` | Executed once, not copied | ### Windows -| Source File | Target Location | -|-------------|----------------| +| Source File | Target Location | +| ----------------------------------- | ---------------------------------- | | `dot_config/powershell/profile.ps1` | `~/.config/powershell/profile.ps1` | | `dot_config/powershell/aliases.ps1` | `~/.config/powershell/aliases.ps1` | -| `dot_config/git/config.tmpl` | `~/.config/git/config` | -| `AppData/.../settings.json` | `%LOCALAPPDATA%/.../settings.json` | -| `run_once_*.ps1.tmpl` | Executed once, not copied | +| `dot_config/git/config.tmpl` | `~/.config/git/config` | +| `AppData/.../settings.json` | `%LOCALAPPDATA%/.../settings.json` | +| `run_once_*.ps1.tmpl` | Executed once, not copied | **Note**: Platform-specific files are filtered via `.chezmoiignore` (supports templates natively). diff --git a/Taskfile.yml b/Taskfile.yml index 27d5849f..84458dac 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -1,3 +1,4 @@ +--- # Taskfile for dotfiles repository # https://taskfile.dev version: '3' @@ -254,7 +255,7 @@ tasks: info:packages: desc: Show packages that would be installed cmds: - - | + - |- echo "📦 Package Information" echo "=====================" if command -v yq >/dev/null 2>&1; then diff --git a/cloud-init/server/nic-config.yml b/cloud-init/server/nic-config.yml index 0f00f6f0..e86189ab 100644 --- a/cloud-init/server/nic-config.yml +++ b/cloud-init/server/nic-config.yml @@ -1,13 +1,14 @@ +--- # This file is generated from information provided by the datasource. Changes # to it will not persist across an instance reboot. To disable cloud-init's # network configuration capabilities, write a file # /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg with the following: # network: {config: disabled} network: - version: 2 - ethernets: - nic0: - match: - name: en* - dhcp4: true - set-name: eth0 + version: 2 + ethernets: + nic0: + match: + name: en* + dhcp4: true + set-name: eth0 diff --git a/cloud-init/server/user-data.yml b/cloud-init/server/user-data.yml index 976750ae..c80a3971 100644 --- a/cloud-init/server/user-data.yml +++ b/cloud-init/server/user-data.yml @@ -1,4 +1,5 @@ #cloud-config +# !yamlfmt!:ignore # To generate seed, run: cloud-localds --hostname <> --verbose cloud-init-seed-<>.qcow2 user-data.yml # Disable password authentication with the SSH daemon @@ -34,21 +35,21 @@ packages: # Create files write_files: -- path: /etc/netplan/50-cloud-init.yaml - content: | - # This file is generated from information provided by the datasource. Changes - # to it will not persist across an instance reboot. To disable cloud-init's - # network configuration capabilities, write a file - # /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg with the following: - # network: {config: disabled} - network: - version: 2 - ethernets: - eth0: - dhcp4: true - set-name: eth0 - owner: "root:root" - permissions: "0644" + - path: /etc/netplan/50-cloud-init.yaml + content: | + # This file is generated from information provided by the datasource. Changes + # to it will not persist across an instance reboot. To disable cloud-init's + # network configuration capabilities, write a file + # /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg with the following: + # network: {config: disabled} + network: + version: 2 + ethernets: + eth0: + dhcp4: true + set-name: eth0 + owner: "root:root" + permissions: "0644" # Enable firewall and allow SSH runcmd: diff --git a/docs/1password-shell-plugins.md b/docs/1password-shell-plugins.md index 512bef6d..13c23bbf 100644 --- a/docs/1password-shell-plugins.md +++ b/docs/1password-shell-plugins.md @@ -14,11 +14,11 @@ version control, so a new machine silently loses the configuration. 1Password documents an alternative: [define the wrapper functions yourself and track them in your dotfiles][opdotfiles]. That is what this repo does. -| | `op plugin init` default | This repo | -| --- | --- | --- | -| Wrapper location | `~/.config/op/plugins.sh` | `~/.config/shell/functions/op-plugins.sh`, `~/.config/fish/conf.d/op-plugins.fish` | -| Tracked in git | ❌ | ✅ (generated from chezmoi templates) | -| New machine | re-run `op plugin init` per CLI | wrappers apply with `chezmoi apply` | +| | `op plugin init` default | This repo | +| ---------------- | ------------------------------- | ---------------------------------------------------------------------------------- | +| Wrapper location | `~/.config/op/plugins.sh` | `~/.config/shell/functions/op-plugins.sh`, `~/.config/fish/conf.d/op-plugins.fish` | +| Tracked in git | ❌ | ✅ (generated from chezmoi templates) | +| New machine | re-run `op plugin init` per CLI | wrappers apply with `chezmoi apply` | `OP_PLUGIN_ALIASES_SOURCED=1` is exported alongside the wrappers, which tells 1Password CLI the aliases are already set up so it stops asking you to source @@ -54,8 +54,8 @@ CLIs. ## First-time setup per CLI -The wrappers only decide *how* a CLI is invoked. You still tell 1Password -*which* item holds the credential, once per CLI and machine: +The wrappers only decide _how_ a CLI is invoked. You still tell 1Password +_which_ item holds the credential, once per CLI and machine: ```bash op signin @@ -79,7 +79,7 @@ still lying around (for example `~/.config/gh/hosts.yml`). ## Safety rails The generated wrappers are deliberately defensive, because a wrapper that -cannot run would otherwise *replace* a working CLI: +cannot run would otherwise _replace_ a working CLI: - **No `op`, no wrappers.** If the 1Password CLI is not on `PATH`, nothing is defined at all and every CLI behaves normally. @@ -88,7 +88,7 @@ cannot run would otherwise *replace* a working CLI: "is it installed?" checks, so each wrapper is guarded on the real CLI existing. - **Completions keep working.** The fish wrappers use `--wraps`, and the - bash/zsh completion files load *before* the wrappers, so generating + bash/zsh completion files load _before_ the wrappers, so generating completions never triggers a 1Password prompt at shell startup. - **Not in SSH sessions.** `op plugin run` needs the 1Password desktop app for biometric unlock, which a headless host does not have. The wrappers are @@ -109,8 +109,8 @@ the plugin still authenticates you with biometrics. ## WSL is not supported -`op plugin run` refuses to run under WSL — you get *"Shell Plugins are -currently not supported on this operating system"* (tracked upstream in +`op plugin run` refuses to run under WSL — you get _"Shell Plugins are +currently not supported on this operating system"_ (tracked upstream in [1Password/shell-plugins#402][issue402]). Wrapping a CLI with a command that always fails is worse than not wrapping it, so chezmoi skips both wrapper files on WSL hosts via `.chezmoiignore`. diff --git a/docs/chezmoi-variables.md b/docs/chezmoi-variables.md index 238c1966..3ba71fab 100644 --- a/docs/chezmoi-variables.md +++ b/docs/chezmoi-variables.md @@ -67,7 +67,7 @@ templates and scripts. already published at — so they are safe to ship in the repo. Override it per-machine by setting `gitSigningKey` in your local chezmoi config to your own key — copy it from the 1Password app, - *item → ⋮ → Configure Commit Signing → Copy Snippet*. An empty value falls + _item → ⋮ → Configure Commit Signing → Copy Snippet_. An empty value falls back to the work/personal default, as does a value that still equals one of the shipped defaults (so a config written by an earlier `chezmoi init` never pins the wrong one). Ignored when `useYubiKey` is `true`, since diff --git a/docs/contributing.md b/docs/contributing.md index 2f98f303..4f9639a3 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -9,23 +9,23 @@ the key workflows. 1. **Edit files in the repository** (not in your home directory): - ```bash - cd /path/to/dotfiles - vim home/dot_config/fish/config.fish - ``` + ```bash + cd /path/to/dotfiles + vim home/dot_config/fish/config.fish + ``` 2. **Test your changes** with a dry run, then apply locally: - ```bash - chezmoi apply --dry-run --source=. - chezmoi apply --source=. - ``` + ```bash + chezmoi apply --dry-run --source=. + chezmoi apply --source=. + ``` 3. **Verify everything still works**: - ```bash - chezmoi verify - ``` + ```bash + chezmoi verify + ``` ## Validate Before Committing diff --git a/docs/copilot-cli.md b/docs/copilot-cli.md index 20843bbc..570ff9b9 100644 --- a/docs/copilot-cli.md +++ b/docs/copilot-cli.md @@ -136,17 +136,17 @@ groups) are listed and the helper refuses to guess. Environment variables: -| Variable | Default | Effect | -| ------------------------------- | ------- | ----------------------------------------------- | -| `COPILOT_SSH_SKIP_PREFLIGHT` | unset | `1` skips the reachability check entirely | -| `COPILOT_SSH_PREFLIGHT_TIMEOUT` | `3` | TCP probe timeout in seconds | -| `COPILOT_SSH_START_TIMEOUT` | `180` | How long to wait for SSH after `az vm start` | -| `COPILOT_SSH_ASSUME_YES` | unset | `1` auto-confirms starting a stopped VM | -| `COPILOT_SSH_ASSUME_NO` | unset | `1` never starts a VM, even on a TTY | +| Variable | Default | Effect | +| ------------------------------- | ------- | -------------------------------------------- | +| `COPILOT_SSH_SKIP_PREFLIGHT` | unset | `1` skips the reachability check entirely | +| `COPILOT_SSH_PREFLIGHT_TIMEOUT` | `3` | TCP probe timeout in seconds | +| `COPILOT_SSH_START_TIMEOUT` | `180` | How long to wait for SSH after `az vm start` | +| `COPILOT_SSH_ASSUME_YES` | unset | `1` auto-confirms starting a stopped VM | +| `COPILOT_SSH_ASSUME_NO` | unset | `1` never starts a VM, even on a TTY | ## Local authentication with the 1Password shell plugin -`copilot-ssh` solves the *remote* case: forwarding a token to a headless +`copilot-ssh` solves the _remote_ case: forwarding a token to a headless server. On your **workstation** you don't need to forward anything — the [1Password Copilot shell plugin][opcopilot] authenticates the local `copilot` command with biometrics, injecting the same `COPILOT_GITHUB_TOKEN` for the @@ -156,10 +156,10 @@ This repo wraps `copilot` (and `gh`) automatically; see [1password-shell-plugins.md](1password-shell-plugins.md). The two mechanisms are complementary and use the same variable name: -| Where | Mechanism | Token source | -| --- | --- | --- | -| Workstation | `op plugin run -- copilot` | 1Password item, per command | -| Headless server | `copilot-ssh` + SSH `SendEnv` | 1Password Environment | +| Where | Mechanism | Token source | +| --------------- | ----------------------------- | --------------------------- | +| Workstation | `op plugin run -- copilot` | 1Password item, per command | +| Headless server | `copilot-ssh` + SSH `SendEnv` | 1Password Environment | Note that the plugin wrappers are not applied on WSL, where shell plugins are unsupported — `copilot-ssh` still works there. @@ -172,10 +172,10 @@ for biometric unlock, which a headless server does not have, so a wrapper on the far side of `copilot-ssh` would replace a working CLI with one that always fails — exactly the situation `copilot-ssh` exists to avoid. -| Session | `copilot` resolves to | Credential | -| --- | --- | --- | -| Local workstation | `op plugin run -- copilot` | 1Password, per command | -| Inside `copilot-ssh` | the real `copilot` binary | forwarded `COPILOT_GITHUB_TOKEN` | +| Session | `copilot` resolves to | Credential | +| -------------------- | -------------------------- | -------------------------------- | +| Local workstation | `op plugin run -- copilot` | 1Password, per command | +| Inside `copilot-ssh` | the real `copilot` binary | forwarded `COPILOT_GITHUB_TOKEN` | In practice the remote host usually has no `op` installed either, which is a second, independent guard. The same reasoning applies to `gh` and `GH_TOKEN`. diff --git a/docs/customization.md b/docs/customization.md index bce78ea2..bdf11948 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -180,10 +180,10 @@ Instead the numbers come from a small cache that is refreshed in the background: the banner shows the previous result instantly while a fresh one is computed for the next login. -| Platform | Cache | Filled by | -| ----------- | -------------------------------------- | ------------------------------------------------------------------------ | -| Linux/macOS | `~/.cache/fastfetch-status/` | `~/.config/fastfetch/status.sh`, which self-spawns its own refresh | -| Windows | `%LOCALAPPDATA%\fastfetch-status\` | `~/.config/fastfetch/status.ps1`, spawned detached by the PowerShell profile | +| Platform | Cache | Filled by | +| ----------- | ---------------------------------- | ---------------------------------------------------------------------------- | +| Linux/macOS | `~/.cache/fastfetch-status/` | `~/.config/fastfetch/status.sh`, which self-spawns its own refresh | +| Windows | `%LOCALAPPDATA%\fastfetch-status\` | `~/.config/fastfetch/status.ps1`, spawned detached by the PowerShell profile | On Windows fastfetch reads the cache with `cmd /c type` rather than starting PowerShell, which keeps the line free (a few milliseconds). @@ -204,12 +204,12 @@ Refresh by hand — useful right after installing updates: ~/.config/fastfetch/status.ps1 refresh # Windows ``` -| Variable | Effect | -| ---------------------------- | ------------------------------------------------------------ | -| `FASTFETCH_STATUS_TTL` | Cache lifetime in seconds (default 3600) | -| `FASTFETCH_STATUS_DISABLE=1` | Print no status lines at all | -| `FASTFETCH_STATUS_CACHE_DIR` | Override the cache directory (Windows; testing) | -| `ANSIBLE_PULL_WORKDIR` | ansible-pull checkout (default `/var/lib/ansible/local`) | +| Variable | Effect | +| ---------------------------- | -------------------------------------------------------- | +| `FASTFETCH_STATUS_TTL` | Cache lifetime in seconds (default 3600) | +| `FASTFETCH_STATUS_DISABLE=1` | Print no status lines at all | +| `FASTFETCH_STATUS_CACHE_DIR` | Override the cache directory (Windows; testing) | +| `ANSIBLE_PULL_WORKDIR` | ansible-pull checkout (default `/var/lib/ansible/local`) | ### A quiet PowerShell startup @@ -244,11 +244,11 @@ present, so a fresh machine with a Dev Drive gets `D:\projects` instead of `%USERPROFILE%\projects`. !!! note "How the Dev Drive is detected" - `fsutil devdrv query` is the authoritative check, but it needs an elevated - shell — unusable from a profile. Fixed, ready ReFS volumes are used as the - heuristic instead. If that guesses wrong (a plain ReFS data volume, or - several Dev Drives), pin the right one with `$env:DEV_DRIVE`, or skip - detection entirely with `$env:PROJECTS_PATH`. +`fsutil devdrv query` is the authoritative check, but it needs an elevated +shell — unusable from a profile. Fixed, ready ReFS volumes are used as the +heuristic instead. If that guesses wrong (a plain ReFS data volume, or +several Dev Drives), pin the right one with `$env:DEV_DRIVE`, or skip +detection entirely with `$env:PROJECTS_PATH`. The Linux/macOS shell configs (`fish`, `bash`, `zsh`) always use `$HOME/projects`; Dev Drive is a Windows-only feature. @@ -265,20 +265,20 @@ when OneDrive is configured. On Windows, `run_onchange_40-set-current-user-personalization.ps1` applies the opinionated settings below to the invoking user's profile without elevation: -| Preference | Applied value | Evidence/source | Normal alternative or reversal | -| ---------- | ------------- | --------------- | ------------------------------ | -| App and Windows theme | Dark (`AppsUseLightTheme=0`, `SystemUsesLightTheme=0`) | Grade 3: related [Microsoft theme guidance](https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/apply-windows-themes), but the registry mappings are community-documented | Choose Light in Settings > Personalization > Colors, delete the values, or set both to `1` | -| Lock-screen Spotlight overlays | Off (`RotatingLockScreenOverlayEnabled=0`) | Grade 3: [Microsoft Community mapping](https://learn.microsoft.com/en-us/answers/questions/1326668/how-to-disable-windows-spotlight-via-registry) | Re-enable lock-screen tips, delete the value, or set it to `1` | -| Task View button | Hidden (`ShowTaskViewButton=0`) | Grade 1: [Windows 11 settings reference](https://learn.microsoft.com/en-us/windows/apps/develop/settings/settings-windows-11) | Enable Task view in taskbar settings, delete the value, or set it to `1` | -| Taskbar search | Hidden (`SearchboxTaskbarMode=0`) | Grade 2: modes correspond to the [Windows 11 settings reference](https://learn.microsoft.com/en-us/windows/apps/develop/settings/settings-windows-11), but this value is not a documented policy | Select Search box in taskbar settings, delete the value, or set it to `3` | -| Taskbar battery percentage | Shown (`IsBatteryPercentageEnabled=1`) | Grade 3: [community-documented Windows 11 preference](https://www.elevenforum.com/t/enable-or-disable-show-battery-percentage-on-taskbar-in-windows-11.32691/) | Turn off Battery percentage in Settings > System > Power & battery, delete the value, or set it to `0` | -| File-name extensions | Shown (`HideFileExt=0`) | Grade 3: exact registry mapping is unverified | Clear File Explorer's File name extensions option, delete the value, or set it to `1` | -| Hidden files and folders | Shown (`Hidden=1`) | Grade 3: exact registry mapping is unverified | Clear File Explorer's Hidden items option, delete the value, or set it to `2` | -| Desktop background | Windows Spotlight (`BackgroundType=3`) | Grade 3: Spotlight is documented in the [settings reference](https://learn.microsoft.com/en-us/windows/apps/develop/settings/settings-windows-11), but the registry mirror is best-effort | Choose another background, delete the value, or set image mode (`1`) | -| Regional format | Dutch (Netherlands), `nl-NL` | Grade 1: [`Set-Culture`](https://learn.microsoft.com/en-us/powershell/module/international/set-culture) | Select another regional format or run `Set-Culture -CultureInfo en-US` | -| Home location | Netherlands, GeoID `176` | Grade 1: [`Set-WinHomeLocation`](https://learn.microsoft.com/en-us/powershell/module/international/set-winhomelocation) | Select another country or run `Set-WinHomeLocation -GeoId 244` for the US | -| Languages and keyboards | `en-US`, then `nl-NL`; both US-International (`00020409`) | Grade 1: [`Set-WinUserLanguageList`](https://learn.microsoft.com/en-us/powershell/module/international/set-winuserlanguagelist) | Edit Language & region settings or run `Set-WinUserLanguageList en-US -Force` | -| Number and CSV separators | Decimal `.`, thousands `,`, list `,` | Grade 2: [Windows locale constants](https://learn.microsoft.com/en-us/windows/win32/intl/locale-custom-constants) document the fields; registry behavior is vendor-observed | Restore Dutch defaults: decimal `,`, thousands `.`, list `;` | +| Preference | Applied value | Evidence/source | Normal alternative or reversal | +| ------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | +| App and Windows theme | Dark (`AppsUseLightTheme=0`, `SystemUsesLightTheme=0`) | Grade 3: related [Microsoft theme guidance](https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/apply-windows-themes), but the registry mappings are community-documented | Choose Light in Settings > Personalization > Colors, delete the values, or set both to `1` | +| Lock-screen Spotlight overlays | Off (`RotatingLockScreenOverlayEnabled=0`) | Grade 3: [Microsoft Community mapping](https://learn.microsoft.com/en-us/answers/questions/1326668/how-to-disable-windows-spotlight-via-registry) | Re-enable lock-screen tips, delete the value, or set it to `1` | +| Task View button | Hidden (`ShowTaskViewButton=0`) | Grade 1: [Windows 11 settings reference](https://learn.microsoft.com/en-us/windows/apps/develop/settings/settings-windows-11) | Enable Task view in taskbar settings, delete the value, or set it to `1` | +| Taskbar search | Hidden (`SearchboxTaskbarMode=0`) | Grade 2: modes correspond to the [Windows 11 settings reference](https://learn.microsoft.com/en-us/windows/apps/develop/settings/settings-windows-11), but this value is not a documented policy | Select Search box in taskbar settings, delete the value, or set it to `3` | +| Taskbar battery percentage | Shown (`IsBatteryPercentageEnabled=1`) | Grade 3: [community-documented Windows 11 preference](https://www.elevenforum.com/t/enable-or-disable-show-battery-percentage-on-taskbar-in-windows-11.32691/) | Turn off Battery percentage in Settings > System > Power & battery, delete the value, or set it to `0` | +| File-name extensions | Shown (`HideFileExt=0`) | Grade 3: exact registry mapping is unverified | Clear File Explorer's File name extensions option, delete the value, or set it to `1` | +| Hidden files and folders | Shown (`Hidden=1`) | Grade 3: exact registry mapping is unverified | Clear File Explorer's Hidden items option, delete the value, or set it to `2` | +| Desktop background | Windows Spotlight (`BackgroundType=3`) | Grade 3: Spotlight is documented in the [settings reference](https://learn.microsoft.com/en-us/windows/apps/develop/settings/settings-windows-11), but the registry mirror is best-effort | Choose another background, delete the value, or set image mode (`1`) | +| Regional format | Dutch (Netherlands), `nl-NL` | Grade 1: [`Set-Culture`](https://learn.microsoft.com/en-us/powershell/module/international/set-culture) | Select another regional format or run `Set-Culture -CultureInfo en-US` | +| Home location | Netherlands, GeoID `176` | Grade 1: [`Set-WinHomeLocation`](https://learn.microsoft.com/en-us/powershell/module/international/set-winhomelocation) | Select another country or run `Set-WinHomeLocation -GeoId 244` for the US | +| Languages and keyboards | `en-US`, then `nl-NL`; both US-International (`00020409`) | Grade 1: [`Set-WinUserLanguageList`](https://learn.microsoft.com/en-us/powershell/module/international/set-winuserlanguagelist) | Edit Language & region settings or run `Set-WinUserLanguageList en-US -Force` | +| Number and CSV separators | Decimal `.`, thousands `,`, list `,` | Grade 2: [Windows locale constants](https://learn.microsoft.com/en-us/windows/win32/intl/locale-custom-constants) document the fields; registry behavior is vendor-observed | Restore Dutch defaults: decimal `,`, thousands `.`, list `;` | The script checks exact desired state before every change and preserves unrelated registry values. It intentionally replaces the input-language list @@ -308,10 +308,10 @@ script to use a different intensity. Night Light has no supported configuration API. Windows persists it as two `REG_BINARY` CloudStore values under `HKEY_CURRENT_USER`: -| Value | Contents | -| ----- | -------- | -| `...\default$windows.data.bluelightreduction.settings\windows.data.bluelightreduction.settings` | Schedule mode, colour temperature, schedule times, cached sunset/sunrise times | -| `...\default$windows.data.bluelightreduction.bluelightreductionstate\windows.data.bluelightreduction.bluelightreductionstate` | Whether Night Light is currently on | +| Value | Contents | +| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| `...\default$windows.data.bluelightreduction.settings\windows.data.bluelightreduction.settings` | Schedule mode, colour temperature, schedule times, cached sunset/sunrise times | +| `...\default$windows.data.bluelightreduction.bluelightreductionstate\windows.data.bluelightreduction.bluelightreductionstate` | Whether Night Light is currently on | Both are [Microsoft Bond CompactBinary v1][bond] payloads inside a CloudStore envelope. The script implements just enough of that codec to decode the diff --git a/docs/git-signing.md b/docs/git-signing.md index ecabd635..eb3eee42 100644 --- a/docs/git-signing.md +++ b/docs/git-signing.md @@ -14,10 +14,10 @@ The repository owner's public keys ship as the defaults for `gitSigningKey`, so signing switches itself on as soon as a 1Password signer binary is present — nothing to configure. Which default applies depends on the machine: -| Machine | Default key | -| --- | --- | -| Entra ID tenant ending in `Microsoft` (`isWork = true`) | work key | -| Everything else | personal key ([published][keys]) | +| Machine | Default key | +| ------------------------------------------------------- | -------------------------------- | +| Entra ID tenant ending in `Microsoft` (`isWork = true`) | work key | +| Everything else | personal key ([published][keys]) | [keys]: https://github.com/DevSecNinja.keys @@ -63,8 +63,8 @@ gives it — with or without a trailing comment. Holding the right key is not enough: the 1Password SSH agent only offers keys from the vaults listed in its config, so the signer can hold a perfectly good -key and still fail with *"No SSH private key found for the specified public -key"*. +key and still fail with _"No SSH private key found for the specified public +key"_. On Windows that config is managed by this repo at `%LOCALAPPDATA%\1Password\config\ssh\agent.toml`, rendered from the @@ -73,7 +73,7 @@ elsewhere. WSL benefits too, since it reaches the same Windows agent (see [wsl.md](wsl.md)). Watch out for a bare `ssh-keys = []`, which 1Password writes on a fresh -install. That is an explicit *empty* list, not "the default set", so the agent +install. That is an explicit _empty_ list, not "the default set", so the agent offers nothing at all and `ssh-add -l` reports no identities. Adding at least one `[[ssh-keys]]` entry is what fixes it. @@ -89,12 +89,12 @@ data: 1Password ships a different binary per platform, and the repo auto-detects the right one: -| Platform | Binary | Auto-detected from | -| --- | --- | --- | -| WSL | `op-ssh-sign-wsl.exe` | Current Windows user's `%LOCALAPPDATA%\Microsoft\WindowsApps\`, then the pre-8.11.18 `…\1Password\app\8\` | -| Native Windows | `op-ssh-sign.exe` | `%LOCALAPPDATA%\Microsoft\WindowsApps\`, then `%LOCALAPPDATA%\1Password\app\8\` | -| macOS | `op-ssh-sign` | `/Applications/1Password.app/Contents/MacOS/` | -| Linux | — | no standard path; set it explicitly | +| Platform | Binary | Auto-detected from | +| -------------- | --------------------- | --------------------------------------------------------------------------------------------------------- | +| WSL | `op-ssh-sign-wsl.exe` | Current Windows user's `%LOCALAPPDATA%\Microsoft\WindowsApps\`, then the pre-8.11.18 `…\1Password\app\8\` | +| Native Windows | `op-ssh-sign.exe` | `%LOCALAPPDATA%\Microsoft\WindowsApps\`, then `%LOCALAPPDATA%\1Password\app\8\` | +| macOS | `op-ssh-sign` | `/Applications/1Password.app/Contents/MacOS/` | +| Linux | — | no standard path; set it explicitly | Paths are emitted with forward slashes, because git config treats a backslash as an escape character. That is also the form 1Password's own snippet uses. @@ -129,8 +129,8 @@ git log --show-signature -1 A good signature shows `Good "git" signature`. In WSL the approval prompt appears on the Windows host — see [wsl.md](wsl.md). -If signing fails with *"No SSH private key found for the specified public -key"*, check what the agent is actually offering: +If signing fails with _"No SSH private key found for the specified public +key"_, check what the agent is actually offering: ```bash ssh-add -l diff --git a/docs/github-repo-config.md b/docs/github-repo-config.md index a8f7fa7c..d1e94cc2 100644 --- a/docs/github-repo-config.md +++ b/docs/github-repo-config.md @@ -6,11 +6,11 @@ drift apart across dozens of repos. Four functions in the `DotfilesHelpers` module: -| Function | Purpose | -| ------------------------- | ----------------------------------------------------------------- | -| `Get-GitHubRepoBaseline` | The desired state — a single, editable source of truth | -| `Get-GitHubRepoConfig` | Read-only audit of one, several or all repositories | -| `Set-GitHubRepoConfig` | Remediation, with `-WhatIf` dry runs | +| Function | Purpose | +| ------------------------- | ---------------------------------------------------------------- | +| `Get-GitHubRepoBaseline` | The desired state — a single, editable source of truth | +| `Get-GitHubRepoConfig` | Read-only audit of one, several or all repositories | +| `Set-GitHubRepoConfig` | Remediation, with `-WhatIf` dry runs | | `Get-GitHubAppCredential` | Reads a GitHub App ID and private key from 1Password or PEM file | ## Requirements diff --git a/docs/installation.md b/docs/installation.md index 4c7dcae9..7effe8c2 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -36,76 +36,76 @@ the dotfiles. 1. **Install Git and chezmoi, then open a _new_ terminal.** - ```powershell - winget install Git.Git twpayne.chezmoi - ``` + ```powershell + winget install Git.Git twpayne.chezmoi + ``` - winget updates the `PATH` environment variable, but the change only applies - to **newly started** shells. Close the current PowerShell window and open a - fresh one before continuing, otherwise `git` and `chezmoi` are reported as - "not recognized". + winget updates the `PATH` environment variable, but the change only applies + to **newly started** shells. Close the current PowerShell window and open a + fresh one before continuing, otherwise `git` and `chezmoi` are reported as + "not recognized". 2. **Allow local scripts to run.** Windows PowerShell blocks scripts by - default (`running scripts is disabled on this system`). Set a policy that - permits local scripts: + default (`running scripts is disabled on this system`). Set a policy that + permits local scripts: - ```powershell - Set-ExecutionPolicy RemoteSigned -Scope CurrentUser - ``` + ```powershell + Set-ExecutionPolicy RemoteSigned -Scope CurrentUser + ``` - !!! warning "Don't use `AllSigned`" - `AllSigned` refuses to run `install.ps1` with *"a certificate chain - processed, but terminated in a root certificate which is not trusted"* - because these scripts are signed with a personal code-signing - certificate whose root isn't in your trust store. Use `RemoteSigned`, - or import the signing certificate first (see - [`Import-SigningCert.ps1`](https://github.com/DevSecNinja/dotfiles/blob/main/home/dot_config/powershell/scripts/Import-SigningCert.ps1)). + !!! warning "Don't use `AllSigned`" + `AllSigned` refuses to run `install.ps1` with _"a certificate chain + processed, but terminated in a root certificate which is not trusted"_ + because these scripts are signed with a personal code-signing + certificate whose root isn't in your trust store. Use `RemoteSigned`, + or import the signing certificate first (see + [`Import-SigningCert.ps1`](https://github.com/DevSecNinja/dotfiles/blob/main/home/dot_config/powershell/scripts/Import-SigningCert.ps1)). 3. **Clone over HTTPS the first time.** SSH access to GitHub depends on your - SSH config and agent — both of which are provided *by* these dotfiles, so - they don't exist yet on a fresh machine. Clone over HTTPS to break the - chicken-and-egg: - - ```powershell - mkdir ~\projects; cd ~\projects - git clone https://github.com/DevSecNinja/dotfiles.git - cd dotfiles - ``` - - !!! tip "Using a Dev Drive" - If you have a [Dev Drive](https://learn.microsoft.com/en-us/windows/dev-drive/), - clone into `\projects` instead (for example `D:\projects`) — - that's the folder the PowerShell profile will `cd` into afterwards. See - [Projects folder and Dev Drive](customization.md#projects-folder-and-dev-drive). - - To use SSH afterwards (e.g. with the 1Password SSH agent), install - 1Password and enable the agent, then switch the remote to SSH: - - ```powershell - winget install AgileBits.1Password AgileBits.1Password.CLI - # In the 1Password app: Settings -> Developer -> "Use the SSH agent" - # and make sure your public key is added to https://github.com/settings/keys - git remote set-url origin git@github.com:DevSecNinja/dotfiles.git - ``` + SSH config and agent — both of which are provided _by_ these dotfiles, so + they don't exist yet on a fresh machine. Clone over HTTPS to break the + chicken-and-egg: + + ```powershell + mkdir ~\projects; cd ~\projects + git clone https://github.com/DevSecNinja/dotfiles.git + cd dotfiles + ``` + + !!! tip "Using a Dev Drive" + If you have a [Dev Drive](https://learn.microsoft.com/en-us/windows/dev-drive/), + clone into `\projects` instead (for example `D:\projects`) — + that's the folder the PowerShell profile will `cd` into afterwards. See + [Projects folder and Dev Drive](customization.md#projects-folder-and-dev-drive). + + To use SSH afterwards (e.g. with the 1Password SSH agent), install + 1Password and enable the agent, then switch the remote to SSH: + + ```powershell + winget install AgileBits.1Password AgileBits.1Password.CLI + # In the 1Password app: Settings -> Developer -> "Use the SSH agent" + # and make sure your public key is added to https://github.com/settings/keys + git remote set-url origin git@github.com:DevSecNinja/dotfiles.git + ``` 4. **Run the installer.** - ```powershell - .\install.ps1 - ``` + ```powershell + .\install.ps1 + ``` !!! note "PowerShell 7 (`pwsh`) is installed for you" - Several steps (PowerShell modules, Nerd Fonts) require PowerShell 7. The - package-install step installs it via winget **before** the module step, and - the module script refreshes `PATH` so the freshly installed `pwsh` is - found within the same run. If you ever run the pieces by hand, install it - first with `winget install Microsoft.PowerShell` and open a new shell. +Several steps (PowerShell modules, Nerd Fonts) require PowerShell 7. The +package-install step installs it via winget **before** the module step, and +the module script refreshes `PATH` so the freshly installed `pwsh` is +found within the same run. If you ever run the pieces by hand, install it +first with `winget install Microsoft.PowerShell` and open a new shell. !!! tip "WSL may need elevation and a reboot" - The WSL step runs `wsl --install -d Debian`, which requires administrator - privileges. On some machines the first run reports *"WSL installation - appears to be corrupted"* and only updates the WSL engine instead of - installing the distro — this needs a reboot to finish: +The WSL step runs `wsl --install -d Debian`, which requires administrator +privileges. On some machines the first run reports _"WSL installation +appears to be corrupted"_ and only updates the WSL engine instead of +installing the distro — this needs a reboot to finish: ```powershell wsl --update # ensure the WSL engine is current @@ -135,7 +135,6 @@ cd dotfiles .\install.ps1 ``` - ## WSL (Windows Subsystem for Linux) Use the Linux installation method inside your WSL distribution: diff --git a/docs/logging.md b/docs/logging.md index 0f3a2c6c..f9938351 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -32,23 +32,23 @@ docker compose pull 2>&1 | log_data INFO "Pulling images for adguard" Reach for the helper that best matches **what you're saying**, not just the severity: -| You want to log… | Helper | -| ----------------------------------------------- | --------------------------------- | -| A plain informational fact | `log_info` | -| The action the script is currently taking | `log_state "Deploying app"` | -| The outcome of an operation (counts, totals) | `log_result "30 deployed, 0 failed"` | -| A suggestion for the reader | `log_hint "Re-run with -v"` | -| One step in a numbered / wizard-style sequence | `log_step "Pulling images"` | -| A noteworthy event that isn't a problem | `log_notice` | -| A recoverable problem / fallback engaged | `log_warn` | -| A failed operation; script may continue | `log_error` | -| A failure the script will exit on | `log_fatal` | -| An implementation detail (off by default) | `log_debug` / `log_trace` | -| Telemetry as flat key/value pairs | `log_kv k=v k=v …` | -| Multi-line payload (YAML/JSON/command output) | `… \| log_data KIND "header"` | -| Unbroken divider between groups | `log_sep` | -| Titled divider for a phase change | `log_rule KIND "phase 1"` | -| Boxed/wrapped title for a top-level boundary | `log_banner "Done" RESULT` | +| You want to log… | Helper | +| ---------------------------------------------- | ------------------------------------ | +| A plain informational fact | `log_info` | +| The action the script is currently taking | `log_state "Deploying app"` | +| The outcome of an operation (counts, totals) | `log_result "30 deployed, 0 failed"` | +| A suggestion for the reader | `log_hint "Re-run with -v"` | +| One step in a numbered / wizard-style sequence | `log_step "Pulling images"` | +| A noteworthy event that isn't a problem | `log_notice` | +| A recoverable problem / fallback engaged | `log_warn` | +| A failed operation; script may continue | `log_error` | +| A failure the script will exit on | `log_fatal` | +| An implementation detail (off by default) | `log_debug` / `log_trace` | +| Telemetry as flat key/value pairs | `log_kv k=v k=v …` | +| Multi-line payload (YAML/JSON/command output) | `… \| log_data KIND "header"` | +| Unbroken divider between groups | `log_sep` | +| Titled divider for a phase change | `log_rule KIND "phase 1"` | +| Boxed/wrapped title for a top-level boundary | `log_banner "Done" RESULT` | `STATE` / `RESULT` / `HINT` / `STEP` are info-priority kinds — they never change filtering behaviour, only color and label. Use them so `grep RESULT` @@ -59,31 +59,31 @@ finds outcomes and `grep HINT` finds suggestions. The library separates **severity** (controls filtering) from **kind** (controls visual category). Both are first-class concepts. -| Concept | Examples | Filtered by `LOG_LEVEL`? | Syslog priority | -| -------- | ------------------------------------- | ------------------------ | --------------- | +| Concept | Examples | Filtered by `LOG_LEVEL`? | Syslog priority | +| -------- | ------------------------------------------------------ | ------------------------ | --------------- | | Severity | `TRACE` `DEBUG` `INFO` `NOTICE` `WARN` `ERROR` `FATAL` | yes | matches | -| Kind | `STATE` `RESULT` `HINT` `STEP` | rendered at `INFO` | always `info` | +| Kind | `STATE` `RESULT` `HINT` `STEP` | rendered at `INFO` | always `info` | Helpers: -| Function | Severity | Kind | Stream | Color (default) | -| -------------- | -------- | -------- | ------ | ---------------- | -| `log_trace` | TRACE | TRACE | stdout | dim | -| `log_debug` | DEBUG | DEBUG | stdout | dim cyan | -| `log_info` | INFO | INFO | stdout | none | -| `log_notice` | NOTICE | NOTICE | stdout | bold blue | -| `log_warn` | WARN | WARN | stderr | bold yellow | -| `log_error` | ERROR | ERROR | stderr | bold red | -| `log_fatal` | FATAL | FATAL | stderr | white on red | -| `log_state` | INFO | STATE | stdout | cyan | -| `log_result` | INFO | RESULT | stdout | green | -| `log_hint` | INFO | HINT | stdout | magenta | -| `log_step` | INFO | STEP | stdout | dim white | -| `log_kv` | INFO | INFO | stdout | none | -| `log_data` | (any) | (any) | stdout | per kind | -| `log_sep` | (any) | (any) | stdout | per kind | -| `log_rule` | (any) | (any) | stdout | per kind | -| `log_banner` | (any) | STATE\* | stdout | per kind | +| Function | Severity | Kind | Stream | Color (default) | +| ------------ | -------- | ------- | ------ | --------------- | +| `log_trace` | TRACE | TRACE | stdout | dim | +| `log_debug` | DEBUG | DEBUG | stdout | dim cyan | +| `log_info` | INFO | INFO | stdout | none | +| `log_notice` | NOTICE | NOTICE | stdout | bold blue | +| `log_warn` | WARN | WARN | stderr | bold yellow | +| `log_error` | ERROR | ERROR | stderr | bold red | +| `log_fatal` | FATAL | FATAL | stderr | white on red | +| `log_state` | INFO | STATE | stdout | cyan | +| `log_result` | INFO | RESULT | stdout | green | +| `log_hint` | INFO | HINT | stdout | magenta | +| `log_step` | INFO | STEP | stdout | dim white | +| `log_kv` | INFO | INFO | stdout | none | +| `log_data` | (any) | (any) | stdout | per kind | +| `log_sep` | (any) | (any) | stdout | per kind | +| `log_rule` | (any) | (any) | stdout | per kind | +| `log_banner` | (any) | STATE\* | stdout | per kind | \* `log_banner` defaults to `STATE` kind; pass an explicit kind as the second argument to override. @@ -147,13 +147,13 @@ log_banner "Deploying app" STATE The `LOG_BANNER_STYLE` env var selects the visual style: -| Style | Sample (40-wide) | -| --------- | ------------------------------------------------------------------ | -| `unicode` (default) | `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━` | -| `ascii` | `========================================` | -| `heavy` | `########################################` | -| `box` | `┌──────────────────────────────────────┐` … `└──────────────────┘` | -| `rule` | `────────────────────────────────────────` | +| Style | Sample (40-wide) | +| ------------------- | ------------------------------------------------------------------- | +| `unicode` (default) | `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━` | +| `ascii` | `========================================` | +| `heavy` | `########################################` | +| `box` | `┌──────────────────────────────────────┐` … `└──────────────────┘` | +| `rule` | `────────────────────────────────────────` | Multi-byte styles (`unicode`, `box`, `rule`) automatically fall back to `ascii` when: @@ -190,8 +190,8 @@ log_kv "msg=hello world" status=ok # values with spaces auto-quoted ### `log_data` — multiline payloads with continuation prefix Reads the payload from stdin. On a TTY the payload lines are prefixed with -`│ ` so they visually belong to the previous header line; in `LOG_FILE` the -prefix is `| ` (ASCII). The whole block shares **one timestamp**, which is +`│` so they visually belong to the previous header line; in `LOG_FILE` the +prefix is `|` (ASCII). The whole block shares **one timestamp**, which is what groups it. The primary use case is wrapping the output of another command without @@ -237,21 +237,21 @@ renders the header and continuation lines in green. ## Configuration env vars -| Var | Default | Purpose | -| -------------------- | ------------ | ------------------------------------------------------ | -| `LOG_LEVEL` | `INFO` | Minimum severity to emit | -| `LOG_TAG` | (auto) | Explicit tag, `[A-Za-z0-9._-]{1,32}` | -| `LOG_FORMAT` | `text` | `text` or `json` | -| `LOG_COLOR` | `auto` | `auto`, `always`, `never` (also `NO_COLOR`) | -| `LOG_BANNER_STYLE` | `unicode` | `unicode`, `ascii`, `heavy`, `box`, `rule` | -| `LOG_RULE_WIDTH` | `40` | Banner / rule width | -| `LOG_RULE_CHAR` | per style | Override the separator character | -| `LOG_MAX_BYTES` | `8192` | Per-line byte cap; longer lines are truncated | -| `LOG_FILE` | (none) | Optional log file path | -| `LOG_FILE_MAX_BYTES` | (none) | Rotate when file exceeds this size | -| `LOG_FILE_TTL_DAYS` | (none) | Delete file when older than N days | -| `LOG_JOURNAL` | `auto` | `auto`, `always`, `never` — `logger(1)` integration | -| `LOG_TO_STDIO` | `1` | Set to `0` to suppress stdout/stderr writes | +| Var | Default | Purpose | +| -------------------- | --------- | --------------------------------------------------- | +| `LOG_LEVEL` | `INFO` | Minimum severity to emit | +| `LOG_TAG` | (auto) | Explicit tag, `[A-Za-z0-9._-]{1,32}` | +| `LOG_FORMAT` | `text` | `text` or `json` | +| `LOG_COLOR` | `auto` | `auto`, `always`, `never` (also `NO_COLOR`) | +| `LOG_BANNER_STYLE` | `unicode` | `unicode`, `ascii`, `heavy`, `box`, `rule` | +| `LOG_RULE_WIDTH` | `40` | Banner / rule width | +| `LOG_RULE_CHAR` | per style | Override the separator character | +| `LOG_MAX_BYTES` | `8192` | Per-line byte cap; longer lines are truncated | +| `LOG_FILE` | (none) | Optional log file path | +| `LOG_FILE_MAX_BYTES` | (none) | Rotate when file exceeds this size | +| `LOG_FILE_TTL_DAYS` | (none) | Delete file when older than N days | +| `LOG_JOURNAL` | `auto` | `auto`, `always`, `never` — `logger(1)` integration | +| `LOG_TO_STDIO` | `1` | Set to `0` to suppress stdout/stderr writes | `LOG_FILE` is only created when at least one of `LOG_FILE_MAX_BYTES` or `LOG_FILE_TTL_DAYS` is set, so every log file has an explicit lifecycle. @@ -262,15 +262,15 @@ The logger is hardened against the following classes of attack — relevant when log content is influenced by untrusted input (CI artifacts, container labels, web requests, etc.). -| Risk | Mitigation | -| ----------------------------------------------- | ------------------------------------------------------------------- | -| ANSI escape injection (terminal hijacking) | `\033`, `\007`, `\000` stripped from messages before output | -| Newline / CR smuggling (multi-line forge) | `\n` and `\r` escaped to literal two-char sequences; one entry = one line | -| Format-string attacks (`%s`, `%n`, …) | Every emitter uses `printf '%s'`; user data never becomes a format | -| `logger -t` flag injection via `LOG_TAG` | Tag validated against strict regex; bad values silently dropped | -| Bash-style flag injection (`--inject` as tag) | Tags starting with `-` or `.` rejected | -| `LOG_FILE` symlink redirection | Refused if the path resolves through a symlink | -| DoS via huge payload | Lines truncated at `LOG_MAX_BYTES` (default 8 KiB) with marker | +| Risk | Mitigation | +| --------------------------------------------- | ------------------------------------------------------------------------- | +| ANSI escape injection (terminal hijacking) | `\033`, `\007`, `\000` stripped from messages before output | +| Newline / CR smuggling (multi-line forge) | `\n` and `\r` escaped to literal two-char sequences; one entry = one line | +| Format-string attacks (`%s`, `%n`, …) | Every emitter uses `printf '%s'`; user data never becomes a format | +| `logger -t` flag injection via `LOG_TAG` | Tag validated against strict regex; bad values silently dropped | +| Bash-style flag injection (`--inject` as tag) | Tags starting with `-` or `.` rejected | +| `LOG_FILE` symlink redirection | Refused if the path resolves through a symlink | +| DoS via huge payload | Lines truncated at `LOG_MAX_BYTES` (default 8 KiB) with marker | These guarantees apply to **the message and tag**. Environment variables (LOG_FILE, LOG_FORMAT, …) are configuration surface — keep them under your diff --git a/docs/structure.md b/docs/structure.md index 804e4f0b..4c7e5594 100644 --- a/docs/structure.md +++ b/docs/structure.md @@ -10,15 +10,15 @@ in the repository. Chezmoi uses special prefixes in filenames to determine how files are managed: -| Prefix | Target | Example | -| --- | --- | --- | -| `dot_` | `.` (hidden file) | `dot_vimrc` → `~/.vimrc` | -| `private_` | File with `0600` permissions | `private_ssh_config` | -| `executable_` | File with `+x` permissions | `executable_script.sh` | -| `run_once_` | Script that runs once | `run_once_install.sh` | -| `run_onchange_` | Script that runs on change | `run_onchange_update.sh` | -| `run_` | Script that runs every apply | `run_backup.sh` | -| `.tmpl` | Template file | `config.tmpl` (Chezmoi templates) | +| Prefix | Target | Example | +| --------------- | ---------------------------- | --------------------------------- | +| `dot_` | `.` (hidden file) | `dot_vimrc` → `~/.vimrc` | +| `private_` | File with `0600` permissions | `private_ssh_config` | +| `executable_` | File with `+x` permissions | `executable_script.sh` | +| `run_once_` | Script that runs once | `run_once_install.sh` | +| `run_onchange_` | Script that runs on change | `run_onchange_update.sh` | +| `run_` | Script that runs every apply | `run_backup.sh` | +| `.tmpl` | Template file | `config.tmpl` (Chezmoi templates) | ## Repository Layout diff --git a/docs/yubikey.md b/docs/yubikey.md index 6b3bf8a4..17db8381 100644 --- a/docs/yubikey.md +++ b/docs/yubikey.md @@ -14,12 +14,12 @@ variable and stays the default until you flip it. When `useYubiKey: true`, `chezmoi apply` also installs `ykman` (yubikey-manager) and the smart-card daemon needed for OATH: -| OS | Package(s) | -| --------- | ------------------------------------------- | -| macOS | `ykman`, `openssh` (Homebrew — Apple's bundled OpenSSH lacks FIDO2) | -| Debian/Ubuntu | `yubikey-manager`, `pcscd`, `scdaemon` | -| Fedora | `yubikey-manager`, `pcsc-lite` | -| Windows | `Yubico.YubikeyManagerCLI` (winget) | +| OS | Package(s) | +| ------------- | ------------------------------------------------------------------- | +| macOS | `ykman`, `openssh` (Homebrew — Apple's bundled OpenSSH lacks FIDO2) | +| Debian/Ubuntu | `yubikey-manager`, `pcscd`, `scdaemon` | +| Fedora | `yubikey-manager`, `pcsc-lite` | +| Windows | `Yubico.YubikeyManagerCLI` (winget) | Set `useYubiKey: false` (the default) and none of these are touched. @@ -145,7 +145,7 @@ For FIDO2 (`*-sk`) keys, the file at `~/.ssh/id_ed25519_sk_` is private key never leaves the hardware and is gated by touch + your FIDO2 PIN. Encrypting the handle with a passphrase therefore adds friction on every `ssh` without any cryptographic benefit — someone -with your handle file *and* your YubiKey *and* your PIN already has +with your handle file _and_ your YubiKey _and_ your PIN already has everything. `yk-ssh-new` (and by extension `yk-enroll`) passes `-N ""` to @@ -169,8 +169,8 @@ re-prompt for the FIDO2 PIN, so the second `ssh` call fails with: sign_and_send_pubkey: signing failed for ED25519-SK "..." from agent: agent refused operation ``` -Letting OpenSSH talk to the YubiKey directly each time keeps the touch -+ PIN dance interactive and reliable. If you ever land in the broken +Letting OpenSSH talk to the YubiKey directly each time keeps the +touch + PIN dance interactive and reliable. If you ever land in the broken state (e.g. you ran an older config that did `AddKeysToAgent yes`), clear the agent and you're back in business: @@ -214,18 +214,18 @@ its own "Done." footer so you don't miss it. ## Helpers (Bash/Zsh + Fish) -| Bash/Zsh | Fish | Purpose | -| ----------------------- | ------------------- | ---------------------------------------------------------- | -| `yk-enroll` | `yk_enroll` | **Wizard**: end-to-end enrollment + health check, idempotent | -| `yk-status` | `yk_status` | Per-device health: firmware, FIPS, PIN status, SSH key check | -| `yk-pick` | `yk_pick` | Pick one serial when multiple keys are connected | -| `yk-ssh-new` | `yk_ssh_new` | Low-level: generate `ed25519-sk` / `ecdsa-sk` on the key | -| `work-checklist` | `work_checklist` | Print manual post-install steps for work machines | -| `clipboard-copy` | `clipboard_copy` | Cross-platform clipboard helper used by `pubkey` | -| `pubkey` | `pubkey` | Print + copy the highest-priority pubkey from `~/.ssh` | -| `yk-git-sign-setup` | `yk_git_sign_setup` | Register your SSH pubkey for git commit signing | -| `yk-otp` | `yk_otp` | TOTP code from the OATH applet (fzf + clipboard) | -| `yk-touch-watch` | `yk_touch_watch` | Notify when a YubiKey is waiting for a touch | +| Bash/Zsh | Fish | Purpose | +| ------------------- | ------------------- | ------------------------------------------------------------ | +| `yk-enroll` | `yk_enroll` | **Wizard**: end-to-end enrollment + health check, idempotent | +| `yk-status` | `yk_status` | Per-device health: firmware, FIPS, PIN status, SSH key check | +| `yk-pick` | `yk_pick` | Pick one serial when multiple keys are connected | +| `yk-ssh-new` | `yk_ssh_new` | Low-level: generate `ed25519-sk` / `ecdsa-sk` on the key | +| `work-checklist` | `work_checklist` | Print manual post-install steps for work machines | +| `clipboard-copy` | `clipboard_copy` | Cross-platform clipboard helper used by `pubkey` | +| `pubkey` | `pubkey` | Print + copy the highest-priority pubkey from `~/.ssh` | +| `yk-git-sign-setup` | `yk_git_sign_setup` | Register your SSH pubkey for git commit signing | +| `yk-otp` | `yk_otp` | TOTP code from the OATH applet (fzf + clipboard) | +| `yk-touch-watch` | `yk_touch_watch` | Notify when a YubiKey is waiting for a touch | `pubkey` discovers per-serial files: it picks the first match of `id_ed25519_sk_*.pub` → `id_ed25519_sk.pub` → `id_ecdsa_sk_*.pub` → @@ -234,12 +234,12 @@ follows you onto a YubiKey enrolled with `yk-enroll`. ## Firmware compatibility -| Feature | Min fw | Notes | -| ------------------------------ | -------- | ------------------------------------ | -| `ed25519-sk` SSH keys | 5.2.3 | Both 5.4.3 and 5.7.4 supported | -| Resident credentials + `-K` | 5.2.3 | Both 5.4.3 and 5.7.4 supported | -| PIV `ed25519` | 5.7 | Not used by these helpers (yet) | -| FIPS-approved algorithms only | FIPS sku | `yk-status` flags FIPS devices | +| Feature | Min fw | Notes | +| ----------------------------- | -------- | ------------------------------- | +| `ed25519-sk` SSH keys | 5.2.3 | Both 5.4.3 and 5.7.4 supported | +| Resident credentials + `-K` | 5.2.3 | Both 5.4.3 and 5.7.4 supported | +| PIV `ed25519` | 5.7 | Not used by these helpers (yet) | +| FIPS-approved algorithms only | FIPS sku | `yk-status` flags FIPS devices | `yk-status` warns when a device is below 5.7 so you remember which features are available on which key. @@ -305,7 +305,7 @@ git commit -S --allow-empty -m "test signing" git log --show-signature -1 ``` -> **Uploading a *signing* key isn't optional** — the whole point of signing is +> **Uploading a _signing_ key isn't optional** — the whole point of signing is > the verified badge. `yk-enroll`'s "Done." block lists both `gh ssh-key add` > commands explicitly, and `work-checklist` includes them as separate > checklist items. @@ -343,5 +343,5 @@ The current flow is preserved as-is until you flip the switch: and the macOS `IdentityAgent` line are removed; `IdentityFile` lines for `id_ed25519_sk` / `id_ecdsa_sk` are added under `Host *`. 5. Apple Passwords does not provide an SSH agent; on macOS the OS keychain - + ssh-agent handle the FIDO2 key directly. Bitwarden CLI (`bw`) can - stand in for `op` when scripts need secrets. + - ssh-agent handle the FIDO2 key directly. Bitwarden CLI (`bw`) can + stand in for `op` when scripts need secrets. diff --git a/home/.chezmoidata/packages.yaml b/home/.chezmoidata/packages.yaml index 128b60c2..09f6adbb 100644 --- a/home/.chezmoidata/packages.yaml +++ b/home/.chezmoidata/packages.yaml @@ -1,3 +1,4 @@ +--- # Cross-platform package definitions for Chezmoi dotfiles # Packages are organized by OS and package manager # Installation modes: light (essential) + full (light + additional packages) @@ -159,10 +160,10 @@ packages: powershell_git_modules: light: [] full: - # Path relative to PowerShell modules directory (~\Documents\PowerShell\Modules\) - # - name: "Office 365 Mail Alias" - # url: "https://github.com/DevSecNinja/Office365AliasModule.git" - # destination: "DevSecNinja.Office365AliasModule" + # Path relative to PowerShell modules directory (~\Documents\PowerShell\Modules\) + # - name: "Office 365 Mail Alias" + # url: "https://github.com/DevSecNinja/Office365AliasModule.git" + # destination: "DevSecNinja.Office365AliasModule" # VS Code extensions (optional, separate from package installation) # Note: GitHub.copilot and GitHub.copilot-chat are now bundled as built-in diff --git a/home/Taskfile.yml b/home/Taskfile.yml index a632ad22..3ad970c8 100644 --- a/home/Taskfile.yml +++ b/home/Taskfile.yml @@ -1,3 +1,4 @@ +--- version: '3' vars: @@ -15,7 +16,8 @@ tasks: desc: Set up and chat with local Qwen3.5 (Apple Silicon, thinking disabled) interactive: true silent: true - deps: [llm:setup] + deps: + - llm:setup cmds: - >- "{{.MLX_VENV}}/bin/python" "{{.ROOT_DIR}}/.config/mlx/chat.py" @@ -43,7 +45,8 @@ tasks: llm:setup: internal: true - deps: [llm:storage] + deps: + - llm:storage preconditions: - sh: | for path in "{{.MLX_CACHE_DIR}}" "{{.MLX_CACHE_DIR}}/hub" "{{.MLX_CACHE_DIR}}/xet" "{{.MLX_CACHE_DIR}}/pip" "{{.MLX_CACHE_DIR}}/tmp"; do @@ -71,7 +74,8 @@ tasks: - sh: >- (test ! -e "{{.MLX_VENV}}" && test ! -L "{{.MLX_VENV}}") || "{{.MLX_VENV}}/bin/python" -c '{{.MLX_VENV_CHECK}}' - msg: 'Existing {{.MLX_VENV}} is not a usable Python 3.11+ arm64 venv. Repair it or move it aside; it will not be deleted automatically.' + msg: 'Existing {{.MLX_VENV}} is not a usable Python 3.11+ arm64 venv. Repair it or move it aside; it will not be deleted + automatically.' status: - '"{{.MLX_VENV}}/bin/python" -c ''{{.MLX_VENV_CHECK}}''' cmds: @@ -88,7 +92,8 @@ tasks: internal: true preconditions: - sh: python3 -c '{{.MLX_PYTHON_CHECK}}' 2>/dev/null || command -v brew - msg: 'A native Python 3.11+ or Homebrew is required. Install Homebrew using the existing dotfiles setup; this task cannot safely bootstrap Homebrew.' + msg: 'A native Python 3.11+ or Homebrew is required. Install Homebrew using the existing dotfiles setup; this task + cannot safely bootstrap Homebrew.' status: - | python3 -c '{{.MLX_PYTHON_CHECK}}' 2>/dev/null || diff --git a/home/dot_config/fish/README.md b/home/dot_config/fish/README.md index 77c1e922..8b0b49f7 100644 --- a/home/dot_config/fish/README.md +++ b/home/dot_config/fish/README.md @@ -85,17 +85,20 @@ complete -c mycommand -s h -l help -d 'Show help' ## 🚀 Useful Fish Features ### Command Substitution + ```fish echo (date) ``` ### Variables + ```fish set -gx MY_VAR "value" # Global export set -l my_var "value" # Local variable ``` ### Conditionals + ```fish if test -f myfile echo "File exists" @@ -103,6 +106,7 @@ end ``` ### Loops + ```fish for file in *.txt echo $file diff --git a/home/dot_config/powershell/README.md b/home/dot_config/powershell/README.md index 69cd944b..989f3f52 100644 --- a/home/dot_config/powershell/README.md +++ b/home/dot_config/powershell/README.md @@ -46,6 +46,7 @@ After installation, start a new PowerShell session. Type `aliases` to see all av - `Invoke-WingetUpgrade` - Full upgrade function with customizable options **Examples:** + ```powershell # Check for updates Test-WingetUpdates diff --git a/home/dot_ohmyposh.omp.yaml b/home/dot_ohmyposh.omp.yaml index 8ed6384a..953067c9 100644 --- a/home/dot_ohmyposh.omp.yaml +++ b/home/dot_ohmyposh.omp.yaml @@ -1,142 +1,145 @@ +--- # yaml-language-server: $schema=https://raw.githubusercontent.com/JanDeDobbeleer/oh-my-posh/main/themes/schema.json # This is the default theme palette: - black: '#262B44' - blue: '#4B95E9' - green: '#59C9A5' - orange: '#F07623' - red: '#D81E5B' - white: '#E0DEF4' - yellow: '#F3AE35' + black: '#262B44' + blue: '#4B95E9' + green: '#59C9A5' + orange: '#F07623' + red: '#D81E5B' + white: '#E0DEF4' + yellow: '#F3AE35' secondary_prompt: - template: '<,p:yellow> >  ' - foreground: p:black - background: transparent + template: '<,p:yellow> >  ' + foreground: p:black + background: transparent transient_prompt: - template: '<,p:yellow> {{ .Folder }}  ' - foreground: p:black - background: transparent + template: '<,p:yellow> {{ .Folder }}  ' + foreground: p:black + background: transparent upgrade: - source: cdn - interval: 168h - auto: false - notice: false + source: cdn + interval: 168h + auto: false + notice: false console_title_template: '{{ .Shell }} in {{ .Folder }}' blocks: - - type: prompt - alignment: left - segments: - - leading_diamond:  - trailing_diamond:  - template: ' {{ if .SSHSession }} {{ end }}{{ .UserName }} ' - foreground: p:black - background: p:yellow - type: session - style: diamond - - options: - style: folder - template: '  {{ path .Path .Location }} ' - foreground: p:white - powerline_symbol:  - background: p:orange - type: path - style: powerline - - options: - branch_template: '{{ trunc 25 .Branch }}' - fetch_status: true - fetch_upstream_icon: true - template: ' {{ if .UpstreamURL }}{{ url .UpstreamIcon .UpstreamURL }} {{ end }}{{ .HEAD }}{{if .BranchStatus }} {{ .BranchStatus }}{{ end }}{{ if .Working.Changed }}  {{ .Working.String }}{{ end }}{{ if .Staging.Changed }}  {{ .Staging.String }}{{ end }} ' - foreground: p:black - powerline_symbol:  - background: p:green - type: git - style: powerline - foreground_templates: - - '{{ if or (.Working.Changed) (.Staging.Changed) }}p:black{{ end }}' - - '{{ if and (gt .Ahead 0) (gt .Behind 0) }}p:white{{ end }}' - - '{{ if gt .Ahead 0 }}p:white{{ end }}' - background_templates: - - '{{ if or (.Working.Changed) (.Staging.Changed) }}p:yellow{{ end }}' - - '{{ if and (gt .Ahead 0) (gt .Behind 0) }}p:red{{ end }}' - - '{{ if gt .Ahead 0 }}#49416D{{ end }}' - - '{{ if gt .Behind 0 }}#7A306C{{ end }}' - - template: '  ' - foreground: p:white - powerline_symbol:  - background: p:yellow - type: root - style: powerline - - options: - always_enabled: true - leading_diamond:  - trailing_diamond:  - template: ' {{ if gt .Code 0 }}{{ else }}{{ end }} ' - foreground: p:white - background: p:blue - type: status - style: diamond - background_templates: - - '{{ if gt .Code 0 }}p:red{{ end }}' - - type: rprompt - segments: - - options: - display_mode: files - fetch_package_manager: false - home_enabled: false - template: ' ' - foreground: p:green - background: transparent - type: node - style: plain - - options: - fetch_version: false - template: ' ' - foreground: p:blue - background: transparent - type: go - style: plain - - options: - display_mode: files - fetch_version: false - fetch_virtual_env: false - template: ' ' - foreground: p:yellow - background: transparent - type: python - style: plain - - template: 'in {{ .Name }} ' - foreground: p:white - background: transparent - type: shell - style: plain - - template: at {{ .CurrentDate | date "15:04:05" }} - foreground: p:white - background: transparent - type: time - style: plain + - type: prompt + alignment: left + segments: + - leading_diamond:  + trailing_diamond:  + template: ' {{ if .SSHSession }} {{ end }}{{ .UserName }} ' + foreground: p:black + background: p:yellow + type: session + style: diamond + - options: + style: folder + template: '  {{ path .Path .Location }} ' + foreground: p:white + powerline_symbol:  + background: p:orange + type: path + style: powerline + - options: + branch_template: '{{ trunc 25 .Branch }}' + fetch_status: true + fetch_upstream_icon: true + template: ' {{ if .UpstreamURL }}{{ url .UpstreamIcon .UpstreamURL }} {{ end }}{{ .HEAD }}{{if .BranchStatus }} {{ + .BranchStatus }}{{ end }}{{ if .Working.Changed }}  {{ .Working.String }}{{ end }}{{ if .Staging.Changed }}  {{ + .Staging.String }}{{ end }} ' + foreground: p:black + powerline_symbol:  + background: p:green + type: git + style: powerline + foreground_templates: + - '{{ if or (.Working.Changed) (.Staging.Changed) }}p:black{{ end }}' + - '{{ if and (gt .Ahead 0) (gt .Behind 0) }}p:white{{ end }}' + - '{{ if gt .Ahead 0 }}p:white{{ end }}' + background_templates: + - '{{ if or (.Working.Changed) (.Staging.Changed) }}p:yellow{{ end }}' + - '{{ if and (gt .Ahead 0) (gt .Behind 0) }}p:red{{ end }}' + - '{{ if gt .Ahead 0 }}#49416D{{ end }}' + - '{{ if gt .Behind 0 }}#7A306C{{ end }}' + - template: '  ' + foreground: p:white + powerline_symbol:  + background: p:yellow + type: root + style: powerline + - options: + always_enabled: true + leading_diamond:  + trailing_diamond:  + template: ' {{ if gt .Code 0 }}{{ else }}{{ end }} ' + foreground: p:white + background: p:blue + type: status + style: diamond + background_templates: + - '{{ if gt .Code 0 }}p:red{{ end }}' + - type: rprompt + segments: + - options: + display_mode: files + fetch_package_manager: false + home_enabled: false + template: ' ' + foreground: p:green + background: transparent + type: node + style: plain + - options: + fetch_version: false + template: ' ' + foreground: p:blue + background: transparent + type: go + style: plain + - options: + display_mode: files + fetch_version: false + fetch_virtual_env: false + template: ' ' + foreground: p:yellow + background: transparent + type: python + style: plain + - template: 'in {{ .Name }} ' + foreground: p:white + background: transparent + type: shell + style: plain + - template: at {{ .CurrentDate | date "15:04:05" }} + foreground: p:white + background: transparent + type: time + style: plain tooltips: - - options: - display_default: true - leading_diamond:  - trailing_diamond:  - template: '  {{ .Profile }}{{ if .Region }}@{{ .Region }}{{ end }} ' - foreground: p:white - background: p:orange - type: aws - style: diamond - tips: - - aws - - options: - display_default: true - leading_diamond:  - trailing_diamond:  - template: '  {{ .Name }} ' - foreground: p:white - background: p:blue - type: az - style: diamond - tips: - - az + - options: + display_default: true + leading_diamond:  + trailing_diamond:  + template: '  {{ .Profile }}{{ if .Region }}@{{ .Region }}{{ end }} ' + foreground: p:white + background: p:orange + type: aws + style: diamond + tips: + - aws + - options: + display_default: true + leading_diamond:  + trailing_diamond:  + template: '  {{ .Name }} ' + foreground: p:white + background: p:blue + type: az + style: diamond + tips: + - az version: 4 final_space: true diff --git a/mkdocs.yml b/mkdocs.yml index 71701a32..e658e0ea 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,7 +1,8 @@ --- site_name: Dotfiles site_url: https://dotfiles.ravensberg.org/ -site_description: Modern dotfiles repository managed with Chezmoi, featuring Fish shell, PowerShell, and automated setup scripts for Linux, macOS, Windows, and WSL +site_description: Modern dotfiles repository managed with Chezmoi, featuring Fish shell, PowerShell, and automated setup scripts + for Linux, macOS, Windows, and WSL site_author: DevSecNinja repo_url: https://github.com/DevSecNinja/dotfiles repo_name: DevSecNinja/dotfiles diff --git a/tests/README.md b/tests/README.md index 755555ff..5fbe2880 100644 --- a/tests/README.md +++ b/tests/README.md @@ -35,6 +35,7 @@ tests/ **Framework**: [Pester 5.x](https://pester.dev/) **Coverage**: + - PowerShell utility scripts - **Packages YAML validation** (cross-platform package configuration) ✨ - Code signing certificate generation (`New-SigningCert.ps1.tmpl`) @@ -43,6 +44,7 @@ tests/ - CI/CD pipeline validation **Run locally**: + ```powershell # Using the test runner script (recommended) .\tests\powershell\Invoke-PesterTests.ps1 @@ -74,6 +76,7 @@ Invoke-Pester -Path ./tests/powershell -Tag "Pipeline" **Framework**: [Bats 1.13+](https://github.com/bats-core/bats-core) **Coverage**: + - Shell function utilities (`find-broken-symlinks`, `git-https-to-ssh`, `git-ssh-to-https`, etc.) - **Configuration validation** (Chezmoi, Fish, shell scripts) ✨ - **Dotfiles verification** (applied files existence) ✨ @@ -83,6 +86,7 @@ Invoke-Pester -Path ./tests/powershell -Tag "Pipeline" - Error handling and edge cases **Test Files** (utility functions): + - `brewup.bats` - Tests Homebrew update/upgrade wrapper - `macup.bats` - Tests macOS update wrapper (brewup + softwareupdate) - `file-set-execution-bit.bats` - Tests shell script executable bit management @@ -97,6 +101,7 @@ Invoke-Pester -Path ./tests/powershell -Tag "Pipeline" - `git-ssh-to-https.bats` - Tests Git SSH-to-HTTPS remote URL conversion **Test Files** (validation & integration): + - `validate-chezmoi.bats` - Validates Chezmoi configuration syntax - `validate-shell-scripts.bats` - Validates all shell script syntax - `validate-fish-config.bats` - Validates Fish configuration files @@ -110,6 +115,7 @@ Invoke-Pester -Path ./tests/powershell -Tag "Pipeline" - `verify-dotfiles.bats` - Verifies applied dotfiles exist **Run locally**: + ```bash # Using the test runner script (recommended) ./tests/bash/run-tests.sh @@ -164,12 +170,14 @@ Existing plain-BATS tests keep working unchanged; `helpers/common.bash` auto-installs missing libraries on first run. **Test features**: + - Comprehensive coverage of all function options (--dry-run, --yes, --verbose) - Edge cases (special characters, nested directories, mixed symlinks) - Error conditions (nonexistent directories, permission issues) - Output validation and behavior verification **Validation tests** (new): + - `validate-chezmoi.bats` - Validates Chezmoi configuration syntax and structure - `validate-shell-scripts.bats` - Checks all shell scripts for syntax errors - `validate-fish-config.bats` - Validates Fish configuration files @@ -184,6 +192,7 @@ auto-installs missing libraries on first run. **Planned Framework**: [pytest](https://pytest.org/) **Planned Coverage**: + - Python utilities - Validation scripts - Configuration helpers @@ -205,6 +214,7 @@ All tests run automatically in GitHub Actions on every push and pull request. ### Test Execution The CI pipeline: + - Uses dedicated test runner scripts for each language: - PowerShell: `tests/powershell/Invoke-PesterTests.ps1` - Bash: reusable `.github/workflows/bats.yml` (mise-managed bats, mirrors @@ -223,6 +233,7 @@ The CI pipeline: ### Viewing Results **Test Artifacts**: + 1. Go to [Actions](../../actions) tab in GitHub 2. Click on the latest workflow run 3. Download test result artifacts: @@ -230,6 +241,7 @@ The CI pipeline: - `pester-test-results` - PowerShell test results (NUnit XML) **Test Summary**: + - Displayed in workflow run logs - Shows pass/fail/skip counts - Includes detailed output for failures @@ -302,6 +314,7 @@ The CI pipeline: Use tags to organize and filter tests: **PowerShell Tags**: + - `Platform` - Platform/environment checks - `Integration` - Integration tests that create resources - `E2E` - End-to-end workflow tests @@ -318,6 +331,7 @@ tag filters during discovery, but top-level `BeforeAll` blocks still execute, so tag filtering alone will not stop certificates from being provisioned. **Example**: + ```powershell Describe "My Feature" -Tag "Integration", "Security" { It "Should be secure" { ... }