tessera-learn 0.3.0 → 0.4.0

package/src/plugin/cli.ts

@@ -4,6 +4,7 @@ import { runA11y } from './a11y-cli.js';
 import { runNew } from './new-cli.js';
 import { runDuplicate } from './duplicate-cli.js';
 import { resolveCourse } from './course-root.js';
+import { VALID_EXPORT_STANDARDS } from './validation.js';
 
 const USAGE = `Usage: tessera <command> [course] [options]
 
@@ -18,9 +19,42 @@ Commands:
 
 Run a command from inside a course folder, or name the course explicitly.
 
+export/validate options:
+  --standard <web|scorm12|scorm2004|cmi5|xapi>    Override course.config.js export.standard
+
 a11y/check options:
   --threshold <minor|moderate|serious|critical>   Failing impact (default: serious)`;
 
+// Validate here, against the config validator's list, so an unknown standard
+// fails before Vite spins up.
+export function parseExportFlags(flags: string[]): {
+  standardOverride?: string;
+  error?: string;
+} {
+  let standardOverride: string | undefined;
+  for (let i = 0; i < flags.length; i++) {
+    const arg = flags[i];
+    let value: string | undefined;
+    if (arg === '--standard') {
+      value = flags[++i];
+    } else if (arg.startsWith('--standard=')) {
+      value = arg.slice('--standard='.length);
+    } else {
+      return { error: `Unknown argument: ${arg}` };
+    }
+    if (value === undefined || value.startsWith('-')) {
+      return { error: '--standard requires a value' };
+    }
+    if (!VALID_EXPORT_STANDARDS.includes(value)) {
+      return {
+        error: `--standard must be one of ${VALID_EXPORT_STANDARDS.join(', ')}, got "${value}"`,
+      };
+    }
+    standardOverride = value;
+  }
+  return standardOverride ? { standardOverride } : {};
+}
+
 // The course is a leading positional: `tessera <cmd> [course] [flags]`. Only the
 // first token can be the course, and only when it isn't a flag — otherwise a flag
 // value (e.g. the `serious` in `--threshold serious`) would be misread as a name.
