@rkarim08/sia 1.0.0

package/skills/sia-visualize-live/scripts/start-visualizer.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# Start the graph visualizer server and output connection info
+# Usage: start-visualizer.sh [--project-dir <path>] [--host <bind-host>] [--url-host <display-host>] [--foreground] [--background]
+#
+# Starts server on a random high port, outputs JSON with URL.
+# Each session gets its own directory to avoid conflicts.
+#
+# Options:
+#   --project-dir <path>  Store session files under <path>/.sia/visualize/
+#                         instead of /tmp. Files persist after server stops.
+#   --host <bind-host>    Host/interface to bind (default: 127.0.0.1).
+#                         Use 0.0.0.0 in remote/containerized environments.
+#   --url-host <host>     Hostname shown in returned URL JSON.
+#   --foreground          Run server in the current terminal (no backgrounding).
+#   --background          Force background mode (overrides Codex auto-foreground).
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Parse arguments
+PROJECT_DIR=""
+FOREGROUND="false"
+FORCE_BACKGROUND="false"
+BIND_HOST="127.0.0.1"
+URL_HOST=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --project-dir)
+      PROJECT_DIR="$2"
+      shift 2
+      ;;
+    --host)
+      BIND_HOST="$2"
+      shift 2
+      ;;
+    --url-host)
+      URL_HOST="$2"
+      shift 2
+      ;;
+    --foreground|--no-daemon)
+      FOREGROUND="true"
+      shift
+      ;;
+    --background|--daemon)
+      FORCE_BACKGROUND="true"
+      shift
+      ;;
+    *)
+      echo "{\"error\": \"Unknown argument: $1\"}"
+      exit 1
+      ;;
+  esac
+done
+
+if [[ -z "$URL_HOST" ]]; then
+  if [[ "$BIND_HOST" == "127.0.0.1" || "$BIND_HOST" == "localhost" ]]; then
+    URL_HOST="localhost"
+  else
+    URL_HOST="$BIND_HOST"
+  fi
+fi
+
+# Some environments reap detached/background processes. Auto-foreground when detected.
+if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
+  FOREGROUND="true"
+fi
+
+# Windows/Git Bash reaps nohup background processes. Auto-foreground when detected.
+if [[ "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
+  case "${OSTYPE:-}" in
+    msys*|cygwin*|mingw*) FOREGROUND="true" ;;
+  esac
+  if [[ -n "${MSYSTEM:-}" ]]; then
+    FOREGROUND="true"
+  fi
+fi
+
+# Generate unique session directory
+SESSION_ID="$$-$(date +%s)"
+
+if [[ -n "$PROJECT_DIR" ]]; then
+  SCREEN_DIR="${PROJECT_DIR}/.sia/visualize/${SESSION_ID}"
+else
+  SCREEN_DIR="/tmp/visualize-${SESSION_ID}"
+fi
+
+PID_FILE="${SCREEN_DIR}/.server.pid"
+LOG_FILE="${SCREEN_DIR}/.server.log"
+
+# Create fresh session directory
+mkdir -p "$SCREEN_DIR"
+
+# Generate graph data before starting server
+if [[ -n "$PROJECT_DIR" ]]; then
+  GRAPH_FILE="${SCREEN_DIR}/graph.json"
+  if command -v sia &>/dev/null; then
+    sia export --format json > "$GRAPH_FILE" 2>/dev/null || echo '{"nodes":[],"edges":[]}' > "$GRAPH_FILE"
+  elif command -v bun &>/dev/null && [[ -f "${PROJECT_DIR}/src/cli/index.ts" ]]; then
+    bun run "${PROJECT_DIR}/src/cli/index.ts" export --format json > "$GRAPH_FILE" 2>/dev/null || echo '{"nodes":[],"edges":[]}' > "$GRAPH_FILE"
+  else
+    echo '{"nodes":[],"edges":[]}' > "$GRAPH_FILE"
+  fi
+fi
+
+# Kill any existing server
+if [[ -f "$PID_FILE" ]]; then
+  old_pid=$(cat "$PID_FILE")
+  kill "$old_pid" 2>/dev/null
+  rm -f "$PID_FILE"
+fi
+
+cd "$SCRIPT_DIR"
+
+# Resolve the harness PID (grandparent of this script).
+OWNER_PID="$(ps -o ppid= -p "$PPID" 2>/dev/null | tr -d ' ')"
+if [[ -z "$OWNER_PID" || "$OWNER_PID" == "1" ]]; then
+  OWNER_PID="$PPID"
+fi
+
+# On Windows/MSYS2, the MSYS2 PID namespace is invisible to Node.js.
+case "${OSTYPE:-}" in
+  msys*|cygwin*|mingw*) OWNER_PID="" ;;
+esac
+
+# Foreground mode for environments that reap detached/background processes.
+if [[ "$FOREGROUND" == "true" ]]; then
+  echo "$$" > "$PID_FILE"
+  env VISUALIZER_DIR="$SCREEN_DIR" VISUALIZER_HOST="$BIND_HOST" VISUALIZER_URL_HOST="$URL_HOST" VISUALIZER_OWNER_PID="$OWNER_PID" GRAPH_DATA_FILE="${GRAPH_FILE:-${SCREEN_DIR}/graph.json}" node visualizer-server.cjs
+  exit $?
+fi
+
+# Start server, capturing output to log file
+nohup env VISUALIZER_DIR="$SCREEN_DIR" VISUALIZER_HOST="$BIND_HOST" VISUALIZER_URL_HOST="$URL_HOST" VISUALIZER_OWNER_PID="$OWNER_PID" GRAPH_DATA_FILE="${GRAPH_FILE:-${SCREEN_DIR}/graph.json}" node visualizer-server.cjs > "$LOG_FILE" 2>&1 &
+SERVER_PID=$!
+disown "$SERVER_PID" 2>/dev/null
+echo "$SERVER_PID" > "$PID_FILE"
+
+# Wait for server-started message (check log file)
+for i in {1..50}; do
+  if grep -q "server-started" "$LOG_FILE" 2>/dev/null; then
+    # Verify server is still alive after a short window (catches process reapers)
+    alive="true"
+    for _ in {1..20}; do
+      if ! kill -0 "$SERVER_PID" 2>/dev/null; then
+        alive="false"
+        break
+      fi
+      sleep 0.1
+    done
+    if [[ "$alive" != "true" ]]; then
+      echo "{\"error\": \"Server started but was killed. Retry in a persistent terminal with: $SCRIPT_DIR/start-visualizer.sh${PROJECT_DIR:+ --project-dir $PROJECT_DIR} --host $BIND_HOST --url-host $URL_HOST --foreground\"}"
+      exit 1
+    fi
+    grep "server-started" "$LOG_FILE" | head -1
+    exit 0
+  fi
+  sleep 0.1
+done
+
+# Timeout - server didn't start
+echo '{"error": "Server failed to start within 5 seconds"}'
+exit 1

