diff --git a/.gitignore b/.gitignore index 6707ec2f..22e79656 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,4 @@ package-lock.json yarn-error.log docs/api +.travis.ssh.key diff --git a/.travis.ssh.key.enc b/.travis.ssh.key.enc new file mode 100644 index 00000000..5f07ddbf Binary files /dev/null and b/.travis.ssh.key.enc differ diff --git a/.travis.ssh.key.pub b/.travis.ssh.key.pub new file mode 100644 index 00000000..e534803e --- /dev/null +++ b/.travis.ssh.key.pub @@ -0,0 +1 @@ +ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQDDFM4nHSbET5V7EYNgjA8NeVfOxV0wVMdZ2YvsDzD+qPJ4+MYbvsL7ZPaSxQSn7n6ATkLHjKje5RpF/Rl9K3kucGs0P6cqJVeE0qryEteQ3Q+fYAk+bD2J9ZQ/hv/0NtLl8T+7lJUZ3WUxFH73sgph77Sw0z+kMpPaK7U2vqMBQD/7+6iJgya31wP0qW0XKDz1BjKeXgwTg10Pm4vcGsR4c2q7YIzSzBHffcyo0vJyFvOX/ZKHlZRcq/wnQMeOl/hPgf1xCENjQZmFVReQlYSw5cNNDT9HZPKekOAZFFez7/AbPiTIo/bnBYIv0mdUjr3nw8nXF505q8LiD3z/ksaaWDqe9CCLM4W0Bh7/dhP7IGPdfX0fVHLhOnYIOsG21D8rWJjMPkVRSLyEvWNAnVuObJNHoQu8VATnOxfPNnMun72IHyyFWVoADk5JcsMbzcP7gZB+5oJO7U1qpcdndtBOA3ZlF0Uz2jVZnqavoEBWT39tl3vs69hAA3aTPGclg7HMuAJOl4HsKmaUgDxqV2wCX/S4pDqmKMbmumDLX+MM0xl0gXj/zpVJp9BzdnrArkC40ivmC6TSA4wrdN0tNBlqApkH5/jxGWrcu2AXVn9PGF3+QrjW0iu+QMZCaKWDhLIQC835uFwzhnNGlx41B7uxMLuNFxKXdQ3f/cC9QMG8ew== TravisCIDeployKey diff --git a/.travis.yml b/.travis.yml index 4933297a..6dd634a3 100644 --- a/.travis.yml +++ b/.travis.yml @@ -13,15 +13,31 @@ cache: - node_modules - app/node_modules -before_install: - - rm app/node_modules/.yarn-integrity || true - - yarn +stages: + - Build + - name: Docs + if: branch = master -script: - - scripts/build-native.js - - yarn run build - - scripts/prepackage-plugins.js - - scripts/build-$BUILD_FOR.js +jobs: + include: + - stage: 'Build' + before_install: + - rm app/node_modules/.yarn-integrity || true + - yarn + script: + - scripts/build-native.js + - yarn run build + - scripts/prepackage-plugins.js + - scripts/build-$BUILD_FOR.js + + - stage: 'Docs' + os: linux + script: + - openssl aes-256-cbc -K $encrypted_4e2fb4889ef8_key -iv $encrypted_4e2fb4889ef8_iv -in .travis.ssh.key.enc -out .travis.ssh.key -d + - ssh-add .travis.ssh.key + - yarn + - yarn run docs + - rsync -r docs/api/ root@ajenti.org:/srv/terminus-docs/ dist: trusty sudo: false diff --git a/package.json b/package.json index de39e16a..5dca2e66 100644 --- a/package.json +++ b/package.json @@ -131,6 +131,7 @@ "watch": "cross-env TERMINUS_DEV=1 webpack --progress --color --watch", "start": "cross-env TERMINUS_DEV=1 electron app --debug", "prod": "cross-env TERMINUS_DEV=1 electron app", + "docs": "typedoc --out docs/api terminus-core/src && typedoc --out docs/api/terminal terminus-terminal/src && typedoc --out docs/api/settings terminus-settings/src", "lint": "tslint -c tslint.json -t stylish terminus-*/src/**/*.ts terminus-*/src/*.ts app/src/*.ts", "postinstall": "node ./scripts/install-deps.js" }, diff --git a/terminus-core/README.md b/terminus-core/README.md index 84724ea4..0bf5ef39 100644 --- a/terminus-core/README.md +++ b/terminus-core/README.md @@ -1,6 +1,8 @@ Terminus Core Plugin -------------------- +See also: [Settings plugin API](./settings/), [Terminal plugin API](./settings/) + * tabbed interface services * toolbar UI * config file management diff --git a/terminus-settings/README.md b/terminus-settings/README.md new file mode 100644 index 00000000..88706262 --- /dev/null +++ b/terminus-settings/README.md @@ -0,0 +1,23 @@ +Terminus Settings Plugin +------------------------ + +* tabbed settings interface + +Using the API: + +```ts +import { SettingsTabProvider } from 'terminus-settings' +``` + +Exporting your subclasses: + +```ts +@NgModule({ + ... + providers: [ + ... + { provide: SettingsTabProvider, useClass: MySettingsTab, multi: true }, + ... + ] +}) +``` diff --git a/terminus-settings/src/api.ts b/terminus-settings/src/api.ts index 97faa620..9f7f4cd3 100644 --- a/terminus-settings/src/api.ts +++ b/terminus-settings/src/api.ts @@ -1,3 +1,6 @@ +/** + * Extend to add your own settings tabs + */ export abstract class SettingsTabProvider { id: string icon: string diff --git a/terminus-terminal/README.md b/terminus-terminal/README.md new file mode 100644 index 00000000..2b7a10a3 --- /dev/null +++ b/terminus-terminal/README.md @@ -0,0 +1,26 @@ +Terminus Terminal Plugin +------------------------ + +* terminal tabs +* terminal frontends +* session management +* shell detection + +Using the API: + +```ts +import { TerminalContextMenuItemProvider } from 'terminus-terminal' +``` + +Exporting your subclasses: + +```ts +@NgModule({ + ... + providers: [ + ... + { provide: TerminalContextMenuItemProvider, useClass: MyContextMenu, multi: true }, + ... + ] +}) +``` diff --git a/terminus-terminal/src/api.ts b/terminus-terminal/src/api.ts index be2e6aff..3f705337 100644 --- a/terminus-terminal/src/api.ts +++ b/terminus-terminal/src/api.ts @@ -1,10 +1,18 @@ import { BaseTerminalTabComponent } from './components/baseTerminalTab.component' +/** + * Extend to automatically run actions on new terminals + */ export abstract class TerminalDecorator { - // tslint:disable-next-line no-empty - attach (_terminal: BaseTerminalTabComponent): void { } - // tslint:disable-next-line no-empty - detach (_terminal: BaseTerminalTabComponent): void { } + /** + * Called when a new terminal tab starts + */ + attach (terminal: BaseTerminalTabComponent): void { } // tslint:disable-line no-empty + + /** + * Called before a terminal tab is destroyed + */ + detach (terminal: BaseTerminalTabComponent): void { } // tslint:disable-line no-empty } export interface ResizeEvent { @@ -17,7 +25,7 @@ export interface SessionOptions { command: string args: string[] cwd?: string - env?: any + env?: {[id: string]: string} width?: number height?: number pauseAfterExit?: boolean @@ -37,10 +45,16 @@ export interface ITerminalColorScheme { colors: string[] } +/** + * Extend to add more terminal color schemes + */ export abstract class TerminalColorSchemeProvider { abstract async getSchemes (): Promise } +/** + * Extend to add more terminal context menu items + */ export abstract class TerminalContextMenuItemProvider { weight: number @@ -52,10 +66,18 @@ export interface IShell { name?: string command: string args?: string[] - env?: any + env?: {[id: string]: string} + + /** + * Base path to which shell's internal FS is relative + * Currently used for WSL only + */ fsBase?: string } +/** + * Extend to add support for more shells + */ export abstract class ShellProvider { abstract async provide (): Promise } diff --git a/terminus-terminal/src/components/baseTerminalTab.component.ts b/terminus-terminal/src/components/baseTerminalTab.component.ts index dc0768d6..784e7c0e 100644 --- a/terminus-terminal/src/components/baseTerminalTab.component.ts +++ b/terminus-terminal/src/components/baseTerminalTab.component.ts @@ -10,29 +10,43 @@ import { TerminalFrontendService } from '../services/terminalFrontend.service' import { TerminalDecorator, ResizeEvent, TerminalContextMenuItemProvider } from '../api' import { Frontend } from '../frontends/frontend' +/** + * A class to base your custom terminal tabs on + */ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit, OnDestroy { static template = `
` static styles = [require('./terminalTab.component.scss')] session: BaseSession @Input() zoom = 0 + + /** @hidden */ @ViewChild('content') content + + /** @hidden */ @HostBinding('style.background-color') backgroundColor: string + + /** @hidden */ @HostBinding('class.top-padded') topPadded: boolean + frontend: Frontend - sessionCloseSubscription: Subscription - hotkeysSubscription: Subscription - htermVisible = false + + /** @hidden */ + frontendIsReady = false + frontendReady = new Subject() size: ResizeEvent + protected logger: Logger protected output = new Subject() + private sessionCloseSubscription: Subscription + private hotkeysSubscription: Subscription private bellPlayer: HTMLAudioElement private termContainerSubscriptions: Subscription[] = [] @@ -122,6 +136,7 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit this.contextMenuProviders.sort((a, b) => a.weight - b.weight) } + /** @hidden */ ngOnInit () { this.focused$.subscribe(() => { this.configure() @@ -131,7 +146,7 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit this.frontend = this.terminalContainersService.getFrontend(this.session) this.frontend.ready$.subscribe(() => { - this.htermVisible = true + this.frontendIsReady = true }) this.frontend.resize$.pipe(first()).subscribe(async ({ columns, rows }) => { @@ -191,14 +206,14 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit return items } - detachTermContainerHandlers () { + protected detachTermContainerHandlers () { for (let subscription of this.termContainerSubscriptions) { subscription.unsubscribe() } this.termContainerSubscriptions = [] } - attachTermContainerHandlers () { + protected attachTermContainerHandlers () { this.detachTermContainerHandlers() const maybeConfigure = () => { @@ -274,6 +289,9 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit ] } + /** + * Feeds input into the active session + */ sendInput (data: string) { this.session.write(data) if (this.config.store.terminal.scrollOnInput) { @@ -281,6 +299,9 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit } } + /** + * Feeds input into the terminal frontend + */ write (data: string) { let percentageMatch = /(^|[^\d])(\d+(\.\d+)?)%([^\d]|$)/.exec(data) if (percentageMatch) { @@ -308,6 +329,9 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit this.sendInput(data) } + /** + * Applies the user settings to the terminal + */ configure (): void { this.frontend.configure() @@ -339,6 +363,7 @@ export class BaseTerminalTabComponent extends BaseTabComponent implements OnInit this.frontend.setZoom(this.zoom) } + /** @hidden */ ngOnDestroy () { this.frontend.detach(this.content.nativeElement) this.detachTermContainerHandlers() diff --git a/terminus-terminal/src/components/terminalTab.component.ts b/terminus-terminal/src/components/terminalTab.component.ts index 59e2e18b..a99f852e 100644 --- a/terminus-terminal/src/components/terminalTab.component.ts +++ b/terminus-terminal/src/components/terminalTab.component.ts @@ -5,6 +5,7 @@ import { BaseTerminalTabComponent } from './baseTerminalTab.component' import { SessionOptions } from '../api' import { Session } from '../services/sessions.service' +/** @hidden */ @Component({ selector: 'terminalTab', template: BaseTerminalTabComponent.template, diff --git a/terminus-terminal/src/frontends/frontend.ts b/terminus-terminal/src/frontends/frontend.ts index fae63875..6efc3f69 100644 --- a/terminus-terminal/src/frontends/frontend.ts +++ b/terminus-terminal/src/frontends/frontend.ts @@ -2,6 +2,9 @@ import { Observable, Subject, AsyncSubject, ReplaySubject, BehaviorSubject } fro import { ResizeEvent } from '../api' import { ConfigService, ThemesService } from 'terminus-core' +/** + * Extend to add support for a different VT frontend implementation + */ export abstract class Frontend { configService: ConfigService themesService: ThemesService diff --git a/terminus-terminal/src/services/sessions.service.ts b/terminus-terminal/src/services/sessions.service.ts index 596391af..7b87b279 100644 --- a/terminus-terminal/src/services/sessions.service.ts +++ b/terminus-terminal/src/services/sessions.service.ts @@ -10,16 +10,13 @@ import { exec } from 'mz/child_process' import { SessionOptions } from '../api' import { WIN_BUILD_CONPTY_SUPPORTED, isWindowsBuild } from '../utils' -let macOSNativeProcessList try { - macOSNativeProcessList = require('macos-native-processlist') -} catch (e) { } // tslint:disable-line + var macOSNativeProcessList = require('macos-native-processlist') // tslint:disable-line +} catch { } // tslint:disable-line -let windowsProcessTree try { - windowsProcessTree = require('windows-process-tree') -} catch (e) { -} // tslint:disable-line + var windowsProcessTree = require('windows-process-tree') // tslint:disable-line +} catch { } // tslint:disable-line export interface IChildProcess { pid: number @@ -31,6 +28,10 @@ const windowsDirectoryRegex = /([a-zA-Z]:[^\:\[\]\?\"\<\>\|]+)/mi // tslint:dis const OSC1337Prefix = '\x1b]1337;' const OSC1337Suffix = '\x07' +/** + * A session object for a [[BaseTerminalTabComponent]] + * Extend this to implement custom I/O and process management for your terminal tab + */ export abstract class BaseSession { open: boolean name: string @@ -59,10 +60,10 @@ export abstract class BaseSession { this.initialDataBuffer = null } - abstract start (options: SessionOptions) - abstract resize (columns, rows) - abstract write (data) - abstract kill (signal?: string) + abstract start (options: SessionOptions): void + abstract resize (columns: number, rows: number): void + abstract write (data: string): void + abstract kill (signal?: string): void abstract async getChildProcesses (): Promise abstract async gracefullyKillProcess (): Promise abstract async getWorkingDirectory (): Promise diff --git a/terminus-terminal/src/services/terminal.service.ts b/terminus-terminal/src/services/terminal.service.ts index cd588492..b42e2612 100644 --- a/terminus-terminal/src/services/terminal.service.ts +++ b/terminus-terminal/src/services/terminal.service.ts @@ -11,8 +11,12 @@ export class TerminalService { private shells = new AsyncSubject() private logger: Logger + /** + * A fresh list of all available shells + */ get shells$ (): Observable { return this.shells } + /** @hidden */ constructor ( private app: AppService, private config: ConfigService, @@ -28,12 +32,12 @@ export class TerminalService { }) } - async getShells (): Promise { + private async getShells (): Promise { let shellLists = await Promise.all(this.config.enabledServices(this.shellProviders).map(x => x.provide())) return shellLists.reduce((a, b) => a.concat(b), []) } - async reloadShells () { + private async reloadShells () { this.shells = new AsyncSubject() let shells = await this.getShells() this.logger.debug('Shells list:', shells) @@ -41,6 +45,10 @@ export class TerminalService { this.shells.complete() } + /** + * Launches a new terminal with a specific shell and CWD + * @param pause Wait for a keypress when the shell exits + */ async openTab (shell?: IShell, cwd?: string, pause?: boolean): Promise { if (cwd && !fs.existsSync(cwd)) { console.warn('Ignoring non-existent CWD:', cwd) @@ -76,6 +84,9 @@ export class TerminalService { } } + /** + * Open a terminal with custom session options + */ openTabWithOptions (sessionOptions: SessionOptions): TerminalTabComponent { if (sessionOptions.runAsAdministrator && this.uac.isAvailable) { sessionOptions = this.uac.patchSessionOptionsForUAC(sessionOptions) diff --git a/terminus-terminal/src/services/terminalFrontend.service.ts b/terminus-terminal/src/services/terminalFrontend.service.ts index 4189a15e..3cb7b92d 100644 --- a/terminus-terminal/src/services/terminalFrontend.service.ts +++ b/terminus-terminal/src/services/terminalFrontend.service.ts @@ -9,6 +9,7 @@ import { BaseSession } from '../services/sessions.service' export class TerminalFrontendService { private containers = new WeakMap() + /** @hidden */ constructor (private config: ConfigService, private themes: ThemesService) { } getFrontend (session?: BaseSession): Frontend {