@marsx-dev/launcher 0.0.3 → 0.0.6

package/src/cli/init.ts

@@ -0,0 +1,142 @@
+import chalk from 'chalk';
+import { spawnSync } from 'child_process';
+import { randomBytes } from 'crypto';
+import path from 'path';
+import { Config, CustomEnvironmentVariables } from '../configuration';
+import { isDirectory, writeFileMakeDir } from '../utils/fileUtils';
+import { assert } from '../utils/textUtils';
+import { CliError } from './index';
+
+const FASTIFY_DEPS = [
+  '@fastify/session',
+  'fastify',
+  'fastify-accepts',
+  'fastify-compress',
+  'fastify-cookie',
+  'fastify-cors',
+  'fastify-csrf',
+  'fastify-flash',
+  'fastify-formbody',
+  'fastify-helmet',
+  'fastify-multipart',
+  'fastify-request-context',
+  'fastify-static',
+  'fastify-websocket',
+];
+
+const COMMON_DEPS = [
+  '@marsx-dev/launcher',
+  'aws-sdk',
+  'axios',
+  'azure-storage',
+  'base-x',
+  'bcrypt',
+  'chokidar',
+  'lodash',
+  'mongodb4@npm:mongodb@4',
+  'mongodb3@npm:mongodb@3',
+  'typescript',
+  'uuid',
+  'xxhash',
+];
+
+const V3_DEPS = [
+  'babel-core',
+  'babel-plugin-transform-react-jsx',
+  'config',
+  'crypto-js',
+  'jsonwebtoken',
+  'mobile-detect',
+  'moment-timezone',
+  'route-pattern',
+  'route-sort',
+];
+
+const DEFAULT_DEPS = [...FASTIFY_DEPS, ...COMMON_DEPS, ...V3_DEPS];
+
+export async function initProject(projectName: string) {
+  if (!projectName.match(/^\w+$/) || projectName !== projectName.toLowerCase()) {
+    throw new CliError(
+      `Project name "${projectName}" may contain only lower case alphanumeric characters and underscores (eg. my_project_name)`,
+    );
+  }
+  const name = {
+    snakeCase: projectName,
+    withDashes: projectName.replace('_', '-'),
+    noSep: projectName.replace('_', ''),
+  };
+
+  const projectDir = path.resolve(projectName);
+
+  if (await isDirectory(projectDir)) {
+    throw new CliError(`Project dir "${projectName}" already exist. Delete it or choose a different name.`);
+  }
+
+  console.log(`Creating a new MarsX project in ${chalk.green(projectDir)}`);
+
+  const packageJson = {
+    name: name.withDashes,
+    version: '0.0.0',
+    private: true,
+    scripts: {
+      start: 'marsx start',
+    },
+    dependencies: {},
+  };
+  const packageJsonStr = JSON.stringify(packageJson, null, 2);
+  await writeFileMakeDir(path.join(projectDir, 'package.json'), packageJsonStr);
+
+  const config: Config = {
+    production: false,
+    port: 3000,
+    blocksDir: 'blocks',
+    cacheDir: '.cache',
+    mongoConn: '<CONN_STR>',
+    mongoDbName: name.withDashes,
+    azureStorageConnection: '<CONN_STR>',
+    azureStorageAccountName: name.noSep,
+    azureStorageUrl: `https://${name.noSep}.blob.core.windows.net`,
+    webFilesTable: 'webFiles',
+    webRecentFilesTable: 'webRecentFiles',
+    webFilesBlob: 'web-files',
+    secret: (await randomBytes(32)).toString('hex'),
+    importProjects: [
+      {
+        name: 'marsx-core',
+        url: 'https://core.marsx.dev',
+        api_key: '<API_KEY>',
+        git_commit_ish: 'main',
+      },
+    ],
+  };
+
+  await writeFileMakeDir(path.join(projectDir, 'config', 'default.json'), JSON.stringify(config, null, 2));
+  await writeFileMakeDir(
+    path.join(projectDir, 'config', 'custom-environment-variables.json'),
+    JSON.stringify(CustomEnvironmentVariables, null, 2),
+  );
+  await writeFileMakeDir(path.join(projectDir, '.gitignore'), 'node_modules\ndist\n.cache\n');
+
+  function run(...args: string[]) {
+    const cmd = args[0];
+    assert(cmd);
+    spawnSync(cmd, args.slice(1), { cwd: projectDir, stdio: 'inherit' });
+  }
+
+  console.log('\nInstalling dependencies. This might take a couple of minutes.');
+  run('npm', 'i', ...DEFAULT_DEPS);
+  console.log('');
+
+  run('git', 'init', '--initial-branch=main');
+  run('git', 'add', '.gitignore');
+  run('git', 'add', '-A');
+  run('git', 'commit', '-m', 'Initial MarsX commit');
+
+  console.log(`\n${chalk.green('Success!')} Created ${projectName} at ${projectDir}`);
+
+  console.log(`\nNext steps:`);
+  console.log(`  - Open new project directory: ${chalk.underline(`cd ${projectName}`)}`);
+  console.log(`  - Contact MarsX to get config params and update them: ${chalk.underline('code config/default.json')}`);
+  console.log(`  - (optionally) Migrate V3 blocks using: ${chalk.underline('npx marsx migrate')}`);
+  console.log(`  - Start local server: ${chalk.underline('npm run start')}`);
+}

