Link published Perl, Erlang and Raku packages, add the Raku port, and refresh registry versions

.github/CONTRIBUTING.md

@@ -704,6 +704,16 @@ cleanup in separate work.
 Follow [WRITING.md](../WRITING.md#commits) for commit messages and
 [AGENTS.md](../AGENTS.md#repository-boundaries) for push and deployment limits.
 
+### Raku source-bound documentation checks
+
+The Raku command-usage scanner parses the library with the compiler that the
+library revision pins in `.tool-versions`, and with `JSON::Fast` installed.
+Put that `raku` on `PATH`, or set `LIBTMUX_DOCS_RAKU` to its executable; a
+missing or different compiler fails the scan. RakuAST can run trusted
+compile-time code, so the scanner reads only reviewed library revisions. CI
+reads the compiler from the committed API model and installs `JSON::Fast`
+before it runs the fixture.
+
 ### Perl source-bound documentation checks
 
 The reusable port builder checks the selected Perl artifact after rendering.

.github/workflows/port-docs.yml

@@ -617,6 +617,36 @@ jobs:
           perl scripts/export-api.pl --revision "$SOURCE_SHA" \
             --exporter-revision "$SOURCE_SHA" --output docs/_build/api.json
 
+      - name: Read the selected Raku documentation runtime
+        if: matrix.port == 'raku'
+        id: raku-runtime
+        working-directory: port
+        run: |
+          python3 - <<'PYCODE'
+          import os, pathlib, re
+          rows = [line.split() for line in pathlib.Path('.tool-versions').read_text().splitlines()]
+          versions = [row[1] for row in rows if len(row) == 2 and row[0] == 'raku']
+          if len(versions) != 1 or not re.fullmatch(r'[0-9]{4}\.[0-9]{2}', versions[0]):
+              raise ValueError('Raku documentation requires an exact compiler pin')
+          with open(os.environ['GITHUB_OUTPUT'], 'a') as output:
+              output.write(f'version={versions[0]}\n')
+          PYCODE
+      - name: Install the selected Raku compiler
+        if: matrix.port == 'raku'
+        uses: Raku/setup-raku@8602b3572876ee7a5e304837c3183cf913a78f47 # v1.15.0
+        with:
+          raku-version: ${{ steps.raku-runtime.outputs.version }}
+      - name: Export the selected Raku declarations and native RakuDoc
+        if: matrix.port == 'raku'
+        working-directory: port
+        run: |
+          set -euo pipefail
+          zef install --/test --deps-only .
+          raku -I. tools/export-docs.raku
+      - name: Install the Raku usage scanner dependency
+        if: matrix.port == 'raku'
+        run: zef install --/test JSON::Fast
+
       - name: Install Common Lisp documentation toolchain
         if: matrix.port == 'lisp'
         uses: jdx/mise-action@b44d12e7d0d8ee7461bb893e1b1993500433185b # v5.2.7
@@ -816,6 +846,11 @@ jobs:
         working-directory: docs
         run: time pnpm run --recursive type-check
 
+      - name: Check the Raku native model adapter
+        if: matrix.port == 'raku'
+        working-directory: docs
+        run: time node site/node_modules/vitest/vitest.mjs run --root packages/api-model test/raku.test.ts
+
       # The version directory itself: its contents become
       # <locale>/<port>/<version>.
       - id: content

.github/workflows/reusable-deploy.yml

@@ -144,7 +144,7 @@ jobs:
             echo "::error::path-prefix '$p' must be an unrooted path using letters, digits, '.', '_', '-' and '/', without '..'" >&2
             exit 1
           fi
-          reserved=(py ruby lua powershell julia erlang elixir haskell lisp ts rs go java clojure kotlin scala csharp fsharp cxx swift ocaml perl manifest _shell)
+          reserved=(py ruby lua powershell julia erlang elixir haskell lisp ts rs go java clojure kotlin scala csharp fsharp cxx swift ocaml perl raku manifest _shell)
           for r in "${reserved[@]}"; do
             if [[ "$p" == "$r" ]]; then
               echo "::error::path-prefix '$p' is a bare reserved top-level name — qualify it, e.g. '$r/latest'" >&2
@@ -153,7 +153,7 @@ jobs:
           done
           if [[ -n "${PORT_IN:-}" ]]; then
             case "$PORT_IN" in
-              py|ruby|lua|powershell|julia|erlang|elixir|haskell|lisp|ts|rs|go|java|clojure|kotlin|scala|csharp|fsharp|cxx|swift|ocaml|perl) ;;
+              py|ruby|lua|powershell|julia|erlang|elixir|haskell|lisp|ts|rs|go|java|clojure|kotlin|scala|csharp|fsharp|cxx|swift|ocaml|perl|raku) ;;
               *) echo "::error::unknown port '$PORT_IN'" >&2; exit 1 ;;
             esac
             if [[ ! "$VERSION_IN" =~ ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ || "$VERSION_IN" == *..* ]]; then

