hngr 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# hngr
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Hangar CLI. Install skills and MCP servers into coding agents, and drive the Hangar
+Management API — from a terminal, a container, or CI.
+
+Requires Node.js >= 22.
+
+```sh
+npm install -g hngr
+hngr --version
+```
+
+## Authenticate
+
+```sh
+# Interactive: username and password, then an access token is written to
+# ~/.config/hngr/config.json (0600).
+hngr auth login --server https://hangar.example.com
+
+# CI or containers: read an existing access token from stdin.
+printf '%s' "$HANGAR_TOKEN_VALUE" | hngr auth login --token --server https://hangar.example.com
+
+# Or skip the config file entirely.
+export HANGAR_URL=https://hangar.example.com
+export HANGAR_TOKEN=hng_...
+hngr auth status
+```
+
+## Install capabilities
+
+A bare name means the `system` namespace; anything else uses `<namespace>/<name>`.
+
+```sh
+# system namespace
+hngr skills add pdf-tools --agent claude-code
+hngr mcp add pdf-tools --agent claude-code
+
+# another namespace
+hngr skills add team-a/pdf-tools --agent claude-code
+
+# pin a version
+hngr skills add pdf-tools@2026.10.25.1 --agent claude-code
+```
+
+Non-interactive runs must pass `--agent` (repeatable) or `--all`. Use `--global` for
+user-level directories, `--copy` to skip the canonical `.agents/skills` directory, and
+`--dry-run` to preview without writing.
+
+## Publish capabilities
+
+```sh
+# A directory containing SKILL.md; creates the capability, or publishes a new version
+hngr skills publish ./my-skill --description "What it does" --visibility internal
+
+# An MCP config snapshot with an mcpServers object
+hngr mcp publish ./mcp.json --name my-mcp --description "What it does"
+
+# Fail instead of creating a new version; preview without sending anything
+hngr skills publish ./my-skill --description "..." --new
+hngr mcp publish ./mcp.json --dry-run
+```
+
+`--namespace` defaults to `system`; `--visibility` defaults to `private` and accepts
+`public`, `internal` or `private`.
+
+## Browse and discover
+
+```sh
+hngr capabilities list
+hngr commands --json        # machine-readable catalogue
+hngr schema capabilities list
+hngr completion bash        # or zsh / fish
+```
+
+## Output contract
+
+stdout carries the payload only (JSON, 2-space indent). Progress, summaries, warnings and
+errors go to stderr. Errors are single-line JSON when stdout is not a TTY or `--json` is
+passed. Exit codes: `0` success, `1` failure or usage error, `4` authentication required,
+`130` cancelled.

package/bin/hngr.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { checkNodeVersion } from "./node-gate.js";
+
+const check = checkNodeVersion(process.versions.node);
+if (!check.ok) {
+  process.stderr.write(`${check.error}\n`);
+  process.exit(1);
+}
+
+// The bundle is only parsed after the version gate passes.
+const { main } = await import("../dist/index.mjs");
+process.exitCode = await main(process.argv.slice(2));

package/bin/node-gate.d.ts

@@ -0,0 +1,5 @@
+export declare const MIN_NODE_MAJOR: number;
+
+export type NodeVersionCheck = { ok: true } | { ok: false; error: string };
+
+export declare function checkNodeVersion(version: string): NodeVersionCheck;

package/bin/node-gate.js

@@ -0,0 +1,18 @@
+export const MIN_NODE_MAJOR = 22;
+
+/**
+ * Gate that runs before any bundled code is imported. Returns { ok: false,
+ * error } with an actionable message when the runtime is too old.
+ *
+ * @param {string} version process.versions.node, e.g. "22.1.0"
+ */
+export function checkNodeVersion(version) {
+  const major = Number.parseInt(String(version).split(".")[0] ?? "0", 10);
+  if (Number.isNaN(major) || major < MIN_NODE_MAJOR) {
+    return {
+      ok: false,
+      error: `hngr requires Node.js >= ${MIN_NODE_MAJOR} (current: v${version}). Install a newer Node.js from https://nodejs.org and retry.`,
+    };
+  }
+  return { ok: true };
+}

package/dist/auth-Bf4n5qaq.mjs

