@crombolo/server 0.9.1 → 0.10.0

package/src/marketplace.ts

@@ -1,19 +1,30 @@
 /**
- * The Bundles section's marketplace, over npm. `docs/17-bundles.md`.
+ * The Bundles section's marketplace, over npm. `docs/bundles.md`.
  *
  * Discovery and declaration are two different things, because npm indexes only
  * one of them: a bundle is *found* by the `crombolo-bundle` keyword, which is
  * the only thing registry search will match, and it *declares* itself with a
  * `crombolo` field in its `package.json`. Search for the keyword, then read each
  * hit's packument — custom fields survive there — and offer only the packages
- * that actually declare extensions. A keyword squatter never reaches the list.
+ * whose manifest is a valid bundle. A keyword squatter never reaches the list.
+ *
+ * An install is `bun add`, and then — unless the site or the request says not
+ * to — the content the bundle carries, through the same installer as
+ * `crombolo bundle install`. A bundle's server half is never loaded by an
+ * install: that still takes an edit to `crombolo.config.ts` and a deploy.
  *
  * The search is proxied rather than done in the browser: it works where the
  * browser cannot reach npm, and the backoffice keeps making same-origin
  * requests only.
  */
 import { join } from 'node:path'
-import { EXTENSION_KEYWORD, type ExtensionRegistry } from '@crombolo/backoffice-host'
+import {
+  type BundlePackage,
+  EXTENSION_KEYWORD,
+  type ExtensionRegistry,
+  type PackageJson,
+  validateBundlePackage,
+} from '@crombolo/backoffice-host'
 import { logger } from './logging.ts'
 
 const log = logger('packages')
@@ -27,12 +38,12 @@ export interface MarketplaceListing {
   description: string
   publisher: string | null
   links: { npm: string; homepage: string | null; repository: string | null }
-  /** Whether the latest version declares backoffice extensions. */
-  declaresExtensions: boolean
+  /** What the latest version carries; only a valid bundle is listed at all. */
+  carries: BundlePackage['carries']
   installedVersion: string | null
 }
 
