@skillsmith/core 0.11.4 → 0.11.6

package/dist/src/services/context-words.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Shared context-word extraction for skill recommendations.
+ * @module @skillsmith/core/services/context-words
+ * @see SMI-5986: CLI `recommend --context` (`recommend.ts:76`) and MCP
+ *   `skill_recommend`'s `project_context` (`recommend.ts:127`) each derived a
+ *   "context words" slice for the recommendation stack via
+ *   `.filter((w) => w.length > 3)` — a bare length threshold that silently
+ *   dropped real 2-3 character technical terms ("git", "ci", "aws", "sql")
+ *   that happen to be short. When a caller's context consisted only of such
+ *   terms, the resulting derived stack was empty and the SMI-5896
+ *   empty-stack guard (`buildEmptyStackGuidance`, this module's sibling)
+ *   fired even though the caller *did* supply usable context.
+ *
+ *   Shared here (not duplicated per-twin) so CLI and MCP can't independently
+ *   drift on what counts as noise vs. a real short technical term — the same
+ *   class of duplication risk `buildEmptyStackGuidance` above already closed
+ *   for the empty-stack message itself (plan-review correction, SMI-5984
+ *   Wave 1: a bare length threshold "admits noise words" and leaves the two
+ *   twins free to drift apart again independently).
+ */
+/**
+ * Extract up to `maxWords` usable technical terms from free-text project
+ * context for the recommendation stack.
+ *
+ * Replaces the old `.filter((w) => w.length > 3)` threshold: real technical
+ * terms of 2-3 characters ("git", "ci", "aws", "sql") are now kept, while
+ * single-character tokens, punctuation-only tokens (including one that
+ * survives edge-stripping because it's made entirely of `+`/`#`, e.g. "++"
+ * or "+#" — PR review round 3, SMI-5986), and short English function words
+ * ("a", "the", "is", ...) are still dropped as noise. Words of 4+
+ * characters are unaffected — this only changes the outcome for the short
+ * end of the spectrum the length threshold got wrong.
+ *
+ * @param projectContext - Free-text project/context description. `null`/
+ *   `undefined`/empty returns `[]`, mirroring both callers' pre-existing
+ *   `if (project_context)` guard.
+ * @param maxWords - Maximum number of words to return (default 5).
+ */
+export declare function extractContextWords(projectContext: string | undefined | null, maxWords?: number): string[];
+//# sourceMappingURL=context-words.d.ts.map

package/dist/src/services/context-words.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-words.d.ts","sourceRoot":"","sources":["../../../src/services/context-words.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAmIH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CACjC,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EACzC,QAAQ,GAAE,MAA0B,GACnC,MAAM,EAAE,CAcV"}

package/dist/src/services/context-words.js

@@ -0,0 +1,178 @@
+/**
+ * @fileoverview Shared context-word extraction for skill recommendations.
+ * @module @skillsmith/core/services/context-words
+ * @see SMI-5986: CLI `recommend --context` (`recommend.ts:76`) and MCP
+ *   `skill_recommend`'s `project_context` (`recommend.ts:127`) each derived a
+ *   "context words" slice for the recommendation stack via
+ *   `.filter((w) => w.length > 3)` — a bare length threshold that silently
+ *   dropped real 2-3 character technical terms ("git", "ci", "aws", "sql")
+ *   that happen to be short. When a caller's context consisted only of such
+ *   terms, the resulting derived stack was empty and the SMI-5896
+ *   empty-stack guard (`buildEmptyStackGuidance`, this module's sibling)
+ *   fired even though the caller *did* supply usable context.
+ *
+ *   Shared here (not duplicated per-twin) so CLI and MCP can't independently
+ *   drift on what counts as noise vs. a real short technical term — the same
+ *   class of duplication risk `buildEmptyStackGuidance` above already closed
+ *   for the empty-stack message itself (plan-review correction, SMI-5984
+ *   Wave 1: a bare length threshold "admits noise words" and leaves the two
+ *   twins free to drift apart again independently).
+ */
+/** Maximum context words carried into the recommendation stack (matches both callers' pre-existing `.slice(0, 5)`). */
+const MAX_CONTEXT_WORDS = 5;
+/**
+ * Common short English function words that would otherwise pass a
+ * length-based filter and pollute the recommendation stack as noise. Kept
+ * intentionally short and grammar-only — no 2-3 letter technical acronym
+ * ("ci", "ai", "ml", "db", "os", "ui", "js", "go", "git", "aws", "sql",
+ * "cli", "api", "sdk", "css") appears here, since those are exactly the real
+ * terms this fix exists to stop dropping.
+ */
+const CONTEXT_STOPWORDS = new Set([
+    // 2-letter
+    'an',
+    'is',
+    'it',
+    'be',
+    'to',
+    'of',
+    'in',
+    'on',
+    'at',
+    'as',
+    'or',
+    'if',
+    'so',
+    'no',
+    'do',
+    'am',
+    'we',
+    'us',
+    'he',
+    'my',
+    'up',
+    // 3-letter
+    'the',
+    'and',
+    'but',
+    'not',
+    'did',
+    'has',
+    'had',
+    'she',
+    'him',
+    'her',
+    'its',
+    'our',
+    'all',
+    'few',
+    'out',
+    'off',
+    'via',
+    'per',
+    'own',
+    'too',
+    'yet',
+    'nor',
+    'you',
+    'are',
+    'was',
+    'for',
+    'may',
+    'who',
+    'why',
+    'how',
+    // Code-review correction (SMI-5986): "any" (TS/SQL keyword), "let"
+    // (JS/Rust keyword), and "can" (CAN-bus acronym) were removed from this
+    // set — each is a real technical term this fix exists to stop dropping,
+    // same class as "git"/"ci"/"aws"/"sql". Leaving them in would have
+    // contradicted this list's own documented promise above.
+]);
+/**
+ * Whether a single character counts as "keep" (not strippable edge
+ * punctuation) — see `stripEdgePunctuation`. Plain character-code range
+ * checks, not a regex — this is the actual "no regex" implementation (PR
+ * review round 3, SMI-5986): round 2's fix still called `.test()` against a
+ * single-character-class regex, which isn't the polynomial-backtracking
+ * shape CodeQL flags, but didn't match its own doc comment's "manual
+ * index-scan rather than a regex" claim either.
+ */
+function isKeepChar(ch) {
+    return (ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9') || ch === '+' || ch === '#';
+}
+/**
+ * Whether a word contains at least one alphanumeric character — used to
+ * reject punctuation-only tokens ("++", "##", "+#") that `isKeepChar` alone
+ * would let through, since `+`/`#` count as "keep" but aren't themselves
+ * usable content (PR review round 3, SMI-5986: `extractContextWords('++ ##
+ * +#')` was returning `['++', '##', '+#']` — all three passed the length
+ * filter with no alphanumeric substance at all).
+ */
+function hasAlphaNumeric(word) {
+    for (let i = 0; i < word.length; i++) {
+        const ch = word[i];
+        if ((ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9'))
+            return true;
+    }
+    return false;
+}
+/**
+ * Strip leading/trailing punctuation from an already-lowercased token
+ * without touching interior characters — "k8s" is untouched, but "git," ->
+ * "git" and "(sql)" -> "sql". Real-world context strings aren't always
+ * clean whitespace-delimited tokens (trailing commas, wrapping parens),
+ * and a stray comma would otherwise make "git," fail to match the real
+ * "git" term downstream.
+ *
+ * `+` and `#` count as "keep" characters (code-review correction, SMI-5986)
+ * — they're meaningful trailing characters in real technical terms ("c++",
+ * "c#"), not punctuation noise; stripping them turned both into the single
+ * character "c", which the length filter then discarded entirely. A
+ * punctuation-only token surviving this step (e.g. "++") is rejected
+ * downstream by `hasAlphaNumeric`, not here — this function only trims
+ * edges, it doesn't judge the result's usability.
+ *
+ * O(n), two linear index scans, no regex anywhere in the call chain
+ * (CodeQL js/polynomial-redos, SMI-5986 PR review round 2 — verified
+ * empirically, a 200k-character adversarial input runs in under 1ms).
+ */
+function stripEdgePunctuation(word) {
+    let start = 0;
+    while (start < word.length && !isKeepChar(word[start]))
+        start++;
+    let end = word.length;
+    while (end > start && !isKeepChar(word[end - 1]))
+        end--;
+    return word.slice(start, end);
+}
+/**
+ * Extract up to `maxWords` usable technical terms from free-text project
+ * context for the recommendation stack.
+ *
+ * Replaces the old `.filter((w) => w.length > 3)` threshold: real technical
+ * terms of 2-3 characters ("git", "ci", "aws", "sql") are now kept, while
+ * single-character tokens, punctuation-only tokens (including one that
+ * survives edge-stripping because it's made entirely of `+`/`#`, e.g. "++"
+ * or "+#" — PR review round 3, SMI-5986), and short English function words
+ * ("a", "the", "is", ...) are still dropped as noise. Words of 4+
+ * characters are unaffected — this only changes the outcome for the short
+ * end of the spectrum the length threshold got wrong.
+ *
+ * @param projectContext - Free-text project/context description. `null`/
+ *   `undefined`/empty returns `[]`, mirroring both callers' pre-existing
+ *   `if (project_context)` guard.
+ * @param maxWords - Maximum number of words to return (default 5).
+ */
+export function extractContextWords(projectContext, maxWords = MAX_CONTEXT_WORDS) {
+    if (!projectContext)
+        return [];
+    return projectContext
+        .toLowerCase()
+        .split(/\s+/)
+        .map(stripEdgePunctuation)
+        .filter((word) => word.length >= 2 &&
+        hasAlphaNumeric(word) &&
+        !(word.length <= 3 && CONTEXT_STOPWORDS.has(word)))
+        .slice(0, maxWords);
+}
+//# sourceMappingURL=context-words.js.map

package/dist/src/services/context-words.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-words.js","sourceRoot":"","sources":["../../../src/services/context-words.ts"],"names":[],"mappings":"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"}

package/dist/src/services/context-words.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=context-words.test.d.ts.map

package/dist/src/services/context-words.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-words.test.d.ts","sourceRoot":"","sources":["../../../src/services/context-words.test.ts"],"names":[],"mappings":""}

package/dist/src/services/context-words.test.js

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Unit tests for the shared context-word extraction helper
+ *   (SMI-5986). Both CLI `recommend --context` and MCP `skill_recommend`'s
+ *   `project_context` now call this instead of duplicating
+ *   `.filter((w) => w.length > 3)`, so their behavior can't drift apart.
+ * @module @skillsmith/core/services/context-words.test
+ */
+import { describe, expect, it } from 'vitest';
+import { extractContextWords } from './context-words.js';
+describe('extractContextWords (SMI-5986)', () => {
+    it('keeps real short technical terms that the old length>3 threshold dropped', () => {
+        const words = extractContextWords('git ci aws sql k8s');
+        expect(words).toEqual(['git', 'ci', 'aws', 'sql', 'k8s']);
+    });
+    it('does not derive an empty stack from a context of only short technical terms', () => {
+        // SMI-5986 regression: this exact shape used to filter to [], which then
+        // tripped the SMI-5896 empty-stack guard even though the caller supplied
+        // usable context.
+        expect(extractContextWords('git').length).toBeGreaterThan(0);
+        expect(extractContextWords('ci').length).toBeGreaterThan(0);
+    });
+    it('drops single-character tokens as noise', () => {
+        expect(extractContextWords('a i x')).toEqual([]);
+    });
+    it('drops short English stopwords but keeps a real term in the same input', () => {
+        const words = extractContextWords('a be api testing');
+        expect(words).not.toContain('a');
+        expect(words).not.toContain('be');
+        expect(words).toContain('api');
+        expect(words).toContain('testing');
+    });
+    it('drops punctuation-only tokens', () => {
+        expect(extractContextWords('... -- !!')).toEqual([]);
+    });
+    it('drops tokens made entirely of + and #, not just other punctuation', () => {
+        // PR review round 3 (SMI-5986): + and # count as "keep" characters for
+        // stripEdgePunctuation (so "c++"/"c#" survive), but a token with no
+        // alphanumeric content at all ("++", "##", "+#") must still be rejected
+        // as noise — it isn't a real technical term just because it contains a
+        // "keep" character.
+        expect(extractContextWords('++ ## +#')).toEqual([]);
+        expect(extractContextWords('++')).toEqual([]);
+    });
+    it('drops a token that is leading-punctuation-only after stripping ("+++x" keeps content, "+++" alone does not)', () => {
+        expect(extractContextWords('+++')).toEqual([]);
+        expect(extractContextWords('+++git')).toEqual(['+++git']);
+    });
+    it('strips edge punctuation without mangling the term ("git," -> "git")', () => {
+        expect(extractContextWords('git,')).toEqual(['git']);
+        expect(extractContextWords('(sql)')).toEqual(['sql']);
+    });
+    it('is case-insensitive ("Git" -> "git")', () => {
+        expect(extractContextWords('Git')).toEqual(['git']);
+        expect(extractContextWords('AWS SQL')).toEqual(['aws', 'sql']);
+    });
+    it('preserves + and # as meaningful trailing characters, not strippable punctuation', () => {
+        // Code-review regression (SMI-5986): edge-punctuation stripping used to
+        // treat "+" and "#" as noise, turning "c++"/"c#" into the single
+        // character "c", which the length filter then discarded entirely.
+        expect(extractContextWords('c++')).toEqual(['c++']);
+        expect(extractContextWords('c#')).toEqual(['c#']);
+        expect(extractContextWords('c++,')).toEqual(['c++']);
+        expect(extractContextWords('(c#)')).toEqual(['c#']);
+    });
+    it('does not filter real technical terms that are also common English words', () => {
+        // Code-review regression (SMI-5986): "any" (TS/SQL keyword), "let"
+        // (JS/Rust keyword), and "can" (CAN-bus acronym) were previously in the
+        // stopword set, contradicting its own documented promise.
+        expect(extractContextWords('any')).toEqual(['any']);
+        expect(extractContextWords('let')).toEqual(['let']);
+        expect(extractContextWords('can')).toEqual(['can']);
+    });
+    it('leaves 4+ character words unaffected (pre-existing behavior preserved)', () => {
+        const words = extractContextWords('testing utilities framework');
+        expect(words).toEqual(['testing', 'utilities', 'framework']);
+    });
+    it('slices to the max word count (default 5)', () => {
+        const words = extractContextWords('one two three four five six seven');
+        expect(words).toHaveLength(5);
+    });
+    it('respects a custom maxWords argument', () => {
+        const words = extractContextWords('git ci aws sql k8s docker', 3);
+        expect(words).toEqual(['git', 'ci', 'aws']);
+    });
+    it('returns [] for undefined, null, or empty input', () => {
+        expect(extractContextWords(undefined)).toEqual([]);
+        expect(extractContextWords(null)).toEqual([]);
+        expect(extractContextWords('')).toEqual([]);
+    });
+    it('returns [] for whitespace-only input', () => {
+        expect(extractContextWords('   ')).toEqual([]);
+    });
+});
+//# sourceMappingURL=context-words.test.js.map

package/dist/src/services/context-words.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-words.test.js","sourceRoot":"","sources":["../../../src/services/context-words.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAE7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAExD,QAAQ,CAAC,gCAAgC,EAAE,GAAG,EAAE;IAC9C,EAAE,CAAC,0EAA0E,EAAE,GAAG,EAAE;QAClF,MAAM,KAAK,GAAG,mBAAmB,CAAC,oBAAoB,CAAC,CAAA;QACvD,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;IAC3D,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,6EAA6E,EAAE,GAAG,EAAE;QACrF,yEAAyE;QACzE,yEAAyE;QACzE,kBAAkB;QAClB,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;QAC5D,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;IAC7D,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAChD,MAAM,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IAClD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,uEAAuE,EAAE,GAAG,EAAE;QAC/E,MAAM,KAAK,GAAG,mBAAmB,CAAC,kBAAkB,CAAC,CAAA;QACrD,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;QAChC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;QACjC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;QAC9B,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;IACpC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IACtD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,mEAAmE,EAAE,GAAG,EAAE;QAC3E,uEAAuE;QACvE,oEAAoE;QACpE,wEAAwE;QACxE,uEAAuE;QACvE,oBAAoB;QACpB,MAAM,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QACnD,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,6GAA6G,EAAE,GAAG,EAAE;QACrH,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QAC9C,MAAM,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC3D,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,qEAAqE,EAAE,GAAG,EAAE;QAC7E,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;QACpD,MAAM,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;IACvD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;QACnD,MAAM,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;IAChE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iFAAiF,EAAE,GAAG,EAAE;QACzF,wEAAwE;QACxE,iEAAiE;QACjE,kEAAkE;QAClE,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;QACnD,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;QACjD,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;QACpD,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;IACrD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,yEAAyE,EAAE,GAAG,EAAE;QACjF,mEAAmE;QACnE,wEAAwE;QACxE,0DAA0D;QAC1D,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;QACnD,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;QACnD,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;IACrD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,wEAAwE,EAAE,GAAG,EAAE;QAChF,MAAM,KAAK,GAAG,mBAAmB,CAAC,6BAA6B,CAAC,CAAA;QAChE,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAA;IAC9D,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,KAAK,GAAG,mBAAmB,CAAC,mCAAmC,CAAC,CAAA;QACtE,MAAM,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;IAC/B,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,KAAK,GAAG,mBAAmB,CAAC,2BAA2B,EAAE,CAAC,CAAC,CAAA;QACjE,MAAM,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;IAC7C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,MAAM,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QAClD,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QAC7C,MAAM,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IAC7C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;IAChD,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/src/services/recommend-guard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Shared empty-derived-stack guard for skill recommendations.
+ * @module @skillsmith/core/services/recommend-guard
+ * @see SMI-5896 (Wave 3, discovery-tool consistency): CLI `recommend` and MCP
+ *   `skill_recommend` each derive a technology "stack" client-side — CLI from
+ *   codebase analysis (`buildStackFromAnalysis`), MCP from installed skills +
+ *   project context keywords — and either can legitimately derive `[]` (a
+ *   non-Node stack, an all-devDeps project, or an unsupported language). The
+ *   `skills-recommend` edge function hard-rejects an empty `stack` with a 400
+ *   (defense in depth, intentionally unchanged by this fix — see the plan's
+ *   Wave 3 Step 2 "decided contract").
+ *
+ *   Both callers now detect the empty-stack case BEFORE calling the API
+ *   instead of letting the guaranteed-400 round trip happen and reacting to
+ *   the failure after the fact — this is the one guidance string they both
+ *   surface, so it can't drift between CLI and MCP wording the way the two
+ *   tools' pre-fix behavior already had (a hard `process.exit(1)` crash on
+ *   CLI vs a silently-swallowed warning on MCP for the exact same input
+ *   shape).
+ */
+/**
+ * Guidance shown when no technology stack could be derived for
+ * recommendations. Written to read naturally from both a terminal (CLI) and
+ * an MCP tool response consumed by a calling agent — neither surface names
+ * its own flag here, since the same string serves both.
+ */
+export declare function buildEmptyStackGuidance(): string;
+//# sourceMappingURL=recommend-guard.d.ts.map

package/dist/src/services/recommend-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommend-guard.d.ts","sourceRoot":"","sources":["../../../src/services/recommend-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAQhD"}

package/dist/src/services/recommend-guard.js

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Shared empty-derived-stack guard for skill recommendations.
+ * @module @skillsmith/core/services/recommend-guard
+ * @see SMI-5896 (Wave 3, discovery-tool consistency): CLI `recommend` and MCP
+ *   `skill_recommend` each derive a technology "stack" client-side — CLI from
+ *   codebase analysis (`buildStackFromAnalysis`), MCP from installed skills +
+ *   project context keywords — and either can legitimately derive `[]` (a
+ *   non-Node stack, an all-devDeps project, or an unsupported language). The
+ *   `skills-recommend` edge function hard-rejects an empty `stack` with a 400
+ *   (defense in depth, intentionally unchanged by this fix — see the plan's
+ *   Wave 3 Step 2 "decided contract").
+ *
+ *   Both callers now detect the empty-stack case BEFORE calling the API
+ *   instead of letting the guaranteed-400 round trip happen and reacting to
+ *   the failure after the fact — this is the one guidance string they both
+ *   surface, so it can't drift between CLI and MCP wording the way the two
+ *   tools' pre-fix behavior already had (a hard `process.exit(1)` crash on
+ *   CLI vs a silently-swallowed warning on MCP for the exact same input
+ *   shape).
+ */
+/**
+ * Guidance shown when no technology stack could be derived for
+ * recommendations. Written to read naturally from both a terminal (CLI) and
+ * an MCP tool response consumed by a calling agent — neither surface names
+ * its own flag here, since the same string serves both.
+ */
+export function buildEmptyStackGuidance() {
+    return ('No technology stack could be derived for recommendations — this usually ' +
+        'means a non-Node project, a stack with no production dependencies, or an ' +
+        'unsupported language, not a backend or registry problem. Provide project ' +
+        'context (a short description of the project or its tooling) or an ' +
+        'explicit list of installed/currently-used skills, then try again.');
+}
+//# sourceMappingURL=recommend-guard.js.map

package/dist/src/services/recommend-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommend-guard.js","sourceRoot":"","sources":["../../../src/services/recommend-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,CACL,0EAA0E;QAC1E,2EAA2E;QAC3E,2EAA2E;QAC3E,oEAAoE;QACpE,mEAAmE,CACpE,CAAA;AACH,CAAC"}

package/dist/src/services/recommend-guard.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=recommend-guard.test.d.ts.map

package/dist/src/services/recommend-guard.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommend-guard.test.d.ts","sourceRoot":"","sources":["../../../src/services/recommend-guard.test.ts"],"names":[],"mappings":""}

package/dist/src/services/recommend-guard.test.js

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Unit tests for the shared empty-derived-stack guidance string
+ *   (SMI-5896 Wave 3 Step 2). Both CLI `recommend` and MCP `skill_recommend`
+ *   surface this exact string so their empty-stack messaging can't drift.
+ * @module @skillsmith/core/services/recommend-guard.test
+ */
+import { describe, expect, it } from 'vitest';
+import { buildEmptyStackGuidance } from './recommend-guard.js';
+describe('buildEmptyStackGuidance (SMI-5896 Wave 3 Step 2)', () => {
+    it('returns a non-empty string', () => {
+        const guidance = buildEmptyStackGuidance();
+        expect(typeof guidance).toBe('string');
+        expect(guidance.length).toBeGreaterThan(0);
+    });
+    it('explains the empty stack is a legitimate under-detection, not a backend fault', () => {
+        const guidance = buildEmptyStackGuidance();
+        expect(guidance).toContain('No technology stack could be derived');
+    });
+    it('guides the caller toward providing context or an installed-skills list', () => {
+        const guidance = buildEmptyStackGuidance();
+        expect(guidance.toLowerCase()).toContain('project context');
+        expect(guidance.toLowerCase()).toContain('installed');
+    });
+    it('is deterministic (identical wording every call) so CLI and MCP never drift apart', () => {
+        expect(buildEmptyStackGuidance()).toBe(buildEmptyStackGuidance());
+    });
+});
+//# sourceMappingURL=recommend-guard.test.js.map

package/dist/src/services/recommend-guard.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommend-guard.test.js","sourceRoot":"","sources":["../../../src/services/recommend-guard.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAE7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAE9D,QAAQ,CAAC,kDAAkD,EAAE,GAAG,EAAE;IAChE,EAAE,CAAC,4BAA4B,EAAE,GAAG,EAAE;QACpC,MAAM,QAAQ,GAAG,uBAAuB,EAAE,CAAA;QAC1C,MAAM,CAAC,OAAO,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACtC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAA;IAC5C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+EAA+E,EAAE,GAAG,EAAE;QACvF,MAAM,QAAQ,GAAG,uBAAuB,EAAE,CAAA;QAC1C,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,sCAAsC,CAAC,CAAA;IACpE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,wEAAwE,EAAE,GAAG,EAAE;QAChF,MAAM,QAAQ,GAAG,uBAAuB,EAAE,CAAA;QAC1C,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAA;QAC3D,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAA;IACvD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,kFAAkF,EAAE,GAAG,EAAE;QAC1F,MAAM,CAAC,uBAAuB,EAAE,CAAC,CAAC,IAAI,CAAC,uBAAuB,EAAE,CAAC,CAAA;IACnE,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/src/services/skill-installation.content.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @fileoverview Content-based skill install path (private registry).
+ * @module @skillsmith/core/services/skill-installation.content
+ * @see SMI-5905 Wave 1: installFromContent() + resolveFreshAccessToken() extraction
+ * @see docs/internal/implementation/private-registry-skill-install.md
+ *
+ * `install()` (skill-installation.service.ts) only knows how to fetch a
+ * skill from GitHub. This module adds a second entry point,
+ * `installFromContent()`, for skills whose content has already been resolved
+ * elsewhere (a private-registry `content` JSONB column, read via a
+ * per-team-member Supabase session or the `private-registry-get` Edge
+ * Function — Waves 2/3 wire those transports; this module only needs the
+ * already-fetched `{skillId, version, content}` triple).
+ *
+ * SCOPE TRIM (Sol review #5 — read before extending this function):
+ * `installFromContent()` deliberately reuses only two things from the
+ * `install()` policy chain:
+ *   1. `writeInstallFiles()`'s disk-write + rollback-on-partial-write handling
+ *      (skill-installation.io.ts), plus this module's own manifest-driven
+ *      already-installed/force gate (mirrors `install()`'s ALREADY_INSTALLED
+ *      check).
+ *   2. A security scan at the `community` trust tier, via the same
+ *      `classifyBundledFile()`/`isRejectableScan()` policy `install()` uses
+ *      for optional bundled files (skill-installation.policy.ts) — applied
+ *      here to every content-map entry (including "SKILL.md" itself, which
+ *      falls through to the conservative 'structured' default class since it
+ *      has no BUNDLED_SCAN_FILES entry).
+ *
+ * It deliberately does NOT route through the rest of `install()`'s chain:
+ *   - `skipScan` is NOT an accepted option here. Registry-content installs
+ *     always scan — there is no opt-out, unlike `install()`'s tier-gated
+ *     skipScan.
+ *   - Dependency-intelligence extraction/persistence (extractDepIntel,
+ *     persistDependencies, checkDepsAgainstQuarantine), risk-history
+ *     recording, AI-defence feedback, and co-install-session recording are
+ *     all OUT of v1 scope — a known, intentional gap, not a silent drop.
+ *     Wave 3's MCP `install` action and Wave 4's CLI command do not get
+ *     these signals for private-registry installs yet.
+ *   - Frontmatter/manifest validation on `SKILL.md` itself DOES still run
+ *     (`validateSkillMd()`), same as any other install.
+ *
+ * PATH VALIDATION (Sol review #2, critical, confirmed exploitable): every key
+ * in `content` is attacker-controlled — any team member with publish access
+ * chooses these filenames — and flows into `writeInstallFiles()`'s
+ * `path.join(installPath, subSkill.filename)` (skill-installation.io.ts:167)
+ * with NO containment check of its own. `path.join('/a/b', '../../etc/passwd')`
+ * escapes `installPath` after normalization, so every key is validated here,
+ * BEFORE any disk write — see `validateContentKeys()`.
+ */
+import type { Database } from '../db/database-interface.js';
+import type { ClientId } from '../install/paths.js';
+import type { ProgressCallback, InstallFromContentOptions, InstallResult } from './skill-installation.types.js';
+import type { ManifestManager } from './skill-manifest.js';
+/**
+ * Validate every key in a content map before any disk write.
+ *
+ * Rejects (as a single combined error, first offense wins):
+ *   - path-traversal (`..` segment), absolute paths (posix or win32/UNC),
+ *     NUL bytes, backslashes, empty/bare-"."/".git"-adjacent keys;
+ *   - any key that, after `path.resolve()` against `installPath`, resolves
+ *     outside `installPath` (a lexical backstop behind the checks above,
+ *     matching `writeInstallFiles()`'s own lexical escape check);
+ *   - two keys that `path.normalize()` to the same on-disk path (a
+ *     collision — e.g. "SKILL.md" and "./SKILL.md").
+ */
+export declare function validateContentKeys(content: Record<string, string>, installPath: string): {
+    valid: true;
+} | {
+    valid: false;
+    error: string;
+};
+/** Internal params bag: the caller's InstallFromContentOptions plus the service state
+ *  installFromContent() needs (mirrors performUninstall()'s flattened-params convention
+ *  in skill-installation.helpers.ts). */
+export interface InstallFromContentParams extends InstallFromContentOptions {
+    db: Database;
+    skillsDir: string;
+    manifest: ManifestManager;
+    client: ClientId;
+    onProgress: ProgressCallback;
+    /**
+     * SMI-5982 code-review fix #1: base dir for resolving a relative companion-agent
+     * target (Antigravity only) — see writeInstallFiles()'s own doc comment.
+     * PR-review follow-up: optional (not required) — an omitted value must flow
+     * through to `resolveCompanionAgentPath()`'s own required-`baseDir` guard as
+     * `undefined`, not be silently defaulted anywhere in this chain.
+     */
+    companionBaseDir?: string;
+}
+/**
+ * Install an already-resolved private-registry skill's content to disk.
+ *
+ * See this file's header doc comment for the full scope trim vs. `install()`.
+ */
+export declare function installFromContent(params: InstallFromContentParams): Promise<InstallResult>;
+//# sourceMappingURL=skill-installation.content.d.ts.map

package/dist/src/services/skill-installation.content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-installation.content.d.ts","sourceRoot":"","sources":["../../../src/services/skill-installation.content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAA;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,KAAK,EACV,gBAAgB,EAChB,yBAAyB,EACzB,aAAa,EACd,MAAM,+BAA+B,CAAA;AAEtC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AA8C1D;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,WAAW,EAAE,MAAM,GAClB;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAgCnD;AA8DD;;yCAEyC;AACzC,MAAM,WAAW,wBAAyB,SAAQ,yBAAyB;IACzE,EAAE,EAAE,QAAQ,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,eAAe,CAAA;IACzB,MAAM,EAAE,QAAQ,CAAA;IAChB,UAAU,EAAE,gBAAgB,CAAA;IAC5B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,aAAa,CAAC,CAqKjG"}