@nuasite/cms-core 0.43.0-beta.1

package/src/fs/glob.ts

@@ -0,0 +1,32 @@
+/** Convert a glob pattern (supports `*`, `**`, `?`, `{a,b}`) to an anchored RegExp. */
+export function globToRegExp(glob: string): RegExp {
+	let re = ''
+	for (let i = 0; i < glob.length; i++) {
+		const c = glob[i]!
+		if (c === '*') {
+			if (glob[i + 1] === '*') {
+				re += '.*'
+				i++
+				if (glob[i + 1] === '/') i++
+			} else {
+				re += '[^/]*'
+			}
+		} else if (c === '?') {
+			re += '[^/]'
+		} else if (c === '{') {
+			const end = glob.indexOf('}', i)
+			if (end === -1) {
+				re += '\\{'
+			} else {
+				const opts = glob.slice(i + 1, end).split(',').map(s => s.replace(/[.+^${}()|[\]\\]/g, '\\$&'))
+				re += `(?:${opts.join('|')})`
+				i = end
+			}
+		} else if ('.+^$()|[]\\'.includes(c)) {
+			re += `\\${c}`
+		} else {
+			re += c
+		}
+	}
+	return new RegExp(`^${re}$`)
+}

package/src/fs/node-fs.ts

@@ -0,0 +1,138 @@
+import type { Dirent } from 'node:fs'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { globToRegExp } from './glob'
+import type { CmsFileSystem } from './types'
+
+/**
+ * Resolve a port-relative (or absolute) path against `root` and ensure it stays
+ * within `root`. Mirrors the previous `resolveAndValidatePath` behavior:
+ * - absolute filesystem paths under the root pass through;
+ * - a project-relative path with a leading slash (e.g. `/src/content/...`) has
+ *   it stripped before joining with the root;
+ * - any path that escapes the root throws.
+ */
+function resolveWithinRoot(root: string, filePath: string): string {
+	const resolvedRoot = path.resolve(root)
+	const isAbsoluteFs = filePath.startsWith(resolvedRoot)
+	const normalizedPath = (!isAbsoluteFs && filePath.startsWith('/')) ? filePath.slice(1) : filePath
+	const fullPath = path.isAbsolute(normalizedPath) ? path.resolve(normalizedPath) : path.resolve(resolvedRoot, normalizedPath)
+
+	if (!fullPath.startsWith(resolvedRoot + path.sep) && fullPath !== resolvedRoot) {
+		throw new Error(`Path traversal detected: ${filePath}`)
+	}
+
+	return fullPath
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && 'code' in error
+}
+
+/** Recursively list files under `absDir`, returning forward-slash paths relative to `absRoot`. */
+async function walkFiles(absRoot: string, absDir: string): Promise<string[]> {
+	let dirEntries: Dirent[]
+	try {
+		dirEntries = await fs.readdir(absDir, { withFileTypes: true })
+	} catch {
+		return []
+	}
+	const out: string[] = []
+	for (const entry of dirEntries) {
+		const abs = path.join(absDir, entry.name)
+		if (entry.isDirectory()) {
+			out.push(...await walkFiles(absRoot, abs))
+		} else if (entry.isFile()) {
+			out.push(path.relative(absRoot, abs).split(path.sep).join('/'))
+		}
+	}
+	return out
+}
+
+/** The longest leading directory of a glob pattern that contains no glob metacharacters. */
+function staticPrefixDir(pattern: string): string {
+	const segments = pattern.split('/')
+	const staticSegments: string[] = []
+	for (const segment of segments) {
+		if (/[*?{}[\]]/.test(segment)) break
+		staticSegments.push(segment)
+	}
+	// Drop the last segment if it is the (potentially globbed) file part: a static prefix
+	// must be a directory, so only keep segments that precede the first globbed segment.
+	if (staticSegments.length === segments.length) {
+		staticSegments.pop()
+	}
+	return staticSegments.join('/')
+}
+
+/**
+ * Create a `CmsFileSystem` backed by `node:fs`, rooted at `root`.
+ * Every path is resolved relative to `root` and validated to stay within it.
+ */
+export function createNodeFs(root: string): CmsFileSystem {
+	const resolvedRoot = path.resolve(root)
+	const resolve = (p: string) => resolveWithinRoot(resolvedRoot, p)
+
+	return {
+		async readFile(filePath) {
+			return fs.readFile(resolve(filePath), 'utf-8')
+		},
+
+		async writeFile(filePath, content) {
+			const fullPath = resolve(filePath)
+			await fs.mkdir(path.dirname(fullPath), { recursive: true })
+			// Atomic write: write to a unique temp file in the same directory, then rename.
+			// A killed write leaves only the temp file, never a half-written target.
+			const tempPath = `${fullPath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`
+			try {
+				await fs.writeFile(tempPath, content, 'utf-8')
+				await fs.rename(tempPath, fullPath)
+			} catch (error) {
+				await fs.rm(tempPath, { force: true })
+				throw error
+			}
+		},
+
+		async rename(from, to) {
+			const fullTo = resolve(to)
+			await fs.mkdir(path.dirname(fullTo), { recursive: true })
+			await fs.rename(resolve(from), fullTo)
+		},
+
+		async remove(filePath) {
+			await fs.rm(resolve(filePath), { force: true })
+		},
+
+		async exists(filePath) {
+			try {
+				await fs.access(resolve(filePath))
+				return true
+			} catch {
+				return false
+			}
+		},
+
+		async list(dir) {
+			try {
+				const entries = await fs.readdir(resolve(dir), { withFileTypes: true })
+				return entries.map(entry => ({ name: entry.name, isDirectory: entry.isDirectory() }))
+			} catch (error) {
+				if (isNodeError(error) && error.code === 'ENOENT') return []
+				throw error
+			}
+		},
+
+		async glob(pattern) {
+			const baseRel = staticPrefixDir(pattern)
+			const absBase = resolve(baseRel)
+			const matcher = globToRegExp(pattern)
+			const files = await walkFiles(resolvedRoot, absBase)
+			return files.filter(rel => matcher.test(rel))
+		},
+
+		async stat(filePath) {
+			const s = await fs.stat(resolve(filePath))
+			return { mtimeMs: s.mtimeMs, size: s.size }
+		},
+	}
+}

