visionos-monorepo 0.1.0

package/cli/src/lib/lessonRunner.ts

@@ -0,0 +1,381 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import chalk from "chalk";
+import inquirer from "inquirer";
+import {
+  type LearningLesson,
+  type LearningProgress,
+  type UpsertLearningProgressRequest
+} from "../../../shared/src/index.js";
+import { readUserProfile } from "./localState.js";
+import { getRemoteProgress, syncProgress } from "./progress.js";
+import { validateStep } from "./validator.js";
+
+const execAsync = promisify(exec);
+
+async function runSystemCommand(command: string, cwd: string): Promise<{ stdout: string; stderr: string; code: number }> {
+  try {
+    const { stdout, stderr } = await execAsync(command, { cwd });
+    return { stdout, stderr, code: 0 };
+  } catch (error: any) {
+    return {
+      stdout: error.stdout ?? "",
+      stderr: error.stderr ?? error.message ?? "",
+      code: error.code ?? 1
+    };
+  }
+}
+
+
+const sandboxBaseDir = path.join(os.homedir(), ".visionos", "sandbox");
+
+// Steps that do not leave a physical filesystem footprint.
+// Learners will be asked to type the command they ran to verify its syntax.
+const syntaxOnlyStepIds = new Set([
+  "git-branch-list",
+  "git-log-short",
+  "linux-pwd",
+  "linux-ls",
+  "linux-cd",
+  "linux-cat",
+  "react-dev",
+  "react-scripts-list",
+  "react-lint",
+  "os-ps",
+  "os-lsof-port",
+  "os-kill",
+  "os-ping",
+  "os-curl-head",
+  "os-dns"
+]);
+
+function padString(label: string, text: string, width: number): string {
+  const plainLabel = label;
+  const plainText = text;
+  const paddingLength = Math.max(0, width - 4 - plainLabel.length - plainText.length);
+  return chalk.cyan("│ ") + chalk.white.bold(plainLabel) + chalk.green(plainText) + " ".repeat(paddingLength) + chalk.cyan(" │");
+}
+
+function wrapText(text: string, maxWidth: number): string[] {
+  const words = text.split(" ");
+  const lines: string[] = [];
+  let currentLine = "";
+
+  for (const word of words) {
+    if ((currentLine + " " + word).trim().length <= maxWidth) {
+      currentLine = (currentLine + " " + word).trim();
+    } else {
+      if (currentLine) lines.push(currentLine);
+      currentLine = word;
+    }
+  }
+  if (currentLine) lines.push(currentLine);
+  return lines;
+}
+
+function printStepBox(step: { title: string; objective: string; explanation: string }, index: number, total: number) {
+  const width = 76;
+  console.log(chalk.cyan(`\n┌─ STEP [${String(index + 1).padStart(2, "0")}/${String(total).padStart(2, "0")}] ` + "─".repeat(width - 15) + "┐"));
+  console.log(padString("Title: ", step.title, width));
+  console.log(padString("Goal:  ", step.objective, width));
+  console.log(chalk.cyan(`├` + "─".repeat(width - 2) + `┤`));
+  
+  const maxTextWidth = width - 6;
+  const wrappedExplanation = wrapText(step.explanation, maxTextWidth);
+  for (const line of wrappedExplanation) {
+    console.log(chalk.cyan("│ ") + chalk.gray(line.padEnd(width - 4)) + chalk.cyan(" │"));
+  }
+  console.log(chalk.cyan(`└` + "─".repeat(width - 2) + `┘`));
+}
+
+function printCompletionBadge(lessonTitle: string) {
+  console.log(chalk.yellow.bold(`
+  ┌────────────────────────────────────────────────────────────┐
+  │                   LESSON COMPLETED                         │
+  │                                                            │
+  │   Congratulations! You have completed:                     │
+  │   "${lessonTitle.slice(0, 48).padEnd(48)}" │
+  │                                                            │
+  │   Your achievements have been synced with the dashboard.   │
+  └────────────────────────────────────────────────────────────┘
+  `));
+}
+
+export async function runLessonInteractive(lesson: LearningLesson, apiBaseUrl: string) {
+  const user = await readUserProfile();
+  if (!user) {
+    console.log(chalk.yellow("No signed-in profile found. Run `visionos start` to authenticate first."));
+    return;
+  }
+
+  console.log(chalk.cyan.bold(`\nEntering Interactive Sandbox Lesson Runner...`));
+
+  // 1. Prompt user to choose between default isolated sandbox or custom directory
+  const { workspaceOption } = await inquirer.prompt<{ workspaceOption: "default" | "custom" }>([
+    {
+      type: "list",
+      name: "workspaceOption",
+      message: "Choose your practice workspace directory:",
+      choices: [
+        { name: "Default isolated sandbox (cleaned automatically)", value: "default" },
+        { name: "Custom directory (work in your own familiar folder)", value: "custom" }
+      ]
+    }
+  ]);
+
+  let sandboxDir = path.join(sandboxBaseDir, lesson.id);
+
+  if (workspaceOption === "custom") {
+    const { customPath } = await inquirer.prompt<{ customPath: string }>([
+      {
+        type: "input",
+        name: "customPath",
+        message: "Enter the absolute path to your custom workspace folder:",
+        validate: async (val: string) => {
+          const trimmed = val.trim();
+          if (!trimmed) {
+            return "Path cannot be empty.";
+          }
+          const p = path.resolve(trimmed.replace(/^~/, os.homedir()));
+          try {
+            const stat = await fs.stat(p);
+            if (!stat.isDirectory()) {
+              return "Path exists but is not a directory.";
+            }
+            return true;
+          } catch {
+            // Try to create it
+            try {
+              await fs.mkdir(p, { recursive: true });
+              return true;
+            } catch {
+              return "Invalid path or unable to create directory.";
+            }
+          }
+        }
+      }
+    ]);
+    sandboxDir = path.resolve(customPath.trim().replace(/^~/, os.homedir()));
+  } else {
+    // Default isolated sandbox: clean and recreate
+    try {
+      await fs.rm(sandboxDir, { recursive: true, force: true });
+      await fs.mkdir(sandboxDir, { recursive: true });
+    } catch (error) {
+      console.error(chalk.red(`Unable to initialize default sandbox folder: ${sandboxDir}`));
+      return;
+    }
+  }
+
+  console.log(chalk.gray(`\nWorkspace: ${sandboxDir}`));
+  console.log(chalk.gray("Open a separate terminal window and operate inside the workspace directory."));
+  if (workspaceOption === "custom") {
+    console.log(chalk.yellow("Safety Notice: Your custom directory files will NEVER be cleaned or deleted."));
+  }
+
+  // 2. Fetch existing progress
+  let completedStepIds: string[] = [];
+  let completedLessonIds: string[] = [];
+
+  try {
+    const remoteRes = await getRemoteProgress(apiBaseUrl);
+    const existing = remoteRes?.progress?.find((p) => p.trackId === lesson.trackId);
+    if (existing) {
+      completedStepIds = existing.completedStepIds ?? [];
+      completedLessonIds = existing.completedLessonIds ?? [];
+    }
+  } catch (e) {
+    // Ignore fetch errors; proceed offline
+  }
+
+  // 3. Step execution & validation loop
+  let stepIndex = 0;
+  const totalSteps = lesson.steps.length;
+
+  while (stepIndex < totalSteps) {
+    const step = lesson.steps[stepIndex];
+    printStepBox(step, stepIndex, totalSteps);
+    
+    console.log(chalk.yellow(`\nTarget Command: ${step.command}`));
+    console.log(chalk.cyan(`👉 Workspace Path: ${sandboxDir}`));
+    console.log(chalk.gray(`   To practice, open a SEPARATE terminal tab/window and run:`));
+    console.log(chalk.green(`   cd ${sandboxDir} && ${step.command}`));
+    console.log("");
+
+    const { action } = await inquirer.prompt<{ action: "verify" | "explain" | "skip" | "exit" }>([
+      {
+        type: "list",
+        name: "action",
+        message: "Select your action:",
+        choices: [
+          { name: "Verify my command (Check if I did it correctly)", value: "verify" },
+          { name: "Show expected command info again", value: "explain" },
+          { name: "Skip this step", value: "skip" },
+          { name: "Exit lesson", value: "exit" }
+        ]
+      }
+    ]);
+
+    if (action === "exit") {
+      console.log(chalk.cyan("Exiting lesson. Your current progress has been saved."));
+      return;
+    }
+
+    if (action === "skip") {
+      stepIndex++;
+      continue;
+    }
+
+    if (action === "explain") {
+      continue; // Displays step info again
+    }
+
+    // 4. Verification routing
+    let typedCommand = "";
+    
+    // If syntax-only, prompt learner to type the command they ran
+    if (syntaxOnlyStepIds.has(step.id)) {
+      const { userTyped } = await inquirer.prompt<{ userTyped: string }>([
+        {
+          type: "input",
+          name: "userTyped",
+          message: "Enter the command you ran to verify its syntax:",
+          validate: (val: string) => val.trim().length > 0 || "Command cannot be empty."
+        }
+      ]);
+      typedCommand = userTyped;
+    }
+
+    console.log(chalk.gray(`\nVerifying state inside workspace: ${sandboxDir}...`));
+
+    let systemStdout = "";
+    let systemStderr = "";
+
+    // 1. Run actual command for syntax-only steps to capture system output
+    if (syntaxOnlyStepIds.has(step.id) && typedCommand) {
+      const result = await runSystemCommand(typedCommand, sandboxDir);
+      systemStdout = result.stdout;
+      systemStderr = result.stderr;
+
+      console.log(chalk.gray(`----------------------------------------`));
+      console.log(chalk.yellow(`💻 System Output for: `) + chalk.cyan(typedCommand));
+      if (systemStdout.trim()) {
+        console.log(chalk.green(systemStdout.trim()));
+      }
+      if (systemStderr.trim()) {
+        console.log(chalk.red(systemStderr.trim()));
+      }
+      if (!systemStdout.trim() && !systemStderr.trim()) {
+        console.log(chalk.gray(`(No output returned)`));
+      }
+      console.log(chalk.gray(`----------------------------------------`));
+    } else {
+      // 2. Safe state inspection for physical steps
+      const inspectionCommands: Record<string, string> = {
+        "git-init": "git status",
+        "git-status": "git status",
+        "git-first-commit": "git log -n 1 --oneline",
+        "git-switch-create": "git branch",
+        "linux-mkdir": "ls -F",
+        "linux-echo-file": "cat practice/hello.txt",
+        "react-create": "ls -F my-app 2>/dev/null || ls -F",
+        "react-install": "ls -F my-app/node_modules 2>/dev/null || ls -F my-app",
+        "react-build": "ls -F my-app/dist 2>/dev/null || ls -F my-app"
+      };
+
+      const inspectCmd = inspectionCommands[step.id];
+      if (inspectCmd) {
+        const result = await runSystemCommand(inspectCmd, sandboxDir);
+        if (result.code === 0 && result.stdout.trim()) {
+          console.log(chalk.gray(`----------------------------------------`));
+          console.log(chalk.yellow(`🔍 Current Workspace State (via ${inspectCmd}):`));
+          console.log(chalk.gray(result.stdout.trim()));
+          console.log(chalk.gray(`----------------------------------------`));
+        }
+      }
+    }
+
+    try {
+      // Run validator
+      const validation = await validateStep(step, sandboxDir, typedCommand, systemStdout, systemStderr);
+      
+      if (!validation.valid) {
+        console.log(chalk.red.bold(`
+  ┌─ MISTAKE IDENTIFIED ──────────────────────────────────────┐
+  │                                                           │`));
+        const wrappedMistake = wrapText(validation.mistake ?? "Validation failed.", 54);
+        for (const line of wrappedMistake) {
+          console.log(chalk.red("  │ ") + chalk.white(line.padEnd(54)) + chalk.red(" │"));
+        }
+        console.log(chalk.red(`  │                                                           │
+  └───────────────────────────────────────────────────────────┘
+        `));
+
+        console.log(chalk.yellow(`💡 How to correct this mistake:`));
+        console.log(chalk.gray(`   1. Open a SEPARATE terminal tab or window.`));
+        console.log(chalk.gray(`   2. Run this command to navigate to the workspace and execute the target:`));
+        console.log(chalk.cyan(`      cd ${sandboxDir} && ${step.command}`));
+        console.log(chalk.gray(`   3. Return here and press [Enter] to try verifying again.\n`));
+
+        await inquirer.prompt([
+          {
+            type: "input",
+            name: "continue",
+            message: "Press [Enter] to try this command again and correct the mistake..."
+          }
+        ]);
+        continue; // Repeat current step
+      }
+
+      console.log(chalk.green("✓ Verification successful! You completed this step correctly."));
+
+      // Save step progress
+      if (!completedStepIds.includes(step.id)) {
+        completedStepIds.push(step.id);
+      }
+
+      // Check if all steps are completed
+      const isLessonFinished = lesson.steps.every((s) => completedStepIds.includes(s.id));
+      if (isLessonFinished && !completedLessonIds.includes(lesson.id)) {
+        completedLessonIds.push(lesson.id);
+      }
+
+      // Sync progress
+      const syncPayload: UpsertLearningProgressRequest = {
+        trackId: lesson.trackId,
+        completedLessonIds,
+        completedStepIds,
+        currentLessonId: lesson.id
+      };
+
+      await syncProgress(apiBaseUrl, syncPayload);
+
+      if (isLessonFinished) {
+        printCompletionBadge(lesson.title);
+        await inquirer.prompt([
+          {
+            type: "input",
+            name: "continue",
+            message: "Press [Enter] to complete this lesson and return to menu..."
+          }
+        ]);
+        return;
+      }
+
+      await inquirer.prompt([
+        {
+          type: "input",
+          name: "continue",
+          message: "Press [Enter] to proceed to the next step..."
+        }
+      ]);
+
+      stepIndex++;
+    } catch (error: any) {
+      console.log(chalk.red(`✗ Validation system error: ${error.message ?? error}`));
+    }
+  }
+}

