hngr 0.2.0 → 0.4.0

package/README.md

@@ -47,9 +47,12 @@ hngr skills add team-a/pdf-tools --agent claude-code
 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.
+Non-interactive runs must pass `--agent` (repeatable) or `--all`. In an interactive
+terminal, omitting `--global` first asks whether to install for the current project or
+the user; without a terminal it defaults to the project. Use `--global` to skip the
+question, `--copy` to skip the canonical `.agents/skills` directory, and `--dry-run` to
+preview without writing. Re-running an install replaces the existing target; `--force`
+is not needed.
 
 ## Publish capabilities
 

package/dist/{auth-BT8HuCif.mjs → auth-ByGgd_Yn.mjs}

@@ -1,6 +1,7 @@
-import { S as HngrError, d as configFilePath, f as deleteStoredConfig, g as resolveConnection, h as redactUrl, m as readStoredConfig, n as apiGet, p as normalizeServerUrl, t as apiFetch, v as writeStoredConfig } from "./http-2HWxLIOq.mjs";
+import { C as HngrError, d as configFilePath, f as deleteStoredConfig, g as resolveConnection, h as redactUrl, m as readStoredConfig, n as apiGet, p as normalizeServerUrl, t as apiFetch, v as storedAudience, y as writeStoredConfig } from "./http-DgHX7Fux.mjs";
 import { hostname } from "node:os";
 import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
 // 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. */
@@ -27,12 +28,33 @@ async function activeToken(ctx) {
 		source: "config"
 	} : void 0;
 }
