visionos-monorepo 0.1.0

package/cli/src/commands/start.ts

@@ -0,0 +1,146 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import inquirer from "inquirer";
+import { APP_NAME, type LearningTrackId } from "../../../shared/src/index.js";
+import { fetchRemoteTracks, fetchRemoteLessons } from "../lib/content.js";
+import { VisionOsApiError } from "../lib/auth.js";
+import { printLessonPreview } from "../lib/lessonPrinter.js";
+import { runBrowserLogin } from "../lib/loginFlow.js";
+import { readAccountState, readUserProfile } from "../lib/localState.js";
+import { getRemoteProgress } from "../lib/progress.js";
+import { runLessonInteractive } from "../lib/lessonRunner.js";
+import { ensureVisionOsRuntime } from "../lib/runtime.js";
+
+export function createStartCommand() {
+  return new Command("start")
+    .description("Start an interactive VisionOS learning session.")
+    .action(async () => {
+      console.log(chalk.cyan.bold(`\n${APP_NAME}`));
+      console.log(
+        chalk.gray(
+          "Complete browser sign-in first, then choose a track and return to the CLI for the guided lesson flow.\n"
+        )
+      );
+
+      try {
+        const [account, user] = await Promise.all([readAccountState(), readUserProfile()]);
+        const runtime = await ensureVisionOsRuntime();
+
+        let apiBaseUrl = runtime.apiBaseUrl;
+        let token = account?.token;
+        let loggedInUser = user;
+
+        if (!token || !loggedInUser) {
+          console.log(chalk.yellow("You need to log in to your VisionOS account to start."));
+          // Use "git" as the default track to initiate the browser login session
+          const loginSession = await runBrowserLogin("git");
+
+          if (!loginSession || !loginSession.accountToken || !loginSession.learner) {
+            return;
+          }
+          token = loginSession.accountToken;
+          loggedInUser = {
+            userId: loginSession.learner.userId,
+            name: loginSession.learner.name,
+            email: loginSession.learner.email,
+            sessionId: loginSession.sessionId,
+            trackId: loginSession.trackId,
+            authenticatedAt: loginSession.authenticatedAt
+          };
+        } else {
+          console.log(chalk.green(`Signed in as ${loggedInUser.name} (${loggedInUser.email}).`));
+        }
+
+        const tracks = await fetchRemoteTracks(apiBaseUrl);
+
+        const { trackId } = await inquirer.prompt<{ trackId: LearningTrackId }>([
+          {
+            type: "list",
+            name: "trackId",
+            message: "Choose a learning track to begin:",
+            choices: tracks.map((track) => ({
+              name: `${track.label} - ${track.description}`,
+              value: track.id
+            }))
+          }
+        ]);
+
+        const selectedTrack = tracks.find((track) => track.id === trackId);
+
+        console.log(chalk.green(`\nSelected track: ${selectedTrack?.label ?? trackId}`));
+
+        // Fetch lessons for this track dynamically
+        const lessons = await fetchRemoteLessons(apiBaseUrl, trackId);
+
+        // Fetch remote progress for this user
+        let lesson = null;
+        const progressRes = await getRemoteProgress(apiBaseUrl);
+        const trackProgress = progressRes?.progress?.find((p) => p.trackId === trackId);
+
+        if (trackProgress?.currentLessonId) {
+          const lastLesson = lessons.find((l) => l.id === trackProgress.currentLessonId);
+          if (lastLesson) {
+            const { action } = await inquirer.prompt<{ action: "resume" | "beginning" | "catalog" }>([
+              {
+                type: "list",
+                name: "action",
+                message: `We found existing progress for this track. Last lesson: "${lastLesson.title}". What would you like to do?`,
+                choices: [
+                  { name: `Resume last lesson (${lastLesson.title})`, value: "resume" },
+                  { name: "Start from beginning (first lesson)", value: "beginning" },
+                  { name: "Choose a new lesson (browse track catalog)", value: "catalog" }
+                ]
+              }
+            ]);
+
+            if (action === "resume") {
+              lesson = lastLesson;
+            } else if (action === "beginning") {
+              lesson = lessons[0] ?? null;
+            }
+          }
+        }
+
+        if (!lesson) {
+          if (lessons.length === 0) {
+            console.log(chalk.red("No lessons are available for this track yet."));
+            return;
+          }
+          const { lessonId } = await inquirer.prompt<{ lessonId: string }>([
+            {
+              type: "list",
+              name: "lessonId",
+              message: "Choose a beginner lesson:",
+              choices: lessons.map((l) => ({
+                name: `${l.title} - ${l.summary}`,
+                value: l.id
+              }))
+            }
+          ]);
+          lesson = lessons.find((l) => l.id === lessonId) ?? null;
+        }
+
+        if (!lesson) {
+          console.log(chalk.red("No lesson was chosen. Exiting."));
+          return;
+        }
+
+        // Launch the interactive sandbox lesson runner
+        await runLessonInteractive(lesson, apiBaseUrl);
+      } catch (error) {
+
+        if (error instanceof VisionOsApiError) {
+          console.error(
+            chalk.red("Unable to start VisionOS learning through the runtime.")
+          );
+          console.error(chalk.gray(error.message));
+        } else if (error instanceof Error) {
+          console.error(chalk.red(error.message));
+        } else {
+          console.error(chalk.red("An unexpected error interrupted browser authentication."));
+        }
+
+        process.exitCode = 1;
+      }
+    });
+}