@@ -43,9 +77,26 @@ type CourseCommand = (
 const COURSE_COMMANDS: Record<string, CourseCommand> = {
   dev: async (courseRoot, workspaceRoot) =>
     (await import('./build-commands.js')).runDev(courseRoot, workspaceRoot),
-  export: async (courseRoot, workspaceRoot) =>
-    (await import('./build-commands.js')).runBuild(courseRoot, workspaceRoot),
-  validate: (courseRoot) => runValidate(courseRoot),
+  export: async (courseRoot, workspaceRoot, flags) => {
+    const { standardOverride, error } = parseExportFlags(flags);
+    if (error) {
+      console.error(`[tessera] ${error}`);
+      return 1;
+    }
+    return (await import('./build-commands.js')).runBuild(
+      courseRoot,
+      workspaceRoot,
+      standardOverride,
+    );
+  },
+  validate: (courseRoot, _workspaceRoot, flags) => {
+    const { standardOverride, error } = parseExportFlags(flags);
+    if (error) {
+      console.error(`[tessera] ${error}`);
+      return 1;
+    }
+    return runValidate(courseRoot, { standardOverride });
+  },
   a11y: (courseRoot, workspaceRoot, flags) =>
     runA11y(courseRoot, workspaceRoot, flags),
   check: (courseRoot, workspaceRoot, flags) => {

package/src/plugin/index.ts

@@ -13,6 +13,7 @@ import {
 import {
   generateManifest,
   readCourseConfig,
+  readResolvedConfig,
   type CourseConfigRead,
 } from './manifest.js';
 import type { Manifest } from './manifest.js';
@@ -119,7 +120,8 @@ function virtualModule(
   };
 }
 
-export function tesseraPlugin() {
+export function tesseraPlugin(options: { standardOverride?: string } = {}) {
+  const { standardOverride } = options;
   const manifestRef: { current: Manifest | null; root: string } = {
     current: null,
     root: '',
@@ -150,18 +152,18 @@ export function tesseraPlugin() {
       },
     }),
     tesseraA11yCompilerPlugin(a11y),
-    tesseraValidationPlugin(),
-    tesseraEntryPlugin(),
+    tesseraValidationPlugin(standardOverride),
+    tesseraEntryPlugin(standardOverride),
     tesseraConfigDefaultsPlugin(),
-    tesseraConfigPlugin(),
+    tesseraConfigPlugin(standardOverride),
     tesseraPagesPlugin(),
     tesseraManifestPlugin(manifestRef),
     tesseraLayoutPlugin(),
     tesseraQuizPlugin(),
-    tesseraAdapterPlugin(),
-    tesseraXAPISetupPlugin(),
+    tesseraAdapterPlugin(standardOverride),
+    tesseraXAPISetupPlugin(standardOverride),
     tesseraFirstPagePreloadPlugin(manifestRef),
-    tesseraExportPlugin(),
+    tesseraExportPlugin(standardOverride),
   ];
 }
 
@@ -172,7 +174,7 @@ const RESOLVED_ENTRY_ID = '\0' + VIRTUAL_ENTRY_ID;
 const VIRTUAL_MAIN_ID = '/virtual:tessera-main';
 const RESOLVED_MAIN_ID = '\0virtual:tessera-main';
 
-function tesseraEntryPlugin(): Plugin {
+function tesseraEntryPlugin(standardOverride?: string): Plugin {
   const runtimeDir = resolveRuntimeDir();
   const stylesDir = resolveStylesDir();
   const appSveltePath = resolve(runtimeDir, 'App.svelte');
@@ -193,7 +195,7 @@ function tesseraEntryPlugin(): 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)),
@@ -265,19 +267,12 @@ function readLanguage(read: CourseConfigRead): string {
   return isPlausibleLanguageTag(lang) ? lang : 'en';
 }
 
-// Fail closed on an unreadable config: cspMeta only emits for exactly 'web', so
-// an unknown standard withholds the CSP rather than guess the one mode it breaks.
-function readExportStandard(read: CourseConfigRead): string {
-  if (!read.ok) return 'unknown';
-  return read.config.export?.standard || 'web';
-}
-
 // 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): string {
-  if (readExportStandard(read) !== '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)}" />`;
@@ -392,6 +387,7 @@ export function mergeCourseConfig(userConfig: Partial<CourseConfig>) {
   return {
     ...userConfig,
     title: userConfig.title || 'Untitled Course',
+    resume: userConfig.resume ?? 'auto',
     navigation: { mode: 'free', ...userConfig.navigation },
     completion: { ...completion, ...userConfig.completion },
     scoring: { passingScore, ...userConfig.scoring },
@@ -399,14 +395,16 @@ export function mergeCourseConfig(userConfig: Partial<CourseConfig>) {
   };
 }
 
-function tesseraConfigPlugin(): Plugin {
+function tesseraConfigPlugin(standardOverride?: string): Plugin {
   return virtualModule(
     'tessera:config',
     VIRTUAL_CONFIG_ID,
     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 : {};
       return `export default ${JSON.stringify(mergeCourseConfig(userConfig))};`;
     },
@@ -448,7 +446,7 @@ function tesseraPagesPlugin(): Plugin {
 
 // ---------- Validation Plugin ----------
 
-function tesseraValidationPlugin(): Plugin {
+function tesseraValidationPlugin(standardOverride?: string): Plugin {
   let projectRoot: string;
   let isBuild = false;
 
@@ -461,14 +459,14 @@ function tesseraValidationPlugin(): Plugin {
       isBuild = config.command === 'build';
       // Run validation during dev (configResolved fires before server starts)
       if (!isBuild) {
-        runValidation(projectRoot);
+        runValidation(projectRoot, standardOverride);
       }
     },
 
     buildStart() {
       // Run validation during build (buildStart fires once before bundling)
       if (isBuild) {
-        runValidation(projectRoot);
+        runValidation(projectRoot, standardOverride);
       }
     },
   };
@@ -506,8 +504,8 @@ function tesseraA11yCompilerPlugin(a11y: A11yCompilerState): Plugin {
   };
 }
 
-function runValidation(projectRoot: string): void {
-  const result = validateProject(projectRoot);
+function runValidation(projectRoot: string, standardOverride?: string): void {
+  const result = validateProject(projectRoot, standardOverride);
   reportValidationIssues(result);
   if (result.errors.length > 0) {
     throw new Error(
@@ -518,7 +516,7 @@ function runValidation(projectRoot: string): void {
 
 // ---------- Export Plugin ----------
 
-function tesseraExportPlugin(): Plugin {
+function tesseraExportPlugin(standardOverride?: string): Plugin {
   let projectRoot: string;
   let isBuild = false;
 
@@ -535,7 +533,7 @@ function tesseraExportPlugin(): 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
@@ -705,7 +703,7 @@ export function createAdapter() {
 `;
 }
 
-function tesseraAdapterPlugin(): Plugin {
+function tesseraAdapterPlugin(standardOverride?: string): Plugin {
   return virtualModule(
     'tessera:adapter',
     VIRTUAL_ADAPTER_ID,
@@ -716,11 +714,7 @@ function tesseraAdapterPlugin(): Plugin {
         return `export { createAdapter } from 'tessera-learn/runtime/adapters/index.js';`;
       }
 
-      let standard = 'web';
-      const read = readCourseConfig(projectRoot);
-      if (read.ok && typeof read.config.export?.standard === 'string') {
-        standard = read.config.export.standard;
-      }
+      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.
@@ -743,7 +737,7 @@ export function createAdapter(config, options) {
 
 const VIRTUAL_XAPI_SETUP_ID = 'virtual:tessera-xapi-setup';
 
-function tesseraXAPISetupPlugin(): Plugin {
+function tesseraXAPISetupPlugin(standardOverride?: string): Plugin {
   return virtualModule(
     'tessera:xapi-setup',
     VIRTUAL_XAPI_SETUP_ID,
@@ -757,14 +751,9 @@ function tesseraXAPISetupPlugin(): Plugin {
         return `export async function buildXAPIClient() { return null; }`;
       }
 
-      let standard = 'web';
-      let hasXapi = false;
-      const read = readCourseConfig(projectRoot);
-      if (read.ok) {
-        if (typeof read.config.export?.standard === 'string')
-          standard = read.config.export.standard;
-        hasXapi = read.config.xapi != null;
-      }
+      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
       // can share for `endpoint: 'lms'`, so wire the client regardless of

package/src/plugin/inline-config.ts

@@ -15,11 +15,12 @@ import { tesseraPlugin } from './index.js';
 export function buildInlineConfig(
   projectRoot: string,
   workspaceRoot: string,
+  standardOverride?: string,
 ): InlineConfig {
   return {
     root: projectRoot,
     configFile: false,
-    plugins: [tesseraPlugin()],
+    plugins: [tesseraPlugin({ standardOverride })],
     resolve: { alias: { $shared: resolve(workspaceRoot, 'shared') } },
     server: { fs: { allow: [workspaceRoot] } },
   };
@@ -46,9 +47,10 @@ export async function resolveTesseraConfig(
   projectRoot: string,
   workspaceRoot: string,
   env: ConfigEnv,
+  standardOverride?: string,
 ): Promise<InlineConfig> {
   const vite = await import('vite');
-  const base = buildInlineConfig(projectRoot, workspaceRoot);
+  const base = buildInlineConfig(projectRoot, workspaceRoot, standardOverride);
   const user = await loadUserConfig(projectRoot, env);
   return user ? vite.mergeConfig(base, user) : base;
 }

package/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

package/src/plugin/validate-cli.ts

@@ -3,9 +3,12 @@ import { validateProject, reportValidationIssues } from './validation.js';
 
 export function runValidate(
   projectRoot: string,
-  { showA11yTip = true }: { showA11yTip?: boolean } = {},
+  {
+    showA11yTip = true,
+    standardOverride,
+  }: { showA11yTip?: boolean; standardOverride?: string } = {},
 ): number {
-  const { errors, warnings } = validateProject(projectRoot);
+  const { errors, warnings } = validateProject(projectRoot, standardOverride);
 
   reportValidationIssues({ errors, warnings });