@nghyane/arcane 0.1.0

package/src/internal-urls/docs-protocol.ts

@@ -0,0 +1,84 @@
+/**
+ * Protocol handler for docs:// URLs.
+ *
+ * Serves statically embedded documentation files bundled at build time.
+ *
+ * URL forms:
+ * - docs:// - Lists all available documentation files
+ * - docs://<file>.md - Reads a specific documentation file
+ */
+import * as path from "node:path";
+import { EMBEDDED_DOC_FILENAMES, EMBEDDED_DOCS } from "./docs-index.generated";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+/**
+ * Handler for docs:// URLs.
+ *
+ * Resolves documentation file names to their content, or lists available docs.
+ */
+export class DocsProtocolHandler implements ProtocolHandler {
+	readonly scheme = "docs";
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		// Extract filename from host + path
+		const host = url.rawHost || url.hostname;
+		const pathname = url.rawPathname ?? url.pathname;
+		const filename = host ? (pathname && pathname !== "/" ? host + pathname : host) : "";
+
+		if (!filename) {
+			return this.#listDocs(url);
+		}
+
+		return this.#readDoc(filename, url);
+	}
+
+	async #listDocs(url: InternalUrl): Promise<InternalResource> {
+		if (EMBEDDED_DOC_FILENAMES.length === 0) {
+			throw new Error("No documentation files found");
+		}
+
+		const listing = EMBEDDED_DOC_FILENAMES.map(f => `- [${f}](docs://${f})`).join("\n");
+		const content = `# Documentation\n\n${EMBEDDED_DOC_FILENAMES.length} files available:\n\n${listing}\n`;
+
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: "docs://",
+		};
+	}
+
+	async #readDoc(filename: string, url: InternalUrl): Promise<InternalResource> {
+		// Validate: no traversal, no absolute paths
+		if (path.isAbsolute(filename)) {
+			throw new Error("Absolute paths are not allowed in docs:// URLs");
+		}
+
+		const normalized = path.posix.normalize(filename.replaceAll("\\", "/"));
+		if (normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
+			throw new Error("Path traversal (..) is not allowed in docs:// URLs");
+		}
+
+		const content = EMBEDDED_DOCS[normalized];
+		if (content === undefined) {
+			const lookup = normalized.replace(/\.md$/, "");
+			const suggestions = EMBEDDED_DOC_FILENAMES.filter(
+				f => f.includes(lookup) || lookup.includes(f.replace(/\.md$/, "")),
+			).slice(0, 5);
+			const suffix =
+				suggestions.length > 0
+					? `\nDid you mean: ${suggestions.join(", ")}`
+					: "\nUse docs:// to list available files.";
+			throw new Error(`Documentation file not found: ${filename}${suffix}`);
+		}
+
+		return {
+			url: url.href,
+			content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: `docs://${normalized}`,
+		};
+	}
+}

package/src/internal-urls/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Internal URL routing system for internal protocols like agent://, memory://, and skill://.
+ *
+ * This module provides a unified way to resolve internal URLs without
+ * exposing filesystem paths to the agent.
+ *
+ * @example
+ * ```ts
+ * import { InternalUrlRouter, AgentProtocolHandler, MemoryProtocolHandler, SkillProtocolHandler } from './internal-urls';
+ *
+ * const router = new InternalUrlRouter();
+ * router.register(new AgentProtocolHandler({ getArtifactsDir: () => sessionDir }));
+ * router.register(new MemoryProtocolHandler({ getMemoryRoot: () => memoryRoot }));
+ * router.register(new SkillProtocolHandler({ getSkills: () => skills }));
+ *
+ * if (router.canHandle('agent://reviewer_0')) {
+ *   const resource = await router.resolve('agent://reviewer_0');
+ *   console.log(resource.content);
+ * }
+ * ```
+ */
+
+export { AgentProtocolHandler, type AgentProtocolOptions } from "./agent-protocol";
+export { ArtifactProtocolHandler, type ArtifactProtocolOptions } from "./artifact-protocol";
+export { DocsProtocolHandler } from "./docs-protocol";
+export { applyQuery, parseQuery, pathToQuery } from "./json-query";
+export { MemoryProtocolHandler, type MemoryProtocolOptions, resolveMemoryUrlToPath } from "./memory-protocol";
+export { InternalUrlRouter } from "./router";
+export { RuleProtocolHandler, type RuleProtocolOptions } from "./rule-protocol";
+export { SkillProtocolHandler, type SkillProtocolOptions } from "./skill-protocol";
+export type { InternalResource, InternalUrl, ProtocolHandler } from "./types";

