@mrpatronz/nexusflow 0.2.19 → 1.3.0

package/.agents/skills/ccc/references/settings.md

@@ -1,126 +0,0 @@
-# ccc Settings
-
-Configuration lives in two YAML files, both created automatically by `ccc init`.
-
-## User-Level Settings (`~/.cocoindex_code/global_settings.yml`)
-
-Shared across all projects. Controls the embedding model and extra environment variables for the daemon.
-
-```yaml
-embedding:
-  provider: sentence-transformers   # or "litellm" (default when provider is omitted)
-  model: Snowflake/snowflake-arctic-embed-xs
-  device: mps                       # optional: cpu, cuda, mps (auto-detected if omitted)
-  min_interval_ms: 300              # optional: pace LiteLLM embedding requests to reduce 429s; defaults to 5 for LiteLLM
-
-envs:                               # extra environment variables for the daemon
-  OPENAI_API_KEY: your-key          # only needed if not already in the shell environment
-```
-
-### Fields
-
-| Field | Description |
-|-------|-------------|
-| `embedding.provider` | `sentence-transformers` for local models, `litellm` (or omit) for cloud/remote models |
-| `embedding.model` | Model identifier — format depends on provider (see examples below) |
-| `embedding.device` | Optional. `cpu`, `cuda`, or `mps`. Auto-detected if omitted. Only relevant for `sentence-transformers`. |
-| `embedding.min_interval_ms` | Optional. Minimum delay between LiteLLM embedding requests in milliseconds. Defaults to `5` for LiteLLM and is ignored by `sentence-transformers`. Set explicitly to override the default. |
-| `envs` | Key-value map of environment variables injected into the daemon. Use for API keys not already in the shell environment. |
-
-### Embedding Model Examples
-
-**Local (sentence-transformers, no API key needed):**
-
-```yaml
-embedding:
-  provider: sentence-transformers
-  model: Snowflake/snowflake-arctic-embed-xs        # default, lightweight
-```
-
-```yaml
-embedding:
-  provider: sentence-transformers
-  model: nomic-ai/CodeRankEmbed                     # better code retrieval, needs GPU (~1 GB VRAM)
-```
-
-**Ollama (local):**
-
-```yaml
-embedding:
-  model: ollama/nomic-embed-text
-```
-
-**OpenAI:**
-
-```yaml
-embedding:
-  model: text-embedding-3-small
-  min_interval_ms: 300
-envs:
-  OPENAI_API_KEY: your-api-key
-```
-
-**Gemini:**
-
-```yaml
-embedding:
-  model: gemini/gemini-embedding-001
-envs:
-  GEMINI_API_KEY: your-api-key
-```
-
-**Voyage (code-optimized):**
-
-```yaml
-embedding:
-  model: voyage/voyage-code-3
-envs:
-  VOYAGE_API_KEY: your-api-key
-```
-
-For the full list of supported cloud providers and model identifiers, see [LiteLLM Embedding Models](https://docs.litellm.ai/docs/embedding/supported_embedding).
-
-### Important
-
-Switching embedding models changes vector dimensions — you must re-index after changing the model:
-
-```bash
-ccc reset && ccc index
-```
-
-## Project-Level Settings (`<project>/.cocoindex_code/settings.yml`)
-
-Per-project. Controls which files to index. Created by `ccc init` and automatically added to `.gitignore`.
-
-```yaml
-include_patterns:
-  - "**/*.py"
-  - "**/*.js"
-  - "**/*.ts"
-  # ... (sensible defaults for 28+ file types)
-
-exclude_patterns:
-  - "**/.*"              # hidden directories
-  - "**/__pycache__"
-  - "**/node_modules"
-  - "**/dist"
-  # ...
-
-language_overrides:
-  - ext: inc             # treat .inc files as PHP
-    lang: php
-```
-
-### Fields
-
-| Field | Description |
-|-------|-------------|
-| `include_patterns` | Glob patterns for files to index. Defaults cover common languages (Python, JS/TS, Rust, Go, Java, C/C++, C#, SQL, Shell, Markdown, PHP, Lua, etc.). |
-| `exclude_patterns` | Glob patterns for files/directories to skip. Defaults exclude hidden dirs, `node_modules`, `dist`, `__pycache__`, `vendor`, etc. |
-| `language_overrides` | List of `{ext, lang}` pairs to override language detection for specific file extensions. |
-
-### Editing Tips
-
-- To index additional file types, append glob patterns to `include_patterns` (e.g. `"**/*.proto"`).
-- To exclude a directory, append to `exclude_patterns` (e.g. `"**/generated"`).
-- After editing, run `ccc index` to re-index with the new settings.

package/.github/dependabot.yml

@@ -1,52 +0,0 @@
-version: 2
-updates:
-  # 1. Root npm dependencies
-  - package-ecosystem: "npm"
-    directory: "/"
-    schedule:
-      interval: "daily"
-      time: "03:00"
-    open-pull-requests-limit: 10
-    reviewers:
-      - "antan87"
-    groups:
-      root-minor-patch:
-        patterns:
-          - "*"
-        update-types:
-          - "minor"
-          - "patch"
-
-  # 2. GUI npm dependencies
-  - package-ecosystem: "npm"
-    directory: "/gui"
-    schedule:
-      interval: "daily"
-      time: "03:00"
-    open-pull-requests-limit: 10
-    reviewers:
-      - "antan87"
-    groups:
-      gui-minor-patch:
-        patterns:
-          - "*"
-        update-types:
-          - "minor"
-          - "patch"
-
-  # 3. VS Code Extension npm dependencies
-  - package-ecosystem: "npm"
-    directory: "/extension"
-    schedule:
-      interval: "daily"
-      time: "03:00"
-    open-pull-requests-limit: 10
-    reviewers:
-      - "antan87"
-    groups:
-      extension-minor-patch:
-        patterns:
-          - "*"
-        update-types:
-          - "minor"
-          - "patch"

package/.github/workflows/ci.yml

@@ -1,44 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  build-and-test:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-
-      - name: Install Dependencies
-        run: npm ci
-
-      - name: Install GUI Dependencies
-        run: npm ci --prefix gui
-
-      - name: Install Extension Dependencies
-        run: npm ci --prefix extension
-
-      - name: Build Project
-        run: npm run build
-
-      - name: Compile VS Code Extension
-        run: npm run extension:compile
-
-      - name: Run Tests
-        run: npm test
-
-      - name: Install Playwright Browsers
-        run: npx playwright install chromium --with-deps
-        working-directory: gui
-
-      - name: Run GUI E2E Tests
-        run: npm run test:gui

package/.github/workflows/dependabot-merge.yml

@@ -1,53 +0,0 @@
-name: Dependabot Auto-Merge and Version Bump
-
-on:
-  pull_request_target:
-    types: [opened, reopened, synchronize]
-    branches: [main]
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  dependabot:
-    runs-on: ubuntu-latest
-    if: github.actor == 'dependabot[bot]'
-    steps:
-      - name: Checkout PR branch
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event.pull_request.head.ref }}
-          fetch-depth: 0
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: Bump Version
-        run: |
-          # Configure Git
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          
-          # Fetch main to compare versions
-          git fetch origin main:main
-          
-          MAIN_VERSION=$(git show main:package.json | node -e "console.log(JSON.parse(require('fs').readFileSync(0, 'utf-8')).version)")
-          PR_VERSION=$(node -e "console.log(JSON.parse(require('fs').readFileSync('package.json', 'utf-8')).version)")
-          
-          if [ "$PR_VERSION" = "$MAIN_VERSION" ]; then
-            echo "Version has not been bumped yet. Bumping patch version..."
-            npm version patch --no-git-tag-version
-            git add package.json package-lock.json
-            git commit -m "chore: bump version for dependabot update"
-            git push origin HEAD:${{ github.event.pull_request.head.ref }}
-          else
-            echo "Version is already bumped ($PR_VERSION vs main $MAIN_VERSION). Skipping bump."
-          fi
-
-      - name: Enable Auto-Merge
-        run: gh pr merge --auto --merge "${{ github.event.pull_request.html_url }}"
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/release-desktop.yml

