@@ -4,7 +4,10 @@ import {
44 ProviderInstanceId ,
55 ThreadId ,
66 type OrchestrationV2ServerCommand as OrchestrationCommand ,
7+ PullRequestOperationError ,
78 type OrchestrationProjectShell ,
9+ type PullRequestRef ,
10+ type PullRequestReviewGuideResult ,
811 type ThreadPullRequestLink ,
912} from "@t3tools/contracts" ;
1013import { describe , expect , it } from "@effect/vitest" ;
@@ -22,6 +25,7 @@ import {
2225 v2PullRequestThread ,
2326} from "../../../orchestration-v2/testkit/pullRequestFixtures.ts" ;
2427import * as ProjectService from "../../../project/ProjectService.ts" ;
28+ import * as PullRequestReviewGuideService from "../../../pullRequest/PullRequestReviewGuideService.ts" ;
2529import * as McpInvocationContext from "../../McpInvocationContext.ts" ;
2630import * as McpToolAccess from "../../McpToolAccess.ts" ;
2731import * as McpToolAccessTestkit from "../../McpToolAccess.testkit.ts" ;
@@ -135,12 +139,24 @@ interface HarnessOptions {
135139 readonly project ?: OrchestrationProjectShell | null ;
136140 /** A rejection the orchestrator reports as the dispatch error's cause. */
137141 readonly reject ?: ( command : OrchestrationCommand ) => string | null ;
142+ /** Every project in the environment; defaults to the thread's own. */
143+ readonly projects ?: ReadonlyArray < OrchestrationProjectShell > ;
144+ /** What the guide service answers for a pull request it is asked to write. */
145+ readonly generate ?: (
146+ input : PullRequestRef ,
147+ ) => Effect . Effect <
148+ PullRequestReviewGuideResult & { started : boolean } ,
149+ PullRequestOperationError
150+ > ;
138151}
139152
153+ const NO_GUIDE : PullRequestReviewGuideResult = { guide : null , run : null , currentHeadSha : "head-1" } ;
154+
140155const makeHarness = Effect . fn ( "makePullRequestsToolkitHarness" ) ( function * (
141156 options : HarnessOptions = { } ,
142157) {
143158 const commands = yield * Ref . make < ReadonlyArray < OrchestrationCommand > > ( [ ] ) ;
159+ const guideRequests = yield * Ref . make < ReadonlyArray < PullRequestRef > > ( [ ] ) ;
144160 const thread = options . thread === undefined ? makeThread ( [ ] ) : options . thread ;
145161 const project = options . project === undefined ? makeProject ( ) : options . project ;
146162 const dispatch : Orchestrator . OrchestratorV2Shape [ "dispatch" ] = ( command ) =>
@@ -158,6 +174,25 @@ const makeHarness = Effect.fn("makePullRequestsToolkitHarness")(function* (
158174 const layerDependencies = Layer . mergeAll (
159175 Layer . mock ( ProjectService . ProjectService ) ( {
160176 getShell : ( ) => Effect . succeed ( Option . fromNullishOr ( project ) ) ,
177+ listShells : ( ) => Effect . succeed ( options . projects ?? ( project ? [ project ] : [ ] ) ) ,
178+ } ) ,
179+ Layer . mock ( PullRequestReviewGuideService . PullRequestReviewGuideService ) ( {
180+ get : ( ) => Effect . succeed ( NO_GUIDE ) ,
181+ generate : ( input ) =>
182+ Ref . update ( guideRequests , ( recorded ) => [ ...recorded , input ] ) . pipe (
183+ Effect . andThen (
184+ options . generate ?.( input ) ??
185+ Effect . succeed ( {
186+ ...NO_GUIDE ,
187+ run : {
188+ _tag : "Running" as const ,
189+ headSha : "head-1" ,
190+ startedAt : "2026-10-11T00:00:00.000Z" ,
191+ } ,
192+ started : true ,
193+ } ) ,
194+ ) ,
195+ ) ,
161196 } ) ,
162197 Layer . mock ( Orchestrator . OrchestratorV2 ) ( {
163198 getThreadShell : ( id ) =>
@@ -189,7 +224,7 @@ const makeHarness = Effect.fn("makePullRequestsToolkitHarness")(function* (
189224 Effect . provideService ( McpInvocationContext . McpInvocationContext , invocation ( capabilities ) ) ,
190225 Effect . provide ( layerDependencies ) ,
191226 ) ;
192- return { commands, call } ;
227+ return { commands, guideRequests , call } ;
193228} ) ;
194229
195230describe ( "pull request toolkit handlers" , ( ) => {
@@ -546,6 +581,159 @@ describe("listThreadPullRequests", () => {
546581 } ) ;
547582} ) ;
548583
584+ describe ( "pull request guide tools" , ( ) => {
585+ it . effect (
586+ "writes guides through the project whose checkout is each pull request's repository" ,
587+ ( ) =>
588+ Effect . gen ( function * ( ) {
589+ const other = {
590+ ...makeProject ( {
591+ canonicalKey : "github.com/acme/web" ,
592+ locator : {
593+ source : "git-remote" ,
594+ remoteName : "origin" ,
595+ remoteUrl :
"[email protected] :acme/web.git" , 596+ } ,
597+ provider : "github" ,
598+ displayName : "acme/web" ,
599+ owner : "acme" ,
600+ name : "web" ,
601+ } ) ,
602+ id : ProjectId . make ( "project-web" ) ,
603+ } ;
604+ const harness = yield * makeHarness ( { projects : [ makeProject ( ) , other ] } ) ;
605+ const result = yield * harness . call ( "write_pull_request_guides" , {
606+ pullRequests : [
607+ { url : "https://github.com/acme/web/pull/7" } ,
608+ { repository : "t3tools/t3code" , number : 12 } ,
609+ { url : "https://github.com/someone/else/pull/1" } ,
610+ ] ,
611+ } ) ;
612+ expect (
613+ result . guides . map ( ( guide ) => [ guide . repository , guide . number , guide . outcome ] ) ,
614+ ) . toEqual ( [
615+ [ "acme/web" , 7 , "started" ] ,
616+ [ "t3tools/t3code" , 12 , "started" ] ,
617+ [ "someone/else" , 1 , "failed" ] ,
618+ ] ) ;
619+ expect ( result . guides [ 2 ] ?. detail ) . toContain ( "No project in this environment" ) ;
620+ expect (
621+ ( yield * Ref . get ( harness . guideRequests ) ) . map ( ( ref ) => [ ref . projectId , ref . number ] ) ,
622+ ) . toEqual ( [
623+ [ "project-web" , 7 ] ,
624+ [ PROJECT_ID , 12 ] ,
625+ ] ) ;
626+ } ) ,
627+ ) ;
628+
629+ it . effect ( "reports a refused run on its own pull request without failing the rest" , ( ) =>
630+ Effect . gen ( function * ( ) {
631+ const harness = yield * makeHarness ( {
632+ generate : ( input ) =>
633+ input . number === 1
634+ ? Effect . fail (
635+ new PullRequestOperationError ( {
636+ operation : "generateReviewGuide" ,
637+ detail : "Review guides are off. Turn them on in Settings → Source Control." ,
638+ } ) ,
639+ )
640+ : Effect . succeed ( {
641+ ...NO_GUIDE ,
642+ run : {
643+ _tag : "Running" as const ,
644+ headSha : "head-1" ,
645+ startedAt : "2026-10-11T00:00:00.000Z" ,
646+ } ,
647+ started : true ,
648+ } ) ,
649+ } ) ;
650+ const result = yield * harness . call ( "write_pull_request_guides" , {
651+ pullRequests : [
652+ { repository : "t3tools/t3code" , number : 1 } ,
653+ { repository : "t3tools/t3code" , number : 2 } ,
654+ ] ,
655+ } ) ;
656+ expect ( result . guides . map ( ( guide ) => [ guide . number , guide . outcome , guide . detail ] ) ) . toEqual ( [
657+ [ 1 , "failed" , "Review guides are off. Turn them on in Settings → Source Control." ] ,
658+ [ 2 , "started" , null ] ,
659+ ] ) ;
660+ } ) ,
661+ ) ;
662+
663+ it . effect ( "reports an unreadable entry on its own and still writes the rest of the batch" , ( ) =>
664+ Effect . gen ( function * ( ) {
665+ const harness = yield * makeHarness ( ) ;
666+ const result = yield * harness . call ( "write_pull_request_guides" , {
667+ pullRequests : [
668+ { url : "https://example.com/not-a-pull-request" } ,
669+ { repository : "t3tools/t3code" } ,
670+ { repository : "t3tools/t3code" , number : 5 } ,
671+ ] ,
672+ } ) ;
673+ expect ( result . guides . map ( ( guide ) => guide . outcome ) ) . toEqual ( [ "failed" , "failed" , "started" ] ) ;
674+ expect ( result . guides [ 0 ] ?. detail ) . toContain ( "not a recognised pull request URL" ) ;
675+ expect ( result . guides [ 1 ] ?. detail ) . toContain ( "Pass either url" ) ;
676+ expect ( ( yield * Ref . get ( harness . guideRequests ) ) . map ( ( ref ) => ref . number ) ) . toEqual ( [ 5 ] ) ;
677+ } ) ,
678+ ) ;
679+
680+ it . effect ( "reports a run the service joined as running, not as a new one" , ( ) =>
681+ Effect . gen ( function * ( ) {
682+ const harness = yield * makeHarness ( {
683+ generate : ( ) =>
684+ Effect . succeed ( {
685+ ...NO_GUIDE ,
686+ run : { _tag : "Running" , headSha : "head-1" , startedAt : "2026-10-11T00:00:00.000Z" } ,
687+ started : false ,
688+ } ) ,
689+ } ) ;
690+ const result = yield * harness . call ( "write_pull_request_guides" , {
691+ pullRequests : [ { repository : "t3tools/t3code" , number : 4 } ] ,
692+ } ) ;
693+ expect ( result . guides . map ( ( guide ) => guide . outcome ) ) . toEqual ( [ "running" ] ) ;
694+ } ) ,
695+ ) ;
696+
697+ it . effect ( "finds an Azure DevOps checkout for a pull request named by its full path" , ( ) =>
698+ Effect . gen ( function * ( ) {
699+ const azure = {
700+ ...makeProject ( {
701+ canonicalKey : "dev.azure.com/org/project/_git/web" ,
702+ locator : {
703+ source : "git-remote" ,
704+ remoteName : "origin" ,
705+ remoteUrl : "https://dev.azure.com/org/project/_git/web" ,
706+ } ,
707+ provider : "azure-devops" ,
708+ displayName : "org/project/_git/web" ,
709+ owner : "org" ,
710+ name : "web" ,
711+ } ) ,
712+ id : ProjectId . make ( "project-azure" ) ,
713+ } ;
714+ const harness = yield * makeHarness ( { projects : [ makeProject ( ) , azure ] } ) ;
715+ const result = yield * harness . call ( "write_pull_request_guides" , {
716+ pullRequests : [ { host : "dev.azure.com" , repository : "org/project/_git/web" , number : 9 } ] ,
717+ } ) ;
718+ expect ( result . guides . map ( ( guide ) => guide . outcome ) ) . toEqual ( [ "started" ] ) ;
719+ expect ( ( yield * Ref . get ( harness . guideRequests ) ) . map ( ( ref ) => ref . projectId ) ) . toEqual ( [
720+ "project-azure" ,
721+ ] ) ;
722+ } ) ,
723+ ) ;
724+
725+ it . effect ( "reads a stored guide and says when a push left it behind" , ( ) =>
726+ Effect . gen ( function * ( ) {
727+ const harness = yield * makeHarness ( ) ;
728+ const result = yield * harness . call ( "read_pull_request_guide" , {
729+ repository : "t3tools/t3code" ,
730+ number : 3 ,
731+ } ) ;
732+ expect ( result ) . toMatchObject ( { number : 3 , guide : null , run : null , stale : false } ) ;
733+ } ) ,
734+ ) ;
735+ } ) ;
736+
549737it ( "keeps failure diagnostics as the cause rather than exposing them in the tool message" , ( ) => {
550738 const cause = new Error ( "database internals" ) ;
551739 const failure = new PullRequestLinkFailedError ( { cause } ) ;
0 commit comments