lcp 1.0.1__tar.gz

lcp-1.0.1/.claude/skills/git-commit-convention/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: git-commit-convention
+description: Use when creating any git commit - enforces structured commit messages with a 3-letter action code, title, and description following the project convention
+---
+
+# Git Commit Convention
+
+## Overview
+
+All commits in this project MUST follow the format: `CODE: Title` with a descriptive body.
+
+**Core principle:** Every commit message clearly communicates WHAT action was taken and WHY through a structured, scannable format.
+
+**Violating the letter of this convention is violating the spirit of this convention.**
+
+## The Iron Law
+
+```
+NO COMMIT WITHOUT A PROPERLY FORMATTED MESSAGE
+```
+
+## Commit Message Format
+
+```
+CODE: Short descriptive title (imperative mood, max ~72 chars)
+
+Detailed description of what was done and why.
+Context, motivation, and any relevant details.
+```
+
+**Never insert co-authors.**
+
+## Action Codes
+
+| Code | Meaning | Use When |
+|------|---------|----------|
+| `ADD` | Addition | New files, features, dependencies, or capabilities |
+| `UPD` | Update | Enhancements, modifications to existing functionality |
+| `FIX` | Fix | Bug fixes, error corrections, broken behavior |
+| `DEL` | Delete | Removing files, features, dead code, dependencies |
+| `DOC` | Documentation | README, comments, docstrings, CHANGELOG |
+| `REF` | Refactor | Code restructuring without behavior change |
+| `TST` | Test | Adding or updating tests |
+| `STY` | Style | Formatting, linting, whitespace (no logic change) |
+| `CFG` | Config | Configuration files, environment, build settings |
+| `SEC` | Security | Security patches, vulnerability fixes, auth changes |
+| `DEP` | Dependency | Dependency upgrades, additions, removals |
+| `MRG` | Merge | Merging branches, resolving merge conflicts |
+| `WIP` | Work in Progress | Incomplete work saved to branch (never on main) |
+
+## Examples
+
+### Good
+
+```
+ADD: User authentication with JWT tokens
+
+Implement JWT-based auth system with login/logout endpoints,
+token refresh, and role-based access control middleware.
+```
+
+```
+FIX: Payslip parser failing on multi-page PDFs
+
+The Azure CU response handler assumed single-page output.
+Updated to iterate all pages and merge extracted fields.
+```
+
+```
+REF: Extract payslip validation into dedicated service
+
+Moved validation logic from workflow into PayslipValidator
+service class to improve testability and separation of concerns.
+```
+
+```
+DEL: Remove legacy CSV export endpoint
+
+CSV export was replaced by the JSON export in v2.1.
+Endpoint had no consumers for 3 months per access logs.
+```
+
+```
+CFG: Add CORS configuration for staging environment
+
+Added staging domain to allowed origins in FastAPI middleware
+to support the new staging deployment pipeline.
+```
+
+### Bad
+
+```
+# Missing code
+Updated stuff
+
+# Vague title
+UPD: Changes
+
+# Wrong code (this is a fix, not an update)
+UPD: Fix login crash on empty password
+
+# No description
+ADD: New component
+```
+
+## Rules
+
+1. **Code is mandatory** - Every commit starts with a 3-letter code from the table above
+2. **Title is imperative** - "Add feature" not "Added feature" or "Adding feature"
+3. **Title is concise** - Max ~72 characters including the code prefix
+4. **Description is required** - Explain the what and why, not just restate the title
+5. **One code per commit** - If work spans multiple codes, split into multiple commits
+6. **Choose the most specific code** - `SEC` over `FIX` for security fixes, `TST` over `ADD` for test files
+
+## Choosing the Right Code
+
+```
+Is it brand new?
+  Yes → ADD
+  No ↓
+Is something removed?
+  Yes → DEL
+  No ↓
+Is it fixing broken behavior?
+  Yes → Is it a security issue?
+    Yes → SEC
+    No → FIX
+  No ↓
+Is it changing how code is organized (no behavior change)?
+  Yes → Is it formatting/whitespace only?
+    Yes → STY
+    No → REF
+  No ↓
+Is it modifying existing behavior or features?
+  Yes → UPD
+  No ↓
+Is it only documentation?
+  Yes → DOC
+  No ↓
+Is it only tests?
+  Yes → TST
+  No ↓
+Is it config/build/environment?
+  Yes → CFG
+  No ↓
+Is it dependency changes only?
+  Yes → DEP
+  No ↓
+Is it a branch merge or merge conflict resolution?
+  Yes → MRG
+  No → Pick the most dominant action
+```
+
+## Red Flags - STOP
+
+- Commit message without a code prefix
+- Using a code not in the table
+- Title longer than 72 characters
+- Empty or missing description
+- Code that doesn't match the actual changes
+- Multiple unrelated changes in one commit (split them)
+
+## When to Apply
+
+**ALWAYS** - this skill applies to every single `git commit` in this project. No exceptions.

