@volter/twin-catalog 0.2.39 → 0.2.41

package/lib/browse.d.mts

@@ -69,7 +69,7 @@ export type Release = {
 export type CatalogRelease = Release & {
   packageMetadata: null | {
     description: string | null;
-    license: string;
+    license: string | null;
     engines: Record<string, string>;
     peerDependencies: Record<string, string>;
     repositoryDirectory: string | null;
@@ -80,6 +80,8 @@ export type CatalogRelease = Release & {
     packageUrl: string;
     issuesUrl: string | null;
   };
+  documentation: null | { markdown: string | null; path: string | null; receiptPath: string;
+    receiptSha256: string; artifactIntegrity: string };
   revoked: { reason: string } | null;
   selectable: boolean;
   default: boolean;

package/lib/browse.mjs

@@ -2,14 +2,15 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { digest, loadIndex, read, requireThat, selection, stable, submissionId, validateIndex } from './model.mjs';
+import { contentIdentity, contentReceipt } from './content.mjs';
 
 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;
+function packageDetails(bound, source, packageName, version, content) {
+  const metadata = content?.packageMetadata ?? bound?.report.prepared?.packageMetadata;
   if (!metadata) return null;
-  const commit = bound.report.prepared?.provenance?.sourceCommit;
+  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('\\'));
@@ -85,7 +86,8 @@ export function browse(root, { vendor, package: packageName, integrity = null }
   requireThat(expected.length === records.size && expected.every((v) => stable(v) === stable(records.get(releaseKey(v)))),
     'catalog records differ from index data');
   const snapshotDigest = (vendors) => digest({ evidence: references, sources: index.sources, vendors,
-    recommendations: index.recommendations, revocations: index.revocations });
+    recommendations: index.recommendations, revocations: index.revocations,
+    ...(catalog.content ? { content: catalog.content } : {}) });
   // Publication can append newly admitted vendors after the legacy vendors. Directory enumeration is alphabetical;
   // catalog.json retains the publication order. Accept either only when its complete digest matches the snapshot.
   const publicationOrder = new Map([...new Set(catalog.versions.map((v) => v.vendor))].map((name, at) => [name, at]));
@@ -115,10 +117,19 @@ export function browse(root, { vendor, package: packageName, integrity = null }
               versions: p.versions.map((v) => {
                 const record = records.get(`${p.name}@${v.version}`);
                 const bound = reportFor(root, record);
+                const contentReference = catalog.content?.[submissionId(contentIdentity(record))];
+                const content = contentReceipt(root, record, contentReference);
+                const preparedReadme = bound?.report.prepared?.readme;
+                const documentation = content ? { markdown: content.readme?.markdown ?? null,
+                  path: content.readme?.path ?? null, receiptPath: contentReference.path,
+                  receiptSha256: contentReference.sha256, artifactIntegrity: v.integrity } :
+                  preparedReadme ? { ...preparedReadme, receiptPath: record.evidence.reportPath,
+                    receiptSha256: record.evidence.reportSha256, artifactIntegrity: v.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, packageMetadata: packageDetails(bound, source, p.name, v.version),
+                return { ...v, packageMetadata: packageDetails(bound, source, p.name, v.version, content),
+                  documentation,
                   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,

package/lib/content.mjs

@@ -0,0 +1,87 @@
+// Artifact documentation is data, independent of assessment and admission evidence.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { digest, read, requireThat, stable, submissionId, validateSubmission, write } from './model.mjs';
+import { artifactBytes, metadata } from './registry.mjs';
+
+export const contentIdentity = (v) => ({ schemaVersion: 1, source: v.source, vendor: v.vendor,
+  package: v.package, version: v.version, integrity: v.integrity });
+export function contentReceipt(root, v, reference) {
+  if (!reference) return null;
+  const identity = contentIdentity(v), path = `content/${submissionId(identity)}.json`;
+  requireThat(reference.path === path && /^[a-f0-9]{64}$/.test(reference.sha256), 'invalid release content reference');
+  const receipt = read(join(root, path));
+  requireThat(digest(receipt) === reference.sha256, `${v.package}@${v.version}: content checksum differs`);
+  requireThat(receipt.schemaVersion === 1 && stable(receipt.release) === stable(identity), 'release content identity differs');
+  requireThat(receipt.packageMetadata && (receipt.readme === null ||
+    (typeof receipt.readme?.markdown === 'string' && /^package\/readme(?:\.md|\.markdown|\.txt)?$/i.test(receipt.readme.path))),
+    'invalid retained release documentation');
+  return receipt;
+}
+export function retainedContent(root, index) {
+  const references = {};
+  for (const e of index.vendors) for (const p of e.packages) for (const v of p.versions) {
+    if (!v.integrity) continue;
+    const release = contentIdentity({ vendor: e.vendor, package: p.name, source: p.source, ...v });
+    const id = submissionId(release), path = `content/${id}.json`;
+    if (!existsSync(join(root, path))) continue;
+    const reference = { path, sha256: digest(read(join(root, path))) };
+    contentReceipt(root, release, reference);
+    references[id] = reference;
+  }
+  return references;
+}
+
+// Read named members to stdout only: no extraction, installation or package execution.
+function archive(bytes, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('tar', args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    const out = [], errors = [];
+    child.stdout.on('data', chunk => out.push(chunk));
+    child.stderr.on('data', chunk => errors.push(chunk));
+    child.on('error', reject);
+    child.stdin.on('error', reject);
+    child.on('close', code => code === 0 ? resolve(Buffer.concat(out).toString('utf8')) :
+      reject(new Error(`read artifact archive: ${Buffer.concat(errors).toString('utf8')}`)));
+    child.stdin.end(bytes);
+  });
+}
+export async function captureContent(root, index, registry, fetcher = fetch) {
+  const releases = [];
+  for (const e of index.vendors) for (const p of e.packages) for (const v of p.versions) {
+    if (!v.integrity) continue;
+    const release = contentIdentity({ vendor: e.vendor, package: p.name, source: p.source, ...v });
+    const source = validateSubmission(release, index.sources);
+    const id = submissionId(release), path = `content/${id}.json`;
+    if (existsSync(join(root, path))) {
+      contentReceipt(root, release, { path, sha256: digest(read(join(root, path))) });
+      releases.push({ package: p.name, version: v.version, path, existing: true });
+      continue;
+    }
+    const doc = await metadata(p.name, v.version, registry, fetcher);
+    const bytes = await artifactBytes(doc, release, registry, fetcher);
+    const members = (await archive(bytes, ['-tzf', '-'])).trim().split('\n');
+    requireThat(members.filter(name => name === 'package/package.json').length === 1, 'artifact needs one package manifest');
+    const pack = JSON.parse(await archive(bytes, ['-xzOf', '-', 'package/package.json']));
+    requireThat(pack.name === p.name && pack.version === v.version, 'artifact manifest identity differs');
+    const repository = typeof pack.repository === 'string' ? pack.repository : pack.repository?.url;
+    requireThat(repository?.replace(/^git\+/, '').replace(/\.git$/, '') === `https://github.com/${source.repository}`,
+      'artifact repository differs from registered source');
+    const readmes = members.filter(name => /^package\/readme(?:\.md|\.markdown|\.txt)?$/i.test(name));
+    requireThat(readmes.length <= 1, 'artifact has ambiguous READMEs');
+    const receipt = { schemaVersion: 1, release,
+      packageMetadata: {
+        description: typeof pack.description === 'string' ? pack.description : null,
+        license: typeof pack.license === 'string' ? pack.license : null,
+        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,
+      },
+      readme: readmes.length ? { path: readmes[0], markdown: await archive(bytes, ['-xzOf', '-', readmes[0]]) } : null,
+    };
+    write(join(root, path), receipt);
+    releases.push({ package: p.name, version: v.version, path, existing: false, readme: Boolean(receipt.readme) });
+  }
+  return { releases, next: 'Commit the captured data with the catalog maintenance change; publication binds it to the snapshot. No assessment was run.' };
+}

package/lib/publication.mjs

@@ -2,6 +2,7 @@ import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:f
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { admit, defaults, digest, loadIndex, read, requireThat, stable, submissionId, validateIndex, write } from './model.mjs';
+import { retainedContent } from './content.mjs';
 
 export function git(root, args) {
   const r = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
@@ -37,7 +38,9 @@ export function build(root, out, evidence = {}) {
   const commit = git(root, ['rev-parse', 'HEAD']);
   const version = `0.2.${git(root, ['rev-list', '--first-parent', '--count', 'HEAD'])}`;
   const references = Object.fromEntries(Object.entries(evidence).map(([id, { envelope, ...receipt }]) => [id, receipt]));
-  const identity = digest({ evidence: references, sources: index.sources, vendors: index.vendors, recommendations: index.recommendations, revocations: index.revocations });
+  const content = retainedContent(root, index);
+  const contentIdentity = Object.keys(content).length ? { content } : {};
+  const identity = digest({ evidence: references, sources: index.sources, vendors: index.vendors, recommendations: index.recommendations, revocations: index.revocations, ...contentIdentity });
   mkdirSync(out, { recursive: true });
   write(join(out, 'sources.json'), index.sources);
   write(join(out, 'recommendations.json'), index.recommendations);
@@ -45,6 +48,11 @@ export function build(root, out, evidence = {}) {
   for (const e of index.vendors) write(join(out, 'vendors', `${e.vendor}.json`), e);
   const catalog = { schemaVersion: 1, sourceCommit: commit, digest: identity, versions: index.vendors.flatMap((e) => e.packages.flatMap((p) => p.versions.map((v) => ({ vendor: e.vendor, package: p.name, source: p.source, ...v, evidence: (v.submission ?? v.assessment) ? { submission: v.submission ?? v.assessment, admissionCommit: v.assessmentCommit ?? v.commit, ...(references[v.submission ?? v.assessment] ?? {}) } : null, assessed: Boolean(v.submission ?? v.assessment) })))) };
   write(join(out, 'catalog.json'), catalog);
+  if (Object.keys(content).length) {
+    catalog.content = content;
+    write(join(out, 'catalog.json'), catalog);
+    for (const { path } of Object.values(content)) write(join(out, path), read(join(root, path)));
+  }
   for (const [id, receipt] of Object.entries(evidence)) write(join(out, 'evidence', `${id}.json`), receipt.envelope);
   const pkg = { ...read(join(root, 'package.json')), version, catalog: { sourceCommit: commit, digest: identity } };
   delete pkg.devDependencies;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-catalog",
-  "version": "0.2.39",
+  "version": "0.2.41",
   "description": "The moderated twin distribution: approved versions and submission tooling for independent publishers.",
   "type": "module",
   "bin": {
@@ -35,10 +35,11 @@
     "lib",
     "runner",
     "docs",
-    "evidence"
+    "evidence",
+    "content"
   ],
   "catalog": {
-    "sourceCommit": "8cc7194bdc4e9bb5c481d862684ebf5f7e75a7ba",
-    "digest": "b24bd5b8f97b7054833cb45fd84ed20361a08eff401aaf0c04b3fd89fda3d945"
+    "sourceCommit": "a4c5e0664985a7f5a173b58cd307b88a7ddd2795",
+    "digest": "5103e721dd9632a05ec4d5348d1b9e668ee092b3edf634c0e4b08f08efb76527"
   }
 }

package/runner/prepare.mjs

@@ -1,5 +1,5 @@
 // No credentials enter this container. This phase downloads data; scripts are disabled.
-import { readFileSync, writeFileSync, mkdirSync, cpSync, realpathSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, cpSync, realpathSync, readdirSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { createRequire } from 'node:module';
@@ -103,6 +103,10 @@ for (const [path, entry] of Object.entries(consumerLock.packages ?? {})) {
 }
 const consumer = { appDir, cli, artifactIntegrity: s.integrity };
 // Retain listing facts from these exact bytes, never the registry's moving latest metadata.
+const readmeNames = readdirSync('/work/unpacked/package').filter(name => /^readme(?:\.md|\.markdown|\.txt)?$/i.test(name));
+requireThat(readmeNames.length <= 1, 'artifact has ambiguous READMEs');
+const readme = readmeNames.length ? { path: `package/${readmeNames[0]}`,
+  markdown: readFileSync(join('/work/unpacked/package', readmeNames[0]), 'utf8') } : null;
 const packageMetadata = {
   description: typeof pack.description === 'string' ? pack.description : null,
   license: pack.license,
@@ -111,5 +115,5 @@ const packageMetadata = {
   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, clientDependencyChoices, tools: policy.tools, consumer, consumerFixture, consumerDependencyLockSha256: digest(readFileSync(join(appDir, 'package-lock.json'), 'utf8')) });
+write('/work/prepared.json', { schemaVersion: 1, submission: s, integrity: s.integrity, provenance, packageMetadata, readme, dependencyLockSha256: digest(readFileSync('/work/package-lock.json', 'utf8')), clientSdkLocks, clientDependencyChoices, tools: policy.tools, consumer, consumerFixture, consumerDependencyLockSha256: digest(readFileSync(join(appDir, 'package-lock.json'), 'utf8')) });
 write('/work/world.json', { id: 'catalog-assessment', network: { egress: [] }, services: [] });

package/vendors/slack.json

@@ -5,6 +5,15 @@
       "name": "@volter/twin-slack",
       "source": "twin-packs-open",
       "versions": [
+        {
+          "version": "3.0.5",
+          "status": "live",
+          "integrity": "sha512-P8jzf8Ss3MsXG+bc+uX9QBfYu4R74tmHgeOuSyJ8WjrsfvbJzBGZHQPGV50qUDTHD6vuh17bDqTaTsesK58aZw==",
+          "submission": "1fa7500b80e0c420b91e602419e1185bb2b2871c338e74eb7d5d20845e167e3c",
+          "commit": "6c08177e4ef0c57c56b5b614f2260ab86d40e065",
+          "at": "2026-10-07T17:40:47Z",
+          "by": "moderated-merge"
+        },
         {
           "version": "3.0.4",
           "status": "live",