2
>
* Copyright (c) Microsoft Corporation. All rights reserved.
3
>
* Licensed under the MIT License. See License.txt in the project root for license information.
4
>
*--------------------------------------------------------------------------------------------*/
5
>
6
>
import { CancellationToken } from '../../../base/common/cancellation.js';
7
>
import type { IDisposable } from '../../../base/common/lifecycle.js';
8
>
import { createDecorator } from '../../instantiation/common/instantiation.js';
9
>
import type { ChangesetKind } from './changesetUri.js';
10
>
import type { InvokeChangesetOperationParams, InvokeChangesetOperationResult } from './state/protocol/channels-changeset/commands.js';
11
>
import type { ChangesetOperation, ISessionGitHubState, ISessionGitState, URI } from './state/sessionState.js';
12
>
13
>
export const IAgentHostChangesetOperationService = createDecorator<IAgentHostChangesetOperationService>('agentHostChangesetOperationService');
14
>
15
>
/**
16
>
* Server-side handler for a changeset operation advertised via
17
>
* `changeset/operationsChanged`.
18
>
*
19
>
* The agent service validates the request shape (changeset exists, operation id
20
>
* known, target scope matches) before invoking the handler; the handler is only
21
>
* responsible for executing the operation.
22
>
*/
23
>
export interface IChangesetOperationHandler {
24
>
/**
25
>
* Executes a previously advertised changeset operation.
26
>
*
27
>
* The handler receives the original protocol params so it can inspect the
28
>
* changeset channel and optional target. Validation that the operation exists
29
>
* on the changeset and supports the requested target scope happens before this
30
>
* method is called.
31
>
*/
32
>
invoke(params: InvokeChangesetOperationParams, token: CancellationToken): Promise<InvokeChangesetOperationResult>;
33
>
}
34
>
35
>
/**
36
>
* Context used by changeset operation contributions to decide which operations
37
>
* to advertise for a session changeset.
38
>
*
39
>
* Keep this interface intentionally small. Add new fields here only when a
40
>
* contribution genuinely needs them to compute operation availability. Likely
41
>
* future additions include the concrete changeset URI, the session state, the
42
>
* changeset state, or the working directory URI.
43
>
*/
44
>
export interface IChangesetOperationContext {
45
>
/** String form of the session URI that owns the changeset. */
46
>
readonly sessionKey: string;
47
>
/** Expanded changeset URI whose operations are being computed. */
48
>
readonly changesetUri: URI;
49
>
/** Well-known changeset kind for {@link changesetUri}. */
50
>
readonly changesetKind: ChangesetKind;
51
>
/** Current git metadata for the session used to compute operation availability. */
52
>
readonly gitState?: ISessionGitState;
53
>
/** Current GitHub metadata for the session used to compute operation availability. */
54
>
readonly gitHubState?: ISessionGitHubState;
55
>
}
56
>
57
>
/**
58
>
* Registration surface handed to changeset operation contributions.
59
>
*
60
>
* Contributions use this object to install operation handlers and request a
61
>
* refresh when external state changes which operations should be advertised.
62
>
*/
63
>
export interface IChangesetOperationRegistry {
64
>
/**
65
>
* Registers the server-side handler for one {@link ChangesetOperation.id}.
66
>
* The returned disposable removes only this registration.
67
>
*/
68
>
registerChangesetOperationHandler(operationId: string, handler: IChangesetOperationHandler): IDisposable;
69
>
/**
70
>
* Notifies the contribution service that advertised operations for all static
71
>
* changesets in `sessionKey` should be recomputed from current session state.
72
>
*/
73
>
onDidChangeOperations(sessionKey: string): void;
74
>
/**
75
>
* Recomputes the session's git metadata and then refreshes advertised
76
>
* operations if that metadata can be resolved.
77
>
*/
78
>
refreshSessionGitState(sessionKey: string): Promise<void>;
79
>
}
80
>
81
>
/**
82
>
* Provider of changeset operations for one feature area.
83
>
*
84
>
* A contribution owns the decision about which operations are available for a
85
>
* changeset and registers the handlers that execute those operations.
86
>
*/
87
>
export interface IChangesetOperationContribution extends IDisposable {
88
>
/**
89
>
* Registers every operation handler owned by this contribution. Called once
90
>
* when the contribution is added to the service.
91
>
*/
92
>
registerHandlers(registry: IChangesetOperationRegistry): IDisposable;
93
>
/**
94
>
* Returns operations that should be advertised for the given changeset, or
95
>
* `undefined` when this contribution has nothing to offer in the context.
96
>
*/
97
>
getOperations(context: IChangesetOperationContext): readonly ChangesetOperation[] | undefined;
98
>
}
99
>
100
>
/**
101
>
* Coordinates changeset operation contributions, advertised operation state,
102
>
* and client-triggered invocation.
103
>
*/
104
>
export interface IAgentHostChangesetOperationService extends IDisposable {
105
>
readonly _serviceBrand: undefined;
106
>
107
>
/**
108
>
* Adds a contribution and registers its handlers. Disposing the returned value
109
>
* unregisters the handlers and disposes the contribution.
110
>
*/
111
>
registerContribution(contribution: IChangesetOperationContribution): IDisposable;
112
>
/**
113
>
* Recomputes and publishes operations for the changesets for a given
114
>
* session. If `gitState` is not provided, the current git state will
115
>
* be used.
116
>
*/
117
>
updateOperations(sessionKey: string, changeset?: string, gitState?: ISessionGitState, gitHubState?: ISessionGitHubState): void;
118
>
119
>
/**
120
>
* Returns the operations that should be advertised for the given changeset, or
121
>
* `undefined` when no operations are available.
122
>
*/
123
>
getOperations(sessionKey: string, changeset?: string, gitState?: ISessionGitState, gitHubState?: ISessionGitHubState): readonly ChangesetOperation[] | undefined;
124
>
125
>
/**
126
>
* Invokes an advertised operation after validating the changeset, operation id,
127
>
* and requested target scope.
128
>
*/
129
>
invokeChangesetOperation(params: InvokeChangesetOperationParams): Promise<InvokeChangesetOperationResult>;
130
>
}