package/skills/sia-visualize-live/scripts/stop-visualizer.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# Stop the visualizer server and clean up
+# Usage: stop-visualizer.sh <screen_dir>
+#
+# Kills the server process. Only deletes session directory if it's
+# under /tmp (ephemeral). Persistent directories (.sia/) are
+# kept so graph snapshots can be reviewed later.
+
+SCREEN_DIR="$1"
+
+if [[ -z "$SCREEN_DIR" ]]; then
+  echo '{"error": "Usage: stop-visualizer.sh <screen_dir>"}'
+  exit 1
+fi
+
+PID_FILE="${SCREEN_DIR}/.server.pid"
+
+if [[ -f "$PID_FILE" ]]; then
+  pid=$(cat "$PID_FILE")
+
+  # Try to stop gracefully, fallback to force if still alive
+  kill "$pid" 2>/dev/null || true
+
+  # Wait for graceful shutdown (up to ~2s)
+  for i in {1..20}; do
+    if ! kill -0 "$pid" 2>/dev/null; then
+      break
+    fi
+    sleep 0.1
+  done
+
+  # If still running, escalate to SIGKILL
+  if kill -0 "$pid" 2>/dev/null; then
+    kill -9 "$pid" 2>/dev/null || true
+
+    # Give SIGKILL a moment to take effect
+    sleep 0.1
+  fi
+
+  if kill -0 "$pid" 2>/dev/null; then
+    echo '{"status": "failed", "error": "process still running"}'
+    exit 1
+  fi
+
+  rm -f "$PID_FILE" "${SCREEN_DIR}/.server.log"
+
+  # Only delete ephemeral /tmp directories
+  if [[ "$SCREEN_DIR" == /tmp/* ]]; then
+    rm -rf "$SCREEN_DIR"
+  fi
+
+  echo '{"status": "stopped"}'
+else
+  echo '{"status": "not_running"}'
+fi

package/skills/sia-visualize-live/scripts/visualizer-server.cjs

@@ -0,0 +1,264 @@
+const crypto = require('crypto');
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+
+// ========== WebSocket Protocol (RFC 6455) ==========
+
+const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
+const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
+
+function computeAcceptKey(clientKey) {
+  return crypto.createHash('sha1').update(clientKey + WS_MAGIC).digest('base64');
+}
+
+function encodeFrame(opcode, payload) {
+  const fin = 0x80;
+  const len = payload.length;
+  let header;
+
+  if (len < 126) {
+    header = Buffer.alloc(2);
+    header[0] = fin | opcode;
+    header[1] = len;
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = fin | opcode;
+    header[1] = 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = fin | opcode;
+    header[1] = 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+
+  return Buffer.concat([header, payload]);
+}
+
+function decodeFrame(buffer) {
+  if (buffer.length < 2) return null;
+
+  const secondByte = buffer[1];
+  const opcode = buffer[0] & 0x0F;
+  const masked = (secondByte & 0x80) !== 0;
+  let payloadLen = secondByte & 0x7F;
+  let offset = 2;
+
+  if (!masked) throw new Error('Client frames must be masked');
+
+  if (payloadLen === 126) {
+    if (buffer.length < 4) return null;
+    payloadLen = buffer.readUInt16BE(2);
+    offset = 4;
+  } else if (payloadLen === 127) {
+    if (buffer.length < 10) return null;
+    payloadLen = Number(buffer.readBigUInt64BE(2));
+    offset = 10;
+  }
+
+  const maskOffset = offset;
+  const dataOffset = offset + 4;
+  const totalLen = dataOffset + payloadLen;
+  if (buffer.length < totalLen) return null;
+
+  const mask = buffer.slice(maskOffset, dataOffset);
+  const data = Buffer.alloc(payloadLen);
+  for (let i = 0; i < payloadLen; i++) {
+    data[i] = buffer[dataOffset + i] ^ mask[i % 4];
+  }
+
+  return { opcode, payload: data, bytesConsumed: totalLen };
+}
+
+// ========== Configuration ==========
+
+const PORT = process.env.VISUALIZER_PORT || (49152 + Math.floor(Math.random() * 16383));
+const HOST = process.env.VISUALIZER_HOST || '127.0.0.1';
+const URL_HOST = process.env.VISUALIZER_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
+const SCREEN_DIR = process.env.VISUALIZER_DIR || '/tmp/visualize';
+const OWNER_PID = process.env.VISUALIZER_OWNER_PID ? Number(process.env.VISUALIZER_OWNER_PID) : null;
+const GRAPH_DATA_FILE = process.env.GRAPH_DATA_FILE || path.join(SCREEN_DIR, 'graph.json');
+
+// ========== Template and Graph Data ==========
+
+const graphTemplate = fs.readFileSync(path.join(__dirname, 'graph-template.html'), 'utf-8');
+
+function loadGraphData() {
+  if (fs.existsSync(GRAPH_DATA_FILE)) {
+    try {
+      return fs.readFileSync(GRAPH_DATA_FILE, 'utf-8');
+    } catch (e) {
+      console.error('Failed to read graph data:', e.message);
+    }
+  }
+  return JSON.stringify({ nodes: [], edges: [] });
+}
+
+function buildPage() {
+  const graphJson = loadGraphData();
+  return graphTemplate.replace('/* GRAPH_DATA */', graphJson);
+}
+
+// ========== HTTP Request Handler ==========
+
+function handleRequest(req, res) {
+  touchActivity();
+  if (req.method === 'GET' && req.url === '/') {
+    const html = buildPage();
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.end(html);
+  } else {
+    res.writeHead(404);
+    res.end('Not found');
+  }
+}
+
+// ========== WebSocket Connection Handling ==========
+
+const clients = new Set();
+
+function handleUpgrade(req, socket) {
+  const key = req.headers['sec-websocket-key'];
+  if (!key) { socket.destroy(); return; }
+
+  const accept = computeAcceptKey(key);
+  socket.write(
+    'HTTP/1.1 101 Switching Protocols\r\n' +
+    'Upgrade: websocket\r\n' +
+    'Connection: Upgrade\r\n' +
+    'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n'
+  );
+
+  let buffer = Buffer.alloc(0);
+  clients.add(socket);
+
+  socket.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length > 0) {
+      let result;
+      try {
+        result = decodeFrame(buffer);
+      } catch (e) {
+        socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
+        clients.delete(socket);
+        return;
+      }
+      if (!result) break;
+      buffer = buffer.slice(result.bytesConsumed);
+
+      switch (result.opcode) {
+        case OPCODES.TEXT:
+          touchActivity();
+          break;
+        case OPCODES.CLOSE:
+          socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
+          clients.delete(socket);
+          return;
+        case OPCODES.PING:
+          socket.write(encodeFrame(OPCODES.PONG, result.payload));
+          break;
+        case OPCODES.PONG:
+          break;
+        default: {
+          const closeBuf = Buffer.alloc(2);
+          closeBuf.writeUInt16BE(1003);
+          socket.end(encodeFrame(OPCODES.CLOSE, closeBuf));
+          clients.delete(socket);
+          return;
+        }
+      }
+    }
+  });
+
+  socket.on('close', () => clients.delete(socket));
+  socket.on('error', () => clients.delete(socket));
+}
+
+function broadcast(msg) {
+  const frame = encodeFrame(OPCODES.TEXT, Buffer.from(JSON.stringify(msg)));
+  for (const socket of clients) {
+    try { socket.write(frame); } catch (e) { clients.delete(socket); }
+  }
+}
+
+// ========== Activity Tracking ==========
+
+const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+let lastActivity = Date.now();
+
+function touchActivity() {
+  lastActivity = Date.now();
+}
+
+// ========== Server Startup ==========
+
+function startServer() {
+  if (!fs.existsSync(SCREEN_DIR)) fs.mkdirSync(SCREEN_DIR, { recursive: true });
+
+  const server = http.createServer(handleRequest);
+  server.on('upgrade', handleUpgrade);
+
+  // Watch for graph data file changes and push reloads
+  const debounceTimers = new Map();
+
+  if (fs.existsSync(path.dirname(GRAPH_DATA_FILE))) {
+    try {
+      const watcher = fs.watch(path.dirname(GRAPH_DATA_FILE), (eventType, filename) => {
+        if (!filename || filename !== path.basename(GRAPH_DATA_FILE)) return;
+
+        if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
+        debounceTimers.set(filename, setTimeout(() => {
+          debounceTimers.delete(filename);
+          if (!fs.existsSync(GRAPH_DATA_FILE)) return;
+          touchActivity();
+          console.log(JSON.stringify({ type: 'graph-updated', file: GRAPH_DATA_FILE }));
+          broadcast({ type: 'reload' });
+        }, 100));
+      });
+      watcher.on('error', (err) => console.error('fs.watch error:', err.message));
+    } catch (e) {
+      console.error('Could not watch graph data directory:', e.message);
+    }
+  }
+
+  function shutdown(reason) {
+    console.log(JSON.stringify({ type: 'server-stopped', reason }));
+    const infoFile = path.join(SCREEN_DIR, '.server-info');
+    if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile);
+    fs.writeFileSync(
+      path.join(SCREEN_DIR, '.server-stopped'),
+      JSON.stringify({ reason, timestamp: Date.now() }) + '\n'
+    );
+    clearInterval(lifecycleCheck);
+    server.close(() => process.exit(0));
+  }
+
+  function ownerAlive() {
+    if (!OWNER_PID) return true;
+    try { process.kill(OWNER_PID, 0); return true; } catch (e) { return false; }
+  }
+
+  // Check every 60s: exit if owner process died or idle for 30 minutes
+  const lifecycleCheck = setInterval(() => {
+    if (!ownerAlive()) shutdown('owner process exited');
+    else if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) shutdown('idle timeout');
+  }, 60 * 1000);
+  lifecycleCheck.unref();
+
+  server.listen(PORT, HOST, () => {
+    const info = JSON.stringify({
+      type: 'server-started', port: Number(PORT), host: HOST,
+      url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + PORT,
+      screen_dir: SCREEN_DIR
+    });
+    console.log(info);
+    fs.writeFileSync(path.join(SCREEN_DIR, '.server-info'), info + '\n');
+  });
+}
+
+if (require.main === module) {
+  startServer();
+}
+
+module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };

package/skills/sia-workspace/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: sia-workspace
+description: Manages SIA workspaces for cross-repo knowledge sharing — creating workspaces, adding repos, and detecting API contracts. Use when working across multiple repositories or setting up shared knowledge.
+---
+
+# SIA Workspace
+
+Manage workspaces that enable cross-repo knowledge sharing.
+
+## What Are Workspaces?
+
+Workspaces group multiple repositories together so SIA can:
+- Share knowledge across repos via bridge edges
+- Detect API contracts between services
+- Enable cross-repo search with `sia_search({ workspace: true })`
+
+## Commands
+
+### Create a workspace
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/workspace.ts create "my-workspace"
+```
+
+### List workspaces
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/workspace.ts list
+```
+
+### Add a repo to a workspace
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/workspace.ts add "my-workspace" /path/to/repo
+```
+
+### Remove a repo from a workspace
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/workspace.ts remove "my-workspace" /path/to/repo
+```
+
+### Show workspace details
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/workspace.ts show "my-workspace"
+```
+
+## Related: Team Sync
+
+For team-based knowledge sharing (requires a sync server):
+
+```bash
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/team.ts join <server-url>
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/team.ts status
+bun run ${CLAUDE_PLUGIN_ROOT}/src/cli/commands/team.ts leave
+```