@vention/vention-cli 0.11.2 → 0.12.0

package/README.md

@@ -1,84 +1,263 @@
-# Vention CLI — Work locally with MachineLogic Python apps
+# Vention CLI
 
-The Vention CLI lets you pull MachineLogic Python applications from an active design into your local IDE, edit them, and push changes back — without leaving MachineBuilder.
+> A command-line tool that enables local development of MachineLogic Python applications with bidirectional sync between your IDE and MachineBuilder.
 
-Important:
-- Supports MachineLogic Python apps only. Code-free MachineLogic programs are not supported.
-- You must have the MachineLogic tab open for your design in MachineBuilder. Opening that tab makes the design active for the CLI.
-- Learn about MachineLogic Python app structure (main.py, project.json, HMI, etc.): https://docs.vention.io/docs/machinelogic-python-programming-guide
+---
 
-## Installation
+## Table of Contents
+- [✨ Features](#-features)
+- [🧠 Concepts & Overview](#-concepts--overview)
+- [⚙️ Installation & Setup](#-installation--setup)
+- [🚀 Quickstart Tutorial](#-quickstart-tutorial)
+- [🛠 How-to Guides](#-how-to-guides)
+- [📖 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
+- **Smart file handling**: Automatically ignores build artifacts, virtual environments, and common development files
+- **Session management**: Persistent authentication with secure token storage
+- **Multiple apps support**: Link and switch between different apps within the same design
+
+---
+
+## 🧠 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`, `node_modules`, `dist`, `build`, `__pycache__`, `*.egg-info`, `.machine-code-app-directory-info.json`
+
+### 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.
+
+---
+
+## ⚙️ Installation & Setup
+
+**Requirements:**
+- Node.js 16 or higher
+- npm or yarn
+- Active MachineBuilder session with MachineLogic tab open
+
+**Install globally via npm:**
 ```bash
-# Install from npm
 npm install -g @vention/vention-cli
 ```
 
-Use either `vention` or `vn` as the command.
+**Verify installation:**
+```bash
+vention --version
+```
+
+**Command aliases:**
+Use either `vention` or `vn` as the command prefix.
+
+**Learn more about MachineLogic Python app structure:**
+https://docs.vention.io/docs/machinelogic-python-programming-guide
+
+---
+
+## 🚀 Quickstart Tutorial
 
-## Quick start
+This tutorial shows the complete workflow from authentication to syncing your first app.
 
-1) Open your design in MachineBuilder and select the MachineLogic tab (this makes your design active).
-2) Authenticate:
+**Step 1: Open your design**
+Open your design in MachineBuilder and select the **MachineLogic tab**. This activates the design for CLI access.
+
+**Step 2: Authenticate**
 ```bash
 vention login
 ```
-3) Pull your app locally (creates a folder named after the app):
+This opens a browser window for secure OAuth login.
+
+**Step 3: Pull your app locally**
 ```bash
 vention pull
 ```
-4) Edit code in your IDE (e.g., update `main.py`, `project.json`).
-5) Push changes back to your active design:
+The CLI will:
+- Show available active designs
+- Let you select a design
+- Display MachineLogic Python apps in that design
+- Let you select an app to pull
+- Create a folder named after the app with all source files
+
+**Step 4: Edit locally**
+Open the created folder in your IDE and edit files like `main.py` or `project.json`.
+
+**Step 5: Push changes back**
 ```bash
 vention push
 ```
-6) In MachineBuilder, use the MachineLogic panel to run/simulate your updated app.
+Your changes are now uploaded to MachineBuilder.
+
+**Step 6: Run in MachineBuilder**
+Use the MachineLogic panel in MachineBuilder to run and test your updated app.
+
+---
+
+## 🛠 How-to Guides
+
+### Link an existing directory without pulling files
+
+If you already have the app files locally and just want to establish the link:
+
+```bash
+cd my-existing-app
+vention link
+```
+
+This writes `.machine-code-app-directory-info.json` without overwriting your files.
+
+### Update an already-linked app
+
+If your directory is already linked, simply run pull again to update files in place:
+
+```bash
+vention pull
+```
+
+The CLI detects the existing link and updates the project without creating a new folder.
+
+### Switch between different apps
+
+To link your current directory to a different app:
+
+1. Delete the `.machine-code-app-directory-info.json` file
+2. Run `vention link` or `vention pull` and select the new app
+
+### View help for any command
+
+```bash
+vention --help
+vention pull --help
+vention push --help
+```
+
+### Work with multiple environments
 
