@mnmal-ai/substrate-tui 0.0.0-stage → 1.0.0-alpha.0

package/dist/bin/substrate-tui.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { t as colorDepthEnv } from "../terminal-XfKFiD7r.js";
+import { basename } from "node:path";
+import { DEFAULT_CAPABILITIES, makeTokenProvider } from "@mnmal-ai/substrate/client";
+
+//#region src/config.ts
+const message = (err) => err instanceof Error ? err.message : String(err);
+function readConfig(env, cwd) {
+	const endpoint = (env.SUBSTRATE_URL ?? "").replace(/\/+$/, "");
+	if (endpoint === "") return { error: "SUBSTRATE_URL is required (e.g. https://substrate.example.com:3100)" };
+	const namespace = env.SUBSTRATE_NAMESPACE ?? "";
+	if (namespace === "") return { error: "SUBSTRATE_NAMESPACE is required (the namespace to watch)" };
+	const keyPath = env.SUBSTRATE_AGENT_KEY_PATH;
+	const kid = env.SUBSTRATE_AGENT_KEY_ID;
+	let token = null;
+	if (keyPath !== void 0 && keyPath !== "" && kid !== void 0 && kid !== "") {
+		const raw = env.SUBSTRATE_AGENT_CAPABILITIES?.split(",").map((c) => c.trim()).filter((c) => c !== "");
+		try {
+			token = makeTokenProvider({
+				keyPath,
+				kid
+			}, { capabilities: raw !== void 0 && raw.length > 0 ? raw : DEFAULT_CAPABILITIES });
+		} catch (err) {
+			return { error: `agent identity: ${message(err)}` };
+		}
+	}
+	return {
+		endpoint,
+		namespace,
+		project: basename(cwd),
+		token
+	};
+}
+
+//#endregion
+//#region src/bin/tui.tsx
+const USAGE = "usage: substrate-tui   (env: SUBSTRATE_URL, optional SUBSTRATE_NAMESPACE, SUBSTRATE_AGENT_KEY_ID + SUBSTRATE_AGENT_KEY_PATH;\n                    SUBSTRATE_TUI_BACKGROUND=#rrggbb|none, SUBSTRATE_TUI_CLEAR=0 to keep the screen,\n                    SUBSTRATE_TUI_COLOR=256 for terminals without truecolor;\n                    admin: SUBSTRATE_ADMIN_TOKEN, or SUBSTRATE_ADMIN_KEY_PATH [+ SUBSTRATE_ADMIN_KEY_ID], SUBSTRATE_TUI_ADMIN_IDLE_MINUTES)\n";
+async function main() {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		process.stderr.write(`substrate-tui needs an interactive terminal.\n${USAGE}`);
+		return 2;
+	}
+	const config = readConfig(process.env, process.cwd());
+	if ("error" in config) {
+		process.stderr.write(`substrate-tui: ${config.error}\n`);
+		return 2;
+	}
+	Object.assign(process.env, colorDepthEnv(process.env));
+	const [{ createTui }, { makeDeps }, { prepareTerminal }, { terminalOptions }] = await Promise.all([
+		import("../app-BLOyJcBh.js"),
+		import("../deps-WzqsHHiC.js"),
+		import("@mnmal-ai/surface-core/pure"),
+		import("../terminal-CVX2CKWu.js")
+	]);
+	let deps;
+	try {
+		deps = makeDeps(config);
+	} catch (err) {
+		process.stderr.write(`substrate-tui: ${err instanceof Error ? err.message : String(err)}\n`);
+		return 2;
+	}
+	const restore = prepareTerminal(process.stdout, terminalOptions(process.env));
+	try {
+		await createTui(deps).run();
+	} finally {
+		restore();
+	}
+	return 0;
+}
+process.exitCode = await main();
+
+//#endregion
+export {  };

