@nextclaw/service 0.1.1

package/dist/cli/commands/secrets/index.js

@@ -0,0 +1,280 @@
+import { getAtConfigPath, parseRequiredConfigPath } from "../../../shared/utils/config-path.js";
+import { buildReloadPlan, diffConfigPaths, getConfigPath, loadConfig, resolveConfigSecrets, saveConfig } from "@nextclaw/core";
+import { readFileSync } from "node:fs";
+//#region src/cli/commands/secrets/index.ts
+const SECRET_SOURCES = [
+	"env",
+	"file",
+	"exec"
+];
+function normalizeSecretSource(value) {
+	if (typeof value !== "string") return null;
+	const normalized = value.trim().toLowerCase();
+	return SECRET_SOURCES.includes(normalized) ? normalized : null;
+}
+function normalizeOptionalString(value) {
+	if (typeof value !== "string") return;
+	return value.trim() || void 0;
+}
+function parseTimeoutMs(value) {
+	if (value === void 0 || value === null || value === "") return;
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`invalid timeout: ${String(value)}`);
+	return Math.trunc(parsed);
+}
+function inferProviderAlias(config, ref) {
+	const explicit = normalizeOptionalString(ref.provider);
+	if (explicit) return explicit;
+	const defaultAlias = normalizeOptionalString(config.secrets.defaults[ref.source]);
+	if (defaultAlias) return defaultAlias;
+	return ref.source;
+}
+function summarizeAudit(items) {
+	const ok = items.filter((item) => item.ok).length;
+	return {
+		total: items.length,
+		ok,
+		failed: items.length - ok
+	};
+}
+function parseRefsPatch(raw) {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) throw new Error("refs patch must be an object");
+	const output = {};
+	for (const [path, value] of Object.entries(raw)) {
+		if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`invalid ref for ${path}`);
+		const source = normalizeSecretSource(value.source);
+		const id = normalizeOptionalString(value.id);
+		const provider = normalizeOptionalString(value.provider);
+		if (!source || !id) throw new Error(`invalid ref for ${path}: source/id is required`);
+		output[path] = {
+			source,
+			...provider ? { provider } : {},
+			id
+		};
+	}
+	return output;
+}
+function parseApplyFile(raw) {
+	const data = JSON.parse(raw);
+	if (!data || typeof data !== "object" || Array.isArray(data)) throw new Error("apply file must be an object");
+	const record = data;
+	if (record.refs || record.providers || record.defaults || Object.prototype.hasOwnProperty.call(record, "enabled")) {
+		const patch = {};
+		if (Object.prototype.hasOwnProperty.call(record, "enabled")) patch.enabled = Boolean(record.enabled);
+		if (record.defaults && typeof record.defaults === "object" && !Array.isArray(record.defaults)) patch.defaults = record.defaults;
+		if (record.providers && typeof record.providers === "object" && !Array.isArray(record.providers)) patch.providers = record.providers;
+		if (record.refs) patch.refs = parseRefsPatch(record.refs);
+		return patch;
+	}
+	return { refs: parseRefsPatch(record) };
+}
+var SecretsCommands = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	audit = (opts = {}) => {
+		const config = loadConfig();
+		const configPath = getConfigPath();
+		const refs = config.secrets.refs;
+		const items = [];
+		for (const [path, ref] of Object.entries(refs)) {
+			const provider = inferProviderAlias(config, ref);
+			const scopedConfig = structuredClone(config);
+			scopedConfig.secrets.refs = { [path]: ref };
+			try {
+				const target = getAtConfigPath(resolveConfigSecrets(scopedConfig, { configPath }), parseRequiredConfigPath(path));
+				if (!target.found) {
+					items.push({
+						path,
+						source: ref.source,
+						provider,
+						id: ref.id,
+						ok: false,
+						detail: "resolved but path not found"
+					});
+					continue;
+				}
+				const resolvedValue = target.value;
+				const detail = typeof resolvedValue === "string" ? `resolved (length=${resolvedValue.length})` : `resolved (${typeof resolvedValue})`;
+				items.push({
+					path,
+					source: ref.source,
+					provider,
+					id: ref.id,
+					ok: true,
+					detail
+				});
+			} catch (error) {
+				items.push({
+					path,
+					source: ref.source,
+					provider,
+					id: ref.id,
+					ok: false,
+					detail: String(error)
+				});
+			}
+		}
+		const summary = summarizeAudit(items);
+		if (opts.json) console.log(JSON.stringify({
+			summary,
+			items
+		}, null, 2));
+		else if (!items.length) console.log("No secret refs configured.");
+		else {
+			for (const item of items) {
+				const status = item.ok ? "OK" : "ERROR";
+				console.log(`[${status}] ${item.path} <- ${item.source}:${item.provider}:${item.id} (${item.detail})`);
+			}
+			console.log(`Summary: total=${summary.total}, ok=${summary.ok}, failed=${summary.failed}`);
+		}
+		if (Boolean(opts.strict) && summary.failed > 0) process.exitCode = 1;
+	};
+	configure = async (opts) => {
+		const alias = normalizeOptionalString(opts.provider);
+		if (!alias) throw new Error("provider alias is required");
+		const prevConfig = loadConfig();
+		const nextConfig = structuredClone(prevConfig);
+		const remove = Boolean(opts.remove);
+		if (remove) this.removeProvider(nextConfig, alias);
+		else this.configureProvider(nextConfig, alias, opts);
+		resolveConfigSecrets(nextConfig, { configPath: getConfigPath() });
+		saveConfig(nextConfig);
+		await this.requestRestartForConfigDiff({
+			prevConfig,
+			nextConfig,
+			reason: `secrets.configure ${alias}`,
+			manualMessage: "Secrets provider updated. Restart the gateway if required."
+		});
+		if (opts.json) {
+			console.log(JSON.stringify({
+				ok: true,
+				providers: nextConfig.secrets.providers,
+				defaults: nextConfig.secrets.defaults
+			}, null, 2));
+			return;
+		}
+		console.log(`Secrets provider ${remove ? "removed" : "configured"}: ${alias}`);
+	};
+	apply = async (opts) => {
+		const prevConfig = loadConfig();
+		const nextConfig = structuredClone(prevConfig);
+		this.applyEnabledPatch(nextConfig, opts);
+		this.applyFilePatch(nextConfig, opts);
+		this.applySingleRefPatch(nextConfig, opts);
+		resolveConfigSecrets(nextConfig, { configPath: getConfigPath() });
+		saveConfig(nextConfig);
+		await this.requestRestartForConfigDiff({
+			prevConfig,
+			nextConfig,
+			reason: "secrets.apply",
+			manualMessage: "Secrets updated. Restart the gateway if required."
+		});
+		if (opts.json) {
+			console.log(JSON.stringify({
+				ok: true,
+				secrets: nextConfig.secrets
+			}, null, 2));
+			return;
+		}
+		console.log("Secrets applied.");
+	};
+	reload = async (opts = {}) => {
+		const config = loadConfig();
+		resolveConfigSecrets(config, { configPath: getConfigPath() });
+		saveConfig(config);
+		if (opts.json) {
+			console.log(JSON.stringify({
+				ok: true,
+				message: "secrets reload signal emitted"
+			}, null, 2));
+			return;
+		}
+		console.log("Secrets reload signal emitted.");
+	};
+	removeProvider = (config, alias) => {
+		delete config.secrets.providers[alias];
+		for (const source of SECRET_SOURCES) if (config.secrets.defaults[source] === alias) delete config.secrets.defaults[source];
+	};
+	configureProvider = (config, alias, opts) => {
+		const source = normalizeSecretSource(opts.source);
+		if (!source) throw new Error("source is required and must be one of env/file/exec");
+		config.secrets.providers[alias] = this.buildProviderConfig(source, opts);
+		if (opts.setDefault) config.secrets.defaults[source] = alias;
+	};
+	buildProviderConfig = (source, opts) => {
+		if (source === "env") return {
+			source,
+			...normalizeOptionalString(opts.prefix) ? { prefix: normalizeOptionalString(opts.prefix) } : {}
+		};
+		if (source === "file") {
+			const path = normalizeOptionalString(opts.path);
+			if (!path) throw new Error("file source requires --path");
+			return {
+				source,
+				path,
+				format: "json"
+			};
+		}
+		const command = normalizeOptionalString(opts.command);
+		if (!command) throw new Error("exec source requires --command");
+		return {
+			source,
+			command,
+			args: Array.isArray(opts.arg) ? opts.arg : [],
+			...normalizeOptionalString(opts.cwd) ? { cwd: normalizeOptionalString(opts.cwd) } : {},
+			timeoutMs: parseTimeoutMs(opts.timeoutMs) ?? 5e3
+		};
+	};
+	applyEnabledPatch = (config, opts) => {
+		const { disable, enable } = opts;
+		if (enable && disable) throw new Error("cannot set --enable and --disable at the same time");
+		if (enable || disable) config.secrets.enabled = Boolean(enable);
+	};
+	applyFilePatch = (config, opts) => {
+		if (!opts.file) return;
+		const { defaults, providers, refs } = parseApplyFile(readFileSync(opts.file, "utf-8"));
+		if (defaults) config.secrets.defaults = defaults;
+		if (providers) config.secrets.providers = providers;
+		if (refs) config.secrets.refs = {
+			...config.secrets.refs,
+			...refs
+		};
+	};
+	applySingleRefPatch = (config, opts) => {
+		if (!opts.path) {
+			if (opts.remove && !opts.file) throw new Error("--remove requires --path");
+			return;
+		}
+		const path = opts.path.trim();
+		if (!path) throw new Error("path is empty");
+		if (opts.remove) {
+			delete config.secrets.refs[path];
+			return;
+		}
+		const source = normalizeSecretSource(opts.source);
+		const id = normalizeOptionalString(opts.id);
+		if (!source || !id) throw new Error("apply single ref requires --source and --id");
+		const provider = normalizeOptionalString(opts.provider);
+		config.secrets.refs[path] = {
+			source,
+			id,
+			...provider ? { provider } : {}
+		};
+	};
+	requestRestartForConfigDiff = async (params) => {
+		const { manualMessage, nextConfig, prevConfig, reason } = params;
+		const changedPaths = diffConfigPaths(prevConfig, nextConfig);
+		if (!changedPaths.length) return;
+		const plan = buildReloadPlan(changedPaths);
+		if (plan.restartRequired.length === 0) return;
+		await this.deps.requestRestart({
+			changedPaths: plan.restartRequired,
+			mode: "notify",
+			reason: `${reason} (${plan.restartRequired.join(", ")})`,
+			manualMessage
+		});
+	};
+};
+//#endregion
+export { SecretsCommands };

