sourcecode 0.19.0__tar.gz → 0.21.0__tar.gz

{sourcecode-0.19.0 → sourcecode-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 0.19.0
+Version: 0.21.0
 Summary: Genera un mapa de contexto estructurado de proyectos de software para agentes IA
 License: MIT
 Requires-Python: >=3.9
@@ -81,7 +81,7 @@ sourcecode --version
 
 ## What It Detects
 
-- Stacks: Node.js, Python, Go, Rust, Java, PHP, Ruby, and Dart.
+- Stacks: Node.js, Python, Go, Rust, Java (Maven `pom.xml` and Gradle `build.gradle`/`build.gradle.kts`), PHP, Ruby, and Dart.
 - Frameworks associated with each stack when enough signals are present.
 - `project_type`: `webapp`, `api`, `library`, `cli`, `fullstack`, `monorepo`, or `unknown`.
 - Relevant `entry_points`, such as `main.py`, `cmd/api/main.go`, or `app/page.tsx`.
@@ -111,6 +111,8 @@ sourcecode --version
 | `--env-map` | off | Map all environment variables referenced in source code: key name, required/optional status, inferred type (`string`, `int`, `bool`, `url`, `path`, `enum`), functional category (`database`, `auth`, `cache`, `storage`, `service`, `observability`, `feature_flag`, `server`, `general`), default value when present, and source file locations. Supplements with descriptions from `.env.example`, `.env.sample`, and similar reference files. |
 | `--code-notes` | off | Extract inline code annotations — `TODO`, `FIXME`, `HACK`, `NOTE`, `DEPRECATED`, `WARNING`, `XXX`, `BUG`, `OPTIMIZE` — with file path, line number, annotation text, and the nearest enclosing function or class. Also detects Architecture Decision Records (ADRs) in `docs/decisions/`, `docs/adr/`, `adr/`, and similar directories, extracting title, status, and summary. |
 | `--depth INTEGER` | `4` | Maximum file tree depth. Range: 1–20. |
+| `--no-tree` | off | Suppress `file_tree`, `file_paths` (and `file_tree_depth1` in `--compact`) from the output. Ideal with `--dependencies` on large projects to get dependency data without a multi-thousand-line file tree. |
+| `--agent` | off | Agent mode: auto-selects `--compact --dependencies --env-map --code-notes` and adds `--no-tree` automatically for Java/Gradle projects or large repositories. Prints selected flags to stderr. Can be combined with other flags (e.g. `--agent --git-context`). |
 | `--no-redact` | off | Disable secret redaction (enabled by default). |
 | `--version` | — | Show version and exit. |
 
@@ -123,8 +125,8 @@ The full schema (`SourceMap`) includes the following fields:
 | Field | Type | Description |
 |-------|------|-------------|
 | `metadata` | object | Schema version, timestamp, `sourcecode` version, and analyzed path. |
-| `file_tree` | object | Repository tree where `null` represents a file and `{}` represents a directory. |
-| `file_paths` | array | Flat list of all project paths derived from `file_tree`, with forward-slash separators. Always present; respects `--depth`. |
+| `file_tree` | object | Repository tree where `null` represents a file and `{}` represents a directory. Suppressed when `--no-tree` is active. |
+| `file_paths` | array | Flat list of all project paths derived from `file_tree`, with forward-slash separators. Respects `--depth`. Suppressed when `--no-tree` is active. |
 | `project_summary` | string\|null | Deterministic natural-language description of the project. Includes: manifest/README description when available, detected architecture pattern (`layered`, `mvc`, `hexagonal`, `fullstack`), business domain names inferred from directory structure, entry points (when no domains are detected), and dependency count. Present when stacks are detected. |
 | `architecture_summary` | string\|null | Static summary of the main execution flow, orchestrated modules, and output produced by the project. Present when enough structural evidence is available. |
 | `stacks` | array | Stack detections with confidence, frameworks, manifests, `primary`, `root`, `workspace`, and `signals`. |
@@ -223,7 +225,7 @@ ADR detection looks for Markdown files in `docs/decisions/`, `docs/adr/`, `adr/`
 
 ## Compact Mode
 
-`--compact` returns a reduced JSON view optimized for LLM prompts (~500-700 tokens). It excludes the full `dependencies` list, `docs`, and `module_graph`, while retaining the fields most useful for project orientation. When optional flags are also active, their summaries are included: `dependency_summary` (with `--dependencies`), `env_summary` (with `--env-map`), and `code_notes_summary` (with `--code-notes`).
+`--compact` returns a reduced JSON view optimized for LLM prompts. It excludes the full `dependencies` list, `docs`, and `module_graph`, while retaining the fields most useful for project orientation. When optional flags are also active, their summaries are included: `dependency_summary` + `key_dependencies` (with `--dependencies`), `env_summary` (with `--env-map`), and `code_notes_summary` (with `--code-notes`). Adding `--no-tree` further removes `file_tree_depth1`, bringing the output to ~500-800 tokens depending on how many flags are active.
 
 Real output from a Python FastAPI project:
 
@@ -266,7 +268,7 @@ Real output from a Python FastAPI project:
 }
 ```
 
-When `--compact --dependencies` is used, `dependency_summary` is populated instead of `null`.
+When `--compact --dependencies` is used, `dependency_summary` is populated and `key_dependencies` lists the top-15 direct dependencies with resolved versions. Add `--no-tree` to drop `file_tree_depth1` for the smallest possible context footprint.
 
 ## Docs Mode
 
@@ -444,15 +446,27 @@ In a monorepo, each stack includes its own `root` and `workspace`, and one of th
 
 Different modes optimize for different tradeoffs between context size and depth of information.
 
-**`--compact` — minimal context (~500-700 tokens)**
+**`--agent` — zero-config mode for AI pipelines**
+
+Best for: running `sourcecode` from inside an agent without knowing the project in advance. Auto-selects the right flag combination based on detected stack and project size.
+
+```bash
+sourcecode --agent .
+sourcecode --agent --git-context .   # add git context on top of auto-selected flags
+```
+
+On a Java/Gradle project the output is: `--compact --dependencies --env-map --code-notes --no-tree` (~800 tokens). On a Node/Python project: same without `--no-tree` (~900 tokens including depth-1 tree). Selected flags are always printed to stderr so the agent can log them.
+
+**`--compact` — minimal context**
 
 Best for: initial orientation, deciding what to explore next, fast handoffs between agents.
 
-Includes: `project_summary` (instant project description), `architecture_summary` (execution-oriented static summary), `stacks`, `entry_points`, `file_tree_depth1`, and `dependency_summary` when `--dependencies` was also requested.
+Includes: `project_summary`, `architecture_summary`, `stacks`, `entry_points`, `file_tree_depth1`, and — when the respective flags are active — `dependency_summary` + `key_dependencies`, `env_summary`, `code_notes_summary`.
 
 ```bash
 sourcecode --compact .
