repo-nexus 0.1.0 → 0.1.2

package/README.md

@@ -5,6 +5,7 @@
 [![License: MIT](https://img.shields.io/github/license/nu-nenoi/repo-nexus)](LICENSE)
 [![POSIX Compatible](https://img.shields.io/badge/POSIX-compatible-success)](#)
 [![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-lightgrey)](#)
+[![FAQ](https://img.shields.io/badge/docs-FAQ-blue.svg)](docs/FAQ.md)
 
 A tooling-independent, zero-dependency workspace orchestrator for multiple repositories with shared, auto-synced AI context across projects using Unix symlinks.
 
@@ -16,6 +17,8 @@ A tooling-independent, zero-dependency workspace orchestrator for multiple repos
 - **Context-aware**: Finds and uses `rnex.yaml` automatically from your current directory or parent tree
 - **Zero dependencies** (pure POSIX shell CLI)
 
+> 💡 **Have questions?** Check out the **[Frequently Asked Questions (FAQ)](docs/FAQ.md)** for architecture deep dives, Git workflows, and AI context strategies.
+
 ---
 
 ## How It Works: The Two Symlink Flows
@@ -172,6 +175,7 @@ repos:
 ```
 
 > See [`docs/rnex.example.yaml`](docs/rnex.example.yaml) for a comprehensive example with all options and supported AI tool configs.
+> For common questions and architecture details, see the [Frequently Asked Questions (FAQ)](docs/FAQ.md).
 
 ---
 
@@ -246,6 +250,7 @@ repo-nexus/
 ├── AGENTS.md                       # Universal AI coding guidelines
 ├── docs/
 │   ├── AGENTS.sample.md            # Template for AGENTS.md
+│   ├── FAQ.md                      # Frequently Asked Questions
 │   └── rnex.example.yaml           # Full config reference with examples
 ├── .github/
 │   ├── workflows/ci.yml            # GitHub Actions CI workflow

package/docs/FAQ.md

@@ -0,0 +1,208 @@
+# Frequently Asked Questions (FAQ)
+
+This document answers common questions about **Repo Nexus (`rnex`)**, why it exists, who it helps, how it handles Git and AI context, and how to use it effectively.
+
+---
+
+## Table of Contents
+
+- [Overview & Value Proposition](#overview--value-proposition)
+  - [Why do I need rnex?](#why-do-i-need-rnex)
+  - [Who is this useful and interesting for?](#who-is-this-useful-and-interesting-for)
+  - [Why not just use a monorepo or Git submodules?](#why-not-just-use-a-monorepo-or-git-submodules)
+- [Architecture & Mechanics](#architecture--mechanics)
+  - [How does rnex work without copying files?](#how-does-rnex-work-without-copying-files)
+  - [What is "Scope In" vs. "Inject Out"?](#what-is-scope-in-vs-inject-out)
+  - [Can I use Git commands (pull, push, commit) on symlinked repos?](#can-i-use-git-commands-pull-push-commit-on-symlinked-repos)
+  - [Can AI agents create and modify files inside member repos via symlinks?](#can-ai-agents-create-and-modify-files-inside-member-repos-via-symlinks)
+  - [Will rnex interfere with Git branches, remotes, or commit histories?](#will-rnex-interfere-with-git-branches-remotes-or-commit-histories)
+- [AI Context Strategy: Workspace vs. Member Repos](#ai-context-strategy-workspace-vs-member-repos)
+  - [Do I need rnex to inject symlinks into my member repos?](#do-i-need-rnex-to-inject-symlinks-into-my-member-repos)
+  - [How should AI instructions be structured across repos? (Committed files vs. symlinks)](#how-should-ai-instructions-be-structured-across-repos-committed-files-vs-symlinks)
+  - [Which AI assistants and configuration files are supported?](#which-ai-assistants-and-configuration-files-are-supported)
+  - [How do I prevent AI agents from running out of context or token bloat?](#how-do-i-prevent-ai-agents-from-running-out-of-context-or-token-bloat)
+- [Platforms & Setup](#platforms--setup)
+  - [What are the system requirements? Does it work on Windows?](#what-are-the-system-requirements-does-it-work-on-windows)
+  - [Does rnex have external dependencies?](#does-rnex-have-external-dependencies)
+  - [What files in a workspace should be committed to Git?](#what-files-in-a-workspace-should-be-committed-to-git)
+  - [How do I fix broken or missing symlinks?](#how-do-i-fix-broken-or-missing-symlinks)
+
+---
+
+## Overview & Value Proposition
+
+### Why do I need rnex?
+
+Modern AI coding assistants (like Cursor, Claude Code, GitHub Copilot, and Antigravity) are designed around a single project root. In real-world software development, applications are rarely confined to a single repository—they are split into frontend apps, backend APIs, shared libraries, infrastructure, and documentation.
+
+This creates two major frictions:
+1. **Siloed Context**: To perform cross-service tasks (e.g. updating an API endpoint and consuming it in the web frontend), you must juggle multiple IDE windows or repeatedly explain code structures between projects.
+2. **Instruction Drift**: As you tune your AI coding guidelines (like coding style, testing requirements, or forbidden patterns), keeping these instructions synced across 5, 10, or 20 separate repositories requires tedious manual updates.
+
+**`rnex` solves both problems**:
+- It unites independent repositories under one virtual workspace using Unix symlinks.
+- It provides a single source of truth for shared AI context files (`AGENTS.md`, Copilot instructions, Cursor rules) without requiring monorepo migrations.
+
+---
+
+### Who is this useful and interesting for?
+
+- **Polyrepo & Microservice Developers**: Engineers whose day-to-day work spans multiple microservices or separated frontends and backends, and who want an AI assistant that can navigate across repository boundaries seamlessly.
+- **Tech Leads & Platform Teams**: Engineering leaders who want to standardize AI instructions and architectural constraints across team repositories without forcing developers into a monorepo.
+- **Solo Developers & Indie Hackers**: Creators juggling a collection of related projects (e.g., mobile app + backend API + landing page + SDK) who want rapid cross-project AI capabilities.
+- **AI Agent Power Users**: Developers using multi-repo autonomous agents (such as Claude Code, Aider, or Antigravity) that require unified file tree visibility.
+
+---
+
+### Why not just use a monorepo or Git submodules?
+
+| Solution | Drawbacks | How `rnex` compares |
+| :--- | :--- | :--- |
+| **Git Monorepo** | Heavy migration effort, combined CI/CD pipelines, complex permission management, slow Git checkouts. | **Zero migration**: Repositories remain completely independent with their own remotes, histories, and deployment pipelines. |
+| **Git Submodules** | Detached HEAD states, tricky merge conflicts, complex multi-step commits, rigid parent-child coupling. | **No Git friction**: Member repositories are linked via filesystem symlinks. Git never tracks other repos as submodules. |
+| **Manual Copy-Paste** | AI configuration files rapidly drift out of sync across repositories. | **Auto-synced**: Edit `AGENTS.md` once in the workspace; changes immediately reflect across all member repositories. |
+
+---
+
+## Architecture & Mechanics
+
+### How does rnex work without copying files?
+
+`rnex` uses native **Unix symbolic links (symlinks)**. Symlinks act as transparent pointers at the filesystem level. Rather than duplicating files or creating complex mount points, your operating system, Git, and IDE resolve the symlinks directly to the original directories on disk.
+
+---
+
+### What is "Scope In" vs. "Inject Out"?
+
+`rnex` offers two complementary symlink flows:
+
+1. **Scope In (Repos into Workspace)**:
+   When you run `rnex add <name> <path>`, a symlink is created at `repos/<name>` pointing to the source project directory. Opening the workspace directory in your editor gives you (and your AI assistant) full access to all linked repositories in a single file tree.
+2. **Inject Out (AI Context into Member Repos)**:
+   Shared configuration files defined in `rnex.yaml` (such as `AGENTS.md`) can be symlinked from the workspace into the root of every member repository. Opening a repository standalone allows standalone IDE windows to discover the shared rules as local files.
+
+---
+
+### Can I use Git commands (pull, push, commit) on symlinked repos?
+
+**Yes.** Git works completely normally.
+* **Operating inside `repos/<name>/`**: When you or your IDE navigate into `repos/<name>/` and run `git status`, `git commit`, `git pull`, or `git push`, Git follows the symlink, discovers the real `.git` directory, and operates directly against that repository's own branches and remotes.
+* **Operating in the source directory**: Any changes made from the workspace are immediately present in the source repo on disk. You can run all Git operations in the original folder as usual.
+
+---
+
+### Can AI agents create and modify files inside member repos via symlinks?
+
+**Yes.** Any file an AI agent creates or edits under `repos/<name>/...` (e.g. `repos/backend/src/service.ts`) is written **directly through the symlink into the underlying repository on disk**.
+- These are genuine application files, not symlinks.
+- They are immediately detected by Git in that member repo.
+- You or the agent can commit and push them directly to that repository.
+
+---
+
+### Will rnex interfere with Git branches, remotes, or commit histories?
+
+**No.** Each member repository retains its own Git history, remotes, and branch topology.
+The Repo Nexus workspace ignores `repos/` in `.gitignore`, ensuring your workspace Git repository never accidentally tracks or commits member repository contents.
+
+---
+
+## AI Context Strategy: Workspace vs. Member Repos
+
+### Do I need rnex to inject symlinks into my member repos?
+
+**Not necessarily.** If your primary workflow is opening the Nexus workspace root (or relying on global workstation AI configs), you do **not** need `rnex` to inject symlinks into member repos.
+
+Running in **Zero-Touch Mode** (`ai_files: []` in `rnex.yaml`):
+- Keeps member repositories 100% pristine.
+- Prevents temporary symlinks or `.gitignore` modifications inside member repos.
+- The AI agent will read `AGENTS.md` directly from the workspace root and apply it across all linked projects.
+
+"Inject Out" is only needed if you frequently open individual member repositories standalone in an editor without opening the Nexus workspace, yet still want that standalone window to pick up shared rules.
+
+---
+
+### How should AI instructions be structured across repos? (Committed files vs. symlinks)
+
+The cleanest architecture separates concerns into two distinct layers:
+
+1. **Workspace Level (Nexus Root)**:
+   Contains multi-repo context, cross-service orchestrations, and workspace-wide rules in `AGENTS.md`.
+2. **Member Repo Level (Committed Files)**:
+   Individual repositories can maintain their own domain-specific AI instructions (e.g., repository `.cursorrules`, `CLAUDE.md`, or component conventions) as **real, first-class files committed to Git**.
+
+**Why real committed files are better than injected symlinks for member repos**:
+- **Shared with the Team**: Anyone on the team who clones the repo immediately gets the rules without needing `rnex` or symlinks.
+- **No Path Fragility**: Symlinks pointing back to an external workspace break if cloned on another computer or Windows. Committed files never break.
+- **Repository Autonomy**: Each project remains self-documenting and independent.
+
+---
+
+### Which AI assistants and configuration files are supported?
+
+`rnex` is tool-agnostic and auto-detects or syncs standard configuration files for:
+
+- **Universal Agents**: `AGENTS.md`
+- **Claude Code**: `CLAUDE.md`
+- **Cursor**: `.cursorrules`, `.cursor/rules/`
+- **Windsurf / Codeium**: `.windsurfrules`, `.windsurf/rules/`
+- **GitHub Copilot**: `.github/copilot-instructions.md`
+- **Aider**: `.aider.conf.yml`, `CONVENTIONS.md`
+- **Cline / Roo Code**: `.clinerules`
+- **Codex**: `CODEX.md`
+- **Continue.dev**: `.continue/`
+- **Skills Standards**: `SKILL.md`
+
+You can add any custom file or prompt template to the `ai_files` list in `rnex.yaml`.
+
+---
+
+### How do I prevent AI agents from running out of context or token bloat?
+
+When managing many repositories, exposing all of them at once can fill your AI model's context window or increase prompt latency.
+
+`rnex` provides scope toggles:
+- **`rnex hide <name>`**: Temporarily removes the symlink from `repos/`, hiding the repo from active AI indexing without unregistering it.
+- **`rnex show <name>`**: Restores the symlink to active workspace scope when you need to work on it again.
+- **`rnex list`**: Displays which repos are currently `visible` or `hidden`.
+
+---
+
+## Platforms & Setup
+
+### What are the system requirements? Does it work on Windows?
+
+- **Supported Platforms**: macOS and Linux.
+- **Windows**: Not officially supported natively due to Windows symlink permission restrictions (requiring Developer Mode or elevated privileges) and POSIX shell requirements. However, `rnex` runs smoothly inside **WSL2 (Windows Subsystem for Linux)**.
+
+---
+
+### Does rnex have external dependencies?
+
+**No.** The `rnex` executable is written in pure POSIX shell script (`/bin/sh`) with zero runtime dependencies. It does not require Node.js, Python, or external package managers to function.
+
+For convenience, `rnex` is also published as an npm package (`npm install -g repo-nexus`) so JavaScript/TypeScript developers can install it globally via standard tooling.
+
+---
+
+### What files in a workspace should be committed to Git?
+
+In your Repo Nexus workspace repository:
+- **Commit**: `rnex.yaml`, `AGENTS.md`, documentation (`docs/`), toolkit prompts/templates, and CI configs.
+- **Do NOT Commit**: `repos/` (this directory should always be in `.gitignore`, as it only contains local symlinks to your projects).
+
+---
+
+### How do I fix broken or missing symlinks?
+
+If you move a repository, clone a workspace on a new machine, or notice missing symlinks, run:
+
+```bash
+rnex sync
+```
+
+This command reconciles all symlinks for member repositories and AI context files defined in `rnex.yaml`, repairing broken links and ensuring your workspace is healthy. To inspect the current status, run:
+
+```bash
+rnex status
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-nexus",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Tooling-independent multi-repo workspace manager with auto-synced AI context via symlinks",
   "bin": {
     "repo-nexus": "./rnex",
@@ -43,4 +43,4 @@
     "darwin",
     "linux"
   ]
-}
+}

package/rnex

@@ -20,11 +20,11 @@ fi
 
 # ---- Logging ---------------------------------------------------------------
 
-log_ok()   { printf "${_G}[✓]${_NC} %s\n" "$1"; }
-log_warn() { printf "${_Y}[!]${_NC} %s\n" "$1"; }
-log_err()  { printf "${_R}[✗]${_NC} %s\n" "$1" >&2; }
-log_info() { printf "${_C}[i]${_NC} %s\n" "$1"; }
-log_dim()  { printf "${_DIM}    %s${_NC}\n" "$1"; }
+log_ok()   { printf '%b[✓]%b %b\n' "$_G" "$_NC" "$1"; }
+log_warn() { printf '%b[!]%b %b\n' "$_Y" "$_NC" "$1"; }
+log_err()  { printf '%b[✗]%b %b\n' "$_R" "$_NC" "$1" >&2; }
+log_info() { printf '%b[i]%b %b\n' "$_C" "$_NC" "$1"; }
+log_dim()  { printf '%b    %b%b\n' "$_DIM" "$1" "$_NC"; }
 die()      { log_err "$1"; exit 1; }
 
 # ---- Path Utilities --------------------------------------------------------
@@ -377,13 +377,13 @@ AGENTS_EOF
   fi
 
   # ---- Auto-detect existing AI config files --------------------------------
-  printf "\n${_BOLD}Scanning for existing AI configuration files...${_NC}\n"
+  printf '\n%b%s%b\n' "$_BOLD" "Scanning for existing AI configuration files..." "$_NC"
 
   # Display detected files
   echo "$_AI_KNOWN_FILES" | while IFS='|' read -r _pattern _desc; do
     [ -n "$_pattern" ] || continue
     if [ -e "$_target_dir/$_pattern" ]; then
-      printf "  ${_G}✓${_NC} Found: ${_BOLD}%s${_NC}  ${_DIM}(%s)${_NC}\n" "$_pattern" "$_desc"
+      printf '  %b✓%b Found: %b%s%b  %b(%s)%b\n' "$_G" "$_NC" "$_BOLD" "$_pattern" "$_NC" "$_DIM" "$_desc" "$_NC"
     fi
   done
 
@@ -488,7 +488,7 @@ cmd_hide() {
 
 cmd_list() {
   require_workspace
-  printf "${_B}%-25s %-12s %s${_NC}\n" "NAME" "SCOPE" "PATH"
+  printf '%b%-25s %-12s %s%b\n' "$_B" "NAME" "SCOPE" "PATH" "$_NC"
   printf '%-25s %-12s %s\n' "----" "-----" "----"
   yaml_list_repos | while read -r _name; do
     _scope="$(yaml_get "$_name" "scope")"
@@ -502,23 +502,23 @@ cmd_status() {
   require_workspace
   ensure_repos_dir
 
-  printf "\n${_B}Repo Nexus Workspace Status${_NC}\n"
+  printf '\n%b%s%b\n' "$_B" "Repo Nexus Workspace Status" "$_NC"
   printf '=%.0s' 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
   printf '\n\n'
 
-  printf "${_BOLD}Configured AI Context Files ($RNEX_CONFIG_FILE):${_NC}\n"
+  printf '%bConfigured AI Context Files (%s):%b\n' "$_BOLD" "$RNEX_CONFIG_FILE" "$_NC"
   yaml_list_ai_files | while read -r _item; do
     if [ -e "$NEXUS_DIR/$_item" ]; then
-      printf "  ${_G}✓${_NC} %s\n" "$_item"
+      printf '  %b✓%b %s\n' "$_G" "$_NC" "$_item"
     else
-      printf "  ${_R}✗${_NC} %s (missing from nexus root)\n" "$_item"
+      printf '  %b✗%b %s (missing from nexus root)\n' "$_R" "$_NC" "$_item"
     fi
   done
   printf '\n'
 
-  printf "${_BOLD}Member Repositories:${_NC}\n"
+  printf '%b%s%b\n' "$_BOLD" "Member Repositories:" "$_NC"
   if [ -z "$(yaml_list_repos)" ]; then
-    printf "  ${_DIM}(No repositories registered yet. Use 'rnex add <name> <path>')${_NC}\n"
+    printf '  %b%s%b\n' "$_DIM" "(No repositories registered yet. Use 'rnex add <name> <path>')" "$_NC"
   else
     yaml_list_repos | while read -r _name; do
       _scope="$(yaml_get "$_name" "scope")"
@@ -526,20 +526,20 @@ cmd_status() {
       _link="$REPOS_DIR/$_name"
 
       if [ "$_scope" = "hidden" ]; then
-        printf "  ${_Y}○${_NC} %-22s ${_DIM}hidden${_NC}\n" "$_name"
+        printf '  %b○%b %-22s %bhidden%b\n' "$_Y" "$_NC" "$_name" "$_DIM" "$_NC"
       elif [ -L "$_link" ] && [ -d "$_link" ]; then
-        printf "  ${_G}●${_NC} %-22s ${_G}active${_NC} → %s\n" "$_name" "$_path"
+        printf '  %b●%b %-22s %bactive%b → %s\n' "$_G" "$_NC" "$_name" "$_G" "$_NC" "$_path"
       elif [ -L "$_link" ]; then
-        printf "  ${_R}✗${_NC} %-22s ${_R}BROKEN LINK${_NC} → %s\n" "$_name" "$_path"
+        printf '  %b✗%b %-22s %bBROKEN LINK%b → %s\n' "$_R" "$_NC" "$_name" "$_R" "$_NC" "$_path"
       else
-        printf "  ${_R}✗${_NC} %-22s ${_R}MISSING LINK${_NC} (run 'rnex sync')\n" "$_name"
+        printf '  %b✗%b %-22s %bMISSING LINK%b %s\n' "$_R" "$_NC" "$_name" "$_R" "$_NC" "(run 'rnex sync')"
       fi
     done
   fi
 
-  printf "\n${_DIM}Workspace:   %s${_NC}\n" "$NEXUS_DIR"
-  printf "${_DIM}Repos Dir:   %s${_NC}\n" "$REPOS_DIR"
-  printf "${_DIM}Config:      %s${_NC}\n\n" "$WORKSPACE_YAML"
+  printf '\n%bWorkspace:   %s%b\n' "$_DIM" "$NEXUS_DIR" "$_NC"
+  printf '%bRepos Dir:   %s%b\n' "$_DIM" "$REPOS_DIR" "$_NC"
+  printf '%bConfig:      %s%b\n\n' "$_DIM" "$WORKSPACE_YAML" "$_NC"
 }
 
 cmd_sync() {
@@ -598,7 +598,7 @@ cmd_install() {
 }
 
 cmd_version() {
-  printf "rnex %s\n" "$RNEX_VERSION"
+  printf 'rnex %s\n' "$RNEX_VERSION"
 }
 
 cmd_help() {