docutrack 0.1.0 → 0.1.6

package/src/viewer/server.test.js

@@ -0,0 +1,50 @@
+'use strict'
+
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+
+const DocuTrackServer = require('./server')
+
+const s = new DocuTrackServer('/fake/root', 4242)
+
+describe('moduleDocName', () => {
+  it('drops leading src/ for shallow files', () => {
+    assert.equal(s.moduleDocName('src/utils.ts'), 'utils')
+  })
+
+  it('uses last 2 segments for deeper paths', () => {
+    assert.equal(s.moduleDocName('app/dashboard/SearchBar.tsx'), 'dashboard-SearchBar')
+  })
+
+  it('handles lib/ prefix', () => {
+    assert.equal(s.moduleDocName('lib/rules-engine.ts'), 'rules-engine')
+  })
+
+  it('handles deeply nested paths', () => {
+    assert.equal(s.moduleDocName('src/components/ui/Button.tsx'), 'ui-Button')
+  })
+})
+
+describe('routeDocName', () => {
+  it('converts simple route', () => {
+    assert.equal(s.routeDocName('app/api/documentos/route.ts'), 'documentos')
+  })
+
+  it('strips dynamic segments brackets', () => {
+    assert.equal(s.routeDocName('app/api/documentos/[id]/evaluar/route.ts'), 'documentos-id-evaluar')
+  })
+
+  it('handles nested api routes', () => {
+    assert.equal(s.routeDocName('app/api/metricas/route.ts'), 'metricas')
+  })
+})
+
+describe('fileToApiPath', () => {
+  it('converts dynamic segments to OpenAPI params', () => {
+    assert.equal(s.fileToApiPath('app/api/documentos/[id]/route.ts'), '/api/documentos/{id}')
+  })
+
+  it('handles simple routes', () => {
+    assert.equal(s.fileToApiPath('app/api/status/route.ts'), '/api/status')
+  })
+})

package/templates/agents/documentalista.md

@@ -9,50 +9,75 @@ You are the **documentalista** — a specialized documentation agent. Your only
 
 When invoked, always follow these steps in order:
 
+**0. Read project preferences**
+```bash
+cat docutrack.config.json
+```
+This tells you how to write docs for this specific project:
+- `lang`: write **all** documentation in this language (e.g. `"es"` = Spanish, `"en"` = English)
+- `projectDescription`: the project's purpose — use it for context when writing module docs
+- `audience`: `"team"` = technical/concise, `"onboarding"` = explain more context for new devs, `"mixed"` = balanced
+- `docDepth`: `"concise"` = summary + public API only, `"standard"` = + design decisions and gotchas, `"detailed"` = + examples and full context
+
+Adapt every doc you write to these preferences. If `lang` is `"es"`, write in Spanish. If `docDepth` is `"concise"`, keep docs short.
+
 **1. Read the queue**
 ```bash
 cat .docutrack/queue.json
 ```
-This shows which files were modified and need documentation.
+This shows which files need documentation.
 
 **2. Understand what changed**
 Read each file in the queue. Understand its purpose, its public API, and how it fits into the system.
 
 **3. Update or create module docs**
-For each file in the queue, update or create `docs/modules/<module-name>.md` using this exact structure:
+For each file in the queue, update or create `docs/modules/<module-name>.md`.
 
+If `docDepth` is `"concise"`:
 ```markdown
 # <Module Name>
 
-**Responsibility**: [one sentence — what this module does]
+**Responsibility**: [one sentence]
 
 ## Public API
+| Export | Type | Description |
+|--------|------|-------------|
+| `name` | function | what it does |
+```
+
+If `docDepth` is `"standard"` (default):
+```markdown
+# <Module Name>
 
+**Responsibility**: [one sentence]
+
+## Public API
 | Export | Type | Description |
 |--------|------|-------------|
-| `functionName` | function | what it does |
+| `name` | function | what it does |
 
 ## Dependencies
-
-- **Imports from**: list of modules/packages this depends on
-- **Used by**: list of modules that import from this one
+- **Imports from**: modules/packages this depends on
+- **Used by**: modules that import this one
 
 ## Data Shapes
-
 ```typescript
 // Key types, interfaces, or schemas
 ```
 
 ## Notes
-
-[Non-obvious constraints, gotchas, or design decisions]
+[Non-obvious constraints, gotchas, design decisions]
 ```
 
