@alexgorbatchev/dotfiles 0.0.1

package/skill/references/installation-methods/brew.md

@@ -0,0 +1,62 @@
+# Homebrew Installation
+
+Install tools using Homebrew package manager on macOS and Linux.
+
+Shims are not supported for Homebrew-installed tools. The `.bin()` method should not be used with this installer. Homebrew manages binary placement and PATH integration natively.
+
+## Basic Usage
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) => install('brew', { formula: 'ripgrep' }));
+```
+
+## Parameters
+
+| Parameter      | Description                                         |
+| -------------- | --------------------------------------------------- |
+| `formula`      | Formula or cask name (defaults to tool name)        |
+| `cask`         | Set `true` for cask installation                    |
+| `tap`          | Tap(s) to add before installing                     |
+| `versionArgs`  | Arguments for version check (e.g., `['--version']`) |
+| `versionRegex` | Regex to extract version from output                |
+| `env`          | Environment variables (static or dynamic function)  |
+
+## Examples
+
+### Homebrew Cask
+
+```typescript
+install('brew', {
+  formula: 'visual-studio-code',
+  cask: true,
+});
+```
+
+### With Custom Tap
+
+```typescript
+install('brew', {
+  formula: 'aerospace',
+  cask: true,
+  tap: 'nikitabobko/tap',
+});
+```
+
+### Multiple Taps
+
+```typescript
+install('brew', {
+  formula: 'custom-tool',
+  tap: ['custom/tap', 'another/tap'],
+});
+```
+
+## Platform Support
+
+| Platform | Support                 |
+| -------- | ----------------------- |
+| macOS    | Full (formulas + casks) |
+| Linux    | Formulas only           |
+| Windows  | Not supported           |

package/skill/references/installation-methods/cargo.md

@@ -0,0 +1,86 @@
+# Cargo Installation
+
+Installs Rust tools from crates.io using pre-compiled binaries via cargo-quickinstall or GitHub releases.
+
+## Basic Usage
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install('cargo', {
+    crateName: 'ripgrep',
+  }).bin('rg')
+);
+```
+
+## Parameters
+
+| Parameter        | Type                                               | Required | Description                                            |
+| ---------------- | -------------------------------------------------- | -------- | ------------------------------------------------------ |
+| `crateName`      | `string`                                           | Yes      | Name of the Rust crate                                 |
+| `binarySource`   | `'cargo-quickinstall' \| 'github-releases'`        | No       | Binary download source (default: `cargo-quickinstall`) |
+| `versionSource`  | `'cargo-toml' \| 'crates-io' \| 'github-releases'` | No       | Version detection source (default: `cargo-toml`)       |
+| `githubRepo`     | `string`                                           | No       | GitHub repo in `owner/repo` format                     |
+| `assetPattern`   | `string`                                           | No       | Pattern for GitHub release assets                      |
+| `cargoTomlUrl`   | `string`                                           | No       | Custom Cargo.toml URL                                  |
+| `customBinaries` | `string[]`                                         | No       | Custom binary names if different from crate            |
+| `env`            | `Record<string, string> \| (ctx) => Record<...>`   | No       | Environment variables (static or dynamic function)     |
+
+### Asset Pattern Placeholders
+
+| Placeholder   | Description          |
+| ------------- | -------------------- |
+| `{version}`   | Resolved version     |
+| `{platform}`  | Current platform     |
+| `{arch}`      | Current architecture |
+| `{crateName}` | Crate name           |
+
+## Examples
+
+### From GitHub Releases
+
+```typescript
+export default defineTool((install, ctx) =>
+  install('cargo', {
+    crateName: 'bat',
+    binarySource: 'github-releases',
+    githubRepo: 'sharkdp/bat',
+    assetPattern: 'bat-v{version}-{arch}-{platform}.tar.gz',
+  }).bin('bat')
+);
+```
+
+### Custom Binary Names
+
+```typescript
+export default defineTool((install, ctx) =>
+  install('cargo', {
+    crateName: 'fd-find',
+    customBinaries: ['fd'],
+  }).bin('fd')
+);
+```
+
+### With Hooks
+
+```typescript
+export default defineTool((install, ctx) =>
+  install('cargo', {
+    crateName: 'tool',
+  })
+    .bin('tool')
+    .hook('after-install', async (ctx) => {
+      // Post-installation setup
+    })
+);
+```
+
+## Platform Mapping
+
+| System | Architecture | Rust Target Triple          |
+| ------ | ------------ | --------------------------- |
+| macOS  | arm64        | `aarch64-apple-darwin`      |
+| macOS  | x64          | `x86_64-apple-darwin`       |
+| Linux  | x64          | `x86_64-unknown-linux-gnu`  |
+| Linux  | arm64        | `aarch64-unknown-linux-gnu` |

