@mrpatronz/nexusflow 0.2.13 → 0.2.18

package/.agents/skills/ccc/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: ccc
+description: "This skill should be used when code search is needed (whether explicitly requested or as part of completing a task), when indexing the codebase after changes, or when the user asks about ccc, cocoindex-code, or the codebase index. Trigger phrases include 'search the codebase', 'find code related to', 'update the index', 'ccc', 'cocoindex-code'."
+---
+
+# ccc - Semantic Code Search & Indexing
+
+`ccc` is the CLI for CocoIndex Code, providing semantic search over the current codebase and index management.
+
+## Ownership
+
+The agent owns the `ccc` lifecycle for the current project — initialization, indexing, and searching. Do not ask the user to perform these steps; handle them automatically.
+
+- **Initialization**: If `ccc search` or `ccc index` fails with an initialization error (e.g., "Not in an initialized project directory"), run `ccc init` from the project root directory, then `ccc index` to build the index, then retry the original command.
+- **Index freshness**: Keep the index up to date by running `ccc index` (or `ccc search --refresh`) when the index may be stale — e.g., at the start of a session, or after making significant code changes (new files, refactors, renamed modules). There is no need to re-index between consecutive searches if no code was changed in between.
+- **Installation**: If `ccc` itself is not found (command not found), refer to [management.md](references/management.md) for installation instructions and inform the user.
+
+## Searching the Codebase
+
+To perform a semantic search:
+
+```bash
+ccc search <query terms>
+```
+
+The query should describe the concept, functionality, or behavior to find, not exact code syntax. For example:
+
+```bash
+ccc search database connection pooling
+ccc search user authentication flow
+ccc search error handling retry logic
+```
+
+### Filtering Results
+
+- **By language** (`--lang`, repeatable): restrict results to specific languages.
+
+  ```bash
+  ccc search --lang python --lang markdown database schema
+  ```
+
+- **By path** (`--path`): restrict results to a glob pattern relative to project root. If omitted, defaults to the current working directory (only results under that subdirectory are returned).
+
+  ```bash
+  ccc search --path 'src/api/*' request validation
+  ```
+
+### Pagination
+
+Results default to the first page. To retrieve additional results:
+
+```bash
+ccc search --offset 5 --limit 5 database schema
+```
+
+If all returned results look relevant, use `--offset` to fetch the next page — there are likely more useful matches beyond the first page.
+
+### Working with Search Results
+
+Search results include file paths and line ranges. To explore a result in more detail:
+
+- Use the editor's built-in file reading capabilities (e.g., the `Read` tool) to load the matched file and read lines around the returned range for full context.
+- When working in a terminal without a file-reading tool, use `sed -n '<start>,<end>p' <file>` to extract a specific line range.
+
+## Settings
+
+To view or edit embedding model configuration, include/exclude patterns, or language overrides, see [settings.md](references/settings.md).
+
+## Management & Troubleshooting
+
+For installation, initialization, daemon management, troubleshooting, and cleanup commands, see [management.md](references/management.md).

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

@@ -0,0 +1,110 @@
+# ccc Management
+
+## Installation
+
+Install CocoIndex Code via pipx. Two install styles:
+
+```bash
+pipx install 'cocoindex-code[full]'      # batteries included (local embeddings via sentence-transformers)
+pipx install cocoindex-code              # slim (LiteLLM-only; requires a cloud embedding provider + API key)
+```
+
+The `[full]` extra pulls in `sentence-transformers` so the first-run default (local embeddings, no API key) works out of the box. The slim install is for environments where you don't want the torch/transformers deps and plan to use a LiteLLM-supported cloud provider instead.
+
+To upgrade to the latest version:
+
+```bash
+pipx upgrade cocoindex-code
+```
+
+After installation, the `ccc` command is available globally.
+
+## Project Initialization
+
+Run from the root directory of the project to index:
+
+```bash
+ccc init
+```
+
+**First run (global settings don't exist yet)** — `ccc init` prompts interactively for the embedding provider (sentence-transformers / litellm) and model, then runs a one-off test embed via the daemon to confirm the model works. Accept the defaults for the sentence-transformers path, or pick litellm and enter a model identifier.
+
+**Subsequent runs** (global settings already exist) — prompts are skipped; only project settings and `.gitignore` are set up.
+
+To skip the interactive prompts on the first run (e.g. in a script or container), pass `--litellm-model MODEL`:
+
+```bash
+ccc init --litellm-model openai/text-embedding-3-small
+```
+
+This is also the only way to pick a LiteLLM model when stdin isn't a TTY and you've done a slim install.
+
+`ccc init` creates:
+- `~/.cocoindex_code/global_settings.yml` (user-level, embedding config + env vars).
+- `.cocoindex_code/settings.yml` (project-level, include/exclude patterns).
+
+If `.git` exists in the directory, `.cocoindex_code/` is automatically added to `.gitignore`.
+
+Use `-f` to skip the confirmation prompt if `ccc init` detects a potential parent project root.
+
+After initialization, edit the settings files if needed (see [settings.md](settings.md) for format details), then run `ccc index` to build the initial index. If the model test printed `[FAIL]` during `init`, edit `global_settings.yml` (and optionally add API keys under the commented `envs:` block) and verify with `ccc doctor` before indexing.
+
+## Troubleshooting
+
+### Diagnostics
+
+Run `ccc doctor` to check system health end-to-end:
+
+```bash
+ccc doctor
+```
+
+This checks global settings, daemon status, embedding model (runs a test embedding), and — if run from within a project — file matching (walks files using the same logic as the indexer) and index status. Results stream incrementally. Always points to `daemon.log` at the end for further investigation.
+
+### Checking Project Status
+
+To view the current project's index status:
+
+```bash
+ccc status
+```
+
+This shows whether indexing is ongoing and index statistics.
+
+### Daemon Management
+
+The daemon starts automatically on first use. To check its status:
+
+```bash
+ccc daemon status
+```
+
+This shows whether the daemon is running, its version, uptime, and loaded projects.
+
+To restart the daemon (useful if it gets into a bad state):
+
+```bash
+ccc daemon restart
+```
+
+To stop the daemon:
+
+```bash
+ccc daemon stop
+```
+
+## Cleanup
+
+To reset a project's index (removes databases, keeps settings):
+
+```bash
+ccc reset
+```
+
+To fully remove all CocoIndex Code data for a project (including settings):
+
+```bash
+ccc reset --all
+```
+
+Both commands prompt for confirmation. Use `-f` to skip.

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

@@ -0,0 +1,126 @@
+# 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/workflows/ci.yml

@@ -0,0 +1,44 @@
+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

@@ -0,0 +1,53 @@
+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

@@ -0,0 +1,67 @@
+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

@@ -0,0 +1,65 @@
+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

@@ -0,0 +1,61 @@
+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/GETTING_STARTED.md

@@ -107,3 +107,8 @@ Here is a summary of the command-line interface:
 | **`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. |