@skillsmith/core 0.11.4 → 0.11.6

package/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to `@skillsmith/core` are documented here.
 
 ## [Unreleased]
 
+## v0.11.6
+
+- **Fix**: Harden manifest concurrency (uninstall lock, temp-file races) (#2331)
+- **Fix**: code-review follow-up on the Antigravity `directory-package` companion-agent path (two BLOCKING findings). (1) `resolveCompanionAgentPath()` gains an explicit 3rd `baseDir` param (default `process.cwd()`) instead of letting Antigravity's relative `dir` resolve implicitly against whatever `process.cwd()` happens to be at the exact `fs` call that consumes the path — wrong for the long-running MCP server, whose cwd is fixed at launch and does not track the calling editor/agent's real project. `writeInstallFiles()` gains a matching optional `companionBaseDir` param, threaded through both its callers (`SkillInstallationService.install()` via a new `companionBaseDir` constructor param, and `installFromContent()`); the MCP `install_skill` tool gains an optional `cwd` input field passed through as `companionBaseDir` so a caller can supply its real project root. (2) `resolveCompanionAgentPath()`'s `directory-package` branch now rejects an unsafe `skillName` (`''`, `'.'`, `'..'`, or containing `/`/`\`) before building the path — `skillName` becomes its own path segment in this mode, so `'..'` would otherwise `path.join`-normalize outside the intended companion-agent directory. Not exploitable through either current caller (both already sanitize `skillName` upstream), but the function is exported/reusable with no validation of its own, so it now enforces the same "last line of defense" standard already applied to `skillNameFromSkillId()` (SMI-5982)
+- **Feature**: `antigravity` is now a real `ClientId` (`install/paths.ts`) — `CLIENT_NATIVE_PATHS['antigravity'] = ~/.gemini/config/skills`, un-deferred from `compatibility/slugs.ts`'s `BROWSE_ONLY_SLUGS` (which now only contains `gemini`), and given its own `CLIENT_TO_COMPATIBILITY_SLUG` entry. `CompanionAgentTarget.fileMode` gains a second value, `'directory-package'` (Antigravity only today) — a per-skill subdirectory `<dir>/<skillName>/agent.md`, instead of every other client's flat `<dir>/<name>-suffix.md`; `resolveCompanionAgentPath()` is now mode-aware. Antigravity's companion-agent output is project-scoped (`.agents/agents/<name>/agent.md`, relative to the invocation directory) — this CLI has no existing global-vs-project install-mode distinction to hook into, confirmed by grep, so global scope (`~/.gemini/config/agents/`) is a fast-follow, not implemented here (SMI-5982)
+- **Fix**: `writeInstallFiles()`'s rollback path could leave behind an orphaned, empty per-skill companion-agent directory when a new `directory-package`-mode install (Antigravity) failed partway through — every other client's agents dir is shared and pre-existing, so this hazard never applied to them. Cleanup uses a non-recursive `rmdir`, a safe no-op when the directory was never created or holds unexpected surviving content (SMI-5982)
+- **Fix (BLOCKING, PR-review follow-up)**: the prior `resolveCompanionAgentPath()` fix's `baseDir: string = process.cwd()` default only closed the cwd-dependence bug for the ONE call site that happened to pass it explicitly (the MCP `install_skill` tool) — every other production `SkillInstallationService`/`installFromContent()` call site (7 more, audited via `grep -rn "new SkillInstallationService(" packages/`) still silently fell back to `process.cwd()`, including the private-registry `install` MCP action, which has no per-call cwd input to source a correct value from at all. `baseDir` is now **structurally required** (no default) whenever the target client's `CompanionAgentTarget.fileMode === 'directory-package'` — closing the bug class by construction for every current and future caller rather than by chasing individual call sites. `writeInstallFiles()`'s `companionBaseDir` param, `SkillInstallationService`'s constructor param, and `installFromContent()`'s param all lost their own `?? process.cwd()` fallbacks to match — an omitted value now flows through as `undefined` and fails closed with a diagnosable error (`sanitizeInstallError()`'s allowlist extended to surface it) instead of resolving against the wrong directory. The 4 CLI call sites that relied on the implicit default (`install`, `registry-install`, interactive `search`, `update`) now pass `companionBaseDir: process.cwd()` explicitly, restoring their exact prior behavior (SMI-5982)
+- **Fix**: `ManifestManager` (`services/skill-manifest.ts`) had two concurrency gaps in the skill
+  manifest write path. `performUninstall()` (`skill-installation.helpers.ts`) loaded the manifest,
+  mutated an in-memory snapshot, and saved it back directly, bypassing the lock/`updateSafely()`
+  mechanism the install path uses — a concurrent update to an unrelated entry in that window could
+  be silently overwritten. `save()` also computed its temp filename from just the process id, so
+  two concurrent saves in the same process could collide on the same temp path. Uninstall now
+  routes its final mutation through `updateSafely()`, and both `save()` and the CLI's separate
+  manifest writer now suffix the temp filename with a random UUID, with best-effort cleanup on
+  failure. `load()` also now distinguishes a missing manifest file (returns empty, expected) from
+  one that exists but is corrupt/unreadable (throws, instead of silently returning empty and
+  risking a subsequent save erasing real state) (SMI-6007).
+- **Fix**: `runMigrations()`/`runMigrationsSafe()` (`db/migration-runner.ts`) had an unguarded
+  concurrent-migration race — two processes opening the same fresh DB at the same time could both
+  read the same `currentVersion`, both apply the same migration, and the loser's plain
+  `INSERT INTO schema_version` throw `UNIQUE constraint failed: schema_version.version`. Both now
+  use `INSERT OR IGNORE`, matching the existing v1-stamp hardening in `initializeSchema()`
+  (`schema.ts`, SMI-4486) that was never extended to per-migration inserts. Found via a flaky
+  `startup-probe.test.ts` failure traced to a real production race, not test-only flakiness
+  (SMI-6003).
+- **Changed (breaking)**: `SearchResponse.compatibilityHidden` renamed to
+  `compatibilityDeprioritized` — the compatibility filter is now a ranking signal, not a hard
+  exclusion (SMI-5929), so results are never actually "hidden" by it anymore; the renamed field is
+  precisely the count of other-tool-only results present on the *returned page*, not a corpus-wide
+  or pre-page count. `SearchOptions` gains a new optional `compatibility?: string[]` field —
+  `SkillsmithApiClient.search()` forwards it to the `skills-search` edge function as a
+  `compatibility` CSV query param (previously never sent by any caller), letting the API rank
+  results server-side, before the page is cut to the requested `limit`.
+- **Fix**: companion-subagent files (the `-specialist.md` shim generated alongside an installed
+  skill) were always written to `~/.claude/agents/`, regardless of which client the skill itself
+  was installed for — a skill installed with `--client cursor` or `SKILLSMITH_CLIENT=cursor`
+  still got its companion subagent dropped into Claude Code's own agent directory instead of
+  Cursor's. New `COMPANION_AGENT_TARGETS` map (`@skillsmith/core/install/paths`) plus
+  `getCompanionAgentTarget()`/`resolveCompanionAgentDir()`/`resolveCompanionAgentPath()` give each
+  `ClientId` its own companion-agent directory and filename pattern, sourced from the same
+  evidence table already used for skill install paths; clients with no independently-verified
+  agents-dir convention default to today's existing `~/.claude/agents/` behavior rather than
+  guessing (GH #2161)
+- **Fix**: new shared `extractContextWords()` (`services/context-words.ts`, exported from the package root) replaces a `.filter((w) => w.length > 3)` threshold both `@skillsmith/mcp-server`'s `skill_recommend` and `@skillsmith/cli`'s `recommend --context` used independently — it was silently dropping real short technical terms ("git", "ci", "aws", "sql", "k8s") from the recommendation stack, tripping the empty-stack guard even when usable context was supplied (SMI-5986)
+- **Fix**: `SqlJsDatabaseAdapter.persist()` (`db/drivers/sqljsDriver.ts`) now writes the exported database buffer atomically — to a temp file, then `renameSync` over the target — instead of a direct `writeFileSync` that truncates the file before the new bytes land. A process kill mid-write (OOM, SIGKILL, machine sleep) could previously leave a 0-byte `skills.db` on disk. `openDatabaseAsync()` (`db/schema.ts`) also now distinguishes a genuinely empty/corrupt database (zero tables) from a real legacy import (has tables, just missing `schema_version`), failing loudly with remediation for the former instead of silently stamping `schema_version=1` and running every migration against a schema that was never created — which previously crashed server startup with an opaque `no such table: skills`/`no such table: cache` error and no actionable diagnostic (SMI-5997)
+
+## v0.11.5
+
+- **Cadence**: Mechanical cadence alignment (no changes since v0.11.4).
+- **Fix**: `SkillsmithApiClient.toSkill()` (`api/client.ts`) no longer hardcodes `riskScore: null, securityFindingsCount: 0, securityScannedAt: null, securityPassed: null` for every API-sourced skill — it now derives real values from the same `security_score`/`quarantined`/`last_scanned_at`/`security_findings` fields already present on the API response, via a new shared `deriveSecuritySummaryFromApiSkill()` (`api/security-summary.ts`, exported from the package root). This was why CLI `info`/`search` could show "Not scanned" for a skill MCP correctly reported as passed — both surfaces now derive from one implementation instead of two independently-maintained copies (formerly `packages/mcp-server/src/utils/security-summary.ts`, moved here so it can't re-diverge) (SMI-5897)
+- **Fix**: two local-DB-path call sites in `@skillsmith/mcp-server` (`search.helpers.ts`'s `mapLocalSkillToSearchResult`, `get-skill.ts`'s local-DB branch) were still building a `security: { passed: null, riskScore: null, findingsCount: 0, scannedAt: null }` placeholder object unconditionally for never-scanned skills, instead of returning `undefined` — violating the same never-scanned contract the API-path fix above already enforced. New sibling `deriveSecuritySummaryFromSkillRow()` (`api/security-summary.ts`, exported from the package root) covers the pre-computed local-DB field shape (`securityPassed`/`riskScore`/`securityFindingsCount`/`securityScannedAt`, as opposed to the API row's raw `last_scanned_at`/`quarantined`/`security_score`/`security_findings` columns); `recommend.helpers.ts`'s pre-existing correct-but-duplicated inline ternary for this same shape now also calls it, so all three call sites share one implementation (SMI-5897)
+- **Fix**: `SKILLSMITH_QUIET` now also suppresses `db/createDatabase.ts`'s WASM-SQLite-driver fallback notice (previously printed unconditionally, at least once per process, regardless of the env var) — this was a second, unguarded warning path in the same class C-18/C-19 fixed for the embedding-load-failure warning. The shared `isQuietModeEnabled()` guard moved from an embeddings-internal module to `utils/quiet-mode.ts` (not part of the package's public export surface) so the db layer doesn't reach into the embeddings layer for a generic env-var check; `probeEmbeddingCapability()` (`embeddings/probe.ts`) and `EmbeddingService.loadModel()`'s fallback warning (`embeddings/index.ts`) continue to share the same implementation from its new location (SMI-5897)
+- **Feature**: `SkillInstallationService.installFromContent()` — installs a skill from already-resolved `{skillId, version, content}` (no GitHub fetch), reusing the existing disk-write path (`writeInstallFiles()`) so private-registry-sourced skills go through the same scan/write/manifest pipeline as a GitHub-fetched install. Scans at `community` trust tier. `writeInstallFiles()` also gains `ensureDirNoFollow()`/`mkdirNoFollow()`: every intermediate path segment of a nested sub-skill filename (e.g. `scripts/run.sh`) is now created symlink-safely, closing a path where a pre-existing symlinked intermediate directory could redirect a write outside the install path, and fixing a prior functional gap where a nested filename's parent directory was never created at all (SMI-5905)
+- **Feature**: `resolveFreshAccessToken()` (`api/client.token-refresh.ts`) — shared JWT-refresh helper extracted for reuse by both the MCP server and CLI's private-registry transports (SMI-5905)
+- **Feature**: `getPrivateRegistrySkillContent()` (`api/client.private-registry.ts`) — the CLI's only transport to `private_registry_skills` content, calling the new `private-registry-get` Edge Function under the signed-in user's own JWT; never carries Supabase credentials directly (SMI-5905)
+- **Feature**: new `resolveSkillApiFirst()` (`@skillsmith/core/services/skill-resolution`) extracts the API-first/local-DB-fallback skill resolution `get_skill` already used into a shared helper, now also used by MCP's `skill_compare` — which previously only ever queried the local SQLite cache and, per SMI-5427, that cache is no longer kept in sync with the remote-first registry, so a real, searchable skill was often reported "not found" by compare alone. Also adds `buildEmptyStackGuidance()` (`@skillsmith/core/services/recommend-guard`), the shared empty-derived-stack guidance text used by both CLI `recommend` and MCP `skill_recommend` (SMI-5896)
+- **Change**: `hashContent` and `manifestKeyFor` are now re-exported from the package root (`@skillsmith/core`) alongside the existing `@skillsmith/core/services/skill-installation-helpers` subpath, so callers outside `core` can reach them through the specifier they already import. Additive — the subpath export is unchanged (SMI-5895)
+- **Feature**: new two-level owned-lock primitive at `@skillsmith/core/config/owned-lock` (`acquireOwnedLock`) replacing the single-level, age-based `acquireConfigLock` (which `config-atomic-write.ts` now implements as a thin wrapper over it). The single-level design was unsound under review: it turned "I inspected this path and concluded the holder is dead" into an unconditional destructive unlink with no mutual exclusion against another reclaimer doing the same. The new design adds a second, strict-never-auto-reclaimed reclaim lock that serializes every reclaim decision, so the authorization to reclaim can no longer go stale between being computed and being consumed. Ownership is verified on release (a token, not just file presence); ships with `StuckLockError` naming a stable `reason` for mechanical triage plus the manual-unstick procedure. Opt-out: `SKILLSMITH_LOCK_NO_AUTO_RECLAIM=1` (SMI-5883)
+
 ## v0.11.4
 
 - **Fix**: Evidence-tier severity for jailbreak/ai_defence findings (#2120)

package/README.md

@@ -1,21 +1,24 @@
 # @skillsmith/core
 
-Core library for Skillsmith - provides database operations, search services, caching, security, analytics, and **multi-language codebase analysis** for agent skill discovery.
+Core library for Skillsmith — database operations, search, caching, security, analytics, and **multi-language codebase analysis** for agent skill management.
+
+Part of Skillsmith: a lifecycle layer for agent skills across teams.
 
 ## Contents
 
-- [What's New](#whats-new-in-v0112)
+- [What's New](#whats-new-in-v0116)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Features](#features)
 - [Exports](#exports)
 
-## What's New in v0.11.2
+## What's New in v0.11.6
 
-- **Cross-session rename revert**: `apply_namespace_rename`'s `action: 'revert'` is now exposed, and `JournalAction`/`JOURNAL_SCHEMA_VERSION` are widened so an older reader no longer flags a legitimate revert journal record as corrupt.
-- **Unified shutdown coordinator**: Awaitable sync stop consolidates shutdown handling across the database and background writers.
-- **Production-grade error logging and diagnostics**: Structured error logging and diagnostics for easier triage in production.
-- **Dependency backfill**: `skill_dependencies` now backfills correctly for installs that predate v0.7.1.
+- **Security-status reporting unified**: CLI and MCP now derive security-scan status (pass/fail, risk score, findings count) from one shared `deriveSecuritySummaryFromApiSkill`/`deriveSecuritySummaryFromSkillRow`, instead of two independently-maintained copies that could disagree on the same skill.
+- **`skill_compare` reuses `get_skill`'s resolution**: new shared `resolveSkillApiFirst()` fixes compare only ever hitting the local SQLite cache (no longer kept in sync with the remote-first registry), which made real, searchable skills report "not found."
+- **New two-level owned-lock primitive** (`config/owned-lock`) replacing the single-level, age-based config lock — closes a case where two concurrent reclaimers could both treat a stale lock as safe to unlink.
+- **Private-registry install support**: `SkillInstallationService.installFromContent()` installs an already-resolved skill (e.g. from a private registry) through the same scan/write/manifest pipeline as a GitHub-fetched install.
+- **Quiet mode covers one more warning path**: `SKILLSMITH_QUIET` now also suppresses the WASM-SQLite-driver fallback notice, previously printed unconditionally.
 
 See [CHANGELOG.md](./CHANGELOG.md) for previous releases.