-## How it works
+The CLI stores the environment (e.g., `prod`, `staging`) in the link metadata file. To switch environments, re-link to the desired environment.
 
-- Active design: The CLI finds designs where the MachineLogic tab is open and connects to your active design.
-- App selection: When pulling/linking, choose one of the design’s MachineLogic Python apps.
-- Local state: The CLI writes `.machine-code-app-directory-info.json` at the project root to remember the selected design/app and environment.
-- File sync:
-  - Pull: Downloads the app’s source files and writes them to disk.
-  - Push: Serializes local files and uploads them to your active design.
-- Ignored items when pushing: `venv`, `node_modules`, `dist`, `build`, `__pycache__`, `*.egg-info`, `.machine-code-app-directory-info.json`.
+---
 
-## Commands
+## 📖 API Reference
+
+### Global Options
 
 ```bash
-vention --help          # Show help
-vention --version       # Show version
+vention --help          # Display help information
+vention --version       # Display CLI version
 ```
 
-- login: Authenticate
+### `vention login`
+
+**Description:** Authenticate with your Vention account using OAuth.
+
+**Usage:**
 ```bash
 vention login
-# will open a browser window where you will be able to login to your Vention account
 ```
 
-- pull: Fetch a MachineLogic Python app from your active design into the current directory
+**Behavior:**
+- Opens a browser window for secure OAuth authentication
+- Stores session tokens in `~/.vention-cli-config.json`
+- Tokens persist across terminal sessions
+
+**Exit codes:**
+- `0`: Authentication successful
+- `1`: Authentication failed or cancelled
+
+---
+
+### `vention pull`
+
+**Description:** Fetch a MachineLogic Python app from your active design into the current directory.
+
+**Usage:**
 ```bash
 vention pull
-# If the current folder isn’t linked yet, select a design (with MachineLogic open) and then an app.
-# If linked, the CLI updates the existing project in place.
 ```
 
-- link: Link the current directory to a design + app without pulling files
+**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
+- Writes/updates `.machine-code-app-directory-info.json`
+- 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
+
+---
+
+### `vention push`
+
+**Description:** Upload local changes from the linked directory to your active design.
+
+**Usage:**
 ```bash
-vention link
-# Writes .machine-code-app-directory-info.json so future push/pull operations know what to target.
+vention push
 ```
 
-- push: Upload local changes from the linked directory to your active design
+**Behavior:**
+- Reads `.machine-code-app-directory-info.json` to identify target design/app
+- Serializes all local files except ignored patterns
+- Uploads to MachineBuilder
+- Updates `lastPushedAt` timestamp
+
+**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`: Push successful
+- `1`: Not linked, not logged in, design not active, or push failed
+
+---
+
+### `vention link`
+
+**Description:** Link the current directory to a design + app without pulling files.
+
+**Usage:**
 ```bash