lcp-1.0.1/.claude/skills/lcp-writing-documentation/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: lcp-writing-documentation
+description: Use when writing or updating documentation for the LCP project — new functionality requires docs, existing docs need updating after a feature change, documentation must be created or reorganized in the docs/ folder, or a significant system behavior or data flow changes. Authoritative guideline for LCP documentation conventions (architecture docs, user-facing guides, and the auto-generated API reference).
+---
+
+# Writing Documentation
+
+## Overview
+
+All documentation lives under `docs/`, which is the MkDocs source tree (`docs_dir: docs`) published to GitHub Pages. The folder holds **three kinds of documentation with different conventions** — pick the right area first, then follow its rules.
+
+**Core principle:** Match the conventions of the area you are writing in. The strict "concepts not code" rules apply to architecture docs; user-facing guides and the auto-generated API reference follow their own conventions.
+
+**Violating the letter of these rules is violating the spirit of these rules.**
+
+## Documentation Map
+
+| Area | Location | Audience | Conventions | Code snippets? |
+|------|----------|----------|-------------|----------------|
+| **Architecture** | `docs/architecture/` | Contributors / maintainers | `snake_case` folders, `index.md` + `architecture.md` per topic, this skill's strict rules | **No** — refer to objects by name |
+| **User-facing** | `docs/guides/`, `docs/spec/`, `docs/introduction.md`, `docs/quickstart.md`, `docs/cli.md` | Users of the SDK/CLI | `kebab-case.md`, task-oriented prose | **Yes** — bash/CLI/Python examples expected |
+| **API Reference** | `docs/api/` | Users browsing the public API | Auto-generated by mkdocstrings from docstrings | N/A — **do not hand-write** |
+
+```
+docs/
+├── index.md                 # Site home (user-facing landing page)
+├── introduction.md          # User-facing
+├── quickstart.md            # User-facing
+├── cli.md                   # User-facing
+├── guides/                  # User-facing how-tos (kebab-case)
+├── spec/                    # LCP specification (user-facing)
+├── api/                     # Auto-generated API reference (mkdocstrings)
+└── architecture/            # ← THIS SKILL'S PRIMARY DOMAIN
+    ├── index.md             # Architecture overview + table of contents
+    └── topic_name/          # snake_case (e.g. manifest, mcp_server, ai_docgen)
+        ├── index.md         # Topic overview + section table of contents
+        └── architecture.md  # System design, data flow, internals
+```
+
+Adding a doc to the site nav requires an entry in `mkdocs.yml` under the matching section, regardless of area.
+
+---
+
+## Architecture Docs (`docs/architecture/`)
+
+This is what this skill primarily governs: conceptual, design-level documentation for contributors. It focuses on concepts, data flows, and component relationships — **not** implementation code. The audience can read source code themselves.
+
+### When to Write or Update
+
+- New major feature or system is implemented
+- Core functionality changes behavior or architecture
+- Data flow between components changes significantly
+- New integrations or external dependencies are added
+- Existing documented behavior is modified or removed
+
+**Do NOT create architecture docs for:**
+
+- Minor bug fixes or cosmetic changes
+- Internal refactors that don't change behavior or interfaces
+- Trivial configuration changes
+
+### File Conventions
+
+| Rule | Convention |
+|------|-----------|
+| Location | Under `docs/architecture/` |
+| Format | Markdown (`.md`), mkdocs-compatible |
+| Naming | `snake_case` folders; files are `index.md` and `architecture.md` |
+| Organization | Topic-based subfolders (e.g., `docs/architecture/manifest/`, `docs/architecture/mcp_server/`) |
+
+### Index Files
+
+Every architecture folder MUST have an `index.md` containing:
+
+1. **Overview** — Brief description of what this section covers
+2. **Key features** — Bullet list of main capabilities (if applicable)
+3. **Table of contents** — Links to all documents in the folder with one-line descriptions
+4. **Key components table** — Component name, location (file path), and purpose
+5. **Related documentation** — Cross-references to related sections
+
+**Maintenance rule:** When adding or removing an architecture document, ALWAYS update:
+
+- The folder's `index.md`
+- The architecture root `docs/architecture/index.md`
+- The `mkdocs.yml` nav (under the `Architecture` section)
+
+**No exceptions.** An orphaned document with no index entry is a documentation bug.
+
+### Document Structure
+
+```markdown
+# Document Title
+
+## Overview
+Brief description of the topic (2-3 sentences max).
+
+## [Core Sections]
+Organized by the topic's natural structure.
+
+## Related Documentation
+Cross-references to related documents.
+
+---
+**Last Updated:** Month Year
+**Status:** Implemented | In Progress | Planned
+```
+
+### Content Guidelines
+
+**DO**
+
+- Write clear, concise prose accessible to developers of all levels
+- Describe functional behavior and data flows
+- Use tables for structured reference data (components, configurations)
+- Use Mermaid diagrams for architecture, data flows, and component relationships
+- Reference classes, functions, and files by name and path
+- Cross-reference related documentation sections
+- Explain the WHY behind design decisions
+
+**DO NOT**
+
+- Include code snippets or source code blocks
+- Copy-paste implementation details
+- Write tutorials or step-by-step coding guides
+- Document obvious behavior that the code itself makes clear
+- Duplicate information that belongs in README or project config files
+
+### Referring to Code Objects
+
+Instead of embedding code, refer to objects by their qualified name and location.
+
+**Bad:** A 10-line code block showing how to call a service method.
+
+**Good:** "Scanning is handled by `scan_package()` in `src/lcp/scanner.py`, which imports the package and walks its modules with `inspect`, producing a `ScannedModule`."
+
+The developer reading this can open the file and understand the implementation. The documentation's job is to explain the concept, purpose, and context — not to replicate the code.
+
+### Diagrams
+
+Use [Mermaid](https://mermaid.js.org/) to illustrate architecture and data flows. Declare diagrams in a fenced code block with the `mermaid` language identifier (rendered natively on the MkDocs site and in GitHub Markdown).
+
+**Flowcharts** — for component interactions, data pipelines, and decision flows:
+
+```mermaid
+flowchart LR
+    A[Component A] --> B[Component B]
+    A --> C[Component C]
+    B --> D[(Storage)]
+    C --> D
+```
+
+**Sequence diagrams** — for request/response cycles and multi-service interactions:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant ServiceA
+    participant ServiceB
+    Client->>ServiceA: request
+    ServiceA->>ServiceB: forward
+    ServiceB-->>ServiceA: response
+    ServiceA-->>Client: result
+```
+
+| Type | Mermaid keyword | Best for |
+|------|-----------------|---------|
+| Flowchart | `flowchart` | Component topology, data pipelines, decision trees |
+| Sequence | `sequenceDiagram` | API calls, multi-service request flows |
+| Class | `classDiagram` | Data models, inheritance hierarchies |
+| State | `stateDiagram-v2` | Lifecycle states, status transitions |
+| Entity-Relationship | `erDiagram` | Database schemas, domain models |
+
+Use a diagram when multiple components interact in a non-obvious way, data transforms across several layers, or a chain spans services.
+
+### Tables for Reference Data
+
+Use tables for component inventories and configuration:
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `scan_package` | `src/lcp/scanner.py` | Introspects an installed package into `ScannedModule` |
+
+### Architecture Quality Checklist
+
+- [ ] File is `index.md` or `architecture.md` in a `snake_case` topic folder under `docs/architecture/`
+- [ ] Folder's `index.md` updated with link and description
+- [ ] `docs/architecture/index.md` updated if a new topic or document was added
+- [ ] `mkdocs.yml` nav updated under the `Architecture` section
+- [ ] **No code snippets** — only references to objects, classes, and file paths
+- [ ] Data flows use Mermaid diagrams where helpful (fenced ` ```mermaid ` block)
+- [ ] Tables used for structured reference data
+- [ ] Cross-references to related docs included
+- [ ] Footer has "Last Updated" and "Status"
+
+---
+
+## User-facing Docs (`docs/guides/`, `docs/spec/`, getting started)
+
+These are written FOR users of the SDK and CLI, not contributors. Conventions differ from architecture docs:
+
+- **Naming:** `kebab-case.md` (e.g., `mcp-server.md`, `ai-docgen.md`).
+- **Code is expected:** include `bash`, CLI, and Python examples — users need copy-pasteable commands.
+- **Task-oriented:** show how to accomplish a goal step by step.
+- **No "Last Updated/Status" footer** — these pages are living user docs.
+- **Nav:** add new pages to `mkdocs.yml` under `Get Started`, `Guides`, or `Specification`.
+
+When in doubt about depth, link to the relevant `docs/architecture/` page rather than duplicating internals.
+
+---
+
+## API Reference (`docs/api/`)
+
+The API reference is **auto-generated by mkdocstrings** from the source docstrings — do not hand-write API descriptions here.
+
+- Each page is a thin stub with a `::: lcp.<module>` directive; the content comes from docstrings in `src/lcp/`.
+- To improve the rendered reference, **edit the docstrings in the source code**, not the markdown.
+- To document a new public module, add a stub page in `docs/api/` and a nav entry under `API Reference` in `mkdocs.yml`.
+
+---
+
+## Red Flags — STOP and Revise
+
+- Writing in `docs/architecture/` and about to paste a code block → refer to the object by name instead
+- Architecture document has no entry in its folder's `index.md` → update the index first
+- Architecture file/folder uses camelCase or kebab-case → use `snake_case` (files are `index.md`/`architecture.md`)
+- Guide uses `snake_case.md` → rename to `kebab-case.md`
+- Hand-writing API descriptions in `docs/api/` → edit the source docstring instead
+- Added any page but forgot the `mkdocs.yml` nav entry → add it
+- Content duplicates another document → cross-reference instead
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Adding an architecture doc but forgetting the index | Update folder `index.md` AND `docs/architecture/index.md` |
+| Adding any page but forgetting the nav | Update the matching section in `mkdocs.yml` |
+| Code snippets in architecture docs | Replace with prose describing the object and its parameters |
+| Editing `docs/api/*.md` to fix API wording | Edit the docstring in `src/lcp/` instead |
+| Mixing user-facing and architecture conventions | Decide the area first (see Documentation Map), then follow its rules |
+| Flat file dump in `docs/architecture/` | Group related files into `snake_case` topic subfolders |

