--- @meta pmacs.packages --- --- EmmyLua-style annotations for the `pmacs.packages.*` Lua surface --- (T M7.3, spec §sec:packages-future). This file is a documentation --- artifact: editor tooling (lua-language-server, EmmyLua) consumes it --- to power completion and hover; the runtime implementation lives in --- Rust (`src/lua_bindings.rs::install_packages_module`). --- --- The runtime never `require`s this file. It is shipped under --- `builtin/api/` so packagers know to include it alongside the --- binary; users who want IDE completion add this directory to their --- workspace's lua-language-server `Lua.workspace.library`. --- A package install spec. --- --- Two accepted shapes: --- --- - Table with positional address at `[1]`. The pin is one of three --- mutually-exclusive fields: --- - `version = ""` (default; constrains to a tag). --- - `branch = ""` (HEAD of the named branch at install time). --- - `commit = ""` (specific revision; full or partial SHA). --- Specifying more than one of these errors with a "must specify --- exactly one" message naming every conflicting field. With none --- specified, the pin defaults to `version = "*"` (any tag). --- The `install_project` variant additionally **requires** --- `project_root = "..."` (no default). --- - Shorthand string `"github:owner/repo@^1.0.0"`. **Version-pin only.** --- The separator is the **last** `@` in the string, so addresses --- containing an `@` (SSH shorthand `git@host:path`) parse correctly. --- Branch and commit pins must use the table form. The shorthand --- form is also not accepted by `install_project` (no place to put --- `project_root`). --- --- @class PackageInstallSpec --- @field [1] string Positional address (e.g., `"github:owner/repo"`). --- @field address string|nil Alternative to the positional `[1]`. --- @field version string|nil Semver constraint (e.g., `"^1.0.0"`, `"=1.2.3"`, `"*"`). Mutually exclusive with `branch` / `commit`. Defaults to `"*"` when none of the three are specified. --- @field branch string|nil Branch name (e.g., `"main"`). The install resolves the branch's HEAD at install time; not reproducible across time. Mutually exclusive with `version` / `commit`. --- @field commit string|nil Commit SHA (full or partial). The install pins to that exact revision. Mutually exclusive with `version` / `branch`. --- @field project_root string|nil `install_project` only: REQUIRED project root. Absolute paths used as-is. Relative paths resolve against the directory of the loading `init.lua` (not against CWD). Common patterns: `os.getenv("PMACS_PROJECT")`, or a literal subdirectory like `"."` for "alongside this init.lua". --- The pin info on an [`InstalledPackage`]. --- --- @class InstalledPackagePin --- @field kind "version"|"branch"|"commit" Which pin kind the user supplied. --- @field value string The user-supplied value: the semver constraint (e.g. `"^1.0.0"`), the branch name (e.g. `"main"`), or the commit SHA. Echoes the field on `PackageInstallSpec` exactly. --- A successful-install record returned by `install` and listed by `installed`. --- --- @class InstalledPackage --- @field name string Package name from `pmacs.toml` (e.g., `"samplepkg"` or `"user/samplepkg"`). --- @field version string Manifest-declared version of the installed snapshot (canonical semver, e.g. `"1.2.3"`). --- @field tag string Resolution descriptor: matched tag (`"v1.2.3"`) for version pins, `"branch:"` for branch pins, `"commit:"` for commit pins. Always non-empty. --- @field commit string 40-character commit SHA of the installed snapshot. --- @field install_path string Absolute on-disk install directory. --- @field entry string Absolute path to the package's `entry` Lua module. --- @field scope "user"|"project" Which scope the package was installed under. --- @field summary string One-line description from the manifest. --- @field pin InstalledPackagePin Structured pin info (the user's request, distinct from the resolved descriptor). local pmacs = pmacs or {} pmacs.packages = pmacs.packages or {} --- Install a package to the user-config root (`$XDG_DATA_HOME/pmacs/packages/`). --- --- Synchronous: clones / fetches the address, picks the highest semver tag --- matching `version`, materializes the snapshot via `git archive | tar -x`, --- and makes the package's entry module requireable as --- `require()`. --- --- Resolution path: standard layouts (`.lua`, --- `/init.lua`) are found via `package.path`. Non-standard --- entries (e.g. `entry = "main.lua"` or `entry = "lib/foo.lua"`) are --- found by a custom searcher pmacs registers in `package.searchers` --- (Lua 5.4) / `package.loaders` (LuaJIT, Lua 5.1), which consults --- the install roster and returns the manifest's exact entry path. --- --- **Init-time-only.** Calling outside `init.lua` raises an error pointing --- at the workaround (restart pmacs after editing `init.lua`). Mid-session --- install is not supported in v0.1; M7.6 adds `pmacs.packages.update(...)` --- for in-place version changes. --- --- @param spec PackageInstallSpec|string Spec table, or shorthand string `"address@constraint"`. --- @return InstalledPackage --- @throws "init-only" if called after init has finished. --- @throws "no matching version" if no tag satisfies `version`. --- @throws "already installed" if a different commit occupies the install path. function pmacs.packages.install(spec) end --- Install a package to a project-scoped root (`/.pmacs/packages/`). --- --- Identical to `install` except for the on-disk root. **Requires** an --- explicit `project_root` field in the spec table. Absolute paths are --- used as-is; relative paths resolve against the directory of the --- loading `init.lua` (not against the process CWD, which is rarely a --- meaningful project root). The shorthand string form is not accepted. --- --- Project installs override user installs of the same package basename --- in `package.path` (project entries are prepended). --- --- **Init-time-only.** See `install` for the gate. --- --- @param spec PackageInstallSpec --- @return InstalledPackage --- @throws "init-only" if called after init has finished. --- @throws "no matching version" if no tag satisfies `version`. --- @throws "already installed" if a different commit occupies the install path. --- @throws "missing project_root" if the spec table omits the `project_root` field. The error message names two patterns for filling it in: `os.getenv("PMACS_PROJECT")` for an env-var-driven setup, or a path relative to the loading `init.lua`'s directory. function pmacs.packages.install_project(spec) end --- Snapshot the in-memory roster of packages installed during this init pass. --- --- Each entry is the same shape as `install`'s return value. The list is --- ordered by install order (first call first). --- --- @return InstalledPackage[] function pmacs.packages.installed() end --- Re-resolve and update an installed package to the latest commit --- matching its constraint. --- --- **Implemented in M7.6** (lockfile + resolver). v0.1 / current builds --- raise an error pointing at the workaround: re-run `pmacs.packages.install` --- with the new constraint to upgrade in place. --- --- @param name string|nil Package name to update; omit to update all. --- @throws "unsupported" until M7.6 ships. function pmacs.packages.update(name) end return pmacs.packages