Refactor code structure for improved readability and maintainability

.github/copilot-instructions.md

@@ -0,0 +1,6 @@
+<!-- mermaid-ai-skills:start -->
+## Mermaid Diagrams
+
+When the user asks to create, edit, or visualize a diagram, follow the
+instructions in `.github/instructions/mermaid.instructions.md`.
+<!-- mermaid-ai-skills:end -->

.github/instructions/mermaid.instructions.md

@@ -0,0 +1,85 @@
+---
+applyTo: "**"
+---
+# Mermaid AI Skills
+
+When the user asks to create, edit, or visualize any diagram, use the Mermaid
+VS Code extension tools and commands described below.
+
+## Workflow
+
+1. Determine the diagram type and generate Mermaid syntax.
+2. Write the diagram to a `.mmd` file in the project.
+3. Validate syntax: correct first-line keyword, arrow types, balanced brackets.
+4. Preview via the Mermaid extension — open the `.mmd` file (auto-preview) or run
+   **MermaidChart: Preview Diagram** (`mermaidChart.preview`).
+
+## LM Tools — call these for every diagram interaction
+
+- `mermaid-diagram-validator` — validate Mermaid syntax before presenting any diagram
+- `mermaid-diagram-preview` — render a live preview inside VS Code after generating
+- `get-syntax-docs-mermaid` — fetch correct syntax docs for any diagram type
+
+## VS Code Commands
+
+Invoke via Command Palette or the VS Code command API (GitHub Copilot in VS Code only).
+Do not invent command IDs. Prefer writing/editing `.mmd` files when a command is not needed.
+
+### Diagram editing & preview
+- **Preview** (`mermaidChart.preview`) — preview the active Mermaid editor (`.mmd` / `.mermaid` must be open).
+- **Create Diagram** (`mermaidChart.createMermaidFile`) — creates a demo flowchart and opens preview side by side.
+- **Repair Diagram** (`mermaidChart.repairDiagram`) — Mermaid AI repair for the active diagram; uses Mermaid AI credits — tell the user before running.
+- **Improve Diagram** (`mermaidChart.improveDiagram`) — uses Copilot / LM API; suggests layout + styling variants for the active diagram.
+
+### Generate diagrams (GitHub Copilot required)
+- **Generate Diagram from Code** (`mermaidChart.generateDiagramFromCode`)
+- **Generate Cloud Diagram** (`mermaidChart.generateCloudDiagram`)
+- **Generate ER Diagram** (`mermaidChart.generateERDiagram`)
+- **Generate Docker Diagram** (`mermaidChart.generateDockerDiagram`)
+- **Open AI Chat** (`mermaidChart.openCopilotChat`)
+
+### Mermaid Chart cloud
+- **Login** (`mermaidChart.login`) / **Logout** (`mermaidChart.logout`)
+- **Connect Diagram** (`mermaidChart.connectDiagramToMermaidChart`) — link a local diagram to Mermaid Chart.
+- **Sync Diagram** (`mermaidChart.syncDiagramWithMermaid`) — only for diagrams already connected (frontmatter has `id:`). Example:
+  ```yaml
+  ---
+  id: cbd9e9ba-a2cb-47c5-a98e-8c28a753428d
+  ---
+  ```
+
+### Review Mermaid Sync
+For diagrams updated by the Mermaid Chart GitHub Sync app (or pre-commit regenerate):
+- **Review Mermaid Sync** (`mermaidChart.reviewAppCommits`) — start / open the review flow.
+- **Regenerate with Mermaid AI** (`mermaidChart.regenerateDiagramWithMermaidAI`) — regenerate from source references.
+Do not manually rewrite diagrams managed by this workflow. Accept/reject/diff UI actions stay in the extension UI.
+
+### Install / update this pack
+- **MermaidChart: Install AI Skills…** (`mermaidChart.installAiSkills`)
+
+## @mermaid-chart slash commands
+
+| Command | Purpose |
+|---|---|
+| `/generate_diagram_from_code` | General diagram from any source file |
+| `/generate_execution_sequence` | Sequence diagram from code flow |
+| `/generate_er_diagram` | ER diagram from schema / models |
+| `/generate_cloud_architecture_diagram` | Cloud / CI-CD architecture |
+| `/generate_docker_diagram` | Architecture from Dockerfiles |
+| `/generate_c4_topdown_architecture` | C4 top-down architecture |
+| `/analyze_code_ownership` | Code ownership diagram |
+| `/generate_dependency_diagram` | Dependency / security visualisation |
+
+## Rules
+
+1. Always call `mermaid-diagram-validator` before showing any diagram.
+2. Always call `mermaid-diagram-preview` after generating a diagram.
+3. Use `get-syntax-docs-mermaid` before generating an unfamiliar diagram type.
+4. Prefer `@mermaid-chart` slash commands for complex generation.
+5. Write diagrams to `.mmd` files; never return unvalidated Mermaid syntax.
+6. Warn the user before Repair (Mermaid AI credits).
+7. Cooperate with the Sync workflow — do not manually regenerate managed diagrams.
+
+## Docs
+
+More commands and features: https://marketplace.visualstudio.com/items?itemName=MermaidChart.vscode-mermaid-chart