+If `docDepth` is `"detailed"`, add a `## Examples` section with a usage snippet for the key exports.
+
+If `audience` is `"onboarding"`, add a brief **Context** paragraph at the top explaining where this module fits in the system — assume the reader is new to the codebase.
+
 **4. Update ARCHITECTURE.md if needed**
-- If a new module was added: add a row to the Module Map table
-- If a new external service was added: add to the Integrations table
-- If a new env variable was added: add to the Environment Variables table
-- If the tech stack changed: update the Tech Stack table
+- New module added → add a row to the Module Map table
+- New external service → add to the Integrations table
+- New env variable → add to the Environment Variables table
+- Tech stack changed → update the Tech Stack table
 
 **5. Create an ADR for significant decisions**
 Create `docs/decisions/ADR-NNN-<slug>.md` when you detect:
@@ -69,18 +94,12 @@ ADR format:
 **Date**: YYYY-MM-DD
 
 ## Context
-Why was this decision needed?
-
 ## Decision
-What was decided?
-
 ## Consequences
-Trade-offs, implications, and things to watch for.
 ```
 
 **6. Update API docs if needed**
 If the modified file defines routes/endpoints, update or create `docs/api/<service>.md`:
-
 ```markdown
 # <Service> API
 
@@ -92,22 +111,22 @@ If the modified file defines routes/endpoints, update or create `docs/api/<servi
 ```
 
 **7. Clear the queue**
-After all documentation is updated, run:
 ```bash
 npx docutrack clear
 ```
 
 ## Quality rules
 
+- Write in the language specified in `docutrack.config.json` — every word
 - Write for the next engineer, not for yourself
-- One responsibility per module doc — if you can't describe it in one sentence, the module does too much
+- One responsibility per module doc
 - Never copy-paste code into docs — describe behavior, not implementation
-- ADRs are permanent records — mark old ones as `Deprecated`, never delete them
-- If you're unsure about something, write what you can observe and add a `> Note: verify this with the team` callout
+- ADRs are permanent — mark old ones as `Deprecated`, never delete
+- If unsure, write what you observe and add `> Note: verify with the team`
 
 ## What you don't do
 
-- You don't write feature code
-- You don't modify source files
-- You don't create tests
-- You don't refactor anything
+- Write feature code
+- Modify source files
+- Create tests
+- Refactor anything

package/templates/claude-snippet.md