package/skill/references/installation-methods/curl-binary.md

@@ -0,0 +1,73 @@
+# Curl Binary Installation
+
+Download standalone binary files directly from URLs. Unlike `curl-tar`, this method does **not** extract an archive — the downloaded file is the binary itself.
+
+## Basic Usage
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) =>
+  install('curl-binary', {
+    url: 'https://example.com/tool-v1.0.0-linux-amd64',
+  }).bin('tool')
+);
+```
+
+## Parameters
+
+| Parameter      | Description                                         |
+| -------------- | --------------------------------------------------- |
+| `url`          | **Required**. Direct URL to the binary file         |
+| `versionArgs`  | Arguments for version check (e.g., `['--version']`) |
+| `versionRegex` | Regex to extract version from output                |
+| `env`          | Environment variables (static or dynamic function)  |
+
+## Examples
+
+### With Version Detection
+
+```typescript
+install('curl-binary', {
+  url: 'https://example.com/tool-v1.0.0-linux-amd64',
+  versionArgs: ['--version'],
+  versionRegex: 'v(\\d+\\.\\d+\\.\\d+)',
+}).bin('tool');
+```
+
+### With Shell Configuration
+
+```typescript
+install('curl-binary', {
+  url: 'https://example.com/tool-v1.0.0-linux-amd64',
+})
+  .bin('tool')
+  .zsh((shell) => shell.aliases({ t: 'tool' }));
+```
+
+### Platform-Specific URLs
+
+```typescript
+import { Architecture, defineTool, Platform } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) =>
+  install()
+    .bin('tool')
+    .platform(Platform.MacOS, Architecture.Arm64, (install) =>
+      install('curl-binary', {
+        url: 'https://example.com/tool-darwin-arm64',
+      }))
+    .platform(Platform.Linux, Architecture.X86_64, (install) =>
+      install('curl-binary', {
+        url: 'https://example.com/tool-linux-amd64',
+      }))
+);
+```
+
+## When to Use
+
+- Direct binary file downloads (single executable, no archive)
+- Tools that distribute platform-specific binaries as standalone files
+- Single-file Go or Rust binaries provided as direct downloads
+
+Prefer `github-release` when GitHub releases are available. Prefer `curl-tar` when the download is an archive.

package/skill/references/installation-methods/curl-script.md

@@ -0,0 +1,132 @@
+# Curl Script Installation
+
+Downloads and executes shell installation scripts.
+
+## Basic Usage
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install('curl-script', {
+    url: 'https://bun.sh/install',
+    shell: 'bash',
+  }).bin('bun')
+);
+```
+
+## Parameters
+
+| Parameter      | Type                                             | Required | Description                               |
+| -------------- | ------------------------------------------------ | -------- | ----------------------------------------- |
+| `url`          | `string`                                         | Yes      | URL of the installation script            |
+| `shell`        | `'bash' \| 'sh'`                                 | Yes      | Shell interpreter to use                  |
+| `args`         | `string[] \| (ctx) => string[]`                  | No       | Arguments to pass to the script           |
+| `env`          | `Record<string, string> \| (ctx) => Record<...>` | No       | Environment variables (static or dynamic) |
+| `versionArgs`  | `string[]`                                       | No       | Args to pass to binary for version check  |
+| `versionRegex` | `string`                                         | No       | Regex to extract version from output      |
+
+> **Note:** The `env` and `args` parameters support both static values and dynamic functions. Dynamic functions receive a context with `projectConfig`, `scriptPath`, and `stagingDir`.
+
+## Understanding `stagingDir`
+
+When the curl-script installer runs, it creates a temporary **staging directory** where the installation takes place. This is critical to understand because:
+
+1. **The system expects binaries in `stagingDir`** - After your installation script completes, the tool installer looks for the declared binaries (from `.bin()`) inside `stagingDir`. If they are not there, installation fails.
+
+2. **`stagingDir` becomes the versioned directory** - After successful installation, the entire staging directory is renamed to the final versioned path (e.g., `~/.dotfiles/tools/fnm/1.2.3`). All files in `stagingDir` are preserved.
+
+3. **Most scripts need to be redirected** - By default, installation scripts install to their own preferred locations (like `~/.local/bin` or `~/.<tool>`). You must redirect them to `stagingDir` using the script's configuration options.
+
+### How to Redirect Installation
+
+Check the installation script's source to find the right argument or environment variable:
+
+```bash
+# Download and inspect the script
+curl -fsSL https://fly.io/install.sh | less
+
+# Look for variables like:
+# INSTALL_DIR, PREFIX, BIN_DIR, FLYCTL_INSTALL, etc.
+```
+
+Then use `args` or `env` with the dynamic context to redirect:
+
+```typescript
+// Using args (if script accepts command-line arguments)
+args: ((ctx) => ['--install-dir', ctx.stagingDir]);
+
+// Using env (if script reads environment variables)
+env: ((ctx) => ({ FLYCTL_INSTALL: ctx.stagingDir }));
+```
+
+## Examples
+
+### With Static Arguments
+
+```typescript
+export default defineTool((install, ctx) =>
+  install('curl-script', {
+    url: 'https://fnm.vercel.app/install',
+    shell: 'bash',
+    args: ['--skip-shell', '--install-dir', '$LOCAL_BIN'],
+  }).bin('fnm')
+);
+```
+
+### With Dynamic Arguments
+
+```typescript
+export default defineTool((install, ctx) =>
+  install('curl-script', {
+    url: 'https://fnm.vercel.app/install',
+    shell: 'bash',
+    args: (argsCtx) => ['--install-dir', argsCtx.stagingDir],
+  }).bin('fnm')
+);
+```
+
+The `args` function receives a context with:
+
+- `projectConfig` - Project configuration with paths and settings
+- `scriptPath` - Absolute path to the downloaded script (in `stagingDir`, already chmod +x)
+- `stagingDir` - Temporary directory for this installation attempt. The script is downloaded here, along with any files your code creates. After successful installation, the entire directory is renamed to the versioned path (e.g., `<tool-name>/1.2.3`), preserving all contents.
+
+### With Environment Variables
+
+Use dynamic `env` to redirect installation to `stagingDir`:
+
+```typescript
+export default defineTool((install, ctx) =>
+  install('curl-script', {
+    url: 'https://fly.io/install.sh',
+    shell: 'sh',
+    env: (ctx) => ({ FLYCTL_INSTALL: ctx.stagingDir }),
+  }).bin('flyctl', 'fly')
+);
+```
+
+Note: The fly.io script installs `flyctl` as the main binary. The second argument to `.bin()` creates `fly` as a symlink alias.
+
+The `env` context provides:
+
+- `projectConfig` - Project configuration with paths and settings
+- `stagingDir` - Temporary directory for installation (becomes versioned path after success)
+- `scriptPath` - Absolute path to the downloaded script (curl-script specific)
+
+### With Hooks
+
+```typescript
+export default defineTool((install, ctx) =>
+  install('curl-script', {
+    url: 'https://example.com/install.sh',
+    shell: 'bash',
+  })
+    .bin('tool')
+    .hook('after-download', async (ctx) => {
+      // Verify script before execution
+    })
+);
+```
+
+**Security Note**: Curl scripts execute arbitrary code. Only use trusted sources with HTTPS URLs.

