@platformos/platformos-common 0.0.12 → 0.0.16

package/src/frontmatter.ts

@@ -0,0 +1,533 @@
+/**
+ * Frontmatter schema definitions for platformOS Liquid file types.
+ *
+ * Each Liquid file type in platformOS has a YAML frontmatter section at the
+ * top of the file that configures server-side behaviour. The schema for each
+ * type is different — Pages have slug/layout, Emails have to/from/subject, etc.
+ *
+ * This module provides:
+ *   - FrontmatterFieldSchema  — type definition for a single field
+ *   - FrontmatterSchema       — type definition for a complete schema
+ *   - FRONTMATTER_SCHEMAS     — per-type schemas keyed by PlatformOSFileType
+ *   - getFrontmatterSchema()  — convenience lookup that returns undefined for
+ *                               types without a frontmatter schema
+ */
+
+import { FILE_TYPE_DIRS, PlatformOSFileType } from './path-utils';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type FrontmatterFieldType = 'string' | 'boolean' | 'integer' | 'number' | 'array' | 'object';
+
+export interface FrontmatterFieldSchema {
+  /** The expected YAML type(s) for this field's value. */
+  type: FrontmatterFieldType | FrontmatterFieldType[];
+  /** Whether this field must be present. */
+  required?: boolean;
+  /** Human-readable description of this field. */
+  description?: string;
+  /** Whether this field name is deprecated in favour of a newer one. */
+  deprecated?: boolean;
+  /** Message shown when this deprecated field is used. */
+  deprecatedMessage?: string;
+  /**
+   * Allowed values for this field. When set, a validator should warn if the
+   * field value is not one of these entries.
+   */
+  enumValues?: (string | number)[];
+}
+
+export interface FrontmatterSchema {
+  /** Human-readable name of the file type, used in diagnostics. */
+  name: string;
+  /**
+   * Known frontmatter fields.
+   * Checks can use this to surface unknown keys or missing required keys.
+   * Any key not listed here will produce an "unknown field" warning.
+   */
+  fields: Record<string, FrontmatterFieldSchema>;
+}
+
+// ─── Schemas ──────────────────────────────────────────────────────────────────
+
+/**
+ * Per-type frontmatter schemas.
+ *
+ * Only Liquid file types are present here — GraphQL, YAML, and Asset types
+ * do not use frontmatter.
+ *
+ * Field lists are derived from the server-side converter files in
+ * app/services/app_builder/converters/. Enum constraints mirror server validations.
+ * Unknown keys always produce a warning; file types with arbitrary frontmatter
+ * (e.g. Migration) are omitted so no validation runs for them.
+ */
+export const FRONTMATTER_SCHEMAS: Partial<Record<PlatformOSFileType, FrontmatterSchema>> = {
+  // ── Page ─────────────────────────────────────────────────────────────────────
+  [PlatformOSFileType.Page]: {
+    name: 'Page',
+    fields: {
+      slug: {
+        type: 'string',
+        description: 'URL slug for this page. Supports dynamic segments (e.g. users/:id).',
+      },
+      layout: {
+        type: 'string',
+        description: 'Layout template to wrap this page (path relative to app root, no extension).',
+      },
+      layout_name: {
+        type: 'string',
+        description: 'Alias for layout.',
+        deprecated: true,
+        deprecatedMessage: 'Use `layout` instead of `layout_name`.',
+      },
+      method: {
+        type: 'string',
+        description: 'HTTP method this page responds to.',
+        enumValues: ['delete', 'get', 'patch', 'post', 'put', 'options'],
+      },
+      redirect_to: {
+        type: 'string',
+        description: 'URL to redirect to.',
+      },
+      redirect_url: {
+        type: 'string',
+        description: 'Alias for redirect_to.',
+        deprecated: true,
+        deprecatedMessage: 'Use `redirect_to` instead of `redirect_url`.',
+      },
+      redirect_code: {
+        type: 'integer',
+        description: 'HTTP redirect status code.',
+        enumValues: [301, 302, 307],
+      },
+      authorization_policies: {
+        type: 'array',
+        description: 'List of authorization policy names that must pass before rendering.',
+      },
+      response_headers: {
+        type: 'string',
+        description: 'Liquid template that renders a JSON object of HTTP response headers.',
+      },
+      metadata: {
+        type: 'object',
+        description: 'Arbitrary metadata object (e.g. SEO title/description, robots directives).',
+      },
+      max_deep_level: {
+        type: 'integer',
+        description: 'Maximum number of dynamic URL segments to capture.',
+      },
+      searchable: {
+        type: 'boolean',
+        description: 'Whether this page is included in platformOS search indexes.',
+      },
+      format: {
+        type: 'string',
+        description: 'Response format (html, json, xml, csv, …). Often encoded in the filename.',
+      },
+      default_layout: {
+        type: 'boolean',
+        description: 'Use the instance default layout.',
+      },
+      handler: {
+        type: 'string',
+        description: 'Template handler type.',
+      },
+      converter: {
+        type: 'string',
+        description: 'Content converter, e.g. `markdown`.',
+      },
+      dynamic_cache: {
+        type: 'object',
+        description: 'Dynamic cache settings: { key, layout, expire }.',
+      },
+      static_cache: {
+        type: 'object',
+        description: 'Static cache settings: { expire }.',
+      },
+      cache_for: {
+        type: 'integer',
+        description: 'Static cache expiration in seconds.',
+      },
+      subdomain: {
+        type: 'string',
+        description: 'Subdomain routing.',
+      },
+      require_verified_user: {
+        type: 'boolean',
+      },
+      admin_page: {
+        type: 'boolean',
+      },
+      enable_profiler: {
+        type: 'boolean',
+      },
+      metadata_title: {
+        type: 'string',
+        description: 'SEO <title> shorthand (alias for metadata.title).',
+      },
+      metadata_meta_description: {
+        type: 'string',
+        description: 'SEO meta description shorthand (alias for metadata.meta_description).',
+      },
+      metadata_canonical_url: {
+        type: 'string',
+        description: 'Canonical URL shorthand (alias for metadata.canonical_url).',
+      },
+    },
+  },
+
+  // ── Layout ───────────────────────────────────────────────────────────────────
+  // liquid_view_converter.rb: primary_key derived from physical_file_path; no `name` property.
+  [PlatformOSFileType.Layout]: {
+    name: 'Layout',
+    fields: {
+      converter: {
+        type: 'string',
+        description: 'Content converter, e.g. `markdown`.',
+      },
+      metadata: {
+        type: 'object',
+      },
+    },
+  },
+
+  // ── Partial ──────────────────────────────────────────────────────────────────
+  [PlatformOSFileType.Partial]: {
+    name: 'Partial',
+    fields: {
+      metadata: {
+        type: 'object',
+        description:
+          'Partial metadata. `metadata.params` declares accepted parameters; `metadata.name` is a human-readable label for the style guide.',
+      },
+      converter: {
+        type: 'string',
+        description: 'Content converter, e.g. `markdown`.',
+      },
+    },
+  },
+
+  // ── AuthorizationPolicy ──────────────────────────────────────────────────────
+  // authorization_policy_converter.rb: name, content, flash_alert, redirect_to, http_status, metadata.
+  // Note: only flash_alert is supported — flash_notice is NOT a valid property here.
+  [PlatformOSFileType.Authorization]: {
+    name: 'AuthorizationPolicy',
+    fields: {
+      name: {
+        type: 'string',
+        description: 'Unique identifier for this authorization policy.',
+      },
+      redirect_to: {
+        type: 'string',
+        description: 'URL to redirect the user to when the policy fails.',
+      },
+      flash_alert: {
+        type: 'string',
+        description: 'Flash alert message shown after a failed authorization redirect.',
+      },
+      http_status: {
+        type: 'integer',
+        description: 'HTTP status code returned on policy failure.',
+        enumValues: [403, 404],
+      },
+      metadata: {
+        type: 'object',
+      },
+    },
+  },
+
+  // ── Email ────────────────────────────────────────────────────────────────────
+  [PlatformOSFileType.Email]: {
+    name: 'Email',
+    fields: {
+      name: {
+        type: 'string',
+        description: 'Unique identifier for this email notification.',
+      },
+      to: {
+        type: 'string',
+        description: 'Recipient email address (may use Liquid).',
+      },
+      from: {
+        type: 'string',
+        description: 'Sender email address.',
+      },
+      reply_to: {
+        type: 'string',
+        description: 'Reply-to email address.',
+      },
+      cc: {
+        type: 'string',
+        description: 'Carbon-copy recipients.',
+      },
+      bcc: {
+        type: 'string',
+        description: 'Blind carbon-copy recipients.',
+      },
+      subject: {
+        type: 'string',
+        description: 'Email subject line (may use Liquid).',
+      },
+      layout: {
+        type: 'string',
+        description: 'Layout partial to wrap the email body.',
+      },
+      layout_path: {
+        type: 'string',
+        description: 'Alias for layout.',
+        deprecated: true,
+        deprecatedMessage: 'Use `layout` instead of `layout_path`.',
+      },
+      delay: {
+        type: 'integer',
+        description: 'Seconds to delay delivery after being triggered.',
+      },
+      enabled: {
+        type: 'boolean',
+        description: 'When false, this email is never sent. Defaults to true.',
+      },
+      trigger_condition: {
+        type: ['boolean', 'string'],
+        description:
+          'Liquid expression or boolean; email is only sent when this evaluates to true.',
+      },
+      locale: {
+        type: 'string',
+        description: 'Locale for the email.',
+      },
+      forced: {
+        type: 'boolean',
+      },
+      attachments: {
+        type: 'string',
+      },
+      unique_args: {
+        type: 'object',
+        description: 'Extra key/value pairs passed to the email delivery provider.',
+      },
+      metadata: {
+        type: 'object',
+      },
+    },
+  },
+
+  // ── ApiCall ──────────────────────────────────────────────────────────────────
+  [PlatformOSFileType.ApiCall]: {
+    name: 'ApiCall',
+    fields: {
+      name: {
+        type: 'string',
+        description: 'Unique identifier for this API call notification.',
+      },
+      to: {
+        type: 'string',
+        description: 'Target URL for the HTTP request (may use Liquid).',
+      },
+      request_type: {
+        type: 'string',
+        description: 'HTTP method: GET, POST, PUT, PATCH, or DELETE.',
+        enumValues: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+      },
+      request_headers: {
+        type: 'string',
+        description: 'Liquid template rendering a JSON object of request headers.',
+      },
+      headers: {
+        type: 'string',
+        description: 'Alias for request_headers.',
+        deprecated: true,
+        deprecatedMessage: 'Use `request_headers` instead of `headers`.',
+      },
+      callback: {
+        type: 'string',
+        description: 'Liquid template executed after the HTTP response is received.',
+      },
+      delay: {
+        type: 'integer',
+        description: 'Seconds to delay the request after being triggered.',
+      },
+      enabled: {
+        type: 'boolean',
+        description: 'When false, this API call is never executed. Defaults to true.',
+      },
+      trigger_condition: {
+        type: ['boolean', 'string'],
+        description: 'Liquid expression or boolean; call is only made when this evaluates to true.',
+      },
+      format: {
+        type: 'string',
+        description: 'Request body encoding format (http, json, …).',
+      },
+      locale: {
+        type: 'string',
+      },
+      metadata: {
+        type: 'object',
+      },
+    },
+  },
+
+  // ── Sms ──────────────────────────────────────────────────────────────────────
+  [PlatformOSFileType.Sms]: {
+    name: 'SMS',
+    fields: {
+      name: {
+        type: 'string',
+        description: 'Unique identifier for this SMS notification.',
+      },
+      to: {
+        type: 'string',
+        description: 'Recipient phone number in E.164 format (may use Liquid).',
+      },
+      content: {
+        type: 'string',
+        description: 'SMS body (may use Liquid).',
+      },
+      delay: {
+        type: 'integer',
+        description: 'Seconds to delay sending after being triggered.',
+      },
+      enabled: {
+        type: 'boolean',
+        description: 'When false, this SMS is never sent. Defaults to true.',
+      },
+      trigger_condition: {
+        type: ['boolean', 'string'],
+        description: 'Liquid expression or boolean; SMS is only sent when this evaluates to true.',
+      },
+      locale: {
+        type: 'string',
+      },
+      metadata: {
+        type: 'object',
+      },
+    },
+  },
+
+  // ── FormConfiguration ────────────────────────────────────────────────────────
+  [PlatformOSFileType.FormConfiguration]: {
+    name: 'FormConfiguration',
+    fields: {
+      name: {
+        type: 'string',
+        description: 'Unique identifier for this form, used in include_form / function calls.',
+      },
+      resource: {
+        type: ['string', 'object'],
+        description: 'Model or resource type this form operates on.',
+      },
+      resource_owner: {
+        type: 'string',
+        description: 'Who owns the resource being created/updated.',
+      },
+      fields: {
+        type: 'object',
+        description: 'Field definitions — what data this form accepts and validates.',
+      },
+      configuration: {
+        type: 'object',
+        description: 'Alias for fields.',
+      },
+      redirect_to: {
+        type: 'string',
+        description: 'URL to redirect to after a successful form submission.',
+      },
+      return_to: {
+        type: 'string',
+        description: 'Alias for redirect_to.',
+        deprecated: true,
+        deprecatedMessage: 'Use `redirect_to` instead of `return_to`.',
+      },
+      flash_notice: {
+        type: 'string',
+        description: 'Flash notice message shown after a successful submission.',
+      },
+      flash_alert: {
+        type: 'string',
+        description: 'Flash alert message shown after a failed submission.',
+      },
+      spam_protection: {
+        type: 'string',
+        description: 'Spam protection mechanism to use.',
+        enumValues: ['recaptcha', 'recaptcha_v2', 'recaptcha_v3', 'hcaptcha'],
+      },
+      request_allowed: {
+        type: 'boolean',
+        description: 'Whether the request is allowed. Default: true.',
+      },
+      live_reindex: {
+        type: 'boolean',
+      },
+      default_payload: {
+        type: ['string', 'object'],
+      },
+      callback_actions: {
+        type: 'string',
+        description: 'Liquid template with GraphQL mutations to run after submission.',
+      },
+      async_callback_actions: {
+        type: 'object',
+        description: 'Async callback settings: { content, delay, max_attempts, priority }.',
+      },
+      email_notifications: {
+        type: 'array',
+        description: 'Email notification names to trigger after successful form submission.',
+      },
+      sms_notifications: {
+        type: 'array',
+        description: 'SMS notification names to trigger after successful form submission.',
+      },
+      api_call_notifications: {
+        type: 'array',
+        description: 'API call notification names to trigger after successful form submission.',
+      },
+      response_headers: {
+        type: ['string', 'object'],
+      },
+      metadata: {
+        type: 'object',
+      },
+    },
+  },
+};
+
+// ─── Lookup helper ────────────────────────────────────────────────────────────
+
+/**
+ * Returns the frontmatter schema for a given file type, or undefined if no
+ * schema is defined for that type (e.g. GraphQL, YAML, Asset types).
+ */
+export function getFrontmatterSchema(
+  fileType: PlatformOSFileType | undefined,
+): FrontmatterSchema | undefined {
+  if (fileType === undefined) return undefined;
+  return FRONTMATTER_SCHEMAS[fileType];
+}
+
+// ─── Frontmatter association directories ──────────────────────────────────────
+
+/**
+ * Maps frontmatter list-field names to their canonical app-relative directory.
+ *
+ * Derived from FILE_TYPE_DIRS[type][0] so it always stays in sync with the
+ * single source of truth in path-utils.ts.
+ *
+ * Used by both the ValidFrontmatter check (file-existence validation) and the
+ * FrontmatterDefinitionProvider (go-to-definition) to resolve association paths.
+ */
+export const FRONTMATTER_ASSOCIATION_DIRS: Readonly<Record<string, string>> = {
+  authorization_policies: FILE_TYPE_DIRS[PlatformOSFileType.Authorization][0],
+  email_notifications: FILE_TYPE_DIRS[PlatformOSFileType.Email][0],
+  sms_notifications: FILE_TYPE_DIRS[PlatformOSFileType.Sms][0],
+  api_call_notifications: FILE_TYPE_DIRS[PlatformOSFileType.ApiCall][0],
+};
+
+// ─── Liquid expression detection ──────────────────────────────────────────────
+
+/**
+ * Returns true if the value contains a Liquid output tag (`{{`) or tag (`{%`).
+ * Used to skip static validation of dynamic frontmatter values.
+ */
+export function containsLiquid(value: string): boolean {
+  return value.includes('{{') || value.includes('{%');
+}

