auto-context-cli 1.0.0__py3-none-any.whl

auto_context/commands/mcp.py

@@ -0,0 +1,304 @@
+"""
+commands/mcp.py — MCP tool registry management.
+
+Subcommands: add, remove, list
+Uses native json.load / json.dump — no shell JSON manipulation.
+
+Presets: sqlite, duckdb, git, fetch, time, postgres, github, filesystem, brave
+"""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from auto_context import config
+from auto_context.config import AGENTS_SUBDIR, GEMINI_SUBDIR
+
+app = typer.Typer(help="MCP tool registry management.")
+console = Console()
+
+# ── Preset definitions ────────────────────────────────────────────────────────
+# Each preset is a callable that receives (runtime, args, env_var) and returns
+# a dict that becomes the server config value in mcp_config.json.
+
+_PRESETS: dict[str, dict] = {
+    "sqlite": {
+        "uvx": lambda db: {"command": "uvx", "args": ["mcp-server-sqlite", "--db-path", db]},
+        "npx": lambda db: {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-sqlite", db]},
+        "default_args": "database.db",
+        "env_var": None,
+    },
+    "duckdb": {
+        "uvx": lambda db: {"command": "uvx", "args": ["duckdb-mcp", "--db-path", db]},
+        "npx": lambda db: {"command": "uvx", "args": ["duckdb-mcp", "--db-path", db]},  # always uvx
+        "default_args": "database.duckdb",
+        "env_var": None,
+        "force_uvx": True,
+    },
+    "git": {
+        "uvx": lambda repo: {"command": "uvx", "args": ["mcp-server-git", "--repository", repo]},
+        "npx": lambda repo: {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-git", repo]},
+        "default_args": ".",
+        "env_var": None,
+    },
+    "fetch": {
+        "uvx": lambda _: {"command": "uvx", "args": ["mcp-server-fetch"]},
+        "npx": lambda _: {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-fetch"]},
+        "env_var": None,
+    },
+    "time": {
+        "uvx": lambda _: {"command": "uvx", "args": ["mcp-server-time"]},
+        "npx": lambda _: {"command": "uvx", "args": ["mcp-server-time"]},  # always uvx
+        "env_var": None,
+        "force_uvx": True,
+    },
+    "postgres": {
+        "uvx": lambda conn: {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", conn]},
+        "npx": lambda conn: {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", conn]},
+        "default_env_var": "DATABASE_URL",
+        "env_placeholder": "postgresql://username:password@localhost:5432/mydb",
+    },
+    "github": {
+        "uvx": lambda _: {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"],
+                          "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"}},
+        "npx": lambda _: {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"],
+                          "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"}},
+        "default_env_var": "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "env_placeholder": "ghp_yourPersonalAccessTokenHere",
+    },
+    "filesystem": {
+        "uvx": lambda d: {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", d]},
+        "npx": lambda d: {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", d]},
+        "default_args": ".",
+        "env_var": None,
+    },
+    "brave": {
+        "uvx": lambda _: {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+                          "env": {"BRAVE_API_KEY": "${BRAVE_API_KEY}"}},
+        "npx": lambda _: {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+                          "env": {"BRAVE_API_KEY": "${BRAVE_API_KEY}"}},
+        "default_env_var": "BRAVE_API_KEY",
+        "env_placeholder": "your_brave_api_key_here",
+    },
+}
+
+
+# ── .env helpers ──────────────────────────────────────────────────────────────
+
+def _write_env_placeholder(project_dir: Path, var_name: str, placeholder: str) -> None:
+    """Write a placeholder to .env.example and protect .env in .gitignore."""
+    example = project_dir / ".env.example"
+    existing = example.read_text(encoding="utf-8") if example.exists() else ""
+    if f"{var_name}=" not in existing:
+        with example.open("a", encoding="utf-8") as fh:
+            fh.write(f"{var_name}={placeholder}\n")
+        console.print(f"  [green][✓] Added placeholder:[/] .env.example ({var_name})")
+
+    # Secure .env with chmod 600 equivalent if it exists
+    dot_env = project_dir / ".env"
+    if dot_env.exists():
+        try:
+            dot_env.chmod(stat.S_IRUSR | stat.S_IWUSR)
+        except OSError:
+            pass  # Windows may not support this; best-effort
+
+
+def _detect_runtime(project_dir: Path) -> str:
+    """Auto-detect uvx vs npx based on project indicators."""
+    import shutil
+    py_indicators = ("pyproject.toml", "requirements.txt", "Pipfile")
+    has_python = any((project_dir / f).exists() for f in py_indicators)
+    if has_python and shutil.which("uvx"):
+        return "uvx"
+    return "npx"
+
+
+# ── JSON config helpers ───────────────────────────────────────────────────────
+
+def _load_mcp_config(path: Path) -> dict:
+    """Load mcp_config.json, returning an empty mcpServers dict on failure."""
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                return data
+        except json.JSONDecodeError:
+            pass
+    return {"mcpServers": {}}
+
+
+def _save_mcp_config(path: Path, data: dict) -> None:
+    """Write mcp_config.json with 2-space indent."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+
+
+def _mcp_paths(project_dir: Path, global_: bool) -> list[Path]:
+    """Return the list of mcp_config.json paths to write."""
+    if global_:
+        return [
+            config.GLOBAL_GEMINI_DIR / "mcp_config.json",
+            config.GLOBAL_PLUGIN_DIR / "mcp_config.json",
+        ]
+    return [
+        project_dir / GEMINI_SUBDIR / "mcp_config.json",
+        project_dir / AGENTS_SUBDIR / "mcp_config.json",
+    ]
+
+
+# ── add subcommand ────────────────────────────────────────────────────────────
+
+@app.command("add")
+def add_mcp(
+    name: Annotated[str, typer.Argument(help="Server name or preset (sqlite, github, …).")],
+    target: Annotated[Optional[Path], typer.Option("--target", "-t")] = None,
+    global_: Annotated[bool, typer.Option("--global", "-g")] = False,
+    preset: Annotated[Optional[str], typer.Option("--preset", "-p", help="Preset name.")] = None,
+    runtime: Annotated[Optional[str], typer.Option("--runtime", "--runner")] = None,
+    command: Annotated[Optional[str], typer.Option("--command", "-c")] = None,
+    args: Annotated[Optional[str], typer.Option("--args", "-a")] = None,
+    url: Annotated[Optional[str], typer.Option("--url")] = None,
+    env_var: Annotated[Optional[str], typer.Option("--env-var")] = None,
+    env: Annotated[Optional[str], typer.Option("--env", help="KEY=val,KEY2=val2")] = None,
+) -> None:
+    """Add or update an MCP server configuration."""
+    project_dir = (target or Path.cwd()).resolve()
+    server_name = name.lower()
+    chosen_preset = preset or (name.lower() if name.lower() in _PRESETS else None)
+    runner = runtime or _detect_runtime(project_dir)
+
+    server_cfg: dict = {}
+
+    if url:
+        server_cfg = {"url": url}
+
+    elif chosen_preset and chosen_preset in _PRESETS:
+        p = _PRESETS[chosen_preset]
+        force_uvx = p.get("force_uvx", False)
+        r = "uvx" if force_uvx else runner
+        arg_val = args or p.get("default_args", ".")
+        fn = p[r] if r in p else p["npx"]
+        server_cfg = fn(arg_val)
+
+        # Handle secret env vars
+        default_ev = p.get("default_env_var")
+        if default_ev:
+            ev = env_var or default_ev
+            ph = p.get("env_placeholder", f"your_{ev}_here")
+            if not global_:
+                _write_env_placeholder(project_dir, ev, ph)
+            console.print(f"  [bold green][🔒] Secret safety:[/] {ev} referenced via env var (not hardcoded).")
+
+    elif command:
+        server_cfg = {"command": command}
+        if args:
+            server_cfg["args"] = args.split()
+        if env_var:
+            server_cfg.setdefault("env", {})[env_var] = f"${{{env_var}}}"
+            if not global_:
+                _write_env_placeholder(project_dir, env_var, f"your_{env_var}_here")
+
+    else:
+        # Generic: derive package name from server_name
+        if runner == "uvx":
+            server_cfg = {"command": "uvx", "args": [f"mcp-server-{server_name}"]}
+        else:
+            server_cfg = {"command": "npx", "args": ["-y", f"@modelcontextprotocol/server-{server_name}"]}
+
+    # Merge explicit --env pairs
+    if env:
+        extra = {}
+        for item in env.split(","):
+            if "=" in item:
+                k, v = item.split("=", 1)
+                extra[k.strip()] = v.strip()
+        server_cfg.setdefault("env", {}).update(extra)
+
+    # Write to all target config files
+    for cfg_path in _mcp_paths(project_dir, global_):
+        data = _load_mcp_config(cfg_path)
+        data["mcpServers"][server_name] = server_cfg
+        _save_mcp_config(cfg_path, data)
+
+    scope = f"GLOBAL (~/.gemini/config/mcp_config.json)" if global_ else f"LOCAL ({project_dir}/.gemini/mcp_config.json)"
+    transport = f"HTTP ({url})" if url else f"stdio ({server_cfg.get('command', '?')})"
+    console.print(f"\n[bold cyan]🔌 MCP Server Configured![/]")
+    console.print(f"   [yellow]Server:[/]    {server_name}")
+    console.print(f"   [cyan]Scope:[/]     {scope}")
+    console.print(f"   [green]Transport:[/] {transport}")
+    console.print("   [dim][i] Restart your AI client to activate new MCP tools.[/]\n")
+
+
+# ── remove subcommand ─────────────────────────────────────────────────────────
+
+@app.command("remove")
+def remove_mcp(
+    name: Annotated[str, typer.Argument(help="Server name to remove.")],
+    target: Annotated[Optional[Path], typer.Option("--target", "-t")] = None,
+    global_: Annotated[bool, typer.Option("--global", "-g")] = False,
+) -> None:
+    """Remove an MCP server from configuration."""
+    project_dir = (target or Path.cwd()).resolve()
+    removed_from: list[Path] = []
+
+    for cfg_path in _mcp_paths(project_dir, global_):
+        if not cfg_path.exists():
+            continue
+        data = _load_mcp_config(cfg_path)
+        if name in data.get("mcpServers", {}):
+            del data["mcpServers"][name]
+            _save_mcp_config(cfg_path, data)
+            removed_from.append(cfg_path)
+
+    if removed_from:
+        console.print(f"[green][✓] Removed MCP server:[/] {name}")
+        for p in removed_from:
+            console.print(f"   [dim]{p}[/]")
+    else:
+        console.print(f"[yellow][!] Server '{name}' not found in any MCP config.[/]")
+
+
+# ── list subcommand ───────────────────────────────────────────────────────────
+
+@app.command("list")
+def list_mcp(
+    target: Annotated[Optional[Path], typer.Option("--target", "-t")] = None,
+    global_: Annotated[bool, typer.Option("--global", "-g")] = False,
+) -> None:
+    """List all registered MCP servers."""
+    project_dir = (target or Path.cwd()).resolve()
+
+    for cfg_path in _mcp_paths(project_dir, global_):
+        if not cfg_path.exists():
+            continue
+        data = _load_mcp_config(cfg_path)
+        servers = data.get("mcpServers", {})
+        if not servers:
+            continue
+
+        table = Table(title=f"MCP Servers — {cfg_path}", border_style="cyan")
+        table.add_column("Name", style="yellow", no_wrap=True)
+        table.add_column("Type", style="magenta", width=6)
+        table.add_column("Endpoint / Command", style="white")
+
+        for sname, cfg in servers.items():
+            if "url" in cfg:
+                table.add_row(sname, "http", cfg["url"])
+            else:
+                cmd_str = cfg.get("command", "?") + " " + " ".join(cfg.get("args", []))
+                if len(cmd_str) > 60:
+                    cmd_str = cmd_str[:57] + "..."
+                table.add_row(sname, "stdio", cmd_str)
+
+        console.print(table)
+        return
+
+    console.print("[yellow][!] No MCP configuration found. Run:[/] init-context mcp add <name>")
+

auto_context/commands/memory.py

@@ -0,0 +1,236 @@
+"""
+commands/memory.py — Central memory brain management.
+
+Wraps git CLI via subprocess.run. Runs security.audit_path()
+before every commit or push — zero-bypass hard-block.
+
+Subcommands: init, push, pull, status
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from datetime import datetime
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from auto_context import config, security
+
+app = typer.Typer(help="Central memory brain management.")
+console = Console()
+
+MEMORY_DIR = config.MEMORY_DIR
+
+_GITIGNORE_ENTRIES = """\
+# Security: Prohibit credentials and environment files from central memory
+.env
+.env.*
+*.local.md
+context.local.md
+*.key
+*.pem
+*.p12
+*.pfx
+*.kdbx
+id_rsa*
+id_ed25519*
+id_ecdsa*
+id_dsa*
+authorized_keys
+known_hosts
+"""
+
+
+def _git(cwd: Path, *args: str, check: bool = True) -> subprocess.CompletedProcess:
+    """Run a git command in *cwd*, capturing output."""
+    return subprocess.run(
+        ["git", "-C", str(cwd), *args],
+        capture_output=True,
+        text=True,
+        check=check,
+    )
+
+
+def _has_gh() -> bool:
+    return shutil.which("gh") is not None
+
+
+# ── init ──────────────────────────────────────────────────────────────────────
+
+@app.command("init")
+def memory_init(
+    repo_name: Annotated[str, typer.Argument(help="GitHub repo name.")] = "auto-context-memory",
+) -> None:
+    """Initialize a private central memory brain repository."""
+    console.print(Panel(
+        f"[bold green]🧠 Initializing Private Central Memory Brain[/]\n"
+        f"[yellow]   Directory:[/] {MEMORY_DIR}\n"
+        f"[cyan]   Repo:     [/] {repo_name} (Strictly Private)",
+        border_style="cyan",
+    ))
+
+    (MEMORY_DIR / "rules").mkdir(parents=True, exist_ok=True)
+    (MEMORY_DIR / "skills").mkdir(parents=True, exist_ok=True)
+
+    # Init git repo
+    if not (MEMORY_DIR / ".git").exists():
+        _git(MEMORY_DIR, "init")
+        console.print("  [green][✓] Initialized Git repository[/]")
+
+    # Hardened .gitignore
+    (MEMORY_DIR / ".gitignore").write_text(_GITIGNORE_ENTRIES, encoding="utf-8")
+    console.print("  [green][✓] Hardened .gitignore written[/]")
+
+    # profile.md
+    _write_profile(repo_name)
+
+    # Security audit before first commit
+    console.print("  [cyan][*] Running pre-commit security audit...[/]")
+    violations = security.audit_path(MEMORY_DIR)
+    security.abort_if_violations(violations)
+
+    _git(MEMORY_DIR, "add", "-A", check=False)
+    _git(MEMORY_DIR, "commit", "-m", config.GIT_COMMIT_INIT, check=False)
+    _git(MEMORY_DIR, "branch", "-M", "main", check=False)
+
+    if _has_gh():
+        console.print("  [cyan][*] Creating strictly private GitHub repository via gh...[/]")
+        result = subprocess.run(
+            ["gh", "repo", "create", repo_name,
+             "--private", f"--source={MEMORY_DIR}", "--remote=origin", "--push"],
+            capture_output=True, text=True,
+        )
+        if result.returncode == 0:
+            console.print("  [green][✓] Private GitHub memory repository created and pushed![/]")
+        else:
+            _print_manual_push(repo_name)
+    else:
+        console.print("  [yellow][!] GitHub CLI ('gh') not found. Install it or connect manually:[/]")
+        _print_manual_push(repo_name)
+
+    console.print(f"\n[bold green]🎉 Central Memory Initialized![/]")
+    console.print(f"   [yellow]Local Brain:[/]  {MEMORY_DIR}")
+    console.print(f"   [green]Sync Command:[/] init-context memory push\n")
+
+
+def _print_manual_push(repo_name: str) -> None:
+    console.print(f"   [dim]git -C \"{MEMORY_DIR}\" remote add origin git@github.com:<username>/{repo_name}.git[/]")
+    console.print(f"   [dim]git -C \"{MEMORY_DIR}\" push -u origin main[/]")
+
+
+def _write_profile(repo_name: str) -> None:
+    profile = MEMORY_DIR / "profile.md"
+    if profile.exists():
+        return
+    import getpass
+    username = getpass.getuser()
+    date_now = datetime.now().strftime("%Y-%m-%d")
+    profile.write_text(
+        f"# Agent Memory & Developer Profile\n\n"
+        f"> **Owner:** {username}  \n"
+        f"> **Initialized:** {date_now}  \n"
+        f"> **Repository:** {repo_name}  \n"
+        f"> **Visibility:** Private Central Agent Brain  \n\n---\n\n"
+        f"## 1. Developer Preferences\n- Edit this file to personalise agent behaviour.\n\n"
+        f"## 2. Central Knowledge Base Index\n"
+        f"- **Global Rules:** `rules/`\n"
+        f"- **Reusable Skills:** `skills/`\n",
+        encoding="utf-8",
+    )
+    console.print("  [green][✓] Generated Developer Profile: profile.md[/]")
+
+
+# ── push ──────────────────────────────────────────────────────────────────────
+
+@app.command("push")
+def memory_push() -> None:
+    """Audit secrets and push memory brain to private GitHub repo."""
+    console.print(Panel(
+        "[bold green]🧠 Synchronizing Central Memory Brain[/]\n"
+        f"[yellow]   Location:[/] {MEMORY_DIR}",
+        border_style="cyan",
+    ))
+
+    if not MEMORY_DIR.exists():
+        console.print(f"[red][✗] Memory directory not found:[/] {MEMORY_DIR}")
+        console.print("    Run: [cyan]init-context memory init[/]")
+        raise typer.Exit(1)
+
+    console.print("  [cyan][*] Running Zero-Bypass Security Auditor...[/]")
+    violations = security.audit_path(MEMORY_DIR)
+    security.abort_if_violations(violations)
+
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M")
+    _git(MEMORY_DIR, "add", "-A", check=False)
+    _git(MEMORY_DIR, "commit", "-m", f"{config.GIT_COMMIT_SYNC} [{timestamp}]", check=False)
+
+    remote = _git(MEMORY_DIR, "remote", "get-url", "origin", check=False).stdout.strip()
+    if remote:
+        console.print("  [cyan][*] Pushing to private remote repository...[/]")
+        result = _git(MEMORY_DIR, "push", "origin", "main", check=False)
+        if result.returncode == 0:
+            console.print("  [green][✓] Memory brain pushed successfully![/]")
+        else:
+            console.print(f"  [red][✗] Push failed:[/] {result.stderr.strip()}")
+    else:
+        console.print("  [yellow][!] No remote 'origin' configured. Run memory init first.[/]")
+
+    console.print("\n[bold green]✨ Memory synchronization complete![/]\n")
+
+
+# ── pull ──────────────────────────────────────────────────────────────────────
+
+@app.command("pull")
+def memory_pull(
+    repo_url: Annotated[Optional[str], typer.Argument(help="Remote repo URL (required for first pull).")] = None,
+) -> None:
+    """Pull and sync the central memory brain from remote."""
+    console.print(Panel(
+        "[bold green]🧠 Pulling Central Memory Brain[/]",
+        border_style="cyan",
+    ))
+
+    if not MEMORY_DIR.exists():
+        if not repo_url:
+            console.print("[red][✗] Memory directory not found. Provide a repo URL:[/]")
+            console.print("    [cyan]init-context memory pull <url>[/]")
+            raise typer.Exit(1)
+        subprocess.run(["git", "clone", repo_url, str(MEMORY_DIR)], check=True)
+    else:
+        _git(MEMORY_DIR, "pull", "origin", "main")
+
+    console.print("  [cyan][*] Running post-pull security audit...[/]")
+    violations = security.audit_path(MEMORY_DIR)
+    security.abort_if_violations(violations)
+    console.print("\n[bold green]✨ Central memory updated successfully![/]\n")
+
+
+# ── status ────────────────────────────────────────────────────────────────────
+
+@app.command("status")
+def memory_status() -> None:
+    """Show status of the central memory brain."""
+    console.print(Panel(
+        "[bold green]🧠 Central Memory Status[/]",
+        border_style="cyan",
+    ))
+
+    if not MEMORY_DIR.exists():
+        console.print("  [yellow][!] Central memory not initialized.[/]")
+        console.print("      Run: [cyan]init-context memory init[/]")
+        return
+
+    remote = _git(MEMORY_DIR, "remote", "get-url", "origin", check=False).stdout.strip()
+    rules_count = len(list((MEMORY_DIR / "rules").glob("*.md"))) if (MEMORY_DIR / "rules").exists() else 0
+    skills_count = len([d for d in (MEMORY_DIR / "skills").iterdir() if d.is_dir()]) if (MEMORY_DIR / "skills").exists() else 0
+
+    console.print(f"  [yellow]Location:[/] {MEMORY_DIR}")
+    console.print(f"  [cyan]Remote:  [/] {remote or '(none)'}")
+    console.print(f"  [green]Rules:   [/] {rules_count} registered")
+    console.print(f"  [green]Skills:  [/] {skills_count} registered")
+    console.print()
+

auto_context/commands/share.py

@@ -0,0 +1,122 @@
+"""
+commands/share.py — Publish a skill or rule via GitHub Gist.
+
+Primary:  gh gist create (if gh CLI available and authenticated)
+Fallback: httpx + GITHUB_TOKEN env var → POST /gists
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+
+from auto_context import config, security
+
+console = Console()
+
+
+def _find_item(name: str, project_dir: Path) -> Optional[Path]:
+    """Search local, memory, and global scopes for a named skill or rule."""
+    clean = name.lower().replace(" ", "-").replace("_", "-").removesuffix(".md")
+    candidates = [
+        project_dir / ".agents" / "skills" / clean / "SKILL.md",
+        project_dir / ".agents" / "rules" / f"{clean}.md",
+        config.MEMORY_DIR / "skills" / clean / "SKILL.md",
+        config.MEMORY_DIR / "rules" / f"{clean}.md",
+        config.GLOBAL_PLUGIN_DIR / "skills" / clean / "SKILL.md",
+        config.GLOBAL_PLUGIN_DIR / "rules" / f"{clean}.md",
+    ]
+    return next((p for p in candidates if p.exists()), None)
+
+
+def _gh_gist_create(file_path: Path, public: bool, description: str) -> Optional[str]:
+    """Create a Gist via gh CLI. Returns the Gist URL or None on failure."""
+    if not shutil.which("gh"):
+        return None
+    cmd = ["gh", "gist", "create", str(file_path), "--desc", description]
+    if public:
+        cmd.append("--public")
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode == 0:
+        for line in result.stdout.splitlines():
+            clean_line = line.strip()
+            if "gist.github.com" in clean_line:
+                return clean_line
+        return result.stdout.strip()
+    return None
+
+
+def _httpx_gist_create(file_path: Path, public: bool, description: str) -> Optional[str]:
+    """Fallback: create a Gist via GitHub REST API using GITHUB_TOKEN."""
+    token = os.environ.get("GITHUB_TOKEN")
+    if not token:
+        return None
+    try:
+        import httpx
+    except ImportError:
+        return None
+
+    content = file_path.read_text(encoding="utf-8")
+    payload = {
+        "description": description,
+        "public": public,
+        "files": {file_path.name: {"content": content}},
+    }
+    resp = httpx.post(
+        "https://api.github.com/gists",
+        headers={"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"},
+        json=payload,
+        timeout=30,
+    )
+    if resp.status_code == 201:
+        return resp.json().get("html_url")
+    return None
+
+
+def share(
+    name: Annotated[str, typer.Argument(help="Skill or rule name to share.")],
+    target: Annotated[Optional[Path], typer.Option("--target", "-t")] = None,
+    public: Annotated[bool, typer.Option("--public", help="Publish as public Gist (default: secret).")] = False,
+) -> None:
+    """Audit and publish a skill or rule via GitHub Gist."""
+    project_dir = (target or Path.cwd()).resolve()
+    target_file = _find_item(name, project_dir)
+
+    if not target_file:
+        console.print(f"[red][✗] Item '{name}' not found in local, memory, or global scopes.[/]")
+        raise typer.Exit(1)
+
+    clean_name = name.lower().replace(" ", "-").replace("_", "-").removesuffix(".md")
+    console.print(f"\n[bold cyan]📤 Publishing:[/] {clean_name}\n   [dim]{target_file}[/]")
+
+    console.print("  [cyan][*] Running pre-share security audit...[/]")
+    violations = security.audit_path(target_file, single_file=True)
+    security.abort_if_violations(violations)
+
+    description = f"auto-context: {clean_name}"
+    gist_url = _gh_gist_create(target_file, public, description)
+    if not gist_url:
+        gist_url = _httpx_gist_create(target_file, public, description)
+
+    if not gist_url:
+        console.print(
+            "[red][✗] Could not publish Gist.[/]\n"
+            "    Install [cyan]gh[/] CLI and run [cyan]gh auth login[/], "
+            "or set the [cyan]GITHUB_TOKEN[/] environment variable."
+        )
+        raise typer.Exit(1)
+
+    console.print(f"\n[bold green]✨ Published successfully![/]")
+    console.print(f"   [cyan]Gist URL:[/] {gist_url}")
+    console.print(f"\n[yellow]💡 Anyone can import this with:[/]")
+    console.print(f"   [green]init-context import {gist_url}[/]\n")
+