tessera-learn 0.1.0 → 0.2.0

package/src/plugin/a11y/audit.ts

@@ -125,6 +125,7 @@ async function loadDeps(): Promise<
  */
 export async function runAudit(
   projectRoot: string,
+  workspaceRoot: string,
   options: AuditOptions = {},
 ): Promise<number> {
   const threshold: ImpactLevel = options.threshold ?? 'serious';
@@ -153,10 +154,14 @@ export async function runAudit(
   const { resolveTesseraConfig } = await import('../inline-config.js');
   // Carries tesseraPlugin() + the Svelte compiler; without it the plugin-less
   // build would silently produce a broken bundle (there is no vite.config.js).
-  const auditBaseConfig = await resolveTesseraConfig(projectRoot, {
-    command: 'build',
-    mode: 'production',
-  });
+  const auditBaseConfig = await resolveTesseraConfig(
+    projectRoot,
+    workspaceRoot,
+    {
+      command: 'build',
+      mode: 'production',
+    },
+  );
 
   // A throwaway web build, kept out of dist/ so a real LMS export is untouched.
   const auditDist = resolve(projectRoot, 'node_modules', '.tessera-a11y');

package/src/plugin/a11y-cli.ts

@@ -38,11 +38,15 @@ export function parseA11yArgs(argv: string[]): ParsedA11yArgs {
   return { ok: true, args };
 }
 
-export async function runA11y(argv: string[]): Promise<number> {
+export async function runA11y(
+  projectRoot: string,
+  workspaceRoot: string,
+  argv: string[],
+): Promise<number> {
   const parsed = parseA11yArgs(argv);
   if (!parsed.ok) {
     console.error(`[tessera a11y] ${parsed.error}`);
     return 1;
   }
-  return runAudit(process.cwd(), parsed.args);
+  return runAudit(projectRoot, workspaceRoot, parsed.args);
 }

package/src/plugin/build-commands.ts

@@ -1,8 +1,11 @@
 import { resolveTesseraConfig } from './inline-config.js';
 
-export async function runDev(projectRoot: string): Promise<number> {
+export async function runDev(
+  projectRoot: string,
+  workspaceRoot: string,
+): Promise<number> {
   const vite = await import('vite');
-  const config = await resolveTesseraConfig(projectRoot, {
+  const config = await resolveTesseraConfig(projectRoot, workspaceRoot, {
     command: 'serve',
     mode: 'development',
   });
@@ -14,9 +17,12 @@ export async function runDev(projectRoot: string): Promise<number> {
   return new Promise<number>(() => {});
 }
 
-export async function runBuild(projectRoot: string): Promise<number> {
+export async function runBuild(
+  projectRoot: string,
+  workspaceRoot: string,
+): Promise<number> {
   const vite = await import('vite');
-  const config = await resolveTesseraConfig(projectRoot, {
+  const config = await resolveTesseraConfig(projectRoot, workspaceRoot, {
     command: 'build',
     mode: 'production',
   });

package/src/plugin/cli.ts

@@ -1,44 +1,87 @@
 #!/usr/bin/env node
 import { runValidate } from './validate-cli.js';
 import { runA11y } from './a11y-cli.js';
+import { runNew } from './new-cli.js';
+import { runDuplicate } from './duplicate-cli.js';
+import { resolveCourse } from './course-root.js';
 
-const USAGE = `Usage: tessera <command> [options]
+const USAGE = `Usage: tessera <command> [course] [options]
 
 Commands:
-  dev                 Start the Vite dev server
-  export              Build and package the course for its LMS standard
-  validate            Fast static structure checks
-  a11y [options]      Runtime accessibility audit (builds + drives Playwright)
-  check [options]     Run validate, then a11y
+  new <name>                  Scaffold a new course into courses/<name>
+  duplicate <source> <new>    Copy courses/<source> to courses/<new>
+  dev       [course]          Start the Vite dev server
+  export    [course]          Build and package the course for its LMS standard
+  validate  [course]          Fast static structure checks
+  a11y      [course]          Runtime accessibility audit (builds + drives Playwright)
+  check     [course]          Run validate, then a11y
+
+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`;
 
-export async function main(argv: string[]): Promise<number> {
+// 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.
+export function splitCourseArg(rest: string[]): {
+  course?: string;
+  flags: string[];
+} {
+  if (rest.length > 0 && !rest[0].startsWith('-')) {
+    return { course: rest[0], flags: rest.slice(1) };
+  }
+  return { course: undefined, flags: rest };
+}
+
+export async function main(
+  argv: string[],
+  cwd: string = process.cwd(),
+): Promise<number> {
   const [sub, ...rest] = argv;
+
+  if (sub === 'new') return runNew(rest[0], cwd);
+  if (sub === 'duplicate') return runDuplicate(rest[0], rest[1], cwd);
+
   switch (sub) {
-    case 'dev': {
-      const { runDev } = await import('./build-commands.js');
-      return runDev(process.cwd());
-    }
-    case 'export': {
-      const { runBuild } = await import('./build-commands.js');
-      return runBuild(process.cwd());
-    }
+    case 'dev':
+    case 'export':
     case 'validate':
-      return runValidate(process.cwd());
     case 'a11y':
     case 'check': {
       if (rest.includes('--help') || rest.includes('-h')) {
         console.log(USAGE);
         return 0;
       }
-      if (sub === 'check') {
-        const validateCode = runValidate(process.cwd());
-        if (validateCode !== 0) return validateCode;
+      const { course, flags } = splitCourseArg(rest);
+      const resolved = resolveCourse(cwd, course);
+      if (!resolved.ok) {
+        console.error(`[tessera] ${resolved.error}`);
+        return 1;
       }
-      return runA11y(rest);
+      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':

package/src/plugin/course-root.ts

@@ -0,0 +1,98 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { validateProjectName } from './project-name.js';
+
+export interface ResolvedCourse {
+  ok: true;
+  courseRoot: string;
+  workspaceRoot: string;
+}
+
+export type ResolveResult = ResolvedCourse | { ok: false; error: string };
+
+function isDir(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isCourse(dir: string): boolean {
+  return existsSync(join(dir, 'course.config.js'));
+}
+
+// A workspace is the nearest ancestor holding a courses/ directory. The walk
+// includes the starting dir, so the workspace root resolves to itself.
+export function findWorkspaceRoot(cwd: string): string | null {
+  for (let dir = resolve(cwd); ; dir = dirname(dir)) {
+    if (isDir(join(dir, 'courses'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+  }
+}
+
+export function listCourses(workspaceRoot: string): string[] {
+  const coursesDir = join(workspaceRoot, 'courses');
+  try {
+    return readdirSync(coursesDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && isCourse(join(coursesDir, e.name)))
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+const NOT_A_WORKSPACE =
+  'Not inside a Tessera workspace — no `courses/` directory was found at or above the current directory.';
+
+function listHint(workspaceRoot: string): string {
+  const courses = listCourses(workspaceRoot);
+  if (courses.length === 0) {
+    return '\nNo courses found. Create one with `tessera new <name>`.';
+  }
+  return (
+    `\nAvailable courses:\n${courses.map((c) => `  ${c}`).join('\n')}` +
+    '\nName one (`tessera <command> <course>`) or cd into its folder.'
+  );
+}
+
+// A name argument always wins; otherwise the cwd must itself be a course. There
+// is deliberately no "single course → use it implicitly" rule, so a bare command
+// never changes meaning when a second course is added.
+export function resolveCourse(cwd: string, name?: string): ResolveResult {
+  const here = resolve(cwd);
+
+  if (name) {
+    const nameError = validateProjectName(name, 'the name');
+    if (nameError) {
+      return {
+        ok: false,
+        error: `Invalid course name "${name}" — ${nameError}.`,
+      };
+    }
+    const workspaceRoot = findWorkspaceRoot(here);
+    if (!workspaceRoot) return { ok: false, error: NOT_A_WORKSPACE };
+    const courseRoot = join(workspaceRoot, 'courses', name);
+    if (!isCourse(courseRoot)) {
+      return {
+        ok: false,
+        error: `Course "${name}" not found in courses/.${listHint(workspaceRoot)}`,
+      };
+    }
+    return { ok: true, courseRoot, workspaceRoot };
+  }
+
+  if (isCourse(here)) {
+    const workspaceRoot = findWorkspaceRoot(here) ?? dirname(dirname(here));
+    return { ok: true, courseRoot: here, workspaceRoot };
+  }
+
+  const workspaceRoot = findWorkspaceRoot(here);
+  if (!workspaceRoot) return { ok: false, error: NOT_A_WORKSPACE };
+  return {
+    ok: false,
+    error: `No course specified.${listHint(workspaceRoot)}`,
+  };
+}

package/src/plugin/duplicate-cli.ts

@@ -0,0 +1,74 @@
+import { cpSync, existsSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { resolveCourse } from './course-root.js';
+import { validateProjectName } from './project-name.js';
+
+const HELP =
+  'Usage: tessera duplicate <source> <new>\n\n' +
+  'Copy courses/<source>/ to courses/<new>/ within the current workspace.';
+
+// Generated/build artifacts that should never travel with a verbatim copy. The
+// a11y throwaway build and Vite's cache live under node_modules, so they're
+// already pruned by the node_modules skip; the rest are belt-and-suspenders.
+const SKIP = new Set(['node_modules', 'dist', 'a11y-report.json', '.vite']);
+
+function skip(srcPath: string): boolean {
+  const name = basename(srcPath);
+  return SKIP.has(name) || name.startsWith('.tessera');
+}
+
+// `tessera duplicate <source> <new>` — copy an existing course verbatim within
+// the current workspace. Unlike `new`, there is no template stamping: the JS
+// config (including its title) is copied untouched.
+export function runDuplicate(
+  source: string | undefined,
+  target: string | undefined,
+  cwd: string,
+): number {
+  if (
+    source === '--help' ||
+    source === '-h' ||
+    target === '--help' ||
+    target === '-h'
+  ) {
+    console.log(HELP);
+    return 0;
+  }
+  if (!source || !target) {
+    console.error('Usage: tessera duplicate <source> <new>');
+    return 1;
+  }
+
+  const nameError = validateProjectName(target, 'Course name');
+  if (nameError) {
+    console.error(`[tessera duplicate] ${nameError}`);
+    return 1;
+  }
+
+  const resolved = resolveCourse(cwd, source);
+  if (!resolved.ok) {
+    console.error(`[tessera duplicate] ${resolved.error}`);
+    return 1;
+  }
+  const { courseRoot: srcDir, workspaceRoot } = resolved;
+
+  const destDir = join(workspaceRoot, 'courses', target);
+  if (existsSync(destDir)) {
+    console.error(`[tessera duplicate] Course "${target}" already exists.`);
+    return 1;
+  }
+
+  cpSync(srcDir, destDir, {
+    recursive: true,
+    filter: (src) => src === srcDir || !skip(src),
+  });
+
+  const rel = relative(workspaceRoot, destDir);
+  const srcRel = relative(workspaceRoot, srcDir);
+  console.log(
+    `\nCreated ${rel} (duplicated from ${srcRel}).\n\n` +
+      `Remember to update the title in ${rel}/course.config.js.\n\n` +
+      `Next steps:\n  pnpm tessera dev ${target}\n`,
+  );
+  return 0;
+}

package/src/plugin/inline-config.ts

@@ -7,11 +7,21 @@ import { tesseraPlugin } from './index.js';
 // Base Vite config for every Tessera command (dev, export, a11y build).
 // configFile:false disables Vite's own discovery — there is no vite.config.js —
 // and tesseraPlugin() supplies the Svelte compiler, so this is the full plugin set.
-export function buildInlineConfig(projectRoot: string): InlineConfig {
+//
+// $shared points at the workspace-level design system, which lives outside the
+// per-course Vite root, so it is wired here (where workspaceRoot is known) rather
+// than next to $assets in the plugin. server.fs.allow must list workspaceRoot or
+// the dev server's fs.strict gate refuses to serve $shared files.
+export function buildInlineConfig(
+  projectRoot: string,
+  workspaceRoot: string,
+): InlineConfig {
   return {
     root: projectRoot,
     configFile: false,
     plugins: [tesseraPlugin()],
+    resolve: { alias: { $shared: resolve(workspaceRoot, 'shared') } },
+    server: { fs: { allow: [workspaceRoot] } },
   };
 }
 
@@ -34,10 +44,11 @@ export async function loadUserConfig(
 
 export async function resolveTesseraConfig(
   projectRoot: string,
+  workspaceRoot: string,
   env: ConfigEnv,
 ): Promise<InlineConfig> {
   const vite = await import('vite');
-  const base = buildInlineConfig(projectRoot);
+  const base = buildInlineConfig(projectRoot, workspaceRoot);
   const user = await loadUserConfig(projectRoot, env);
   return user ? vite.mergeConfig(base, user) : base;
 }

package/src/plugin/new-cli.ts

@@ -0,0 +1,51 @@
+import { existsSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { findWorkspaceRoot } from './course-root.js';
+import { validateProjectName, toTitleCase } from './project-name.js';
+import { copyTemplate } from './template-copy.js';
+import { resolvePackageRoot } from './package-root.js';
+
+// `tessera new <name>` — stamp a new course into courses/<name> inside the
+// current workspace. No install step: the workspace already owns the deps.
+export function runNew(name: string | undefined, cwd: string): number {
+  if (name === '--help' || name === '-h') {
+    console.log(
+      'Usage: tessera new <name>\n\n' +
+        'Scaffold a new course into courses/<name> inside the current workspace.',
+    );
+    return 0;
+  }
+  if (!name) {
+    console.error('Usage: tessera new <name>');
+    return 1;
+  }
+
+  const nameError = validateProjectName(name, 'Course name');
+  if (nameError) {
+    console.error(`[tessera new] ${nameError}`);
+    return 1;
+  }
+
+  const workspaceRoot = findWorkspaceRoot(resolve(cwd));
+  if (!workspaceRoot) {
+    console.error(
+      '[tessera new] Not inside a Tessera workspace — run this from a workspace (a directory with a `courses/` folder).',
+    );
+    return 1;
+  }
+
+  const courseDir = join(workspaceRoot, 'courses', name);
+  if (existsSync(courseDir)) {
+    console.error(`[tessera new] Course "${name}" already exists.`);
+    return 1;
+  }
+
+  const templateDir = join(resolvePackageRoot(), 'templates', 'course');
+  copyTemplate(templateDir, courseDir, {
+    PROJECT_TITLE: toTitleCase(name),
+  });
+
+  const rel = relative(workspaceRoot, courseDir);
+  console.log(`\nCreated ${rel}.\n\nNext steps:\n  pnpm tessera dev ${name}\n`);
+  return 0;
+}

package/src/plugin/project-name.ts

@@ -0,0 +1,29 @@
+// Pure, dependency-free helpers shared by the `tessera new` subcommand and the
+// `create-tessera` scaffolder. Kept import-free so create-tessera can bundle it
+// at build time without dragging in the rest of the plugin (vite, svelte, …).
+
+// npm package name rules: 1-214 chars, lowercase, must start with [a-z0-9],
+// allowed chars [a-z0-9._-], no leading dot or underscore.
+export function validateProjectName(
+  name: string,
+  label = 'Project name',
+): string | null {
+  if (!name) return `${label} is required`;
+  if (name.length > 214) return `${label} must be 214 characters or fewer`;
+  if (name !== name.toLowerCase()) return `${label} must be lowercase`;
+  if (!/^[a-z0-9]/.test(name)) {
+    return `${label} must start with a letter or digit`;
+  }
+  if (!/^[a-z0-9._-]+$/.test(name)) {
+    return `${label} may only contain lowercase letters, digits, "-", "_", and "."`;
+  }
+  return null;
+}
+
+export function toTitleCase(slug: string): string {
+  return slug
+    .split(/[-_.\s]+/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}

package/src/plugin/template-copy.ts

@@ -0,0 +1,43 @@
+import {
+  copyFileSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+// npm's tarball packing strips/renames leading-dot files, so templates store
+// them prefixed and we restore the dot on copy. (create-vite convention.)
+const RENAME: Record<string, string> = {
+  _gitignore: '.gitignore',
+  _gitkeep: '.gitkeep',
+};
+
+// Text files get token substitution; everything else is copied byte-for-byte.
+const TEXT = /\.(svelte|js|ts|json|css|md|html)$/;
+
+function applyTokens(s: string, tokens: Record<string, string>): string {
+  return s.replace(/__([A-Z_]+)__/g, (m, key) =>
+    key in tokens ? tokens[key] : m,
+  );
+}
+
+export function copyTemplate(
+  srcDir: string,
+  destDir: string,
+  tokens: Record<string, string>,
+): void {
+  mkdirSync(destDir, { recursive: true });
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    const src = join(srcDir, entry.name);
+    const dest = join(destDir, RENAME[entry.name] ?? entry.name);
+    if (entry.isDirectory()) {
+      copyTemplate(src, dest, tokens);
+    } else if (TEXT.test(entry.name)) {
+      writeFileSync(dest, applyTokens(readFileSync(src, 'utf-8'), tokens));
+    } else {
+      copyFileSync(src, dest);
+    }
+  }
+}

package/src/plugin/validate-cli.ts

@@ -24,7 +24,7 @@ export function runValidate(projectRoot: string): number {
     );
   }
   console.log(
-    '\x1b[2m[tessera] Static checks only. For a full runtime accessibility audit, run: tessera a11y\x1b[0m',
+    '\x1b[2m[tessera] Static checks only. For a full runtime accessibility audit, run: pnpm exec tessera a11y\x1b[0m',
   );
   return 0;
 }

package/templates/course/course.config.js

@@ -0,0 +1,11 @@
+export default {
+  title: '__PROJECT_TITLE__',
+  language: 'en',
+  navigation: { mode: 'free' },
+  completion: { mode: 'percentage', percentageThreshold: 100 },
+  scoring: { passingScore: 70 },
+  branding: {
+    primaryColor: '#0066cc',
+  },
+  export: { standard: 'web' },
+};

package/templates/course/layout.svelte

@@ -0,0 +1,116 @@
+<script>
+  import '$shared/tokens.css';
+  import { useNavigation, useProgress } from 'tessera-learn';
+
+  let { page } = $props();
+  const nav = useNavigation();
+  const progress = useProgress();
+</script>
+
+<div class="course">
+  <header>
+    <h1>__PROJECT_TITLE__</h1>
+    <span class="progress"
+      >{progress.visitedPages.size} / {nav.pages.length}</span
+    >
+  </header>
+
+  <main>
+    {@render page()}
+  </main>
+
+  <footer>
+    <button
+      class="nav-btn"
+      disabled={!nav.canGoPrev}
+      onclick={() => nav.prev()}
+    >
+      ← Previous
+    </button>
+    <button
+      class="nav-btn nav-btn--primary"
+      disabled={!nav.canGoNext}
+      onclick={() => nav.next()}
+    >
+      Next →
+    </button>
+  </footer>
+</div>
+
+<style>
+  .course {
+    display: flex;
+    flex-direction: column;
+    min-height: 100vh;
+  }
+
+  header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--tessera-spacing-md);
+    padding: var(--tessera-spacing-md) var(--tessera-spacing-xl);
+    border-bottom: 1px solid var(--tessera-border);
+  }
+
+  header h1 {
+    margin: 0;
+    font-size: 1.125rem;
+  }
+
+  .progress {
+    flex: none;
+    padding: 0.15rem 0.6rem;
+    border-radius: 999px;
+    background: var(--tessera-bg-secondary);
+    color: var(--tessera-text-light);
+    font-size: 0.875rem;
+  }
+
+  main {
+    flex: 1;
+    width: 100%;
+    max-width: var(--tessera-content-max-width);
+    margin: 0 auto;
+    padding: var(--tessera-spacing-xl);
+  }
+
+  footer {
+    display: flex;
+    justify-content: space-between;
+    gap: var(--tessera-spacing-md);
+    padding: var(--tessera-spacing-md) var(--tessera-spacing-xl);
+    border-top: 1px solid var(--tessera-border);
+  }
+
+  .nav-btn {
+    padding: 0.5rem 1rem;
+    border: 1px solid var(--tessera-border);
+    border-radius: 6px;
+    background: var(--tessera-bg);
+    color: var(--tessera-text);
+    cursor: pointer;
+    transition:
+      background var(--tessera-transition-fast),
+      border-color var(--tessera-transition-fast);
+  }
+
+  .nav-btn:hover:not(:disabled) {
+    background: var(--tessera-bg-secondary);
+  }
+
+  .nav-btn--primary {
+    border-color: transparent;
+    background: var(--tessera-primary);
+    color: #fff;
+  }
+
+  .nav-btn--primary:hover:not(:disabled) {
+    background: var(--tessera-primary-dark);
+  }
+
+  .nav-btn:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+</style>

package/templates/course/pages/01-getting-started/01-welcome/_meta.js

@@ -0,0 +1 @@
+export default { title: 'Welcome', pages: ['welcome'] };

package/templates/course/pages/01-getting-started/01-welcome/welcome.svelte

@@ -0,0 +1,19 @@
+<script module>
+  export const pageConfig = { title: 'Welcome' };
+</script>
+
+<script>
+  import Button from '$shared/Button.svelte';
+</script>
+
+<h1>Welcome to __PROJECT_TITLE__</h1>
+
+<p>This is a basic demo page of your Tessera course.</p>
+
+<p>
+  Point your agent to <code>AGENTS.md</code> at the workspace root for the
+  authoring guide. The button below is imported from the workspace design system
+  via <code>$shared</code>.
+</p>
+
+<Button>A shared button</Button>

package/templates/course/pages/01-getting-started/_meta.js

@@ -0,0 +1 @@
+export default { title: 'Getting Started' };