visionos-monorepo 0.1.0

package/server/src/routes/progress.ts

@@ -0,0 +1,105 @@
+import { Router } from "express";
+import {
+  LEARNING_TRACKS,
+  type LearnerIdentity,
+  type UpsertLearningProgressRequest
+} from "../../../shared/src/index.js";
+import {
+  AccountStoreError,
+  bearerTokenFromHeader,
+  type AccountStore
+} from "../features/accounts/accountStore.js";
+
+export function createProgressRouter(
+  accountStore: AccountStore | null,
+  getCurrentUser?: () => Promise<LearnerIdentity | null> | LearnerIdentity | null,
+  getProgress?: (userId: string) => Promise<any[]> | any[],
+  upsertProgress?: (userId: string, input: UpsertLearningProgressRequest) => Promise<any> | any
+) {
+  const router = Router();
+
+  async function resolveUser(authorization: string | undefined) {
+    const token = bearerTokenFromHeader(authorization);
+
+    if (token && accountStore) {
+      const user = await accountStore.getUserFromToken(token);
+      if (user) {
+        return user;
+      }
+      throw new AccountStoreError("Your session is invalid or expired. Sign in again.", 401);
+    }
+
+    if (getCurrentUser) {
+      const user = await getCurrentUser();
+      if (user) {
+        return user;
+      }
+    }
+
+    throw new AccountStoreError("Sign in before accessing progress.", 401);
+  }
+
+  router.get("/", async (req, res, next) => {
+    try {
+      const user = await resolveUser(req.header("authorization"));
+      
+      let progress;
+      if (getProgress) {
+        progress = await getProgress(user.userId);
+      } else {
+        const store = requireAccountStore(accountStore);
+        progress = await store.getProgress(user.userId);
+      }
+
+      return res.status(200).json({ progress });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  router.put("/", async (req, res, next) => {
+    try {
+      const user = await resolveUser(req.header("authorization"));
+      const body = req.body as Partial<UpsertLearningProgressRequest>;
+
+      if (!body.trackId || !LEARNING_TRACKS.some((track) => track.id === body.trackId)) {
+        return res.status(400).json({
+          message: "A valid learning track is required to save progress."
+        });
+      }
+
+      let progress;
+      if (upsertProgress) {
+        progress = await upsertProgress(user.userId, {
+          trackId: body.trackId,
+          completedLessonIds: body.completedLessonIds,
+          completedStepIds: body.completedStepIds,
+          currentLessonId: body.currentLessonId
+        });
+      } else {
+        const store = requireAccountStore(accountStore);
+        progress = await store.upsertProgress(user.userId, {
+          trackId: body.trackId,
+          completedLessonIds: body.completedLessonIds,
+          completedStepIds: body.completedStepIds,
+          currentLessonId: body.currentLessonId
+        });
+      }
+
+      return res.status(200).json({ progress });
+    } catch (error) {
+      return next(error);
+    }
+  });
+
+  return router;
+}
+
+function requireAccountStore(accountStore: AccountStore | null) {
+  if (!accountStore) {
+    throw new AccountStoreError("MongoDB account storage is not configured. Set MONGODB_URI first.", 503);
+  }
+
+  return accountStore;
+}
+

package/server/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": [
+      "ES2022"
+    ],
+    "types": [
+      "node"
+    ],
+    "noEmit": true
+  },
+  "include": [
+    "src/**/*.ts",
+    "../shared/src/**/*.ts"
+  ]
+}
+

package/shared/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@visionos/shared",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "lint": "tsc --noEmit -p tsconfig.json"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.3"
+  }
+}
+

package/shared/src/index.ts

