@guiho/runx 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+---
+name: RunX Changelog
+purpose: Record externally meaningful RunX release changes.
+description: Tracks release-level changes managed with Mirror.
+created: 2026-07-12
+flags: []
+tags:
+  - releases
+  - changelog
+keywords:
+  - runx
+  - changelog
+owner: runx
+---
+
+# Changelog
+
+## 0.2.0 - 2026-07-12
+
+### Added
+
+- Added `publish.yml` GitHub Actions workflow to compile and upload release binaries to GitHub releases on version tag pushes.
+
+### Changed
+
+- Updated `devops/build-binaries.ts` to compile the full 12 binary target matrix in parallel using optimized build flags.
+- Replaced `devops/install.sh` and `devops/install.ps1` with robust, parameter-driven installers.
+
+## 0.1.1 - 2026-07-12
+
+### Changed
+
+- Finalized task completion and validation evidence for the initial alpha release.
+
+## 0.1.0 - 2026-07-12
+
+### Added
+
+- First alpha implementation of the RunX command-catalog CLI.

package/DOCS.md

@@ -0,0 +1,118 @@
+---
+name: RunX Documentation
+purpose: Provide the canonical user-facing RunX CLI and manifest reference.
+description: Documents command behavior, manifest schema, safety model, agent workflow, and native distribution.
+created: 2026-07-12
+flags: []
+tags:
+  - documentation
+  - cli
+keywords:
+  - runx
+  - manifest
+owner: runx
+---
+
+# RunX Documentation
+
+## Purpose
+
+RunX makes project operations visible and documented. A `runx.yaml` file is a
+single local command catalog; RunX discovers the nearest catalog, validates it,
+lists its commands, and runs exactly one selected command.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `runx` | Show the home page and usage without loading a manifest. |
+| `runx list` | List all manifest commands. Add `--format json` for structured output. |
+| `runx describe <selector>` | Show one command's description and operational metadata. |
+| `runx check` | Validate discovery and the manifest without execution. |
+| `runx run <selector>` | Execute a selected command. |
+| `runx r <selector>` | Short alias for `runx run`. |
+| `runx <selector>` | Human shorthand for `runx run <selector>` when no built-in name conflicts. |
+| `runx agents install <local|global>` | Install `guiho-s-runx`; add `--tool agents|claude|all` when needed. |
+| `runx agents instructions` | Add or refresh the managed RunX section in `AGENTS.md`. |
+| `runx upgrade [check|list]` | Check releases, list releases, or replace a native installed executable. |
+| `runx uninstall [--dry-run]` | Remove a native installed executable. |
+
+Global flags: `--cwd <path>`, `--file <path>`, `--format <text|json>`,
+`--verbose`, `--version`, `--help`, `--help-tree`, and `--help-docs`.
+
+## Manifest
+
+RunX searches upward from the current directory for `runx.yaml`. Use `--file`
+to select an explicit manifest. RunX does not merge files.
+
+```yaml
+version: 1
+project:
+  name: example
+groups:
+  development:
+    summary: Local development work.
+  release:
+    summary: Explicit release actions.
+commands:
+  - uid: example-check
+    id: check
+    group: development
+    summary: Type-check the project.
+    description: Runs the project's static type checker without emitting build files.
+    command: bun run typecheck
+    cwd: .
+    shell: auto
+    tags: [validation]
+  - uid: example-release
+    id: release
+    group: release
+    summary: Build the release artifact.
+    description: Builds the release artifact after the project has passed its required checks.
+    command: bun run build
+    confirm: always
+```
+
+Required fields are `uid`, `id`, `group`, `summary`, `description`, and
+`command`. `uid` and `id` begin with a lowercase letter and use lowercase
+letters, digits, and hyphens. `uid` is globally unique; the group and ID pair
+is also unique.
+
+Optional fields are `cwd`, `shell`, `tags`, and `confirm`. `cwd` is relative to
+the manifest and cannot escape its directory. Shell values are `auto`, `bash`,
+`sh`, `powershell`, and `cmd`. Confirmation values are `never` and `always`.
+
+## Selectors and Safety
+
+RunX resolves selectors in this order: exact UID, exact `group/id`, one-based
+manifest index, then an unambiguous bare ID. Use UIDs in automation. An index is
+only stable until commands are reordered, and an ambiguous bare ID fails rather
+than selecting a command.
+
+`list`, `describe`, `check`, and `run --dry-run` never execute a configured
+command. A real run streams stdout/stderr and uses the child process exit code.
+`confirm: always` requires the user to add `--yes`.
+
+Manifests are executable local code. Do not place secrets in a manifest and do
+not assume a group name determines safety.
+
+## Agent Skill
+
+The bundled `guiho-s-runx` skill directs agents to validate and list a catalog,
+select a UID, inspect unfamiliar commands, use dry runs, and obtain explicit
+authorization before `--yes` for high-impact commands. Install it with:
+
+```text
+runx agents install local
+```
+
+## Native Install, Upgrade, and Uninstall
+
+`devops/install.ps1` installs Windows assets and `devops/install.sh` installs
+macOS/Linux assets from GitHub Releases into the user's local bin directory.
+`runx upgrade` uses the matching release asset and replaces a native executable;
+on Windows replacement is scheduled after RunX exits. `runx uninstall` removes
+the same native executable and supports `--dry-run`.
+
+The alpha CI validates code and compiles a native executable but intentionally
+does not publish to npm or GitHub Releases.

