feat(shared): centralize CodesignError codes into registry

Add packages/shared/src/error-codes.ts with:
- ERROR_CODES const object (all known string codes, value === key)
- CodesignErrorCode type (literal union for TS narrowing)
- ERROR_CODE_DESCRIPTIONS with user-facing strings + categories

Update CodesignError.code signature to CodesignErrorCode | string
so new call sites get TS auto-complete while old string-passed callers
stay backward compatible.

Migrate every throw site across main process, providers, core, and
exporters to use ERROR_CODES.XXX instead of bare string literals.
Test files asserting on code string values are intentionally left as-is.

Vitest: 6 new tests in error-codes.test.ts (identity invariant,
no duplicates, completeness, non-empty descriptions, valid categories,
no extra keys).

Author: hqhq1025

apps/desktop/src/main/chat-messages-ipc.ts

@@ -7,7 +7,7 @@
  */
 
 import type { ChatAppendInput, ChatMessageKind, ChatMessageRow } from '@open-codesign/shared';
-import { CodesignError } from '@open-codesign/shared';
+import { CodesignError, ERROR_CODES } from '@open-codesign/shared';
 import type BetterSqlite3 from 'better-sqlite3';
 import { ipcMain } from './electron-runtime';
 import { getLogger } from './logger';
@@ -32,38 +32,47 @@ const VALID_KINDS: ChatMessageKind[] = [
 
 function requireSchemaV1(r: Record<string, unknown>, channel: string): void {
   if (r['schemaVersion'] !== 1) {
-    throw new CodesignError(`${channel} requires schemaVersion: 1`, 'IPC_BAD_INPUT');
+    throw new CodesignError(`${channel} requires schemaVersion: 1`, ERROR_CODES.IPC_BAD_INPUT);
   }
 }
 
 function parseDesignId(raw: unknown, channel: string): string {
   if (typeof raw !== 'object' || raw === null) {
-    throw new CodesignError(`${channel} expects an object with designId`, 'IPC_BAD_INPUT');
+    throw new CodesignError(
+      `${channel} expects an object with designId`,
+      ERROR_CODES.IPC_BAD_INPUT,
+    );
   }
   const r = raw as Record<string, unknown>;
   requireSchemaV1(r, channel);
   if (typeof r['designId'] !== 'string' || r['designId'].trim().length === 0) {
-    throw new CodesignError('designId must be a non-empty string', 'IPC_BAD_INPUT');
+    throw new CodesignError('designId must be a non-empty string', ERROR_CODES.IPC_BAD_INPUT);
   }
   return r['designId'] as string;
 }
 
 function parseAppendInput(raw: unknown): ChatAppendInput {
   if (typeof raw !== 'object' || raw === null) {
-    throw new CodesignError('chat:v1:append expects an object payload', 'IPC_BAD_INPUT');
+    throw new CodesignError('chat:v1:append expects an object payload', ERROR_CODES.IPC_BAD_INPUT);
   }
   const r = raw as Record<string, unknown>;
   requireSchemaV1(r, 'chat:v1:append');
   if (typeof r['designId'] !== 'string' || r['designId'].trim().length === 0) {
-    throw new CodesignError('designId must be a non-empty string', 'IPC_BAD_INPUT');
+    throw new CodesignError('designId must be a non-empty string', ERROR_CODES.IPC_BAD_INPUT);
   }
   const kind = r['kind'];
   if (typeof kind !== 'string' || !VALID_KINDS.includes(kind as ChatMessageKind)) {
-    throw new CodesignError(`kind must be one of: ${VALID_KINDS.join(', ')}`, 'IPC_BAD_INPUT');
+    throw new CodesignError(
+      `kind must be one of: ${VALID_KINDS.join(', ')}`,
+      ERROR_CODES.IPC_BAD_INPUT,
+    );
   }
   const snapshotId = r['snapshotId'];
   if (snapshotId !== undefined && snapshotId !== null && typeof snapshotId !== 'string') {
-    throw new CodesignError('snapshotId must be a string, null, or absent', 'IPC_BAD_INPUT');
+    throw new CodesignError(
+      'snapshotId must be a string, null, or absent',
+      ERROR_CODES.IPC_BAD_INPUT,
+    );
   }
   return {
     designId: r['designId'],
@@ -82,24 +91,27 @@ function parseUpdateToolStatus(raw: unknown): {
   if (typeof raw !== 'object' || raw === null) {
     throw new CodesignError(
       'chat:update-tool-status:v1 expects an object payload',
-      'IPC_BAD_INPUT',
+      ERROR_CODES.IPC_BAD_INPUT,
     );
   }
   const r = raw as Record<string, unknown>;
   requireSchemaV1(r, 'chat:update-tool-status:v1');
   if (typeof r['designId'] !== 'string' || r['designId'].trim().length === 0) {
-    throw new CodesignError('designId must be a non-empty string', 'IPC_BAD_INPUT');
+    throw new CodesignError('designId must be a non-empty string', ERROR_CODES.IPC_BAD_INPUT);
   }
   if (typeof r['seq'] !== 'number' || !Number.isInteger(r['seq']) || r['seq'] < 0) {
-    throw new CodesignError('seq must be a non-negative integer', 'IPC_BAD_INPUT');
+    throw new CodesignError('seq must be a non-negative integer', ERROR_CODES.IPC_BAD_INPUT);
   }
   const status = r['status'];
   if (status !== 'done' && status !== 'error') {
-    throw new CodesignError("status must be 'done' or 'error'", 'IPC_BAD_INPUT');
+    throw new CodesignError("status must be 'done' or 'error'", ERROR_CODES.IPC_BAD_INPUT);
   }
   const errorMessage = r['errorMessage'];
   if (errorMessage !== undefined && typeof errorMessage !== 'string') {
-    throw new CodesignError('errorMessage must be a string when present', 'IPC_BAD_INPUT');
+    throw new CodesignError(
+      'errorMessage must be a string when present',
+      ERROR_CODES.IPC_BAD_INPUT,
+    );
   }
   return {
     designId: r['designId'],
@@ -134,7 +146,9 @@ export function registerChatMessagesIpc(db: Database): void {
         kind: input.kind,
         message: err instanceof Error ? err.message : String(err),
       });
-      throw new CodesignError('Failed to append chat message', 'IPC_DB_ERROR', { cause: err });
+      throw new CodesignError('Failed to append chat message', ERROR_CODES.IPC_DB_ERROR, {
+        cause: err,
+      });
     }
   });
 
@@ -159,7 +173,7 @@ export function registerChatMessagesIpc(db: Database): void {
         seq: input.seq,
         message: err instanceof Error ? err.message : String(err),
       });
