gator-command 1.0.0__py3-none-any.whl

gator_command/scripts/gatorize-lib.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# gatorize-lib.sh — Utility and detection functions for gatorize.sh
+#
+# Sourced by gatorize.sh. Not a standalone script.
+#
+# Contains: logging, confirmation, content detection, scenario detection,
+# generation detection, version writing, knowledge detection.
+
+# =============================================================================
+# Utility Functions
+# =============================================================================
+
+log_step() { echo "  $1"; }
+log_blank() { echo ""; }
+
+confirm() {
+    # confirm "prompt" "default" → returns 0 for yes, 1 for no
+    # default: "Y" means yes-default, "N" means no-default
+    local prompt="$1" default="${2:-Y}"
+    local suffix
+    if [ "$default" = "Y" ]; then suffix="[Y/n]"; else suffix="[y/N]"; fi
+    read -rp "  $prompt $suffix: " answer
+    case "$answer" in
+        [Yy]*) return 0 ;;
+        [Nn]*) return 1 ;;
+        "")
+            if [ "$default" = "Y" ]; then return 0; else return 1; fi
+            ;;
+        *) if [ "$default" = "Y" ]; then return 0; else return 1; fi ;;
+    esac
+}
+
+has_content() {
+    # Returns 0 if file has meaningful content (non-blank, non-heading,
+    # non-bracket-placeholder, non-YAML-frontmatter-structure).
+    # Ignores: blank lines, headings, [placeholders], YAML delimiters (---),
+    # and YAML key-value lines with empty/placeholder values (e.g., "message: """,
+    # "decision-tags: []", "significance:").
+    local file="$1"
+    [ -f "$file" ] || return 1
+    local lines
+    lines=$(grep -cvE '^\s*$|^#|^\[|^---|^[a-z-]+:\s*(""|$|\[\])' "$file" 2>/dev/null || true)
+    [ "$lines" -gt 0 ]
+}
+
+file_count() {
+    # Count .md files in a directory (excluding templates)
+    local dir="$1"
+    [ -d "$dir" ] || { echo "0"; return; }
+    find "$dir" -name "*.md" ! -name "_template.md" ! -name "README.md" \
+        ! -name ".gitkeep" 2>/dev/null | wc -l | tr -d ' '
+}
+
+# =============================================================================
+# Detection Functions
+# =============================================================================
+
+detect_scenario() {
+    local target="$1"
+    local has_git=false has_gator=false has_memex=false
+
+    [ -d "$target/.git" ] && has_git=true
+    [ -d "$target/.gator" ] && has_gator=true
+    [ -d "$target/memex" ] || [ -d "$target/.memex" ] && has_memex=true
+
+    if ! $has_git && ! $has_memex && ! $has_gator; then echo 1; return; fi
+    if   $has_git && ! $has_memex && ! $has_gator; then echo 2; return; fi
+    if   $has_git && ! $has_memex &&   $has_gator; then echo 3; return; fi
+    if   $has_git &&   $has_memex && ! $has_gator; then echo 4; return; fi
+    if   $has_git &&   $has_memex &&   $has_gator; then echo 5; return; fi
+
+    # Edge case: memex but no git
+    if ! $has_git && $has_memex; then
+        echo ""
+        echo "  Error: Found memex structure but no git repository in $target."
+        echo "  Initialize git first, then re-run gatorize.sh."
+        exit 1
+    fi
+
+    echo 2  # fallback
+}
+
+detect_legacy_memex() {
+    # Sets globals describing what legacy structure exists
+    local target="$1"
+    HAS_MEMEX_DIR=false
+    HAS_DOT_MEMEX_DIR=false
+    HAS_ROOT_CONSTITUTION=false
+    HAS_ROOT_CONSTITUTION_CORE=false
+
+    [ -d "$target/memex" ] && HAS_MEMEX_DIR=true
+    [ -d "$target/.memex" ] && HAS_DOT_MEMEX_DIR=true
+    [ -f "$target/constitution.md" ] && HAS_ROOT_CONSTITUTION=true
+    [ -f "$target/constitution-core.md" ] && HAS_ROOT_CONSTITUTION_CORE=true
+}
+
+detect_gator_generation() {
+    # Returns the generation of an existing .gator/ install.
+    # Gen 0: pre-gatorize.sh (no command-post.md, no .gator-version)
+    # Gen 1: early gatorize.sh (has command-post.md, no .gator-version)
+    # Gen 2+: current (has .gator-version with generation field)
+    local target="$1"
+
+    if [ -f "$target/.gator/.gator-version" ]; then
+        local gen
+        gen=$(grep '^generation:' "$target/.gator/.gator-version" 2>/dev/null | \
+              sed 's/generation: *//' | tr -d ' ')
+        echo "${gen:-2}"
+    elif [ -f "$target/.gator/command-post.md" ]; then
+        echo 1
+    else
+        echo 0
+    fi
+}
+
+write_gator_version() {
+    # Writes .gator/.gator-version with current generation and timestamps
+    local target="$1"
+    local action="${2:-install}"  # install, upgrade, or morph
+
+    # Preserve original install date if upgrading
+    local installed="$TODAY"
+    if [ -f "$target/.gator/.gator-version" ]; then
+        local prev_installed
+        prev_installed=$(grep '^installed:' "$target/.gator/.gator-version" 2>/dev/null | \
+                         sed 's/installed: *//')
+        [ -n "$prev_installed" ] && installed="$prev_installed"
+    fi
+
+    local now
+    now="$(date +%Y-%m-%dT%H:%M:%S)"
+
+    cat > "$target/.gator/.gator-version" << EOF
+generation: $GATOR_GEN
+installed: $installed
+updated: $now
+action: $action
+installer: gatorize.sh
+EOF
+}
+
+has_gator_knowledge() {
+    # Returns 0 if .gator/ has user-created content worth preserving
+    local target="$1"
+
+    # Check for non-template charters
+    local charters
+    charters=$(file_count "$target/.gator/charters")
+    # Subtract INDEX.md if present
+    [ -f "$target/.gator/charters/INDEX.md" ] && charters=$((charters - 1))
+    [ "$charters" -gt 0 ] && return 0
+
+    # Check for populated content files
+    for f in mission.md roadmap.md inbox.md commit_draft.md identity.md issues.md; do
+        has_content "$target/.gator/$f" && return 0
+    done
+
+    # Check for threads or artifacts
+    local threads artifacts
+    threads=$(find "$target/.gator/threads" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    [ "$threads" -gt 0 ] && return 0
+    artifacts=$(find "$target/.gator/artifacts" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    [ "$artifacts" -gt 0 ] && return 0
+
+    return 1
+}

gator_command/scripts/gatorize-post.sh

@@ -0,0 +1,394 @@
+#!/usr/bin/env bash
+# gatorize-post.sh — Post-action functions for gatorize.sh
+#
+# Sourced by gatorize.sh. Not a standalone script.
+# Requires: gatorize-lib.sh (for log_step, confirm, has_content, detect_gator_generation)
+# Requires: COMMAND_POST, GATOR_BRANCH, TODAY, GATOR_MARKER, COMMAND_POST_MARKER
+#
+# Contains: thin link installation, outbox creation, entry point installation,
+# registry registration, and summary output.
+
+# =============================================================================
+# Action: Install thin link
+# =============================================================================
+
+action_install_thin_link() {
+    local target="$1"
+    local repo_name
+    repo_name="$(basename "$target")"
+
+    # Compute relative path from target to command post
+    local relative_path link_path path_note
+    relative_path=$(python3 -c "import os.path; print(os.path.relpath('$COMMAND_POST', '$target'))" 2>/dev/null || echo "")
+
+    if [ -n "$relative_path" ]; then
+        link_path="$relative_path"
+        path_note="Relative path (portable across machines with the same directory layout)."
+    else
+        link_path="$COMMAND_POST"
+        path_note="Absolute path (works on this machine only). For team use, update to a relative path or use an environment variable."
+    fi
+
+    cat > "$target/.gator/command-post.md" << EOF
+---
+command-post: $link_path
+command-post-absolute: $COMMAND_POST  # machine-local, not portable — gitignore or override per-machine
+remote: # optional — add remote URL for team sync
+version: $TODAY
+---
+
+# Gator Command Post
+
+This repo is governed by [Gator Command]($link_path).
+$path_note
+
+The agent should read org standards from the command post at session open.
+**Do not modify the command post from this repo.**
+
+## What to read from the command post
+
+- \`gator-command/org-policy.md\` — org-wide inherited policy (engineering standards, commit rules, agent behavioral rules). This is the primary file to read at session open.
+- Additional procedures referenced from org-policy.md (branching-standard.md, coding-standard.md, etc.)
+
+## What to do with cross-repo discoveries
+
+Write to this repo's \`outbox.md\`. Do not create threads or edit files
+in the command post. The PI reviews outbox items during gator-command sessions.
+EOF
+
+    log_step "Installed thin link (.gator/command-post.md)"
+}
+
+# =============================================================================
+# Action: Install outbox
+# =============================================================================
+
+action_install_outbox() {
+    local target="$1"
+
+    # Don't overwrite an outbox that has content
+    if [ -f "$target/outbox.md" ] && has_content "$target/outbox.md"; then
+        log_step "outbox.md already exists with content — preserved"
+        return
+    fi
+
+    cat > "$target/outbox.md" << 'STUB'
+# Outbox
+
+Messages for Gator Command. The PI triages these during command post sessions.
+Do not clear this file from the project repo — the command post session clears
+entries after processing.
+
+---
+
+STUB
+    log_step "Created outbox.md"
+}
+
+# =============================================================================
+# Action: Install product source
+# =============================================================================
+
+action_install_product_source() {
+    local target="$1"
+
+    # Detect template directory relative to the gator clone root.
+    # Two layouts: gator-engine/templates/gator-starter (public clone)
+    #              gator-command/templates/gator-starter (source repo)
+    local gator_root="$COMMAND_POST"
+    local template_dir=""
+    if [ -d "$gator_root/gator-engine/templates/gator-starter" ]; then
+        template_dir="gator-engine/templates/gator-starter"
+    elif [ -d "$gator_root/gator-command/templates/gator-starter" ]; then
+        template_dir="gator-command/templates/gator-starter"
+    fi
+
+    # Always write — this is machine-local state, updated on every gatorize
+    cat > "$target/.gator/product-source.json" << EOF
+{
+  "gator_root": "$gator_root",
+  "template_dir": "$template_dir",
+  "installed": "$TODAY",
+  "updated": "$TODAY"
+}
+EOF
+    log_step "Wrote product-source.json (template source: $gator_root)"
+}
+
+# =============================================================================
+# Action: Install entry points
+# =============================================================================
+
+action_install_entry_points() {
+    local target="$1"
+    local has_command_post="${2:-true}"
+
+    # Shared gator-init instruction (goes in all entry points)
+    local gator_init_block='**"gator init" means**: run \`python .gator/scripts/gator-init.py\` and display the output exactly as printed. It is NOT a repo bootstrap or git init — it is the standardized Gator boot sequence. Run the script, show the output, then proceed with session opening.
+
+**"gator pulse"**: run \`python .gator/scripts/gator-pulse.py\` to generate \`.gator/pulse.md\` — a strategic operations brief with next steps, project assessment, roadmap check, priorities, and recent activity.
+
+**Project assessment**: when the Architect asks for a project assessment, write a 2-paragraph expert evaluation to \`.gator/artifacts/YYYY-MM-DD-project-assessment.md\` with YAML frontmatter (\`date\`, \`type: project-assessment\`, \`model: <your model name>\`). Write as an expert consultant advising an engineering manager. The next \`gator pulse\` will include it automatically.'
+
+    # Command-post section — included only when a command post is linked
+    local cp_section=""
+    if [ "$has_command_post" = "true" ]; then
+        cp_section="
+
+$COMMAND_POST_MARKER
+This repo is governed by a Gator Command post. Read [\`.gator/command-post.md\`](.gator/command-post.md) for the command post location. Read org standards from there at session open. **Never write to the command post from this session.** Cross-repo discoveries go in [\`outbox.md\`](outbox.md)."
+    fi
+
+    # Entry point content for each model
+    local claude_entry agents_entry gemini_entry
+
+    claude_entry="$gator_init_block
+
+Read [\`.gator/constitution.md\`](.gator/constitution.md) before your first response. It governs how you work here.
+
+If this is a **fresh project** (charters/ is empty or contains only templates), follow the bootstrap procedure in [\`.gator/gator-start-up.md\`](.gator/gator-start-up.md).$cp_section"
+
+    agents_entry="$gator_init_block
+
+Read [\`.gator/constitution.md\`](.gator/constitution.md) before your first response. It governs how you work here.
+
+If this is a **fresh project** (\`charters/\` is empty or contains only templates), follow the bootstrap procedure in [\`.gator/gator-start-up.md\`](.gator/gator-start-up.md).
+
+If the PI asks for an **enforcer review**, do not repurpose yourself as the enforcer. Use the dedicated enforcer prompt at [\`.gator/scripts/enforcer-prompt.md\`](.gator/scripts/enforcer-prompt.md).$cp_section"
+
+    gemini_entry="$gator_init_block
+
+Read [\`.gator/constitution.md\`](.gator/constitution.md) before your first response. It governs how you work here.
+
+If this is a **fresh project** (charters/ is empty or contains only templates), follow the bootstrap procedure in [\`.gator/gator-start-up.md\`](.gator/gator-start-up.md).$cp_section"
+
+    local entry_files=("CLAUDE.md" "AGENTS.md" "GEMINI.md")
+    local idx=0
+
+    while [ $idx -lt ${#entry_files[@]} ]; do
+        local entry_file="${entry_files[$idx]}"
+        local entry_content header rollback_file agent_name
+
+        case "$entry_file" in
+            CLAUDE.md)
+                entry_content="$claude_entry"
+                header="# Claude Code Entry Point"
+                rollback_file="CLAUDE_ROLLBACK.md"
+                agent_name="Claude Code"
+                ;;
+            AGENTS.md)
+                entry_content="$agents_entry"
+                header="# Codex Entry Point"
+                rollback_file="AGENTS_ROLLBACK.md"
+                agent_name="Codex"
+                ;;
+            GEMINI.md)
+                entry_content="$gemini_entry"
+                header="# Gemini Entry Point"
+                rollback_file="GEMINI_ROLLBACK.md"
+                agent_name="Gemini"
+                ;;
+        esac
+
+        if [ -f "$target/$entry_file" ]; then
+            # Already gatorized?
+            if grep -q "$GATOR_MARKER\|$COMMAND_POST_MARKER" "$target/$entry_file" 2>/dev/null; then
+                log_step "$entry_file already has Gator entry point — skipped"
+                idx=$((idx + 1))
+                continue
+            fi
+
+            local line_count
+            line_count=$(wc -l < "$target/$entry_file" | tr -d ' ')
+            log_blank
+            echo "  $entry_file already exists ($line_count lines)."
+            log_blank
+            echo "  Options:"
+            log_blank
+            echo "    [1] Backup & replace (recommended) — save your existing file as"
+            echo "        $rollback_file, then create a new $entry_file that leads with"
+            echo "        Gator governance and includes your original content by reference."
+            echo "        Best for: files with skills, custom instructions, or complex setups."
+            echo "        Your original content is preserved and the agent is told to read it."
+            log_blank
+            echo "    [2] Append — add Gator lines to the end of the existing file."
+            echo "        Your existing content stays. Gator instructions are appended below."
+            echo "        Best for: short files, simple setups."
+            log_blank
+            echo "    [3] Overwrite — replace $entry_file entirely with Gator's version."
+            echo "        Your existing content is lost. Only use if the current file is disposable."
+            log_blank
+            if [ $idx -gt 0 ]; then
+                echo "    [b] Go back — return to previous entry point."
+            fi
+            echo "    [x] Cancel installation."
+            log_blank
+            read -rp "  Choice [1/2/3$([ $idx -gt 0 ] && echo '/b')/x]: " choice
+            case "$choice" in
+                1)
+                    cp "$target/$entry_file" "$target/$rollback_file"
+                    log_step "Saved original as $rollback_file"
+                    cat > "$target/$entry_file" << MERGED
+$header
+
+You are the primary agent for this project.
+
+$entry_content
+
+## Pre-Gator Instructions
+
+This project had an existing $entry_file before Gator was installed.
+Those instructions have been preserved in [\`$rollback_file\`]($rollback_file).
+**Read that file now** — it may contain skills, custom instructions, personas,
+or project-specific rules that should still be followed alongside the
+Gator constitution.
+
+If any instructions in $rollback_file conflict with the Gator constitution,
+the constitution takes precedence for code governance (charters, commit loop,
+enforcer rules). For everything else (skills, personas, custom workflows),
+follow $rollback_file.
+MERGED
+                    log_step "Created new $entry_file with Gator governance + reference to $rollback_file"
+                    ;;
+                2)
+                    echo "" >> "$target/$entry_file"
+                    echo "$GATOR_MARKER" >> "$target/$entry_file"
+                    echo "" >> "$target/$entry_file"
+                    echo "$entry_content" >> "$target/$entry_file"
+                    log_step "Appended Gator entry point to $entry_file"
+                    ;;
+                3)
+                    printf "%s\n\nYou are the primary agent for this project.\n\n%s\n" \
+                        "$header" "$entry_content" > "$target/$entry_file"
+                    log_step "Replaced $entry_file (original content lost)"
+                    ;;
+                [bB])
+                    if [ $idx -gt 0 ]; then
+                        idx=$((idx - 1))
+                        continue
+                    fi
+                    ;;
+                [xX])
+                    echo ""
+                    echo "  Installation cancelled."
+                    echo "  To clean up: git checkout dev && git branch -D gator-install"
+                    exit 0
+                    ;;
+            esac
+        else
+            printf "%s\n\nYou are the primary agent for this project.\n\n%s\n" \
+                "$header" "$entry_content" > "$target/$entry_file"
+            log_step "Created $entry_file"
+        fi
+        idx=$((idx + 1))
+    done
+}
+
+# =============================================================================
+# Action: Register in command post registry
+# =============================================================================
+
+action_register() {
+    local target="$1"
+    local repo_name
+    repo_name="$(basename "$target")"
+
+    local registry="$COMMAND_POST/gator-command/registry.md"
+
+    if [ ! -f "$registry" ]; then
+        cat > "$registry" << 'STUB'
+# Registry
+
+Repos governed by this Gator Command post. Updated by `gatorize.sh` and maintained by the PI.
+
+**Note**: Local paths are machine-specific. In team use, the Remote column is the portable identifier. Local paths may differ per workstation.
+
+| Repo | Local path | Remote | Registered | Status |
+|------|-----------|--------|------------|--------|
+STUB
+    fi
+
+    if grep -q "$target" "$registry" 2>/dev/null; then
+        log_blank
+        log_step "$repo_name already registered in command post registry."
+    else
+        local remote_url
+        remote_url=$(cd "$target" && git remote get-url origin 2>/dev/null || echo "—")
+        echo "| $repo_name | $target | $remote_url | $TODAY | current |" >> "$registry"
+        log_blank
+        log_step "Registered $repo_name in command post registry."
+    fi
+}
+
+# =============================================================================
+# Summary
+# =============================================================================
+
+print_summary() {
+    local target="$1"
+    local scenario="$2"
+    local has_command_post="${3:-true}"
+    local repo_name
+    repo_name="$(basename "$target")"
+
+    log_blank
+    echo "  ================================================================"
+    echo "  ✓ Gatorized: $repo_name"
+    echo "  ================================================================"
+    log_blank
+
+    case "$scenario" in
+        1) echo "  Type: Fresh install (git initialized)" ;;
+        2) echo "  Type: Fresh install" ;;
+        3)
+            local final_gen
+            final_gen=$(detect_gator_generation "$target")
+            echo "  Type: Upgrade (generation $final_gen, templates refreshed, content preserved)"
+            ;;
+        4) echo "  Type: Morph (memex → gator)" ;;
+        5) echo "  Type: Dual structure (PI-directed)" ;;
+    esac
+
+    if [ "$scenario" = "4" ]; then
+        log_blank
+        echo "  Preserved for review:"
+        [ -d "$target/memex.pre-gator" ] && echo "    memex.pre-gator/     — original content layer"
+        [ -d "$target/.memex.pre-gator" ] && echo "    .memex.pre-gator/    — original system layer"
+        [ -f "$target/.gator/legacy-constitution.md" ] && echo "    .gator/legacy-constitution.md"
+        [ -f "$target/.gator/legacy-constitution-core.md" ] && echo "    .gator/legacy-constitution-core.md"
+    fi
+
+    # Git instructions
+    local final_branch
+    final_branch=$(cd "$target" && git branch --show-current 2>/dev/null)
+    if [ "$final_branch" = "$GATOR_BRANCH" ]; then
+        log_blank
+        echo "  You are on the '$GATOR_BRANCH' branch. To finalize:"
+        echo ""
+        echo "      cd $target"
+        echo "      git add -A && git commit -m 'Gatorize: install .gator/ governance layer'"
+        echo "      git checkout dev && git merge $GATOR_BRANCH"
+        echo "      git branch -d $GATOR_BRANCH"
+    fi
+
+    log_blank
+    echo "  ================================================================"
+    echo "  SUCCESS"
+    echo "  ================================================================"
+    log_blank
+    echo "  What to do now:"
+    log_blank
+    echo "    1. cd $target"
+    echo "    2. Launch your AI coding tool (Claude Code, Codex, Gemini, etc.)"
+    echo "    3. Type: gator init"
+    echo "    4. The agent will read the constitution and orient to the project."
+    echo "       Your first git commit fires the governance hooks."
+    log_blank
+    echo "  Enforcement: strict (commit gate active)"
+    if [ "$has_command_post" = "true" ]; then
+        echo "  Command post: linked"
+    else
+        echo "  Command post: standalone"
+    fi
+    log_blank
+}