package/dist/cli/commands/serve/index.d.ts

@@ -0,0 +1,14 @@
+import { StartCommandOptions } from "../../../shared/types/cli.types.js";
+import { RuntimeCommandService } from "../../../shared/services/runtime/runtime-command.service.js";
+
+//#region src/cli/commands/serve/index.d.ts
+declare class ServeCommands {
+  private readonly deps;
+  constructor(deps: {
+    runtimeCommandService: RuntimeCommandService;
+    forcedPublicHost: string;
+  });
+  run: (opts: StartCommandOptions) => Promise<void>;
+}
+//#endregion
+export { ServeCommands };

package/dist/cli/commands/serve/index.js

@@ -0,0 +1,19 @@
+import { resolveManagedServiceUiOverrides } from "../../../shared/utils/runtime-helpers.js";
+//#region src/cli/commands/serve/index.ts
+var ServeCommands = class {
+	constructor(deps) {
+		this.deps = deps;
+	}
+	run = async (opts) => {
+		const uiOverrides = resolveManagedServiceUiOverrides({
+			uiPort: opts.uiPort,
+			forcedPublicHost: this.deps.forcedPublicHost
+		});
+		await this.deps.runtimeCommandService.runForeground({
+			uiOverrides,
+			open: Boolean(opts.open)
+		});
+	};
+};
+//#endregion
+export { ServeCommands };