@@ -0,0 +1,455 @@
+export const APP_NAME = "VisionOS";
+export const APP_VERSION = "0.1.0";
+
+export type LearningTrackId = string;
+
+export interface LearningTrack {
+  id: LearningTrackId;
+  label: string;
+  description: string;
+  creatorId?: string;
+  createdAt?: string;
+}
+
+export interface LearnerIdentity {
+  userId: string;
+  name: string;
+  email: string;
+}
+
+export interface VisionOsUserProfile extends LearnerIdentity {
+  sessionId?: string;
+  trackId?: LearningTrackId;
+  authenticatedAt?: string;
+}
+
+export type AccountAuthMode = "login" | "register";
+
+export interface AccountAuthRequest {
+  email: string;
+  password: string;
+  name?: string;
+}
+
+export interface GoogleAuthRequest {
+  credential: string;
+}
+
+export interface AccountUser extends LearnerIdentity {
+  createdAt: string;
+}
+
+export interface AccountAuthResponse {
+  user: AccountUser;
+  token: string;
+}
+
+export type CliAuthSessionStatus = "pending" | "authenticated" | "expired";
+
+export interface CliAuthSession {
+  sessionId: string;
+  trackId: LearningTrackId;
+  status: CliAuthSessionStatus;
+  createdAt: string;
+  expiresAt: string;
+  authenticatedAt?: string;
+  accountToken?: string;
+  learner?: LearnerIdentity;
+}
+
+export interface CliAuthSessionEnvelope {
+  session: CliAuthSession;
+  auth?: AccountAuthResponse;
+}
+
+export interface CreateCliAuthSessionRequest {
+  trackId: LearningTrackId;
+}
+
+export interface CreateCliAuthSessionResponse extends CliAuthSessionEnvelope {
+  browserUrl: string;
+  pollIntervalMs: number;
+}
+
+export interface CompleteCliAuthSessionRequest {
+  mode: AccountAuthMode;
+  learnerName?: string;
+  learnerEmail: string;
+  password: string;
+}
+
+export interface VisionOsUserInfoResponse {
+  user: VisionOsUserProfile | null;
+}
+
+export interface LearningProgress {
+  userId: string;
+  trackId: LearningTrackId;
+  completedLessonIds: string[];
+  completedStepIds: string[];
+  currentLessonId?: string;
+  updatedAt: string;
+}
+
+export interface LearningProgressResponse {
+  progress: LearningProgress[];
+}
+
+export interface UpsertLearningProgressRequest {
+  trackId: LearningTrackId;
+  completedLessonIds?: string[];
+  completedStepIds?: string[];
+  currentLessonId?: string;
+}
+
+export interface VisionOsRuntimeInfo {
+  appUrl: string;
+  apiBaseUrl: string;
+  mainAppUrl?: string;
+  mode: "development" | "embedded";
+}
+
+export interface VisionOsRuntimeInfoResponse {
+  runtime: VisionOsRuntimeInfo;
+}
+
+export type LessonDifficulty = "beginner" | "intermediate" | "advanced";
+
+export interface LessonStep {
+  id: string;
+  title: string;
+  objective: string;
+  command: string;
+  explanation: string;
+  validationType?: "syntax" | "file-exists" | "file-contains";
+  validationPath?: string;
+  validationContent?: string;
+}
+
+export interface LearningLesson {
+  id: string;
+  trackId: LearningTrackId;
+  title: string;
+  difficulty: LessonDifficulty;
+  summary: string;
+  estimatedMinutes: number;
+  steps: LessonStep[];
+  creatorId?: string;
+  createdAt?: string;
+}
+
+export const CLI_AUTH_POLL_INTERVAL_MS = 1_500;
+export const CLI_AUTH_SESSION_TTL_MS = 10 * 60 * 1_000;
+
+export const LEARNING_TRACKS: LearningTrack[] = [
+  {
+    id: "git",
+    label: "Git",
+    description: "Learn branching, commits, rebasing, and collaboration commands."
+  },
+  {
+    id: "linux",
+    label: "Linux",
+    description: "Build confidence with filesystem navigation, permissions, and shell basics."
+  },
+  {
+    id: "react-cli",
+    label: "React CLI",
+    description: "Practice project scaffolding, package scripts, and frontend workflows."
+  },
+  {
+    id: "os-commands",
+    label: "OS Commands",
+    description: "Train with practical day-to-day terminal commands across common environments."
+  }
+];
+
+export const BEGINNER_LESSONS: LearningLesson[] = [
+  {
+    id: "git-first-repo",
+    trackId: "git",
+    title: "Your First Git Repository",
+    difficulty: "beginner",
+    summary: "Create a repository, inspect status, and make a first commit.",
+    estimatedMinutes: 12,
+    steps: [
+      {
+        id: "git-init",
+        title: "Initialize the repository",
+        objective: "Create Git tracking in the current project folder.",
+        command: "git init",
+        explanation: "This creates the hidden .git directory where Git stores repository history."
+      },
+      {
+        id: "git-status",
+        title: "Check the working tree",
+        objective: "See which files are untracked, staged, or modified.",
+        command: "git status",
+        explanation: "Status is the safest command to run before and after every Git action."
+      },
+      {
+        id: "git-first-commit",
+        title: "Create a first snapshot",
+        objective: "Stage files and save them in history.",
+        command: "git add . && git commit -m \"Initial commit\"",
+        explanation: "Staging chooses what goes into the next commit; commit records the snapshot."
+      }
+    ]
+  },
+  {
+    id: "git-branch-basics",
+    trackId: "git",
+    title: "Branch Basics",
+    difficulty: "beginner",
+    summary: "Create a branch, switch to it, and inspect branch state.",
+    estimatedMinutes: 10,
+    steps: [
+      {
+        id: "git-branch-list",
+        title: "List branches",
+        objective: "See the branches in a repository.",
+        command: "git branch",
+        explanation: "The current branch is marked with an asterisk."
+      },
+      {
+        id: "git-switch-create",
+        title: "Create and switch",
+        objective: "Start isolated work on a new branch.",
+        command: "git switch -c feature/readme-update",
+        explanation: "A branch lets you work without changing the main line until you merge."
+      },
+      {
+        id: "git-log-short",
+        title: "Read recent history",
+        objective: "Inspect compact commit history.",
+        command: "git log --oneline",
+        explanation: "Short logs make it easier to understand recent snapshots."
+      }
+    ]
+  },
+  {
+    id: "git-github-connect",
+    trackId: "git",
+    title: "Connecting to GitHub",
+    difficulty: "beginner",
+    summary: "Rename your main branch, link your terminal to GitHub, and push your first commit.",
+    estimatedMinutes: 15,
+    steps: [
+      {
+        id: "git-branch-main",
+        title: "Rename branch to main",
+        objective: "Set the local branch name to 'main' for compatibility with GitHub.",
+        command: "git branch -M main",
+        explanation: "GitHub expects the primary branch of a repository to be named 'main' rather than 'master' or 'temp'."
+      },
+      {
+        id: "git-github-remote",
+        title: "Create GitHub repository and remote",
+        objective: "Create a GitHub repository from your terminal and link it as 'origin'.",
+        command: "gh repo create my-vision-project --public --source=. --remote=origin",
+        explanation: "This uses the GitHub CLI to create a public cloud repository named 'my-vision-project' and hooks it to your local files as 'origin'. Alternatively, if you don't have GitHub CLI installed, you can create a repository at github.com and link it using: git remote add origin https://github.com/YOUR_USERNAME/my-vision-project.git"
+      },
+      {
+        id: "git-github-push",
+        title: "Push your first commit",
+        objective: "Upload your local code snapshots to GitHub.",
+        command: "git push -u origin main",
+        explanation: "The -u flag sets your upstream, linking local main to remote main. Future pushes only need 'git push'!"
+      }
+    ]
+  },
+  {
+    id: "linux-navigation",
+    trackId: "linux",
+    title: "Terminal Navigation",
+    difficulty: "beginner",
+    summary: "Move through folders and inspect the filesystem confidently.",
+    estimatedMinutes: 10,
+    steps: [
+      {
+        id: "linux-pwd",
+        title: "Print your location",
+        objective: "Show the absolute path of the current directory.",
+        command: "pwd",
+        explanation: "pwd tells you exactly where your shell is operating."
+      },
+      {
+        id: "linux-ls",
+        title: "List files",
+        objective: "View visible and hidden files with details.",
+        command: "ls -la",
+        explanation: "The -l flag shows details; -a includes hidden dotfiles."
+      },
+      {
+        id: "linux-cd",
+        title: "Change directory",
+        objective: "Move into a folder and back out.",
+        command: "cd ..",
+        explanation: "Two dots mean the parent directory."
+      }
+    ]
+  },
+  {
+    id: "linux-files",
+    trackId: "linux",
+    title: "Create And Read Files",
+    difficulty: "beginner",
+    summary: "Create folders, write text, and read file contents.",
+    estimatedMinutes: 12,
+    steps: [
+      {
+        id: "linux-mkdir",
+        title: "Create a folder",
+        objective: "Make a new practice directory.",
+        command: "mkdir practice",
+        explanation: "mkdir creates a directory when it does not already exist."
+      },
+      {
+        id: "linux-echo-file",
+        title: "Write a small file",
+        objective: "Redirect text into a file.",
+        command: "echo \"hello terminal\" > practice/hello.txt",
+        explanation: "The > operator writes command output into a file."
+      },
+      {
+        id: "linux-cat",
+        title: "Read file contents",
+        objective: "Print a file to the terminal.",
+        command: "cat practice/hello.txt",
+        explanation: "cat is useful for quick inspection of small text files."
+      }
+    ]
+  },
+  {
+    id: "react-cli-scaffold",
+    trackId: "react-cli",
+    title: "React Project Commands",
+    difficulty: "beginner",
+    summary: "Understand the commands used to create and run a React app.",
+    estimatedMinutes: 12,
+    steps: [
+      {
+        id: "react-create",
+        title: "Create a Vite React app",
+        objective: "Scaffold a React project from the terminal.",
+        command: "npm create vite@latest my-app -- --template react",
+        explanation: "Vite creates a fast local React project with sensible defaults."
+      },
+      {
+        id: "react-install",
+        title: "Install dependencies",
+        objective: "Download the packages required by the app.",
+        command: "cd my-app && npm install",
+        explanation: "npm install reads package.json and creates node_modules."
+      },
+      {
+        id: "react-dev",
+        title: "Start development server",
+        objective: "Run the app locally for development.",
+        command: "npm run dev",
+        explanation: "The dev script starts Vite with hot reloading."
+      }
+    ]
+  },
+  {
+    id: "react-cli-package-scripts",
+    trackId: "react-cli",
+    title: "Package Script Basics",
+    difficulty: "beginner",
+    summary: "Inspect and run common npm scripts in a frontend project.",
+    estimatedMinutes: 10,
+    steps: [
+      {
+        id: "react-scripts-list",
+        title: "List scripts",
+        objective: "See available project commands.",
+        command: "npm run",
+        explanation: "npm run without a script name lists scripts from package.json."
+      },
+      {
+        id: "react-lint",
+        title: "Run checks",
+        objective: "Execute the project's lint or type-check script.",
+        command: "npm run lint",
+        explanation: "Linting catches mistakes before they reach the browser."
+      },
+      {
+        id: "react-build",
+        title: "Create production build",
+        objective: "Compile optimized assets.",
+        command: "npm run build",
+        explanation: "Build output is what gets deployed to static hosting."
+      }
+    ]
+  },
+  {
+    id: "os-process-basics",
+    trackId: "os-commands",
+    title: "Processes And Ports",
+    difficulty: "beginner",
+    summary: "Inspect running commands and understand local ports.",
+    estimatedMinutes: 10,
+    steps: [
+      {
+        id: "os-ps",
+        title: "List processes",
+        objective: "Show running processes for your user.",
+        command: "ps",
+        explanation: "Processes are programs currently running on your machine."
+      },
+      {
+        id: "os-lsof-port",
+        title: "Check a local port",
+        objective: "Find what is listening on a development port.",
+        command: "lsof -nP -iTCP:3000 -sTCP:LISTEN",
+        explanation: "This helps diagnose why a dev server port is unavailable."
+      },
+      {
+        id: "os-kill",
+        title: "Stop a process",
+        objective: "Terminate a process by PID.",
+        command: "kill <pid>",
+        explanation: "Use kill carefully after confirming the PID belongs to the process you intend to stop."
+      }
+    ]
+  },
+  {
+    id: "os-network-basics",
+    trackId: "os-commands",
+    title: "Network Checks",
+    difficulty: "beginner",
+    summary: "Use common commands to inspect connectivity and HTTP responses.",
+    estimatedMinutes: 10,
+    steps: [
+      {
+        id: "os-ping",
+        title: "Check reachability",
+        objective: "Send a small network probe.",
+        command: "ping example.com",
+        explanation: "ping helps check whether a host can be reached."
+      },
+      {
+        id: "os-curl-head",
+        title: "Inspect response headers",
+        objective: "Fetch only HTTP headers from a URL.",
+        command: "curl -I https://example.com",
+        explanation: "Headers reveal status codes, cache rules, and server metadata."
+      },
+      {
+        id: "os-dns",
+        title: "Resolve a hostname",
+        objective: "Look up DNS records for a domain.",
+        command: "nslookup example.com",
+        explanation: "DNS resolution maps names to network addresses."
+      }
+    ]
+  }
+];
+
+export function getLessonsForTrack(trackId: LearningTrackId) {
+  return BEGINNER_LESSONS.filter((lesson) => lesson.trackId === trackId);
+}
+
+export function getLessonById(lessonId: string) {
+  return BEGINNER_LESSONS.find((lesson) => lesson.id === lessonId);
+}

package/shared/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": [
+      "ES2022"
+    ],
+    "declaration": true,
+    "noEmit": true
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}
+

package/tsconfig.base.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true
+  }
+}
+