@aigne/aos 0.2.0-beta

package/dist/terminal-repl.mjs

@@ -0,0 +1,370 @@
+//#region src/terminal-repl.ts
+const ARC_ART = ["▄▀█ █▀█ █▀▀", "█▀█ █▀▄ █▄▄"];
+const TAGLINE = "Agentic Realm Computer";
+const COPYRIGHT = "Copyright (c) 2026 ArcBlock Inc. All rights reserved.";
+const R = "\x1B[0m";
+const ART_GRADIENT = [[
+	100,
+	220,
+	255
+], [
+	180,
+	120,
+	255
+]];
+const TAGLINE_GRADIENT = [
+	[
+		100,
+		255,
+		255
+	],
+	[
+		80,
+		220,
+		255
+	],
+	[
+		60,
+		180,
+		255
+	],
+	[
+		100,
+		140,
+		255
+	],
+	[
+		180,
+		120,
+		255
+	],
+	[
+		220,
+		100,
+		255
+	]
+];
+function interpColor(t, stops) {
+	const scaled = t * (stops.length - 1);
+	const i = Math.min(Math.floor(scaled), stops.length - 2);
+	const frac = scaled - i;
+	const a = stops[i] ?? [
+		0,
+		0,
+		0
+	];
+	const b = stops[i + 1] ?? [
+		0,
+		0,
+		0
+	];
+	return [
+		Math.round(a[0] + (b[0] - a[0]) * frac),
+		Math.round(a[1] + (b[1] - a[1]) * frac),
+		Math.round(a[2] + (b[2] - a[2]) * frac)
+	];
+}
+function rainbowText(text) {
+	const chars = [...text];
+	return chars.map((ch, i) => {
+		if (ch === " ") return ch;
+		const [r, g, b] = interpColor(chars.length > 1 ? i / (chars.length - 1) : 0, TAGLINE_GRADIENT);
+		return `\x1b[38;2;${r};${g};${b}m${ch}${R}`;
+	}).join("");
+}
+/**
+* Render the ARC terminal banner.
+*
+* Uses 24-bit truecolor gradient (matches Node splash.ts exactly).
+*
+* Output (colored):
+*   ▄▀█ █▀█ █▀▀  Agentic Realm Computer
+*   █▀█ █▀▄ █▄▄  v1.0.0 (abc1234) · 2026-04-23
+*   Copyright (c) 2026 ArcBlock Inc. All rights reserved.
+*
+*   Session: <id> · N providers · Type help for commands.
+*/
+function renderArcBanner(opts) {
+	const color = opts.color !== false;
+	const { version, commit, date, providerCount, sessionId } = opts;
+	const tc = (rgb, s) => color ? `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${s}${R}` : s;
+	const cyan = (s) => color ? `\x1b[96m${s}${R}` : s;
+	const dim = (s) => color ? `\x1b[2m${s}${R}` : s;
+	const art = ARC_ART.map((line, i) => color ? tc(ART_GRADIENT[i], line) : line);
+	const tagline = color ? rainbowText(TAGLINE) : TAGLINE;
+	const versionStr = [
+		cyan(`v${version}`),
+		dim(`(${commit})`),
+		dim("·"),
+		dim(date)
+	].join(" ");
+	const copyrightStr = dim(COPYRIGHT);
+	const gap = "  ";
+	const lines = [
+		`  ${art[0]}${gap}${tagline}`,
+		`  ${art[1]}${gap}${versionStr}`,
+		`  ${copyrightStr}`
+	];
+	if (providerCount !== void 0 || sessionId) {
+		const parts = [];
+		if (sessionId) parts.push(`Session: ${dim(sessionId)}`);
+		if (providerCount !== void 0) {
+			const plural = providerCount === 1 ? "provider" : "providers";
+			parts.push(`${providerCount} ${plural}`);
+		}
+		parts.push(`Type ${cyan("help")} for commands.`);
+		lines.push("", `  ${parts.join(dim(" · "))}`);
+	}
+	return lines.join("\r\n");
+}
+/** Generate a random hex session ID. */
+function genSessionId() {
+	const arr = new Uint8Array(8);
+	if (typeof crypto !== "undefined" && crypto.getRandomValues) crypto.getRandomValues(arr);
+	else for (let i = 0; i < arr.length; i++) arr[i] = Math.floor(Math.random() * 256);
+	return Array.from(arr, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function resolvePath(cwd, raw) {
+	if (!raw || raw === ".") return cwd;
+	const parts = (raw.startsWith("/") ? raw : `${cwd === "/" ? "" : cwd}/${raw}`).split("/").filter(Boolean);
+	const resolved = [];
+	for (const p of parts) if (p === "..") resolved.pop();
+	else if (p !== ".") resolved.push(p);
+	return `/${resolved.join("/")}`;
+}
+function parseArgs(input) {
+	const args = [];
+	let current = "";
+	let quote = null;
+	for (const ch of input) if (quote) if (ch === quote) quote = null;
+	else current += ch;
+	else if (ch === "\"" || ch === "'") quote = ch;
+	else if (ch === " " || ch === "	") {
+		if (current) {
+			args.push(current);
+			current = "";
+		}
+	} else current += ch;
+	if (current) args.push(current);
+	return args;
+}
+function makeAnsi(color) {
+	const r = color ? "\x1B[0m" : "";
+	const red = color ? "\x1B[31m" : "";
+	const blue = color ? "\x1B[34m" : "";
+	const yellow = color ? "\x1B[33m" : "";
+	const bold = color ? "\x1B[1m" : "";
+	return {
+		r,
+		red,
+		blue,
+		yellow,
+		bold,
+		err: (msg) => `${red}Error:${r} ${msg}`,
+		help: () => [
+			`${bold}Available commands:${r}`,
+			"",
+			`  ${bold}AFS Commands:${r}`,
+			`    ${yellow}ls${r} [path]               List directory contents (default: current dir)`,
+			`    ${yellow}read${r} <path>             Read file content`,
+			`    ${yellow}write${r} <path> <content>  Write content to file`,
+			`    ${yellow}stat${r} [path]             Get file or directory info`,
+			`    ${yellow}exec${r} <path> [args]      Execute an action`,
+			`    ${yellow}explain${r} [path]          Explain path capabilities`,
+			`    ${yellow}search${r} <path> <query>   Search content`,
+			"",
+			`  ${bold}REPL Commands:${r}`,
+			`    ${yellow}cd${r} [path]               Change working directory`,
+			`    ${yellow}pwd${r}                     Print working directory`,
+			`    ${yellow}help${r}                    Show this help`,
+			`    ${yellow}clear${r}                   Clear screen`,
+			`    ${yellow}exit${r} / ${yellow}quit${r}             Exit session`
+		].join("\r\n")
+	};
+}
+async function cmdLs(afs, path, ansi) {
+	try {
+		const items = (await afs.list(path, { maxDepth: 1 })).data ?? [];
+		if (!items.length) return "(empty)";
+		return items.map((e) => {
+			const isDir = e.meta?.kind === "directory" || (e.meta?.childrenCount ?? 0) > 0;
+			const name = e.path.split("/").at(-1) ?? e.path;
+			return isDir ? `${ansi.blue}${name}/${ansi.r}` : name;
+		}).join("\r\n");
+	} catch (e) {
+		return ansi.err(e instanceof Error ? e.message : String(e));
+	}
+}
+async function cmdRead(afs, path, ansi) {
+	try {
+		const content = (await afs.read(path)).data?.content;
+		if (content === void 0 || content === null) return ansi.err("Not found or not readable");
+		if (typeof content === "string") return content;
+		if (content instanceof Uint8Array) return new TextDecoder().decode(content);
+		return JSON.stringify(content, null, 2);
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		if (/not found|ENOENT/i.test(msg)) return ansi.err(`Not found: ${path}`);
+		return ansi.err(msg);
+	}
+}
+async function cmdWrite(afs, path, content, ansi) {
+	try {
+		await afs.write(path, { content });
+		return `Written: ${path}`;
+	} catch (e) {
+		return ansi.err(e instanceof Error ? e.message : String(e));
+	}
+}
+async function cmdStat(afs, path, ansi) {
+	try {
+		const meta = (await afs.stat(path))?.data?.meta ?? {};
+		const lines = [`${ansi.bold}Path:${ansi.r} ${path}`];
+		for (const [k, v] of Object.entries(meta)) if (v !== void 0 && v !== null) lines.push(`${ansi.yellow}${k}:${ansi.r} ${JSON.stringify(v)}`);
+		return lines.join("\r\n");
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		if (/not found|ENOENT/i.test(msg)) return ansi.err(`Not found: ${path}`);
+		return ansi.err(msg);
+	}
+}
+async function cmdExec(afs, path, args, ansi) {
+	try {
+		const data = (await afs.exec(path, args))?.data;
+		if (data === void 0 || data === null) return "(no output)";
+		if (typeof data === "string") return data;
+		return JSON.stringify(data, null, 2);
+	} catch (e) {
+		return ansi.err(e instanceof Error ? e.message : String(e));
+	}
+}
+async function cmdExplain(afs, path, ansi) {
+	try {
+		const result = await afs.explain(path);
+		if (!result) return "(no explanation)";
+		return result.content ?? "(no explanation)";
+	} catch (e) {
+		return ansi.err(e instanceof Error ? e.message : String(e));
+	}
+}
+async function cmdSearch(afs, path, query, ansi) {
+	try {
+		const items = (await afs.search(path, query))?.data ?? [];
+		if (!Array.isArray(items) || !items.length) return "(no results)";
+		return items.map((e) => {
+			const entry = e;
+			return typeof entry.path === "string" ? entry.path : JSON.stringify(e);
+		}).join("\r\n");
+	} catch (e) {
+		return ansi.err(e instanceof Error ? e.message : String(e));
+	}
+}
+async function cmdCd(afs, cwd, target) {
+	const newCwd = resolvePath(cwd, target);
+	if (newCwd === "/") return { newCwd };
+	try {
+		const meta = (await afs.stat(newCwd))?.data?.meta ?? {};
+		if (!(meta.kind === "directory" || meta.childrenCount !== void 0 || newCwd.split("/").filter(Boolean).length === 1)) return {
+			newCwd: cwd,
+			error: `Not a directory: ${newCwd}`
+		};
+		return { newCwd };
+	} catch {
+		try {
+			await afs.list(newCwd, { maxDepth: 1 });
+			return { newCwd };
+		} catch {
+			return {
+				newCwd: cwd,
+				error: `Not found: ${newCwd}`
+			};
+		}
+	}
+}
+/**
+* Create a platform-agnostic AFS REPL session.
+*
+* Used by both the CF Worker terminal and the Node daemon terminal.
+* Transport (WebSocket send/receive) is handled by the caller.
+*/
+function createAfsReplSession(afs, opts) {
+	const sessionId = genSessionId();
+	const ansi = makeAnsi(opts.color !== false);
+	let cwd = "/";
+	let cachedProviderCount = null;
+	return {
+		sessionId,
+		getPrompt() {
+			return `afs ${cwd === "/" ? "/" : cwd.split("/").at(-1)}> `;
+		},
+		async countProviders() {
+			if (cachedProviderCount !== null) return cachedProviderCount;
+			try {
+				const result = await afs.list("/");
+				const seen = /* @__PURE__ */ new Set();
+				for (const e of result.data ?? []) if (typeof e?.path === "string") seen.add(e.path);
+				cachedProviderCount = seen.size || 0;
+			} catch {
+				cachedProviderCount = 0;
+			}
+			return cachedProviderCount;
+		},
+		async route(line) {
+			const trimmed = line.trim();
+			if (!trimmed) return {};
+			const args = parseArgs(trimmed.startsWith("afs ") ? trimmed.slice(4).trim() : trimmed);
+			const cmd = args[0]?.toLowerCase() ?? "";
+			switch (cmd) {
+				case "ls": {
+					const rawPath = args[1] ?? cwd;
+					return { output: await cmdLs(afs, resolvePath(cwd, rawPath), ansi) };
+				}
+				case "read":
+				case "cat":
+					if (!args[1]) return { output: ansi.err("Usage: read <path>") };
+					return { output: (await cmdRead(afs, resolvePath(cwd, args[1]), ansi)).replace(/\n/g, "\r\n") };
+				case "write":
+					if (!args[1]) return { output: ansi.err("Usage: write <path> <content>") };
+					return { output: await cmdWrite(afs, resolvePath(cwd, args[1]), args.slice(2).join(" "), ansi) };
+				case "stat": {
+					const rawPath = args[1] ?? cwd;
+					return { output: await cmdStat(afs, resolvePath(cwd, rawPath), ansi) };
+				}
+				case "exec": {
+					if (!args[1]) return { output: ansi.err("Usage: exec <path> [args...]") };
+					const path = resolvePath(cwd, args[1]);
+					const execArgs = {};
+					for (let i = 2; i < args.length; i++) {
+						const kv = args[i].split("=");
+						if (kv.length === 2) execArgs[kv[0]] = kv[1];
+						else execArgs[`arg${i - 2}`] = args[i];
+					}
+					return { output: await cmdExec(afs, path, execArgs, ansi) };
+				}
+				case "explain": {
+					const rawPath = args[1] ?? cwd;
+					return { output: await cmdExplain(afs, resolvePath(cwd, rawPath), ansi) };
+				}
+				case "search":
+					if (!args[1] || !args[2]) return { output: ansi.err("Usage: search <path> <query>") };
+					return { output: await cmdSearch(afs, resolvePath(cwd, args[1]), args.slice(2).join(" "), ansi) };
+				case "cd": {
+					const target = args[1] ?? "/";
+					const { newCwd, error } = await cmdCd(afs, cwd, target);
+					cwd = newCwd;
+					return { output: error ? ansi.err(error) : void 0 };
+				}
+				case "pwd": return { output: cwd };
+				case "help": return { output: ansi.help() };
+				case "clear": return { clear: true };
+				case "exit":
+				case "quit": return { exit: true };
+				default: return { output: `${ansi.err(`Unknown command: ${cmd}`)} — type ${ansi.yellow}help${ansi.r} for available commands` };
+			}
+		}
+	};
+}
+
+//#endregion
+export { createAfsReplSession, renderArcBanner };
+//# sourceMappingURL=terminal-repl.mjs.map

package/dist/terminal-repl.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-repl.mjs","names":[],"sources":["../src/terminal-repl.ts"],"sourcesContent":["/**\n * Shared AFS terminal REPL — portable, CF-compatible.\n *\n * Contains the business logic for the AFS interactive terminal:\n * - ARC banner rendering (ASCII art, version, session info)\n * - REPL session factory (command routing, cwd management)\n *\n * No Node.js APIs. Usable in Cloudflare Workers, Node, Bun, browsers.\n *\n * Transport (WebSocket / readline) is left to the caller:\n *   - CF Worker: runtimes/cloudflare/src/terminal-handler.ts\n *   - Node daemon: runtimes/node/src/daemon/server.ts\n */\n\nimport type { AFS } from \"@aigne/afs\";\n\n// ---------------------------------------------------------------------------\n// Banner\n// ---------------------------------------------------------------------------\n\nconst ARC_ART = [\"▄▀█ █▀█ █▀▀\", \"█▀█ █▀▄ █▄▄\"];\nconst TAGLINE = \"Agentic Realm Computer\";\nconst COPYRIGHT = \"Copyright (c) 2026 ArcBlock Inc. All rights reserved.\";\nconst R = \"\\x1b[0m\";\n\n// Truecolor gradient for ASCII art: light cyan → purple (matches splash.ts)\nconst ART_GRADIENT: readonly [number, number, number][] = [\n  [100, 220, 255],\n  [180, 120, 255],\n];\n\n// Per-character tagline gradient (matches splash.ts TAGLINE_TRUECOLOR)\nconst TAGLINE_GRADIENT: readonly [number, number, number][] = [\n  [100, 255, 255],\n  [80, 220, 255],\n  [60, 180, 255],\n  [100, 140, 255],\n  [180, 120, 255],\n  [220, 100, 255],\n];\n\nfunction interpColor(\n  t: number,\n  stops: readonly (readonly [number, number, number])[],\n): [number, number, number] {\n  const scaled = t * (stops.length - 1);\n  const i = Math.min(Math.floor(scaled), stops.length - 2);\n  const frac = scaled - i;\n  const a = stops[i] ?? [0, 0, 0];\n  const b = stops[i + 1] ?? [0, 0, 0];\n  return [\n    Math.round(a[0] + (b[0] - a[0]) * frac),\n    Math.round(a[1] + (b[1] - a[1]) * frac),\n    Math.round(a[2] + (b[2] - a[2]) * frac),\n  ];\n}\n\nfunction rainbowText(text: string): string {\n  const chars = [...text];\n  return chars\n    .map((ch, i) => {\n      if (ch === \" \") return ch;\n      const t = chars.length > 1 ? i / (chars.length - 1) : 0;\n      const [r, g, b] = interpColor(t, TAGLINE_GRADIENT);\n      return `\\x1b[38;2;${r};${g};${b}m${ch}${R}`;\n    })\n    .join(\"\");\n}\n\nexport interface BannerOptions {\n  version: string;\n  commit: string;\n  date: string;\n  /** Provider count to display in the session line. */\n  providerCount?: number;\n  /** Session ID to display in the session line. */\n  sessionId?: string;\n  /** Use ANSI color codes. Default: true. */\n  color?: boolean;\n}\n\n/**\n * Render the ARC terminal banner.\n *\n * Uses 24-bit truecolor gradient (matches Node splash.ts exactly).\n *\n * Output (colored):\n *   ▄▀█ █▀█ █▀▀  Agentic Realm Computer\n *   █▀█ █▀▄ █▄▄  v1.0.0 (abc1234) · 2026-04-23\n *   Copyright (c) 2026 ArcBlock Inc. All rights reserved.\n *\n *   Session: <id> · N providers · Type help for commands.\n */\nexport function renderArcBanner(opts: BannerOptions): string {\n  const color = opts.color !== false;\n  const { version, commit, date, providerCount, sessionId } = opts;\n\n  const tc = (rgb: readonly [number, number, number], s: string) =>\n    color ? `\\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m${s}${R}` : s;\n  const cyan = (s: string) => (color ? `\\x1b[96m${s}${R}` : s);\n  const dim = (s: string) => (color ? `\\x1b[2m${s}${R}` : s);\n\n  const art = ARC_ART.map((line, i) => (color ? tc(ART_GRADIENT[i]!, line) : line));\n  const tagline = color ? rainbowText(TAGLINE) : TAGLINE;\n  const versionStr = [cyan(`v${version}`), dim(`(${commit})`), dim(\"·\"), dim(date)].join(\" \");\n  const copyrightStr = dim(COPYRIGHT);\n  const gap = \"  \";\n\n  const lines: string[] = [\n    `  ${art[0]}${gap}${tagline}`,\n    `  ${art[1]}${gap}${versionStr}`,\n    `  ${copyrightStr}`,\n  ];\n\n  if (providerCount !== undefined || sessionId) {\n    const parts: string[] = [];\n    if (sessionId) parts.push(`Session: ${dim(sessionId)}`);\n    if (providerCount !== undefined) {\n      const plural = providerCount === 1 ? \"provider\" : \"providers\";\n      parts.push(`${providerCount} ${plural}`);\n    }\n    parts.push(`Type ${cyan(\"help\")} for commands.`);\n    lines.push(\"\", `  ${parts.join(dim(\" · \"))}`);\n  }\n\n  return lines.join(\"\\r\\n\");\n}\n\n// ---------------------------------------------------------------------------\n// Session\n// ---------------------------------------------------------------------------\n\nexport interface AfsReplResult {\n  /** Text to display in the terminal (pre-formatted, CRLF line endings). */\n  output?: string;\n  /** If true, the terminal should clear its screen. */\n  clear?: boolean;\n  /** If true, the session is ending; caller should close the connection. */\n  exit?: boolean;\n}\n\nexport interface AfsReplSession {\n  /** Unique session ID (hex string). */\n  readonly sessionId: string;\n  /** Get current prompt string (e.g. `afs data> `). */\n  getPrompt(): string;\n  /**\n   * Count mounted providers via `afs.list(\"/\")`.\n   * Safe to call before the first command — result is cached.\n   */\n  countProviders(): Promise<number>;\n  /**\n   * Route a line of user input.\n   * Handles builtins (cd, pwd, help, clear, exit) and AFS primitives\n   * (ls, read, write, stat, exec, explain, search).\n   */\n  route(line: string): Promise<AfsReplResult>;\n}\n\nexport interface AfsReplOptions {\n  version: string;\n  commit: string;\n  date: string;\n  /** Use ANSI color. Default: true. */\n  color?: boolean;\n}\n\n/** Generate a random hex session ID. */\nfunction genSessionId(): string {\n  const arr = new Uint8Array(8);\n  if (typeof crypto !== \"undefined\" && crypto.getRandomValues) {\n    crypto.getRandomValues(arr);\n  } else {\n    for (let i = 0; i < arr.length; i++) arr[i] = Math.floor(Math.random() * 256);\n  }\n  return Array.from(arr, (b) => b.toString(16).padStart(2, \"0\")).join(\"\");\n}\n\n// ---------------------------------------------------------------------------\n// Path helpers\n// ---------------------------------------------------------------------------\n\nfunction resolvePath(cwd: string, raw: string): string {\n  if (!raw || raw === \".\") return cwd;\n  const absolute = raw.startsWith(\"/\") ? raw : `${cwd === \"/\" ? \"\" : cwd}/${raw}`;\n  const parts = absolute.split(\"/\").filter(Boolean);\n  const resolved: string[] = [];\n  for (const p of parts) {\n    if (p === \"..\") resolved.pop();\n    else if (p !== \".\") resolved.push(p);\n  }\n  return `/${resolved.join(\"/\")}`;\n}\n\n// ---------------------------------------------------------------------------\n// Arg parser\n// ---------------------------------------------------------------------------\n\nfunction parseArgs(input: string): string[] {\n  const args: string[] = [];\n  let current = \"\";\n  let quote: '\"' | \"'\" | null = null;\n  for (const ch of input) {\n    if (quote) {\n      if (ch === quote) quote = null;\n      else current += ch;\n    } else if (ch === '\"' || ch === \"'\") {\n      quote = ch;\n    } else if (ch === \" \" || ch === \"\\t\") {\n      if (current) {\n        args.push(current);\n        current = \"\";\n      }\n    } else {\n      current += ch;\n    }\n  }\n  if (current) args.push(current);\n  return args;\n}\n\n// ---------------------------------------------------------------------------\n// Color helpers (injected from opts.color)\n// ---------------------------------------------------------------------------\n\ninterface Ansi {\n  r: string;\n  red: string;\n  blue: string;\n  yellow: string;\n  bold: string;\n  err(msg: string): string;\n  help(): string;\n}\n\nfunction makeAnsi(color: boolean): Ansi {\n  const r = color ? \"\\x1b[0m\" : \"\";\n  const red = color ? \"\\x1b[31m\" : \"\";\n  const blue = color ? \"\\x1b[34m\" : \"\";\n  const yellow = color ? \"\\x1b[33m\" : \"\";\n  const bold = color ? \"\\x1b[1m\" : \"\";\n  return {\n    r,\n    red,\n    blue,\n    yellow,\n    bold,\n    err: (msg) => `${red}Error:${r} ${msg}`,\n    help: () =>\n      [\n        `${bold}Available commands:${r}`,\n        \"\",\n        `  ${bold}AFS Commands:${r}`,\n        `    ${yellow}ls${r} [path]               List directory contents (default: current dir)`,\n        `    ${yellow}read${r} <path>             Read file content`,\n        `    ${yellow}write${r} <path> <content>  Write content to file`,\n        `    ${yellow}stat${r} [path]             Get file or directory info`,\n        `    ${yellow}exec${r} <path> [args]      Execute an action`,\n        `    ${yellow}explain${r} [path]          Explain path capabilities`,\n        `    ${yellow}search${r} <path> <query>   Search content`,\n        \"\",\n        `  ${bold}REPL Commands:${r}`,\n        `    ${yellow}cd${r} [path]               Change working directory`,\n        `    ${yellow}pwd${r}                     Print working directory`,\n        `    ${yellow}help${r}                    Show this help`,\n        `    ${yellow}clear${r}                   Clear screen`,\n        `    ${yellow}exit${r} / ${yellow}quit${r}             Exit session`,\n      ].join(\"\\r\\n\"),\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Command implementations (pure AFS API calls, color-aware)\n// ---------------------------------------------------------------------------\n\nasync function cmdLs(afs: AFS, path: string, ansi: Ansi): Promise<string> {\n  try {\n    const result = await afs.list(path, { maxDepth: 1 });\n    const items = result.data ?? [];\n    if (!items.length) return \"(empty)\";\n    return items\n      .map((e) => {\n        const isDir =\n          (e.meta as Record<string, unknown> | undefined)?.kind === \"directory\" ||\n          (((e.meta as Record<string, unknown> | undefined)?.childrenCount as number | undefined) ??\n            0) > 0;\n        const name = e.path.split(\"/\").at(-1) ?? e.path;\n        return isDir ? `${ansi.blue}${name}/${ansi.r}` : name;\n      })\n      .join(\"\\r\\n\");\n  } catch (e) {\n    return ansi.err(e instanceof Error ? e.message : String(e));\n  }\n}\n\nasync function cmdRead(afs: AFS, path: string, ansi: Ansi): Promise<string> {\n  try {\n    const result = await afs.read(path);\n    const content = result.data?.content;\n    if (content === undefined || content === null) return ansi.err(\"Not found or not readable\");\n    if (typeof content === \"string\") return content;\n    if (content instanceof Uint8Array) return new TextDecoder().decode(content);\n    return JSON.stringify(content, null, 2);\n  } catch (e) {\n    const msg = e instanceof Error ? e.message : String(e);\n    if (/not found|ENOENT/i.test(msg)) return ansi.err(`Not found: ${path}`);\n    return ansi.err(msg);\n  }\n}\n\nasync function cmdWrite(afs: AFS, path: string, content: string, ansi: Ansi): Promise<string> {\n  try {\n    await afs.write(path, { content });\n    return `Written: ${path}`;\n  } catch (e) {\n    return ansi.err(e instanceof Error ? e.message : String(e));\n  }\n}\n\nasync function cmdStat(afs: AFS, path: string, ansi: Ansi): Promise<string> {\n  try {\n    const result = await afs.stat(path);\n    const meta = (result?.data?.meta as Record<string, unknown>) ?? {};\n    const lines = [`${ansi.bold}Path:${ansi.r} ${path}`];\n    for (const [k, v] of Object.entries(meta)) {\n      if (v !== undefined && v !== null)\n        lines.push(`${ansi.yellow}${k}:${ansi.r} ${JSON.stringify(v)}`);\n    }\n    return lines.join(\"\\r\\n\");\n  } catch (e) {\n    const msg = e instanceof Error ? e.message : String(e);\n    if (/not found|ENOENT/i.test(msg)) return ansi.err(`Not found: ${path}`);\n    return ansi.err(msg);\n  }\n}\n\nasync function cmdExec(\n  afs: AFS,\n  path: string,\n  args: Record<string, unknown>,\n  ansi: Ansi,\n): Promise<string> {\n  try {\n    const result = await afs.exec(path, args);\n    const data = result?.data;\n    if (data === undefined || data === null) return \"(no output)\";\n    if (typeof data === \"string\") return data;\n    return JSON.stringify(data, null, 2);\n  } catch (e) {\n    return ansi.err(e instanceof Error ? e.message : String(e));\n  }\n}\n\nasync function cmdExplain(afs: AFS, path: string, ansi: Ansi): Promise<string> {\n  try {\n    const result = await afs.explain(path);\n    if (!result) return \"(no explanation)\";\n    return result.content ?? \"(no explanation)\";\n  } catch (e) {\n    return ansi.err(e instanceof Error ? e.message : String(e));\n  }\n}\n\nasync function cmdSearch(afs: AFS, path: string, query: string, ansi: Ansi): Promise<string> {\n  try {\n    const result = await afs.search(path, query);\n    const items = result?.data ?? [];\n    if (!Array.isArray(items) || !items.length) return \"(no results)\";\n    return items\n      .map((e: unknown) => {\n        const entry = e as Record<string, unknown>;\n        return typeof entry.path === \"string\" ? entry.path : JSON.stringify(e);\n      })\n      .join(\"\\r\\n\");\n  } catch (e) {\n    return ansi.err(e instanceof Error ? e.message : String(e));\n  }\n}\n\nasync function cmdCd(\n  afs: AFS,\n  cwd: string,\n  target: string,\n): Promise<{ newCwd: string; error?: string }> {\n  const newCwd = resolvePath(cwd, target);\n  if (newCwd === \"/\") return { newCwd };\n  try {\n    const result = await afs.stat(newCwd);\n    const meta = (result?.data?.meta as Record<string, unknown>) ?? {};\n    const isDir =\n      meta.kind === \"directory\" ||\n      meta.childrenCount !== undefined ||\n      newCwd.split(\"/\").filter(Boolean).length === 1;\n    if (!isDir) return { newCwd: cwd, error: `Not a directory: ${newCwd}` };\n    return { newCwd };\n  } catch {\n    try {\n      await afs.list(newCwd, { maxDepth: 1 });\n      return { newCwd };\n    } catch {\n      return { newCwd: cwd, error: `Not found: ${newCwd}` };\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Create a platform-agnostic AFS REPL session.\n *\n * Used by both the CF Worker terminal and the Node daemon terminal.\n * Transport (WebSocket send/receive) is handled by the caller.\n */\nexport function createAfsReplSession(afs: AFS, opts: AfsReplOptions): AfsReplSession {\n  const sessionId = genSessionId();\n  const ansi = makeAnsi(opts.color !== false);\n  let cwd = \"/\";\n  let cachedProviderCount: number | null = null;\n\n  return {\n    sessionId,\n\n    getPrompt(): string {\n      const dir = cwd === \"/\" ? \"/\" : cwd.split(\"/\").at(-1);\n      return `afs ${dir}> `;\n    },\n\n    async countProviders(): Promise<number> {\n      if (cachedProviderCount !== null) return cachedProviderCount;\n      try {\n        const result = await afs.list(\"/\");\n        const seen = new Set<string>();\n        for (const e of result.data ?? []) {\n          if (typeof e?.path === \"string\") seen.add(e.path);\n        }\n        cachedProviderCount = seen.size || 0;\n      } catch {\n        cachedProviderCount = 0;\n      }\n      return cachedProviderCount;\n    },\n\n    async route(line: string): Promise<AfsReplResult> {\n      const trimmed = line.trim();\n      if (!trimmed) return {};\n\n      // Strip optional \"afs \" prefix (users may type `afs ls /`)\n      const input = trimmed.startsWith(\"afs \") ? trimmed.slice(4).trim() : trimmed;\n      const args = parseArgs(input);\n      const cmd = args[0]?.toLowerCase() ?? \"\";\n\n      switch (cmd) {\n        case \"ls\": {\n          const rawPath = args[1] ?? cwd;\n          const path = resolvePath(cwd, rawPath);\n          return { output: await cmdLs(afs, path, ansi) };\n        }\n        case \"read\":\n        case \"cat\": {\n          if (!args[1]) return { output: ansi.err(\"Usage: read <path>\") };\n          const path = resolvePath(cwd, args[1]);\n          const out = await cmdRead(afs, path, ansi);\n          return { output: out.replace(/\\n/g, \"\\r\\n\") };\n        }\n        case \"write\": {\n          if (!args[1]) return { output: ansi.err(\"Usage: write <path> <content>\") };\n          const path = resolvePath(cwd, args[1]);\n          const content = args.slice(2).join(\" \");\n          return { output: await cmdWrite(afs, path, content, ansi) };\n        }\n        case \"stat\": {\n          const rawPath = args[1] ?? cwd;\n          const path = resolvePath(cwd, rawPath);\n          return { output: await cmdStat(afs, path, ansi) };\n        }\n        case \"exec\": {\n          if (!args[1]) return { output: ansi.err(\"Usage: exec <path> [args...]\") };\n          const path = resolvePath(cwd, args[1]);\n          const execArgs: Record<string, unknown> = {};\n          for (let i = 2; i < args.length; i++) {\n            const kv = args[i]!.split(\"=\");\n            if (kv.length === 2) execArgs[kv[0]!] = kv[1];\n            else execArgs[`arg${i - 2}`] = args[i];\n          }\n          return { output: await cmdExec(afs, path, execArgs, ansi) };\n        }\n        case \"explain\": {\n          const rawPath = args[1] ?? cwd;\n          const path = resolvePath(cwd, rawPath);\n          return { output: await cmdExplain(afs, path, ansi) };\n        }\n        case \"search\": {\n          if (!args[1] || !args[2]) return { output: ansi.err(\"Usage: search <path> <query>\") };\n          const path = resolvePath(cwd, args[1]);\n          const query = args.slice(2).join(\" \");\n          return { output: await cmdSearch(afs, path, query, ansi) };\n        }\n        case \"cd\": {\n          const target = args[1] ?? \"/\";\n          const { newCwd, error } = await cmdCd(afs, cwd, target);\n          cwd = newCwd;\n          return { output: error ? ansi.err(error) : undefined };\n        }\n        case \"pwd\":\n          return { output: cwd };\n        case \"help\":\n          return { output: ansi.help() };\n        case \"clear\":\n          return { clear: true };\n        case \"exit\":\n        case \"quit\":\n          return { exit: true };\n        default:\n          return {\n            output: `${ansi.err(`Unknown command: ${cmd}`)} — type ${ansi.yellow}help${ansi.r} for available commands`,\n          };\n      }\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/transport/idle-timer.cjs

@@ -0,0 +1,136 @@
+
+//#region src/transport/idle-timer.ts
+/**
+* Per-WebSocket idle timer — runtime-neutral.
+*
+* Why: long-lived WebSockets that sit idle still consume runtime resources.
+* On Cloudflare Durable Objects this is direct billing (`server.accept()`
+* keeps the DO active for the full WS lifetime); on Node it's memory and
+* file descriptors. Both runtimes benefit from closing WebSockets that
+* haven't seen a client message in a configurable window.
+*
+* What: arm a timer per connection, reset on every inbound message; on
+* expiry, close the WS with a close code ≥ 4000 so the AUP client suppresses
+* its auto-reconnect loop (see `web-page/core.ts` — code ≥ 4000 means
+* "server rejected, do not reconnect"). The user reconnects on next
+* interaction; the existing `sessionId`-based handshake restores per-session
+* state.
+*
+* On Cloudflare, once all WebSockets close, the DO is auto-evicted by the
+* Workers runtime and duration billing stops. On Node, the WS object is GC'd
+* and the file descriptor returned to the OS.
+*/
+/** Close code used for intentional idle close (must be ≥ 4000). */
+const IDLE_CLOSE_CODE = 4001;
+/** Short ASCII reason — CF caps reason at 123 bytes. */
+const IDLE_CLOSE_REASON = "idle-timeout";
+/** Lower bound — under 1s is almost certainly a misconfiguration. */
+const MIN_TIMEOUT_MS = 1e3;
+/** Upper bound — keep one connection alive at most 24h on a single client. */
+const MAX_TIMEOUT_MS = 1440 * 6e4;
+function createIdleTimer(opts) {
+	const { timeoutMs, onIdle } = opts;
+	const setT = opts.setTimeout ?? globalThis.setTimeout;
+	const clearT = opts.clearTimeout ?? globalThis.clearTimeout;
+	if (timeoutMs <= 0) return {
+		rearm() {},
+		cancel() {}
+	};
+	let handle = null;
+	const fire = () => {
+		handle = null;
+		try {
+			onIdle();
+		} catch {}
+	};
+	return {
+		rearm() {
+			if (handle !== null) clearT(handle);
+			handle = setT(fire, timeoutMs);
+		},
+		cancel() {
+			if (handle !== null) {
+				clearT(handle);
+				handle = null;
+			}
+		}
+	};
+}
+/**
+* Best-effort `{ type: string }` sniff of an inbound WS message event, used
+* only to decide whether it should rearm the idle timer. Any parse failure
+* (binary frame, non-JSON text, missing `.data`) is treated as "not a
+* recognized synthetic type" — i.e. it still counts as real activity. This
+* keeps `ignoreMessageTypes` strictly opt-in and never silently swallows a
+* message the caller didn't ask to ignore.
+*/
+function messageTypeOf(event) {
+	try {
+		const data = event?.data;
+		if (typeof data !== "string") return void 0;
+		const parsed = JSON.parse(data);
+		return typeof parsed?.type === "string" ? parsed.type : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* Wire an idle timer to a WebSocket-like object: arm immediately, rearm on
+* every inbound message, cancel on close/error. On expiry, close the socket
+* with `IDLE_CLOSE_CODE` and `IDLE_CLOSE_REASON`.
+*
+* Returns the timer so callers can `cancel()` it during external teardown.
+*/
+function attachIdleClose(server, timeoutMs, options) {
+	const timer = createIdleTimer({
+		timeoutMs,
+		onIdle: () => {
+			try {
+				if (server.readyState === 1) server.close(IDLE_CLOSE_CODE, IDLE_CLOSE_REASON);
+			} catch {}
+		},
+		setTimeout: options?.setTimeout,
+		clearTimeout: options?.clearTimeout
+	});
+	timer.rearm();
+	const ignoreTypes = options?.ignoreMessageTypes;
+	server.addEventListener("message", (event) => {
+		if (ignoreTypes?.length) {
+			const type = messageTypeOf(event);
+			if (type !== void 0 && ignoreTypes.includes(type)) return;
+		}
+		timer.rearm();
+	});
+	server.addEventListener("close", () => timer.cancel());
+	server.addEventListener("error", () => timer.cancel());
+	if (options?.rearmOnOutbound && server.send) {
+		const orig = server.send.bind(server);
+		server.send = (data) => {
+			timer.rearm();
+			orig(data);
+		};
+	}
+	return timer;
+}
+/**
+* Parse an env-supplied idle timeout. Accepts undefined / empty / non-numeric
+* (returns `defaultMs`), `0` (returns `0` — disabled), and clamps to
+* [MIN_TIMEOUT_MS, MAX_TIMEOUT_MS] for any positive value.
+*/
+function resolveIdleTimeoutMs(value, defaultMs) {
+	if (value === void 0 || value === "") return defaultMs;
+	if (!/^-?\d+$/.test(value.trim())) return defaultMs;
+	const n = Number.parseInt(value, 10);
+	if (Number.isNaN(n)) return defaultMs;
+	if (n <= 0) return 0;
+	if (n < MIN_TIMEOUT_MS) return MIN_TIMEOUT_MS;
+	if (n > MAX_TIMEOUT_MS) return MAX_TIMEOUT_MS;
+	return n;
+}
+
+//#endregion
+exports.IDLE_CLOSE_CODE = IDLE_CLOSE_CODE;
+exports.IDLE_CLOSE_REASON = IDLE_CLOSE_REASON;
+exports.attachIdleClose = attachIdleClose;
+exports.createIdleTimer = createIdleTimer;
+exports.resolveIdleTimeoutMs = resolveIdleTimeoutMs;

package/dist/transport/idle-timer.d.cts

@@ -0,0 +1,92 @@
+//#region src/transport/idle-timer.d.ts
+/**
+ * Per-WebSocket idle timer — runtime-neutral.
+ *
+ * Why: long-lived WebSockets that sit idle still consume runtime resources.
+ * On Cloudflare Durable Objects this is direct billing (`server.accept()`
+ * keeps the DO active for the full WS lifetime); on Node it's memory and
+ * file descriptors. Both runtimes benefit from closing WebSockets that
+ * haven't seen a client message in a configurable window.
+ *
+ * What: arm a timer per connection, reset on every inbound message; on
+ * expiry, close the WS with a close code ≥ 4000 so the AUP client suppresses
+ * its auto-reconnect loop (see `web-page/core.ts` — code ≥ 4000 means
+ * "server rejected, do not reconnect"). The user reconnects on next
+ * interaction; the existing `sessionId`-based handshake restores per-session
+ * state.
+ *
+ * On Cloudflare, once all WebSockets close, the DO is auto-evicted by the
+ * Workers runtime and duration billing stops. On Node, the WS object is GC'd
+ * and the file descriptor returned to the OS.
+ */
+/** Close code used for intentional idle close (must be ≥ 4000). */
+declare const IDLE_CLOSE_CODE = 4001;
+/** Short ASCII reason — CF caps reason at 123 bytes. */
+declare const IDLE_CLOSE_REASON = "idle-timeout";
+interface IdleTimerOptions {
+  /** Idle window in ms. `0` disables the timer (useful for tests / opt-out). */
+  timeoutMs: number;
+  /** Invoked when the idle window elapses without a `rearm()`. */
+  onIdle: () => void;
+  /** Test seam — defaults to `globalThis.setTimeout`. */
+  setTimeout?: typeof setTimeout;
+  /** Test seam — defaults to `globalThis.clearTimeout`. */
+  clearTimeout?: typeof clearTimeout;
+}
+interface IdleTimer {
+  /** Reset (or start) the idle countdown. Safe to call repeatedly. */
+  rearm(): void;
+  /** Stop the timer. After cancel, `rearm()` resumes it. */
+  cancel(): void;
+}
+declare function createIdleTimer(opts: IdleTimerOptions): IdleTimer;
+/**
+ * Minimal WebSocket surface used by `attachIdleClose`. Both the CF Workers
+ * `WebSocket` and the Node `ws` library satisfy this shape.
+ */
+interface IdleCloseTarget {
+  readyState: number;
+  close(code?: number, reason?: string): void;
+  send?: (data: any) => void;
+  addEventListener(type: "message" | "close" | "error", listener: (event: unknown) => void): void;
+}
+/**
+ * Wire an idle timer to a WebSocket-like object: arm immediately, rearm on
+ * every inbound message, cancel on close/error. On expiry, close the socket
+ * with `IDLE_CLOSE_CODE` and `IDLE_CLOSE_REASON`.
+ *
+ * Returns the timer so callers can `cancel()` it during external teardown.
+ */
+declare function attachIdleClose(server: IdleCloseTarget, timeoutMs: number, options?: {
+  /**
+   * When true, wraps `server.send` so that every outbound server push also
+   * rearms the idle timer. Without this, a session receiving only passive
+   * live-update pushes (no client→server traffic) is considered "idle" and
+   * closed after `timeoutMs` even though it has ongoing server activity.
+   */
+  rearmOnOutbound?: boolean;
+  /**
+   * Inbound message `type` values that must NOT rearm the idle timer.
+   * Exists for synthetic client keepalive frames (e.g. the AUP web client's
+   * `{type:"ping"}`, sent purely to defeat CF-edge / mobile-NAT idle-drop
+   * of an otherwise-unused connection — see WS_KEEPALIVE_MESSAGE_TYPE in
+   * `@aigne/afs-ui`). Without this, a keepalive ping would itself count as
+   * "activity" and the idle-close timer — whose entire purpose is evicting
+   * genuinely-unused connections to stop Durable Object duration billing —
+   * would never fire for as long as the tab merely sits open (arc#1243).
+   * Messages that fail to parse as `{type: string}` JSON are never treated
+   * as ignorable, so this can only narrow rearm triggers, never widen them.
+   */
+  ignoreMessageTypes?: string[];
+  setTimeout?: typeof setTimeout;
+  clearTimeout?: typeof clearTimeout;
+}): IdleTimer;
+/**
+ * Parse an env-supplied idle timeout. Accepts undefined / empty / non-numeric
+ * (returns `defaultMs`), `0` (returns `0` — disabled), and clamps to
+ * [MIN_TIMEOUT_MS, MAX_TIMEOUT_MS] for any positive value.
+ */
+declare function resolveIdleTimeoutMs(value: string | undefined, defaultMs: number): number;
+//#endregion
+export { IDLE_CLOSE_CODE, IDLE_CLOSE_REASON, IdleCloseTarget, IdleTimer, IdleTimerOptions, attachIdleClose, createIdleTimer, resolveIdleTimeoutMs };
+//# sourceMappingURL=idle-timer.d.cts.map

package/dist/transport/idle-timer.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idle-timer.d.cts","names":[],"sources":["../../src/transport/idle-timer.ts"],"mappings":";;AAsBA;;;;;AAGA;;;;;AAOA;;;;;;;;;;cAVa,eAAA;;cAGA,iBAAA;AAAA,UAOI,gBAAA;;EAEf,SAAA;EAaM;EAXN,MAAA;EAc6B;EAZ7B,UAAA,UAAoB,UAAA;EAY4C;EAVhE,YAAA,UAAsB,YAAA;AAAA;AAAA,UAGP,SAAA;EAOiD;EALhE,KAAA;EA2Ce;EAzCf,MAAA;AAAA;AAAA,iBAGc,eAAA,CAAgB,IAAA,EAAM,gBAAA,GAAmB,SAAA;;;;;UAsCxC,eAAA;EACf,UAAA;EACA,KAAA,CAAM,IAAA,WAAe,MAAA;EACrB,IAAA,IAAQ,IAAA;EACR,gBAAA,CAAiB,IAAA,iCAAqC,QAAA,GAAW,KAAA;AAAA;;;AA6BnE;;;;;iBAAgB,eAAA,CACd,MAAA,EAAQ,eAAA,EACR,SAAA,UACA,OAAA;EAwBC;;;;;;EAjBC,eAAA;EAaA;;;;;;;;;AAgDJ;;;EAhDI,kBAAA;EACA,UAAA,UAAoB,UAAA;EACpB,YAAA,UAAsB,YAAA;AAAA,IAEvB,SAAA;;;;;;iBA4Ca,oBAAA,CAAqB,KAAA,sBAA2B,SAAA"}