package/cli/src/commands/status.ts

@@ -0,0 +1,28 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import { readAccountState, readUserProfile } from "../lib/localState.js";
+import { getVisionOsRuntimeStatus } from "../lib/runtime.js";
+
+export function createStatusCommand() {
+  return new Command("status")
+    .description("Show the VisionOS runtime and local auth status.")
+    .action(async () => {
+      const [account, user, runtimeStatus] = await Promise.all([
+        readAccountState(),
+        readUserProfile(),
+        getVisionOsRuntimeStatus()
+      ]);
+
+      console.log(chalk.cyan.bold("VisionOS Status"));
+      console.log(`${chalk.white("Runtime:")} ${runtimeStatus.isRunning ? "running" : "stopped"}`);
+
+      if (runtimeStatus.runtime) {
+        console.log(`${chalk.white("App URL:")} ${runtimeStatus.runtime.appUrl}`);
+        console.log(`${chalk.white("API URL:")} ${runtimeStatus.runtime.apiBaseUrl}`);
+        console.log(`${chalk.white("PID:")} ${runtimeStatus.runtime.pid}`);
+      }
+
+      console.log(`${chalk.white("User:")} ${user ? `${user.name} <${user.email}>` : "not signed in"}`);
+      console.log(`${chalk.white("Account Token:")} ${account ? "stored" : "missing"}`);
+    });
+}

package/cli/src/commands/userinfo.ts

@@ -0,0 +1,59 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import { LEARNING_TRACKS } from "../../../shared/src/index.js";
+import { getVisionOsStatePaths, readAccountState, readUserProfile } from "../lib/localState.js";
+import { getVisionOsRuntimeStatus } from "../lib/runtime.js";
+
+export function createUserInfoCommand() {
+  return new Command("userinfo")
+    .description("Show the locally stored VisionOS learner profile.")
+    .option("--json", "Print the stored profile as JSON.")
+    .action(async ({ json }: { json?: boolean }) => {
+      const [account, user, runtimeStatus] = await Promise.all([
+        readAccountState(),
+        readUserProfile(),
+        getVisionOsRuntimeStatus()
+      ]);
+
+      if (json) {
+        console.log(
+          JSON.stringify(
+            {
+              account: account
+                ? {
+                    authenticatedAt: account.authenticatedAt,
+                    hasToken: Boolean(account.token),
+                    userId: account.userId
+                  }
+                : null,
+              runtime: runtimeStatus.runtime,
+              statePaths: getVisionOsStatePaths(),
+              user
+            },
+            null,
+            2
+          )
+        );
+        return;
+      }
+
+      if (!user) {
+        console.log(chalk.yellow("No VisionOS learner profile is stored locally yet."));
+        console.log(chalk.gray("Run `visionos start` to authenticate and create one."));
+        return;
+      }
+
+      const track = LEARNING_TRACKS.find((item) => item.id === user.trackId);
+
+      console.log(chalk.cyan.bold("VisionOS User"));
+      console.log(`${chalk.white("Name:")} ${user.name}`);
+      console.log(`${chalk.white("Email:")} ${user.email}`);
+      console.log(`${chalk.white("Account ID:")} ${user.userId}`);
+      console.log(`${chalk.white("Last Track:")} ${track?.label ?? user.trackId ?? "not started"}`);
+      console.log(`${chalk.white("Authenticated:")} ${user.authenticatedAt ?? "unknown"}`);
+      console.log(
+        `${chalk.white("Runtime:")} ${runtimeStatus.runtime?.appUrl ?? "not running"}`
+      );
+      console.log(`${chalk.white("State Dir:")} ${getVisionOsStatePaths().visionOsHomeDir}`);
+    });
+}

