visionos-monorepo 0.1.0

package/.claude/worktrees/competent-burnell-8d1330/README.md

@@ -0,0 +1,138 @@
+# VisionOS
+
+VisionOS is a CLI-first learning platform for command-line practice across tracks such as Git, Linux, React CLI, and OS commands.
+
+The current build includes:
+
+- An installable `visionos-cli` package with a `visionos` binary
+- An embedded local runtime that serves the web UI and API automatically
+- Browser-based CLI authentication handoff
+- Local user/session persistence in `~/.visionos/`
+- Commands for `start`, `open`, `userinfo`, `status`, and `logout`
+- A monorepo dev setup for separate server/client development
+
+## Monorepo Layout
+
+```text
+visionos/
+├── brain/
+├── cli/
+├── client/
+├── server/
+├── shared/
+└── README.md
+```
+
+## Install The CLI
+
+The npm package name is `visionos-cli`, but the command you run is `visionos`.
+
+### From npm
+
+Once the package is published, install it globally with:
+
+```bash
+npm install -g visionos-cli
+```
+
+Then run:
+
+```bash
+visionos start
+```
+
+### From this repository
+
+This repo is not published automatically. To build the installable tarball locally:
+
+```bash
+npm install
+npm run pack:cli
+npm install -g ./visionos-cli-0.1.1.tgz
+```
+
+After that, the CLI works the same way:
+
+```bash
+visionos start
+```
+
+You do not need `npm run dev:cli -- start` for installed usage.
+
+## CLI Commands
+
+- `visionos start`
+  Starts the local VisionOS runtime if needed, opens the browser auth flow, and waits for the session to complete.
+
+- `visionos open`
+  Opens the local VisionOS web interface without restarting the monorepo dev servers.
+
+- `visionos userinfo`
+  Shows the locally stored learner profile from `~/.visionos/user.json`.
+
+- `visionos userinfo --json`
+  Prints the stored learner profile, runtime info, and state file paths as JSON.
+
+- `visionos status`
+  Shows whether the embedded runtime is running and whether a learner profile is stored.
+
+- `visionos logout`
+  Removes the locally stored learner profile.
+
+## Installed Runtime Behavior
+
+- `visionos start` boots a local embedded runtime on `127.0.0.1` using an available port.
+- The runtime serves both the React frontend and the API from the same origin.
+- The browser auth page writes the authenticated learner profile to `~/.visionos/user.json`.
+- Runtime metadata is stored in `~/.visionos/runtime.json`.
+
+## Development Workflow
+
+If you want to work on the monorepo directly instead of using the installed package:
+
+```bash
+npm install
+npm run dev
+```
+
+That starts:
+
+- React on `http://localhost:5173`
+- Express on `http://127.0.0.1:4000`
+
+You can still run the CLI in dev mode with:
+
+```bash
+npm run dev:cli -- start
+```
+
+The backend API stays available at `http://127.0.0.1:4000`.
+
+## Workspace Scripts
+
+- `npm run build` builds every workspace in dependency order, including the packaged CLI runtime assets
+- `npm run pack:cli` builds the repo and creates `visionos-cli-0.1.1.tgz`
+- `npm run dev` starts the Express API and React frontend together
+- `npm run dev:cli` starts the CLI in development mode
+- `npm run dev:server` starts the Express API with file watching
+- `npm run dev:client` starts the React frontend
+
+## Current Web Surface
+
+- `/` serves the VisionOS homepage and runtime dashboard
+- `/?cliAuthSession=...` serves the browser auth confirmation page
+- `/health` returns API health JSON
+- `/auth/me` returns the stored learner profile for the current machine
+- `/runtime/info` returns the current app/API origin information
+
+## Current Limitations
+
+- The lesson execution engine is not implemented yet
+- Progress sync/resume is not implemented yet
+- The package is ready to publish, but publishing to npm has not been done from this repository
+
+## Next Milestones
+
+- Command execution and validation engine
+- Local progress persistence and backend sync
+- Resume support across CLI and web experiences

package/.claude/worktrees/competent-burnell-8d1330/cli/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "visionos-cli",
+  "version": "0.1.1",
+  "type": "module",
+  "bin": {
+    "visionos": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/runtime/index.ts --format esm --clean --out-dir dist && node ./scripts/copy-web-assets.mjs",
+    "dev": "tsx src/index.ts",
+    "lint": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.21.1",
+    "inquirer": "^9.3.7"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.10.1",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.3"
+  }
+}

package/.claude/worktrees/competent-burnell-8d1330/cli/scripts/copy-web-assets.mjs

@@ -0,0 +1,12 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url));
+const cliDir = path.resolve(currentDir, "..");
+const sourceDir = path.resolve(cliDir, "../client/dist");
+const targetDir = path.resolve(cliDir, "./dist/web");
+
+await fs.rm(targetDir, { force: true, recursive: true });
+await fs.mkdir(path.dirname(targetDir), { recursive: true });
+await fs.cp(sourceDir, targetDir, { recursive: true });

package/.claude/worktrees/competent-burnell-8d1330/cli/src/commands/logout.ts

@@ -0,0 +1,12 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import { clearUserProfile } from "../lib/localState.js";
+
+export function createLogoutCommand() {
+  return new Command("logout")
+    .description("Remove the locally stored VisionOS learner profile.")
+    .action(async () => {
+      await clearUserProfile();
+      console.log(chalk.yellow("Cleared the local VisionOS learner profile."));
+    });
+}

package/.claude/worktrees/competent-burnell-8d1330/cli/src/commands/open.ts

