@kodrunhq/opencode-autopilot 1.4.0 → 1.6.0

package/src/tools/stocktake.ts

@@ -0,0 +1,170 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tool } from "@opencode-ai/plugin";
+import { lintAgent, lintCommand, lintSkill } from "../skills/linter";
+import { getAssetsDir, getGlobalConfigDir } from "../utils/paths";
+
+interface StocktakeArgs {
+	readonly lint?: boolean;
+}
+
+interface AssetEntry {
+	readonly name: string;
+	readonly type: "skill" | "command" | "agent";
+	readonly origin: "built-in" | "user-created";
+	readonly lint?: {
+		readonly valid: boolean;
+		readonly errors: readonly string[];
+		readonly warnings: readonly string[];
+	};
+}
+
+/** Read directory entries safely, returning empty array on ENOENT only. */
+async function safeReaddir(dirPath: string): Promise<string[]> {
+	try {
+		return await readdir(dirPath);
+	} catch (error: unknown) {
+		const errObj = error as { code?: unknown };
+		if (errObj?.code === "ENOENT") return [];
+		throw error;
+	}
+}
+
+/** Cache for built-in asset lookups (keyed by assetType). */
+const builtInCache = new Map<string, ReadonlySet<string>>();
+
+/** Check if an asset name exists in the bundled assets directory. */
+async function isBuiltIn(assetType: string, name: string): Promise<boolean> {
+	let cached = builtInCache.get(assetType);
+	if (!cached) {
+		const assetsDir = getAssetsDir();
+		const entries = await safeReaddir(join(assetsDir, assetType));
+		cached = new Set(entries);
+		builtInCache.set(assetType, cached);
+	}
+	return cached.has(name);
+}
+
+export async function stocktakeCore(args: StocktakeArgs, baseDir: string): Promise<string> {
+	const shouldLint = args.lint !== false;
+	const skills: AssetEntry[] = [];
+	const commands: AssetEntry[] = [];
+	const agents: AssetEntry[] = [];
+
+	// Scan skills (each subdirectory is a skill) — filter to directories only
+	const skillEntries = await readdir(join(baseDir, "skills"), { withFileTypes: true }).catch(
+		() => [],
+	);
+	const skillDirs = skillEntries
+		.filter((e) => e.isDirectory() && e.name !== ".gitkeep")
+		.map((e) => e.name);
+	for (const name of skillDirs) {
+		const skillFile = join(baseDir, "skills", name, "SKILL.md");
+		const origin = (await isBuiltIn("skills", name)) ? "built-in" : "user-created";
+		const entry: AssetEntry = { name, type: "skill", origin };
+
+		if (shouldLint) {
+			try {
+				const content = await readFile(skillFile, "utf-8");
+				const lint = lintSkill(content);
+				skills.push({ ...entry, lint });
+			} catch {
+				skills.push({
+					...entry,
+					lint: { valid: false, errors: ["Could not read SKILL.md"], warnings: [] },
+				});
+			}
+		} else {
+			skills.push(entry);
+		}
+	}
+
+	// Scan commands (.md files)
+	const commandFiles = await safeReaddir(join(baseDir, "commands"));
+	for (const file of commandFiles.filter((f) => f.endsWith(".md"))) {
+		const name = file.replace(/\.md$/, "");
+		const origin = (await isBuiltIn("commands", file)) ? "built-in" : "user-created";
+		const entry: AssetEntry = { name, type: "command", origin };
+
+		if (shouldLint) {
+			try {
+				const content = await readFile(join(baseDir, "commands", file), "utf-8");
+				const lint = lintCommand(content);
+				commands.push({ ...entry, lint });
+			} catch {
+				commands.push({
+					...entry,
+					lint: { valid: false, errors: ["Could not read command file"], warnings: [] },
+				});
+			}
+		} else {
+			commands.push(entry);
+		}
+	}
+
+	// Scan agents (.md files)
+	const agentFiles = await safeReaddir(join(baseDir, "agents"));
+	for (const file of agentFiles.filter((f) => f.endsWith(".md"))) {
+		const name = file.replace(/\.md$/, "");
+		const origin = (await isBuiltIn("agents", file)) ? "built-in" : "user-created";
+		const entry: AssetEntry = { name, type: "agent", origin };
+
+		if (shouldLint) {
+			try {
+				const content = await readFile(join(baseDir, "agents", file), "utf-8");
+				const lint = lintAgent(content);
+				agents.push({ ...entry, lint });
+			} catch {
+				agents.push({
+					...entry,
+					lint: { valid: false, errors: ["Could not read agent file"], warnings: [] },
+				});
+			}
+		} else {
+			agents.push(entry);
+		}
+	}
+
+	// Compute summary
+	const allAssets = [...skills, ...commands, ...agents];
+	const builtIn = allAssets.filter((a) => a.origin === "built-in").length;
+	const userCreated = allAssets.filter((a) => a.origin === "user-created").length;
+	const lintErrors = shouldLint
+		? allAssets.reduce((sum, a) => sum + (a.lint?.errors.length ?? 0), 0)
+		: 0;
+	const lintWarnings = shouldLint
+		? allAssets.reduce((sum, a) => sum + (a.lint?.warnings.length ?? 0), 0)
+		: 0;
+
+	return JSON.stringify(
+		{
+			skills,
+			commands,
+			agents,
+			summary: {
+				total: allAssets.length,
+				builtIn,
+				userCreated,
+				lintErrors,
+				lintWarnings,
+			},
+		},
+		null,
+		2,
+	);
+}
+
+export const ocStocktake = tool({
+	description:
+		"Audit all installed skills, commands, and agents with optional YAML frontmatter lint validation.",
+	args: {
+		lint: tool.schema
+			.boolean()
+			.optional()
+			.default(true)
+			.describe("Run YAML frontmatter linter on all assets"),
+	},
+	async execute(args) {
+		return stocktakeCore(args, getGlobalConfigDir());
+	},
+});

