@sebastienrousseau/dotfiles 0.2.520 → 0.2.521

package/docs/operations/VERSION_SYNC.md

@@ -1,393 +0,0 @@
----
-render_with_liquid: false
----
-
-# Version Synchronization System
-
-The version synchronization system ensures that all version references across the repository remain consistent with the version specified in `package.json`.
-
-## Overview
-
-### Problem Statement
-
-Large repositories often have version numbers scattered across multiple files:
-
-- README badges
-- Documentation headers
-- Feature version stamps
-- Configuration files
-
-Manually keeping these synchronized is error-prone and time-consuming.
-
-### Solution Architecture
-
-This system provides automated version synchronization through:
-
-1. **CI/CD Workflow** (`.github/workflows/sync-versions.yml`) - Automated synchronization on version changes
-2. **Local Script** (`scripts/version-sync.sh`) - Manual synchronization and verification
-3. **Verification System** - Ensures all references remain consistent
-
-## Components
-
-### 1. GitHub Actions Workflow
-
-**Location**: `.github/workflows/sync-versions.yml`
-
-**Triggers**:
-
-- Push to `main` branch when `package.json` changes
-- Pull requests affecting `package.json`
-- Manual dispatch with optional target version
-
-**Process**:
-
-1. **Detect Changes** - Compares current vs previous `package.json` version
-2. **Sync Versions** - Updates all markdown files with version references
-3. **Verify Consistency** - Ensures all references match target version
-4. **Commit & Push** - Automatically commits changes (except on PRs)
-
-**Features**:
-
-- Backup creation before changes
-- Comprehensive change reporting
-- PR comment integration
-- Artifact preservation for rollback
-
-### 2. Local Synchronization Script
-
-**Location**: `scripts/version-sync.sh`
-
-**Usage**:
-
-```bash
-# Sync to current package.json version
-./scripts/version-sync.sh
-
-# Sync to specific version
-./scripts/version-sync.sh 1.2.3
-
-# Preview changes without applying
-./scripts/version-sync.sh --dry-run
-
-# Verify current consistency
-./scripts/version-sync.sh --verify
-```
-
-**Options**:
-
-- `--dry-run` - Preview changes without applying
-- `--verify` - Check version consistency only
-- `--backup` / `--no-backup` - Control backup creation
-- `--force` - Force sync even if no changes detected
-
-### 3. Version Patterns
-
-The system recognizes and updates these patterns:
-
-#### README.md
-
-```markdown
-[![Version](https://img.shields.io/badge/Version-v0.2.501-blue?style=for-the-badge)]
-```
-
-#### Documentation Files
-
-```markdown
-**Version**: v0.2.503
-**Dotfiles Version**: v0.2.503
-Version: v0.2.503
-version 0.2.485
-```
-
-## Integration Points
-
-### CI/CD Pipeline Integration
-
-The workflow integrates with the existing CI pipeline:
-
-```yaml
-# Existing CI workflow can depend on version sync
-needs: [sync-versions, lint-shell, test-linux]
-```
-
-### Git Hooks Integration
-
-For local development, add to `.git/hooks/pre-commit`:
-
-```bash
-#!/bin/bash
-# Check version consistency before commits
-./scripts/version-sync.sh --verify || {
-    echo "Version inconsistency detected. Run: ./scripts/version-sync.sh"
-    exit 1
-}
-```
-
-### Package.json Integration
-
-Version changes in `package.json` automatically trigger synchronization:
-
-```json
-{
-  "name": "@sebastienrousseau/dotfiles",
-  "version": "0.2.485",  // Changes here trigger sync
-  "scripts": {
-    "version-sync": "./scripts/version-sync.sh",
-    "version-verify": "./scripts/version-sync.sh --verify"
-  }
-}
-```
-
-## Workflow Examples
-
-### Scenario 1: Version Bump
-
-```bash
-# Developer updates package.json version
-npm version patch
-
-# Push to main
-git push origin main
-
-# GitHub Actions automatically:
-# 1. Detects version change
-# 2. Updates all markdown files
-# 3. Commits and pushes changes
-# 4. Verifies consistency
-```
-
-### Scenario 2: PR Review
-
-```bash
-# PR with package.json changes
-# GitHub Actions automatically:
-# 1. Checks version consistency
-# 2. Reports any mismatches
-# 3. Comments on PR with sync status
-# 4. Provides diff preview
-```
-
-### Scenario 3: Manual Sync
-
-```bash
-# Local development
-./scripts/version-sync.sh --dry-run  # Preview changes
-./scripts/version-sync.sh            # Apply changes
-./scripts/version-sync.sh --verify   # Confirm consistency
-```
-
-## File Detection Logic
-
-### Automatic Discovery
-
-The system automatically discovers files containing version references:
-
-```bash
-rg -l "v?[0-9]+\.[0-9]+\.[0-9]+" --type md
-```
-
-### Known Files
-
-These files are always included even if they don't currently contain versions:
-
-- `README.md`
-- `docs/reference/FEATURES.md`
-- Any file matching version patterns
-
-### Exclusions
-
-Files that are intentionally excluded:
-
-- `CHANGELOG.md` - May contain historical versions
-- `package.json` - Source of truth
-- `docs/security/COMPLIANCE.md` - Includes external compliance spec versions
-- `docs/reference/FONTS.md` - Includes upstream font release versions
-- `docs/archive/LEGACY_ROADMAP.md` - Keeps historical release markers
-- `docs/archive/PLAN.md` - Captures multi-release planning references
-- `docs/operations/VERSION_SYNC.md` - Documentation examples and usage
-- `docs/architecture/WALKTHROUGH.md` - Contains environment-specific tag examples
-- `docs/guides/WSL2_NIX_TROUBLESHOOTING.md` - Contains IP addresses and version-like values
-- Binary files
-- Test fixtures
-
-## Error Handling
-
-### Common Issues
-
-#### Version Mismatch
-
-```text
-❌ Found inconsistent release in docs/reference/FEATURES.md: vX.Y.Z (expected: vA.B.C)
-```
-
-**Solution**: Run `./scripts/version-sync.sh` to fix
-
-#### Missing Dependencies
-
-```text
-❌ jq is required but not installed
-```
-
-**Solution**: Install dependencies (`jq`, `rg`)
-
-#### Permission Issues
-
-```text
-❌ Permission denied writing to README.md
-```
-
-**Solution**: Check file permissions and Git status
-
-### Recovery Procedures
-
-#### Rollback Changes
-
-```bash
-# Restore from backup
-cp .version-sync-backup/README.md.*.backup README.md
-
-# Or restore from Git
-git checkout HEAD~1 -- README.md
-```
-
-#### Force Resync
-
-```bash
-./scripts/version-sync.sh --force
-```
-
-## Monitoring & Maintenance
-
-### Health Checks
-
-```bash
-# Daily verification (add to cron)
-./scripts/version-sync.sh --verify || echo "Version drift detected"
-```
-
-### Metrics Tracking
-
-The GitHub Actions workflow provides metrics:
-
-- Files scanned
-- Files updated
-- Verification status
-- Processing time
-
-### Backup Strategy
-
-- Local backups in `.version-sync-backup/`
-- GitHub Actions artifacts (30-day retention)
-- Git history for rollback
-
-## Security Considerations
-
-### Token Permissions
-
-```yaml
-permissions:
-  contents: write      # Required for commits
-  pull-requests: write # Required for PR comments
-```
-
-### Validation
-
-- Version format validation (`x.y.z` pattern)
-- File path validation (no directory traversal)
-- Change verification before commit
-
-### Audit Trail
-
-- All changes logged in Git history
-- GitHub Actions run history
-- Backup preservation
-
-## Performance Optimization
-
-### Caching Strategy
-
-- Git operations use shallow fetch when possible
-- Pattern compilation cached
-- File discovery optimized with `ripgrep`
-
-### Parallel Processing
-
-- File processing is sequential but optimized
-- Git operations batched
-- Verification runs concurrently with updates
-
-### Resource Usage
-
-- Typical run time: 30-60 seconds
-- Memory usage: <100MB
-- Network usage: Minimal (only Git operations)
-
-## Future Enhancements
-
-### Planned Features
-
-1. **Smart Version Detection** - Semantic version awareness
-2. **Template Support** - Custom version patterns
-3. **Multi-Format Support** - YAML, JSON, TOML files
-4. **Rollback Automation** - One-command rollback
-5. **Integration Testing** - End-to-end workflow tests
-
-### Extension Points
-
-- Custom pattern definitions
-- File-specific update rules
-- Pre/post-sync hooks
-- External validation services
-
-## Troubleshooting
-
-### Debug Mode
-
-```bash
-# Enable verbose output
-DEBUG=1 ./scripts/version-sync.sh --dry-run
-```
-
-### Common Solutions
-
-| Issue | Solution |
-|-------|----------|
-| Script not executable | `chmod +x scripts/version-sync.sh` |
-| Missing tools | `apt install jq ripgrep` (Ubuntu) |
-| Permission denied | Check Git status and file permissions |
-| Workflow not triggering | Verify `package.json` changes are in push |
-| Changes not committed | Check branch protection rules |
-
-### Log Analysis
-
-```bash
-# View GitHub Actions logs
-gh run list --workflow=sync-versions.yml
-gh run view <run-id> --log
-```
-
-## Contributing
-
-### Testing Changes
-
-```bash
-# Test local changes
-./scripts/version-sync.sh --dry-run
-
-# Test workflow changes (requires GitHub CLI)
-gh workflow run sync-versions.yml --ref feature-branch
-```
-
-### Adding New Patterns
-
-1. Update pattern regex in script
-2. Add test cases
-3. Update documentation
-4. Submit PR with examples
-
----
-
-**Last Updated**: 2026-02-15
-**Version**: v0.2.503
-**Maintainer**: Principal Automation Engineer
-**Status**: Production Ready ✅