@@ -1,39 +1,53 @@
-## Documentation Protocol (DocuTrack)
-
-This project uses DocuTrack to maintain living documentation. After every code change, follow this protocol:
-
-### When you create or modify a module
-
-Update or create `docs/modules/<module-name>.md` with:
-- **Responsibility**: what this module does (one sentence)
-- **Public API**: exported functions/classes with brief descriptions
-- **Dependencies**: what it imports from and what depends on it
-- **Data shapes**: key types, schemas, or interfaces
-- **Notes**: constraints, gotchas, non-obvious design decisions
-
-### When you add or change an API endpoint
-
-Update `docs/api/` — one file per service/router. Document:
-- Method + path
-- Request body / query params
-- Response shape and status codes
-- Auth requirements
-
-### When you make a significant architectural decision
-
-Create `docs/decisions/ADR-<NNN>-<slug>.md`. Use this format:
-```
-# ADR-NNN: Title
-## Status: Proposed | Accepted | Deprecated
-## Context: why this decision was needed
-## Decision: what was decided
-## Consequences: trade-offs and implications
-```
-
-### When you modify `ARCHITECTURE.md`
-
-Keep the Module Map table current. If you add a new service, integration, or env variable, add it to the relevant section.
-
-### The Stop hook will warn you
-
-If you end the session with modified files and no doc update, the Stop hook prints a list of what needs attention. Clear the queue with `npx docutrack clear` only after documentation is updated.
+## DocuTrack — documentation auto-pilot
+
+This project uses DocuTrack for living documentation.
+
+### At the start of every session
+
+Run this check silently (no output to user needed):
+
+```bash
+node -e "const fs=require('fs');if(!fs.existsSync('.docutrack')){console.log('NEEDS_SETUP')}else{try{const q=JSON.parse(fs.readFileSync('.docutrack/queue.json','utf8'));console.log('PENDING:'+(q.pending||[]).length)}catch{console.log('PENDING:0')}}"
+```
+
+Based on the output:
+- **`NEEDS_SETUP`** → ask the user these questions (in the conversation), then run `docutrack init` with the answers as flags:
+  1. *"Documentation language? (e.g. Spanish, English, Portuguese…)"*
+  2. *"Describe this project in one sentence"*
+  3. *"Who reads the docs? → `team` (technical) / `onboarding` (new devs) / `mixed`"*
+  4. *"Documentation depth? → `concise` / `standard` / `detailed`"*
+
+  Then run:
+  ```bash
+  docutrack init --lang=<es|en|…> --description="<desc>" --audience=<team|onboarding|mixed> --depth=<concise|standard|detailed>
+  ```
+- **`PENDING:N`** (N > 0) → run the **documentalista** subagent to process the queue
+- **`PENDING:0`** → documentation is up to date ✓
+
+### The documentalista subagent
+
+The documentalista is at `.claude/agents/documentalista.md`. It reads `.docutrack/queue.json`, writes a doc for every queued file, and clears the queue. To invoke it, say: *"Run the documentalista"* — Claude will delegate to it automatically.
+
+### During the session — documentation protocol
+
+When you create or modify a module, update or create `docs/modules/<name>.md` with:
+- **Responsibility**: what this module does (one sentence)
+- **Public API**: exported functions/classes with brief descriptions
+- **Dependencies**: what it imports and what depends on it
+- **Data shapes**: key types, schemas, interfaces
+- **Notes**: constraints, gotchas, non-obvious design decisions
+
+When you add or change an API endpoint, update `docs/api/` — one file per service/router.
+
+When you make a significant architectural decision, create `docs/decisions/ADR-<NNN>-<slug>.md`:
+```
+# ADR-NNN: Title
+## Status: Proposed | Accepted | Deprecated
+## Context
+## Decision
+## Consequences
+```
+
+### The Stop hook
+
+The Stop hook fires when the session ends. If files are still pending, it will list them and ask you to run the documentalista before closing. This keeps docs in sync with the code automatically.

package/templates/hooks/on-stop.js

@@ -1,7 +1,9 @@
 'use strict'
 
 // Stop hook — fires when the Claude Code session ends
-// Warns if there are files modified without documentation updates
+// 1. Catch-all: queues any source files that the PostToolUse hook missed
+//    (happens when docutrack init ran mid-session, before hooks were active)
+// 2. Reports pending files and asks Claude to run the documentalista
 
 const fs = require('fs')
 const path = require('path')
@@ -17,23 +19,69 @@ try {
   process.exit(0)
 }
 
-if (!queue.pending || queue.pending.length === 0) process.exit(0)
+queue.pending = queue.pending || []
 
+// ── Catch-all scan ─────────────────────────────────────────────
+// Add any source files not yet in the queue (catches files created
+// before the PostToolUse hook was active in this session)
+const SOURCE_DIRS = ['src', 'lib', 'app', 'pkg', 'internal', 'api', 'routes', 'controllers', 'handlers', 'packages']
+const SOURCE_EXTS = new Set(['.js', '.ts', '.mjs', '.cjs', '.jsx', '.tsx', '.py', '.go', '.rs', '.rb', '.java', '.cs', '.cpp', '.c', '.swift', '.kt'])
+const IGNORE_DIRS = new Set(['node_modules', '.next', '.git', 'dist', 'build', '__pycache__', '.docutrack', 'docs', '.worktrees', 'coverage', '.turbo', '.claude'])
+const IGNORE_RE   = [/\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /\.d\.ts$/, /\.min\.js$/]
+
+const queued = new Set(queue.pending.map(e => e.file))
+const now = new Date().toISOString()
+let caught = 0
+
+const walk = (dir, root) => {
+  if (!fs.existsSync(dir)) return
+  let entries
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }) } catch { return }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (!IGNORE_DIRS.has(e.name) && !e.name.startsWith('.')) walk(path.join(dir, e.name), root)
+    } else if (e.isFile() && SOURCE_EXTS.has(path.extname(e.name).toLowerCase())) {
+      if (IGNORE_RE.some(re => re.test(e.name))) continue
+      const rel = path.relative(root, path.join(dir, e.name)).replace(/\\/g, '/')
+      if (!queued.has(rel)) {
+        queue.pending.push({ file: rel, addedAt: now })
+        queued.add(rel)
+        caught++
+      }
+    }
+  }
+}
+
+const root = process.cwd()
+for (const dir of SOURCE_DIRS) walk(path.join(root, dir), root)
+
+if (caught > 0) {
+  try { fs.writeFileSync(QUEUE_PATH, JSON.stringify(queue, null, 2)) } catch { /* ok */ }
+}
+
+// ── Report ─────────────────────────────────────────────────────
 const count = queue.pending.length
