@newsails/veil-studio 1.0.0

package/README.md

@@ -0,0 +1,181 @@
+# Veil Studio
+
+Visual workflow IDE for VeilCLI — an LLM agent runner.  
+Drag agents, sessions, tasks, memories, and data blocks onto an infinite canvas, wire them together, and watch everything run in real time.
+
+---
+
+## Features
+
+- **Infinite canvas** — place any element type, wire ports, organize with zones and saved views
+- **Real-time sync** — all board mutations broadcast to every connected client instantly
+- **Live chat** — stream token-by-token responses from any agent session, directly in the canvas
+- **External session monitoring** — sessions started by other apps or agent tools appear in Studio in real time, with live streaming, tool indicators, and user messages
+- **File explorer** — browse, edit, and add project files to the board as elements
+- **Custom elements** — drop a folder into `.veil-studio/elements/` to add any element type without rebuilding
+- **No build step** — Express server is plain CommonJS; starts instantly
+
+---
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g @newsails/veil-studio
+
+# Run (from any directory — that directory becomes the workspace)
+veil-studio
+```
+
+Open **http://localhost:4444**
+
+> **Node ≥18 required** for running. Node 20 is only needed if building the frontend from source.
+
+### CLI Options
+
+```
+veil-studio [options]
+
+  --port,     -p  <number>  Studio port                  (default: 4444)
+  --api,      -a  <url>     VeilCLI API base URL       (default: http://localhost:5050)
+  --api-port, -ap <number>  VeilCLI port on localhost  (shortcut for --api)
+  --project,  -d  <path>    Workspace directory          (default: cwd)
+  --secret,   -s  <token>   VeilCLI API secret token
+  --dev,      -D            Force dev mode
+  --help,     -h            Show help
+```
+
+Positional shorthand: `veil-studio <port> [api] [project] [secret]`
+
+### Run from source
+
+```bash
+npm install
+node bin/veil-studio.js
+# or
+npm start
+```
+
+---
+
+## Architecture
+
+```
+Browser (Nuxt 3 SPA — TypeScript, Pinia, TailwindCSS)
+  │  Socket.IO   ← board mutations, chat, VeilCLI proxy
+  │  REST /api/files/*  ← file system only
+  ▼
+Express server (port 4444) — Plain CommonJS, no build step
+  ├── Socket.IO handlers    server/socket.js
+  ├── REST routes           server/routes/files.js
+  ├── SQLite (sync)         .veil-studio/studio.db
+  ├── In-memory Maps        board state (elements, links, zones, views)
+  └── WebSocket client  ──► VeilCLI /ws (port 5050)
+                            real-time events for all sessions & tasks
+```
+
+**Key rules:**
+- Browser **never** talks to VeilCLI directly — all calls proxied via Studio Socket.IO
+- Board state is **server-authoritative** — clients never optimistically mutate
+- Socket.IO for everything board/agent/chat; REST only for `/api/files/*`
+
+---
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `STUDIO_PORT` | `4444` | Studio server port |
+| `VEIL_API` | `http://localhost:5050` | VeilCLI base URL (auto-read from `.veil/settings.json`) |
+| `VEIL_SECRET` | _(empty)_ | `X-Veil-Secret` auth header (auto-read from `.veil/settings.json`) |
+| `PROJECT_DIR` | `process.cwd()` | Working directory (files, custom elements, DB) |
+
+---
+
+## Project Structure
+
+```
+VeilCLI_Studio/
+├── server/                   Backend — plain CommonJS
+│   ├── index.js              Entry: startup sequence, dev proxy, listen
+│   ├── socket.js             All Socket.IO event handlers
+│   ├── routes/files.js       REST /api/files/*
+│   └── utils/
+│       ├── config.js         All env/config resolution
+│       ├── db.js             SQLite singleton + schema
+│       ├── board-state.js    In-memory Maps + DB sync + broadcasts
+│       ├── element-registry.js  55 built-in + custom type registry
+│       ├── element-instances.js Running element instance Map
+│       ├── veil-client.js  VeilCLI REST + SSE streaming wrapper
+│       ├── veil-ws.js      Persistent WS to VeilCLI /ws
+│       ├── session-watcher.js   Message-count baseline tracker
+│       ├── socket-io.js      getIO()/setIO() singleton
+│       ├── file-utils.js     Path-safe file operations
+│       └── elements/         55 built-in element definitions
+│
+├── nuxt-app/                 Frontend — Nuxt 3, TypeScript, SPA
+│   ├── stores/               board.ts · ui.ts · chat.ts
+│   ├── composables/          useSocket · useBoard · useCamera · useChat
+│   │                         useVeil · useElementRegistry · useFileExplorer
+│   ├── components/           canvas/ · elements/ · sidebar/ · chat/
+│   └── .output/              Production build (served by Express in prod)
+│
+└── docs/                     Full reference documentation
+```
+
+---
+
+## Built-in Element Types (55)
+
+| Category | Types |
+|---|---|
+| CLI | `agent` `agent-instance` `chat-view` `task` `skill` `memory` `todo-list` `custom-tool` |
+| Data | `text` `rich-text` `code-block` `json-object` `file-reference` `image` `image-local` `url-card` `web-snapshot` |
+| Research | `source-collection` `research-note` `comparison-table` `fact-claim` `question` `web-search-query` |
+| Docs | `document-draft` `outline` `section` `template` |
+| Dev | `diff-patch` `error-log` `test-case` |
+| Thinking | `idea` `pro-con-list` `decision` `assumption` `constraint` `goal` `blocker` |
+| PM | `project` `milestone` `status-update` |
+| Comm | `chat-room` `message` `feedback-request` `approval-gate` |
+| Flow | `generator` `processor` `splitter` `merger` `filter` `queue` |
+| Org | `collapsible-group` `annotation` `label-tag` `divider` `primitive` |
+
+---
+
+## Custom Elements
+
+Drop a folder in `.veil-studio/elements/<type>/` containing:
+
+```
+element.json       — metadata (type, name, icon, defaultWidth/Height, …)
+index.js           — server-side factory: createInstance(context) → { getViewData, getPorts, actions }
+vue-component.js   — frontend Vue component (receives viewData, elementId props; emits action)
+```
+
+Click **Reload Custom Elements** in the palette sidebar — no server restart needed. Custom types with the same name as a built-in **override** the built-in completely.
+
+---
+
+## Documentation
+
+| Document | Contents |
+|---|---|
+| [`docs/README.md`](docs/README.md) | Architecture deep-dive, data flow, key decisions |
+| [`docs/Server.md`](docs/Server.md) | All server modules, DB schema, element system reference |
+| [`docs/SocketIO.md`](docs/SocketIO.md) | Every Socket.IO event — payloads, handlers, end-to-end flows |
+| [`docs/UI.md`](docs/UI.md) | Stores, composables, canvas components, chat components |
+
+---
+
+## Production Build
+
+When installed via `npm`, the pre-built frontend is included in the package (`nuxt-app/.output/public/`). The server auto-detects it and serves it statically.
+
+To rebuild the frontend from source (requires Node 20):
+
+```bash
+npm run build
+# runs scripts/build-ui.js → cd nuxt-app && nuxt build
+```
+
+The server auto-detects whether `nuxt-app/.output/public/` exists — if yes, production mode; if no, dev mode (spawns Nuxt dev automatically).

package/bin/veil-studio.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+'use strict'
+
+const path = require('path')
+
+// ─── CLI help ────────────────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2)
+
+if (argv.includes('--version') || argv.includes('-v')) {
+  const { version } = require('../package.json')
+  console.log(version)
+  process.exit(0)
+}
+
+if (argv.includes('--check-for-update') || argv.includes('-cu')) {
+  const https = require('https')
+  const { name, version } = require('../package.json')
+  const url = `https://registry.npmjs.org/${name}/latest`
+  https.get(url, { headers: { 'User-Agent': 'veil-studio-cli' } }, (res) => {
+    let data = ''
+    res.on('data', chunk => { data += chunk })
+    res.on('end', () => {
+      if (res.statusCode === 404) {
+        console.error(`Package "${name}" not found on npm registry. Has it been published yet?`)
+        process.exit(1)
+      }
+      if (res.statusCode !== 200) {
+        console.error(`Registry returned HTTP ${res.statusCode}.`)
+        process.exit(1)
+      }
+      try {
+        const latest = JSON.parse(data).version
+        if (!latest) { console.error('Unexpected registry response (no version field).'); process.exit(1) }
+        if (latest === version) {
+          console.log(`No updates available (current: v${version})`)
+        } else {
+          console.log(`New update exists: v${latest}  (current: v${version})`)
+        }
+        process.exit(0)
+      } catch { console.error('Failed to parse registry response.'); process.exit(1) }
+    })
+  }).on('error', (err) => {
+    console.error(`Update check failed: ${err.message}`)
+    process.exit(1)
+  })
+  return  // prevent server startup while check is pending
+}
+
+if (argv.includes('--help') || argv.includes('-h')) {
+  console.log([
+    '',
+    '  veil-studio — AI agent orchestration workspace with drag-and-drop canvas, real-time chat, and visual workflow builder for creating reusable agent workflows.',
+    '',
+    '  Usage (named flags):',
+    '    veil-studio [--port 4444] [--api <url>] [--project <path>] [--secret <token>]',
+    '',
+    '  Usage (positional args):',
+    '    veil-studio <port> [api] [project] [secret]',
+    '    veil-studio 4444',
+    '    veil-studio 4444 http://localhost:5050 /my/workspace',
+    '',
+    '  Options:',
+    '    --port     | -p   <number>  Studio port              (default: 4444)',
+    '    --api      | -a   <url>     Veil CLI API base URL  (default: http://localhost:5050)',
+    '    --api-port | -ap  <number>  Veil API port on localhost (shortcut for --api)',
+    '    --project  | -d   <path>    Workspace directory      (default: cwd)',
+    '    --secret   | -s   <token>   Veil API secret token',
+    '    --dev      | -D            Force dev mode (nuxt dev even if build exists)',
+    '    --check-for-update | -cu  Check npm registry for a newer version',
+    '    --version  | -v            Print version and exit',
+    '    --help     | -h            Show this help',
+    '',
+    '  Priority (highest → lowest):',
+    '    named flags  →  positional args  →  env vars  →  hardcoded defaults',
+    '',
+    '  Environment variables:',
+    '    STUDIO_PORT   VEIL_API   PROJECT_DIR   VEIL_SECRET',
+    '',
+  ].join('\n'))
+  process.exit(0)
+}
+
+// ─── Step 1: start from env vars / hardcoded defaults ────────────────────────
+
+let port       = process.env.STUDIO_PORT   || '4444'
+let api        = process.env.VEIL_API    || 'http://localhost:5050'
+let projectDir = process.env.PROJECT_DIR   || process.cwd()
+let secret     = process.env.VEIL_SECRET || ''
+let devMode    = process.env.STUDIO_DEV    === '1'
+let apiExplicit = !!process.env.VEIL_API  // track if api was set by env
+
+// ─── Step 2: apply positional args (override env/defaults) ───────────────────
+
+const positional = []
+for (let i = 0; i < argv.length; i++) {
+  if (!argv[i].startsWith('-')) positional.push(argv[i])
+}
+if (positional[0]) port       = positional[0]
+if (positional[1]) api        = positional[1]
+if (positional[2]) projectDir = positional[2]
+if (positional[3]) secret     = positional[3]
+
+// ─── Step 3: apply named flags (highest priority) ────────────────────────────
+
+let apiPort = ''
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i]
+  const v = argv[i + 1]
+  if ((a === '--port'     || a === '-p')  && v && !v.startsWith('-')) { port       = v; i++ }
+  if ((a === '--api'      || a === '-a')  && v && !v.startsWith('-')) { api        = v; apiExplicit = true; i++ }
+  if ((a === '--api-port' || a === '-ap') && v && !v.startsWith('-')) { apiPort    = v; i++ }
+  if ((a === '--project'  || a === '-d')  && v && !v.startsWith('-')) { projectDir = v; i++ }
+  if ((a === '--secret'   || a === '-s')  && v && !v.startsWith('-')) { secret     = v; i++ }
+  if (a === '--dev' || a === '-D') devMode = true
+}
+
+// --api-port: build localhost URL only when --api was not explicitly provided
+if (apiPort && !apiExplicit) {
+  api = `http://localhost:${apiPort}`
+}
+
+// ─── Set env before requiring server ────────────────────────────────────────
+
+process.env.STUDIO_PORT   = port
+process.env.VEIL_API    = api
+process.env.PROJECT_DIR   = path.resolve(projectDir)
+if (secret)  process.env.VEIL_SECRET = secret
+if (devMode) process.env.STUDIO_DEV    = '1'
+
+// ─── Banner ──────────────────────────────────────────────────────────────────
+
+console.log('')
+console.log('  Veil Studio')
+console.log(`  Studio    : http://localhost:${port}`)
+console.log(`  VeilAPI : ${api}`)
+console.log(`  Project   : ${process.env.PROJECT_DIR}`)
+console.log('')
+
+// ─── Boot server ─────────────────────────────────────────────────────────────
+
+require('../server/index.js')

package/nuxt-app/.output/public/200.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html><html><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Veil Studio</title>
+<link rel="stylesheet" href="/_nuxt/entry.CYnp7zY5.css">
+<link rel="modulepreload" as="script" crossorigin href="/_nuxt/entry.BrrOeBSX.js">
+<link rel="prefetch" as="style" crossorigin href="/_nuxt/error-404.JekaaCis.css">
+<link rel="prefetch" as="script" crossorigin href="/_nuxt/error-404.BbdzCaXe.js">
+<link rel="prefetch" as="script" crossorigin href="/_nuxt/vue.-sixQ7xP.BlWffD__.js">
+<link rel="prefetch" as="style" crossorigin href="/_nuxt/error-500.CNP9nqm1.css">
+<link rel="prefetch" as="script" crossorigin href="/_nuxt/error-500.DbOlBIIY.js">
+<script type="module" src="/_nuxt/entry.BrrOeBSX.js" crossorigin></script>
+<script id="unhead:payload" type="application/json">{"title":"Veil Studio"}</script></head><body><div id="__nuxt"></div><script type="application/json" id="__NUXT_DATA__" data-ssr="false">[{"_errors":1,"serverRendered":2,"data":3,"state":4,"once":5},{},false,{},{},["Set"]]</script>
+<script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script></body></html>

package/nuxt-app/.output/public/404.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html><html><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Veil Studio</title>
+<link rel="stylesheet" href="/_nuxt/entry.CYnp7zY5.css">
+<link rel="modulepreload" as="script" crossorigin href="/_nuxt/entry.BrrOeBSX.js">
+<link rel="prefetch" as="style" crossorigin href="/_nuxt/error-404.JekaaCis.css">
+<link rel="prefetch" as="script" crossorigin href="/_nuxt/error-404.BbdzCaXe.js">
+<link rel="prefetch" as="script" crossorigin href="/_nuxt/vue.-sixQ7xP.BlWffD__.js">
+<link rel="prefetch" as="style" crossorigin href="/_nuxt/error-500.CNP9nqm1.css">
+<link rel="prefetch" as="script" crossorigin href="/_nuxt/error-500.DbOlBIIY.js">
+<script type="module" src="/_nuxt/entry.BrrOeBSX.js" crossorigin></script>
+<script id="unhead:payload" type="application/json">{"title":"Veil Studio"}</script></head><body><div id="__nuxt"></div><script type="application/json" id="__NUXT_DATA__" data-ssr="false">[{"_errors":1,"serverRendered":2,"data":3,"state":4,"once":5},{},false,{},{},["Set"]]</script>
+<script>window.__NUXT__={};window.__NUXT__.config={public:{},app:{baseURL:"/",buildAssetsDir:"/_nuxt/",cdnURL:""}}</script></body></html>

package/nuxt-app/.output/public/_nuxt/builds/latest.json

@@ -0,0 +1 @@
+{"id":"6b28df26-54af-4fad-a1f0-38808960d9fe","timestamp":1773909250273}

package/nuxt-app/.output/public/_nuxt/builds/meta/6b28df26-54af-4fad-a1f0-38808960d9fe.json

@@ -0,0 +1 @@
+{"id":"6b28df26-54af-4fad-a1f0-38808960d9fe","timestamp":1773909250273,"matcher":{"static":{},"wildcard":{},"dynamic":{}},"prerendered":[]}