tessera-learn 0.2.1 → 0.2.3

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/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
@@ -74,7 +73,7 @@ export async function main(
         case 'validate':
           return runValidate(courseRoot);
         case 'check': {
-          const validateCode = runValidate(courseRoot);
+          const validateCode = runValidate(courseRoot, { showA11yTip: false });
           if (validateCode !== 0) return validateCode;
           return runA11y(courseRoot, workspaceRoot, flags);
         }

package/src/plugin/course-root.ts

@@ -32,29 +32,57 @@ export function findWorkspaceRoot(cwd: string): string | null {
   }
 }
 
-export function listCourses(workspaceRoot: string): string[] {
+function scanCourses(workspaceRoot: string): {
+  courses: string[];
+  malformed: string[];
+} {
   const coursesDir = join(workspaceRoot, 'courses');
+  const courses: string[] = [];
+  const malformed: string[] = [];
   try {
-    return readdirSync(coursesDir, { withFileTypes: true })
-      .filter((e) => e.isDirectory() && isCourse(join(coursesDir, e.name)))
-      .map((e) => e.name)
-      .sort();
+    for (const e of readdirSync(coursesDir, { withFileTypes: true })) {
+      if (!e.isDirectory()) continue;
+      const dir = join(coursesDir, e.name);
+      if (isCourse(dir)) courses.push(e.name);
+      else if (isDir(join(dir, 'pages'))) malformed.push(e.name);
+    }
   } catch {
-    return [];
+    return { courses, malformed };
   }
+  return { courses: courses.sort(), malformed: malformed.sort() };
+}
+
+export function listCourses(workspaceRoot: string): string[] {
+  return scanCourses(workspaceRoot).courses;
+}
+
+export function listMalformedCourses(workspaceRoot: string): string[] {
+  return scanCourses(workspaceRoot).malformed;
 }
 
 const NOT_A_WORKSPACE =
   'Not inside a Tessera workspace — no `courses/` directory was found at or above the current directory.';
 
+function malformedHint(malformed: string[]): string {
+  if (malformed.length === 0) return '';
+  return (
+    `\nSkipped (missing course.config.js):\n` +
+    malformed.map((c) => `  courses/${c}`).join('\n')
+  );
+}
+
 function listHint(workspaceRoot: string): string {
-  const courses = listCourses(workspaceRoot);
+  const { courses, malformed } = scanCourses(workspaceRoot);
   if (courses.length === 0) {
-    return '\nNo courses found. Create one with `tessera new <name>`.';
+    return (
+      '\nNo courses found. Create one with `tessera new <name>`.' +
+      malformedHint(malformed)
+    );
   }
   return (
     `\nAvailable courses:\n${courses.map((c) => `  ${c}`).join('\n')}` +
-    '\nName one (`tessera <command> <course>`) or cd into its folder.'
+    '\nName one (`tessera <command> <course>`) or cd into its folder.' +
+    malformedHint(malformed)
   );
 }
 

package/src/plugin/validate-cli.ts

@@ -1,6 +1,10 @@
+import { basename } from 'node:path';
 import { validateProject, reportValidationIssues } from './validation.js';
 
-export function runValidate(projectRoot: string): number {
+export function runValidate(
+  projectRoot: string,
+  { showA11yTip = true }: { showA11yTip?: boolean } = {},
+): number {
   const { errors, warnings } = validateProject(projectRoot);
 
   reportValidationIssues({ errors, warnings });
@@ -23,8 +27,10 @@ export function runValidate(projectRoot: string): number {
       '\x1b[32m[tessera]\x1b[0m Validation passed — no issues found.',
     );
   }
-  console.log(
-    '\x1b[2m[tessera] Static checks only. For a full runtime accessibility audit, run: pnpm exec tessera a11y\x1b[0m',
-  );
+  if (showA11yTip) {
+    console.log(
+      `\x1b[2m[tessera] Static checks only. For a full runtime accessibility audit, run: pnpm a11y ${basename(projectRoot)}\x1b[0m`,
+    );
+  }
   return 0;
 }

package/src/runtime/adapters/cmi5.ts

@@ -579,10 +579,7 @@ export class CMI5Adapter implements PersistenceAdapter {
     opts: { moveOn?: boolean; mastery?: boolean } = {},
   ): Record<string, unknown> {
     const tmpl = this.#launchData?.contextTemplate ?? {};
-    const tmplActivities = (tmpl.contextActivities ?? {}) as Record<
-      string,
-      unknown
-    >;
+    const tmplActivities = tmpl.contextActivities ?? {};
 
     // Concat-dedupe category to preserve any template-supplied entries
     // (§10.2.1 forbids overwriting them).
@@ -594,14 +591,8 @@ export class CMI5Adapter implements PersistenceAdapter {
         category.push({ id, objectType: 'Activity' });
       }
     };
-    const templateCategory = Array.isArray(
-      (tmplActivities as { category?: unknown }).category,
-    )
-      ? (
-          tmplActivities as {
-            category: Array<{ id: string; objectType?: string }>;
-          }
-        ).category
+    const templateCategory = Array.isArray(tmplActivities.category)
+      ? tmplActivities.category
       : [];
     for (const c of templateCategory) {
       if (c && typeof c.id === 'string') push(c.id);
@@ -615,13 +606,13 @@ export class CMI5Adapter implements PersistenceAdapter {
     };
 
     const ctx: Record<string, unknown> = {
-      ...(tmpl as Record<string, unknown>),
+      ...tmpl,
       contextActivities,
     };
     // cmi5 §9.6.3.2 — masteryScore extension is scoped to Passed/Failed.
     if (opts.mastery && this.#masteryScore !== null) {
       ctx.extensions = {
-        ...((tmpl.extensions ?? {}) as Record<string, unknown>),
+        ...(tmpl.extensions ?? {}),
         [CMI5_MASTERYSCORE_EXT]: this.#masteryScore,
       };
     }

package/src/runtime/adapters/index.ts

@@ -19,27 +19,6 @@ export class LMSAdapterError extends Error {
   }
 }
 
-function missingApiError(
-  standard: 'scorm12' | 'scorm2004' | 'cmi5',
-): LMSAdapterError {
-  const label =
-    standard === 'scorm12'
-      ? 'SCORM 1.2'
-      : standard === 'scorm2004'
-        ? 'SCORM 2004'
-        : 'cmi5';
-  const detail =
-    standard === 'cmi5'
-      ? 'No cmi5 launch parameters (fetch / endpoint / activityId / actor) on the URL.'
-      : `No ${label} API object found in the window.parent or window.opener chain.`;
-  return new LMSAdapterError(
-    standard,
-    `Tessera: this course is configured for ${label} but ${detail} ` +
-      `The course must be launched from an LMS that provides the ${label} runtime. ` +
-      `If you are testing locally, run \`npm run dev\` instead, or set export.standard to "web".`,
-  );
-}
-
 export interface CreateAdapterOptions {
   /**
    * When true, a missing LMS API falls back to `WebAdapter` with a console
@@ -49,44 +28,68 @@ export interface CreateAdapterOptions {
   allowFallback?: boolean;
 }
 
-/**
- * Select the appropriate persistence adapter based on course config.
- *
- * In production builds, an LMS-configured course (scorm12/scorm2004/cmi5)
- * will throw `LMSAdapterError` if the matching LMS API isn't reachable —
- * we fail loud so a misconfigured launch is visible immediately rather
- * than silently losing tracking to localStorage.
- *
- * In dev mode, missing APIs warn and fall back to `WebAdapter` so authors
- * can still iterate locally.
- */
 type LMSStandard = 'scorm12' | 'scorm2004' | 'cmi5';
 
-/** Per-standard LMS detection. `detect` returns an adapter when the LMS runtime is reachable, else null. */
+/** Per-standard LMS wiring: `detect` returns an adapter when the LMS runtime is reachable, else null. Labels are the single source for the dev warning and production error. */
 const LMS_ADAPTERS: Record<
   LMSStandard,
-  { detect: () => PersistenceAdapter | null; label: string }
+  {
+    detect: () => PersistenceAdapter | null;
+    warnLabel: string;
+    name: string;
+    missingDetail: string;
+  }
 > = {
   scorm12: {
     detect: () => {
       const api = findSCORM12API();
       return api ? new SCORM12Adapter(api) : null;
     },
-    label: 'SCORM 1.2 API',
+    warnLabel: 'SCORM 1.2 API',
+    name: 'SCORM 1.2',
+    missingDetail:
+      'No SCORM 1.2 API object found in the window.parent or window.opener chain.',
   },
   scorm2004: {
     detect: () => {
       const api = findSCORM2004API();
       return api ? new SCORM2004Adapter(api) : null;
     },
-    label: 'SCORM 2004 API',
+    warnLabel: 'SCORM 2004 API',
+    name: 'SCORM 2004',
+    missingDetail:
+      'No SCORM 2004 API object found in the window.parent or window.opener chain.',
   },
   cmi5: {
     detect: () => (hasCMI5LaunchParams() ? new CMI5Adapter() : null),
-    label: 'cmi5 launch parameters',
+    warnLabel: 'cmi5 launch parameters',
+    name: 'cmi5',
+    missingDetail:
+      'No cmi5 launch parameters (fetch / endpoint / activityId / actor) on the URL.',
   },
 };
 
+function missingApiError(standard: LMSStandard): LMSAdapterError {
+  const { name, missingDetail } = LMS_ADAPTERS[standard];
+  return new LMSAdapterError(
+    standard,
+    `Tessera: this course is configured for ${name} but ${missingDetail} ` +
+      `The course must be launched from an LMS that provides the ${name} runtime. ` +
+      `If you are testing locally, run \`npm run dev\` instead, or set export.standard to "web".`,
+  );
+}
+
+/**
+ * Select the appropriate persistence adapter based on course config.
+ *
+ * In production builds, an LMS-configured course (scorm12/scorm2004/cmi5)
+ * will throw `LMSAdapterError` if the matching LMS API isn't reachable —
+ * we fail loud so a misconfigured launch is visible immediately rather
+ * than silently losing tracking to localStorage.
+ *
+ * In dev mode, missing APIs warn and fall back to `WebAdapter` so authors
+ * can still iterate locally.
+ */
 export function createAdapter(
   config: CourseConfig,
   options: CreateAdapterOptions = {},
@@ -103,7 +106,7 @@ export function createAdapter(
     if (adapter) return adapter;
     if (!allowFallback) throw missingApiError(standard);
     console.warn(
-      `Tessera (dev): ${entry.label} not found — falling back to localStorage`,
+      `Tessera (dev): ${entry.warnLabel} not found — falling back to localStorage`,
     );
   }
   return new WebAdapter(config);

package/src/runtime/adapters/scorm12.ts

@@ -29,7 +29,7 @@ const SCORM12_DIALECT: ScormDialect<SCORM12API> = {
     responseField: 'student_response',
     timestampField: 'time',
     timestamp: () => new Date().toTimeString().slice(0, 8),
-    typeValue: (t) => scorm12Type(t),
+    typeValue: scorm12Type,
     resultLabels: { correct: 'correct', incorrect: 'wrong' },
     format: SCORM12_INTERACTION_FORMAT,
   },