package/cli/src/index.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import dotenv from "dotenv";
+import { Command } from "commander";
+import { createLessonsCommand } from "./commands/lessons.js";
+import { createLoginCommand } from "./commands/login.js";
+import { createLogoutCommand } from "./commands/logout.js";
+import { createOpenCommand } from "./commands/open.js";
+import { createStatusCommand } from "./commands/status.js";
+import { createStartCommand } from "./commands/start.js";
+import { createUserInfoCommand } from "./commands/userinfo.js";
+
+function loadEnvFile(filePath: string) {
+  if (fs.existsSync(filePath)) {
+    dotenv.config({ path: filePath });
+    return true;
+  }
+  return false;
+}
+
+function loadEnvironment() {
+  // 1. Try standard current working directory
+  dotenv.config();
+
+  // 2. Walk up parent directories of process.cwd() to find `.env` or `server/.env`
+  try {
+    let currentDir = process.cwd();
+    for (let i = 0; i < 10; i++) {
+      const rootEnv = path.join(currentDir, ".env");
+      const serverEnv = path.join(currentDir, "server", ".env");
+
+      if (loadEnvFile(serverEnv)) {
+        break;
+      } else if (loadEnvFile(rootEnv)) {
+        break;
+      }
+
+      const parent = path.dirname(currentDir);
+      if (parent === currentDir) break;
+      currentDir = parent;
+    }
+  } catch {
+    // Ignore fallback errors
+  }
+
+  // 3. Walk up directories starting from import.meta.url to find `.env` or `server/.env`
+  try {
+    const startDir = path.dirname(fileURLToPath(import.meta.url));
+    let currentDir = startDir;
+
+    for (let i = 0; i < 10; i++) {
+      const rootEnv = path.join(currentDir, ".env");
+      const serverEnv = path.join(currentDir, "server", ".env");
+
+      if (loadEnvFile(serverEnv)) {
+        break;
+      } else if (loadEnvFile(rootEnv)) {
+        break;
+      }
+
+      const parent = path.dirname(currentDir);
+      if (parent === currentDir) break;
+      currentDir = parent;
+    }
+  } catch {
+    // Ignore fallback errors
+  }
+
+  // 4. Try global user configuration directory (~/.visionos/.env)
+  try {
+    const globalEnvPath = path.join(os.homedir(), ".visionos", ".env");
+    loadEnvFile(globalEnvPath);
+  } catch {
+    // Ignore fallback errors
+  }
+}
+
+// Load active .env configurations at CLI startup
+loadEnvironment();
+
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+let version = "0.1.7";
+try {
+  version = require("../package.json").version;
+} catch {
+  // Fallback
+}
+
+const program = new Command();
+
+program
+  .name("visionos")
+  .description("Interactive CLI for VisionOS learning tracks.")
+  .version(version);
+
+program.addCommand(createStartCommand());
+program.addCommand(createLoginCommand());
+program.addCommand(createLessonsCommand());
+program.addCommand(createOpenCommand());
+program.addCommand(createUserInfoCommand());
+program.addCommand(createStatusCommand());
+program.addCommand(createLogoutCommand());
+
+void program.parseAsync(process.argv);

package/cli/src/lib/auth.ts

@@ -0,0 +1,84 @@
+import {
+  type CliAuthSession,
+  type CliAuthSessionEnvelope,
+  type CreateCliAuthSessionResponse,
+  type LearningTrackId,
+  type VisionOsRuntimeInfoResponse,
+  type VisionOsUserInfoResponse
+} from "../../../shared/src/index.js";
+
+export class VisionOsApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number
+  ) {
+    super(message);
+    this.name = "VisionOsApiError";
+  }
+}
+
+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;
+}
+
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function request<T>(apiBaseUrl: string, path: string, init?: RequestInit): Promise<T> {
+  const response = await fetch(`${apiBaseUrl.replace(/\/$/, "")}${path}`, init);
+
+  return parseResponse<T>(response);
+}
+
+export async function createCliAuthSession(
+  apiBaseUrl: string,
+  trackId: LearningTrackId
+): Promise<CreateCliAuthSessionResponse> {
+  return request<CreateCliAuthSessionResponse>(apiBaseUrl, "/auth/cli/sessions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ trackId })
+  });
+}
+
+export async function fetchCliAuthSession(apiBaseUrl: string, sessionId: string): Promise<CliAuthSession> {
+  const payload = await request<CliAuthSessionEnvelope>(apiBaseUrl, `/auth/cli/sessions/${sessionId}`);
+
+  return payload.session;
+}
+
+export async function waitForCliAuthCompletion(
+  apiBaseUrl: string,
+  sessionId: string,
+  pollIntervalMs: number
+): Promise<CliAuthSession> {
+  while (true) {
+    const session = await fetchCliAuthSession(apiBaseUrl, sessionId);
+
+    if (session.status !== "pending") {
+      return session;
+    }
+
+    await sleep(pollIntervalMs);
+  }
+}
+
+export function fetchCurrentUser(apiBaseUrl: string) {
+  return request<VisionOsUserInfoResponse>(apiBaseUrl, "/auth/me");
+}
+
+export function fetchRuntimeInfo(apiBaseUrl: string) {
+  return request<VisionOsRuntimeInfoResponse>(apiBaseUrl, "/runtime/info");
+}