package/skill/references/installation-methods/curl-tar.md

@@ -0,0 +1,58 @@
+# Curl Tar Installation
+
+Download and extract tarballs directly from URLs.
+
+## Basic Usage
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) =>
+  install('curl-tar', {
+    url: 'https://example.com/tool.tar.gz',
+  }).bin('tool')
+);
+```
+
+## Parameters
+
+| Parameter         | Description                                         |
+| ----------------- | --------------------------------------------------- |
+| `url`             | **Required**. Direct URL to the tarball             |
+| `extractPath`     | Path to binary within extracted archive             |
+| `stripComponents` | Directory levels to strip during extraction         |
+| `versionArgs`     | Arguments for version check (e.g., `['--version']`) |
+| `versionRegex`    | Regex to extract version from output                |
+| `env`             | Environment variables (static or dynamic function)  |
+
+## Examples
+
+### Binary in Subdirectory
+
+```typescript
+install('curl-tar', {
+  url: 'https://releases.example.com/tool-v1.0.0.tar.gz',
+}).bin('tool', 'bin/tool'); // Binary at bin/tool in archive
+```
+
+### With Shell Configuration
+
+```typescript
+install('curl-tar', {
+  url: 'https://releases.example.com/tool-v1.0.0.tar.gz',
+})
+  .bin('tool')
+  .zsh((shell) => shell.aliases({ t: 'tool' }));
+```
+
+## Supported Formats
+
+`.tar.gz`, `.tgz`, `.tar.bz2`, `.tbz2`, `.tar.xz`, `.txz`, `.tar`
+
+## When to Use
+
+- Direct tarball downloads from known URLs
+- Tools without GitHub releases
+- Simple archive structures
+
+Prefer `github-release` when GitHub releases are available.

package/skill/references/installation-methods/dmg.md

@@ -0,0 +1,113 @@
+# DMG Installation
+
+Install macOS applications distributed as DMG disk images. The plugin mounts the DMG, copies the `.app` bundle to `/Applications`, and is silently skipped on non-macOS platforms.
+
+The DMG source is configured via a required `source` object. Sources can be direct URLs or GitHub releases.
+
+If the resolved source points to a supported archive (`.zip`, `.tar.gz`, etc.) containing a `.dmg` file, the archive is automatically extracted first. This is common for GitHub releases that compress DMGs into zip files.
+
+DMG is externally managed. Temporary files (download, mount point, optional archive extraction) use `stagingDir`, but the final `.app` is installed to `/Applications`.
+
+Shims are not supported for DMG-installed applications. The `.bin()` method should not be used with this installer.
+
+## Basic Usage
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) =>
+  install('dmg', {
+    source: {
+      type: 'url',
+      url: 'https://example.com/MyApp-1.0.0.dmg',
+    },
+  })
+);
+```
+
+## Parameters
+
+| Parameter      | Description                                                                    |
+| -------------- | ------------------------------------------------------------------------------ |
+| `source`       | **Required**. DMG source definition (see source variants below)                |
+| `appName`      | Name of the `.app` bundle (e.g., `'MyApp.app'`). Auto-detected if omitted      |
+| `binaryPath`   | Relative path to binary inside `.app`. Defaults to `Contents/MacOS/{bin name}` |
+| `versionArgs`  | Arguments for version check (e.g., `['--version']`)                            |
+| `versionRegex` | Regex to extract version from output                                           |
+| `env`          | Environment variables (static or dynamic function)                             |
+
+### Source Variants
+
+| Source type      | Required fields | Optional fields                                                   | Notes                                                    |
+| ---------------- | --------------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
+| `url`            | `url`           | —                                                                 | Direct DMG URL or archive URL containing a DMG           |
+| `github-release` | `repo`          | `version`, `assetPattern`, `assetSelector`, `ghCli`, `prerelease` | Resolves release asset first, then installs from the DMG |
+
+## Examples
+
+### Explicit App Name
+
+```typescript
+install('dmg', {
+  source: {
+    type: 'url',
+    url: 'https://example.com/MyApp-1.0.0.dmg',
+  },
+  appName: 'MyApp.app',
+}).version('1.0.0');
+```
+
+### From Archive Containing DMG
+
+```typescript
+install('dmg', {
+  source: {
+    type: 'url',
+    url: 'https://github.com/example/app/releases/download/v1.0.0/MyApp.dmg.zip',
+  },
+});
+```
+
+### GitHub Release Source
+
+```typescript
+install('dmg', {
+  source: {
+    type: 'github-release',
+    repo: 'manaflow-ai/cmux',
+    assetPattern: '*macos*.dmg',
+  },
+  appName: 'cmux.app',
+});
+```
+
+### With Version Detection
+
+```typescript
+install('dmg', {
+  source: {
+    type: 'url',
+    url: 'https://example.com/MyApp-1.0.0.dmg',
+  },
+  versionArgs: ['--version'],
+  versionRegex: 'v(\\d+\\.\\d+\\.\\d+)',
+});
+```
+
+## Platform Behavior
+
+| Platform | Behavior                                  |
+| -------- | ----------------------------------------- |
+| macOS    | Full installation via hdiutil             |
+| Linux    | Silently skipped (returns empty binaries) |
+| Windows  | Silently skipped (returns empty binaries) |
+
+No `.platform()` wrapper is needed — the plugin handles platform detection internally.
+
+## When to Use
+
+- macOS applications distributed as `.dmg` disk images
+- Tools that ship as `.app` bundles
+- GitHub releases that distribute `.dmg` files inside `.zip` or `.tar.gz` archives
+
+Prefer `brew` when the tool is available as a Homebrew formula or cask. Prefer `curl-binary` or `github-release` for cross-platform tools.