-/** An installed extension as the Installed view lists it. */
+/** A bundle the site depends on, as the Installed view lists it. */
 export interface InstalledListing {
   /** The npm package name, which is what an uninstall names. */
   packageName: string
@@ -41,6 +52,19 @@ export interface InstalledListing {
   id: string
   version: string
   extensionCount: number
+  carries: BundlePackage['carries']
+  /** Whether its server half is imported into `crombolo.config.ts`; only meaningful when it carries one. */
+  wired: boolean
+  /** The version whose content was applied here, or null when none has been. */
+  contentApplied: string | null
+}
+
+/** What became of the content half of an install. */
+export interface ContentOutcome {
+  applied: boolean
+  /** Set when it was applied: the transfer run that can revert it. */
+  runId?: string
+  message: string
 }
 
 export interface MarketplaceOptions {
@@ -53,6 +77,17 @@ export interface MarketplaceOptions {
   siteDir: string
   /** Overridden by tests; the real one shells out to Bun. */
   install?: PackageInstaller
+  /** The ids of the bundles whose server half this node has mounted. */
+  wired?: () => readonly string[]
+  /** The version of a package whose content has been applied here. */
+  contentApplied?: (packageName: string) => Promise<string | null>
+  /**
+   * Installs the content half of a bundle the site now depends on. Absent where
+   * content cannot be applied, which declines it for every install.
+   */
+  applyContent?: (packageName: string) => Promise<ContentOutcome>
+  /** The site's `applyBundleContentOnInstall`. */
+  applyContentOnInstall?: boolean
 }
 
 export interface InstallOutcome {
@@ -64,6 +99,8 @@ export interface InstallOutcome {
    */
   dependency?: { name: string; range: string; version: string }
   message: string
+  /** What happened to the content the bundle carries; absent when it carries none. */
+  content?: ContentOutcome
 }
 
 export type PackageInstaller = (
@@ -102,8 +139,12 @@ export interface Marketplace {
   /** Where someone browsing should be sent, when they want more than this list. */
   url(): string
   search(query: string | undefined): Promise<MarketplaceListing[]>
-  installed(): InstalledListing[]
-  install(name: string, version: string | undefined): Promise<InstallOutcome>
+  installed(): Promise<InstalledListing[]>
+  install(
+    name: string,
+    version: string | undefined,
+    options?: { applyContent?: boolean },
+  ): Promise<InstallOutcome>
   uninstall(name: string): Promise<InstallOutcome>
 }
 
@@ -156,24 +197,35 @@ export function createMarketplace(options: MarketplaceOptions): Marketplace {
   let cached: { at: number; query: string; listings: MarketplaceListing[] } | undefined
 
   const installedVersion = (name: string): string | null =>
-    options.extensions.list().find((extension) => extension.packageName === name)?.version ?? null
+    options.extensions.bundles().bundles.find((bundle) => bundle.packageName === name)?.version ??
+    null
 
-  /** Whether the registry says this package's latest version declares extensions. */
-  const declares = async (name: string): Promise<boolean> => {
+  /** What the registry says this package's latest version carries, when it is a valid bundle. */
+  const declares = async (name: string): Promise<BundlePackage['carries'] | undefined> => {
     try {
       const response = await call(`${options.registry}/${encodeURIComponent(name)}`, {
         headers: { accept: 'application/json' },
       })
-      if (!response.ok) return false
+      if (!response.ok) return undefined
       const packument = (await response.json()) as {
         'dist-tags'?: { latest?: string }
-        versions?: Record<string, { crombolo?: { extensions?: unknown[] } }>
+        versions?: Record<string, PackageJson>
       }
       const latest = packument['dist-tags']?.latest
       const version = latest ? packument.versions?.[latest] : undefined
-      return Array.isArray(version?.crombolo?.extensions) && version.crombolo.extensions.length > 0
+      if (!version || validateBundlePackage(version).length > 0) return undefined
+      const field = version.crombolo as {
+        extensions?: unknown[]
+        content?: string
+        server?: string
+      }
+      return {
+        extensions: Array.isArray(field.extensions) && field.extensions.length > 0,
+        content: field.content !== undefined,
+        server: field.server !== undefined,
+      }
     } catch {
-      return false
+      return undefined
     }
   }
 
@@ -213,8 +265,10 @@ export function createMarketplace(options: MarketplaceOptions): Marketplace {
           .filter((pkg): pkg is NonNullable<typeof pkg> =>
             Boolean(pkg?.name && isValidPackageName(pkg.name)),
           )
-          .map(async (pkg): Promise<MarketplaceListing> => {
+          .map(async (pkg): Promise<MarketplaceListing | undefined> => {
             const name = pkg.name as string
+            const carries = await declares(name)
+            if (!carries) return undefined
             return {
               name,
               version: pkg.version ?? '0.0.0',
@@ -225,29 +279,35 @@ export function createMarketplace(options: MarketplaceOptions): Marketplace {
                 homepage: pkg.links?.homepage ?? null,
                 repository: pkg.links?.repository ?? null,
               },
-              declaresExtensions: await declares(name),
+              carries,
               installedVersion: installedVersion(name),
             }
           }),
       )
-      // Only what really declares extensions: the keyword is a claim, the field
-      // is the thing itself.
-      const offered = listings.filter((listing) => listing.declaresExtensions)
+      // Only what really is a bundle: the keyword is a claim, the manifest is
+      // the thing itself.
+      const offered = listings.filter((listing): listing is MarketplaceListing => Boolean(listing))
       cached = { at: Date.now(), query: text, listings: offered }
       return offered
     },
 
-    installed() {
-      return options.extensions.list().map((extension) => ({
-        packageName: extension.packageName,
-        name: extension.manifest.name,
-        id: extension.manifest.id ?? extension.packageName,
-        version: extension.version,
-        extensionCount: extension.manifest.extensions.length,
-      }))
+    async installed() {
+      const wired = new Set(options.wired?.() ?? [])
+      return Promise.all(
+        options.extensions.bundles().bundles.map(async (bundle) => ({
+          packageName: bundle.packageName,
+          name: bundle.name,
+          id: bundle.id,
+          version: bundle.version,
+          extensionCount: bundle.field.extensions?.length ?? 0,
+          carries: bundle.carries,
+          wired: wired.has(bundle.id),
+          contentApplied: (await options.contentApplied?.(bundle.packageName)) ?? null,
+        })),
+      )
     },
 
-    async install(name, version) {
+    async install(name, version, request = {}) {
       if (!isValidPackageName(name))
         return { ok: false, message: `'${name}' is not a package name npm would accept.` }
       if (version !== undefined && !isValidVersion(version))
@@ -263,19 +323,44 @@ export function createMarketplace(options: MarketplaceOptions): Marketplace {
         }
 
       const range = (await rangeFor(name)) ?? version ?? 'latest'
-      const found = options.extensions.list().find((extension) => extension.packageName === name)
+      const found = options.extensions
+        .bundles()
+        .bundles.find((bundle) => bundle.packageName === name)
       if (!found)
         return {
           ok: true,
           dependency: { name, range, version: version ?? range },
-          message: `${name} was installed, but it declares no backoffice extensions, so nothing was added to the backoffice.`,
+          message: `${name} was installed, but it is not a valid bundle, so nothing was added to the backoffice.`,
         }
+
+      // The content half lands after the dependency, so a refused check leaves
+      // the package installed and says why, rather than undoing an install that
+      // succeeded.
+      let content: ContentOutcome | undefined
+      if (found.carries.content) {
+        const declined = request.applyContent === false || options.applyContentOnInstall === false
+        content =
+          declined || !options.applyContent
+            ? {
+                applied: false,
+                message: `Its content was not applied. Run \`crombolo bundle install ${name}\` to apply it.`,
+              }
+            : await options.applyContent(name).catch((error: unknown) => ({
+                applied: false,
+                message: `Its content could not be applied: ${error instanceof Error ? error.message : String(error)}`,
+              }))
+      }
       return {
         ok: true,
         dependency: { name, range, version: found.version },
         // The install lives in this node's node_modules until the dependency is
         // committed; saying so is the difference between a surprise and a plan.
-        message: `${name}@${found.version} is installed and active. Commit the changed package.json and bun.lock to keep it across deployments.`,
+        message: `${name}@${found.version} is installed. Commit the changed package.json and bun.lock to keep it across deployments.${
+          found.carries.server
+            ? ' Its server half runs only once crombolo.config.ts imports it and the site is deployed.'
+            : ''
+        }`,
+        ...(content ? { content } : {}),
       }
     },
 

package/src/no-nodes.ts

@@ -1,6 +1,6 @@
 /**
  * The holding page for a site with nothing published — Umbraco's "no nodes"
- * screen, which `docs/06-features.md` asks for.
+ * screen, which `docs/features.md` asks for.
  *
  * It answers 404, not 200: a brand-new site is not a working one, and anything
  * watching the URL should keep saying so until a page is published. It is only

package/src/ports.ts

@@ -89,7 +89,7 @@ const CULTURES = [
 
 function createServerPort(config: CromboloConfig, canSendUserLinks: boolean): ServerPort {
   return {
-    // Phase 6 derives this from migration state; until then the site is always up.
+    // Story 080 derives this from migration state; until then the site is always up.
     status: () => ({ serverStatus: 'Run' }),
     configuration: () => ({
       // Reported false when no link could be delivered, so the client does not

package/src/schema.ts

@@ -1,7 +1,7 @@
 /**
  * Schema-as-code at runtime: the boot sync, the development watcher that
  * re-syncs on file changes, and the cache-instruction poll that keeps this
- * node's caches coherent with the others. docs/09-schema-as-code.md.
+ * node's caches coherent with the others. docs/schema-as-code.md.
  */
 
 import { existsSync, watch } from 'node:fs'

package/src/server.ts

@@ -1,7 +1,7 @@
 /**
  * The Crombolo server.
  *
- * Route order matters and mirrors docs/01-architecture.md: static assets, the
+ * Route order matters and mirrors docs/architecture.md: static assets, the
  * non-contract security and branding endpoints, the contract-first Management
  * API, the SPA shells, then the front-end site.
  */
@@ -41,11 +41,13 @@ import {
 } from '@crombolo/core'
 import {
   appendCacheInstruction,
+  createTablesCapability,
   type Db,
   FormEntryRepository,
   FormWorkflowRepository,
   RedirectRepository,
   readReport,
+  TransferRunRepository,
   type WritesPaused,
 } from '@crombolo/data'
 import {
@@ -63,9 +65,12 @@ import {
 import type { SyncReport } from '@crombolo/schema'
 import type { Server } from 'bun'
 import { createNodeLookup, loadAccess } from './access.ts'
+import { readCreatedBundlePackage, writeCreatedBundlePackage } from './adapters/bundles.ts'
 import { createPublishedContentSource, loadDraftNode } from './adapters/documents.ts'
 import { createSchemaProposals } from './adapters/schema-proposals.ts'
-import { createBundleRedirects, createServerBundles } from './bundles.ts'
+import { installBundleContent } from './bundle-install.ts'
+import { bundleChains, bundleTablesReport } from './bundle-tables.ts'
+import { createBundleRedirects, createServerBundles, validateServerBundles } from './bundles.ts'
 import { type CromboloConfig, loadConfig, type ServerRole, VERSION } from './config.ts'
 import { attachDatabase, bootstrapDatabase } from './database.ts'
 import { createDiagnostics } from './diagnostics.ts'
@@ -198,7 +203,7 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
     }
   }
   const domainLog = logger('domains')
-  // Extensions are the site's own npm dependencies (`docs/17-bundles.md`).
+  // Extensions are the site's own npm dependencies (`docs/bundles.md`).
   // Uncached in development so an author editing one sees a reload pick it up.
   const extensions = createExtensionRegistry(config.siteDir, { cache: !config.development })
   const marketplace = createMarketplace({
@@ -207,6 +212,26 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
     marketplaceUrl: config.marketplaceUrl,
     extensions,
     siteDir: config.siteDir,
+    wired: () => bundles?.mounted.map((bundle) => bundle.id) ?? [],
+    contentApplied: async (packageName) =>
+      (await new TransferRunRepository(db).appliedForPackage(packageName))?.packageVersion ?? null,
+    applyContentOnInstall: config.applyBundleContentOnInstall,
+    applyContent: async (packageName) => {
+      const result = await installBundleContent(db, config, { bundle: packageName })
+      if (!result.runId) {
+        const reasons = [
+          ...result.problems,
+          ...result.check.outstanding.map((finding) => finding.message),
+        ]
+        return {
+          applied: false,
+          message: `Its content was not applied: ${reasons.join('; ') || 'the check refused it'}. Resolve that, then run \`crombolo bundle install ${packageName}\`.`,
+        }
+      }
+      // The content landed under a cache this process had already constructed.
+      cache.invalidate()
+      return { applied: true, runId: result.runId, message: 'Its content was applied.' }
+    },
   })
   const paths = createBackOfficePaths({ backOfficePath: config.backOfficePath })
   // Two questions, not one: what this process answers, and what it is
@@ -214,8 +239,17 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
   // `all` and `web` serve the public site.
   const servesBackOffice = config.role !== 'web'
   const owns = config.role !== 'web'
+  // Bundles are checked before the database is touched, because a bundle that
+  // owns tables is migrated at boot, and a bad declaration must not get that far.
+  const bundlePackages = servesBackOffice ? extensions.bundles().bundles : []
+  if (servesBackOffice) {
+    const problems = validateServerBundles(config.bundles, bundlePackages, VERSION)
+    if (problems.length > 0)
+      throw new Error(`The configured bundles cannot be mounted:\n- ${problems.join('\n- ')}`)
+  }
+  const chains = servesBackOffice ? bundleChains(config.bundles, bundlePackages) : []
   const { db, seededAdminPassword } = owns
-    ? await bootstrapDatabase(config)
+    ? await bootstrapDatabase(config, chains)
     : await attachDatabase(config)
   // A configured schema store is copied down before anything reads `schema/`, and
   // becomes the schema directory for this boot. Everything after here — loading,
@@ -351,6 +385,12 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
   const bundles = servesBackOffice
     ? createServerBundles({
         bundles: config.bundles,
+        packages: bundlePackages,
+        coreVersion: VERSION,
+        tables: (bundle) => {
+          const chain = chains.find((candidate) => candidate.id === bundle.id)
+          return chain ? createTablesCapability(db, chain.compiled.schema) : undefined
+        },
         pluginApiPath: `${paths.pluginPath}/api`,
         host: {
           redirects: createBundleRedirects({ db, cache }),
@@ -592,7 +632,7 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
     nodeId: schema.nodeId,
     role: config.role,
   })
-  // App_Plugins is gone (`docs/17-bundles.md`). Saying so beats a site whose
+  // App_Plugins is gone (`docs/bundles.md`). Saying so beats a site whose
   // extensions silently stopped loading after an upgrade; remove at 1.0.
   warnAboutAppPlugins(config.siteDir, log)
   noticeAboutEmail(emailStatus, logger('email'), { development: config.development })
@@ -847,24 +887,44 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
         return Response.json({
           url: marketplace.url(),
           keyword: config.packageKeyword,
+          appliesContent: config.applyBundleContentOnInstall,
           items: await marketplace.search(url.searchParams.get('q') ?? undefined),
         })
       }
 
+      // A created bundle's npm name and version: not in Umbraco's definition, so
+      // not in the contract, and set from the Created view beside it.
+      const created = /^created\/([0-9a-f-]{36})\/package$/i.exec(action)
+      if (created) {
+        const id = created[1] as string
+        if (request.method === 'GET') {
+          const found = await readCreatedBundlePackage(db, id)
+          return found ? Response.json(found) : new Response('Not Found', { status: 404 })
+        }
+        if (request.method === 'PUT') {
+          const body = (await request.json().catch(() => ({}))) as Record<string, unknown>
+          const outcome = await writeCreatedBundlePackage(db, id, body)
+          return Response.json(outcome, { status: outcome.ok ? 200 : 400 })
+        }
+      }
+
       if (action === 'installed' && request.method === 'GET') {
-        return Response.json({ items: marketplace.installed() })
+        return Response.json({ items: await marketplace.installed() })
       }
 
       if ((action === 'install' || action === 'uninstall') && request.method === 'POST') {
         const body = (await request.json().catch(() => ({}))) as {
           name?: unknown
           version?: unknown
+          applyContent?: unknown
         }
         const name = typeof body.name === 'string' ? body.name : ''
         const version = typeof body.version === 'string' ? body.version : undefined
         const outcome =
           action === 'install'
-            ? await marketplace.install(name, version)
+            ? await marketplace.install(name, version, {
+                applyContent: body.applyContent !== false,
+              })
             : await marketplace.uninstall(name)
         log.info('{user} {action} the package {name}: {outcome}', {
           user: principal.email,
@@ -901,7 +961,7 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
     /**
      * Non-contract: forms and their entries. There is no form operation in the
      * vendored contract — Umbraco Forms ships its own API and its own client,
-     * and neither is here — so this is ours (`docs/18-forms.md`).
+     * and neither is here — so this is ours (`docs/forms.md`).
      *
      * Definitions are read from `schema/` per request rather than cached: the
      * files are the truth, the backoffice may have just rewritten one, and a
@@ -924,7 +984,7 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
       const byKey = formsByKey(definitions)
       // Submissions are personal data, so reading them asks for more than a
       // session. Four verbs, because designing a form and reading what people
-      // sent it are different jobs (`docs/18-forms.md`).
+      // sent it are different jobs (`docs/forms.md`).
       const may = (verb: string) => principal.isAdmin || principal.permissions.includes(verb)
       const formFiles = {
         schemaDir: config.schemaDir,
@@ -1122,7 +1182,10 @@ export async function createServer(config: CromboloConfig = loadConfig()): Promi
         source[f.kind] = (source[f.kind] ?? 0) + 1
         bySource[f.source] = source
       }
-      return Response.json({ health: health(), counts, bySource, findings })
+      // A bundle's tables are part of what an upgrade changes, so the dashboard
+      // that shows an upgrade's findings shows their steps too.
+      const bundles = await bundleTablesReport(db, chains)
+      return Response.json({ health: health(), counts, bySource, findings, bundles })
     }
 
     const staticMatch = resolveStaticFile(paths, pathname, {

package/src/status.ts

@@ -27,6 +27,7 @@ import {
   TransferRunRepository,
 } from '@crombolo/data'
 import { loadSchemaDirectory } from '@crombolo/schema'
+import { BundleConfigurationError, bundleChainsFor, pendingBundleSteps } from './bundle-tables.ts'
 import { type CromboloConfig, describeDatabase, VERSION } from './config.ts'
 import { type EmailAvailability, emailAvailability, resolveEmailPort } from './email.ts'
 import { assertViewRuntime } from './view-runtime.ts'
@@ -60,6 +61,12 @@ export interface SiteStatus {
     pending: boolean
   }
   framework: { pending: string[] }
+  /**
+   * Each wired bundle that owns tables, by id: its chain's state and the steps
+   * still to run. Only a node that mounts bundles applies them, so this is what
+   * such a node would refuse to boot over in production.
+   */
+  bundles: Record<string, { name: string; state: string | null; pending: string[] }>
   content: { documents: number; media: number; elements: number; lastImport?: string }
   /**
    * Open findings by kind. `auto` ones are reported, not counted against the
@@ -140,6 +147,7 @@ export async function siteStatus(config: CromboloConfig): Promise<SiteStatus> {
       pending: false,
     },
     framework: { pending: [] },
+    bundles: {},
     content: { documents: 0, media: 0, elements: 0 },
     findings: { blocking: 0, person: 0, auto: 0, resolved: 0 },
     versions: { crombolo: VERSION, backoffice: backofficeVersion(), bun: Bun.version },
@@ -189,6 +197,27 @@ export async function siteStatus(config: CromboloConfig): Promise<SiteStatus> {
         `${status.framework.pending.length} framework migration(s) pending: run \`crombolo upgrade\``,
       )
 
+    try {
+      const chains = bundleChainsFor(config)
+      for (const chain of chains)
+        status.bundles[chain.id] = { name: chain.name, state: null, pending: [] }
+      for (const bundle of await pendingBundleSteps(db, chains)) {
+        status.bundles[bundle.id] = {
+          name: bundle.name,
+          state: bundle.state,
+          pending: bundle.pending.map((step) => step.name),
+        }
+        if (bundle.pending.length > 0 && !config.development)
+          status.problems.push(
+            `the bundle "${bundle.id}" has ${bundle.pending.length} step(s) pending: run \`crombolo upgrade\``,
+          )
+      }
+    } catch (error) {
+      if (error instanceof BundleConfigurationError)
+        for (const problem of error.problems) status.problems.push(problem)
+      else status.problems.push((error as Error).message)
+    }
+
     const state = await currentSchemaState(db)
     status.schema.database = { version: state.version, revision: state.revision }
     if (loaded) {

package/src/tar.ts

@@ -0,0 +1,85 @@
+/**
+ * A minimal npm package tarball writer: a gzipped ustar archive with every entry
+ * under `package/`, which is the layout `npm pack` produces and `bun add
+ * ./file.tgz` and `bun publish` read (`docs/bundles.md`).
+ *
+ * No dependency: the format is 512-byte headers and padded file bodies, and
+ * `Bun.gzipSync` does the compression. Timestamps are fixed, as npm fixes them,
+ * so the same selection packs to the same bytes.
+ */
+
+export interface TarEntry {
+  /** The path inside the package, `/`-separated and never absolute. */
+  path: string
+  bytes: Uint8Array
+}
+
+const BLOCK = 512
+
+/** 1985-10-26T08:15:00Z, the mtime npm writes into every packed file. */
+const NPM_MTIME = 499162500
+
+const encoder = new TextEncoder()
+
+/** An octal field, NUL-terminated and zero-padded to its width. */
+function octal(value: number, width: number): Uint8Array {
+  return encoder.encode(`${value.toString(8).padStart(width - 1, '0')}\0`)
+}
+
+/**
+ * Splits a path across ustar's `prefix` (155 bytes) and `name` (100 bytes) at a
+ * slash, which is how a path longer than 100 bytes is written without an
+ * extension header.
+ */
+function splitPath(path: string): { name: string; prefix: string } {
+  if (encoder.encode(path).length <= 100) return { name: path, prefix: '' }
+  for (let i = path.lastIndexOf('/'); i > 0; i = path.lastIndexOf('/', i - 1)) {
+    const prefix = path.slice(0, i)
+    const name = path.slice(i + 1)
+    if (encoder.encode(prefix).length <= 155 && encoder.encode(name).length <= 100)
+      return { name, prefix }
+  }
+  throw new Error(`${path} is too long to pack`)
+}
+
+function header(path: string, size: number): Uint8Array {
+  const block = new Uint8Array(BLOCK)
+  const put = (bytes: Uint8Array, offset: number) => block.set(bytes, offset)
+  const { name, prefix } = splitPath(path)
+  put(encoder.encode(name), 0)
+  put(octal(0o644, 8), 100)
+  put(octal(0, 8), 108)
+  put(octal(0, 8), 116)
+  put(octal(size, 12), 124)
+  put(octal(NPM_MTIME, 12), 136)
+  // The checksum is computed with its own field read as spaces.
+  put(encoder.encode('        '), 148)
+  put(encoder.encode('0'), 156)
+  put(encoder.encode('ustar\0'), 257)
+  put(encoder.encode('00'), 263)
+  put(encoder.encode(prefix), 345)
+  const sum = block.reduce((total, byte) => total + byte, 0)
+  put(encoder.encode(`${sum.toString(8).padStart(6, '0')}\0 `), 148)
+  return block
+}
+
+/** The entries as an npm package tarball, each under `package/`. */
+export function writeNpmTarball(entries: readonly TarEntry[]): Uint8Array<ArrayBuffer> {
+  const parts: Uint8Array[] = []
+  for (const entry of entries) {
+    if (entry.path.startsWith('/') || entry.path.split('/').includes('..'))
+      throw new Error(`${entry.path} is not a path inside the package`)
+    parts.push(header(`package/${entry.path}`, entry.bytes.length), entry.bytes)
+    const pad = (BLOCK - (entry.bytes.length % BLOCK)) % BLOCK
+    if (pad > 0) parts.push(new Uint8Array(pad))
+  }
+  // Two empty blocks end the archive.
+  parts.push(new Uint8Array(BLOCK * 2))
+  const tar = new Uint8Array(parts.reduce((total, part) => total + part.length, 0))
+  let offset = 0
+  for (const part of parts) {
+    tar.set(part, offset)
+    offset += part.length
+  }
+  return Bun.gzipSync(tar) as Uint8Array<ArrayBuffer>
+}

package/src/zip.ts

@@ -1,6 +1,6 @@
 /**
  * A minimal zip writer, because a created package is a zip and nothing else
- * here needs one (`docs/17-bundles.md`).
+ * here needs one (`docs/bundles.md`).
  *
  * No dependency: `node:zlib` provides `deflateRawSync` and `crc32`, which is
  * everything the format needs. Entries are written in the order given, each