circuschief 0.8.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "circuschief",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "description": "Local-first web UI for managing Claude Code sessions",
   "type": "module",
   "bin": {

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

@@ -8,6 +8,7 @@ import { databaseManager } from '../db/DatabaseManager.js';
 
 // Error message constants
 const ERR_SESSION_NOT_FOUND = 'Session not found';
+const ERR_BUTTON_NOT_FOUND = 'Circus Command not found';
 
 const router = Router({ mergeParams: true });
 
@@ -64,14 +65,14 @@ function broadcastCommandRunError({ sessionId, projectId, runId, buttonId, error
   });
 }
 
-// GET /api/projects/:projectId/command-buttons - List all command buttons for project
+// GET /api/projects/:projectId/circus-commands - List all command buttons for project
 router.get('/', (req, res) => {
   const { projectId } = req.params;
   const buttons = commandButtons.getByProjectId(projectId);
   res.json(buttons);
 });
 
-// GET /api/projects/:projectId/command-buttons/latest-runs - Get latest run for each button per session in project
+// GET /api/projects/:projectId/circus-commands/latest-runs - Get latest run for each button per session in project
 router.get('/latest-runs', (req, res) => {
   const { projectId } = req.params;
 
@@ -85,7 +86,7 @@ router.get('/latest-runs', (req, res) => {
   res.json(latestRuns);
 });
 
-// POST /api/projects/:projectId/command-buttons - Create new command button
+// POST /api/projects/:projectId/circus-commands - Create new command button
 router.post('/', (req, res) => {
   const result = CreateCommandButtonRequest.safeParse(req.body);
   if (!result.success) {
@@ -103,20 +104,20 @@ router.post('/', (req, res) => {
   res.status(201).json(button);
 });
 
-// GET /api/projects/:projectId/command-buttons/:id - Get single button
+// GET /api/projects/:projectId/circus-commands/:id - Get single button
 router.get('/:id', (req, res) => {
   const button = commandButtons.getById(req.params.id);
   if (!button) {
-    return res.status(404).json({ error: 'Command button not found' });
+    return res.status(404).json({ error: ERR_BUTTON_NOT_FOUND });
   }
   res.json(button);
 });
 
-// PATCH /api/projects/:projectId/command-buttons/:id - Update button
+// PATCH /api/projects/:projectId/circus-commands/:id - Update button
 router.patch('/:id', (req, res) => {
   const button = commandButtons.getById(req.params.id);
   if (!button) {
-    return res.status(404).json({ error: 'Command button not found' });
+    return res.status(404).json({ error: ERR_BUTTON_NOT_FOUND });
   }
 
   const result = UpdateCommandButtonRequest.safeParse(req.body);
@@ -135,18 +136,18 @@ router.patch('/:id', (req, res) => {
   res.json(updated);
 });
 
-// DELETE /api/projects/:projectId/command-buttons/:id - Delete button
+// DELETE /api/projects/:projectId/circus-commands/:id - Delete button
 router.delete('/:id', (req, res) => {
   const button = commandButtons.getById(req.params.id);
   if (!button) {
-    return res.status(404).json({ error: 'Command button not found' });
+    return res.status(404).json({ error: ERR_BUTTON_NOT_FOUND });
   }
 
   commandButtons.delete(req.params.id);
   res.status(204).send();
 });
 
-// POST /api/sessions/:sessionId/command-buttons/:buttonId/run - Execute button command
+// POST /api/sessions/:sessionId/circus-commands/:buttonId/run - Execute button command
 router.post('/run/:buttonId', (req, res) => {
   const { sessionId, buttonId } = req.params;
 
@@ -157,7 +158,7 @@ router.post('/run/:buttonId', (req, res) => {
 
   const button = commandButtons.getById(buttonId);
   if (!button) {
-    return res.status(404).json({ error: 'Command button not found' });
+    return res.status(404).json({ error: ERR_BUTTON_NOT_FOUND });
   }
 
   const workingDirectory = session.gitWorktree || session.project?.workingDirectory || process.cwd();
@@ -181,7 +182,7 @@ router.post('/run/:buttonId', (req, res) => {
   })();
 });
 
-// GET /api/sessions/:sessionId/command-buttons/runs - Get active runs for session
+// GET /api/sessions/:sessionId/circus-commands/runs - Get active runs for session
 router.get('/runs', (req, res) => {
   const { sessionId } = req.params;
 
@@ -221,7 +222,7 @@ router.get('/runs', (req, res) => {
   res.json(Array.from(runMap.values()));
 });
 
-// GET /api/sessions/:sessionId/command-buttons/runs/:runId - Get single run by ID
+// GET /api/sessions/:sessionId/circus-commands/runs/:runId - Get single run by ID
 router.get('/runs/:runId', (req, res) => {
   const { sessionId, runId } = req.params;
 
@@ -256,7 +257,7 @@ router.get('/runs/:runId', (req, res) => {
   });
 });
 
-// DELETE /api/sessions/:sessionId/command-buttons/runs/:runId - Delete a command run record
+// DELETE /api/sessions/:sessionId/circus-commands/runs/:runId - Delete a command run record
 router.delete('/runs/:runId', (req, res) => {
   const { sessionId, runId } = req.params;
 
@@ -292,7 +293,7 @@ router.delete('/runs/:runId', (req, res) => {
   res.status(204).send();
 });
 
-// POST /api/sessions/:sessionId/command-buttons/runs/:runId/kill - Kill running command
+// POST /api/sessions/:sessionId/circus-commands/runs/:runId/kill - Kill running command
 router.post('/runs/:runId/kill', (req, res) => {
   const { sessionId, runId } = req.params;
 

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

@@ -4,11 +4,11 @@ import { CreateCommandButtonRequest, UpdateCommandButtonRequest } from '../../..
 
 // Error message constants
 const ERR_PROJECT_NOT_FOUND = 'Project not found';
-const ERR_BUTTON_NOT_FOUND = 'Command button not found';
+const ERR_BUTTON_NOT_FOUND = 'Circus Command not found';
 
 const router = Router({ mergeParams: true });
 
-// GET /api/projects/:id/command-buttons - List all command buttons for project
+// GET /api/projects/:id/circus-commands - List all command buttons for project
 router.get('/', (req, res) => {
   const project = projects.getById(req.params.id);
   if (!project) {
@@ -19,7 +19,7 @@ router.get('/', (req, res) => {
   res.json(buttons);
 });
 
-// POST /api/projects/:id/command-buttons - Create new command button
+// POST /api/projects/:id/circus-commands - Create new command button
 router.post('/', (req, res) => {
   const project = projects.getById(req.params.id);
   if (!project) {
@@ -42,7 +42,7 @@ router.post('/', (req, res) => {
   res.status(201).json(button);
 });
 
-// GET /api/projects/:id/command-buttons/:buttonId - Get single button
+// GET /api/projects/:id/circus-commands/:buttonId - Get single button
 router.get('/:buttonId', (req, res) => {
   const project = projects.getById(req.params.id);
   if (!project) {
@@ -56,7 +56,7 @@ router.get('/:buttonId', (req, res) => {
   res.json(button);
 });
 
-// PATCH /api/projects/:id/command-buttons/:buttonId - Update button
+// PATCH /api/projects/:id/circus-commands/:buttonId - Update button
 router.patch('/:buttonId', (req, res) => {
   const project = projects.getById(req.params.id);
   if (!project) {
@@ -77,7 +77,7 @@ router.patch('/:buttonId', (req, res) => {
   res.json(updated);
 });
 
-// DELETE /api/projects/:id/command-buttons/:buttonId - Delete button
+// DELETE /api/projects/:id/circus-commands/:buttonId - Delete button
 router.delete('/:buttonId', (req, res) => {
   const project = projects.getById(req.params.id);
   if (!project) {

package/packages/server/src/api/projects-session-create.js

@@ -0,0 +1,109 @@
+import { sessions, projectDefaults } from '../database.js';
+import { ProjectDefaultsRepository } from '../db/ProjectDefaultsRepository.js';
+import { broadcastToProject } from '../websocket.js';
+import { WS_MESSAGE_TYPES } from '../../../shared/src/index.js';
+import {
+  generateInitialName,
+  prepareSessionConfig,
+  applyTemplateOverrides,
+  resolveNextTemplateId,
+  buildSchedulingUpdate,
+  setupAndStartSession,
+} from './projects-session-helpers.js';
+import { validateGitSettings } from './projects-helpers.js';
+
+/**
+ * Validate and prepare the session configuration from the request body.
+ * Returns { config, nextTemplateId } on success, or { error, status } on failure.
+ */
+export async function validateAndPrepareSessionConfig(reqBody, reqFiles, projectId, project) {
+  const projectDefs = projectDefaults.getByProjectId(projectId);
+  const systemDefaults = ProjectDefaultsRepository.getSystemDefaults();
+  const config = prepareSessionConfig(reqBody, projectDefs, systemDefaults);
+  config.files = reqFiles || [];
+
+  if (!config.prompt) {
+    return { error: 'Prompt is required', status: 400 };
+  }
+
+  if (config.schedulingError) {
+    return { error: config.schedulingError, status: 400 };
+  }
+
+  if (config.parentSessionId) {
+    const parentSession = sessions.getById(config.parentSessionId);
+    if (!parentSession) {
+      return { error: 'Parent session not found', status: 404 };
+    }
+    if (parentSession.projectId !== projectId) {
+      return { error: 'Parent session does not belong to this project', status: 400 };
+    }
+  }
+
+  // Apply template overrides and resolve nextTemplateId
+  applyTemplateOverrides(config);
+  const { nextTemplateId, error: nextTemplateError } = resolveNextTemplateId(reqBody, config.nextTemplateId || null);
+  if (nextTemplateError) {
+    return { error: nextTemplateError, status: 400 };
+  }
+  config.nextTemplateId = nextTemplateId;
+
+  // Validate git settings for git repos
+  const { config: updatedConfig, error: gitError } = await validateGitSettings(config, project);
+  if (gitError) {
+    return { error: gitError, status: 400 };
+  }
+  Object.assign(config, updatedConfig);
+
+  return { config, nextTemplateId };
+}
+
+/**
+ * Create the session row and apply any post-create updates.
+ * Returns the created session (already persisted in DB).
+ */
+export function createSessionRow(projectId, config, nextTemplateId, initialStatus) {
+  const sessionName = config.name || generateInitialName(config.prompt);
+  const session = sessions.create(projectId, sessionName, config.prompt, {
+    mode: config.mode,
+    thinkingEnabled: config.thinkingEnabled,
+    gitBranch: config.gitBranch,
+    parentSessionId: config.parentSessionId,
+    status: initialStatus,
+    model: config.model,
+    providerId: config.providerId,
+    effortLevel: config.effortLevel,
+    agentType: config.agentType,
+  });
+
+  const postCreateUpdate = {
+    ...(nextTemplateId ? { nextTemplateId } : {}),
+    ...buildSchedulingUpdate(config, initialStatus),
+  };
+  if (Object.keys(postCreateUpdate).length > 0) {
+    sessions.update(session.id, postCreateUpdate);
+  }
+  return session;
+}
+
+/**
+ * Run setupAndStartSession and translate any failure into an error response,
+ * marking the session as errored and broadcasting the update.
+ */
+export async function startSessionOrFail(req, res, { session, config, project }) {
+  try {
+    const { updatedSession } = await setupAndStartSession({
+      session, config, project, projectId: req.params.id, files: config.files,
+    });
+    return res.status(201).json(updatedSession);
+  } catch (error) {
+    console.error('Git setup error:', error);
+    const updatedSession = sessions.update(session.id, { status: 'error', error: error.message });
+    broadcastToProject(req.params.id, WS_MESSAGE_TYPES.SESSION_UPDATED, {
+      projectId: req.params.id,
+      sessionId: session.id,
+      session: updatedSession,
+    });
+    return res.status(500).json({ error: `Git setup failed: ${error.message}` });
+  }
+}

package/packages/server/src/api/projects-session-defaults.js

@@ -0,0 +1,51 @@
+import { Router } from 'express';
+import { projects, projectDefaults } from '../database.js';
+import { ProjectSessionDefaultsRequest } from '../../../shared/src/contracts/projects.js';
+
+const ERR_PROJECT_NOT_FOUND = 'Project not found';
+
+const router = Router({ mergeParams: true });
+
+// GET /api/projects/:id/session-defaults - Get session defaults for project
+router.get('/', (req, res) => {
+  const project = projects.getById(req.params.id);
+  if (!project) {
+    return res.status(404).json({ error: ERR_PROJECT_NOT_FOUND });
+  }
+
+  const defaults = projectDefaults.getByProjectId(req.params.id);
+  if (!defaults) {
+    return res.json(null);
+  }
+
+  res.json(defaults);
+});
+
+// POST /api/projects/:id/session-defaults - Update/create session defaults for project
+router.post('/', (req, res) => {
+  const project = projects.getById(req.params.id);
+  if (!project) {
+    return res.status(404).json({ error: ERR_PROJECT_NOT_FOUND });
+  }
+
+  const result = ProjectSessionDefaultsRequest.safeParse(req.body);
+  if (!result.success) {
+    return res.status(400).json({ error: result.error.issues[0].message });
+  }
+
+  const updated = projectDefaults.upsert(req.params.id, result.data);
+  res.status(200).json(updated);
+});
+
+// DELETE /api/projects/:id/session-defaults - Reset session defaults for project
+router.delete('/', (req, res) => {
+  const project = projects.getById(req.params.id);
+  if (!project) {
+    return res.status(404).json({ error: ERR_PROJECT_NOT_FOUND });
+  }
+
+  projectDefaults.resetToDefaults(req.params.id);
+  res.json({ message: 'Session defaults reset to system defaults' });
+});
+
+export default router;

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

@@ -6,6 +6,9 @@ import { executeHookAsync } from '../services/hookService.js';
 import { broadcastToProject } from '../websocket.js';
 import { WS_MESSAGE_TYPES, DEFAULT_RESCHEDULE_DELAY_MINUTES } from '../../../shared/src/index.js';
 
+const SCHEDULED_AT_FORMAT_MESSAGE = 'scheduledAt must be a valid ISO 8601 date-time string with a timezone, for example "2026-06-12T14:00:00Z".';
+const ISO_8601_DATE_TIME_WITH_TIMEZONE = /^(\d{4})-(\d{2})-(\d{2})T([01]\d|2[0-3]):([0-5]\d):([0-5]\d)(?:\.\d+)?(Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/;
+
 /**
  * Generate an initial session name from the prompt
  * This will be replaced by a better name when the summary is generated
@@ -83,14 +86,57 @@ export function resolveThinkingEnabled(body, projectDefs, systemDefaults) {
   return systemDefaults.thinkingEnabled;
 }
 
+function hasValidDateParts(year, month, day) {
+  const parsed = new Date(Date.UTC(year, month - 1, day));
+  return parsed.getUTCFullYear() === year
+    && parsed.getUTCMonth() === month - 1
+    && parsed.getUTCDate() === day;
+}
+
+/**
+ * Parse scheduledAt from the public API contract.
+ * @param {*} value - Raw scheduledAt value
+ * @returns {{ value: number|undefined, error: string|null }}
+ */
+export function parseScheduledAt(value) {
+  if (value === undefined || value === null || value === '') {
+    return { value: undefined, error: null };
+  }
+
+  if (typeof value !== 'string') {
+    return { value: undefined, error: SCHEDULED_AT_FORMAT_MESSAGE };
+  }
+
+  const match = ISO_8601_DATE_TIME_WITH_TIMEZONE.exec(value);
+  if (!match) {
+    return { value: undefined, error: SCHEDULED_AT_FORMAT_MESSAGE };
+  }
+
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  if (!hasValidDateParts(year, month, day)) {
+    return { value: undefined, error: SCHEDULED_AT_FORMAT_MESSAGE };
+  }
+
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp)) {
+    return { value: undefined, error: SCHEDULED_AT_FORMAT_MESSAGE };
+  }
+
+  return { value: timestamp, error: null };
+}
+
 /**
  * Parse scheduling fields from request body.
  * @param {object} body - Request body
  * @returns {object} Scheduling configuration
  */
 export function parseSchedulingConfig(body) {
+  const scheduledAt = parseScheduledAt(body.scheduledAt);
   return {
-    scheduledAt: body.scheduledAt ? parseInt(body.scheduledAt, 10) : undefined,
+    scheduledAt: scheduledAt.value,
+    schedulingError: scheduledAt.error,
     autoRescheduleEnabled: body.autoRescheduleEnabled === true || body.autoRescheduleEnabled === 'true',
     rescheduleDelayMinutes: body.rescheduleDelayMinutes ? parseInt(body.rescheduleDelayMinutes, 10) : DEFAULT_RESCHEDULE_DELAY_MINUTES,
     rescheduleOnTokenLimit: body.rescheduleOnTokenLimit !== false && body.rescheduleOnTokenLimit !== 'false',

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

@@ -0,0 +1,38 @@
+import { Router } from 'express';
+import { projects, sessionTemplates } from '../database.js';
+import { CreateSessionTemplateRequest } from '../../../shared/src/contracts/templates.js';
+
+const ERR_PROJECT_NOT_FOUND = 'Project not found';
+const router = Router({ mergeParams: true });
+
+// GET - List available templates for project (project + global)
+router.get('/', (req, res) => {
+  const project = projects.getById(req.params.id);
+  if (!project) {
+    return res.status(404).json({ error: ERR_PROJECT_NOT_FOUND });
+  }
+
+  const available = sessionTemplates.getAvailableForProject(req.params.id);
+  res.json(available);
+});
+
+// POST - Create project template
+router.post('/', (req, res) => {
+  const project = projects.getById(req.params.id);
+  if (!project) {
+    return res.status(404).json({ error: ERR_PROJECT_NOT_FOUND });
+  }
+
+  const result = CreateSessionTemplateRequest.safeParse(req.body);
+  if (!result.success) {
+    return res.status(400).json({ error: result.error.issues[0].message });
+  }
+
+  const template = sessionTemplates.create({
+    projectId: req.params.id,
+    ...result.data,
+  });
+  res.status(201).json(template);
+});
+
+export default router;