refactor: add output schemas, extract and use input schema as types (#275)

We previously were not enforcing output schemas, and also not using
the input schemas as types, meaning we did not have 1 source of truth.

Author: jonathanlab

ARCHITECTURE.md

@@ -127,22 +127,25 @@ We use [tRPC](https://trpc.io/) with [trpc-electron](https://github.com/jsonnull
 
 ```typescript
 // src/main/trpc/routers/my-router.ts
-import { z } from "zod";
 import { container } from "../../di/container";
 import { MAIN_TOKENS } from "../../di/tokens";
+import {
+  getDataInput,
+  getDataOutput,
+  updateDataInput,
+} from "../../services/my-service/schemas";
 import { router, publicProcedure } from "../trpc";
 
 const getService = () => container.get<MyService>(MAIN_TOKENS.MyService);
 
 export const myRouter = router({
-  // Query - for read operations
   getData: publicProcedure
-    .input(z.object({ id: z.string() }))
+    .input(getDataInput)
+    .output(getDataOutput)
     .query(({ input }) => getService().getData(input.id)),
 
-  // Mutation - for write operations
   updateData: publicProcedure
-    .input(z.object({ id: z.string(), value: z.string() }))
+    .input(updateDataInput)
     .mutation(({ input }) => getService().updateData(input.id, input.value)),
 });
 ```
@@ -238,12 +241,64 @@ Main services should be:
 src/main/services/
 ├── my-service/
 │   ├── service.ts      # The injectable service class
-│   └── types.ts        # Types and interfaces
+│   ├── schemas.ts      # Zod schemas for tRPC input/output
+│   └── types.ts        # Internal types (not exposed via tRPC)
 
 src/renderer/services/
 ├── my-service.ts       # Renderer-side service
 ```
 
+### Zod Schemas
+
+All tRPC inputs and outputs use Zod schemas as the single source of truth. Types are inferred from schemas.
+
+```typescript
+// src/main/services/my-service/schemas.ts
+import { z } from "zod";
+
+export const getDataInput = z.object({
+  id: z.string(),
+});
+
+export const getDataOutput = z.object({
+  id: z.string(),
+  name: z.string(),
+  createdAt: z.string(),
+});
+
+export type GetDataInput = z.infer<typeof getDataInput>;
+export type GetDataOutput = z.infer<typeof getDataOutput>;
+```
+
+```typescript
+// src/main/trpc/routers/my-router.ts
+import { getDataInput, getDataOutput } from "../../services/my-service/schemas";
+
+export const myRouter = router({
+  getData: publicProcedure
+    .input(getDataInput)
+    .output(getDataOutput)
+    .query(({ input }) => getService().getData(input.id)),
+});
+```
+
+```typescript
+// src/main/services/my-service/service.ts
+import type { GetDataInput, GetDataOutput } from "./schemas";
+
+@injectable()
+export class MyService {
+  async getData(id: string): Promise<GetDataOutput> {
+    // ...
+  }
+}
+```
+
+This pattern provides:
+- Runtime validation of inputs and outputs
+- Single source of truth for types
+- Explicit API contracts between main and renderer
+
 ## Adding a New Feature
 
 1. **Create the service** in `src/main/services/`

apps/array/src/main/services/context-menu/schemas.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+
+export const taskContextMenuInput = z.object({
+  taskTitle: z.string(),
+  worktreePath: z.string().optional(),
+});
+
+export const folderContextMenuInput = z.object({
+  folderName: z.string(),
+  folderPath: z.string().optional(),
+});
+
+export const tabContextMenuInput = z.object({
+  canClose: z.boolean(),
+  filePath: z.string().optional(),
+});
+
+export const fileContextMenuInput = z.object({
+  filePath: z.string(),
+  showCollapseAll: z.boolean().optional(),
+});
+
+const externalAppAction = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("open-in-app"), appId: z.string() }),
+  z.object({ type: z.literal("copy-path") }),
+]);
+
+const taskAction = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("rename") }),
+  z.object({ type: z.literal("duplicate") }),
+  z.object({ type: z.literal("delete") }),
+  z.object({ type: z.literal("external-app"), action: externalAppAction }),
+]);
+
+const folderAction = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("remove") }),
+  z.object({ type: z.literal("external-app"), action: externalAppAction }),
+]);
+
+const tabAction = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("close") }),
+  z.object({ type: z.literal("close-others") }),
+  z.object({ type: z.literal("close-right") }),
+  z.object({ type: z.literal("external-app"), action: externalAppAction }),
+]);
+
+const fileAction = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("collapse-all") }),
+  z.object({ type: z.literal("external-app"), action: externalAppAction }),
+]);
+
+const splitDirection = z.enum(["left", "right", "up", "down"]);
+
+export const taskContextMenuOutput = z.object({
+  action: taskAction.nullable(),
+});
+export const folderContextMenuOutput = z.object({
+  action: folderAction.nullable(),
+});
+export const tabContextMenuOutput = z.object({ action: tabAction.nullable() });
+export const fileContextMenuOutput = z.object({
+  action: fileAction.nullable(),
+});
+export const splitContextMenuOutput = z.object({
+  direction: splitDirection.nullable(),
+});
+
+export type TaskContextMenuInput = z.infer<typeof taskContextMenuInput>;
+export type FolderContextMenuInput = z.infer<typeof folderContextMenuInput>;
+export type TabContextMenuInput = z.infer<typeof tabContextMenuInput>;
+export type FileContextMenuInput = z.infer<typeof fileContextMenuInput>;
+
+export type ExternalAppAction = z.infer<typeof externalAppAction>;
+export type TaskAction = z.infer<typeof taskAction>;
+export type FolderAction = z.infer<typeof folderAction>;
+export type TabAction = z.infer<typeof tabAction>;
+export type FileAction = z.infer<typeof fileAction>;
+export type SplitDirection = z.infer<typeof splitDirection>;
+
+export type TaskContextMenuResult = z.infer<typeof taskContextMenuOutput>;
+export type FolderContextMenuResult = z.infer<typeof folderContextMenuOutput>;
+export type TabContextMenuResult = z.infer<typeof tabContextMenuOutput>;
+export type FileContextMenuResult = z.infer<typeof fileContextMenuOutput>;
+export type SplitContextMenuResult = z.infer<typeof splitContextMenuOutput>;

apps/array/src/main/services/context-menu/service.ts

@@ -10,16 +10,12 @@ import { MAIN_TOKENS } from "../../di/tokens.js";
 import { getMainWindow } from "../../trpc/context.js";
 import type { ExternalAppsService } from "../external-apps/service.js";
 import type {
-  ActionItemDef,
-  ConfirmOptions,
   FileAction,
   FileContextMenuInput,
   FileContextMenuResult,
   FolderAction,
   FolderContextMenuInput,
   FolderContextMenuResult,
-  MenuItemDef,
-  SeparatorDef,
   SplitContextMenuResult,
   SplitDirection,
   TabAction,
@@ -28,6 +24,12 @@ import type {
   TaskAction,
   TaskContextMenuInput,
   TaskContextMenuResult,
+} from "./schemas.js";
+import type {
+  ActionItemDef,
+  ConfirmOptions,
+  MenuItemDef,
+  SeparatorDef,
 } from "./types.js";
 
 @injectable()

apps/array/src/main/services/context-menu/types.ts

@@ -1,69 +1,3 @@
-export type ExternalAppAction =
-  | { type: "open-in-app"; appId: string }
-  | { type: "copy-path" };
-
-export type TaskAction =
-  | { type: "rename" }
-  | { type: "duplicate" }
-  | { type: "delete" }
-  | { type: "external-app"; action: ExternalAppAction };
-
-export type FolderAction =
-  | { type: "remove" }
-  | { type: "external-app"; action: ExternalAppAction };
-
-export type TabAction =
-  | { type: "close" }
-  | { type: "close-others" }
-  | { type: "close-right" }
-  | { type: "external-app"; action: ExternalAppAction };
-
-export type FileAction =
-  | { type: "collapse-all" }
-  | { type: "external-app"; action: ExternalAppAction };
-
-export type SplitDirection = "left" | "right" | "up" | "down";
-
-export interface TaskContextMenuInput {
-  taskTitle: string;
-  worktreePath?: string;
-}
-
-export interface TaskContextMenuResult {
-  action: TaskAction | null;
-}
-
-export interface FolderContextMenuInput {
-  folderName: string;
-  folderPath?: string;
-}
-
-export interface FolderContextMenuResult {
-  action: FolderAction | null;
-}
-
-export interface TabContextMenuInput {
-  canClose: boolean;
-  filePath?: string;
-}
-
-export interface TabContextMenuResult {
-  action: TabAction | null;
-}
-
-export interface SplitContextMenuResult {
-  direction: SplitDirection | null;
-}
-
-export interface FileContextMenuInput {
-  filePath: string;
-  showCollapseAll?: boolean;
-}
-
-export interface FileContextMenuResult {
-  action: FileAction | null;
-}
-
 export interface ConfirmOptions {
   title: string;
   message: string;

apps/array/src/main/services/external-apps/schemas.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+
+export const openInAppInput = z.object({
+  appId: z.string(),
+  targetPath: z.string(),
+});
+
+export const setLastUsedInput = z.object({
+  appId: z.string(),
+});
+
+export const copyPathInput = z.object({
+  targetPath: z.string(),
+});
+
+const externalAppType = z.enum(["editor", "terminal", "file-manager"]);
+
+const detectedApplication = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: externalAppType,
+  path: z.string(),
+  command: z.string(),
+  icon: z.string().optional(),
+});
+
+export const getDetectedAppsOutput = z.array(detectedApplication);
+export const openInAppOutput = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+});
+export const getLastUsedOutput = z.object({
+  lastUsedApp: z.string().optional(),
+});
+
+export type OpenInAppInput = z.infer<typeof openInAppInput>;
+export type SetLastUsedInput = z.infer<typeof setLastUsedInput>;
+export type CopyPathInput = z.infer<typeof copyPathInput>;
+export type DetectedApplication = z.infer<typeof detectedApplication>;
+export type OpenInAppOutput = z.infer<typeof openInAppOutput>;
+export type GetLastUsedOutput = z.infer<typeof getLastUsedOutput>;

apps/array/src/main/services/external-apps/service.ts

@@ -7,21 +7,12 @@ import Store from "electron-store";
 import { injectable } from "inversify";
 import type {
   DetectedApplication,
-  ExternalAppsPreferences,
   ExternalAppType,
 } from "../../../shared/types.js";
+import type { AppDefinition, ExternalAppsSchema } from "./types.js";
 
 const execAsync = promisify(exec);
 
-interface AppDefinition {
-  path: string;
-  type: ExternalAppType;
-}
-
-interface ExternalAppsSchema {
-  externalAppsPrefs: ExternalAppsPreferences;
-}
-
 @injectable()
 export class ExternalAppsService {
   private readonly APP_DEFINITIONS: Record<string, AppDefinition> = {

apps/array/src/main/services/external-apps/types.ts

@@ -0,0 +1,14 @@
+import type { ExternalAppType } from "../../../shared/types.js";
+
+export interface AppDefinition {
+  path: string;
+  type: ExternalAppType;
+}
+
+export interface ExternalAppsPreferences {
+  lastUsedApp?: string;
+}
+
+export interface ExternalAppsSchema {
+  externalAppsPrefs: ExternalAppsPreferences;
+}

apps/array/src/main/services/git/schemas.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+export const detectRepoInput = z.object({
+  directoryPath: z.string(),
+});
+
+export const detectRepoOutput = z
+  .object({
+    organization: z.string(),
+    repository: z.string(),
+    remote: z.string().optional(),
+    branch: z.string().optional(),
+  })
+  .nullable();
+
+export type DetectRepoInput = z.infer<typeof detectRepoInput>;
+export type DetectRepoResult = z.infer<typeof detectRepoOutput>;

apps/array/src/main/services/git/service.ts

@@ -1,8 +1,8 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { injectable } from "inversify";
-import type { DetectRepoResult } from "./types";
-import { parseGitHubUrl } from "./utils";
+import type { DetectRepoResult } from "./schemas.js";
+import { parseGitHubUrl } from "./utils.js";
 
 const execFileAsync = promisify(execFile);