-sourcecode --compact --dependencies .
+sourcecode --compact --dependencies .           # + key dependencies with versions
+sourcecode --compact --dependencies --no-tree . # smallest footprint: no file tree
 ```
 
 **Full output — deep analysis**
@@ -622,6 +636,75 @@ Combine flags for a comprehensive project handoff:
 sourcecode --compact --env-map --code-notes --git-context .
 ```
 
+## `prepare-context` — Task-aware context for LLMs
+
+`prepare-context` is a subcommand that builds a focused, task-specific context optimized for LLM reasoning. Instead of a full project dump, it returns only the data an LLM needs for a specific goal.
+
+> **Note:** Because `sourcecode` has a positional `PATH` argument, you must provide it explicitly before the subcommand:
+> ```bash
+> sourcecode . prepare-context <task>         # current directory
+> sourcecode /my/project prepare-context <task>
+> ```
+
+### Available tasks
+
+| Task | Goal | Output |
+|------|------|--------|
+| `explain` | Onboard an LLM to the project | `project_summary`, `architecture_summary`, `relevant_files`, `key_dependencies` |
+| `fix-bug` | Identify likely bug locations | `relevant_files` (ranked by risk), `suspected_areas`, `code_notes_summary` |
+| `refactor` | Surface improvement opportunities | `relevant_files`, `improvement_opportunities`, `architecture_summary` |
+| `generate-tests` | Find untested areas | `test_gaps`, `relevant_files` (source without tests), `key_dependencies` |
+
+### Usage
+
+```bash
+# List tasks with descriptions
+sourcecode . prepare-context --task-help
+
+# Explain the project
+sourcecode . prepare-context explain
+
+# Find bug areas, with a ready-to-paste LLM prompt
+sourcecode . prepare-context fix-bug --llm-prompt
+
+# Find untested files in a specific project
+sourcecode . prepare-context generate-tests --path /my/project
+
+# Preview what will be analyzed (no analysis run)
+sourcecode . prepare-context refactor --dry-run
+```
+
+### Output format
+
+```json
+{
+  "task": "fix-bug",
+  "goal": "Identify the most likely files and areas where a bug may be located.",
+  "project_summary": "CLI en Python (Typer). Entry points: src/cli.py. 4 dependencias.",
+  "architecture_summary": null,
+  "relevant_files": [
+    { "path": "src/handler.py", "role": "source", "score": 2.0, "reason": "matches 'handler'" },
+    { "path": "src/cli.py",     "role": "entrypoint", "score": 3.0, "reason": "entry point" }
+  ],
+  "suspected_areas": ["src/handler.py (2 annotations)", "src/parser.py (1 annotation)"],
+  "code_notes_summary": { "total": 5, "by_kind": { "FIXME": 3, "BUG": 2 }, "top_files": ["src/handler.py"] }
+}
+```
+
+### `--llm-prompt`
+
+Add `--llm-prompt` to include a ready-to-use prompt that you can paste directly into any LLM:
+
+```bash
+sourcecode . prepare-context explain --llm-prompt | jq -r '.llm_prompt'
+```
+
+The prompt is task-specific and includes the project context, relevant files, and concrete instructions for the LLM.
+
+### Task auto-selection with `--agent`
+
+For zero-config usage, `--agent` on the main command automatically selects the right flags for the project type. For task-aware context, use `prepare-context` explicitly with the task that matches your goal.
+
 ## Development
 
 Editable install with development dependencies:

