@aexol/opencode-wizard 0.3.4 → 0.3.6

package/dist/server/runtime.js

@@ -1,226 +1,98 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { CREATE_OR_UPDATE_SKILL_FROM_MARKDOWN_MUTATION, SET_PUBLISHED_SKILL_PREFERENCE_MUTATION } from '../graphql-operations.js';
-import { createPublishedSkillToolDefinitions } from '../plugin-tools.js';
-import { readGlobalAuthState, resolveStoredAuthState, toAuthState, toStoredUserKey, writeAuthState } from './auth-store.js';
+import { CREATE_OR_UPDATE_SKILL_FROM_MARKDOWN_MUTATION, IMPORT_WIZARD_ARTIFACT_SNAPSHOT_MUTATION, SET_WIZARD_ARTIFACT_PREFERENCE_MUTATION } from '../graphql-operations.js';
+import { createPublishedSkillToolDefinitions, resolveAvailableTools } from '../plugin-tools.js';
+import { resolveStoredAuthState, toAuthState, writeAuthState } from './auth-store.js';
 import { resolveConfig } from './config.js';
 export { resolveConfig } from './config.js';
 import { createPluginSession, openBrowser, startLoginFlow } from './auth-flow.js';
-import { fetchPublishedSkillDetail, fetchPublishedSkillsCatalog, fetchPublishedSkillsGraphQl, maybePersistWorkspaceSlugFromCatalog } from './client.js';
+import { fetchPublishedSkillDetail, fetchPublishedSkillsCatalog, fetchPublishedSkillsGraphQl, fetchWizardArtifactDetail, fetchWizardArtifactsCatalog, maybePersistWorkspaceSlugFromCatalog } from './client.js';
 import { normalizeAbsolutePath } from './path-utils.js';
 import { emitPluginActionEvent, emitPresenceEvent } from './presence.js';
-import { normalizeDirectoryArg, normalizeRepositoryPath, resolveWorkspace, toDeliveryInput, toWorkspaceResolutionMetadata, toWorkspaceResolutionOutput } from './workspace.js';
-import { parseRequestedSkillArgs, selectPublishedSkills, toPublishedSkillDetail, toPublishedSkillSummary } from '../published-skills-transform.js';
-import { CACHE_TTL_MS, LOGIN_TIMEOUT_MS, OIDC_CALLBACK_URL, PLUGIN_ID, PRESENCE_EVENT_TIMEOUT_MS, PRESENCE_SHUTDOWN_SIGNALS, PRESENCE_SIGNAL_EXIT_CODES } from './constants.js';
+import { normalizeDirectoryArg, normalizeRepositoryPath, resolveWorkspace, toWorkspaceResolutionMetadata, toWorkspaceResolutionOutput } from './workspace.js';
+import { parseRequestedSkillArgs, selectPublishedSkills, 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, withStatusMessage } from './status.js';
+import { buildSystemNote, filterIgnoredPublishedSkills, resolvePluginStatusSnapshot, toAiFacingPluginStatusSnapshot, toFetchFailureOutput, toPluginStatusMetadata, toPublishedSkillCatalog } from './status.js';
+import { createIdleLoginBootstrapSnapshot } from './auth-bootstrap.js';
+import { fetchWizardArtifactImportSource, planWizardArtifactImport } from './import-sources.js';
+import { getCatalogCacheKey, resolvePublishedSkillPreferenceCacheContext, setPublishedSkillIgnored, setPublishedSkillInstalled, toPublishedSkillPreferenceAction, toPublishedSkillPreferenceScope } from './preferences.js';
 export { buildSystemNote, resolvePluginStatusSnapshot, toPluginAuthStateSummary, toPublishedSkillCatalog } from './status.js';
-const createIdleLoginBootstrapSnapshot = () => ({
-  status: 'idle',
-  trigger: null,
-  startedAt: null,
-  expiresAt: null,
-  browserUrl: null,
-  browserOpenError: null,
-  email: null,
-  message: null
-});
-const STATUS_PATH_LOGIN_RETRY_COOLDOWN_MS = 60_000;
-const statusPathLoginBootstrap = {
-  promise: null,
-  status: 'idle',
-  message: null,
-  failedAt: null
-};
 const importOpencodePluginModule = new Function('specifier', 'return import(specifier)');
