@lionweb/delta-protocol-test-cli 0.7.0-beta.13 → 0.7.0-beta.15

package/src/cli-client.ts

@@ -19,36 +19,51 @@
 
 import { argv, exit } from "process"
 import { Concept } from "@lionweb/core"
-import { LionWebClient, wsLocalhostUrl } from "@lionweb/delta-protocol-impl"
+import {
+    Command,
+    createWebSocketClient,
+    Event,
+    LionWebClient,
+    QueryMessage,
+    wsLocalhostUrl
+} from "@lionweb/delta-protocol-impl"
+import { semanticConsoleLogger, semanticLogItemStorer } from "@lionweb/delta-protocol-impl/dist/semantic-logging.js"
+import { clientInfo, genericError } from "@lionweb/delta-protocol-impl/dist/utils/ansi.js"
+import { combine } from "@lionweb/delta-protocol-impl/dist/utils/procedure.js"
+import { LowLevelClientLogItem } from "@lionweb/delta-protocol-impl/dist/web-socket/client-log-types.js"
+import { writeJsonAsFile } from "@lionweb/utilities"
 import { runAsApp, tryParseInteger } from "./common.js"
 import { recognizedTasks, taskExecutor } from "./tasks.js"
-import { clientInfo, withStylesApplied } from "@lionweb/delta-protocol-impl/dist/utils/ansi.js"
-import { combine } from "@lionweb/delta-protocol-impl/dist/utils/procedure.js"
-import { ShapesBase } from "./gen/Shapes.g.js"
 import { TestLanguageBase } from "./gen/TestLanguage.g.js"
-import { semanticConsoleLogger, semanticLogItemStorer } from "@lionweb/delta-protocol-impl/dist/semantic-logging.js"
 
-const shapesLanguageBase = ShapesBase.INSTANCE
 const testLanguageBase = TestLanguageBase.INSTANCE
-const languageBases = [shapesLanguageBase, testLanguageBase]
+const languageBases = [testLanguageBase]
 
 const boldRedIf = (apply: boolean, text: string) =>
-    apply ? withStylesApplied("bold", "red")(text) : text
+    apply ? genericError(text) : text
 
 const partitionConcepts: Record<string, Concept> = Object.fromEntries(
-    [testLanguageBase.DataTypeTestConcept, shapesLanguageBase.Geometry, testLanguageBase.LinkTestConcept]
+    [testLanguageBase.DataTypeTestConcept, testLanguageBase.LinkTestConcept]
         .map((concept) => [concept.name, concept])
 )
 