{sourcecode-0.19.0 → sourcecode-0.21.0}/README.md

@@ -65,7 +65,7 @@ sourcecode --version
 
 ## What It Detects
 
-- Stacks: Node.js, Python, Go, Rust, Java, PHP, Ruby, and Dart.
+- Stacks: Node.js, Python, Go, Rust, Java (Maven `pom.xml` and Gradle `build.gradle`/`build.gradle.kts`), PHP, Ruby, and Dart.
 - Frameworks associated with each stack when enough signals are present.
 - `project_type`: `webapp`, `api`, `library`, `cli`, `fullstack`, `monorepo`, or `unknown`.
 - Relevant `entry_points`, such as `main.py`, `cmd/api/main.go`, or `app/page.tsx`.
@@ -95,6 +95,8 @@ sourcecode --version
 | `--env-map` | off | Map all environment variables referenced in source code: key name, required/optional status, inferred type (`string`, `int`, `bool`, `url`, `path`, `enum`), functional category (`database`, `auth`, `cache`, `storage`, `service`, `observability`, `feature_flag`, `server`, `general`), default value when present, and source file locations. Supplements with descriptions from `.env.example`, `.env.sample`, and similar reference files. |
 | `--code-notes` | off | Extract inline code annotations — `TODO`, `FIXME`, `HACK`, `NOTE`, `DEPRECATED`, `WARNING`, `XXX`, `BUG`, `OPTIMIZE` — with file path, line number, annotation text, and the nearest enclosing function or class. Also detects Architecture Decision Records (ADRs) in `docs/decisions/`, `docs/adr/`, `adr/`, and similar directories, extracting title, status, and summary. |
 | `--depth INTEGER` | `4` | Maximum file tree depth. Range: 1–20. |
+| `--no-tree` | off | Suppress `file_tree`, `file_paths` (and `file_tree_depth1` in `--compact`) from the output. Ideal with `--dependencies` on large projects to get dependency data without a multi-thousand-line file tree. |
+| `--agent` | off | Agent mode: auto-selects `--compact --dependencies --env-map --code-notes` and adds `--no-tree` automatically for Java/Gradle projects or large repositories. Prints selected flags to stderr. Can be combined with other flags (e.g. `--agent --git-context`). |
 | `--no-redact` | off | Disable secret redaction (enabled by default). |
 | `--version` | — | Show version and exit. |
 