package/dist/cli/commands/skills/index.d.ts

@@ -0,0 +1,26 @@
+import { MarketplaceSkillsRecommendCommandOptions, MarketplaceSkillsSearchCommandOptions, SkillsInfoCommandOptions, SkillsInstalledCommandOptions } from "../../../shared/types/cli.types.js";
+import { MarketplacePublishCommandOptions } from "./marketplace-command-options.utils.js";
+
+//#region src/cli/commands/skills/index.d.ts
+declare class SkillsCommands {
+  private readonly skillsQueryService;
+  installed: (options?: SkillsInstalledCommandOptions) => Promise<void>;
+  info: (selector: string, options?: SkillsInfoCommandOptions) => Promise<void>;
+  install: (options: {
+    slug: string;
+    workdir?: string;
+    dir?: string;
+    force?: boolean;
+    apiBaseUrl?: string;
+  }) => Promise<void>;
+  marketplaceSearch: (options?: MarketplaceSkillsSearchCommandOptions) => Promise<void>;
+  marketplaceInfo: (slug: string, options?: {
+    apiBase?: string;
+    json?: boolean;
+  }) => Promise<void>;
+  marketplaceRecommend: (options?: MarketplaceSkillsRecommendCommandOptions) => Promise<void>;
+  publish: (options: MarketplacePublishCommandOptions) => Promise<void>;
+  update: (options: Omit<MarketplacePublishCommandOptions, "publishedAt">) => Promise<void>;
+}
+//#endregion
+export { SkillsCommands };