.github/workflows/test.yml

@@ -65,6 +65,7 @@ jobs:
           } >> "$GITHUB_OUTPUT"
           echo "lisp=$(jq -r .revision site/src/data/api/lisp.json)" >> "$GITHUB_OUTPUT"
           echo "erlang=$(jq -r .revision site/src/data/api/erlang.json)" >> "$GITHUB_OUTPUT"
+          echo "raku=$(jq -r .revision site/src/data/api/raku.json)" >> "$GITHUB_OUTPUT"
 
       - uses: actions/checkout@v7
         with:
@@ -126,6 +127,24 @@ jobs:
           ref: ${{ steps.integrated-sources.outputs.erlang }}
           path: .port-sources/erlang
           persist-credentials: false
+      - uses: actions/checkout@v7
+        with:
+          repository: libtmux/libtmux-raku
+          ref: ${{ steps.integrated-sources.outputs.raku }}
+          path: .port-sources/raku
+          persist-credentials: false
+
+      # The usage scanner parses library source with the compiler that revision pins; RakuAST can run compile-time code.
+      - name: Read the integrated Raku compiler
+        id: raku-runtime
+        run: |
+          version=$(jq -er '.nativeProvenance.exporter.compiler | select(test("^[0-9]{4}\\.[0-9]{2}$"))' site/src/data/api/raku.json)
+          printf 'version=%s\n' "$version" >> "$GITHUB_OUTPUT"
+      - uses: Raku/setup-raku@8602b3572876ee7a5e304837c3183cf913a78f47 # v1.15.0
+        with:
+          raku-version: ${{ steps.raku-runtime.outputs.version }}
+      - name: Install the Raku scanner dependency
+        run: zef install --/test JSON::Fast
 
       # The exporter tests compile a fixture with the package's own toolchain:
       # the exact pair the integrated Elixir source pins, read as port-docs.yml
@@ -197,6 +216,7 @@ jobs:
           LIBTMUX_DOCS_CHECKOUT_PERL: ${{ github.workspace }}/.port-sources/perl
           LIBTMUX_DOCS_CHECKOUT_LISP: ${{ github.workspace }}/.port-sources/lisp
           LIBTMUX_DOCS_CHECKOUT_ERLANG: ${{ github.workspace }}/.port-sources/erlang
+          LIBTMUX_DOCS_CHECKOUT_RAKU: ${{ github.workspace }}/.port-sources/raku
         run: |
           node scripts/stage-port-docs.mjs --from-source
           node scripts/stage-port-docs.mjs --cached --check
@@ -220,6 +240,7 @@ jobs:
           LIBTMUX_DOCS_CHECKOUT_LUA: ${{ github.workspace }}/.port-sources/lua
           LIBTMUX_DOCS_CHECKOUT_OCAML: ${{ github.workspace }}/.port-sources/ocaml
           LIBTMUX_DOCS_CHECKOUT_LISP: ${{ github.workspace }}/.port-sources/lisp
