@dailephd/my-dev-kit 1.0.0

package/docs/QUICKSTART.md

@@ -0,0 +1,243 @@
+# Quickstart
+
+This guide shows the shortest path from installing the public npm package to using all six commands in your own project.
+
+For the full flag reference, see [COMMANDS.md](COMMANDS.md). For artifact and schema details, see [GRAPH_SCHEMA.md](GRAPH_SCHEMA.md). For practical workflows, see [WORKFLOWS.md](WORKFLOWS.md).
+
+## Prerequisites
+
+- Node.js 18 or later
+- npm
+
+Python is required only when indexing `.py` files. Graphviz is optional; DOT output works without it, while SVG and PNG rendering require the Graphviz `dot` executable.
+
+## 1. Install
+
+```sh
+npm install -g @dailephd/my-dev-kit
+```
+
+## 2. Confirm the CLI
+
+```sh
+my-dev-kit --help
+my-dev-kit --version
+```
+
+## 3. Index your project
+
+Run the CLI from inside your own project:
+
+```sh
+cd <your-project>
+my-dev-kit index --root . --src src --out .my-dev-kit --json
+```
+
+The `--out` path is relative to `--root`. This creates `.my-dev-kit/` in your project.
+
+Use multiple source roots when needed:
+
+```sh
+my-dev-kit index --root . --src src --src tests --out .my-dev-kit --json
+```
+
+For large repositories and monorepos, prefer targeted source folders over broad package roots. my-dev-kit automatically skips common generated, dependency, cache, and build directories such as `node_modules`, `.next`, `dist`, `build`, `coverage`, `playwright-report`, `test-results`, `.cache`, `.turbo`, `.vercel`, `.git`, `.pytest_cache`, `__pycache__`, `.venv`, and `venv`.
+
+```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
+```
+
+Preview a scan without writing artifacts:
+
+```sh
+my-dev-kit index --root . --src apps/web --out .my-dev-kit-web --dry-run --json
+```
+
+Add extra path/name exclusions and progress diagnostics when a scan is large:
+
+```sh
+my-dev-kit index --root . --src apps/web --out .my-dev-kit-web --exclude .next --exclude coverage --progress --json
+```
+
+For Python projects:
+
+```sh
+my-dev-kit index --root . --src src --language python --out .my-dev-kit --json
+```
+
+To include a best-effort static call graph:
+
+```sh
+my-dev-kit index --root . --src src --out .my-dev-kit --call-graph --json
+```
+
+Generated artifacts inside `.my-dev-kit/`:
+
+- `manifest.json` - project metadata and summary counts
+- `symbol-index.json` - per-file symbol tables
+- `code-graph.json` - graph of file and symbol nodes
+- `call-graph.json` - call edges, when `--call-graph` was requested
+
+Split indexes can keep large workspaces easier to navigate:
+
+```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
+```
+
+## 4. Search for a symbol or file
+
+Use `search` to discover node IDs before using `lookup`, `slice`, or `source`.
+
+```sh
+my-dev-kit search --index .my-dev-kit --query "<term>" --limit 20 --json
+```
+
+Each result includes a `nodeId` field that can be passed to other commands.
+
+## 5. Look up a node
+
+Pass an exact node ID from search results:
+
+```sh
+my-dev-kit lookup --index .my-dev-kit --node "<node-id>" --depth 1 --json
+```
+
+The result includes the focus node, incoming edges, outgoing edges, and neighbors at the requested depth.
+
+## 6. Build a graph slice
+
+Get a bounded subgraph around a selected node:
+
+```sh
+my-dev-kit slice --index .my-dev-kit --node "<node-id>" --depth 2 --direction both --json
+```
+
+`slice` reads graph artifacts only. It does not read source files and does not require Graphviz.
+
+## 7. Retrieve source
+
+Retrieve a symbol with line numbers:
+
+```sh
+my-dev-kit source --index .my-dev-kit --file "<path>" --symbol "<symbol-name>" --format numbered
+```
+
+Retrieve an exact line range:
+
+```sh
+my-dev-kit source --index .my-dev-kit --file "<path>" --start 1 --end 40 --format numbered
+```
+
+Retrieve as structured JSON:
+
+```sh
+my-dev-kit source --index .my-dev-kit --file "<path>" --start 1 --end 40 --format json
+```
+
+Source retrieval never modifies source files. The `--max-lines` limit is enforced, and file paths that escape the project root are rejected.
+
+## 8. Render the graph as DOT
+
+DOT output does not require Graphviz:
+
+```sh
+my-dev-kit view --index .my-dev-kit --format dot --out .my-dev-kit/graph.dot
+```
+
+Use a different edge style when useful:
+
+```sh
+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
+```
+
+## 9. Render SVG or PNG with Graphviz
+
+If Graphviz is installed:
+
+```sh
+my-dev-kit view --index .my-dev-kit --format svg --out .my-dev-kit/graph.svg
+```
+
+If Graphviz is not installed, use DOT output directly or fall back automatically:
+
+```sh
+my-dev-kit view --index .my-dev-kit --format svg --allow-dot-fallback --out .my-dev-kit/graph.dot
+```
+
+## Use the output with ChatGPT or a coding agent
+
+my-dev-kit does not call ChatGPT or any coding agent. It prepares bounded local context that you can paste into an LLM conversation or provide to a downstream tool.
+
+Paste only the selected outputs that support the task:
+
+- Selected `search` result or a concise summary of the best matches
+- Selected `lookup` result
+- Selected `slice` result or a concise graph summary
+- Numbered `source` excerpts with file paths and symbol names
+
+Do not paste full `symbol-index.json` or `code-graph.json` unless specifically needed. They are index artifacts, not the normal context format for LLM-assisted work.
+
+Short prompt:
+
+```text
+I am using my-dev-kit to provide bounded codebase context.
+
+Task:
+<describe the task>
+
+Selected search, lookup, slice, and source outputs:
+<paste targeted my-dev-kit output>
+
+Use only this context unless you say which additional my-dev-kit command I should run.
+```
+
+For the fuller reusable template, see [Workflow 5 in WORKFLOWS.md](WORKFLOWS.md#workflow-5-use-my-dev-kit-with-chatgpt-or-a-coding-agent).
+
+## Bundled examples for cloned repositories
+
+The `examples/basic-ts` and `examples/basic-python` folders are useful when working from the repository source, inspecting package examples, or smoke testing. They are not the normal path for a user inside their own project.
+
+TypeScript example:
+
+```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 "service" --limit 5 --json
+my-dev-kit lookup --index examples/basic-ts/.my-dev-kit --node file:src/index.ts --depth 1 --json
+my-dev-kit source --index examples/basic-ts/.my-dev-kit --file src/index.ts --symbol describeUser --format numbered
+```
+
+Python example:
+
+```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
+```
+
+## Clean up generated artifacts
+
+Inside your own project:
+
+```sh
+rm -rf .my-dev-kit
+```
+
+For bundled examples in a cloned repository:
+
+```sh
+rm -rf examples/basic-ts/.my-dev-kit
+rm -rf examples/basic-python/.my-dev-kit
+```
+
+## Next steps
+
+- [COMMANDS.md](COMMANDS.md) - full flag reference for every command
+- [GRAPH_SCHEMA.md](GRAPH_SCHEMA.md) - artifact formats, node ID conventions, and edge kinds
+- [WORKFLOWS.md](WORKFLOWS.md) - practical workflows including graph-guided retrieval
+- [ARCHITECTURE.md](ARCHITECTURE.md) - internal subsystem structure
+- [ROADMAP.md](ROADMAP.md) - current feature status and planned improvements

package/docs/RELEASE.md

@@ -0,0 +1,249 @@
+# Release Guide
+
+This guide describes the manual release process for my-dev-kit.
+
+The npm package is published manually. There is no automated release workflow for npm publishing.
+
+## Release profile
+
+- Product name: my-dev-kit
+- Package name: @dailephd/my-dev-kit
+- Binary name: my-dev-kit
+- Release version: 1.0.0
+- License: MIT
+- Copyright holder: dailephd LLC
+- npm scope: @dailephd
+- Publish mode: manual npm publish
+
+## Before release
+
+Confirm the release branch is clean and the package metadata is correct.
+
+Required checks:
+
+- package.json name is @dailephd/my-dev-kit
+- package.json version is 1.0.0
+- package.json license is MIT
+- package.json author is dailephd LLC
+- package.json does not contain private: true
+- package.json bin maps my-dev-kit to dist/cli.js
+- src/version.ts VERSION matches package.json version
+- LICENSE exists and contains the MIT license with copyright 2026 dailephd LLC
+- CHANGELOG.md exists and includes the 1.0.0 release
+- dist/cli.js is generated by the build
+- dist/cli.js starts with the shebang #!/usr/bin/env node
+
+## Public documentation audit
+
+Review public-facing documentation before publishing.
+
+The product name should be my-dev-kit. The version label v1 may appear only when referring to version history or roadmap planning. Public install and usage sections should not present my-dev-kit-v1 as the product name.
+
+Check the following files at minimum:
+
+- README.md
+- QUICKSTART.md
+- CHANGELOG.md
+- doc/COMMANDS.md
+- doc/ROADMAP.md
+- doc/PROJECT_OVERVIEW.md
+- examples/README.md, if present
+
+Documentation should use:
+
+- my-dev-kit as the product name
+- @dailephd/my-dev-kit as the npm package name
+- my-dev-kit as the command name
+- npm install -g @dailephd/my-dev-kit as the primary global install example
+
+Documentation should not include:
+
+- my-dev-kit-v1 as the public product name
+- version 0.1.0
+- old alpha repository names in public usage sections
+- primary examples that require node dist/cli.js
+- PromptPack, orchestrator, or evaluation features as public v1 package features
+- CONTRIBUTING.md references
+- CODE_OF_CONDUCT.md references
+- package publishing automation claims
+- GitHub release automation claims
+
+Internal development notes may mention implementation details, but public package documentation should describe the actual v1 CLI product.
+
+## Validate locally
+
+Run validation from the repository root.
+
+    npm ci
+    npm run verify
+    npm audit
+
+If npm run verify does not already run typecheck, tests, and build in the current repository state, run the explicit validation sequence instead:
+
+    npm ci
+    npm run typecheck
+    npm run test
+    npm run build
+    npm run verify
+    npm audit
+
+The release should not continue until validation passes or every remaining issue is understood and intentionally accepted.
+
+## Inspect package contents
+
+Run a dry pack first.
+
+    npm pack --dry-run
+
+Review the package file list.
+
+Expected package contents:
+
+- dist/
+- README.md
+- LICENSE
+- CHANGELOG.md
+- doc/ files intended for public package documentation
+- examples intended for public users
+- package.json
+
+Unexpected package contents:
+
+- src/
+- tests/
+- generated index artifacts
+- temporary release-test folders
+- alpha-import/
+- node_modules/
+- local logs
+- unpublished notes
+- private planning files
+- old migration files that are not part of the public package
+
+The package should include enough documentation and examples for users to run the CLI after installation, but it should not include development-only source, tests, or generated artifacts unless they are intentionally part of the distributed package.
+
+## Test the packed tarball
+
+Create the tarball.
+
+    npm pack
+
+Install the tarball globally.
+
+    npm install -g ./dailephd-my-dev-kit-1.0.0.tgz
+
+Run basic CLI checks.
+
+    my-dev-kit --help
+    my-dev-kit --version
+
+The version command should print 1.0.0.
+
+Run TypeScript or JavaScript indexing against the packaged examples.
+
+    my-dev-kit index --root examples/basic-ts --src src --out examples/basic-ts/.my-dev-kit-release --call-graph --json
+    my-dev-kit search --index examples/basic-ts/.my-dev-kit-release --query service --limit 5 --json
+    my-dev-kit view --index examples/basic-ts/.my-dev-kit-release --format dot --out examples/basic-ts/.my-dev-kit-release/graph.dot --edge-style semantic --json
+
+Run Python indexing if the package includes the Python example.
+
+    my-dev-kit index --root examples/basic-python --src src --language python --out examples/basic-python/.my-dev-kit-release --json
+
+Confirm the expected artifacts are created.
+
+Expected TypeScript or JavaScript artifacts:
+
+- manifest.json
+- symbol-index.json
+- code-graph.json
+- call-graph.json, when --call-graph is used
+
+Expected Python artifacts:
+
+- manifest.json
+- symbol-index.json
+- code-graph.json
+
+Remove local release-test artifacts after inspection.
+
+    rm -rf examples/basic-ts/.my-dev-kit-release
+    rm -rf examples/basic-python/.my-dev-kit-release
+
+Uninstall the global tarball test package.
+
+    npm uninstall -g @dailephd/my-dev-kit
+
+If the example directory names differ from examples/basic-ts or examples/basic-python, use the actual packaged example paths and update this guide before release.
+
+## Publish to npm
+
+Log in to npm if needed.
+
+    npm login
+
+Confirm package metadata one final time.
+
+    npm info @dailephd/my-dev-kit
+
+If this is the first public release, npm info may report that the package does not exist yet. That is acceptable.
+
+Publish the package publicly.
+
+    npm publish --access public
+
+Do not publish until local validation, package inspection, and tarball smoke tests have passed.
+
+## Verify the published package
+
+After publishing, verify the package from npm.
+
+    npm info @dailephd/my-dev-kit
+    npm install -g @dailephd/my-dev-kit
+    my-dev-kit --help
+    my-dev-kit --version
+
+Confirm:
+
+- npm reports version 1.0.0
+- my-dev-kit --help shows the expected command list
+- my-dev-kit --version prints 1.0.0
+- the package installs without using the local tarball
+
+Optionally run the same example indexing smoke tests against the published package.
+
+After verification, uninstall the global package if it is not needed locally.
+
+    npm uninstall -g @dailephd/my-dev-kit
+
+## Release record
+
+After publishing, update or confirm the following:
+
+- CHANGELOG.md includes the published version and release date
+- README.md install instructions point to the npm package
+- ROADMAP.md still describes future versions accurately
+- package.json version matches the published version
+- any release notes are consistent with the actual v1 command surface
+
+If a GitHub release is created manually, use the CHANGELOG.md entry as the source of truth. Do not describe unreleased roadmap items as released features.
+
+## Automation status
+
+The release process is currently manual.
+
+The following steps are not automated:
+
+- version bumping
+- changelog generation
+- npm publishing
+- GitHub release creation
+- Docker publishing
+- deployment
+
+Release automation can be added later if the project needs it. If automation is added, use a dedicated release workflow rather than extending the CI validation workflow with publishing behavior.
+
+## Package metadata notes
+
+No official funding or donation URL is configured for this release.
+
+Do not add package.json funding metadata until an official support or donation page exists.