diff --git a/docs/superpowers/plans/2026-06-15-api-admin-full-refactor-v3.md b/docs/superpowers/plans/2026-06-15-api-admin-full-refactor-v3.md index d2e96b2..9814d06 100644 --- a/docs/superpowers/plans/2026-06-15-api-admin-full-refactor-v3.md +++ b/docs/superpowers/plans/2026-06-15-api-admin-full-refactor-v3.md @@ -653,7 +653,7 @@ git -C D:\MyFiles\KT commit -m "docs: 记录第三期迁移准备" - Create: `D:\MyFiles\KT\Node\kt-template-online-api\src\runtime\client\runtime-docker-client.types.ts` - Create: `D:\MyFiles\KT\Node\kt-template-online-api\test\runtime\runtime-client-contract.spec.ts` -- [ ] **Step 1: Write RED contract test** +- [x] **Step 1: Write RED contract test** Test expectations: @@ -673,15 +673,15 @@ describe('runtime client contracts', () => { }); ``` -- [ ] **Step 2: Create type files** +- [x] **Step 2: Create type files** Define request/response types for HTTP, process, and Docker calls. Each request type includes `timeoutMs`, `correlationId`, and `safeSummary`. -- [ ] **Step 3: Export contracts** +- [x] **Step 3: Export contracts** Modify `src/runtime/index.ts` to export the new client contract types. -- [ ] **Step 4: Verify** +- [x] **Step 4: Verify** Run: @@ -699,7 +699,7 @@ Expected: PASS. - Modify: `D:\MyFiles\KT\Node\kt-template-online-api\src\common\common.module.ts` - Test: existing `test/common/*.spec.ts` -- [ ] **Step 1: List exported common symbols** +- [x] **Step 1: List exported common symbols** Run: @@ -707,11 +707,13 @@ Run: Get-Content D:\MyFiles\KT\Node\kt-template-online-api\src\common\index.ts ``` -- [ ] **Step 2: Remove only exports made obsolete by new runtime contracts** +- [x] **Step 2: Remove only exports made obsolete by new runtime contracts** Keep response wrappers, filters, interceptors, time decorators, Snowflake, logger config, and generic tools. -- [ ] **Step 3: Verify common tests** +Actual note: no runtime client or now-obsolete export was present in `src/common/index.ts` or `src/common/common.module.ts`, so Common stayed unchanged to avoid artificial churn. + +- [x] **Step 3: Verify common tests** Run: @@ -728,7 +730,7 @@ Expected: PASS. - Modify: `D:\MyFiles\KT\TASKS.md` - API and root commits. -- [ ] **Step 1: Run Batch 1 review gates** +- [x] **Step 1: Run Batch 1 review gates** Run MCP tools: @@ -739,7 +741,7 @@ kt_global_code_review(projects=["api","root"], contentScanMode="changed", includ Expected: required docs resolved and `findings=[]`. -- [ ] **Step 2: Commit** +- [x] **Step 2: Commit** Run: diff --git a/src/runtime/client/runtime-docker-client.types.ts b/src/runtime/client/runtime-docker-client.types.ts new file mode 100644 index 0000000..d756724 --- /dev/null +++ b/src/runtime/client/runtime-docker-client.types.ts @@ -0,0 +1,26 @@ +export type RuntimeDockerClientAction = + | 'exec' + | 'run' + | 'start' + | 'stop' + | 'restart' + | 'logs' + | 'inspect'; + +export interface RuntimeDockerClientRequest { + action: RuntimeDockerClientAction; + containerName?: string; + image?: string; + command?: string[]; + timeoutMs: number; + correlationId: string; + safeSummary: string; +} + +export interface RuntimeDockerClientResponse { + exitCode: number | null; + output: string; + timeoutMs: number; + correlationId: string; + safeSummary: string; +} diff --git a/src/runtime/client/runtime-http-client.types.ts b/src/runtime/client/runtime-http-client.types.ts new file mode 100644 index 0000000..3604df5 --- /dev/null +++ b/src/runtime/client/runtime-http-client.types.ts @@ -0,0 +1,19 @@ +export interface RuntimeHttpClientRequest { + url: string; + method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'; + headers?: Record; + body?: string | Record | ArrayBuffer | null; + timeoutMs: number; + correlationId: string; + safeSummary: string; + redactHeaders?: string[]; +} + +export interface RuntimeHttpClientResponse { + statusCode: number; + headers: Record; + body: string; + timeoutMs: number; + correlationId: string; + safeSummary: string; +} diff --git a/src/runtime/client/runtime-process-client.types.ts b/src/runtime/client/runtime-process-client.types.ts new file mode 100644 index 0000000..d382573 --- /dev/null +++ b/src/runtime/client/runtime-process-client.types.ts @@ -0,0 +1,18 @@ +export interface RuntimeProcessClientRequest { + command: string; + args: string[]; + cwd?: string; + timeoutMs: number; + correlationId: string; + safeSummary: string; +} + +export interface RuntimeProcessClientResponse { + exitCode: number | null; + signal?: NodeJS.Signals | null; + stdout: string; + stderr: string; + timeoutMs: number; + correlationId: string; + safeSummary: string; +} diff --git a/src/runtime/index.ts b/src/runtime/index.ts index 57e5ecb..19e1039 100644 --- a/src/runtime/index.ts +++ b/src/runtime/index.ts @@ -1,5 +1,8 @@ export * from './config/runtime-config.service'; export * from './config/runtime-config.types'; +export * from './client/runtime-docker-client.types'; +export * from './client/runtime-http-client.types'; +export * from './client/runtime-process-client.types'; export * from './errors/runtime-error.types'; export * from './evidence/runtime-evidence.service'; export * from './evidence/runtime-evidence.types'; diff --git a/test/runtime/runtime-client-contract.spec.ts b/test/runtime/runtime-client-contract.spec.ts new file mode 100644 index 0000000..675c5a1 --- /dev/null +++ b/test/runtime/runtime-client-contract.spec.ts @@ -0,0 +1,47 @@ +import type { + RuntimeDockerClientRequest, + RuntimeHttpClientRequest, + RuntimeProcessClientRequest, +} from '../../src/runtime'; + +describe('runtime client contracts', () => { + it('uses explicit timeout and redaction fields for external calls', () => { + const request: RuntimeHttpClientRequest = { + url: 'https://example.invalid', + method: 'GET', + timeoutMs: 1000, + correlationId: 'runtime-contract-test', + safeSummary: 'fetch runtime contract fixture', + redactHeaders: ['authorization'], + }; + + expect(request.timeoutMs).toBeGreaterThan(0); + expect(request.redactHeaders).toContain('authorization'); + expect(request.safeSummary).toContain('runtime contract'); + }); + + it('keeps process and docker requests explicit without secret-bearing fields', () => { + const processRequest: RuntimeProcessClientRequest = { + command: 'pnpm', + args: ['run', 'typecheck'], + cwd: 'D:\\MyFiles\\KT\\Node\\kt-template-online-api', + timeoutMs: 1000, + correlationId: 'runtime-contract-test', + safeSummary: 'run api typecheck', + }; + + const dockerRequest: RuntimeDockerClientRequest = { + action: 'exec', + containerName: 'kt-template-online-api', + command: ['pnpm', 'run', 'typecheck'], + timeoutMs: 1000, + correlationId: 'runtime-contract-test', + safeSummary: 'exec api typecheck in container', + }; + + expect(processRequest.command).toBe('pnpm'); + expect(processRequest.args).toContain('typecheck'); + expect(dockerRequest.action).toBe('exec'); + expect(dockerRequest.command).toContain('typecheck'); + }); +});