@@ -1,67 +0,0 @@
-name: Release — Desktop Installer
-
-on:
-  workflow_run:
-    workflows: [CI]
-    branches: [main]
-    types: [completed]
-
-permissions:
-  contents: write
-
-jobs:
-  build-installer:
-    if: github.event.workflow_run.conclusion == 'success'
-    runs-on: windows-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event.workflow_run.head_sha }}
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          registry-url: 'https://registry.npmjs.org/'
-
-      - name: Install Dependencies
-        run: npm ci
-
-      - name: Install GUI Dependencies
-        run: npm ci --prefix gui
-
-      - name: Install Desktop Dependencies
-        run: npm ci --prefix desktop
-
-      - name: Build Desktop GUI
-        run: npm run build --prefix gui
-
-      - name: Build Desktop Binaries
-        run: npm run build --prefix desktop
-
-      - name: Build Standalone Installer
-        run: npm run build:installer --prefix desktop
-
-      - name: Check npm version
-        id: check-version
-        shell: bash
-        run: |
-          VERSION=$(node -e "console.log(require('./package.json').version)")
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-          if npm info @mrpatronz/nexusflow@$VERSION --json >/dev/null 2>&1; then
-            echo "is_new=false" >> $GITHUB_OUTPUT
-            echo "Version $VERSION already published. Skipping installer upload."
-          else
-            echo "is_new=true" >> $GITHUB_OUTPUT
-            echo "Version $VERSION is new."
-          fi
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Upload installer to GitHub Release
-        if: steps.check-version.outputs.is_new == 'true'
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: v${{ steps.check-version.outputs.version }}
-          files: desktop/dist-installer-output/NexusFlowSetup.exe