lcp-1.0.1/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "lcp",
+  "owner": {
+    "name": "Andrea Zanini",
+    "email": "andrea.za94@gmail.com"
+  },
+  "description": "Library Context Protocol — universal Python library documentation for AI coding agents.",
+  "plugins": [
+    {
+      "name": "lcp",
+      "source": "./plugin/lcp",
+      "description": "Universal Python library documentation for AI coding agents via the Library Context Protocol. Resolves any pip-installed package on demand through browsable MCP tools.",
+      "category": "documentation",
+      "tags": ["python", "mcp", "documentation", "api-introspection", "lcp"],
+      "homepage": "https://github.com/zazza123/lcp",
+      "repository": "https://github.com/zazza123/lcp",
+      "license": "MIT"
+    }
+  ]
+}

lcp-1.0.1/.github/CODEOWNERS

@@ -0,0 +1,10 @@
+# Code owners for the lcp repository.
+#
+# When a PR touches a matching path, GitHub auto-requests review from the
+# listed owners. Pairs with branch protection's "Require review from Code
+# Owners" option.
+#
+# Syntax reference: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+# Default owner for everything in the repo.
+* @zazza123

lcp-1.0.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,98 @@
+name: Bug report
+description: Report something that is broken or behaves unexpectedly in lcp.
+title: "[Bug]: "
+labels: ["bug", "status:needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report! Please fill in the
+        fields below so the issue can be triaged quickly.
+
+        For **security vulnerabilities**, do not use this form — report
+        privately via
+        [GitHub Security Advisories](https://github.com/zazza123/lcp/security/advisories/new).
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: A clear, one-paragraph description of what is wrong.
+      placeholder: Calling `lcp scan foo` raises a `TypeError` on Python 3.12.
+    validations:
+      required: true
+
+  - type: input
+    id: lcp-version
+    attributes:
+      label: lcp version
+      description: Output of `lcp --version` or `pip show lcp | grep -i version`.
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: Output of `python --version`.
+      placeholder: "Python 3.12.4"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      description: e.g. macOS 14.5, Ubuntu 22.04, Windows 11.
+      placeholder: "macOS 14.5"
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproducer
+    attributes:
+      label: Minimal reproducer
+      description: |
+        A command, code snippet, or pointer to a small repo that reproduces
+        the problem. Smaller is better.
+      render: shell
+      placeholder: |
+        $ lcp scan requests -o requests.lcp.json
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Full traceback (if any)
+      description: Paste the complete stack trace. No need to truncate.
+      render: shell
+    validations:
+      required: false
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Additional context
+      description: |
+        Anything else that might be relevant — related packages, virtualenv
+        details, recent changes, screenshots, etc.
+    validations:
+      required: false

lcp-1.0.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/zazza123/lcp/security/advisories/new
+    about: Report a security issue privately via GitHub Security Advisories.
+  - name: Question or discussion
+    url: https://github.com/zazza123/lcp/discussions
+    about: Use Discussions for usage questions or design conversations.

lcp-1.0.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,65 @@
+name: Feature request
+description: Suggest a new capability, API, or improvement for lcp.
+title: "[Feature]: "
+labels: ["feature", "status:needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for proposing an improvement! Filling in the fields below
+        helps reach a decision faster. For broader design discussions,
+        consider opening a
+        [GitHub Discussion](https://github.com/zazza123/lcp/discussions)
+        first.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What is hard or impossible today? Who is affected and why?
+      placeholder: |
+        When scanning packages with namespace subpackages, the resulting
+        manifest does not include ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: |
+        How should `lcp` solve this? Describe the user-visible behaviour,
+        new CLI flag / API, or change in output.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: |
+        Other approaches you thought about and why you rejected them. Even
+        a short note here helps avoid re-litigating during review.
+    validations:
+      required: true
+
+  - type: textarea
+    id: example
+    attributes:
+      label: Example usage
+      description: |
+        A short CLI invocation or Python API sketch showing how the feature
+        would be used in practice.
+      render: shell
+      placeholder: |
+        $ lcp scan mypkg --include-namespaces -o mypkg.lcp.json
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Additional context
+      description: Links to related issues, prior art, or relevant background.
+    validations:
+      required: false

lcp-1.0.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,22 @@
+## Summary
+
+<!-- One paragraph describing what this PR changes and why. Focus on the
+"why" — the diff already shows the "what". -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor / code cleanup
+- [ ] Documentation
+- [ ] Tests
+- [ ] Other:
+
+## Checklist
+
+- [ ] Linked issue: closes #
+- [ ] Tests added or updated
+- [ ] Documentation updated (README / docs / docstrings)
+- [ ] `ruff check src/lcp tests` passes locally
+- [ ] `pytest` passes locally
+- [ ] Commit messages follow the project convention (`CODE: title`)