package/src/tools/update-docs.ts

@@ -0,0 +1,116 @@
+import { execFile as execFileCb } from "node:child_process";
+import { basename } from "node:path";
+import { promisify } from "node:util";
+import { tool } from "@opencode-ai/plugin";
+
+const execFile = promisify(execFileCb);
+
+interface UpdateDocsArgs {
+	readonly scope?: string;
+}
+
+interface AffectedDoc {
+	readonly doc: string;
+	readonly reason: string;
+	readonly suggestion: string;
+}
+
+/** Run a git command and return stdout lines (empty array on error). */
+async function gitLines(args: readonly string[], cwd: string): Promise<readonly string[]> {
+	try {
+		const { stdout } = await execFile("git", [...args], { cwd });
+		return stdout
+			.trim()
+			.split("\n")
+			.filter((line) => line.length > 0);
+	} catch {
+		return [];
+	}
+}
+
+export async function updateDocsCore(args: UpdateDocsArgs, projectDir: string): Promise<string> {
+	const scope = args.scope ?? "changed";
+
+	// Get changed source files
+	const changedFiles: readonly string[] =
+		scope === "all"
+			? await gitLines(["ls-files"], projectDir)
+			: await gitLines(["diff", "--name-only", "HEAD"], projectDir);
+
+	// Get all markdown files in the project
+	const mdFiles = await gitLines(["ls-files", "*.md"], projectDir);
+
+	// For each changed source file, check if any markdown file references it
+	const affectedDocs: AffectedDoc[] = [];
+	const seenDocs = new Set<string>();
+
+	for (const changedFile of changedFiles) {
+		// Skip markdown files themselves
+		if (changedFile.endsWith(".md")) continue;
+
+		const fileBaseName = basename(changedFile);
+		// Strip extension for module-style references
+		const moduleName = fileBaseName.replace(/\.[^.]+$/, "");
+
+		for (const mdFile of mdFiles) {
+			if (seenDocs.has(`${mdFile}:${changedFile}`)) continue;
+
+			// Simple heuristic: check if the markdown file path suggests it documents this area
+			// or if the changed file's name/module appears in common documentation patterns
+			const mdBaseName = basename(mdFile).replace(/\.md$/, "").toLowerCase();
+			const changedDir = changedFile.split("/").slice(0, -1).join("/");
+
+			const isRelated =
+				mdBaseName === "readme" ||
+				mdBaseName === moduleName.toLowerCase() ||
+				(changedDir.length > 0 && mdFile.toLowerCase().includes(changedDir.toLowerCase()));
+
+			if (isRelated) {
+				seenDocs.add(`${mdFile}:${changedFile}`);
+				affectedDocs.push({
+					doc: mdFile,
+					reason: `may be related to ${changedFile} (heuristic: path/name match)`,
+					suggestion: `Review ${mdFile} — it may need updates to reflect changes to ${changedFile}`,
+				});
+			}
+		}
+	}
+
+	// Deduplicate by doc path
+	const uniqueDocs = Array.from(
+		affectedDocs
+			.reduce((map, item) => {
+				if (!map.has(item.doc)) {
+					map.set(item.doc, item);
+				}
+				return map;
+			}, new Map<string, AffectedDoc>())
+			.values(),
+	);
+
+	const nonMdChanged = changedFiles.filter((f) => !f.endsWith(".md"));
+
+	return JSON.stringify(
+		{
+			changedFiles: nonMdChanged,
+			affectedDocs: uniqueDocs,
+			summary: `${nonMdChanged.length} source files changed, ${uniqueDocs.length} docs may need updates`,
+		},
+		null,
+		2,
+	);
+}
+
+export const ocUpdateDocs = tool({
+	description: "Detect documentation affected by recent code changes and suggest updates.",
+	args: {
+		scope: tool.schema
+			.enum(["changed", "all"])
+			.optional()
+			.default("changed")
+			.describe("Scope: 'changed' for git diff, 'all' for full scan"),
+	},
+	async execute(args) {
+		return updateDocsCore(args, process.cwd());
+	},
+});