dkit 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 53e0c6ec379900435c8ecf139f2960b5438df945e674a6709be32a71732fd9e9
-  data.tar.gz: f2b8ad870c59fc01acba6640e6c02cb13216a303373cfb7e008a2dd3d1e4d7fd
+  metadata.gz: a173ce3a5064aaf3e9a5526d56778f31d120143895b4f50c05d72040ab29dcf0
+  data.tar.gz: 4fc0ee2bc56023dd5c4e41bab23074c625feda03973bc580a23d8cd9f4658f35
 SHA512:
-  metadata.gz: 788dcd77ebde166204346894dacc6772fbd04fe613acef1a6b72f16fff26f7894a238948d3d26c59377a942c9b28081d28a9b03b366b59a8cddf0372df1dd536
-  data.tar.gz: 1d19f03a3b15edf459ad0d20806ed4abce82983b3db85fedd98be820f1b6a9b96a6ee351fc4294908b8cdec56ab496a432bb1eb8bf1a67bb665af86a2fe639e7
+  metadata.gz: b2240d8964608f615e1355b2c3fb1825851b298d9c16f6682fde69a809beb5856b0d2231d74f16ac854d6d22e9d34b3380ec616f90159a500cdeefbd2aabda72
+  data.tar.gz: a11f2cb2be61440684ebd4fc25dacd3ad8b98a59adbba51651402dece54dd5caaf97dee9c26b077e1ee35f1cd748508c805ff0f2df40143128afc1b44bf649b3

