@dailephd/my-dev-kit 1.0.0

package/docs/SECURITY.md

@@ -0,0 +1,92 @@
+# Security
+
+This document describes the security model, boundaries, and audit findings for my-dev-kit.
+
+For command flags, see [COMMANDS.md](COMMANDS.md). For architecture details, see [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Security model
+
+my-dev-kit is a local, offline CLI tool. It reads source files and JSON artifact files from the local filesystem and writes output files. It does not:
+
+- Make network requests
+- Call external services or LLMs
+- Execute arbitrary code from indexed projects
+- Spawn shells or evaluate dynamic input as code
+
+The attack surface is limited to:
+
+- Crafted JSON artifact files (`manifest.json`, `code-graph.json`, `symbol-index.json`) that could cause path traversal or trigger unsafe behavior during artifact loading
+- Malicious file paths embedded in artifacts that could read files outside the project root during source retrieval
+- DOT output injection through symbol names, node IDs, or edge labels
+- The Graphviz `dot` subprocess invocation (SVG/PNG rendering only)
+
+## Boundaries enforced
+
+### Source retrieval path containment
+
+`getSourceSlice` enforces that all source file reads stay within `manifest.projectRoot`. The check uses `path.relative` and rejects any path whose relative form starts with `..` or is absolute.
+
+Paths that escape the project root are rejected with a clear error before any file I/O occurs.
+
+### Artifact path containment
+
+`readIndexManifest` resolves artifact paths recorded in `manifest.json` (for `symbolIndex`, `codeGraph`, `callGraph`) relative to the index directory and validates that each resolved path stays within the index directory using `isInsideRoot`. A crafted manifest with paths like `../../../../etc/passwd` is rejected before the artifact file is opened.
+
+### DOT output escaping
+
+`buildDotGraph` quotes all node IDs, node labels, edge source/target IDs, and edge labels through a single `quote()` function that escapes backslashes (`\` → `\\`), double-quotes (`"` → `\"`), and newlines (CR+LF/LF → `\n`). This prevents DOT syntax injection through symbol names, file paths, or user-provided edge labels in artifact data.
+
+### Graphviz subprocess isolation
+
+`renderGraphviz` invokes `dot` using `spawnSync` with `shell: false`. The DOT content is passed as stdin, not as a shell argument or temporary file. The format argument is pre-validated to be `'svg'` or `'png'` before the subprocess is launched. There is no shell interpolation.
+
+### Python indexing subprocess isolation
+
+Python indexing invokes `python` or `python3` with `shell: false` and passes embedded `ast` parsing scripts via `python -c`. Indexed Python source is provided on stdin and parsed statically. my-dev-kit does not import or execute user Python modules during symbol, import, or call-graph extraction.
+
+### Traversal limits
+
+All graph traversal operations are bounded:
+
+- Slice depth: 0 through 3 (`validateSliceInputs`)
+- Lookup depth: 0 through 3 (`validateDepth`)
+- Source line range: capped by `--max-lines` (default 160), enforced in `validateLineRange`
+- Search result limit: 1 through 100 (`parseLimit`)
+
+These limits prevent runaway traversal on large or pathologically-shaped graphs.
+
+### Output path behavior
+
+The `--out` flags in `source`, `view`, and `slice` commands accept user-specified output paths. These paths are resolved to absolute form and parent directories are created automatically. There is no traversal restriction on output destinations — users control where output is written. This is intentional for a local CLI tool.
+
+## User responsibilities when indexing private repositories
+
+my-dev-kit reads source files and writes index artifacts containing file paths, symbol names, and import data from the indexed project. When indexing a private repository:
+
+- Index artifacts (`manifest.json`, `symbol-index.json`, `code-graph.json`) contain structural metadata about the project. Treat them with the same access controls as the source code.
+- The `--out` directory should be placed inside the project root or another location that matches your project's access policy.
+- Do not publish index artifacts or include them in version control unless intentional.
+
+## Dependency security
+
+The production runtime has no npm dependencies beyond Node.js built-ins and the `commander` package for CLI argument parsing.
+
+The `esbuild` package used in the build and test infrastructure has a known moderate-severity advisory (GHSA-67mh-4wv8-2f99) affecting `esbuild ≤ 0.24.2` via `vite` and `vitest`. This affects development tooling only. The built `dist/cli.js` output does not include esbuild or vite at runtime.
+
+Run `npm audit` to see the current advisory status. Upgrading `vitest` to v4.x would resolve the esbuild advisory but may introduce breaking changes in the test suite.
+
+## Security test coverage
+
+Security tests are in `tests/security/`:
+
+| File | What it tests |
+| ---- | -------------- |
+| `pathTraversal.spec.ts` | `ensureInsideProjectRoot` and `isInsideRoot` reject `../` traversal patterns |
+| `malformedArtifacts.spec.ts` | `readIndexManifest` rejects missing, invalid, or traversal-exploiting manifests |
+| `dotEscaping.spec.ts` | `buildDotGraph` escapes quotes, backslashes, newlines, and angle brackets |
+| `outputPath.spec.ts` | Write helpers create parent directories and return normalized paths |
+| `graphTraversalLimits.spec.ts` | Slice depth, lookup depth, and source line range limits are enforced |
+
+## Reporting
+
+This is a local open-source CLI tool with no external services. If you discover a security issue, open an issue in the project repository with a description of the finding and a reproduction case.

package/docs/WORKFLOWS.md

@@ -0,0 +1,316 @@
+# Workflows
+
+Practical usage workflows for my-dev-kit. For the full flag reference, see [COMMANDS.md](COMMANDS.md). For artifact and schema details, see [GRAPH_SCHEMA.md](GRAPH_SCHEMA.md).
+
+## Overview
+
+The recommended usage pattern:
+
+1. Index the project once, then re-run when source changes.
+2. Use `search` to discover relevant node IDs.
+3. Use `lookup` or `slice` to inspect graph relationships.
+4. Use `source` to retrieve specific code excerpts.
+5. Use `view` to render the full graph when a visual overview is needed.
+
+Do not start by reading the full graph or full source tree. Use `search` first to narrow the context.
+
+---
+
+## Workflow 1: Index a TypeScript or JavaScript project
+
+Run `index` from the project root:
+
+```sh
+my-dev-kit index --root . --src src --out .my-dev-kit --json
+```
+
+The `--out` path is relative to `--root`. The above creates `.my-dev-kit/`.
+
+Include a call graph:
+
+```sh
+my-dev-kit index --root . --src src --out .my-dev-kit --call-graph --json
+```
+
+Index multiple source roots:
+
+```sh
+my-dev-kit index --root . --src src --src tests --out .my-dev-kit --json
+```
+
+For large monorepos, avoid indexing broad roots that contain application output, dependency folders, caches, or generated artifacts. Target the source folders that matter for the current workflow:
+
+```sh
+my-dev-kit index --root . --src apps/web/app --src apps/web/lib --src apps/web/prisma --out .my-dev-kit-web --call-graph --json
+```
+
+my-dev-kit skips common generated, dependency, cache, and build directories by default, including `node_modules`, `.next`, `dist`, `build`, `coverage`, `playwright-report`, `test-results`, `output`, `out`, `.cache`, `.turbo`, `.vercel`, `.git`, `.pytest_cache`, `__pycache__`, `.venv`, and `venv`. Add project-specific exclusions with repeated `--exclude` values:
+
+```sh
+my-dev-kit index --root . --src apps/web --out .my-dev-kit-web --exclude .next --exclude coverage --exclude apps/web/generated --json
+```
+
+Use `--dry-run` before indexing a large tree, and add `--progress` when you want phase and count diagnostics. Progress is written to stderr and does not corrupt JSON stdout.
+
+```sh
+my-dev-kit index --root . --src apps/web --out .my-dev-kit-web --dry-run --json
+my-dev-kit index --root . --src apps/web/app --src apps/web/lib --out .my-dev-kit-web --progress --json
+```
+
+Split indexes can keep focused workflows faster and easier to inspect:
+
+```sh
+my-dev-kit index --root . --src apps/web/app --src apps/web/lib --src apps/web/prisma --out .my-dev-kit-web --call-graph --json
+my-dev-kit index --root . --src apps/web/tests --src apps/web/e2e --out .my-dev-kit-web-tests --exclude playwright-report --exclude test-results --json
+my-dev-kit index --root . --src apps/nlp-service/src --language python --out .my-dev-kit-nlp --call-graph --json
+my-dev-kit index --root . --src scripts --out .my-dev-kit-scripts --json
+```
+
+---
+
+## Workflow 2: Index a Python project
+
+Python indexing requires `python` or `python3` on `PATH` with Python 3.8 or later. The `--language python` flag selects Python mode. Language can also be inferred from `.py` file extensions.
+
+**Step 1: Index the Python source root**
+
+```sh
+my-dev-kit index --root . --src src --language python --out .my-dev-kit --json
+```
+
+Include a static call graph when call edges are useful:
+
+```sh
+my-dev-kit index --root . --src src --language python --out .my-dev-kit --call-graph --json
+```
+
+**Step 2: Search for Python symbols**
+
+```sh
+my-dev-kit search --index .my-dev-kit --query "greet" --limit 20 --json
+```
+
+**Step 3: Look up a Python node**
+
+```sh
+my-dev-kit lookup --index .my-dev-kit --node file:src/main.py --depth 1 --json
+```
+
+**Step 4: Retrieve Python source**
+
+```sh
+my-dev-kit source --index .my-dev-kit --file src/main.py --symbol greet --format numbered
+```
+
+Use line-range retrieval for exact bounds:
+
+```sh
+my-dev-kit source --index .my-dev-kit --file src/main.py --start 1 --end 40 --format numbered
+```
+
+**Python notes:**
+
+- Call-graph extraction is static and conservative. It uses `ast` parsing and may miss dynamic calls.
+- If no Python interpreter is found on `PATH`, Python files are skipped with a warning in the manifest.
+
+---
+
+## Workflow 3: Graph-Guided Symbol Retrieval
+
+Graph-Guided Symbol Retrieval is the recommended approach when navigating an unfamiliar codebase. It avoids broad file reading by narrowing context progressively from keyword search to exact graph nodes to targeted source excerpts.
+
+**Step 1: Index the project**
+
+```sh
+my-dev-kit index --root . --src src --out .my-dev-kit --json
+```
+
+**Step 2: Search to narrow candidates**
+
+```sh
+my-dev-kit search --index .my-dev-kit --query "<relevant term>" --limit 20 --json
+```
+
+Inspect `nodeId`, `kind`, and `matchReasons` in the results. Prefer symbol nodes when the target is a specific function, class, or type.
+
+**Step 3: Look up the strongest candidate**
+
+```sh
+my-dev-kit lookup --index .my-dev-kit --node "<node-id>" --depth 1 --json
+```
+
+Review incoming edges, outgoing edges, and neighbors to understand the node's relationships. Repeat for adjacent nodes as needed.
+
+**Step 4: Slice around the focus node**
+
+```sh
+my-dev-kit slice --index .my-dev-kit --node "<node-id>" --depth 2 --direction both --json
+```
+
+The slice provides a bounded subgraph view that is easier to reason about than the full graph.
+
+**Step 5: Retrieve source for specific symbols**
+
+Use symbol-mode retrieval when possible:
+
+```sh
+my-dev-kit source --index .my-dev-kit --file "<path>" --symbol "<symbol-name>" --format numbered
+```
+
+Use line-range retrieval when symbol-mode is too broad or incomplete:
+
+```sh
+my-dev-kit source --index .my-dev-kit --file "<path>" --start <n> --end <n> --format numbered
+```
+
+**What to avoid:**
+
+- Do not read full `code-graph.json` manually to find node IDs. Use `search` first.
+- Do not retrieve large line ranges when a symbol name is known. Use `--symbol` mode first.
+- Do not iterate all files before searching. Let `search` narrow the scope.
+
+---
+
+## Workflow 4: Generate graph visualization
+
+DOT output does not require Graphviz:
+
+```sh
+my-dev-kit view --index .my-dev-kit --format dot --out .my-dev-kit/graph.dot
+my-dev-kit view --index .my-dev-kit --format dot --edge-style labeled --out .my-dev-kit/graph.labeled.dot
+my-dev-kit view --index .my-dev-kit --format dot --edge-style minimal --out .my-dev-kit/graph.minimal.dot
+```
+
+SVG output requires Graphviz:
+
+```sh
+my-dev-kit view --index .my-dev-kit --format svg --out .my-dev-kit/graph.svg
+```
+
+Fall back to DOT if Graphviz is unavailable:
+
+```sh
+my-dev-kit view --index .my-dev-kit --format svg --allow-dot-fallback --out .my-dev-kit/graph.dot
+```
+
+Use `--format dot` for automated checks. Reserve SVG or PNG for interactive review.
+
+---
+
+## Workflow 5: Use my-dev-kit with ChatGPT or a coding agent
+
+LLMs perform better when given bounded, relevant context instead of whole files or broad project dumps. my-dev-kit helps collect that context deterministically from your local project.
+
+my-dev-kit does not call LLMs, does not edit files, and does not act as an autonomous agent. It prepares local bounded context for you or for downstream tools.
+
+**Command sequence**
+
+```sh
+my-dev-kit index --root . --src src --out .my-dev-kit --json
+my-dev-kit search --index .my-dev-kit --query "<topic>" --limit 20 --json
+my-dev-kit lookup --index .my-dev-kit --node "<node-id>" --depth 1 --json
+my-dev-kit slice --index .my-dev-kit --node "<node-id>" --depth 2 --direction both --json
+my-dev-kit source --index .my-dev-kit --file "<path>" --symbol "<symbol-name>" --format numbered
+```
+
+**What to paste into the LLM**
+
+- Selected search output or a concise summary of the strongest matches
+- Selected lookup output
+- Selected graph slice or a concise summary of nearby nodes and edges
+- Numbered source excerpts
+- File paths, symbol names, and node IDs used to retrieve the context
+
+**What not to paste**
+
+- The entire source tree
+- Full `symbol-index.json`
+- Full `code-graph.json`
+- Broad unrelated files
+- Generated artifacts that are not relevant to the current task
+
+**Reusable prompt template**
+
+```text
+I am using my-dev-kit to provide bounded codebase context.
+
+Task:
+<describe the coding, debugging, documentation, or refactoring task>
+
+Repository context:
+Project root: <project root>
+Index directory: .my-dev-kit
+Source roots indexed: <source roots>
+
+Graph-guided retrieval:
+Search query used:
+<query>
+
+Search results:
+<paste selected search JSON or summarized result>
+
+Selected node:
+<node-id>
+Reason selected:
+<why this node is the strongest candidate>
+
+Lookup result:
+<paste lookup result or concise summary>
+
+Graph slice:
+<paste slice result or concise summary>
+
+Source excerpts:
+<paste numbered source output with file paths>
+
+Instructions:
+Use only the provided context unless you explicitly say what additional file, symbol, or graph node is needed.
+Do not assume unrelated files were inspected.
+If the context is insufficient, ask for the next my-dev-kit search, lookup, slice, or source command to run.
+Prefer targeted changes grounded in the retrieved source.
+Explain which provided evidence supports your answer.
+```
+
+**When to rerun commands**
+
+- Re-run `index` after source changes so graph artifacts match the current project.
+- Use better query terms if `search` results are weak. Try symbol names, feature terms, error text, file names, or imported module names.
+- Use `lookup --depth 1` first. Increase depth only when the immediate graph neighborhood is insufficient.
+- Use `slice --depth 1` or `slice --depth 2` depending on context size.
+- Use line-range source retrieval when symbol retrieval is too broad or incomplete.
+
+---
+
+## Bundled examples
+
+The examples are for cloned repositories, documentation writers, and package smoke tests. Normal npm users should run my-dev-kit inside their own project.
+
+```sh
+my-dev-kit index --root examples/basic-ts --src src --out .my-dev-kit --json
+my-dev-kit search --index examples/basic-ts/.my-dev-kit --query "service" --limit 5 --json
+
+my-dev-kit index --root examples/basic-python --src src --language python --out .my-dev-kit --json
+my-dev-kit search --index examples/basic-python/.my-dev-kit --query "greet" --limit 5 --json
+```
+
+---
+
+## Troubleshooting
+
+**Problem: "Missing index manifest"**
+The index artifact directory does not contain `manifest.json`. Run `index` first, or check the `--index` path.
+
+**Problem: "Unknown node ID"**
+The node ID passed to `lookup`, `source`, or `slice` is not in the graph. Use `search` to discover valid node IDs.
+
+**Problem: "Symbol not found"**
+The symbol name does not match any indexed symbol in the specified file. Run `search --query <symbol-name>` to confirm spelling and which file contains it.
+
+**Problem: "Graphviz dot executable is not available"**
+SVG and PNG rendering requires Graphviz. Install Graphviz, use `--format dot`, or add `--allow-dot-fallback`.
+
+**Problem: Result content is capped with a preview warning**
+Symbol retrieval is bounded from the start line. Increase `--max-lines` or use line-range mode with explicit `--start` and `--end` values.
+
+**Problem: Python symbols not indexed or warnings about Python interpreter**
+Python indexing requires `python` or `python3` on `PATH`. Install Python 3.8 or later and ensure the interpreter is accessible.

package/examples/README.md

@@ -0,0 +1,23 @@
+# Examples
+
+These folders are small projects for learning and smoke testing my-dev-kit from a cloned repository or inspected package contents.
+
+- `basic-ts` is a small TypeScript project for learning command behavior and running smoke checks.
+- `basic-python` is a small Python project for learning command behavior and running smoke checks.
+
+Normal npm users should run `my-dev-kit` inside their own project:
+
+```sh
+cd <your-project>
+my-dev-kit index --root . --src src --out .my-dev-kit --json
+```
+
+Use these examples when you want a tiny known project:
+
+```sh
+my-dev-kit index --root examples/basic-ts --src src --out .my-dev-kit --json
+my-dev-kit search --index examples/basic-ts/.my-dev-kit --query "service" --limit 5 --json
+
+my-dev-kit index --root examples/basic-python --src src --language python --out .my-dev-kit --json
+my-dev-kit search --index examples/basic-python/.my-dev-kit --query "greet" --limit 5 --json
+```

package/examples/basic-python/README.md

@@ -0,0 +1,14 @@
+# basic-python
+
+Small Python project for learning and smoke testing my-dev-kit. Python indexing requires `python` or `python3` on `PATH` with Python 3.8 or later.
+
+From the repository root:
+
+```sh
+my-dev-kit index --root examples/basic-python --src src --language python --out .my-dev-kit --call-graph --json
+my-dev-kit search --index examples/basic-python/.my-dev-kit --query "greet" --limit 5 --json
+my-dev-kit lookup --index examples/basic-python/.my-dev-kit --node file:src/main.py --depth 1 --json
+my-dev-kit source --index examples/basic-python/.my-dev-kit --file src/main.py --symbol greet --format numbered
+```
+
+This example is secondary documentation for cloned repositories and package smoke tests. Normal npm users should run `my-dev-kit` inside their own project.

package/examples/basic-python/src/main.py

@@ -0,0 +1,38 @@
+"""Main module for the basic-python example."""
+
+import os
+from utils import format_name, Formatter
+
+__all__ = ["greet", "UserService"]
+
+APP_NAME = "BasicPython"
+
+
+def greet(name: str) -> str:
+    """Return a greeting string for the given name."""
+    return f"Hello, {name}!"
+
+
+async def fetch_user(user_id: int) -> dict:
+    """Async function to fetch a user by ID (stub)."""
+    return {"id": user_id, "name": "Alice"}
+
+
+def _build_message(template: str, **kwargs) -> str:
+    """Private builder — not in __all__."""
+    return template.format(**kwargs)
+
+
+class UserService:
+    """Service for managing users."""
+
+    def __init__(self, base_url: str) -> None:
+        self.base_url = base_url
+        self._formatter = Formatter(prefix="[user] ")
+
+    def describe(self, first: str, last: str) -> str:
+        full = format_name(first, last)
+        return self._formatter.format(full)
+
+    def get_env(self) -> str:
+        return os.environ.get("APP_ENV", "development")

package/examples/basic-python/src/utils.py

@@ -0,0 +1,24 @@
+"""Shared utilities for the basic-python example."""
+
+MAX_RETRIES = 3
+DEFAULT_TIMEOUT = 30
+
+
+def format_name(first: str, last: str) -> str:
+    """Return a formatted full name."""
+    return f"{first} {last}"
+
+
+def _internal_helper(value: str) -> str:
+    """Private helper not included in public API."""
+    return value.strip().lower()
+
+
+class Formatter:
+    """Formats values for display."""
+
+    def __init__(self, prefix: str = "") -> None:
+        self.prefix = prefix
+
+    def format(self, value: str) -> str:
+        return f"{self.prefix}{value}" if self.prefix else value

package/examples/basic-ts/README.md

@@ -0,0 +1,14 @@
+# basic-ts
+
+Small TypeScript project for learning and smoke testing my-dev-kit.
+
+From the repository root:
+
+```sh
+my-dev-kit index --root examples/basic-ts --src src --out .my-dev-kit --call-graph --json
+my-dev-kit search --index examples/basic-ts/.my-dev-kit --query "user" --limit 5 --json
+my-dev-kit lookup --index examples/basic-ts/.my-dev-kit --node symbol:src/index.ts#describeUser --depth 1 --json
+my-dev-kit source --index examples/basic-ts/.my-dev-kit --file src/index.ts --symbol describeUser --format numbered
+```
+
+This example is secondary documentation for cloned repositories and package smoke tests. Normal npm users should run `my-dev-kit` inside their own project.

package/examples/basic-ts/src/index.ts

@@ -0,0 +1,6 @@
+import { formatUser, roleLabel } from './userService'
+import type { User, UserRole } from './userTypes'
+
+export function describeUser(user: User, role: UserRole): string {
+  return `${formatUser(user)} - ${roleLabel(role)}`
+}

package/examples/basic-ts/src/userService.ts

@@ -0,0 +1,9 @@
+import type { User, UserRole } from './userTypes'
+
+export function formatUser(user: User): string {
+  return `${user.name} (${user.id})`
+}
+
+export function roleLabel(role: UserRole): string {
+  return role === 'admin' ? 'Administrator' : 'Member'
+}

package/examples/basic-ts/src/userTypes.ts

@@ -0,0 +1,6 @@
+export interface User {
+  id: string
+  name: string
+}
+
+export type UserRole = 'admin' | 'member'

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@dailephd/my-dev-kit",
+  "version": "1.0.0",
+  "description": "Local codebase graph, indexing, slicing, source retrieval, search, and Graphviz visualization CLI.",
+  "type": "module",
+  "bin": {
+    "my-dev-kit": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "docs/ARCHITECTURE.md",
+    "docs/CI_CD.md",
+    "docs/COMMANDS.md",
+    "docs/DEVELOPMENT.md",
+    "docs/GRAPH_SCHEMA.md",
+    "docs/QUICKSTART.md",
+    "docs/RELEASE.md",
+    "docs/ROADMAP.md",
+    "docs/SECURITY.md",
+    "docs/WORKFLOWS.md",
+    "examples/README.md",
+    "examples/basic-ts/src",
+    "examples/basic-ts/README.md",
+    "examples/basic-python/src",
+    "examples/basic-python/README.md"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "verify": "npm run typecheck && npm run test && npm run build",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "prepack": "npm run build"
+  },
+  "license": "MIT",
+  "author": "dailephd LLC",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.25",
+    "tsup": "^8.5.1",
+    "tsx": "^4.20.6",
+    "vitest": "^2.1.9"
+  }
+}