package/src/index.ts

@@ -3,3 +3,4 @@ export * from './translation-provider/TranslationProvider';
 export * from './route-table';
 export * from './AbstractFileSystem';
 export * from './path-utils';
+export * from './frontmatter';

package/src/path-utils.ts

@@ -220,6 +220,19 @@ export function isKnownLiquidFile(uri: UriString): boolean {
   return type !== undefined && LIQUID_FILE_TYPES.has(type);
 }
 
+/**
+ * Returns true if the URI has a `.liquid` extension but does not match any
+ * recognized platformOS directory. Useful for detecting misplaced files that
+ * the server will silently ignore.
+ *
+ * @example
+ * isUnclassifiedLiquidFile('file:///project/scripts/helper.liquid') // → true
+ * isUnclassifiedLiquidFile('file:///project/app/views/pages/home.liquid') // → false (Page)
+ */
+export function isUnclassifiedLiquidFile(uri: UriString): boolean {
+  return uri.endsWith('.liquid') && getFileType(uri) === undefined;
+}
+
 /**
  * Returns true if the URI belongs to a recognized platformOS GraphQL directory
  * and should be linted. Files outside known directories (e.g. generator
@@ -264,3 +277,45 @@ export function isMigration(uri: UriString): boolean {
 export function isFormConfiguration(uri: UriString): boolean {
   return getFileType(uri) === PlatformOSFileType.FormConfiguration;
 }
+
+// ─── Module prefix utilities ──────────────────────────────────────────────────
+
+/**
+ * Result of parsing a `modules/{name}/...` prefix from a path or key.
+ * Used by DocumentsLocator and TranslationProvider to route lookups to the
+ * correct module directory.
+ */
+export type ModulePrefix =
+  | { isModule: false; key: string }
+  | { isModule: true; moduleName: string; key: string };
+
+/**
+ * Parse a `modules/{name}/{rest}` prefix from a path or translation key.
+ * Returns the module name and the remaining key, or marks it as non-module.
+ *
+ * @example
+ * parseModulePrefix('modules/community/components/card') // → { isModule: true, moduleName: 'community', key: 'components/card' }
+ * parseModulePrefix('modules/community/hello.world')     // → { isModule: true, moduleName: 'community', key: 'hello.world' }
+ * parseModulePrefix('app/views/partials/card')           // → { isModule: false, key: 'app/views/partials/card' }
+ * parseModulePrefix('modules/community')                 // → { isModule: false, key: 'modules/community' } (no key segment)
+ */
+export function parseModulePrefix(path: string): ModulePrefix {
+  if (!path.startsWith('modules/')) {
+    return { isModule: false, key: path };
+  }
+
+  const withoutPrefix = path.slice('modules/'.length);
+  const slashIdx = withoutPrefix.indexOf('/');
+
+  if (slashIdx === -1) {
+    // Just "modules/name" with no key segment
+    return { isModule: false, key: path };
+  }
+
+  const moduleName = withoutPrefix.slice(0, slashIdx);
+  const key = withoutPrefix.slice(slashIdx + 1);
+
+  // moduleName must be non-empty to be a valid module prefix.
+  // key may be empty (e.g. 'modules/users/') — that means "all files in the module".
+  return moduleName ? { isModule: true, moduleName, key } : { isModule: false, key: path };
+}

