Expose shell integration command knowledge to extensions

[Tyriar]

Shell integration in the terminal could enable APIs like being able to listen to commands that run and get their output/exit code.

Rough example:

interface Terminal {
  executeCommand(command): Thenable<TerminalCommandResult>;
}

[ClockworkV]

I came here to request this, and here it is already.
Being in Backlog means it'll get on the work plan eventually?

Cheers, looking forward to this, it's the missing link for my 'debug last command line' extension!

[Tyriar]

@ClockworkV backlog means it's a valid item and it may be worked on in the future. I'm pretty sure this one will happen within the next year

[meganrogge]

Proposal:

registerQuickFixProvider(...options: ITerminalQuickFixOptions[]): void;


export interface ITerminalQuickFixOptions {
	commandLineMatcher: string | RegExp;
	outputMatcher?: ITerminalOutputMatcher;
	getQuickFixes: TerminalQuickFixCallback;
	exitStatus?: boolean;
}
export type TerminalQuickFixMatchResult = { commandLineMatch: RegExpMatchArray; outputMatch?: RegExpMatchArray | null };
export type TerminalQuickFixAction = IAction | ITerminalQuickFixCommandAction | ITerminalQuickFixOpenerAction;
export type TerminalQuickFixCallback = (matchResult: TerminalQuickFixMatchResult, command: ITerminalCommand) => TerminalQuickFixAction[] | TerminalQuickFixAction | undefined;

export interface ITerminalQuickFixCommandAction {
	type: 'command';
	command: string;
	addNewLine: boolean;
}
export interface ITerminalQuickFixOpenerAction {
	type: 'opener';
	uri: URI;
}
export interface ITerminalOutputMatcher {
	/**
	 * A string or regex to match against the unwrapped line. If this is a regex with the multiline
	 * flag, it will scan an amount of lines equal to `\n` instances in the regex + 1.
	 */
	lineMatcher: string | RegExp;
	/**
	 * Which side of the output to anchor the {@link offset} and {@link length} against.
	 */
	anchor: 'top' | 'bottom';
	/**
	 * How far from either the top or the bottom of the butter to start matching against.
	 */
	offset: number;
	/**
	 * The number of rows to match against, this should be as small as possible for performance
	 * reasons.
	 */
	length: number;
}

@alexr00 and @lszomoru how does this look to you, as you'll be adopting this for the git extension?

[Tyriar]

@meganrogge I've forked this off to #162950 as I realized this issue is more about general listening to commands

[mmisiewicz]

Voting for this issue. The proposed interface would exactly solve a problem I have developing an extension.

[lroberts7]

+1 for this, can we get it on a roadmap plz?

[mmisiewicz-yext]

Hi @meganrogge and @Tyriar - I've noticed this issue has been on an "iteration plan" in Nov and Oct of 2022. I'm wondering if you think it will be picked up any time soon? Thanks, really appreciate all the hard work!

[degrammer]

Hi @Tyriar, can you please confirm, if as part of this feature, allowing access to the active terminal selected text is going to be available / planned to work in the short term? (related issue #188173).

One of the use cases could be for extensions using a command as part of terminal/context to access the selected text from the terminal to perform things like AI Suggestions, Output sharing, etc.

Thank you 🙏🏼

[Tyriar]

@degrammer selection access will be done as a part of the buffer access api, not this one. That's been but on hold for a while as I have some competing priorities and want to think about the API shape in the background a bit.

We definitely do want to finalize an api for selection eventually as GH copilot uses the current proposal, unfortunately to make it future proof we need to tie it in with the much more complex buffer proposal.

[Tyriar]

Moving to July for Python to adopt first and give feedback before finalizing.

[whitequark]

Is there any way to receive a stream of raw data from a terminal that does not have shell integration? For example if I create a terminal with any command of my choice by setting shellPath to argv[0] and shellArgs to argv[1...].

Since there's only one command that could plausibly be run in that terminal it's not necessary to try and guess which command the output comes from. The current API doesn't seem to offer anything to cover this use case, and I think it would be too limiting for my purpose.

[Tyriar]

@whitequark no, this is only for when shell integration is enabled. There is the related proposal for buffer access which allows reading the buffer which would probably cover your use case. #207504

[whitequark]

@Tyriar Thank you, this really helps!

[itstreefam]

I have a quick question. What is the difference between this API and vscode.proposed.terminalExecuteCommandEvent.d.ts? My current use case is grabbing the output from an executed command, and I am using vscode.proposed.terminalExecuteCommandEvent.d.ts to do so. I suppose we can also use read() from vscode.proposed.terminalShellIntegration.d.ts to read the output stream but feel free to correct me. I wonder which one would you think have a higher chance for public release. Before these two APIs I remembered having to work around with the old vscode.proposed.terminalDataWriteEvent.d.ts, so I truly appreciate the current more stable approaches you have made available. Thanks!

[Tyriar]

@itstreefam terminalExecuteCommandEvent is old and will be removed, terminalDataWriteEvent is unlikely to get finalized and may be replaced eventually with improvements upon terminalShellIntegration. terminalShellIntegration should be finalized very soon, I just need a fix a few bugs with it.

[Tyriar]

Plan:

• Fix the 2 bugs that have been found, these are impl-related, not API shape related TerminalShellExecution.read() shows extra comma #221405, Don't fire onDidEndTerminalShellExecution with exitCode undefined immediately after first onDidChangeTerminalShellIntegration #221399
• Get final sign off from @jrieken
• Finalize for August