package/src/cli/migrate.ts

@@ -0,0 +1,23 @@
+import chalk from 'chalk';
+import { MongoClient } from 'mongodb';
+import path from 'path';
+import { config } from '../configuration';
+import { serializeSfc } from '../utils/sfc';
+import { writeFileMakeDir } from '../utils/fileUtils';
+import { convertV3ToSfc, V3MongoBlock } from '../utils/v3';
+
+export async function migrateV3ToV4() {
+  console.log('Connecting to MongoDB...');
+  const mongoConn = await new MongoClient(config.mongoConn).connect();
+  const db = mongoConn.db(config.mongoDbName);
+  const allBlocks = await db.collection<V3MongoBlock>('blocks').find().toArray();
+  console.log(`Downloaded ${allBlocks.length} block(s)`);
+
+  for (const block of allBlocks) {
+    const serialized = serializeSfc(convertV3ToSfc(block));
+    await writeFileMakeDir(path.join(config.blocksDir, serialized.filePath), serialized.content);
+    console.log(`Saved ${serialized.filePath}`);
+  }
+
+  console.log(chalk.green('\nMigration complete successfully!'));
+}

package/src/cli/start.ts

@@ -0,0 +1,34 @@
+import child_process from 'child_process';
+import { config } from '../configuration';
+import { launchBooter } from '../launcher';
+import { assert } from '../utils/textUtils';
+
+export const RESTART_EXIT_CODe = 9;
+
+export const start = async () => {
+  if (config.production || process.env['MARSX_NO_SPAWN']) {
+    console.log(`MarsX process ${process.pid} starting...`);
+    await launchBooter();
+    console.log(`MarsX process ${process.pid} started`);
+  } else {
+    const spawnChildProc = () => {
+      assert(process.argv[0]);
+      const child = child_process.spawn(process.argv[0], ['--inspect', '--enable-source-maps', ...process.argv.slice(1)], {
+        cwd: process.cwd(),
+        env: { ...process.env, MARSX_NO_SPAWN: 'true' },
+        stdio: 'inherit',
+      });
+
+      child.on('close', (code: number) => {
+        console.log(`MarsX process ${child.pid} terminated with ${code}`);
+        if (code === RESTART_EXIT_CODe) {
+          setTimeout(spawnChildProc, 100);
+        } else {
+          process.exit(code);
+        }
+      });
+    };
+
+    spawnChildProc();
+  }
+};

