@suwujs/codex-vault 0.6.0 → 0.7.1

package/vault/.codex-vault/hooks/codex/session-start.py

@@ -1,387 +0,0 @@
-#!/usr/bin/env python3
-"""Session-start hook for Codex CLI — injects vault context into the agent's prompt.
-
-Outputs structured JSON: additionalContext for LLM.
-Banner is written to stderr (Codex CLI does not render systemMessage).
-
-Dynamic context: adapts git log window, reads full North Star,
-shows all active work, and includes uncommitted changes.
-"""
-import json
-import os
-import re
-import subprocess
-import sys
-from collections import Counter
-from datetime import datetime
-from pathlib import Path
-
-
-def _find_vault_root():
-    """Find vault root from CWD — check for Home.md/brain/, then vault/ subdir."""
-    cwd = os.environ.get("CODEX_PROJECT_DIR", os.getcwd())
-    if os.path.isfile(os.path.join(cwd, "Home.md")) or os.path.isdir(os.path.join(cwd, "brain")):
-        return cwd
-    vault_sub = os.path.join(cwd, "vault")
-    if os.path.isdir(vault_sub) and (
-        os.path.isfile(os.path.join(vault_sub, "Home.md")) or
-        os.path.isdir(os.path.join(vault_sub, "brain"))
-    ):
-        return vault_sub
-    return None
-
-
-def _run_git(args, cwd, timeout=5):
-    """Run git command and return stdout lines."""
-    try:
-        result = subprocess.run(
-            ["git"] + args,
-            capture_output=True, text=True, cwd=cwd, timeout=timeout,
-        )
-        return result.stdout.strip().splitlines() if result.stdout.strip() else []
-    except Exception:
-        return []
-
-
-def _git_log_oneline(cwd, since=None, max_count=None):
-    """Get git log --oneline entries."""
-    args = ["log", "--oneline", "--no-merges"]
-    if since:
-        args.append(f"--since={since}")
-    if max_count:
-        args.extend(["-n", str(max_count)])
-    return _run_git(args, cwd)
-
-
-def _git_status_short(cwd):
-    """Get git status --short output."""
-    return _run_git(["status", "--short", "--", "."], cwd)
-
-
-def _read_file(path):
-    """Read file content, return empty string on error."""
-    try:
-        return Path(path).read_text(encoding="utf-8")
-    except Exception:
-        return ""
-
-
-def _find_md_files(vault_dir):
-    """Find all .md files in vault, excluding non-vault directories."""
-    exclude = {".git", ".obsidian", "thinking", ".claude", ".codex",
-               ".codex-vault", ".codex-mem", "node_modules"}
-    files = []
-    for root, dirs, filenames in os.walk(vault_dir):
-        dirs[:] = [d for d in dirs if d not in exclude]
-        for f in filenames:
-            if f.endswith(".md"):
-                rel = os.path.relpath(os.path.join(root, f), vault_dir)
-                files.append(f"./{rel}")
-    return sorted(files)
-
-
-def _folder_summary(all_files):
-    """Generate folder summary with file counts."""
-    folders = Counter()
-    for f in all_files:
-        parts = f[2:].split("/")  # strip ./
-        folders[parts[0] if len(parts) > 1 else "."] += 1
-    return [f"  {folder}/ ({count} files)"
-            for folder, count in folders.most_common()]
-
-
-def _key_files(all_files):
-    """Filter for key vault files."""
-    pattern = re.compile(
-        r"(Home|Index|North Star|Memories|Key Decisions|Patterns|log)\.md$")
-    return [f for f in all_files if pattern.search(f)]
-
-
-def _mtime_ok(vault_dir, rel_path, cutoff):
-    """Check if file was modified after cutoff timestamp."""
-    try:
-        return os.path.getmtime(os.path.join(vault_dir, rel_path.lstrip("./"))) > cutoff
-    except Exception:
-        return False
-
-
-def _north_star_goal(vault_dir):
-    """Extract first goal from North Star for banner display."""
-    ns_path = os.path.join(vault_dir, "brain", "North Star.md")
-    if not os.path.isfile(ns_path):
-        return None
-    content = _read_file(ns_path)
-    in_focus = False
-    for line in content.splitlines():
-        if re.match(r"^## Current Focus", line):
-            in_focus = True
-            continue
-        if in_focus and line.startswith("## "):
-            break
-        if in_focus and re.match(r"^- .+", line):
-            goal = line[2:].strip()
-            return goal[:40] if goal else None
-    return None
-
-
-# ── Context builder (→ additionalContext for LLM) ──────────────────────
-
-
-def _build_context(vault_dir):
-    lines = []
-    lines.append("## Session Context")
-    lines.append("")
-
-    # Date
-    lines.append("### Date")
-    now = datetime.now()
-    lines.append(f"{now.strftime('%Y-%m-%d')} ({now.strftime('%A')})")
-    lines.append("")
-
-    # North Star — full file
-    lines.append("### North Star")
-    ns_path = os.path.join(vault_dir, "brain", "North Star.md")
-    if os.path.isfile(ns_path):
-        lines.append(_read_file(ns_path))
-    else:
-        lines.append("(No North Star found — create brain/North Star.md to set goals)")
-    lines.append("")
-
-    # Recent changes — adaptive window
-    lines.append("### Recent Changes")
-    commits_48h = _git_log_oneline(vault_dir, since="48 hours ago")
-    if commits_48h:
-        lines.append("(last 48 hours)")
-        lines.extend(commits_48h[:15])
-    else:
-        commits_7d = _git_log_oneline(vault_dir, since="7 days ago")
-        if commits_7d:
-            lines.append("(nothing in 48h — showing last 7 days)")
-            lines.extend(commits_7d[:15])
-        else:
-            lines.append("(nothing recent — showing last 5 commits)")
-            commits = _git_log_oneline(vault_dir, max_count=5)
-            lines.extend(commits if commits else ["(no git history)"])
-    lines.append("")
-
-    # Recent operations from log.md
-    lines.append("### Recent Operations")
-    log_path = os.path.join(vault_dir, "log.md")
-    if os.path.isfile(log_path):
-        entries = [l for l in _read_file(log_path).splitlines()
-                   if l.startswith("## [")]
-        lines.extend(entries[-5:] if entries else ["(no entries in log.md)"])
-    else:
-        lines.append("(no log.md)")
-    lines.append("")
-
-    # Active work
-    lines.append("### Active Work")
-    active_dir = os.path.join(vault_dir, "work", "active")
-    if os.path.isdir(active_dir):
-        work_files = sorted(f for f in os.listdir(active_dir) if f.endswith(".md"))
-        if work_files:
-            for f in work_files:
-                lines.append(f.replace(".md", ""))
-        else:
-            lines.append("(none)")
-    else:
-        lines.append("(no work/active/ directory)")
-    lines.append("")
-
-    # Uncommitted changes
-    lines.append("### Uncommitted Changes")
-    changes = _git_status_short(vault_dir)
-    lines.extend(changes[:20] if changes else ["(working tree clean)"])
-    lines.append("")
-
-    # Recently modified brain files
-    lines.append("### Recently Modified Brain Files")
-    brain_dir = os.path.join(vault_dir, "brain")
-    if os.path.isdir(brain_dir):
-        cutoff = datetime.now().timestamp() - 7 * 86400
-        recent = sorted(
-            f.replace(".md", "")
-            for f in os.listdir(brain_dir)
-            if f.endswith(".md") and os.path.getmtime(os.path.join(brain_dir, f)) > cutoff
-        )
-        if recent:
-            lines.append("(modified in last 7 days)")
-            lines.extend(recent)
-        else:
-            lines.append("(no recent changes)")
-    lines.append("")
-
-    # Vault file listing — tiered
-    lines.append("### Vault Files")
-    all_files = _find_md_files(vault_dir)
-    n = len(all_files)
-
-    if n <= 20:
-        lines.extend(all_files)
-
-    elif n <= 50:
-        hot = [f for f in all_files
-               if not re.match(r"\./sources/|\./work/archive/", f)]
-        cold = n - len(hot)
-        lines.extend(hot)
-        if cold > 0:
-            lines.append("")
-            lines.append(f"(+ {cold} files in sources/ and work/archive/ — use /recall to search)")
-
-    elif n <= 150:
-        lines.append(f"({n} files — showing summary)")
-        lines.append("")
-        lines.extend(_folder_summary(all_files))
-        lines.append("")
-        lines.append("Recently modified (7 days):")
-        cutoff = datetime.now().timestamp() - 7 * 86400
-        recent = [f for f in all_files if _mtime_ok(vault_dir, f, cutoff)]
-        lines.extend(recent if recent else ["  (none)"])
-        lines.append("")
-        lines.append("Key files:")
-        lines.extend(_key_files(all_files))
-
-    else:
-        lines.append(f"({n} files — showing summary)")
-        lines.append("")
-        lines.extend(_folder_summary(all_files))
-        lines.append("")
-        lines.append("Recently modified (3 days):")
-        cutoff = datetime.now().timestamp() - 3 * 86400
-        recent = [f for f in all_files if _mtime_ok(vault_dir, f, cutoff)]
-        lines.extend(recent if recent else ["  (none)"])
-        lines.append("")
-        lines.append("Key files:")
-        lines.extend(_key_files(all_files))
-        lines.append("")
-        lines.append("Use /recall <topic> to search the vault.")
-
-    return "\n".join(lines)
-
-
-# ── ANSI colors (oh-my-codex style) ──────────────────────────────────
-
-RESET = "\x1b[0m"
-BOLD = "\x1b[1m"
-DIM = "\x1b[2m"
-CYAN = "\x1b[36m"
-GREEN = "\x1b[32m"
-YELLOW = "\x1b[33m"
-SEP = f" {DIM}|{RESET} "
-
-
-def _c(code, text):
-    return f"{code}{text}{RESET}"
-
-
-# ── Banner builder (→ stderr for terminal) ────────────────────────────
-
-
-def _build_banner(vault_dir):
-    # --- Line 1: statusline ---
-    elements = []
-
-    # Git branch
-    branch = _run_git(["rev-parse", "--abbrev-ref", "HEAD"], vault_dir)
-    if branch:
-        elements.append(_c(CYAN, branch[0]))
-
-    # North Star goal
-    goal = _north_star_goal(vault_dir)
-    if goal:
-        elements.append(f"\U0001f3af {goal}")
-    else:
-        elements.append(_c(DIM, "\U0001f3af no goal set"))
-
-    # Active work
-    active_dir = os.path.join(vault_dir, "work", "active")
-    work_files = sorted(
-        f.replace(".md", "")
-        for f in os.listdir(active_dir) if f.endswith(".md")
-    ) if os.path.isdir(active_dir) else []
-    if work_files:
-        names = ", ".join(work_files[:3])
-        suffix = f" +{len(work_files) - 3}" if len(work_files) > 3 else ""
-        elements.append(_c(GREEN, f"active:{len(work_files)}") + _c(DIM, f" {names}{suffix}"))
-    else:
-        elements.append(_c(DIM, "active:0"))
-
-    # Changes
-    changes = _git_status_short(vault_dir)
-    if changes:
-        elements.append(_c(YELLOW, f"changes:{len(changes)}"))
-    else:
-        elements.append(_c(GREEN, "clean"))
-
-    label = _c(BOLD, "[Vault]")
-    statusline = label + " " + SEP.join(elements)
-
-    # --- Line 2+: recent commits ---
-    lines = ["", statusline]
-    commits = _git_log_oneline(vault_dir, since="7 days ago")
-    if not commits:
-        commits = _git_log_oneline(vault_dir, max_count=3)
-    if commits:
-        for c in commits[:3]:
-            # hash in cyan, message in dim
-            parts = c.split(" ", 1)
-            if len(parts) == 2:
-                lines.append(f"  {_c(DIM, parts[0])} {_c(DIM, parts[1])}")
-            else:
-                lines.append(f"  {_c(DIM, c)}")
-
-    # --- Line: vault file count ---
-    all_files = _find_md_files(vault_dir)
-    lines.append(_c(DIM, f"  {len(all_files)} notes"))
-    lines.append("")
-
-    return "\n".join(lines)
-
-
-# ── Main ───────────────────────────────────────────────────────────────
-
-
-def main():
-    vault_dir = _find_vault_root()
-    if not vault_dir:
-        output = {
-            "hookSpecificOutput": {
-                "hookEventName": "SessionStart",
-                "additionalContext": "## Session Context\n\n(No vault found)"
-            }
-        }
-        json.dump(output, sys.stdout)
-        sys.exit(0)
-
-    # Read hook input for session metadata
-    try:
-        event = json.load(sys.stdin)
-    except Exception:
-        event = {}
-
-    context = _build_context(vault_dir)
-    banner = _build_banner(vault_dir)
-
-    # Codex CLI: systemMessage not rendered by TUI,
-    # use stderr for terminal visibility (best effort)
-    sys.stderr.write(banner + "\n")
-
-    output = {
-        "hookSpecificOutput": {
-            "hookEventName": "SessionStart",
-            "additionalContext": context
-        },
-    }
-
-    json.dump(output, sys.stdout)
-    sys.stdout.flush()
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    try:
-        main()
-    except Exception:
-        # Never block session start
-        sys.exit(0)

