vectorforce 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to the `vectorforce` package will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.2.0] - 2026-10-31
+
+### Added
+- **Unified Remote Sync Commands (`vf remote`, `vf push`, `vf pull`)**:
+  - `vf remote set <URL> [--key <KEY>] [--project <ID>]`: Configure remote cloud synchronization endpoint in `.vectorforce/config.json`.
+  - `vf push`: Read local `.vectorforce/vectorforce.db`, wrap tasks & checkpoints in End-to-End Encrypted (E2EE) envelopes (`AES-256-GCM` + `X25519` + `Ed25519`), and push to VectorForce Cloud / Modal.com.
+  - `vf pull`: Pull the latest encrypted envelope from the cloud, verify the `Ed25519` digital signature, decrypt via `X25519` + `AES-256-GCM`, reconcile into local SQLite, and synthesize the **Meta Muse (`muse-spark-open`)** reasoning briefing.
+- **VectorForce Cloud & Modal.com Serverless Deployment**:
+  - Dedicated cloud sync server supporting multi-project registries, B2B2B sub-customer tenant isolation, and developer task assignment boards.
+  - One-command deployment to Modal.com (`modal_app.py`) with persistent `modal.Volume` storage for encrypted SQLite WAL databases.
+- **Interactive Team Handoff & Studio UI Upgrades**:
+  - Added direct browser download of `.vfhandoff.json` bundle files.
+  - Added interactive in-browser **Import & Reconcile Teammate Handoff Package** modal (`POST /api/handoff/import`) with SHA-256 manifest validation.
+  - Automatic resolution of active tasks and divergent checkpoint heads in Studio export endpoints.
+- **Automated npm Lifecycle Hooks**:
+  - Added `prepublishOnly` script in `package.json` to ensure `npm --prefix studio run build` and all 75 tests run automatically before every `npm publish`.
+
+### Changed
+- **CLI Commands Simplified**: Unified remote cloud sync under the standard `vf` command (following the `git remote`, `git push`, `git pull` mental model).
+- **Workspace Agent Protocols**: Upgraded workspace-level `AGENTS.md` and role definitions for `vectorforce-architect`, `vectorforce-auditor`, and `vectorforce-samples-builder`.
+
+### Fixed
+- Fixed `TypeError` in `TeamHandoffView.jsx` when resolving checkpoints with differing `id` vs `checkpoint_id` shapes.
+- Fixed divergent leaf head resolution in `/api/handoff/export` by auto-selecting the latest timestamped checkpoint.
+- Fixed ephemeral key generation in serverless environments by persisting machine identities in durable SQLite storage.
+
+---
+
+## [0.1.0] - 2026-10-27
+
+### Added
+- Initial public release of VectorForce — "Git for AI Context".
+- Zero-dependency local SQLite WAL persistence engine (`node:sqlite`).
+- Model Context Protocol (MCP) server over JSON-RPC 2.0 stdio with 9 core tools (`save_checkpoint`, `get_resume_briefing`, `check_workspace_drift`, `reason_about_task`, `list_tasks`, `set_document_policy`, `export_handoff`, `import_handoff`, `get_timeline`).
+- Automatic multi-harness configuration generators for Google Antigravity, Claude Code, Command Code, Meta Muse, and OpenAI Codex.
+- Multi-provider AI reasoning engine supporting Meta Muse (`muse-spark-1.3`, `muse-spark-open`), Fireworks AI, OpenRouter, Local Ollama, OpenAI, Anthropic, and custom BYOK endpoints.
+- Local VectorForce Studio Web UI (`vf studio`) on port 3210 with interactive SVG architecture dependency and blast-radius graph.

package/README.md