package/src/configuration.ts

@@ -0,0 +1,104 @@
+process.env['SUPPRESS_NO_CONFIG_WARNING'] = 'true';
+import configModule from 'config';
+import _ from 'lodash';
+import path from 'path';
+import * as yup from 'yup';
+import { ValidationError } from 'yup';
+
+export interface ImportProjectConfig {
+  name: string;
+  url: string;
+  api_key: string;
+  git_commit_ish?: string | undefined;
+}
+
+export interface Config {
+  production: boolean;
+  port: number;
+  blocksDir: string;
+  cacheDir: string;
+  mongoConn: string;
+  mongoDbName: string;
+  azureStorageConnection: string;
+  azureStorageAccountName: string;
+  azureStorageUrl: string;
+  secret: string;
+  webFilesTable: string;
+  webRecentFilesTable: string;
+  webFilesBlob: string;
+  importProjects: ImportProjectConfig[];
+}
+
+export class ConfigError extends Error {}
+
+const ImportProjectSchema = yup.object({
+  name: yup.string().required(),
+  url: yup.string().url().required(),
+  api_key: yup.string().required(),
+  git_commit_ish: yup.string().optional(),
+});
+
+const ConfigSchema = yup.object().shape({
+  production: yup.boolean().required(),
+  port: yup.number().required().positive().integer(),
+  blocksDir: yup
+    .string()
+    .required()
+    .transform(v => path.resolve(v)),
+  cacheDir: yup
+    .string()
+    .required()
+    .transform(v => path.resolve(v)),
+  mongoConn: yup.string().required(),
+  mongoDbName: yup.string().required(),
+  azureStorageConnection: yup.string().required(),
+  azureStorageAccountName: yup.string().required(),
+  azureStorageUrl: yup.string().required(),
+  secret: yup.string().required(),
+  webFilesTable: yup.string().required(),
+  webRecentFilesTable: yup.string().required(),
+  webFilesBlob: yup.string().required(),
+  importProjects: yup.array().of(ImportProjectSchema).required(),
+});
+
+function ErrorThrowingConfig(errorMessage: string) {
+  return new Proxy({} as never, {
+    get() {
+      throw new ConfigError(errorMessage);
+    },
+  });
+}
+
+function validateConfig(): Config {
+  if (configModule.util.getConfigSources().length === 0) {
+    return ErrorThrowingConfig('Config file not found, ensure you have "config/default.json" file.');
+  }
+
+  const configObject = configModule.util.toObject();
+  try {
+    return ConfigSchema.validateSync(configObject, { abortEarly: false, stripUnknown: false });
+  } catch (e) {
+    if (e instanceof ValidationError) {
+      return ErrorThrowingConfig(e.errors.join('\n'));
+    } else {
+      throw e;
+    }
+  }
+}
+
+export const config = validateConfig();
+
+function getEnvVarMapping() {
+  const result: Record<string, string | { __name: string; __format: string }> = {};
+  for (const [name, field] of Object.entries(ConfigSchema.fields)) {
+    const envVar = `MARSX_${_.snakeCase(name).toUpperCase()}`;
+    if ('type' in field && (field.type === 'object' || field.type === 'array')) {
+      result[name] = { __name: envVar, __format: 'json' };
+    } else {
+      result[name] = envVar;
+    }
+  }
+  return result;
+}
+
+export const CustomEnvironmentVariables = getEnvVarMapping();

package/src/index.ts

@@ -0,0 +1,6 @@
+export { config, ImportProjectConfig, Config } from './configuration';
+export { compileSfcSource, transpileTypescript } from './utils/compile';
+export { parseSFC, serializeSfc, parseSfcPath, serializeSfcPath, SfcBlock, SfcPath, SfcSource } from './utils/sfc';
+export { convertSfcToV3, convertV3ToSfc, V3MongoBlock } from './utils/v3';
+export * as textUtils from './utils/textUtils';
+export * as fileUtils from './utils/fileUtils';

