logos-cpp-sdk/doctests/cpp-sdk-module-runtime.test.yaml

name: "Running a Real Module Against This C++ SDK"
output: cpp-sdk-module-runtime.md
release: ""

intro: |
  `logos-cpp-sdk` is the foundation every other Logos component is built on: it
  pins nixpkgs/Qt and ships the SDK that `logos-liblogos` (`logos_host`,
  `liblogos_core`), the module client, and every module compile and link against
  — `LogosAPI`, `LogosResult`, the IPC layer, and the code generator. A change
  here ripples through the entire stack, so the way to know it is safe is to run
  a real module on top of it. This doc-test does exactly that, end-to-end through
  the headless `logoscore` runtime:

  1. Build the `logoscore` CLI, **overriding `logos-cpp-sdk` with the commit
     under test** — and overriding it in the same way for every consumer in
     `logoscore`'s closure (`logos-liblogos`, `logos-module-client`, and the
     `capability_module`'s `logos-module-builder`). Because the published flakes
     pin the SDK independently (there is no single `follows` unifying them), all
     of these must point at the same commit so the whole runtime is built and
     linked against one consistent SDK ABI.
  2. Build the `lgpm` local package manager.
  3. Build the real [`accounts_module`](https://github.com/logos-co/logos-accounts-module)
     as an `.lgx` package straight from its own flake — **also built against the
     SDK commit under test** — and install it into a `./modules` directory with
     `lgpm`.
  4. Start `logoscore` in daemon mode (`-D`), load `accounts_module`, introspect
     it, and call its methods — verifying a module compiled against this SDK
     actually loads and round-trips real values over the SDK's IPC.

  Because every layer (host, module loader, IPC, and the module itself) is built
  against the SDK commit under test, a green run is real evidence that this
  change keeps the module runtime working from the bottom of the stack up.

what_you_build: "The real `accounts_module`, installed with `lgpm` and called through a `logoscore` daemon — every layer compiled against this C++ SDK commit."

what_you_learn:
  - How to build `logoscore` against a specific `logos-cpp-sdk` commit by overriding it across every consumer in the closure
  - Why a foundational input pinned independently by several flakes needs the override applied at each consumer, not just once
  - How to build a real module's `.lgx` against the same SDK commit
  - How to install an `.lgx` into a modules directory with `lgpm`
  - How to start the `logoscore` daemon, load a module, and call its methods

prerequisites:
  - |
    **Nix** with flakes enabled. Install from [nixos.org](https://nixos.org/download.html), then enable flakes:

    ```bash
    mkdir -p ~/.config/nix
    echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf
    ```

    Verify: `nix flake --help >/dev/null 2>&1 && echo "Flakes enabled"`
  - "**git** — to clone the module repository."
  - "A Linux or macOS machine."

sections:
  - title: "Build logoscore against this C++ SDK"
    step: true
    text: |
      Build the `logoscore` CLI from its published flake, but **override
      `logos-cpp-sdk` to the commit under test** — and apply the same override to
      every consumer that pins the SDK in `logoscore`'s closure. The result is
      symlinked to `./logos/`.

      > Unlike a leaf input, the SDK is pinned independently by `logos-liblogos`,
      > `logos-module-client`, and the `capability_module`'s `logos-module-builder`
      > — there is no single `follows` tying them together in the published
      > flakes. So we override it at each of those paths (e.g.
      > `--override-input logos-liblogos/logos-cpp-sdk …`) to keep the whole
      > runtime on one consistent SDK ABI. Each override URL carries a `{release}`
      > placeholder the doc-test runner expands to a concrete ref: locally that is
      > this checkout's `HEAD` (see `run.sh`); in CI it is the commit being
      > tested. With no pin it falls back to latest `master`.
    steps:
      - title: "Build the CLI with the SDK override"
        run: |
          nix build 'github:logos-co/logos-logoscore-cli{release}' \
            --override-input logos-cpp-sdk 'github:logos-co/logos-cpp-sdk{release}' \
            --override-input logos-liblogos/logos-cpp-sdk 'github:logos-co/logos-cpp-sdk{release}' \
            --override-input logos-module-client/logos-cpp-sdk 'github:logos-co/logos-cpp-sdk{release}' \
            --override-input logos-capability-module/logos-module-builder 'github:logos-co/logos-module-builder{release}' \
            --override-input logos-capability-module/logos-module-builder/logos-cpp-sdk 'github:logos-co/logos-cpp-sdk{release}' \
            --out-link ./logos
        code_block: |
          nix build 'github:logos-co/logos-logoscore-cli' \
            --override-input logos-cpp-sdk 'github:logos-co/logos-cpp-sdk' \
            --override-input logos-liblogos/logos-cpp-sdk 'github:logos-co/logos-cpp-sdk' \
            --override-input logos-module-client/logos-cpp-sdk 'github:logos-co/logos-cpp-sdk' \
            --override-input logos-capability-module/logos-module-builder/logos-cpp-sdk 'github:logos-co/logos-cpp-sdk' \
            --out-link ./logos
        check_file: "logos/bin/logoscore"
        post_text: |
          The build produces `logos/bin/logoscore` plus bundled runtime libraries
          and a `logos/modules/` directory containing the built-in
          `capability_module` (required for the auth handshake when loading
          modules). Every overridden input resolves to the same SDK commit, so
          `logos_host`, `liblogos_core`, the module client, and the capability
          module are all rebuilt and linked against this SDK.

  - title: "Build the lgpm package manager"
    step: true
    text: |
      `lgpm` installs `.lgx` packages into a modules directory and scans what is
      installed. Build it from the `logos-package-manager` flake and link it as
      `./lgpm`. (`lgpm` is plain C++ with no SDK dependency, so it needs no
      override.)
    steps:
      - title: "Build lgpm"
        run: "nix build 'github:logos-co/logos-package-manager#cli' -o lgpm"
        check_file: "lgpm/bin/lgpm"
        post_text: "The executable is at `./lgpm/bin/lgpm`."

  - title: "Build and install the accounts module against this SDK"
    step: true
    text: |
      Clone [`logos-accounts-module`](https://github.com/logos-co/logos-accounts-module),
      build its `.lgx` straight from its flake's `#lgx` output **against the SDK
      commit under test**, and install it into a local `./modules` directory with
      `lgpm`. Building the module against the same SDK as the runtime keeps the
      plugin ABI-compatible with the host that will load it. Every module built
      with [`logos-module-builder`](https://github.com/logos-co/logos-module-builder)
      exposes a ready-to-install `#lgx`, and the builder owns the module's SDK
      pin — so the override path here is
      `logos-module-builder/logos-cpp-sdk`.
    steps:
      - title: "Clone the module"
        text: |
          We clone over HTTPS so the step works in CI; over SSH the URL is
          `git@github.com:logos-co/logos-accounts-module.git`.
        run: "git clone --depth 1 https://github.com/logos-co/logos-accounts-module.git"
        check_file: "logos-accounts-module/flake.nix"

      - title: "Build the module's .lgx against this SDK"
        text: |
          Build the `#lgx` output, overriding the module builder's `logos-cpp-sdk`
          to the commit under test, and link it as `./accounts-lgx`. (This
          compiles the module and its SDK dependencies through Nix, so the first
          build is slow.)
        run: |
          nix build 'path:./logos-accounts-module#lgx' \
            --override-input logos-module-builder 'github:logos-co/logos-module-builder{release}' \
            --override-input logos-module-builder/logos-cpp-sdk 'github:logos-co/logos-cpp-sdk{release}' \
            -o accounts-lgx
        code_block: |
          # From inside the clone this is simply:
          #   nix build '.#lgx' --override-input logos-module-builder/logos-cpp-sdk 'github:logos-co/logos-cpp-sdk'
          nix build 'path:./logos-accounts-module#lgx' \
            --override-input logos-module-builder/logos-cpp-sdk 'github:logos-co/logos-cpp-sdk' \
            -o accounts-lgx
        post_text: "The `.lgx` package is now under `./accounts-lgx/`:"
        extra_run:
          run: "ls accounts-lgx/*.lgx"

      - title: "Seed the modules directory with the bundled capability module"
        text: |
          `accounts_module` is loaded through the host's capability layer, so the
          modules directory also needs the `capability_module` that ships with
          `logoscore` (and that we just rebuilt against this SDK). Copy it across
          first.
        run: |
          mkdir -p modules
          cp -RL ./logos/modules/. ./modules/
        check_file: "modules/capability_module/manifest.json"

      - title: "Install the .lgx with lgpm"
        text: |
          Install the freshly-built package into `./modules`. `accounts_module` is
          a `core` module, so it goes to `--modules-dir`. The package is unsigned
          (a local dev build), so we pass `--allow-unsigned`.
        run: "./lgpm/bin/lgpm --modules-dir ./modules --allow-unsigned install --file accounts-lgx/*.lgx"
        expect_contains:
          - "Installed to:"

      - title: "Confirm the install"
        text: "Scan the directory and confirm the module landed:"
        run: "./lgpm/bin/lgpm --modules-dir ./modules list"
        expect_contains:
          - "accounts_module"
        check_file: "modules/accounts_module/manifest.json"

  - title: "Run the daemon and call the module"
    step: true
    text: |
      Start `logoscore` in daemon mode pointed at `./modules`, then use the client
      subcommands to load `accounts_module`, introspect it, and call its methods.
      Daemon output is captured in `logs.txt`.
    steps:
      - title: "Start the daemon"
        text: |
          Start logoscore in daemon mode in the background, capturing output to
          `logs.txt`:
        run: "sh -c './logos/bin/logoscore -D -m ./modules > logs.txt 2>&1 &'"
        code_block: "logoscore -D -m ./modules > logs.txt &"
        post_text: |
          The `-D` flag starts the daemon. The client subcommands below connect to
          this running process via the config written under `~/.logoscore/`.

      - run: "sleep 3"

      - title: "Inspect the startup log"
        text: "Review the daemon's startup output:"
        run: "cat logs.txt"

      - title: "Check daemon status"
        text: "Verify the daemon is running:"
        run: "./logos/bin/logoscore status"
        code_block: "logoscore status"

      - title: "List discovered modules"
        text: "`accounts_module` should be visible in the scan directory:"
        run: "./logos/bin/logoscore list-modules"
        code_block: "logoscore list-modules"
        expect_contains:
          - "accounts_module"

      - title: "Load the module"
        text: "Load `accounts_module` into the running daemon:"
        run: "./logos/bin/logoscore load-module accounts_module"
        code_block: "logoscore load-module accounts_module"
        expect_contains:
          - "accounts_module"

      - title: "Confirm the module is loaded"
        text: |
          Re-run `status`; the module that was `not_loaded` before now reports
          `loaded`:
        run: "./logos/bin/logoscore status"
        code_block: "logoscore status"
        expect_contains:
          - "accounts_module"
          - '"status":"loaded"'

      - title: "Introspect the module with module-info"
        text: |
          `module-info` lists the `Q_INVOKABLE` methods the module exposes — the
          same methods you can `call`. Each one is dispatched over the SDK's IPC
          layer:
        run: "./logos/bin/logoscore module-info accounts_module"
        code_block: "logoscore module-info accounts_module"
        expect_contains:
          - "accounts_module"
          - "createRandomMnemonic"

      - title: "Call a method"
        text: |
          Generate a fresh 12-word BIP-39 mnemonic. `createRandomMnemonic` takes
          the word count and returns the phrase — a real round-trip dispatched
          over the SDK's IPC layer into the module compiled against this SDK:
        run: "./logos/bin/logoscore call accounts_module createRandomMnemonic 12"
        code_block: "logoscore call accounts_module createRandomMnemonic 12"
        expect_contains:
          - '"result"'

      - title: "Call a second method"
        text: |
          `lengthToEntropyStrength` maps a mnemonic word count to its entropy
          strength in bits — 12 words is 128 bits. This exercises an `int`
          round-trip through `LogosResult` over the SDK's IPC:
        run: "./logos/bin/logoscore call accounts_module lengthToEntropyStrength 12"
        code_block: "logoscore call accounts_module lengthToEntropyStrength 12"
        expect_contains:
          - '"result":128'

      - title: "Stop the daemon"
        text: "Shut the daemon down cleanly:"
        run: "./logos/bin/logoscore stop"
        code_block: "logoscore stop"
        post_text: |
          The daemon removes its state file and exits.

      - run: "sleep 2"

      - title: "Confirm the daemon has stopped"
        text: |
          With no daemon running, the client reports `not_running` and exits
          non-zero, so we add `|| true` to let the doc-test assert on the output:
        run: "./logos/bin/logoscore status || true"
        code_block: "logoscore status"
        expect_contains:
          - '"status":"not_running"'