@alexgorbatchev/dotfiles 0.0.1

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

@@ -0,0 +1,97 @@
+# GitHub Release Installation
+
+Download and install tools from GitHub releases with automatic platform asset selection.
+
+## Basic Usage
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) => install('github-release', { repo: 'junegunn/fzf' }).bin('fzf'));
+```
+
+## Parameters
+
+| Parameter       | Description                                               |
+| --------------- | --------------------------------------------------------- |
+| `repo`          | **Required**. GitHub repository in "owner/repo" format    |
+| `assetPattern`  | Glob 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) |
+| `githubHost`    | Custom GitHub API host for Enterprise                     |
+| `ghCli`         | Use `gh` CLI for API requests instead of fetch            |
+| `env`           | Environment variables (static or dynamic function)        |
+
+## Examples
+
+### With Asset Pattern
+
+```typescript
+install('github-release', {
+  repo: 'sharkdp/bat',
+  assetPattern: '*linux_amd64.tar.gz',
+}).bin('bat');
+```
+
+### Custom Asset Selector
+
+```typescript
+install('github-release', {
+  repo: 'example/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('github-release', {
+  repo: 'owner/tool',
+  version: 'v2.1.0',
+}).bin('tool');
+```
+
+### Using gh CLI
+
+Use the `gh` CLI for API requests instead of fetch. Useful when working behind proxies or leveraging existing `gh` authentication:
+
+```typescript
+install('github-release', {
+  repo: 'owner/tool',
+  ghCli: true,
+}).bin('tool');
+```
+
+### Including Prereleases
+
+By default, GitHub's "latest" excludes prereleases. Use `prerelease: true` for repos that only publish prerelease versions:
+
+```typescript
+install('github-release', {
+  repo: 'owner/nightly-only-tool',
+  prerelease: true,
+}).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)
+
+## Platform Detection
+
+Available in `assetSelector` as `systemInfo`:
+
+| Property   | Values                     |
+| ---------- | -------------------------- |
+| `platform` | `darwin`, `linux`, `win32` |
+| `arch`     | `x64`, `arm64`             |

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

@@ -0,0 +1,74 @@
+# Manual Installation
+
+Installs files from your tool configuration directory (custom scripts, pre-built binaries) or registers configuration-only tools. The `manual` method can be called with or without params.
+
+## Basic Usage
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+// Install a custom script
+export default defineTool((install, ctx) =>
+  install('manual', {
+    binaryPath: './scripts/my-tool.sh',
+  }).bin('my-tool')
+);
+
+// Without params (shell-only or dependency wrapper)
+export default defineTool((install) =>
+  install('manual')
+    .bin('tokscale')
+    .dependsOn('bun')
+    .zsh((shell) =>
+      shell.functions({
+        tokscale: `bun x tokscale@latest`,
+      })
+    )
+);
+
+// Configuration-only tool (no binary)
+export default defineTool((install, ctx) => install().zsh((shell) => shell.aliases({ ll: 'ls -la' })));
+```
+
+## Parameters
+
+| Parameter    | Type                                             | Required | Description                                        |
+| ------------ | ------------------------------------------------ | -------- | -------------------------------------------------- |
+| `binaryPath` | `string`                                         | No       | Path to binary relative to `.tool.ts` file         |
+| `env`        | `Record<string, string> \| (ctx) => Record<...>` | No       | Environment variables (static or dynamic function) |
+
+## Examples
+
+### Pre-built Binary
+
+```typescript
+export default defineTool((install, ctx) =>
+  install('manual', {
+    binaryPath: './binaries/linux/x64/custom-tool',
+  }).bin('custom-tool')
+);
+```
+
+### Configuration-Only Tool
+
+```typescript
+export default defineTool((install, ctx) => install().zsh((shell) => shell.aliases({ ll: 'ls -la', la: 'ls -A' })));
+```
+
+### With Shell Configuration
+
+```typescript
+export default defineTool((install, ctx) =>
+  install('manual', {
+    binaryPath: './bin/my-tool.sh',
+  })
+    .bin('my-tool')
+    .zsh((shell) => shell.aliases({ mt: 'my-tool' }).completions('./completions/_my-tool'))
+);
+```
+
+**Notes:**
+
+- Binary paths are relative to the tool configuration file location
+- Files are copied to the managed installation directory with executable permissions
+- Configuration-only tools use `install()` with no arguments and must not define `.bin()`

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

@@ -0,0 +1,75 @@
+# npm Installation
+
+Install tools published as npm packages. Supports both `npm` and `bun` as package managers.
+
+## Basic Usage
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) => install('npm', { package: 'prettier' }).bin('prettier'));
+```
+
+## Parameters
+
+| Parameter        | Type                                             | Required | Description                                                   |
+| ---------------- | ------------------------------------------------ | -------- | ------------------------------------------------------------- |
+| `package`        | `string`                                         | No       | npm package name (defaults to tool name)                      |
+| `version`        | `string`                                         | No       | Version or version range (e.g., `3.0.0`, defaults to latest)  |
+| `packageManager` | `'npm' \| 'bun'`                                 | No       | Package manager to use for installation (defaults to `'npm'`) |
+| `versionArgs`    | `string[]`                                       | No       | Arguments for version check (e.g., `['--version']`)           |
+| `versionRegex`   | `string`                                         | No       | Regex to extract version from output                          |
+| `env`            | `Record<string, string> \| (ctx) => Record<...>` | No       | Environment variables (static or dynamic function)            |
+
+## Examples
+
+### Specific Version
+
+```typescript
+export default defineTool((install) =>
+  install('npm', {
+    package: 'prettier',
+    version: '3.0.0',
+  }).bin('prettier')
+);
+```
+
+### Using Bun
+
+```typescript
+export default defineTool((install) =>
+  install('npm', {
+    package: 'prettier',
+    packageManager: 'bun',
+  }).bin('prettier')
+);
+```
+
+### Scoped Package
+
+```typescript
+export default defineTool((install) =>
+  install('npm', {
+    package: '@angular/cli',
+  }).bin('ng')
+);
+```
+
+### Custom Version Detection
+
+```typescript
+export default defineTool((install) =>
+  install('npm', {
+    package: 'typescript',
+    versionArgs: ['--version'],
+    versionRegex: '(\\d+\\.\\d+\\.\\d+)',
+  }).bin('tsc')
+);
+```
+
+## How It Works
+
+1. **Install**: Runs `npm install --prefix <stagingDir> <package>[@version]` (or `bun add --cwd <stagingDir> <package>[@version]` when `packageManager: 'bun'`)
+2. **Binaries**: Resolved from `node_modules/.bin/` in the install directory
+3. **Version**: Detected via `npm ls --json` (npm), `node_modules/<package>/package.json` (bun), or custom `versionArgs`/`versionRegex`
+4. **Updates**: Checked via `npm view <package> version` (regardless of package manager)

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

