skilld 1.5.1 → 1.5.3

package/dist/THIRD-PARTY-LICENSES.md

@@ -0,0 +1,38 @@
+# Licenses of Bundled Dependencies
+
+The published artifact additionally contains code with the following licenses:
+MIT
+
+# Bundled Dependencies
+
+## @sinclair/typebox
+
+License: MIT
+By: sinclairzx81
+Repository: https://github.com/sinclairzx81/typebox-legacy
+
+> TypeBox
+> 
+> Json Schema Type Builder with Static Type Resolution for TypeScript 
+> 
+> The MIT License (MIT)
+> 
+> Copyright (c) 2017-2026 Haydn Paterson
+> 
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+> 
+> The above copyright notice and this permission notice shall be included in
+> all copies or substantial portions of the Software.
+> 
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+> THE SOFTWARE.

package/dist/_chunks/agent.mjs

@@ -1,34 +1,25 @@
+import { t as __exportAll } from "./rolldown-runtime.mjs";
 import { n as sanitizeMarkdown } from "./sanitize.mjs";
 import { h as writeSections, m as readCachedSection } from "./cache.mjs";
 import { i as resolveSkilldCommand } from "./shared.mjs";
 import { a as targets, t as detectInstalledAgents } from "./detect.mjs";
-import { c as SECTION_OUTPUT_FILES, f as getSectionValidator, l as buildAllSectionPrompts, m as wrapSection, p as portabilizePrompt, s as SECTION_MERGE_ORDER } from "./prompts.mjs";
+import { c as SECTION_OUTPUT_FILES, f as getSectionValidator, l as buildAllSectionPrompts, m as wrapSection, s as SECTION_MERGE_ORDER } from "./prompts.mjs";
+import { t as Type } from "./libs/@sinclair/typebox.mjs";
 import { homedir } from "node:os";
 import { dirname, join } from "pathe";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, unlinkSync, writeFileSync } from "node:fs";
-import { exec, spawn } from "node:child_process";
+import { exec, execFileSync, spawn } from "node:child_process";
 import { isWindows } from "std-env";
 import { glob } from "tinyglobby";
 import { findDynamicImports, findStaticImports } from "mlly";
 import { createHash } from "node:crypto";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { promisify } from "node:util";
+import { resolve as resolve$1 } from "node:path";
 import { getEnvApiKey, getModel, getModels, getProviders, streamSimple } from "@mariozechner/pi-ai";
 import { getOAuthApiKey, getOAuthProvider, getOAuthProviders } from "@mariozechner/pi-ai/oauth";
 import { readFile } from "node:fs/promises";
 import { parseSync } from "oxc-parser";
