@guiho/runx 0.2.0

package/devops/install.sh

@@ -0,0 +1,324 @@
+#!/usr/bin/env bash
+#
+# Install GUIHO RunX as a native CLI binary from GitHub Releases.
+#
+set -Eeuo pipefail
+
+REPO="${RUNX_REPO:-CGuiho/runx}"
+VERSION="${RUNX_VERSION:-latest}"
+INSTALL_DIR="${RUNX_INSTALL_DIR:-$HOME/.local/bin}"
+ARCH_OVERRIDE=""
+VARIANT_OVERRIDE=""
+OS=""
+ARCH=""
+CANDIDATES=()
+TMP=""
+
+cleanup() {
+  if [[ -n "$TMP" ]]; then
+    rm -rf -- "$TMP"
+  fi
+}
+
+trap cleanup EXIT
+
+usage() {
+  cat <<EOF
+Install GUIHO RunX as a native CLI binary from GitHub Releases.
+
+Usage: install.sh [flags]
+
+Flags:
+  -v, --version VERSION   Version to install (default: latest).
+                          Examples: latest, 0.1.1, @guiho/runx@0.1.1
+  --arch ARCH             Force architecture: x64 | arm64 (default: auto-detect)
+  --variant VARIANT       Force x64 variant: baseline | default | modern (default: baseline)
+  --install-dir DIR       Install directory (default: \$HOME/.local/bin)
+  -h, --help              Show this help
+
+Environment variables:
+  RUNX_VERSION            Same as --version
+  RUNX_REPO               GitHub repo (default: CGuiho/runx)
+  RUNX_INSTALL_DIR        Same as --install-dir
+EOF
+}
+
+fail() {
+  printf 'error: %s\n' "$*" >&2
+  exit 1
+}
+
+require_command() {
+  command -v "$1" >/dev/null 2>&1 || fail "required command not found: $1"
+}
+
+require_value() {
+  local option="$1"
+  local value="${2:-}"
+
+  [[ -n "$value" ]] || fail "$option requires a value"
+}
+
+parse_args() {
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -v | --version)
+        require_value "$1" "${2:-}"
+        VERSION="$2"
+        shift 2
+        ;;
+      --version=*)
+        VERSION="${1#*=}"
+        shift
+        ;;
+      --arch)
+        require_value "$1" "${2:-}"
+        ARCH_OVERRIDE="$2"
+        shift 2
+        ;;
+      --arch=*)
+        ARCH_OVERRIDE="${1#*=}"
+        shift
+        ;;
+      --variant)
+        require_value "$1" "${2:-}"
+        VARIANT_OVERRIDE="$2"
+        shift 2
+        ;;
+      --variant=*)
+        VARIANT_OVERRIDE="${1#*=}"
+        shift
+        ;;
+      --install-dir)
+        require_value "$1" "${2:-}"
+        INSTALL_DIR="$2"
+        shift 2
+        ;;
+      --install-dir=*)
+        INSTALL_DIR="${1#*=}"
+        shift
+        ;;
+      -h | --help)
+        usage
+        exit 0
+        ;;
+      *)
+        fail "unknown flag: $1. Run with --help for usage."
+        ;;
+    esac
+  done
+}
+
+detect_os() {
+  case "$(uname -s)" in
+    Linux) printf 'linux\n' ;;
+    Darwin) printf 'macos\n' ;;
+    *) fail "unsupported OS: $(uname -s)" ;;
+  esac
+}
+
+detect_arch() {
+  if [[ -n "$ARCH_OVERRIDE" ]]; then
+    case "$ARCH_OVERRIDE" in
+      x64 | arm64) printf '%s\n' "$ARCH_OVERRIDE" ;;
+      *) fail "invalid --arch '$ARCH_OVERRIDE'. Must be x64 or arm64." ;;
+    esac
+    return
+  fi
+
+  case "$(uname -m)" in
+    x86_64 | amd64) printf 'x64\n' ;;
+    arm64 | aarch64) printf 'arm64\n' ;;
+    *) fail "unsupported architecture: $(uname -m)" ;;
+  esac
+}
+
+build_candidates() {
+  local variant="${VARIANT_OVERRIDE:-baseline}"
+
+  if [[ "$ARCH" == "arm64" ]]; then
+    [[ -z "$VARIANT_OVERRIDE" ]] || fail "--variant is only valid for x64 installs"
+    CANDIDATES=("runx-${OS}-arm64")
+    return
+  fi
+
+  case "$variant" in
+    baseline)
+      CANDIDATES=("runx-${OS}-x64-baseline" "runx-${OS}-x64" "runx-${OS}-x64-modern")
+      ;;
+    default)
+      CANDIDATES=("runx-${OS}-x64" "runx-${OS}-x64-baseline" "runx-${OS}-x64-modern")
+      ;;
+    modern)
+      CANDIDATES=("runx-${OS}-x64-modern" "runx-${OS}-x64" "runx-${OS}-x64-baseline")
+      ;;
+    *)
+      fail "invalid --variant '$variant'. Must be baseline, default, or modern."
+      ;;
+  esac
+}
+
+build_url() {
+  local asset="$1"
+
+  if [[ "$VERSION" == "latest" ]]; then
+    printf 'https://github.com/%s/releases/latest/download/%s\n' "$REPO" "$asset"
+    return
+  fi
+
+  local tag
+  case "$VERSION" in
+    @guiho/runx@*) tag="$VERSION" ;;
+    @*) tag="$VERSION" ;;
+    *) tag="@guiho/runx@${VERSION}" ;;
+  esac
+
+  local encoded_tag="${tag//@/%40}"
+  encoded_tag="${encoded_tag//\//%2F}"
+  printf 'https://github.com/%s/releases/download/%s/%s\n' "$REPO" "$encoded_tag" "$asset"
+}
+
+verify_native_binary() {
+  local path="$1"
+  local magic2
+  local magic4
+
+  magic2="$(LC_ALL=C head -c 2 "$path" 2>/dev/null || true)"
+  magic4="$(LC_ALL=C head -c 4 "$path" 2>/dev/null || true)"
+
+  case "$magic4" in
+    $'\177ELF' | $'\xcf\xfa\xed\xfe' | $'\xce\xfa\xed\xfe' | $'\xca\xfe\xba\xbe') return 0 ;;
+    '<!DO' | '<htm') return 1 ;;
+  esac
+
+  case "$magic2" in
+    MZ) return 0 ;;
+    '#!') return 1 ;;
+  esac
+
+  return 2
+}
+
+shell_profile_path() {
+  local shell_name="${SHELL##*/}"
+
+  case "$shell_name" in
+    fish) printf '%s/.config/fish/config.fish\n' "$HOME" ;;
+    zsh) printf '%s/.zshrc\n' "$HOME" ;;
+    bash)
+      if [[ "$OS" == "macos" && -f "$HOME/.bash_profile" ]]; then
+        printf '%s/.bash_profile\n' "$HOME"
+      else
+        printf '%s/.bashrc\n' "$HOME"
+      fi
+      ;;
+    *) printf '%s/.profile\n' "$HOME" ;;
+  esac
+}
+
+path_contains_install_dir() {
+  case ":$PATH:" in
+    *:"$INSTALL_DIR":*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+append_path_to_profile() {
+  local profile="$1"
+  local shell_name="${SHELL##*/}"
+
+  if [[ "$shell_name" == "fish" ]]; then
+    mkdir -p "$HOME/.config/fish"
+    if [[ -f "$profile" ]] && grep -Fq "$INSTALL_DIR" "$profile"; then
+      return 0
+    fi
+    printf '\n# Added by runx installer\nfish_add_path %q\n' "$INSTALL_DIR" >>"$profile"
+    return 0
+  fi
+
+  if [[ -f "$profile" ]] && grep -Fq "$INSTALL_DIR" "$profile"; then
+    return 0
+  fi
+
+  printf '\n# Added by runx installer\nexport PATH=%q:\$PATH\n' "$INSTALL_DIR" >>"$profile"
+}
+
+ensure_path() {
+  export PATH="$INSTALL_DIR:$PATH"
+
+  if path_contains_install_dir; then
+    printf 'runx: %s is available in PATH for this installer process.\n' "$INSTALL_DIR"
+  fi
+
+  local profile
+  profile="$(shell_profile_path)"
+  append_path_to_profile "$profile"
+
+  printf 'runx: ensured %s is added to PATH in %s\n' "$INSTALL_DIR" "$profile"
+  printf 'runx: restart your terminal, or run this for the current shell:\n'
+  printf '  export PATH=%q:\$PATH\n' "$INSTALL_DIR"
+}
+
+check_shadowing() {
+  local installed="$INSTALL_DIR/runx"
+  local resolved
+
+  resolved="$(command -v runx 2>/dev/null || true)"
+  [[ -n "$resolved" ]] || return 0
+  [[ "$resolved" == "$installed" ]] && return 0
+
+  printf '\nwarning: another runx appears earlier in PATH:\n' >&2
+  printf '  %s\n' "$resolved" >&2
+  printf 'The newly installed binary is at:\n' >&2
+  printf '  %s\n' "$installed" >&2
+}
+
+install_binary() {
+  TMP="$(mktemp -d)"
+
+  for asset in "${CANDIDATES[@]}"; do
+    local url
+    url="$(build_url "$asset")"
+    printf '  Trying %s\n' "$url"
+
+    if curl --fail --location --silent --show-error --proto '=https' --tlsv1.2 "$url" --output "$TMP/runx"; then
+      if ! verify_native_binary "$TMP/runx"; then
+        printf '  %s was not a native binary, trying next candidate...\n' "$asset" >&2
+        continue
+      fi
+
+      mkdir -p "$INSTALL_DIR"
+      install -m 0755 "$TMP/runx" "$INSTALL_DIR/runx"
+      printf 'Installed runx to %s/runx\n' "$INSTALL_DIR"
+      ensure_path
+      check_shadowing
+      printf 'Run: runx --help\n'
+      return 0
+    fi
+
+    printf '  not available, trying next...\n'
+  done
+
+  fail "no compatible runx binary found. Check available assets at: https://github.com/${REPO}/releases"
+}
+
+main() {
+  parse_args "$@"
+  require_command curl
+  require_command grep
+  require_command head
+  require_command install
+  require_command mktemp
+  require_command uname
+
+  OS="$(detect_os)"
+  ARCH="$(detect_arch)"
+  build_candidates
+
+  local variant_label=""
+  [[ -z "$VARIANT_OVERRIDE" ]] || variant_label=" variant=${VARIANT_OVERRIDE}"
+  printf 'runx: %s  os=%s  arch=%s%s\n' "$VERSION" "$OS" "$ARCH" "$variant_label"
+  install_binary
+}
+
+main "$@"

package/docs/architecture/architecture.xdocs.md

@@ -0,0 +1,20 @@
+---
+subject: runx-architecture
+description: Technical architecture for the RunX manifest, CLI, agent skill, and native distribution.
+parent: runx-docs
+children: []
+files:
+  cli-architecture.md: Documents RunX component boundaries and execution flow.
+documents:
+  cli-architecture.md: Technical architecture for the first RunX CLI release.
+tags:
+  - architecture
+keywords:
+  - runx
+  - bun
+  - cli
+flags: []
+status: stable
+---
+
+Architecture records for the independently distributed RunX CLI.

package/docs/architecture/cli-architecture.md

@@ -0,0 +1,39 @@
+---
+name: RunX CLI Architecture
+purpose: Describe the component boundaries and data flow of the RunX alpha CLI.
+description: Explains manifest discovery, TypeBox validation, selector resolution, execution, agent installation, and native distribution.
+created: 2026-07-12
+flags:
+  - approved
+tags:
+  - architecture
+  - cli
+keywords:
+  - runx
+  - typebox
+  - bun
+owner: runx-architecture
+---
+
+# RunX CLI Architecture
+
+## Flow
+
+`cli.ts` parses a command and global flags. Manifest commands use `manifest.ts`
+to discover the nearest `runx.yaml`, parse YAML, validate a strict TypeBox
+schema, and resolve a selector. `render.ts` presents text or JSON. `executor.ts`
+spawns exactly one configured shell command only for a real run.
+
+## Boundaries
+
+- Inspection paths never call the executor.
+- `agents.ts` copies the embedded or packaged skill into the requested standard
+  or Claude-compatible skill location.
+- `self-management.ts` queries GitHub Releases and only replaces/removes a
+  native executable, never a Bun development process.
+- Native builds register `embedded-resources.ts`, which includes the skill.
+
+## Distribution
+
+Bun compiles standalone binaries. Direct installers select a GitHub Release
+asset; CI validates source and a native build but does not publish artifacts.

package/docs/decisions/alpha-boundaries.md

@@ -0,0 +1,29 @@
+---
+name: RunX Alpha Boundaries
+purpose: Preserve the accepted product and technical decisions that constrain the first RunX implementation.
+description: Records the manifest-first, local-only, safety, distribution, and public licensing decisions for the alpha.
+created: 2026-07-12
+flags:
+  - accepted
+tags:
+  - decisions
+keywords:
+  - runx
+  - yaml
+  - safety
+owner: runx-decisions
+---
+
+# RunX Alpha Boundaries
+
+- Use one versioned YAML manifest named `runx.yaml`; do not merge manifests.
+- RunX is implemented in Bun/TypeScript but consumes commands from any project
+  language through a configured local shell.
+- Default `runx` behavior is a home page; `runx list` is explicit discovery.
+- Keep `runx r` as an alias for explicit `runx run`.
+- Treat manifests as trusted executable code and keep secret storage outside
+  the manifest.
+- Use explicit confirmation fields rather than guessing safety from groups.
+- Start as MIT-licensed open source with CI only and no npm publishing job.
+- Keep task graphs, variables, remote execution, caching, and automatic imports
+  out of the alpha.

package/docs/decisions/decisions.xdocs.md

@@ -0,0 +1,19 @@
+---
+subject: runx-decisions
+description: Durable product and technical decisions for RunX.
+parent: runx-docs
+children: []
+files:
+  alpha-boundaries.md: Captures accepted alpha scope, safety, distribution, and compatibility decisions.
+documents:
+  alpha-boundaries.md: Decision record for RunX alpha boundaries.
+tags:
+  - decisions
+keywords:
+  - runx
+  - decisions
+flags: []
+status: stable
+---
+
+Accepted decisions that later RunX work must preserve or intentionally supersede.

package/docs/docs.xdocs.md

@@ -0,0 +1,24 @@
+---
+subject: runx-docs
+description: Durable requirements, architecture, decisions, plans, task specifications, and validation records for RunX.
+parent: runx
+children:
+  - runx-requirements
+  - runx-architecture
+  - runx-decisions
+  - runx-plans
+  - runx-todo
+  - runx-validation
+files: {}
+documents: {}
+tags:
+  - documentation
+keywords:
+  - runx
+  - requirements
+  - architecture
+flags: []
+status: stable
+---
+
+The documentation tree records the approved alpha direction and its verification evidence.

package/docs/plans/alpha-implementation.md

@@ -0,0 +1,27 @@
+---
+name: RunX Alpha Implementation Plan
+purpose: Record the approved implementation sequence for the first RunX release.
+description: Sequences package setup, manifest behavior, safety, native distribution, documentation, and validation.
+created: 2026-07-12
+flags:
+  - executed
+tags:
+  - plans
+keywords:
+  - runx
+  - alpha
+  - implementation
+owner: runx-plans
+---
+
+# RunX Alpha Implementation Plan
+
+1. Initialize Bun, XDocs, Mirror, task tracking, and the open-source baseline.
+2. Implement strict YAML discovery, validation, grouping, and selector rules.
+3. Implement listing, describe, check, run, `r`, dry-run, and confirmation.
+4. Add help surfaces, agent-skill installation, upgrade, uninstall, native
+   compilation, and direct installers.
+5. Add unit tests, CI, canonical user documentation, XDocs descriptors, and
+   parent GUIHO coordination links.
+6. Validate, record the implementation summary, and apply a Mirror minor
+   version transition without publishing or pushing.

package/docs/plans/plans.xdocs.md

@@ -0,0 +1,19 @@
+---
+subject: runx-plans
+description: Executable implementation plans for RunX milestones.
+parent: runx-docs
+children: []
+files:
+  alpha-implementation.md: Breaks the accepted alpha into implementation and validation units.
+documents:
+  alpha-implementation.md: Plan used for the initial RunX implementation.
+tags:
+  - plans
+keywords:
+  - runx
+  - implementation
+flags: []
+status: stable
+---
+
+Plans that sequence RunX delivery work without replacing requirements or architecture.

package/docs/requirements/alpha-command-catalog.md

@@ -0,0 +1,41 @@
+---
+name: RunX Alpha Command Catalog Requirements
+purpose: Define the approved first-release outcome and acceptance criteria for RunX.
+description: Captures the user-visible command catalog, safety, agent, installer, and CI requirements.
+created: 2026-07-12
+flags:
+  - approved
+tags:
+  - requirements
+  - cli
+keywords:
+  - runx
+  - runx.yaml
+  - command catalog
+owner: runx-requirements
+---
+
+# RunX Alpha Command Catalog Requirements
+
+## Outcome
+
+RunX must provide a language-agnostic local command catalog in `runx.yaml` so
+project operations no longer need to be hidden in `package.json` scripts.
+
+## Acceptance Criteria
+
+- `runx` shows a home page and usage; `runx list` lists catalog commands.
+- Each command has a stable UID, group-scoped ID, summary, description, and
+  shell command; validation rejects malformed or ambiguous manifests.
+- `runx run` and `runx r` execute a selector, while `--dry-run` is read-only.
+- Text and JSON inspection output support humans and agents.
+- `confirm: always` blocks execution until `--yes` is supplied.
+- The CLI provides help, help tree, help docs, native upgrade, uninstall, and
+  skill-install commands.
+- Windows and macOS/Linux direct-install scripts, CI, MIT licensing, and a
+  bundled `guiho-s-runx` skill are present.
+
+## Non-goals
+
+The alpha does not publish to npm, orchestrate task graphs, manage secrets,
+run commands remotely, or perform automatic package-script migration.

package/docs/requirements/requirements.xdocs.md

@@ -0,0 +1,19 @@
+---
+subject: runx-requirements
+description: Product requirements and acceptance criteria for RunX releases.
+parent: runx-docs
+children: []
+files:
+  alpha-command-catalog.md: Defines the accepted first-release scope and observable outcomes.
+documents:
+  alpha-command-catalog.md: Requirements for the RunX alpha command catalog.
+tags:
+  - requirements
+keywords:
+  - runx
+  - command catalog
+flags: []
+status: stable
+---
+
+Requirements that drive RunX implementation and validation.

package/docs/todo/implement-runx-alpha.md

@@ -0,0 +1,36 @@
+---
+name: Implement RunX Alpha Command Catalog
+purpose: Define the expected outcome, constraints, and completion signals for task 1 in TODO.md.
+description: Describes the first RunX CLI release and the safety, documentation, and validation constraints that govern it.
+created: 2026-07-12
+flags:
+  - implementation
+tags:
+  - todo
+  - cli
+keywords:
+  - runx
+  - alpha
+owner: runx-todo
+---
+
+# Implement RunX Alpha Command Catalog
+
+## Todo Index
+
+- Task: `1. Implement RunX Alpha Command Catalog`
+- Status: completed
+- Index: [TODO.md](../../TODO.md)
+
+## Outcome
+
+Deliver a documented, locally executable RunX alpha that meets the approved
+command-catalog acceptance criteria without publishing a package.
+
+## Watch-outs
+
+- Preserve read-only behavior for list, describe, check, and dry run paths.
+- Never place secrets in a manifest or run confirmation-gated commands without
+  `--yes`.
+- Keep every new module and document represented by XDocs metadata.
+- Use Mirror for the version transition and keep commits one file at a time.

package/docs/todo/protect-branches-and-tag-creation.md

@@ -0,0 +1,83 @@
+---
+name: Protect RunX Branches and Tag Creation
+purpose: Define the expected outcome, constraints, and completion signals for the highest-priority RunX repository protection task in TODO.md.
+description: Describes the branch protection and tag creation safeguards needed before release activity continues.
+created: 2026-07-12
+flags:
+  - repository-security
+tags:
+  - todo
+  - security
+  - release
+keywords:
+  - runx
+  - branch protection
+  - protected branches
+  - tag creation
+  - release tags
+owner: runx-todo
+---
+
+# Protect RunX Branches and Tag Creation
+
+## Todo Index
+
+- Task: `0. Protect RunX Branches and Tag Creation`
+- Status: completed
+- Priority: highest
+- Index: [TODO.md](../../TODO.md)
+
+## Outcome
+
+RunX has repository rules that protect important branches and restrict tag creation so release history cannot be changed or created without the intended review and authorization controls.
+
+## Scope
+
+### In Scope
+
+- Protect the default branch and any release-maintained branches that RunX uses.
+- Restrict creation of release tags and other protected tag patterns.
+- Confirm the protections match the RunX release and Mirror workflow before release work continues.
+
+### Out of Scope
+
+- Publishing packages, pushing tags, or changing release versions.
+- Bypassing repository protections for local convenience.
+
+## Acceptance Signals
+
+- The RunX repository has branch protection or repository rulesets active for the default branch and any selected release branches.
+- Tag creation is restricted for the relevant release tag patterns.
+- Required maintainers or administrators can verify that the rules are active before the next release/tagging step.
+
+## Active GitHub Rulesets
+
+- [`Protect main`](https://github.com/CGuiho/runx/rules/18933230) - active branch ruleset `18933230` for `refs/heads/main` and `~DEFAULT_BRANCH`; blocks deletion and non-fast-forward updates, requires pull requests, and enables Copilot review on pushes and draft pull requests.
+- [`Protect release tags`](https://github.com/CGuiho/runx/rules/18933243) - active tag ruleset `18933243` for `refs/tags/@guiho*/*@*`; restricts creation, updates, deletion, and non-fast-forward changes and requires linear history.
+
+## Verification Evidence
+
+- GitHub CLI authenticated as repository owner `CGuiho` with the required repository scope.
+- Both rulesets were created with `gh api` using the same active conditions and rule parameters used by the Mirror and XDocs repositories.
+- Both RunX rulesets were read back from the GitHub API after creation and confirmed active.
+- No release tag was created or pushed, and no package was published while configuring the protections.
+
+## Watch-outs
+
+- Do not push tags or publish packages while configuring protections.
+- Coordinate with GitHub permissions and GUIHO release ownership before locking down rules that could block maintainers.
+- Keep Mirror-managed versioning and tag workflows intact; protections should guard the workflow, not replace it.
+
+## Before Starting
+
+- Confirm the GitHub repository, default branch, release branch names, tag patterns, and required approvers.
+- Confirm whether protections should be implemented with classic branch protection rules, repository rulesets, or both.
+
+## After Finishing
+
+- Record the active rules, protected patterns, and any remaining manual verification needed.
+- Update this task status only after the rules are confirmed in GitHub.
+
+## References
+
+- [TODO.md](../../TODO.md)