geet-geet 0.1.0

package/docs/DEV_GUIDE.md

@@ -0,0 +1,519 @@
+# Developer Guide
+
+This guide explains the internal architecture and developer workflow for geet.
+
+## Table of Contents
+
+- [Script Setup & Entrypoint](#script-setup--entrypoint)
+- [Prework & Initialization](#prework--initialization)
+- [Logging System](#logging-system)
+- [Available Variables & Functions](#available-variables--functions)
+- [Writing New Commands](#writing-new-commands)
+
+## Script Setup & Entrypoint
+
+### Entry Point: `bin/geet.sh`
+
+All geet commands flow through `bin/geet.sh`, which serves as the main dispatcher:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# 1. Locate the geet library
+NODE_BIN="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+GEET_LIB="$(cd -- "$NODE_BIN/../lib/node_modules/geet-geet/lib" && pwd)"
+
+# 2. Run the prework (digest-and-locate.sh)
+source "$GEET_LIB/digest-and-locate.sh" "$@"
+
+# 3. Dispatch to the appropriate command handler
+cmd="${1:-help}"
+shift || true
+
+case "$cmd" in
+  help|-h|--help)
+    source "$GEET_LIB/help.sh"
+    help
+    ;;
+  sync)
+    source "$GEET_LIB/sync.sh"
+    sync "${GEET_ARGS[@]:1}"
+    ;;
+  # ... more commands
+  *)
+    # Default: treat as git subcommand
+    source "$GEET_LIB/git.sh"
+    call_cmd "${GEET_ARGS[@]}"
+    ;;
+esac
+```
+
+### Command Flow
+
+1. **Entry** → `bin/geet.sh`
+2. **Prework** → Sources `lib/digest-and-locate.sh` (sets up environment)
+3. **Dispatch** → Routes to appropriate command handler in `lib/*.sh`
+4. **Execute** → Command-specific logic runs
+
+## Prework & Initialization
+
+### `digest-and-locate.sh` - The Setup Script
+
+Before any geet command runs, `digest-and-locate.sh` is sourced. This script:
+
+1. **Sources logger.sh** - Sets up the logging system
+2. **Loads global config** - Sources `config.env` from package root for user preferences
+3. **Parses flags** - Extracts `--geet-dir`, `--verbose`, `--filter`, `--brave`, etc.
+4. **Auto-detects template directory** - Finds `.geethier` in parent directories (with caching)
+5. **Loads template config** - Sources `template-config.env`
+6. **Sets up environment** - Exports all variables and functions needed by commands
+
+### What Gets Set Up
+
+After sourcing `digest-and-locate.sh`, you have access to:
+
+- **Paths**: `$GEET_LIB`, `$GEET_CMD`, `$APP_DIR`, `$TEMPLATE_DIR`, etc.
+- **Config values**: `$TEMPLATE_NAME`, `$GEET_ALIAS`, `$TEMPLATE_GH_URL`, etc.
+- **Logging functions**: `debug`, `info`, `log`, `warn`, `critical`, `die`
+- **Helper functions**: `read_config`, `geet_git`, `brave_guard`, etc.
+
+See the comments at the top of `lib/digest-and-locate.sh` for the complete list.
+
+### Configuration System
+
+Geet uses a multi-file `.env` configuration system for fast loading and clear separation of concerns:
+
+#### Global User Preferences: `config.env`
+
+Located at the package root (`$GEET_LIB/../config.env`), this file contains user preferences that apply to all geet operations:
+
+```bash
+# Global user preferences
+SHOW_LEVEL=true        # Show log level in output
+COLOR_MODE=light       # Color scheme: light, dark, or none
+COLOR_SCOPE=line       # Color scope: line or level
+```
+
+This file is:
+- Created automatically on first `geet template` run
+- Tracked by git (part of the npm package)
+- User-editable for customization
+- Loaded before any template configs
+
+#### Template Configuration: `template-config.env`
+
+Located in the template directory (e.g., `.mytemplate/template-config.env`), this file contains template identity and settings:
+
+```bash
+# Template configuration
+TEMPLATE_NAME=mytemplate
+TEMPLATE_DESC="Description of the template"
+
+TEMPLATE_GH_USER=username
+TEMPLATE_GH_NAME=reponame
+TEMPLATE_GH_URL=https://github.com/user/repo
+TEMPLATE_GH_SSH=git@github.com:user/repo.git
+TEMPLATE_GH_HTTPS=https://github.com/user/repo.git
+
+GEET_ALIAS=geet
+DD_APP_NAME=MyApp
+DD_TEMPLATE_NAME=mytemplate
+```
+
+This file is:
+- Created by `geet template`
+- Tracked by git (committed to template repo)
+- Defines the template's core identity
+
+
+#### Local System Cache: `untracked-template-config.env`
+
+Located in the template directory (e.g., `.mytemplate/untracked-template-config.env`), this file contains system-specific paths:
+
+```bash
+# Auto-generated system-specific paths
+GEET_LIB=/absolute/path/to/lib
+GEET_CMD=/absolute/path/to/bin/geet.sh
+TEMPLATE_DIR=/absolute/path/to/.mytemplate
+APP_DIR=/absolute/path/to/app
+```
+
+This file is:
+- Auto-generated on first run in a directory
+- **NOT tracked** (in `.gitignore`)
+- Caches TEMPLATE_DIR detection (50-200ms savings per run)
+- System-specific, regenerated per installation
+
+#### Load Order & Precedence
+
+Configuration is loaded in this order (later overrides earlier):
+
+1. **Global config** (`config.env`) - User preferences
+2. **Template config** (`template-config.env`) - Template identity
+4. **Local cache** (`untracked-template-config.env`) - System paths
+5. **Command-line flags** - Highest precedence
+
+#### Performance Impact
+
+The .env system provides massive performance improvements:
+
+- **Before**: 300-900ms prework time
+  - 10 jq calls: 100-200ms
+  - gh API call: 200-500ms
+  - Directory walking: 50-200ms
+- **After**: 6-10ms prework time
+  - Load 3-4 .env files: 4-8ms
+  - String operations: ~1ms
+  - **35-90x faster!**
+
+### Template Detection
+
+`digest-and-locate.sh` uses a **fast path / slow path** strategy to find your template directory:
+
+#### Fast Path (Cached)
+
+1. Check for `untracked-template-config.env` in current directory and parent directories
+2. If found, load `TEMPLATE_DIR` from cache (4-8ms)
+3. Verify cached path is still valid (`.geethier` exists)
+
+#### Slow Path (Directory Walking)
+
+Only runs on cache miss:
+
+1. Starting from `$PWD`
+2. Looking for hidden directories containing `.geethier`
+3. Choosing the directory with the most lines in `.geethier` (indicates hierarchy depth)
+4. Walking up parent directories until finding a candidate or hitting a `.git` directory
+5. Creating `untracked-template-config.env` cache for future runs
+
+**Result**: First run in a directory is ~50-200ms, subsequent runs are ~4-8ms.
+
+You can override auto-detection with `--geet-dir /path/to/template`.
+
+## Logging System
+
+### Overview
+
+The logging system lives in `lib/logger.sh` and provides structured, filterable logging with color support.
+
+### Log Levels
+
+From least to most severe:
+
+- `DEBUG` - Verbose diagnostic information
+- `INFO` - General informational messages
+- `WARN` - Warning messages
+- `ERROR` - Error messages
+- `CRITICAL` - Critical errors (used by `die`)
+- `NEVER` - Suppresses all output
+
+### Logging Functions
+
+```bash
+debug "Checking for template at $dir"      # Only shown with --verbose
+info "Syncing template changes..."         # Default level
+log "Same as info"                         # Alias
+warn "Config file not found, using defaults"
+critical "Failed to initialize repository"
+die "Fatal error: cannot proceed"          # Logs and exits with code 1
+```
+
+### Controlling Log Output
+
+#### By Level
+
+```bash
+# Show everything including debug messages
+geet sync --verbose
+
+# Show only warnings and errors
+geet sync --quiet
+
+# Show only errors
+geet sync --min-level ERROR
+
+# Suppress all output
+geet sync --silent
+```
+
+#### By Filter Pattern
+
+Use `--filter` to show only messages containing a specific string:
+
+```bash
+# Only show messages containing "template"
+geet sync --filter template
+
+# Only show messages containing "LOCATE"
+geet tree --verbose --filter LOCATE
+```
+
+#### Inverting Filters with `~`
+
+Prefix your filter with `~` to **exclude** messages matching the pattern:
+
+```bash
+# Show all messages EXCEPT those containing "DEBUG"
+geet sync --verbose --filter '~DEBUG'
+
+# Show all messages EXCEPT those containing "git"
+geet doctor --filter '~git'
+```
+
+The `~` acts as a "NOT" operator, inverting the filter logic.
+
+### Filter Implementation
+
+From `lib/logger.sh:125-136`:
+
+```bash
+if [[ -n "${LOG_FILTER:-}" ]]; then
+  if [[ "$LOG_FILTER" == \~* ]]; then
+    # exclude mode: pattern starts with ~
+    local pat="${LOG_FILTER:1}"
+    [[ "$plain" == *"$pat"* ]] && return 0  # Skip if matches
+  else
+    # include mode: normal pattern
+    [[ "$plain" != *"$LOG_FILTER"* ]] && return 0  # Skip if doesn't match
+  fi
+fi
+```
+
+### Color Configuration
+
+Colors are controlled by environment variables in `digest-and-locate.sh`:
+
+```bash
+COLOR_MODE="light"   # Options: light, dark, none
+COLOR_SCOPE="line"   # Options: line, level
+```
+
+- `COLOR_MODE` - Color scheme for terminal output
+  - `light` - Colors optimized for light backgrounds
+  - `dark` - Colors optimized for dark backgrounds
+  - `none` - No colors
+- `COLOR_SCOPE` - What gets colored
+  - `line` - Color the entire log line
+  - `level` - Color only the level prefix (e.g., `[DEBUG]`)
+
+## Available Variables & Functions
+
+After sourcing `digest-and-locate.sh`, these are available in your command scripts:
+
+### Key Paths
+
+```bash
+$GEET_LIB                    # Path to lib/ directory
+$GEET_CMD                    # Path to bin/geet.sh
+$APP_DIR                     # Your app's root directory (parent of template dir)
+$APP_NAME                    # Name of your app
+$TEMPLATE_DIR                # The template directory (e.g., .mytemplate)
+$DOTGIT                      # The template's git directory (TEMPLATE_DIR/dot-git)
+$GEET_GIT                    # Path to geet-git.sh wrapper
+```
+
+### Config Values
+
+```bash
+$TEMPLATE_NAME               # Template name from config
+$TEMPLATE_DESC               # Template description
+$GEET_ALIAS                  # Command alias (usually "geet")
+$TEMPLATE_GH_USER            # GitHub username
+$TEMPLATE_GH_NAME            # GitHub repo name
+$TEMPLATE_GH_URL             # GitHub URL
+$TEMPLATE_GH_SSH      # SSH remote URL
+$TEMPLATE_GH_HTTPS    # HTTPS remote URL
+```
+
+### Flags
+
+```bash
+$BRAVE                       # Set if --brave flag present
+$VERBOSE                     # Set if --verbose flag present
+$QUIET                       # Set if --quiet flag present
+$SILENT                      # Set if --silent flag present
+$MIN_LOG_LEVEL              # Current minimum log level
+$LOG_FILTER                 # Active log filter pattern
+```
+
+### Helper Functions
+
+```bash
+read_config KEY [DEFAULT]              # Get config value by key name
+geet_git [args...]                     # Run git in template context
+detect_template_dir_from_cwd           # Auto-find template directory
+brave_guard CMD [REASON]               # Require --brave flag or exit
+log_if_brave MESSAGE                   # Log only if --brave is set
+```
+
+## Writing New Commands
+
+### Basic Template
+
+Create a new file in `lib/your-command.sh`:
+
+```bash
+#!/usr/bin/env bash
+# lib/my-command.sh
+
+# This function assumes digest-and-locate.sh has already been sourced
+# So you have access to all the variables and functions listed above
+
+my_command() {
+  debug "Starting my-command with args: $*"
+
+  # Check if we're in a template directory
+  if [[ -z "$TEMPLATE_DIR" ]]; then
+    die "Not in a geet template directory. Run this from your app directory."
+  fi
+
+  # Use logging functions
+  log "Running my command..."
+
+  # Read from config
+  local template_name
+  template_name="$(read_config name "unknown")"
+  info "Template name: $template_name"
+
+  # Run git commands
+  geet_git status
+
+  # Guard dangerous operations
+  brave_guard "my dangerous operation" "This will modify important files."
+
+  log "Done!"
+}
+```
+
+### Add to Dispatcher
+
+Edit `bin/geet.sh` to add your command:
+
+```bash
+case "$cmd" in
+  # ... existing commands ...
+
+  my-command)
+    source "$GEET_LIB/my-command.sh"
+    my_command "${GEET_ARGS[@]:1}"
+    ;;
+
+  # ... rest of commands ...
+esac
+```
+
+### Testing Your Command
+
+```bash
+# Run with verbose logging
+geet my-command --verbose
+
+# Run with filtering
+geet my-command --verbose --filter "my-command"
+
+# Run with brave mode
+geet my-command --brave
+```
+
+## Debugging Tips
+
+### Use Verbose Mode
+
+Always develop with `--verbose` to see debug messages:
+
+```bash
+geet your-command --verbose
+```
+
+### Filter Noise
+
+If there's too much output, filter it:
+
+```bash
+# Only show messages from your command
+geet your-command --verbose --filter "my-command"
+
+# Exclude git-related messages
+geet your-command --verbose --filter '~git'
+```
+
+### Check What's Loaded
+
+Add debug messages to see what's set:
+
+```bash
+debug "TEMPLATE_DIR=$TEMPLATE_DIR"
+debug "TEMPLATE_NAME=$TEMPLATE_NAME"
+debug "BRAVE=$BRAVE"
+```
+
+### Trace Execution
+
+Enable bash tracing for maximum detail:
+
+```bash
+bash -x "$(which geet)" your-command
+```
+
+## Common Patterns
+
+### Reading Config Values
+
+All config values are available as environment variables after prework. Access them directly:
+
+```bash
+# Direct access (preferred)
+log "Template name: $TEMPLATE_NAME"
+log "GitHub URL: $TEMPLATE_GH_URL"
+
+# Using read_config helper (maps legacy keys to env vars)
+timeout="$(read_config timeout 30)"
+
+# Check if required value is set
+[[ -z "$TEMPLATE_NAME" ]] && die "TEMPLATE_NAME not set"
+```
+
+### Guarding Destructive Operations
+
+```bash
+dangerous_operation() {
+  brave_guard "deleting files" "This will permanently remove files."
+
+  # This only runs if --brave was passed
+  rm -rf "$SOME_DIR"
+}
+```
+
+### Conditional Logging
+
+```bash
+# Only log if --brave
+log_if_brave "About to do something risky..."
+
+# Custom conditions
+if [[ "$VERBOSE" ]]; then
+  log "Detailed diagnostic info..."
+fi
+```
+
+### Working with Git
+
+```bash
+# Use geet_git wrapper (respects template context)
+geet_git fetch origin
+
+# Get git output
+current_branch="$(geet_git rev-parse --abbrev-ref HEAD)"
+```
+
+## Summary
+
+1. **All commands start** via `bin/geet.sh`
+2. **Prework runs first** (`digest-and-locate.sh` sets up environment)
+3. **Logging is centralized** (use `debug`, `info`, `warn`, `critical`, `die`)
+4. **Filter with `--filter`** (use `~` prefix to invert)
+5. **Guard dangerous ops** with `brave_guard`
+6. **Everything is documented** in `digest-and-locate.sh` comments
+
+For more examples, browse the existing command files in `lib/`.

package/docs/FAQ.md

@@ -0,0 +1,128 @@
+## FAQ
+
+### What is geet?
+
+**Geet lets you maintain a reusable template as a real Git repo over the same working tree as your app, without copying files, moving paths, or running generators.**
+
+In practice: two or more Git repos, one folder.
+
+---
+
+### How is this different from a normal template?
+
+Normal templates:
+
+* copy files once
+* drift immediately as the template owner makes updates and changes
+* require regeneration or manual syncing
+
+Geet:
+
+* shares *real files at real paths*
+* updates via `git pull`
+* never copies or regenerates code
+
+---
+
+### How is this different from Git submodules?
+
+Submodules:
+
+* live in a subdirectory
+* can’t interleave files with the app
+* break path-sensitive systems (Expo, routing, config)
+
+Geet:
+
+* works **at the project root**
+* files stay exactly where the app expects them
+* no nested repos in your source tree
+
+**NOTE**: If you have the ability to fully and cleanly separate your template into a separate folder, consider using submodules instead. Geet is made for cases where that is not feasible.
+
+---
+
+### How is this different from Git subtrees?
+
+Subtrees:
+
+* still copy files into the repo
+* still requires a separate folder for the template, does not support interleaving
+* updates are noisy and opaque
+* merges become painful over time
+
+Geet:
+
+* no copying
+* no sync step
+* updates are normal Git merges
+
+---
+
+### Why not monorepos?
+
+Monorepos:
+
+* assume clear ownership boundaries
+* don’t work well when *most* files overlap
+* still require indirection or abstraction
+
+Geet is for cases where:
+
+* 50–90% of files are shared
+* file locations are non-negotiable
+* you want minimal abstraction
+
+---
+
+### Is this safe?
+
+Yes, if used as intended.
+
+* The app repo remains totally standard.
+* The template repo is sandboxed via a whitelist.
+* Destructive Git commands are blocked by default.
+* You can detach at any time by deleting the layer folder.
+
+---
+
+### Is this a Git hack?
+
+Yes — deliberately.
+
+Git already supports:
+
+* separate `GIT_DIR`
+* shared working trees
+* repo-local ignore rules
+
+Geet just assembles those primitives into a usable tool.
+
+---
+
+### Who is geet for?
+
+* Teams maintaining multiple similar apps
+* Path-sensitive frameworks (Expo, RN, Next, native builds)
+* Developers who want **Git-native updates**, not generators
+* Anyone burned by templates that drift
+
+---
+
+### When should I *not* use geet?
+
+Don’t use geet if:
+
+* your template can live in a subdirectory
+* copying files is acceptable
+* your shared code is small or purely library-based
+
+Geet is for the “everything overlaps” case.
+
+---
+
+If you want, next we can:
+
+* tighten this FAQ even more
+* add a “When geet is the wrong tool” section
+* or turn this into a README-ready block