.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "arcanis.vscode-zipfs"
+  ]
+}

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+  "search.exclude": {
+    "**/.yarn": true,
+    "**/.pnp.*": true
+  },
+  "typescript.tsdk": ".yarn/sdks/typescript/lib",
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "typescript.suggest.autoImports": true,
+  "javascript.suggest.autoImports": true,
+  "js/ts.experimental.useTsgo": false,
+  "js/ts.tsdk.path": ".yarn/sdks/typescript/lib"
+}

.yarn/sdks/integrations.yml

@@ -0,0 +1,5 @@
+# This file is automatically generated by @yarnpkg/sdks.
+# Manual changes might be lost!
+
+integrations:
+  - vscode

.yarn/sdks/typescript/bin/tsc

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+const {existsSync} = require(`fs`);
+const {createRequire, register} = require(`module`);
+const {resolve} = require(`path`);
+const {pathToFileURL} = require(`url`);
+
+const relPnpApiPath = "../../../../.pnp.cjs";
+
+const absPnpApiPath = resolve(__dirname, relPnpApiPath);
+const absUserWrapperPath = resolve(__dirname, `./sdk.user.cjs`);
+const absRequire = createRequire(absPnpApiPath);
+
+const absPnpLoaderPath = resolve(absPnpApiPath, `../.pnp.loader.mjs`);
+const isPnpLoaderEnabled = existsSync(absPnpLoaderPath);
+
+if (existsSync(absPnpApiPath)) {
+  if (!process.versions.pnp) {
+    // Setup the environment to be able to require typescript/bin/tsc
+    require(absPnpApiPath).setup();
+    if (isPnpLoaderEnabled && register) {
+      register(pathToFileURL(absPnpLoaderPath));
+    }
+  }
+}
+
+const wrapWithUserWrapper = existsSync(absUserWrapperPath)
+  ? exports => absRequire(absUserWrapperPath)(exports)
+  : exports => exports;
+
+// Defer to the real typescript/bin/tsc your application uses
+module.exports = wrapWithUserWrapper(absRequire(`typescript/bin/tsc`));

.yarn/sdks/typescript/bin/tsserver

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+const {existsSync} = require(`fs`);
+const {createRequire, register} = require(`module`);
+const {resolve} = require(`path`);
+const {pathToFileURL} = require(`url`);
+
+const relPnpApiPath = "../../../../.pnp.cjs";
+
+const absPnpApiPath = resolve(__dirname, relPnpApiPath);
+const absUserWrapperPath = resolve(__dirname, `./sdk.user.cjs`);
+const absRequire = createRequire(absPnpApiPath);
+
+const absPnpLoaderPath = resolve(absPnpApiPath, `../.pnp.loader.mjs`);
+const isPnpLoaderEnabled = existsSync(absPnpLoaderPath);
+
+if (existsSync(absPnpApiPath)) {
+  if (!process.versions.pnp) {
+    // Setup the environment to be able to require typescript/bin/tsserver
+    require(absPnpApiPath).setup();
+    if (isPnpLoaderEnabled && register) {
+      register(pathToFileURL(absPnpLoaderPath));
+    }
+  }
+}
+
+const wrapWithUserWrapper = existsSync(absUserWrapperPath)
+  ? exports => absRequire(absUserWrapperPath)(exports)
+  : exports => exports;
+
+// Defer to the real typescript/bin/tsserver your application uses
+module.exports = wrapWithUserWrapper(absRequire(`typescript/bin/tsserver`));

