gator-command 1.0.0__py3-none-any.whl

gator_command/scripts/gatorize.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# gatorize.sh — Install, upgrade, or morph the Gator knowledge layer into a
+# project repo and connect it to this Gator Command post.
+#
+# Handles five scenarios:
+#   1. Fresh directory (no git)        → git init + install
+#   2. Git repo, clean                 → install
+#   3. Git repo, has .gator/           → upgrade (preserve knowledge)
+#   4. Git repo, has memex structure   → morph memex → gator
+#   5. Git repo, has both              → warn, let PI choose
+#
+# Every scenario creates a 'gator-install' feature branch. No exceptions.
+#
+# Structure:
+#   gatorize.sh          — this file (orchestrator: constants, args, dispatch)
+#   gatorize-lib.sh      — utilities, detection, shared helpers
+#   gatorize-actions.sh  — scenario actions: install, upgrade, morph, dual
+#   gatorize-post.sh     — thin link, outbox, entry points, register, summary
+#
+# Procedure: gator-command/procedures/gatorize-permutations.md
+#
+# Usage:
+#   bash gator-command/scripts/gatorize.sh /path/to/your/project
+#   bash gator-command/scripts/gatorize.sh .
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+COMMAND_POST="$(cd "$SCRIPT_DIR/../.." && pwd)"
+# Templates are siblings of scripts/ — works whether parent is
+# gator-command/ (dev) or gator-engine/ (public distribution)
+TEMPLATES="$(cd "$SCRIPT_DIR/../templates/gator-starter" 2>/dev/null && pwd)"
+if [ -z "$TEMPLATES" ] || [ ! -d "$TEMPLATES" ]; then
+    # Fallback: try gator-command/ path (legacy)
+    TEMPLATES="$COMMAND_POST/gator-command/templates/gator-starter"
+fi
+GATOR_BRANCH="gator-install"
+TODAY="$(date +%Y-%m-%d)"
+
+# Detect whether we are running from a live command post.
+# Uses find_command_post() from gator_core.py as the single canonical predicate.
+HAS_COMMAND_POST="false"
+DETECTED_CP=$(python3 -c "import sys; sys.path.insert(0,'$SCRIPT_DIR'); from gator_core import find_command_post; cp=find_command_post('$SCRIPT_DIR'); print(cp or '')" 2>/dev/null || echo "")
+if [ -n "$DETECTED_CP" ]; then
+    HAS_COMMAND_POST="true"
+fi
+
+# Template generation — read from gator_core.py (single source of truth).
+GATOR_GEN=$(sed -n 's/^CURRENT_GENERATION\s*=\s*\([0-9]*\)/\1/p' "$SCRIPT_DIR/gator_core.py" 2>/dev/null)
+if [ -z "$GATOR_GEN" ]; then
+    GATOR_GEN=2  # fallback if gator_core.py not found
+fi
+
+# Entry point markers (used for idempotent detection)
+GATOR_MARKER="# --- Gator Navigation Coding ---"
+COMMAND_POST_MARKER="# --- Gator Command Post ---"
+
+# =============================================================================
+# Source libraries
+# =============================================================================
+
+source "$SCRIPT_DIR/gatorize-lib.sh"
+source "$SCRIPT_DIR/gatorize-actions.sh"
+source "$SCRIPT_DIR/gatorize-post.sh"
+
+# =============================================================================
+# Main
+# =============================================================================
+
+# --- Validate args ---
+
+if [ $# -eq 0 ]; then
+    echo "Usage: bash gator-command/scripts/gatorize.sh <target-directory>"
+    echo ""
+    echo "Installs, upgrades, or morphs .gator/ into the target project and"
+    echo "connects it to this Gator Command post."
+    echo ""
+    echo "Handles: fresh dirs, existing repos, prior gator installs, and"
+    echo "legacy memex structures (.memex/, memex/)."
+    echo ""
+    echo "Always creates a 'gator-install' feature branch for safety."
+    echo ""
+    echo "Procedure: gator-command/procedures/gatorize-permutations.md"
+    exit 1
+fi
+
+if [ ! -d "$1" ]; then
+    echo ""
+    echo "  Directory does not exist: $1"
+    echo "  Gatorize can create it from scratch — git init, .gator/, the works."
+    echo ""
+    if confirm "Create $1 and gatorize it?" "Y"; then
+        mkdir -p "$1"
+        echo "  Created $1"
+    else
+        echo "  Aborted."
+        exit 1
+    fi
+fi
+
+TARGET="$(cd "$1" && pwd)"
+
+if [ "$TARGET" = "$COMMAND_POST" ]; then
+    echo "Error: Target is the command post itself. Gatorize a project repo, not gator-command."
+    exit 1
+fi
+
+if [ ! -d "$TEMPLATES" ]; then
+    echo "Error: Templates not found at $TEMPLATES"
+    echo "Are you running this from the gator-command repo root?"
+    exit 1
+fi
+
+# --- Detect scenario ---
+
+SCENARIO=$(detect_scenario "$TARGET")
+
+echo ""
+echo "  ================================================================"
+echo "  gatorize.sh — $(basename "$TARGET")"
+echo "  ================================================================"
+
+case "$SCENARIO" in
+    1) echo "  Scenario 1: Fresh directory (no git, no memex, no gator)" ;;
+    2) echo "  Scenario 2: Git repo, clean (no prior knowledge layer)" ;;
+    3)
+        DETECTED_GEN=$(detect_gator_generation "$TARGET")
+        echo "  Gator is already installed (generation $DETECTED_GEN). Running update..."
+        echo ""
+        # Use the SOURCE repo's gator-update with --source pointing to this gator clone
+        python "$SCRIPT_DIR/gator-update.py" --path "$TARGET" --source "$COMMAND_POST" --no-policy
+        echo ""
+        echo "  ================================================================"
+        echo "  SUCCESS — updated"
+        echo "  ================================================================"
+        echo ""
+        echo "  Templates and scripts refreshed. Your content is preserved."
+        echo ""
+        exit 0
+        ;;
+    4) echo "  Scenario 4: Git repo, legacy memex structure (morph)" ;;
+    5) echo "  Scenario 5: Git repo, both memex and gator (dual)" ;;
+esac
+
+echo ""
+
+# --- Dispatch ---
+
+case "$SCENARIO" in
+    1)
+        action_git_init "$TARGET"
+        action_install_gator "$TARGET"
+        ;;
+    2)
+        action_feature_branch "$TARGET"
+        action_install_gator "$TARGET"
+        ;;
+    3)
+        action_feature_branch "$TARGET"
+        action_upgrade_gator "$TARGET"
+        ;;
+    4)
+        action_feature_branch "$TARGET"
+        action_morph_memex "$TARGET"
+        ;;
+    5)
+        action_feature_branch "$TARGET"
+        action_warn_dual "$TARGET"
+        ;;
+esac
+
+# --- Common tail (all scenarios) ---
+
+if [ "$HAS_COMMAND_POST" = "true" ]; then
+    action_install_thin_link "$TARGET"
+fi
+action_install_entry_points "$TARGET" "$HAS_COMMAND_POST"
+action_install_outbox "$TARGET"
+action_install_product_source "$TARGET"
+action_register "$TARGET"
+print_summary "$TARGET" "$SCENARIO" "$HAS_COMMAND_POST"

