2026 05 13 package api and repo polish

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,17 @@
+# Code of Conduct
+
+This project adopts the [Contributor Covenant 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) code of conduct.
+
+In brief:
+
+- Be respectful and constructive.
+- No harassment, personal attacks, or exclusionary behavior.
+- Assume good intent; ask questions before drawing conclusions.
+
+## Reporting
+
+Report violations to [shmakov@konturnomad.am](mailto:shmakov@konturnomad.am). Reports are reviewed within 7 days and treated with discretion.
+
+## Enforcement
+
+Violations may result in comment removal, temporary restriction, or permanent ban from the project, depending on severity and context.

.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,41 @@
+name: Bug report
+description: Report a defect or unexpected behavior
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before submitting, check [existing issues](https://github.com/sergeyshmakov/data-path/issues) to avoid duplicates.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened, and what did you expect?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: A self-contained TypeScript snippet that demonstrates the issue.
+      render: ts
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Package version
+      placeholder: "1.0.0"
+    validations:
+      required: true
+
+  - type: input
+    id: ts-version
+    attributes:
+      label: TypeScript version
+      placeholder: "5.5.0"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://sergeyshmakov.github.io/data-path/
+    about: Browse the full documentation site first — your question may already be answered.
+  - name: Discussions
+    url: https://github.com/sergeyshmakov/data-path/discussions
+    about: Usage questions, ideas, and general conversation.

.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,30 @@
+name: Feature request
+description: Propose a new capability or API change
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please open an issue before writing code for large features — this avoids wasted effort if the design needs adjusting.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What is missing or painful today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What would you like to see? A code sketch is welcome.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you considered, and why you ruled them out.

.github/dependabot.yml

@@ -5,13 +5,13 @@ updates:
     directory: "/"
     schedule:
       interval: "monthly"
-      day: "monday"
       time: "06:00"
       timezone: "UTC"
+    allow:
+      - dependency-type: "direct"
     open-pull-requests-limit: 5
     labels:
       - "dependencies"
-    dependency-type: "direct"
     groups:
       npm-production:
         dependency-type: "production"
@@ -20,3 +20,40 @@ updates:
     ignore:
       - dependency-name: "@types/node*"
         versions: [ ">=24" ]
+      - dependency-name: "lint-staged"
+        versions: [ ">=17" ]
+      - dependency-name: "typescript"
+        versions: [ ">=6" ]
+
+  - package-ecosystem: "npm"
+    directory: "/docs"
+    schedule:
+      interval: "monthly"
+      time: "06:00"
+      timezone: "UTC"
+    allow:
+      - dependency-type: "direct"
+    open-pull-requests-limit: 1
+    labels:
+      - "dependencies"
+    groups:
+      docs-dependencies:
+        patterns: ["*"]
+    ignore:
+      - dependency-name: "lint-staged"
+        versions: [ ">=17" ]
+      - dependency-name: "typescript"
+        versions: [ ">=6" ]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+      time: "06:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 1
+    labels:
+      - "dependencies"
+    groups:
+      github-actions:
+        patterns: ["*"]

.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## What does this PR do?
+
+<!-- A concise description. Link any related issue with "Closes #123" or "Fixes #123". -->
+
+## How to test
+
+<!-- Steps to reproduce or verify the change. -->
+
+## Checklist
+
+- [ ] Tests added or updated
+- [ ] Docs updated (if public API changed)
+- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)

.github/workflows/deploy-docs.yml