@@ -107,8 +109,8 @@ The full schema (`SourceMap`) includes the following fields:
 | Field | Type | Description |
 |-------|------|-------------|
 | `metadata` | object | Schema version, timestamp, `sourcecode` version, and analyzed path. |
-| `file_tree` | object | Repository tree where `null` represents a file and `{}` represents a directory. |
-| `file_paths` | array | Flat list of all project paths derived from `file_tree`, with forward-slash separators. Always present; respects `--depth`. |
+| `file_tree` | object | Repository tree where `null` represents a file and `{}` represents a directory. Suppressed when `--no-tree` is active. |
+| `file_paths` | array | Flat list of all project paths derived from `file_tree`, with forward-slash separators. Respects `--depth`. Suppressed when `--no-tree` is active. |
 | `project_summary` | string\|null | Deterministic natural-language description of the project. Includes: manifest/README description when available, detected architecture pattern (`layered`, `mvc`, `hexagonal`, `fullstack`), business domain names inferred from directory structure, entry points (when no domains are detected), and dependency count. Present when stacks are detected. |
 | `architecture_summary` | string\|null | Static summary of the main execution flow, orchestrated modules, and output produced by the project. Present when enough structural evidence is available. |
 | `stacks` | array | Stack detections with confidence, frameworks, manifests, `primary`, `root`, `workspace`, and `signals`. |
@@ -207,7 +209,7 @@ ADR detection looks for Markdown files in `docs/decisions/`, `docs/adr/`, `adr/`
 
 ## Compact Mode
 
-`--compact` returns a reduced JSON view optimized for LLM prompts (~500-700 tokens). It excludes the full `dependencies` list, `docs`, and `module_graph`, while retaining the fields most useful for project orientation. When optional flags are also active, their summaries are included: `dependency_summary` (with `--dependencies`), `env_summary` (with `--env-map`), and `code_notes_summary` (with `--code-notes`).
+`--compact` returns a reduced JSON view optimized for LLM prompts. It excludes the full `dependencies` list, `docs`, and `module_graph`, while retaining the fields most useful for project orientation. When optional flags are also active, their summaries are included: `dependency_summary` + `key_dependencies` (with `--dependencies`), `env_summary` (with `--env-map`), and `code_notes_summary` (with `--code-notes`). Adding `--no-tree` further removes `file_tree_depth1`, bringing the output to ~500-800 tokens depending on how many flags are active.
 
 Real output from a Python FastAPI project:
 
@@ -250,7 +252,7 @@ Real output from a Python FastAPI project:
 }
 ```
 
-When `--compact --dependencies` is used, `dependency_summary` is populated instead of `null`.
+When `--compact --dependencies` is used, `dependency_summary` is populated and `key_dependencies` lists the top-15 direct dependencies with resolved versions. Add `--no-tree` to drop `file_tree_depth1` for the smallest possible context footprint.
 
 ## Docs Mode
 
@@ -428,15 +430,27 @@ In a monorepo, each stack includes its own `root` and `workspace`, and one of th
 
 Different modes optimize for different tradeoffs between context size and depth of information.
 
-**`--compact` — minimal context (~500-700 tokens)**
+**`--agent` — zero-config mode for AI pipelines**
+
+Best for: running `sourcecode` from inside an agent without knowing the project in advance. Auto-selects the right flag combination based on detected stack and project size.
+
+```bash
+sourcecode --agent .
+sourcecode --agent --git-context .   # add git context on top of auto-selected flags
+```
+
+On a Java/Gradle project the output is: `--compact --dependencies --env-map --code-notes --no-tree` (~800 tokens). On a Node/Python project: same without `--no-tree` (~900 tokens including depth-1 tree). Selected flags are always printed to stderr so the agent can log them.
+
+**`--compact` — minimal context**
 
 Best for: initial orientation, deciding what to explore next, fast handoffs between agents.
 
-Includes: `project_summary` (instant project description), `architecture_summary` (execution-oriented static summary), `stacks`, `entry_points`, `file_tree_depth1`, and `dependency_summary` when `--dependencies` was also requested.
+Includes: `project_summary`, `architecture_summary`, `stacks`, `entry_points`, `file_tree_depth1`, and — when the respective flags are active — `dependency_summary` + `key_dependencies`, `env_summary`, `code_notes_summary`.
 
 ```bash
 sourcecode --compact .