-if (argv.length < 5) {  // $ node dist/cli-client.js <port> <clientID> <partitionConcept> [tasks]
+// $ node dist/cli-client.js <port> <clientID> <partitionConcept> [tasks] [--${protocolLogOptionPrefix}=<path>]
+
+const protocolLogOptionPrefix = "--protocol-log="
+const protocolLogPathIndex = argv.findIndex((argument) => argument.startsWith(protocolLogOptionPrefix))
+// arguments without "node" (index=0), "dist/cli-client.js" (index=1), and `${protocolLogOptionPrefix}=<path>` (optional)
+const trueArguments = argv.filter((_, index) => !(index === 0 || index === 1 || index === protocolLogPathIndex))
+
+if (trueArguments.length < 3) {
     console.log(
 `A Node.js-based app that implements a LionWeb delta protocol client.
 
-Parameters (${boldRedIf(true, "bold red")} are missing):
-  - ${boldRedIf(argv.length < 3, `<port>: the port of the WebSocket where the LionWeb delta protocol repository is running on localhost`)}
-  - ${boldRedIf(argv.length < 4, `<clientID>: the ID that the client identifies itself with at the repository`)}
-  - ${boldRedIf(argv.length < 5, `<partitionConcept>: the name of a partition concept that gets instantiated as the model's primary partition — one of: ${Object.keys(partitionConcepts).join(", ")}`)}
-  - ${boldRedIf(argv.length < 6, `[tasks]: a comma-separated list of tasks — one of ${Object.keys(recognizedTasks).sort().join(", ")}`)}
+Parameters (${genericError("bold red")} are missing):
+  - ${boldRedIf(trueArguments.length < 1, `<port>: the port of the WebSocket where the LionWeb delta protocol repository is running on localhost`)}
+  - ${boldRedIf(trueArguments.length < 2, `<clientID>: the ID that the client identifies itself with at the repository`)}
+  - ${boldRedIf(trueArguments.length < 3, `<partitionConcept>: the name of a partition concept that gets instantiated as the model's primary partition — one of: ${Object.keys(partitionConcepts).join(", ")}`)}
+  - ${boldRedIf(trueArguments.length < 4, `[tasks]: a comma-separated list of tasks — one of ${Object.keys(recognizedTasks).sort().join(", ")}`)}
+  - ${boldRedIf(protocolLogPathIndex === -1, `${protocolLogOptionPrefix}=<path>: option to configure that the client logs all messages exchanged with the repository to a file with the given path`)}
 
     ASSUMPTION: the initial (states of the models) on client(s) and repository are identical!
 `)
@@ -59,22 +74,40 @@ const port = tryParseInteger(argv[2])
 const clientId = argv[3]
 const partitionConcept = argv[4]
 if (!(partitionConcept in partitionConcepts)) {
-    console.log(boldRedIf(true, `unknown partition concept specified: ${partitionConcept} — must be one of: ${Object.keys(partitionConcepts).join(", ")}`))
+    console.error(genericError(`unknown partition concept specified: ${partitionConcept} — must be one of: ${Object.keys(partitionConcepts).join(", ")}`))
     exit(2)
 }
-const tasks = argv[5]?.split(",") ?? []  // unknown tasks will be ignored
+const tasks = argv[5]?.split(",") ?? []
 console.log(clientInfo(`tasks provided: ${tasks.length === 0 ? "none" : tasks.join(", ")}`))
+const infoUnrecognizedTasks = tasks
+    .map((task, index) => task in recognizedTasks ? undefined : [task, index] as [string, number])
+    .filter((taskInfoOrUndefined) => taskInfoOrUndefined !== undefined)
+if (infoUnrecognizedTasks.length > 0) {
+    console.error(genericError(`unrecognized tasks encountered:`))
+    infoUnrecognizedTasks.forEach(([task, index]) => {
+            console.error(genericError(`\t${task} (#${index + 1})`))
+        })
+    exit(2)
+}
 
 await runAsApp(async () => {
     const url = wsLocalhostUrl(port)
 
     const [storingLogger, semanticLogItems] = semanticLogItemStorer()
+    const logItems: LowLevelClientLogItem<unknown, unknown>[] = []
 
     const lionWebClient = await LionWebClient.create({
         clientId,
         url,
         languageBases,
-        semanticLogger: combine(semanticConsoleLogger, storingLogger)
+        semanticLogger: combine(semanticConsoleLogger, storingLogger),
+        lowLevelClientInstantiator: async (lowLevelClientParameters) =>
+            await createWebSocketClient<(Event | QueryMessage), (Command | QueryMessage)>(
+                lowLevelClientParameters,
+                (logItem) => {
+                    logItems.push(logItem)
+                }
+            )
     })
 
     console.log(clientInfo(`LionWeb delta protocol client (with ID=${clientId}) connecting to repository on ${url} - press Ctrl+C to terminate`))
@@ -91,6 +124,10 @@ await runAsApp(async () => {
         await executeTask(task, queryId())
     }
 
+    if (protocolLogPathIndex > -1) {
+        writeJsonAsFile(argv[protocolLogPathIndex].substring(protocolLogOptionPrefix.length), logItems)
+    }
+
     return () => {
         return lionWebClient.disconnect()
     }

package/src/tasks.ts

@@ -18,35 +18,28 @@
 import { INodeBase } from "@lionweb/class-core"
 import { LionWebClient } from "@lionweb/delta-protocol-impl"
 import { LionWebId } from "@lionweb/json"
-import { ClientAppliedEvent, ISemanticLogItem } from "@lionweb/delta-protocol-impl/dist/semantic-logging.js"
-import { withStylesApplied } from "@lionweb/delta-protocol-impl/dist/utils/ansi.js"
+import { lastOfArray } from "@lionweb/ts-utils"
+import { ClientReceivedMessage, ISemanticLogItem } from "@lionweb/delta-protocol-impl/dist/semantic-logging.js"
+import { clientInfo, genericWarning } from "@lionweb/delta-protocol-impl/dist/utils/ansi.js"
 import { waitUntil } from "@lionweb/delta-protocol-impl/dist/utils/async.js"
-import { Documentation, Geometry, ShapesBase } from "./gen/Shapes.g.js"
-import {
-    DataTypeTestConcept,
-    LinkTestConcept,
-    TestAnnotation,
-    TestLanguageBase
-} from "./gen/TestLanguage.g.js"
-
-
-const lastOf = <T>(ts: T[]): T => {
-    if (ts.length === 0) {
-        throw new Error(`empty array doesn't have a last element`)
-    }
-    return ts[ts.length - 1]
-}
+import { DataTypeTestConcept, LinkTestConcept, TestAnnotation, TestLanguageBase } from "./gen/TestLanguage.g.js"
 
 
+/**
+ * **DEV note**: run
+ *
+ *  $ node src/code-reading/tasks-from-csharp.js
+ *
+  * inside the build package to generate the contents of the following object.
+ */
 export const recognizedTasks: Record<string, boolean> = {
     "SignOn": true,
     "SignOff": true,
     "Wait": true,
-    "AddDocs": true,
-    "SetDocsText": true,
     "AddStringValue_0_1": true,
     "SetStringValue_0_1": true,
     "DeleteStringValue_0_1": true,
+    "AddName_Containment_0_1": true,
     "AddAnnotation": true,
     "AddAnnotations": true,
     "AddAnnotation_to_Containment_0_1": true,
@@ -63,6 +56,7 @@ export const recognizedTasks: Record<string, boolean> = {
     "AddContainment_0_1_Containment_0_1": true,
     "AddContainment_1_Containment_0_1": true,
     "AddContainment_0_n": true,
+    "AddContainment_0_n_Containment_0_n": true,
     "AddContainment_1_n": true,
     "MoveAndReplaceChildFromOtherContainment_Single": true,
     "MoveAndReplaceChildFromOtherContainmentInSameParent_Single": true,
@@ -71,24 +65,24 @@ export const recognizedTasks: Record<string, boolean> = {
     "MoveChildFromOtherContainment_Single": true,
     "MoveChildFromOtherContainment_Multiple": true,
     "MoveChildFromOtherContainmentInSameParent_Single": true,
-    "MoveChildFromOtherContainmentInSameParent_Multiple": true,
-    "AddPartition": true
+    "AddPartition": true,
+    "MoveChildFromOtherContainmentInSameParent_Multiple": true
 }
 
 
-const shapesLanguageBase = ShapesBase.INSTANCE
 const testLanguageBase = TestLanguageBase.INSTANCE
 
 
 export const taskExecutor = (lionWebClient: LionWebClient, partition: INodeBase, semanticLogItems: ISemanticLogItem[]) => {
-    const numberOfAppliedEvents = () =>
-        semanticLogItems.filter((item) => item instanceof ClientAppliedEvent).length
 
-    const waitForReceived = async (delta: number) => {
-        const expectedNumber = numberOfAppliedEvents() + delta  // (precompute here)
-        return waitUntil(10, () => numberOfAppliedEvents() >= expectedNumber)
+    const numberOfReceivedMessages = () =>
+        semanticLogItems.filter((item) => item instanceof ClientReceivedMessage).length
+
+    const waitForReceivedMessages = async (numberOfMessagesToReceive: number) => {
+        const expectedNumber = numberOfReceivedMessages() + numberOfMessagesToReceive  // (precompute here)
+        return waitUntil(10, () => numberOfReceivedMessages() >= expectedNumber)
             .then(() => {
-                console.log(withStylesApplied("italic")(`(client applied (the deltas from) a total of ${numberOfAppliedEvents()} events so far)`))
+                console.log(clientInfo(`(client "${lionWebClient.clientId}" received a total of ${numberOfReceivedMessages()} messages so far)`))
             })
     }
 
@@ -100,116 +94,126 @@ export const taskExecutor = (lionWebClient: LionWebClient, partition: INodeBase,
             ? partition as LinkTestConcept
             : lionWebClient.createNode(testLanguageBase.LinkTestConcept, id) as LinkTestConcept
 
-    return async (task: string, queryId: string) => {
+    return async (task: keyof typeof recognizedTasks, queryId: string) => {
+        console.log(clientInfo(`client "${lionWebClient.clientId}" is executing task "${task}"`))
         switch (task) {
             case "SignOn":
-                return await lionWebClient.signOn(queryId)
+                return await lionWebClient.signOn(queryId, "myRepo")
             case "SignOff":
                 return await lionWebClient.signOff(queryId)
             case "Wait": {
-                return waitForReceived(1)
-            }
-            case "AddDocs": {
-                (partition as Geometry).documentation = lionWebClient.createNode(shapesLanguageBase.Documentation, "documentation") as Documentation
-                return waitForReceived(1)
-            }
-            case "SetDocsText": {
-                (partition as Geometry).documentation!.text = "hello there"
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             }
             case "AddStringValue_0_1":
                 (partition as DataTypeTestConcept).stringValue_0_1 = "new property"
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "SetStringValue_0_1":
                 (partition as DataTypeTestConcept).stringValue_0_1 = "changed property"
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "DeleteStringValue_0_1":
                 (partition as DataTypeTestConcept).stringValue_0_1 = undefined
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
+            case "AddName_Containment_0_1":
+                linkTestConcept().containment_0_1!.name = "my name"
+                return waitForReceivedMessages(1)
             case "AddAnnotation":
                 linkTestConcept().addAnnotation(annotation("annotation"))
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "AddAnnotations":
                 linkTestConcept().addAnnotation(annotation("annotation0"));   // (keep ;!)
                 linkTestConcept().addAnnotation(annotation("annotation1"))
-                return waitForReceived(2)
+                return waitForReceivedMessages(2)
             case "AddAnnotation_to_Containment_0_1":
                 linkTestConcept().containment_0_1!.addAnnotation(annotation("annotation"))
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "DeleteAnnotation":
                 linkTestConcept().removeAnnotation(linkTestConcept().annotations[0])
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "MoveAnnotationInSameParent":
-                linkTestConcept().insertAnnotationAtIndex(lastOf(linkTestConcept().annotations), 0)
-                return waitForReceived(1)
+                linkTestConcept().insertAnnotationAtIndex(lastOfArray(linkTestConcept().annotations), 0)
+                return waitForReceivedMessages(1)
             case "MoveAnnotationFromOtherParent":
                 linkTestConcept().addAnnotation(linkTestConcept().containment_0_1!.annotations[0])
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "AddReference_0_1_to_Containment_0_1":
                 linkTestConcept().reference_0_1 = linkTestConcept().containment_0_1
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "AddReference_0_1_to_Containment_1":
                 linkTestConcept().reference_0_1 = linkTestConcept().containment_1
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "DeleteReference_0_1":
                 linkTestConcept().reference_0_1 = undefined
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "AddContainment_0_1":
                 linkTestConcept().containment_0_1 = linkTestConcept("containment_0_1")
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "AddContainment_1":
                 linkTestConcept().containment_1 = linkTestConcept("containment_1")
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "ReplaceContainment_0_1":
-                linkTestConcept().containment_0_1 = linkTestConcept("substitute")
-                return waitForReceived(1)
+                linkTestConcept().replaceContainment_0_1With(linkTestConcept("substitute"))
+                return waitForReceivedMessages(1)
             case "DeleteContainment_0_1":
                 linkTestConcept().containment_0_1 = undefined
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "AddContainment_0_1_Containment_0_1":
                 linkTestConcept().containment_0_1!.containment_0_1 = linkTestConcept("containment_0_1_containment_0_1")
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "AddContainment_1_Containment_0_1":
                 linkTestConcept().containment_1.containment_0_1 = linkTestConcept("containment_1_containment_0_1")
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "AddContainment_0_n":
                 linkTestConcept().addContainment_0_n(linkTestConcept("containment_0_n_child0"));   // (keep ;!)
                 linkTestConcept().addContainment_0_n(linkTestConcept("containment_0_n_child1"))
-                return waitForReceived(2)
+                return waitForReceivedMessages(2)
+            case "AddContainment_0_n_Containment_0_n": {
+                const outerChild = linkTestConcept("containment_0_n_child0")
+                outerChild.addContainment_0_n(linkTestConcept("containment_0_n_containment_0_n_child0"))
+                linkTestConcept().addContainment_0_n(outerChild)
+                return waitForReceivedMessages(1)
+            }
             case "AddContainment_1_n":
                 linkTestConcept().addContainment_1_n(linkTestConcept("containment_1_n_child0"));   // (keep ;!)
                 linkTestConcept().addContainment_1_n(linkTestConcept("containment_1_n_child1"))
-                return waitForReceived(2)
+                return waitForReceivedMessages(2)
             case "MoveAndReplaceChildFromOtherContainment_Single":
                 linkTestConcept().containment_1.replaceContainment_0_1With(linkTestConcept().containment_0_1!.containment_0_1!)
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "MoveAndReplaceChildFromOtherContainmentInSameParent_Single":
                 linkTestConcept().replaceContainment_1With(linkTestConcept().containment_0_1!)
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "MoveAndReplaceChildFromOtherContainment_Multiple":
-                linkTestConcept().replaceContainment_1_nAtIndex(lastOf(linkTestConcept().containment_0_n), linkTestConcept().containment_1_n.length - 1)
-                return waitForReceived(1)
+                if (linkTestConcept().containment_1_n.length === 0) {
+                    throw new Error(`can't replace an item of an array with no items`)
+                }
+                linkTestConcept().replaceContainment_1_nAtIndex(
+                    lastOfArray(lastOfArray(linkTestConcept().containment_0_n).containment_0_n),
+                    linkTestConcept().containment_1_n.length - 1
+                )
+                return waitForReceivedMessages(1)
             case "MoveChildInSameContainment":
-                linkTestConcept().addContainment_0_nAtIndex(lastOf(linkTestConcept().containment_0_n), 0)
-                return waitForReceived(1)
+                linkTestConcept().addContainment_0_nAtIndex(lastOfArray(linkTestConcept().containment_0_n), 0)
+                // Note: this is effectively a move rather than an insert — hence the name of the task.
+                return waitForReceivedMessages(1)
             case "MoveChildFromOtherContainment_Single":
                 linkTestConcept().containment_1 = linkTestConcept().containment_0_1!.containment_0_1!
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "MoveChildFromOtherContainment_Multiple":
-                linkTestConcept().addContainment_1_nAtIndex(lastOf(linkTestConcept().containment_0_n).containment_0_n[0], 1)
-                return waitForReceived(1)
+                linkTestConcept().addContainment_1_nAtIndex(lastOfArray(linkTestConcept().containment_0_n).containment_0_n[0], 1)
+                return waitForReceivedMessages(1)
             case "MoveChildFromOtherContainmentInSameParent_Single":
                 linkTestConcept().containment_1 = linkTestConcept().containment_0_1!
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
             case "MoveChildFromOtherContainmentInSameParent_Multiple":
-                linkTestConcept().addContainment_1_nAtIndex(lastOf(linkTestConcept().containment_0_n), 1)
-                return waitForReceived(1)
+                linkTestConcept().addContainment_1_nAtIndex(lastOfArray(linkTestConcept().containment_0_n), 1)
+                return waitForReceivedMessages(1)
             case "AddPartition":
                 lionWebClient.addPartition(linkTestConcept("partition"))
-                return waitForReceived(1)
+                return waitForReceivedMessages(1)
 
             default: {
-                console.log(withStylesApplied("italic", "red")(`task "${task}" is unknown => ignored`))
+                // (shouldn't happen because of upfront validation of tasks)
+                console.log(genericWarning(`task "${task}" is unknown => ignored`))
                 return Promise.resolve()
             }
         }