@crombolo/cli 0.9.1 → 0.11.0

package/src/templates.ts

@@ -29,7 +29,7 @@ export const TEMPLATES_DIR = join(import.meta.dir, '..', 'templates')
  * Written into the site's own files rather than hidden anywhere, because that
  * import is the whole of what lets a bundle answer a request — so it has to be
  * a line the developer owns from the first commit and can delete
- * (`docs/17-bundles.md`).
+ * (`docs/bundles.md`).
  */
 export interface TemplateServerBundle {
   /** The npm package, added to the site's dependencies. */

package/templates/basic/bundle/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "basic",
+  "version": "1.0.0",
+  "private": true,
+  "files": [
+    "content"
+  ],
+  "peerDependencies": {
+    "@crombolo/crombolo": "^0.11.0"
+  },
+  "crombolo": {
+    "id": "basic",
+    "name": "Basic",
+    "content": "content"
+  }
+}

package/templates/demo/harbourstone/bundle/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "demo-harbourstone",
+  "version": "1.0.0",
+  "private": true,
+  "files": [
+    "content"
+  ],
+  "peerDependencies": {
+    "@crombolo/crombolo": "^0.11.0"
+  },
+  "crombolo": {
+    "id": "demo-harbourstone",
+    "name": "Harbourstone Distillery",
+    "content": "content"
+  }
+}

package/templates/demo/harbourstone/files/schema/forms/contact.toml

@@ -1,5 +1,5 @@
 # A form is structure, so it is a file like the content types beside it and a
-# change to it shows up in a diff (`docs/18-forms.md`). The Contact page points
+# change to it shows up in a diff (`docs/forms.md`). The Contact page points
 # at this one through its `enquiryForm` property, and `components/contactPage.tsx`
 # renders it with `<Form>`.
 #
@@ -103,7 +103,7 @@ minimum-submit-seconds = 3
     mandatory-message = "We cannot store your message without this"
 
 # Telling somebody about a submission takes an e-mail provider, which this
-# template does not configure — see `docs/14-configuration.md`. With
+# template does not configure — see `docs/configuration.md`. With
 # CROMBOLO_EMAIL_* set, uncomment this and the message is mailed on submit; the
 # queue retries, so a provider that is briefly down loses nothing.
 #

package/templates/starter/bundle/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "starter",
+  "version": "1.0.0",
+  "private": true,
+  "files": [
+    "content"
+  ],
+  "peerDependencies": {
+    "@crombolo/crombolo": "^0.11.0"
+  },
+  "crombolo": {
+    "id": "starter",
+    "name": "Starter",
+    "content": "content"
+  }
+}

package/src/operations/sections.ts