package/src/internal-urls/json-query.ts

@@ -0,0 +1,126 @@
+/**
+ * JSON query parser and executor for agent:// URL extraction.
+ *
+ * Supports jq-like syntax: .foo, [0], .foo.bar[0].baz, ["special-key"]
+ * Also supports path form: /foo/bar/0 -> .foo.bar[0]
+ */
+
+/**
+ * Parse a jq-like query string into tokens.
+ *
+ * @example
+ * parseQuery(".foo.bar[0]") // ["foo", "bar", 0]
+ * parseQuery(".foo['special-key']") // ["foo", "special-key"]
+ */
+export function parseQuery(query: string): Array<string | number> {
+	let input = query.trim();
+	if (!input) return [];
+	if (input.startsWith(".")) input = input.slice(1);
+	if (!input) return [];
+
+	const tokens: Array<string | number> = [];
+	let i = 0;
+
+	const isIdentChar = (ch: string) => /[A-Za-z0-9_-]/.test(ch);
+
+	while (i < input.length) {
+		const ch = input[i];
+		if (ch === ".") {
+			i++;
+			continue;
+		}
+		if (ch === "[") {
+			const closeIndex = input.indexOf("]", i + 1);
+			if (closeIndex === -1) {
+				throw new Error(`Invalid query: missing ] in ${query}`);
+			}
+			const raw = input.slice(i + 1, closeIndex).trim();
+			if (!raw) {
+				throw new Error(`Invalid query: empty [] in ${query}`);
+			}
+			const quote = raw[0];
+			if ((quote === '"' || quote === "'") && raw.endsWith(quote)) {
+				let inner = raw.slice(1, -1);
+				inner = inner.replace(/\\(["'\\])/g, "$1");
+				tokens.push(inner);
+			} else if (/^\d+$/.test(raw)) {
+				tokens.push(Number(raw));
+			} else {
+				tokens.push(raw);
+			}
+			i = closeIndex + 1;
+			continue;
+		}
+
+		const start = i;
+		while (i < input.length && isIdentChar(input[i])) {
+			i++;
+		}
+		if (start === i) {
+			throw new Error(`Invalid query: unexpected token '${input[i]}' in ${query}`);
+		}
+		const ident = input.slice(start, i);
+		tokens.push(ident);
+	}
+
+	return tokens;
+}
+
+/**
+ * Apply a parsed query to a JSON value.
+ *
+ * @example
+ * applyQuery({ foo: { bar: [1, 2, 3] } }, ".foo.bar[0]") // 1
+ */
+export function applyQuery(data: unknown, query: string): unknown {
+	const tokens = parseQuery(query);
+	let current: unknown = data;
+	for (const token of tokens) {
+		if (current === null || current === undefined) return undefined;
+		if (typeof token === "number") {
+			if (!Array.isArray(current)) return undefined;
+			current = current[token];
+			continue;
+		}
+		if (typeof current !== "object") return undefined;
+		const record = current as Record<string, unknown>;
+		current = record[token];
+	}
+	return current;
+}
+
+/**
+ * Convert a URL path form to a query string.
+ *
+ * Path form: /foo/bar/0 -> .foo.bar[0]
+ * Trailing slash is normalized (ignored).
+ *
+ * Segments that are not valid identifiers use bracket notation: ['segment']
+ */
+export function pathToQuery(urlPath: string): string {
+	if (!urlPath || urlPath === "/") return "";
+
+	const segments = urlPath.split("/").filter(Boolean);
+	if (segments.length === 0) return "";
+
+	const parts: string[] = [];
+	for (const segment of segments) {
+		let decoded = segment;
+		try {
+			decoded = decodeURIComponent(segment);
+		} catch {
+			decoded = segment;
+		}
+		const isIdentifier = /^[A-Za-z0-9_-]+$/.test(decoded);
+		if (/^\d+$/.test(decoded)) {
+			parts.push(`[${decoded}]`);
+		} else if (isIdentifier) {
+			parts.push(`.${decoded}`);
+		} else {
+			const escaped = decoded.replace(/\\/g, String.raw`\\`).replace(/'/g, String.raw`\'`);
+			parts.push(`['${escaped}']`);
+		}
+	}
+
+	return parts.join("");
+}

package/src/internal-urls/memory-protocol.ts

@@ -0,0 +1,133 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isEnoent } from "@nghyane/arcane-utils";
+import { validateRelativePath } from "./skill-protocol";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+const DEFAULT_MEMORY_FILE = "memory_summary.md";
+const MEMORY_NAMESPACE = "root";
+
+/**
+ * Options for the memory:// URL protocol.
+ */
+export interface MemoryProtocolOptions {
+	/**
+	 * Returns the absolute path to the current project's memory root.
+	 */
+	getMemoryRoot: () => string;
+}
+
+function ensureWithinRoot(targetPath: string, rootPath: string): void {
+	if (targetPath !== rootPath && !targetPath.startsWith(`${rootPath}${path.sep}`)) {
+		throw new Error("memory:// URL escapes memory root");
+	}
+}
+
+function toMemoryValidationError(error: unknown): Error {
+	const message = error instanceof Error ? error.message : String(error);
+	return new Error(message.replace("skill://", "memory://"));
+}
+
+/**
+ * Resolve a memory:// URL to an absolute filesystem path under memory root.
+ */
+export function resolveMemoryUrlToPath(url: InternalUrl, memoryRoot: string): string {
+	const namespace = url.rawHost || url.hostname;
+	if (!namespace) {
+		throw new Error("memory:// URL requires a namespace: memory://root");
+	}
+	if (namespace !== MEMORY_NAMESPACE) {
+		throw new Error(`Unknown memory namespace: ${namespace}. Supported: ${MEMORY_NAMESPACE}`);
+	}
+
+	const rawPathname = url.rawPathname ?? url.pathname;
+	const hasPath = rawPathname && rawPathname !== "/" && rawPathname !== "";
+	if (!hasPath) {
+		return path.resolve(memoryRoot, DEFAULT_MEMORY_FILE);
+	}
+	let relativePath: string;
+	try {
+		relativePath = decodeURIComponent(rawPathname.slice(1));
+	} catch {
+		throw new Error(`Invalid URL encoding in memory:// path: ${url.href}`);
+	}
+
+	try {
+		validateRelativePath(relativePath);
+	} catch (error) {
+		throw toMemoryValidationError(error);
+	}
+
+	return path.resolve(memoryRoot, relativePath);
+}
+
+/**
+ * Protocol handler for memory:// URLs.
+ *
+ * URL forms:
+ * - memory://root - Reads memory_summary.md
+ * - memory://root/<path> - Reads a relative file under memory root
+ */
+export class MemoryProtocolHandler implements ProtocolHandler {
+	readonly scheme = "memory";
+
+	constructor(private readonly options: MemoryProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const memoryRoot = path.resolve(this.options.getMemoryRoot());
+		let resolvedRoot: string;
+		try {
+			resolvedRoot = await fs.realpath(memoryRoot);
+		} catch (error) {
+			if (isEnoent(error)) {
+				throw new Error(
+					"Memory artifacts are not available for this project yet. Run a session with memories enabled first.",
+				);
+			}
+			throw error;
+		}
+
+		const targetPath = resolveMemoryUrlToPath(url, resolvedRoot);
+		ensureWithinRoot(targetPath, resolvedRoot);
+
+		const parentDir = path.dirname(targetPath);
+		try {
+			const realParent = await fs.realpath(parentDir);
+			ensureWithinRoot(realParent, resolvedRoot);
+		} catch (error) {
+			if (!isEnoent(error)) {
+				throw error;
+			}
+		}
+
+		let realTargetPath: string;
+		try {
+			realTargetPath = await fs.realpath(targetPath);
+		} catch (error) {
+			if (isEnoent(error)) {
+				throw new Error(`Memory file not found: ${url.href}`);
+			}
+			throw error;
+		}
+
+		ensureWithinRoot(realTargetPath, resolvedRoot);
+
+		const stat = await fs.stat(realTargetPath);
+		if (!stat.isFile()) {
+			throw new Error(`memory:// URL must resolve to a file: ${url.href}`);
+		}
+
+		const content = await Bun.file(realTargetPath).text();
+		const ext = path.extname(realTargetPath).toLowerCase();
+		const contentType: InternalResource["contentType"] = ext === ".md" ? "text/markdown" : "text/plain";
+
+		return {
+			url: url.href,
+			content,
+			contentType,
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: realTargetPath,
+			notes: [],
+		};
+	}
+}

package/src/internal-urls/router.ts

@@ -0,0 +1,70 @@
+/**
+ * Internal URL router for internal protocols (agent://, artifact://, plan://, memory://, skill://, rule://, docs://).
+ */
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+/**
+ * Router for internal URL schemes.
+ *
+ * Dispatches URLs like `agent://output_id` or `memory://root/memory_summary.md` to
+ * registered protocol handlers.
+ */
+export class InternalUrlRouter {
+	#handlers = new Map<string, ProtocolHandler>();
+
+	/**
+	 * Register a protocol handler.
+	 * @param handler Handler to register (uses handler.scheme as key)
+	 */
+	register(handler: ProtocolHandler): void {
+		this.#handlers.set(handler.scheme, handler);
+	}
+
+	/**
+	 * Check if the router can handle a URL.
+	 * @param input URL string to check
+	 */
+	canHandle(input: string): boolean {
+		const match = input.match(/^([a-z][a-z0-9+.-]*):\/\//i);
+		if (!match) return false;
+		const scheme = match[1].toLowerCase();
+		return this.#handlers.has(scheme);
+	}
+
+	/**
+	 * Resolve an internal URL to its content.
+	 * @param input URL string (e.g., "agent://reviewer_0", "skill://notion-pages")
+	 * @throws Error if scheme is not registered or resolution fails
+	 */
+	async resolve(input: string): Promise<InternalResource> {
+		let parsed: URL;
+		try {
+			parsed = new URL(input);
+		} catch {
+			throw new Error(`Invalid URL: ${input}`);
+		}
+
+		const hostMatch = input.match(/^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)/i);
+		let rawHost = hostMatch ? hostMatch[2] : parsed.hostname;
+		try {
+			rawHost = decodeURIComponent(rawHost);
+		} catch {
+			// Leave rawHost as-is if decoding fails.
+		}
+		(parsed as InternalUrl).rawHost = rawHost;
+		const pathMatch = input.match(/^[a-z][a-z0-9+.-]*:\/\/[^/?#]*(\/[^?#]*)?/i);
+		(parsed as InternalUrl).rawPathname = pathMatch?.[1] ?? parsed.pathname;
+
+		const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
+		const handler = this.#handlers.get(scheme);
+
+		if (!handler) {
+			const available = Array.from(this.#handlers.keys())
+				.map(s => `${s}://`)
+				.join(", ");
+			throw new Error(`Unknown protocol: ${scheme}://\nSupported: ${available || "none"}`);
+		}
+
+		return handler.resolve(parsed as InternalUrl);
+	}
+}

package/src/internal-urls/rule-protocol.ts

@@ -0,0 +1,55 @@
+/**
+ * Protocol handler for rule:// URLs.
+ *
+ * Resolves rule names to their content files.
+ *
+ * URL forms:
+ * - rule://<name> - Reads rule content
+ */
+import type { Rule } from "../capability/rule";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+export interface RuleProtocolOptions {
+	/**
+	 * Returns the currently loaded rules.
+	 */
+	getRules: () => readonly Rule[];
+}
+
+/**
+ * Handler for rule:// URLs.
+ *
+ * Resolves rule names to their content.
+ */
+export class RuleProtocolHandler implements ProtocolHandler {
+	readonly scheme = "rule";
+
+	constructor(private readonly options: RuleProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const rules = this.options.getRules();
+
+		// Extract rule name from host
+		const ruleName = url.rawHost || url.hostname;
+		if (!ruleName) {
+			throw new Error("rule:// URL requires a rule name: rule://<name>");
+		}
+
+		// Find the rule
+		const rule = rules.find(r => r.name === ruleName);
+		if (!rule) {
+			const available = rules.map(r => r.name);
+			const availableStr = available.length > 0 ? available.join(", ") : "none";
+			throw new Error(`Unknown rule: ${ruleName}\nAvailable: ${availableStr}`);
+		}
+
+		return {
+			url: url.href,
+			content: rule.content,
+			contentType: "text/markdown",
+			size: Buffer.byteLength(rule.content, "utf-8"),
+			sourcePath: rule.path,
+			notes: [],
+		};
+	}
+}

package/src/internal-urls/skill-protocol.ts

@@ -0,0 +1,111 @@
+/**
+ * Protocol handler for skill:// URLs.
+ *
+ * Resolves skill names to their SKILL.md files or relative paths within skill directories.
+ *
+ * URL forms:
+ * - skill://<name> - Reads SKILL.md
+ * - skill://<name>/<path> - Reads relative path within skill's baseDir
+ */
+import * as path from "node:path";
+import type { Skill } from "../extensibility/skills";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+export interface SkillProtocolOptions {
+	/**
+	 * Returns the currently loaded skills.
+	 */
+	getSkills: () => readonly Skill[];
+}
+
+/**
+ * Get content type based on file extension.
+ */
+function getContentType(filePath: string): InternalResource["contentType"] {
+	const ext = path.extname(filePath).toLowerCase();
+	if (ext === ".md") return "text/markdown";
+	return "text/plain";
+}
+
+/**
+ * Validate that a path is safe (no traversal, no absolute paths).
+ */
+export function validateRelativePath(relativePath: string): void {
+	if (path.isAbsolute(relativePath)) {
+		throw new Error("Absolute paths are not allowed in skill:// URLs");
+	}
+
+	const normalized = path.normalize(relativePath);
+	if (normalized.startsWith("..") || normalized.includes("/../") || normalized.includes("/..")) {
+		throw new Error("Path traversal (..) is not allowed in skill:// URLs");
+	}
+}
+
+/**
+ * Handler for skill:// URLs.
+ *
+ * Resolves skill names to their content files.
+ */
+export class SkillProtocolHandler implements ProtocolHandler {
+	readonly scheme = "skill";
+
+	constructor(private readonly options: SkillProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const skills = this.options.getSkills();
+
+		// Extract skill name from host
+		const skillName = url.rawHost || url.hostname;
+		if (!skillName) {
+			throw new Error("skill:// URL requires a skill name: skill://<name>");
+		}
+
+		// Find the skill
+		const skill = skills.find(s => s.name === skillName);
+		if (!skill) {
+			const available = skills.map(s => s.name);
+			const availableStr = available.length > 0 ? available.join(", ") : "none";
+			throw new Error(`Unknown skill: ${skillName}\nAvailable: ${availableStr}`);
+		}
+
+		// Determine the file to read
+		let targetPath: string;
+		const urlPath = url.pathname;
+		const hasRelativePath = urlPath && urlPath !== "/" && urlPath !== "";
+
+		if (hasRelativePath) {
+			// Read relative path within skill's baseDir
+			const relativePath = decodeURIComponent(urlPath.slice(1)); // Remove leading /
+			validateRelativePath(relativePath);
+			targetPath = path.join(skill.baseDir, relativePath);
+
+			// Verify the resolved path is still within baseDir
+			const resolvedPath = path.resolve(targetPath);
+			const resolvedBaseDir = path.resolve(skill.baseDir);
+			if (!resolvedPath.startsWith(resolvedBaseDir + path.sep) && resolvedPath !== resolvedBaseDir) {
+				throw new Error("Path traversal is not allowed");
+			}
+		} else {
+			// Read SKILL.md
+			targetPath = skill.filePath;
+		}
+
+		// Read the file
+		const file = Bun.file(targetPath);
+		if (!(await file.exists())) {
+			throw new Error(`File not found: ${targetPath}`);
+		}
+
+		const content = await file.text();
+		const contentType = getContentType(targetPath);
+
+		return {
+			url: url.href,
+			content,
+			contentType,
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: targetPath,
+			notes: [],
+		};
+	}
+}

package/src/internal-urls/types.ts

@@ -0,0 +1,52 @@
+/**
+ * Types for the internal URL routing system.
+ *
+ * Internal URLs (agent://, artifact://, plan://, memory://, skill://, rule://) are resolved by tools like fetch and read,
+ * providing access to agent outputs and skill files without exposing filesystem paths.
+ */
+
+/**
+ * Resolved internal resource returned by protocol handlers.
+ */
+export interface InternalResource {
+	/** Canonical URL that was resolved */
+	url: string;
+	/** Resolved text content */
+	content: string;
+	/** MIME type: text/markdown, application/json, or text/plain */
+	contentType: "text/markdown" | "application/json" | "text/plain";
+	/** Content size in bytes */
+	size?: number;
+	/** Underlying filesystem path (for debugging, not exposed to agent) */
+	sourcePath?: string;
+	/** Additional notes about resolution */
+	notes?: string[];
+}
+
+/**
+ * Parsed internal URL with preserved host casing.
+ */
+export interface InternalUrl extends URL {
+	/**
+	 * Raw host segment extracted from input, preserving case.
+	 */
+	rawHost: string;
+	/**
+	 * Raw pathname extracted from input, preserving traversal markers before URL normalization.
+	 */
+	rawPathname?: string;
+}
+
+/**
+ * Handler for a specific internal URL scheme (e.g., agent://, memory://, skill://).
+ */
+export interface ProtocolHandler {
+	/** The scheme this handler processes (without trailing ://) */
+	readonly scheme: string;
+	/**
+	 * Resolve an internal URL to its content.
+	 * @param url Parsed URL object
+	 * @throws Error with user-friendly message if resolution fails
+	 */
+	resolve(url: InternalUrl): Promise<InternalResource>;
+}