package/.github/workflows/release-npm.yml

@@ -1,65 +0,0 @@
-name: Release — npm
-
-on:
-  workflow_run:
-    workflows: [CI]
-    branches: [main]
-    types: [completed]
-
-permissions:
-  contents: write
-
-jobs:
-  publish-npm:
-    if: github.event.workflow_run.conclusion == 'success'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event.workflow_run.head_sha }}
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          registry-url: 'https://registry.npmjs.org/'
-
-      - name: Install Dependencies
-        run: npm ci
-
-      - name: Install GUI Dependencies
-        run: npm ci --prefix gui
-
-      - name: Build Project
-        run: npm run build
-
-      - name: Check version
-        id: check-version
-        run: |
-          VERSION=$(node -e "console.log(require('./package.json').version)")
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-          if npm info @mrpatronz/nexusflow@$VERSION --json >/dev/null 2>&1; then
-            echo "is_new=false" >> $GITHUB_OUTPUT
-            echo "Version $VERSION is already published on npm. Skipping."
-          else
-            echo "is_new=true" >> $GITHUB_OUTPUT
-            echo "Version $VERSION is new."
-          fi
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Publish to npm
-        if: steps.check-version.outputs.is_new == 'true'
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Create GitHub Release
-        if: steps.check-version.outputs.is_new == 'true'
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: v${{ steps.check-version.outputs.version }}
-          name: Release v${{ steps.check-version.outputs.version }}
-          generate_release_notes: true
-          target_commitish: ${{ github.event.workflow_run.head_sha }}

package/.github/workflows/release-vscode.yml