package/dist/cli/commands/skills/index.js

@@ -0,0 +1,147 @@
+import { resolveSkillsInstallWorkdir } from "../../../shared/utils/runtime-helpers.js";
+import { buildMarketplacePublishOptions, buildMarketplaceUpdateOptions } from "./marketplace-command-options.utils.js";
+import { installMarketplaceSkill, publishMarketplaceSkill } from "./marketplace.service.js";
+import { SkillsQueryService } from "./skills-query.service.js";
+import { loadConfig } from "@nextclaw/core";
+//#region src/cli/commands/skills/index.ts
+var SkillsCommands = class {
+	skillsQueryService = new SkillsQueryService();
+	installed = async (options = {}) => {
+		const config = loadConfig();
+		const workdir = resolveSkillsInstallWorkdir({
+			explicitWorkdir: options.workdir,
+			configuredWorkspace: config.agents.defaults.workspace
+		});
+		const result = this.skillsQueryService.listInstalled({
+			workdir,
+			scope: options.scope,
+			query: options.query
+		});
+		if (options.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		if (result.skills.length === 0) {
+			console.log("No installed skills found.");
+			return;
+		}
+		for (const skill of result.skills) {
+			console.log(`${skill.name} (${skill.scope})`);
+			console.log(`  ref: ${skill.ref}`);
+			console.log(`  path: ${skill.path}`);
+			console.log(`  summary: ${skill.summary ?? "-"}`);
+			console.log(`  description: ${skill.description ?? "-"}`);
+			console.log(`  tags: ${skill.tags.join(", ") || "-"}`);
+			console.log(`  always: ${skill.always ? "yes" : "no"}`);
+		}
+	};
+	info = async (selector, options = {}) => {
+		const config = loadConfig();
+		const workdir = resolveSkillsInstallWorkdir({
+			explicitWorkdir: options.workdir,
+			configuredWorkspace: config.agents.defaults.workspace
+		});
+		const result = this.skillsQueryService.getInstalledInfo({
+			workdir,
+			selector
+		});
+		if (options.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		console.log(`${result.name} (${result.scope})`);
+		console.log(`  ref: ${result.ref}`);
+		console.log(`  path: ${result.path}`);
+		console.log(`  summary: ${result.summary ?? "-"}`);
+		console.log(`  description: ${result.description ?? "-"}`);
+		console.log(`  author: ${result.author ?? "-"}`);
+		console.log(`  tags: ${result.tags.join(", ") || "-"}`);
+		console.log(`  always: ${result.always ? "yes" : "no"}`);
+	};
+	install = async (options) => {
+		const { apiBaseUrl, dir, force, slug, workdir: explicitWorkdir } = options;
+		const result = await installMarketplaceSkill({
+			slug,
+			workdir: resolveSkillsInstallWorkdir({
+				explicitWorkdir,
+				configuredWorkspace: loadConfig().agents.defaults.workspace
+			}),
+			dir,
+			force,
+			apiBaseUrl
+		});
+		if (result.alreadyInstalled) console.log(`✓ ${result.slug} is already installed`);
+		else console.log(`✓ Installed ${result.slug} (${result.source})`);
+		console.log(`  Path: ${result.destinationDir}`);
+	};
+	marketplaceSearch = async (options = {}) => {
+		const result = await this.skillsQueryService.searchMarketplaceSkills({
+			apiBaseUrl: options.apiBase,
+			query: options.query,
+			tag: options.tag,
+			sort: options.sort,
+			page: options.page,
+			pageSize: options.pageSize
+		});
+		if (options.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		if (result.items.length === 0) {
+			console.log("No marketplace skills found.");
+			return;
+		}
+		for (const item of result.items) {
+			console.log(`${item.name} (${item.slug})`);
+			console.log(`  summary: ${item.summary}`);
+			console.log(`  author: ${item.author}`);
+			console.log(`  tags: ${item.tags.join(", ") || "-"}`);
+			console.log(`  install: ${item.install.command}`);
+		}
+	};
+	marketplaceInfo = async (slug, options = {}) => {
+		const result = await this.skillsQueryService.getMarketplaceSkillInfo({
+			apiBaseUrl: options.apiBase,
+			slug
+		});
+		if (options.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		console.log(`${result.item.name} (${result.item.slug})`);
+		console.log(`  summary: ${result.item.summary}`);
+		console.log(`  description: ${result.item.description ?? "-"}`);
+		console.log(`  author: ${result.item.author}`);
+		console.log(`  tags: ${result.item.tags.join(", ") || "-"}`);
+		console.log(`  install: ${result.item.install.command}`);
+		console.log(`  content: ${result.content ? "available" : "unavailable"}`);
+		if (result.content) console.log(`  source: ${result.content.source}`);
+		else if (result.contentUnavailableReason) console.log(`  reason: ${result.contentUnavailableReason}`);
+	};
+	marketplaceRecommend = async (options = {}) => {
+		const result = await this.skillsQueryService.recommendMarketplaceSkills({
+			apiBaseUrl: options.apiBase,
+			scene: options.scene,
+			limit: options.limit
+		});
+		if (options.json) {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+		console.log(`${result.title} (${result.sceneId})`);
+		if (result.description) console.log(`  ${result.description}`);
+		for (const item of result.items) console.log(`- ${item.name} (${item.slug})`);
+	};
+	publish = async (options) => {
+		const result = await publishMarketplaceSkill(buildMarketplacePublishOptions(options));
+		console.log(`${result.created ? `✓ Published new skill: ${result.packageName}` : `✓ Updated skill: ${result.packageName}`}\n  Alias: ${result.slug}\n  Files: ${result.fileCount}`);
+	};
+	update = async (options) => {
+		const result = await publishMarketplaceSkill(buildMarketplaceUpdateOptions(options));
+		console.log(`✓ Updated skill: ${result.packageName}`);
+		console.log(`  Alias: ${result.slug}`);
+		console.log(`  Files: ${result.fileCount}`);
+	};
+};
+//#endregion
+export { SkillsCommands };

package/dist/cli/commands/skills/marketplace-client.d.ts

@@ -0,0 +1,31 @@
+//#region src/cli/commands/skills/marketplace-client.d.ts
+type MarketplaceEnvelope<T> = {
+  ok: boolean;
+  data?: T;
+  error?: {
+    code?: string;
+    message?: string;
+  };
+};
+type MarketplaceSkillInstallKind = "builtin" | "marketplace";
+type MarketplaceSkillFileManifestEntry = {
+  path: string;
+  downloadPath?: string;
+  contentBase64?: string;
+};
+declare function resolveMarketplaceApiBase(explicitBase: string | undefined): string;
+declare function resolveMarketplaceAdminToken(explicitToken: string | undefined): string | undefined;
+declare function fetchMarketplaceSkillItem(apiBase: string, slug: string): Promise<{
+  slug: string;
+  packageName?: string;
+  install: {
+    kind: MarketplaceSkillInstallKind;
+  };
+}>;
+declare function fetchMarketplaceSkillFiles(apiBase: string, slug: string): Promise<{
+  files: MarketplaceSkillFileManifestEntry[];
+}>;
+declare function fetchMarketplaceSkillFileBlob(apiBase: string, slug: string, file: MarketplaceSkillFileManifestEntry): Promise<Buffer>;
+declare function readMarketplaceEnvelope<T>(response: Response): Promise<MarketplaceEnvelope<T>>;
+//#endregion
+export { MarketplaceSkillFileManifestEntry, fetchMarketplaceSkillFileBlob, fetchMarketplaceSkillFiles, fetchMarketplaceSkillItem, readMarketplaceEnvelope, resolveMarketplaceAdminToken, resolveMarketplaceApiBase };

package/dist/cli/commands/skills/marketplace-client.js

@@ -0,0 +1,84 @@
+import { runWithMarketplaceNetworkRetry } from "./marketplace-network-retry.js";
+//#region src/cli/commands/skills/marketplace-client.ts
+const DEFAULT_MARKETPLACE_API_BASE = "https://marketplace-api.nextclaw.io";
+function resolveMarketplaceApiBase(explicitBase) {
+	return (explicitBase?.trim() || process.env.NEXTCLAW_MARKETPLACE_API_BASE?.trim() || DEFAULT_MARKETPLACE_API_BASE).replace(/\/+$/, "");
+}
+function resolveMarketplaceAdminToken(explicitToken) {
+	const token = explicitToken?.trim() || process.env.NEXTCLAW_MARKETPLACE_ADMIN_TOKEN?.trim();
+	return token && token.length > 0 ? token : void 0;
+}
+async function fetchMarketplaceSkillItem(apiBase, slug) {
+	return runWithMarketplaceNetworkRetry(async () => {
+		const response = await fetch(`${apiBase}/api/v1/skills/items/${encodeURIComponent(slug)}`, { headers: { Accept: "application/json" } });
+		const payload = await readMarketplaceEnvelope(response);
+		if (!payload.ok || !payload.data) {
+			const message = payload.error?.message || `marketplace skill fetch failed: ${response.status}`;
+			throw new Error(message);
+		}
+		const kind = payload.data.install?.kind;
+		if (kind !== "builtin" && kind !== "marketplace") throw new Error(`Unsupported skill install kind from marketplace: ${String(kind)}`);
+		return {
+			slug: typeof payload.data.slug === "string" && payload.data.slug.trim() ? payload.data.slug.trim() : slug,
+			packageName: typeof payload.data.packageName === "string" && payload.data.packageName.trim() ? payload.data.packageName.trim() : void 0,
+			install: { kind }
+		};
+	});
+}
+async function fetchMarketplaceSkillFiles(apiBase, slug) {
+	return runWithMarketplaceNetworkRetry(async () => {
+		const response = await fetch(`${apiBase}/api/v1/skills/items/${encodeURIComponent(slug)}/files`, { headers: { Accept: "application/json" } });
+		const payload = await readMarketplaceEnvelope(response);
+		if (!payload.ok || !payload.data) {
+			const message = payload.error?.message || `marketplace skill file fetch failed: ${response.status}`;
+			throw new Error(message);
+		}
+		if (!isRecord(payload.data) || !Array.isArray(payload.data.files)) throw new Error("Invalid marketplace skill file manifest response");
+		return { files: payload.data.files.map((entry, index) => {
+			if (!isRecord(entry) || typeof entry.path !== "string" || entry.path.trim().length === 0) throw new Error(`Invalid marketplace skill file manifest at index ${index}`);
+			const normalized = { path: entry.path.trim() };
+			if (typeof entry.downloadPath === "string" && entry.downloadPath.trim().length > 0) normalized.downloadPath = entry.downloadPath.trim();
+			if (typeof entry.contentBase64 === "string" && entry.contentBase64.trim().length > 0) normalized.contentBase64 = entry.contentBase64.trim();
+			return normalized;
+		}) };
+	});
+}
+async function fetchMarketplaceSkillFileBlob(apiBase, slug, file) {
+	const downloadUrl = resolveSkillFileDownloadUrl(apiBase, slug, file);
+	return runWithMarketplaceNetworkRetry(async () => {
+		const response = await fetch(downloadUrl, { headers: { Accept: "application/octet-stream" } });
+		if (!response.ok) {
+			const message = extractMarketplaceErrorMessage(await response.text(), response.status) || `marketplace skill file download failed: ${response.status}`;
+			throw new Error(message);
+		}
+		return Buffer.from(await response.arrayBuffer());
+	});
+}
+async function readMarketplaceEnvelope(response) {
+	const raw = await response.text();
+	let payload;
+	try {
+		payload = raw.length > 0 ? JSON.parse(raw) : null;
+	} catch {
+		throw new Error(`Invalid marketplace response: ${response.status}`);
+	}
+	if (!isRecord(payload) || typeof payload.ok !== "boolean") throw new Error(`Invalid marketplace response shape: ${response.status}`);
+	return payload;
+}
+function resolveSkillFileDownloadUrl(apiBase, slug, file) {
+	if (file.downloadPath) return file.downloadPath.startsWith("http://") || file.downloadPath.startsWith("https://") ? file.downloadPath : `${apiBase}${file.downloadPath}`;
+	return `${apiBase}/api/v1/skills/items/${encodeURIComponent(slug)}/files/blob?path=${encodeURIComponent(file.path)}`;
+}
+function extractMarketplaceErrorMessage(raw, fallbackStatus) {
+	if (!raw) return;
+	try {
+		return JSON.parse(raw).error?.message;
+	} catch {
+		return raw || `Request failed (${fallbackStatus})`;
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+export { fetchMarketplaceSkillFileBlob, fetchMarketplaceSkillFiles, fetchMarketplaceSkillItem, readMarketplaceEnvelope, resolveMarketplaceAdminToken, resolveMarketplaceApiBase };

package/dist/cli/commands/skills/marketplace-command-options.utils.d.ts

@@ -0,0 +1,25 @@
+import { MarketplaceSkillPublishOptions } from "./marketplace.service.js";
+
+//#region src/cli/commands/skills/marketplace-command-options.utils.d.ts
+type MarketplacePublishCommandOptions = {
+  dir: string;
+  meta?: string;
+  slug?: string;
+  packageName?: string;
+  scope?: string;
+  name?: string;
+  summary?: string;
+  description?: string;
+  author?: string;
+  tag?: string[];
+  sourceRepo?: string;
+  homepage?: string;
+  publishedAt?: string;
+  updatedAt?: string;
+  apiBaseUrl?: string;
+  token?: string;
+};
+declare function buildMarketplacePublishOptions(options: MarketplacePublishCommandOptions): MarketplaceSkillPublishOptions;
+declare function buildMarketplaceUpdateOptions(options: Omit<MarketplacePublishCommandOptions, "publishedAt">): MarketplaceSkillPublishOptions;
+//#endregion
+export { MarketplacePublishCommandOptions, buildMarketplacePublishOptions, buildMarketplaceUpdateOptions };

package/dist/cli/commands/skills/marketplace-command-options.utils.js

@@ -0,0 +1,31 @@
+import { expandHome } from "@nextclaw/core";
+//#region src/cli/commands/skills/marketplace-command-options.utils.ts
+function buildMarketplacePublishOptions(options) {
+	const { apiBaseUrl, author, description, dir, homepage, meta, name, packageName, publishedAt, scope, slug, sourceRepo, summary, tag, token, updatedAt } = options;
+	return {
+		skillDir: expandHome(dir),
+		metaFile: meta ? expandHome(meta) : void 0,
+		slug,
+		packageName,
+		scope,
+		name,
+		summary,
+		description,
+		author,
+		tags: tag,
+		sourceRepo,
+		homepage,
+		publishedAt,
+		updatedAt,
+		apiBaseUrl,
+		token
+	};
+}
+function buildMarketplaceUpdateOptions(options) {
+	return {
+		...buildMarketplacePublishOptions(options),
+		requireExisting: true
+	};
+}
+//#endregion
+export { buildMarketplacePublishOptions, buildMarketplaceUpdateOptions };

package/dist/cli/commands/skills/marketplace-identity.utils.d.ts

@@ -0,0 +1,14 @@
+import { PlatformMeResult } from "../../../commands/platform-auth/services/platform-auth-commands.service.js";
+//#region src/cli/commands/skills/marketplace-identity.utils.d.ts
+declare function resolvePublishPackageName(params: {
+  explicitPackageName?: string;
+  explicitScope?: string;
+  slug: string;
+  adminTokenPresent: boolean;
+  currentUser: PlatformMeResult | null;
+}): string;
+declare function validateSkillSlug(raw: string, fieldName: string): string;
+declare function validateSkillSelector(raw: string, fieldName: string): string;
+declare function normalizeTags(rawTags: string[] | undefined): string[];
+//#endregion
+export { normalizeTags, resolvePublishPackageName, validateSkillSelector, validateSkillSlug };