-vention push
-# Requires the same design to be open in MachineBuilder (MachineLogic tab selected).
+vention link
 ```
 
-## Project metadata file
+**Behavior:**
+- Prompts for design and app selection
+- Writes `.machine-code-app-directory-info.json` with link metadata
+- Does not download or modify existing files
+
+**Use case:** Useful when you already have the app files and just want to establish the connection for push operations.
 
-The CLI stores link info in `.machine-code-app-directory-info.json` at the project root:
+**Exit codes:**
+- `0`: Link successful
+- `1`: Not logged in, no active design found, or link failed
+
+---
+
+### Link Metadata File
+
+**Location:** `.machine-code-app-directory-info.json` (project root)
+
+**Schema:**
 ```json
 {
   "appName": "My App",
@@ -91,27 +270,67 @@ The CLI stores link info in `.machine-code-app-directory-info.json` at the proje
 }
 ```
 
-## Requirements and limitations
+**Fields:**
+- `appName` (string): Human-readable app name
+- `designId` (number): Unique design identifier
+- `applicationId` (string): Unique application identifier
+- `uuid` (string, optional): App UUID if available
+- `environment` (string): Target environment (e.g., `prod`, `staging`)
+- `lastPulledAt` (ISO 8601 timestamp): Last successful pull time
+- `lastPushedAt` (ISO 8601 timestamp): Last successful push time
+
+---
+
+## 🔍 Troubleshooting & FAQ
+
+### 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 …" (during push)**
+- **Cause:** The directory doesn't have `.machine-code-app-directory-info.json`
+- **Solution:** Run `vention link` or `vention pull` to establish the link
+
+**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)
+  - Rename or delete the conflicting folder
+  - Run `vention link` instead to link without creating a new folder
+
+### FAQ
+
+**Q: Can I use this with code-free MachineLogic programs?**  
+A: No, only MachineLogic Python apps are supported.
+
+**Q: Do I need to keep MachineBuilder open while editing locally?**  
+A: No, you only need MachineBuilder open (with MachineLogic tab active) when running `pull` or `push` commands.
 
-- The MachineLogic tab must be open for the target design (the design must be active) when running pull or push.
-- Only MachineLogic Python apps are supported.
-- The CLI ignores common build artifacts and environments when pushing (see list above).
-- Session storage: Login data is saved to `~/.vention-cli-config.json`.
+**Q: Where are my authentication tokens stored?**  
+A: In `~/.vention-cli-config.json` in your home directory.
 
-## Typical workflow
+**Q: Can I work on multiple apps simultaneously?**  
+A: Yes, each app folder maintains its own link metadata. You can have multiple linked directories.
 
-- Create your app in the web IDE first (MachineLogic Python).
-- Keep MachineBuilder open with the MachineLogic tab selected (design active).
-- Use `vention pull` to get the app locally, edit in your IDE, then `vention push` to update the running app in your active design.
-- Use the MachineLogic UI to run and test.
+**Q: What files are ignored during push?**  
+A: `venv`, `node_modules`, `dist`, `build`, `__pycache__`, `*.egg-info`, and `.machine-code-app-directory-info.json`.
 
-For app structure, deployment, multi-process `project.json`, and HMI guidance see: https://docs.vention.io/docs/machinelogic-python-programming-guide
+**Q: Can I add custom ignore patterns?**  
+A: Not currently. The ignore list is built into the CLI.
 
-## Troubleshooting
+**Q: What happens if I edit the same app in both MachineBuilder and locally?**  
+A: The last push/pull wins. There's no conflict resolution or merging. We recommend using version control (Git) for your local copy.
 
-- “Not logged in. Please run 'vention login' first.” → Run `vention login`.
-- “No active design found …” or “Please open the design and navigate to MachineLogic …” → Open your design in MachineBuilder and select the MachineLogic tab.
-- “This directory is not linked …” during push → Run `vention link` or pull the app first.
-- Push fails with auth errors → Re-run `vention login` (tokens may have expired).
-- Directory already exists when pulling → Either run pull inside the existing project directory or rename/delete the conflicting folder.
+**Q: Does this work with MachineMotion apps?**  
+A: The CLI specifically targets MachineLogic Python apps. For MachineMotion development, see the MachineMotion SDK documentation.
  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vention/vention-cli",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "CLI tool for Vention applications",
   "type": "module",
   "engines": {