@@ -1,61 +0,0 @@
-name: Release — VS Code Extension
-
-on:
-  workflow_run:
-    workflows: [CI]
-    branches: [main]
-    types: [completed]
-
-permissions:
-  id-token: write   # required for OIDC token request
-  contents: read
-
-jobs:
-  publish-extension:
-    if: github.event.workflow_run.conclusion == 'success'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event.workflow_run.head_sha }}
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-
-      - name: Install Extension Dependencies
-        run: npm ci --prefix extension
-
-      - name: Azure Login (OIDC — no stored secrets)
-        uses: azure/login@v2
-        with:
-          client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          allow-no-subscriptions: true
-
-      - name: Check extension version
-        id: check-version
-        working-directory: extension
-        run: |
-          VERSION=$(node -e "console.log(require('./package.json').version)")
-          echo "version=$VERSION" >> $GITHUB_OUTPUT
-          PUBLISHED=$(npx vsce show nexusflow.nexusflow-vscode --json 2>/dev/null \
-            | node -e "
-                const d=require('fs').readFileSync(0,'utf8');
-                try { process.exit(JSON.parse(d).versions?.['$VERSION'] ? 0 : 1); }
-                catch { process.exit(1); }
-              " && echo "true" || echo "false")
-          if [ "$PUBLISHED" = "true" ]; then
-            echo "is_new=false" >> $GITHUB_OUTPUT
-            echo "Extension version $VERSION already published. Skipping."
-          else
-            echo "is_new=true" >> $GITHUB_OUTPUT
-            echo "Extension version $VERSION is new."
-          fi
-
-      - name: Publish to VS Code Marketplace
-        if: steps.check-version.outputs.is_new == 'true'
-        working-directory: extension
-        run: npx vsce publish --no-dependencies --azure-credential

package/.vscode/launch.json

@@ -1,17 +0,0 @@
-{
-  "version": "0.2.0",
-  "configurations": [
-    {
-      "name": "Launch Extension",
-      "type": "extensionHost",
-      "request": "launch",
-      "args": [
-        "--extensionDevelopmentPath=${workspaceRoot}/extension"
-      ],
-      "outFiles": [
-        "${workspaceRoot}/extension/dist/**/*.js"
-      ],
-      "preLaunchTask": "npm: extension-compile"
-    }
-  ]
-}

package/.vscode/tasks.json

@@ -1,17 +0,0 @@
-{
-  "version": "2.0.0",
-  "tasks": [
-    {
-      "type": "npm",
-      "script": "extension:compile",
-      "group": {
-        "kind": "build",
-        "isDefault": true
-      },
-      "label": "npm: extension-compile",
-      "problemMatcher": [
-        "$tsc"
-      ]
-    }
-  ]
-}

package/GETTING_STARTED.md

@@ -1,114 +0,0 @@
-# NexusFlow — Getting Started Guide
-
-Welcome to **NexusFlow**! This guide will walk you through the system, explain its core workflows, and show you how to leverage multi-repository workspaces and agentic orchestration to accelerate feature development.
-
----
-
-## 💡 What is NexusFlow?
-
-When developing complex features in modern systems, you often need to touch multiple repositories simultaneously (e.g., modifying a shared package, updating a backend REST API, and updating a frontend application). 
-
-Traditional AI assistant setups only give the assistant context of a single repository. NexusFlow solves this by:
-1. **Grouping Repositories**: Creating a dedicated workspace using **git worktrees** on a unified feature branch name.
-2. **Generating AI Context**: Writing specialized configurations (`CLAUDE.md`, `AGENTS.md`, Copilot guidelines, and Cursor rules) that outline the workspace architecture.
-3. **Smart Codebase Analysis**: Scanning tech stacks, ports, and API endpoints so the AI instantly understands the codebase boundaries.
-4. **Service Orchestration**: Running, stopping, and logging all projects simultaneously from a single place.
-
----
-
-## 🚀 Step-by-Step Workflow
-
-Here is how to get started with your first feature workspace.
-
-```mermaid
-flowchart TD
-    A["1. Run Web GUI or CLI"] --> B["2. Fill Feature Details & Pick Repos"]
-    B --> C["3. Workspace Created\n(Git Worktrees + Context generated)"]
-    C --> D["4. AI Agent Initializes\n(Fills nexusflow-overview.md + questions)"]
-    D --> E["5. Confirm Assumptions & Spin up services"]
-```
-
-### 1. Initialize NexusFlow
-First, initialize the default configuration on your machine:
-```bash
-nexusflow init
-```
-This sets up `~/.nexusflow/config.json` with default settings:
-* **Development Directory**: Where your git repositories are located (defaults to `~/dev`).
-* **Workspaces Directory**: Where your worktrees will be created (defaults to `~/dev/workspaces`).
-
----
-
-### 2. Launch the Web Dashboard
-NexusFlow comes with a rich, interactive Web Dashboard. Launch it by running:
-```bash
-nexusflow ui
-```
-This starts the local backend server on port `3000` and automatically opens the browser.
-
----
-
-### 3. Create a Feature Workspace
-On the dashboard (or via the `nexusflow create` CLI command):
-1. **Branch name**: Enter your branch name (e.g. `feature/user-profiles`). Slashes are supported!
-2. **Description**: Describe the feature you are building. The AI assistant will read this to compile the plan.
-3. **Pick Repositories**: Choose which repositories you need to modify or reference.
-4. **Assistant Selection**: Select which AI coding assistants you plan to use (Claude Code, Antigravity, Cursor, etc.).
-5. **Click Build Workspace**: NexusFlow will fetch origin updates, create local branches, spin up git worktrees under `workspaces/feature/user-profiles`, run tech analyses, and write context configurations.
-
----
-
-### 4. The Agentic Initialization (Universal Context)
-Once the workspace is built, open it in your preferred AI assistant. 
-
-Whichever AI harness you use, **the agent's very first instructions** are to:
-1. Scan the workspace projects.
-2. Create a universal reference file: **`nexusflow-overview.md`**.
-3. Write down its assumptions of what each project does, how they interact, and their responsibilities.
-4. List any **Clarifying Questions** it needs you to answer before coding.
-
-**Your Action**: Review the generated `nexusflow-overview.md`, answer the assistant's questions directly in the chat or file, and confirm its assumptions. This ensures you and the agent are aligned before a single line of code is modified.
-
----
-
-### 5. Orchestrate Local Services
-You don't need to open five terminal windows to start your backend, frontend, databases, or libraries.
-
-**On the Web Dashboard:**
-* Expand your active workspace to see all detected services (e.g. node scripts, dotnet servers, python hosts).
-* Click **Start All** to spin them up.
-* View aggregate console streams inside the tabbed retro-terminal output screen.
-
-**Via the CLI:**
-* Navigate to your workspace directory and run:
-  ```bash
-  nexusflow start
-  ```
-* Check logs or stop services with:
-  ```bash
-  nexusflow logs
-  nexusflow stop
-  ```
-
----
-
-## 🛠️ CLI Reference
-
-Here is a summary of the command-line interface:
-
-| Command | Usage | Description |
-| :--- | :--- | :--- |
-| **`nexusflow ui`** | `nexusflow ui [-p <port>]` | Starts the backend Hono API server and opens the GUI Dashboard. |
-| **`nexusflow create`** | `nexusflow create` | Launches the interactive step-by-step terminal wizard to build a workspace. |
-| **`nexusflow list`** | `nexusflow list` / `nexusflow ls` | Lists all active feature workspaces discovered on your machine. |
-| **`nexusflow open`** | `nexusflow open` | Prompts you to pick an active workspace and opens it in your editor. |
-| **`nexusflow start`** | `nexusflow start [path]` | Starts background processes for all projects in the workspace. |
-| **`nexusflow stop`** | `nexusflow stop [path]` | Kills all running processes for the workspace. |
-| **`nexusflow logs`** | `nexusflow logs [path] [-n <lines>]` | Tails output log files for all service processes in the workspace. |
-| **`nexusflow status`** | `nexusflow status [path]` | Displays running/stopped statuses and PIDs for each service. |
-| **`nexusflow init`** | `nexusflow init` | Creates or edits the global config file. |
-| **`nexusflow diff`** | `nexusflow diff` | Displays pending code changes across all active workspace repositories. |
-| **`nexusflow commit`** | `nexusflow commit` | Automates cross-repository git commit and branch pushes in the workspace. |
-| **`nexusflow sync`** | `nexusflow sync` | Syncs and rebases all workspace worktrees with default base branches. |
-| **`nexusflow refresh`**| `nexusflow refresh` | Regenerates architecture maps, task plans, and AI context files. |
-| **`nexusflow doctor`** | `nexusflow doctor` | Assesses and reports diagnostics of the current workspace setup. |