package/dist/deps-WzqsHHiC.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import { n as adminIdleMs, r as createAdminSession } from "./session-C1D5Ermr.js";
+import { SubstrateClient, noRedirectFetch, tokenAudience } from "@mnmal-ai/substrate/client";
+
+//#region src/deps.ts
+/** An HTTP failure from `getJson`: `status` is what `NetworkError` and `AuthError` also carry. */
+var HttpStatusError = class extends Error {
+	status;
+	constructor(status, path) {
+		super(`${status} from ${path}`);
+		this.name = "HttpStatusError";
+		this.status = status;
+	}
+};
+const sig = (signal) => signal !== void 0 ? { signal } : {};
+function makeDeps(config, fetchImpl = fetch, env = process.env) {
+	const token = config.token;
+	if (token !== null || [
+		"SUBSTRATE_ADMIN_TOKEN",
+		"SUBSTRATE_ADMIN_KEY_PATH",
+		"SUBSTRATE_ADMIN_KEY_ID"
+	].some((k) => (env[k] ?? "") !== "")) tokenAudience(config.endpoint);
+	fetchImpl = noRedirectFetch(fetchImpl);
+	const adminFetch = (input, init) => {
+		tokenAudience(config.endpoint);
+		return fetchImpl(input, init);
+	};
+	const client = new SubstrateClient({
+		endpoint: config.endpoint,
+		...config.token !== null ? { getToken: config.token } : {},
+		fetch: fetchImpl,
+		onDiagnostics: () => {}
+	});
+	const admin = createAdminSession({
+		endpoint: config.endpoint,
+		idleMs: adminIdleMs(env),
+		fetch: adminFetch
+	});
+	return {
+		endpoint: config.endpoint,
+		project: config.project,
+		namespace: config.namespace,
+		nl: client.nl,
+		federatedSchema: () => client.federatedSchema(),
+		metrics: (signal) => client.metrics(sig(signal)),
+		errors: (signal) => admin.unlocked() ? admin.run(({ client: c }) => c.errors(sig(signal)), { touch: false }) : client.errors(sig(signal)),
+		admin,
+		adminEnv: {
+			...env.SUBSTRATE_ADMIN_TOKEN !== void 0 ? { SUBSTRATE_ADMIN_TOKEN: env.SUBSTRATE_ADMIN_TOKEN } : {},
+			...env.SUBSTRATE_ADMIN_KEY_PATH !== void 0 ? { SUBSTRATE_ADMIN_KEY_PATH: env.SUBSTRATE_ADMIN_KEY_PATH } : {},
+			...env.SUBSTRATE_ADMIN_KEY_ID !== void 0 ? { SUBSTRATE_ADMIN_KEY_ID: env.SUBSTRATE_ADMIN_KEY_ID } : {},
+			...env.SUBSTRATE_ADMIN_CAPABILITY !== void 0 ? { SUBSTRATE_ADMIN_CAPABILITY: env.SUBSTRATE_ADMIN_CAPABILITY } : {},
+			...env.HOME !== void 0 ? { HOME: env.HOME } : {}
+		},
+		agentAuthorization: token !== null ? () => `Bearer ${token()}` : null,
+		keys: (signal) => client.admin.keys(sig(signal)),
+		async getJson(path, signal) {
+			const headers = { accept: "application/json" };
+			if (config.token !== null) headers.authorization = `Bearer ${config.token()}`;
+			const res = await fetchImpl(`${config.endpoint}${path}`, {
+				headers,
+				...sig(signal)
+			});
+			if (!res.ok) throw new HttpStatusError(res.status, path);
+			return res.json();
+		}
+	};
+}
+
+//#endregion
+export { HttpStatusError, makeDeps };

package/dist/session-C1D5Ermr.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { AdminBackfillError, AuthError, SubstrateClient } from "@mnmal-ai/substrate/client";
+
+//#region src/admin/session.ts
+/**
+* The admin identity while unlocked. Holds ONLY the token provider and the kid; every
+* admin operation builds its own SubstrateClient and closes it after, so no admin connection, cache
+* or socket outlives one. Lock, idle expiry and a rejected key all drop the provider; an
+* operation already running finishes on the client it holds.
+*/
+var AdminLockedError = class extends Error {
+	name = "AdminLockedError";
+	constructor() {
+		super("admin is locked — /admin unlock");
+	}
+};
+const ADMIN_IDLE_DEFAULT_MIN = 15;
+/** setTimeout's ceiling: a longer delay overflows and fires at once, which would lock on unlock. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+function adminIdleMs(env) {
+	const n = Number(env.SUBSTRATE_TUI_ADMIN_IDLE_MINUTES);
+	return Math.min(MAX_TIMER_MS, (Number.isInteger(n) && n > 0 ? n : 15) * 6e4);
+}
+/** `SUBSTRATE_ADMIN_CAPABILITY` as the CLI reads it: unset or empty means diagnose's default. */
+function adminCapabilityOf(env) {
+	const c = env.SUBSTRATE_ADMIN_CAPABILITY;
+	return c !== void 0 && c.length > 0 ? { adminCapability: c } : {};
+}
+/**
+* The admin key itself was refused: a 401, or the auth gate's 403 (no code, or `forbidden`). A
+* route's own coded 403 (`directory_denied`, `destructive_ops_disabled`) refuses the request, not
+* the key. A chunked backfill wraps every failure, so the cause is what is judged.
+*/
+function isKeyRejection(err) {
+	const e = err instanceof AdminBackfillError ? err.cause : err;
+	return e instanceof AuthError && (e.status === 401 || e.code === void 0 || e.code === "forbidden");
+}
+function createAdminSession(opts) {
+	const now = opts.now ?? Date.now;
+	const make = opts.makeClient ?? ((getToken) => new SubstrateClient({
+		endpoint: opts.endpoint,
+		getToken,
+		...opts.fetch !== void 0 ? { fetch: opts.fetch } : {},
+		onDiagnostics: () => {}
+	}));
+	let held = null;
+	let state = {
+		kind: "locked",
+		reason: null
+	};
+	let timer;
+	let disposed = false;
+	const listeners = /* @__PURE__ */ new Set();
+	const set = (s) => {
+		state = s;
+		for (const fn of listeners) fn(s);
+	};
+	const lock = (reason) => {
+		if (timer !== void 0) clearTimeout(timer);
+		timer = void 0;
+		held = null;
+		set({
+			kind: "locked",
+			reason
+		});
+	};
+	const touch = () => {
+		if (held === null) return;
+		if (timer !== void 0) clearTimeout(timer);
+		timer = setTimeout(() => lock(`idle — no admin action for ${Math.round(opts.idleMs / 6e4)}m`), opts.idleMs);
+		timer.unref?.();
+		set({
+			kind: "unlocked",
+			kid: held.kid,
+			idleUntil: now() + opts.idleMs
+		});
+	};
+	return {
+		state: () => state,
+		unlocked: () => held !== null,
+		unlock(kid, getToken) {
+			if (disposed) return;
+			held = {
+				kid,
+				getToken
+			};
+			touch();
+		},
+		lock,
+		async run(op, runOpts) {
+			if (held === null) throw new AdminLockedError();
+			const { getToken } = held;
+			if (runOpts?.touch !== false) touch();
+			const client = make(getToken);
+			try {
+				return await op({
+					client,
+					authorization: () => `Bearer ${getToken()}`
+				});
+			} catch (err) {
+				if (isKeyRejection(err) && held !== null) {
+					const e = err instanceof AdminBackfillError ? err.cause : err;
+					lock(`admin locked: ${e.status} — the admin key was rejected`);
+				}
+				throw err;
+			} finally {
+				await client.close();
+			}
+		},
+		onChange(fn) {
+			listeners.add(fn);
+			return () => listeners.delete(fn);
+		},
+		dispose() {
+			disposed = true;
+			lock("session ended");
+			listeners.clear();
+		}
+	};
+}
+
+//#endregion
+export { isKeyRejection as i, adminIdleMs as n, createAdminSession as r, adminCapabilityOf as t };

