feat: add CommentaryReponse to snapshot/replay the response of commentary command

Fixes #5439

Author: myan9

packages/core/src/index.ts

@@ -147,6 +147,7 @@ export { disableInputQueueing } from './webapp/queueing'
 export { isPopup } from './webapp/popup-core'
 export { removeAllDomChildren as empty } from './webapp/util/dom'
 export { default as Presentation } from './webapp/views/presentation'
+export { CommentaryResponse, isCommentaryResponse } from './models/CommentaryResponse'
 export {
   ModeOrButton as Mode,
   Button,

packages/core/src/models/CommentaryResponse.ts

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2020 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Entity } from './entity'
+import REPL from './repl'
+
+export type CommentaryResponse = {
+  apiVersion: 'kui-shell/v1'
+  kind: 'CommentaryResponse'
+  props: {
+    /** Content rendered inside the CardTitle */
+    title?: string
+
+    /** Body of the Card. It will be passed through as the source <Markdown source="..." /> */
+    children: string
+
+    /** [Optional] REPL controller, but required if you want your Card
+     * to have functional kuiexec?command=... links via Markdown */
+    repl?: REPL
+  }
+}
+
+export function isCommentaryResponse(entity: Entity): entity is CommentaryResponse {
+  const response = entity as CommentaryResponse
+  return response.apiVersion === 'kui-shell/v1' && response.kind === 'CommentaryResponse'
+}

packages/core/src/models/entity.ts

@@ -21,6 +21,7 @@ import { UsageModel } from '../core/usage-error'
 import isMultiModalResponse from './mmr/is'
 import MultiModalResponse from './mmr/types'
 import { NavResponse, isNavResponse } from './NavResponse'
+import { CommentaryResponse } from './CommentaryResponse'
 import RadioTable from './RadioTable'
 import Presentation from '../webapp/views/presentation'
 import { ReactNode, isValidElement } from 'react'
