@skillsmith/core 0.11.3 → 0.11.5

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to `@skillsmith/core` are documented here.
 
 ## [Unreleased]
 
+## 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)
+- **Fix**: `escalateCodeExecution` (`security/scanner/SecurityScanner.exec.ts`) now only escalates a `code_execution` finding to `critical` when its corroborating jailbreak/prompt-injection finding is within 40 lines of it, matching the locality bound already applied to `escalateCorroboratedMentions` (SMI-5876) — previously it escalated on any same-file match regardless of distance, the same false-positive class SMI-5876 fixed for the sibling mechanism. Fail-closed: a missing line number on either side still escalates (SMI-5880)
+- **Fix**: `AD_CRLF_INJECTION` (`security/scanner/patterns.jailbreak.ts`) no longer has catastrophic-backtracking behavior — a live, exploitable production denial-of-service reachable through the public `SecurityScanner.scan()` API with no crafted payload (an ~80-byte adversarial CRLF-repeat input hung a scan for hours). The regex is rewritten with a negative lookbehind instead of an ambiguous `(?:\r\n|\r|\n){2,}` quantified alternation, verified match-language-equivalent to the old pattern (22-case fixture table + 20,000-case randomized differential fuzz, zero mismatches). Introduces a `PatternScope` model (`patterns.scope.ts`) replacing the deleted `isMultilinePattern()` source-sniffing heuristic, which was wrong in both directions (missed genuinely cross-line patterns using a bounded `[\s\S]{0,N}` class with no literal `\r`/`\n` in its source; misclassified patterns using a negated newline-excluding class as multiline anyway) — scope is now an explicit, fail-closed, per-pattern declaration with no silent default. Also narrows two SSRF word-boundary gaps and threads a content-length cap through the multiline scan passes to bound worst-case regex cost. `SCANNER_RULESET_VERSION` bumped (SMI-5881)
+- **Fix**: jailbreak/`ai_defence` findings in `SecurityScanner` now carry an evidence tier (`mention`/`role_turn_with_body`/`imperative_instruction`/`instruction_override`/`state_assertion`) instead of a flat doc-context severity pair, closing a false-positive class where a skill that *documents* jailbreak/prompt-injection patterns defensively (a security-checklist skill, Skillsmith's own bundled SKILL.md, `find-skills`) scored identically to skills containing an actual attack payload — reported via third-party UAT feedback. Bare vocabulary mentions ("jailbreak", "DAN", a role-marker with no body) are capped at `low` severity in any context; genuine imperative/override/state-assertion payloads still reach `critical`/`high` even inside a fenced documentation example (documentation context is evidence, not an exemption). `JAILBREAK_PATTERNS` gains 8 new patterns (activation/persona frames, declarative jailbroken-state assertions, an obedience-compulsion pattern) closing false-negative gaps opened by demoting the bare mentions; `AI_DEFENCE_PATTERNS` gains 4 new patterns closing an equivalent gap for role-marker-plus-injected-body attacks the prior single pattern could not match on the same line. A `mention`-tier finding can still escalate to `high` when corroborated by an allowlisted, non-documentation, high/critical instruction-bearing finding (`code_execution`/`obfuscated_directive`/`data_exfiltration`/`privilege_escalation`/`ssrf`) within 40 lines. `scan()`'s `passed` expression is unchanged — the evidence tier carries the fix, not a new veto path (SMI-5876)
+- **Fix**: `scanPiiPatterns`'s author-contact-email severity exemption now recognizes a markdown list bullet/numbering/blockquote/emphasis before the `author:`/`contact:`/`support:`/`email:`/`maintainer:` label (e.g. `- Email: support@skillsmith.app`) — previously only an unbulleted `Email: ...` line qualified, so a "Getting Help" section's contact bullet scored `high` PII severity purely from markdown list syntax (SMI-5876)
+- **Refactor**: `scanPrivilegeEscalation` (`security/scanner/SecurityScanner.scanners.ts`) drops an unnecessary `as RegExp[]` type assertion on its `CREDENTIAL_SUBSTITUTION_PATTERNS.includes(pattern)` check (SMI-5833/SMI-5838 pattern-identity lookup) — TypeScript already infers the correct type without it; no behavior change
+
+- **Fix**: `scanPrivilegeEscalation` (`security/scanner/SecurityScanner.scanners.ts`) now caps severity at `medium` for the two credential-substitution `PRIVILEGE_ESCALATION_PATTERNS` entries added in SMI-5833 (split out as `CREDENTIAL_SUBSTITUTION_PATTERNS` in `patterns.ts`, identified by reference), instead of the usual `high`/`critical` — the pattern pair is purely lexical and can false-positive on benign dev/test troubleshooting text carrying both required signals (e.g. "get around the 403 in local testing... mock token instead of your expired token"). Detection is unchanged; a match still surfaces as a finding for review, it just no longer blocks a skill install the way `critical`/`high` does (SMI-5838)
+- **Fix**: `PRIVILEGE_ESCALATION_PATTERNS` (`security/scanner/patterns.ts`) gains two new contextual entries detecting credential/auth-level substitution used to defeat an auth check (e.g. "use the service_role key instead of your admin JWT to bypass the 403") — closes a double-miss where this exact phrasing, grammatical and lexically benign, slipped past both the internal SecurityScanner and AIDefence during a real staged-payload hardening pass (SMI-5833)
+- **Fix**: `__resetLoggingStateForTests()` (`logging/rotation.ts`, test-only helper) now awaits every surface's pending write queue before closing streams and clearing state, instead of detaching it. `writeLogLine` is fire-and-forget by design; under I/O contention a write could still be queued when a test's cleanup ran, and since `resolveStream` reads `SKILLSMITH_LOG_DIR`/in-memory state live (not snapshotted), that orphaned write could land in a *later* test's fresh temp directory — a stray record (missing that later test's own fields) could then be the first line read back, failing an unrelated assertion. Reproduced under combined CPU+disk contention; never in isolation (SMI-5837)
+- **Fix**: `checkForModifications()` (`services/skill-installation.io.ts`) now tolerates up to 2 seconds of clock skew between a skill's `installDate` and its on-disk mtime, instead of a strict `mtime > installDate` comparison — closes a race where `install()`'s `writeInstallFiles()` timestamp and its later `installedAt` capture could disagree by a few milliseconds under load, causing `uninstall()` to spuriously report the skill as locally modified and fail (SMI-5828)
+- **Feature**: `sha256Hex` (`journal/hash.ts`) exposed from the package root — one shared content-hash implementation for every `content_hash` computation (public inventory, private registry) instead of independent inline `createHash('sha256')` copies that could silently drift. `sync/inventory-collector.ts` switched to it (SMI-5816)
+- **Feature**: `logging/types.ts`'s `Surface` union gains `'doc-retrieval'`, and `logging/rotation.ts`'s `getLogDir()` gains a `SKILLSMITH_STATE_DIR_OVERRIDE` precedence tier (checked after the existing `SKILLSMITH_LOG_DIR` test seam, before the `homedir()` fallback) — lets the doc-retrieval reindex CLI's structured logs land on a Docker-bind-mounted, host-visible path instead of the container's own throwaway filesystem (SMI-5793)
+
 ## v0.11.3
 
 - **Chore**: Migrate remaining stale references to ruflo v3 (#1952)
@@ -140,7 +169,10 @@ All notable changes to `@skillsmith/core` are documented here.
 
 ## v0.5.4
 
-- **Fix**: rename webhook-dlq /retry → /resolve with migration 077 (SMI-4308) (#647)
+- **Feature**: Webhook dead-letter queue — new `WebhookDeadLetterRepository`, optional `deadLetterSink` on `WebhookQueueOptions`, and `webhook-dlq` authenticated edge function (SMI-4291, closes GitHub #601)
+- **Fix**: `WebhookDeadLetterRepository` gains `markResolved(id, resolvedBy?)` for operator acknowledgement and renames `listUnretried` → `listOpen` (the in-process filter now excludes both retried and resolved rows); `listUnretried` kept as a deprecated alias, removed when SMI-4322's delivery worker lands; repository types add `resolved_at` / `resolved_by` matching migration 077; `markRetried` unchanged — dormant until SMI-4322 (SMI-4308) (#647)
+- **Fix**: RLS recursion on `teams` and `team_members` that caused 500s on `/account/team*` pages once any user had a membership row — migration 072 rewrites the two legacy policies to call SECURITY DEFINER helpers (SMI-4306)
+- **Feature**: tree-sitter incremental parsing for Python analyzer — WASM-backed (`web-tree-sitter@0.25.10`), LRU tree cache (100 entries), query-based extraction replaces regex fallback; unchanged file re-parse ~0ms (memoised), incremental edit ~60ms on 1955-line fixture (well under 100ms target), ~27,000× speedup on cache hits vs cold parse; regression guard ensures query extraction matches or exceeds prior regex coverage on all fixtures (SMI-4293, PR #633, closes #604)
 - **Feature**: team provisioning on subscription (SMI-4307) (#646)
 - **Fix**: populate UndoSnapshot.backup_path in ActivationManager (SMI-4297) (#644)
 
@@ -153,17 +185,10 @@ All notable changes to `@skillsmith/core` are documented here.
 - **Fix**: restore category/security/repo in skill detail view (SMI-4240) (#583)
 - **Other**: SMI-4190: release cadence docs — ADR-114 + CHANGELOG backfill + CONTRIBUTING (#552)
 
-## [Unreleased]
-
-- **SMI-4308**: `WebhookDeadLetterRepository` gains `markResolved(id, resolvedBy?)` for operator acknowledgement and renames `listUnretried` → `listOpen` (the in-process filter now excludes both retried and resolved rows). `listUnretried` kept as a deprecated alias; removed when SMI-4322's delivery worker lands. Repository types add `resolved_at` / `resolved_by` matching migration 077. `markRetried` unchanged — dormant until SMI-4322.
-- **SMI-4306**: Fix RLS recursion on `teams` and `team_members` that caused 500s on `/account/team*` pages once any user had a membership row. Migration 072 rewrites the two legacy policies to call SECURITY DEFINER helpers.
-- **SMI-4293**: tree-sitter incremental parsing for Python analyzer — WASM-backed (`web-tree-sitter@0.25.10`), LRU tree cache (100 entries), query-based extraction replaces regex fallback. Unchanged file re-parse ~0ms (memoised); incremental edit ~60ms on 1955-line fixture (well under 100ms target); ~27,000× speedup on cache hits vs cold parse. Regression guard ensures query extraction matches or exceeds prior regex coverage on all fixtures (PR #633, closes #604).
-- **SMI-4291**: Webhook dead-letter queue — new `WebhookDeadLetterRepository`, optional `deadLetterSink` on `WebhookQueueOptions`, and `webhook-dlq` authenticated edge function. Closes GitHub #601.
-- **SMI-4124**: `skill_pack_audit` trigger-quality + namespace collision checks (PR #505).
-
 ## v0.5.1
 
 - **Fix**: SMI-4182 suppress CodeQL false positive on telemetry hash (#550 retro).
+- **Feature**: `skill_pack_audit` trigger-quality + namespace collision checks (SMI-4124, PR #505)
 
 ## v0.4.18
 

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-v0115)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Features](#features)
 - [Exports](#exports)
 
-## What's New in v0.11.2
+## What's New in v0.11.5
 
-- **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.