repodoc-local 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/README.md +128 -2
  2. package/dist/agent-loop.d.ts +21 -0
  3. package/dist/agent-loop.d.ts.map +1 -0
  4. package/dist/agent-loop.js +549 -0
  5. package/dist/agent-loop.js.map +1 -0
  6. package/dist/cli.d.ts +3 -0
  7. package/dist/cli.d.ts.map +1 -0
  8. package/dist/cli.js +337 -0
  9. package/dist/cli.js.map +1 -0
  10. package/dist/file-walker.d.ts +30 -0
  11. package/dist/file-walker.d.ts.map +1 -0
  12. package/dist/file-walker.js +164 -0
  13. package/dist/file-walker.js.map +1 -0
  14. package/dist/followup.d.ts +25 -0
  15. package/dist/followup.d.ts.map +1 -0
  16. package/dist/followup.js +185 -0
  17. package/dist/followup.js.map +1 -0
  18. package/dist/guardrails.d.ts +28 -0
  19. package/dist/guardrails.d.ts.map +1 -0
  20. package/dist/guardrails.js +241 -0
  21. package/dist/guardrails.js.map +1 -0
  22. package/dist/hardware-detector.d.ts +6 -0
  23. package/dist/hardware-detector.d.ts.map +1 -0
  24. package/dist/hardware-detector.js +121 -0
  25. package/dist/hardware-detector.js.map +1 -0
  26. package/dist/local-llm.d.ts +49 -0
  27. package/dist/local-llm.d.ts.map +1 -0
  28. package/dist/local-llm.js +173 -0
  29. package/dist/local-llm.js.map +1 -0
  30. package/dist/model-manager.d.ts +9 -0
  31. package/dist/model-manager.d.ts.map +1 -0
  32. package/dist/model-manager.js +97 -0
  33. package/dist/model-manager.js.map +1 -0
  34. package/dist/persistence.d.ts +17 -0
  35. package/dist/persistence.d.ts.map +1 -0
  36. package/dist/persistence.js +88 -0
  37. package/dist/persistence.js.map +1 -0
  38. package/dist/secret-redactor.d.ts +19 -0
  39. package/dist/secret-redactor.d.ts.map +1 -0
  40. package/dist/secret-redactor.js +92 -0
  41. package/dist/secret-redactor.js.map +1 -0
  42. package/dist/security/audit.d.ts +15 -0
  43. package/dist/security/audit.d.ts.map +1 -0
  44. package/dist/security/audit.js +200 -0
  45. package/dist/security/audit.js.map +1 -0
  46. package/dist/types.d.ts +97 -0
  47. package/dist/types.d.ts.map +1 -0
  48. package/dist/types.js +6 -0
  49. package/dist/types.js.map +1 -0
  50. package/package.json +63 -4
  51. package/prompts/analyze-e2b.txt +28 -0
  52. package/prompts/analyze-e4b.txt +31 -0
  53. package/repodoc.example.yml +27 -0
