# LuaRocks

Recommend AXM extensions from a LuaRocks (Lua) rock and target LuaRocks packages from an extension.

AXM reads Lua extension metadata from an `agent-extensions.json` sidecar shipped
at the rock root inside the installed rock. This is the
[two-way linking](/docs/package-ecosystems/overview) model applied to the
LuaRocks ecosystem.

## Recommend extensions from a rock

Add an `agent-extensions.json` file with an `agentExtensions` array. Each entry
is an extension reference (`@owner/<type>/<name>`):

```jsonc
// agent-extensions.json
{
  "$schema": "https://axm.sh/schemas/agent-extensions.schema.json",
  "agentExtensions": [{ "ref": "@examples/packs/lua-luarocks-tinyflags" }],
}
```

Ship the sidecar as package data in the rock root. For a builtin rockspec, add
an install mapping:

```lua
-- agentxm-example-tinyflags-0.1.0-1.rockspec
build = {
  type = "builtin",
  install = {
    conf = { ["agent-extensions.json"] = "agent-extensions.json" },
  },
}
```

Keep recommendations **identity-only** — omit `versionRange`. AXM resolves the
reference to the newest matching extension version and pins it in the user's
`axm.lock`. Prefer recommending a single **pack** so you keep one stable
reference while its contents evolve.

Add a semver `versionRange` only when your rock genuinely pairs with a bounded
major line of the extension:

```jsonc
{
  "agentExtensions": [
    {
      "ref": "@examples/packs/lua-luarocks-tinyflags",
      "versionRange": "^1.0.0",
    },
  ],
}
```

## Target LuaRocks packages from an extension

On the extension manifest (`skill.json`, `pack.json`, `subagent.json`, …), add a
`packages` array with a LuaRocks
[purl](https://github.com/package-url/purl-spec). Use the rock name as the purl
name:

```jsonc
// pack.json
{
  "packages": [{ "purl": "pkg:luarocks/agentxm-example-tinyflags" }],
}
```

### Version ranges

Default to identity-only. Add a [VERS](https://github.com/package-url/vers-spec)
`versionRange` with the `luarocks` scheme only when the extension depends on
rock APIs introduced or removed in a known range:

```jsonc
{
  "packages": [
    {
      "purl": "pkg:luarocks/agentxm-example-tinyflags",
      "versionRange": "vers:luarocks/>=0.1.0|<1.0.0",
    },
  ],
}
```

## Official status

When the rock recommends an extension through the AgentXM Registry **and** that
extension names the rock as a companion via its purl, AXM derives **official**
status for the pair — no extra flag. See
[Official extensions](/docs/package-ecosystems/overview#official-extensions).

## Reference fixture

The
[`lua-luarocks-lib`](https://github.com/agentxm/polyglot-examples/tree/main/lua-luarocks-lib)
and
[`lua-luarocks-app`](https://github.com/agentxm/polyglot-examples/tree/main/lua-luarocks-app)
directories in `polyglot-examples` are the working fixtures for everything
above. The rock publishes a TinyFlags companion pack and recommends it from the
`agent-extensions.json` sidecar at the rock root; the pack and each skill
declare the rock's `pkg:luarocks` purl as an identity-only companion package.