@vention/vention-cli 0.34.0 → 0.34.2

package/README.md

@@ -5,6 +5,7 @@
 ---
 
 ## Table of Contents
+
 - [✨ Features](#-features)
 - [🧠 Concepts & Overview](#-concepts--overview)
 - [⚙️ Installation & Setup](#-installation--setup)
@@ -13,8 +14,8 @@
 - [📖 API Reference](#-api-reference)
 - [🔍 Troubleshooting & FAQ](#-troubleshooting--faq)
 
-
 ## ✨ Features
+
 - **Local IDE development**: Edit MachineLogic Python apps in your preferred IDE with full tooling support
 - **Bidirectional sync**: Pull apps from MachineBuilder and push changes back seamlessly
 - **Active design detection**: Automatically finds and connects to designs with MachineLogic tab open
@@ -28,24 +29,30 @@
 ## 🧠 Concepts & Overview
 
 ### Active Design
+
 The Vention CLI connects to **active designs** — designs where you have the MachineLogic tab open in MachineBuilder. This active session enables the CLI to discover available designs and apps for sync operations.
 
 ### Link State
+
 When you pull or link an app, the CLI creates a `.machine-code-app-directory-info.json` file in your project root. This file maintains the connection between your local directory and a specific design/app combination, enabling seamless push/pull operations without re-selection.
 
 ### File Synchronization
+
 - **Pull**: Downloads the app's source files from MachineBuilder and writes them to your local directory
 - **Push**: Serializes local files and uploads them to the active design in MachineBuilder
-- **Ignored patterns**: `venv`, `.venv`, `node_modules`, `dist`, `build`, `__pycache__`, `*.egg-info`, `.machine-code-app-directory-info.json`, `.vention-design-scene-assets.json`, `.vention-design-configuration.json`
+- **Ignored patterns**: `venv`, `.venv`, `node_modules`, `dist`, `build`, `__pycache__`, `.claude`, `.agents`, `.git`, `*.egg-info`, `.machine-code-app-directory-info.json`, `.vention-design-scene-assets.json`, `.vention-design-configuration.json`
 
 ### Read-only Config & Scene Assets
+
 Every `vention pull` also writes two read-only reference files to the app directory, sourced from the active design:
+
 - `.vention-design-configuration.json`: the design's MachineMotion configuration
 - `.vention-design-scene-assets.json`: the design's library assets, if the design has a library (omitted otherwise)
 
 Both files are chmodded read-only (`0o444`) after writing, and are excluded from `push` via the ignored patterns above — they're a local snapshot for reference only, not something the CLI syncs back to MachineBuilder.
 
 ### Authentication Flow
+
 OAuth-based authentication opens a browser window for secure login. Session tokens are stored in `~/.vention-cli-config.json` for subsequent CLI operations.
 
 ---
@@ -53,16 +60,19 @@ OAuth-based authentication opens a browser window for secure login. Session toke
 ## ⚙️ Installation & Setup
 
 **Requirements:**
+
 - Node.js 18 or higher
 - npm or yarn
 - Active MachineBuilder session with MachineLogic tab open
 
 **Install globally via npm:**
+
 ```bash
 npm install -g @vention/vention-cli
 ```
 
 **Verify installation:**
+
 ```bash
 vention --version
 ```
@@ -83,16 +93,21 @@ This tutorial shows the complete workflow from authentication to syncing your fi
 Open your design in MachineBuilder and select the **MachineLogic tab**. This activates the design for CLI access.
 
 **Step 2: Authenticate**
+
 ```bash
 vention login
 ```
+
 This opens a browser window for secure OAuth login.
 
 **Step 3: Pull your app locally**
+
 ```bash
 vention pull
 ```
+
 The CLI will:
+
 - Show available active designs
 - Let you select a design
 - Display MachineLogic Python apps in that design
@@ -103,9 +118,11 @@ The CLI will:
 Open the created folder in your IDE and edit files like `main.py` or `project.json`.
 
 **Step 5: Push changes back**
+
 ```bash
 vention push
 ```
+
 Your changes are now uploaded to MachineBuilder.
 
 **Step 6: Run in MachineBuilder**
@@ -182,16 +199,19 @@ vention --verbose       # Enable verbose output for debugging (use with any comm
 **Description:** Authenticate with your Vention account using OAuth.
 
 **Usage:**
+
 ```bash
 vention login
 ```
 
 **Behavior:**
+
 - Opens a browser window for secure OAuth authentication
 - Stores session tokens in `~/.vention-cli-config.json`
 - Tokens persist across terminal sessions and are refreshed automatically
 
 **Exit codes:**
+
 - `0`: Authentication successful
 - `1`: Authentication failed or cancelled
 
@@ -202,11 +222,13 @@ vention login
 **Description:** Fetch a MachineLogic Python app from your active design into the current directory.
 
 **Usage:**
+
 ```bash
 vention pull
 ```
 
 **Behavior:**
+
 - If the directory is not linked: prompts for design and app selection, creates a new folder
 - If the directory is already linked: updates files in place using stored link metadata
 - Downloads all source files except ignored patterns
@@ -215,11 +237,13 @@ vention pull
 - Updates `lastPulledAt` timestamp
 
 **Prerequisites:**
+
 - User must be logged in (`vention login`)
 - Target design must have MachineLogic tab open in MachineBuilder
 - Target app must be a MachineLogic Python app (code-free apps not supported)
 
 **Exit codes:**
+
 - `0`: Pull successful
 - `1`: Not logged in, no active design found, or pull failed
 
@@ -230,11 +254,13 @@ vention pull
 **Description:** Upload local changes from the linked directory to your active design.
 
 **Usage:**
+
 ```bash
 vention push
 ```
 
 **Behavior:**
+
 - If the directory is not linked: offers to link it to an application and continue the push
 - Reads `.machine-code-app-directory-info.json` to identify target design/app
 - Serializes all local files except ignored patterns
@@ -242,10 +268,12 @@ vention push
 - Updates `lastPushedAt` timestamp
 
 **Prerequisites:**
+
 - User must be logged in
 - The same design must be active in MachineBuilder (MachineLogic tab open)
 
 **Exit codes:**
+
 - `0`: Push successful, or push cancelled at the link prompt
 - `1`: Not logged in, design not active, or push failed
 
@@ -256,11 +284,13 @@ vention push
 **Description:** Link the current directory to a design + app without pulling files.
 
 **Usage:**
+
 ```bash
 vention link
 ```
 
 **Behavior:**
+
 - Prompts for design and app selection
 - Writes `.machine-code-app-directory-info.json` with link metadata
 - Does not download or modify existing files
@@ -268,6 +298,7 @@ vention link
 **Use case:** Useful when you already have the app files and just want to establish the connection for push operations.
 
 **Exit codes:**
+
 - `0`: Link successful
 - `1`: Not logged in, no active design found, or link failed
 
@@ -278,21 +309,25 @@ vention link
 **Description:** Fetch application logs from the linked digital twin.
 
 **Usage:**
+
 ```bash
 vention logs
 ```
 
 **Behavior:**
+
 - Reads `.machine-code-app-directory-info.json` to identify the target design/app
 - Fetches the application's logs from the digital twin
 - Prints the logs to the terminal
 
 **Prerequisites:**
+
 - Directory must be linked (contains `.machine-code-app-directory-info.json`)
 - User must be logged in
 - The same design must be active in MachineBuilder (MachineLogic tab open)
 
 **Exit codes:**
+
 - `0`: Logs fetched successfully
 - `1`: Not linked, not logged in, design not active, or fetch failed
 
@@ -303,6 +338,7 @@ vention logs
 **Location:** `.machine-code-app-directory-info.json` (project root)
 
 **Schema:**
+
 ```json
 {
   "appName": "My App",
@@ -316,6 +352,7 @@ vention logs
 ```
 
 **Fields:**
+
 - `appName` (string): Human-readable app name
 - `designId` (number): Unique design identifier
 - `applicationId` (string): Unique application identifier
@@ -331,22 +368,27 @@ vention logs
 ### Common Errors
 
 **"Not logged in. Please run 'vention login' first."**
+
 - **Cause:** Authentication tokens not found or expired
 - **Solution:** Run `vention login` to re-authenticate
 
 **"No active design found …" or "Please open the design and navigate to MachineLogic …"**
+
 - **Cause:** No designs have the MachineLogic tab open in MachineBuilder
 - **Solution:** Open your target design in MachineBuilder and click the MachineLogic tab to activate it
 
 **"This directory is not linked …"**
+
 - **Cause:** The directory doesn't have `.machine-code-app-directory-info.json`
 - **Solution:** Run `vention link` or `vention pull` to establish the link. During `push`, the CLI will offer to link the directory and continue automatically.
 
 **Push fails with authentication errors**
+
 - **Cause:** Session tokens expired
 - **Solution:** Run `vention login` to refresh authentication
 
 **"Directory already exists" (during pull)**
+
 - **Cause:** A folder with the app name already exists
 - **Solution:** Either:
   - `cd` into the existing directory and run `vention pull` (updates in place)
@@ -378,4 +420,3 @@ A: The last push/pull wins. There's no conflict resolution or merging. We recomm
 
 **Q: Does this work with MachineMotion apps?**  
 A: The CLI specifically targets MachineLogic Python apps. For MachineMotion development, see the MachineMotion SDK documentation.
-