-sourcecode --compact --dependencies .
+sourcecode --compact --dependencies .           # + key dependencies with versions
+sourcecode --compact --dependencies --no-tree . # smallest footprint: no file tree
 ```
 
 **Full output — deep analysis**
@@ -606,6 +620,75 @@ Combine flags for a comprehensive project handoff:
 sourcecode --compact --env-map --code-notes --git-context .
 ```
 
+## `prepare-context` — Task-aware context for LLMs
+
+`prepare-context` is a subcommand that builds a focused, task-specific context optimized for LLM reasoning. Instead of a full project dump, it returns only the data an LLM needs for a specific goal.
+
+> **Note:** Because `sourcecode` has a positional `PATH` argument, you must provide it explicitly before the subcommand:
+> ```bash
+> sourcecode . prepare-context <task>         # current directory
+> sourcecode /my/project prepare-context <task>
+> ```
+
+### Available tasks
+
+| Task | Goal | Output |
+|------|------|--------|
+| `explain` | Onboard an LLM to the project | `project_summary`, `architecture_summary`, `relevant_files`, `key_dependencies` |
+| `fix-bug` | Identify likely bug locations | `relevant_files` (ranked by risk), `suspected_areas`, `code_notes_summary` |
+| `refactor` | Surface improvement opportunities | `relevant_files`, `improvement_opportunities`, `architecture_summary` |
+| `generate-tests` | Find untested areas | `test_gaps`, `relevant_files` (source without tests), `key_dependencies` |
+
+### Usage
+
+```bash
+# List tasks with descriptions
+sourcecode . prepare-context --task-help
+
+# Explain the project
+sourcecode . prepare-context explain
+
+# Find bug areas, with a ready-to-paste LLM prompt
+sourcecode . prepare-context fix-bug --llm-prompt
+
+# Find untested files in a specific project
+sourcecode . prepare-context generate-tests --path /my/project
+
+# Preview what will be analyzed (no analysis run)
+sourcecode . prepare-context refactor --dry-run
+```
+
+### Output format
+
+```json
+{
+  "task": "fix-bug",
+  "goal": "Identify the most likely files and areas where a bug may be located.",
+  "project_summary": "CLI en Python (Typer). Entry points: src/cli.py. 4 dependencias.",
+  "architecture_summary": null,
+  "relevant_files": [
+    { "path": "src/handler.py", "role": "source", "score": 2.0, "reason": "matches 'handler'" },
+    { "path": "src/cli.py",     "role": "entrypoint", "score": 3.0, "reason": "entry point" }
+  ],
+  "suspected_areas": ["src/handler.py (2 annotations)", "src/parser.py (1 annotation)"],
+  "code_notes_summary": { "total": 5, "by_kind": { "FIXME": 3, "BUG": 2 }, "top_files": ["src/handler.py"] }
+}
+```
+
+### `--llm-prompt`
+
+Add `--llm-prompt` to include a ready-to-use prompt that you can paste directly into any LLM:
+
+```bash
+sourcecode . prepare-context explain --llm-prompt | jq -r '.llm_prompt'
+```
+
+The prompt is task-specific and includes the project context, relevant files, and concrete instructions for the LLM.
+
+### Task auto-selection with `--agent`
+
+For zero-config usage, `--agent` on the main command automatically selects the right flags for the project type. For task-aware context, use `prepare-context` explicitly with the task that matches your goal.
+
 ## Development
 
 Editable install with development dependencies:

{sourcecode-0.19.0 → sourcecode-0.21.0}/docs/schema.md

