Toware skuilder.json config standard (#897)

- **use skuilder.json for multi-course config**
- **move responibility for skuilder.json parsing to db**
- **add def for SkuilderManifest**

PR introduces `skuilder.json` general config for declaring course
contents and dependencies. Test usage in the docs site inlining skuilder
demo course.

Author: NiloCK

docs/.vitepress/theme/components/EmbeddedCourse.vue

@@ -86,13 +86,13 @@ interface Props {
 }
 
 const props = withDefaults(defineProps<Props>(), {
-  courseId: '2aeb8315ef78f3e89ca386992d00825b',
+  courseId: '@skuilder/hero-course',
   sessionTimeLimit: 10,
   sessionConfig: () => ({ likesConfetti: true })
 });
 
 // Data layer composable
-const { dataLayer, error: dataLayerError, isLoading: dataLayerLoading, initialize } = useStaticDataLayer([props.courseId]);
+const { dataLayer, error: dataLayerError, isLoading: dataLayerLoading, initialize } = useStaticDataLayer();
 
 // Component state
 const sessionPrepared = ref(false);
@@ -188,7 +188,7 @@ const initializeSession = async () => {
     
     // Ensure data layer is initialized
     if (!dataLayer.value) {
-      await initialize();
+      await initialize(props.courseId);
     }
     
     if (!dataLayer.value) {

docs/.vitepress/theme/components/HeroStudySession.vue

@@ -2,7 +2,7 @@
 <template>
   <div class="hero-study-session">
     <EmbeddedCourse
-      course-id="2aeb8315ef78f3e89ca386992d00825b"
+      course-id="@skuilder/hero-course"
       :session-time-limit="5"
       :session-config="{ likesConfetti: true }"
     />

docs/.vitepress/theme/composables/useStaticDataLayer.ts

@@ -6,6 +6,7 @@ import {
   type DataLayerConfig,
   initializeDataLayer 
 } from '@vue-skuilder/db';
+import { withBase } from 'vitepress';
 
 interface UseStaticDataLayerReturn {
   dataLayer: Ref<DataLayerProvider | null>;
@@ -14,98 +15,74 @@ interface UseStaticDataLayerReturn {
   initialize: () => Promise<void>;
 }
 
+// Cache the dataLayer promise to prevent re-initialization across components
+let dataLayerPromise: Promise<DataLayerProvider> | null = null;
+
 /**
- * Composable for initializing static data layer in VitePress docs context
- * Provides localStorage persistence and error handling
+ * Composable for initializing a static data layer in VitePress.
+ * It fetches the root skuilder.json manifest and passes it to the DataLayerProvider.
  */
-export function useStaticDataLayer(courseIds: string[] = ['2aeb8315ef78f3e89ca386992d00825b']): UseStaticDataLayerReturn {
+export function useStaticDataLayer(): UseStaticDataLayerReturn {
   const dataLayer = ref<DataLayerProvider | null>(null);
   const error = ref<Error | null>(null);
   const isLoading = ref(false);
 
-  // Calculate relative path to static-courses from current location
-  const getStaticCoursesPath = (): string => {
-    // Get current path depth to calculate relative path back to root
-    const currentPath = window.location.pathname;
-    const basePath = '/vue-skuilder/';
-    
-    // Remove base path to get relative path within docs
-    const relativePath = currentPath.replace(basePath, '');
-    const pathDepth = relativePath.split('/').filter(segment => segment.length > 0).length - 1;
-    
-    // Build relative path back to root: '../' repeated pathDepth times + 'static-courses'
-    const backToRoot = pathDepth > 0 ? '../'.repeat(pathDepth) : './';
-    const staticCoursesPath = `${backToRoot}static-courses`;
-    
-    console.log(`[useStaticDataLayer] Current path: ${currentPath}, depth: ${pathDepth}, static path: ${staticCoursesPath}`);
-    return staticCoursesPath;
-  };
-
   const initialize = async (): Promise<void> => {
     if (dataLayer.value) {
-      console.log('[useStaticDataLayer] Already initialized, skipping');
+      console.log('[useStaticDataLayer] Data layer already available, skipping initialization.');
+      return;
+    }
+
+    // If another component is already initializing, just wait for its promise
+    if (dataLayerPromise) {
+      console.log('[useStaticDataLayer] Initialization already in progress, awaiting result...');
+      isLoading.value = true;
+      try {
+        dataLayer.value = await dataLayerPromise;
+      } catch (e) {
+        error.value = e as Error;
+      } finally {
+        isLoading.value = false;
+      }
       return;
     }
 
     try {
       isLoading.value = true;
       error.value = null;
 
-      console.log('[useStaticDataLayer] Initializing with course IDs:', courseIds);
-
-      // Get the correct relative path to static-courses
-      const staticCoursesPath = getStaticCoursesPath();
+      console.log('[useStaticDataLayer] Starting data layer initialization...');
 
-      // Load individual manifests for each course (following testproject pattern)
-      const manifests: Record<string, any> = {};
-      
-      for (const courseId of courseIds) {
-        try {
-          console.log(`[useStaticDataLayer] Loading manifest for course: ${courseId}`);
-          const manifestResponse = await fetch(`${staticCoursesPath}/${courseId}/manifest.json`);
-          
-          if (!manifestResponse.ok) {
-            throw new Error(`Failed to load manifest: ${manifestResponse.status} ${manifestResponse.statusText}`);
-          }
-          
-          const manifest = await manifestResponse.json();
-          manifests[courseId] = manifest;
-          console.log(`[useStaticDataLayer] Loaded manifest for course ${courseId}:`, manifest.courseName || 'Unknown');
-          
-        } catch (manifestError) {
-          console.error(`[useStaticDataLayer] Failed to load manifest for course ${courseId}:`, manifestError);
-          throw new Error(`Could not load course manifest for ${courseId}: ${manifestError}`);
-        }
+      // 1. Fetch the root application manifest
+      const rootManifestUrl = withBase('/skuilder.json');
+      const rootManifestResponse = await fetch(rootManifestUrl);
+      if (!rootManifestResponse.ok) {
+        throw new Error(`Failed to fetch root manifest: ${rootManifestUrl}`);
       }
+      const rootManifest = await rootManifestResponse.json();
 
-      console.log('[useStaticDataLayer] All manifests loaded:', Object.keys(manifests));
-
-      // Configure static data layer (following testproject pattern)
+      // 2. Prepare the simplified config for the DataLayerProvider
       const config: DataLayerConfig = {
         type: 'static',
         options: {
-          staticContentPath: staticCoursesPath,
-          manifests,
-          COURSE_IDS: courseIds
+          rootManifest,
+          rootManifestUrl: new URL(rootManifestUrl, window.location.href).href
         }
       };
 
-      console.log('[useStaticDataLayer] Initializing data layer with config');
+      console.log('[useStaticDataLayer] Initializing data layer with root manifest.');
 
-      // Initialize the data layer
-      dataLayer.value = await initializeDataLayer(config);
+      // 3. Initialize the data layer and cache the promise
+      dataLayerPromise = initializeDataLayer(config);
+      dataLayer.value = await dataLayerPromise;
 
       console.log('[useStaticDataLayer] Data layer initialized successfully');
 
     } catch (e) {
       const err = e as Error;
       error.value = err;
+      dataLayerPromise = null; // Clear promise on failure
       console.error('[useStaticDataLayer] Failed to initialize data layer:', err);
-      console.error('[useStaticDataLayer] Error details:', {
-        message: err.message,
-        stack: err.stack,
-        courseIds,
-      });
     } finally {
       isLoading.value = false;
     }

docs/dbg/embedded-course-test.md

@@ -6,6 +6,15 @@ Test page for EmbeddedCourse component development and debugging.
 import EmbeddedCourse from '../.vitepress/theme/components/EmbeddedCourse.vue'
 </script>
 
-## EmbeddedCourse Component Test
+## Embedded "local" course
 
-<EmbeddedCourse course-id="2aeb8315ef78f3e89ca386992d00825b" :session-time-limit="5" />
+<EmbeddedCourse course-id="@skuilder/hero-course" :session-time-limit="5" />
+
+
+## Embedded "remote" course
+
+This is loaded from a static deployed course from another repo at https://patched-network.github.io/demo-chess
+
+NB: it is not running content for a chess course, but a repackaging of the golang course.
+
+<EmbeddedCourse course-id="@skuilder/external-test" :session-time-limit="5" />

docs/public/skuilder.json

@@ -0,0 +1,9 @@
+{
+  "name": "@skuilder/docs-site",
+  "version": "0.1.0",
+  "description": "The root manifest for the vue-skuilder documentation site.",
+  "dependencies": {
+    "@skuilder/hero-course": "/vue-skuilder/static-courses/2aeb8315ef78f3e89ca386992d00825b/skuilder.json",
+    "@skuilder/external-test": "https://patched-network.github.io/demo-chess/static-courses/2aeb8315ef78f3e89ca386992d00825b/skuilder.json"
+  }
+}

docs/public/static-courses/2aeb8315ef78f3e89ca386992d00825b/skuilder.json

@@ -0,0 +1,9 @@
+{
+  "name": "@skuilder/hero-course",
+  "version": "1.0.0",
+  "description": "The interactive course used in the VitePress hero section.",
+  "content": {
+    "type": "static",
+    "manifest": "./manifest.json"
+  }
+}

docs/skuilder.json.md

@@ -0,0 +1,58 @@
+
+# `skuilder.json` Manifest (WIP)
+
+The `skuilder.json` file is a declarative manifest used to define a Skuilder project or a composable content package (a "quilt"). It is inspired by `package.json` from the Node.js ecosystem, allowing content to be managed as packages with their own metadata and dependencies.
+
+## Current Usage (MVP)
+
+In the current implementation, `skuilder.json` enables the documentation site to load multiple courses from different locations using a runtime resolution strategy.
+
+There are two primary ways this file is used:
+
+### 1. Root Manifest (Aggregator)
+
+An application (like this docs site) has a root `skuilder.json` file that declares its content dependencies. The `dependencies` field maps a package name to the URL of its own `skuilder.json`.
+
+**Example: `/public/skuilder.json`**
+
+```json
+{
+  "name": "@skuilder/docs-site",
+  "version": "0.1.0",
+  "description": "The root manifest for the vue-skuilder documentation site.",
+  "dependencies": {
+    "@skuilder/hero-course": "/vue-skuilder/static-courses/2aeb8315ef78f3e89ca386992d00825b/skuilder.json",
+    "@skuilder/example-course-1": "https://patched-network.github.io/example-course-1/skuilder.json"
+  }
+}
+```
+
+### 2. Leaf Manifest (Content Package)
+
+A self-contained course (a "leaf" package) has its own `skuilder.json` that defines its metadata and points to its content manifest.
+
+**Example: A `skuilder.json` within a course directory**
+
+```json
+{
+  "name": "@skuilder/hero-course",
+  "version": "1.0.0",
+  "description": "The interactive course used in the VitePress hero section.",
+  "content": {
+    "type": "static",
+    "manifest": "./manifest.json"
+  }
+}
+```
+
+At runtime, the data layer starts by fetching the root manifest, then recursively fetches the manifest for each dependency to discover the location of the actual course content.
+
+## Roadmap
+
+This runtime resolution is the first step. The long-term vision is to create a more robust system analogous to modern package managers.
+
+-   **Build-Time Dependency Resolution:** A CLI command (e.g., `skuilder install`) will be introduced. This tool will read the root `skuilder.json` and resolve the entire dependency graph ahead of time.
+
+-   **Lock File Generation:** The resolution step will produce a `skuilder.lock.json` file. This file will contain a flat, deterministic list of all required course manifests and their absolute URLs. The runtime data layer will consume this simple lock file directly, resulting in faster and more reliable startup.
+
+-   **Registry Support:** Eventually, the system will support version-based dependencies (e.g., `"@skuilder/math-basics": "^1.2.0"`) which will be resolved against a central or private Skuilder package registry.

packages/db/src/impl/static/StaticDataLayerProvider.ts

@@ -1,3 +1,4 @@
+
 // packages/db/src/impl/static/StaticDataLayerProvider.ts
 
 import {
@@ -17,39 +18,78 @@ import { StaticCoursesDB } from './coursesDB';
 import { BaseUser } from '../common';
 import { NoOpSyncStrategy } from './NoOpSyncStrategy';
 
+
+interface SkuilderManifest {
+  name?: string;
+  version?: string;
+  description?: string;
+  dependencies?: Record<string, string>;
+}
+
 interface StaticDataLayerConfig {
-  staticContentPath: string;
   localStoragePrefix?: string;
-  manifests: Record<string, StaticCourseManifest>; // courseId -> manifest
+  rootManifest: SkuilderManifest; // The parsed root skuilder.json object
+  rootManifestUrl: string; // The absolute URL where the root manifest was found
 }
 
 export class StaticDataLayerProvider implements DataLayerProvider {
   private config: StaticDataLayerConfig;
   private initialized: boolean = false;
   private courseUnpackers: Map<string, StaticDataUnpacker> = new Map();
+  private manifests: Record<string, StaticCourseManifest> = {};
 
   constructor(config: Partial<StaticDataLayerConfig>) {
     this.config = {
-      staticContentPath: config.staticContentPath || '/static-courses',
       localStoragePrefix: config.localStoragePrefix || 'skuilder-static',
-      manifests: config.manifests || {},
+      rootManifest: config.rootManifest || { dependencies: {} },
+      rootManifestUrl: config.rootManifestUrl || '/',
     };
   }
 
+  private async resolveCourseDependencies(): Promise<void> {
+    logger.info('[StaticDataLayerProvider] Starting course dependency resolution...');
+    const rootManifest = this.config.rootManifest;
+
+    for (const [courseName, courseUrl] of Object.entries(rootManifest.dependencies || {})) {
+      try {
+        logger.debug(`[StaticDataLayerProvider] Resolving dependency: ${courseName} from ${courseUrl}`);
+        
+        const courseManifestUrl = new URL(courseUrl as string, this.config.rootManifestUrl).href;
+        const courseJsonResponse = await fetch(courseManifestUrl);
+        if (!courseJsonResponse.ok) {
+          throw new Error(`Failed to fetch course manifest for ${courseName}`);
+        }
+        const courseJson = await courseJsonResponse.json();
+
+        if (courseJson.content && courseJson.content.manifest) {
+          const baseUrl = new URL('.', courseManifestUrl).href;
+          const finalManifestUrl = new URL(courseJson.content.manifest, courseManifestUrl).href;
+
+          const finalManifestResponse = await fetch(finalManifestUrl);
+          if (!finalManifestResponse.ok) {
+            throw new Error(`Failed to fetch final content manifest for ${courseName} at ${finalManifestUrl}`);
+          }
+          const finalManifest = await finalManifestResponse.json();
+          
+          this.manifests[courseName] = finalManifest;
+          const unpacker = new StaticDataUnpacker(finalManifest, baseUrl);
+          this.courseUnpackers.set(courseName, unpacker);
+
+          logger.info(`[StaticDataLayerProvider] Successfully resolved and prepared course: ${courseName}`);
+        }
+      } catch (e) {
+        logger.error(`[StaticDataLayerProvider] Failed to resolve dependency ${courseName}:`, e);
+        // Continue to next dependency
+      }
+    }
+    logger.info('[StaticDataLayerProvider] Course dependency resolution complete.');
+  }
+
   async initialize(): Promise<void> {
     if (this.initialized) return;
 
     logger.info('Initializing static data layer provider');
-
-    // Load manifests for all courses
-    for (const [courseId, manifest] of Object.entries(this.config.manifests)) {
-      const unpacker = new StaticDataUnpacker(
-        manifest,
-        `${this.config.staticContentPath}/${courseId}`
-      );
-      this.courseUnpackers.set(courseId, unpacker);
-    }
-
+    await this.resolveCourseDependencies();
     this.initialized = true;
   }
 
@@ -67,14 +107,14 @@ export class StaticDataLayerProvider implements DataLayerProvider {
   getCourseDB(courseId: string): CourseDBInterface {
     const unpacker = this.courseUnpackers.get(courseId);
     if (!unpacker) {
-      throw new Error(`Course ${courseId} not found in static data`);
+      throw new Error(`Course ${courseId} not found or failed to initialize in static data layer.`);
     }
-    const manifest = this.config.manifests[courseId];
+    const manifest = this.manifests[courseId];
     return new StaticCourseDB(courseId, unpacker, this.getUserDB(), manifest);
   }
 
   getCoursesDB(): CoursesDBInterface {
-    return new StaticCoursesDB(this.config.manifests);
+    return new StaticCoursesDB(this.manifests);
   }
 
   async getClassroomDB(