@minhduydev/mdpi 0.3.0

package/dist/template/.pi/skills/opensrc/references/cli-usage.md

@@ -0,0 +1,176 @@
+# opensrc CLI Reference
+
+## Contents
+- Fetch command (default)
+- List command
+- Remove command
+- Clean command
+- Global options
+
+## Fetch Command (Default)
+
+Fetch source for packages/repos.
+
+```bash
+opensrc [packages...] [options]
+```
+
+### Package Formats
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| `<name>` | `zod` | npm package (latest or installed version) |
+| `<name>@<version>` | `zod@3.22.0` | npm package at specific version |
+| `npm:<name>` | `npm:react` | Explicit npm prefix |
+| `pypi:<name>` | `pypi:requests` | Python package from PyPI |
+| `pip:<name>` | `pip:flask` | Alias for pypi: |
+| `crates:<name>` | `crates:serde` | Rust crate from crates.io |
+| `cargo:<name>` | `cargo:tokio` | Alias for crates: |
+
+### Repository Formats
+
+| Format | Example |
+|--------|---------|
+| `owner/repo` | `vercel/ai` |
+| `owner/repo@ref` | `vercel/ai@v1.0.0` |
+| `owner/repo#ref` | `vercel/ai#main` |
+| `github:owner/repo` | `github:facebook/react` |
+| `gitlab:owner/repo` | `gitlab:inkscape/inkscape` |
+| `https://github.com/...` | Full URL |
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--cwd <path>` | Working directory (default: cwd) |
+| `--modify` | Allow file modifications (skip prompt) |
+| `--modify=false` | Deny file modifications (skip prompt) |
+
+### Examples
+
+```bash
+# Single package
+opensrc zod
+
+# Multiple packages
+opensrc react react-dom next
+
+# Mixed registries
+opensrc zod pypi:requests crates:serde
+
+# Specific versions
+opensrc zod@3.22.0
+opensrc pypi:requests==2.31.0
+
+# GitHub repos
+opensrc vercel/ai
+opensrc facebook/react@v18.2.0
+```
+
+## List Command
+
+List all fetched sources.
+
+```bash
+opensrc list [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON |
+| `--cwd <path>` | Working directory |
+
+### Output
+
+Groups by registry (npm, PyPI, crates.io) and repos:
+
+```
+npm Packages:
+
+  zod@3.22.0
+    Path: opensrc/repos/github.com/colinhacks/zod
+    Fetched: Jan 10, 2025
+
+Repositories:
+
+  github.com/vercel/ai@main
+    Path: opensrc/repos/github.com/vercel/ai
+    Fetched: Jan 10, 2025
+
+Total: 1 package(s) (1 npm), 1 repo(s)
+```
+
+## Remove Command
+
+Remove specific sources.
+
+```bash
+opensrc remove <packages...> [options]
+opensrc rm <packages...>  # alias
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--cwd <path>` | Working directory |
+
+### Examples
+
+```bash
+opensrc remove zod
+opensrc rm pypi:requests
+opensrc remove vercel/ai
+```
+
+## Clean Command
+
+Remove all sources by category.
+
+```bash
+opensrc clean [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--packages` | Only remove packages (all registries) |
+| `--repos` | Only remove repos |
+| `--npm` | Only remove npm packages |
+| `--pypi` | Only remove PyPI packages |
+| `--crates` | Only remove crates.io packages |
+| `--cwd <path>` | Working directory |
+
+### Examples
+
+```bash
+opensrc clean              # Remove everything
+opensrc clean --packages   # Remove all packages, keep repos
+opensrc clean --npm        # Remove only npm packages
+opensrc clean --repos      # Remove only repos
+```
+
+## File Modifications
+
+On first run, prompts to modify:
+
+1. **`.gitignore`** - Adds `opensrc/` entry
+2. **`tsconfig.json`** - Adds `opensrc/` to exclude array
+3. **`AGENTS.md`** - Adds source code reference section
+
+Choice saved to `opensrc/settings.json`.
+
+### AGENTS.md Section
+
+Adds guidance for AI agents:
+
+```markdown
+<!-- opensrc:start -->
+## Source Code Reference
+Source code for dependencies is available in `opensrc/`...
+See `opensrc/sources.json` for the list of available packages.
+<!-- opensrc:end -->
+```

package/dist/template/.pi/skills/opensrc/references/registry-support.md

@@ -0,0 +1,137 @@
+# Registry Support
+
+## Contents
+- npm (Node.js)
+- PyPI (Python)
+- crates.io (Rust)
+- Repository hosts
+
+## npm (Node.js)
+
+**Prefixes:** `npm:` (or none - default)
+
+**API:** `https://registry.npmjs.org/{package}`
+
+### Version Detection
+
+Auto-detects installed version from (in order):
+1. `node_modules/{pkg}/package.json`
+2. `package-lock.json` (npm v6 and v7+ formats)
+3. `pnpm-lock.yaml`
+4. `yarn.lock`
+5. `package.json` dependencies (strips `^`, `~`, etc.)
+
+### Spec Parsing
+
+```
+zod           → name: zod, version: (detected or latest)
+zod@3.22.0    → name: zod, version: 3.22.0
+@babel/core   → name: @babel/core (scoped)
+@babel/core@7.0.0 → name: @babel/core, version: 7.0.0
+```
+
+### Repo URL Extraction
+
+From `repository` field, normalizes:
+- `git+https://...` → `https://...`
+- `git://...` → `https://...`
+- `git+ssh://git@...` → `https://...`
+- Removes `.git` suffix
+- Handles `github:owner/repo` shorthand
+
+### Monorepo Support
+
+Uses `repository.directory` field for packages in monorepos.
+Path becomes: `repos/{host}/{owner}/{repo}/{directory}`
+
+## PyPI (Python)
+
+**Prefixes:** `pypi:`, `pip:`, `python:`
+
+**API:** `https://pypi.org/pypi/{package}/json`
+
+### Spec Parsing
+
+```
+requests        → name: requests
+requests==2.31.0 → name: requests, version: 2.31.0
+requests@2.31.0  → name: requests, version: 2.31.0
+```
+
+### Repo URL Extraction
+
+Checks `project_urls` in order:
+1. `Source`, `Source Code`
+2. `Repository`, `GitHub`
+3. `Code`, `Homepage`
+
+Falls back to `home_page` if it's a git URL.
+
+## crates.io (Rust)
+
+**Prefixes:** `crates:`, `cargo:`, `rust:`
+
+**API:** `https://crates.io/api/v1/crates/{crate}`
+
+### Spec Parsing
+
+```
+serde       → name: serde
+serde@1.0.0 → name: serde, version: 1.0.0
+```
+
+### Repo URL Extraction
+
+Uses `repository` field, falls back to `homepage` if it's a git URL.
+
+## Repository Hosts
+
+### GitHub
+
+**API:** `https://api.github.com/repos/{owner}/{repo}`
+
+Resolves default branch, constructs clone URL.
+
+**Rate limiting:** 60 req/hour unauthenticated. Error on 403.
+
+### GitLab
+
+**API:** `https://gitlab.com/api/v4/projects/{owner}%2F{repo}`
+
+Resolves default branch, constructs clone URL.
+
+### Bitbucket
+
+Supported for parsing (`bitbucket:owner/repo`), but no API resolution.
+Assumes `main` as default branch.
+
+## Repo Spec Formats
+
+| Format | Example | Host |
+|--------|---------|------|
+| `owner/repo` | `vercel/ai` | github.com |
+| `github:owner/repo` | `github:facebook/react` | github.com |
+| `gitlab:owner/repo` | `gitlab:inkscape/inkscape` | gitlab.com |
+| `bitbucket:owner/repo` | `bitbucket:atlassian/python-bitbucket` | bitbucket.org |
+| `host/owner/repo` | `gitlab.com/owner/repo` | (from URL) |
+| Full URL | `https://github.com/...` | (from URL) |
+
+## Ref Specifications
+
+Append to repo spec:
+
+| Suffix | Example | Meaning |
+|--------|---------|---------|
+| `@ref` | `owner/repo@v1.0.0` | Tag, branch, or commit |
+| `#ref` | `owner/repo#main` | Branch (alternative syntax) |
+
+URL paths also supported: `https://github.com/owner/repo/tree/branch`
+
+## Git Tag Patterns
+
+When cloning packages, tries tags in order:
+1. `v{version}` - Most common (e.g., `v3.22.0`)
+2. `{version}` - No prefix (e.g., `3.22.0`)
+3. Default branch - Fallback with warning
+
+Uses `--depth 1 --single-branch` for efficient cloning.