{"_id":"@aefree/pi-package-references","_rev":"2-af0e6e747b91fb93b2b9969cb87615e1","name":"@aefree/pi-package-references","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@aefree/pi-package-references","version":"0.1.0","keywords":["pi-package","references","package-resources"],"license":"MIT","_id":"@aefree/pi-package-references@0.1.0","maintainers":[{"name":"aefree","email":"aaron@secretcrush.net"}],"homepage":"https://github.com/aefreedman/pi-package-references#readme","bugs":{"url":"https://github.com/aefreedman/pi-package-references/issues"},"pi":{"extensions":["./extensions/index.ts"]},"dist":{"shasum":"31dff5bb4131ba2aec195d1b40ee11ede2ff700b","tarball":"https://registry.npmjs.org/@aefree/pi-package-references/-/pi-package-references-0.1.0.tgz","fileCount":30,"integrity":"sha512-UQHGmXZ7t9PqU86lA0EUNKUd3YZGR0WhJvkifpPAMK6ZL/9kJ8Xp4pcYPkNIrShO0/dGf9DSIthxZiCtI4BEqg==","signatures":[{"sig":"MEYCIQCUvZEw5NKNvpsg1tn3xnsLCwgS86/drgTtChtl1BQ49QIhAM8V6GeVF3NkIA6915Tae2/u/inNX0YyPzyS16oO6MjE","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":52755},"type":"module","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./runtime/v1":{"types":"./dist/runtime/v1.d.ts","import":"./dist/runtime/v1.js"},"./contracts/v1":{"types":"./dist/contracts/v1/index.d.ts","import":"./dist/contracts/v1/index.js"}},"gitHead":"8083abb2a24300f08f54d710d2ec6bff077c7f4f","scripts":{"test":"npm run build && node --test tests/*.test.mjs","build":"tsc -p tsconfig.json","prepack":"npm run build","pack:check":"npm pack --dry-run"},"_npmUser":{"name":"aefree","email":"aaron@secretcrush.net"},"repository":{"url":"git+https://github.com/aefreedman/pi-package-references.git","type":"git"},"_npmVersion":"11.6.2","description":"Bounded package-relative public reference reader for independently installed Pi packages.","directories":{},"sideEffects":["./extensions/index.ts"],"_nodeVersion":"24.13.0","dependencies":{"@aefree/pi-capability-registry":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typebox":"1.1.38","typescript":"^5.8.3","@types/node":"^24.0.0","@earendil-works/pi-ai":"0.82.1","@earendil-works/pi-tui":"0.82.1","@earendil-works/pi-coding-agent":"0.82.1"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"peerDependenciesMeta":{"typebox":{"optional":true},"@earendil-works/pi-ai":{"optional":true},"@earendil-works/pi-tui":{"optional":true},"@earendil-works/pi-coding-agent":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/pi-package-references_0.1.0_1785255825886_0.5996595947625405","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"pi":{"extensions":["./extensions/index.ts"]},"_id":"@aefree/pi-package-references@0.1.1","bugs":{"url":"https://github.com/aefreedman/pi-package-references/issues"},"dist":{"shasum":"48aa27ec1febd30996a9f4d7cff567673f4acea4","tarball":"https://registry.npmjs.org/@aefree/pi-package-references/-/pi-package-references-0.1.1.tgz","fileCount":15,"integrity":"sha512-XQBX0fUI3SmmmY8Z/0qR5cZWshoIuS9bpbvKuFR2z/08o1Y84TdEAds/0qZvghcM+1pm6os9GtQfokeb5uiNXw==","signatures":[{"sig":"MEYCIQC/za0LqQ4rHim3aFH5M4glVNJJq8sLoQY29n9X5j0TowIhAO5kzvxEO/thcz4mfHatAaDBiywa7NmeibAKXJRU3eWc","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDurW9i6cCJtFHAMniJRjZn239lKGOSuMhyZ4saF8ZHTQIgVLxyR9GTKo4u1hR4pLJ/yCN5rMdkX3VuJbCnuugLDE4="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aefree%2fpi-package-references@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":24299},"name":"@aefree/pi-package-references","type":"module","engines":{"node":">=22.19.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./runtime/v1":{"types":"./dist/runtime/v1.d.ts","import":"./dist/runtime/v1.js"},"./contracts/v1":{"types":"./dist/contracts/v1/index.d.ts","import":"./dist/contracts/v1/index.js"}},"gitHead":"9765137651b61bf93e2356d6c9ee4ef43e142631","license":"MIT","scripts":{"test":"npm run build && node --test tests/*.test.mjs","build":"tsc -p tsconfig.json","prepack":"npm run build","pack:check":"npm pack --dry-run"},"version":"0.1.1","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"5a115f4e-ac14-40ee-af88-089551f7e8b2"}},"homepage":"https://github.com/aefreedman/pi-package-references#readme","keywords":["pi-package","references","package-resources"],"repository":{"url":"git+https://github.com/aefreedman/pi-package-references.git","type":"git"},"_npmVersion":"11.6.2","description":"Bounded package-relative public reference reader for independently installed Pi packages.","directories":{},"maintainers":[{"name":"aefree","email":"aaron@secretcrush.net"}],"sideEffects":["./extensions/index.ts"],"_nodeVersion":"24.21.0","dependencies":{"@aefree/pi-capability-registry":"^0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typebox":"1.3.8","typescript":"7.0.2","@types/node":"22.20.4","@earendil-works/pi-ai":"0.99.1","@earendil-works/pi-tui":"0.99.1","@earendil-works/pi-coding-agent":"0.99.1"},"peerDependencies":{"typebox":"*","@earendil-works/pi-ai":"*","@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"peerDependenciesMeta":{"typebox":{"optional":true},"@earendil-works/pi-ai":{"optional":true},"@earendil-works/pi-tui":{"optional":true},"@earendil-works/pi-coding-agent":{"optional":true}},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-package-references_0.1.1_1790729449034_0.6601853536814577"}}},"time":{"created":"2026-07-28T16:23:45.746Z","modified":"2026-09-30T00:50:49.513Z","0.1.0":"2026-07-28T16:23:46.044Z","0.1.1":"2026-09-30T00:50:49.137Z"},"bugs":{"url":"https://github.com/aefreedman/pi-package-references/issues"},"license":"MIT","homepage":"https://github.com/aefreedman/pi-package-references#readme","keywords":["pi-package","references","package-resources"],"repository":{"url":"git+https://github.com/aefreedman/pi-package-references.git","type":"git"},"description":"Bounded package-relative public reference reader for independently installed Pi packages.","maintainers":[{"name":"aefree","email":"aaron@secretcrush.net"}],"readme":"# pi-package-references\n\n`@aefree/pi-package-references` provides the single `read_package_reference` Pi tool for bounded text owned by independently installed packages.\n\n## Installation\n\nInstall it in the package that owns the public reference files:\n\n```sh\nnpm install @aefree/pi-package-references\n```\n\nThe package has a normal runtime dependency on `@aefree/pi-capability-registry`; npm resolves that publicly available prerequisite transitively.\n\n## Use it from an owner package\n\n1. Add `@aefree/pi-package-references` as a normal runtime dependency of the package that owns the reference files.\n2. Ensure both that package's extension and this package's `extensions/index.ts` are active in Pi. The reader extension registers the single `read_package_reference` tool; importing `contracts/v1` or `runtime/v1` has no Pi-resource registration side effects.\n3. During each `session_start`, register only the directory prefixes the owner intends to publish. During the matching `session_shutdown`, unregister that registration.\n4. In prompts or agents, call the tool with an exact package name and public path. Do not use project-relative file reads as a substitute.\n\nFor example, `@example/review-policy`, an extension package containing `references/review/delivery-policy.md`, can register that directory as follows:\n\n```ts\nimport { readFileSync } from \"node:fs\";\nimport { dirname, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport type { ExtensionAPI } from \"@earendil-works/pi-coding-agent\";\nimport type { RegistrationToken } from \"@aefree/pi-capability-registry\";\nimport {\n  registerPackageReferenceOwnerV1,\n  unregisterPackageReferenceOwnerV1,\n} from \"@aefree/pi-package-references/runtime/v1\";\n\nexport default function registerOwner(pi: ExtensionAPI): void {\n  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), \"..\");\n  const manifest = JSON.parse(readFileSync(resolve(packageRoot, \"package.json\"), \"utf8\")) as {\n    name: string;\n    version: string;\n  };\n  let activeScope: object | undefined;\n  let token: RegistrationToken | undefined;\n\n  pi.on(\"session_start\", async (_event, ctx) => {\n    unregisterPackageReferenceOwnerV1(token);\n    activeScope = ctx.sessionManager;\n    token = await registerPackageReferenceOwnerV1(ctx.sessionManager, {\n      contractVersion: 1,\n      packageName: manifest.name,\n      packageVersion: manifest.version,\n      packageRoot,\n      registeredBy: \"extensions/index.ts\",\n      publicMounts: [{\n        prefix: \"references/review/\",\n        directory: \"references/review\",\n        extensions: [\".md\"],\n      }],\n    });\n  });\n\n  pi.on(\"session_shutdown\", async (_event, ctx) => {\n    if (ctx.sessionManager !== activeScope) return; // stale shutdown\n    unregisterPackageReferenceOwnerV1(token);\n    token = undefined;\n    activeScope = undefined;\n  });\n}\n```\n\nA prompt or agent then reads an exact package-qualified reference:\n\n```json\n{\"packageName\":\"@example/review-policy\",\"path\":\"references/review/delivery-policy.md\"}\n```\n\nThe result is tool output, so callers should handle a failed read explicitly: state that mandatory guidance is unavailable and do not claim to have applied unread guidance.\n\nPaths are normalized POSIX-relative, mounts and extensions are explicit, reads are capped at 50 KiB and 2,000 lines, and results expose package/version/mount provenance without installation paths. Missing, private, malformed, ambiguous, incompatible, escaping, changed, and oversized resources fail with sanitized codes.\n\nThis is a correctness boundary for trusted installed packages, not a filesystem sandbox. On Windows Node runtimes without `O_NOFOLLOW`, guarantees are canonical containment plus post-open identity/change detection; adversarial race prevention is not claimed.\n\nThe reader must be installed and active as a Pi resource package in addition to any owner package's code dependency. Activate it explicitly with `pi install npm:@aefree/pi-package-references`, and install/activate the owner package separately. A code dependency alone does not activate Pi extensions. If package resources are filtered in Pi settings, ensure this package's `extensions/index.ts` and the owner's extension are enabled, then start a new Pi session.\n\nThe supported validation baseline is Pi 0.99.1 on Node.js >=22.19.0. The npm artifact contains compiled runtime code, public declarations, and the Pi entry point; authored source, source maps, tests, fixtures, and evals remain repository-only. Build and test scripts are maintainer commands for a repository checkout, not consumer installation steps.\n","readmeFilename":"README.md"}