@@ -73,7 +73,24 @@ node bin/vf.js checkpoint --task auth-module \
   --doc "AGENTS.md"
 ```
 
-### 5. Reason Over Context (AI Engineering Memory)
+### 5. Multi-Machine & Team Cloud Sync (`vf remote`, `vf push`, `vf pull`)
+
+VectorForce follows the Git mental model for sharing context between two computers or across a team using Zero-Knowledge End-to-End Encryption (`X25519` + `AES-256-GCM` + `Ed25519`):
+
+```bash
+# 1. Connect local workspace to your Cloud Remote once:
+node bin/vf.js remote set https://omprakash-pce2011--vectorforce-cloud-vectorforce-cloud-web.modal.run \
+  --key vf_live_sub_98a7bc65f012e4d9 \
+  --project proj-bistro-pos
+
+# 2. Push local checkpoints & tasks to Cloud (E2EE):
+node bin/vf.js push
+
+# 3. Pull & reconcile context on Computer 2 (reconciles into SQLite & runs Meta Muse reasoning):
+node bin/vf.js pull
+```
+
+### 6. Reason Over Context (AI Engineering Memory)
 
 VectorForce prioritizes **Meta Muse (`muse-spark-1.3`)** and the open-weights **Meta Muse Spark Open (`muse-spark-open` • 1M token context window)** as its **#1 reasoning models**, while also supporting **Fireworks AI**, **OpenRouter**, **Local Ollama**, **OpenAI / Codex**, **Anthropic Claude**, and any **Custom BYOK** OpenAI-compatible endpoint:
 

package/bin/vf.js

@@ -276,8 +276,8 @@ function parseFlags(args) {
 }
 
 function getRemoteConfig(cwd) {
-  const defaultUrl = process.env.VF_CLOUD_URL || 'https://omprakash-pce2011--vectorforce-cloud-vectorforce-cloud-web.modal.run';
-  const defaultKey = process.env.VF_SUBSCRIPTION_KEY || 'vf_live_sub_98a7bc65f012e4d9';
+  const defaultUrl = process.env.VF_CLOUD_URL || '';
+  const defaultKey = process.env.VF_SUBSCRIPTION_KEY || '';
   const cfgPath = join(cwd, '.vectorforce', 'config.json');
   try {
     if (existsSync(cfgPath)) {
@@ -285,14 +285,14 @@ function getRemoteConfig(cwd) {
       return {
         remoteUrl: (parsed.remoteUrl || defaultUrl).replace(/\/+$/, ''),
         subscriptionKey: parsed.subscriptionKey || defaultKey,
-        remoteProjectId: parsed.remoteProjectId || 'proj-bistro-pos'
+        remoteProjectId: parsed.remoteProjectId || 'default'
       };
     }
   } catch {}
   return {
     remoteUrl: defaultUrl.replace(/\/+$/, ''),
     subscriptionKey: defaultKey,
-    remoteProjectId: 'proj-bistro-pos'
+    remoteProjectId: 'default'
   };
 }
 
@@ -940,7 +940,11 @@ VectorForce Harness Configuration:
       case 'push': {
         const remote = getRemoteConfig(cwd);
         const targetUrl = (flags.url || remote.remoteUrl).replace(/\/+$/, '');
-        const remoteProjectId = flags.project || remote.remoteProjectId || 'proj-bistro-pos';
+        if (!targetUrl) {
+          console.error('Error: Remote URL is not configured. Run "vf remote set <CLOUD_URL> --key <SUBSCRIPTION_KEY>" first.');
+          process.exit(1);
+        }
+        const remoteProjectId = flags.project || remote.remoteProjectId || 'default';
         const project = projectService.getProjectForWorkspace(cwd);
         const tasks = store.listTasks(project.project_id);
         const machineId = `${hostname()}-local`;
@@ -1008,7 +1012,11 @@ VectorForce Harness Configuration:
       case 'pull': {
         const remote = getRemoteConfig(cwd);
         const targetUrl = (flags.url || remote.remoteUrl).replace(/\/+$/, '');
-        const remoteProjectId = flags.project || remote.remoteProjectId || 'proj-bistro-pos';
+        if (!targetUrl) {
+          console.error('Error: Remote URL is not configured. Run "vf remote set <CLOUD_URL> --key <SUBSCRIPTION_KEY>" first.');
+          process.exit(1);
+        }
+        const remoteProjectId = flags.project || remote.remoteProjectId || 'default';
 
         console.log(`🔓 Pulling & Decrypting latest context from ${targetUrl} ...`);
         const res = await fetch(`${targetUrl}/api/cloud/sync/pull`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vectorforce",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Portable engineering context platform - Git for AI context",
   "type": "module",
   "main": "src/index.js",
@@ -9,6 +9,8 @@
     "vectorforce": "bin/vf.js"
   },
   "scripts": {
+    "build": "npm --prefix studio run build",
+    "prepublishOnly": "npm --prefix studio run build && npm test",
     "test": "node --test \"test/**/*.test.js\"",
     "test:practical": "node scripts/practical-test-env.js"
   },
@@ -20,11 +22,7 @@
     "src",
     "studio/dist",
     "AGENTS.md",
-    "commandcode.json",
-    "musecode.json",
-    "codex.json",
-    ".agents",
-    ".codex"
+    "CHANGELOG.md"
   ],
   "keywords": [
     "context",

package/src/studio/server.js

@@ -290,7 +290,7 @@ export function createStudioServer({
             authorMap.set(name, {
               id: name.toLowerCase().replace(/[^a-z0-9]/g, '-'),
               name,
-              role: name === 'omprakashprajapat' ? 'Lead Architect / Owner' : 'Collaborator',
+              role: 'Contributor',
               harness: cp.author?.harness || 'cli',
               tasks: new Set(),
               checkpointsCount: 0,

package/.agents/agents/AGENTS.md

@@ -1,12 +0,0 @@
-# Workspace Agents Directory (`.agents/agents/`)
-
-This directory defines workspace-scoped agents for **VectorForce** (alongside the project-root [`AGENTS.md`](../../AGENTS.md)).
-
-## Registered Workspace Agents
-
-| Agent Name | File | Role & Responsibility |
-| :--- | :--- | :--- |
-| **`vectorforce-architect`** | [`vectorforce-architect.md`](vectorforce-architect.md) | Upgrades core VectorForce services (`src/operations/*`), SQLite WAL store (`src/storage/sqlite-store.js`), MCP tools (`src/mcp/mcp-server.js`), AI providers (`src/providers/llm-provider.js`), CLI (`bin/vf.js`), and Studio UI (`studio/`) while enforcing zero runtime dependencies. |
-| **`vectorforce-samples-builder`** | [`vectorforce-samples-builder.md`](vectorforce-samples-builder.md) | Builds runnable multi-agent workflows, cross-harness reference architectures, and integration demos inside [`samples/`](../../samples/README.md). |
-| **`vectorforce-auditor`** | [`vectorforce-auditor.md`](vectorforce-auditor.md) | Verifies security boundaries, allowlist limits (`AGENTS.md < 8192` bytes), HMAC-SHA256 handoff integrity, and runs `npm test` + `npm run test:practical`. |
-

package/.agents/agents/vectorforce-architect.md

@@ -1,35 +0,0 @@
----
-name: vectorforce-architect
-description: >-
-  Specialized production architect for upgrading VectorForce core services, SQLite WAL storage, MCP tools, AI reasoning providers, and VectorForce Studio while enforcing zero runtime dependencies.
-tools:
-  - read_file
-  - write_file
-  - edit_file
-  - run_command
----
-
-# VectorForce Production Architect (`vectorforce-architect`)
-
-You are the **VectorForce Production Architect**, responsible for designing and implementing production-grade upgrades across the VectorForce engine (`src/`), CLI (`bin/vf.js`), MCP server (`src/mcp/mcp-server.js`), and Studio UI (`src/studio/server.js`, `studio/`).
-
-## Non-Negotiable Architectural Invariants
-
-1. **Zero External Runtime Dependencies**:
-   - All backend code (`bin/`, `src/`) must use **only** Node.js built-in modules (`node:sqlite`, `node:http`, `node:crypto`, `node:fs`, `node:path`, `node:child_process`).
-   - Never add runtime dependencies to the root `package.json`.
-2. **Strict Separation of `claims` vs `evidence`**:
-   - Human/AI assertions (`goals`, `constraints`, `decisions`, `next_steps`) live in `checkpoint.claims`.
-   - Verifiable observations (Git commit SHA, branch, dirty status, SHA-256 document digests) live in `checkpoint.evidence`.
-3. **Workspace Containment & Allowlist Enforcement**:
-   - Every file operation must pass through `Authorizer` (`src/policy/authorizer.js`).
-   - Reject symlinks, absolute paths, and `..` traversal sequences.
-4. **Full-Stack Tool Registration Checklist**:
-   When adding or upgrading a VectorForce capability:
-   - **Storage**: Add/update SQLite tables or queries in `src/storage/sqlite-store.js`.
-   - **Operations**: Add service method in `src/operations/*-service.js`.
-   - **MCP Bridge**: Register JSON-RPC tool schema and handler in `src/mcp/mcp-server.js`.
-   - **CLI**: Add command flag handling and help text in `bin/vf.js`.
-   - **SDK Export**: Export any new classes/types in `src/index.js`.
-   - **Tests**: Add unit tests in `test/` and verify `npm test` + `npm run test:practical`.
-

package/.agents/agents/vectorforce-auditor.md

@@ -1,25 +0,0 @@
----
-name: vectorforce-auditor
-description: >-
-  Specialized security, workspace drift, and cross-OS verification auditor for VectorForce checkpoints, HMAC-SHA256 handoff packages, and test suites.
-tools:
-  - read_file
-  - run_command
----
-
-# VectorForce Security & Continuity Auditor (`vectorforce-auditor`)
-
-You are the **VectorForce Security & Continuity Auditor**, responsible for verifying security invariants, cross-OS compatibility, and checkpoint/handoff integrity across the workspace.
-
-## Verification Checklist
-
-1. **Automated Unit & Security Suite**:
-   - Run `npm test` and ensure all tests pass with `fail 0`.
-2. **Practical 7-Stage E2E Simulation**:
-   - Run `npm run test:practical` (`node scripts/practical-test-env.js`) to validate Git + CLI + live MCP stdio + HMAC-SHA256 handoff + tamper rejection + drift detection.
-3. **Workspace Health & Policy Check**:
-   - Run `node bin/vf.js status` and `node bin/vf.js policy list`.
-   - Ensure `AGENTS.md` at the repository root remains `< 8192` bytes (`wc -c AGENTS.md`) so it can always be collected as allowlisted document evidence.
-4. **Checkpoint Continuity**:
-   - Verify that every completed phase ends with a committed VectorForce checkpoint (`node bin/vf.js checkpoint --task <id> ... --doc "AGENTS.md"`).
-

package/.agents/agents/vectorforce-samples-builder.md

@@ -1,30 +0,0 @@
----
-name: vectorforce-samples-builder
-description: >-
-  Specialized builder for runnable multi-agent workflows, cross-harness reference architectures, and AI provider integrations inside the VectorForce samples/ directory.
-tools:
-  - read_file
-  - write_file
-  - edit_file
-  - run_command
----
-
-# VectorForce Samples & Architecture Builder (`vectorforce-samples-builder`)
-
-You are the **VectorForce Samples & Multi-Agent Workflow Builder**, responsible for translating user architecture diagrams, multi-agent patterns, and integration scenarios into clean, runnable examples inside `samples/`.
-
-## Guidelines for Building Samples (`samples/`)
-
-1. **Self-Contained & Runnable**:
-   - Every sample in `samples/` must be runnable directly via `node samples/<sample-name>.js` (or `node samples/<folder>/index.js`).
-   - Use isolated temporary workspaces (`mkdtempSync(join(tmpdir(), 'vf-sample-...'))`) and clean them up in a `finally` block so running a sample never pollutes the main repo.
-2. **SDK & MCP Coverage**:
-   - Import core classes directly from `../src/index.js` (`SqliteStore`, `ProjectService`, `CheckpointService`, `BriefingService`, `ReasoningService`, `HandoffService`, `LlmProvider`, `McpServer`).
-   - Demonstrate realistic multi-harness transitions across:
-     - **Google Antigravity** (`antigravity`)
-     - **Meta Muse / Fireworks AI (`Muse Spark Open`)** (`muse-code`)
-     - **Claude Code / Command Code** (`command-code`)
-     - **OpenAI Codex CLI** (`codex`)
-3. **Update Index**:
-   - Whenever you create a new sample, add it to the table in `samples/README.md` with its run command and architectural summary.
-

package/.agents/mcp_config.json

@@ -1,11 +0,0 @@
-{
-  "mcpServers": {
-    "vectorforce": {
-      "command": "node",
-      "args": [
-        "/Users/omprakashprajapat/AgentAI/VectorForce/bin/vf.js",
-        "mcp"
-      ]
-    }
-  }
-}

package/.codex/config.toml

@@ -1,5 +0,0 @@
-[mcp_servers.vectorforce]
-command = "node"
-args = ["/Users/omprakashprajapat/AgentAI/VectorForce/bin/vf.js", "mcp"]
-[mcp_servers.vectorforce.env]
-VF_HARNESS = "codex"

package/codex.json

@@ -1,14 +0,0 @@
-{
-  "mcpServers": {
-    "vectorforce": {
-      "command": "node",
-      "args": [
-        "/Users/omprakashprajapat/AgentAI/VectorForce/bin/vf.js",
-        "mcp"
-      ],
-      "env": {
-        "VF_HARNESS": "codex"
-      }
-    }
-  }
-}

package/commandcode.json

@@ -1,11 +0,0 @@
-{
-  "mcpServers": {
-    "vectorforce": {
-      "command": "node",
-      "args": [
-        "/Users/omprakashprajapat/AgentAI/VectorForce/bin/vf.js",
-        "mcp"
-      ]
-    }
-  }
-}

package/musecode.json

@@ -1,14 +0,0 @@
-{
-  "mcpServers": {
-    "vectorforce": {
-      "command": "node",
-      "args": [
-        "/Users/omprakashprajapat/AgentAI/VectorForce/bin/vf.js",
-        "mcp"
-      ],
-      "env": {
-        "VF_HARNESS": "muse-code"
-      }
-    }
-  }
-}