packref

Imported from adelrodriguez/packref (AGENTS.md). Install upstream with npx skills add adelrodriguez/packref. Copyright stays with the author.

AGENTS.md

Use ASD-STE100 Simplified Technical English for all communication.

Before you explore or change code, read the relevant CONTEXT.md files. Use the ubiquitous language in these files.

Agent skills

Issue tracker

Issues and PRDs are tracked as GitHub issues at adelrodriguez/packref. See docs/agents/issue-tracker.md.

Triage labels

Use the default five-role triage vocabulary. See docs/agents/triage-labels.md.

Domain docs

Use the single-context domain-doc layout. See docs/agents/domain.md.

Changesets

Use Changesets for versioning and changelog management. See docs/agents/changesets.md.

Testing

• pnpm run test runs the unit Vitest project. It must pass without network access.
• Put each test that uses the network in a *.integration.test.ts file. The integration project in vitest.config.ts selects these files by that pattern, and the unit project excludes them. pnpm run test:integration runs them.
• A network test in a file without the pattern runs in the unit project. This makes the unit CI job depend on the registry, and the test only fails offline. Rename the file to correct this.
• The reflink tests in src/lib/workspace/__tests__/reflinker.test.ts are hermetic, not integration tests. They probe the filesystem and skip where copy-on-write cloning is unsupported.

Packref

Packref provides local copies of dependency source code so you can inspect the exact implementation used by this project.

• Source references are stored in .packref/packages/<registry>/<package>/<version>/ for unscoped packages and .packref/packages/<registry>/<scope>/<package>/<version>/ for scoped packages — browse these directories to read dependency internals
• .packref/packref-lock.json is shared and should be committed; .packref/packages/ is developer-local and git-ignored
• Run npx -y packref install after cloning when locked references are missing; install restores locked references exactly and does not install runtime dependencies
• Run every command with npx -y packref <command>; -y skips the npx install confirmation prompt, so the command does not wait for input
• Available commands:
  • npx -y packref add [package] — select manifest dependencies, fetch a registry package, or fetch a direct repository source (e.g. npx -y packref add react, npx -y packref add hono@4.2.0, npx -y packref add adelrodriguez/packref)
    • Direct repository package specs support GitHub shorthand (owner/repository[/directory][@ref]), provider shorthand (github:, gitlab:, bitbucket:, or sourcehut:), standard Git URLs, and SCP-style SSH URLs
    • A repository ref can be a tag, branch, or full 40-character commit SHA; without a ref, Packref pins the default branch commit
  • npx -y packref remove [package] — select or name package references to remove
  • npx -y packref install — materialize every reference already recorded in the committed lockfile
  • npx -y packref sync — update or remove dependency-tracked lock entries to match current package.json dependency versions
  • npx -y packref list — show all referenced packages
  • npx -y packref prune — remove unused entries from the global store
  • npx -y packref clean — remove all project-local references
  • npx -y packref clean --global — wipe all global store entries
• remove, prune, and clean delete state — run them only when the user requests that removal
• Use Packref when you need to understand how a dependency works internally — read the source in .packref/ instead of guessing or searching the web
• Multiple versions of the same package can coexist; check .packref/packref-lock.json for the full list

Adamantite

This project uses Adamantite for its managed formatting, linting, type checking, and dependency-analysis setup.

• Prefer the package scripts Adamantite added for this workspace.
• Run pnpm run check to catch lint and type issues. Direct command: adamantite check.
• Run pnpm run fix after editing files to apply formatting and safe lint fixes. Direct command: adamantite fix.
• Run pnpm run analyze after changing dependencies, imports, or exports. Direct command: adamantite analyze.
• Use adamantite doctor to inspect managed setup and adamantite doctor --fix for safe local fixes.