package/vault/.codex-vault/hooks/codex/validate-write.py

@@ -1,127 +0,0 @@
-#!/usr/bin/env python3
-"""Post-write validation for vault notes — Codex CLI version.
-
-Checks frontmatter and wikilinks on any .md file written to the vault.
-Outputs hookSpecificOutput for Codex CLI. Feedback via stderr
-(Codex CLI does not render systemMessage).
-
-Note: Codex CLI PostToolUse only supports Bash matcher, so this script
-will only run when triggered by a Bash tool writing .md files. The
-validation logic is identical to the Claude Code version.
-"""
-import json
-import re
-import sys
-import os
-from pathlib import Path
-
-
-def _check_log_format(content):
-    """Validate log.md entry format: ## [YYYY-MM-DD] <type> | <title>"""
-    warnings = []
-    for i, line in enumerate(content.splitlines(), 1):
-        if line.startswith("## ") and not line.startswith("## ["):
-            # Heading that looks like a log entry but missing date brackets
-            if any(t in line.lower() for t in ["ingest", "session", "query", "maintenance", "decision", "archive"]):
-                warnings.append(f"Line {i}: log entry missing date format — expected `## [YYYY-MM-DD] <type> | <title>`")
-        elif line.startswith("## ["):
-            if not re.match(r"^## \[\d{4}-\d{2}-\d{2}\] \w+", line):
-                warnings.append(f"Line {i}: malformed log entry — expected `## [YYYY-MM-DD] <type> | <title>`")
-    return warnings
-
-
-def main():
-    try:
-        input_data = json.load(sys.stdin)
-    except (ValueError, EOFError, OSError):
-        sys.exit(0)
-
-    tool_input = input_data.get("tool_input")
-    if not isinstance(tool_input, dict):
-        sys.exit(0)
-
-    file_path = tool_input.get("file_path", "")
-    if not isinstance(file_path, str) or not file_path:
-        sys.exit(0)
-
-    if not file_path.endswith(".md"):
-        sys.exit(0)
-
-    normalized = file_path.replace("\\", "/")
-    basename = os.path.basename(normalized)
-
-    # Skip non-vault files
-    skip_names = {"README.md", "CHANGELOG.md", "CONTRIBUTING.md", "CLAUDE.md", "AGENTS.md", "LICENSE"}
-    if basename in skip_names:
-        sys.exit(0)
-    if basename.startswith("README.") and basename.endswith(".md"):
-        sys.exit(0)
-
-    skip_paths = [".claude/", ".codex/", ".codex-vault/", ".mind/", "templates/", "thinking/", "node_modules/", "plugin/", "docs/"]
-    if any(skip in normalized for skip in skip_paths):
-        sys.exit(0)
-
-    warnings = []
-
-    try:
-        content = Path(file_path).read_text(encoding="utf-8")
-
-        if not content.startswith("---"):
-            warnings.append("Missing YAML frontmatter")
-        else:
-            parts = content.split("---", 2)
-            if len(parts) >= 3:
-                fm = parts[1]
-                if "date:" not in fm and basename != "log.md":
-                    warnings.append("Missing `date` in frontmatter")
-                if "tags:" not in fm:
-                    warnings.append("Missing `tags` in frontmatter")
-                if "description:" not in fm:
-                    warnings.append("Missing `description` in frontmatter (~150 chars)")
-
-        if len(content) > 300 and "[[" not in content:
-            warnings.append("No [[wikilinks]] found — every note should link to at least one other note")
-
-        # Check for unfilled template placeholders
-        placeholders = re.findall(r"\{\{[^}]+\}\}", content)
-        if placeholders:
-            examples = ", ".join(placeholders[:3])
-            warnings.append(f"Unfilled template placeholders found: {examples}")
-
-        # Validate log.md format
-        if basename == "log.md":
-            log_warnings = _check_log_format(content)
-            warnings.extend(log_warnings)
-
-    except Exception:
-        sys.exit(0)
-
-    if warnings:
-        hint_list = "\n".join(f"  - {w}" for w in warnings)
-        count = len(warnings)
-        first = warnings[0]
-        if count == 1:
-            feedback = f"\u26a0\ufe0f  vault: {basename} — {first}"
-        else:
-            feedback = f"\u26a0\ufe0f  vault: {basename} — {first} (+{count - 1} more)"
-
-        # Codex CLI: use stderr for feedback (no systemMessage rendering)
-        sys.stderr.write(f"  {feedback}\n")
-
-        output = {
-            "hookSpecificOutput": {
-                "hookEventName": "PostToolUse",
-                "additionalContext": f"Vault warnings for `{basename}`:\n{hint_list}\nFix these before moving on."
-            },
-        }
-        json.dump(output, sys.stdout)
-        sys.stdout.flush()
-
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    try:
-        main()
-    except Exception:
-        sys.exit(0)