package/docs/packaging.md

@@ -1,222 +0,0 @@
----
-render_with_liquid: false
----
-
-<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
-<!-- Copyright (c) 2015-2026 Sebastien Rousseau -->
-
-# Packaging guide
-
-**Audience: distribution maintainers.** If you are packaging `dot` for
-Debian, Fedora, Arch, Homebrew, nixpkgs, Scoop, or anything else, this
-page is written for you. Everything a packager normally has to
-reverse-engineer — the licence grant, the toolchain floor, how the
-dependencies are pinned, how to build and test offline, and how to
-verify what you downloaded — is here.
-
-Existing packaging inputs live in [`pkg/`](https://github.com/sebastienrousseau/dotfiles/tree/main/pkg),
-one directory per format.
-
-## What this software is
-
-A shell framework, not a compiled program. The shipped artefact is:
-
-- `bin/dot` — the CLI dispatcher (bash)
-- `lib/dot/`, `scripts/` — sourced bash libraries and subcommands
-- `share/man/man1/dot.1` — the man page, **generated** from the CLI's
-  command registry at build time
-- `share/{bash-completion,zsh,fish}/…` — completions, also generated
-- `defaults/` — the chezmoi source tree the CLI applies to `$HOME`
-
-There is nothing to compile and no architecture-specific output. The
-release archive is `noarch`/`any`.
-
-## Licence grant
-
-**`Apache-2.0 OR MIT`** — the SPDX expression declared in
-`package.json` and in `REUSE.toml`. Both full texts ship in the
-repository and in the release archive as `LICENSE-APACHE` and
-`LICENSE-MIT`, and `make install` places both under
-`$(PREFIX)/share/doc/dotfiles/`.
-
-This is a dual grant, not a conjunction: a downstream recipient may
-comply with **either** licence, at their option. For distributions
-that require a single choice, MIT is the permissive default; choose
-Apache-2.0 if you want the explicit patent grant.
-
-Per-file licensing is machine-readable via [REUSE](https://reuse.software/):
-`REUSE.toml` at the repository root annotates the tree, and
-`reuse lint` runs in CI. Vendored third-party material, where present,
-is annotated separately and keeps its own licence.
-
-## Minimum toolchain
-
-Full policy, per-distro mapping, and the rules for when a floor may
-rise: [`MINIMUM-TOOLCHAIN.md`](MINIMUM-TOOLCHAIN.md). The short form
-for a packaging recipe:
-
-| Dependency | Minimum | Kind |
-|---|---|---|
-| `bash` | 3.2 | **required at runtime** |
-| `git` | 2.34 | required at runtime |
-| `curl` | any | required by the bootstrap path only |
-| `chezmoi` | 2.47.1 | **required at runtime** — the CLI is a control plane over chezmoi |
-| `zsh` / `fish` / `nushell` | 5.8 / 4.0 / 0.98 | optional; only if the user wants that shell's integration |
-| `jq`, `gum`, `starship`, `fzf` | any | optional; enable JSON output, rich prompts, and interactive pickers |
-| `go` | 1.23 | **build/test only** — fuzz harnesses and the two Go TUIs. Not needed to build or run the package. |
-
-Suggested dependency split for a distro package: `Depends: bash (>= 3.2),
-git (>= 2.34), chezmoi (>= 2.47.1)`; `Recommends: jq, zsh`;
-`Suggests: fish, nushell, gum, starship, fzf`.
-
-## Dependency pin model
-
-Every dependency this project *builds and tests against* is pinned,
-and every pin is committed:
-
-| Surface | Pinned by | Notes |
-|---|---|---|
-| Development toolchain (node, go, rust, and ~20 CLI tools) | `mise.toml` + `mise.lock` + `mise-versions.lock.json` | mise is the package manager; the lock carries checksums |
-| Documentation build (Python) | `requirements-docs.txt` | Hash-pinned (`--require-hashes`-compatible), compiled from `requirements-docs.in` |
-| Node tooling | `package.json` | Dev-only |
-| Nix | `flake.lock`, `nix/flake.lock` | Root flake provides the dev shell; `nix/flake.nix` provides `packages.default` |
-| GitHub Actions | 40-hex commit SHA on every `uses:` | Enforced by `tools/ci/lint-reusable-pins.sh` and OpenSSF Scorecard |
-| Container bases | `FROM image:tag@sha256:<digest>` | Policy in [`security/CI_PINNING.md`](security/CI_PINNING.md) |
-| Binaries fetched during CI | `sha256sum -c` against a committed manifest | `security/remote-installers.sha256` |
-
-None of these are needed to *build the package*: the release archive
-is self-contained and its build has no network step. They exist so
-that the tests you may want to run are reproducible.
-
-Full provenance policy: [`supply-chain/README.md`](https://github.com/sebastienrousseau/dotfiles/blob/main/supply-chain/README.md).
-
-## Building the package
-
-From a release tarball (recommended — it is the attested artefact):
-
-```sh
-tar -xzf dot-0.2.520.tar.gz
-cd dot-0.2.520
-make install PREFIX=/usr DESTDIR="$pkgdir"
-```
-
-From a git checkout:
-
-```sh
-make                                   # generates man page + completions into build/
-make install PREFIX=/usr DESTDIR="$pkgdir"
-```
-
-Both honour `PREFIX` (default `/usr/local`) and `DESTDIR`, and install
-to FHS paths:
-
-```
-$(DESTDIR)$(PREFIX)/bin/dot                                  -> symlink into libexec
-$(DESTDIR)$(PREFIX)/lib/dotfiles/                            program tree
-$(DESTDIR)$(PREFIX)/share/man/man1/dot.1
-$(DESTDIR)$(PREFIX)/share/bash-completion/completions/dot
-$(DESTDIR)$(PREFIX)/share/zsh/site-functions/_dot
-$(DESTDIR)$(PREFIX)/share/fish/vendor_completions.d/dot.fish
-$(DESTDIR)$(PREFIX)/share/doc/dotfiles/{LICENSE-APACHE,LICENSE-MIT,README.md,CHANGELOG.md}
-```
-
-Every directory is individually overridable — `BINDIR`, `MANDIR`,
-`DOCDIR`, `LIBEXECDIR`, `BASHCOMPDIR`, `ZSHCOMPDIR`, `FISHCOMPDIR` —
-for distributions whose layout differs. If your `BINDIR` and
-`LIBEXECDIR` are not siblings under `PREFIX`, also set `DOT_LINK` to
-the correct relative or absolute symlink target; `make install` fails
-loudly rather than leaving a dangling link.
-
-`make uninstall` removes exactly what `make install` placed.
-
-## Testing offline
-
-There are no vendored build dependencies to unbundle, and the checks a
-packager cares about need no network:
-
-```sh
-make installcheck DESTDIR="$pkgdir"    # asserts the installed tree is complete and runs
-make -C "$pkgdir" smoke                # from a release tarball: run the CLI in place
-```
-
-`installcheck` verifies the `bin` symlink resolves, the man page and
-all three completions are present, the licences are installed, and the
-installed binary reports the expected version and renders help — from
-a sandboxed `HOME`, with no source checkout and no network.
-
-The full suite also runs offline:
-
-```sh
-make test           # unit + regression; no network
-make examples       # every example under examples/ executed
-```
-
-`make test-integration` and anything under `install/provision/` **do**
-touch the network and modify `$HOME`; do not run them in a build
-chroot.
-
-## Verifying what you downloaded
-
-Do not package an unverified tarball. Every release carries four
-independent attestations, and the consumer-side recipe with copy-paste
-commands is in
-[`pkg/VERIFY.md`](https://github.com/sebastienrousseau/dotfiles/blob/main/pkg/VERIFY.md)
-and [`security/VERIFY_RELEASE.md`](security/VERIFY_RELEASE.md).
-
-Minimum a packager should do:
-
-```sh
-TAG=v0.2.520
-REPO=sebastienrousseau/dotfiles
-
-# SLSA build provenance on the tarball itself
-gh attestation verify "dot-${TAG#v}.tar.gz" --repo "$REPO"
-
-# Or, without the gh CLI: the signed manifest covering every asset
-gh release download "$TAG" --repo "$REPO" \
-  --pattern ALL_SHA256SUMS --pattern 'ALL_SHA256SUMS.*'
-cosign verify-blob \
-  --certificate ALL_SHA256SUMS.pem --signature ALL_SHA256SUMS.sig \
-  --certificate-identity-regexp "^https://github.com/$REPO/" \
-  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
-  ALL_SHA256SUMS
-sha256sum -c ALL_SHA256SUMS
-```
-
-Tags are signed with an SSH ed25519 key published in
-[`KEYS.asc`](https://github.com/sebastienrousseau/dotfiles/blob/main/KEYS.asc),
-which is itself a `git allowed_signers` file:
-
-```sh
-git -c gpg.ssh.allowedSignersFile=KEYS.asc tag -v v0.2.520
-```
-
-An SBOM ships with every release in both CycloneDX and SPDX JSON.
-
-## Reproducibility
-
-The release archives are built deterministically — `tar --sort=name
---mtime='1970-01-01' --owner=0 --group=0 --numeric-owner`, and
-`zip -X -D` over a normalised tree — so two builds of the same tag
-produce identical bytes.
-
-This is a statement about the *archive build*, which is exercised by
-CI on every release. It is **not** a verified end-to-end
-reproducible-builds claim: no diffoscope comparison of two independent
-rebuilds runs in CI today. Treat it as "deterministic archiving",
-not as a reproducible-builds certification.
-
-## Channel notes
-
-| Channel | File | How it is produced |
-|---|---|---|
-| Homebrew | `pkg/brew/dot.rb` | `release-distribute-homebrew.yml` rewrites `url` + `sha256`, opens a PR on `sebastienrousseau/homebrew-tap` |
-| Scoop | `pkg/scoop/dot.json` | `release-distribute-scoop.yml` rewrites version + hashes via `jq`, opens a PR on `sebastienrousseau/scoop-bucket` |
-| AUR | `pkg/aur/PKGBUILD` | `release-distribute-aur.yml` rewrites `pkgver` + `sha256sums`, regenerates `.SRCINFO`, pushes to the AUR |
-| Nix | `pkg/nix/` → `nix/flake.nix` | `packages.default` in `nix/flake.nix` |
-| deb / rpm | *not yet provided* | Contributions welcome; `make install` already produces a correct `DESTDIR` tree, so a recipe is thin |
-
-If you are packaging for a distribution not listed here, please open
-an issue — a link to your package will be added, and the `pkg/`
-directory is the right place for the recipe to live so it stays in
-lockstep with the release build.