1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
//! Package management — install, list, remove, and project-local resolution.
//!
//! # Package resolution model
//!
//! algocline resolves `require("name")` through an ordered chain of
//! `mlua_isle::FsResolver`s. When `alc_run` / `alc_advice` starts a session,
//! the executor registers resolvers in the following priority (high → low):
//!
//! 1. **Project-local** (`alc.toml` path entries, resolved via `alc.lock`) —
//! zero-copy references to on-disk directories. Resolved via
//! [`super::lockfile::resolve_local_dir_paths`].
//! 2. **`ALC_PACKAGES_PATH`** — colon-separated search paths from the env var.
//! 3. **Global default** (`~/.algocline/packages/`) — packages installed by
//! `alc_pkg_install`.
//!
//! A higher-priority package **shadows** a lower-priority one with the same
//! name. `pkg_list` reports both, marking the effective one as `active: true`.
//!
//! # Scope concept
//!
//! Each package belongs to a scope:
//!
//! - **`"global"`** — installed in `~/.algocline/packages/` via `pkg_install`.
//! Physical directory managed by algocline (clone/copy).
//! - **`"project"`** — declared in `alc.toml` via `pkg_install` or manual entry.
//! Recorded in `alc.lock`. algocline never copies or deletes the source files.
//!
//! # `alc.toml` / `alc.lock` lifecycle
//!
//! `alc.toml` is the package declaration file (user-authored).
//! `alc.lock` is the resolved lockfile (tool-managed).
//!
//! - `pkg_install` updates both `alc.toml` (adds entry) and `alc.lock` (records version/source).
//! - `pkg_remove` removes entries scoped by `scope`:
//! - `"project"` (default): `alc.toml` + `alc.lock`.
//! - `"global"`: `~/.algocline/installed.json`.
//! - `"all"`: both.
//! - Physical files in `~/.algocline/packages/` are never deleted by `pkg_remove`
//! under any scope.
//!
//! `alc.lock` is updated atomically via temp-file + rename.
//! Read at session start to build extra `FsResolver` entries.
//!
//! # Project root resolution
//!
//! See [`super::project`] for the 3-tier priority (explicit arg →
//! `ALC_PROJECT_ROOT` env → ancestor walk from cwd looking for `alc.toml`).
//!
//! # Security invariants
//!
//! - Package names are whitelist-validated (`[a-zA-Z0-9_-]`) before Lua
//! interpolation in `pkg_list` meta evaluation.
//! - Lockfile writes are serialized in-process (`SAVE_GUARD` mutex)
//! and use atomic rename to prevent half-written reads.
//!
//! # Submodules
//!
//! - [`list`] — `pkg_list` and its intermediate DTOs.
//! - [`install`] — `pkg_install`, local-path variant, and bundled auto-install.
//! - [`remove`] — `pkg_remove` (project / global / all scope dispatch).
pub