@@ -0,0 +1,293 @@
+# Installation Methods Overview
+
+The system supports multiple installation methods to accommodate different tool distribution patterns. Each method has its own parameters and use cases.
+
+## Available Methods
+
+### GitHub Release
+
+Install tools from GitHub releases with automatic asset selection and extraction.
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install('github-release', {
+    repo: 'owner/repository',
+  }).bin('tool')
+);
+```
+
+### Gitea/Forgejo Release
+
+Install tools from Gitea, Forgejo, or Codeberg releases with automatic asset selection.
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install('gitea-release', {
+    instanceUrl: 'https://codeberg.org',
+    repo: 'owner/repository',
+  }).bin('tool')
+);
+```
+
+### Homebrew
+
+Install tools using Homebrew package manager (macOS and Linux).
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install('brew', {
+    formula: 'ripgrep',
+  }).bin('rg')
+);
+```
+
+### Cargo
+
+Install Rust tools from crates.io with cargo-quickinstall for faster downloads.
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install('cargo', {
+    crateName: 'ripgrep',
+  }).bin('rg')
+);
+```
+
+### npm
+
+Install tools published as npm packages.
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install('npm', {
+    package: 'prettier',
+  }).bin('prettier')
+);
+```
+
+### Curl Script
+
+Download and execute installation scripts.
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install('curl-script', {
+    url: 'https://bun.sh/install',
+    shell: 'bash',
+  }).bin('bun')
+);
+```
+
+### Curl Tar
+
+Download and extract tarballs directly from URLs.
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install('curl-tar', {
+    url: 'https://releases.example.com/tool-v1.0.0.tar.gz',
+  }).bin('tool')
+);
+```
+
+### Curl Binary
+
+Download standalone binary files directly from URLs (no archive extraction).
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install('curl-binary', {
+    url: 'https://example.com/tool-v1.0.0-linux-amd64',
+  }).bin('tool')
+);
+```
+
+### DMG
+
+Install macOS applications from DMG disk images into `/Applications` (silently skipped on other platforms).
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install('dmg', {
+    source: {
+      type: 'url',
+      url: 'https://example.com/MyApp-1.0.0.dmg',
+    },
+  })
+);
+```
+
+DMG also supports GitHub release sources:
+
+```typescript
+install('dmg', {
+  source: {
+    type: 'github-release',
+    repo: 'manaflow-ai/cmux',
+    assetPattern: '*macos*.dmg',
+  },
+});
+```
+
+### Manual
+
+Install files from your dotfiles directory (custom scripts, pre-built binaries) or configuration-only tools. Can be called without params: `install('manual')`.
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+// With binary installation
+export default defineTool((install, ctx) =>
+  install('manual', {
+    binaryPath: './bin/my-script.sh',
+  }).bin('my-script')
+);
+
+// Without params (shell-only or dependency wrapper)
+export default defineTool((install) =>
+  install('manual')
+    .bin('tokscale')
+    .dependsOn('bun')
+    .zsh((shell) =>
+      shell.functions({
+        tokscale: `bun x tokscale@latest`,
+      })
+    )
+);
+
+// Configuration-only
+export default defineTool((install, ctx) => install().zsh((shell) => shell.aliases({ ll: 'ls -la' })));
+```
+
+### Zsh Plugin
+
+Clone Git repositories for zsh plugins.
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install('zsh-plugin', {
+    repo: 'jeffreytse/zsh-vi-mode',
+  })
+    .zsh((shell) => shell.always(`source "${ctx.currentDir}/zsh-vi-mode.plugin.zsh"`))
+);
+```
+
+## Choosing the Right Method
+
+| Method             | Best For                            | Pros                                   | Cons                                 |
+| ------------------ | ----------------------------------- | -------------------------------------- | ------------------------------------ |
+| **GitHub Release** | Most open source tools              | Automatic updates, cross-platform      | Requires GitHub hosting              |
+| **Gitea/Forgejo**  | Codeberg / self-hosted Gitea tools  | Supports any Gitea-compatible host     | Requires instance URL                |
+| **Homebrew**       | macOS/Linux tools                   | Simple, well-maintained                | Platform-specific, requires Homebrew |
+| **Cargo**          | Rust tools                          | Fast pre-compiled binaries             | Rust tools only                      |
+| **npm**            | Node.js tools                       | Simple, version management             | Requires Node.js/npm                 |
+| **Curl Script**    | Custom installers                   | Flexible, handles complex setups       | Less predictable, security concerns  |
+| **Curl Tar**       | Archive downloads                   | Simple, no dependencies                | Manual URL management                |
+| **Curl Binary**    | Direct binary downloads             | Simplest, no extraction needed         | Manual URL management                |
+| **DMG**            | macOS .app bundles                  | Handles mount/unmount, archive extract | macOS only                           |
+| **Manual**         | Custom scripts, configuration tools | Include files with dotfiles, flexible  | Manual file management               |
+| **Zsh Plugin**     | Zsh plugins from Git repos          | Simple, automatic updates              | Zsh plugins only                     |
+
+## Manual Installation Guide
+
+The `manual` method is the unified approach for binary installation from your dotfiles directory.
+
+### Use **Manual** for Binary Installation:
+
+- You have custom scripts or binaries to include with your dotfiles
+- You want the system to manage and version your tool files
+- You need shims generated for your custom tools
+- You want to distribute pre-built binaries with your dotfiles
+
+**Example:** Including a custom deployment script with your dotfiles.
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install('manual', {
+    binaryPath: './scripts/deploy.sh',
+  }).bin('deploy')
+);
+```
+
+### Use `install()` for Configuration Only:
+
+- You only need shell configuration (aliases, environment, symlinks)
+- Tools are managed entirely outside the dotfiles system
+- You don't want any binary installation or management
+- Creating configuration-only "tools"
+
+**Example:** Setting up shell aliases and environment variables.
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install, ctx) =>
+  install().zsh((shell) =>
+    shell
+      .aliases({
+        ll: 'ls -la',
+      })
+      .env({
+        EDITOR: 'vim',
+      })
+  )
+);
+```
+
+## Common Parameters
+
+Most installation methods support these common concepts:
+
+- **Version Selection**: Specify exact versions or use constraints
+- **Platform Detection**: Automatic selection of appropriate binaries
+- **Binary Path**: Specify which file is the main executable
+- **Asset Selection**: Choose the right download for your platform
+- **Environment Variables**: Set `env` for installation (static or dynamic)
+
+### Environment Variables (`env`)
+
+All installation methods support an `env` parameter for setting environment variables during installation:
+
+```typescript
+// Static environment variables
+install('github-release', {
+  repo: 'owner/tool',
+  env: { CUSTOM_FLAG: 'true' },
+}).bin('tool');
+
+// Dynamic environment variables
+install('curl-script', {
+  url: 'https://example.com/install.sh',
+  shell: 'bash',
+  env: (ctx) => ({ INSTALL_DIR: ctx.stagingDir }),
+}).bin('tool');
+```
+
+Dynamic `env` functions receive a context with:
+
+- `projectConfig` - Full project configuration
+- `stagingDir` - Temporary installation directory
+
+For `curl-script`, the context also includes `scriptPath`.

package/skill/references/installation-methods/zsh-plugin.md

@@ -0,0 +1,156 @@
+# Zsh Plugin Installation
+
+The `zsh-plugin` installation method clones Git repositories for zsh plugins and automatically configures them to be sourced in your shell. This is useful for installing plugins that are not available via package managers.
+
+## Configuration
+
+### Basic Usage
+
+#### GitHub Shorthand
+
+The simplest way to install a plugin from GitHub:
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) =>
+  install('zsh-plugin', {
+    repo: 'jeffreytse/zsh-vi-mode',
+  })
+);
+```
+
+The plugin is automatically sourced - no additional configuration needed!
+
+#### Full Git URL
+
+For plugins hosted elsewhere (GitLab, Bitbucket, private repos):
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) =>
+  install('zsh-plugin', {
+    url: 'https://gitlab.com/user/custom-plugin.git',
+  })
+);
+```
+
+### Install Parameters
+
+| Parameter    | Type    | Required | Description                                                |
+| ------------ | ------- | -------- | ---------------------------------------------------------- |
+| `repo`       | string  | No\*     | GitHub repository shorthand (e.g., `user/repo`)            |
+| `url`        | string  | No\*     | Full Git URL (e.g., `https://github.com/user/repo.git`)    |
+| `pluginName` | string  | No       | Custom plugin directory name (defaults to repository name) |
+| `source`     | string  | No       | Explicit source file path (auto-detected if not specified) |
+| `auto`       | boolean | No       | Auto-install during `generate` command (default: `true`)   |
+
+\* Either `repo` or `url` must be provided.
+
+### Auto-Install Behavior
+
+By default (`auto: true`), zsh plugins are automatically installed during the `dotfiles generate` command. This means:
+
+1. When you run `dotfiles generate`, plugins with `auto: true` are cloned/updated
+2. The plugin's `source` command is automatically added to your shell init
+3. No separate `dotfiles install` step is needed for these plugins
+
+To disable auto-installation and require explicit `dotfiles install`:
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) =>
+  install('zsh-plugin', {
+    repo: 'jeffreytse/zsh-vi-mode',
+    auto: false, // Requires explicit `dotfiles install`
+  })
+);
+```
+
+### Custom Plugin Name
+
+Use `pluginName` when you want the plugin directory name to differ from the repository name:
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) =>
+  install('zsh-plugin', {
+    repo: 'jeffreytse/zsh-vi-mode',
+    pluginName: 'vi-mode', // Cloned to plugins/vi-mode instead of plugins/zsh-vi-mode
+  })
+);
+```
+
+### Explicit Source File
+
+If the plugin's source file doesn't follow standard naming conventions, specify it explicitly:
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) =>
+  install('zsh-plugin', {
+    repo: 'some-org/some-plugin',
+    source: 'custom-init.zsh', // Use this file instead of auto-detection
+  })
+);
+```
+
+## How It Works
+
+1. **Clone**: The repository is cloned with `--depth 1` to minimize download size
+2. **Detect**: The plugin's source file is auto-detected (e.g., `*.plugin.zsh`)
+3. **Source**: A `source` command is automatically added to your shell init
+4. **Update**: On subsequent runs, `git pull --ff-only` updates the plugin
+5. **Version**: Version is determined from git tags (e.g., `v0.1.0`) or commit hash (e.g., `abc1234`)
+
+### Auto-detected Source Files
+
+The installer checks for these files in order:
+
+- `{pluginName}.plugin.zsh`
+- `{pluginName}.zsh`
+- `init.zsh`
+- `plugin.zsh`
+- `{pluginName}.zsh-theme`
+
+## Adding Environment Variables
+
+Use `.zsh()` to add environment variables or other shell configuration:
+
+```typescript
+import { defineTool } from '@alexgorbatchev/dotfiles';
+
+export default defineTool((install) =>
+  install('zsh-plugin', {
+    repo: 'jeffreytse/zsh-vi-mode',
+  })
+    .zsh((shell) =>
+      shell.env({
+        ZVM_VI_INSERT_ESCAPE_BINDKEY: 'jj',
+        ZVM_CURSOR_STYLE_ENABLED: 'false',
+      })
+    )
+);
+```
+
+The environment variables are set **before** the plugin is sourced, allowing you to configure the plugin's behavior.
+
+## Troubleshooting
+
+### Update fails
+
+If `git pull --ff-only` fails, you may have local changes. Delete the plugin directory and reinstall, or manually reset it:
+
+```bash
+cd ~/.dotfiles-generated/plugins/<plugin-name>
+git reset --hard origin/HEAD
+```
+
+## Related
+
+- Manual Installation - For plugins requiring custom setup
+- Shell Integration - How shell configs are generated