@@ -81,7 +81,7 @@ Campos:
 {
   "schema_version": "1.0",
   "generated_at": "2026-04-07T19:41:05.686277+00:00",
-  "sourcecode_version": "0.19.0",
+  "sourcecode_version": "0.21.0",
   "analyzed_path": "/abs/path/to/project"
 }
 ```
@@ -645,7 +645,7 @@ Ejemplo de salida para un monorepo con web Node.js y API Python con `--dependenc
   "metadata": {
     "schema_version": "1.0",
     "generated_at": "2026-04-07T19:41:05.686277+00:00",
-    "sourcecode_version": "0.19.0",
+    "sourcecode_version": "0.21.0",
     "analyzed_path": "/abs/path/to/project"
   },
   "file_tree": {

{sourcecode-0.19.0 → sourcecode-0.21.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "0.19.0"
+version = "0.21.0"
 description = "Genera un mapa de contexto estructurado de proyectos de software para agentes IA"
 readme = "README.md"
 requires-python = ">=3.9"

{sourcecode-0.19.0 → sourcecode-0.21.0}/src/sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Genera mapas de contexto estructurado para agentes IA."""
 
-__version__ = "0.19.0"
+__version__ = "0.21.0"

{sourcecode-0.19.0 → sourcecode-0.21.0}/src/sourcecode/cli.py

@@ -75,6 +75,11 @@ def main(
         "--graph-edges",
         help="Tipos de arista para `--graph-modules` separados por comas: imports,calls,contains,extends",
     ),
+    no_tree: bool = typer.Option(
+        False,
+        "--no-tree",
+        help="Suprimir file_tree y file_paths del output (ideal con --dependencies en proyectos grandes)",
+    ),
     no_redact: bool = typer.Option(
         False,
         "--no-redact",
@@ -151,8 +156,17 @@ def main(
         "--code-notes",
         help="Extraer anotaciones TODO/FIXME/HACK/NOTE/DEPRECATED/WARNING/BUG/XXX/OPTIMIZE con ubicacion y simbolo envolvente, y detectar ADRs en docs/decisions/, docs/adr/ y similares",
     ),
+    agent: bool = typer.Option(
+        False,
+        "--agent",
+        help="Modo agente: selecciona automaticamente --compact --dependencies --env-map --code-notes y activa --no-tree en proyectos Java/Gradle o grandes",
+    ),
 ) -> None:
     """Genera un mapa de contexto estructurado del proyecto en formato JSON o YAML."""
+    # When a subcommand (e.g. prepare-context) is invoked, skip the main analysis.
+    if ctx.invoked_subcommand is not None:
+        return
+
     # Validar formato
     if format not in FORMAT_CHOICES:
         typer.echo(
@@ -221,6 +235,16 @@ def main(
     _java_min_depth = 8
     effective_depth = max(depth, _java_min_depth) if _is_java and depth < _java_min_depth else depth
 
+    # --agent: auto-select flags based on project characteristics
+    if agent:
+        compact = True
+        if _is_java:
+            no_tree = True
+        _agent_flags = ["--compact", "--dependencies", "--env-map", "--code-notes"]
+        if no_tree:
+            _agent_flags.append("--no-tree")
+        typer.echo(f"[agent] {' '.join(_agent_flags)}", err=True)
+
     scanner = FileScanner(target, max_depth=effective_depth)
     raw_tree = scanner.scan_tree()
 
@@ -594,7 +618,7 @@ def main(
 
     # 4. Serializar (con o sin modo compact)
     if compact:
-        data = compact_view(sm)
+        data = compact_view(sm, no_tree=no_tree)
         # Aplicar redaccion sobre el dict del compact view
         if not no_redact:
             data = redact_dict(data)
@@ -602,6 +626,9 @@ def main(
     else:
         # Redactar sobre el dict serializado (SEC-01, SEC-03)
         raw_dict = asdict(sm)
+        if no_tree:
+            raw_dict.pop("file_tree", None)
+            raw_dict.pop("file_paths", None)
         if not no_redact:
             raw_dict = redact_dict(raw_dict)
 
@@ -631,31 +658,103 @@ def main(
 
 @app.command("prepare-context")
 def prepare_context_cmd(
-    task: str = typer.Argument(..., help="Descripción de la tarea"),
-    path: Path = typer.Option(".", "--path", "-p", help="Directorio del proyecto"),
+    task: Optional[str] = typer.Argument(
+        None,
+        help="Task: explain | fix-bug | refactor | generate-tests",
+    ),
+    path: Path = typer.Option(
+        Path("."),
+        "--path", "-p",
+        help="Project directory to analyze (default: current directory)",
+    ),
+    llm_prompt: bool = typer.Option(
+        False,
+        "--llm-prompt",
+        help="Append a ready-to-use LLM prompt to the output",
+    ),
+    task_help: bool = typer.Option(
+        False,
+        "--task-help",
+        help="List available tasks with descriptions and exit",
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        help="Show what would be analyzed without running it",
+    ),
 ) -> None:
-    """Prepara contexto mínimo optimizado para que un LLM modifique el código."""
-    from dataclasses import asdict
+    """Prepare task-aware context optimized for LLM reasoning.
+
+    \b
+    Note: PATH must be provided before the subcommand (default: '.'):
+      sourcecode . prepare-context explain
+      sourcecode . prepare-context fix-bug --path /my/project
+      sourcecode . prepare-context generate-tests --llm-prompt
+      sourcecode . prepare-context --task-help
+    """
+    from sourcecode.prepare_context import TASKS, TaskContextBuilder
+
+    if task_help:
+        typer.echo("Available tasks:\n")
+        for name, spec in TASKS.items():
+            typer.echo(f"  {name:<20} {spec.description}")
+            typer.echo(f"  {'':20} Output: {spec.output_hint}\n")
+        raise typer.Exit()
 
-    from sourcecode.prepare_context import ContextBuilder
+    if task is None:
+        typer.echo(
+            f"Error: task is required. Available: {', '.join(TASKS)}\n"
+            "Use --task-help for descriptions.",
+            err=True,
+        )
+        raise typer.Exit(code=1)
 
-    target = path.resolve()
+    if task not in TASKS:
+        typer.echo(
+            f"Error: unknown task '{task}'. Available: {', '.join(TASKS)}",
+            err=True,
+        )
+        raise typer.Exit(code=1)
 
+    target = path.resolve()
     if not target.exists() or not target.is_dir():
         typer.echo(f"Error: '{target}' no es un directorio válido.", err=True)
         raise typer.Exit(code=1)
 
-    builder = ContextBuilder(target)
-    result = builder.prepare(task)
-
-    out = {
-        "task": result.task,
-        "entry_points": result.entry_points,
-        "relevant_files": [asdict(f) for f in result.relevant_files],
-        "call_flow": result.call_flow,
-        "snippets": [asdict(s) for s in result.snippets],
-        "tests": result.tests,
-        "notes": result.notes,
+    if dry_run:
+        spec = TASKS[task]
+        typer.echo(f"task:        {task}")
+        typer.echo(f"goal:        {spec.goal}")
+        typer.echo(f"path:        {target}")
+        typer.echo(f"analyzers:   dependencies={'yes' if spec.enable_dependencies else 'no'}"
+                   f", code_notes={'yes' if spec.enable_code_notes else 'no'}")
+        typer.echo(f"output:      {spec.output_hint}")
+        raise typer.Exit()
+
+    from dataclasses import asdict
+
+    builder = TaskContextBuilder(target)
+    output = builder.build(task)
+
+    out: dict[str, Any] = {
+        "task": output.task,
+        "goal": output.goal,
+        "project_summary": output.project_summary,
+        "architecture_summary": output.architecture_summary,
+        "relevant_files": [asdict(f) for f in output.relevant_files],
+        "key_dependencies": output.key_dependencies,
     }
+    if output.suspected_areas:
+        out["suspected_areas"] = output.suspected_areas
+    if output.improvement_opportunities:
+        out["improvement_opportunities"] = output.improvement_opportunities
+    if output.test_gaps:
+        out["test_gaps"] = output.test_gaps
+    if output.code_notes_summary:
+        out["code_notes_summary"] = output.code_notes_summary
+    if output.limitations:
+        out["limitations"] = output.limitations
+    if llm_prompt:
+        out["llm_prompt"] = builder.render_prompt(output)
 
     typer.echo(json.dumps(out, indent=2, ensure_ascii=False))