@aexol/opencode-wizard 0.3.11 → 0.3.13

package/dist/server/runtime.js

@@ -10,7 +10,7 @@ import { fetchPublishedSkillDetail, fetchPublishedSkillsCatalog, fetchPublishedS
 import { normalizeAbsolutePath } from './path-utils.js';
 import { emitPluginActionEvent, emitPresenceEvent } from './presence.js';
 import { normalizeDirectoryArg, normalizeRepositoryPath, resolveWorkspace, toWorkspaceResolutionMetadata, toWorkspaceResolutionOutput } from './workspace.js';
-import { parseRequestedSkillArgs, selectPublishedSkills, toPublishedSkillDetail, toPublishedSkillSummary, toWizardArtifactCatalog, toWizardArtifactDetail, toWizardArtifactSummary } from '../published-skills-transform.js';
+import { parseRequestedSkillArgs, selectPublishedSkills, toInstallableSkillSummary, toPublishedSkillDetail, toPublishedSkillSummary, toWizardArtifactCatalog, toWizardArtifactDetail, toWizardArtifactSummary } from '../published-skills-transform.js';
 import { CACHE_TTL_MS, LOGIN_TIMEOUT_MS, OIDC_CALLBACK_URL, PLUGIN_ID, PRESENCE_SHUTDOWN_SIGNALS, PRESENCE_SIGNAL_EXIT_CODES } from './constants.js';
 export { PLUGIN_ID, NATIVE_SKILLS_URL_COMPATIBILITY } from './constants.js';
 import { buildSystemNote, filterIgnoredPublishedSkills, resolvePluginStatusSnapshot, toAiFacingPluginStatusSnapshot, toFetchFailureOutput, toPluginStatusMetadata, toPublishedSkillCatalog } from './status.js';
@@ -20,7 +20,7 @@ import { getCatalogCacheKey, resolvePublishedSkillPreferenceCacheContext, setPub
 export { buildSystemNote, resolvePluginStatusSnapshot, toPluginAuthStateSummary, toPublishedSkillCatalog } from './status.js';
 const importOpencodePluginModule = new Function('specifier', 'return import(specifier)');
 export { resolvePluginStatusSnapshotWithAuthBootstrap } from './auth-bootstrap.js';
-export { setPublishedSkillIgnored, setPublishedSkillInstalled } from './preferences.js';
+export { setPublishedSkillIgnored, setPublishedSkillInstalled, toPublishedSkillPreferenceScope } from './preferences.js';
 const getDetailCacheKey = (catalogCacheKey, skillVersionId, revision) => {
   return JSON.stringify([catalogCacheKey, skillVersionId, revision]);
 };
@@ -118,6 +118,105 @@ const selectWizardArtifacts = (items, identifiers) => {
     missingIdentifiers
   };
 };
+const MAX_IDENTIFIER_SUGGESTIONS = 3;
+const RECOMMENDATION_METADATA_NOTE = 'Recommendation fields are backend metadata for routing and discoverability only; fetch/detail tools are still required before using artifact bodies as guidance.';
+const normalizeRecommendationContext = args => {
+  if (typeof args.recommendationContext !== 'string') return null;
+  const recommendationContext = args.recommendationContext.trim();
+  if (!recommendationContext) return null;
+  return recommendationContext;
+};
+const normalizeSuggestionIdentifier = value => value.trim().toLowerCase().normalize('NFKD').replace(/[^\p{Letter}\p{Number}]+/gu, '');
+const getEditDistance = (left, right) => {
+  if (left === right) return 0;
+  if (!left) return right.length;
+  if (!right) return left.length;
+  const previous = Array.from({
+    length: right.length + 1
+  }, (_, index) => index);
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+    const current = [leftIndex];
+    for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+      const substitutionCost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+      current[rightIndex] = Math.min(current[rightIndex - 1] + 1, previous[rightIndex] + 1, previous[rightIndex - 1] + substitutionCost);
+    }
+    previous.splice(0, previous.length, ...current);
+  }
+  return previous[right.length];
+};
+const getSuggestionScore = (requested, candidate) => {
+  const normalizedRequested = normalizeSuggestionIdentifier(requested);
+  const normalizedCandidate = normalizeSuggestionIdentifier(candidate);
+  if (!normalizedRequested || !normalizedCandidate) return null;
+  if (normalizedRequested === normalizedCandidate) return 0;
+  if (normalizedCandidate.includes(normalizedRequested) || normalizedRequested.includes(normalizedCandidate)) return 1;
+  const distance = getEditDistance(normalizedRequested, normalizedCandidate);
+  const threshold = Math.max(2, Math.ceil(Math.max(normalizedRequested.length, normalizedCandidate.length) * 0.35));
+  if (distance > threshold) return null;
+  return distance + 2;
+};
+const dedupeSuggestionCandidates = candidates => {
+  const seen = new Set();
+  return candidates.filter(candidate => {
+    const key = normalizeSuggestionIdentifier(candidate.identifier);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+};
+const getIdentifierSuggestions = (requestedIdentifier, candidates) => dedupeSuggestionCandidates(candidates).map(candidate => ({
+  candidate,
+  score: getSuggestionScore(requestedIdentifier, candidate.identifier)
+})).filter(result => result.score !== null).sort((left, right) => {
+  if (left.score !== right.score) return left.score - right.score;
+  if (left.candidate.source !== right.candidate.source) return left.candidate.source === 'active' ? -1 : 1;
+  return left.candidate.identifier.localeCompare(right.candidate.identifier);
+}).slice(0, MAX_IDENTIFIER_SUGGESTIONS).map(({
+  candidate
+}) => ({
+  identifier: candidate.canonicalIdentifier,
+  matchedIdentifier: candidate.identifier,
+  label: candidate.label,
+  source: candidate.source
+}));
+const getSkillSuggestionCandidates = payload => [...payload.skills.flatMap(item => {
+  const summary = toPublishedSkillSummary(item);
+  return summary.identifiers.map(identifier => ({
+    identifier,
+    canonicalIdentifier: summary.skillSlug,
+    label: summary.artifactName || summary.skillName || summary.skillSlug,
+    source: 'active'
+  }));
+}), ...payload.catalogSkills.flatMap(item => {
+  const summary = toInstallableSkillSummary(item);
+  return summary.identifiers.map(identifier => ({
+    identifier,
+    canonicalIdentifier: summary.skillSlug,
+    label: summary.artifactName || summary.skillName || summary.skillSlug,
+    source: 'catalog'
+  }));
+})];
+const getWizardArtifactSuggestionCandidates = (items, catalogItems) => [...items.flatMap(item => {
+  const summary = toWizardArtifactSummary(item);
+  return summary.identifiers.map(identifier => ({
+    identifier,
+    canonicalIdentifier: summary.artifactSlug,
+    label: summary.artifactName || summary.artifactSlug,
+    source: 'active'
+  }));
+}), ...toWizardArtifactCatalogCursorItems(catalogItems).flatMap(item => {
+  const summary = toWizardArtifactSummary(item);
+  return summary.identifiers.map(identifier => ({
+    identifier,
+    canonicalIdentifier: summary.artifactSlug,
+    label: summary.artifactName || summary.artifactSlug,
+    source: 'catalog'
+  }));
+})];
+const getMissingIdentifierSuggestions = (identifiers, candidates) => identifiers.map(identifier => ({
+  identifier,
+  suggestions: getIdentifierSuggestions(identifier, candidates)
+}));
 export const OpencodeWizardSkillsPlugin = async input => {
   const {
     tool
@@ -339,7 +438,8 @@ export const OpencodeWizardSkillsPlugin = async input => {
   const loadPublishedSkillCatalog = async ({
     directory,
     useCache,
-    signal
+    signal,
+    recommendationContext
   }) => {
     const workspaceResolution = await resolveWorkspace({
       config,
@@ -347,7 +447,7 @@ export const OpencodeWizardSkillsPlugin = async input => {
     });
     const directoryPath = workspaceResolution.directoryPath;
     const preferenceContext = await resolvePublishedSkillPreferenceCacheContext(config);
-    const cacheKey = getCatalogCacheKey(workspaceResolution, preferenceContext);
+    const cacheKey = JSON.stringify([getCatalogCacheKey(workspaceResolution, preferenceContext), recommendationContext ?? '']);
     const cached = cache.get(cacheKey);
     if (useCache && cached && cached.expiresAt > Date.now()) {
       return {
@@ -364,7 +464,7 @@ export const OpencodeWizardSkillsPlugin = async input => {
       return inflight;
     }
     const requestPromise = (async () => {
-      const fetchResult = await fetchPublishedSkillsCatalog(input.worktree, config, workspaceResolution, signal, clearPublishedSkillState);
+      const fetchResult = await fetchPublishedSkillsCatalog(input.worktree, config, workspaceResolution, signal, recommendationContext, clearPublishedSkillState);
       await maybePersistWorkspaceSlugFromCatalog({
         config,
         resolution: workspaceResolution,
@@ -421,6 +521,7 @@ export const OpencodeWizardSkillsPlugin = async input => {
         config,
         resolution: workspaceResolution,
         skillVersionId: item.skillVersion.id,
+        artifactVersionId: item.publishedArtifact.id,
         signal,
         onAuthStateChanged: clearPublishedSkillState,
         purpose
@@ -529,6 +630,7 @@ export const OpencodeWizardSkillsPlugin = async input => {
   }) => {
     const requestedDirectory = normalizeDirectoryArg(context.directory, args.directory);
     const requestedSkills = parseRequestedSkillArgs(args);
+    const recommendationContext = normalizeRecommendationContext(args);
     const fetchActionDirectoryPath = normalizeRepositoryPath(workspacePath, requestedDirectory);
     lastInteractiveDirectoryPath = fetchActionDirectoryPath;
     const emitFetchOutcome = async event => {
@@ -540,7 +642,8 @@ export const OpencodeWizardSkillsPlugin = async input => {
     let publishedSkillsResult = await loadPublishedSkillCatalog({
       directory: requestedDirectory,
       useCache: !args.refresh,
-      signal: context.abort
+      signal: context.abort,
+      recommendationContext
     });
     if (publishedSkillsResult.fetchResult.ok) {
       await scheduleInteractivePresenceStart();
@@ -553,7 +656,8 @@ export const OpencodeWizardSkillsPlugin = async input => {
         publishedSkillsResult = await loadPublishedSkillCatalog({
           directory: requestedDirectory,
           useCache: false,
-          signal: context.abort
+          signal: context.abort,
+          recommendationContext
         });
         if (publishedSkillsResult.fetchResult.ok) {
           await scheduleInteractivePresenceStart();
@@ -583,6 +687,7 @@ export const OpencodeWizardSkillsPlugin = async input => {
     }
     const selection = selectPublishedSkills(filteredPublishedSkillsResult.fetchResult.payload, requestedSkills);
     const isSingleRequest = requestedSkills.length === 1;
+    const skillSuggestionCandidates = getSkillSuggestionCandidates(filteredPublishedSkillsResult.fetchResult.payload);
     if (requestedSkills.length === 0) {
       const catalog = toPublishedSkillCatalog(filteredPublishedSkillsResult.fetchResult.payload, registeredTools);
       context.metadata({
@@ -610,9 +715,12 @@ export const OpencodeWizardSkillsPlugin = async input => {
           },
           fetchedAt: filteredPublishedSkillsResult.fetchResult.fetchedAt,
           source: filteredPublishedSkillsResult.fetchResult.source,
+          recommendationContext,
+          recommendationNote: RECOMMENDATION_METADATA_NOTE,
           cacheCursor: getCatalogCursor(filteredPublishedSkillsResult.fetchResult.payload.skills, filteredPublishedSkillsResult.fetchResult.payload.catalogSkills),
           cacheTtlMs: CACHE_TTL_MS,
-          message: args.refresh ? 'Catalog discovery refreshed from the backend. Provide `skill` for one identifier or prefer `skills` for comma/newline-separated multiple identifiers to fetch markdown bodies/details.' : 'Catalog discovery only. Cached results include deterministic revision cursors; pass `refresh: true` to force a backend refresh immediately. Provide `skill` for one identifier or prefer `skills` for comma/newline-separated multiple identifiers to fetch markdown bodies/details.'
+          message: args.refresh ? 'Catalog discovery refreshed from the backend. Provide `skill` for one identifier or prefer `skills` for comma/newline-separated multiple identifiers to fetch markdown bodies/details.' : 'Catalog discovery only. Cached results include deterministic revision cursors; pass `refresh: true` to force a backend refresh immediately. Provide `skill` for one identifier or prefer `skills` for comma/newline-separated multiple identifiers to fetch markdown bodies/details.',
+          nextStep: 'Choose an active skill identifier from `skills` and call `opencode_wizard_published_skills_fetch` with `skill`; catalog-only skills must be installed before their bodies are fetchable.'
         }, null, 2),
         metadata: {
           status: 'ready',
@@ -627,7 +735,7 @@ export const OpencodeWizardSkillsPlugin = async input => {
         }
       };
     }
-    if (selection.selectedItems.length === 0 && isSingleRequest) {
+    if (selection.selectedItems.length === 0) {
       await emitFetchOutcome('FETCH_FAILED');
       return {
         output: JSON.stringify({
@@ -636,12 +744,19 @@ export const OpencodeWizardSkillsPlugin = async input => {
           status: 'not_found',
           requestedDirectoryPath: filteredPublishedSkillsResult.directoryPath,
           workspaceResolution: toWorkspaceResolutionOutput(filteredPublishedSkillsResult.workspaceResolution),
-          requestedSkill: requestedSkills[0],
+          requestedSkill: isSingleRequest ? requestedSkills[0] : undefined,
+          requestedSkills,
+          missingSkills: selection.missingIdentifiers,
+          recommendationContext,
+          recommendationNote: RECOMMENDATION_METADATA_NOTE,
+          suggestions: isSingleRequest ? getIdentifierSuggestions(requestedSkills[0] ?? '', skillSuggestionCandidates) : undefined,
+          missingSkillSuggestions: getMissingIdentifierSuggestions(selection.missingIdentifiers, skillSuggestionCandidates),
           availableSkills: filteredPublishedSkillsResult.fetchResult.payload.skills.map(toPublishedSkillSummary),
           ignoredPublishedSkills: {
             scopeKey: filteredPublishedSkillsResult.ignoreState.scopeKey,
             count: filteredPublishedSkillsResult.ignoreState.ignoredSkillSlugs.length
-          }
+          },
+          nextStep: 'Retry with one suggested identifier, fetch the catalog with no args/refresh to inspect available skills, or install a catalog-only suggestion before fetching its body.'
         }, null, 2),
         metadata: {
           status: 'not_found',
@@ -703,6 +818,8 @@ export const OpencodeWizardSkillsPlugin = async input => {
           workspace: filteredPublishedSkillsResult.fetchResult.payload.workspace,
           fetchedAt: filteredPublishedSkillsResult.fetchResult.fetchedAt,
           source: filteredPublishedSkillsResult.fetchResult.source,
+          recommendationContext,
+          recommendationNote: RECOMMENDATION_METADATA_NOTE,
           skill: detail
         }, null, 2),
         metadata: {
@@ -733,6 +850,10 @@ export const OpencodeWizardSkillsPlugin = async input => {
         source: filteredPublishedSkillsResult.fetchResult.source,
         requestedSkills,
         missingSkills: selection.missingIdentifiers,
+        recommendationContext,
+        recommendationNote: RECOMMENDATION_METADATA_NOTE,
+        missingSkillSuggestions: getMissingIdentifierSuggestions(selection.missingIdentifiers, skillSuggestionCandidates),
+        nextStep: selection.missingIdentifiers.length > 0 ? 'Fetched matched skills. Retry missing identifiers with suggested active names, or inspect the no-arg catalog for catalog-only skills that need installation first.' : 'Use each fetched `skill.markdownDocument` as reference content for matched backend-published skills.',
         skills: skillDetails
       }, null, 2),
       metadata: {
@@ -757,11 +878,12 @@ export const OpencodeWizardSkillsPlugin = async input => {
       });
     }
     if (artifactKind === 'DESIGN_DOC') {
+      const recommendationContext = normalizeRecommendationContext(args);
       const workspaceResolution = await resolveWorkspace({
         config,
         directory: requestedDirectory
       });
-      const fetchResult = await fetchWizardArtifactsCatalog(input.worktree, config, workspaceResolution, artifactKind, context.abort, clearPublishedSkillState);
+      const fetchResult = await fetchWizardArtifactsCatalog(input.worktree, config, workspaceResolution, artifactKind, context.abort, recommendationContext, clearPublishedSkillState);
       if (!fetchResult.ok) {
         return {
           output: JSON.stringify({
@@ -796,9 +918,12 @@ export const OpencodeWizardSkillsPlugin = async input => {
           workspaceResolution: toWorkspaceResolutionOutput(workspaceResolution),
           fetchedAt: fetchResult.fetchedAt,
           source: fetchResult.source,
+          recommendationContext,
+          recommendationNote: RECOMMENDATION_METADATA_NOTE,
           cacheCursor,
           cacheTtlMs: CACHE_TTL_MS,
-          message: 'Generic artifact catalog discovery only. Full bodies/files require opencode_wizard_artifact_fetch with artifactKind and artifact identifiers.'
+          message: 'Generic artifact catalog discovery only. Full bodies/files require opencode_wizard_artifact_fetch with artifactKind and artifact identifiers.',
+          nextStep: 'Choose an active artifact identifier from `artifacts` and call `opencode_wizard_artifact_fetch`; catalog-only artifacts must be installed before their bodies are fetchable.'
         }, null, 2),
         metadata: {
           status: 'ready',
@@ -814,7 +939,8 @@ export const OpencodeWizardSkillsPlugin = async input => {
     const result = await executePublishedSkillsFetchTool({
       args: {
         directory: args.directory,
-        refresh: args.refresh
+        refresh: args.refresh,
+        recommendationContext: args.recommendationContext
       },
       context
     });
@@ -838,11 +964,12 @@ export const OpencodeWizardSkillsPlugin = async input => {
         skill: args.artifact,
         skills: args.artifacts
       });
+      const recommendationContext = normalizeRecommendationContext(args);
       const workspaceResolution = await resolveWorkspace({
         config,
         directory: requestedDirectory
       });
-      const fetchResult = await fetchWizardArtifactsCatalog(input.worktree, config, workspaceResolution, artifactKind, context.abort, clearPublishedSkillState);
+      const fetchResult = await fetchWizardArtifactsCatalog(input.worktree, config, workspaceResolution, artifactKind, context.abort, recommendationContext, clearPublishedSkillState);
       if (!fetchResult.ok) {
         return {
           output: JSON.stringify({
@@ -865,6 +992,7 @@ export const OpencodeWizardSkillsPlugin = async input => {
         };
       }
       const selection = selectWizardArtifacts(fetchResult.payload.artifacts, requestedArtifacts);
+      const artifactSuggestionCandidates = getWizardArtifactSuggestionCandidates(fetchResult.payload.artifacts, fetchResult.payload.catalogArtifacts);
       if (requestedArtifacts.length === 0) {
         const catalog = toWizardArtifactCatalog(fetchResult.payload, {
           pluginId: PLUGIN_ID,
@@ -879,9 +1007,12 @@ export const OpencodeWizardSkillsPlugin = async input => {
             workspaceResolution: toWorkspaceResolutionOutput(workspaceResolution),
             fetchedAt: fetchResult.fetchedAt,
             source: fetchResult.source,
+            recommendationContext,
+            recommendationNote: RECOMMENDATION_METADATA_NOTE,
             cacheCursor,
             cacheTtlMs: CACHE_TTL_MS,
-            message: 'Provide artifact or artifacts to fetch artifact body/files.'
+            message: 'Provide artifact or artifacts to fetch artifact body/files.',
+            nextStep: 'Choose an active artifact identifier from `artifacts` and call `opencode_wizard_artifact_fetch`; install catalog-only artifacts before fetching their bodies.'
           }, null, 2),
           metadata: {
             status: 'ready',
@@ -892,17 +1023,24 @@ export const OpencodeWizardSkillsPlugin = async input => {
           }
         };
       }
-      if (selection.selectedItems.length === 0 && requestedArtifacts.length === 1) {
+      if (selection.selectedItems.length === 0) {
         return {
           output: JSON.stringify({
             pluginId: PLUGIN_ID,
             runtimeMode: 'tool_fetch_only',
             status: 'not_found',
             artifactKind,
-            requestedArtifact: requestedArtifacts[0],
+            requestedArtifact: requestedArtifacts.length === 1 ? requestedArtifacts[0] : undefined,
+            requestedArtifacts,
+            missingArtifacts: selection.missingIdentifiers,
+            recommendationContext,
+            recommendationNote: RECOMMENDATION_METADATA_NOTE,
+            suggestions: requestedArtifacts.length === 1 ? getIdentifierSuggestions(requestedArtifacts[0] ?? '', artifactSuggestionCandidates) : undefined,
+            missingArtifactSuggestions: getMissingIdentifierSuggestions(selection.missingIdentifiers, artifactSuggestionCandidates),
             availableArtifacts: fetchResult.payload.artifacts.map(toWizardArtifactSummary),
             requestedDirectoryPath: directoryPath,
-            workspaceResolution: toWorkspaceResolutionOutput(workspaceResolution)
+            workspaceResolution: toWorkspaceResolutionOutput(workspaceResolution),
+            nextStep: 'Retry with one suggested identifier, fetch the artifact catalog to inspect available artifacts, or install a catalog-only suggestion before fetching its body.'
           }, null, 2),
           metadata: {
             status: 'not_found',
@@ -962,6 +1100,10 @@ export const OpencodeWizardSkillsPlugin = async input => {
           cacheTtlMs: CACHE_TTL_MS,
           requestedArtifacts,
           missingArtifacts: selection.missingIdentifiers,
+          recommendationContext,
+          recommendationNote: RECOMMENDATION_METADATA_NOTE,
+          missingArtifactSuggestions: getMissingIdentifierSuggestions(selection.missingIdentifiers, artifactSuggestionCandidates),
+          nextStep: selection.missingIdentifiers.length > 0 ? 'Fetched matched artifacts. Retry missing identifiers with suggested active names, or inspect the catalog for catalog-only artifacts that need installation first.' : 'Use the fetched artifact markdown as reference content for matched backend-published artifacts.',
           artifacts: details
         }, null, 2),
         metadata: {
@@ -978,7 +1120,8 @@ export const OpencodeWizardSkillsPlugin = async input => {
         skill: args.artifact,
         skills: args.artifacts,
         directory: args.directory,
-        refresh: args.refresh
+        refresh: args.refresh,
+        recommendationContext: args.recommendationContext
       },
       context
     });
@@ -1048,7 +1191,8 @@ export const OpencodeWizardSkillsPlugin = async input => {
       const catalogResult = await loadPublishedSkillCatalog({
         directory: requestedDirectory,
         useCache: true,
-        signal: context.abort
+        signal: context.abort,
+        recommendationContext: null
       });
       if (!catalogResult.fetchResult.ok) {
         await emitPreferenceOutcome('PREFERENCE_FAILED');
@@ -1564,7 +1708,8 @@ export const OpencodeWizardSkillsPlugin = async input => {
       let publishedSkillsResult = await loadPublishedSkillCatalog({
         directory: input.directory,
         useCache: true,
-        signal: AbortSignal.timeout(5_000)
+        signal: AbortSignal.timeout(5_000),
+        recommendationContext: null
       });
       if (!publishedSkillsResult.fetchResult.ok && publishedSkillsResult.fetchResult.status === 'missing_auth') {
         try {
@@ -1574,7 +1719,8 @@ export const OpencodeWizardSkillsPlugin = async input => {
           publishedSkillsResult = await loadPublishedSkillCatalog({
             directory: input.directory,
             useCache: false,
-            signal: AbortSignal.timeout(5_000)
+            signal: AbortSignal.timeout(5_000),
+            recommendationContext: null
           });
         } catch {
           const loginMessage = loginBootstrap.snapshot.message ? ` Last login status: ${loginBootstrap.snapshot.message}` : '';