package/README.md CHANGED
@@ -1,3 +1,129 @@
1
- # Temporary Holding Version
1
+ # repodoc-local
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > **Local-first AI bug fixer and guardrails. Code never leaves your machine. Powered by Gemma 4.**
4
+
5
+ [![npm version](https://img.shields.io/npm/v/repodoc-local.svg)](https://www.npmjs.com/package/repodoc-local)
6
+ [![Node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8
+
9
+ ---
10
+
11
+ > [!WARNING]
12
+ > **Alpha Notice**: `repodoc-local` is currently in active alpha. It requires a local [Ollama](https://ollama.com) instance running on your machine to perform local model inference.
13
+
14
+ ---
15
+
16
+ ## What It Does
17
+
18
+ `repodoc-local` scans your codebase locally, executes zero-egress security guardrails, detects bugs with local Gemma 4 models, generates unified diff patches with AI-grounded explanations, and lets you ask follow-up questions or chat with the analysis context — completely offline.
19
+
20
+ - **Grounded Bug Detection**: Analyzes files one by one against static guardrail findings. Never invents nonexistent files or hallucinated lines.
21
+ - **AI-Generated Explanations**: Every patch includes structured rationale: `rule_id`, `what`, `why`, and `risk` assessment (level + double-check tips).
22
+ - **Interactive Follow-ups**: Query and chat against analysis runs using local conversational context.
23
+ - **Strict Local Privacy**: Zero external telemetry, zero cloud calls. All models run on your own hardware via Ollama.
24
+
25
+ ---
26
+
27
+ ## Prerequisites
28
+
29
+ 1. **Node.js**: `>=18.0.0`
30
+ 2. **Ollama**: Installed and running locally ([Download Ollama](https://ollama.com/download))
31
+ 3. **Gemma 4 model**: Pulled via `repodoc model pull` or `ollama pull gemma4:e4b`
32
+
33
+ | Tier | Ollama Tag | Download Size | Required RAM | Target Hardware |
34
+ |------|------------|---------------|--------------|-----------------|
35
+ | `gemma-4-e4b` | `gemma4:e4b` | ~2.8 GB | ~5.5 GB | Recommended (8GB+ RAM) |
36
+ | `gemma-4-e2b` | `gemma4:e2b` | ~1.4 GB | ~3.0 GB | Lightweight (<8GB RAM) |
37
+
38
+ ---
39
+
40
+ ## Installation & Quick Start
41
+
42
+ ```bash
43
+ # Global install via npm
44
+ npm install -g repodoc-local
45
+
46
+ # Check system hardware & recommended model
47
+ repodoc --check-hardware
48
+
49
+ # Download local model
50
+ repodoc model pull
51
+
52
+ # Run analysis on the current repository
53
+ repodoc .
54
+ ```
55
+
56
+ You can also run directly with `npx`:
57
+
58
+ ```bash
59
+ npx repodoc-local .
60
+ ```
61
+
62
+ ---
63
+
64
+ ## Commands
65
+
66
+ ### `repodoc [path] [options]`
67
+ Analyzes a repository at `[path]` (defaults to `.`):
68
+
69
+ ```bash
70
+ # Analyze repository and output human-readable report
71
+ repodoc .
72
+
73
+ # Auto-apply verified patches
74
+ repodoc . --apply
75
+
76
+ # Output structured JSON (CI / automation)
77
+ repodoc . --json
78
+
79
+ # Run completely offline (skips LLM if model not local, runs static guardrails)
80
+ repodoc . --offline
81
+
82
+ # Debug mode (prints prompt tokens, raw model output, done_reason)
83
+ repodoc . --debug
84
+ ```
85
+
86
+ ### `repodoc ask "<question>"`
87
+ Ask natural language questions grounded in the latest analysis run (or specify `--run <id>`):
88
+
89
+ ```bash
90
+ repodoc ask "Why was the no_eval patch recommended in auth.js?"
91
+ repodoc ask "Summarize all high-risk changes" --run run-1795225539813
92
+ ```
93
+
94
+ ### `repodoc chat`
95
+ Start an interactive terminal chat session grounded in the latest saved run:
96
+
97
+ ```bash
98
+ repodoc chat
99
+ ```
100
+
101
+ ### `repodoc model <subcommand>`
102
+ Manage local Ollama models:
103
+
104
+ ```bash
105
+ repodoc model pull [--model auto|gemma-4-e4b|gemma-4-e2b]
106
+ repodoc model list
107
+ repodoc model rm <tier>
108
+ ```
109
+
110
+ ### `repodoc open-live`
111
+ Opens the hosted live web app [https://repodoc.app](https://repodoc.app) in your default browser.
112
+
113
+ ---
114
+
115
+ ## Privacy Model & Security
116
+
117
+ `repodoc-local` is designed from the ground up for strict privacy and confidentiality:
118
+
119
+ 1. **Zero External Egress**: Code is never sent to any external server or API. All LLM calls connect strictly to your local Ollama daemon (`http://127.0.0.1:11434`).
120
+ 2. **Local Persistence**: Analysis results are persisted strictly inside your project at `.repodoc/runs/<run-id>.json`. Nothing leaves your filesystem.
121
+ 3. **Automatic Secret Redaction**: Before any code context is passed to the local model or written to run files, sensitive strings (AWS keys, GitHub tokens, private keys, passwords, database URIs) are redacted in memory.
122
+ 4. **Offline Flag**: Use `--offline` to ensure no network calls are initiated.
123
+ 5. **No Hallucinations**: Prompt templates strictly ground the LLM to file contents and guardrail findings, preventing fabricated paths or phantom lines.
124
+
125
+ ---
126
+
127
+ ## License
128
+
129
+ MIT © repoDoc contributors
@@ -0,0 +1,21 @@
1
+ import { LocalLLM } from "./local-llm.js";
2
+ import { AnalysisResult, ModelTier } from "./types.js";
3
+ export interface AgentOptions {
4
+ repoPath: string;
5
+ model: ModelTier;
6
+ apply: boolean;
7
+ runTests: boolean;
8
+ offline: boolean;
9
+ promptFile?: string;
10
+ json: boolean;
11
+ debug?: boolean;
12
+ }
13
+ export interface AgentStep {
14
+ step: "observe" | "decide" | "act" | "verify";
15
+ status: "running" | "done" | "error";
16
+ message: string;
17
+ timestamp: string;
18
+ }
19
+ export type StepCallback = (step: AgentStep) => void;
20
+ export declare function runAgentLoop(llm: LocalLLM, opts: AgentOptions, onStep?: StepCallback): Promise<AnalysisResult>;
21
+ //# sourceMappingURL=agent-loop.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../src/agent-loop.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAI1C,OAAO,EACL,cAAc,EAGd,SAAS,EAGV,MAAM,YAAY,CAAC;AASpB,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC9C,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;AAgNrD,wBAAsB,YAAY,CAChC,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,EAClB,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,cAAc,CAAC,CA6ezB"}