tessera-learn 0.2.2 → 0.3.0

package/src/plugin/a11y/audit.ts

@@ -1,5 +1,5 @@
 import { spawn, type SpawnOptions } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, resolve } from 'node:path';
 import { generateManifest, readCourseConfig } from '../manifest.js';
@@ -8,8 +8,6 @@ import { normalizeA11y, type A11ySettings } from '../validation.js';
 export interface AuditOptions {
   /** Minimum violation impact that fails the run (CI gate). Default 'serious'. */
   threshold?: ImpactLevel;
-  /** Force a fresh `vite build` even if dist/ exists. */
-  rebuild?: boolean;
 }
 
 export type ImpactLevel = 'minor' | 'moderate' | 'serious' | 'critical';
@@ -378,7 +376,6 @@ export async function runAudit(
 
   // A throwaway web build, kept out of dist/ so a real LMS export is untouched.
   const auditDist = resolve(projectRoot, 'node_modules', '.tessera-a11y');
-  const distHtml = resolve(auditDist, 'index.html');
 
   const prevEnv = process.env[AUDIT_ENV_FLAG];
   process.env[AUDIT_ENV_FLAG] = '1';
@@ -386,15 +383,13 @@ export async function runAudit(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   let server: any;
   try {
-    if (options.rebuild || !existsSync(distHtml)) {
-      console.log('[tessera a11y] Building course…');
-      await vite.build(
-        vite.mergeConfig(auditBaseConfig, {
-          build: { outDir: auditDist, emptyOutDir: true },
-          logLevel: 'warn',
-        }),
-      );
-    }
+    console.log('[tessera a11y] Building course…');
+    await vite.build(
+      vite.mergeConfig(auditBaseConfig, {
+        build: { outDir: auditDist, emptyOutDir: true },
+        logLevel: 'warn',
+      }),
+    );
 
     server = await vite.preview({
       root: projectRoot,

package/src/plugin/a11y-cli.ts

@@ -13,7 +13,6 @@ export type ParsedA11yArgs =
 
 export function parseA11yArgs(argv: string[]): ParsedA11yArgs {
   let threshold: ImpactLevel | undefined;
-  let rebuild = false;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -26,14 +25,12 @@ export function parseA11yArgs(argv: string[]): ParsedA11yArgs {
         };
       }
       threshold = value;
-    } else if (arg === '--build') {
-      rebuild = true;
     } else {
       return { ok: false, error: `Unknown argument: ${arg}` };
     }
   }
 
-  const args: AuditOptions = { rebuild };
+  const args: AuditOptions = {};
   if (threshold !== undefined) args.threshold = threshold;
   return { ok: true, args };
 }

package/src/plugin/ast.ts

@@ -41,10 +41,12 @@ interface CacheEntry {
 }
 
 const rootCache = new Map<string, CacheEntry>();
+const jsModuleCache = new Map<string, Node | null>();
 
 /** Drop every cached root. Call at the start of a run to scope the cache. */
 export function clearParseCache(): void {
   rootCache.clear();
+  jsModuleCache.clear();
 }
 
 function parseRoot(source: string): CacheEntry {
@@ -168,14 +170,19 @@ const TsParser = Parser.extend(
 );
 
 function parseJsModule(source: string): Node | null {
+  const cached = jsModuleCache.get(source);
+  if (cached !== undefined) return cached;
+  let result: Node | null;
   try {
-    return TsParser.parse(source, {
+    result = TsParser.parse(source, {
       ecmaVersion: 'latest',
       sourceType: 'module',
     }) as unknown as Node;
   } catch {
-    return null;
+    result = null;
   }
+  jsModuleCache.set(source, result);
+  return result;
 }
 
 function unwrapTsCast(node: Node | null): Node | null {

package/src/plugin/cli.ts

@@ -19,8 +19,7 @@ Commands:
 Run a command from inside a course folder, or name the course explicitly.
 
 a11y/check options:
-  --threshold <minor|moderate|serious|critical>   Failing impact (default: serious)
-  --build                                          Force a fresh build first`;
+  --threshold <minor|moderate|serious|critical>   Failing impact (default: serious)`;
 
 // 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
@@ -35,6 +34,27 @@ export function splitCourseArg(rest: string[]): {
   return { course: undefined, flags: rest };
 }
 
+type CourseCommand = (
+  courseRoot: string,
+  workspaceRoot: string,
+  flags: string[],
+) => number | Promise<number>;
+
+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),
+  a11y: (courseRoot, workspaceRoot, flags) =>
+    runA11y(courseRoot, workspaceRoot, flags),
+  check: (courseRoot, workspaceRoot, flags) => {
+    const validateCode = runValidate(courseRoot, { showA11yTip: false });
+    if (validateCode !== 0) return validateCode;
+    return runA11y(courseRoot, workspaceRoot, flags);
+  },
+};
+
 export async function main(
   argv: string[],
   cwd: string = process.cwd(),
@@ -44,56 +64,34 @@ export async function main(
   if (sub === 'new') return runNew(rest[0], cwd);
   if (sub === 'duplicate') return runDuplicate(rest[0], rest[1], cwd);
 
-  switch (sub) {
-    case 'dev':
-    case 'export':
-    case 'validate':
-    case 'a11y':
-    case 'check': {
-      if (rest.includes('--help') || rest.includes('-h')) {
-        console.log(USAGE);
-        return 0;
-      }
-      const { course, flags } = splitCourseArg(rest);
-      const resolved = resolveCourse(cwd, course);
-      if (!resolved.ok) {
-        console.error(`[tessera] ${resolved.error}`);
-        return 1;
-      }
-      const { courseRoot, workspaceRoot } = resolved;
-
-      switch (sub) {
-        case 'dev': {
-          const { runDev } = await import('./build-commands.js');
-          return runDev(courseRoot, workspaceRoot);
-        }
-        case 'export': {
-          const { runBuild } = await import('./build-commands.js');
-          return runBuild(courseRoot, workspaceRoot);
-        }
-        case 'validate':
-          return runValidate(courseRoot);
-        case 'check': {
-          const validateCode = runValidate(courseRoot);
-          if (validateCode !== 0) return validateCode;
-          return runA11y(courseRoot, workspaceRoot, flags);
-        }
-        case 'a11y':
-          return runA11y(courseRoot, workspaceRoot, flags);
-      }
-      return 0;
-    }
-    case '--help':
-    case '-h':
+  if (sub !== undefined && Object.hasOwn(COURSE_COMMANDS, sub)) {
+    if (rest.includes('--help') || rest.includes('-h')) {
       console.log(USAGE);
       return 0;
-    case undefined:
-      console.error(`No command given.\n\n${USAGE}`);
-      return 1;
-    default:
-      console.error(`Unknown command: ${sub}\n\n${USAGE}`);
+    }
+    const { course, flags } = splitCourseArg(rest);
+    const resolved = resolveCourse(cwd, course);
+    if (!resolved.ok) {
+      console.error(`[tessera] ${resolved.error}`);
       return 1;
+    }
+    return COURSE_COMMANDS[sub](
+      resolved.courseRoot,
+      resolved.workspaceRoot,
+      flags,
+    );
+  }
+
+  if (sub === '--help' || sub === '-h') {
+    console.log(USAGE);
+    return 0;
+  }
+  if (sub === undefined) {
+    console.error(`No command given.\n\n${USAGE}`);
+    return 1;
   }
+  console.error(`Unknown command: ${sub}\n\n${USAGE}`);
+  return 1;
 }
 
 // import.meta.main is true only when this module is the program entry point,

package/src/plugin/csp.ts

@@ -0,0 +1,59 @@
+// Baseline Content-Security-Policy for web exports, as a per-directive object so
+// course.config.js can extend individual directives (union, never replace).
+// 'unsafe-inline' stays because Vite injects an inline modulepreload polyfill and
+// Svelte ships scoped <style>. blob: on frame/worker-src needs prior script
+// execution, so it adds no attacker capability; data: is intentionally absent
+// from frame-src (a classic XSS-escalation vector).
+export const WEB_CSP_BASELINE: Record<string, string[]> = {
+  'default-src': ["'self'"],
+  'img-src': ["'self'", 'data:', 'https:'],
+  'media-src': ["'self'", 'blob:', 'data:', 'https:'],
+  'style-src': ["'self'", "'unsafe-inline'"],
+  'script-src': ["'self'", "'unsafe-inline'"],
+  'font-src': ["'self'", 'data:'],
+  'connect-src': ["'self'", 'https:'],
+  'frame-src': ["'self'", 'blob:', 'https:'],
+  'worker-src': ["'self'", 'blob:'],
+  'object-src': ["'none'"],
+  'base-uri': ["'self'"],
+};
+
+// Reject the separators (whitespace ends a source, ';' ends a directive, ','
+// ends a policy) so a stray char can't inject directives when sources are joined,
+// plus " < > so a source can't break out of the content="..." meta attribute.
+const CSP_DIRECTIVE = /^[a-zA-Z][a-zA-Z-]*$/;
+const CSP_SOURCE = /^[^\s;,"<>]+$/;
+
+export function isCspOverrides(v: unknown): v is Record<string, string[]> {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    !Array.isArray(v) &&
+    Object.entries(v).every(
+      ([directive, sources]) =>
+        CSP_DIRECTIVE.test(directive) &&
+        Array.isArray(sources) &&
+        sources.every((s) => typeof s === 'string' && CSP_SOURCE.test(s)),
+    )
+  );
+}
+
+// Malformed input falls back to the baseline unchanged — validation surfaces the
+// warning separately.
+export function buildCsp(overrides?: unknown): string {
+  const merged = new Map(
+    Object.entries(WEB_CSP_BASELINE).map(([k, v]) => [k, [...v]]),
+  );
+  if (isCspOverrides(overrides)) {
+    for (const [directive, sources] of Object.entries(overrides)) {
+      const existing = merged.get(directive) ?? [];
+      for (const src of sources) {
+        if (!existing.includes(src)) existing.push(src);
+      }
+      merged.set(directive, existing);
+    }
+  }
+  return [...merged]
+    .map(([directive, sources]) => `${directive} ${sources.join(' ')}`)
+    .join('; ');
+}

package/src/plugin/duplicate-cli.ts

@@ -1,8 +1,43 @@
-import { cpSync, existsSync } from 'node:fs';
+import { cpSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { basename, join, relative } from 'node:path';
 import { resolveCourse } from './course-root.js';
 import { validateProjectName } from './project-name.js';
 
+// The top-level `id` property as scaffolders write it: the key (bare or quoted)
+// first on its own line, then its value. Anchoring to line start keeps `id:`
+// inside a comment or a string value from matching, and CourseConfig has no
+// nested `id`, so the first match is always the course identity.
+const ID_LINE =
+  /^([ \t]*'?id'?[ \t]*:[ \t]*)('(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|`(?:[^`\\]|\\.)*`|[^\n,}]*)/m;
+const DEFAULT_OBJECT = /export\s+default\s*\{/;
+
+// A verbatim copy inherits the source's `id`; mint a fresh one so the duplicate
+// is a distinct course (own storage key + LRS activity id).
+function reidentifyCourse(courseRoot: string): void {
+  const configPath = join(courseRoot, 'course.config.js');
+  if (!existsSync(configPath)) return;
+  const text = readFileSync(configPath, 'utf-8');
+  const newId = `'urn:uuid:${randomUUID()}'`;
+
+  if (ID_LINE.test(text)) {
+    writeFileSync(configPath, text.replace(ID_LINE, `$1${newId}`));
+    return;
+  }
+  const obj = DEFAULT_OBJECT.exec(text);
+  if (obj) {
+    const at = obj.index + obj[0].length;
+    writeFileSync(
+      configPath,
+      `${text.slice(0, at)}\n  id: ${newId},${text.slice(at)}`,
+    );
+    return;
+  }
+  console.warn(
+    `[tessera duplicate] Could not set a unique id in ${configPath} — the copy shares the source's identity. Add a unique "id" manually.`,
+  );
+}
+
 const HELP =
   'Usage: tessera duplicate <source> <new>\n\n' +
   'Copy courses/<source>/ to courses/<new>/ within the current workspace.';
@@ -62,6 +97,7 @@ export function runDuplicate(
     recursive: true,
     filter: (src) => src === srcDir || !skip(src),
   });
+  reidentifyCourse(destDir);
 
   const rel = relative(workspaceRoot, destDir);
   const srcRel = relative(workspaceRoot, srcDir);

package/src/plugin/export.ts

@@ -10,11 +10,13 @@ import { createWriteStream } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { ZipArchive } from 'archiver';
 import { slugify } from '../runtime/slugify.js';
+import { courseIdentity } from '../runtime/types.js';
 
 // ---------- Types ----------
 
 interface ExportConfig {
   title: string;
+  id?: string;
   description?: string;
   version?: string;
   scoring?: { passingScore?: number };
@@ -24,6 +26,8 @@ interface ExportConfig {
 
 // ---------- Helpers ----------
 
+const UNTITLED_TITLE = 'Untitled Course';
+
 function escapeXml(str: string): string {
   return str
     .replace(/&/g, '&')
@@ -40,11 +44,14 @@ function collectFiles(dir: string, base: string = ''): string[] {
   const files: string[] = [];
   if (!existsSync(dir)) return files;
 
-  for (const entry of readdirSync(dir)) {
-    const fullPath = resolve(dir, entry);
-    const relPath = base ? `${base}/${entry}` : entry;
-    if (statSync(fullPath).isDirectory()) {
-      files.push(...collectFiles(fullPath, relPath));
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const relPath = base ? `${base}/${entry.name}` : entry.name;
+    // Dirent is lstat-based; stat symlinks so a symlinked dir still recurses.
+    const isDir = entry.isSymbolicLink()
+      ? statSync(resolve(dir, entry.name)).isDirectory()
+      : entry.isDirectory();
+    if (isDir) {
+      files.push(...collectFiles(resolve(dir, entry.name), relPath));
     } else {
       files.push(relPath);
     }
@@ -68,6 +75,13 @@ function stableUrn(kind: 'course' | 'au', seed: string): string {
   return `urn:tessera:${kind}:${h.slice(0, 32)}`;
 }
 
+// AU activity id, derived from the course id so re-exports don't orphan LRS
+// records. Shared by the cmi5 and tincan manifests.
+function auIdFor(config: ExportConfig): string {
+  const id = courseIdentity(config);
+  return stableUrn('au', id ? `${id}#au` : 'tessera-au');
+}
+
 function formatSize(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
@@ -115,7 +129,7 @@ export function generateScormManifest(
   distDir: string,
 ): string {
   const dialect = SCORM_DIALECTS[version];
-  const title = escapeXml(config.title || 'Tessera Course');
+  const title = escapeXml(config.title || UNTITLED_TITLE);
   const files = collectFiles(distDir);
   const fileElements = files
     .map((f) => `      <file href="${escapeXml(f)}" />`)
@@ -147,27 +161,16 @@ ${fileElements}
 </manifest>`;
 }
 
-export function generateSCORM12Manifest(
-  config: ExportConfig,
-  distDir: string,
-): string {
-  return generateScormManifest('1.2', config, distDir);
-}
-
-export function generateSCORM2004Manifest(
-  config: ExportConfig,
-  distDir: string,
-): string {
-  return generateScormManifest('2004', config, distDir);
-}
-
 export function generateCMI5Xml(config: ExportConfig): string {
-  const title = escapeXml(config.title || 'Tessera Course');
+  const title = escapeXml(config.title || UNTITLED_TITLE);
   const description = escapeXml(config.description || '');
-  // Derive stable IDs from the course title so they survive rebuilds without
+  // Derive stable IDs from the course id so they survive rebuilds without
   // orphaning existing learner records in the LRS.
-  const courseId = stableUrn('course', `tessera-course:${config.title || ''}`);
-  const auId = stableUrn('au', `tessera-au:${config.title || ''}`);
+  const courseId = stableUrn(
+    'course',
+    courseIdentity(config) || 'tessera-course',
+  );
+  const auId = auIdFor(config);
   // cmi5 §10.2.4 caps masteryScore at 4 decimals; avoid float drift like 0.7000000000000001.
   const masteryScore = Number(
     ((config.scoring?.passingScore ?? 70) / 100).toFixed(4),
@@ -195,6 +198,25 @@ export function generateCMI5Xml(config: ExportConfig): string {
 </courseStructure>`;
 }
 
+export function generateTincanXml(config: ExportConfig): string {
+  const title = escapeXml(config.title || UNTITLED_TITLE);
+  const description = escapeXml(config.description || '');
+  // Reuse the cmi5/SCORM stable-id scheme so re-exports don't orphan LRS records.
+  const auId = auIdFor(config);
+  // tincan.xml carries NO xAPI version — the version is set at runtime by the
+  // adapter's X-Experience-API-Version header, not declared in the manifest.
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<tincan xmlns="http://projecttincan.com/tincan.xsd">
+  <activities>
+    <activity id="${auId}" type="http://adlnet.gov/expapi/activities/course">
+      <name>${title}</name>
+      <description lang="en-US">${description}</description>
+      <launch lang="en-US">index.html</launch>
+    </activity>
+  </activities>
+</tincan>`;
+}
+
 // ---------- ZIP Packaging ----------
 
 export async function createZip(
@@ -238,7 +260,7 @@ function cleanOldZips(projectRoot: string, slug: string): void {
 
 /** Packaged (zipped) export targets: which manifest file to write and how. */
 const PACKAGED_EXPORTS: Record<
-  'scorm12' | 'scorm2004' | 'cmi5',
+  'scorm12' | 'scorm2004' | 'cmi5' | 'xapi',
   {
     manifestFile: string;
     label: string;
@@ -248,18 +270,25 @@ const PACKAGED_EXPORTS: Record<
   scorm12: {
     manifestFile: 'imsmanifest.xml',
     label: 'SCORM 1.2',
-    generate: generateSCORM12Manifest,
+    generate: (config, distDir) =>
+      generateScormManifest('1.2', config, distDir),
   },
   scorm2004: {
     manifestFile: 'imsmanifest.xml',
     label: 'SCORM 2004',
-    generate: generateSCORM2004Manifest,
+    generate: (config, distDir) =>
+      generateScormManifest('2004', config, distDir),
   },
   cmi5: {
     manifestFile: 'cmi5.xml',
     label: 'CMI5',
     generate: (config) => generateCMI5Xml(config),
   },
+  xapi: {
+    manifestFile: 'tincan.xml',
+    label: 'xAPI 1.0.3',
+    generate: (config) => generateTincanXml(config),
+  },
 };
 
 export async function runExport(