package/src/launcher.ts

@@ -0,0 +1,39 @@
+import { config } from './configuration';
+import { loadAllBlocks } from './loader';
+import { compileSfcSource, transpileTypescript } from './utils/compile';
+import { parseSFC, serializeSfc } from './utils/sfc';
+import { writeFileMakeDir } from './utils/fileUtils';
+import { assert } from './utils/textUtils';
+import { convertSfcToV3, convertV3ToSfc } from './utils/v3';
+
+const LAUNCHER_UTILS = {
+  config,
+  parseSFC,
+  serializeSfc,
+  convertV3ToSfc,
+  convertSfcToV3,
+  transpileTypescript,
+  compileSfcSource,
+  writeFileMakeDir,
+};
+
+export async function launchBooter(booterBlockName = 'Booter') {
+  const allBlocks = await loadAllBlocks();
+
+  const booterBlocks = allBlocks.filter(b => b.path.name === booterBlockName);
+  if (booterBlocks.length === 0)
+    throw new Error(`Booter block ${booterBlockName} not found. Ensure you have it locally or it is imported.`);
+
+  // Take last because order of imports matter and local blocks always override imported.
+  const booterBlock = booterBlocks[booterBlocks.length - 1];
+  assert(booterBlock);
+
+  const compiledBooterPath = await compileSfcSource(booterBlock, 'BlockFunction');
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    await require(compiledBooterPath).default(allBlocks, LAUNCHER_UTILS);
+  } catch (e) {
+    console.error('Booter failed with:', e);
+    process.exit(1);
+  }
+}

package/src/loader.ts

@@ -0,0 +1,65 @@
+import axios from 'axios';
+import crypto from 'crypto';
+import { promises as fs } from 'fs';
+import stringify from 'json-stable-stringify';
+import _ from 'lodash';
+import path from 'path';
+import { config, ImportProjectConfig } from './configuration';
+import { parseSFC, SfcBlock } from './utils/sfc';
+import { isFile, listFilesRecursive, writeFileMakeDir } from './utils/fileUtils';
+import { convertV3ToSfc, V3MongoBlock } from './utils/v3';
+
+async function downloadFromExternal(externalImport: ImportProjectConfig): Promise<SfcBlock[]> {
+  const params = { api_key: externalImport.api_key, git_commit_ish: externalImport.git_commit_ish || '' };
+
+  console.log(`Downloading blocks from ${externalImport.url}`);
+  try {
+    const v4Resp = await axios.get<SfcBlock[]>(`${externalImport.url}/api/GetExportedAppBlocksV4`, { params });
+    return v4Resp.data;
+  } catch (e) {
+    console.log(`${externalImport.url} does not support V4, fallback to V3`);
+  }
+
+  const v3Resp = await axios.get<V3MongoBlock[]>(`${externalImport.url}/api/GetExportedAppBlocks`, { params });
+  return v3Resp.data.map(b => convertV3ToSfc(b));
+}
+
+async function loadCachedOrDownload(externalImport: ImportProjectConfig): Promise<SfcBlock[]> {
+  const hash = crypto.createHash('md5').update(stringify(externalImport)).digest('hex');
+  const cacheFileName = `${externalImport.name}_${externalImport.git_commit_ish}_${hash}.json`.replace(/[^\w.]+/g, '_');
+  const cacheFilePath = path.join(config.cacheDir, 'imports', cacheFileName);
+
+  if (await isFile(cacheFilePath)) {
+    const content = await fs.readFile(cacheFilePath);
+    console.log(`Loading cached blocks from ${externalImport.url}`);
+    return JSON.parse(content.toString('utf-8'));
+  }
+
+  const data = await downloadFromExternal(externalImport);
+  console.log(`Downloaded ${data.length} blocks from ${externalImport.url}`);
+
+  await writeFileMakeDir(cacheFilePath, JSON.stringify(data, null, 2), 'utf-8');
+  return data;
+}
+
+async function downloadAll(externalImports: ImportProjectConfig[]) {
+  const responses = await Promise.all(externalImports.map(loadCachedOrDownload));
+  return _.flatten(responses);
+}
+
+async function readBlockFile(blocksDir: string, filePath: string): Promise<SfcBlock> {
+  const content = await fs.readFile(filePath);
+  const relPath = path.relative(blocksDir, filePath);
+  return parseSFC(relPath, content);
+}
+
+async function readBlockFiles(blocksDir: string) {
+  const files = await listFilesRecursive(blocksDir);
+  return await Promise.all(files.filter(f => !path.basename(f).startsWith('.')).map(f => readBlockFile(blocksDir, f)));
+}
+
+export async function loadAllBlocks(): Promise<SfcBlock[]> {
+  const externalBlocks = await downloadAll(config.importProjects);
+  const localBlocks = await readBlockFiles(config.blocksDir);
+  return [...externalBlocks, ...localBlocks];
+}