-      throw new CodesignError('Failed to update tool call status', 'IPC_DB_ERROR', {
+      throw new CodesignError('Failed to update tool call status', ERROR_CODES.IPC_DB_ERROR, {
         cause: err,
       });
     }
@@ -169,7 +183,7 @@ export function registerChatMessagesIpc(db: Database): void {
 export function registerChatMessagesUnavailableIpc(reason: string): void {
   const message = `Chat history is unavailable. ${reason}`;
   const fail = (): never => {
-    throw new CodesignError(message, 'SNAPSHOTS_UNAVAILABLE');
+    throw new CodesignError(message, ERROR_CODES.SNAPSHOTS_UNAVAILABLE);
   };
   for (const channel of CHAT_MESSAGES_CHANNELS_V1) {
     ipcMain.handle(channel, fail);

apps/desktop/src/main/comments-ipc.ts

@@ -11,7 +11,7 @@ import type {
   CommentRow,
   CommentStatus,
 } from '@open-codesign/shared';
-import { CodesignError } from '@open-codesign/shared';
+import { CodesignError, ERROR_CODES } from '@open-codesign/shared';
 import type BetterSqlite3 from 'better-sqlite3';
 import { ipcMain } from './electron-runtime';
 import { getLogger } from './logger';
@@ -33,36 +33,42 @@ const VALID_STATUSES: CommentStatus[] = ['pending', 'applied', 'dismissed'];
 
 function requireSchemaV1(r: Record<string, unknown>, channel: string): void {
   if (r['schemaVersion'] !== 1) {
-    throw new CodesignError(`${channel} requires schemaVersion: 1`, 'IPC_BAD_INPUT');
+    throw new CodesignError(`${channel} requires schemaVersion: 1`, ERROR_CODES.IPC_BAD_INPUT);
   }
 }
 
 function asObject(raw: unknown, channel: string): Record<string, unknown> {
   if (typeof raw !== 'object' || raw === null) {
-    throw new CodesignError(`${channel} expects an object payload`, 'IPC_BAD_INPUT');
+    throw new CodesignError(`${channel} expects an object payload`, ERROR_CODES.IPC_BAD_INPUT);
   }
   return raw as Record<string, unknown>;
 }
 
 function parseNonEmptyString(r: Record<string, unknown>, field: string, channel: string): string {
   const v = r[field];
   if (typeof v !== 'string' || v.trim().length === 0) {
-    throw new CodesignError(`${channel}: ${field} must be a non-empty string`, 'IPC_BAD_INPUT');
+    throw new CodesignError(
+      `${channel}: ${field} must be a non-empty string`,
+      ERROR_CODES.IPC_BAD_INPUT,
+    );
   }
   return v;
 }
 
 function parseRect(raw: unknown, channel: string): CommentCreateInput['rect'] {
   if (typeof raw !== 'object' || raw === null) {
-    throw new CodesignError(`${channel}: rect must be an object`, 'IPC_BAD_INPUT');
+    throw new CodesignError(`${channel}: rect must be an object`, ERROR_CODES.IPC_BAD_INPUT);
   }
   const r = raw as Record<string, unknown>;
   const fields = ['top', 'left', 'width', 'height'] as const;
   const out: Record<string, number> = {};
   for (const f of fields) {
     const v = r[f];
     if (typeof v !== 'number' || !Number.isFinite(v)) {
-      throw new CodesignError(`${channel}: rect.${f} must be a finite number`, 'IPC_BAD_INPUT');
+      throw new CodesignError(
+        `${channel}: rect.${f} must be a finite number`,
+        ERROR_CODES.IPC_BAD_INPUT,
+      );
     }
     out[f] = v;
   }
@@ -83,30 +89,33 @@ function parseAddInput(raw: unknown): CommentCreateInput {
   if (typeof kind !== 'string' || !VALID_KINDS.includes(kind as CommentKind)) {
     throw new CodesignError(
       `${channel}: kind must be one of ${VALID_KINDS.join(', ')}`,
-      'IPC_BAD_INPUT',
+      ERROR_CODES.IPC_BAD_INPUT,
     );
   }
   const text = r['text'];
   if (typeof text !== 'string') {
-    throw new CodesignError(`${channel}: text must be a string`, 'IPC_BAD_INPUT');
+    throw new CodesignError(`${channel}: text must be a string`, ERROR_CODES.IPC_BAD_INPUT);
   }
   const outerHTML = r['outerHTML'];
   if (typeof outerHTML !== 'string') {
-    throw new CodesignError(`${channel}: outerHTML must be a string`, 'IPC_BAD_INPUT');
+    throw new CodesignError(`${channel}: outerHTML must be a string`, ERROR_CODES.IPC_BAD_INPUT);
   }
   const scopeRaw = r['scope'];
   let scope: 'element' | 'global' = 'element';
   if (scopeRaw !== undefined) {
     if (scopeRaw !== 'element' && scopeRaw !== 'global') {
-      throw new CodesignError(`${channel}: scope must be 'element' or 'global'`, 'IPC_BAD_INPUT');
+      throw new CodesignError(
+        `${channel}: scope must be 'element' or 'global'`,
+        ERROR_CODES.IPC_BAD_INPUT,
+      );
     }
     scope = scopeRaw;
   }
   const parentRaw = r['parentOuterHTML'];
   if (parentRaw !== undefined && parentRaw !== null && typeof parentRaw !== 'string') {
     throw new CodesignError(
       `${channel}: parentOuterHTML must be a string when present`,
-      'IPC_BAD_INPUT',
+      ERROR_CODES.IPC_BAD_INPUT,
     );
   }
   const parentOuterHTML =
@@ -150,7 +159,7 @@ export function registerCommentsIpc(db: Database): void {
         designId: input.designId,
         message: err instanceof Error ? err.message : String(err),
       });
-      throw new CodesignError('Failed to create comment', 'IPC_DB_ERROR', { cause: err });
+      throw new CodesignError('Failed to create comment', ERROR_CODES.IPC_DB_ERROR, { cause: err });
     }
   });
 
@@ -163,7 +172,7 @@ export function registerCommentsIpc(db: Database): void {
     if (snapshotId !== undefined && snapshotId !== null && typeof snapshotId !== 'string') {
       throw new CodesignError(
         `${channel}: snapshotId must be a string, null, or absent`,
-        'IPC_BAD_INPUT',
+        ERROR_CODES.IPC_BAD_INPUT,
       );
     }
     return typeof snapshotId === 'string'
@@ -184,7 +193,7 @@ export function registerCommentsIpc(db: Database): void {
     const patch: { text?: string; status?: CommentStatus } = {};
     if (r['text'] !== undefined) {
       if (typeof r['text'] !== 'string') {
-        throw new CodesignError(`${channel}: text must be a string`, 'IPC_BAD_INPUT');
+        throw new CodesignError(`${channel}: text must be a string`, ERROR_CODES.IPC_BAD_INPUT);
       }
       patch.text = r['text'];
     }
@@ -193,7 +202,7 @@ export function registerCommentsIpc(db: Database): void {
       if (typeof s !== 'string' || !VALID_STATUSES.includes(s as CommentStatus)) {
         throw new CodesignError(
           `${channel}: status must be one of ${VALID_STATUSES.join(', ')}`,
-          'IPC_BAD_INPUT',
+          ERROR_CODES.IPC_BAD_INPUT,
         );
       }
       patch.status = s as CommentStatus;
@@ -220,7 +229,7 @@ export function registerCommentsIpc(db: Database): void {
     if (!Array.isArray(ids) || ids.some((x) => typeof x !== 'string' || x.length === 0)) {
       throw new CodesignError(
         `${channel}: ids must be an array of non-empty strings`,
-        'IPC_BAD_INPUT',
+        ERROR_CODES.IPC_BAD_INPUT,
       );
     }
     const rows = markCommentsApplied(db, ids as string[], snapshotId);
@@ -232,7 +241,7 @@ export function registerCommentsIpc(db: Database): void {
 export function registerCommentsUnavailableIpc(reason: string): void {
   const message = `Comments are unavailable. ${reason}`;
   const fail = (): never => {
-    throw new CodesignError(message, 'SNAPSHOTS_UNAVAILABLE');
+    throw new CodesignError(message, ERROR_CODES.SNAPSHOTS_UNAVAILABLE);
   };
   for (const channel of COMMENTS_CHANNELS_V1) {
     ipcMain.handle(channel, fail);

apps/desktop/src/main/config.ts

@@ -5,6 +5,7 @@ import {
   CodesignError,
   type Config,
   ConfigV3Schema,
+  ERROR_CODES,
   parseConfigFlexible,
   toPersistedV3,
 } from '@open-codesign/shared';
@@ -34,7 +35,7 @@ export async function readConfig(): Promise<Config | null> {
     raw = await readFile(path, 'utf8');
   } catch (err) {
     if (isNotFound(err)) return null;
-    throw new CodesignError(`Failed to read config at ${path}`, 'CONFIG_READ_FAILED', {
+    throw new CodesignError(`Failed to read config at ${path}`, ERROR_CODES.CONFIG_READ_FAILED, {
       cause: err,
     });
   }
@@ -43,16 +44,20 @@ export async function readConfig(): Promise<Config | null> {
   try {
     parsed = parseToml(raw);
   } catch (err) {
-    throw new CodesignError(`Config at ${path} is not valid TOML`, 'CONFIG_PARSE_FAILED', {
-      cause: err,
-    });
+    throw new CodesignError(
+      `Config at ${path} is not valid TOML`,
+      ERROR_CODES.CONFIG_PARSE_FAILED,
+      {
+        cause: err,
+      },
+    );
   }
 
   const validated = safeParseConfig(parsed);
   if (!validated.ok) {
     throw new CodesignError(
       `Config at ${path} does not match the expected schema: ${validated.error}`,
-      'CONFIG_SCHEMA_INVALID',
+      ERROR_CODES.CONFIG_SCHEMA_INVALID,
       { cause: validated.cause },
     );
   }