circuschief 0.1.3 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "circuschief",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Local-first web UI for managing Claude Code sessions",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "zod": "^4.2.1",
     "@anthropic-ai/claude-agent-sdk": "^0.1.76",
     "@anthropic-ai/sdk": "^0.71.2",
-    "better-sqlite3": "^11.7.0",
+    "better-sqlite3": "^12.1.0",
     "cors": "^2.8.5",
     "express": "^4.21.2",
     "http-proxy-middleware": "^3.0.5",

package/packages/server/src/api/commands.js

@@ -71,6 +71,49 @@ router.get('/:name', async (req, res) => {
  *   - sessionId: Session to execute command in (required)
  *   - args: Object with argument values keyed by argument name (optional)
  */
+/**
+ * Handle execution of a skill invocation (skill body -> system prompt, args -> user message).
+ * Returns the response payload, or null if the command is not a skill.
+ */
+async function handleSkillExecution({ workingDirectory, name, args, sessionId, project }) {
+  const skillInvocation = await slashCommandService.buildSkillInvocation(
+    workingDirectory, name, args
+  );
+
+  if (!skillInvocation) return null;
+
+  const skillSystemPrompt = slashCommandService.buildSkillSystemPrompt(
+    project.systemPrompt || null, skillInvocation
+  );
+  const userMessage = slashCommandService.buildSkillUserMessage(skillInvocation);
+
+  continueSession(sessionId, userMessage, workingDirectory, {
+    systemPrompt: skillSystemPrompt,
+  }).catch(err => {
+    console.error('Error executing skill:', err);
+  });
+
+  return { success: true, command: name, message: userMessage };
+}
+
+/**
+ * Handle execution of a non-skill slash command.
+ * Returns the response payload.
+ */
+async function handleCommandExecution({ workingDirectory, name, args, sessionId, project }) {
+  const commandString = await slashCommandService.buildCommandString(
+    workingDirectory, name, args
+  );
+
+  continueSession(sessionId, commandString, workingDirectory, {
+    systemPrompt: project.systemPrompt || null,
+  }).catch(err => {
+    console.error('Error executing command:', err);
+  });
+
+  return { success: true, command: name, message: commandString };
+}
+
 router.post('/:name/execute', async (req, res) => {
   const { name } = req.params;
   const { sessionId, args = {} } = req.body;
@@ -103,63 +146,15 @@ router.post('/:name/execute', async (req, res) => {
     }
 
   try {
-    // Check if this is a skill — skills need special handling:
-    // skill body → system prompt, user args → user message
-    const skillInvocation = await slashCommandService.buildSkillInvocation(
-      workingDirectory,
-      name,
-      args
-    );
-
-    if (skillInvocation) {
-      // Skill: inject body as system prompt context, args as user message
-      const skillSystemPrompt = slashCommandService.buildSkillSystemPrompt(
-        project.systemPrompt || null,
-        skillInvocation
-      );
-      const userMessage = slashCommandService.buildSkillUserMessage(skillInvocation);
-
-      continueSession(
-        sessionId,
-        userMessage,
-        workingDirectory,
-        { systemPrompt: skillSystemPrompt } // No file attachments for slash commands
-      ).catch(err => {
-        console.error('Error executing skill:', err);
-      });
-
-      res.json({
-        success: true,
-        command: name,
-        message: userMessage,
-      });
-      return;
+    // Check if this is a skill — skills need special handling
+    const skillResult = await handleSkillExecution({ workingDirectory, name, args, sessionId, project });
+    if (skillResult) {
+      return res.json(skillResult);
     }
 
-    // Non-skill command: build command string and send as user message
-    const commandString = await slashCommandService.buildCommandString(
-      workingDirectory,
-      name,
-      args
-    );
-
-    // Use continueSession to send the command
-    // This handles the full message flow including broadcasting to WebSocket
-    continueSession(
-      sessionId,
-      commandString,
-      workingDirectory,
-      { systemPrompt: project.systemPrompt || null } // No file attachments for slash commands
-    ).catch(err => {
-      // Log but don't throw - continueSession runs asynchronously
-      console.error('Error executing command:', err);
-    });
-
-    res.json({
-      success: true,
-      command: name,
-      message: commandString,
-    });
+    // Non-skill command
+    const cmdResult = await handleCommandExecution({ workingDirectory, name, args, sessionId, project });
+    res.json(cmdResult);
   } catch (err) {
     console.error('Error executing command:', err);
     res.status(500).json({ error: err.message });

package/packages/server/src/api/projects-helpers.js

@@ -1,19 +1,28 @@
 import { isGitRepo } from '../services/gitService.js';
 
 /**
- * Validate that git projects have required gitMode and gitBranch settings.
+ * Validate and default git settings for git-backed projects.
+ * If gitMode or gitBranch are missing for a git project, defaults are applied
+ * (gitMode: 'none', gitBranch: 'main') instead of rejecting the request.
  * @param {Object} config - The session configuration
  * @param {Object} project - The project object
- * @returns {Promise<string|null>} Error message if validation fails, null otherwise.
+ * @returns {Promise<{config: Object, error: string|null}>} Updated config and error message if validation fails.
  */
 export async function validateGitSettings(config, project) {
   if (!config.gitMode || !config.gitBranch) {
     const isGit = await isGitRepo(project.workingDirectory);
     if (isGit) {
-      return 'Git projects require both gitMode and gitBranch. Set project defaults or provide them per-session.';
+      return {
+        config: {
+          ...config,
+          gitMode: config.gitMode || 'none',
+          gitBranch: config.gitBranch || 'main',
+        },
+        error: null,
+      };
     }
   }
-  return null;
+  return { config, error: null };
 }
 
 /**

package/packages/server/src/api/projects.js

@@ -151,38 +151,53 @@ router.get('/:id/sessions', (req, res) => {
   }
 });
 
-// POST /api/projects/:id/sessions - Create session
-// Supports both JSON and multipart/form-data (for file attachments)
-router.post('/:id/sessions', uploadMiddleware('files', 10), handleUploadError, async (req, res) => {
-  const project = projects.getById(req.params.id);
-  if (!project) {
-    return res.status(404).json({ error: ERR_PROJECT_NOT_FOUND });
-  }
-
-  const projectDefs = projectDefaults.getByProjectId(req.params.id);
+/**
+ * Validate and prepare the session configuration from the request body.
+ * Returns { config, nextTemplateId } on success, or { error, status } on failure.
+ */
+async function validateAndPrepareSessionConfig(reqBody, reqFiles, projectId, project) {
+  const projectDefs = projectDefaults.getByProjectId(projectId);
   const systemDefaults = ProjectDefaultsRepository.getSystemDefaults();
-  const config = prepareSessionConfig(req.body, projectDefs, systemDefaults);
-  config.files = req.files || [];
+  const config = prepareSessionConfig(reqBody, projectDefs, systemDefaults);
+  config.files = reqFiles || [];
 
   if (!config.prompt) {
-    return res.status(400).json({ error: 'Prompt is required' });
+    return { error: 'Prompt is required', status: 400 };
   }
 
   // Apply template overrides and resolve nextTemplateId
   applyTemplateOverrides(config);
-  const { nextTemplateId, error: nextTemplateError } = resolveNextTemplateId(req.body, config.nextTemplateId || null);
+  const { nextTemplateId, error: nextTemplateError } = resolveNextTemplateId(reqBody, config.nextTemplateId || null);
   if (nextTemplateError) {
-    return res.status(400).json({ error: nextTemplateError });
+    return { error: nextTemplateError, status: 400 };
   }
   config.nextTemplateId = nextTemplateId;
 
-  const initialStatus = determineInitialStatus(config);
-
   // Validate git settings for git repos
-  const gitError = await validateGitSettings(config, project);
+  const { config: updatedConfig, error: gitError } = await validateGitSettings(config, project);
   if (gitError) {
-    return res.status(400).json({ error: gitError });
+    return { error: gitError, status: 400 };
   }
+  Object.assign(config, updatedConfig);
+
+  return { config, nextTemplateId };
+}
+
+// POST /api/projects/:id/sessions - Create session
+// Supports both JSON and multipart/form-data (for file attachments)
+router.post('/:id/sessions', uploadMiddleware('files', 10), handleUploadError, async (req, res) => {
+  const project = projects.getById(req.params.id);
+  if (!project) {
+    return res.status(404).json({ error: ERR_PROJECT_NOT_FOUND });
+  }
+
+  const prepared = await validateAndPrepareSessionConfig(req.body, req.files, req.params.id, project);
+  if (prepared.error) {
+    return res.status(prepared.status).json({ error: prepared.error });
+  }
+
+  const { config, nextTemplateId } = prepared;
+  const initialStatus = determineInitialStatus(config);
 
   const sessionName = config.name || generateInitialName(config.prompt);
   const session = sessions.create(req.params.id, sessionName, config.prompt, {

package/packages/server/src/cli.js

@@ -0,0 +1,82 @@
+import { parseArgs } from 'node:util';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { DEFAULT_SERVER_PORT } from '../../shared/src/index.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function showHelp() {
+  console.log(`Usage: circuschief [options]
+
+Options:
+  -p, --port <number>  Port to listen on (env: PORT, default: ${DEFAULT_SERVER_PORT})
+  --no-analytics       Disable anonymous usage analytics
+  -h, --help           Show this help message
+  -V, --version        Show version number`);
+}
+
+function getVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(__dirname, '../package.json'), 'utf-8')
+    );
+    return pkg.version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+export function parseCliOptions(argv = process.argv) {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args: argv.slice(2),
+      strict: true,
+      options: {
+        port: {
+          type: 'string',
+          short: 'p',
+          default: process.env.PORT || String(DEFAULT_SERVER_PORT),
+        },
+        help: {
+          type: 'boolean',
+          short: 'h',
+          default: false,
+        },
+        version: {
+          type: 'boolean',
+          short: 'V',
+          default: false,
+        },
+        'no-analytics': {
+          type: 'boolean',
+          default: false,
+        },
+      },
+    }));
+  } catch (err) {
+    console.error(err.message);
+    showHelp();
+    process.exit(1);
+  }
+
+  if (values.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (values.version) {
+    console.log(getVersion());
+    process.exit(0);
+  }
+
+  const port = parseInt(values.port, 10);
+  if (isNaN(port) || port < 1 || port > 65535) {
+    console.error(`Error: Invalid port "${values.port}". Must be 1-65535.`);
+    process.exit(1);
+  }
+
+  return { port, disableAnalytics: values['no-analytics'] };
+}

package/packages/server/src/db/AgentCallLogRepository.js

@@ -133,6 +133,33 @@ export class AgentCallLogRepository extends BaseRepository {
       );
   }
 
+  /**
+   * Build WHERE conditions and params from filter options.
+   * @param {Object} options - Filter options
+   * @returns {{ conditions: string[], params: any[] }}
+   */
+  static buildFilters({ agentType, callType, status, model, sessionId, startDate, endDate }) {
+    const filterMap = [
+      [agentType, 'acl.agent_type = ?'],
+      [callType, 'acl.call_type = ?'],
+      [status, 'acl.status = ?'],
+      [model, 'acl.model = ?'],
+      [sessionId, 'acl.session_id = ?'],
+      [startDate, 'acl.started_at >= ?'],
+      [endDate, 'acl.started_at <= ?'],
+    ];
+
+    const conditions = [];
+    const params = [];
+    for (const [value, condition] of filterMap) {
+      if (value) {
+        conditions.push(condition);
+        params.push(value);
+      }
+    }
+    return { conditions, params };
+  }
+
   /**
    * Get all call logs with optional filtering, sorting, and pagination.
    * Returns { rows, total } where total is the full count (before limit/offset).
@@ -162,37 +189,9 @@ export class AgentCallLogRepository extends BaseRepository {
     const safeSortBy = SORTABLE_COLUMNS.includes(sortBy) ? sortBy : 'started_at';
     const safeSortOrder = sortOrder === 'ASC' ? 'ASC' : 'DESC';
 
-    const conditions = [];
-    const params = [];
-
-    if (agentType) {
-      conditions.push('acl.agent_type = ?');
-      params.push(agentType);
-    }
-    if (callType) {
-      conditions.push('acl.call_type = ?');
-      params.push(callType);
-    }
-    if (status) {
-      conditions.push('acl.status = ?');
-      params.push(status);
-    }
-    if (model) {
-      conditions.push('acl.model = ?');
-      params.push(model);
-    }
-    if (sessionId) {
-      conditions.push('acl.session_id = ?');
-      params.push(sessionId);
-    }
-    if (startDate) {
-      conditions.push('acl.started_at >= ?');
-      params.push(startDate);
-    }
-    if (endDate) {
-      conditions.push('acl.started_at <= ?');
-      params.push(endDate);
-    }
+    const { conditions, params } = AgentCallLogRepository.buildFilters({
+      agentType, callType, status, model, sessionId, startDate, endDate,
+    });
 
     const whereClause = conditions.length > 0 ? `WHERE ${  conditions.join(' AND ')}` : '';
 

package/packages/server/src/db/ConversationRepository.js

@@ -91,26 +91,31 @@ export class ConversationRepository extends BaseRepository {
    * @param {Object} data - Fields to update
    * @returns {Object} The updated conversation
    */
-  update(id, data) {
+  /**
+   * Build the SET clause fields from data, collecting updates and values.
+   * Handles the isActive special case (deactivating other conversations).
+   * @param {string} id - Conversation ID
+   * @param {Object} data - Fields to update
+   * @returns {{ updates: string[], values: any[] }}
+   */
+  #buildUpdateFields(id, data) {
+    const FIELD_MAP = {
+      name: 'name',
+      summary: 'summary',
+      summaryGeneratedAt: 'summary_generated_at',
+      claudeSessionId: 'claude_session_id',
+    };
+
     const updates = [];
     const values = [];
 
-    if (data.name !== undefined) {
-      updates.push('name = ?');
-      values.push(data.name);
-    }
-    if (data.summary !== undefined) {
-      updates.push('summary = ?');
-      values.push(data.summary);
-    }
-    if (data.summaryGeneratedAt !== undefined) {
-      updates.push('summary_generated_at = ?');
-      values.push(data.summaryGeneratedAt);
-    }
-    if (data.claudeSessionId !== undefined) {
-      updates.push('claude_session_id = ?');
-      values.push(data.claudeSessionId);
+    for (const [key, column] of Object.entries(FIELD_MAP)) {
+      if (data[key] !== undefined) {
+        updates.push(`${column} = ?`);
+        values.push(data[key]);
+      }
     }
+
     if (data.isActive !== undefined) {
       // If setting this conversation as active, deactivate others first
       if (data.isActive) {
@@ -125,6 +130,12 @@ export class ConversationRepository extends BaseRepository {
       values.push(data.isActive ? 1 : 0);
     }
 
+    return { updates, values };
+  }
+
+  update(id, data) {
+    const { updates, values } = this.#buildUpdateFields(id, data);
+
     if (updates.length === 0) {
       return this.getById(id);
     }

package/packages/server/src/db/ProjectRepository.js

@@ -61,42 +61,32 @@ export class ProjectRepository extends BaseRepository {
     return this.mapAll(rows);
   }
 
+  /**
+   * Field mapping from camelCase data keys to snake_case column names.
+   * Entries with a transform function apply that transform to the value.
+   */
+  static #FIELD_MAP = {
+    name: { column: 'name' },
+    workingDirectory: { column: 'working_directory' },
+    systemPrompt: { column: 'system_prompt' },
+    onSessionCreated: { column: 'on_session_created' },
+    onSessionDeleted: { column: 'on_session_deleted' },
+    prPollInterval: { column: 'pr_poll_interval' },
+    repoUrl: { column: 'repo_url' },
+    kanbanEnabled: { column: 'kanban_enabled', transform: (v) => v ? 1 : 0 },
+  };
+
   update(id, data) {
     const updates = [];
     const values = [];
 
-    if (data.name !== undefined) {
-      updates.push('name = ?');
-      values.push(data.name);
-    }
-    if (data.workingDirectory !== undefined) {
-      updates.push('working_directory = ?');
-      values.push(data.workingDirectory);
-    }
-    if (data.systemPrompt !== undefined) {
-      updates.push('system_prompt = ?');
-      values.push(data.systemPrompt);
-    }
-    if (data.onSessionCreated !== undefined) {
-      updates.push('on_session_created = ?');
-      values.push(data.onSessionCreated);
-    }
-    if (data.onSessionDeleted !== undefined) {
-      updates.push('on_session_deleted = ?');
-      values.push(data.onSessionDeleted);
-    }
-    if (data.prPollInterval !== undefined) {
-      updates.push('pr_poll_interval = ?');
-      values.push(data.prPollInterval);
-    }
-    if (data.repoUrl !== undefined) {
-      updates.push('repo_url = ?');
-      values.push(data.repoUrl);
-    }
-    if (data.kanbanEnabled !== undefined) {
-      updates.push('kanban_enabled = ?');
-      values.push(data.kanbanEnabled ? 1 : 0);
+    for (const [key, { column, transform }] of Object.entries(ProjectRepository.#FIELD_MAP)) {
+      if (data[key] !== undefined) {
+        updates.push(`${column} = ?`);
+        values.push(transform ? transform(data[key]) : data[key]);
+      }
     }
+
     if (updates.length === 0) return this.getById(id);
 
     updates.push('updated_at = ?');

package/packages/server/src/db/QuickResponseRepository.js

@@ -102,6 +102,15 @@ export class QuickResponseRepository extends BaseRepository {
    * @param {Object} data - Fields to update
    * @returns {Object|null} Updated quick response or null if not found
    */
+  /** @type {Array<[string, string, ((v: any) => any)?]>} [dataKey, columnName, transform?] */
+  static #UPDATE_FIELDS = [
+    ['label', 'label'],
+    ['content', 'content'],
+    ['autoSubmit', 'auto_submit', (v) => v ? 1 : 0],
+    ['category', 'category'],
+    ['sortOrder', 'sort_order'],
+  ];
+
   update(id, data) {
     const existing = this.getById(id);
     if (!existing) {
@@ -111,25 +120,11 @@ export class QuickResponseRepository extends BaseRepository {
     const updates = [];
     const values = [];
 
-    if (data.label !== undefined) {
-      updates.push('label = ?');
-      values.push(data.label);
-    }
-    if (data.content !== undefined) {
-      updates.push('content = ?');
-      values.push(data.content);
-    }
-    if (data.autoSubmit !== undefined) {
-      updates.push('auto_submit = ?');
-      values.push(data.autoSubmit ? 1 : 0);
-    }
-    if (data.category !== undefined) {
-      updates.push('category = ?');
-      values.push(data.category);
-    }
-    if (data.sortOrder !== undefined) {
-      updates.push('sort_order = ?');
-      values.push(data.sortOrder);
+    for (const [key, column, transform] of QuickResponseRepository.#UPDATE_FIELDS) {
+      if (data[key] !== undefined) {
+        updates.push(`${column} = ?`);
+        values.push(transform ? transform(data[key]) : data[key]);
+      }
     }
 
     if (updates.length > 0) {