refactor: centralize export-standard resolution (#100)

## Summary

The effective export standard (course.config.js `export.standard` + CLI
`--standard` override) was re-derived in ~8 places via three different
idioms: `resolveExportStandard` (returns a string),
`applyStandardOverride` (returns a new config), and an inline mutation
in validation. This unifies the build-plugin path behind one helper.

- New `readResolvedConfig(projectRoot, override)` in `manifest.ts` —
owns override-application plus the `web`/`unknown` defaults, returns
`CourseConfigRead & { standard: string }`.
- Deletes `resolveExportStandard` and `applyStandardOverride`; the 5
call sites (cspMeta, entry/config/adapter/xapi-setup/export plugins)
each collapse to a single `readResolvedConfig` call.
- `validation.ts`'s inline override is intentionally left as-is: it must
validate the file's raw `export.standard` *before* overriding, so its
explicit ordering is clearer than forcing the helper.

No user-facing behavior change.

## Testing

- `pnpm --filter tessera-learn test` → 974 passed
- `pnpm check` → prettier + eslint + svelte-check clean
- Rewrote `export-standard-override.test.ts` to cover
`readResolvedConfig` (config value, web default, override-wins, field
preservation, `unknown` fail-closed, override-on-unreadable).

Modes: pure build/CLI resolution refactor — exercised across all
standards by the existing unit suite (web/scorm12/scorm2004/cmi5/xapi);
no runtime adapter behavior changed.

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: redmodd

.changeset/resolve-export-standard.md

@@ -0,0 +1,6 @@
+---
+'tessera-learn': patch
+'create-tessera': patch
+---
+
+Centralize export-standard resolution behind a single `readResolvedConfig` helper (no user-facing change).

packages/tessera-learn/src/plugin/index.ts

@@ -13,6 +13,7 @@ import {
 import {
   generateManifest,
   readCourseConfig,
+  readResolvedConfig,
   type CourseConfigRead,
 } from './manifest.js';
 import type { Manifest } from './manifest.js';
@@ -194,13 +195,10 @@ function tesseraEntryPlugin(standardOverride?: string): Plugin {
     // For build mode: write index.html so Rollup can find it
     buildStart() {
       if (isBuild) {
-        const read = readCourseConfig(projectRoot);
+        const read = readResolvedConfig(projectRoot, standardOverride);
         writeFileSync(
           resolve(projectRoot, 'index.html'),
-          generateIndexHtml(
-            readLanguage(read),
-            cspMeta(read, standardOverride),
-          ),
+          generateIndexHtml(readLanguage(read), cspMeta(read)),
           'utf-8',
         );
       }
@@ -269,32 +267,12 @@ function readLanguage(read: CourseConfigRead): string {
   return isPlausibleLanguageTag(lang) ? lang : 'en';
 }
 
-// Override wins, else course.config.js, else 'web'. An unreadable config with no
-// override fails closed with 'unknown' so cspMeta withholds the CSP rather than
-// guess the one mode it breaks. Exported for tests.
-export function resolveExportStandard(
-  read: CourseConfigRead,
-  override?: string,
-): string {
-  if (override) return override;
-  if (!read.ok) return 'unknown';
-  return read.config.export?.standard || 'web';
-}
-
-/** Apply a CLI `--standard` override onto a config's export.standard. Exported for tests. */
-export function applyStandardOverride<
-  T extends { export?: { standard?: string } },
->(config: T, override?: string): T {
-  if (!override) return config;
-  return { ...config, export: { ...config.export, standard: override } };
-}
-
 // Web export only — never on LMS packages (whose iframe JS bridges a meta CSP
 // could break) and never on the dev server (a meta connect-src would block
 // Vite's HMR websocket). `export.csp` extends the baseline per-directive, or
 // `false` drops the meta for deployments that set a CSP header themselves.
-function cspMeta(read: CourseConfigRead, override?: string): string {
-  if (resolveExportStandard(read, override) !== 'web') return '';
+function cspMeta(read: CourseConfigRead & { standard: string }): string {
+  if (read.standard !== 'web') return '';
   const csp = read.ok ? read.config.export?.csp : undefined;
   if (csp === false) return '';
   return `\n  <meta http-equiv="Content-Security-Policy" content="${buildCsp(csp)}" />`;
@@ -424,12 +402,11 @@ function tesseraConfigPlugin(standardOverride?: string): Plugin {
     function ({ projectRoot }) {
       const configPath = resolve(projectRoot, 'course.config.js');
       if (existsSync(configPath)) this.addWatchFile(configPath);
-      const read = readCourseConfig(projectRoot);
+      // The runtime reads export.standard too, so readResolvedConfig must apply
+      // the override here — the bundled config, not just the manifest/adapter.
+      const read = readResolvedConfig(projectRoot, standardOverride);
       const userConfig: Partial<CourseConfig> = read.ok ? read.config : {};
-      // The runtime reads export.standard too, so the override must reach the
-      // bundled config, not just the manifest/adapter.
-      const withOverride = applyStandardOverride(userConfig, standardOverride);
-      return `export default ${JSON.stringify(mergeCourseConfig(withOverride))};`;
+      return `export default ${JSON.stringify(mergeCourseConfig(userConfig))};`;
     },
   );
 }
@@ -556,7 +533,7 @@ function tesseraExportPlugin(standardOverride?: string): Plugin {
       if (!isBuild) return;
       if (isAuditBuild()) return;
 
-      const read = readCourseConfig(projectRoot);
+      const read = readResolvedConfig(projectRoot, standardOverride);
       if (!read.ok) {
         // Validation already required a parseable course.config.js — getting
         // here means it vanished or broke mid-build. Surface that loudly
@@ -576,8 +553,10 @@ function tesseraExportPlugin(standardOverride?: string): Plugin {
         );
       }
 
-      const config = applyStandardOverride(read.config, standardOverride);
-      await runExport(projectRoot, config as Parameters<typeof runExport>[1]);
+      await runExport(
+        projectRoot,
+        read.config as Parameters<typeof runExport>[1],
+      );
     },
   };
 }
@@ -735,10 +714,7 @@ function tesseraAdapterPlugin(standardOverride?: string): Plugin {
         return `export { createAdapter } from 'tessera-learn/runtime/adapters/index.js';`;
       }
 
-      let standard = resolveExportStandard(
-        readCourseConfig(projectRoot),
-        standardOverride,
-      );
+      let standard = readResolvedConfig(projectRoot, standardOverride).standard;
 
       // The audit renders headless with no LMS in the frame chain; the SCORM/
       // cmi5 adapters throw when their API is absent, so render with WebAdapter.
@@ -775,8 +751,8 @@ function tesseraXAPISetupPlugin(standardOverride?: string): Plugin {
         return `export async function buildXAPIClient() { return null; }`;
       }
 
-      const read = readCourseConfig(projectRoot);
-      const standard = resolveExportStandard(read, standardOverride);
+      const read = readResolvedConfig(projectRoot, standardOverride);
+      const standard = read.standard;
       const hasXapi = read.ok && read.config.xapi != null;
 
       // The launch standards (cmi5, plain xAPI) own a publisher the runtime

packages/tessera-learn/src/plugin/manifest.ts

@@ -121,6 +121,27 @@ export function readCourseConfig(projectRoot: string): CourseConfigRead {
   }
 }
 
+/**
+ * Resolve a project's effective export standard once: the CLI `--standard`
+ * override wins, else `export.standard`, else `'web'`. An unreadable config with
+ * no override fails closed with `'unknown'` so callers withhold standard-specific
+ * output rather than guess. The returned `config` already has the override
+ * applied, so consumers read it back directly. Exported for tests.
+ */
+export function readResolvedConfig(
+  projectRoot: string,
+  standardOverride?: string,
+): CourseConfigRead & { standard: string } {
+  const read = readCourseConfig(projectRoot);
+  if (!read.ok) return { ...read, standard: standardOverride ?? 'unknown' };
+  // The CLI validates --standard against the allowed set before it reaches here.
+  const override = standardOverride as CourseConfig['export']['standard'];
+  const config: Partial<CourseConfig> = override
+    ? { ...read.config, export: { ...read.config.export, standard: override } }
+    : read.config;
+  return { ok: true, config, standard: config.export?.standard || 'web' };
+}
+
 /**
  * Read a _meta.js file and extract its default export object.
  * Uses the same JSON5 approach as pageConfig extraction — find the object literal

packages/tessera-learn/tests/export-standard-override.test.ts

@@ -1,59 +1,64 @@
-import { describe, it, expect } from 'vitest';
-import {
-  resolveExportStandard,
-  applyStandardOverride,
-} from '../src/plugin/index.js';
-import type { CourseConfigRead } from '../src/plugin/manifest.js';
-
-const ok = (standard?: string): CourseConfigRead => ({
-  ok: true,
-  config: standard === undefined ? {} : { export: { standard } },
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { readResolvedConfig } from '../src/plugin/manifest.js';
+
+let projectRoot: string;
+
+beforeEach(() => {
+  projectRoot = resolve(
+    tmpdir(),
+    `tessera-resolve-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  mkdirSync(projectRoot, { recursive: true });
+});
+
+afterEach(() => {
+  if (existsSync(projectRoot))
+    rmSync(projectRoot, { recursive: true, force: true });
 });
 
-describe('resolveExportStandard', () => {
+function writeConfig(body: string) {
+  writeFileSync(
+    resolve(projectRoot, 'course.config.js'),
+    `export default ${body};`,
+    'utf-8',
+  );
+}
+
+describe('readResolvedConfig', () => {
   it('uses the course config standard when no override is given', () => {
-    expect(resolveExportStandard(ok('scorm12'))).toBe('scorm12');
+    writeConfig(`{ export: { standard: "scorm12" } }`);
+    const read = readResolvedConfig(projectRoot);
+    expect(read.standard).toBe('scorm12');
+    expect(read.ok && read.config.export?.standard).toBe('scorm12');
   });
 
   it('defaults to web when the config omits export.standard', () => {
-    expect(resolveExportStandard(ok())).toBe('web');
+    writeConfig(`{ title: "x" }`);
+    expect(readResolvedConfig(projectRoot).standard).toBe('web');
   });
 
-  it('lets a CLI override win over the config standard', () => {
-    expect(resolveExportStandard(ok('web'), 'cmi5')).toBe('cmi5');
+  it('lets a CLI override win while preserving other export fields', () => {
+    writeConfig(`{ export: { standard: "web", csp: false } }`);
+    const read = readResolvedConfig(projectRoot, 'cmi5');
+    expect(read.standard).toBe('cmi5');
+    expect(read.ok && read.config.export).toEqual({
+      standard: 'cmi5',
+      csp: false,
+    });
   });
 
   it('reports unknown for an unreadable config with no override', () => {
-    expect(resolveExportStandard({ ok: false, reason: 'missing' })).toBe(
-      'unknown',
-    );
+    const read = readResolvedConfig(projectRoot);
+    expect(read.ok).toBe(false);
+    expect(read.standard).toBe('unknown');
   });
 
   it('honours the override even when the config is unreadable', () => {
-    expect(
-      resolveExportStandard({ ok: false, reason: 'missing' }, 'scorm2004'),
-    ).toBe('scorm2004');
-  });
-});
-
-describe('applyStandardOverride', () => {
-  it('returns the config unchanged when no override is given', () => {
-    const config = { export: { standard: 'web' } };
-    expect(applyStandardOverride(config)).toBe(config);
-  });
-
-  it('overrides export.standard while preserving other export fields', () => {
-    expect(
-      applyStandardOverride(
-        { export: { standard: 'web', csp: false } },
-        'cmi5',
-      ),
-    ).toEqual({ export: { standard: 'cmi5', csp: false } });
-  });
-
-  it('sets export.standard when the config has no export block', () => {
-    expect(applyStandardOverride({}, 'scorm2004')).toEqual({
-      export: { standard: 'scorm2004' },
-    });
+    const read = readResolvedConfig(projectRoot, 'scorm2004');
+    expect(read.ok).toBe(false);
+    expect(read.standard).toBe('scorm2004');
   });
 });