visionos-monorepo 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish CLI to npm
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build monorepo packages
+        run: npm run build
+
+      - name: Publish CLI package to npm
+        run: npm publish -w cli
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -0,0 +1,175 @@
+# 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`, `login`, `lessons`, `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
+
+> [!TIP]
+> For a comprehensive guide covering options, internal behaviors, offline state configuration, and validation mechanics, refer directly to the [CLI Documentation](file:///Users/adityapathania/Codes/Chitkara/Projects/IP-project/VisionOS/cli/README.md).
+
+- `visionos start`
+  Starts the local VisionOS runtime if needed, opens browser account login when required, lets the learner choose a beginner lesson, and saves the selected lesson as current progress.
+
+- `visionos login`
+  Opens the browser account flow so a learner can log in or create a MongoDB-backed account.
+
+- `visionos lessons`
+  Browses beginner lessons for Git, Linux, React CLI, and OS Commands.
+
+- `visionos lessons --track git`
+  Shows beginner lessons for a specific track.
+
+- `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`.
+- The account bearer token is stored separately in `~/.visionos/account.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
+- `/login` serves the account login page
+- `/register` serves the account registration page
+- `/?cliAuthSession=...` serves the browser auth confirmation page
+- `/health` returns API health JSON
+- `/auth/me` returns the stored learner profile for the current machine
+- `/auth/register`, `/auth/login`, and `/auth/google` authenticate MongoDB-backed accounts
+- `/progress` reads and saves MongoDB-backed learner progress for the signed-in account
+- `/runtime/info` returns the current app/API origin information
+
+## Account Storage
+
+VisionOS account and progress storage uses MongoDB.
+
+Server environment:
+
+```bash
+MONGODB_URI=mongodb://127.0.0.1:27017
+MONGODB_DB=visionos
+GOOGLE_CLIENT_ID=
+```
+
+Client environment:
+
+```bash
+VITE_GOOGLE_CLIENT_ID=
+```
+
+Password accounts are stored in MongoDB with salted `scrypt` password hashes. Google login is available in the UI and works once both `GOOGLE_CLIENT_ID` and `VITE_GOOGLE_CLIENT_ID` are configured.
+
+## Current Limitations
+
+- The lesson execution engine is not implemented yet
+- Progress persistence endpoints exist, but the lesson runner does not write real lesson progress 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/cli/README.md

@@ -0,0 +1,165 @@
+# VisionOS Command Line Interface (CLI)
+
+The `visionos-cli` package provides the `visionos` binary—a high-fidelity, interactive, and terminal-first educational environment. It guides users through hands-on learning tracks (Git, Linux, OS, React) with physical workspace analysis and real-time command syntax validation.
+
+---
+
+## 🚀 Installation & Setup
+
+### Installing Globally
+To install the `visionos` CLI executable globally from npm:
+
+```bash
+npm install -g visionos-cli
+```
+
+### Building & Installing Locally
+To build and install the CLI from this monorepo directory:
+
+```bash
+# Navigate to monorepo root and execute build
+npm run build
+
+# Package the CLI into a tarball
+npm run pack:cli
+
+# Globally install the generated package tarball
+npm install -g ./visionos-cli-*.tgz
+```
+
+Verify your installation by running:
+```bash
+visionos --version
+```
+
+---
+
+## 🛠 Command Reference
+
+### `visionos start`
+Starts a guided, interactive terminal-based learning session. 
+
+* **Description**: Boots the local embedded runtime (if stopped), handles session authorization checks, prompts you to select a learning track, handles resume state checkpoints, configures your practice directory, and launches you into the step-by-step interactive lesson runner.
+* **Interactive Engine Flow**:
+  1. **Authentication Check**: Verifies active session token. Launches browser sign-in if credentials are missing.
+  2. **Track Selector**: Queries all available tracks from MongoDB (or local offline catalog fallback).
+  3. **Checkpoint Detection**: Automatically detects your progress. Offers to **Resume Last Lesson**, **Start from Beginning**, or **Browse Catalog**.
+  4. **Workspace Choice**: Prompts you to practice in the **Default isolated sandbox** or a **Custom directory**.
+  5. **Step Execution Loop**: Prints lesson title, estimated minutes, step instructions, and expected result verification commands. Executes commands, displays real OS system stdout/stderr outputs, and intercepts typos or failed exit codes to render descriptive mistake cards.
+* **Usage**:
+  ```bash
+  visionos start
+  ```
+
+---
+
+### `visionos login`
+Authenticates the terminal with your cloud-backed learner account.
+
+* **Description**: Spins up a local temporary embedded bridge server, launches your system browser to coordinate a secure MongoDB or Google authentication token handoff, and saves credentials under `~/.visionos/account.json` and `~/.visionos/user.json`.
+* **Options**:
+  * `-t, --track <trackId>`: Directly attach a specific learning track (e.g. `git`, `linux`, `os-commands`) to the browser login session to skip intermediate track prompts.
+* **Usage**:
+  ```bash
+  visionos login
+  visionos login --track os-commands
+  ```
+
+---
+
+### `visionos lessons`
+Browse and preview the interactive track curriculum.
+
+* **Description**: Lists all structured lessons, estimated completion times, and step counts for each learning path.
+* **Options**:
+  * `-t, --track <trackId>`: Filter and display lessons belonging exclusively to the specified track.
+  * `-l, --lesson <lessonId>`: Directly preview details (steps, objectives, verification commands, and descriptions) for a specific lesson without starting it.
+* **Usage**:
+  ```bash
+  # Interactive track search
+  visionos lessons
+
+  # View all lessons in the Git track
+  visionos lessons --track git
+
+  # Inspect a specific rebase lesson
+  visionos lessons --lesson git-github-connect
+  ```
+
+---
+
+### `visionos open`
+Instantly opens the VisionOS web learning dashboard.
+
+* **Description**: Evaluates active local runtime parameters and opens the dashboard inside your default system browser. Automatically injects your local account credentials securely via one-time URL tokens so you bypass manual login screens.
+* **Usage**:
+  ```bash
+  visionos open
+  ```
+
+---
+
+### `visionos userinfo`
+Inspects and displays details about your locally stored learner profile.
+
+* **Description**: Reads and formats cached session data, active progress tracks, authentication dates, and configuration folder structures.
+* **Options**:
+  * `--json`: Prints the entire structured learner profile, active paths, and runtime metadata as a raw JSON block (perfect for script hooks or advanced telemetry debugging).
+* **Usage**:
+  ```bash
+  # Formatted terminal display
+  visionos userinfo
+
+  # Print machine-readable JSON
+  visionos userinfo --json
+  ```
+
+---
+
+### `visionos status`
+Show the embedded VisionOS runtime and connectivity status.
+
+* **Description**: Runs a diagnostic inspect check on active local runtime configurations. Reports background process IDs (PIDs), target API server endpoints, web dashboard URLs, and authentication status.
+* **Usage**:
+  ```bash
+  visionos status
+  ```
+
+---
+
+### `visionos logout`
+Removes the locally stored VisionOS learner session.
+
+* **Description**: Securely clears all cached profile states, local accounts, and session metadata from the `~/.visionos/` directory.
+* **Usage**:
+  ```bash
+  visionos logout
+  ```
+
+---
+
+## 💾 State & Sandbox Architecture
+
+VisionOS operates with a highly robust system structure designed for sandbox isolation and hybrid data replication:
+
+### 1. File Configuration Directory (`~/.visionos/`)
+The CLI stores internal state and configurations in the user's home folder:
+* `~/.visionos/account.json`: Stores secure token parameters for API authorization.
+* `~/.visionos/user.json`: Caches core learner profile details (name, email, current track key).
+* `~/.visionos/runtime.json`: Keeps track of current local embedded server specifications (ports, endpoints, PIDs).
+* `~/.visionos/progress.json`: Stores local backup checkpoints for completed lessons/steps. Automatically synchronizes with the MongoDB remote server once internet connection is established.
+
+### 2. Workspace Sandbox Isolation
+When executing dynamic steps, learners are offered two practice directories:
+* **Default isolated sandbox (`~/.visionos/sandbox/<lesson-id>`)**: A completely secure, isolated repository rebuilt from scratch at every lesson boot. Bounded operations guarantee zero impact on your computer's home directory.
+* **Custom workspace directory**: Allows learners to select a path of their choice on their system.
+  > [!IMPORTANT]
+  > When working inside a custom workspace, all clean/reset triggers are disabled. The CLI operates in a pure **read-only inspection mode**, ensuring none of your personal files are ever modified or deleted.
+
+---
+
+## 🔍 Validation Engine Modes
+Every learning step defines a validation rule that is dynamically validated by the local parser without compiling TypeScript code:
+* **`syntax` Mode**: The user runs the command. The engine runs it in the sandbox, captures real OS stdout/stderr, and confirms successful exit codes (exit 0). Intercepts errors (e.g. typos, options flags) to display rich troubleshooting mistake alerts.
+* **`file-exists` Mode**: Scans the workspace to physically confirm folder or file creation rules.
+* **`file-contains` Mode**: Inspects the file contents to verify exact characters, branch bindings, or repository commits exist.

package/cli/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "visionos-cli",
+  "version": "0.1.7",
+  "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",
+    "mongodb": "^6.21.0"
+  },
+  "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/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/cli/src/commands/lessons.ts

@@ -0,0 +1,68 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import inquirer from "inquirer";
+import {
+  LEARNING_TRACKS,
+  getLessonById,
+  getLessonsForTrack,
+  type LearningTrackId
+} from "../../../shared/src/index.js";
+import { printLessonCatalog, printLessonPreview } from "../lib/lessonPrinter.js";
+
+export function createLessonsCommand() {
+  return new Command("lessons")
+    .description("Browse beginner lessons for each VisionOS track.")
+    .option("-t, --track <trackId>", "Show lessons for a specific track.")
+    .option("-l, --lesson <lessonId>", "Preview a specific lesson.")
+    .action(async ({ lesson, track }: { lesson?: string; track?: LearningTrackId }) => {
+      if (lesson) {
+        const selectedLesson = getLessonById(lesson);
+
+        if (!selectedLesson) {
+          console.error(chalk.red(`Lesson not found: ${lesson}`));
+          process.exitCode = 1;
+          return;
+        }
+
+        printLessonPreview(selectedLesson);
+        return;
+      }
+
+      const trackId = track ?? (await promptForTrack());
+
+      printLessonCatalog(trackId);
+    });
+}
+
+export async function promptForLesson(trackId: LearningTrackId) {
+  const lessons = getLessonsForTrack(trackId);
+  const { lessonId } = await inquirer.prompt<{ lessonId: string }>([
+    {
+      type: "list",
+      name: "lessonId",
+      message: "Choose a beginner lesson:",
+      choices: lessons.map((lesson) => ({
+        name: `${lesson.title} - ${lesson.summary}`,
+        value: lesson.id
+      }))
+    }
+  ]);
+
+  return getLessonById(lessonId);
+}
+
+async function promptForTrack() {
+  const { trackId } = await inquirer.prompt<{ trackId: LearningTrackId }>([
+    {
+      type: "list",
+      name: "trackId",
+      message: "Choose a learning track:",
+      choices: LEARNING_TRACKS.map((track) => ({
+        name: `${track.label} - ${track.description}`,
+        value: track.id
+      }))
+    }
+  ]);
+
+  return trackId;
+}

package/cli/src/commands/login.ts

@@ -0,0 +1,46 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import inquirer from "inquirer";
+import { LEARNING_TRACKS, type LearningTrackId } from "../../../shared/src/index.js";
+import { VisionOsApiError } from "../lib/auth.js";
+import { runBrowserLogin } from "../lib/loginFlow.js";
+
+export function createLoginCommand() {
+  return new Command("login")
+    .description("Log in to a VisionOS account through the browser.")
+    .option("-t, --track <trackId>", "Learning track to attach to this login session.")
+    .action(async ({ track }: { track?: LearningTrackId }) => {
+      try {
+        const trackId = track ?? (await promptForTrack());
+
+        await runBrowserLogin(trackId);
+      } catch (error) {
+        if (error instanceof VisionOsApiError) {
+          console.error(chalk.red("Unable to complete VisionOS account login."));
+          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 VisionOS account login."));
+        }
+
+        process.exitCode = 1;
+      }
+    });
+}
+
+async function promptForTrack() {
+  const { trackId } = await inquirer.prompt<{ trackId: LearningTrackId }>([
+    {
+      type: "list",
+      name: "trackId",
+      message: "Choose a track for this login session:",
+      choices: LEARNING_TRACKS.map((track) => ({
+        name: `${track.label} - ${track.description}`,
+        value: track.id
+      }))
+    }
+  ]);
+
+  return trackId;
+}

package/cli/src/commands/logout.ts

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

package/cli/src/commands/open.ts

@@ -0,0 +1,29 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import { openBrowser } from "../lib/browser.js";
+import { ensureVisionOsRuntime } from "../lib/runtime.js";
+import { readAccountState } from "../lib/localState.js";
+
+export function createOpenCommand() {
+  return new Command("open")
+    .description("Open the VisionOS web interface.")
+    .action(async () => {
+      const runtime = await ensureVisionOsRuntime();
+      const account = await readAccountState();
+
+      let launchUrl = runtime.appUrl;
+      if (account?.token) {
+        const separator = launchUrl.includes("?") ? "&" : "?";
+        launchUrl = `${launchUrl}${separator}token=${encodeURIComponent(account.token)}`;
+      }
+
+      const browserOpened = await openBrowser(launchUrl);
+
+      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."));
+      }
+    });
+}
+