hngr 0.1.0 → 0.2.0

package/dist/publish-D7zaQl9x.mjs

@@ -0,0 +1,512 @@
+import { S as HngrError, _ as scrubCredentials, a as toHngrError, g as resolveConnection, h as redactUrl, i as buildRequestUrl, l as apiErrorFromResponse, n as apiGet } from "./http-2HWxLIOq.mjs";
+import { t as collectPages } from "./pagination-BbKLKSw3.mjs";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+// ../client/src/capability-path.ts
+/** The Namespace every bare capability reference means. */
+const SYSTEM_NAMESPACE = "system";
+/**
+* Splits a capability reference into its Namespace and name. A bare name is in
+* the system Namespace; every other reference is `<namespace>/<name>`.
+* Returns null for any other segment count so callers can report their own
+* usage error.
+*/
+function splitCapabilityPath(path) {
+	const segments = path.split("/");
+	if (segments.length === 1) return {
+		namespace: SYSTEM_NAMESPACE,
+		name: path
+	};
+	if (segments.length === 2) return {
+		namespace: segments[0] ?? "",
+		name: segments[1] ?? ""
+	};
+	return null;
+}
+// src/capability-resolve.ts
+const CAPABILITIES_PATH = "/api/v1/capabilities";
+const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const CALVER_PATTERN = /^[0-9]{4}\.[0-9]{2}\.[0-9]{2}\.(0|[1-9][0-9]*)$/;
+const SKILL_KIND = {
+	kind: "skill",
+	noun: "skill",
+	filtersKind: false
+};
+const MCP_KIND = {
+	kind: "mcp",
+	noun: "MCP capability",
+	filtersKind: true
+};
+function usage$1(title, detail) {
+	return new HngrError({
+		type: "usage",
+		title,
+		detail
+	});
+}
+/** Validates a namespace/name pair without parsing a full capability path. */
+function validateCapabilityName(namespace, name, kind) {
+	const raw = `${namespace}/${name}`;
+	checkNamePart(namespace, raw, kind.noun);
+	checkNamePart(name, raw, kind.noun);
+}
+function checkNamePart(part, raw, noun) {
+	if (!NAME_PATTERN.test(part) || part.length > 64) throw usage$1(`Invalid ${noun} path ${JSON.stringify(raw)}`, "Names are 1-64 lowercase letters, digits and hyphens, for example `pdf` or `team-a/pdf`.");
+}
+/** Parses `<name>` or `<namespace>/<name>`, with an optional `@YYYY.MM.DD.N`. */
+function parseCapabilityPath(raw, kind) {
+	if (raw.trim() === "") throw usage$1(`A ${kind.noun} path is required`, "Pass `<name>` or `<namespace>/<name>`.");
+	let path = raw;
+	let version;
+	const at = raw.lastIndexOf("@");
+	if (at !== -1) {
+		path = raw.slice(0, at);
+		version = raw.slice(at + 1);
+		if (!CALVER_PATTERN.test(version)) throw usage$1(`Invalid version in ${JSON.stringify(raw)}`, "A version is `@YYYY.MM.DD.N`, for example `pdf@2026.10.25.0`.");
+	}
+	const split = splitCapabilityPath(path);
+	if (split === null) throw usage$1(`Invalid ${kind.noun} path ${JSON.stringify(raw)}`, "Use `<name>` for the system namespace or `<namespace>/<name>`.");
+	checkNamePart(split.name, raw, kind.noun);
+	checkNamePart(split.namespace, raw, kind.noun);
+	return {
+		namespace: split.namespace,
+		name: split.name,
+		version
+	};
+}
+function candidateLabel(capability) {
+	return `${capability.id} (${capability.namespace}/${capability.name}, ${capability.kind})`;
+}
+/**
+* Resolves one parsed path to exactly one Capability of the expected kind. The
+* list `q` is a case-insensitive substring filter, so kind/namespace/name are
+* matched here; zero or several matches are errors that name the candidates.
+*/
+async function findCapability(connection, parsed, kind, signal) {
+	const matches = (await collectPages(CAPABILITIES_PATH, (cursor) => apiGet(connection, CAPABILITIES_PATH, {
+		...kind.filtersKind ? { kind: kind.kind } : {},
+		namespace: parsed.namespace,
+		q: parsed.name,
+		cursor
+	}, { signal }))).filter((item) => item !== null && typeof item === "object" && item.kind === kind.kind && item.namespace === parsed.namespace && item.name === parsed.name);
+	const label = `${parsed.namespace}/${parsed.name}`;
+	if (matches.length > 1) throw new HngrError({
+		type: "api",
+		title: `${label} matches ${matches.length} capabilities`,
+		detail: `Candidates: ${matches.map(candidateLabel).join("; ")}.`
+	});
+	return matches[0] ?? null;
+}
+/** Resolves a path to exactly one Capability, or reports that it does not exist. */
+async function resolveCapability(connection, parsed, kind, signal) {
+	const capability = await findCapability(connection, parsed, kind, signal);
+	if (capability === null) {
+		const label = `${parsed.namespace}/${parsed.name}`;
+		throw new HngrError({
+			type: "api",
+			title: `No ${kind.noun} named ${label}`,
+			detail: "Check the name and namespace, or list the catalog with `hngr capabilities list`."
+		});
+	}
+	return capability;
+}
+/** The pinned version, or the capability's Current Version. */
+function resolveCapabilityVersion(capability, parsed, kind) {
+	if (parsed.version) return parsed.version;
+	if (!capability.current_version) throw new HngrError({
+		type: "api",
+		title: `The ${kind.noun} ${capability.namespace}/${capability.name} has no Current Version`
+	});
+	return capability.current_version;
+}
+// src/capability-download.ts
+/**
+* Downloads one Capability Version's content with the requested media type.
+* Bearer credentials are only sent when configured; a 401 maps to exit code 4
+* through the shared contract.
+*/
+async function downloadContent(connection, capabilityId, version, accept, signal) {
+	const path = `/api/v1/capabilities/${encodeURIComponent(capabilityId)}/versions/${encodeURIComponent(version)}/content`;
+	const { url } = buildRequestUrl(connection, path);
+	const headers = { Accept: accept };
+	if (connection.token) headers.Authorization = `Bearer ${connection.token}`;
+	let response;
+	try {
+		response = await fetch(url, {
+			method: "GET",
+			headers,
+			signal
+		});
+	} catch (err) {
+		const origin = redactUrl(connection.server);
+		const cause = err instanceof Error ? err.message : String(err);
+		throw new HngrError({
+			type: "network",
+			title: `Could not reach the Hangar server at ${origin}`,
+			detail: scrubCredentials(cause, connection.server)
+		});
+	}
+	if (!response.ok) {
+		const apiError = await apiErrorFromResponse(response, response.headers.get("X-Request-ID") ?? void 0);
+		throw toHngrError(apiError);
+	}
+	return {
+		bytes: Buffer.from(await response.arrayBuffer()),
+		etag: response.headers.get("ETag") ?? void 0
+	};
+}
+// src/agents.ts
+/** The user's home directory, honouring the environment used by the CLI. */
+function homeDir(env) {
+	return env.HOME ?? homedir();
+}
+function underHome(...segments) {
+	return (env) => join(homeDir(env), ...segments);
+}
+/** Claude Code's config directory: `CLAUDE_CONFIG_DIR` or `~/.claude`. */
+function claudeConfigDir(env) {
+	return env.CLAUDE_CONFIG_DIR && env.CLAUDE_CONFIG_DIR !== "" ? env.CLAUDE_CONFIG_DIR : join(homeDir(env), ".claude");
+}
+/** `XDG_CONFIG_HOME` or `~/.config`; Devin's user-level MCP config lives below it. */
+function xdgConfigDir(env) {
+	return env.XDG_CONFIG_HOME && env.XDG_CONFIG_HOME !== "" ? env.XDG_CONFIG_HOME : join(homeDir(env), ".config");
+}
+const universalSkills = {
+	projectDir: null,
+	globalDir: null,
+	link: false
+};
+/**
+* Every agent this version knows, with its skills and MCP locations in one
+* place so adding an agent is a single edit. Universal agents read the
+* canonical `.agents/skills` store directly and have no per-agent directory.
+*/
+const AGENTS = [
+	{
+		id: "claude-code",
+		skills: {
+			projectDir: ".claude/skills",
+			globalDir: (env) => join(claudeConfigDir(env), "skills"),
+			link: true
+		},
+		mcp: {
+			kind: "claude-cli",
+			configPath: (env) => join(homeDir(env), ".claude.json")
+		}
+	},
+	{
+		id: "codex",
+		skills: universalSkills,
+		mcp: {
+			kind: "unsupported",
+			reason: "Codex stores MCP servers as TOML in .codex/config.toml."
+		}
+	},
+	{
+		id: "gemini-cli",
+		skills: universalSkills,
+		mcp: {
+			kind: "json",
+			project: ".gemini/settings.json",
+			global: underHome(".gemini", "settings.json")
+		}
+	},
+	{
+		id: "opencode",
+		skills: universalSkills,
+		mcp: {
+			kind: "unsupported",
+			reason: "OpenCode uses a top-level `mcp` object with local/remote entries."
+		}
+	},
+	{
+		id: "amp",
+		skills: universalSkills,
+		mcp: {
+			kind: "unsupported",
+			reason: "Amp uses a top-level `amp.mcpServers` object."
+		}
+	},
+	{
+		id: "cursor",
+		skills: universalSkills,
+		mcp: {
+			kind: "json",
+			project: ".cursor/mcp.json",
+			global: underHome(".cursor", "mcp.json")
+		}
+	},
+	{
+		id: "copilot",
+		skills: universalSkills,
+		mcp: {
+			kind: "unsupported",
+			reason: "VS Code and Copilot use a top-level `servers` object."
+		}
+	},
+	{
+		id: "cline",
+		skills: {
+			projectDir: ".cline/skills",
+			globalDir: underHome(".cline", "skills"),
+			link: true
+		},
+		mcp: { kind: "none" }
+	},
+	{
+		id: "zed",
+		skills: universalSkills,
+		mcp: {
+			kind: "unsupported",
+			reason: "Zed uses a top-level `context_servers` object."
+		}
+	},
+	{
+		id: "junie",
+		skills: {
+			projectDir: ".junie/skills",
+			globalDir: underHome(".junie", "skills"),
+			link: true
+		},
+		mcp: {
+			kind: "json",
+			project: ".junie/mcp/mcp.json",
+			global: underHome(".junie", "mcp", "mcp.json")
+		}
+	},
+	{
+		id: "qwen-code",
+		skills: universalSkills,
+		mcp: {
+			kind: "json",
+			project: ".qwen/settings.json",
+			global: underHome(".qwen", "settings.json")
+		}
+	},
+	{
+		id: "kiro-cli",
+		skills: {
+			projectDir: ".kiro/skills",
+			globalDir: underHome(".kiro", "skills"),
+			link: true
+		},
+		mcp: {
+			kind: "json",
+			project: ".kiro/settings/mcp.json",
+			global: underHome(".kiro", "settings", "mcp.json")
+		}
+	},
+	{
+		id: "devin",
+		skills: universalSkills,
+		mcp: {
+			kind: "json",
+			project: null,
+			global: (env) => join(xdgConfigDir(env), "devin", "mcp_config.json")
+		}
+	}
+];
+function findAgentDefinition(id) {
+	return AGENTS.find((agent) => agent.id === id);
+}
+// src/commands/batch.ts
+/** A repeatable string flag can arrive as one value or an array of values. */
+function stringValues(value) {
+	if (typeof value === "string" && value !== "") return [value];
+	if (Array.isArray(value)) return value.flatMap((item) => stringValues(item));
+	return [];
+}
+/** Positional paths arrive as a string for one and an array for several. */
+function positionalPaths(value) {
+	if (typeof value === "string") return [value];
+	if (Array.isArray(value)) return value.map((item) => String(item));
+	return [];
+}
+function errorBody(err) {
+	if (err instanceof HngrError) return err.body;
+	return {
+		type: "io",
+		title: err instanceof Error ? err.message : String(err)
+	};
+}
+/** The common fields of a per-path failure; callers spread in their extras. */
+function failedResult(parsed, err, version) {
+	return {
+		name: parsed.name,
+		namespace: parsed.namespace,
+		version,
+		status: "failed",
+		targets: [],
+		error: errorBody(err)
+	};
+}
+/**
+* Runs one command body per path. A per-path failure is reported as a result
+* and does not stop the remaining paths; an error with its own exit code
+* (authentication, cancellation) is command-level and escapes immediately.
+*/
+async function runBatch(options) {
+	const { ctx, paths, run, failure, onResult } = options;
+	const results = [];
+	for (const parsed of paths) {
+		const state = { version: parsed.version ?? null };
+		try {
+			const result = await run(parsed, state);
+			results.push(result);
+			onResult?.(result);
+		} catch (err) {
+			if (err instanceof HngrError && err.exitCode !== 1) throw err;
+			const result = failure(parsed, err, state.version);
+			results.push(result);
+			ctx.summary(`error: ${parsed.namespace}/${parsed.name}: ${result.error?.title ?? "install failed"}`);
+		}
+	}
+	return {
+		results,
+		failed: results.some((result) => result.status === "failed")
+	};
+}
+// src/commands/publish.ts
+const VISIBILITIES = [
+	"public",
+	"internal",
+	"private"
+];
+function usage(title, detail) {
+	return new HngrError({
+		type: "usage",
+		title,
+		detail
+	});
+}
+function stringFlag(argv, name) {
+	const value = argv[name];
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+async function readOptionalFile(path) {
+	if (path === void 0) return;
+	try {
+		return await readFile(resolve(path), "utf8");
+	} catch (err) {
+		throw new HngrError({
+			type: "io",
+			title: `Could not read ${path}`,
+			detail: err instanceof Error ? err.message : String(err)
+		});
+	}
+}
+/** Reads the shared publish flags; a bad value fails before any request. */
+async function readPublishFlags(argv, kind) {
+	const visibility = stringFlag(argv, "visibility") ?? "private";
+	if (!VISIBILITIES.includes(visibility)) throw usage(`Invalid --visibility ${JSON.stringify(visibility)}`, `Use one of: ${VISIBILITIES.join(", ")}.`);
+	const tags = stringValues(argv.tag);
+	if (tags.length > 8) throw usage("Too many --tag values", "At most eight tags are allowed.");
+	for (const tag of tags) {
+		if (tag.trim() === "") throw usage("Empty --tag value", "Pass a non-empty tag.");
+		if (kind === "skill" && tag.includes(",")) throw usage(`Invalid --tag ${JSON.stringify(tag)}`, "A Skill tag cannot contain a comma; the multipart form joins tags with commas.");
+	}
+	return {
+		namespace: stringFlag(argv, "namespace") ?? "system",
+		description: stringFlag(argv, "description"),
+		visibility,
+		readme: await readOptionalFile(stringFlag(argv, "readme")),
+		tags,
+		forceNew: argv.new === true
+	};
+}
+/** The `--name` flag applies to one target; several targets each use their own name. */
+function explicitName(argv, targetCount) {
+	const name = stringFlag(argv, "name");
+	if (name !== void 0 && targetCount > 1) throw usage("--name cannot be combined with several targets", "Publish each target separately or drop --name to derive it from the path.");
+	return name;
+}
+function asRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function printPreview(ctx, kind, namespace, name, preview) {
+	ctx.detail(`dry-run: would publish ${kind} ${namespace}/${name}`);
+	for (const [key, value] of Object.entries(preview)) {
+		const shown = typeof value === "string" ? value : JSON.stringify(value);
+		ctx.detail(`  ${key}: ${shown}`);
+	}
+}
+/**
+* Runs one publish per target. Local validation and the capability lookup
+* happen per target, so one bad directory does not stop the others; a target
+* failure is reported in the results and the command exits 1.
+*/
+async function runPublish(options) {
+	const { ctx } = options;
+	const connection = await resolveConnection(ctx.flags, ctx.env);
+	const results = [];
+	for (const item of options.items) {
+		const base = {
+			name: item.name,
+			namespace: options.namespace,
+			kind: options.kind,
+			version: null,
+			status: "failed",
+			capabilityId: null,
+			mode: null,
+			error: null
+		};
+		try {
+			validateCapabilityName(options.namespace, item.name, options.info);
+			const metadata = {
+				namespace: options.namespace,
+				name: item.name,
+				description: options.description,
+				visibility: options.visibility,
+				readme: options.readme,
+				tags: options.tags
+			};
+			const prepared = await item.prepare(metadata);
+			if (ctx.flags.dryRun) {
+				printPreview(ctx, options.kind, options.namespace, item.name, prepared.preview());
+				results.push({
+					...base,
+					status: "dry-run"
+				});
+				continue;
+			}
+			const existing = await findCapability(connection, {
+				namespace: options.namespace,
+				name: item.name
+			}, options.info);
+			if (existing !== null && options.forceNew) throw usage(`The ${options.info.noun} ${options.namespace}/${item.name} already exists`, "Drop --new to publish a new version of it.");
+			let response;
+			let mode;
+			if (existing !== null) {
+				response = await prepared.version(connection, existing.id);
+				mode = "version";
+			} else {
+				if (options.description === void 0) throw usage("Missing --description", "Creating a capability requires --description <text>.");
+				response = await prepared.create(connection);
+				mode = "created";
+			}
+			const body = asRecord(response);
+			const result = {
+				...base,
+				version: typeof body?.current_version === "string" ? body.current_version : null,
+				status: "published",
+				capabilityId: typeof body?.id === "string" ? body.id : null,
+				mode
+			};
+			results.push(result);
+			ctx.progress(`published ${options.namespace}/${item.name}${result.version ? `@${result.version}` : ""} (${mode})`);
+		} catch (err) {
+			if (err instanceof HngrError && err.exitCode !== 1) throw err;
+			const error = errorBody(err);
+			results.push({
+				...base,
+				status: "failed",
+				error
+			});
+			ctx.summary(`error: ${options.namespace}/${item.name}: ${error.title}`);
+		}
+	}
+	ctx.writePayload({ results });
+	return results.some((result) => result.status === "failed") ? 1 : 0;
+}
+export { resolveCapabilityVersion as _, failedResult as a, stringValues as c, homeDir as d, downloadContent as f, resolveCapability as g, parseCapabilityPath as h, errorBody as i, AGENTS as l, SKILL_KIND as m, readPublishFlags as n, positionalPaths as o, MCP_KIND as p, runPublish as r, runBatch as s, explicitName as t, findAgentDefinition as u };