-async function token(ctx) {
+async function token(ctx, argv) {
+	if (argv.audience === "mcp") return mintMCPToken(ctx);
 	const active = await activeToken(ctx);
 	if (!active) throw notLoggedInError();
 	ctx.io.stdout.write(`${active.token}\n`);
 	return 0;
 }
+/**
+* Mints a static MCP token with the active credential and prints it once.
+* The stored config is never rewritten, so the same machine keeps its
+* management login while handing out MCP tokens.
+*
+* The caller's kind is deliberately not checked here: the server owns the
+* owner rule (a Principal can manage its own tokens), so the request must go
+* out and its Problem, if any, reaches the user through the usual mapping.
+*/
+async function mintMCPToken(ctx) {
+	const connection = await resolveConnection(ctx.flags, ctx.env);
+	if (!connection.token) throw notLoggedInError();
+	const minted = await mintAccessToken(connection.server, {
+		name: cliMCPTokenName(),
+		audience: "mcp",
+		headers: { Authorization: `Bearer ${connection.token}` }
+	});
+	ctx.io.stdout.write(`${minted.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;
@@ -103,37 +125,43 @@ async function login(ctx, argv) {
 	} 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 (argv.token === true) return loginWithToken(ctx, server, stored);
+	if (argv.password === true) return loginWithPassword(ctx, server, stored);
+	return loginDevice(ctx, server, stored);
+}
+async function loginWithToken(ctx, server, stored) {
+	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,
+		audience: "management",
+		principal,
+		created_at: (/* @__PURE__ */ new Date()).toISOString()
+	});
+	summarizeLogin(ctx, principal.username, matched?.name, prefix, path);
+	return 0;
+}
+async function loginWithPassword(ctx, server, stored) {
 	if (!canPrompt(ctx)) throw new HngrError({
 		type: "auth",
-		title: "Logging in needs a terminal",
+		title: "Logging in with a password 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;
@@ -152,7 +180,11 @@ async function login(ctx, argv) {
 		}
 	}));
 	if (ctx.flags.force && stored) await revokePreviousToken(ctx, stored);
-	const minted = await mintAccessToken(server, cookie, cliTokenName());
+	const minted = await mintAccessToken(server, {
+		name: cliTokenName(),
+		audience: "management",
+		headers: { Cookie: cookie }
+	});
 	const principal = asStoredPrincipal(await apiGet({
 		server,
 		token: minted.token
@@ -165,6 +197,7 @@ async function login(ctx, argv) {
 			token_id: minted.id,
 			token_name: minted.name,
 			token_prefix: minted.token_prefix,
+			audience: "management",
 			principal,
 			created_at: (/* @__PURE__ */ new Date()).toISOString()
 		});
@@ -175,6 +208,144 @@ async function login(ctx, argv) {
 	summarizeLogin(ctx, principal.username, minted.name, minted.token_prefix, path);
 	return 0;
 }
+const DEVICE_CODE_PATH = "/api/v1/auth/device/code";
+const DEVICE_TOKEN_PATH = "/api/v1/auth/device/token";
+/** Suggested when the device flow cannot finish; the password flow still works. */
+const PASSWORD_REMEDIATION = "Run `hngr auth login --password` to sign in with a username and password instead.";
+/** Validates the create response; a bad shape is an api error, not a crash. */
+function asDeviceCode(body) {
+	const value = body;
+	if (value === null || typeof value !== "object" || typeof value.device_code !== "string" || typeof value.user_code !== "string" || typeof value.verification_uri !== "string" || typeof value.verification_uri_complete !== "string" || typeof value.expires_in !== "number" || typeof value.interval !== "number" || value.interval <= 0) throw new HngrError({
+		type: "api",
+		title: "The server returned an unexpected device authorization payload",
+		detail: "Expected {device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval} from POST /api/v1/auth/device/code."
+	});
+	return value;
+}
+/** Validates the poll success response; the token is stored only when complete. */
+function asDeviceToken(body) {
+	const value = body;
+	if (value === null || typeof value !== "object" || typeof value.token !== "string" || typeof value.token_id !== "string" || typeof value.token_prefix !== "string" || typeof value.name !== "string") throw new HngrError({
+		type: "api",
+		title: "The server returned an unexpected device token payload",
+		detail: "Expected {token, token_id, token_prefix, name, principal} from POST /api/v1/auth/device/token."
+	});
+	return value;
+}
+function deviceDeniedError() {
+	return new HngrError({
+		type: "auth",
+		title: "The login request was denied",
+		detail: PASSWORD_REMEDIATION
+	});
+}
+function deviceExpiredError() {
+	return new HngrError({
+		type: "auth",
+		title: "The login request expired",
+		detail: PASSWORD_REMEDIATION
+	});
+}
+function defaultSleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Starts the platform opener without waiting for it; failures are silent. */
+function openInBrowser(url) {
+	const [command, args] = process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+	try {
+		const child = spawn(command, args, {
+			detached: true,
+			stdio: "ignore"
+		});
+		child.on("error", () => {});
+		child.unref();
+	} catch {}
+}
+/** The device name shown to the approver. */
+function deviceName() {
+	return hostname().slice(0, 128);
+}
+/**
+* Polls until the request leaves the pending state. `slow_down` extends the
+* interval permanently by five seconds; network failures are retried until the
+* advertised lifetime runs out. Sleeps and the clock are injectable for tests.
+*/
+async function pollDeviceToken(ctx, server, deviceCode, expiresIn, interval) {
+	const now = ctx.io.now ?? Date.now;
+	const sleep = ctx.io.sleep ?? defaultSleep;
+	const deadline = now() + expiresIn * 1e3;
+	let waitSeconds = interval;
+	for (;;) {
+		if (now() >= deadline) throw deviceExpiredError();
+		try {
+			return asDeviceToken(await (await apiFetch({ server }, {
+				method: "POST",
+				path: DEVICE_TOKEN_PATH,
+				body: { device_code: deviceCode }
+			})).json());
+		} catch (err) {
+			if (!(err instanceof HngrError)) throw err;
+			const problem = String(err.body.type);
+			if (problem.endsWith("/authorization-pending")) {
+				await sleep(waitSeconds * 1e3);
+				continue;
+			}
+			if (problem.endsWith("/slow-down")) {
+				waitSeconds += 5;
+				await sleep(waitSeconds * 1e3);
+				continue;
+			}
+			if (problem.endsWith("/access-denied")) throw deviceDeniedError();
+			if (problem.endsWith("/expired-token")) throw deviceExpiredError();
+			if (err.body.type === "network") {
+				await sleep(waitSeconds * 1e3);
+				continue;
+			}
+			throw err;
+		}
+	}
+}
+/** The browser-based login: request a code, wait for approval, store the token. */
+async function loginDevice(ctx, server, stored) {
+	const device = asDeviceCode(await (await apiFetch({ server }, {
+		method: "POST",
+		path: DEVICE_CODE_PATH,
+		body: {
+			device_name: deviceName(),
+			token_name: cliTokenName()
+		}
+	})).json());
+	ctx.detail("To approve this login from a browser:");
+	ctx.io.stderr.write(`open ${device.verification_uri}\n`);
+	ctx.io.stderr.write(`enter the user code: ${device.user_code}\n`);
+	if (ctx.io.stderr.isTTY) try {
+		await (ctx.io.openBrowser ?? openInBrowser)(device.verification_uri_complete);
+	} catch {}
+	const minted = await pollDeviceToken(ctx, server, device.device_code, device.expires_in, device.interval);
+	if (ctx.flags.force && stored) await revokePreviousToken(ctx, stored);
+	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.token_id,
+			token_name: minted.name,
+			token_prefix: minted.token_prefix,
+			audience: "management",
+			principal,
+			created_at: (/* @__PURE__ */ new Date()).toISOString()
+		});
+	} catch (err) {
+		if (!await revokeToken(server, minted.token, minted.token_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();
@@ -189,6 +360,10 @@ function sessionCookieOf(response) {
 function cliTokenName() {
 	return `hngr-cli@${hostname()}`.slice(0, 64);
 }
+/** `hngr-mcp@<hostname>`, so MCP tokens are recognisable in the token list. */
+function cliMCPTokenName() {
+	return `hngr-mcp@${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
@@ -217,20 +392,24 @@ async function lookupTokenMetadata(server, token, prefix) {
 	} : { 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.
+* Mints an access token with the caller's credentials and a random
+* Idempotency-Key. The caller passes either a session cookie (login) or a
+* Bearer token (minting for an audience). A replay response carries no token
+* value: delete the replayed id and mint again under a fresh key.
 */
-async function mintAccessToken(server, cookie, name) {
+async function mintAccessToken(server, options) {
 	for (let attempt = 0; attempt < 2; attempt++) {
 		const response = await apiFetch({ server }, {
 			method: "POST",
 			path: "/api/v1/me/tokens",
 			headers: {
-				Cookie: cookie,
+				...options.headers,
 				"Idempotency-Key": randomUUID()
 			},
-			body: { name }
+			body: {
+				name: options.name,
+				audience: options.audience
+			}
 		});
 		const body = await response.json();
 		if (response.status === 201) {
@@ -254,7 +433,7 @@ async function mintAccessToken(server, cookie, name) {
 		await apiFetch({ server }, {
 			method: "DELETE",
 			path: `/api/v1/me/tokens/${encodeURIComponent(body.id)}`,
-			headers: { Cookie: cookie }
+			headers: options.headers
 		});
 	}
 	throw new HngrError({
@@ -304,6 +483,7 @@ async function status(ctx, argv) {
 	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);
+	const audience = active.source === "config" ? storedAudience(config) : "management";
 	let principal = config?.principal ?? null;
 	if (argv.offline !== true) try {
 		principal = await apiGet(connection, "/api/v1/me", void 0, { signal: AbortSignal.timeout(5e3) });
@@ -315,7 +495,8 @@ async function status(ctx, argv) {
 		source,
 		server: connection.server,
 		principal,
-		token_prefix: tokenPrefix
+		token_prefix: tokenPrefix,
+		audience
 	});
 	return 0;
 }