package/vault/AGENTS.md

@@ -1,118 +0,0 @@
-# Codex-Vault — Core Instructions
-
-A structured knowledge vault maintained by an LLM agent. You write notes, maintain links, and keep indexes current. The human curates sources, directs analysis, and asks questions.
-
-## Vault Structure
-
-| Folder | Purpose |
-|--------|---------|
-| `Home.md` | Vault entry point — quick links, current focus |
-| `brain/` | Persistent memory — goals, decisions, patterns |
-| `work/` | Work notes index (`Index.md`) |
-| `work/active/` | Current projects (move to archive when done) |
-| `work/archive/` | Completed work |
-| `templates/` | Note templates with YAML frontmatter |
-| `sources/` | Raw source documents — immutable, LLM reads only |
-| `thinking/` | Scratchpad — promote findings, then delete |
-| `reference/` | Saved answers and analyses from query writeback |
-
-## Session Lifecycle
-
-### Start
-
-The SessionStart hook injects: North Star goals, recent git changes, active work, vault file listing. You start with context, not a blank slate.
-
-### Work
-
-1. The classify hook detects intent and suggests skills — **do not auto-execute**. Suggest the skill to the user and let them decide.
-2. Available skills: `/dump`, `/recall`, `/ingest`, `/wrap-up`
-3. Search before creating — check if a related note exists (use `/recall <topic>` for targeted vault search)
-4. Update `work/Index.md` if a new note was created
-
-### End
-
-When the user says "wrap up" or similar:
-1. Verify new notes have frontmatter and wikilinks
-2. Update `work/Index.md` with any new or completed notes
-3. Archive completed projects: move from `work/active/` to `work/archive/`
-4. Check if `brain/` notes need updating with new decisions or patterns
-
-## Creating Notes
-
-1. **Always use YAML frontmatter**: `date`, `description` (~150 chars), `tags`
-2. **Use templates** from `templates/`
-3. **Place files correctly**: active work in `work/active/`, completed in `work/archive/`, source summaries in `work/active/` (tag: `source-summary`), drafts in `thinking/`
-4. **Name files descriptively** — use the note title as filename
-
-## Linking — Critical
-
-**Graph-first.** Folders group by purpose, links group by meaning. A note lives in one folder but links to many notes.
-
-**A note without links is a bug.** Every new note must link to at least one existing note via `[[wikilinks]]`.
-
-Link syntax:
-- `[[Note Title]]` — standard wikilink
-- `[[Note Title|display text]]` — aliased
-- `[[Note Title#Heading]]` — deep link
-
-### When to Link
-
-- Work note ↔ Decision Record (bidirectional)
-- Index → all work notes
-- North Star → active projects
-- Memories → source notes
-
-## Memory System
-
-All persistent memory lives in `brain/`:
-
-| File | Stores |
-|------|--------|
-| `North Star.md` | Goals and focus areas — read every session |
-| `Memories.md` | Index of memory topics |
-| `Key Decisions.md` | Decisions worth recalling across sessions |
-| `Patterns.md` | Recurring patterns discovered across work |
-
-When asked to "remember" something: write to the appropriate `brain/` file with a wikilink to context.
-
-## Sources & Ingest
-
-`sources/` holds raw source documents (articles, papers, web clips). This is the immutable layer — the agent reads from it but never modifies source files.
-
-- Drop raw files into `sources/` (markdown preferred) or use `/ingest` with a URL
-- `/ingest` reads the source, discusses key takeaways, then creates a **Source Summary** in `work/active/` with tag `source-summary`
-- The summary uses the Source Summary template: Key Takeaways, Summary, Connections, Quotes/Data Points
-- Every ingest updates `work/Index.md` (Sources section) and checks for cross-links to existing notes
-- If the source contains decisions or patterns, update the relevant `brain/` notes too
-- Source summaries link back to the raw source via the `source` frontmatter field
-
-## Operation Log
-
-Append to `log.md` after significant operations: ingests, decisions, project archives, maintenance passes.
-
-- Format: `## [YYYY-MM-DD] <type> | <title>` followed by bullet points
-- Types: `ingest`, `session`, `query`, `maintenance`, `decision`, `archive`
-- Don't log every small edit — only operations that change the vault's knowledge state
-- Entries are append-only; never edit or delete previous entries
-
-## Query Writeback
-
-When answering a substantial question that synthesizes multiple vault notes:
-
-1. Offer: "This answer could be useful later — want me to save it as a reference note?"
-2. If yes, create a Reference Note in `reference/` using the template
-3. Link the reference note from related work notes in `## Related`
-4. Add the reference note to `work/Index.md` under `## Reference`
-5. Don't prompt for trivial questions — only for answers that synthesize, compare, or analyze
-
-## Vault Location
-
-The vault may live at the project root or in a `vault/` subdirectory. Use the SessionStart context to determine the actual path. All folder references above (e.g. `brain/`, `work/active/`) are relative to the vault root.
-
-## Rules
-
-- Preserve existing frontmatter when editing notes
-- Always check for and suggest connections between notes
-- Every note must have a `description` field (~150 chars)
-- When reorganizing, never delete without user confirmation
-- Use `[[wikilinks]]` not markdown links