.yarn/sdks/typescript/lib/tsc.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+const {existsSync} = require(`fs`);
+const {createRequire, register} = require(`module`);
+const {resolve} = require(`path`);
+const {pathToFileURL} = require(`url`);
+
+const relPnpApiPath = "../../../../.pnp.cjs";
+
+const absPnpApiPath = resolve(__dirname, relPnpApiPath);
+const absUserWrapperPath = resolve(__dirname, `./sdk.user.cjs`);
+const absRequire = createRequire(absPnpApiPath);
+
+const absPnpLoaderPath = resolve(absPnpApiPath, `../.pnp.loader.mjs`);
+const isPnpLoaderEnabled = existsSync(absPnpLoaderPath);
+
+if (existsSync(absPnpApiPath)) {
+  if (!process.versions.pnp) {
+    // Setup the environment to be able to require typescript/lib/tsc.js
+    require(absPnpApiPath).setup();
+    if (isPnpLoaderEnabled && register) {
+      register(pathToFileURL(absPnpLoaderPath));
+    }
+  }
+}
+
+const wrapWithUserWrapper = existsSync(absUserWrapperPath)
+  ? exports => absRequire(absUserWrapperPath)(exports)
+  : exports => exports;
+
+// Defer to the real typescript/lib/tsc.js your application uses
+module.exports = wrapWithUserWrapper(absRequire(`typescript/lib/tsc.js`));