@@ -182,7 +183,11 @@ export function isRawResponse<Content extends RawContent>(entity: Entity<Content
  * that views may wish to interpret into fancier views.
  *
  */
-export type ScalarResponse<RowType extends Row = Row> = SimpleEntity | Table<RowType> | MixedResponse
+export type ScalarResponse<RowType extends Row = Row> =
+  | SimpleEntity
+  | Table<RowType>
+  | MixedResponse
+  | CommentaryResponse
 
 export function isScalarResponse(response: Entity): response is ScalarResponse {
   return !isMultiModalResponse(response) && !isNavResponse(response)

plugins/plugin-client-common/src/components/Content/Commentary.tsx

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2020 IBM Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as React from 'react'
+import { CommentaryResponse } from '@kui-shell/core'
+import Card from '../spi/Card'
+
+export default class Commentary extends React.PureComponent<CommentaryResponse['props']> {
+  public render() {
+    return <Card {...this.props} />
+  }
+}

plugins/plugin-client-common/src/components/Content/Scalar/index.tsx

@@ -20,6 +20,7 @@ import {
   isMessageWithCode,
   Tab as KuiTab,
   ScalarResponse,
+  isCommentaryResponse,
   isHTML,
   isMarkdownResponse,
   isReactResponse,
@@ -29,6 +30,7 @@ import {
   isUsageError
 } from '@kui-shell/core'
 
+import Commentary from '../Commentary'
 import HTMLDom from './HTMLDom'
 import renderTable from '../Table'
 import Markdown from '../Markdown'
@@ -83,6 +85,8 @@ export default class Scalar extends React.PureComponent<Props, State> {
         return <React.Fragment />
       } else if (typeof response === 'number' || typeof response === 'string') {
         return <pre>{response}</pre>
+      } else if (isCommentaryResponse(response)) {
+        return <Commentary {...response.props} />
       } else if (isRadioTable(response)) {
         return (
           <KuiContext.Consumer>

plugins/plugin-client-common/src/components/Views/Terminal/Block/Output.tsx

@@ -19,6 +19,7 @@ import * as React from 'react'
 import {
   i18n,
   isCodedError,
+  isCommentaryResponse,
   isHTML,
   isReactResponse,
   isMarkdownResponse,
@@ -199,6 +200,7 @@ export default class Output extends React.PureComponent<Props, State> {
     if (isFinished(block) && !isCancelled(block) && !isEmpty(block)) {
       const { response } = block
       return (
+        isCommentaryResponse(response) ||
         isReactResponse(response) ||
         isHTML(response) ||
         isMarkdownResponse(response) ||

plugins/plugin-client-common/src/controller/card.ts

@@ -14,17 +14,10 @@
  * limitations under the License.
  */
 
-import {
-  Arguments,
-  Registrar,
-  ParsedOptions,
-  UsageModel,
-  ReactResponse,
-  findFile,
-  expandHomeDir
-} from '@kui-shell/core'
-import { FStat } from '@kui-shell/plugin-bash-like/fs'
+import { Arguments, Registrar, ParsedOptions, UsageModel, ReactResponse } from '@kui-shell/core'
+
 import card from '../components/spi/Card'
+import { fetchMarkdownFile } from './commentary'
 
 /**
  * card command parsedOptions type
@@ -79,25 +72,8 @@ async function doCard(opts: Arguments<CardOptions>): Promise<ReactResponse> {
 
   const filepath = option.filename || option.f
   if (filepath) {
-    const fullpath = findFile(expandHomeDir(filepath))
-    const suffix = filepath.substring(filepath.lastIndexOf('.') + 1)
-
-    if (suffix !== 'md') {
-      throw new Error('File extension not support')
-    } else {
-      // fetch the data:
-      //   --with-data says give us the file contents
-      const stats = (
-        await opts.tab.REPL.rexec<FStat>(`vfs fstat ${opts.tab.REPL.encodeComponent(fullpath)} --with-data`)
-      ).content
-
-      if (stats.isDirectory) {
-        throw new Error('Invalid filepath')
-      } else {
-        const data: string = stats.data
-        return { react: card({ title, children: data, icon }) }
-      }
-    }
+    const data = await fetchMarkdownFile(filepath, opts)
+    return { react: card({ title, children: data, icon }) }
   } else {
     const body = argv.slice(1)
     if (body) {

plugins/plugin-client-common/src/controller/commentary.ts

@@ -14,7 +14,25 @@
  * limitations under the License.
  */
 
-import { Arguments, Registrar, UsageModel } from '@kui-shell/core'
+import {
+  Arguments,
+  CommentaryResponse,
+  ParsedOptions,
+  Registrar,
+  UsageModel,
+  findFile,
+  expandHomeDir
+} from '@kui-shell/core'
+import { FStat } from '@kui-shell/plugin-bash-like/fs'
+
+/**
+ * commentary command parsedOptions type
+ */
+interface CommentaryOptions extends ParsedOptions {
+  title: string
+  file: string
+  f: string
+}
 
 /**
  * commentary command usage
@@ -38,9 +56,43 @@ const usage: UsageModel = {
   ]
 }
 
-async function addComment(args: Arguments) {
-  // delegate to the card command
-  return args.tab.REPL.qexec(args.command.replace(/^commentary/, 'card'))
+export async function fetchMarkdownFile(filepath: string, args: Arguments): Promise<string> {
+  const fullpath = findFile(expandHomeDir(filepath))
+  const suffix = filepath.substring(filepath.lastIndexOf('.') + 1)
+
+  if (suffix !== 'md') {
+    throw new Error('File extension not support')
+  } else {
+    // fetch the data:
+    //   --with-data says give us the file contents
+    const stats = (await args.tab.REPL.rexec<FStat>(`vfs fstat ${args.tab.REPL.encodeComponent(fullpath)} --with-data`))
+      .content
+
+    if (stats.isDirectory) {
+      throw new Error('Invalid filepath')
+    } else {
+      return stats.data as string
+    }
+  }
+}
+
+async function addComment(args: Arguments<CommentaryOptions>): Promise<CommentaryResponse> {
+  const { title } = args.parsedOptions
+  const filepath = args.parsedOptions.file || args.parsedOptions.f
+
+  if (filepath) {
+    const data = await fetchMarkdownFile(filepath, args)
+    return {
+      apiVersion: 'kui-shell/v1',
+      kind: 'CommentaryResponse',
+      props: {
+        title,
+        children: data
+      }
+    }
+  } else {
+    throw new Error('Insufficient arguments: must specify --file or -f')
+  }
 }
 
 /**

plugins/plugin-core-support/src/test/core-support/commentary.ts

@@ -21,26 +21,25 @@ import { Common, CLI, ReplExpect, Selectors } from '@kui-shell/test'
 
 const ROOT = dirname(require.resolve('@kui-shell/plugin-core-support/package.json'))
 
-describe('commentary command', function(this: Common.ISuite) {
+describe('commentary and replay', function(this: Common.ISuite) {
   before(Common.before(this))
   after(Common.after(this))
 
+  const verifyComment = async () => {
+    await this.app.client.waitForVisible(`${Selectors.OUTPUT_LAST} ${Selectors.TERMINAL_CARD}`)
+    const title: string = await this.app.client.getText(`${Selectors.OUTPUT_LAST} ${Selectors.TERMINAL_CARD_TITLE}`)
+    assert.strictEqual(title, 'hello there')
+
+    const head1: string = await this.app.client.getText(`${Selectors.OUTPUT_LAST} ${Selectors.TERMINAL_CARD} h1`)
+    assert.strictEqual(head1, 'The Kui Framework for Graphical Terminals')
+
+    const head2: string = await this.app.client.getText(`${Selectors.OUTPUT_LAST} ${Selectors.TERMINAL_CARD} h2`)
+    assert.strictEqual(head2, 'Installation')
+  }
   const addComment = () => {
     it('should show comment with file', () =>
       CLI.command(`commentary --title "hello there" -f=${ROOT}/tests/data/comment.md`, this.app)
-        .then(async () => {
-          await this.app.client.waitForVisible(`${Selectors.OUTPUT_LAST} ${Selectors.TERMINAL_CARD}`)
-          const title: string = await this.app.client.getText(
-            `${Selectors.OUTPUT_LAST} ${Selectors.TERMINAL_CARD_TITLE}`
-          )
-          assert.strictEqual(title, 'hello there')
-
-          const head1: string = await this.app.client.getText(`${Selectors.OUTPUT_LAST} ${Selectors.TERMINAL_CARD} h1`)
-          assert.strictEqual(head1, 'The Kui Framework for Graphical Terminals')
-
-          const head2: string = await this.app.client.getText(`${Selectors.OUTPUT_LAST} ${Selectors.TERMINAL_CARD} h2`)
-          assert.strictEqual(head2, 'Installation')
-        })
+        .then(() => verifyComment())
         .catch(Common.oops(this)))
   }
 
@@ -50,4 +49,16 @@ describe('commentary command', function(this: Common.ISuite) {
       .then(ReplExpect.okWithCustom({ expect: Common.expectedVersion }))
       .catch(Common.oops(this)))
   addComment()
+
+  it('should snapshot', () =>
+    CLI.command('snapshot /tmp/test.kui', this.app)
+      .then(ReplExpect.justOK)
+      .catch(Common.oops(this, true)))
+
+  it('should refresh', () => Common.refresh(this))
+
+  it('should replay', () =>
+    CLI.command('replay /tmp/test.kui', this.app)
+      .then(() => verifyComment())
+      .catch(Common.oops(this)))
 })