@@ -0,0 +1,334 @@
+import { _ as writeStoredConfig, d as deleteStoredConfig, f as normalizeServerUrl, h as resolveConnection, m as redactUrl, n as apiGet, p as readStoredConfig, t as apiFetch, u as configFilePath, x as HngrError } from "./http-DpXNrkSL.mjs";
+import { hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+// src/commands/auth.ts
+const AUTH_REMEDIATION = "Run `hngr auth login` or set HANGAR_TOKEN.";
+/** The first 8 characters after the `hng_` prefix, for recognising a token. Not a credential. */
+function tokenPrefixOf(token) {
+	return (token.startsWith("hng_") ? token.slice(4) : token).slice(0, 8);
+}
+/** Exit-4 error for commands that need credentials the caller does not have. */
+function notLoggedInError() {
+	return new HngrError({
+		type: "auth",
+		title: "Not logged in",
+		detail: AUTH_REMEDIATION
+	}, 4);
+}
+/** The active token and where it came from; `HANGAR_TOKEN` wins over the config file. */
+async function activeToken(ctx) {
+	if (ctx.env.HANGAR_TOKEN) return {
+		token: ctx.env.HANGAR_TOKEN,
+		source: "env"
+	};
+	const config = await readStoredConfig(ctx.env);
+	return config?.token ? {
+		token: config.token,
+		source: "config"
+	} : void 0;
+}
+async function token(ctx) {
+	const active = await activeToken(ctx);
+	if (!active) throw notLoggedInError();
+	ctx.io.stdout.write(`${active.token}\n`);
+	return 0;
+}
+/** Prompts only happen with both stdin and stdout on a TTY and a prompter available. */
+function canPrompt(ctx) {
+	return ctx.io.stdin.isTTY && ctx.io.stdout.isTTY && ctx.io.prompts !== void 0;
+}
+/**
+* Enforces https everywhere; http only for localhost, 127.0.0.1 and [::1],
+* or with an explicit --insecure.
+*/
+function assertServerUrlAllowed(raw, insecure) {
+	const server = normalizeServerUrl(raw);
+	const url = new URL(server);
+	if (url.protocol === "https:") return server;
+	if (url.protocol === "http:") {
+		if ([
+			"localhost",
+			"127.0.0.1",
+			"[::1]"
+		].includes(url.hostname) || insecure) return server;
+		throw new HngrError({
+			type: "config",
+			title: `Refusing insecure server URL ${redactUrl(server)}`,
+			detail: "Use https://, or pass --insecure to allow http:// for non-local hosts."
+		});
+	}
+	throw new HngrError({
+		type: "config",
+		title: `Unsupported server URL scheme in ${redactUrl(server)}`,
+		detail: "Use an https:// server URL."
+	});
+}
+/** Maps the GET /me payload onto the stored principal shape; a bad shape is an api error. */
+function asStoredPrincipal(body) {
+	const principal = body;
+	if (principal === null || typeof principal !== "object" || typeof principal.id !== "string" || typeof principal.username !== "string" || typeof principal.kind !== "string") throw new HngrError({
+		type: "api",
+		title: "The server returned an unexpected GET /me payload",
+		detail: "Expected {id, username, kind} strings."
+	});
+	return {
+		id: principal.id,
+		username: principal.username,
+		type: principal.kind
+	};
+}
+/** The login summary; never carries the token, password or cookie. */
+function summarizeLogin(ctx, username, tokenName, tokenPrefix, configPath) {
+	ctx.progress(`logged in as ${username}`);
+	ctx.progress(tokenName ? `token ${tokenName} (prefix ${tokenPrefix})` : `token prefix ${tokenPrefix}`);
+	ctx.progress(`config ${configPath}`);
+	ctx.progress("source: config");
+}
+/** Best-effort revoke of the previous stored token on a --force re-login. */
+async function revokePreviousToken(ctx, stored) {
+	if (!stored.token || !stored.token_id || !stored.server) return;
+	if (!await revokeToken(normalizeServerUrl(stored.server), stored.token, stored.token_id)) ctx.summary(SERVER_TOKEN_LINGERING_WARNING);
+}
+async function login(ctx, argv) {
+	if (ctx.env.HANGAR_TOKEN) throw envTokenRefusal();
+	const stored = await readStoredConfig(ctx.env);
+	let rawServer = ctx.flags.server ?? ctx.env.HANGAR_URL ?? stored?.server;
+	if (!rawServer && canPrompt(ctx)) rawServer = await ctx.io.prompts?.text("Server URL");
+	if (!rawServer) throw new HngrError({
+		type: "config",
+		title: "No Hangar server configured",
+		detail: "Pass --server <url>, set HANGAR_URL, or run `hngr auth login` interactively to store one."
+	});
+	const server = assertServerUrlAllowed(rawServer, ctx.flags.insecure);
+	if (stored?.token && !ctx.flags.force) try {
+		const me = asStoredPrincipal(await apiGet({
+			server,
+			token: stored.token
+		}, "/api/v1/me"));
+		ctx.progress(`already logged in as ${me.username}; pass --force to re-authenticate`);
+		return 0;
+	} catch (err) {
+		if (err instanceof HngrError && err.body.type === "api") throw err;
+	}
+	if (argv.token === true) {
+		const pasted = (await ctx.io.stdin.readAll()).trim();
+		if (!pasted) throw new HngrError({
+			type: "usage",
+			title: "No token on stdin",
+			detail: "Pipe an access token into `hngr auth login --token`."
+		});
+		const principal = asStoredPrincipal(await apiGet({
+			server,
+			token: pasted
+		}, "/api/v1/me"));
+		if (ctx.flags.force && stored) await revokePreviousToken(ctx, stored);
+		const prefix = tokenPrefixOf(pasted);
+		const matched = await lookupTokenMetadata(server, pasted, prefix);
+		const path = await writeStoredConfig(ctx.env, {
+			server,
+			token: pasted,
+			...matched ? {
+				token_id: matched.id,
+				token_name: matched.name
+			} : {},
+			token_prefix: prefix,
+			principal,
+			created_at: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		summarizeLogin(ctx, principal.username, matched?.name, prefix, path);
+		return 0;
+	}
+	if (!canPrompt(ctx)) throw new HngrError({
+		type: "auth",
+		title: "Logging in needs a terminal",
+		detail: "Set HANGAR_TOKEN, or pass --token and pipe an access token on stdin, in non-interactive use."
+	}, 4);
+	const prompter = ctx.io.prompts;
+	if (!prompter) throw new HngrError({
+		type: "io",
+		title: "No interactive prompter available"
+	});
+	const username = await prompter.text("Username");
+	const password = await prompter.password("Password");
+	const cookie = sessionCookieOf(await apiFetch({ server }, {
+		method: "POST",
+		path: "/api/v1/login",
+		body: {
+			username,
+			password
+		}
+	}));
+	if (ctx.flags.force && stored) await revokePreviousToken(ctx, stored);
+	const minted = await mintAccessToken(server, cookie, cliTokenName());
+	const principal = asStoredPrincipal(await apiGet({
+		server,
+		token: minted.token
+	}, "/api/v1/me"));
+	let path;
+	try {
+		path = await writeStoredConfig(ctx.env, {
+			server,
+			token: minted.token,
+			token_id: minted.id,
+			token_name: minted.name,
+			token_prefix: minted.token_prefix,
+			principal,
+			created_at: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	} catch (err) {
+		if (!await revokeToken(server, minted.token, minted.id)) ctx.summary(SERVER_TOKEN_LINGERING_WARNING);
+		throw err;
+	}
+	summarizeLogin(ctx, principal.username, minted.name, minted.token_prefix, path);
+	return 0;
+}
+/** Reads the session cookie off the login response; missing cookie is an api error. */
+function sessionCookieOf(response) {
+	const pair = (response.headers.getSetCookie()[0] ?? response.headers.get("set-cookie"))?.split(";")[0]?.trim();
+	if (!pair) throw new HngrError({
+		type: "api",
+		title: "The login response carried no session cookie",
+		detail: "Expected Set-Cookie from POST /api/v1/login."
+	});
+	return pair;
+}
+/** `hngr-cli@<hostname>`, capped at the server's 64-character name limit. */
+function cliTokenName() {
+	return `hngr-cli@${hostname()}`.slice(0, 64);
+}
+/**
+* Finds the stored token's id so logout can revoke it. A token list that is
+* unavailable, malformed, or ambiguous leaves the id unknown; login itself
+* still succeeds and logout warns that it could not revoke.
+*/
+async function lookupTokenMetadata(server, token, prefix) {
+	let body;
+	try {
+		body = await apiGet({
+			server,
+			token
+		}, "/api/v1/me/tokens");
+	} catch (err) {
+		if (err instanceof HngrError || err instanceof SyntaxError) return;
+		throw err;
+	}
+	const items = body?.items;
+	if (!Array.isArray(items)) return;
+	const matches = items.filter((item) => item !== null && typeof item === "object" && typeof item.id === "string" && item.token_prefix === prefix);
+	if (matches.length !== 1) return;
+	const [match] = matches;
+	if (!match) return;
+	return typeof match.name === "string" ? {
+		id: match.id,
+		name: match.name
+	} : { id: match.id };
+}
+/**
+* Mints an access token with the session cookie and a random Idempotency-Key.
+* A replay response carries no token value: delete the replayed id and mint
+* again under a fresh key.
+*/
+async function mintAccessToken(server, cookie, name) {
+	for (let attempt = 0; attempt < 2; attempt++) {
+		const response = await apiFetch({ server }, {
+			method: "POST",
+			path: "/api/v1/me/tokens",
+			headers: {
+				Cookie: cookie,
+				"Idempotency-Key": randomUUID()
+			},
+			body: { name }
+		});
+		const body = await response.json();
+		if (response.status === 201) {
+			if (typeof body.id !== "string" || typeof body.name !== "string" || typeof body.token_prefix !== "string" || typeof body.token !== "string") throw new HngrError({
+				type: "api",
+				title: "The server returned an unexpected token payload",
+				detail: "Expected {id, name, token_prefix, token} from POST /api/v1/me/tokens."
+			});
+			return {
+				id: body.id,
+				name: body.name,
+				token_prefix: body.token_prefix,
+				token: body.token
+			};
+		}
+		if (typeof body.id !== "string") throw new HngrError({
+			type: "api",
+			title: "The server returned an unexpected token replay payload",
+			detail: "Expected {id} from POST /api/v1/me/tokens."
+		});
+		await apiFetch({ server }, {
+			method: "DELETE",
+			path: `/api/v1/me/tokens/${encodeURIComponent(body.id)}`,
+			headers: { Cookie: cookie }
+		});
+	}
+	throw new HngrError({
+		type: "api",
+		title: "Minting an access token kept replaying",
+		detail: "POST /api/v1/me/tokens answered 200 twice under different idempotency keys."
+	});
+}
+const ENV_TOKEN_REFUSAL = "HANGAR_TOKEN is set, so stored credentials are read-only. Unset HANGAR_TOKEN to change them.";
+/** Refuses to modify stored credentials while an environment token is active. */
+function envTokenRefusal() {
+	return new HngrError({
+		type: "auth",
+		title: ENV_TOKEN_REFUSAL
+	});
+}
+/** Revokes one access token; 401/404 mean it is already gone. Returns false when unsure. */
+async function revokeToken(server, bearer, tokenId) {
+	try {
+		await apiFetch({ server }, {
+			method: "DELETE",
+			path: `/api/v1/me/tokens/${encodeURIComponent(tokenId)}`,
+			headers: { Authorization: `Bearer ${bearer}` }
+		});
+		return true;
+	} catch (err) {
+		if (err instanceof HngrError && (err.body.status === 401 || err.body.status === 404)) return true;
+		return false;
+	}
+}
+const SERVER_TOKEN_LINGERING_WARNING = "warning: could not revoke the token on the server; the server token may still be valid";
+async function logout(ctx) {
+	if (ctx.env.HANGAR_TOKEN) throw envTokenRefusal();
+	const config = await readStoredConfig(ctx.env);
+	if (!config?.token) throw notLoggedInError();
+	if (config.token_id && config.server) {
+		if (!await revokeToken(normalizeServerUrl(config.server), config.token, config.token_id)) ctx.summary(SERVER_TOKEN_LINGERING_WARNING);
+	} else ctx.summary("warning: no token id is stored, so the server token was not revoked; revoke it from the web console if needed");
+	await deleteStoredConfig(ctx.env);
+	ctx.progress("logged out");
+	return 0;
+}
+async function status(ctx, argv) {
+	const active = await activeToken(ctx);
+	if (!active) throw notLoggedInError();
+	const connection = await resolveConnection(ctx.flags, ctx.env);
+	const config = await readStoredConfig(ctx.env);
+	const source = active.source === "env" ? "env:HANGAR_TOKEN" : configFilePath(ctx.env);
+	const tokenPrefix = active.source === "config" && config?.token_prefix ? config.token_prefix : tokenPrefixOf(active.token);
+	let principal = config?.principal ?? null;
+	if (argv.offline !== true) try {
+		principal = await apiGet(connection, "/api/v1/me", void 0, { signal: AbortSignal.timeout(5e3) });
+	} catch (err) {
+		if (err instanceof HngrError && err.body.type === "network") ctx.summary("warning: the live GET /me check failed; showing the stored principal");
+		else throw err;
+	}
+	ctx.writePayload({
+		source,
+		server: connection.server,
+		principal,
+		token_prefix: tokenPrefix
+	});
+	return 0;
+}
+async function whoami(ctx) {
+	const connection = await resolveConnection(ctx.flags, ctx.env);
+	ctx.writePayload(await apiGet(connection, "/api/v1/me"));
+	return 0;
+}
+export { login, logout, status, token, whoami };