npx skills add ...
npx skills add google-labs-code/stitch-sdk --skill typed-service-contracts
npx skills add google-labs-code/stitch-sdk --skill typed-service-contracts
Architecture standard for building robust, type-safe TypeScript services using the "Spec and Handler" pattern. Use when building CLIs, libraries, or complex business logic.
This skill defines a Vertical Slice Architecture backed by Design by Contract (DbC) principles. It treats application logic as rigorously defined Units of Work where inputs are parsed (not just validated) and errors are treated as values (Result Pattern) rather than exceptions.
spec.ts)The "Contract" or "Port". It defines the What. It must contain:
DiscriminatedUnion of Success | Failure.interface ConfigureSpec).handler.ts)The "Implementation" or "Adapter". It defines the How. It must:
Result type.spec.ts)Follow this template to define the boundaries.
handler.ts)Follow this template to implement the logic.
Do not write monolithic tests. Split them into Contract Tests and Logic Tests.
Test the Bouncer. Ensure invalid data is rejected before it reaches the handler.
Test the Chef. Mock external dependencies (fs, network) and assert the Result Object.
import { MyTaskSpec, MyTaskInput, MyTaskResult } from "./spec.js";
import * as fs from "fs";
export class MyTaskHandler implements MyTaskSpec {
async execute(input: MyTaskInput): Promise<MyTaskResult> {
try {
// 1. Business Logic
if (!fs.existsSync(input.path)) {
// 2. Explicit Error Return (No Throwing)
return {
success: false,
error: {
code: "FILE_NOT_FOUND",
message: `Path does not exist: ${input.path}`,
recoverable: true,
},
};
}
// 3. Success Return
return {
success: true,
data: "Operation complete",
};
} catch (error) {
// 4. Safety Net: Catch unknown runtime errors
return {
success: false,
error: {
code: "UNKNOWN_ERROR",
message: error instanceof Error ? error.message : String(error),
recoverable: false,
},
};
}
}
}// spec.test.ts
import { MyTaskInputSchema } from "./spec";
const invalidCases = [
{ val: "../etc/passwd", err: "No traversal allowed" },
{ val: "", err: "min(1)" },
];
test.each(invalidCases)("validates paths", ({ val, err }) => {
const result = MyTaskInputSchema.safeParse({ path: val });
expect(result.success).toBe(false);
});// handler.test.ts
import { MyTaskHandler } from "./handler";
import { vi } from "vitest"; // or jest
test("returns FILE_NOT_FOUND if path missing", async () => {
// MOCK
vi.mocked(fs.existsSync).mockReturnValue(false);
// EXECUTE
const handler = new MyTaskHandler();
const result = await handler.execute({ path: "/fake" });
// ASSERT (Check the Result Object)
expect(result.success).toBe(false);
if (!result.success) {
expect(result.error.code).toBe("FILE_NOT_FOUND");
}
});