package/skill/references/installation-methods/gitea-release.md

@@ -0,0 +1,106 @@
+# Gitea/Forgejo Release Installation
+
+Download and install tools from Gitea or Forgejo instance releases with automatic platform asset selection. Supports any Gitea-compatible instance including Codeberg, Forgejo, and self-hosted Gitea.
+
+## Basic Usage
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) =>
+  install('gitea-release', {
+    instanceUrl: 'https://codeberg.org',
+    repo: 'Codeberg/pages-server',
+  }).bin('pages-server')
+);
+```
+
+## Parameters
+
+| Parameter       | Description                                               |
+| --------------- | --------------------------------------------------------- |
+| `instanceUrl`   | **Required**. Base URL of the Gitea/Forgejo instance      |
+| `repo`          | **Required**. Repository in "owner/repo" format           |
+| `assetPattern`  | Glob or regex pattern to match release assets             |
+| `assetSelector` | Custom function to select the correct asset               |
+| `version`       | Specific version (e.g., `'v1.2.3'`)                       |
+| `prerelease`    | Include prereleases when fetching latest (default: false) |
+| `token`         | API token for authentication with the instance            |
+| `env`           | Environment variables (static or dynamic function)        |
+
+## Examples
+
+### With Asset Pattern
+
+```typescript
+install('gitea-release', {
+  instanceUrl: 'https://codeberg.org',
+  repo: 'owner/tool',
+  assetPattern: '*linux_amd64.tar.gz',
+}).bin('tool');
+```
+
+### Custom Asset Selector
+
+```typescript
+install('gitea-release', {
+  instanceUrl: 'https://codeberg.org',
+  repo: 'owner/tool',
+  assetSelector: ({ assets, systemInfo }) => {
+    const platform = systemInfo.platform === 'darwin' ? 'macos' : systemInfo.platform;
+    return assets.find((a) => a.name.includes(platform));
+  },
+}).bin('tool');
+```
+
+### Specific Version
+
+```typescript
+install('gitea-release', {
+  instanceUrl: 'https://codeberg.org',
+  repo: 'owner/tool',
+  version: 'v2.1.0',
+}).bin('tool');
+```
+
+### With Authentication Token
+
+For private repositories or to avoid rate limits:
+
+```typescript
+install('gitea-release', {
+  instanceUrl: 'https://gitea.example.com',
+  repo: 'org/private-tool',
+  token: process.env.GITEA_TOKEN,
+}).bin('tool');
+```
+
+## Asset Pattern Matching
+
+| Pattern                | Matches             |
+| ---------------------- | ------------------- |
+| `*linux*amd64*.tar.gz` | Linux x64 tarballs  |
+| `*darwin*arm64*.zip`   | macOS ARM64 zips    |
+| `*windows*.exe`        | Windows executables |
+
+Glob syntax: `*` (any chars), `?` (single char), `[abc]` (char class), `{a,b}` (alternation)
+
+Regex patterns can also be used by wrapping in forward slashes: `/tool-v\d+.*linux/`
+
+## Platform Detection
+
+Available in `assetSelector` as `systemInfo`:
+
+| Property   | Values                     |
+| ---------- | -------------------------- |
+| `platform` | `darwin`, `linux`, `win32` |
+| `arch`     | `x64`, `arm64`             |
+
+## Supported Instances
+
+Any server running the Gitea API v1 is supported:
+
+- Codeberg — Free hosting for open source projects
+- Forgejo — Community fork of Gitea
+- Gitea — Self-hosted Git service
+- Self-hosted instances