@lightnet/cli 4.2.0 → 4.3.0

package/src/support/content-collections.js

@@ -0,0 +1,191 @@
+// @ts-check
+
+import { posix, relative, resolve } from "node:path"
+
+import { CliError } from "./cli-error.js"
+import { jsonFiles, pathExists, readJsonFile } from "./filesystem.js"
+
+const mediaDir = "src/content/media"
+const categoriesDir = "src/content/categories"
+
+/**
+ * @typedef {{
+ *   type: "upload"|"link"
+ *   url: string
+ * }} MediaContent
+ */
+
+/**
+ * @typedef {{
+ *   path: string
+ *   id: string
+ *   image: string
+ *   content: MediaContent[]
+ * }} MediaItem
+ */
+
+/**
+ * @typedef {{
+ *   path: string
+ *   id: string
+ *   image?: string
+ * }} Category
+ */
+
+/**
+ * @typedef {{
+ *   getMediaItems: () => Promise<MediaItem[]>
+ *   getCategories: () => Promise<Category[]>
+ * }} ContentCollections
+ */
+
+/**
+ * @param {string} cwd
+ * @returns {ContentCollections}
+ */
+export function contentCollections(cwd) {
+  return {
+    async getMediaItems() {
+      const files = await jsonFiles(resolve(cwd, mediaDir))
+      return Promise.all(files.map((filePath) => readMediaItem(cwd, filePath)))
+    },
+    async getCategories() {
+      const absoluteDir = resolve(cwd, categoriesDir)
+      if (!(await pathExists(absoluteDir))) {
+        return []
+      }
+      const files = await jsonFiles(absoluteDir)
+      return Promise.all(files.map((filePath) => readCategory(cwd, filePath)))
+    },
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} filePath
+ * @returns {Promise<MediaItem>}
+ */
+async function readMediaItem(cwd, filePath) {
+  const value = await readJsonFile(filePath)
+  if (!isPlainObject(value)) {
+    throw new CliError(
+      `Invalid media item in "${filePath}": expected an object.`,
+    )
+  }
+
+  const image = readRequiredImageReference(value.image, filePath)
+  const content = readContentArray(value.content, filePath)
+
+  return {
+    path: filePath,
+    id: toCollectionId(cwd, mediaDir, filePath),
+    content,
+    image,
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} filePath
+ * @returns {Promise<Category>}
+ */
+async function readCategory(cwd, filePath) {
+  const value = await readJsonFile(filePath)
+  if (!isPlainObject(value)) {
+    throw new CliError(`Invalid category in "${filePath}": expected an object.`)
+  }
+
+  return {
+    path: filePath,
+    id: toCollectionId(cwd, categoriesDir, filePath),
+    image: readOptionalImageReference(value.image, filePath),
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} collectionDir
+ * @param {string} filePath
+ */
+function toCollectionId(cwd, collectionDir, filePath) {
+  const relativePath = posix.normalize(
+    toPosixPath(relative(resolve(cwd, collectionDir), filePath)),
+  )
+  return relativePath.replace(/\.json$/, "")
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} filePath
+ */
+function readRequiredImageReference(value, filePath) {
+  if (typeof value !== "string") {
+    throw new CliError(`Invalid "image" in "${filePath}": expected a string.`)
+  }
+  return value
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} filePath
+ */
+function readOptionalImageReference(value, filePath) {
+  if (value === undefined) {
+    return undefined
+  }
+  if (typeof value !== "string") {
+    throw new CliError(
+      `Invalid "image" in "${filePath}": expected a string when provided.`,
+    )
+  }
+  return value
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} filePath
+ * @returns {MediaContent[]}
+ */
+function readContentArray(value, filePath) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new CliError(
+      `Invalid "content" in "${filePath}": expected a non-empty array.`,
+    )
+  }
+
+  return value.map((item) => {
+    if (!isPlainObject(item)) {
+      throw new CliError(
+        `Invalid "content" in "${filePath}": expected array items to be objects.`,
+      )
+    }
+    if (item.type !== "upload" && item.type !== "link") {
+      throw new CliError(
+        `Invalid "content.type" in "${filePath}": expected "upload" or "link".`,
+      )
+    }
+    if (typeof item.url !== "string") {
+      throw new CliError(
+        `Invalid "content.url" in "${filePath}": expected a string.`,
+      )
+    }
+    return {
+      type: item.type,
+      url: item.url,
+    }
+  })
+}
+
+/**
+ * @param {unknown} value
+ */
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+/**
+ * @param {string} filePath
+ */
+function toPosixPath(filePath) {
+  return filePath.split("\\").join("/")
+}

package/src/support/filesystem.js

@@ -0,0 +1,216 @@
+// @ts-check
+
+import { access, readdir, readFile, unlink } from "node:fs/promises"
+import { join, posix, relative, resolve } from "node:path"
+
+import { CliError } from "./cli-error.js"
+
+const localJunkFileNames = new Set([".DS_Store"])
+const publicFilesDir = "public/files"
+
+/**
+ * @typedef {{
+ *   init: () => Promise<FileStorage>
+ *   list: () => Promise<string[]>
+ *   delete: (paths: string[]) => Promise<string[]>
+ *   toPath: (url: string) => string|undefined
+ * }} FileStorage
+ */
+
+/**
+ * @param {string} cwd
+ * @returns {FileStorage}
+ */
+export function contentFiles(cwd) {
+  return files(cwd, {
+    displayPath: (path) =>
+      `/${toPosixPath(relative(resolve(cwd, "public"), resolve(cwd, path)))}`,
+    rootDir: publicFilesDir,
+    toAbsolutePath: toLocalContentFilePath,
+    toPath: (url) => (url.startsWith("/files/") ? url : undefined),
+  })
+}
+
+/**
+ * @param {string} cwd
+ * @param {{
+ *   displayPath?: (path:string) => string
+ *   ignoreJunk?: boolean
+ *   rootDir: string
+ *   toAbsolutePath?: (path:string) => string
+ *   toPath?: (url:string) => string|undefined
+ * }} options
+ * @returns {FileStorage}
+ */
+export function files(cwd, options) {
+  const storage = {
+    async init() {
+      return storage
+    },
+    async list() {
+      return collectLocalFiles(resolve(cwd, options.rootDir), {
+        displayPath: options.displayPath ?? ((path) => path),
+        ignoreJunk: options.ignoreJunk ?? true,
+        rootDir: options.rootDir,
+      })
+    },
+    /**
+     * @param {string[]} paths
+     */
+    async delete(paths) {
+      /** @type {string[]} */
+      const removed = []
+      for (const path of paths) {
+        try {
+          await unlink(
+            resolve(
+              cwd,
+              options.toAbsolutePath?.(path) ??
+                toLocalFilePath(options.rootDir, path),
+            ),
+          )
+          removed.push(path)
+        } catch {
+          // The caller prints per-file failures based on the returned paths.
+        }
+      }
+      return removed
+    },
+    /**
+     * @param {string} url
+     */
+    toPath(url) {
+      return options.toPath?.(url)
+    },
+  }
+  return storage
+}
+
+/**
+ * @param {string} dirPath
+ */
+export async function jsonFiles(dirPath) {
+  if (!(await pathExists(dirPath))) {
+    return []
+  }
+  const files = await walkFiles(dirPath)
+  return files.filter((filePath) => filePath.endsWith(".json")).sort()
+}
+
+/**
+ * @param {string} filePath
+ */
+export async function readJsonFile(filePath) {
+  const text = await readFile(filePath, "utf8")
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new CliError(`Invalid JSON in "${filePath}".`)
+  }
+}
+
+/**
+ * @param {string} filePath
+ */
+export async function pathExists(filePath) {
+  try {
+    await access(filePath)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * @param {string} path
+ */
+export function toLocalContentDisplayPath(path) {
+  if (!path.startsWith("/files/")) {
+    return path
+  }
+  return toPosixPath(join(publicFilesDir, path.slice("/files/".length)))
+}
+
+/**
+ * @param {string} absoluteDir
+ * @param {{displayPath:(path:string)=>string, ignoreJunk:boolean, rootDir:string}} options
+ */
+async function collectLocalFiles(absoluteDir, options) {
+  if (!(await pathExists(absoluteDir))) {
+    return []
+  }
+  const files = await walkFiles(absoluteDir)
+  return files
+    .filter((filePath) =>
+      options.ignoreJunk
+        ? !localJunkFileNames.has(posix.basename(filePath))
+        : true,
+    )
+    .map((filePath) =>
+      options.displayPath(
+        toPosixPath(join(options.rootDir, relative(absoluteDir, filePath))),
+      ),
+    )
+    .sort()
+}
+
+/**
+ * @param {string} dirPath
+ */
+async function walkFiles(dirPath) {
+  /** @type {string[]} */
+  const files = []
+  const entries = await readdir(dirPath, { withFileTypes: true })
+  for (const entry of entries) {
+    const entryPath = join(dirPath, entry.name)
+    if (entry.isDirectory()) {
+      files.push(...(await walkFiles(entryPath)))
+    } else if (entry.isFile()) {
+      files.push(entryPath)
+    }
+  }
+  return files
+}
+
+/**
+ * @param {string} path
+ */
+function toLocalContentFilePath(path) {
+  if (!path.startsWith("/files/")) {
+    throw new CliError(`Unexpected local content file path "${path}".`)
+  }
+  const relativePath = path.slice("/files/".length)
+  if (
+    !relativePath ||
+    relativePath.startsWith("/") ||
+    relativePath.includes("../")
+  ) {
+    throw new CliError(`Unexpected local content file path "${path}".`)
+  }
+  return toPosixPath(join(publicFilesDir, relativePath))
+}
+
+/**
+ * @param {string} rootDir
+ * @param {string} path
+ */
+function toLocalFilePath(rootDir, path) {
+  if (!path.startsWith(`${rootDir}/`) && path !== rootDir) {
+    throw new CliError(`Unexpected local file path "${path}".`)
+  }
+  if (path.includes("../")) {
+    throw new CliError(`Unexpected local file path "${path}".`)
+  }
+  return path
+}
+
+/**
+ * @param {string} filePath
+ */
+function toPosixPath(filePath) {
+  return filePath.split("\\").join("/")
+}
+
+/**
+ * @param {string} filePath
+ */