package/cli/src/lib/browser.ts

@@ -0,0 +1,37 @@
+import { spawn } from "node:child_process";
+
+function getBrowserCommand(url: string): { command: string; args: string[] } {
+  if (process.platform === "darwin") {
+    return { command: "open", args: [url] };
+  }
+
+  if (process.platform === "win32") {
+    return { command: "cmd", args: ["/c", "start", "", url] };
+  }
+
+  return { command: "xdg-open", args: [url] };
+}
+
+export function openBrowser(url: string): Promise<boolean> {
+  const { command, args } = getBrowserCommand(url);
+
+  return new Promise((resolve) => {
+    try {
+      const child = spawn(command, args, {
+        detached: true,
+        stdio: "ignore"
+      });
+
+      child.once("error", () => {
+        resolve(false);
+      });
+
+      child.once("spawn", () => {
+        child.unref();
+        resolve(true);
+      });
+    } catch {
+      resolve(false);
+    }
+  });
+}

package/cli/src/lib/content.ts

@@ -0,0 +1,57 @@
+import {
+  type LearningTrack,
+  type LearningLesson,
+  LEARNING_TRACKS,
+  BEGINNER_LESSONS
+} from "../../../shared/src/index.js";
+import { readAccountState } from "./localState.js";
+
+export async function fetchRemoteTracks(apiBaseUrl: string): Promise<LearningTrack[]> {
+  try {
+    const account = await readAccountState();
+    const headers: Record<string, string> = {};
+    if (account?.token) {
+      headers["Authorization"] = `Bearer ${account.token}`;
+    }
+
+    const response = await fetch(`${apiBaseUrl.replace(/\/$/, "")}/content/tracks`, {
+      method: "GET",
+      headers
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch tracks: ${response.status}`);
+    }
+
+    const data = (await response.json()) as { tracks: LearningTrack[] };
+    return data.tracks ?? LEARNING_TRACKS;
+  } catch (error) {
+    // Graceful offline fallback
+    return LEARNING_TRACKS;
+  }
+}
+
+export async function fetchRemoteLessons(apiBaseUrl: string, trackId: string): Promise<LearningLesson[]> {
+  try {
+    const account = await readAccountState();
+    const headers: Record<string, string> = {};
+    if (account?.token) {
+      headers["Authorization"] = `Bearer ${account.token}`;
+    }
+
+    const response = await fetch(`${apiBaseUrl.replace(/\/$/, "")}/content/tracks/${trackId}/lessons`, {
+      method: "GET",
+      headers
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch lessons: ${response.status}`);
+    }
+
+    const data = (await response.json()) as { lessons: LearningLesson[] };
+    return data.lessons ?? BEGINNER_LESSONS.filter((l) => l.trackId === trackId);
+  } catch (error) {
+    // Graceful offline fallback
+    return BEGINNER_LESSONS.filter((l) => l.trackId === trackId);
+  }
+}

package/cli/src/lib/lessonPrinter.ts

@@ -0,0 +1,38 @@
+import chalk from "chalk";
+import {
+  LEARNING_TRACKS,
+  getLessonsForTrack,
+  type LearningLesson,
+  type LearningTrackId
+} from "../../../shared/src/index.js";
+
+export function printLessonCatalog(trackId: LearningTrackId) {
+  const track = LEARNING_TRACKS.find((item) => item.id === trackId);
+  const lessons = getLessonsForTrack(trackId);
+
+  console.log(chalk.cyan.bold(`\n${track?.label ?? trackId} beginner lessons`));
+
+  for (const lesson of lessons) {
+    console.log(chalk.white(`\n${lesson.title}`));
+    console.log(chalk.gray(`${lesson.summary} (${lesson.estimatedMinutes} min)`));
+
+    for (const [index, step] of lesson.steps.entries()) {
+      console.log(chalk.gray(`  ${index + 1}. ${step.title}`));
+      console.log(chalk.yellow(`     ${step.command}`));
+    }
+  }
+}
+
+export function printLessonPreview(lesson: LearningLesson) {
+  console.log(chalk.cyan.bold(`\n${lesson.title}`));
+  console.log(chalk.gray(`${lesson.summary} (${lesson.estimatedMinutes} min)\n`));
+
+  for (const [index, step] of lesson.steps.entries()) {
+    console.log(chalk.white(`${index + 1}. ${step.title}`));
+    console.log(chalk.gray(`   Goal: ${step.objective}`));
+    console.log(chalk.yellow(`   Command: ${step.command}`));
+    console.log(chalk.gray(`   Why: ${step.explanation}\n`));
+  }
+
+  console.log(chalk.gray("Command execution and validation will be the next implementation step."));
+}