@volter/twin-catalog 0.2.3 → 0.2.4

package/catalog.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sourceCommit": "d275fdf823a900c7acd092f05570ecf6888b8878",
+  "sourceCommit": "d295a1e52d80b36146cac13cfccc403139d8d947",
   "digest": "1c9e35135ce16a67c8c5ba817277ac2e11869b8a1234206aee5674eb8851a134",
   "versions": [
     {

package/docs/process.md

@@ -42,6 +42,19 @@ recommendation is moderated separately from a submission and selects a package,
 version is offered. Prereleases require an explicit version. A World pins package and version; a catalog update
 does not change that pin. Removing a recommendation is not uninstalling a running World.
 
+## Release information for users
+
+Each assessed release exposes its artifact's description, license, Node requirements, kernel peer requirements,
+source directory and issue tracker beside its integrity, provenance and measured behavior. README and license links
+point to the source commit verified by npm provenance. They describe that version, not the publisher's current branch.
+Historical assessments without these retained fields show them as unavailable; current registry metadata does not
+fill missing historical evidence. A provenance link establishes source and build identity, not vendor fidelity.
+
+Publishers describe useful workflows, setup and throwaway credential requirements, companion services, supported
+SDK/API versions and explicit limitations in the package README. Model replies, simulated email/search and partial
+interfaces are labeled. Declared gaps remain in the coverage denominator. No publisher badge or aggregate grade
+substitutes for the exact release's supported operations, replay results and scope of browser measurements.
+
 ## Submission
 
 A release PR adds exactly one `submissions/<id>.json`, with no executable files or index edits:

package/lib/browse.d.mts

@@ -45,6 +45,19 @@ export type Release = {
   assessedAt?: string;
 };
 export type CatalogRelease = Release & {
+  packageMetadata: null | {
+    description: string | null;
+    license: string;
+    engines: Record<string, string>;
+    peerDependencies: Record<string, string>;
+    repositoryDirectory: string | null;
+    bugs: string | null;
+    sourceCommit: string | null;
+    readmeUrl: string | null;
+    licenseUrl: string | null;
+    packageUrl: string;
+    issuesUrl: string | null;
+  };
   revoked: { reason: string } | null;
   selectable: boolean;
   default: boolean;

package/lib/browse.mjs

@@ -6,6 +6,25 @@ import { digest, loadIndex, read, requireThat, selection, stable, submissionId,
 const textOrder = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 const releaseKey = (v) => `${v.package}@${v.version}`;
 
+function packageDetails(bound, source, packageName, version) {
+  const metadata = bound?.report.prepared?.packageMetadata;
+  if (!metadata) return null;
+  const commit = bound.report.prepared?.provenance?.sourceCommit;
+  const directory = metadata.repositoryDirectory ?? '';
+  const parts = typeof directory === 'string' ? directory.split('/').filter(Boolean) : null;
+  const validDirectory = parts && parts.every((part) => part !== '.' && part !== '..' && !part.includes('\\'));
+  const sourceRoot = /^[a-f0-9]{40}$/.test(commit ?? '') && validDirectory
+    ? `https://github.com/${source.repository}/blob/${commit}/${parts.length ? parts.map(encodeURIComponent).join('/') + '/' : ''}`
+    : null;
+  let issuesUrl = null;
+  try { const url = new URL(metadata.bugs); if (url.protocol === 'https:') issuesUrl = url.href; } catch { /* No usable issue URL was supplied. */ }
+  return { ...metadata, sourceCommit: commit ?? null,
+    readmeUrl: sourceRoot ? `${sourceRoot}README.md` : null,
+    licenseUrl: sourceRoot ? `${sourceRoot}LICENSE` : null,
+    packageUrl: `https://www.npmjs.com/package/${packageName}/v/${encodeURIComponent(version)}`,
+    issuesUrl };
+}
+
 function repositoryOf(pkg) {
   const value = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url;
   const match = /^git\+https:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value ?? '') ??
@@ -99,7 +118,8 @@ export function browse(root, { vendor, package: packageName, integrity = null }
                 const revoked = index.revocations.find((r) => r.package === p.name && r.version === v.version);
                 const selectable = v.status === 'live' && !v.version.includes('-') && !revoked;
                 const quick = bound?.report.quick, browser = bound?.report.browser;
-                return { ...v, revoked: revoked ? { reason: revoked.reason } : null, selectable: Boolean(selectable),
+                return { ...v, packageMetadata: packageDetails(bound, source, p.name, v.version),
+                  revoked: revoked ? { reason: revoked.reason } : null, selectable: Boolean(selectable),
                   default: choice?.p.name === p.name && choice.v.version === v.version,
                   assessment: { recorded: record.assessed, available: Boolean(bound), evidence: record.evidence,
                     input: bound ? { repository: bound.envelope.input.repository, pullRequest: bound.envelope.input.pullRequest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-catalog",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "The moderated twin distribution: approved versions and submission tooling for independent publishers.",
   "type": "module",
   "bin": {
@@ -38,7 +38,7 @@
     "evidence"
   ],
   "catalog": {
-    "sourceCommit": "d275fdf823a900c7acd092f05570ecf6888b8878",
+    "sourceCommit": "d295a1e52d80b36146cac13cfccc403139d8d947",
     "digest": "1c9e35135ce16a67c8c5ba817277ac2e11869b8a1234206aee5674eb8851a134"
   }
 }

package/policy.json

@@ -2,9 +2,9 @@
   "schemaVersion": 1,
   "registry": "https://registry.npmjs.org",
   "tools": {
-    "@volter/world-core": "3.0.59",
-    "@volter/world-runtime": "3.0.59",
-    "@volter/twin-standard": "1.0.51",
+    "@volter/world-core": "3.0.68",
+    "@volter/world-runtime": "3.0.68",
+    "@volter/twin-standard": "1.0.60",
     "playwright": "1.63.0"
   },
   "bun": "1.3.11",

package/runner/prepare.mjs

@@ -77,5 +77,14 @@ const provenance = await verifiedProvenance(await response.json(), source, bytes
 // Keep a vendor-named package directory for the standard's public directory API; preserve the installed artifact.
 mkdirSync('/work/packs', { recursive: true });
 cpSync(join('/work/node_modules', s.package), join('/work/packs', s.vendor), { recursive: true });
-write('/work/prepared.json', { schemaVersion: 1, submission: s, integrity: s.integrity, provenance, dependencyLockSha256: digest(readFileSync('/work/package-lock.json', 'utf8')), clientSdkLocks, tools: policy.tools });
+// Retain listing facts from these exact bytes, never the registry's moving latest metadata.
+const packageMetadata = {
+  description: typeof pack.description === 'string' ? pack.description : null,
+  license: pack.license,
+  engines: pack.engines ?? {},
+  peerDependencies: pack.peerDependencies ?? {},
+  repositoryDirectory: typeof pack.repository === 'object' ? pack.repository.directory ?? null : null,
+  bugs: typeof pack.bugs === 'string' ? pack.bugs : pack.bugs?.url ?? null,
+};
+write('/work/prepared.json', { schemaVersion: 1, submission: s, integrity: s.integrity, provenance, packageMetadata, dependencyLockSha256: digest(readFileSync('/work/package-lock.json', 'utf8')), clientSdkLocks, tools: policy.tools });
 write('/work/world.json', { id: 'catalog-assessment', network: { egress: [] }, services: [] });