package/cli/src/lib/localState.ts

@@ -0,0 +1,114 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { type VisionOsRuntimeInfo, type VisionOsUserProfile, type LearningProgress } from "../../../shared/src/index.js";
+
+export interface VisionOsRuntimeState extends VisionOsRuntimeInfo {
+  host: string;
+  pid: number;
+  port: number;
+  startedAt: string;
+}
+
+export interface VisionOsAccountState {
+  authenticatedAt: string;
+  token: string;
+  userId: string;
+}
+
+const visionOsHomeDir = path.join(os.homedir(), ".visionos");
+const accountStatePath = path.join(visionOsHomeDir, "account.json");
+const runtimeStatePath = path.join(visionOsHomeDir, "runtime.json");
+const userStatePath = path.join(visionOsHomeDir, "user.json");
+const progressStatePath = path.join(visionOsHomeDir, "progress.json");
+
+async function ensureVisionOsHomeDir() {
+  await fs.mkdir(visionOsHomeDir, { recursive: true });
+}
+
+async function readJsonFile<T>(filePath: string): Promise<T | null> {
+  try {
+    const contents = await fs.readFile(filePath, "utf8");
+
+    return JSON.parse(contents) as T;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return null;
+    }
+
+    throw error;
+  }
+}
+
+async function writeJsonFile(filePath: string, payload: unknown) {
+  await ensureVisionOsHomeDir();
+  await fs.writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+async function removeFileIfPresent(filePath: string) {
+  try {
+    await fs.unlink(filePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+export function getVisionOsStatePaths() {
+  return {
+    accountStatePath,
+    runtimeStatePath,
+    userStatePath,
+    visionOsHomeDir
+  };
+}
+
+export function readUserProfile() {
+  return readJsonFile<VisionOsUserProfile>(userStatePath);
+}
+
+export function writeUserProfile(profile: VisionOsUserProfile) {
+  return writeJsonFile(userStatePath, profile);
+}
+
+export function clearUserProfile() {
+  return removeFileIfPresent(userStatePath);
+}
+
+export function readAccountState() {
+  return readJsonFile<VisionOsAccountState>(accountStatePath);
+}
+
+export function writeAccountState(state: VisionOsAccountState) {
+  return writeJsonFile(accountStatePath, state);
+}
+
+export function clearAccountState() {
+  return removeFileIfPresent(accountStatePath);
+}
+
+export function readRuntimeState() {
+  return readJsonFile<VisionOsRuntimeState>(runtimeStatePath);
+}
+
+export function writeRuntimeState(state: VisionOsRuntimeState) {
+  return writeJsonFile(runtimeStatePath, state);
+}
+
+export function clearRuntimeState() {
+  return removeFileIfPresent(runtimeStatePath);
+}
+
+export async function readLocalProgress(): Promise<LearningProgress[]> {
+  const data = await readJsonFile<LearningProgress[]>(progressStatePath);
+  return data ?? [];
+}
+
+export function writeLocalProgress(progress: LearningProgress[]) {
+  return writeJsonFile(progressStatePath, progress);
+}
+
+export function clearLocalProgress() {
+  return removeFileIfPresent(progressStatePath);
+}

package/cli/src/lib/loginFlow.ts

@@ -0,0 +1,74 @@
+import chalk from "chalk";
+import {
+  APP_NAME,
+  LEARNING_TRACKS,
+  type CliAuthSession,
+  type LearningTrackId
+} from "../../../shared/src/index.js";
+import { createCliAuthSession, waitForCliAuthCompletion } from "./auth.js";
+import { openBrowser } from "./browser.js";
+import { writeAccountState, writeUserProfile } from "./localState.js";
+import { ensureVisionOsRuntime } from "./runtime.js";
+
+export async function runBrowserLogin(trackId: LearningTrackId): Promise<CliAuthSession | null> {
+  const selectedTrack = LEARNING_TRACKS.find((track) => track.id === trackId);
+  const runtime = await ensureVisionOsRuntime();
+  const authSession = await createCliAuthSession(runtime.apiBaseUrl, trackId);
+
+  console.log(chalk.white(`VisionOS runtime ready at ${runtime.appUrl}`));
+  console.log(chalk.white("Starting browser account login..."));
+
+  const browserOpened = await openBrowser(authSession.browserUrl);
+
+  if (browserOpened) {
+    console.log(chalk.gray("A browser window was opened for account sign-in."));
+  } else {
+    console.log(chalk.yellow("Open this URL to continue account sign-in:"));
+    console.log(chalk.white(authSession.browserUrl));
+  }
+
+  console.log(chalk.gray("Waiting for browser confirmation...\n"));
+
+  const completedSession = await waitForCliAuthCompletion(
+    runtime.apiBaseUrl,
+    authSession.session.sessionId,
+    authSession.pollIntervalMs
+  );
+
+  if (completedSession.status !== "authenticated" || !completedSession.learner) {
+    console.log(chalk.red("The authentication session expired. Run `visionos login` again."));
+    return null;
+  }
+
+  const authenticatedAt = completedSession.authenticatedAt ?? new Date().toISOString();
+
+  await writeUserProfile({
+    authenticatedAt,
+    email: completedSession.learner.email,
+    name: completedSession.learner.name,
+    sessionId: completedSession.sessionId,
+    trackId: completedSession.trackId,
+    userId: completedSession.learner.userId
+  });
+
+  if (completedSession.accountToken) {
+    await writeAccountState({
+      authenticatedAt,
+      token: completedSession.accountToken,
+      userId: completedSession.learner.userId
+    });
+  }
+
+  console.log(
+    chalk.green(
+      `Authenticated as ${completedSession.learner.name} (${completedSession.learner.email}).`
+    )
+  );
+  console.log(
+    chalk.white(
+      `${APP_NAME} account ready for the ${selectedTrack?.label ?? completedSession.trackId} track.`
+    )
+  );
+
+  return completedSession;
+}

package/cli/src/lib/progress.ts

@@ -0,0 +1,94 @@
+import {
+  type LearningProgress,
+  type LearningTrackId,
+  type UpsertLearningProgressRequest
+} from "../../../shared/src/index.js";
+import { VisionOsApiError } from "./auth.js";
+import { readAccountState } from "./localState.js";
+
+async function parseResponse<T>(response: Response): Promise<T> {
+  const payload = (await response.json().catch(() => null)) as { message?: string } | null;
+
+  if (!response.ok) {
+    throw new VisionOsApiError(
+      payload?.message ?? `VisionOS API request failed with status ${response.status}.`,
+      response.status
+    );
+  }
+
+  return payload as T;
+}
+
+export async function saveCurrentLessonProgress(
+  apiBaseUrl: string,
+  input: {
+    currentLessonId: string;
+    trackId: LearningTrackId;
+  }
+) {
+  const account = await readAccountState();
+
+  if (!account?.token) {
+    return null;
+  }
+
+  const body: UpsertLearningProgressRequest = {
+    completedLessonIds: [],
+    completedStepIds: [],
+    currentLessonId: input.currentLessonId,
+    trackId: input.trackId
+  };
+  const response = await fetch(`${apiBaseUrl.replace(/\/$/, "")}/progress`, {
+    method: "PUT",
+    headers: {
+      Authorization: `Bearer ${account.token}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(body)
+  });
+
+  return parseResponse<{ progress: LearningProgress }>(response);
+}
+
+export async function getRemoteProgress(
+  apiBaseUrl: string
+): Promise<{ progress: LearningProgress[] } | null> {
+  const account = await readAccountState();
+
+  if (!account?.token) {
+    return null;
+  }
+
+  const response = await fetch(`${apiBaseUrl.replace(/\/$/, "")}/progress`, {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${account.token}`
+    }
+  });
+
+  return parseResponse<{ progress: LearningProgress[] }>(response);
+}
+
+export async function syncProgress(
+  apiBaseUrl: string,
+  input: UpsertLearningProgressRequest
+): Promise<{ progress: LearningProgress } | null> {
+  const account = await readAccountState();
+
+  if (!account?.token) {
+    return null;
+  }
+
+  const response = await fetch(`${apiBaseUrl.replace(/\/$/, "")}/progress`, {
+    method: "PUT",
+    headers: {
+      Authorization: `Bearer ${account.token}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(input)
+  });
+
+  return parseResponse<{ progress: LearningProgress }>(response);
+}
+
+