nebula-cms 0.1.0

package/src/client/js/storage/workers/yaml-parser.ts

@@ -0,0 +1,132 @@
+/*
+ * YAML Parser Worker
+ *
+ * Handles YAML parsing and serialization on behalf of the main thread.
+ * Messages are dispatched by type: 'parse', 'parse-batch', 'stringify'.
+ * Each handler wraps its logic in try/catch and always posts a typed result.
+ */
+
+import { load, dump } from 'js-yaml';
+
+// Inbound message shape for a single YAML parse request.
+interface ParseMessage {
+  type: 'parse';
+  id: string;
+  content: string;
+}
+
+// A single item in a batch parse request.
+interface BatchItem {
+  key: string;
+  content: string;
+}
+
+// Inbound message shape for a batch YAML parse request.
+interface ParseBatchMessage {
+  type: 'parse-batch';
+  id: string;
+  items: BatchItem[];
+}
+
+// Inbound message shape for a YAML stringify request.
+interface StringifyMessage {
+  type: 'stringify';
+  id: string;
+  data: Record<string, unknown>;
+}
+
+// Union of all inbound message types.
+type InboundMessage = ParseMessage | ParseBatchMessage | StringifyMessage;
+
+/*
+//////////////////////////////
+// Message handler
+//////////////////////////////
+*/
+
+/**
+ * Handles a single YAML parse request. Parses the provided content string
+ * and posts a parse-result message with the resulting data object or error.
+ * @param {ParseMessage} msg - The inbound parse message
+ * @return {void}
+ */
+function handleParse(msg: ParseMessage): void {
+  try {
+    const data = load(msg.content) as Record<string, unknown>;
+    self.postMessage({ type: 'parse-result', id: msg.id, ok: true, data });
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    self.postMessage({ type: 'parse-result', id: msg.id, ok: false, error });
+  }
+}
+
+/**
+ * Handles a batch YAML parse request. Iterates over all items, parses each
+ * one, and posts a parse-batch-result with a key-to-data results map.
+ * If any item fails to parse, the entire batch result is marked as failed.
+ * @param {ParseBatchMessage} msg - The inbound parse-batch message
+ * @return {void}
+ */
+function handleParseBatch(msg: ParseBatchMessage): void {
+  try {
+    const results: Record<string, Record<string, unknown>> = {};
+    for (const item of msg.items) {
+      results[item.key] = load(item.content) as Record<string, unknown>;
+    }
+    self.postMessage({
+      type: 'parse-batch-result',
+      id: msg.id,
+      ok: true,
+      results,
+    });
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    self.postMessage({
+      type: 'parse-batch-result',
+      id: msg.id,
+      ok: false,
+      error,
+    });
+  }
+}
+
+/**
+ * Handles a YAML stringify request. Serializes the provided data object to
+ * a YAML string and posts a stringify-result message with the content.
+ * lineWidth: -1 disables js-yaml's automatic line folding so long values
+ * are not wrapped across lines, which would corrupt multi-line string values.
+ * @param {StringifyMessage} msg - The inbound stringify message
+ * @return {void}
+ */
+function handleStringify(msg: StringifyMessage): void {
+  try {
+    const content = dump(msg.data, { lineWidth: -1 });
+    self.postMessage({
+      type: 'stringify-result',
+      id: msg.id,
+      ok: true,
+      content,
+    });
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    self.postMessage({
+      type: 'stringify-result',
+      id: msg.id,
+      ok: false,
+      error,
+    });
+  }
+}
+
+// Listen for messages from the main thread and dispatch by type
+self.addEventListener('message', (event: MessageEvent<InboundMessage>) => {
+  const msg = event.data;
+
+  if (msg.type === 'parse') {
+    handleParse(msg);
+  } else if (msg.type === 'parse-batch') {
+    handleParseBatch(msg);
+  } else if (msg.type === 'stringify') {
+    handleStringify(msg);
+  }
+});