@@ -0,0 +1,19 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import { openBrowser } from "../lib/browser.js";
+import { ensureVisionOsRuntime } from "../lib/runtime.js";
+
+export function createOpenCommand() {
+  return new Command("open")
+    .description("Open the VisionOS web interface.")
+    .action(async () => {
+      const runtime = await ensureVisionOsRuntime();
+      const browserOpened = await openBrowser(runtime.appUrl);
+
+      console.log(chalk.cyan(`VisionOS web interface: ${runtime.appUrl}`));
+
+      if (!browserOpened) {
+        console.log(chalk.yellow("Open the URL above manually if your browser did not launch."));
+      }
+    });
+}

package/.claude/worktrees/competent-burnell-8d1330/cli/src/commands/start.ts

@@ -0,0 +1,97 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import inquirer from "inquirer";
+import { APP_NAME, LEARNING_TRACKS, type LearningTrackId } from "../../../shared/src/index.js";
+import { VisionOsApiError, createCliAuthSession, waitForCliAuthCompletion } from "../lib/auth.js";
+import { openBrowser } from "../lib/browser.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(
+          "Choose a track, complete browser sign-in, and return to the CLI for the guided lesson flow.\n"
+        )
+      );
+
+      const { trackId } = await inquirer.prompt<{ trackId: LearningTrackId }>([
+        {
+          type: "list",
+          name: "trackId",
+          message: "Choose a learning track to begin:",
+          choices: LEARNING_TRACKS.map((track) => ({
+            name: `${track.label} - ${track.description}`,
+            value: track.id
+          }))
+        }
+      ]);
+
+      const selectedTrack = LEARNING_TRACKS.find((track) => track.id === trackId);
+
+      console.log(chalk.green(`\nSelected track: ${selectedTrack?.label ?? trackId}`));
+
+      try {
+        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 authentication..."));
+
+        const browserOpened = await openBrowser(authSession.browserUrl);
+
+        if (browserOpened) {
+          console.log(chalk.gray("A browser window was opened for sign-in."));
+        } else {
+          console.log(chalk.yellow("Open this URL to continue authentication:"));
+          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 before it was completed. Run `visionos start` again."
+            )
+          );
+          return;
+        }
+
+        console.log(
+          chalk.green(
+            `Authenticated as ${completedSession.learner.name} (${completedSession.learner.email}).`
+          )
+        );
+        console.log(
+          chalk.white(
+            `Browser handoff completed for the ${selectedTrack?.label ?? completedSession.trackId} track.`
+          )
+        );
+        console.log(
+          chalk.yellow("Next milestone: command execution, validation, and persistent progress.\n")
+        );
+      } catch (error) {
+        if (error instanceof VisionOsApiError) {
+          console.error(
+            chalk.red("Unable to start browser authentication through the VisionOS 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/.claude/worktrees/competent-burnell-8d1330/cli/src/commands/status.ts

@@ -0,0 +1,23 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import { 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 [user, runtimeStatus] = await Promise.all([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"}`);
+    });
+}

package/.claude/worktrees/competent-burnell-8d1330/cli/src/commands/userinfo.ts

@@ -0,0 +1,47 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import { LEARNING_TRACKS } from "../../../shared/src/index.js";
+import { getVisionOsStatePaths, 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 [user, runtimeStatus] = await Promise.all([readUserProfile(), getVisionOsRuntimeStatus()]);
+
+      if (json) {
+        console.log(
+          JSON.stringify(
+            {
+              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("Last Track:")} ${track?.label ?? user.trackId}`);
+      console.log(`${chalk.white("Authenticated:")} ${user.authenticatedAt}`);
+      console.log(
+        `${chalk.white("Runtime:")} ${runtimeStatus.runtime?.appUrl ?? "not running"}`
+      );
+      console.log(`${chalk.white("State Dir:")} ${getVisionOsStatePaths().visionOsHomeDir}`);
+    });
+}

package/.claude/worktrees/competent-burnell-8d1330/cli/src/index.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+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";
+
+const program = new Command();
+
+program
+  .name("visionos")
+  .description("Interactive CLI for VisionOS learning tracks.")
+  .version("0.1.0");
+
+program.addCommand(createStartCommand());
+program.addCommand(createOpenCommand());
+program.addCommand(createUserInfoCommand());
+program.addCommand(createStatusCommand());
+program.addCommand(createLogoutCommand());
+
+void program.parseAsync(process.argv);

package/.claude/worktrees/competent-burnell-8d1330/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/.claude/worktrees/competent-burnell-8d1330/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/.claude/worktrees/competent-burnell-8d1330/cli/src/lib/localState.ts

@@ -0,0 +1,80 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { type VisionOsRuntimeInfo, type VisionOsUserProfile } from "../../../shared/src/index.js";
+
+export interface VisionOsRuntimeState extends VisionOsRuntimeInfo {
+  host: string;
+  pid: number;
+  port: number;
+  startedAt: string;
+}
+
+const visionOsHomeDir = path.join(os.homedir(), ".visionos");
+const runtimeStatePath = path.join(visionOsHomeDir, "runtime.json");
+const userStatePath = path.join(visionOsHomeDir, "user.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 {
+    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 readRuntimeState() {
+  return readJsonFile<VisionOsRuntimeState>(runtimeStatePath);
+}
+
+export function writeRuntimeState(state: VisionOsRuntimeState) {
+  return writeJsonFile(runtimeStatePath, state);
+}
+
+export function clearRuntimeState() {
+  return removeFileIfPresent(runtimeStatePath);
+}