@@ -1,423 +0,0 @@
-/**
- * The sections a bundle carries beyond its content: schema, views, partials,
- * styles, scripts and dictionary items. `docs/17-bundles.md`.
- *
- * A bundle names what a file *is*, never where it goes — the destination site
- * decides that from its own configuration, so a bundle written against one
- * layout installs into another. This module owns that mapping, and the order
- * applying them has to happen in: structure before the content that needs it,
- * views before the content that names a template.
- *
- * Checking is read-only and has to answer "what would the schema do" *before*
- * anything is written, which `checkSchemaDirectory` cannot do against files that
- * are not there yet. So the check runs against a copy of the site's `schema/`
- * with the bundle's files laid over it — the site's own directory is never
- * touched until an apply.
- */
-import {
-  copyFileSync,
-  cpSync,
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  renameSync,
-  rmSync,
-  writeFileSync,
-} from 'node:fs'
-import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
-import type { Db } from '@crombolo/data'
-import type { CromboloConfig } from '@crombolo/server'
-import { checkSchemaDirectory, importDictionaryUdt, syncSchemaDirectory } from '@crombolo/server'
-import type { BundleSection, LoadedBundle } from '@crombolo/transfer'
-import { BUNDLE_SECTIONS } from '@crombolo/transfer'
-
-/** What applying one carried file would do to the destination. */
-export type FileAction = 'create' | 'overwrite' | 'unchanged'
-
-export interface SectionFile {
-  /** The path inside the bundle, e.g. `views/homePage.tsx`. */
-  path: string
-  /** Where it would land on this site. */
-  target: string
-  action: FileAction
-}
-
-export interface SectionPlan {
-  files: SectionFile[]
-  /** How many dictionary items the bundle carries, when it carries any. */
-  dictionaryItems: number
-  /**
-   * What the schema half would do, checked against an overlay rather than the
-   * site: `none` when the bundle carries no schema.
-   */
-  schema: { classification: string; findings: string[] } | undefined
-  /** Sections present in the bundle, for a caller that only wants to say so. */
-  sections: BundleSection[]
-}
-
-export interface SectionOptions {
-  /** Skip the schema half, leaving the site's own structure alone. */
-  withoutSchema?: boolean
-  /** Skip views, partials, styles and scripts. */
-  withoutFiles?: boolean
-  /**
-   * Allow replacing files this site already has.
-   *
-   * Off by default, and an install is refused while any file would be
-   * replaced. These files are editable in the backoffice — a stylesheet, a
-   * template, a content type — so overwriting one destroys somebody's work,
-   * and this site may well have no git to recover it from.
-   */
-  replaceFiles?: boolean
-}
-
-/**
- * Where an install keeps the files it replaced, under the site.
- *
- * A sibling of the components cache, not inside it: `.crombolo/components` is
- * rebuilt from `components/` and cleared at boot, and these have to outlive a
- * restart to be worth taking.
- */
-export const RUN_BACKUP_DIR = join('.crombolo', 'transfer')
-
-/** What one install did to the files, so a revert can undo exactly that. */
-interface FileRecord {
-  path: string
-  action: FileAction
-}
-
-const RECORD_FILE = 'files.json'
-const REPLACED_DIR = 'replaced'
-
-/** Where each section lands, from the site's own configuration. */
-function destinationOf(config: CromboloConfig, section: BundleSection): string | undefined {
-  switch (section) {
-    case 'schema':
-      return config.schemaDir
-    case 'components':
-      return config.componentsDir
-    case 'styles':
-      return config.stylesheetsDir
-    case 'scripts':
-      return config.scriptsDir
-    case 'dictionary':
-      return undefined
-  }
-}
-
-const FILE_SECTIONS: readonly BundleSection[] = ['components', 'styles', 'scripts']
-
-/** The path inside a section, with the section's own directory stripped. */
-const withinSection = (path: string, section: BundleSection): string =>
-  path.slice(`${BUNDLE_SECTIONS[section]}/`.length)
-
-function actionFor(target: string, content: string): FileAction {
-  if (!existsSync(target)) return 'create'
-  try {
-    return readFileSync(target, 'utf8') === content ? 'unchanged' : 'overwrite'
-  } catch {
-    return 'overwrite'
-  }
-}
-
-export interface CarriedSections {
-  /** Section → the bundle paths it carries. */
-  carries: Partial<Record<BundleSection, string[]>>
-  /** Bundle path → the file on disk holding it. */
-  files: Map<string, string>
-}
-
-/** What a loaded bundle carries, or nothing when it is content-only. */
-export function carriedSections(loaded: LoadedBundle): CarriedSections {
-  return { carries: loaded.set?.manifest.carries ?? {}, files: loaded.files }
-}
-
-const read = (carried: CarriedSections, path: string): string => {
-  const file = carried.files.get(path)
-  if (!file) throw new Error(`${path} is declared but was not read`)
-  return readFileSync(file, 'utf8')
-}
-
-/** Read-only: what applying the carried sections here would do. */
-export async function planSections(
-  db: Db,
-  config: CromboloConfig,
-  carried: CarriedSections,
-  options: SectionOptions = {},
-): Promise<SectionPlan> {
-  const sections = Object.keys(carried.carries) as BundleSection[]
-  const files: SectionFile[] = []
-
-  if (!options.withoutFiles) {
-    for (const section of FILE_SECTIONS) {
-      const destination = destinationOf(config, section)
-      if (!destination) continue
-      for (const path of carried.carries[section] ?? []) {
-        const target = join(destination, withinSection(path, section))
-        files.push({ path, target, action: actionFor(target, read(carried, path)) })
-      }
-    }
-  }
-
-  const schemaPaths = options.withoutSchema ? [] : (carried.carries.schema ?? [])
-  if (!options.withoutSchema) {
-    for (const path of schemaPaths) {
-      const target = join(config.schemaDir, withinSection(path, 'schema'))
-      files.push({ path, target, action: actionFor(target, read(carried, path)) })
-    }
-  }
-
-  return {
-    files,
-    dictionaryItems: (carried.carries.dictionary ?? []).length,
-    schema:
-      schemaPaths.length > 0
-        ? await checkSchemaOverlay(db, config, carried, schemaPaths)
-        : undefined,
-    sections,
-  }
-}
-
-/**
- * The schema check, run against a copy of the site's `schema/` with the
- * bundle's files laid over it.
- *
- * The site's directory is not written to: a check has to be able to say "this
- * would need data work" without having already changed the thing it is
- * reporting on.
- */
-async function checkSchemaOverlay(
-  db: Db,
-  config: CromboloConfig,
-  carried: CarriedSections,
-  paths: readonly string[],
-): Promise<{ classification: string; findings: string[] }> {
-  const overlay = mkdtempSync(join(tmpdir(), 'crombolo-schema-overlay-'))
-  try {
-    if (existsSync(config.schemaDir)) cpSync(config.schemaDir, overlay, { recursive: true })
-    for (const path of paths) {
-      const target = join(overlay, withinSection(path, 'schema'))
-      mkdirSync(dirname(target), { recursive: true })
-      writeFileSync(target, read(carried, path))
-    }
-    const report = await checkSchemaDirectory(
-      db,
-      { ...config, schemaDir: overlay },
-      { nodeId: config.nodeId, revision: config.schemaRevision },
-    )
-    return {
-      classification: report.classification,
-      findings: report.outstanding.map((finding) => finding.message),
-    }
-  } finally {
-    rmSync(overlay, { recursive: true, force: true })
-  }
-}
-
-export interface SectionResult {
-  /** The files written, by the path they were written to. */
-  written: string[]
-  /** Those that replaced something, whose originals were kept. */
-  replaced: string[]
-  /** The schema sync's outcome, when the bundle carried schema. */
-  schema: { action: string } | undefined
-  dictionary: { imported: number; skipped: string[] } | undefined
-}
-
-/**
- * Applies the carried sections, structure first.
- *
- * Schema goes to `schema/` and is then synced — the same path a commit takes,
- * so an install cannot produce a database the files do not describe. Views land
- * before content is imported, because a node naming a template whose view is
- * absent arrives without one.
- */
-export async function applySections(
-  db: Db,
-  config: CromboloConfig,
-  carried: CarriedSections,
-  options: SectionOptions & { backupDir?: string } = {},
-): Promise<SectionResult> {
-  const written: string[] = []
-  const replaced: string[] = []
-  const records: FileRecord[] = []
-
-  /**
-   * Writes one file, keeping what was there.
-   *
-   * The original is copied under its *bundle* path rather than its path on this
-   * site, so a revert re-derives the destination through the same mapping — and
-   * restores to where the file would go now, not where it went then.
-   */
-  const put = (target: string, content: string, bundlePath: string) => {
-    const action = actionFor(target, content)
-    if (action === 'overwrite' && options.backupDir) {
-      const keep = join(options.backupDir, REPLACED_DIR, bundlePath)
-      mkdirSync(dirname(keep), { recursive: true })
-      copyFileSync(target, keep)
-      replaced.push(target)
-    }
-    records.push({ path: bundlePath, action })
-    mkdirSync(dirname(target), { recursive: true })
-    writeFileSync(target, content)
-    written.push(target)
-  }
-
-  const schemaPaths = options.withoutSchema ? [] : (carried.carries.schema ?? [])
-  for (const path of schemaPaths)
-    put(join(config.schemaDir, withinSection(path, 'schema')), read(carried, path), path)
-
-  let schema: { action: string } | undefined
-  if (schemaPaths.length > 0) {
-    const report = await syncSchemaDirectory(db, config, {
-      nodeId: config.nodeId,
-      revision: config.schemaRevision,
-    })
-    schema = { action: report.action }
-  }
-
-  if (!options.withoutFiles) {
-    for (const section of FILE_SECTIONS) {
-      const destination = destinationOf(config, section)
-      if (!destination) continue
-      for (const path of carried.carries[section] ?? [])
-        put(join(destination, withinSection(path, section)), read(carried, path), path)
-    }
-  }
-
-  let dictionary: SectionResult['dictionary']
-  for (const path of carried.carries.dictionary ?? []) {
-    const outcome = await importDictionaryUdt(db, read(carried, path))
-    dictionary = {
-      imported: (dictionary?.imported ?? 0) + outcome.imported,
-      skipped: [...(dictionary?.skipped ?? []), ...outcome.skipped],
-    }
-  }
-
-  // Written last: a record that exists means the files beside it are complete.
-  if (options.backupDir && records.length > 0) {
-    mkdirSync(options.backupDir, { recursive: true })
-    writeFileSync(join(options.backupDir, RECORD_FILE), `${JSON.stringify(records, null, 2)}\n`)
-  }
-
-  return { written, replaced, schema, dictionary }
-}
-
-/** Whether a bundle carries anything beyond its content. */
-export const carriesSections = (carried: CarriedSections): boolean =>
-  Object.keys(carried.carries).length > 0
-
-/**
- * The files an install would replace, and so may not touch without being told
- * it may.
- *
- * Its own function rather than a condition inside the importer, because this is
- * the rule that stops an install destroying an editor's work: a stylesheet, a
- * template or a content type changed in the backoffice, on a site that may
- * have no git behind it. `unchanged` is not a replacement, and a declined
- * section never reaches the plan.
- */
-export function replacementsNeedingPermission(
-  plan: SectionPlan,
-  options: SectionOptions = {},
-): SectionFile[] {
-  if (options.replaceFiles) return []
-  return plan.files.filter((file) => file.action === 'overwrite')
-}
-
-/** A staging directory for an install's backups, before the run it belongs to exists. */
-export function stageBackups(config: CromboloConfig): string {
-  const dir = join(config.siteDir, RUN_BACKUP_DIR, `pending-${Date.now().toString(36)}`)
-  mkdirSync(dir, { recursive: true })
-  return dir
-}
-
-/**
- * Files an install replaced belong to the run that imported its content, and
- * the run id only exists once that import has happened — so the backups are
- * staged first and moved here afterwards.
- *
- * A staging directory that is never promoted is an install whose content was
- * refused after its files had landed. It is left where it is rather than
- * deleted: it holds the only copy of what was replaced.
- */
-export function promoteBackups(
-  config: CromboloConfig,
-  staging: string,
-  runId: string,
-): string | undefined {
-  if (!existsSync(join(staging, RECORD_FILE))) {
-    rmSync(staging, { recursive: true, force: true })
-    return undefined
-  }
-  const target = join(config.siteDir, RUN_BACKUP_DIR, runId)
-  rmSync(target, { recursive: true, force: true })
-  mkdirSync(dirname(target), { recursive: true })
-  renameSync(staging, target)
-  return target
-}
-
-export interface RestoredFiles {
-  /** Files put back to what they were before the install. */
-  restored: string[]
-  /** Files the install created, and which reverting therefore removes. */
-  removed: string[]
-}
-
-/**
- * Puts back what an install replaced, for a run that is being reverted.
- *
- * Undoing an install is one action because of this: the content comes back
- * through the ledger, and the files come back from here. Nothing depends on the
- * site being a git checkout — these files are editable in the backoffice, so
- * assuming a repository would have been assuming somebody else's workflow.
- */
-export function restoreSectionFiles(config: CromboloConfig, runId: string): RestoredFiles {
-  const dir = join(config.siteDir, RUN_BACKUP_DIR, runId)
-  const record = join(dir, RECORD_FILE)
-  if (!existsSync(record)) return { restored: [], removed: [] }
-
-  let records: FileRecord[]
-  try {
-    records = JSON.parse(readFileSync(record, 'utf8')) as FileRecord[]
-  } catch {
-    return { restored: [], removed: [] }
-  }
-
-  const restored: string[] = []
-  const removed: string[] = []
-  for (const entry of records) {
-    const section = sectionFor(entry.path)
-    if (!section) continue
-    const destination = destinationOf(config, section)
-    if (!destination) continue
-    const target = join(destination, withinSection(entry.path, section))
-
-    if (entry.action === 'overwrite') {
-      const kept = join(dir, REPLACED_DIR, entry.path)
-      if (!existsSync(kept)) continue
-      mkdirSync(dirname(target), { recursive: true })
-      copyFileSync(kept, target)
-      restored.push(target)
-      continue
-    }
-    // A file the install created: reverting takes it away again. `unchanged`
-    // is left alone — the install did not put it there.
-    if (entry.action === 'create' && existsSync(target)) {
-      rmSync(target, { force: true })
-      removed.push(target)
-    }
-  }
-  return { restored, removed }
-}
-
-/** The section a bundle path belongs to, by its leading directory. */
-function sectionFor(path: string): BundleSection | undefined {
-  if (path === `${BUNDLE_SECTIONS.dictionary}.udt`) return 'dictionary'
-  const top = path.split('/')[0]
-  for (const [section, dir] of Object.entries(BUNDLE_SECTIONS))
-    if (top === dir) return section as BundleSection
-  return undefined
-}