package/src/utils/compile.ts

@@ -0,0 +1,59 @@
+import { SourceMapPayload } from 'module';
+import path from 'path';
+import ts from 'typescript';
+import { config } from '../configuration';
+import { SfcBlock } from './sfc';
+import { writeFileMakeDir } from './fileUtils';
+import { assert } from './textUtils';
+
+function genSourceMapComment(sourceMap: SourceMapPayload): string {
+  return `\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(JSON.stringify(sourceMap)).toString('base64')}`;
+}
+
+export function transpileTypescript(
+  sourceCode: string,
+  options?: {
+    sourceRoot?: string;
+    originalFilePath?: string;
+    compiledFilePath?: string;
+    lineOffset?: number | undefined;
+  },
+): string {
+  const compiledFilePath = options?.compiledFilePath || '<UNKNOWN>.js';
+  const originalFilePath = options?.originalFilePath || '<UNKNOWN>.ts';
+
+  if (options?.lineOffset) {
+    sourceCode = '\n'.repeat(options.lineOffset) + sourceCode;
+  }
+
+  const transpiled = ts.transpileModule(sourceCode, {
+    compilerOptions: {
+      module: ts.ModuleKind.CommonJS,
+      target: ts.ScriptTarget.Latest,
+      esModuleInterop: true,
+      sourceMap: true,
+      // inlineSources: true,
+      // inlineSourceMap: true,
+    },
+  });
+  assert(transpiled.sourceMapText);
+
+  const sourceMap: SourceMapPayload = JSON.parse(transpiled.sourceMapText);
+  sourceMap.sourceRoot = options?.sourceRoot || '';
+  sourceMap.file = compiledFilePath;
+  sourceMap.sources = [originalFilePath];
+  const sourceMapComment = genSourceMapComment(sourceMap);
+  return transpiled.outputText.replace(/\n\/\/# sourceMappingURL=.+/, '') + sourceMapComment;
+}
+
+export async function compileSfcSource(sfcBlock: SfcBlock, sourceId: string): Promise<string> {
+  const sourceCode = sfcBlock.sources[sourceId];
+  if (!sourceCode) throw new Error(`Source code block ${sourceId} not found in ${sfcBlock.path.filePath}`);
+
+  const compiledFilePath = path.join(config.cacheDir, 'compiled', `${sfcBlock.path.filePath}.${sourceId}.js`);
+  const originalFilePath = path.join(config.blocksDir, sfcBlock.path.filePath);
+  const code = transpileTypescript(sourceCode.source, { compiledFilePath, originalFilePath, lineOffset: sourceCode.lineOffset });
+
+  await writeFileMakeDir(compiledFilePath, code, 'utf-8');
+  return compiledFilePath;
+}

package/src/utils/fileUtils.ts

@@ -0,0 +1,54 @@
+import { promises as fs } from 'fs';
+import _ from 'lodash';
+import { Abortable } from 'node:events';
+import { Mode, ObjectEncodingOptions, OpenMode } from 'node:fs';
+import { Stream } from 'node:stream';
+import path from 'path';
+
+export async function listFilesRecursive(dir: string): Promise<string[]> {
+  const entries = await fs.readdir(dir);
+
+  const files = await Promise.all(
+    entries.map(async (entry): Promise<string[]> => {
+      const entryPath = path.resolve(dir, entry);
+      return (await fs.stat(entryPath)).isDirectory() ? listFilesRecursive(entryPath) : [entryPath];
+    }),
+  );
+  return _.flatten(files);
+}
+
+export async function isFile(filePath: string): Promise<boolean> {
+  try {
+    return (await fs.stat(filePath)).isFile();
+  } catch (e) {
+    return false;
+  }
+}
+
+export async function isDirectory(dirPath: string): Promise<boolean> {
+  try {
+    return (await fs.stat(dirPath)).isDirectory();
+  } catch (e) {
+    return false;
+  }
+}
+
+export async function writeFileMakeDir(
+  filePath: string,
+  data:
+    | string
+    | NodeJS.ArrayBufferView
+    | Iterable<string | NodeJS.ArrayBufferView>
+    | AsyncIterable<string | NodeJS.ArrayBufferView>
+    | Stream,
+  options?:
+    | (ObjectEncodingOptions & {
+        mode?: Mode | undefined;
+        flag?: OpenMode | undefined;
+      } & Abortable)
+    | BufferEncoding
+    | null,
+): Promise<void> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, data, options);
+}