+          LIBTMUX_DOCS_CHECKOUT_RAKU: ${{ github.workspace }}/.port-sources/raku
           # PowerShell, Julia, Elixir, Haskell and Perl paths stay scoped to guide staging
           # above, which checks the cache used by ordinary builds. Native API
           # and MCP export freshness remain owning-port checks, not claims of
@@ -228,7 +249,7 @@ jobs:
           # OCaml's checkout also feeds source-derived usage checks. Its
           # compiled API is qualified by the owning port's exporter job.
           # Common Lisp's checkout stays available here so example sources are checked against the exact revision.
-          LIBTMUX_DOCS_SKIP_NATIVE_MODEL_PORTS: ruby,lua,powershell,julia,elixir,ocaml,haskell,perl,lisp,erlang
+          LIBTMUX_DOCS_SKIP_NATIVE_MODEL_PORTS: ruby,lua,powershell,julia,elixir,ocaml,haskell,perl,lisp,erlang,raku
 
       - name: Upload audited preview
         if: github.event_name == 'pull_request'

.github/workflows/verify-destinations.yml

@@ -69,6 +69,14 @@ jobs:
         if: ${{ !cancelled() }}
         run: node scripts/verify-api-destinations.mjs --check --fresh
 
+      # A Perl reference page links to the POD of the latest CPAN release. When
+      # a release lands the record is stale, so this names the distribution
+      # and its old and new release; commit the output of
+      # node scripts/gen-perl-pod.mjs with the change that follows.
+      - name: Check the recorded Perl POD release against MetaCPAN
+        if: ${{ !cancelled() }}
+        run: node scripts/gen-perl-pod.mjs --check
+
       - name: Keep the fresh evidence
         if: ${{ !cancelled() }}
         uses: actions/upload-artifact@v7

notes/branding.md

@@ -38,6 +38,15 @@ and neutral reading surfaces. Its library cards describe the repository
 scaffold without an API example. Provenance is recorded in
 [`perl/source.json`](../site/public/brand/perl/source.json).
 
