refactor: add output schemas, extract and use input schema as types

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);