@piecemaker-legal/piecemaker 1.0.0

package/server/modules/plugins/plugins.routes.ts

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import http from 'node:http';
+
+import express from 'express';
+
+import type { createPluginsService } from './plugins.service.js';
+
+function wildcardPath(req: express.Request): string {
+  return ((req.params as Record<string, string>)['0'] ?? '').trim();
+}
+
+function routeParameter(value: string | string[]): string {
+  return Array.isArray(value) ? value[0] ?? '' : value;
+}
+
+/** Creates plugin routes; transport streaming remains here while decisions live in the service. */
+export function createPluginsRouter(service: ReturnType<typeof createPluginsService>): express.Router {
+  const router = express.Router();
+  const respond = (operation: (req: express.Request) => unknown | Promise<unknown>) =>
+    async (req: express.Request, res: express.Response, next: express.NextFunction) => {
+      try { res.json(await operation(req)); } catch (error) { next(error); }
+    };
+
+  router.get('/', respond(() => service.list()));
+  router.get('/:name/manifest', respond((req) => service.getManifest(routeParameter(req.params.name))));
+  router.get('/:name/assets/*', async (req, res, next) => {
+    try {
+      const asset = service.resolveAsset(routeParameter(req.params.name), wildcardPath(req));
+      res.setHeader('Content-Type', asset.contentType);
+      res.setHeader('Cache-Control', 'no-store, no-cache, must-revalidate');
+      const stream = fs.createReadStream(asset.path);
+      stream.on('error', next);
+      stream.pipe(res);
+    } catch (error) { next(error); }
+  });
+  router.put('/:name/enable', respond((req) => service.setEnabled(routeParameter(req.params.name), req.body?.enabled)));
+  router.post('/install', respond((req) => service.install(req.body?.url)));
+  router.post('/:name/update', respond((req) => service.update(routeParameter(req.params.name))));
+  router.all('/:name/rpc/*', async (req, res, next) => {
+    try {
+      const { port, secrets } = await service.prepareRpc(routeParameter(req.params.name));
+      const headers: Record<string, string> = {
+        'content-type': String(req.headers['content-type'] ?? 'application/json'),
+      };
+      for (const [key, value] of Object.entries(secrets)) {
+        headers[`x-plugin-secret-${key.toLowerCase()}`] = String(value);
+      }
+      const query = req.url.includes('?') ? `?${req.url.split('?').slice(1).join('?')}` : '';
+      const proxyRequest = http.request({
+        hostname: '127.0.0.1', port, path: `/${wildcardPath(req)}${query}`, method: req.method, headers,
+      }, (proxyResponse) => {
+        res.writeHead(proxyResponse.statusCode ?? 502, proxyResponse.headers);
+        proxyResponse.pipe(res);
+      });
+      proxyRequest.on('error', next);
+      if (req.headers['content-length'] && req.body !== undefined) {
+        const body = JSON.stringify(req.body);
+        proxyRequest.setHeader('content-length', Buffer.byteLength(body));
+        proxyRequest.write(body);
+      }
+      proxyRequest.end();
+    } catch (error) { next(error); }
+  });
+  router.delete('/:name', respond((req) => service.uninstall(routeParameter(req.params.name))));
+  return router;
+}

package/server/modules/plugins/plugins.service.ts

@@ -0,0 +1,147 @@
+import { AppError } from '@/shared/utils.js';
+
+type PluginManifest = Record<string, unknown> & {
+  name: string;
+  dirName?: string;
+  enabled?: boolean;
+  server?: unknown;
+};
+
+type PluginConfig = Record<string, { enabled?: boolean; secrets?: Record<string, unknown> }>;
+
+type PluginDependencies = {
+  scanPlugins(): PluginManifest[];
+  readConfig(): PluginConfig;
+  saveConfig(config: PluginConfig): void;
+  getPluginDirectory(pluginName: string): string | null;
+  getPluginsDirectory(): string;
+  resolveAsset(pluginName: string, assetPath: string): string | null;
+  assetIsFile(assetPath: string): boolean;
+  contentType(assetPath: string): string;
+  install(url: string): Promise<unknown>;
+  update(pluginName: string): Promise<unknown>;
+  uninstall(pluginName: string): Promise<unknown>;
+  startServer(pluginName: string, pluginDirectory: string, serverConfig: unknown): Promise<number>;
+  stopServer(pluginName: string): Promise<void>;
+  getServerPort(pluginName: string): number | undefined;
+  isServerRunning(pluginName: string): boolean;
+  joinPath(...parts: string[]): string;
+  logError(message: string, error: unknown): void;
+};
+
+function validatePluginName(pluginName: string): void {
+  if (!/^[a-zA-Z0-9_-]+$/.test(pluginName)) {
+    throw new AppError('Invalid plugin name', { code: 'INVALID_PLUGIN_NAME', statusCode: 400 });
+  }
+}
+
+function normalizePluginManifest(value: unknown): PluginManifest {
+  if (typeof value !== 'object' || value === null) {
+    throw new AppError('Plugin manifest is invalid', {
+      code: 'INVALID_PLUGIN_MANIFEST',
+      statusCode: 400,
+    });
+  }
+  const manifest = value as Record<string, unknown>;
+  if (typeof manifest.name !== 'string') {
+    throw new AppError('Plugin manifest is missing its name', {
+      code: 'INVALID_PLUGIN_MANIFEST',
+      statusCode: 400,
+    });
+  }
+  return manifest as PluginManifest;
+}
+
+/** Creates plugin-management workflows around loader and process adapters. */
+export function createPluginsService(dependencies: PluginDependencies) {
+  async function startServerIfAvailable(plugin: PluginManifest): Promise<void> {
+    if (!plugin.server || dependencies.isServerRunning(plugin.name)) return;
+    const pluginDirectory = dependencies.getPluginDirectory(plugin.name);
+    if (!pluginDirectory) return;
+    try {
+      await dependencies.startServer(plugin.name, pluginDirectory, plugin.server);
+    } catch (error) {
+      dependencies.logError(`Failed to start plugin server for ${plugin.name}`, error);
+    }
+  }
+
+  return {
+    list() {
+      return {
+        plugins: dependencies.scanPlugins().map((plugin) => ({
+          ...plugin,
+          serverRunning: plugin.server ? dependencies.isServerRunning(plugin.name) : false,
+        })),
+      };
+    },
+    getManifest(pluginName: string) {
+      validatePluginName(pluginName);
+      const plugin = dependencies.scanPlugins().find((candidate) => candidate.name === pluginName);
+      if (!plugin) throw new AppError('Plugin not found', { code: 'PLUGIN_NOT_FOUND', statusCode: 404 });
+      return plugin;
+    },
+    resolveAsset(pluginName: string, assetPath: string) {
+      validatePluginName(pluginName);
+      if (!assetPath) throw new AppError('No asset path specified', { code: 'PLUGIN_ASSET_REQUIRED', statusCode: 400 });
+      const resolvedPath = dependencies.resolveAsset(pluginName, assetPath);
+      if (!resolvedPath || !dependencies.assetIsFile(resolvedPath)) {
+        throw new AppError('Asset not found', { code: 'PLUGIN_ASSET_NOT_FOUND', statusCode: 404 });
+      }
+      return { path: resolvedPath, contentType: dependencies.contentType(resolvedPath) };
+    },
+    async setEnabled(pluginName: string, enabled: unknown) {
+      validatePluginName(pluginName);
+      if (typeof enabled !== 'boolean') {
+        throw new AppError('"enabled" must be a boolean', { code: 'INVALID_PLUGIN_ENABLED', statusCode: 400 });
+      }
+      const plugin = this.getManifest(pluginName);
+      const config = dependencies.readConfig();
+      config[pluginName] = { ...config[pluginName], enabled };
+      dependencies.saveConfig(config);
+      if (plugin.server && enabled) await startServerIfAvailable(plugin);
+      if (plugin.server && !enabled && dependencies.isServerRunning(pluginName)) {
+        await dependencies.stopServer(pluginName);
+      }
+      return { success: true, name: pluginName, enabled };
+    },
+    async install(urlInput: unknown) {
+      const url = typeof urlInput === 'string' ? urlInput.trim() : '';
+      if (!url || (!url.startsWith('https://') && !url.startsWith('git@'))) {
+        throw new AppError('URL must start with https:// or git@', { code: 'INVALID_PLUGIN_URL', statusCode: 400 });
+      }
+      const plugin = normalizePluginManifest(await dependencies.install(url));
+      await startServerIfAvailable(plugin);
+      return { success: true, plugin };
+    },
+    async update(pluginName: string) {
+      validatePluginName(pluginName);
+      const wasRunning = dependencies.isServerRunning(pluginName);
+      if (wasRunning) await dependencies.stopServer(pluginName);
+      const plugin = normalizePluginManifest(await dependencies.update(pluginName));
+      if (wasRunning) await startServerIfAvailable(plugin);
+      return { success: true, plugin };
+    },
+    async prepareRpc(pluginName: string) {
+      validatePluginName(pluginName);
+      let port = dependencies.getServerPort(pluginName);
+      if (!port) {
+        const plugin = this.getManifest(pluginName);
+        if (!plugin.server) throw new AppError('Plugin server is not running', { code: 'PLUGIN_SERVER_UNAVAILABLE', statusCode: 503 });
+        if (!plugin.enabled) throw new AppError('Plugin is disabled', { code: 'PLUGIN_DISABLED', statusCode: 503 });
+        const pluginDirectory = dependencies.joinPath(
+          dependencies.getPluginsDirectory(),
+          plugin.dirName ?? plugin.name,
+        );
+        port = await dependencies.startServer(pluginName, pluginDirectory, plugin.server);
+      }
+      const secrets = dependencies.readConfig()[pluginName]?.secrets ?? {};
+      return { port, secrets };
+    },
+    async uninstall(pluginName: string) {
+      validatePluginName(pluginName);
+      if (dependencies.isServerRunning(pluginName)) await dependencies.stopServer(pluginName);
+      await dependencies.uninstall(pluginName);
+      return { success: true, name: pluginName };
+    },
+  };
+}

package/server/modules/plugins/tests/plugins.service.test.ts

@@ -0,0 +1,32 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createPluginsService } from '../plugins.service.js';
+
+type Dependencies = Parameters<typeof createPluginsService>[0];
+
+function dependencies(overrides: Partial<Dependencies> = {}): Dependencies {
+  return {
+    scanPlugins: () => [], readConfig: () => ({}), saveConfig: () => undefined,
+    getPluginDirectory: () => null, getPluginsDirectory: () => '/plugins',
+    resolveAsset: () => null, assetIsFile: () => false, contentType: () => 'text/plain',
+    install: async () => ({ name: 'plugin', dirName: 'plugin' }),
+    update: async () => ({ name: 'plugin', dirName: 'plugin' }),
+    uninstall: async () => undefined, startServer: async () => 4000,
+    stopServer: async () => undefined, getServerPort: () => undefined,
+    isServerRunning: () => false, joinPath: (...parts) => parts.join('/'),
+    logError: () => undefined, ...overrides,
+  };
+}
+
+test('setEnabled persists configuration and starts an enabled plugin server', async () => {
+  const operations: string[] = [];
+  const service = createPluginsService(dependencies({
+    scanPlugins: () => [{ name: 'demo', dirName: 'demo', server: { entry: 'server.js' } }],
+    getPluginDirectory: () => '/plugins/demo',
+    saveConfig: () => operations.push('save'),
+    startServer: async () => { operations.push('start'); return 4000; },
+  }));
+  await service.setEnabled('demo', true);
+  assert.deepEqual(operations, ['save', 'start']);
+});

package/server/modules/projects/index.ts

@@ -0,0 +1,11 @@
+export {
+  generateDisplayName,
+  getProjectsWithSessions,
+} from './services/projects-with-sessions-fetch.service.js';
+export { updateProjectDisplayName } from './services/project-management.service.js';
+// createProject: used by the worktrees module to register a worktree directory as a switchable project.
+export { createProject } from './services/project-management.service.js';
+// deleteOrArchiveProject: used by Projects routes and Worktrees cleanup to hide or permanently remove a project.
+export { deleteOrArchiveProject, deleteSessionJsonlFilesForProjectPath } from './services/project-delete.service.js';
+// restoreArchivedProject: used by the worktrees module to re-activate an archived project when its worktree is reopened.
+export { restoreArchivedProject } from './services/project-delete.service.js';

package/server/modules/projects/projects.routes.ts

@@ -0,0 +1,273 @@
+import express from 'express';
+
+import { createProject, updateProjectDisplayName } from '@/modules/projects/services/project-management.service.js';
+import { startCloneProject } from '@/modules/projects/services/project-clone.service.js';
+import { getProjectTaskMaster } from '@/modules/projects/services/projects-has-taskmaster.service.js';
+import { AppError, asyncHandler, createApiSuccessResponse } from '@/shared/utils.js';
+import { getArchivedProjectsWithSessions, getProjectSessionsPage, getProjectsWithSessions } from '@/modules/projects/services/projects-with-sessions-fetch.service.js';
+import { deleteOrArchiveProject, restoreArchivedProject } from '@/modules/projects/services/project-delete.service.js';
+import { applyLegacyStarredProjectIds, toggleProjectStar } from '@/modules/projects/services/project-star.service.js';
+
+const router = express.Router();
+
+type AuthenticatedUser = {
+  id?: number | string;
+};
+
+function readQueryStringValue(value: unknown): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (Array.isArray(value) && typeof value[0] === 'string') {
+    return value[0];
+  }
+
+  return '';
+}
+
+function readOptionalNumericQueryValue(value: unknown): number | null {
+  const rawValue = readQueryStringValue(value).trim();
+  if (!rawValue) {
+    return null;
+  }
+
+  const parsedValue = Number.parseInt(rawValue, 10);
+  return Number.isNaN(parsedValue) ? null : parsedValue;
+}
+
+function parseNonNegativeIntQuery(value: unknown, name: string, fallback: number): number {
+  const rawValue = readQueryStringValue(value).trim();
+  if (!rawValue) {
+    return fallback;
+  }
+
+  const parsedValue = Number.parseInt(rawValue, 10);
+  if (Number.isNaN(parsedValue) || parsedValue < 0) {
+    throw new AppError(`${name} must be a non-negative integer`, {
+      code: 'INVALID_QUERY_PARAMETER',
+      statusCode: 400,
+    });
+  }
+
+  return parsedValue;
+}
+
+function resolveRouteErrorMessage(error: unknown): string {
+  if (error instanceof AppError) {
+    return error.message;
+  }
+
+  if (error instanceof Error && error.message) {
+    return error.message;
+  }
+
+  return 'Failed to clone repository';
+}
+
+router.get(
+  '/',
+  asyncHandler(async (req, res) => {
+    const skipSynchronization =
+      readQueryStringValue(req.query.skipSynchronization).trim() === '1' ||
+      readQueryStringValue(req.query.skipSync).trim() === '1';
+    const sessionsLimit = readOptionalNumericQueryValue(req.query.sessionsLimit) ?? undefined;
+    const sessionsOffset = readOptionalNumericQueryValue(req.query.sessionsOffset) ?? undefined;
+    const projects = await getProjectsWithSessions({
+      skipSynchronization,
+      sessionsLimit,
+      sessionsOffset,
+    });
+    res.json(projects);
+  }),
+);
+
+router.get(
+  '/archived',
+  asyncHandler(async (_req, res) => {
+    const projects = await getArchivedProjectsWithSessions();
+    res.json(createApiSuccessResponse({ projects }));
+  }),
+);
+
+router.get(
+  '/:projectId/sessions',
+  asyncHandler(async (req, res) => {
+    const projectId = typeof req.params.projectId === 'string' ? req.params.projectId : '';
+    const limit = parseNonNegativeIntQuery(req.query.limit, 'limit', 20);
+    const offset = parseNonNegativeIntQuery(req.query.offset, 'offset', 0);
+    const sessionsPage = await getProjectSessionsPage(projectId, { limit, offset });
+    res.json(sessionsPage);
+  }),
+);
+
+router.post(
+  '/create-project',
+  asyncHandler(async (req, res) => {
+    const requestBody = req.body as Record<string, unknown>;
+    const projectPath = typeof requestBody.path === 'string' ? requestBody.path : '';
+    const customName = typeof requestBody.customName === 'string' ? requestBody.customName : null;
+
+    if (requestBody.workspaceType !== undefined) {
+      throw new AppError('workspaceType is no longer supported. Use the single create-project flow.', {
+        code: 'LEGACY_WORKSPACE_TYPE_UNSUPPORTED',
+        statusCode: 400,
+      });
+    }
+
+    if (requestBody.githubUrl || requestBody.githubTokenId || requestBody.newGithubToken) {
+      throw new AppError('Repository cloning is not supported on create-project', {
+        code: 'CLONE_NOT_SUPPORTED_ON_CREATE_PROJECT',
+        statusCode: 400,
+        details: 'Use /api/projects/clone-progress for cloning workflows',
+      });
+    }
+
+    const projectCreationResult = await createProject({
+      projectPath,
+      customName,
+    });
+
+    res.json({
+      success: true,
+      project: projectCreationResult.project,
+      message:
+        projectCreationResult.outcome === 'reactivated_archived'
+          ? 'Archived project path reused successfully'
+          : 'Project created successfully',
+    });
+  }),
+);
+
+/**
+ * One-time (or idempotent) migration: apply legacy `localStorage` starred projectIds to the DB, then clear client storage.
+ */
+router.post(
+  '/migrate-legacy-stars',
+  asyncHandler(async (req, res) => {
+    const projectIds = Array.isArray((req.body as { projectIds?: unknown })?.projectIds)
+      ? ((req.body as { projectIds: unknown[] }).projectIds as unknown[]).map((x) => String(x))
+      : [];
+    const { updated } = applyLegacyStarredProjectIds(projectIds);
+    res.json({ success: true, updated });
+  }),
+);
+
+router.get('/clone-progress', async (req, res) => {
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+  res.flushHeaders();
+
+  const sendEvent = (type: string, data: Record<string, unknown>) => {
+    if (res.writableEnded) {
+      return;
+    }
+
+    res.write(`data: ${JSON.stringify({ type, ...data })}\n\n`);
+  };
+
+  let cloneOperation: Awaited<ReturnType<typeof startCloneProject>> | null = null;
+  const closeListener = () => {
+    cloneOperation?.cancel();
+  };
+  req.on('close', closeListener);
+
+  try {
+    const queryParams = req.query as Record<string, unknown>;
+    const workspacePath = readQueryStringValue(queryParams.path);
+    const githubUrl = readQueryStringValue(queryParams.githubUrl);
+    const githubTokenId = readOptionalNumericQueryValue(queryParams.githubTokenId);
+    const newGithubToken = readQueryStringValue(queryParams.newGithubToken) || null;
+
+    const authenticatedUser = (req as typeof req & { user?: AuthenticatedUser }).user;
+    const userId = authenticatedUser?.id;
+    if (userId === undefined || userId === null) {
+      throw new AppError('Authenticated user is required', {
+        code: 'AUTHENTICATION_REQUIRED',
+        statusCode: 401,
+      });
+    }
+
+    cloneOperation = await startCloneProject(
+      {
+        workspacePath,
+        githubUrl,
+        githubTokenId,
+        newGithubToken,
+        userId,
+      },
+      {
+        onProgress: (message) => {
+          sendEvent('progress', { message });
+        },
+        onComplete: ({ project, message }) => {
+          sendEvent('complete', { project, message });
+        },
+      },
+    );
+
+    await cloneOperation.waitForCompletion;
+  } catch (error) {
+    sendEvent('error', { message: resolveRouteErrorMessage(error) });
+  } finally {
+    req.off('close', closeListener);
+    if (!res.writableEnded) {
+      res.end();
+    }
+  }
+});
+
+router.get(
+  '/:projectId/taskmaster',
+  asyncHandler(async (req, res) => {
+    const projectId = typeof req.params.projectId === 'string' ? req.params.projectId : '';
+    const taskMasterDetails = await getProjectTaskMaster(projectId);
+    res.json(taskMasterDetails);
+  }),
+);
+
+router.put('/:projectId/rename', (req, res) => {
+  try {
+    const projectId = typeof req.params.projectId === 'string' ? req.params.projectId : '';
+    const { displayName } = req.body as { displayName?: unknown };
+    updateProjectDisplayName(projectId, displayName);
+    res.json({ success: true });
+  } catch (error) {
+    res.status(500).json({ error: error instanceof Error ? error.message : 'Failed to rename project' });
+  }
+});
+
+router.post(
+  '/:projectId/toggle-star',
+  asyncHandler(async (req, res) => {
+    const projectId = typeof req.params.projectId === 'string' ? req.params.projectId : '';
+    const { isStarred } = toggleProjectStar(projectId);
+    res.json({ success: true, isStarred });
+  }),
+);
+
+router.post(
+  '/:projectId/restore',
+  asyncHandler(async (req, res) => {
+    const projectId = typeof req.params.projectId === 'string' ? req.params.projectId : '';
+    restoreArchivedProject(projectId);
+    res.json(createApiSuccessResponse({ projectId, isArchived: false }));
+  }),
+);
+
+/**
+ * - `force` not set / false: archive project in DB only (`isArchived` = 1; hidden from active list).
+ * - `force=true`: remove DB row, delete session rows for that path, remove all `*.jsonl` under the Claude project dir.
+ */
+router.delete(
+  '/:projectId',
+  asyncHandler(async (req, res) => {
+    const projectId = typeof req.params.projectId === 'string' ? req.params.projectId : '';
+    const force = req.query.force === 'true';
+    await deleteOrArchiveProject(projectId, force);
+    res.json({ success: true });
+  }),
+);
+
+export default router;