Skip to content

Commit 4844ebe

Browse files
oritwoenoritwoen
committed
chore: add AGENTS.md files
1 parent 44b1a3e commit 4844ebe

File tree

7 files changed

+305
-0
lines changed

7 files changed

+305
-0
lines changed

‎AGENTS.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# PROJECT KNOWLEDGE BASE
2+
3+
**Generated:** 2026-03-05T10:50:45Z
4+
**Commit:** 44b1a3e
5+
**Branch:** main
6+
7+
## OVERVIEW
8+
unpux is an ESM-only TypeScript library + CLI that normalizes package metadata across npm, PyPI, crates.io, RubyGems, and Packagist using PURL-first APIs.
9+
The architecture is layered: `core` abstractions, per-ecosystem `registries`, optional `cache` decorator, and CLI `commands`.
10+
11+
## STRUCTURE
12+
```text
13+
pkio/
14+
|- src/ # source modules and entrypoints
15+
| |- core/ # contracts, parsing, client, errors
16+
| |- registries/ # ecosystem adapters
17+
| |- cache/ # storage and lockfile caching
18+
| |- commands/ # citty command handlers
19+
| |- index.ts # public API barrel
20+
| `- cli.ts # executable entrypoint
21+
|- test/ # unit + e2e tests
22+
|- .github/workflows/ # CI and publish workflows
23+
`- build.config.ts # obuild entry matrix
24+
```
25+
26+
## WHERE TO LOOK
27+
| Task | Location | Notes |
28+
|------|----------|-------|
29+
| Public API changes | `src/index.ts` | Main export surface used by package root `.` |
30+
| Add ecosystem support | `src/registries/*.ts` | Implement `Registry`, then register via side-effect import |
31+
| PURL behavior | `src/core/purl.ts` | Validation, normalization, parser/builder |
32+
| HTTP/retry behavior | `src/core/client.ts` | Retry status handling and timeout defaults |
33+
| Cache semantics | `src/cache/lockfile.ts` | TTL + integrity freshness gates |
34+
| CLI command behavior | `src/commands/*.ts`, `src/cli.ts` | Dynamic subcommand loading through citty |
35+
| Test updates | `test/unit/*.test.ts`, `test/e2e/smoke.test.ts` | Unit first; e2e for live registry checks |
36+
| Build/export wiring | `build.config.ts`, `package.json` | Entry points, exports, bin wiring |
37+
38+
## CODE MAP
39+
| Symbol | Type | Location | Refs | Role |
40+
|--------|------|----------|------|------|
41+
| `create` | function | `src/core/registry.ts` | high | Registry factory from ecosystem key |
42+
| `createCached` | function | `src/cache/index.ts` | medium | Decorates a registry with cache + lockfile |
43+
| `parsePURL` | function | `src/core/purl.ts` | high | Canonical parser for all PURL input |
44+
| `Client` | class | `src/core/client.ts` | high | Central HTTP behavior, retry, timeout |
45+
| `CachedRegistry` | class | `src/cache/cached-registry.ts` | medium | Cache wrapper implementing `Registry` |
46+
| `main` | constant command | `src/cli.ts` | medium | CLI root with subcommand routing |
47+
| `DEFAULT_TTL` | constant | `src/cache/lockfile.ts` | medium | Project-wide cache freshness policy |
48+
49+
## CONVENTIONS
50+
- ESM-only; TypeScript imports keep `.ts` extension style in source.
51+
- `tsc` is typecheck-only (`noEmit`); build artifacts come from `obuild`.
52+
- Public API is export-barrel-driven; avoid hidden side-channel exports.
53+
- Registries are plugin-like via registration factories, not hardcoded switch logic.
54+
- Tests use Vitest globals with `test/unit` and `test/e2e` split.
55+
56+
## ANTI-PATTERNS (THIS PROJECT)
57+
- Do not parse PURLs outside `src/core/purl.ts`; call `createFromPURL`/`parsePURL`.
58+
- Do not bypass `Client` for direct fetch logic in registries.
59+
- Do not duplicate retry/backoff constants outside `src/core/client.ts`.
60+
- Do not hardcode cache TTL in random modules; use `DEFAULT_TTL` in `src/cache/lockfile.ts`.
61+
- Do not add CommonJS output or `require` paths; package is ESM-first.
62+
63+
## UNIQUE STYLES
64+
- Side-effect ecosystem registration is intentional (`import 'unpux/registries'`).
65+
- `cache` is an optional decorator layer, not mandatory in core flows.
66+
- Bulk fetch helpers intentionally skip failed packages instead of failing all.
67+
68+
## COMMANDS
69+
```bash
70+
pnpm typecheck
71+
pnpm build
72+
pnpm test:run
73+
pnpm test
74+
pnpm release
75+
```
76+
77+
## NOTES
78+
- Release workflow triggers on tags `v*` and publishes with `pnpm publish --no-git-checks`.
79+
- Node runtime floor is `>=22.6.0`; respect modern syntax assumptions.
80+
- Unit tests are broad; e2e smoke tests can be network-sensitive.

