dev_context 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ec8da4562204b25b61b33aa7c0bcf48e75c4db79d85ad153f59c86dffad62a1
+  data.tar.gz: 5c7a271e4eabb39c9e60d009c0da8a983b4d2e907029c32b095e46cda997b60b
+SHA512:
+  metadata.gz: b8c424382c0f58b5be6254621cec4cc6b0a204a5f934417fdaec0f5f4a1f98da35877709d54c278116bf7b3ed394dfd616d2721cfe6b3fa884ca55214aeebe16
+  data.tar.gz: 0e9458aa53afb5729b9270e56b90ff0e1be01ef3e56a00818a0843e6a0206949672f3c69edc6381b0163ab74d7a711871c9b09d19a38f7a9c7a79e68eeb4e4a3

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-05-01
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,18 @@
+# Code of Conduct
+
+This repository, "dev_context", follows [The Ruby Community Conduct
+Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space",
+which is defined as community communications channels (such as mailing lists,
+submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+
+* Participants must ensure that their language and actions are free of personal
+* attacks and disparaging personal remarks.
+
+* When interpreting the words and actions of others, participants should always
+* assume good intentions.
+
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["aks@stebbens.org"](mailto:"aks@stebbens.org").

data/DESIGN.md

@@ -0,0 +1,250 @@
+# dx — DevContext: Design
+
+`dx` is a Ruby CLI for managing development context across repositories and branches.
+It is the layer between filesystem navigation, Git branch intent, and daily workflow.
+
+---
+
+## 1) Core Model
+
+- **Context identity:** a context is exactly one pair: `(repo_dir, branch)`.
+- **Context naming:** a context name is either:
+  - explicit (provided by user), or
+  - implicit: `<repo_basename>:<branch>`.
+- **Name normalization:** all context names are stored lowercase; lookup is case-insensitive.
+- **Active stack:** `dx` maintains an ordered stack of active contexts, most recent first.
+- **Scope for status/diff/branches/wip:** operates on active contexts.
+
+---
+
+## 2) Shell Integration Model
+
+Because a child process cannot change the parent shell CWD, `dx` is used through a shell function wrapper.
+
+- The wrapper calls the Ruby executable and evaluates emitted shell for stateful commands.
+- The Ruby executable supports:
+  - **shell-emitting mode** for commands like `cd`, `activate`, `pushd`, and `popd`
+  - **plain output mode** for report commands like `status`, `diff`, `branches`, `wip`
+- Shell-emitting responses are prefixed with a marker (`# DX_SHELL_EVAL`) so wrappers can detect eval-safe output without hardcoding command names.
+
+### Required behavior
+
+- `dx cd ...` changes the current shell directory.
+- `dx activate ...` also changes directory (same destination semantics as `dx cd`).
+- `dx pushd ...` changes current shell directory and pushes context on active stack.
+- `dx popd ...` removes context from active stack and changes directory to new top context when present.
+- On partial failure (for example pull conflict), CWD remains in the target repo to enable direct investigation.
+
+---
+
+## 3) Activation Semantics
+
+Activating a context should be DWIM and deterministic:
+
+1. Resolve the requested context (exact name, exact path, FSF fuzzy).
+2. Ensure repository exists and is a valid Git repo.
+3. Resolve/switch branch:
+   - if branch exists locally: checkout it
+   - else if remote branch exists and `DX_AUTO_CREATE_LOCAL_BRANCH=true`: create tracking branch
+   - else fail with actionable guidance
+4. Pull latest changes using configured remote policy.
+5. Persist activation metadata (`last_used_at`, active stack update).
+
+### Pull behavior UX
+
+- Use safe defaults (fast-forward only).
+- If pull fails:
+  - keep user in target repo/branch
+  - return non-zero
+  - print short next-step hints (`git status`, conflict resolution, retry strategy)
+
+---
+
+## 4) Remote Resolution Policy
+
+- `DX_GIT_REMOTE_NAME=USE-REPO` by default.
+- If `USE-REPO`, resolve remote from the repository itself:
+  - prefer branch upstream (`@{upstream}`)
+  - otherwise use single-remote fallback when unambiguous
+  - fail with guidance when ambiguous or absent
+- If `DX_GIT_REMOTE_NAME=<name>` (for example `origin`), force that remote.
+
+`~/.dxcf` does not duplicate Git remote topology; Git remains source of truth.
+
+---
+
+## 5) Global Config: `~/.dxcf`
+
+Store as YAML. Suggested v1 shape:
+
+```yaml
+version: 1
+
+contexts:
+  dev_context:main:
+    name: dev_context:main
+    repo_path: /Users/aks/src/github/aks/dev_context
+    branch: main
+    created_at: 2026-05-12T09:30:00Z
+    last_used_at: 2026-05-12T10:15:00Z
+
+active_stack:
+  - dev_context:main
+
+repos:
+  dev_context:
+    path: /Users/aks/src/github/aks/dev_context
+    last_seen_at: 2026-05-12T10:15:00Z
+
+clone_roots:
+  - /Users/aks/src/github
+```
+
+Notes:
+- context key collisions are prevented via normalized lowercase naming
+- repo metadata and context metadata are separate concerns
+
+---
+
+## 6) Name Resolution and Matching
+
+Resolution order for context arguments:
+
+1. exact context name match
+2. exact path match
+3. `DX_PATH` + `DX_CLONE_BASE_DIR` directory search for relative repo targets
+4. FSF-style fuzzy match against known context names and repo basenames
+
+If fuzzy matching returns multiple candidates, `dx` lists them and exits non-zero.
+
+---
+
+## 7) URL and Path Handling
+
+Accepted location inputs:
+
+- relative path (`./api`)
+- absolute path (`/Users/aks/src/github/api`)
+- Git URL (`https://github.com/org/repo.git`, `git@github.com:org/repo.git`)
+
+`DX_PATH` behavior for repo target lookup:
+
+- `DX_PATH` is a path-separated list of directories (like `PATH`).
+- When a relative target is not found under current working directory, `dx` searches each `DX_PATH` root and `DX_CLONE_BASE_DIR` for `<root>/<target>`.
+- A single match is accepted.
+- Multiple matches are treated as ambiguous and fail with candidate listing.
+- If exact path search does not find a unique match, `dx` performs FSF subsequence matching across directory basenames in those roots.
+
+URL behavior:
+
+1. derive repo basename (`repo.git` -> `repo`)
+2. place clone under `clone_roots`/`DX_CLONE_BASE_DIR` policy
+3. clone if missing, otherwise reuse existing path
+4. register repo and optionally create context
+5. activate/cd when command requires it
+
+---
+
+## 8) Command Set (v1)
+
+- `dx init`
+- `dx add PATH|URL ...`
+- `dx create NAME [PATH] [BRANCH]`
+- `dx cd CONTEXT|PATH|URL`
+- `dx activate CONTEXT|PATH|URL`
+- `dx pushd CONTEXT|PATH|URL`
+- `dx popd [CONTEXT]`
+- `dx deactivate CONTEXT`
+- `dx active`
+- `dx status` (`dx wip` alias allowed)
+- `dx diff [CONTEXT]`
+- `dx branches [CONTEXT]`
+- `dx co -b FEATURE [CONTEXT]`
+- `dx help [COMMAND]`
+- `dx doctor` (or `dx check`)
+
+---
+
+## 9) Status Output Contract
+
+Single-line status summary per active context:
+
+- `m`: staged modified count
+- `u`: unstaged modified count
+- `n`: new/untracked count
+- `d`: deleted count
+- `r`: renamed count
+
+Example:
+
+`m:0 u:10 n:26 d:3 r:0`
+
+If all counts are zero, display `Up to date`.
+
+---
+
+## 10) High-Level Ruby Architecture
+
+- `DevContext::CLI` - argument parsing and command dispatch
+- `DevContext::Config` - load/save/validate `~/.dxcf`
+- `DevContext::Context` - context value object `(repo_path, branch, name)`
+- `DevContext::Registry` - known repos and contexts
+- `DevContext::Matcher` - exact/fuzzy resolution
+- `DevContext::Git` - status, branch, pull, checkout helpers
+- `DevContext::ShellEmitter` - emits safe shell snippets for stateful commands
+- `DevContext::Commands::*` - command handlers
+- `DevContext::JJ` - optional read-only integration
+- `DevContext::TUI` - optional dashboard (future)
+
+Execution flow:
+
+1. Parse command
+2. Load config
+3. Resolve target (name/path/url)
+4. Perform command logic (Git + config updates)
+5. Emit shell script or plain output
+6. Return stable exit code
+
+---
+
+## 11) DWIM UX Contract
+
+`dx` is a DWIM-first CLI: easy, intuitive, forgiving, and discoverable.
+
+- **Default usefulness**
+  - Bare `dx` performs the most useful safe default for initialized users (`dx status`).
+  - If uninitialized, `dx` guides user to `dx init`.
+
+- **Help discoverability**
+  - `dx help`
+  - `dx help <command>`
+  - `dx <command> --help`
+  - All three forms are supported and consistent.
+
+- **Name resolution**
+  - Context lookup order: exact name -> exact path -> FSF fuzzy match.
+  - Matching is case-insensitive; stored context names are lowercase.
+  - Ambiguous fuzzy matches never guess silently; show candidates and exit non-zero.
+
+- **Error ergonomics**
+  - Every error message includes:
+    - what failed
+    - why (if known)
+    - one concrete next command
+  - Prefer short, actionable output over long diagnostics.
+
+- **Activation behavior**
+  - `dx activate` / `dx cd` prioritize flow:
+    - switch to target repo/branch
+    - attempt pull using configured policy
+  - On pull failure, keep user in target repo for investigation.
+  - Return non-zero on failure so scripts can detect problems.
+
+- **Safe automation**
+  - Non-destructive by default.
+  - No silent data-changing operations without explicit user intent.
+  - Behavior controlled by env vars with sensible defaults.
+
+- **Operator confidence**
+  - `dx doctor` (or `dx check`) validates shell integration, config, and git availability.
+  - Command output is stable and script-friendly when possible.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alan Stebbens
+
+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.

data/README.md

@@ -0,0 +1,184 @@
+# DevContext (dx)
+
+This repo contains `dx` (`dev_context`), a script for managing developer context across repository directories and branches.
+
+A context is one `(repo_dir, branch)` pair. Context names can be explicit, or implicit as `<repo_basename>:<branch>` (stored lowercase), and resolved with exact then FSF-style fuzzy matching.
+
+## Installation
+
+    gem install -n ~/bin dev_context
+
+Install the gem in the current ruby gem path, with the executable installed as `~/bin/dev_context.rb`.
+
+To clone from the github repo:
+
+    cd ~/src/github    # or wherever you keep github repos
+    git clone https://github.com/aks/dev_context.git
+    cd dev_context
+    bundle install
+    bundle exec rake install
+
+## Usage
+
+### Current model (authoritative)
+
+- A context is exactly one repo+branch pair (not a multi-repo aggregate).
+- `dx cd` and `dx activate` both activate the target context and change CWD via shell integration.
+- Activation attempts branch checkout + pull; on pull failure, CWD remains in the target repo for investigation and the command exits non-zero.
+- Defaults:
+  - `DX_AUTO_CREATE_LOCAL_BRANCH=true`
+  - `DX_GIT_REMOTE_NAME=USE-REPO` (or explicit like `origin`)
+
+### Shell integration
+
+To support `cd`, `dx` should be wrapped by a shell function that evaluates shell output for stateful commands.
+
+```bash
+dx() {
+  case "$1" in
+    cd|activate|pushd|popd)
+      local out
+      out="$(DX_SHELL_WRAPPED=1 command dev_context.rb "$@")" || return $?
+      case "$out" in
+        "# DX_SHELL_EVAL"*) eval "$out" ;;
+        *) printf "%s\n" "$out" ;;
+      esac
+      ;;
+    *)
+      command dev_context.rb "$@"
+      ;;
+  esac
+}
+```
+
+In the descriptions below, the following terms are used consistently:
+
+- `NAME`: the context NAME (which can match a PATH)
+
+- `PATH`: the file system path to a single repository directory.
+
+- `URL`:  a standard http/https/git scheme URL that leads to a git-based
+          repository.
+
+- `CONTEXT`: a context name, a `PATH`, or `URL` that identifies one context.
+             Implicit naming uses `<repo_basename>:<branch>`.
+
+### Common Options
+
+These options are currently supported on `dx add`, `dx clone`, and `dx create`:
+
+- `-c, --context NAME`: explicit context name
+- `-n, --norun`: preview actions without changing state
+- `-v, --verbose`: print extra command details
+
+Examples:
+
+```bash
+dx add -c api:main ~/src/github/api
+dx clone -n https://github.com/acme/tooling.git
+dx create -v feature:abc-123 ~/src/github/dev_context feature/abc-123
+```
+
+### Context stack commands
+
+- `dx pushd CONTEXT|PATH|URL`: activate and push context to top of stack
+- `dx popd [CONTEXT]`: pop the top context (or a specific one); if a new top exists, switch CWD to it
+
+### `DX_PATH` repo lookup
+
+`DX_PATH` can be used as a list of parent directories that contain repositories.
+
+- Format: path-separated directories (same separator as shell `PATH`)
+- Example:
+
+```bash
+export DX_PATH="$HOME/src/github:$HOME/src/work"
+dx add dev_context
+```
+
+Lookup behavior for relative repo targets:
+
+1. check current directory-relative path
+2. check each `DX_PATH` root and `DX_CLONE_BASE_DIR` as `<root>/<target>`
+3. if needed, run FSF subsequence search across repo directory names in those roots
+4. if one match is found, use it
+5. if multiple matches are found, fail and list candidates
+
+### Initialization and Adding Directories
+
+    dx [init | help]
+    dx init
+    dx help
+
+The first thing to do is to initialize `dx` with one or more repo directories.
+They do not need to be added but, they can be discovered automatically with `dx
+add PATH`.
+
+When initialized, a `~/.dxcf` file will exist with the current `dx` settings.
+
+When `dx` is invoked without any arguments (or options), and `~/.dxcf` does
+*not* exist, then `dx init` is performed.  `dx init` returns exit code 0
+(success) when it actually succeeds in performing the initialization; it returns
+1 (fail) otherwise.
+
+When `dx` is invoked without any arguments or options, and `~/.dxcf`
+*already* exists, `dx` defaults to `dx status`.
+
+| dx command | ~/.dxcf? | action      |
+| ---------- | -------- | ----------- |
+| `dx`       | no       | `dx init`   |
+| `dx`       | yes      | `dx status` |
+
+> Note: some command examples below were written before the current context model was finalized.
+> The authoritative behavior is defined in the "Current model (authoritative)" section above and in `DESIGN.md`.
+
+### Command reference (v1)
+
+```text
+dx init
+dx add PATH|URL ...
+dx clone URL [PATH]
+dx create NAME [PATH] [BRANCH]
+dx remove CONTEXT|PATH
+dx active
+dx activate CONTEXT|PATH|URL
+dx cd CONTEXT|PATH|URL
+dx deactivate CONTEXT
+dx pushd CONTEXT|PATH|URL
+dx popd [CONTEXT]
+dx status|wip [--all] [--dirty] [-b BRANCHPATTERN] [-p PATHPATTERN]
+dx repos [-b BRANCHPATTERN] [-p PATHPATTERN] [PATTERN]
+dx stashes [--list] [PATTERN]
+dx find [--stashes|--branches|--paths] <pattern>
+dx find --all
+dx branches|br [CONTEXT|PATTERN]
+dx checkout|co [-b] FEATURE [CONTEXT]
+dx diff [CONTEXT]
+```
+
+Notes:
+
+- `dx add` accepts one or more `PATH`/`URL` targets; there is no trailing aggregate context argument.
+- `dx add URL` behaves like clone+register for that repo.
+- `dx stashes [PATTERN]`, `dx repos [PATTERN]`, and `dx branches [PATTERN]` are focused find-style shortcuts.
+- `dx <pattern>` is shorthand for `dx find <pattern>` when the first token is not a command.
+- `dx wip` is `dx status --dirty` by default.
+- `dx status`/`dx wip` show stash count as `s:<count>` when non-zero.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/aks/dev_context. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/aks/dev_context/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+MIT License — see [LICENSE.txt](LICENSE.txt).
+
+## Code of Conduct
+
+Please adhere to our [code of conduct](https://github.com/aks/dev_context/blob/main/CODE_OF_CONDUCT.md).

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "dev_context"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/dev_context.rb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/dev_context"
+
+exit DevContext::CLI.run(ARGV)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/dev_context/cli.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "shellwords"
+require "fileutils"
+require "pathname"
+require "optparse"
+
+module DevContext
+  class CLI
+    include Commands::Init
+    include Commands::Help
+    include Commands::Support
+    include Commands::ContextLifecycle
+    include Commands::GitOps
+    include Commands::SearchHelpers
+    include Commands::Find
+    include Commands::Repos
+    include Commands::Stashes
+    include Commands::Status
+    include Commands::Remove
+
+    COLOR_RESET = "\e[0m"
+    COLOR_ORANGE = "\e[38;5;208m"
+    COLOR_CYAN = "\e[36m"
+    COLOR_GREEN = "\e[32m"
+    COLOR_RED = "\e[31m"
+    COLOR_YELLOW = "\e[33m"
+    COLOR_MAGENTA = "\e[35m"
+
+    def self.run(argv, out: $stdout, err: $stderr, env: ENV, pwd: Dir.pwd)
+      new(argv, out: out, err: err, env: env, pwd: pwd).run
+    end
+
+    def initialize(argv, out:, err:, env:, pwd:)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @env = env
+      @pwd = pwd
+      @config = Config.new
+      @matcher = Matcher.new(config: @config)
+    end
+
+    def run
+      raw_command = argv.shift
+
+      return default_action if raw_command.nil?
+
+      resolution = resolve_command(raw_command)
+      command = resolution[:command]
+      if command.nil?
+        if resolution[:error] == :unknown && !raw_command.start_with?("-")
+          argv.unshift(raw_command)
+          return cmd_find
+        end
+        return 1
+      end
+
+      if %w[--help -h].include?(argv.first)
+        argv.shift
+        return cmd_help_topic(command)
+      end
+
+      case command
+      when "init" then cmd_init
+      when "help", "--help", "-h" then cmd_help
+      when "add" then cmd_add
+      when "clone" then cmd_clone
+      when "create" then cmd_create
+      when "remove" then cmd_remove
+      when "active" then cmd_active
+      when "deactivate" then cmd_deactivate
+      when "find" then cmd_find
+      when "stashes" then cmd_stashes
+      when "repos" then cmd_repos
+      when "status", "wip" then cmd_status(mode: command)
+      when "diff" then cmd_diff
+      when "branches", "br" then cmd_branches
+      when "co", "checkout" then cmd_checkout
+      when "cd", "activate", "pushd" then cmd_activate
+      when "popd" then cmd_pop
+      else
+        err.puts("dx: unknown command '#{raw_command}'")
+        cmd_help
+        1
+      end
+    end
+
+    private
+
+    attr_reader :argv, :out, :err, :env, :pwd, :config, :matcher
+
+    COMMANDS = %w[
+      init help add clone create remove active deactivate find repos stashes status wip diff branches br co checkout cd activate pushd popd
+    ].freeze
+
+    def default_action
+      return cmd_init unless config.initialized?
+
+      cmd_status
+    end
+  end
+end