simple-skills-manager 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Changelog
+
+## 1.0.1
+
+Quality pass — bug fixes and hardening, no config or manifest format changes.
+
+- Fixed the directory import flow: when the picked `SKILL.md` was nested,
+  the whole import source was copied instead of the skill's own directory,
+  so the copy never contained a root-level `SKILL.md` and the flow always
+  failed. The copy now starts at the chosen skill directory, and the
+  pre-read of its `SKILL.md` is size- and symlink-guarded.
+- The tree (and root details) no longer crash on a root whose `${...}`
+  path template cannot be resolved: labels, mirror checks, and exposure
+  counts fail closed to zero/unmirrored instead of throwing.
+- Scan hygiene: root-level `.md` files are size-checked via `lstat` before
+  being read (a giant file no longer loads into memory first), the shebang
+  inventory reads only the first two bytes of each file instead of whole
+  files (skill directories may contain large assets), and the root-level
+  inventory runs once per scan instead of once per root-level file.
+- `copyTreeInto` counts every filesystem entry against `maxScanFiles`
+  (previously only directories were counted).
+- Drift/manifest-miss at invocation now evicts the cached scan, so a fixed
+  skill works on the next call without a reload.
+- `promptGuidelines` are no longer duplicated once per exposed skill tool;
+  the shared awareness lines ride on the first registered tool and every
+  tool gets a guideline that names it (pi's flat-guidelines requirement).
+- The truncation marker now lands inside the `maxResultBytes` budget.
+- Editing a root-level `.md` store skill keeps its instruction file name
+  (the refreshed snapshot no longer falls back to `SKILL.md`); removing
+  one deletes its file instead of refusing with a wrong message.
+- Tree QoL: unchecking every skill disables the root (an enabled root with
+  an empty selection registered nothing anyway); Enter on a group row
+  folds it; the rejected-directory suppression no longer swallows sibling
+  directories that share a name prefix.
+- Cleanup: shared `writeFileAtomic` reused by `writeConfigText`, static
+  imports in `util.ts`, duplicate `NAME_RE` removed, `addRoot` reuses
+  `isNativePath` (templates now recognized), magic literals replaced with
+  the exported limits, raw `scannedAt` sanitized for display, and the
+  exposure list in the awareness line is capped.
+- New smoke regressions, each failing against the exact bug above:
+  template-root tree resilience, snapshot file-name preservation, and the
+  copyTreeInto entry budget.
+
+## 1.0.0
+
+Initial release.
+
+- Single-file configuration: every library root (the registrar), approved
+  skill manifest, and extension setting lives in
+  `~/.pi/agent/simple-skills-manager.json` (JSONC; auto-created with
+  commented defaults and a seeded store root on first run; the store
+  directory `~/.pi/agent/managed-skills` is created alongside).
+- Vocabulary: the *library* is all known skills; the *registrar* is the
+  corpus of directory roots, displayed flat in the TUI; the *store* is the
+  built-in root skills accumulate in.
+- `/skills-manager` TUI: a tree navigator (roots → groups → skill leaves
+  with spacebar exposure checkboxes; Enter on a root opens its actions:
+  bulk enable/disable, scan-or-refresh, remove), adding skills to the store
+  (editor / .md import / wholesale directory import with an interactive
+  SKILL.md picker), adding roots (guided skills-dir, single-skill), the
+  scan-and-approve ceremony (which is also the adoption path for native
+  locations), per-skill edit (auto re-approval) and removal (store only),
+  root removal (unregister only), and extension settings (view, edit the
+  raw config file, reset to defaults).
+- Groups as subdirectories: the first path segment under a root is the
+  display group — no group config, re-tagging is a directory move plus a
+  scan.
+- Approval workflow: scans snapshot each skill's name, description, group
+  path, file inventory, executable-script flags, and a SHA-256 content
+  hash; the manifest is fingerprinted to the root identity. Drift between
+  the approved hash and the delivered bytes fails closed on every
+  invocation; changing the root path invalidates the manifest.
+- Lazy loading: a root is never scanned merely because pi starts; the
+  first approved invocation opens the scan (cached per session).
+- Exposure surfaces: namespaced tools `skill_<root>__<skill>` (bounded,
+  sanitized, collision-checked, hidden skills excluded) with prompt
+  snippets and harness awareness lines, plus `skill:<name>` extension
+  commands that shadow pi's native skill-command namespace, dispatch
+  before native expansion, load through the same drift-checked path, and
+  appear in the live autocomplete dropdown with group paths.
+- Auto-adoption of native pi locations (`~/.pi/agent/skills`,
+  `~/.agents/skills`): existing directories are seeded into the registrar
+  automatically — disabled, unapproved, flagged — and rendered in the tree
+  with their natively-live skills as red unapproved-but-live leaves.
+  "Scan or refresh" adopts them; auto-detected roots cannot be dismissed
+  (they are real exposure) and are persisted to the file only once a save
+  blesses them. Mirroring registers nothing by itself: an auto-detected root
+  is disabled with no manifest.
+- Path hygiene: `${workspace}`/`${home}`/`~` expansion, symlinked roots
+  and skills fail closed, scan budgets (entries, depth, per-file sizes),
+  mutable-location warnings, duplicate-name rejection with first-wins.
+- Settings knobs: `maxResultBytes`, `maxResultLines`, `maxSkills`,
+  `toolNameLimit`, `maxSkillBytes`, `maxScanFiles` — all editable from the
+  TUI or the file.
+- Smoke test covering both transports, validation invariants, single-file
+  discovery, per-entry isolation, lazy registration (tool registered
+  while its directory does not exist), native-tool preservation, command
+  registration, native mirror computation, and first-run starter creation,
+  plus regression suites for name-length invariants, malformed-manifest
+  safety, scan budget/maxSkills enforcement, and pathological sources.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The simple-mcp-manager authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# simple-skills-manager
+
+A [pi](https://github.com/earendil-works/pi-mono) extension for exposing
+**reviewed** skills to the model — with a scan-approval workflow, content
+hashes that fail closed on drift, a tree navigator for the whole library,
+and an honest mirror of pi's own native skill discovery.
+
+One file, one command. Everything — library roots (the *registrar*),
+approved skill manifests, and extension settings — lives in
+`~/.pi/agent/simple-skills-manager.json`, and everything is manageable from
+the `/skills-manager` TUI. Skills themselves are plain files: the built-in
+*store* accumulates them at `~/.pi/agent/managed-skills`, and existing or
+native directories are adopted without moving anything.
+
+---
+
+## Why this exists
+
+pi already has native skills: drop a folder in `~/.agents/skills/` and pi
+exposes it. Native discovery has zero ceremony — which is exactly the
+point of divergence. A skill is **untrusted instructions the model will
+follow, plus scripts it may execute, with your user permissions.** Native
+pi's answer to "is this skill safe to expose?" is *"it's on your disk, so
+yes."*
+
+**"A skill is on your disk" never silently means "the model follows it."**
+This extension keeps three decisions separate, on purpose:
+
+1. **Configuration** — where a root is and how the library is scanned.
+2. **Manifest approval** — which skill names, descriptions, and content
+   hashes a human actually inspected, fingerprinted to the exact root.
+3. **Invocation** — whether the model may load a particular skill right now.
+
+If you wrote every skill yourself and trust your own directories, native
+pi is fine — this extension is opt-in governance for when the collection
+grows, comes from third parties (Anthropic skills, pi-skills, Claude/Codex
+imports), or you simply want to see and control what every chat is being
+influenced by.
+
+## What it adds over native pi skills
+
+| | Native pi skills | simple-skills-manager |
+|---|---|---|
+| Exposure gate | On disk → in every chat's system prompt at next startup. Zero ceremony. | Scan → approve (fingerprint-bound) → expose. |
+| Content drift | Silent. | Hash-bound approval; changed content **fails closed** at invocation until re-approved. |
+| Per-skill control | Minimal (frontmatter flag). | Tree navigator with spacebar exposure checkboxes, enable/disable, live state. |
+| Management UI | None. | `/skills-manager`: grouped tree, rendered skill view, metadata (hash, file inventory, executable-script warnings), edit-in-place, remove, imports. |
+| Invocation | `/skill:name` (user), read-on-demand (model). | Same `/skill:name` syntax (shadowed, drift-checked) **plus** namespaced tools the model calls; live autocomplete dropdown carries group paths. |
+| Delivery hygiene | Raw file content. | Sanitized, bounded, collision-checked names (`skill_<root>__<skill>`), harness awareness lines. |
+| Laziness | Frontmatter read for every chat at startup. | The root is not scanned until an approved skill is invoked. |
+
+## Quick start
+
+Inside pi:
+
+1. Run `/skills-manager` — a starter config and the store
+   (`~/.pi/agent/managed-skills`) are created on first run.
+2. **Add a skill to the store**: write one in the editor, import an `.md`
+   file, or import a whole directory (if it has no `SKILL.md`, the TUI
+   prints its tree and asks which one it is).
+3. Or **Add or import a library root**: point at any skills directory or a
+   single skill. Native pi locations need no adding — they appear
+   automatically when they exist.
+4. The **scan ceremony** shows exactly what was found — descriptions, file
+   counts, executable-script warnings, rejections — and asks which skills
+   to expose.
+5. Reload. Exposed skills appear as `skill_<root>__<skill>` tools for the
+   model and `skill:<name>` commands for you.
+
+## Groups
+
+Subdirectories of the store are groups — "subdirs as automatic tagging."
+`managed-skills/research/arxiv/SKILL.md` displays as `research / arxiv` in
+the tree; move the directory and it re-tags on the next scan. No group
+config exists anywhere.
+
+## The tree navigator
+
+`/skills-manager` → *Open the library tree*: every root sits flat at the
+top level (store first, auto-detected native roots included), groups nest
+beneath, skills are leaves with `[√]`/`[ ]` checkboxes. **Spacebar toggles
+exposure; unchecked means invisible to the model.** Enter inspects (metadata,
+live drift check, full content, edit/remove for store skills; on roots:
+overview plus bulk enable/disable, scan-or-refresh, and remove actions).
+Red `⊘` leaves are **native mirrors** — skills pi is exposing through its own
+discovery that cannot be revoked here; the footer explains how (remove the
+files, or launch `pi --no-skills`).
+
+## Native roots and the override story
+
+- **Auto-adoption.** `~/.pi/agent/skills` and `~/.agents/skills` are
+  recognized automatically: if they exist on disk, they appear in the
+  registrar on the next load — disabled, unapproved, flagged
+  "Auto-detected" — showing their natively-live skills as red unscanned
+  leaves. *Scan or refresh* is the adoption ceremony. Auto-adoption never
+  creates exposure: nothing is enabled, approved, or even scanned without
+  an explicit act.
+- **Command layer — fully ours.** Every exposed skill registers a
+  `skill:<name>` *extension* command; extension commands dispatch before
+  pi's native skill expansion, so the namespace is shadowed, with drift
+  checking pi doesn't have. The live autocomplete dropdown narrows as you
+  type, with `group/skill` paths in the descriptions.
+- **Discovery layer — not overrideable by an extension.** If files sit in
+  `~/.pi/agent/skills/` or `~/.agents/skills/`, pi *will* list them in the
+  system prompt. The manager is the honest mirror: auto-detected roots
+  render their skills red and locked in the tree, drift-checked on our
+  surfaces, with unapproved-but-live skills visible.
+- **Library-only mode — the full takeover:** launch `pi --no-skills` and
+  native discovery stops entirely. The mirror rule finds nothing, native
+  roots become fully gated, and the manager is the *sole* skills surface.
+  (The extension detects and displays which mode is live in the tree
+  footer.)
+
+## Security model
+
+Skills instruct the model and may include code it executes with your
+permissions. Permission prompts are not an OS sandbox. This extension's
+boundaries:
+
+- scanning is read-only and bounded (file counts, depth, per-file sizes);
+- symlinks fail closed (roots and skills); nothing is ever executed;
+- exposure requires an approved manifest, and every invocation re-hashes the
+  **bytes being delivered** against the approval — drift fails closed;
+- the manifest fingerprint binds the approval to the exact root
+  (name/transport/path) — move it and the approval is void;
+- helper scripts are inventoried and shebang files flagged at inspection
+  (their content is not hash-bound; re-scan before trusting — same posture
+  as an MCP server whose code may change under bound schemas);
+- skill text is sanitized and size-bounded on delivery;
+- external and native roots are read-only to the manager; store deletions
+  are constrained to `managed-skills/`;
+- hidden skills (`disable-model-invocation`) are command-only, mirroring
+  pi's semantics.
+
+Review skill content; pin or vendor third-party skills; use a container or
+VM when you need real isolation.
+
+## Testing
+
+No external model or untrusted network calls — local fixtures only:
+
+```bash
+npm run typecheck   # tsc --noEmit
+npm test            # tests/smoke.sh
+```
+
+The smoke test exercises both transports end-to-end (discovery, grouping,
+script flagging, rejections), validation invariants, config save/load
+round-trips (upsert, remove, settings fallback, loud failure on a corrupt
+file), manifest fingerprint binding, the full registered-tool execute path
+(lazy scan at first call, reuse, fail-closed content drift), managed
+discovery through pi's normal extension loading (per-entry isolation,
+lazy registration against a *nonexistent* directory, native-tool
+preservation, `skill:<name>` command registration), native mirror
+computation, and first-run starter creation. Dedicated regression suites
+cover the registered-name length invariant, defensive handling of a
+malformed approved manifest, scan-budget and maxSkills enforcement,
+pathological-source survival, copy-budget and snapshot file-name
+invariants, and tree resilience against an unresolvable root-path
+template — each verified to fail against the exact bug it guards.
+
+## License
+
+[MIT](./LICENSE)