package/LICENSE.md

@@ -0,0 +1,36 @@
+---
+name: RunX MIT License
+purpose: State the open-source license for RunX.
+description: MIT license grant and warranty disclaimer.
+created: 2026-07-12
+flags: []
+tags:
+  - legal
+  - license
+keywords:
+  - runx
+  - mit
+owner: runx
+---
+
+MIT License
+
+Copyright (c) 2026 Cristovao GUIHO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+---
+name: RunX README
+purpose: Introduce RunX and give users the shortest installation and command-catalog path.
+description: Public overview, direct installation commands, quick manifest example, and documentation links.
+created: 2026-07-12
+flags: []
+tags:
+  - documentation
+  - cli
+keywords:
+  - runx
+  - readme
+owner: runx
+---
+
+# GUIHO RunX
+
+RunX is a local, language-agnostic command catalog. Put documented commands in
+`runx.yaml`; use `runx list` to discover them and `runx run` to execute one.
+It works for Bun, Python, Go, shell, and mixed repositories because it executes
+local shell commands rather than package-manager scripts.
+
+## Install
+
+RunX is distributed as a native executable from GitHub Releases. It is not
+published to npm during the alpha.
+
+```powershell
+irm https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.ps1 | iex
+```
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/CGuiho/runx/main/devops/install.sh | sh
+```
+
+## Quick Start
+
+Create `runx.yaml` in a project root:
+
+```yaml
+version: 1
+groups:
+  development:
+    summary: Local development commands.
+commands:
+  - uid: app-dev
+    id: dev
+    group: development
+    summary: Start the application locally.
+    description: Starts the application in local development mode until interrupted.
+    command: bun run dev
+    shell: bash
+    tags: [local, watch]
+```
+
+Then use RunX:
+
+```text
+runx                         Show the home page and usage.
+runx list                    List commands in the nearest manifest.
+runx describe app-dev        Explain one command without execution.
+runx run app-dev --dry-run   Inspect the execution plan.
+runx run app-dev             Execute the command.
+runx r app-dev               Use the short run alias.
+```
+
+Use `confirm: always` for commands that should require an explicit `--yes`.
+Use `runx list --format json` and stable UIDs for agent automation.
+
+## Documentation
+
+- [Full CLI and manifest reference](DOCS.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security policy](SECURITY.md)
+- [Changelog](CHANGELOG.md)
+
+## License
+
+[MIT](LICENSE.md)

package/SECURITY.md

@@ -0,0 +1,28 @@
+---
+name: RunX Security Policy
+purpose: Explain private vulnerability reporting and the RunX manifest trust boundary.
+description: Documents responsible disclosure and the risks of executable local manifests.
+created: 2026-07-12
+flags: []
+tags:
+  - security
+keywords:
+  - runx
+  - security
+owner: runx
+---
+
+# Security Policy
+
+## Reporting
+
+Report a potential security issue privately to `cg@guiho.co`. Do not include
+credentials, tokens, or private manifests in public issues.
+
+## RunX Trust Boundary
+
+RunX manifests contain shell commands and are trusted local executable code.
+RunX validates structure and makes commands visible; it cannot make arbitrary
+shell code safe. Do not store secrets in `runx.yaml`, inspect a command before
+running it, and use `confirm: always` for operations that benefit from an
+explicit `--yes` acknowledgement.

package/devops/build-binaries.ts

@@ -0,0 +1,99 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ *
+ * Build release binaries for the supported RunX platform matrix.
+ */
+
+import { mkdir, rm, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+type BinaryTarget = {
+  readonly bunTarget: string
+  readonly assetName: string
+}
+
+const targets: readonly BinaryTarget[] = [
+  { bunTarget: 'bun-linux-arm64', assetName: 'runx-linux-arm64' },
+  { bunTarget: 'bun-linux-x64', assetName: 'runx-linux-x64' },
+  { bunTarget: 'bun-linux-x64-baseline', assetName: 'runx-linux-x64-baseline' },
+  { bunTarget: 'bun-linux-x64-modern', assetName: 'runx-linux-x64-modern' },
+  { bunTarget: 'bun-darwin-arm64', assetName: 'runx-macos-arm64' },
+  { bunTarget: 'bun-darwin-x64', assetName: 'runx-macos-x64' },
+  { bunTarget: 'bun-darwin-x64-baseline', assetName: 'runx-macos-x64-baseline' },
+  { bunTarget: 'bun-darwin-x64-modern', assetName: 'runx-macos-x64-modern' },
+  { bunTarget: 'bun-windows-arm64', assetName: 'runx-windows-arm64.exe' },
+  { bunTarget: 'bun-windows-x64', assetName: 'runx-windows-x64.exe' },
+  { bunTarget: 'bun-windows-x64-baseline', assetName: 'runx-windows-x64-baseline.exe' },
+  { bunTarget: 'bun-windows-x64-modern', assetName: 'runx-windows-x64-modern.exe' },
+]
+
+const expectedAssetCount = 12
+const assetNames = targets.map((target) => target.assetName)
+const uniqueAssetNames = new Set(assetNames)
+
+if (targets.length !== expectedAssetCount) {
+  throw new Error(`Expected ${expectedAssetCount} binary targets, found ${targets.length}`)
+}
+
+if (uniqueAssetNames.size !== assetNames.length) {
+  throw new Error('Binary target matrix contains duplicate asset names')
+}
+
+const root = fileURLToPath(new URL('..', import.meta.url))
+const binDirectory = join(root, 'bin')
+const bunExecutable = process.execPath
+
+await rm(binDirectory, { recursive: true, force: true })
+await mkdir(binDirectory, { recursive: true })
+
+const builds = targets.map(async (target) => {
+  const outputPath = join(binDirectory, target.assetName)
+  const proc = Bun.spawn({
+    cmd: [
+      bunExecutable,
+      'build',
+      'source/guiho-runx-native-bin.ts',
+      '--compile',
+      '--production',
+      '--minify-whitespace',
+      '--minify-syntax',
+      '--target',
+      target.bunTarget,
+      '--outfile',
+      outputPath,
+    ],
+    cwd: root,
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ])
+
+  if (exitCode !== 0) {
+    throw new Error([
+      `Failed to build ${target.bunTarget} -> ${target.assetName}`,
+      stdout.trim(),
+      stderr.trim(),
+    ].filter(Boolean).join('\n'))
+  }
+
+  process.stdout.write(`built: ${target.bunTarget} -> bin/${target.assetName}\n`)
+})
+
+await Promise.all(builds)
+
+for (const target of targets) {
+  const outputPath = join(binDirectory, target.assetName)
+  const output = await stat(outputPath)
+
+  if (output.size === 0) {
+    throw new Error(`Built binary is empty: bin/${target.assetName}`)
+  }
+}
+
+process.stdout.write(`verified ${targets.length} native binary assets\n`)

package/devops/devops.xdocs.md

@@ -0,0 +1,25 @@
+---
+subject: runx-devops
+description: Native release-asset compilation and direct RunX installer scripts.
+parent: runx
+children: []
+files:
+  build-binaries.ts: Cross-compiles supported Bun native executable assets.
+  install.ps1: Installs the latest Windows executable from GitHub Releases.
+  install.sh: Installs the latest macOS or Linux executable from GitHub Releases.
+documents: {}
+tags:
+  - devops
+  - installers
+  - releases
+keywords:
+  - runx
+  - windows
+  - macos
+  - linux
+  - native binary
+flags: []
+status: stable
+---
+
+These scripts support direct native installation without an npm publication.

package/devops/install.ps1

@@ -0,0 +1,216 @@
+param(
+  [string]$Version,
+  [string]$Arch,
+  [string]$Variant,
+  [string]$InstallDir,
+  [switch]$Help
+)
+
+$ErrorActionPreference = 'Stop'
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+
+# === Defaults from env vars or sensible defaults ===
+if ([string]::IsNullOrWhiteSpace($Version)) {
+  $Version = if ($env:RUNX_VERSION) { $env:RUNX_VERSION } else { 'latest' }
+}
+$Repo = if ($env:RUNX_REPO) { $env:RUNX_REPO } else { 'CGuiho/runx' }
+if ([string]::IsNullOrWhiteSpace($InstallDir)) {
+  $InstallDir = if ($env:RUNX_INSTALL_DIR) { $env:RUNX_INSTALL_DIR } else { Join-Path $HOME '.local\bin' }
+}
+
+# === Show help ===
+if ($Help -or $Version -eq '--help' -or $Version -eq '-h') {
+  @"
+Install GUIHO RunX as a native CLI binary from GitHub Releases.
+
+Usage: install.ps1 [-Version VERSION] [-Arch ARCH] [-Variant VARIANT] [-InstallDir DIR]
+
+Parameters:
+  -Version      Version to install (default: latest).
+                Examples: latest, 0.1.1, @guiho/runx@0.1.1
+  -Arch         Force architecture: x64 | arm64 (default: auto-detect)
+  -Variant      Force x64 variant: baseline | default | modern (default: baseline)
+  -InstallDir   Install directory (default: `$HOME\.local\bin)
+  -Help         Show this help
+
+Environment variables:
+  RUNX_VERSION, RUNX_REPO, RUNX_INSTALL_DIR
+"@
+  return
+}
+
+# === Detect architecture (compatible with PowerShell 5.1+) ===
+$detectedArch = if ($Arch) {
+  $Arch
+} else {
+  switch ($env:PROCESSOR_ARCHITECTURE) {
+    'AMD64' { 'x64' }
+    'ARM64' { 'arm64' }
+    default { throw "Unsupported architecture: $env:PROCESSOR_ARCHITECTURE. Must be AMD64 or ARM64." }
+  }
+}
+
+if ($detectedArch -notin @('x64', 'arm64')) {
+  throw "Invalid architecture: $detectedArch. Must be x64 or arm64."
+}
+
+if (-not [Environment]::Is64BitOperatingSystem) {
+  throw 'Unsupported platform: Windows 32-bit is not supported.'
+}
+
+# === Build asset candidates (baseline-first for x64) ===
+$variant = if ($Variant) { $Variant } else { 'baseline' }
+
+$assetCandidates = if ($detectedArch -eq 'x64') {
+  switch ($variant) {
+    'baseline' { @(
+      "runx-windows-x64-baseline.exe",
+      "runx-windows-x64.exe",
+      "runx-windows-x64-modern.exe"
+    )}
+    'default' { @(
+      "runx-windows-x64.exe",
+      "runx-windows-x64-baseline.exe",
+      "runx-windows-x64-modern.exe"
+    )}
+    'modern' { @(
+      "runx-windows-x64-modern.exe",
+      "runx-windows-x64.exe",
+      "runx-windows-x64-baseline.exe"
+    )}
+    default { throw "Invalid variant: $variant. Must be baseline, default, or modern." }
+  }
+} else {
+  if ($Variant) {
+    throw '-Variant is only valid for x64 installs.'
+  }
+  @("runx-windows-arm64.exe")
+}
+
+# === Build download URL ===
+function Get-DownloadUrl {
+  param([string]$Asset)
+
+  if ($Version -eq 'latest') {
+    return "https://github.com/$Repo/releases/latest/download/$Asset"
+  }
+
+  $tag = if ($Version.StartsWith('@guiho/runx@')) { $Version }
+         elseif ($Version.StartsWith('@')) { $Version }
+         else { "@guiho/runx@$Version" }
+
+  $encodedTag = [Uri]::EscapeDataString($tag)
+  return "https://github.com/$Repo/releases/download/$encodedTag/$Asset"
+}
+
+function Get-PathEntries {
+  param([string]$PathValue)
+
+  if ([string]::IsNullOrWhiteSpace($PathValue)) {
+    return @()
+  }
+
+  return @($PathValue -split ';' | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
+}
+
+function Test-PathContains {
+  param(
+    [string]$PathValue,
+    [string]$Directory
+  )
+
+  $normalizedDirectory = $Directory.TrimEnd('\')
+  foreach ($entry in Get-PathEntries -PathValue $PathValue) {
+    if ($entry.TrimEnd('\').Equals($normalizedDirectory, [StringComparison]::OrdinalIgnoreCase)) {
+      return $true
+    }
+  }
+
+  return $false
+}
+
+function Add-InstallDirToPath {
+  param([string]$Directory)
+
+  $userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+  if (-not (Test-PathContains -PathValue $userPath -Directory $Directory)) {
+    $entries = @(Get-PathEntries -PathValue $userPath)
+    $newUserPath = (@($Directory) + $entries) -join ';'
+    [Environment]::SetEnvironmentVariable('Path', $newUserPath.TrimEnd(';'), 'User')
+    Write-Host "Added $Directory to user PATH. Restart your terminal to use runx globally."
+  } else {
+    Write-Host "$Directory is already configured in user PATH."
+  }
+
+  if (-not (Test-PathContains -PathValue $env:Path -Directory $Directory)) {
+    $env:Path = "$Directory;$env:Path"
+  }
+}
+
+$temporaryFile = Join-Path ([System.IO.Path]::GetTempPath()) ([System.IO.Path]::GetRandomFileName())
+
+function Test-NativeBinary {
+  param([string]$Path)
+
+  $bytes = [System.IO.File]::ReadAllBytes($Path)
+  if ($bytes.Length -lt 2) {
+    return $false
+  }
+
+  return $bytes[0] -eq 0x4D -and $bytes[1] -eq 0x5A
+}
+
+function Test-Shadowing {
+  param([string]$ExpectedPath)
+
+  $command = Get-Command runx -ErrorAction SilentlyContinue
+  if (-not $command) {
+    return
+  }
+
+  if (-not $command.Source.Equals($ExpectedPath, [StringComparison]::OrdinalIgnoreCase)) {
+    Write-Warning "Another runx appears earlier in PATH: $($command.Source)"
+    Write-Warning "The newly installed binary is at: $ExpectedPath"
+  }
+}
+
+# === Main ===
+$variantLabel = if ($Variant) { " variant=$Variant" } else { "" }
+Write-Host "runx: $Version  os=windows  arch=$detectedArch$variantLabel"
+
+New-Item -ItemType Directory -Force -Path $InstallDir | Out-Null
+$InstallDir = (Resolve-Path -LiteralPath $InstallDir).Path
+$destination = Join-Path $InstallDir 'runx.exe'
+
+foreach ($asset in $assetCandidates) {
+  $url = Get-DownloadUrl -Asset $asset
+  Write-Host "  Trying $url"
+  try {
+    Invoke-WebRequest -Uri $url -OutFile $temporaryFile -UseBasicParsing -ErrorAction Stop
+    if (-not (Test-NativeBinary -Path $temporaryFile)) {
+      Write-Host "  $asset was not a native Windows binary, trying next..."
+      continue
+    }
+
+    Move-Item -Force -Path $temporaryFile -Destination $destination
+    Write-Host "Installed runx to $destination"
+
+    Add-InstallDirToPath -Directory $InstallDir
+    Test-Shadowing -ExpectedPath $destination
+
+    if (Test-Path -LiteralPath $temporaryFile) {
+      Remove-Item -LiteralPath $temporaryFile -Force
+    }
+
+    Write-Host 'Run: runx --help'
+    return
+  } catch {
+    Write-Host "  not available, trying next..."
+  }
+}
+
+if (Test-Path -LiteralPath $temporaryFile) {
+  Remove-Item -LiteralPath $temporaryFile -Force
+}
+
+throw "No compatible runx binary found. Check available assets at: https://github.com/$Repo/releases"