.yarn/sdks/typescript/lib/tsserver.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+const {existsSync} = require(`fs`);
+const {createRequire, register} = require(`module`);
+const {resolve} = require(`path`);
+const {pathToFileURL} = require(`url`);
+
+const relPnpApiPath = "../../../../.pnp.cjs";
+
+const absPnpApiPath = resolve(__dirname, relPnpApiPath);
+const absUserWrapperPath = resolve(__dirname, `./sdk.user.cjs`);
+const absRequire = createRequire(absPnpApiPath);
+
+const absPnpLoaderPath = resolve(absPnpApiPath, `../.pnp.loader.mjs`);
+const isPnpLoaderEnabled = existsSync(absPnpLoaderPath);
+
+if (existsSync(absPnpApiPath)) {
+  if (!process.versions.pnp) {
+    // Setup the environment to be able to require typescript/lib/tsserver.js
+    require(absPnpApiPath).setup();
+    if (isPnpLoaderEnabled && register) {
+      register(pathToFileURL(absPnpLoaderPath));
+    }
+  }
+}
+
+const wrapWithUserWrapper = existsSync(absUserWrapperPath)
+  ? exports => absRequire(absUserWrapperPath)(exports)
+  : exports => exports;
+
+const moduleWrapper = exports => {
+  return wrapWithUserWrapper(moduleWrapperFn(exports));
+};
+
+const moduleWrapperFn = tsserver => {
+  if (!process.versions.pnp) {
+    return tsserver;
+  }
+
+  const {isAbsolute} = require(`path`);
+  const pnpApi = require(`pnpapi`);
+
+  const isVirtual = str => str.match(/\/(\$\$virtual|__virtual__)\//);
+  const isPortal = str => str.startsWith("portal:/");
+  const normalize = str => str.replace(/\\/g, `/`).replace(/^\/?/, `/`);
+
+  const dependencyTreeRoots = new Set(pnpApi.getDependencyTreeRoots().map(locator => {
+    return `${locator.name}@${locator.reference}`;
+  }));
+
+  // VSCode sends the zip paths to TS using the "zip://" prefix, that TS
+  // doesn't understand. This layer makes sure to remove the protocol
+  // before forwarding it to TS, and to add it back on all returned paths.
+
+  function toEditorPath(str) {
+    // We add the `zip:` prefix to both `.zip/` paths and virtual paths
+    if (isAbsolute(str) && !str.match(/^\^?(zip:|\/zip\/)/) && (str.match(/\.zip\//) || isVirtual(str))) {
+      // We also take the opportunity to turn virtual paths into physical ones;
+      // this makes it much easier to work with workspaces that list peer
+      // dependencies, since otherwise Ctrl+Click would bring us to the virtual
+      // file instances instead of the real ones.
+      //
+      // We only do this to modules owned by the the dependency tree roots.
+      // This avoids breaking the resolution when jumping inside a vendor
+      // with peer dep (otherwise jumping into react-dom would show resolution
+      // errors on react).
+      //
+      const resolved = isVirtual(str) ? pnpApi.resolveVirtual(str) : str;
+      if (resolved) {
+        const locator = pnpApi.findPackageLocator(resolved);
+        if (locator && (dependencyTreeRoots.has(`${locator.name}@${locator.reference}`) || isPortal(locator.reference))) {
+          str = resolved;
+        }
+      }
+
+      str = normalize(str);
+
+      if (str.match(/\.zip\//)) {
+        switch (hostInfo) {
+          // Absolute VSCode `Uri.fsPath`s need to start with a slash.
+          // VSCode only adds it automatically for supported schemes,
+          // so we have to do it manually for the `zip` scheme.
+          // The path needs to start with a caret otherwise VSCode doesn't handle the protocol
+          //
+          // Ref: https://github.com/microsoft/vscode/issues/105014#issuecomment-686760910
+          //
+          // 2021-10-08: VSCode changed the format in 1.61.
+          // Before | ^zip:/c:/foo/bar.zip/package.json
+          // After  | ^/zip//c:/foo/bar.zip/package.json
+          //
+          // 2022-04-06: VSCode changed the format in 1.66.
+          // Before | ^/zip//c:/foo/bar.zip/package.json
+          // After  | ^/zip/c:/foo/bar.zip/package.json
+          //
+          // 2022-05-06: VSCode changed the format in 1.68
+          // Before | ^/zip/c:/foo/bar.zip/package.json
+          // After  | ^/zip//c:/foo/bar.zip/package.json
+          //
+          case `vscode <1.61`: {
+            str = `^zip:${str}`;
+          } break;
+
+          case `vscode <1.66`: {
+            str = `^/zip/${str}`;
+          } break;
+
+          case `vscode <1.68`: {
+            str = `^/zip${str}`;
+          } break;
+
+          case `vscode`: {
+            str = `^/zip/${str}`;
+          } break;
+
+          // To make "go to definition" work,
+          // We have to resolve the actual file system path from virtual path
+          // and convert scheme to supported by [vim-rzip](https://github.com/lbrayner/vim-rzip)
+          case `coc-nvim`: {
+            str = normalize(resolved).replace(/\.zip\//, `.zip::`);
+            str = resolve(`zipfile:${str}`);
+          } break;
+
+          // Support neovim native LSP and [typescript-language-server](https://github.com/theia-ide/typescript-language-server)
+          // We have to resolve the actual file system path from virtual path,
+          // everything else is up to neovim
+          case `neovim`: {
+            str = normalize(resolved).replace(/\.zip\//, `.zip::`);
+            str = `zipfile://${str}`;
+          } break;
+
+          default: {
+            str = `zip:${str}`;
+          } break;
+        }
+      } else {
+        str = str.replace(/^\/?/, process.platform === `win32` ? `` : `/`);
+      }
+    }
+
+    return str;
+  }
+
+  function fromEditorPath(str) {
+    switch (hostInfo) {
+      case `coc-nvim`: {
+        str = str.replace(/\.zip::/, `.zip/`);
+        // The path for coc-nvim is in format of /<pwd>/zipfile:/<pwd>/.yarn/...
+        // So in order to convert it back, we use .* to match all the thing
+        // before `zipfile:`
+        return process.platform === `win32`
+          ? str.replace(/^.*zipfile:\//, ``)
+          : str.replace(/^.*zipfile:/, ``);
+      } break;
+
+      case `neovim`: {
+        str = str.replace(/\.zip::/, `.zip/`);
+        // The path for neovim is in format of zipfile:///<pwd>/.yarn/...
+        return str.replace(/^zipfile:\/\//, ``);
+      } break;
+
+      case `vscode`:
+      default: {
+        return str.replace(/^\^?(zip:|\/zip(\/ts-nul-authority)?)\/+/, process.platform === `win32` ? `` : `/`)
+      } break;
+    }
+  }
+
+  // Force enable 'allowLocalPluginLoads'
+  // TypeScript tries to resolve plugins using a path relative to itself
+  // which doesn't work when using the global cache
+  // https://github.com/microsoft/TypeScript/blob/1b57a0395e0bff191581c9606aab92832001de62/src/server/project.ts#L2238
+  // VSCode doesn't want to enable 'allowLocalPluginLoads' due to security concerns but
+  // TypeScript already does local loads and if this code is running the user trusts the workspace
+  // https://github.com/microsoft/vscode/issues/45856
+  const ConfiguredProject = tsserver.server.ConfiguredProject;
+  const {enablePluginsWithOptions: originalEnablePluginsWithOptions} = ConfiguredProject.prototype;
+  ConfiguredProject.prototype.enablePluginsWithOptions = function() {
+    this.projectService.allowLocalPluginLoads = true;
+    return originalEnablePluginsWithOptions.apply(this, arguments);
+  };
+
+  // And here is the point where we hijack the VSCode <-> TS communications
+  // by adding ourselves in the middle. We locate everything that looks
+  // like an absolute path of ours and normalize it.
+
+  const Session = tsserver.server.Session;
+  const {onMessage: originalOnMessage, send: originalSend} = Session.prototype;
+  let hostInfo = `unknown`;
+
+  Object.assign(Session.prototype, {
+    onMessage(/** @type {string | object} */ message) {
+      const isStringMessage = typeof message === 'string';
+      const parsedMessage = isStringMessage ? JSON.parse(message) : message;
+
+      if (
+        parsedMessage != null &&
+        typeof parsedMessage === `object` &&
+        parsedMessage.arguments &&
+        typeof parsedMessage.arguments.hostInfo === `string`
+      ) {
+        hostInfo = parsedMessage.arguments.hostInfo;
+        if (hostInfo === `vscode` && process.env.VSCODE_IPC_HOOK) {
+          const [, major, minor] = (process.env.VSCODE_IPC_HOOK.match(
+            // The RegExp from https://semver.org/ but without the caret at the start
+            /(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/
+          ) ?? []).map(Number)
+
+          if (major === 1) {
+            if (minor < 61) {
+              hostInfo += ` <1.61`;
+            } else if (minor < 66) {
+              hostInfo += ` <1.66`;
+            } else if (minor < 68) {
+              hostInfo += ` <1.68`;
+            }
+          }
+        }
+      }
+
+      const processedMessageJSON = JSON.stringify(parsedMessage, (key, value) => {
+        return typeof value === 'string' ? fromEditorPath(value) : value;
+      });
+
+      return originalOnMessage.call(
+        this,
+        isStringMessage ? processedMessageJSON : JSON.parse(processedMessageJSON)
+      );
+    },
+
+    send(/** @type {any} */ msg) {
+      return originalSend.call(this, JSON.parse(JSON.stringify(msg, (key, value) => {
+        return typeof value === `string` ? toEditorPath(value) : value;
+      })));
+    }
+  });
+
+  return tsserver;
+};
+
+const [major, minor] = absRequire(`typescript/package.json`).version.split(`.`, 2).map(value => parseInt(value, 10));
+// In TypeScript@>=5.5 the tsserver uses the public TypeScript API so that needs to be patched as well.
+// Ref https://github.com/microsoft/TypeScript/pull/55326
+if (major > 5 || (major === 5 && minor >= 5)) {
+  moduleWrapper(absRequire(`typescript`));
+}
+
+// Defer to the real typescript/lib/tsserver.js your application uses
+module.exports = moduleWrapper(absRequire(`typescript/lib/tsserver.js`));

.yarn/sdks/typescript/lib/tsserverlibrary.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+const {existsSync} = require(`fs`);
+const {createRequire, register} = require(`module`);
+const {resolve} = require(`path`);
+const {pathToFileURL} = require(`url`);
+
+const relPnpApiPath = "../../../../.pnp.cjs";
+
+const absPnpApiPath = resolve(__dirname, relPnpApiPath);
+const absUserWrapperPath = resolve(__dirname, `./sdk.user.cjs`);
+const absRequire = createRequire(absPnpApiPath);
+
+const absPnpLoaderPath = resolve(absPnpApiPath, `../.pnp.loader.mjs`);
+const isPnpLoaderEnabled = existsSync(absPnpLoaderPath);
+
+if (existsSync(absPnpApiPath)) {
+  if (!process.versions.pnp) {
+    // Setup the environment to be able to require typescript/lib/tsserverlibrary.js
+    require(absPnpApiPath).setup();
+    if (isPnpLoaderEnabled && register) {
+      register(pathToFileURL(absPnpLoaderPath));
+    }
+  }
+}
+
+const wrapWithUserWrapper = existsSync(absUserWrapperPath)
+  ? exports => absRequire(absUserWrapperPath)(exports)
+  : exports => exports;
+
+const moduleWrapper = exports => {
+  return wrapWithUserWrapper(moduleWrapperFn(exports));
+};
+
+const moduleWrapperFn = tsserver => {
+  if (!process.versions.pnp) {
+    return tsserver;
+  }
+
+  const {isAbsolute} = require(`path`);
+  const pnpApi = require(`pnpapi`);
+
+  const isVirtual = str => str.match(/\/(\$\$virtual|__virtual__)\//);
+  const isPortal = str => str.startsWith("portal:/");
+  const normalize = str => str.replace(/\\/g, `/`).replace(/^\/?/, `/`);
+
+  const dependencyTreeRoots = new Set(pnpApi.getDependencyTreeRoots().map(locator => {
+    return `${locator.name}@${locator.reference}`;
+  }));
+
+  // VSCode sends the zip paths to TS using the "zip://" prefix, that TS
+  // doesn't understand. This layer makes sure to remove the protocol
+  // before forwarding it to TS, and to add it back on all returned paths.
+
+  function toEditorPath(str) {
+    // We add the `zip:` prefix to both `.zip/` paths and virtual paths
+    if (isAbsolute(str) && !str.match(/^\^?(zip:|\/zip\/)/) && (str.match(/\.zip\//) || isVirtual(str))) {
+      // We also take the opportunity to turn virtual paths into physical ones;
+      // this makes it much easier to work with workspaces that list peer
+      // dependencies, since otherwise Ctrl+Click would bring us to the virtual
+      // file instances instead of the real ones.
+      //
+      // We only do this to modules owned by the the dependency tree roots.
+      // This avoids breaking the resolution when jumping inside a vendor
+      // with peer dep (otherwise jumping into react-dom would show resolution
+      // errors on react).
+      //
+      const resolved = isVirtual(str) ? pnpApi.resolveVirtual(str) : str;
+      if (resolved) {
+        const locator = pnpApi.findPackageLocator(resolved);
+        if (locator && (dependencyTreeRoots.has(`${locator.name}@${locator.reference}`) || isPortal(locator.reference))) {
+          str = resolved;
+        }
+      }
+
+      str = normalize(str);
+
+      if (str.match(/\.zip\//)) {
+        switch (hostInfo) {
+          // Absolute VSCode `Uri.fsPath`s need to start with a slash.
+          // VSCode only adds it automatically for supported schemes,
+          // so we have to do it manually for the `zip` scheme.
+          // The path needs to start with a caret otherwise VSCode doesn't handle the protocol
+          //
+          // Ref: https://github.com/microsoft/vscode/issues/105014#issuecomment-686760910
+          //
+          // 2021-10-08: VSCode changed the format in 1.61.
+          // Before | ^zip:/c:/foo/bar.zip/package.json
+          // After  | ^/zip//c:/foo/bar.zip/package.json
+          //
+          // 2022-04-06: VSCode changed the format in 1.66.
+          // Before | ^/zip//c:/foo/bar.zip/package.json
+          // After  | ^/zip/c:/foo/bar.zip/package.json
+          //
+          // 2022-05-06: VSCode changed the format in 1.68
+          // Before | ^/zip/c:/foo/bar.zip/package.json
+          // After  | ^/zip//c:/foo/bar.zip/package.json
+          //
+          case `vscode <1.61`: {
+            str = `^zip:${str}`;
+          } break;
+
+          case `vscode <1.66`: {
+            str = `^/zip/${str}`;
+          } break;
+
+          case `vscode <1.68`: {
+            str = `^/zip${str}`;
+          } break;
+
+          case `vscode`: {
+            str = `^/zip/${str}`;
+          } break;
+
+          // To make "go to definition" work,
+          // We have to resolve the actual file system path from virtual path
+          // and convert scheme to supported by [vim-rzip](https://github.com/lbrayner/vim-rzip)
+          case `coc-nvim`: {
+            str = normalize(resolved).replace(/\.zip\//, `.zip::`);
+            str = resolve(`zipfile:${str}`);
+          } break;
+
+          // Support neovim native LSP and [typescript-language-server](https://github.com/theia-ide/typescript-language-server)
+          // We have to resolve the actual file system path from virtual path,
+          // everything else is up to neovim
+          case `neovim`: {
+            str = normalize(resolved).replace(/\.zip\//, `.zip::`);
+            str = `zipfile://${str}`;
+          } break;
+
+          default: {
+            str = `zip:${str}`;
+          } break;
+        }
+      } else {
+        str = str.replace(/^\/?/, process.platform === `win32` ? `` : `/`);
+      }
+    }
+
+    return str;
+  }
+
+  function fromEditorPath(str) {
+    switch (hostInfo) {
+      case `coc-nvim`: {
+        str = str.replace(/\.zip::/, `.zip/`);
+        // The path for coc-nvim is in format of /<pwd>/zipfile:/<pwd>/.yarn/...
+        // So in order to convert it back, we use .* to match all the thing
+        // before `zipfile:`
+        return process.platform === `win32`
+          ? str.replace(/^.*zipfile:\//, ``)
+          : str.replace(/^.*zipfile:/, ``);
+      } break;
+
+      case `neovim`: {
+        str = str.replace(/\.zip::/, `.zip/`);
+        // The path for neovim is in format of zipfile:///<pwd>/.yarn/...
+        return str.replace(/^zipfile:\/\//, ``);
+      } break;
+
+      case `vscode`:
+      default: {
+        return str.replace(/^\^?(zip:|\/zip(\/ts-nul-authority)?)\/+/, process.platform === `win32` ? `` : `/`)
+      } break;
+    }
+  }
+
+  // Force enable 'allowLocalPluginLoads'
+  // TypeScript tries to resolve plugins using a path relative to itself
+  // which doesn't work when using the global cache
+  // https://github.com/microsoft/TypeScript/blob/1b57a0395e0bff191581c9606aab92832001de62/src/server/project.ts#L2238
+  // VSCode doesn't want to enable 'allowLocalPluginLoads' due to security concerns but
+  // TypeScript already does local loads and if this code is running the user trusts the workspace
+  // https://github.com/microsoft/vscode/issues/45856
+  const ConfiguredProject = tsserver.server.ConfiguredProject;
+  const {enablePluginsWithOptions: originalEnablePluginsWithOptions} = ConfiguredProject.prototype;
+  ConfiguredProject.prototype.enablePluginsWithOptions = function() {
+    this.projectService.allowLocalPluginLoads = true;
+    return originalEnablePluginsWithOptions.apply(this, arguments);
+  };
+
+  // And here is the point where we hijack the VSCode <-> TS communications
+  // by adding ourselves in the middle. We locate everything that looks
+  // like an absolute path of ours and normalize it.
+
+  const Session = tsserver.server.Session;
+  const {onMessage: originalOnMessage, send: originalSend} = Session.prototype;
+  let hostInfo = `unknown`;
+
+  Object.assign(Session.prototype, {
+    onMessage(/** @type {string | object} */ message) {
+      const isStringMessage = typeof message === 'string';
+      const parsedMessage = isStringMessage ? JSON.parse(message) : message;
+
+      if (
+        parsedMessage != null &&
+        typeof parsedMessage === `object` &&
+        parsedMessage.arguments &&
+        typeof parsedMessage.arguments.hostInfo === `string`
+      ) {
+        hostInfo = parsedMessage.arguments.hostInfo;
+        if (hostInfo === `vscode` && process.env.VSCODE_IPC_HOOK) {
+          const [, major, minor] = (process.env.VSCODE_IPC_HOOK.match(
+            // The RegExp from https://semver.org/ but without the caret at the start
+            /(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/
+          ) ?? []).map(Number)
+
+          if (major === 1) {
+            if (minor < 61) {
+              hostInfo += ` <1.61`;
+            } else if (minor < 66) {
+              hostInfo += ` <1.66`;
+            } else if (minor < 68) {
+              hostInfo += ` <1.68`;
+            }
+          }
+        }
+      }
+
+      const processedMessageJSON = JSON.stringify(parsedMessage, (key, value) => {
+        return typeof value === 'string' ? fromEditorPath(value) : value;
+      });
+
+      return originalOnMessage.call(
+        this,
+        isStringMessage ? processedMessageJSON : JSON.parse(processedMessageJSON)
+      );
+    },
+
+    send(/** @type {any} */ msg) {
+      return originalSend.call(this, JSON.parse(JSON.stringify(msg, (key, value) => {
+        return typeof value === `string` ? toEditorPath(value) : value;
+      })));
+    }
+  });
+
+  return tsserver;
+};
+
+const [major, minor] = absRequire(`typescript/package.json`).version.split(`.`, 2).map(value => parseInt(value, 10));
+// In TypeScript@>=5.5 the tsserver uses the public TypeScript API so that needs to be patched as well.
+// Ref https://github.com/microsoft/TypeScript/pull/55326
+if (major > 5 || (major === 5 && minor >= 5)) {
+  moduleWrapper(absRequire(`typescript`));
+}
+
+// Defer to the real typescript/lib/tsserverlibrary.js your application uses
+module.exports = moduleWrapper(absRequire(`typescript/lib/tsserverlibrary.js`));

.yarn/sdks/typescript/lib/typescript.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+const {existsSync} = require(`fs`);
+const {createRequire, register} = require(`module`);
+const {resolve} = require(`path`);
+const {pathToFileURL} = require(`url`);
+
+const relPnpApiPath = "../../../../.pnp.cjs";
+
+const absPnpApiPath = resolve(__dirname, relPnpApiPath);
+const absUserWrapperPath = resolve(__dirname, `./sdk.user.cjs`);
+const absRequire = createRequire(absPnpApiPath);
+
+const absPnpLoaderPath = resolve(absPnpApiPath, `../.pnp.loader.mjs`);
+const isPnpLoaderEnabled = existsSync(absPnpLoaderPath);
+
+if (existsSync(absPnpApiPath)) {
+  if (!process.versions.pnp) {
+    // Setup the environment to be able to require typescript
+    require(absPnpApiPath).setup();
+    if (isPnpLoaderEnabled && register) {
+      register(pathToFileURL(absPnpLoaderPath));
+    }
+  }
+}
+
+const wrapWithUserWrapper = existsSync(absUserWrapperPath)
+  ? exports => absRequire(absUserWrapperPath)(exports)
+  : exports => exports;
+
+// Defer to the real typescript your application uses
+module.exports = wrapWithUserWrapper(absRequire(`typescript`));

.yarn/sdks/typescript/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "typescript",
+  "version": "5.9.3-sdk",
+  "main": "./lib/typescript.js",
+  "type": "commonjs",
+  "bin": {
+    "tsc": "./bin/tsc",
+    "tsserver": "./bin/tsserver"
+  }
+}

.yarnrc.yml

@@ -0,0 +1,18 @@
+enableGlobalCache: false
+
+enableScripts: true
+
+nodeLinker: pnp
+
+npmMinimalAgeGate: 0
+
+npmPreapprovedPackages:
+  - "@jig-software/trest"
+  - "@jig-software/sdk"
+
+npmScopes:
+  jig-software:
+    npmAlwaysAuth: true
+    npmAuthToken: "${JIG_SOFTWARE_GITEA_DEPLOYMENT_TOKEN:-NONE}"
+    npmPublishRegistry: "https://gitea.jig.com.hk/api/packages/jig-software/npm/"
+    npmRegistryServer: "https://gitea.jig.com.hk/api/packages/jig-software/npm/"

README.md

@@ -0,0 +1 @@
+# study-koa-trest

package.json

@@ -1,4 +1,29 @@
 {
   "name": "study-koa-trest",
-  "packageManager": "yarn@4.18.0"
+  "packageManager": "yarn@4.18.0",
+  "type": "module",
+  "scripts": {
+     "dev": "tsx --watch ./src/index.ts",
+  "start": "node ./dist/index.js",
+  "build": "tsc",
+  "clean": "rm -rf dist",
+  "compile": "yarn clean && yarn build",
+  "script": "tsx"
+  },
+  "dependencies": {
+    "@jig-software/trest": "2.0.0-beta",
+    "@koa/cors": "^5.0.0",
+    "@koa/router": "^15.7.0",
+    "koa": "^3.2.1",
+    "koa-bodyparser": "^4.4.1"
+  },
+  "devDependencies": {
+    "@types/koa": "^3.0.3",
+    "@types/koa-bodyparser": "^4",
+    "@types/koa__cors": "^5",
+    "@types/node": "^26.4.1",
+    "nodemon": "^3.1.14",
+    "tsx": "^4.23.13",
+    "typescript": "^5.9.3"
+  }
 }

src/index.ts

@@ -0,0 +1,19 @@
+import Koa from 'koa';
+import cors from '@koa/cors';
+import bodyParser from 'koa-bodyparser';
+//import { errorHandler } from './middleware/error';
+//import userRouter from './routes/userRoutes';
+
+const app = new Koa();
+const PORT = 3000;
+
+//app.use(errorHandler);
+app.use(cors());
+app.use(bodyParser());
+
+//app.use(userRouter.routes());
+//app.use(userRouter.allowedMethods());
+
+app.listen(PORT, () => {
+  console.log(`🚀 TypeScript Koa server running at http://localhost:${PORT}`);
+});

src/middleware/error.ts

@@ -0,0 +1,17 @@
+import { Context,Next } from "koa";
+
+export async function errorHandler(ctx:Context, next: Next) {
+  try {
+    await next();
+  } catch (err:any) {
+    // Fallback to 500 Internal Server Error if status code is omitted
+    ctx.status = err.status || 500;
+    ctx.body = {
+      success: false,
+      error: err.message || 'Internal Server Error',
+    };
+    
+    // Log the error stack to your console for debugging
+    console.error(`🚨 Error [${ctx.method}] ${ctx.url}:`, err);
+  }
+}

tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "./dist"
+  },
+  "include": ["src/**/*"]
+}