package/src/client/js/utils/file-types.ts

@@ -0,0 +1,192 @@
+/*
+ * File Type Registry
+ * Central source of truth for supported file formats. All other modules
+ * (storage adapters, orchestrator worker, editor, publish handler) derive
+ * extension lists, category, and serialization format from this registry.
+ */
+
+// Configuration for a single supported file type.
+export type FileTypeConfig = {
+  // All file extensions associated with this type, first entry is the default.
+  extensions: string[];
+  // Whether this type has a body editor (markdown/MDX/Markdoc).
+  hasBody: boolean;
+  // Whether the file holds frontmatter+body or pure data.
+  category: 'frontmatter' | 'data';
+  // For data files, which serialization format to use.
+  dataFormat?: 'json' | 'yaml' | 'toml';
+};
+
+// Registry mapping type identifiers (as used in schema `files` arrays) to their config.
+export const FILE_TYPES: Record<string, FileTypeConfig> = {
+  md: {
+    extensions: ['.md', '.markdown'],
+    hasBody: true,
+    category: 'frontmatter',
+  },
+  mdx: {
+    extensions: ['.mdx'],
+    hasBody: true,
+    category: 'frontmatter',
+  },
+  markdoc: {
+    extensions: ['.mdoc', '.markdoc'],
+    hasBody: true,
+    category: 'frontmatter',
+  },
+  json: {
+    extensions: ['.json'],
+    hasBody: false,
+    category: 'data',
+    dataFormat: 'json',
+  },
+  yaml: {
+    extensions: ['.yml', '.yaml'],
+    hasBody: false,
+    category: 'data',
+    dataFormat: 'yaml',
+  },
+  toml: {
+    extensions: ['.toml'],
+    hasBody: false,
+    category: 'data',
+    dataFormat: 'toml',
+  },
+};
+
+/*
+//////////////////////////////
+// Extension reverse-lookup map
+// Built once at module load for O(1) extension-to-config lookups.
+//////////////////////////////
+*/
+
+// Maps each known extension to its FileTypeConfig.
+const extensionMap = new Map<string, FileTypeConfig>();
+
+// Maps each known extension to its type identifier (e.g. '.md' -> 'md').
+const extensionToTypeID = new Map<string, string>();
+
+for (const [typeId, config] of Object.entries(FILE_TYPES)) {
+  for (const ext of config.extensions) {
+    extensionMap.set(ext, config);
+    extensionToTypeID.set(ext, typeId);
+  }
+}
+
+/*
+//////////////////////////////
+// Helper: extract extension
+//////////////////////////////
+*/
+
+/**
+ * Extracts the last dot-prefixed extension from a filename, or an empty string if none.
+ * @param {string} filename - The filename to extract the extension from
+ * @return {string} The extension including the leading dot (e.g. '.md'), or ''
+ */
+function getExtension(filename: string): string {
+  const idx = filename.lastIndexOf('.');
+  if (idx === -1) return '';
+  return filename.slice(idx);
+}
+
+/*
+//////////////////////////////
+// Exported helpers
+//////////////////////////////
+*/
+
+/**
+ * Resolves a schema's `files` array of type identifiers to a flat list of file extensions.
+ * Used by storage adapters for file discovery filtering.
+ * @param {Record<string, unknown>} schema - A collection JSON Schema with an optional `files` array
+ * @return {string[]} Ordered list of extensions (e.g. ['.md', '.markdown', '.json'])
+ */
+export function getExtensionsForSchema(
+  schema: Record<string, unknown>,
+): string[] {
+  const files = schema['files'];
+  if (!Array.isArray(files)) return [];
+
+  const extensions: string[] = [];
+  for (const typeId of files as string[]) {
+    const config = FILE_TYPES[typeId];
+    if (config) {
+      extensions.push(...config.extensions);
+    }
+  }
+  return extensions;
+}
+
+/**
+ * Returns whether a file should show the body editor panel.
+ * True for markdown, MDX, and Markdoc files; false for pure data files.
+ * @param {string} filename - The filename to check
+ * @return {boolean} True if the file type has a body editor
+ */
+export function hasBodyEditor(filename: string): boolean {
+  const config = extensionMap.get(getExtension(filename));
+  return config?.hasBody ?? false;
+}
+
+/**
+ * Returns the category of a file based on its extension.
+ * Used to determine whether to render frontmatter fields or data-only fields.
+ * @param {string} filename - The filename to categorise
+ * @return {'frontmatter' | 'data' | null} The file category, or null for unrecognised extensions
+ */
+export function getFileCategory(
+  filename: string,
+): 'frontmatter' | 'data' | null {
+  const config = extensionMap.get(getExtension(filename));
+  return config?.category ?? null;
+}
+
+/**
+ * Returns the serialization format for a data file.
+ * Returns null for frontmatter files and unrecognised extensions.
+ * @param {string} filename - The filename to inspect
+ * @return {'json' | 'yaml' | 'toml' | null} The data format, or null if not a data file
+ */
+export function getDataFormat(
+  filename: string,
+): 'json' | 'yaml' | 'toml' | null {
+  const config = extensionMap.get(getExtension(filename));
+  return config?.dataFormat ?? null;
+}
+
+/**
+ * Strips the file extension from a filename when the extension is a known type.
+ * Returns the filename unchanged if the extension is not recognised.
+ * Used for generating URL slugs from filenames.
+ * @param {string} filename - The filename to strip the extension from
+ * @return {string} The filename without its known extension, or the original filename
+ */
+export function stripExtension(filename: string): string {
+  const ext = getExtension(filename);
+  if (ext && extensionMap.has(ext)) {
+    return filename.slice(0, filename.length - ext.length);
+  }
+  return filename;
+}
+
+/**
+ * Returns the default (first) file extension for a given type identifier.
+ * Used when creating new files to pick the canonical extension for a format.
+ * @param {string} type - A type identifier (e.g. 'md', 'yaml', 'toml')
+ * @return {string | null} The default extension including the leading dot, or null for unknown types
+ */
+export function getDefaultExtension(type: string): string | null {
+  return FILE_TYPES[type]?.extensions[0] ?? null;
+}
+
+/**
+ * Returns the type identifier for a given filename by looking up its extension.
+ * Used when the active file's type must be determined for the format selector.
+ * @param {string} filename - The filename to look up
+ * @return {string | null} The type identifier (e.g. 'md', 'yaml'), or null for unrecognised extensions
+ */
+export function getTypeForFilename(filename: string): string | null {
+  return extensionToTypeID.get(getExtension(filename)) ?? null;
+}