‎src/AGENTS.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# SOURCE GUIDE
2+
3+
## OVERVIEW
4+
`src/` is the implementation boundary: core contracts, ecosystem adapters, cache decorator, CLI commands, and top-level export barrels.
5+
6+
## STRUCTURE
7+
```text
8+
src/
9+
|- core/ # primitives and shared contracts
10+
|- registries/ # ecosystem implementations
11+
|- cache/ # storage + freshness metadata
12+
|- commands/ # CLI command handlers
13+
|- index.ts # package public API barrel
14+
|- helpers.ts # high-level PURL helpers
15+
|- cli.ts # executable command root
16+
`- types.ts # root type re-exports
17+
```
18+
19+
## WHERE TO LOOK
20+
| Task | Location | Notes |
21+
|------|----------|-------|
22+
| Extend public exports | `src/index.ts` | Keep grouping order stable (Core, Errors, Helpers, Types, Cache) |
23+
| Add convenience API | `src/helpers.ts` | Wrap `createFromPURL`; preserve normalization path |
24+
| Add CLI command | `src/commands/*.ts` + `src/cli.ts` | Command file + dynamic import wiring |
25+
| Add ecosystem adapter | `src/registries/*.ts` | Register through factory + side-effect import hub |
26+
| Change shared models | `src/core/types.ts` | Impacts all registries and helpers |
27+
28+
## CONVENTIONS
29+
- Direction is inward: commands/registries/cache depend on `core`, not the reverse.
30+
- Use `.ts` import suffixes consistently.
31+
- Keep barrels (`src/index.ts`, `src/core/index.ts`, `src/cache/index.ts`) as canonical export surfaces.
32+
33+
## ANTI-PATTERNS
34+
- Do not duplicate parsing logic in commands/helpers; route through `createFromPURL`.
35+
- Do not implement fetch/retry behavior outside `src/core/client.ts`.
36+
- Do not make cache mandatory for base registry usage.

‎src/cache/AGENTS.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# CACHE GUIDE
2+
3+
## OVERVIEW
4+
`src/cache` is an optional decorator subsystem that adds storage-backed reads and lockfile freshness checks around registry operations.
5+
6+
## STRUCTURE
7+
```text
8+
src/cache/
9+
|- cached-registry.ts # registry decorator with cache read/write flow
10+
|- lockfile.ts # freshness metadata + TTL + integrity
11+
|- storage.ts # unstorage setup and lifecycle
12+
|- paths.ts # OS-specific cache directory selection
13+
`- index.ts # cache public exports + createCached
14+
```
15+
16+
## WHERE TO LOOK
17+
| Task | Location | Notes |
18+
|------|----------|-------|
19+
| Cache wrapper behavior | `src/cache/cached-registry.ts` | Read-through/write-through wrapper for `Registry` |
20+
| Freshness and TTL policy | `src/cache/lockfile.ts` | `DEFAULT_TTL`, integrity, stale pruning |
21+
| Storage lifecycle | `src/cache/storage.ts` | Global storage config + disposal/clear hooks |
22+
| Platform path behavior | `src/cache/paths.ts` | Linux/macOS/Windows cache directory rules |
23+
| Public cache entry points | `src/cache/index.ts` | Exports + `createCached` convenience API |
24+
25+
## CONVENTIONS
26+
- Cache is optional; uncached path must remain first-class.
27+
- Lockfile integrity hash gates cache reuse.
28+
- `createCached` composes core registry creation with `CachedRegistry`.
29+
30+
## ANTI-PATTERNS
31+
- Do not hardcode TTL values outside `lockfile.ts`.
32+
- Do not bypass lockfile freshness checks for cached reads.
33+
- Do not assume filesystem-only storage; keep `unstorage` driver compatibility.
34+
35+
## NOTES
36+
- Corrupt or stale entries fail soft and trigger network fallback.
37+
- Keep cache-key format stable; lockfile compatibility depends on it.

‎src/commands/AGENTS.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# COMMANDS GUIDE
2+
3+
## OVERVIEW
4+
`src/commands` defines CLI subcommands and shared command utilities on top of core/helpers/cache layers.
5+
6+
## STRUCTURE
7+
```text
8+
src/commands/
9+
|- shared.ts # shared args, PURL resolver, error wrapper
10+
|- info.ts # package metadata command
11+
|- versions.ts # versions list command
12+
|- deps.ts # dependencies command (versioned)
13+
|- maintainers.ts # maintainer listing command
14+
`- cache.ts # cache status/path/clear/prune
15+
```
16+
17+
## WHERE TO LOOK
18+
| Task | Location | Notes |
19+
|------|----------|-------|
20+
| Shared argument flags | `src/commands/shared.ts` | `--json` and `--no-cache` handling |
21+
| PURL input resolution | `src/commands/shared.ts` | Optional `pkg:` prefix normalization |
22+
| `info` output flow | `src/commands/info.ts` | Package metadata command |
23+
| `versions` output flow | `src/commands/versions.ts` | Version list command |
24+
| `deps` output flow | `src/commands/deps.ts` | Version-specific dependency command |
25+
| `maintainers` output flow | `src/commands/maintainers.ts` | Maintainer listing command |
26+
| Cache maintenance commands | `src/commands/cache.ts` | status/path/clear/prune subcommands |
27+
28+
## CONVENTIONS
29+
- Commands are thin orchestration layers; domain logic stays in core/cache/helpers.
30+
- Wrap command bodies with shared error handling helpers.
31+
- Keep output dual-mode (`human` + `--json`).
32+
33+
## ANTI-PATTERNS
34+
- Do not reimplement PURL parsing in individual command files.
35+
- Do not mutate cache internals directly from commands; use cache API.
36+
- Do not bypass shared argument definitions for common flags.
37+
38+
## NOTES
39+
- `src/cli.ts` owns subcommand registration; keep command files focused on execution.
40+
- For new command output, maintain parity between human-readable and `--json` branches.

‎src/core/AGENTS.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# CORE GUIDE
2+
3+
## OVERVIEW
4+
`src/core` defines the stable contract layer: types, errors, PURL parser, registry factory, client behavior, and normalization helpers.
5+
6+
## STRUCTURE
7+
```text
8+
src/core/
9+
|- client.ts # HTTP, retries, timeout, rate limiter hook
10+
|- registry.ts # factory registry (`register`/`create`)
11+
|- purl.ts # parse/build PURL pipeline
12+
|- errors.ts # typed error hierarchy
13+
|- types.ts # shared cross-module contracts
14+
|- license.ts # SPDX normalization utilities
15+
|- repository.ts # repository URL cleanup
16+
`- index.ts # core barrel exports
17+
```
18+
19+
## WHERE TO LOOK
20+
| Task | Location | Notes |
21+
|------|----------|-------|
22+
| Registry creation flow | `src/core/registry.ts` | `register` + `create` map-based factory |
23+
| PURL parse/build behavior | `src/core/purl.ts` | Single source of truth for validation and normalization |
24+
| HTTP retries/timeouts | `src/core/client.ts` | Shared retry status list and backoff policy |
25+
| Type-level contract updates | `src/core/types.ts` | Changes cascade to all adapters and CLI |
26+
| Domain-specific errors | `src/core/errors.ts` | Throw these classes from adapters/helpers |
27+
| URL normalization | `src/core/repository.ts` | Canonical repository link cleanup |
28+
29+
## CONVENTIONS
30+
- Throw typed errors (`InvalidPURLError`, `NotFoundError`, `RateLimitError`) instead of plain `Error` in core flows.
31+
- `Client` owns network behavior defaults (`maxRetries`, `timeout`, retry codes).
32+
- `VersionStatus` and `Scope` are closed unions; keep adapter outputs inside allowed values.
33+
34+
## ANTI-PATTERNS
35+
- No direct registry-specific assumptions in core modules.
36+
- No duplicate PURL parsing utilities outside `purl.ts`.
37+
- No hardcoded HTTP behavior in adapters when client defaults exist.
38+
39+
## NOTES
40+
- Keep core adapter-agnostic; keep ecosystem details in `src/registries`.
41+
- Assume changes to `types.ts` require updates in tests and multiple adapters.

‎src/registries/AGENTS.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# REGISTRIES GUIDE
2+
3+
## OVERVIEW
4+
`src/registries` contains ecosystem adapters implementing a common `Registry` contract and normalizing foreign API payloads into shared core types.
5+
6+
## STRUCTURE
7+
```text
8+
src/registries/
9+
|- index.ts # side-effect registration hub
10+
|- npm.ts # npm adapter
11+
|- pypi.ts # PyPI adapter
12+
|- cargo.ts # crates.io adapter
13+
|- rubygems.ts # RubyGems adapter
14+
`- packagist.ts # Packagist adapter
15+
```
16+
17+
## WHERE TO LOOK
18+
| Task | Location | Notes |
19+
|------|----------|-------|
20+
| Register all ecosystems | `src/registries/index.ts` | Side-effect import hub |
21+
| npm adapter behavior | `src/registries/npm.ts` | Largest implementation; good pattern baseline |
22+
| Python package behavior | `src/registries/pypi.ts` | Name normalization and metadata mapping |
23+
| Cargo crate behavior | `src/registries/cargo.ts` | crates.io-specific dependency mapping |
24+
| RubyGems behavior | `src/registries/rubygems.ts` | Maintainer/license mapping nuances |
25+
| Packagist behavior | `src/registries/packagist.ts` | Composer ecosystem parsing |
26+
27+
## CONVENTIONS
28+
- Each adapter exposes `ecosystem`, `fetchPackage`, `fetchVersions`, `fetchDependencies`, `fetchMaintainers`, `urls`.
29+
- Convert source-specific fields into core `Package`/`Version`/`Dependency`/`Maintainer` shapes.
30+
- Map remote API failures to core error classes.
31+
- Keep adapter internals self-contained; no adapter-to-adapter imports.
32+
33+
## ANTI-PATTERNS
34+
- Do not call `fetch` directly; use `Client`.
35+
- Do not return raw upstream payloads through public methods.
36+
- Do not skip registration wiring; new adapter must be imported in `index.ts`.
37+
38+
## NOTES
39+
- `npm.ts` is the largest adapter and a reliable local reference for new adapter patterns.
40+
- Keep per-registry quirks isolated to that file; normalize before returning shared types.

‎test/AGENTS.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# TEST GUIDE
2+
3+
## OVERVIEW
4+
`test/` is split into deterministic unit coverage and live-network e2e smoke checks under Vitest projects.
5+
6+
## STRUCTURE
7+
```text
8+
test/
9+
|- unit/ # focused unit suites per module
10+
`- e2e/ # smoke tests against live registries
11+
```
12+
13+
## WHERE TO LOOK
14+
| Task | Location | Notes |
15+
|------|----------|-------|
16+
| PURL contract tests | `test/unit/purl.test.ts` | Parse/build validation matrix |
17+
| Registry factory + plugin tests | `test/unit/registry.test.ts`, `test/unit/registries.test.ts` | Registration + per-ecosystem behavior |
18+
| Cache behavior tests | `test/unit/lockfile.test.ts`, `test/unit/cached-registry.test.ts` | Freshness, TTL, integrity, wrapper behavior |
19+
| Normalization tests | `test/unit/license.test.ts`, `test/unit/repository.test.ts` | Canonical output normalization |
20+
| Error-type expectations | `test/unit/errors.test.ts` | Custom error classes |
21+
| Live smoke tests | `test/e2e/smoke.test.ts` | Network-sensitive ecosystem checks |
22+
23+
## CONVENTIONS
24+
- Test files use `*.test.ts` naming.
25+
- Vitest globals are enabled (`describe`, `it`, `expect`, `vi` without imports).
26+
- Unit tests rely on mocks/spies; e2e tests use real HTTP.
27+
28+
## ANTI-PATTERNS
29+
- Do not rely on e2e tests for deterministic behavior checks handled by unit suites.
30+
- Do not add module coverage gaps without corresponding unit tests.
31+
- Do not place production helper code under `test/`.

0 commit comments

Comments
 (0)