ragtime-cli 0.2.1__py3-none-any.whl → 0.2.2__py3-none-any.whl

{ragtime_cli-0.2.1.dist-info → ragtime_cli-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragtime-cli
-Version: 0.2.1
+Version: 0.2.2
 Summary: Local-first memory and RAG system for Claude Code - semantic search over code, docs, and team knowledge
 Author-email: Bret Martineau <bretwardjames@gmail.com>
 License-Expression: MIT

{ragtime_cli-0.2.1.dist-info → ragtime_cli-0.2.2.dist-info}/RECORD

@@ -1,12 +1,13 @@
-ragtime_cli-0.2.1.dist-info/licenses/LICENSE,sha256=9A0wJs2PRDciGRH4F8JUJ-aMKYQyq_gVu2ixrXs-l5A,1070
+ragtime_cli-0.2.2.dist-info/licenses/LICENSE,sha256=9A0wJs2PRDciGRH4F8JUJ-aMKYQyq_gVu2ixrXs-l5A,1070
 src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-src/cli.py,sha256=uZldKb8m53E3lKdhEVHjBYEnTvFSIv90AQ2iyuXIhDA,38083
+src/cli.py,sha256=bjLpugyxTB3h6Ir-D5eHilYmKGhx1sa4r8K_ZXiqaO8,44717
 src/config.py,sha256=_zSMnGSO8uFFF8Was_Jtm2m1JDPGhT3Lh8Zz2rcQs98,3232
 src/db.py,sha256=BKrlhilXYHNaj-ZcffinSXVhdUqowmwpFPBx7aLxamU,4642
 src/mcp_server.py,sha256=Tx0i73GXO0YmcVrdO7UjRMS0auN8fBG2LOpHuf_LUC0,20374
 src/memory.py,sha256=POT2lYeBcEx4_MPbsIdet6ScwcjmuETz8Dxmz-Z_7IY,11939
 src/commands/audit.md,sha256=Xkucm-gfBIMalK9wf7NBbyejpsqBTUAGGlb7GxMtMPY,5137
 src/commands/handoff.md,sha256=8VxTddtW08jGTW36GW_rS77JdeSn8vHeMfklrWwVUD4,5055
+src/commands/import-docs.md,sha256=ByIdcfbdiF77HoFv5U6zZ_YvZf00-hAs9EMconXssvY,6927
 src/commands/pr-graduate.md,sha256=TdqcIwtemrvLbbbUw-mY7hvixjOSh8H_L-63_QsAtpI,6455
 src/commands/recall.md,sha256=unQPWsmocKRoQR7jRtjrj8aVcMHverjGR6u5mYL8TLw,6008
 src/commands/remember.md,sha256=nNewsUhIqF4wtD1jhVDZvmLZjdcmPN6NmUM43SdWepc,5368
@@ -14,8 +15,8 @@ src/commands/save.md,sha256=7gTpW46AU9Y4l8XVZ8f4h1sEdBfVqIRA7hlidUxMAC4,251
 src/commands/start.md,sha256=qoqhkMgET74DBx8YPIT1-wqCiVBUDxlmevigsCinHSY,6506
 src/indexers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 src/indexers/docs.py,sha256=7FENHaKSvC1T557bRzvmrjyaG_vK94GuQG9XMZdr89w,3349
-ragtime_cli-0.2.1.dist-info/METADATA,sha256=Cg_bRuQ87B6OuOLhQ4TBQ_uUMQS7dGBL_Q-ZtkjI3JY,5311
-ragtime_cli-0.2.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-ragtime_cli-0.2.1.dist-info/entry_points.txt,sha256=cWLbeyMxZNbew-THS3bHXTpCRXt1EaUy5QUOXGXLjl4,75
-ragtime_cli-0.2.1.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
-ragtime_cli-0.2.1.dist-info/RECORD,,
+ragtime_cli-0.2.2.dist-info/METADATA,sha256=TqC9Yyq8QFFSxwXnJaRAMxnW3PttYEyoGkRhowwouLo,5311
+ragtime_cli-0.2.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ragtime_cli-0.2.2.dist-info/entry_points.txt,sha256=cWLbeyMxZNbew-THS3bHXTpCRXt1EaUy5QUOXGXLjl4,75
+ragtime_cli-0.2.2.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
+ragtime_cli-0.2.2.dist-info/RECORD,,

src/cli.py

@@ -166,7 +166,7 @@ def get_remote_branches_with_ragtime(path: Path) -> list[str]:
 
 
 @click.group()
-@click.version_option(version="0.2.1")
+@click.version_option(version="0.2.2")
 def main():
     """Ragtime - semantic search over code and documentation."""
     pass
@@ -1105,6 +1105,193 @@ def daemon_status(path: Path):
         pid_file.unlink()
 
 
+@main.command()
+@click.argument("docs_path", type=click.Path(exists=True, path_type=Path), default="docs")
+@click.option("--path", type=click.Path(exists=True, path_type=Path), default=".")
+@click.option("--fix", is_flag=True, help="Interactively add frontmatter to files")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def audit(docs_path: Path, path: Path, fix: bool, as_json: bool):
+    """Audit docs for ragtime-compatible frontmatter.
+
+    Scans markdown files and suggests metadata for better indexing.
+
+    Examples:
+        ragtime audit docs/              # Audit docs folder
+        ragtime audit docs/ --fix        # Interactively add frontmatter
+        ragtime audit . --json           # Output suggestions as JSON
+    """
+    import re
+    import json as json_module
+
+    path = Path(path).resolve()
+    docs_path = Path(docs_path).resolve()
+
+    if not docs_path.exists():
+        click.echo(f"✗ Path not found: {docs_path}", err=True)
+        return
+
+    # Find all markdown files
+    md_files = list(docs_path.rglob("*.md"))
+
+    if not md_files:
+        click.echo(f"No markdown files found in {docs_path}")
+        return
+
+    results = []
+
+    for md_file in md_files:
+        content = md_file.read_text()
+        relative = md_file.relative_to(path) if md_file.is_relative_to(path) else md_file
+
+        # Check for existing frontmatter
+        has_frontmatter = content.startswith("---")
+        existing_meta = {}
+
+        if has_frontmatter:
+            try:
+                import yaml
+                parts = content.split("---", 2)
+                if len(parts) >= 3:
+                    existing_meta = yaml.safe_load(parts[1]) or {}
+            except:
+                pass
+
+        # Analyze file for suggestions
+        suggestions = analyze_doc_for_metadata(md_file, content, existing_meta)
+
+        status = "ok" if not suggestions["missing"] else "needs_update"
+        if not has_frontmatter:
+            status = "no_frontmatter"
+
+        results.append({
+            "file": str(relative),
+            "status": status,
+            "has_frontmatter": has_frontmatter,
+            "existing": existing_meta,
+            "suggestions": suggestions,
+        })
+
+    if as_json:
+        click.echo(json_module.dumps(results, indent=2))
+        return
+
+    # Summary
+    no_fm = [r for r in results if r["status"] == "no_frontmatter"]
+    needs_update = [r for r in results if r["status"] == "needs_update"]
+    ok = [r for r in results if r["status"] == "ok"]
+
+    click.echo(f"\nAudited {len(md_files)} files in {docs_path.name}/\n")
+
+    if ok:
+        click.echo(f"✓ {len(ok)} files have complete frontmatter")
+
+    if needs_update:
+        click.echo(f"• {len(needs_update)} files could use more metadata")
+
+    if no_fm:
+        click.echo(f"✗ {len(no_fm)} files have no frontmatter\n")
+
+        for r in no_fm[:10]:  # Show first 10
+            click.echo(f"{'─' * 60}")
+            click.echo(f"  {r['file']}")
+            s = r["suggestions"]
+            click.echo(f"  Suggested frontmatter:")
+            click.echo(f"    namespace: {s.get('namespace', 'app')}")
+            click.echo(f"    type: {s.get('type', 'document')}")
+            if s.get("component"):
+                click.echo(f"    component: {s['component']}")
+
+        if len(no_fm) > 10:
+            click.echo(f"\n  ... and {len(no_fm) - 10} more files")
+
+    if fix and no_fm:
+        click.echo(f"\n{'─' * 60}")
+        if click.confirm(f"\nAdd frontmatter to {len(no_fm)} files?"):
+            added = 0
+            for r in no_fm:
+                file_path = path / r["file"]
+                content = file_path.read_text()
+                s = r["suggestions"]
+
+                # Build frontmatter
+                fm_lines = ["---"]
+                fm_lines.append(f"namespace: {s.get('namespace', 'app')}")
+                fm_lines.append(f"type: {s.get('type', 'document')}")
+                if s.get("component"):
+                    fm_lines.append(f"component: {s['component']}")
+                fm_lines.append("---")
+                fm_lines.append("")
+
+                new_content = "\n".join(fm_lines) + content
+                file_path.write_text(new_content)
+                added += 1
+                click.echo(f"  ✓ {r['file']}")
+
+            click.echo(f"\n✓ Added frontmatter to {added} files")
+            click.echo(f"  Run 'ragtime reindex' to update the search index")
+
+
+def analyze_doc_for_metadata(file_path: Path, content: str, existing: dict) -> dict:
+    """Analyze a document and suggest metadata."""
+    import re
+
+    suggestions = {}
+    missing = []
+
+    # Infer from path
+    parts = file_path.parts
+    path_lower = str(file_path).lower()
+
+    # Namespace inference
+    if "namespace" not in existing:
+        missing.append("namespace")
+        if ".ragtime" in path_lower or "memory" in path_lower:
+            suggestions["namespace"] = "app"
+        elif "team" in path_lower or "convention" in path_lower:
+            suggestions["namespace"] = "team"
+        else:
+            suggestions["namespace"] = "app"
+
+    # Type inference
+    if "type" not in existing:
+        missing.append("type")
+
+        # Check content for clues
+        content_lower = content.lower()
+
+        if "api" in path_lower or "endpoint" in content_lower:
+            suggestions["type"] = "architecture"
+        elif "decision" in path_lower or "adr" in path_lower or "we decided" in content_lower:
+            suggestions["type"] = "decision"
+        elif "guide" in path_lower or "how to" in content_lower:
+            suggestions["type"] = "pattern"
+        elif "setup" in path_lower or "install" in path_lower:
+            suggestions["type"] = "convention"
+        elif "readme" in path_lower:
+            suggestions["type"] = "document"
+        elif "changelog" in path_lower or "release" in path_lower:
+            suggestions["type"] = "document"
+        else:
+            suggestions["type"] = "document"
+
+    # Component inference from path
+    if "component" not in existing:
+        # Look for component-like folder names
+        component_candidates = []
+        skip = {"docs", "src", "lib", "app", "pages", "components", "memory", ".ragtime"}
+
+        for part in parts[:-1]:  # Exclude filename
+            if part.lower() not in skip and not part.startswith("."):
+                component_candidates.append(part.lower())
+
+        if component_candidates:
+            suggestions["component"] = component_candidates[-1]  # Most specific
+            missing.append("component")
+
+    suggestions["missing"] = missing
+    return suggestions
+
+
 @main.command()
 @click.option("--check", is_flag=True, help="Only check for updates, don't install")
 def update(check: bool):
@@ -1113,7 +1300,7 @@ def update(check: bool):
     from urllib.request import urlopen
     from urllib.error import URLError
 
-    current = "0.2.1"
+    current = "0.2.2"
 
     click.echo(f"Current version: {current}")
     click.echo("Checking PyPI for updates...")

src/commands/import-docs.md

@@ -0,0 +1,259 @@
+---
+description: Migrate existing docs into ragtime memory structure with AI-assisted classification
+allowed-arguments: path to docs folder (e.g., /import-docs docs/)
+allowed-tools: Bash, Read, Write, Edit, AskUserQuestion
+---
+
+# Import Docs
+
+Analyze an existing docs folder and migrate content into the ragtime memory structure.
+
+**Usage:**
+- `/import-docs docs/` - Analyze docs folder and create memories
+- `/import-docs` - Interactive mode, asks for path
+
+## Overview
+
+This command helps teams that have existing documentation migrate into ragtime's structured memory system. It:
+
+1. Scans all markdown files using `ragtime audit --json`
+2. Analyzes each document's content to classify properly
+3. Determines what should become memories vs. stay as indexed docs
+4. Creates memories in `.ragtime/app/` or `.ragtime/team/` as appropriate
+
+## Step 1: Get the Docs Path
+
+**If `$ARGUMENTS` provided:**
+- Use it as the docs path
+
+**If no arguments:**
+- Ask: "What docs folder should I analyze? (e.g., docs/, documentation/)"
+
+## Step 2: Run Audit
+
+Run the ragtime audit command to get a structured view of all docs:
+
+```bash
+ragtime audit {docs_path} --json
+```
+
+Parse the JSON output to get the list of files and initial suggestions.
+
+## Step 3: Analyze Documents
+
+For each document (or batch), read the content and classify:
+
+### Classification Questions
+
+For each doc, determine:
+
+1. **Is this memory-worthy or just reference?**
+   - Memory-worthy: Contains decisions, patterns, architecture insights, conventions
+   - Reference: API docs, changelogs, auto-generated content, raw specs
+
+2. **What type of knowledge is it?**
+   - `architecture` - How systems/components work
+   - `decision` - Why we chose X over Y (look for "we decided", "because", trade-off discussion)
+   - `convention` - Team rules, coding standards, process docs
+   - `pattern` - Reusable solutions, "how to do X"
+   - `integration` - How external services connect
+   - `feature` - Feature documentation
+
+3. **What namespace?**
+   - `app` - Technical knowledge about this codebase
+   - `team` - Team conventions, process, standards
+
+4. **What component?** (infer from path and content)
+
+5. **Should this doc be split?**
+   - Large docs with multiple distinct sections may become multiple memories
+   - Each memory should be focused on ONE concept
+
+### Classification Hints
+
+Look for signals in the content:
+
+| Signal | Likely Type |
+|--------|-------------|
+| "We decided to..." | decision |
+| "Always do X when Y" | convention |
+| "The {system} works by..." | architecture |
+| "To implement X, follow these steps..." | pattern |
+| "Integrates with {service} via..." | integration |
+| ADR format, numbered decisions | decision |
+| API endpoints, request/response | architecture |
+| Setup instructions, onboarding | convention |
+
+## Step 4: Choose Migration Strategy
+
+Ask the user:
+
+```
+How should I handle the original docs?
+
+1. **Memories only** - Create memories in .ragtime/, leave original docs unchanged
+2. **Frontmatter only** - Add frontmatter to original docs for better indexing, no memories
+3. **Both** - Add frontmatter to originals AND create memories for key insights (recommended)
+```
+
+Based on their choice, adjust what the migration plan includes.
+
+## Step 5: Generate Migration Plan
+
+Create a migration plan based on the user's strategy choice:
+
+```
+## Migration Plan
+
+### Will Add Frontmatter (if strategy includes frontmatter)
+
+| File | Namespace | Type | Component |
+|------|-----------|------|-----------|
+| docs/auth/JWT_DESIGN.md | app | architecture | auth |
+| docs/CODING_STANDARDS.md | team | convention | - |
+| ... | | | |
+
+### Will Create Memories (if strategy includes memories)
+
+| File | Type | Namespace | Component | Notes |
+|------|------|-----------|-----------|-------|
+| docs/auth/JWT_DESIGN.md | architecture | app | auth | Split into 2 memories |
+| docs/CODING_STANDARDS.md | convention | team | - | Full doc |
+| ... | | | | |
+
+### Will Index Only (no memory, just frontmatter or skip)
+
+These stay as searchable docs but don't become memories:
+- docs/CHANGELOG.md (reference)
+- docs/api/endpoints.md (reference, auto-generated)
+- ...
+
+### Will Skip (Z files)
+
+- docs/archive/old-stuff.md (outdated)
+- ...
+```
+
+## Step 6: Get Approval
+
+Present the plan and ask:
+
+```
+I've analyzed {total} docs:
+- {X} will become memories in .ragtime/
+- {Y} will be indexed as reference docs
+- {Z} will be skipped
+
+Review the plan above. Should I:
+1. Proceed with all
+2. Let me adjust some classifications
+3. Show me a specific file's analysis
+4. Cancel
+```
+
+## Step 7: Execute Migration
+
+### If adding frontmatter to originals:
+
+For each doc that needs frontmatter, prepend:
+
+```yaml
+---
+namespace: {app|team}
+type: {type}
+component: {if applicable}
+---
+```
+
+This makes the original docs index better with `ragtime index`.
+
+### If creating memories:
+
+1. **Extract the key content** - Don't copy the whole doc verbatim unless it's focused. Extract the essential knowledge.
+
+2. **Write the memory file** to `.ragtime/app/{component}/{id}-{slug}.md` or `.ragtime/team/{id}-{slug}.md`:
+
+```yaml
+---
+id: {8-char-uuid}
+namespace: {app|team}
+type: {type}
+component: {if applicable}
+confidence: medium
+confidence_reason: import-docs
+source: import-docs
+status: active
+added: {today}
+migrated_from: {original-file-path}
+---
+
+{extracted content}
+```
+
+3. **For split documents**, create multiple focused memories with related IDs.
+
+## Step 8: Reindex
+
+After all memories are created:
+
+```bash
+ragtime reindex
+```
+
+## Step 9: Summary
+
+Summarize based on what was done:
+
+```
+## Migration Complete
+
+### Frontmatter Added (if applicable)
+Updated {X} docs with frontmatter for better indexing.
+
+### Memories Created (if applicable)
+Created {Y} memories:
+- {N} architecture in app/
+- {N} conventions in team/
+- {N} decisions in app/
+- ...
+
+Next steps:
+- Run 'ragtime index' to update the search index
+- Review memories with: ragtime memories --namespace app
+- Search with: ragtime search "your query"
+- Edit any misclassified content in .ragtime/ or docs/
+```
+
+## Tips
+
+- **Don't over-migrate**: Not every doc needs to be a memory. Reference docs are fine as indexed content.
+- **Preserve originals**: This creates memories FROM docs, doesn't delete originals.
+- **Review component inference**: The path-based component detection may need adjustment.
+- **Batch by folder**: For large doc sets, consider migrating one folder at a time.
+
+## Example Session
+
+```
+User: /import-docs docs/
+
+Claude: I'll analyze your docs folder...
+
+Running: ragtime audit docs/ --json
+
+Found 45 markdown files. Let me analyze each one...
+
+[Analyzes docs/auth/JWT_DESIGN.md]
+This is an architecture doc about JWT implementation. Key insights:
+- 15-minute access token expiry
+- Refresh token rotation strategy
+- Why we chose asymmetric keys
+
+I'll create 1 memory in app/auth/ for this.
+
+[Continues for other files...]
+
+## Migration Plan
+...
+
+Proceed? (yes/adjust/cancel)
+```