@crombolo/transfer 0.9.1 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crombolo/transfer",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Content transfer for crombolo: bundles of content moved between environments.",
   "license": "MIT",
   "author": "Crombolo",
@@ -28,7 +28,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@crombolo/core": "0.9.1",
-    "@crombolo/data": "0.9.1"
+    "@crombolo/core": "0.10.0",
+    "@crombolo/data": "0.10.0"
   }
 }

package/src/check.ts

@@ -3,7 +3,7 @@
  * from someone first.
  *
  * Read-only, and it runs before every import rather than only when asked
- * (`13-content-transfer.md`). The point is that nothing is written until the
+ * (`content-transfer.md`). The point is that nothing is written until the
  * conflicts are named and answered, so a transfer is never a surprise.
  *
  * Findings share the shape, table, endpoint and dashboard of the pre-upgrade

package/src/import.ts

@@ -59,6 +59,8 @@ export interface ImportOptions extends CheckOptions {
   nodeId?: string
   /** A human label for the run listing. */
   label?: string | undefined
+  /** The npm package the bundle arrived in, recorded on the run. */
+  package?: { name: string; version: string } | undefined
 }
 
 export interface ImportResult {
@@ -158,6 +160,8 @@ export async function importBundle(
         id: runId,
         bundleId: set.manifest.id,
         bundleLabel: options.label ?? null,
+        packageName: options.package?.name ?? null,
+        packageVersion: options.package?.version ?? null,
         direction: 'import',
         revertsRunId: null,
         schemaStateId: state.id,

package/src/index.ts

@@ -3,6 +3,7 @@ export * from './export.ts'
 export * from './import.ts'
 export * from './load.ts'
 export * from './model.ts'
+export * from './package.ts'
 export * from './references.ts'
 export * from './resolutions.ts'
 export * from './revert.ts'

package/src/model.ts

@@ -1,6 +1,6 @@
 /**
  * The bundle: content selected out of one environment and reviewable on its way
- * to another. `docs/13-content-transfer.md`.
+ * to another. `docs/content-transfer.md`.
  *
  * Everything travels by uuid and alias, never by integer id, because the ids
  * differ between environments and the keys do not. A content type is matched by
@@ -32,7 +32,7 @@ export const CONTENT_ONLY_FORMAT_VERSION = 1
  * layout therefore installs into another's.
  *
  * There is one section for components, not two. Umbraco's split of templates
- * and partial views was a Razor concern (`docs/05-rendering.md`), and a bundle
+ * and partial views was a Razor concern (`docs/rendering.md`), and a bundle
  * that carried it would push the distinction back into every site that
  * installed one.
  */

package/src/package.ts

@@ -0,0 +1,84 @@
+/**
+ * A written bundle as the npm package every bundle is: a `package.json` whose
+ * `crombolo` field declares the payload, and the payload under `content/`.
+ * `docs/bundles.md`.
+ *
+ * The payload is `writeBundle`'s output unchanged, so its manifest, integrity
+ * hash and sections mean what they always did. The package is what gives it a
+ * name, a version and a core it was written for.
+ */
+import type { BundleFile } from './write.ts'
+
+/** The directory inside a package that holds the `bundle.json` payload. */
+export const PAYLOAD_DIR = 'content'
+
+/** The npm keyword a bundle publishes so the marketplace can find it. */
+export const BUNDLE_KEYWORD = 'crombolo-bundle'
+
+export interface BundlePackageInfo {
+  /** The npm package name. */
+  name: string
+  version: string
+  /** `crombolo.id`. */
+  id: string
+  /** `crombolo.name`, what a person calls it. */
+  label: string
+  description?: string
+  /** A package that is never published: an environment's export. */
+  private?: boolean
+  /** The range on `@crombolo/crombolo` it is written for. */
+  peerRange: string
+}
+
+const NPM_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/
+
+/** Lowercase words joined by hyphens, from whatever someone named a thing. */
+const slug = (text: string): string =>
+  text
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+
+/** A name npm would accept. */
+export function isPackageName(name: string): boolean {
+  return NPM_NAME.test(name) && name.length <= 214
+}
+
+/** A bundle id, 2–39 characters, derived from a name: what an unset definition defaults to. */
+export function bundleIdFor(text: string): string {
+  let id = slug(text).replace(/^[^a-z]+/, '')
+  if (id.length < 2) id = `bundle-${id}`.replace(/-$/, '')
+  return id.slice(0, 39).replace(/-+$/, '')
+}
+
+/** An unscoped package name derived from a name. */
+export function packageNameFor(text: string): string {
+  return bundleIdFor(text)
+}
+
+/** The `package.json` a bundle package is written with. */
+export function bundlePackageJson(info: BundlePackageInfo): Record<string, unknown> {
+  return {
+    name: info.name,
+    version: info.version,
+    ...(info.description ? { description: info.description } : {}),
+    ...(info.private ? { private: true } : { keywords: [BUNDLE_KEYWORD] }),
+    files: [PAYLOAD_DIR],
+    peerDependencies: { '@crombolo/crombolo': info.peerRange },
+    crombolo: { id: info.id, name: info.label, content: PAYLOAD_DIR },
+  }
+}
+
+/** A payload's files, placed into a package under `content/` beside its `package.json`. */
+export function writeBundlePackage(
+  payload: readonly BundleFile[],
+  info: BundlePackageInfo,
+): BundleFile[] {
+  if (!isPackageName(info.name)) throw new Error(`"${info.name}" is not a package name npm accepts`)
+  return [
+    { path: 'package.json', text: `${JSON.stringify(bundlePackageJson(info), null, 2)}\n` },
+    ...payload.map((file) => ({ ...file, path: `${PAYLOAD_DIR}/${file.path}` })),
+  ]
+}

package/src/resolutions.ts

@@ -2,7 +2,7 @@
  * `resolutions.json`, beside the bundle it answers.
  *
  * A decision is committed with the bundle rather than retyped per environment,
- * for the reason `10-packaging-and-upgrades.md` gives for site-authored value
+ * for the reason `packaging-and-upgrades.md` gives for site-authored value
  * migrations: the same fix-up should not be worked out again in test and then
  * again in production, each time against more content.
  *

package/src/revert.ts

@@ -275,6 +275,8 @@ export async function revertRun(
         id: newRunId,
         bundleId: original.bundleId,
         bundleLabel: `revert of ${runId}`,
+        packageName: original.packageName,
+        packageVersion: original.packageVersion,
         direction: 'revert',
         revertsRunId: runId,
         schemaStateId: state.id,