V0.38.2 library packages (#235)

Co-authored-by: gobha <jasafpro@gmail.com>
Co-committed-by: gobha <jasafpro@gmail.com>

docs/ICD/extensions.md

@@ -414,6 +414,50 @@ config fields with secrets decrypted.
 
 ---
 
+### Library Packages (v0.38.2)
+
+Library packages (`type: "library"`) export Starlark functions for other
+packages to consume. Libraries run with their own permission context,
+isolating consumers from implementation details.
+
+**Manifest fields:**
+- `type: "library"` — required
+- `tier: "starlark"` — required (libraries are always starlark-tier)
+- `exports: ["fn_a", "fn_b"]` — required, names of globals to expose
+- `permissions: [...]` — the library's own permissions (not inherited by consumers)
+- `dependencies: {"other-lib": ">=1.0.0"}` — optional, libraries can depend on other libraries
+
+**Restrictions:** Libraries cannot have `tools`, `pipes`, or a `route`.
+
+**Consumer usage (Starlark):**
+
+Consumers declare dependencies in their manifest:
+```json
+{ "dependencies": { "gitea-client": ">=1.0.0" } }
+```
+
+Then load at runtime:
+```python
+gitea = lib.load("gitea-client")
+repos = gitea.get_repos(conn)
+```
+
+`lib.load()` validates the dependency record, loads the library's script
+with the library's own permissions, extracts the declared exports, and
+returns them as a frozen struct. Results are cached per invocation.
+
+**Admin endpoints:**
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/v1/admin/packages/:id/dependencies` | Libraries this package depends on |
+| GET | `/api/v1/admin/packages/:id/consumers` | Packages that depend on this library |
+| GET | `/api/v1/admin/dependencies` | Full dependency graph |
+
+**Uninstall protection:** Libraries with active consumers return 409 on delete.
+
+---
+
 ### Builtin Seeding
 
 On startup, `SeedBuiltinExtensions()` scans `extensions/builtin/`

docs/ROADMAP.md

@@ -281,7 +281,7 @@ See design docs for full specifications.
 |---------|---------|------------|
 | v0.38.0 ✅ | Multi-file Starlark | [DESIGN-MULTI-FILE-STARLARK.md](DESIGN-MULTI-FILE-STARLARK.md) — `load()` support, disk-based scripts, package-scoped loader. Prerequisite for libraries. 5 backend changesets. |
 | v0.38.1 ✅ | Extension Connections | [DESIGN-EXT-CONNECTIONS-LIBRARIES.md](DESIGN-EXT-CONNECTIONS-LIBRARIES.md) Part 1 — `ext_connections` table, scoped CRUD (personal → team → global resolution), `connections` Starlark module, 3 management UIs. |
-| v0.38.2 | Library Packages | Part 2 — `library` package type, `ext_dependencies` table, `lib.load()` with per-library permission context, dependency resolution, uninstall protection. |
+| v0.38.2 ✅ | Library Packages | Part 2 — `library` package type, `ext_dependencies` table, `lib.require()` with per-library permission context, dependency resolution, uninstall protection, `test-tool` admin endpoint. 8+3 SDK runner tests. |
 | v0.38.3 | Extension Config Sections | Manifest-driven `config_section` — packages declare a Preact component that the Settings/Admin surfaces discover and lazy-load as a nav section. Enables headless extensions (no surface) and libraries to own their configuration UX. Libraries can provide rich config for their connection types (OAuth flows, test buttons, pickers). |
 | v0.38.4 | Full Composition | Part 3 — Libraries declare connection types for consumers, reference `gitea-client` library. |
 | v0.38.5 | Git-board Rewrite | Capstone validation — rewrite git-board as multi-package, multi-platform extension (Gitea/GitLab/GitHub). Proves the entire extension architecture works end-to-end. Reference implementation for future extension authors. |