@@ -0,0 +1,49 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths: ["docs/**"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history so Starlight's `lastUpdated` (git log per file) is accurate.
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+      - name: Install dependencies
+        working-directory: docs
+        run: npm ci
+      - name: Build docs
+        working-directory: docs
+        run: npm run build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/dist
+
+  deploy:
+    name: Deploy
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/publish.yml

@@ -13,11 +13,11 @@ jobs:
       pull-requests: write 
       id-token: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
           fetch-tags: true
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: 'lts/*'
 

.husky/pre-commit

@@ -1,2 +1,2 @@
+npx lint-staged
 npm test
-npx @biomejs/biome check --write --staged --no-errors-on-unmatched

.lintstagedrc

@@ -0,0 +1,3 @@
+{
+	"*.{js,jsx,ts,tsx,json,jsonc,md,mdx,css,yml,yaml}": "biome check --write --no-errors-on-unmatched"
+}

CONTRIBUTING.md

@@ -1,51 +1,47 @@
-# Contributing to `data-path`
+# Contributing
 
-First off, thank you for being here! 🎉 
+## Before you start
 
-I'm a solo maintainer working on this project in my free time, and I am thrilled that you want to help make it better. To keep things moving smoothly and respect everyone's time, I just have a few simple guidelines.
+**Bugs and typos:** open a pull request directly.
 
-## 💡 The Golden Rule: Let's talk first!
+**New features and significant changes:** open an issue first. Features need to fit the scope of the project and use an approach we agree on before significant implementation work begins.
 
-**Bugs & Typos:** Did you find a bug, a typo, or something broken? Feel free to open a Pull Request directly! No need to ask.
+## Local development
 
-**New Features & Big Changes:** Before you spend your valuable time writing code for a new feature, **please open an Issue first to discuss it.** 
-Why? Because I want to make sure your idea fits the vision of the project, doesn't duplicate ongoing work, and uses an architecture we agree on. I would hate to reject a massive PR that you spent hours on just because we didn't chat first!
+```bash
+git clone https://github.com/sergeyshmakov/data-path.git
+cd data-path
+npm ci
+npm run dev          # watch mode — rebuilds on save
+npm test             # run tests and type checks
+```
 
-## 🛠️ Local Development
+## Code style
 
-Setting up the project is super simple. We don't have a massive web of tools—just install and build!
+[Biome](https://biomejs.dev/) handles formatting and linting. The pre-commit hook runs automatically on `git commit`. To run it manually:
 
-1. **Fork & Clone** the repository.
-2. **Install dependencies:**
-   ```bash
-   npm ci
-   ```
-3. **Run the dev watcher:**
-   ```bash
-   npm run dev
-   ```
-   *This uses `tsup` to instantly rebuild the MCP server whenever you save a file.*
+```bash
+npm run lint:fix
+```
 
-## 🎨 Code Style (Zero Config!)
+## Commits
 
-You don't need to configure your editor, set up ESLint, or worry about formatting rules. We use **Biome**.
+This project uses [Conventional Commits](https://www.conventionalcommits.org/). The commit prefix determines the version bump:
 
-Just write your code naturally. When you are ready to commit, our Husky pre-commit hook will automatically format your files and fix any basic linting errors in milliseconds. 
+| Prefix | Release |
+|--------|---------|
+| `feat:` | Minor (1.1.0) |
+| `fix:` | Patch (1.0.1) |
+| `docs:`, `chore:`, `test:` | No release |
 
-If you want to run it manually before committing:
-```bash
-npm run lint:fix
-```
+Breaking changes use `feat!:` or a `BREAKING CHANGE:` footer in the commit body.
 
-## 📦 Committing & Publishing
+The commit message format is validated on commit. If the format is wrong, the commit is rejected with a helpful message.
 
-We use automated releases, which means your commit messages dictate the version numbers and the changelog. 
+## Release
 
-When you run `git commit`, you must use **Conventional Commits**:
-* `feat: added a new tool` (Triggers a Minor release, e.g., 1.1.0)
-* `fix: resolved crash on startup` (Triggers a Patch release, e.g., 1.0.1)
-* `docs: updated readme` (No release triggered)
+Merging to `main` triggers `semantic-release` — it determines the version from commit history, publishes to npm, and creates a GitHub release. No manual version bumps needed.
 
-*(Don't worry, if you format it wrong, the terminal will kindly reject the commit and ask you to fix it!)*
+## Code of Conduct
 
-Once your PR is merged into `main`, GitHub Actions will automatically compile the code, write the release notes, and publish the new version to NPM. You don't need to bump any version numbers in `package.json`.
+By participating you agree to abide by the [Code of Conduct](.github/CODE_OF_CONDUCT.md).

LICENSE

@@ -1,8 +1,22 @@
-ISC License (ISC)
+MIT License
 
 Copyright (c) 2026 Sergei Shmakov
 https://github.com/sergeyshmakov
 
-Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.