package/dist/terminal-CVX2CKWu.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { n as terminalOptions, t as colorDepthEnv } from "./terminal-XfKFiD7r.js";
+
+export { colorDepthEnv, terminalOptions };

package/dist/terminal-XfKFiD7r.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+//#region src/terminal.ts
+/**
+* How substrate-tui prepares the terminal: a black ground and a fresh, bottom-anchored pane.
+* `SUBSTRATE_TUI_BACKGROUND` takes `#rrggbb` or `none`; `SUBSTRATE_TUI_CLEAR=0` keeps what was on screen.
+*/
+function terminalOptions(env) {
+	return {
+		...env.SUBSTRATE_TUI_BACKGROUND !== void 0 ? { ground: env.SUBSTRATE_TUI_BACKGROUND } : {},
+		clear: (env.SUBSTRATE_TUI_CLEAR ?? "").trim() !== "0"
+	};
+}
+/**
+* The environment chalk must see for the theme's hex colours to reach the terminal as hex
+*. chalk picks its depth once, at import, and reports 256 colours for any TERM
+* ending `-256color`, rounding every hex to the nearest palette entry; COLORTERM=truecolor is the
+* one check it makes first. So: truecolor by default, a COLORTERM the terminal already set is left
+* alone, and `SUBSTRATE_TUI_COLOR=256` opts out for a terminal that cannot render 24-bit colour.
+* Must be applied before Ink (and so chalk) is imported.
+*/
+function colorDepthEnv(env) {
+	if ((env.SUBSTRATE_TUI_COLOR ?? "").trim() === "256") return {};
+	if (env.COLORTERM !== void 0 && env.COLORTERM !== "") return {};
+	return { COLORTERM: "truecolor" };
+}
+
+//#endregion
+export { terminalOptions as n, colorDepthEnv as t };

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@mnmal-ai/substrate-tui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-alpha.0",
+  "description": "Terminal UI for Substrate: ask in natural language, browse the schema, see the service status.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mnmal-ai/substrate.git",
+    "directory": "apps/substrate-tui"
+  },
+  "type": "module",
+  "bin": {
+    "substrate-tui": "dist/bin/tui.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "@mnmal-ai/substrate": "1.0.0-alpha.0",
+    "@mnmal-ai/substrate-nl": "1.0.0-alpha.0",
+    "@mnmal-ai/surface-core": "0.14.5",
+    "@mnmal-ai/surface-kit": "0.14.5",
+    "@mnmal-ai/surface-theme": "0.14.5",
+    "ink": "^7.1.1",
+    "react": "^19.3.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "@mnmal-ai/substrate-config": "1.0.0-alpha.0",
+    "@types/node": "^26.6.4",
+    "@types/react": "^19.2.0",
+    "ink-testing-library": "^4.0.0",
+    "tsdown": "^0.23.0",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "engines": {
+    "node": ">=26.2.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsx src/bin/tui.tsx",
+    "test": "vitest run",
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome check ."
+  }
 }