package/src/route-table/RouteTable.ts

@@ -16,7 +16,9 @@ function extractFrontmatter(source: string): PageFrontmatter | null {
   const trimmed = source.trimStart();
   if (!trimmed.startsWith('---')) return null;
 
-  const end = trimmed.indexOf('---', 3);
+  // Search for the closing delimiter as `\n---` so we don't accidentally match
+  // a `---` sequence that appears inside a YAML value (e.g. `slug: my---slug`).
+  const end = trimmed.indexOf('\n---', 3);
   if (end === -1) return null;
 
   const yamlBlock = trimmed.slice(3, end).trim();
@@ -48,7 +50,7 @@ function extractFrontmatter(source: string): PageFrontmatter | null {
  *   file:///project/app/views/pages/about.html.liquid -> about.html.liquid
  *   file:///project/modules/admin/public/views/pages/dashboard.html.liquid -> dashboard.html.liquid
  */
-function extractRelativePagePath(uri: string): string | null {
+export function extractRelativePagePath(uri: string): string | null {
   const patterns = [
     // App-level pages: app/views/pages/ or marketplace_builder/pages/
     /\/(app|marketplace_builder)\/(views\/pages|pages)\//,
@@ -187,6 +189,21 @@ export class RouteTable {
     return this._built;
   }
 
+  /**
+   * Populate the route table from an in-memory collection of URI → content
+   * pairs, bypassing the filesystem entirely. Useful for warming the table
+   * from a DocumentManager without a full disk scan on startup.
+   *
+   * Only page URIs are registered; non-page URIs are silently skipped.
+   */
+  buildFromEntries(entries: Iterable<[uri: string, content: string]>): void {
+    this.routes.clear();
+    for (const [uri, content] of entries) {
+      this.addPageFromContent(uri, content);
+    }
+    this._built = true;
+  }
+
   async build(rootUri: URI): Promise<void> {
     this.routes.clear();
 

package/src/route-table/index.ts

@@ -1,4 +1,4 @@
-export { RouteTable } from './RouteTable';
+export { RouteTable, extractRelativePagePath } from './RouteTable';
 export { slugFromFilePath, formatFromFilePath, KNOWN_FORMATS } from './slugFromFilePath';
 export { parseSlug, calculatePrecedence } from './parseSlug';
 export type { RouteEntry, RouteSegment } from './types';