gator_command/scripts/generate_markdown.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""Render the Memex thread graph into Markdown."""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import re
+from pathlib import Path
+
+from generate_wiki import (
+    CATEGORY_ORDER,
+    IDENTITY_SECTIONS,
+    category_threads,
+    extract_links,
+    load_threads,
+    parse_identity,
+    section_blocks,
+)
+
+
+LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
+
+
+def slugify_heading(text: str) -> str:
+    slug = text.strip().lower()
+    slug = re.sub(r"[^\w\s-]", "", slug)
+    slug = re.sub(r"\s", "-", slug)
+    return slug
+
+
+def convert_inline(text: str, title_lookup: dict[Path, str], source_dir: Path) -> str:
+    def replace_link(match: re.Match[str]) -> str:
+        label = match.group(1)
+        raw_target = match.group(2)
+        if raw_target.endswith(".md"):
+            target_path = (source_dir / raw_target).resolve()
+            target_title = title_lookup.get(target_path)
+            if target_title:
+                return f"[{label}](#{slugify_heading(target_title)})"
+        return label
+
+    return LINK_RE.sub(replace_link, text)
+
+
+def render_markdown_lines(
+    lines: list[str], title_lookup: dict[Path, str], source_dir: Path
+) -> list[str]:
+    rendered: list[str] = []
+    for kind, block in section_blocks(lines):
+        if kind == "bullet":
+            for line in block:
+                rendered.append("- " + convert_inline(line.lstrip()[2:], title_lookup, source_dir))
+        else:
+            paragraph = " ".join(line.strip() for line in block)
+            rendered.append(convert_inline(paragraph, title_lookup, source_dir))
+        rendered.append("")
+
+    if rendered and rendered[-1] == "":
+        rendered.pop()
+    return rendered
+
+
+def render_identity(identity_path: Path, title_lookup: dict[Path, str]) -> list[str]:
+    sections = parse_identity(identity_path)
+    rendered = ["## About the Operator", ""]
+    for section_name in IDENTITY_SECTIONS:
+        lines = sections.get(section_name, [])
+        if not lines:
+            continue
+        rendered.append(f"### {section_name}")
+        rendered.extend(
+            render_markdown_lines(lines, title_lookup=title_lookup, source_dir=identity_path.parent)
+        )
+        rendered.append("")
+    if rendered[-1] == "":
+        rendered.pop()
+    return rendered
+
+
+def render_see_also(thread, title_lookup: dict[Path, str]) -> list[str]:
+    items: list[str] = []
+    seen: set[Path] = set()
+    for link in extract_links(thread.connection_lines, thread.source_path):
+        if link.target_path is None or link.target_path in seen:
+            continue
+        target_title = title_lookup.get(link.target_path)
+        if not target_title:
+            continue
+        seen.add(link.target_path)
+        item = f"- [{link.label}](#{slugify_heading(target_title)})"
+        if link.annotation:
+            item += f" - {link.annotation}"
+        items.append(item)
+    return items
+
+
+def render_thread(thread, title_lookup: dict[Path, str]) -> list[str]:
+    lines = [
+        f"### {thread.title}",
+        "",
+        f"*{thread.tier_label} | hits: {thread.hits} | last touched: {thread.last_touched} | tags: {', '.join(thread.tags)}*",
+        "",
+    ]
+
+    if thread.summary_lines:
+        lines.extend(
+            render_markdown_lines(
+                thread.summary_lines,
+                title_lookup=title_lookup,
+                source_dir=thread.source_path.parent,
+            )
+        )
+    else:
+        lines.append("*Missing Summary section in source thread.*")
+
+    see_also = render_see_also(thread, title_lookup)
+    if see_also:
+        lines.extend(["", "**See also**", ""])
+        lines.extend(see_also)
+    return lines
+
+
+def render_main_page(repo_root: Path, output_path: Path) -> str:
+    memex_dir = repo_root / "gator-command"
+    identity_path = memex_dir / "identity.md"
+    threads = load_threads(memex_dir)
+    title_lookup = {thread.source_path.resolve(): thread.title for thread in threads}
+    grouped = category_threads(threads)
+
+    today = dt.date.today().isoformat()
+    lines = [
+        "# Memex - Personal Knowledge System",
+        "",
+        f"**Last rendered:** {today}  ",
+        f"**Threads:** {len(threads)}  ",
+        f"**Categories:** {len(CATEGORY_ORDER)}",
+        "",
+        "This page is auto-generated from the Memex thread graph. The Memex is the source of truth; this file is a rendered summary for human navigation.",
+        "",
+        "**To regenerate:** `python gator-command/scripts/generate_wiki.py && python gator-command/scripts/generate_markdown.py`",
+        "",
+        "**Memex CLI** (`python gator-command/scripts/memex.py`):",
+        "- `memex status` — graph health, inbox count, patterns due, active threads (`--full` for complete state dump)",
+        "- `memex search <query>` — full-text search across threads, artifacts, designs, reports",
+        "- `memex read <type> <name>` — render thread/artifact/design/report (`--section` for specific sections)",
+        "- Add `--format json` for structured agent output, `--role <name>` for role-aware views",
+        "",
+    ]
+
+    lines.extend(render_identity(identity_path, title_lookup))
+    lines.extend(["", "", "## Categories", ""])
+
+    for key, label in CATEGORY_ORDER:
+        titles = [thread.title for thread in grouped.get(key, [])]
+        if not titles:
+            continue
+        lines.append(f"- [{label}](#{slugify_heading(label)}) - {', '.join(titles)}")
+
+    for key, label in CATEGORY_ORDER:
+        category_items = grouped.get(key, [])
+        if not category_items:
+            continue
+        lines.extend(["", "", f"## {label}", ""])
+        for thread in category_items:
+            lines.extend(render_thread(thread, title_lookup))
+            lines.extend(["", ""])
+
+    while lines and lines[-1] == "":
+        lines.pop()
+
+    lines.extend(
+        [
+            "",
+            "",
+            "_This Markdown render was generated mechanically from the Memex thread graph. Summaries are extracted from source threads; no thread prose is synthesized during rendering._",
+            "",
+        ]
+    )
+
+    text = "\n".join(lines)
+    output_path.write_text(text, encoding="utf-8")
+    return text
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--repo-root",
+        default=Path(__file__).resolve().parents[2],
+        type=Path,
+        help="Path to the repository root.",
+    )
+    parser.add_argument(
+        "--output",
+        default=Path("docs/wiki/Main_Page.md"),
+        type=Path,
+        help="Output path, relative to repo root unless absolute.",
+    )
+    args = parser.parse_args()
+
+    repo_root = args.repo_root.resolve()
+    output_path = args.output
+    if not output_path.is_absolute():
+        output_path = repo_root / output_path
+
+    render_main_page(repo_root=repo_root, output_path=output_path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())