data/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2026-04-13
+
+### Added
+- Verbose routing messages: when a command is intercepted, prints `[dkit] <cmd> → <container>` to stderr before executing
+- `verbose_enabled?` helper that checks both env var and intercept file directive
+- Disable per-project: add `verbose: false` to `.devcontainer/dkit-intercept` (committed, shared with team)
+- Disable personally: set `DKIT_VERBOSE=0` env var (takes precedence over intercept file)
+- `dkit init` now includes `# verbose: false` comment in the generated intercept file
+
+### Changed
+- `dkit help` documents verbose configuration options
+
+### Notes
+- Compatible with Linux and macOS (no platform-specific dependencies)
+
+## [0.2.0] - 2026-04-13
+
+### Added
+- Per-project intercept file (`.devcontainer/dkit-intercept`) replaces global config
+- `dkit init` auto-detects Ruby and Node projects and seeds intercept file
+- `dkit intercept add/remove/list` subcommands for managing per-project commands
+- `dkit root` — print project root without requiring a running container
+- `dkit code` — open VS Code attached to devcontainer via `vscode-remote://` URI
+- `dkit claude` — run claude interactively inside the container
+- `dkit exec` — non-TTY variant of `dkit run` for scripting
+- Shell hook (`dkit hook`) with fast-path `chpwd` to avoid redundant root lookups
+- `code` and `claude` always intercepted when a devcontainer is active
+- `DKIT_PROJECT_ROOT` env var to override project root resolution
+- Distributed as a Ruby gem
+
+### Changed
+- Container name resolution now tries three strategies: compose YAML `container_name`, docker label query, then `docker compose ps -q`
+- Intercept configuration moved from `~/.config/dkit/intercept` to per-project `.devcontainer/dkit-intercept`
+
+## [0.1.0] - 2025-01-01
+
+### Added
+- Initial release: basic command routing into devcontainer
+- Global intercept file at `~/.config/dkit/intercept`
+- `dkit run`, `dkit shell`, `dkit up`, `dkit down`, `dkit logs`
+- Shell hook with `chpwd` integration

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Augusto Stroligo
+
+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,135 @@
+# dkit
+
+[![Gem Version](https://badge.fury.io/rb/dkit.svg)](https://rubygems.org/gems/dkit)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+DevKit CLI — routes shell commands transparently into a running devcontainer.
+
+When you `cd` into a project, dkit intercepts configured commands (e.g. `rails`, `bundle`, `rspec`) and executes them inside the devcontainer instead of on the host, preserving the correct working directory. When no container is running the commands fall through to the host as normal.
+
+## Requirements
+
+- macOS or Linux
+- Ruby >= 2.7
+- Docker with Compose v2 (`docker compose`)
+- A project with `.devcontainer/devcontainer.json` using `dockerComposeFile` + `service`
+
+## Installation
+
+```sh
+gem install dkit
+echo 'eval "$(dkit hook)"' >> ~/.zshrc && exec zsh
+```
+
+### From source
+
+```sh
+gem build dkit.gemspec && gem install dkit-*.gem
+```
+
+## Shell integration
+
+The hook registers a `chpwd` listener that loads and unloads command shims as you navigate between projects. Add it once to `~/.zshrc`:
+
+```sh
+eval "$(dkit hook)"
+```
+
+`code` and `claude` are always intercepted when a devcontainer is active — no configuration needed.
+
+## Project setup
+
+```sh
+cd ~/projects/my-app
+dkit init
+```
+
+`dkit init` detects the project type (Ruby, Node) and creates `.devcontainer/dkit-intercept` with sensible defaults. Commit that file so your whole team gets the same behavior:
+
+```sh
+git add .devcontainer/dkit-intercept
+git commit -m "chore: add dkit intercept config"
+```
+
+### Managing intercepted commands
+
+```sh
+dkit intercept list              # show active commands for this project
+dkit intercept add terraform     # add a command
+dkit intercept remove terraform  # remove a command
+exec zsh                         # reload shell to apply changes
+```
+
+### Verbose routing messages
+
+By default, dkit prints a line to stderr whenever it intercepts a command:
+
+```
+[dkit] rails server → myapp-dev
+```
+
+To disable **per project** (committed, shared with the team), add to `.devcontainer/dkit-intercept`:
+
+```
+verbose: false
+rails
+bundle
+```
+
+To disable **personally** regardless of project config:
+
+```sh
+export DKIT_VERBOSE=0   # add to ~/.zshrc
+```
+
+## Usage
+
+```
+dkit exec <cmd> [args]      Run command without TTY (scripting/CI)
+dkit run  <cmd> [args]      Run command interactively (TTY)
+dkit shell                  Open interactive zsh shell in container
+dkit code  [path]           Open VS Code attached to devcontainer
+dkit claude [args]          Run claude inside container
+
+dkit status                 Show resolved devcontainer context
+dkit status --quiet         Exit 0 if running, 1 otherwise (for scripting)
+dkit root                   Print project root (no docker required)
+
+dkit up    [service]        docker compose up -d
+dkit down  [flags]          docker compose down
+dkit logs  [service]        docker compose logs -f
+
+dkit init                   Create .devcontainer/dkit-intercept
+dkit intercept list|add|remove <cmd>
+dkit hook                   Emit shell hook for ~/.zshrc
+dkit version
+```
+
+## How it works
+
+1. On `cd`, the shell hook calls `dkit root` to find the nearest `.devcontainer/devcontainer.json`.
+2. It reads `.devcontainer/dkit-intercept` and defines a shell function for each listed command.
+3. Each function calls `dkit status --quiet` to check if the container is running. If yes, it delegates to `dkit run <cmd>`; otherwise it calls the host binary.
+4. `dkit run` resolves the container name from the devcontainer config (via compose YAML, docker labels, or `docker compose ps`) and execs into it at the mirrored working directory.
+
+## devcontainer.json requirements
+
+dkit reads the following fields:
+
+| Field | Default | Purpose |
+|---|---|---|
+| `service` | `"app"` | Compose service name |
+| `dockerComposeFile` | — | Path(s) to compose file(s) |
+| `workspaceFolder` | `"/workspace"` | Container working directory root |
+| `remoteUser` | `"root"` | User for `docker exec` |
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `DKIT_PROJECT_ROOT` | Override project root resolution (useful in scripts) |
+| `DKIT_VERBOSE` | Set to `0` to suppress routing messages globally |
+
+## License
+
+MIT

data/bin/dkit

@@ -16,7 +16,7 @@ require 'pathname'
 require 'shellwords'
 require 'fileutils'
 
-VERSION   = "0.2.0"
+VERSION   = "0.3.0"
 DC_CONFIG = ".devcontainer/devcontainer.json"
 DC_INTERCEPT = ".devcontainer/dkit-intercept"
 
@@ -92,6 +92,13 @@ def intercept_remove(project_root, cmd)
   puts "dkit: removed '#{cmd}' — reload shell to deactivate (exec zsh)"
 end
 
+def verbose_enabled?(project_root)
+  return false if ENV["DKIT_VERBOSE"] == "0"
+  f = intercept_file(project_root)
+  return true unless File.exist?(f)
+  !File.readlines(f, chomp: true).any? { |l| l.strip == "verbose: false" }
+end
+
 # ── Devcontainer config ────────────────────────────────────────────────────────
 
 def load_dc_config(project_root)
@@ -207,7 +214,7 @@ def cmd_init
   cmds += %w[yarn node npx]                   if File.exist?(File.join(root, "package.json"))
   cmds = %w[bash]                             if cmds.empty?
 
-  File.write(f, cmds.join("\n") + "\n")
+  File.write(f, "# verbose: false  # uncomment to suppress routing messages\n" + cmds.join("\n") + "\n")
   puts "dkit: created #{f}"
   puts "Commands: #{cmds.join(", ")}"
   puts "Tip: commit this file to share with your team"
@@ -290,12 +297,14 @@ end
 
 def cmd_exec(ctx, args)
   abort_err("exec: no command given") if args.empty?
+  warn "[dkit] #{args.join(" ")} → #{ctx.container}" if verbose_enabled?(ctx.project_root)
   system("docker", "exec", "--user", ctx.user, "--workdir", ctx.cwd, ctx.container, *args)
   exit $?.exitstatus
 end
 
 def cmd_run(ctx, args)
   abort_err("run: no command given") if args.empty?
+  warn "[dkit] #{args.join(" ")} → #{ctx.container}" if verbose_enabled?(ctx.project_root)
   exec("docker", "exec", "-it", "--user", ctx.user, "--workdir", ctx.cwd, ctx.container, *args)
 end
 
@@ -374,6 +383,10 @@ def cmd_help
       dkit intercept add <cmd>        Add command to current project's intercept list
       dkit intercept remove <cmd>     Remove command from current project's intercept list
 
+    Verbose routing messages (on by default):
+      Add 'verbose: false' to .devcontainer/dkit-intercept  (per project, committed)
+      Export DKIT_VERBOSE=0                                  (personal override)
+
       dkit hook                       Emit shell hook code for ~/.zshrc
       dkit version                    Print version
       dkit help                       Show this help

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dkit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Augusto Stroligo
@@ -19,11 +19,18 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE
+- README.md
 - bin/dkit
-homepage:
+homepage: https://github.com/ggstroligo/dkit
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/ggstroligo/dkit
+  changelog_uri: https://github.com/ggstroligo/dkit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ggstroligo/dkit/issues
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: