@piecemaker-legal/piecemaker 1.0.0

package/server/modules/taskmaster/taskmaster.service.ts

@@ -0,0 +1,132 @@
+import path from 'node:path';
+
+type TaskmasterServiceDependencies = {
+    readTextFile(filePath: string): Promise<string>;
+    getHomeDirectory(): string;
+};
+
+/**
+ * Creates TaskMaster status workflows for the TaskMaster composition root.
+ * The returned service is consumed by TaskMaster routes so filesystem and
+ * environment access remain explicit production dependencies.
+ */
+export function createTaskmasterService(dependencies: TaskmasterServiceDependencies) {
+    return {
+        /** Detects TaskMaster in the user's Claude MCP configuration without exposing secret values. */
+        async detectMcpServer() {
+            const homeDirectory = dependencies.getHomeDirectory();
+            const configurationPaths = [
+                path.join(homeDirectory, '.claude.json'),
+                path.join(homeDirectory, '.claude', 'settings.json'),
+            ];
+            let configuration: Record<string, unknown> | null = null;
+            let configurationPath: string | null = null;
+
+            for (const candidatePath of configurationPaths) {
+                try {
+                    const parsedConfiguration = JSON.parse(
+                        await dependencies.readTextFile(candidatePath),
+                    ) as unknown;
+                    if (typeof parsedConfiguration === 'object' && parsedConfiguration !== null) {
+                        configuration = parsedConfiguration as Record<string, unknown>;
+                        configurationPath = candidatePath;
+                        break;
+                    }
+                } catch {
+                    // A missing or malformed candidate must not prevent checking the fallback file.
+                }
+            }
+
+            if (!configuration) {
+                return {
+                    hasMCPServer: false,
+                    reason: 'No Claude configuration file found',
+                    hasConfig: false,
+                };
+            }
+
+            const serverGroups: Array<{
+                scope: string;
+                projectPath?: string;
+                servers: Record<string, unknown>;
+            }> = [];
+
+            if (typeof configuration.mcpServers === 'object' && configuration.mcpServers !== null) {
+                serverGroups.push({
+                    scope: 'user',
+                    servers: configuration.mcpServers as Record<string, unknown>,
+                });
+            }
+
+            if (typeof configuration.projects === 'object' && configuration.projects !== null) {
+                for (const [projectPath, projectValue] of Object.entries(configuration.projects)) {
+                    const projectConfiguration = typeof projectValue === 'object' && projectValue !== null
+                        ? projectValue as Record<string, unknown>
+                        : {};
+
+                    if (
+                        typeof projectConfiguration.mcpServers === 'object'
+                        && projectConfiguration.mcpServers !== null
+                    ) {
+                        serverGroups.push({
+                            scope: 'local',
+                            projectPath,
+                            servers: projectConfiguration.mcpServers as Record<string, unknown>,
+                        });
+                    }
+                }
+            }
+
+            for (const serverGroup of serverGroups) {
+                for (const [serverName, serverValue] of Object.entries(serverGroup.servers)) {
+                    const serverConfiguration = typeof serverValue === 'object' && serverValue !== null
+                        ? serverValue as Record<string, unknown>
+                        : {};
+                    const command = typeof serverConfiguration.command === 'string'
+                        ? serverConfiguration.command
+                        : null;
+                    const url = typeof serverConfiguration.url === 'string'
+                        ? serverConfiguration.url
+                        : null;
+                    const isTaskmasterServer = serverName === 'task-master-ai'
+                        || serverName.includes('task-master')
+                        || command?.includes('task-master');
+
+                    if (!isTaskmasterServer) {
+                        continue;
+                    }
+
+                    const environmentVariables = (
+                        typeof serverConfiguration.env === 'object'
+                        && serverConfiguration.env !== null
+                    )
+                        ? serverConfiguration.env as Record<string, unknown>
+                        : {};
+
+                    return {
+                        hasMCPServer: true,
+                        isConfigured: Boolean(command || url),
+                        hasApiKeys: Object.keys(environmentVariables).length > 0,
+                        scope: serverGroup.scope,
+                        ...(serverGroup.projectPath ? { projectPath: serverGroup.projectPath } : {}),
+                        config: {
+                            command,
+                            args: Array.isArray(serverConfiguration.args) ? serverConfiguration.args : [],
+                            url,
+                            envVars: Object.keys(environmentVariables),
+                            type: command ? 'stdio' : url ? 'http' : 'unknown',
+                        },
+                    };
+                }
+            }
+
+            return {
+                hasMCPServer: false,
+                reason: 'task-master-ai not found in configured MCP servers',
+                hasConfig: true,
+                configPath: configurationPath,
+                availableServers: serverGroups.flatMap((serverGroup) => Object.keys(serverGroup.servers)),
+            };
+        },
+    };
+}

package/server/modules/taskmaster/tests/taskmaster.routes.test.ts

@@ -0,0 +1,201 @@
+import assert from 'node:assert/strict';
+import { EventEmitter, once } from 'node:events';
+import type { AddressInfo } from 'node:net';
+import { PassThrough } from 'node:stream';
+import test from 'node:test';
+
+import express from 'express';
+
+import { connectedClients } from '@/modules/websocket/index.js';
+
+import { createTaskmasterRouter } from '../taskmaster.routes.js';
+
+test('tasks route resolves project ids through the injected project adapter', async () => {
+  const resolvedIds: string[] = [];
+  const router = createTaskmasterRouter({
+    fileSystem: {} as typeof import('node:fs'),
+    fileSystemPromises: {} as typeof import('node:fs/promises'),
+    spawnProcess: (() => { throw new Error('spawn should not run'); }) as unknown as
+      Parameters<typeof createTaskmasterRouter>[0]['spawnProcess'],
+    resolveProjectPathById: (projectId) => { resolvedIds.push(projectId); return null; },
+    taskmasterService: {
+      detectMcpServer: async () => ({
+        hasMCPServer: false,
+        reason: 'Not configured',
+        hasConfig: false,
+      }),
+    },
+  });
+  const app = express().use('/api/taskmaster', router);
+  const server = app.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  try {
+    const address = server.address() as AddressInfo;
+    const response = await fetch(`http://127.0.0.1:${address.port}/api/taskmaster/tasks/project-1`);
+    assert.equal(response.status, 404);
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+  assert.deepEqual(resolvedIds, ['project-1']);
+});
+
+test('MCP status route delegates detection to the injected TaskMaster service', async () => {
+  let detectionCount = 0;
+  const router = createTaskmasterRouter({
+    fileSystem: {} as typeof import('node:fs'),
+    fileSystemPromises: {} as typeof import('node:fs/promises'),
+    spawnProcess: (() => { throw new Error('spawn should not run'); }) as unknown as
+      Parameters<typeof createTaskmasterRouter>[0]['spawnProcess'],
+    resolveProjectPathById: () => null,
+    taskmasterService: {
+      detectMcpServer: async () => {
+        detectionCount += 1;
+        return {
+          hasMCPServer: true,
+          isConfigured: true,
+          hasApiKeys: false,
+          scope: 'user',
+          config: {
+            command: 'npx',
+            args: ['-y', 'task-master-ai'],
+            url: null,
+            envVars: [],
+            type: 'stdio',
+          },
+        };
+      },
+    },
+  });
+  const app = express().use('/api/taskmaster', router);
+  const server = app.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+
+  try {
+    const address = server.address() as AddressInfo;
+    const response = await fetch(`http://127.0.0.1:${address.port}/api/taskmaster/mcp-status`);
+    assert.equal(response.status, 200);
+    assert.deepEqual(await response.json(), {
+      hasMCPServer: true,
+      isConfigured: true,
+      hasApiKeys: false,
+      scope: 'user',
+      config: {
+        command: 'npx',
+        args: ['-y', 'task-master-ai'],
+        url: null,
+        envVars: [],
+        type: 'stdio',
+      },
+    });
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+
+  assert.equal(detectionCount, 1);
+});
+
+test('TaskMaster process errors use the endpoint failure response and settle once', async () => {
+  const child = new EventEmitter() as EventEmitter & {
+    stdin: PassThrough;
+    stdout: PassThrough;
+    stderr: PassThrough;
+  };
+  child.stdin = new PassThrough();
+  child.stdout = new PassThrough();
+  child.stderr = new PassThrough();
+
+  const router = createTaskmasterRouter({
+    fileSystem: { constants: { F_OK: 0 } } as typeof import('node:fs'),
+    fileSystemPromises: {
+      access: async () => { throw new Error('not initialized'); },
+    } as unknown as typeof import('node:fs/promises'),
+    spawnProcess: (() => {
+      process.nextTick(() => {
+        child.emit('error', new Error('spawn failed'));
+        child.emit('close', 1);
+      });
+      return child;
+    }) as unknown as Parameters<typeof createTaskmasterRouter>[0]['spawnProcess'],
+    resolveProjectPathById: () => '/workspace/project',
+    taskmasterService: {
+      detectMcpServer: async () => ({
+        hasMCPServer: false,
+        reason: 'Not configured',
+        hasConfig: false,
+      }),
+    },
+  });
+  const app = express().use('/api/taskmaster', router);
+  const server = app.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+
+  try {
+    const address = server.address() as AddressInfo;
+    const response = await fetch(`http://127.0.0.1:${address.port}/api/taskmaster/init/project-1`, {
+      method: 'POST',
+    });
+    assert.equal(response.status, 500);
+    assert.deepEqual(await response.json(), {
+      error: 'Failed to initialize TaskMaster',
+      message: 'spawn failed',
+      code: null,
+    });
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+});
+
+test('TaskMaster broadcasts reach only the tracked chat clients', async () => {
+  const child = new EventEmitter() as EventEmitter & {
+    stdin: PassThrough;
+    stdout: PassThrough;
+    stderr: PassThrough;
+  };
+  child.stdin = new PassThrough();
+  child.stdout = new PassThrough();
+  child.stderr = new PassThrough();
+
+  const chatClient = { readyState: 1, frames: [] as string[], send(data: string) { this.frames.push(data); } };
+  const closingClient = { readyState: 3, frames: [] as string[], send(data: string) { this.frames.push(data); } };
+
+  const router = createTaskmasterRouter({
+    fileSystem: { constants: { F_OK: 0 } } as typeof import('node:fs'),
+    fileSystemPromises: {
+      access: async () => { throw new Error('not initialized'); },
+    } as unknown as typeof import('node:fs/promises'),
+    spawnProcess: (() => {
+      process.nextTick(() => child.emit('close', 0));
+      return child;
+    }) as unknown as Parameters<typeof createTaskmasterRouter>[0]['spawnProcess'],
+    resolveProjectPathById: () => '/workspace/project',
+    taskmasterService: {
+      detectMcpServer: async () => ({
+        hasMCPServer: false,
+        reason: 'Not configured',
+        hasConfig: false,
+      }),
+    },
+  });
+  const app = express().use('/api/taskmaster', router);
+  const server = app.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+
+  connectedClients.add(chatClient as never);
+  connectedClients.add(closingClient as never);
+  try {
+    const address = server.address() as AddressInfo;
+    const response = await fetch(`http://127.0.0.1:${address.port}/api/taskmaster/init/project-1`, {
+      method: 'POST',
+    });
+    assert.equal(response.status, 200);
+
+    assert.equal(chatClient.frames.length, 1);
+    const frame = JSON.parse(chatClient.frames[0]) as Record<string, unknown>;
+    assert.equal(frame.type, 'taskmaster-project-updated');
+    assert.equal(frame.projectId, 'project-1');
+    assert.equal(closingClient.frames.length, 0);
+  } finally {
+    connectedClients.clear();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+});

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

@@ -0,0 +1,97 @@
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import test from 'node:test';
+
+import { createTaskmasterService } from '../taskmaster.service.js';
+
+type ServiceDependencies = Parameters<typeof createTaskmasterService>[0];
+
+function createDependencies(
+  homeDirectory: string,
+  files: Record<string, string>,
+): ServiceDependencies {
+  return {
+    getHomeDirectory: () => homeDirectory,
+    readTextFile: async (filePath) => {
+      const content = files[filePath];
+      if (content === undefined) {
+        throw new Error(`Missing fake file: ${filePath}`);
+      }
+      return content;
+    },
+  };
+}
+
+test('detectMcpServer returns a redacted TaskMaster server status', async () => {
+  const homeDirectory = path.join(path.sep, 'fake-home');
+  const configurationPath = path.join(homeDirectory, '.claude.json');
+  const service = createTaskmasterService(createDependencies(homeDirectory, {
+    [configurationPath]: JSON.stringify({
+      mcpServers: {
+        'task-master-ai': {
+          command: 'npx',
+          args: ['-y', 'task-master-ai'],
+          env: { ANTHROPIC_API_KEY: 'secret-value' },
+        },
+      },
+    }),
+  }));
+
+  assert.deepEqual(await service.detectMcpServer(), {
+    hasMCPServer: true,
+    isConfigured: true,
+    hasApiKeys: true,
+    scope: 'user',
+    config: {
+      command: 'npx',
+      args: ['-y', 'task-master-ai'],
+      url: null,
+      envVars: ['ANTHROPIC_API_KEY'],
+      type: 'stdio',
+    },
+  });
+});
+
+test('detectMcpServer checks the fallback configuration after malformed JSON', async () => {
+  const homeDirectory = path.join(path.sep, 'fake-home');
+  const primaryConfigurationPath = path.join(homeDirectory, '.claude.json');
+  const fallbackConfigurationPath = path.join(homeDirectory, '.claude', 'settings.json');
+  const service = createTaskmasterService(createDependencies(homeDirectory, {
+    [primaryConfigurationPath]: '{ malformed',
+    [fallbackConfigurationPath]: JSON.stringify({
+      projects: {
+        '/workspace/project': {
+          mcpServers: {
+            'project-task-master': { url: 'https://taskmaster.example.test/mcp' },
+          },
+        },
+      },
+    }),
+  }));
+
+  assert.deepEqual(await service.detectMcpServer(), {
+    hasMCPServer: true,
+    isConfigured: true,
+    hasApiKeys: false,
+    scope: 'local',
+    projectPath: '/workspace/project',
+    config: {
+      command: null,
+      args: [],
+      url: 'https://taskmaster.example.test/mcp',
+      envVars: [],
+      type: 'http',
+    },
+  });
+});
+
+test('detectMcpServer reports when no readable Claude configuration exists', async () => {
+  const homeDirectory = path.join(path.sep, 'fake-home');
+  const service = createTaskmasterService(createDependencies(homeDirectory, {}));
+
+  assert.deepEqual(await service.detectMcpServer(), {
+    hasMCPServer: false,
+    reason: 'No Claude configuration file found',
+    hasConfig: false,
+  });
+});

package/server/modules/user/index.ts

@@ -0,0 +1,2 @@
+// userRoutes: used by the server entrypoint to mount protected user-profile endpoints.
+export { userRoutes } from './user.module.js';

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

@@ -0,0 +1,151 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { createUserService } from '../user.service.js';
+
+type UserDependencies = Parameters<typeof createUserService>[0];
+
+function createDependencies(overrides: Partial<UserDependencies> = {}): UserDependencies {
+  return {
+    users: {
+      getGitConfig: () => undefined,
+      updateGitConfig: () => undefined,
+      completeOnboarding: () => undefined,
+      hasCompletedOnboarding: () => false,
+    },
+    preferences: {
+      getPreferences: () => ({}),
+      savePreferences: () => undefined,
+    },
+    drafts: {
+      getDrafts: () => [],
+      saveDraft: () => undefined,
+      deleteDraft: () => undefined,
+    },
+    readSystemGitConfig: async () => ({ git_name: null, git_email: null }),
+    applyGlobalGitConfig: async () => undefined,
+    logInfo: () => undefined,
+    logError: () => undefined,
+    ...overrides,
+  };
+}
+
+test('getGitConfig imports system configuration when the repository is empty', async () => {
+  const updates: unknown[][] = [];
+  const service = createUserService(createDependencies({
+    users: {
+      getGitConfig: () => undefined,
+      updateGitConfig: (...args) => updates.push(args),
+      completeOnboarding: () => undefined,
+      hasCompletedOnboarding: () => false,
+    },
+    readSystemGitConfig: async () => ({ git_name: 'Alice', git_email: 'alice@example.com' }),
+  }));
+
+  const result = await service.getGitConfig(7);
+
+  assert.equal(result.gitName, 'Alice');
+  assert.deepEqual(updates, [[7, 'Alice', 'alice@example.com']]);
+});
+
+test('updateGitConfig persists valid input and invokes the Git adapter', async () => {
+  const operations: string[] = [];
+  const service = createUserService(createDependencies({
+    users: {
+      getGitConfig: () => undefined,
+      updateGitConfig: (_id, name, email) => operations.push(`persist:${name}:${email}`),
+      completeOnboarding: () => undefined,
+      hasCompletedOnboarding: () => false,
+    },
+    applyGlobalGitConfig: async (name, email) => {
+      operations.push(`git:${name}:${email}`);
+    },
+  }));
+
+  await service.updateGitConfig(1, 'Alice', 'alice@example.com');
+  assert.deepEqual(operations, [
+    'persist:Alice:alice@example.com',
+    'git:Alice:alice@example.com',
+  ]);
+});
+
+test('savePreferences forwards only the keys the client sent', () => {
+  const saved: Array<Record<string, unknown>> = [];
+  const service = createUserService(createDependencies({
+    preferences: {
+      getPreferences: () => ({ theme: 'dark' }),
+      savePreferences: (_id, updates) => saved.push(updates),
+    },
+  }));
+
+  const result = service.savePreferences(3, { theme: 'light' });
+
+  assert.deepEqual(saved, [{ theme: 'light' }]);
+  assert.deepEqual(result.preferences, { theme: 'dark' });
+});
+
+test('savePreferences rejects a non-object body', () => {
+  const service = createUserService(createDependencies());
+
+  assert.throws(() => service.savePreferences(3, ['theme']), /object/i);
+  assert.throws(() => service.savePreferences(3, 'theme'), /object/i);
+});
+
+test('savePreferences rejects an over-long preference key', () => {
+  const service = createUserService(createDependencies());
+
+  assert.throws(() => service.savePreferences(3, { ['k'.repeat(201)]: 1 }), /1-200/);
+});
+
+test('saveDraft stores the text and queued message under the given scope', () => {
+  const saved: unknown[][] = [];
+  const service = createUserService(createDependencies({
+    drafts: {
+      getDrafts: () => [],
+      saveDraft: (...args) => saved.push(args),
+      deleteDraft: () => undefined,
+    },
+  }));
+
+  service.saveDraft(5, 'session-1', {
+    scope: 'session-1',
+    text: 'half a thought',
+    queuedMessage: { content: 'later' },
+  });
+
+  assert.deepEqual(saved, [[5, 'session-1', {
+    text: 'half a thought',
+    queuedMessage: { content: 'later' },
+  }]]);
+});
+
+test('saveDraft defaults a missing queued message to null rather than dropping the row', () => {
+  const saved: unknown[][] = [];
+  const service = createUserService(createDependencies({
+    drafts: {
+      getDrafts: () => [],
+      saveDraft: (...args) => saved.push(args),
+      deleteDraft: () => undefined,
+    },
+  }));
+
+  service.saveDraft(5, 'session-1', { scope: 'session-1', text: 'typing' });
+
+  assert.deepEqual(saved, [[5, 'session-1', { text: 'typing', queuedMessage: null }]]);
+});
+
+test('saveDraft rejects a blank or over-long scope', () => {
+  const service = createUserService(createDependencies());
+
+  assert.throws(() => service.saveDraft(5, '   ', { text: 'x' }), /scope/i);
+  assert.throws(() => service.saveDraft(5, 'x'.repeat(201), { text: 'x' }), /scope/i);
+});
+
+test('saveDraft rejects text past the storage limit', () => {
+  const service = createUserService(createDependencies());
+
+  assert.throws(
+    () => service.saveDraft(5, 'session-1', { text: 'x'.repeat(100_001) }),
+    /too long/i,
+  );
+});

package/server/modules/user/user.module.ts

@@ -0,0 +1,67 @@
+import spawn from 'cross-spawn';
+
+import { sessionDraftsDb, userDb, userPreferencesDb } from '@/modules/database/index.js';
+
+import { createUserRouter } from './user.routes.js';
+import { createUserService } from './user.service.js';
+
+type GitCommandResult = { stdout: string };
+
+function runGit(args: string[]): Promise<GitCommandResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', args, { shell: false });
+    let stdout = '';
+    child.stdout?.on('data', (data: Buffer) => { stdout += data.toString(); });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve({ stdout });
+        return;
+      }
+      reject(new Error(`Git command failed with code ${code}`));
+    });
+  });
+}
+
+async function readSystemGitConfig() {
+  const [nameResult, emailResult] = await Promise.all([
+    runGit(['config', '--global', 'user.name']).catch(() => ({ stdout: '' })),
+    runGit(['config', '--global', 'user.email']).catch(() => ({ stdout: '' })),
+  ]);
+  return {
+    git_name: nameResult.stdout.trim() || null,
+    git_email: emailResult.stdout.trim() || null,
+  };
+}
+
+const userService = createUserService({
+  users: {
+    getGitConfig: (userId) => userDb.getGitConfig(userId),
+    updateGitConfig: (userId, gitName, gitEmail) => userDb.updateGitConfig(
+      userId,
+      gitName ?? '',
+      gitEmail ?? '',
+    ),
+    completeOnboarding: (userId) => userDb.completeOnboarding(userId),
+    hasCompletedOnboarding: (userId) => userDb.hasCompletedOnboarding(userId),
+  },
+  preferences: {
+    getPreferences: (userId) => userPreferencesDb.getPreferences(userId),
+    savePreferences: (userId, updates) => userPreferencesDb.savePreferences(userId, updates),
+  },
+  drafts: {
+    getDrafts: (userId) => sessionDraftsDb.getDrafts(userId),
+    saveDraft: (userId, scope, draft) => sessionDraftsDb.saveDraft(userId, scope, draft),
+    deleteDraft: (userId, scope) => sessionDraftsDb.deleteDraft(userId, scope),
+  },
+  readSystemGitConfig,
+  applyGlobalGitConfig: async (gitName, gitEmail) => {
+    await runGit(['config', '--global', 'user.name', gitName]);
+    await runGit(['config', '--global', 'user.email', gitEmail]);
+  },
+  logInfo: (message) => console.log(message),
+  logError: (message, error) => console.error(message, error),
+});
+
+/** User router assembled for the authenticated server mount. */
+export const userRoutes = createUserRouter(userService);