-const files = queue.pending.map(e => `  - ${e.file}`).join('\n')
+if (count === 0) process.exit(0)
+
+const shown = queue.pending.slice(0, 8)
+const files = shown.map(e => `  - ${e.file}`).join('\n')
+const overflow = count > 8 ? `\n  … and ${count - 8} more` : ''
+const caughtNote = caught > 0 ? `\n  (${caught} file(s) added by catch-all scan)\n` : ''
 
 console.log(`
-╔════════════════════════════════════════════════════╗
-║  DocuTrack: ${String(count).padEnd(3)} file(s) need documentation     ║
-╚════════════════════════════════════════════════════╝
+╔══════════════════════════════════════════════════════════╗
+║  DocuTrack — ${String(count).padEnd(3)} file(s) pending documentation       ║
+╚══════════════════════════════════════════════════════════╝
+${caughtNote}
+${files}${overflow}
 
-${files}
+Please run the documentalista subagent to document these
+files before ending the session:
 
-To update the docs, tell the agent:
-  "Update the documentation for the files in .docutrack/queue.json"
+  Task: "Run the documentalista to document all pending files"
 
-To clear the queue manually:
-  npx docutrack clear
+The documentalista reads .docutrack/queue.json, writes a doc
+for each pending file, and clears the queue automatically.
 `)
 
 process.exit(0)

package/templates/hooks/post-tool-use.js

@@ -6,6 +6,9 @@
 const fs = require('fs')
 const path = require('path')
 
+// Only source code files belong in the documentation queue
+const SOURCE_EXTS = new Set(['.js', '.ts', '.mjs', '.cjs', '.jsx', '.tsx', '.py', '.go', '.rs', '.rb', '.java', '.cs', '.cpp', '.c', '.swift', '.kt'])
+
 let raw = ''
 process.stdin.setEncoding('utf8')
 process.stdin.on('data', chunk => { raw += chunk })
@@ -23,7 +26,6 @@ process.stdin.on('end', () => {
 function extractFilePath(event) {
   const { tool_name, tool_input } = event
   if (!tool_input) return null
-
   if (tool_name === 'Write' || tool_name === 'Edit' || tool_name === 'MultiEdit') {
     return tool_input.file_path || null
   }
@@ -32,18 +34,20 @@ function extractFilePath(event) {
 
 function addToQueue(filePath) {
   const normalized = filePath.replace(/\\/g, '/')
-  const ignored = [
-    'docs/', '.docutrack/', '.claude/', 'node_modules/', '.git/',
-  ]
-  if (ignored.some(p => normalized.startsWith(p))) return
+
+  // Filter by extension — only source code files
+  const ext = path.extname(normalized).toLowerCase()
+  if (!SOURCE_EXTS.has(ext)) return
+
+  // Filter by path — works for both relative and absolute paths
+  const IGNORED = ['docs/', '.docutrack/', '.claude/', 'node_modules/', '.git/', 'dist/', 'build/', '.next/', 'coverage/']
+  if (IGNORED.some(seg => normalized.includes('/' + seg) || normalized.startsWith(seg))) return
 
   const queuePath = path.join('.docutrack', 'queue.json')
   if (!fs.existsSync(path.dirname(queuePath))) return // not initialized
 
   let queue = { pending: [], lastClear: null }
-  try {
-    queue = JSON.parse(fs.readFileSync(queuePath, 'utf8'))
-  } catch { /* start fresh */ }
+  try { queue = JSON.parse(fs.readFileSync(queuePath, 'utf8')) } catch { /* start fresh */ }
 
   if (queue.pending.some(e => e.file === normalized)) return