-//#region \0rolldown/runtime.js
-var __defProp = Object.defineProperty;
-var __exportAll = (all, no_symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
-//#endregion
 //#region src/agent/clis/claude.ts
 var claude_exports = /* @__PURE__ */ __exportAll({
 	agentId: () => agentId$2,
@@ -455,93 +446,147 @@ function getAvailablePiAiModels() {
 	}
 	return available;
 }
-const REFERENCE_SUBDIRS = [
-	"docs",
-	"issues",
-	"discussions",
-	"releases"
+const TOOLS = [
+	{
+		name: "Read",
+		description: "Read a file. Path is relative to the working directory (e.g. \"./.skilld/docs/api.md\").",
+		parameters: Type.Object({ path: Type.String({ description: "File path to read" }) })
+	},
+	{
+		name: "Glob",
+		description: "List files matching a glob pattern (e.g. \"./.skilld/docs/*.md\"). Returns newline-separated paths.",
+		parameters: Type.Object({
+			pattern: Type.String({ description: "Glob pattern" }),
+			no_ignore: Type.Optional(Type.Boolean({ description: "Include gitignored files" }))
+		})
+	},
+	{
+		name: "Write",
+		description: "Write content to a file.",
+		parameters: Type.Object({
+			path: Type.String({ description: "File path to write" }),
+			content: Type.String({ description: "File content" })
+		})
+	},
+	{
+		name: "Bash",
+		description: "Run a shell command. Use for `skilld search`, `skilld validate`, etc.",
+		parameters: Type.Object({ command: Type.String({ description: "Shell command to run" }) })
+	}
 ];
-const MAX_REFERENCE_CHARS = 15e4;
-/** Read reference files from .skilld/ and format as inline context */
-function collectReferenceContent(skillDir) {
-	const skilldDir = join(skillDir, ".skilld");
-	if (!existsSync(skilldDir)) return "";
-	const files = [];
-	let totalChars = 0;
-	for (const subdir of REFERENCE_SUBDIRS) {
-		const dirPath = join(skilldDir, subdir);
-		if (!existsSync(dirPath)) continue;
-		const indexPath = join(dirPath, "_INDEX.md");
-		if (existsSync(indexPath) && totalChars < MAX_REFERENCE_CHARS) {
-			const content = sanitizeMarkdown(readFileSync(indexPath, "utf-8"));
-			if (totalChars + content.length <= MAX_REFERENCE_CHARS) {
-				files.push({
-					path: `references/${subdir}/_INDEX.md`,
-					content
-				});
-				totalChars += content.length;
-			}
-		}
-		const entries = readdirSync(dirPath, { recursive: true });
-		for (const entry of entries) {
-			if (totalChars >= MAX_REFERENCE_CHARS) break;
-			const entryStr = String(entry);
-			if (!entryStr.endsWith(".md") || entryStr === "_INDEX.md") continue;
-			const fullPath = join(dirPath, entryStr);
-			if (!existsSync(fullPath)) continue;
-			try {
-				const content = sanitizeMarkdown(readFileSync(fullPath, "utf-8"));
-				if (totalChars + content.length > MAX_REFERENCE_CHARS) continue;
-				files.push({
-					path: `references/${subdir}/${entryStr}`,
-					content
-				});
-				totalChars += content.length;
-			} catch {}
+const MAX_TOOL_TURNS = 30;
+const SAFE_COMMANDS = new Set([
+	"skilld",
+	"ls",
+	"cat",
+	"find"
+]);
+const SHELL_META_RE = /[;&|`$()<>]/;
+/** Resolve a path safely within skilldDir, blocking traversal */
+function resolveSandboxedPath(p, skilldDir) {
+	const resolved = resolve$1(skilldDir, String(p).replace(/^\.\/\.skilld\//, "./").replace(/^\.skilld\//, "./").replace(/^\.\//, ""));
+	if (!resolved.startsWith(`${skilldDir}/`) && resolved !== skilldDir) throw new Error(`Path traversal blocked: ${p}`);
+	return resolved;
+}
+/** Match a file path against a glob pattern using simple segment matching (no regex from user input) */
+function globMatch(filePath, pattern) {
+	const segments = pattern.split("**");
+	if (segments.length === 1) {
+		const parts = pattern.split("*");
+		if (parts.length === 1) return filePath === pattern;
+		let pos = 0;
+		for (let i = 0; i < parts.length; i++) {
+			const part = parts[i];
+			if (!part) continue;
+			const idx = filePath.indexOf(part, pos);
+			if (idx === -1) return false;
+			if (i === 0 && idx !== 0) return false;
+			pos = idx + part.length;
 		}
+		if (parts.at(-1) !== "") return pos === filePath.length;
+		return true;
 	}
-	const readmePath = join(skilldDir, "pkg", "README.md");
-	if (existsSync(readmePath) && totalChars < MAX_REFERENCE_CHARS) {
-		const content = sanitizeMarkdown(readFileSync(readmePath, "utf-8"));
-		if (totalChars + content.length <= MAX_REFERENCE_CHARS) {
-			files.push({
-				path: "references/pkg/README.md",
-				content
-			});
-			totalChars += content.length;
+	let remaining = filePath;
+	for (let i = 0; i < segments.length; i++) {
+		const seg = segments[i];
+		if (!seg) continue;
+		const segParts = seg.split("*");
+		let pos = 0;
+		let matched = false;
+		for (let attempt = remaining.indexOf(segParts[0], 0); attempt !== -1; attempt = remaining.indexOf(segParts[0], attempt + 1)) {
+			pos = attempt;
+			matched = true;
+			for (const sp of segParts) {
+				if (!sp) continue;
+				const idx = remaining.indexOf(sp, pos);
+				if (idx === -1) {
+					matched = false;
+					break;
+				}
+				pos = idx + sp.length;
+			}
+			if (matched) break;
 		}
+		if (!matched) return false;
+		remaining = remaining.slice(pos);
 	}
-	const pkgDir = join(skilldDir, "pkg");
-	if (existsSync(pkgDir) && totalChars < MAX_REFERENCE_CHARS) try {
-		const pkgEntries = readdirSync(pkgDir, { recursive: true });
-		for (const entry of pkgEntries) {
-			const entryStr = String(entry);
-			if (!entryStr.endsWith(".d.ts")) continue;
-			const fullPath = join(pkgDir, entryStr);
-			if (!existsSync(fullPath)) continue;
-			const content = sanitizeMarkdown(readFileSync(fullPath, "utf-8"));
-			if (totalChars + content.length <= MAX_REFERENCE_CHARS) {
-				files.push({
-					path: `references/pkg/${entryStr}`,
-					content
-				});
-				totalChars += content.length;
+	return true;
+}
+/** Execute a tool call against the .skilld/ directory */
+function executeTool(toolCall, skilldDir) {
+	const args = toolCall.arguments;
+	switch (toolCall.name) {
+		case "Read": {
+			const filePath = resolveSandboxedPath(args.path, skilldDir);
+			if (!existsSync(filePath)) return `Error: file not found: ${args.path}`;
+			return sanitizeMarkdown(readFileSync(filePath, "utf-8"));
+		}
+		case "Glob": {
+			const pattern = String(args.pattern).replace(/^\.\/\.skilld\//, "./").replace(/^\.skilld\//, "./").replace(/^\.\//, "");
+			const results = [];
+			const walkDir = (dir, prefix) => {
+				if (!existsSync(dir)) return;
+				for (const entry of readdirSync(dir, { withFileTypes: true })) {
+					const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+					if (entry.isDirectory()) walkDir(join(dir, entry.name), relPath);
+					else results.push(`./.skilld/${relPath}`);
+				}
+			};
+			const baseDir = pattern.split("*")[0]?.replace(/\/$/, "") ?? "";
+			walkDir(join(skilldDir, baseDir), baseDir);
+			const matched = results.filter((r) => globMatch(r.replace(/^\.\/\.skilld\//, ""), pattern));
+			return matched.length > 0 ? matched.join("\n") : `No files matching: ${args.pattern}`;
+		}
+		case "Write":
+			writeFileSync(resolveSandboxedPath(args.path, skilldDir), sanitizeMarkdown(String(args.content)));
+			return "File written successfully.";
+		case "Bash": {
+			const cmd = String(args.command).trim();
+			const parts = cmd.split(/\s+/);
+			const bin = parts[0] ?? "";
+			if (!SAFE_COMMANDS.has(bin) || SHELL_META_RE.test(cmd)) return `Error: command not allowed. Only skilld, ls, cat, find commands are permitted.`;
+			try {
+				return execFileSync(bin, parts.slice(1), {
+					cwd: skilldDir,
+					timeout: 15e3,
+					encoding: "utf-8",
+					maxBuffer: 512 * 1024
+				}).trim();
+			} catch (err) {
+				return `Error: ${err.message}`;
 			}
-			break;
 		}
-	} catch {}
-	if (files.length === 0) return "";
-	return `<reference-files>\n${files.map((f) => `<file path="${f.path}">\n${f.content.replaceAll("</file>", "&lt;/file&gt;").replaceAll("</reference-files>", "&lt;/reference-files&gt;")}\n</file>`).join("\n")}\n</reference-files>`;
+		default: return `Unknown tool: ${toolCall.name}`;
+	}
 }
-/** Optimize a single section using pi-ai direct API */
+/** Optimize a single section using pi-ai agentic API with tool use */
 async function optimizeSectionPiAi(opts) {
 	const parsed = parsePiAiModelId(opts.model);
 	if (!parsed) throw new Error(`Invalid pi-ai model ID: ${opts.model}. Expected format: pi:provider/model-id`);
 	const model = getModel(parsed.provider, parsed.modelId);
 	const apiKey = await resolveApiKey(parsed.provider);
-	const portablePrompt = portabilizePrompt(opts.prompt, opts.section);
-	const references = collectReferenceContent(opts.skillDir);
-	const fullPrompt = references ? `${portablePrompt}\n\n## Reference Content\n\nThe following files are provided inline for your reference:\n\n${references}` : portablePrompt;
+	const skilldDir = join(opts.skillDir, ".skilld");
+	const fullPrompt = opts.prompt;
 	opts.onProgress?.({
 		chunk: "[starting...]",
 		type: "reasoning",
@@ -549,53 +594,103 @@ async function optimizeSectionPiAi(opts) {
 		reasoning: "",
 		section: opts.section
 	});
-	const stream = streamSimple(model, {
-		systemPrompt: "You are a technical documentation expert generating SKILL.md sections for AI agent skills. Output clean, structured markdown following the format instructions exactly.",
-		messages: [{
-			role: "user",
-			content: [{
-				type: "text",
-				text: fullPrompt
-			}],
-			timestamp: Date.now()
-		}]
-	}, {
-		reasoning: "medium",
-		maxTokens: 16384,
-		...apiKey ? { apiKey } : {}
-	});
+	const messages = [{
+		role: "user",
+		content: [{
+			type: "text",
+			text: fullPrompt
+		}],
+		timestamp: Date.now()
+	}];
 	let text = "";
-	let usage;
-	let cost;
-	for await (const event of stream) {
+	let completed = false;
+	let totalUsage;
+	let totalCost;
+	let lastWriteContent = "";
+	for (let turn = 0; turn < MAX_TOOL_TURNS; turn++) {
 		if (opts.signal?.aborted) throw new Error("pi-ai request timed out");
-		switch (event.type) {
-			case "text_delta":
-				text += event.delta;
-				opts.onProgress?.({
-					chunk: event.delta,
-					type: "text",
-					text,
-					reasoning: "",
-					section: opts.section
-				});
-				break;
-			case "done":
-				if (event.message?.usage) {
-					usage = {
-						input: event.message.usage.input,
-						output: event.message.usage.output
-					};
-					cost = event.message.usage.cost?.total;
+		const eventStream = streamSimple(model, {
+			systemPrompt: "You are a technical documentation expert generating SKILL.md sections for AI agent skills. Follow the format instructions exactly. Use the provided tools to explore reference files in ./.skilld/ before writing your output.",
+			messages,
+			tools: TOOLS
+		}, {
+			reasoning: turn === 0 ? "medium" : void 0,
+			maxTokens: 16384,
+			...apiKey ? { apiKey } : {}
+		});
+		let assistantMessage;
+		let turnText = "";
+		for await (const event of eventStream) {
+			if (opts.signal?.aborted) throw new Error("pi-ai request timed out");
+			switch (event.type) {
+				case "text_delta":
+					turnText += event.delta;
+					opts.onProgress?.({
+						chunk: event.delta,
+						type: "text",
+						text: turnText,
+						reasoning: "",
+						section: opts.section
+					});
+					break;
+				case "toolcall_end": {
+					const tc = event.toolCall;
+					const hint = tc.name === "Read" || tc.name === "Write" ? `[${tc.name}: ${tc.arguments.path}]` : tc.name === "Bash" ? `[${tc.name}: ${tc.arguments.command}]` : `[${tc.name}: ${tc.arguments.pattern}]`;
+					opts.onProgress?.({
+						chunk: hint,
+						type: "reasoning",
+						text: "",
+						reasoning: hint,
+						section: opts.section
+					});
+					break;
 				}
-				break;
-			case "error": throw new Error(event.error?.errorMessage ?? "pi-ai stream error");
+				case "done":
+					assistantMessage = event.message;
+					break;
+				case "error": throw new Error(event.error?.errorMessage ?? "pi-ai stream error");
+			}
+		}
+		if (!assistantMessage) throw new Error("pi-ai stream ended without a message");
+		if (assistantMessage.usage) {
+			if (totalUsage) {
+				totalUsage.input += assistantMessage.usage.input;
+				totalUsage.output += assistantMessage.usage.output;
+			} else totalUsage = {
+				input: assistantMessage.usage.input,
+				output: assistantMessage.usage.output
+			};
+			totalCost = (totalCost ?? 0) + (assistantMessage.usage.cost?.total ?? 0);
+		}
+		messages.push(assistantMessage);
+		const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");
+		if (toolCalls.length === 0) {
+			text = turnText;
+			completed = true;
+			break;
+		}
+		for (const tc of toolCalls) {
+			const result = executeTool(tc, skilldDir);
+			if (tc.name === "Write") lastWriteContent = String(tc.arguments.content);
+			messages.push({
+				role: "toolResult",
+				toolCallId: tc.id,
+				toolName: tc.name,
+				content: [{
+					type: "text",
+					text: result
+				}],
+				isError: result.startsWith("Error:"),
+				timestamp: Date.now()
+			});
 		}
 	}
+	if (!completed) throw new Error(`pi-ai exceeded ${MAX_TOOL_TURNS} tool turns without completing`);
 	return {
-		text,
-		usage,
-		cost
+		text: text || lastWriteContent,
+		fullPrompt,
+		usage: totalUsage,
+		cost: totalCost
 	};
 }
 //#endregion
@@ -630,16 +725,22 @@ function createToolProgress(log) {
 			log.message(msg);
 		}
 	}
-	return ({ type, chunk, section }) => {
+	return ({ type, chunk, text, section }) => {
 		if (type === "text") {
 			const key = section ?? "";
 			const now = Date.now();
 			if (now - (lastTextEmit.get(key) ?? 0) < TEXT_THROTTLE_MS) return;
 			lastTextEmit.set(key, now);
-			emit(`${section ? `\x1B[90m[${section}]\x1B[0m ` : ""}Writing...`);
+			const prefix = section ? `\x1B[90m[${section}]\x1B[0m ` : "";
+			const items = text ? text.match(/^- (?:BREAKING|DEPRECATED|NEW|CHANGED|REMOVED|Use |Do |Set |Add |Avoid |Always |Never |Prefer |Check |Ensure )/gm)?.length ?? 0 : 0;
+			emit(items > 0 ? `${prefix}Writing... \x1B[90m(${items} items)\x1B[0m` : `${prefix}Writing...`);
 			return;
 		}
 		if (type !== "reasoning" || !chunk.startsWith("[")) return;
+		if (/^\[(?:starting|retrying|cached)/.test(chunk)) {
+			emit(`${section ? `\x1B[90m[${section}]\x1B[0m ` : ""}${chunk.slice(1, -1)}`);
+			return;
+		}
 		const match = chunk.match(/^\[([^:[\]]+)(?::\s(.+))?\]$/);
 		if (!match) return;
 		const names = match[1].split(",").map((n) => n.trim());
@@ -805,6 +906,9 @@ async function optimizeSectionViaPiAi(opts) {
 	const { section, prompt, outputFile, skillDir, model, onProgress, timeout, debug } = opts;
 	const skilldDir = join(skillDir, ".skilld");
 	const outputPath = join(skilldDir, outputFile);
+	const logsDir = join(skilldDir, "logs");
+	const logName = section.toUpperCase().replace(/-/g, "_");
+	if (existsSync(outputPath)) unlinkSync(outputPath);
 	writeFileSync(join(skilldDir, `PROMPT_${section}.md`), prompt);
 	try {
 		const ac = new AbortController();
@@ -819,9 +923,8 @@ async function optimizeSectionViaPiAi(opts) {
 		}).finally(() => clearTimeout(timer));
 		const raw = result.text.trim();
 		if (debug) {
-			const logsDir = join(skilldDir, "logs");
-			const logName = section.toUpperCase().replace(/-/g, "_");
 			mkdirSync(logsDir, { recursive: true });
+			writeFileSync(join(skilldDir, `PROMPT_${section}.md`), result.fullPrompt);
 			if (raw) writeFileSync(join(logsDir, `${logName}.md`), raw);
 		}
 		if (!raw) return {
@@ -846,11 +949,16 @@ async function optimizeSectionViaPiAi(opts) {
 			cost: result.cost
 		};
 	} catch (err) {
+		const errMsg = err.message;
+		if (debug || errMsg) {
+			mkdirSync(logsDir, { recursive: true });
+			writeFileSync(join(logsDir, `${logName}.stderr.log`), errMsg);
+		}
 		return {
 			section,
 			content: "",
 			wasOptimized: false,
-			error: err.message
+			error: errMsg
 		};
 	}
 }
@@ -1141,15 +1249,28 @@ async function optimizeDocs(opts) {
 			prompt
 		});
 	}
-	for (const { section, prompt } of retryQueue) {
-		onProgress?.({
-			chunk: `[${section}: retrying...]`,
-			type: "reasoning",
-			text: "",
-			reasoning: "",
-			section
-		});
-		await setTimeout$1(STAGGER_MS);
+	for (const { index, section, prompt } of retryQueue) {
+		const rateLimitDelay = parseRateLimitDelay(getRetryError(spawnResults[index]));
+		if (rateLimitDelay != null) {
+			const waitSec = Math.max(rateLimitDelay, 5);
+			onProgress?.({
+				chunk: `[${section}] Rate limited, waiting ${waitSec}s...`,
+				type: "reasoning",
+				text: "",
+				reasoning: "",
+				section
+			});
+			await setTimeout$1(waitSec * 1e3);
+		} else {
+			onProgress?.({
+				chunk: `[${section}: retrying...]`,
+				type: "reasoning",
+				text: "",
+				reasoning: "",
+				section
+			});
+			await setTimeout$1(STAGGER_MS);
+		}
 		const result = await optimizeSection({
 			section,
 			prompt,
@@ -1212,6 +1333,22 @@ async function optimizeDocs(opts) {
 		debugLogsDir
 	};
 }
+/** Check if an error string indicates a rate limit (429) */
+function isRateLimitError(error) {
+	if (!error) return false;
+	return /\b429\b/.test(error) || /rate.?limit/i.test(error) || /exhausted.*capacity/i.test(error) || /quota.*reset/i.test(error);
+}
+/** Parse delay hint from rate limit error (e.g. "reset after 5s" → 5). Returns undefined if not a rate limit. */
+function parseRateLimitDelay(error) {
+	if (!error || !isRateLimitError(error)) return void 0;
+	const match = error.match(/reset\s+after\s+(\d+)s/i);
+	return match ? Number(match[1]) : 10;
+}
+/** Extract error string from a PromiseSettledResult */
+function getRetryError(result) {
+	if (result.status === "rejected") return String(result.reason);
+	return result.value.error;
+}
 /** Shorten absolute paths for display: /home/user/project/.claude/skills/vue/SKILL.md → .claude/.../SKILL.md */
 function shortenPath(p) {
 	const refIdx = p.indexOf(".skilld/");
@@ -1243,10 +1380,7 @@ function cleanSectionOutput(content) {
 		else cleaned = cleaned.slice(afterOpen).trim();
 	}
 	const firstMarker = cleaned.match(/^(##\s|- (?:BREAKING|DEPRECATED|NEW): )/m);
-	if (firstMarker?.index && firstMarker.index > 0) {
-		const preamble = cleaned.slice(0, firstMarker.index);
-		if (/\b(?:function|const |let |var |export |return |import |async |class )\b/.test(preamble)) cleaned = cleaned.slice(firstMarker.index).trim();
-	}
+	if (firstMarker?.index && firstMarker.index > 0) cleaned = cleaned.slice(firstMarker.index).trim();
 	const headingMatch = cleaned.match(/^(## .+)\n/);
 	if (headingMatch) {
 		const heading = headingMatch[1];