-let publishedSkillPreferenceCacheVersion = 0;
-const toIgnoredSkillSlug = value => {
-  const normalized = value.trim().toLowerCase();
-  if (!normalized) return null;
-  return normalized;
-};
-const toPublishedSkillPreferenceAction = value => {
-  const normalized = value.trim().toLowerCase();
-  if (normalized === 'install' || normalized === 'uninstall' || normalized === 'ignore' || normalized === 'unignore') {
-    return normalized;
-  }
-  throw new Error('Published skill preference action must be one of: install, uninstall, ignore, unignore.');
-};
-const toPublishedSkillPreferenceScope = (value, defaultScope) => {
-  if (!value) return defaultScope;
-  const normalized = value.trim().toLowerCase();
-  if (normalized === 'global' || normalized === 'project') return normalized;
-  throw new Error('Published skill preferenceScope must be either global or project.');
+export { resolvePluginStatusSnapshotWithAuthBootstrap } from './auth-bootstrap.js';
+export { setPublishedSkillIgnored, setPublishedSkillInstalled } from './preferences.js';
+const getDetailCacheKey = (catalogCacheKey, skillVersionId) => {
+  return JSON.stringify([catalogCacheKey, skillVersionId]);
 };
-const resolvePublishedSkillPreferenceCacheContext = async config => {
-  const authState = await readGlobalAuthState(config.authStatePath);
-  return {
-    userKey: toStoredUserKey(authState),
-    preferenceVersion: publishedSkillPreferenceCacheVersion
-  };
+const getDetailInflightKey = (catalogCacheKey, skillVersionId, purpose) => {
+  return JSON.stringify([catalogCacheKey, skillVersionId, purpose]);
 };
-const getCatalogCacheKey = (workspaceResolution, preferenceContext) => {
-  return JSON.stringify([workspaceResolution.cacheKey, preferenceContext.userKey, preferenceContext.preferenceVersion]);
+const SUPPORTED_WIZARD_ARTIFACT_KINDS = ['SKILL', 'DESIGN_DOC'];
+const DESIGN_DOC_UNSUPPORTED_MESSAGE = 'DESIGN_DOC is supported by generic wizard artifact persistence; use catalog/detail tools for assigned or installed documents.';
+const toWizardArtifactKind = value => {
+  if (!value) return 'SKILL';
+  const normalized = value.trim().toUpperCase().replace(/[-\s]+/gu, '_');
+  if (normalized === 'SKILL') return 'SKILL';
+  if (normalized === 'DESIGN_DOC') return 'DESIGN_DOC';
+  return null;
 };
-const startStatusPathLoginBootstrap = (worktree, config) => {
-  if (statusPathLoginBootstrap.promise) return;
-  if (statusPathLoginBootstrap.status === 'failed' && statusPathLoginBootstrap.failedAt && Date.now() - statusPathLoginBootstrap.failedAt < STATUS_PATH_LOGIN_RETRY_COOLDOWN_MS) {
-    return;
+const buildUnsupportedWizardArtifactOutput = ({
+  artifactKind,
+  directoryPath
+}) => ({
+  output: JSON.stringify({
+    pluginId: PLUGIN_ID,
+    runtimeMode: 'tool_fetch_only',
+    status: artifactKind === 'DESIGN_DOC' ? 'unsupported' : 'bad_artifact_kind',
+    artifactKind,
+    supportedArtifactKinds: SUPPORTED_WIZARD_ARTIFACT_KINDS,
+    requestedDirectoryPath: directoryPath,
+    message: artifactKind === 'DESIGN_DOC' ? DESIGN_DOC_UNSUPPORTED_MESSAGE : 'Unsupported wizard artifact kind. Use SKILL or DESIGN_DOC.'
+  }, null, 2),
+  metadata: {
+    status: artifactKind === 'DESIGN_DOC' ? 'unsupported' : 'bad_artifact_kind',
+    artifactKind,
+    directoryPath
   }
-  statusPathLoginBootstrap.status = 'pending';
-  statusPathLoginBootstrap.message = 'Browser login started automatically from the TUI/status path.';
-  statusPathLoginBootstrap.failedAt = null;
-  statusPathLoginBootstrap.promise = (async () => {
-    const loginSignal = AbortSignal.timeout(LOGIN_TIMEOUT_MS);
-    const loginStart = await startLoginFlow(loginSignal);
-    const browserOpenError = await openBrowser(loginStart.browserUrl);
-    if (browserOpenError) {
-      statusPathLoginBootstrap.message = `Automatic browser open failed. Open ${loginStart.browserUrl} manually.`;
-    }
-    try {
-      const callbackPayload = await loginStart.callbackPromise;
-      if (callbackPayload.status === 'error') {
-        throw new Error(callbackPayload.message);
-      }
-      if (callbackPayload.state !== loginStart.expectedState) {
-        throw new Error('OAuth callback state did not match the original login request.');
+});
+const withWizardArtifactEnvelope = (result, artifactKind) => {
+  if (!result || typeof result !== 'object' || !('output' in result)) return result;
+  const outputResult = result;
+  if (typeof outputResult.output !== 'string') return result;
+  try {
+    return {
+      ...outputResult,
+      output: JSON.stringify({
+        ...JSON.parse(outputResult.output),
+        artifactKind,
+        supportedArtifactKinds: SUPPORTED_WIZARD_ARTIFACT_KINDS,
+        compatibilityAliases: ['opencode_wizard_published_skills_fetch', 'opencode_wizard_published_skill_preference_set']
+      }, null, 2),
+      metadata: {
+        ...(outputResult.metadata ?? {}),
+        artifactKind
       }
-      const pluginSession = await createPluginSession({
-        code: callbackPayload.code,
-        codeVerifier: loginStart.codeVerifier,
-        redirectUri: OIDC_CALLBACK_URL,
-        config,
-        signal: loginSignal
-      });
-      const authState = toAuthState(pluginSession);
-      await writeAuthState(config.authStatePath, authState);
-      statusPathLoginBootstrap.status = 'authenticated';
-      statusPathLoginBootstrap.message = `Browser login completed successfully for ${authState.email}.`;
-      return authState;
-    } finally {
-      await loginStart.closeCallbackServer().catch(() => undefined);
-    }
-  })().catch(error => {
-    statusPathLoginBootstrap.status = 'failed';
-    statusPathLoginBootstrap.failedAt = Date.now();
-    statusPathLoginBootstrap.message = error instanceof Error ? error.message : 'Browser login failed.';
-    throw error;
-  }).finally(() => {
-    statusPathLoginBootstrap.promise = null;
-  });
-  statusPathLoginBootstrap.promise.catch(() => undefined);
-};
-export const resolvePluginStatusSnapshotWithAuthBootstrap = async ({
-  worktree,
-  directory,
-  signal
-}) => {
-  const snapshot = await resolvePluginStatusSnapshot({
-    worktree,
-    directory,
-    signal
-  });
-  if (snapshot.status !== 'missing_auth') return snapshot;
-  const config = await resolveConfig(worktree);
-  startStatusPathLoginBootstrap(worktree, config);
-  if (statusPathLoginBootstrap.message) {
-    return withStatusMessage(snapshot, statusPathLoginBootstrap.message);
+    };
+  } catch {
+    return result;
   }
-  return withStatusMessage(snapshot, 'Browser login is pending from the TUI/status path.');
 };
-const toBackendPreferenceScope = preferenceScope => {
-  if (preferenceScope === 'global') return 'GLOBAL';
-  return 'WORKSPACE';
+const matchesWizardArtifactIdentifier = (item, identifier) => {
+  const normalizedIdentifier = identifier.trim().toLowerCase();
+  if (!normalizedIdentifier) return false;
+  if (item.artifact.slug.toLowerCase() === normalizedIdentifier) return true;
+  if (item.artifact.name.toLowerCase() === normalizedIdentifier) return true;
+  if (item.artifactVersion.frontmatterName.toLowerCase() === normalizedIdentifier) return true;
+  return item.artifactVersion.id.toLowerCase() === normalizedIdentifier;
 };
-const setPublishedSkillPreference = async ({
-  worktree,
-  directory,
-  config,
-  skillSlug,
-  preferenceScope,
-  installed,
-  ignored
-}) => {
-  const workspaceResolution = await resolveWorkspace({
-    config,
-    directory
-  });
-  const response = await fetchPublishedSkillsGraphQl({
-    worktree,
-    config,
-    query: SET_PUBLISHED_SKILL_PREFERENCE_MUTATION,
-    variables: {
-      input: {
-        ...toDeliveryInput(workspaceResolution),
-        skillSlug,
-        preferenceScope: toBackendPreferenceScope(preferenceScope),
-        installed,
-        ignored
-      }
-    },
-    signal: AbortSignal.timeout(PRESENCE_EVENT_TIMEOUT_MS)
-  });
-  if (!response.ok) {
-    throw new Error(response.result.message);
-  }
-  const preferences = response.data.setPublishedSkillPreference;
-  publishedSkillPreferenceCacheVersion += 1;
+const selectWizardArtifacts = (items, identifiers) => {
+  const selectedItems = items.filter(item => identifiers.some(identifier => matchesWizardArtifactIdentifier(item, identifier)));
+  const missingIdentifiers = identifiers.filter(identifier => !selectedItems.some(item => matchesWizardArtifactIdentifier(item, identifier)));
   return {
-    scopeKey: preferences.scopeKey,
-    userKey: preferences.userKey,
-    ignoredSkillSlugs: preferences.ignoredSkills.map(item => item.skill.slug),
-    installedGlobalSkillSlugs: [],
-    installedWorkspaceSkillSlugs: []
+    selectedItems,
+    missingIdentifiers
   };
 };
-export const setPublishedSkillIgnored = async ({
-  worktree,
-  directory,
-  skillSlug,
-  ignored,
-  preferenceScope
-}) => {
-  const config = await resolveConfig(worktree);
-  const normalizedSkillSlug = toIgnoredSkillSlug(skillSlug);
-  if (!normalizedSkillSlug) {
-    throw new Error('Cannot toggle an empty published skill slug.');
-  }
-  return setPublishedSkillPreference({
-    worktree,
-    directory,
-    config,
-    skillSlug: normalizedSkillSlug,
-    preferenceScope: preferenceScope ?? 'project',
-    ignored
-  });
-};
-export const setPublishedSkillInstalled = async ({
-  worktree,
-  directory,
-  skillSlug,
-  installed,
-  preferenceScope
-}) => {
-  const config = await resolveConfig(worktree);
-  const normalizedSkillSlug = toIgnoredSkillSlug(skillSlug);
-  if (!normalizedSkillSlug) {
-    throw new Error('Cannot toggle an empty published skill slug.');
-  }
-  return setPublishedSkillPreference({
-    worktree,
-    directory,
-    config,
-    skillSlug: normalizedSkillSlug,
-    preferenceScope,
-    installed
-  });
-};
-const getDetailCacheKey = (catalogCacheKey, skillVersionId) => {
-  return JSON.stringify([catalogCacheKey, skillVersionId]);
-};
-const getDetailInflightKey = (catalogCacheKey, skillVersionId, purpose) => {
-  return JSON.stringify([catalogCacheKey, skillVersionId, purpose]);
-};
 export const OpencodeWizardSkillsPlugin = async input => {
   const {
     tool
@@ -561,20 +433,6 @@ export const OpencodeWizardSkillsPlugin = async input => {
     args,
     context
   }) => {
-    const authState = await resolveStoredAuthState(input.worktree, config);
-    if (!authState || authState.role !== 'ADMIN' && authState.role !== 'EDITOR') {
-      return {
-        output: JSON.stringify({
-          pluginId: PLUGIN_ID,
-          status: 'forbidden',
-          message: 'This tool requires ADMIN or EDITOR role. Your current session does not have the required permission.'
-        }, null, 2),
-        metadata: {
-          status: 'forbidden',
-          role: authState?.role ?? 'none'
-        }
-      };
-    }
     const requestedDirectory = normalizeDirectoryArg(context.directory, args.directory);
     const requestedSkills = parseRequestedSkillArgs(args);
     const fetchActionDirectoryPath = normalizeRepositoryPath(workspacePath, requestedDirectory);
@@ -632,7 +490,11 @@ export const OpencodeWizardSkillsPlugin = async input => {
     const selection = selectPublishedSkills(filteredPublishedSkillsResult.fetchResult.payload, requestedSkills);
     const isSingleRequest = requestedSkills.length === 1;
     if (requestedSkills.length === 0) {
-      const catalog = toPublishedSkillCatalog(filteredPublishedSkillsResult.fetchResult.payload);
+      const authState = await resolveStoredAuthState(input.worktree, config);
+      const catalog = {
+        ...toPublishedSkillCatalog(filteredPublishedSkillsResult.fetchResult.payload),
+        availableTools: resolveAvailableTools(authState?.role ?? null)
+      };
       context.metadata({
         title: `opencode-wizard published skills catalog: ${catalog.publishedSkillCount} active`,
         metadata: {
@@ -789,24 +651,241 @@ export const OpencodeWizardSkillsPlugin = async input => {
       }
     };
   };
-  const executeStatusTool = async ({
+  const executeWizardArtifactCatalogTool = async ({
     args,
     context
   }) => {
-    const authState = await resolveStoredAuthState(input.worktree, config);
-    if (!authState || authState.role !== 'ADMIN' && authState.role !== 'EDITOR') {
+    const requestedDirectory = normalizeDirectoryArg(context.directory, args.directory);
+    const directoryPath = normalizeRepositoryPath(workspacePath, requestedDirectory);
+    const artifactKind = toWizardArtifactKind(args.artifactKind);
+    if (!artifactKind) {
+      return buildUnsupportedWizardArtifactOutput({
+        artifactKind: args.artifactKind ?? '',
+        directoryPath
+      });
+    }
+    if (artifactKind === 'DESIGN_DOC') {
+      const workspaceResolution = await resolveWorkspace({
+        config,
+        directory: requestedDirectory
+      });
+      const fetchResult = await fetchWizardArtifactsCatalog(input.worktree, config, workspaceResolution, artifactKind, context.abort, clearPublishedSkillState);
+      if (!fetchResult.ok) {
+        return {
+          output: JSON.stringify({
+            pluginId: PLUGIN_ID,
+            runtimeMode: 'tool_fetch_only',
+            status: fetchResult.status,
+            artifactKind,
+            requestedDirectoryPath: directoryPath,
+            workspaceResolution: toWorkspaceResolutionOutput(workspaceResolution),
+            message: fetchResult.message,
+            fetchedAt: fetchResult.fetchedAt,
+            source: fetchResult.source
+          }, null, 2),
+          metadata: {
+            status: fetchResult.status,
+            artifactKind,
+            directoryPath,
+            source: fetchResult.source
+          }
+        };
+      }
+      const authState = await resolveStoredAuthState(input.worktree, config);
+      const catalog = toWizardArtifactCatalog(fetchResult.payload, {
+        pluginId: PLUGIN_ID,
+        availableTools: resolveAvailableTools(authState?.role ?? null)
+      });
       return {
         output: JSON.stringify({
+          ...catalog,
+          status: 'ready',
+          requestedDirectoryPath: directoryPath,
+          workspaceResolution: toWorkspaceResolutionOutput(workspaceResolution),
+          fetchedAt: fetchResult.fetchedAt,
+          source: fetchResult.source,
+          message: 'DESIGN_DOC catalog discovery only. Full DESIGN.md bodies/files require opencode_wizard_artifact_fetch with artifactKind DESIGN_DOC.'
+        }, null, 2),
+        metadata: {
+          status: 'ready',
+          artifactKind,
+          artifactCount: catalog.artifactCount.toString(),
+          ...toWorkspaceResolutionMetadata(workspaceResolution),
+          source: fetchResult.source
+        }
+      };
+    }
+    const result = await executePublishedSkillsFetchTool({
+      args: {
+        directory: args.directory,
+        refresh: args.refresh
+      },
+      context
+    });
+    return withWizardArtifactEnvelope(result, artifactKind);
+  };
+  const executeWizardArtifactFetchTool = async ({
+    args,
+    context
+  }) => {
+    const requestedDirectory = normalizeDirectoryArg(context.directory, args.directory);
+    const directoryPath = normalizeRepositoryPath(workspacePath, requestedDirectory);
+    const artifactKind = toWizardArtifactKind(args.artifactKind);
+    if (!artifactKind) {
+      return buildUnsupportedWizardArtifactOutput({
+        artifactKind: args.artifactKind ?? '',
+        directoryPath
+      });
+    }
+    if (artifactKind === 'DESIGN_DOC') {
+      const requestedArtifacts = parseRequestedSkillArgs({
+        skill: args.artifact,
+        skills: args.artifacts
+      });
+      const workspaceResolution = await resolveWorkspace({
+        config,
+        directory: requestedDirectory
+      });
+      const fetchResult = await fetchWizardArtifactsCatalog(input.worktree, config, workspaceResolution, artifactKind, context.abort, clearPublishedSkillState);
+      if (!fetchResult.ok) {
+        return {
+          output: JSON.stringify({
+            pluginId: PLUGIN_ID,
+            runtimeMode: 'tool_fetch_only',
+            status: fetchResult.status,
+            artifactKind,
+            requestedDirectoryPath: directoryPath,
+            workspaceResolution: toWorkspaceResolutionOutput(workspaceResolution),
+            message: fetchResult.message,
+            fetchedAt: fetchResult.fetchedAt,
+            source: fetchResult.source
+          }, null, 2),
+          metadata: {
+            status: fetchResult.status,
+            artifactKind,
+            directoryPath,
+            source: fetchResult.source
+          }
+        };
+      }
+      const selection = selectWizardArtifacts(fetchResult.payload.artifacts, requestedArtifacts);
+      if (requestedArtifacts.length === 0) {
+        const authState = await resolveStoredAuthState(input.worktree, config);
+        const catalog = toWizardArtifactCatalog(fetchResult.payload, {
           pluginId: PLUGIN_ID,
-          status: 'forbidden',
-          message: 'This tool requires ADMIN or EDITOR role. Your current session does not have the required permission.'
+          availableTools: resolveAvailableTools(authState?.role ?? null)
+        });
+        return {
+          output: JSON.stringify({
+            ...catalog,
+            status: 'ready',
+            requestedDirectoryPath: directoryPath,
+            workspaceResolution: toWorkspaceResolutionOutput(workspaceResolution),
+            fetchedAt: fetchResult.fetchedAt,
+            source: fetchResult.source,
+            message: 'Provide artifact or artifacts to fetch DESIGN.md body/files.'
+          }, null, 2),
+          metadata: {
+            status: 'ready',
+            artifactKind,
+            ...toWorkspaceResolutionMetadata(workspaceResolution)
+          }
+        };
+      }
+      if (selection.selectedItems.length === 0 && requestedArtifacts.length === 1) {
+        return {
+          output: JSON.stringify({
+            pluginId: PLUGIN_ID,
+            runtimeMode: 'tool_fetch_only',
+            status: 'not_found',
+            artifactKind,
+            requestedArtifact: requestedArtifacts[0],
+            availableArtifacts: fetchResult.payload.artifacts.map(toWizardArtifactSummary),
+            requestedDirectoryPath: directoryPath,
+            workspaceResolution: toWorkspaceResolutionOutput(workspaceResolution)
+          }, null, 2),
+          metadata: {
+            status: 'not_found',
+            artifactKind,
+            ...toWorkspaceResolutionMetadata(workspaceResolution)
+          }
+        };
+      }
+      const detailResults = await Promise.all(selection.selectedItems.map(item => fetchWizardArtifactDetail({
+        worktree: input.worktree,
+        config,
+        resolution: workspaceResolution,
+        artifactKind,
+        artifactVersionId: item.artifactVersion.id,
+        signal: context.abort,
+        onAuthStateChanged: clearPublishedSkillState,
+        purpose: 'TOOL_FETCH'
+      })));
+      const failedDetail = detailResults.find(result => !result.ok);
+      if (failedDetail && !failedDetail.ok) {
+        return {
+          output: JSON.stringify({
+            pluginId: PLUGIN_ID,
+            runtimeMode: 'tool_fetch_only',
+            status: failedDetail.result.status,
+            artifactKind,
+            requestedDirectoryPath: directoryPath,
+            workspaceResolution: toWorkspaceResolutionOutput(workspaceResolution),
+            message: failedDetail.result.message,
+            fetchedAt: failedDetail.result.fetchedAt,
+            source: failedDetail.result.source
+          }, null, 2),
+          metadata: {
+            status: failedDetail.result.status,
+            artifactKind,
+            ...toWorkspaceResolutionMetadata(workspaceResolution)
+          }
+        };
+      }
+      const details = detailResults.map((result, index) => {
+        if (!result.ok) throw new Error('Wizard artifact detail result unexpectedly missing after success guard.');
+        return toWizardArtifactDetail({
+          ...selection.selectedItems[index],
+          artifactVersion: result.artifact
+        });
+      });
+      return {
+        output: JSON.stringify({
+          pluginId: PLUGIN_ID,
+          runtimeMode: 'tool_fetch_only',
+          artifactKind,
+          requestedDirectoryPath: directoryPath,
+          workspaceResolution: toWorkspaceResolutionOutput(workspaceResolution),
+          workspace: fetchResult.payload.workspace,
+          fetchedAt: fetchResult.fetchedAt,
+          source: fetchResult.source,
+          requestedArtifacts,
+          missingArtifacts: selection.missingIdentifiers,
+          artifacts: details
         }, null, 2),
         metadata: {
-          status: 'forbidden',
-          role: authState?.role ?? 'none'
+          status: selection.missingIdentifiers.length > 0 ? 'partial' : 'ready',
+          artifactKind,
+          matchedCount: details.length.toString(),
+          ...toWorkspaceResolutionMetadata(workspaceResolution)
         }
       };
     }
+    const result = await executePublishedSkillsFetchTool({
+      args: {
+        skill: args.artifact,
+        skills: args.artifacts,
+        directory: args.directory,
+        refresh: args.refresh
+      },
+      context
+    });
+    return withWizardArtifactEnvelope(result, artifactKind);
+  };
+  const executeStatusTool = async ({
+    args,
+    context
+  }) => {
     const requestedDirectory = normalizeDirectoryArg(context.directory, args.directory);
     let snapshot = await resolvePluginStatusSnapshot({
       worktree: input.worktree,
@@ -844,20 +923,6 @@ export const OpencodeWizardSkillsPlugin = async input => {
     args,
     context
   }) => {
-    const authState = await resolveStoredAuthState(input.worktree, config);
-    if (!authState || authState.role !== 'ADMIN' && authState.role !== 'EDITOR') {
-      return {
-        output: JSON.stringify({
-          pluginId: PLUGIN_ID,
-          status: 'forbidden',
-          message: 'This tool requires ADMIN or EDITOR role. Your current session does not have the required permission.'
-        }, null, 2),
-        metadata: {
-          status: 'forbidden',
-          role: authState?.role ?? 'none'
-        }
-      };
-    }
     const requestedDirectory = normalizeDirectoryArg(context.directory, args.directory);
     const directoryPath = normalizeRepositoryPath(workspacePath, requestedDirectory);
     lastInteractiveDirectoryPath = directoryPath;
@@ -882,7 +947,13 @@ export const OpencodeWizardSkillsPlugin = async input => {
         signal: context.abort
       });
       if (!catalogResult.fetchResult.ok) {
-        throw new Error(`Cannot resolve published skill preference target: ${catalogResult.fetchResult.message}`);
+        await emitPreferenceOutcome('PREFERENCE_FAILED');
+        return toFetchFailureOutput({
+          worktree: input.worktree,
+          config,
+          publishedSkillsResult: catalogResult,
+          loginBootstrapSnapshot: loginBootstrap.snapshot
+        });
       }
       const selectableCatalogSkills = catalogResult.fetchResult.payload.catalogSkills.map(item => ({
         ...item,
@@ -941,8 +1012,132 @@ export const OpencodeWizardSkillsPlugin = async input => {
       };
     } catch (error) {
       await emitPreferenceOutcome('PREFERENCE_FAILED');
-      throw error;
+      const message = error instanceof Error ? error.message : 'Unknown published skill preference failure.';
+      const metadata = {
+        status: 'preference_failed',
+        directoryPath
+      };
+      context.metadata({
+        title: 'opencode-wizard published skill preference failed',
+        metadata
+      });
+      return {
+        output: JSON.stringify({
+          pluginId: PLUGIN_ID,
+          status: 'preference_failed',
+          requestedIdentifier: requestedSkill,
+          requestedDirectoryPath: directoryPath,
+          message,
+          guidance: 'The preference tool remains available. Check opencode_wizard_status for safe auth/catalog state, rerun fetch/status to bootstrap auth, and retry after catalog status is ready.'
+        }, null, 2),
+        metadata
+      };
+    }
+  };
+  const executeWizardArtifactPreferenceTool = async ({
+    args,
+    context
+  }) => {
+    const requestedDirectory = normalizeDirectoryArg(context.directory, args.directory);
+    const directoryPath = normalizeRepositoryPath(workspacePath, requestedDirectory);
+    const artifactKind = toWizardArtifactKind(args.artifactKind);
+    if (!artifactKind) {
+      return buildUnsupportedWizardArtifactOutput({
+        artifactKind: args.artifactKind ?? '',
+        directoryPath
+      });
+    }
+    if (artifactKind === 'DESIGN_DOC') {
+      try {
+        const action = toPublishedSkillPreferenceAction(args.action);
+        const workspaceResolution = await resolveWorkspace({
+          config,
+          directory: requestedDirectory
+        });
+        const response = await fetchPublishedSkillsGraphQl({
+          worktree: input.worktree,
+          config,
+          query: SET_WIZARD_ARTIFACT_PREFERENCE_MUTATION,
+          variables: {
+            input: {
+              workspaceSlug: workspaceResolution.workspaceSlug,
+              repositoryUrl: workspaceResolution.repositoryUrl,
+              directoryPath: workspaceResolution.directoryPath,
+              artifactKind,
+              artifactSlug: args.artifact.trim(),
+              preferenceScope: toPublishedSkillPreferenceScope(args.preferenceScope, 'project') === 'global' ? 'GLOBAL' : 'WORKSPACE',
+              installed: action === 'install' ? true : action === 'uninstall' ? false : undefined,
+              ignored: action === 'ignore' ? true : action === 'unignore' ? false : undefined
+            }
+          },
+          signal: context.abort,
+          onAuthStateChanged: clearPublishedSkillState
+        });
+        if (!response.ok) {
+          return {
+            output: JSON.stringify({
+              pluginId: PLUGIN_ID,
+              status: response.result.status,
+              artifactKind,
+              requestedIdentifier: args.artifact,
+              requestedDirectoryPath: directoryPath,
+              message: response.result.message,
+              fetchedAt: response.result.fetchedAt,
+              source: response.result.source
+            }, null, 2),
+            metadata: {
+              status: response.result.status,
+              artifactKind,
+              directoryPath
+            }
+          };
+        }
+        return {
+          output: JSON.stringify({
+            pluginId: PLUGIN_ID,
+            status: 'updated',
+            artifactKind,
+            requestedIdentifier: args.artifact,
+            action,
+            requestedDirectoryPath: directoryPath,
+            preferenceState: response.data.setWizardArtifactPreference,
+            message: 'Wizard artifact preference updated through the generic backend API.'
+          }, null, 2),
+          metadata: {
+            status: 'updated',
+            artifactKind,
+            directoryPath,
+            action
+          }
+        };
+      } catch (error) {
+        return {
+          output: JSON.stringify({
+            pluginId: PLUGIN_ID,
+            status: 'preference_failed',
+            artifactKind,
+            requestedIdentifier: args.artifact,
+            requestedDirectoryPath: directoryPath,
+            message: error instanceof Error ? error.message : 'Unknown wizard artifact preference failure.'
+          }, null, 2),
+          metadata: {
+            status: 'preference_failed',
+            artifactKind,
+            directoryPath
+          }
+        };
+      }
     }
+    const result = await executePublishedSkillPreferenceTool({
+      args: {
+        skill: args.artifact,
+        action: args.action,
+        preferenceScope: args.preferenceScope,
+        directory: args.directory
+      },
+      context
+    });
+    return withWizardArtifactEnvelope(result, artifactKind);
   };
   const executeEditorPublishSkillTool = async ({
     args,
@@ -1038,8 +1233,122 @@ export const OpencodeWizardSkillsPlugin = async input => {
       }
     };
   };
+  const executeWizardArtifactImportTool = async ({
+    args,
+    context
+  }) => {
+    const authState = await resolveStoredAuthState(input.worktree, config);
+    const importPlan = planWizardArtifactImport({
+      artifactKind: args.artifactKind,
+      source: args.source,
+      slug: args.slug,
+      skill: args.skill
+    });
+    if (!authState || authState.role !== 'EDITOR') {
+      return {
+        output: JSON.stringify({
+          pluginId: PLUGIN_ID,
+          status: 'forbidden',
+          artifactKind: importPlan.artifactKind,
+          source: importPlan.source,
+          message: 'This tool requires EDITOR role. Your current session does not have the required editor permission.'
+        }, null, 2),
+        metadata: {
+          status: 'forbidden',
+          role: authState?.role ?? 'none'
+        }
+      };
+    }
+    const requestedDirectory = normalizeDirectoryArg(context.directory, args.directory);
+    const directoryPath = normalizeRepositoryPath(workspacePath, requestedDirectory);
+    lastInteractiveDirectoryPath = directoryPath;
+    let importSource;
+    try {
+      importSource = await fetchWizardArtifactImportSource({
+        artifactKind: args.artifactKind,
+        source: args.source,
+        slug: args.slug,
+        skill: args.skill,
+        signal: context.abort
+      });
+    } catch (error) {
+      return {
+        output: JSON.stringify({
+          pluginId: PLUGIN_ID,
+          status: 'source_fetch_failed',
+          artifactKind: importPlan.artifactKind,
+          source: importPlan.source,
+          candidateUrls: importPlan.candidateUrls,
+          message: error instanceof Error ? error.message : 'Unknown import source fetch failure.'
+        }, null, 2),
+        metadata: {
+          status: 'source_fetch_failed',
+          artifactKind: importPlan.artifactKind,
+          directoryPath
+        }
+      };
+    }
+    const response = await fetchPublishedSkillsGraphQl({
+      worktree: input.worktree,
+      config,
+      query: IMPORT_WIZARD_ARTIFACT_SNAPSHOT_MUTATION,
+      variables: {
+        input: {
+          artifactKind: importSource.artifactKind,
+          slug: importSource.slug,
+          name: args.name,
+          summary: args.summary,
+          markdownContent: importSource.markdownContent,
+          source: importSource.fetchedUrl,
+          sourceSnapshotRef: importSource.sourceRef
+        }
+      },
+      signal: context.abort
+    });
+    if (!response.ok) {
+      return {
+        output: JSON.stringify({
+          pluginId: PLUGIN_ID,
+          status: 'request_failed',
+          artifactKind: importSource.artifactKind,
+          source: importSource.source,
+          fetchedUrl: importSource.fetchedUrl,
+          message: response.result.message
+        }, null, 2),
+        metadata: {
+          status: 'request_failed',
+          artifactKind: importSource.artifactKind,
+          directoryPath
+        }
+      };
+    }
+    const payload = response.data.importWizardArtifactSnapshot;
+    await scheduleInteractivePresenceStart();
+    return {
+      output: JSON.stringify({
+        pluginId: PLUGIN_ID,
+        status: payload.success ? 'imported' : 'import_failed',
+        artifactKind: importSource.artifactKind,
+        artifactSlug: payload.artifactSlug,
+        artifactVersionId: payload.artifactVersionId,
+        skillSlug: payload.skillSlug,
+        skillVersionId: payload.skillVersionId,
+        source: importSource.source,
+        fetchedUrl: importSource.fetchedUrl,
+        sourceSnapshotRef: importSource.sourceRef,
+        errors: payload.errors,
+        message: 'Imported backend artifact is now the wizard/plugin runtime authority; no project files were written.'
+      }, null, 2),
+      metadata: {
+        status: payload.success ? 'imported' : 'import_failed',
+        artifactKind: importSource.artifactKind,
+        artifactSlug: payload.artifactSlug ?? '',
+        artifactVersionId: payload.artifactVersionId ?? '',
+        directoryPath
+      }
+    };
+  };
   const role = initialAuthState?.role ?? null;
-  const hasSharedToolAccess = role === 'ADMIN' || role === 'EDITOR';
   const isEditor = role === 'EDITOR';
   const {
     sharedTools,
@@ -1049,10 +1358,22 @@ export const OpencodeWizardSkillsPlugin = async input => {
       args,
       context
     }),
+    fetchWizardArtifactCatalog: (args, context) => executeWizardArtifactCatalogTool({
+      args,
+      context
+    }),
+    fetchWizardArtifacts: (args, context) => executeWizardArtifactFetchTool({
+      args,
+      context
+    }),
     updatePublishedSkillPreference: (args, context) => executePublishedSkillPreferenceTool({
       args,
       context
     }),
+    updateWizardArtifactPreference: (args, context) => executeWizardArtifactPreferenceTool({
+      args,
+      context
+    }),
     getStatus: (args, context) => executeStatusTool({
       args,
       context
@@ -1060,10 +1381,14 @@ export const OpencodeWizardSkillsPlugin = async input => {
     publishEditorSkill: (args, context) => executeEditorPublishSkillTool({
       args,
       context
+    }),
+    importWizardArtifact: (args, context) => executeWizardArtifactImportTool({
+      args,
+      context
     })
   });
   return {
-    tool: !hasSharedToolAccess ? {} : {
+    tool: {
       ...sharedTools,
       ...(isEditor ? editorOnlyTools : {})
     },