package/src/client/js/utils/format.ts

@@ -0,0 +1,16 @@
+/*
+ * Display formatting utilities for property names and labels.
+ */
+
+/**
+ * Converts a property name string to Title Case for display in form labels.
+ * Splits on camelCase boundaries, hyphens, and underscores, then capitalizes each word.
+ * @param {string} str - The raw property name to convert (e.g., "firstName", "last-name", "zip_code")
+ * @return {string} The title-cased display string (e.g., "First Name", "Last Name", "Zip Code")
+ */
+export function toTitleCase(str: string): string {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1 $2')
+    .replace(/[-_]/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}

package/src/client/js/utils/frontmatter.ts

@@ -0,0 +1,38 @@
+// Result of splitting a file into frontmatter and body.
+export type SplitResult = {
+  rawFrontmatter: string;
+  body: string;
+};
+
+/**
+ * Splits a markdown/MDX file into raw YAML frontmatter and body content.
+ * Handles BOM stripping, CRLF normalization, and horizontal rule rejection.
+ * @param {string} content - Raw file content
+ * @return {SplitResult} The separated frontmatter and body strings
+ */
+export function splitFrontmatter(content: string): SplitResult {
+  let str = content.startsWith('\uFEFF') ? content.slice(1) : content;
+  str = str.replace(/\r\n/g, '\n');
+
+  // Reject horizontal rules (----) and content not starting with frontmatter delimiter
+  if (str.startsWith('----') || !str.startsWith('---\n')) {
+    return { rawFrontmatter: '', body: str };
+  }
+
+  const closeIndex = str.indexOf('\n---\n', 3);
+  if (closeIndex === -1) {
+    // Check for --- at end of file with no trailing newline
+    if (str.endsWith('\n---')) {
+      return {
+        rawFrontmatter: str.slice(4, str.length - 4),
+        body: '',
+      };
+    }
+    return { rawFrontmatter: '', body: str };
+  }
+
+  return {
+    rawFrontmatter: str.slice(4, closeIndex),
+    body: str.slice(closeIndex + 5),
+  };
+}

package/src/client/js/utils/schema-utils.ts

@@ -0,0 +1,295 @@
+/*
+ * Utilities for reading and resolving JSON Schema nodes.
+ * Provides type resolution, path traversal, tab extraction, and
+ * convenience accessors for common schema annotations.
+ */
+
+import { toTitleCase } from './format';
+
+// A generic JSON Schema node represented as a plain object.
+export type SchemaNode = Record<string, unknown>;
+
+/**
+ * Discriminated union describing the resolved type of a schema field. All variants carry an optional `nullable` flag set when the field was expressed as `anyOf: [<type>, { type: 'null' }]`.
+ */
+export type FieldType =
+  | { kind: 'string'; nullable?: boolean }
+  | { kind: 'number'; nullable?: boolean }
+  | { kind: 'boolean'; nullable?: boolean }
+  | { kind: 'date'; nullable?: boolean }
+  | { kind: 'enum'; options: string[]; nullable?: boolean }
+  | { kind: 'array'; nullable?: boolean }
+  | { kind: 'object'; nullable?: boolean }
+  | { kind: 'unknown'; nullable?: boolean };
+
+/**
+ * A path segment used to address nested values. Strings address object keys; numbers address array indices.
+ */
+export type PathSegment = string | number;
+
+/*
+//////////////////////////////
+// resolveFieldType
+//////////////////////////////
+*/
+
+/**
+ * Resolves a JSON Schema node to a `FieldType` discriminated union.
+ * Handles anyOf nullable unwrapping, enum detection, and date-time format.
+ * @param {SchemaNode} schema - The JSON Schema node to resolve
+ * @return {FieldType} The resolved field type descriptor
+ */
+export function resolveFieldType(schema: SchemaNode): FieldType {
+  // Unwrap nullable anyOf: [<innerType>, { type: 'null' }]
+  const anyOf = schema['anyOf'];
+  if (Array.isArray(anyOf)) {
+    const nonNull = (anyOf as SchemaNode[]).find((s) => s['type'] !== 'null');
+    if (nonNull) {
+      const inner = resolveFieldType(nonNull);
+      return { ...inner, nullable: true } as FieldType;
+    }
+  }
+
+  const type = schema['type'] as string | undefined;
+  const format = schema['format'] as string | undefined;
+  const enumValues = schema['enum'];
+
+  // date-time format takes precedence over plain string
+  if (type === 'string' && format === 'date-time') {
+    return { kind: 'date' };
+  }
+
+  // enum values present — treat as enum regardless of string subtype
+  if (type === 'string' && Array.isArray(enumValues)) {
+    return { kind: 'enum', options: enumValues as string[] };
+  }
+
+  if (type === 'string') return { kind: 'string' };
+  if (type === 'number' || type === 'integer') return { kind: 'number' };
+  if (type === 'boolean') return { kind: 'boolean' };
+  if (type === 'array') return { kind: 'array' };
+  if (type === 'object') return { kind: 'object' };
+
+  return { kind: 'unknown' };
+}
+
+/*
+//////////////////////////////
+// extractTabs
+//////////////////////////////
+*/
+
+/**
+ * Scans an object schema's properties for `tab` arrays and returns a sorted, deduplicated list of all tab names found.
+ * @param {SchemaNode} schema - A JSON Schema node with an optional `properties` map
+ * @return {string[]} Sorted, deduplicated list of tab names
+ */
+export function extractTabs(schema: SchemaNode): string[] {
+  const properties = getProperties(schema);
+  if (!properties) return [];
+
+  const tabs = new Set<string>();
+
+  for (const field of Object.values(properties)) {
+    const tab = field['tab'];
+    if (Array.isArray(tab)) {
+      for (const name of tab as string[]) {
+        tabs.add(name);
+      }
+    }
+  }
+
+  return Array.from(tabs).sort();
+}
+
+/*
+//////////////////////////////
+// createDefaultValue
+//////////////////////////////
+*/
+
+/**
+ * Returns a type-appropriate default value for a given JSON Schema node.
+ * Honors `schema.default` when present, returns null for nullable types, and recurses into object properties.
+ * @param {SchemaNode} schema - The JSON Schema node to generate a default value for
+ * @return {unknown} A default value appropriate for the schema type
+ */
+export function createDefaultValue(schema: SchemaNode): unknown {
+  // Honour an explicit schema default first
+  if ('default' in schema) {
+    return schema['default'];
+  }
+
+  // Nullable anyOf — default to null
+  const anyOf = schema['anyOf'];
+  if (Array.isArray(anyOf)) {
+    const hasNull = (anyOf as SchemaNode[]).some((s) => s['type'] === 'null');
+    if (hasNull) return null;
+  }
+
+  const type = schema['type'] as string | undefined;
+
+  if (type === 'string') return '';
+  if (type === 'number' || type === 'integer') return 0;
+  if (type === 'boolean') return false;
+  if (type === 'array') return [];
+
+  if (type === 'object') {
+    const properties = getProperties(schema);
+    if (!properties) return {};
+    const result: Record<string, unknown> = {};
+    for (const [key, fieldSchema] of Object.entries(properties)) {
+      result[key] = createDefaultValue(fieldSchema);
+    }
+    return result;
+  }
+
+  return null;
+}
+
+/*
+//////////////////////////////
+// getByPath
+//////////////////////////////
+*/
+
+/**
+ * Reads a deeply nested value from an object by following path segments.
+ * Returns `undefined` if any segment along the path is missing.
+ * @param {unknown} obj - The root object to traverse
+ * @param {PathSegment[]} path - Ordered path segments (string keys or numeric indices)
+ * @return {unknown} The value at the resolved path, or undefined if any segment is missing
+ */
+export function getByPath(obj: unknown, path: PathSegment[]): unknown {
+  let current: unknown = obj;
+  for (const segment of path) {
+    if (current === null || current === undefined) return undefined;
+    current = (current as Record<string | number, unknown>)[segment];
+  }
+  return current;
+}
+
+/*
+//////////////////////////////
+// setByPath
+//////////////////////////////
+*/
+
+/**
+ * Sets a deeply nested value in an object by following path segments, creating intermediate objects as needed.
+ * @param {unknown} obj - The root object to mutate
+ * @param {PathSegment[]} path - Ordered path segments (string keys or numeric indices)
+ * @param {unknown} value - The value to assign at the resolved path
+ * @return {void}
+ */
+export function setByPath(
+  obj: unknown,
+  path: PathSegment[],
+  value: unknown,
+): void {
+  if (path.length === 0) return;
+
+  let current = obj as Record<string | number, unknown>;
+
+  // Walk down to the parent of the final segment, creating objects as needed
+  for (let i = 0; i < path.length - 1; i++) {
+    const segment = path[i];
+    if (current[segment] === null || current[segment] === undefined) {
+      current[segment] = {};
+    }
+    current = current[segment] as Record<string | number, unknown>;
+  }
+
+  current[path[path.length - 1]] = value;
+}
+
+/*
+//////////////////////////////
+// getFieldsForTab
+//////////////////////////////
+*/
+
+/**
+ * Returns property names from a schema that belong to the given tab.
+ * When `tab` is `null`, all property names are returned (no filtering — every field appears in the catch-all Metadata view).
+ * @param {SchemaNode} schema - A JSON Schema node with an optional `properties` map
+ * @param {string | null} tab - Tab name to filter by, or `null` to return all fields
+ * @return {string[]} Array of property names belonging to the specified tab
+ */
+export function getFieldsForTab(
+  schema: SchemaNode,
+  tab: string | null,
+): string[] {
+  const properties = getProperties(schema);
+  if (!properties) return [];
+
+  // Filter out $schema — it's a JSON Schema meta-property that Astro adds
+  // to every generated schema, not a user-editable frontmatter field
+  const keys = Object.keys(properties).filter((k) => k !== '$schema');
+
+  // null means "all fields" — no tab filtering applied
+  if (tab === null) {
+    return keys;
+  }
+
+  return keys.filter((key) => {
+    const fieldTab = properties[key]['tab'];
+    return Array.isArray(fieldTab) && (fieldTab as string[]).includes(tab);
+  });
+}
+
+/*
+//////////////////////////////
+// Schema property accessors
+//////////////////////////////
+*/
+
+/**
+ * Extracts the `properties` map from a schema node, with a safe cast.
+ * @param {SchemaNode} schema - A JSON Schema node
+ * @return {Record<string, SchemaNode> | undefined} The properties map, or undefined if absent
+ */
+export function getProperties(
+  schema: SchemaNode,
+): Record<string, SchemaNode> | undefined {
+  return schema['properties'] as Record<string, SchemaNode> | undefined;
+}
+
+/**
+ * Extracts the `required` array from a schema node, returning an empty array if absent.
+ * @param {SchemaNode} schema - A JSON Schema node
+ * @return {string[]} Array of required property names
+ */
+export function getRequiredFields(schema: SchemaNode): string[] {
+  return Array.isArray(schema['required'])
+    ? (schema['required'] as string[])
+    : [];
+}
+
+/**
+ * Returns whether a schema node is marked as read-only.
+ * @param {SchemaNode} schema - A JSON Schema node
+ * @return {boolean} True if the schema has readOnly set to true
+ */
+export function isReadOnly(schema: SchemaNode): boolean {
+  return !!(schema['readOnly'] as boolean | undefined);
+}
+
+/**
+ * Returns whether a schema node was unwrapped from a nullable anyOf and flagged as nullable by SchemaField.
+ * @param {SchemaNode} schema - A JSON Schema node (possibly annotated with _nullable)
+ * @return {boolean} True if the schema has the _nullable annotation
+ */
+export function isNullable(schema: SchemaNode): boolean {
+  return !!(schema['_nullable'] as boolean | undefined);
+}
+
+/**
+ * Returns the display label for a schema field — the schema title if present, otherwise the property name converted to title case.
+ * @param {SchemaNode} schema - A JSON Schema node
+ * @param {string} name - The raw property name used as a fallback
+ * @return {string} The human-readable label
+ */
+export function getLabel(schema: SchemaNode, name: string): string {
+  return (schema['title'] as string | undefined) ?? toTitleCase(name);
+}

package/src/client/js/utils/slug.ts

@@ -0,0 +1,18 @@
+/*
+ * URL-friendly slug generation without external dependencies.
+ * Replicates the behavior of the `slugify` package with `lower: true, strict: true`.
+ */
+
+/**
+ * Converts a string to a URL-friendly slug.
+ * Lowercases, replaces non-alphanumeric characters with hyphens, collapses consecutive hyphens, and trims edge hyphens.
+ * @param {string} input - The string to slugify
+ * @return {string} A URL-safe slug
+ */
+export function slugify(input: string): string {
+  return input
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^-|-$/g, '');
+}