package/src/utils/sfc.ts

@@ -0,0 +1,155 @@
+import { CompilerError } from '@vue/compiler-core';
+import JSON5 from 'json5';
+import _ from 'lodash';
+import path from 'path';
+import { escapeCloseTag, escapeHtmlAttr, parseVueLike, stableHtmlAttributes, stablePrettyJson, unescapeCloseTag } from './textUtils';
+
+export const METADATA_SECTION_ID = 'metadata';
+export const MARS_SFC_EXT = 'mars';
+
+const SAVE_EMPTY_SOURCES = true;
+
+export type SfcPath = {
+  folder: string;
+  name: string;
+  blockTypeName: string;
+  ext: string;
+  filePath: string;
+};
+
+export type SfcSource = {
+  source: string;
+  lang: keyof typeof LANG_TAG_MAP | string | undefined;
+  props?: Record<string, string | undefined>;
+  lineOffset?: number;
+};
+
+export type SfcBlock = { path: SfcPath } & (
+  | { metadata: Record<string, unknown>; jsons: Record<string, unknown>; sources: Record<string, SfcSource>; rawContent: null }
+  | { metadata: EmptyObject; jsons: EmptyObject; sources: EmptyObject; rawContent: Buffer }
+);
+
+export function parseSfcPath(filePath: string): SfcPath {
+  // Blog/BlogPost.page.mars => {folder:"Blog", name: "BlogPost", blockTypeName: "page", ext: "mars", fullName: "Blog.BlogPost"}
+  const originalParsed = path.parse(filePath);
+  const withoutExt = originalParsed.name;
+  const ext = originalParsed.ext.slice(1);
+
+  const parsed = path.parse(withoutExt);
+  if (!parsed.name || !parsed.ext) throw new Error(`Invalid block file path: ${filePath}`);
+  const blockTypeName = parsed.ext.slice(1);
+
+  return {
+    folder: originalParsed.dir,
+    name: parsed.name,
+    blockTypeName,
+    ext,
+    filePath,
+  };
+}
+
+export function serializeSfcPath(identity: SfcPath): string {
+  return path.join(identity.folder, `${identity.name}.${identity.blockTypeName}.${identity.ext}`);
+}
+
+type EmptyObject = {
+  [K in string]: never;
+};
+
+const LANG_TAG_MAP = {
+  html: 'html',
+  pug: 'template',
+  js: 'script',
+  jsx: 'script',
+  ts: 'script',
+  tsx: 'script',
+  css: 'style',
+  scss: 'style',
+  less: 'style',
+  sass: 'style',
+  stylus: 'style',
+  text: 'text',
+};
+
+export function parseSFC(filePath: string, content: Buffer): SfcBlock {
+  const sfcPath = parseSfcPath(filePath);
+  if (sfcPath.ext !== MARS_SFC_EXT) {
+    return { path: sfcPath, metadata: {}, jsons: {}, sources: {}, rawContent: content };
+  }
+
+  const block: SfcBlock = {
+    path: parseSfcPath(filePath),
+    metadata: {},
+    jsons: {},
+    sources: {},
+    rawContent: null,
+  };
+  const seenIds = new Set<string>();
+  const errors: (CompilerError | SyntaxError)[] = [];
+
+  for (const node of parseVueLike(content.toString('utf-8'), errors)) {
+    const { id: sectionId, lang, ...props } = node.props;
+
+    if (!sectionId) {
+      errors.push({ name: `missing-id`, message: `Id property is missing`, code: 0, loc: node.loc });
+      continue;
+    }
+    if (seenIds.has(sectionId)) {
+      errors.push({ name: `duplicate-id`, message: `Duplicate section id: ${sectionId}`, code: 0, loc: node.loc });
+      continue;
+    }
+    seenIds.add(sectionId);
+
+    if (node.tag === 'json') {
+      try {
+        const jsonData = JSON5.parse(node.content);
+        if (sectionId === METADATA_SECTION_ID) {
+          block.metadata = jsonData;
+        } else {
+          block.jsons[sectionId] = jsonData;
+        }
+      } catch (e) {
+        errors.push({ name: 'invalid-json', message: `${e}`, code: 0, loc: node.loc });
+      }
+    } else {
+      const source = unescapeCloseTag(node.content.slice(1, -1), node.tag);
+      const lineOffset = node.loc.start.line;
+      block.sources[sectionId] = { source, lang, props, lineOffset };
+    }
+  }
+
+  if (errors.length) {
+    throw new Error(`Parsing SFC ${filePath} failed with ${JSON.stringify(errors)}`);
+  }
+
+  return block;
+}
+
+export function serializeSfc(block: SfcBlock): { filePath: string; content: Buffer } {
+  const filePath = serializeSfcPath(block.path);
+  if (block.path.ext !== MARS_SFC_EXT) {
+    if (block.rawContent === null) throw new Error(`SfcBlock must have rawContent if ext!="${MARS_SFC_EXT}"`);
+    return { filePath, content: block.rawContent };
+  }
+
+  if (block.rawContent !== null) throw new Error(`SfcBlock cannot have rawContent if ext=="${MARS_SFC_EXT}"`);
+
+  let content = '';
+
+  for (const [name, source] of [[METADATA_SECTION_ID, block.metadata] as const, ..._.sortBy(Object.entries(block.jsons), e => e[0])]) {
+    const jsonStr = stablePrettyJson(source);
+    content += `<json id="${escapeHtmlAttr(name)}">\n${jsonStr}</json>\n\n`;
+  }
+
+  for (const [name, source] of _.sortBy(Object.entries(block.sources), e => e[0])) {
+    if (!SAVE_EMPTY_SOURCES && !source.source.trim()) continue;
+    const tag = (LANG_TAG_MAP as Record<string, string>)[source.lang || ''] || 'text';
+    const id = escapeHtmlAttr(name);
+    const lang = escapeHtmlAttr(source.lang || '');
+    const props = stableHtmlAttributes(source.props);
+    const text = escapeCloseTag(source.source, tag);
+    content += `<${tag} id="${id}" lang="${lang}"${props}>\n${text}\n</${tag}>\n\n`;
+  }
+
+  return { filePath, content: Buffer.from(content, 'utf-8') };
+}