+Raku uses the library set from assets revision
+`55dd6eac4347ba22270788b74a71ec0cba12e287`, with Linguist's `#0000fb` primary.
+Its link and filled-control shades are darker in light mode and lighter in dark
+mode; reading surfaces stay neutral. Only the library set is included because
+the port publishes no workspace or MCP product. The port switcher shows the
+library tile, labelled as libtmux for Raku rather than as the Raku language
+logo. Digests and the shared-root manifest overrides are recorded in
+[`raku/source.json`](../site/public/brand/raku/source.json).
+
 - [GitHub Linguist colors](https://github.com/github-linguist/linguist/blob/538da05f034fa5c83bd81df128d144e208898da3/lib/linguist/languages.yml)
 - The original libtmux and tmuxp geometry was supplied by the project owner.
 - The MCP overlay uses the symbol, without the wordmark, from the

packages/api-model/src/builtins.ts

@@ -156,6 +156,10 @@ export const BUILTINS: Record<string, Record<string, string>> = {
   erlang: {
     'erl_error:format_exception/3': 'https://www.erlang.org/doc/apps/stdlib/erl_error.html#format_exception/3',
   },
+  raku: {
+    Promise: 'https://docs.raku.org/type/Promise',
+    Supply: 'https://docs.raku.org/type/Supply',
+  },
   ocaml: {
     Iarray: 'https://ocaml.org/manual/5.5/api/Iarray.html',
     'Iarray.t': 'https://ocaml.org/manual/5.5/api/Iarray.html#TYPEt',

packages/api-model/src/concepts.ts

@@ -4144,8 +4144,98 @@ for (const [id, binding] of Object.entries(CLOJURE_CONCEPTS)) {
   concept.symbols.clojure = binding.symbol
   if (binding.note) (concept.notes ??= {}).clojure = binding.note
 }
+const RAKU_CONCEPTS: Record<string, { symbol: string; note?: string }> = {
+  server: { symbol: 'LibTmux::Server' },
+  session: { symbol: 'LibTmux::Model::Session' },
+  window: { symbol: 'LibTmux::Model::Window', note: 'A physical window may have multiple WindowLink placements, including distinct indexes in one session.' },
+  pane: { symbol: 'LibTmux::Model::Pane' },
+  snapshot: { symbol: 'LibTmux::Server.snapshot', note: 'Explicit I/O captures an observation interval. Existing views and relationships remain local.' },
+  'list-sessions': { symbol: 'LibTmux::Model::Snapshot.sessions' },
+  'list-server-windows': { symbol: 'LibTmux::Model::Snapshot.windows', note: 'Physical windows occur once; window-links preserves placements.' },
+  'list-server-panes': { symbol: 'LibTmux::Model::Snapshot.panes' },
+  'list-clients': { symbol: 'LibTmux::Model::Snapshot.clients' },
+  'list-windows': { symbol: 'LibTmux::Model::Session.window-links', note: 'Returns captured WindowLink placements. Follow each window relationship for the physical window.' },
+  'list-panes': { symbol: 'LibTmux::Model::Window.panes' },
+  'pane-window': { symbol: 'LibTmux::Model::Pane.window' },
+  'window-session': { symbol: 'LibTmux::Model::WindowLink.session', note: 'The session belongs to a link, not to the physical Window.' },
+  'window-link-window': { symbol: 'LibTmux::Model::WindowLink.window' },
+  'client-session': { symbol: 'LibTmux::Model::Client.session' },
+  'active-pane': { symbol: 'LibTmux::Model::Window.active-pane' },
+  'active-window': { symbol: 'LibTmux::Model::Session.current-link', note: 'Returns the captured active WindowLink; its window relationship selects the physical window.' },
+  'new-session': { symbol: 'LibTmux::Server.new-session' },
+  'start-server': { symbol: 'LibTmux::Server.start', note: 'Starts an owned private daemon; close stops only an owned incarnation.' },
+  'kill-server': { symbol: 'LibTmux::Server.kill-server', note: 'Explicitly terminates the observed daemon. Owned callers still close to join cleanup.' },
+  'server-from-env': { symbol: 'LibTmux::Server.from-env', note: 'Explicitly imports TMUX environment data, verifies the daemon PID and binds that incarnation.' },
+  'has-session': { symbol: 'LibTmux::Server.has-session', note: 'Checks one exact ID or name; acquisition and identity failures still throw.' },
+  'run-shell': { symbol: 'LibTmux::Server.run-shell', note: 'Background acknowledgement does not establish job completion.' },
+  'if-shell': { symbol: 'LibTmux::Server.if-shell', note: 'Branches use bounded Invocation values; the condition explicitly selects shell or FORMAT semantics.' },
+  'source-file': { symbol: 'LibTmux::Server.source-file', note: 'Sources a literal pathname; parse-only validates without executing commands.' },
+  'wait-for': { symbol: 'LibTmux::Server.wait-for', note: 'Waits, signals, locks or unlocks a named channel within the Server deadline.' },
+  'server-cmd': { symbol: 'LibTmux::Server.command' },
+  'attach-session': { symbol: 'LibTmux::Server.attach', note: 'Returns a separately owned attachment with an explicit lifecycle.' },
+  'server-version': { symbol: 'LibTmux::Server.capabilities', note: 'Client and observed daemon versions are distinct capability inputs.' },
+  'chain-commands': { symbol: 'LibTmux::Server.run-batch', note: 'Returns per-operation evidence and partial results; this is not a transaction.' },
+}
+for (const [owner, bindings] of Object.entries({
+  SessionRef: { 'new-window': 'new-window', 'kill-session': 'kill', 'rename-session': 'rename', 'session-cmd': 'command',
+    'refresh-session': 'inspect', 'next-window': 'next-window', 'previous-window': 'previous-window', 'last-window': 'last-window',
+    'detach-session-clients': 'detach-clients', 'lock-session': 'lock' },
+  WindowRef: { 'kill-window': 'kill', 'rename-window': 'rename', 'window-cmd': 'command', 'refresh-window': 'inspect',
+    'select-layout': 'select-layout', 'next-layout': 'next-layout', 'previous-layout': 'previous-layout', 'resize-window': 'resize',
+    'respawn-window': 'respawn', 'link-window': 'link', 'rotate-panes': 'rotate', 'last-pane': 'last-pane' },
+  WindowLinkRef: { 'unlink-window': 'unlink', 'move-window': 'move', 'swap-window': 'swap', 'select-window': 'select' },
+  PaneRef: { 'capture-pane': 'capture', 'send-keys': 'send-keys', 'split-pane': 'split', 'respawn-pane': 'respawn',
+    'resize-pane': 'resize', 'kill-pane': 'kill', 'break-pane': 'break', 'join-pane': 'join', 'move-pane': 'move', 'swap-pane': 'swap',
+    'pipe-pane': 'pipe', 'select-pane': 'select', 'clear-history': 'clear-history', 'set-pane-title': 'set-title',
+    'copy-mode': 'copy-mode', 'clock-mode': 'clock-mode', 'send-prefix': 'send-prefix', 'reset-pane': 'reset',
+    'pane-cmd': 'command', 'refresh-pane': 'inspect' },
+  ClientRef: { 'detach-client': 'detach', 'refresh-client': 'refresh', 'switch-client': 'switch', 'lock-client': 'lock',
+    'suspend-client': 'suspend', 'display-menu': 'menu-async', 'display-popup': 'popup-async', 'command-prompt': 'prompt-async',
+    'confirm-before': 'confirm-async', 'prompt-history': 'prompt-history', 'clear-prompt-history': 'clear-prompt-history',
+    'find-window': 'find-window' },
+})) for (const [concept, method] of Object.entries(bindings)) RAKU_CONCEPTS[concept] = { symbol: `LibTmux::Model::${owner}.${method}` }
+for (const [prefix, owner, fields] of [
+  ['session', 'Session', ['id', 'name', 'created', 'path', 'group', 'grouped']],
+  ['window', 'Window', ['id', 'name', 'height', 'width', 'layout', 'linked']],
+  ['pane', 'Pane', ['id', 'index', 'height', 'width', 'title', 'active', 'current-command', 'current-path', 'pid', 'tty', 'dead', 'in-mode', 'window-id']],
+  ['window', 'WindowLink', ['index', 'active', 'session-id']],
+] as const) for (const field of fields) RAKU_CONCEPTS[`${prefix}-${field}`] = { symbol: `LibTmux::Model::${owner}.${field}` }
+for (const scope of ['server', 'session', 'window', 'pane']) {
+  for (const [suffix, method] of Object.entries({ options: 'entries', option: 'get' })) RAKU_CONCEPTS[`${scope}-${suffix}`] = {
+    symbol: `LibTmux::Configuration::Options.${method}`, note: 'Use the corresponding server or reference options facade; acquisition is explicit.' }
+  for (const method of ['set', 'unset']) RAKU_CONCEPTS[`${method}-${scope}-option`] = { symbol: `LibTmux::Configuration::Options.${method}` }
+  RAKU_CONCEPTS[`${scope}-hooks`] = { symbol: 'LibTmux::Configuration::Hooks.list', note: 'Use the explicitly scoped hooks facade.' }
+  for (const method of ['set', 'unset']) RAKU_CONCEPTS[`${method}-${scope}-hook`] = { symbol: `LibTmux::Configuration::Hooks.${method}` }
+}
+for (const scope of ['server', 'session']) {
+  RAKU_CONCEPTS[`${scope}-environment`] = { symbol: 'LibTmux::Configuration::Environment.list', note: 'Use the corresponding server or session environment facade.' }
+  RAKU_CONCEPTS[`${scope}-get-environment`] = { symbol: 'LibTmux::Configuration::Environment.get' }
+  for (const method of ['set', 'unset', 'remove']) RAKU_CONCEPTS[`${method}-${scope}-environment`] = { symbol: `LibTmux::Configuration::Environment.${method}` }
+}
+for (const [concept, method] of Object.entries({ 'list-buffers': 'list', 'show-buffer': 'get', 'set-buffer': 'put', 'delete-buffer': 'delete', 'paste-buffer': 'paste' })) {
+  RAKU_CONCEPTS[concept] = { symbol: `LibTmux::Configuration::Buffers.${method}`, note: 'Buffer content is byte data; file I/O remains a separate caller operation.' }
+}
+for (const [concept, method] of Object.entries({ 'list-keys': 'list', 'bind-key': 'bind', 'unbind-key': 'unbind' })) RAKU_CONCEPTS[concept] = { symbol: `LibTmux::Configuration::KeyBindings.${method}` }
+for (const [id, binding] of Object.entries(RAKU_CONCEPTS)) {
+  const concept = CONCEPTS[id]
+  if (!concept) throw new Error(`concepts: Raku maps unknown concept ${id}`)
+  concept.symbols.raku = binding.symbol
+  if (binding.note) (concept.notes ??= {}).raku = binding.note
+}
+for (const [id, reason] of Object.entries({
+  'workspace-description': 'Workspace functionality is outside the Raku core library scope.',
+  'build-workspace': 'Workspace functionality is outside the Raku core library scope.',
+  'freeze-workspace': 'Workspace functionality is outside the Raku core library scope.',
+  'pane-session': 'A pane belongs to a physical window, which can have several session links. Traverse window.links and each link.session.',
+  'pane-session-id': 'A physical pane has no single session identity; inspect its window links.',
+  'session-from-env': 'Session targeting is explicit and incarnation-bound.',
+  'load-buffer': 'Read file bytes with native Raku I/O and pass them to Buffers.put.',
+  'save-buffer': 'Acquire bytes with Buffers.get and write them with native Raku I/O.',
+})) (CONCEPTS[id]!.absent ??= {}).raku = reason
+
 for (const concept of Object.values(CONCEPTS)) {
   concept.absent ??= {}
+  if (!concept.symbols.raku) concept.absent.raku ??= 'No direct Raku mapping is recorded for this operation; consult the native API reference.'
   if (!concept.symbols.powershell) concept.absent.powershell ??= 'No source-verified PowerShell equivalent is recorded for this operation.'
   if (!concept.symbols.julia) concept.absent.julia ??= 'No source-verified Julia equivalent is recorded for this operation.'
   if (!concept.symbols.elixir) concept.absent.elixir = 'No source-verified Elixir equivalent is recorded for this operation.'

packages/api-model/src/doc/roles.ts

@@ -284,6 +284,8 @@ const SYNTAX: Record<string, ReadonlySet<string>> = {
   py: new Set(['rest', 'citation']),
   // Pod::Simple exports local POD targets as roles and external targets as Markdown links.
   perl: new Set(['pod', 'markdown-link']),
+  // The RakuDoc adapter resolves L<> links into roles; C<> stays literal code.
+  raku: new Set(['rest-role', 'markdown-link', 'literal-code']),
   rs: new Set(['intra-doc']),
   go: new Set(['go-link']),
   java: new Set(['jsdoc']),

packages/api-model/src/index.ts

@@ -1,4 +1,5 @@
 export { extractPerlArtifact } from './languages/perl.ts'
+export { extractRakuArtifact } from './languages/raku.ts'
 export * from './model.ts'
 export * from './doc/prose-blocks.ts'
 export { sourceUrl, symbolsForProduct } from './products.ts'