package/src/fs/types.ts

@@ -0,0 +1,26 @@
+/**
+ * The FileSystem port: the only I/O boundary of cms-core.
+ *
+ * All paths are interpreted relative to the implementation's configured root.
+ * Implementations must resolve them under the root and reject any path that
+ * escapes it (path traversal). The same brain therefore runs unchanged over
+ * `node:fs` (sidecar + local dev) and, in principle, over a remote adapter.
+ */
+export interface CmsFileSystem {
+	/** Read a UTF-8 text file. Rejects when the file does not exist. */
+	readFile(path: string): Promise<string>
+	/** Write a UTF-8 text file atomically (write temp + rename). Creates parent dirs. */
+	writeFile(path: string, content: string): Promise<void>
+	/** Rename/move a file. Creates the destination's parent dir. */
+	rename(from: string, to: string): Promise<void>
+	/** Remove a file. No-op when it does not exist. */
+	remove(path: string): Promise<void>
+	/** Whether a file or directory exists. */
+	exists(path: string): Promise<boolean>
+	/** List the immediate children of a directory. Returns [] when it does not exist. */
+	list(dir: string): Promise<{ name: string; isDirectory: boolean }[]>
+	/** Resolve a glob pattern (supports `*`, `**`, `?`, `{a,b}`) to matching file paths, root-relative. */
+	glob(pattern: string): Promise<string[]>
+	/** File metadata. Rejects when the path does not exist. */
+	stat(path: string): Promise<{ mtimeMs: number; size: number }>
+}