@happyvertical/smrt-cli 0.45.0 → 0.45.2

package/AGENTS.md

@@ -271,7 +271,7 @@ sessions/magic-link tokens/CLI-auth requests from `smrt-users`).
 - `src/commands/` — individual command implementations
 - `src/loaders/` — class-loader, local-loader, npm-loader, git-loader, template-loader
 - `src/discovery/manifest-discovery.ts` — manifest auto-discovery
-- `src/commands/docs-claude.ts` — downstream AGENTS.md generation plus Claude compatibility alias
+- `src/commands/docs-claude.ts` — downstream AGENTS.md generation plus Claude compatibility alias; uses core knowledge discovery without object scanning
 
 ## Gotchas
 

package/README.md

@@ -140,6 +140,18 @@ layout that means declaring them, not relying on the CLI's own dependencies.
 | `smrt knowledge:review-context --scope project\|local\|package\|sdk\|installed --package <name> --format markdown\|json` | Build a model-ready domain review prompt bundle |
 | `smrt knowledge:architecture-context --scope project\|local\|package\|sdk\|installed --package <name> --format markdown\|json` | Build a model-ready domain architecture prompt bundle |
 
+`docs:agents` includes package AGENTS guidance and lists linked module files by
+source path; it does not read or embed their bodies. Use
+`smrt docs:agents --complete` for a complete authored reference. The deprecated `docs:claude`
+alias supports the same flag and retains its historical output path.
+Regenerate snapshots after moving the project or updating dependencies so the
+local source paths remain current.
+
+Review and architecture prompt bundles include package guidance and modules
+matched by file or focus hints. Add `--complete` to either context command to
+include every module for the selected packages. These commands still build the
+knowledge index; documentation snapshots use lightweight package discovery.
+
 ### Configuration
 
 | Command | Description |

package/dist/{commands-DBnnqrFy.js → commands-COd77prj.js}

@@ -1,7 +1,7 @@
 import { t as resolveManifestEntryPackageName } from "./index.js";
 import { createRequire } from "node:module";
 import * as fs from "node:fs";
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import * as path from "node:path";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -12,7 +12,7 @@ import { createLogger } from "@happyvertical/logger";
 import glob from "fast-glob";
 import { createHash } from "node:crypto";
 import { toSnakeCase } from "@happyvertical/smrt-core/utils";
-import { readAgentModuleDocs } from "@happyvertical/smrt-core/knowledge";
+import { discoverScopedPackageDirectories, readAgentModuleDocs, readPackageAgentDoc, resolveAgentModuleDocPaths } from "@happyvertical/smrt-core/knowledge";
 import { MCPGenerator } from "@happyvertical/smrt-core/generators";
 import { generateDeclarationsFromCLI } from "@happyvertical/smrt-core/prebuild";
 import { execFileSync, execSync, spawn, spawnSync } from "node:child_process";
@@ -21,7 +21,7 @@ import { homedir, tmpdir } from "node:os";
 import { extract } from "tar";
 import { importWorkspaceModule } from "@happyvertical/smrt-core/utils/import-workspace-module";
 import { buildIntegerWidthTableStatements, collectIntegerWidthTargets, parsePostgresTimeoutMs, preflightIntegerWidthWidening, widenIntegerColumnsToBigInt } from "@happyvertical/smrt-core/migrations";
-import { buildArchitectureContext, buildKnowledgeIndex, buildReviewContext, checkKnowledgeFreshness, diffKnowledgeIndex, renderFreshnessResult, renderKnowledgeIndexMarkdown } from "@happyvertical/smrt-dev-mcp/knowledge";
+import { buildArchitectureContext, buildKnowledgeIndex, buildReviewContext, checkKnowledgeFreshness, compactContextResult, diffKnowledgeIndex, renderFreshnessResult, renderKnowledgeIndexMarkdown } from "@happyvertical/smrt-dev-mcp/knowledge";
 //#region src/commands/db-command-utils.ts
 var SENSITIVE_QUERY_PARAMS = /* @__PURE__ */ new Set([
 	"access_token",
@@ -3183,6 +3183,11 @@ function createDocsCommand(config) {
 				description: `Output file path (default: ${config.defaultOutput})`,
 				short: "o"
 			},
+			complete: {
+				type: "boolean",
+				description: "Include every linked module document in the snapshot",
+				default: false
+			},
 			"dry-run": {
 				type: "boolean",
 				description: "Print to stdout without writing file",
@@ -3197,14 +3202,15 @@ function createDocsCommand(config) {
 				const dryRun = options["dry-run"];
 				const monorepoRoot = detectMonorepoRoot();
 				const rootDocs = monorepoRoot ? loadRootDocs(monorepoRoot) : [];
-				const packages = await discoverInstalledPackages();
-				const sdkPackages = await discoverSdkPackages();
+				const installedDirectories = discoverScopedPackageDirectories([join(process.cwd(), "node_modules", "@happyvertical")]);
+				const packages = await discoverInstalledPackages(installedDirectories, options.complete);
+				const sdkPackages = discoverSdkPackages(installedDirectories, options.complete);
 				if (packages.length === 0 && sdkPackages.length === 0) {
 					console.log("\n⚠️  No @happyvertical packages found in node_modules");
 					console.log("   Make sure packages are installed before running this command.\n");
 					process.exit(1);
 				}
-				const content = generateMarkdown(packages, rootDocs.length > 0 ? rootDocs : void 0, sdkPackages.length > 0 ? sdkPackages : void 0, config.generatedBy);
+				const content = generateMarkdown(packages, rootDocs.length > 0 ? rootDocs : void 0, sdkPackages.length > 0 ? sdkPackages : void 0, config.generatedBy, { complete: options.complete });
 				if (dryRun) {
 					console.log(content);
 					return;
@@ -3220,7 +3226,7 @@ function createDocsCommand(config) {
 				const allPackages = [...packages, ...sdkPackages];
 				const withAgentDocs = allPackages.filter((p) => p.agentMd).length;
 				if (withAgentDocs > 0) console.log(`   ${withAgentDocs} with AGENTS.md`);
-				const moduleDocCount = allPackages.reduce((total, p) => total + (p.moduleDocs?.length ?? 0), 0);
+				const moduleDocCount = allPackages.reduce((total, p) => total + (p.moduleDocPaths?.length ?? p.moduleDocs?.length ?? 0), 0);
 				if (moduleDocCount > 0) console.log(`   ${moduleDocCount} linked module docs`);
 				if (rootDocs.length > 0) console.log(`   ${rootDocs.length} framework documents included`);
 				console.log("");
@@ -3249,22 +3255,13 @@ var docsClaudeCommand = createDocsCommand({
 * Discover installed @happyvertical/smrt-* packages.
 * Checks both node_modules and workspace packages directory.
 */
-async function discoverInstalledPackages() {
+async function discoverInstalledPackages(installedDirectories, complete = false) {
 	const packages = [];
 	const { readdirSync } = await import("node:fs");
-	const nodeModulesPath = join(process.cwd(), "node_modules", "@happyvertical");
-	if (existsSync(nodeModulesPath)) {
-		const entries = readdirSync(nodeModulesPath, { withFileTypes: true });
-		for (const entry of entries) {
-			if (!entry.name.startsWith("smrt-")) continue;
-			const entryPath = join(nodeModulesPath, entry.name);
-			let packagePath = entryPath;
-			try {
-				if (lstatSync(entryPath).isSymbolicLink()) packagePath = realpathSync(entryPath);
-			} catch {}
-			const pkg = loadPackageInfo(packagePath, entry.name);
-			if (pkg) packages.push(pkg);
-		}
+	for (const entry of installedDirectories) {
+		if (!entry.name.startsWith("smrt-")) continue;
+		const pkg = loadPackageInfo(entry.realDirectory, entry.name, complete);
+		if (pkg) packages.push(pkg);
 	}
 	if (packages.length === 0) {
 		const workspacePath = join(process.cwd(), "packages");
@@ -3278,7 +3275,7 @@ async function discoverInstalledPackages() {
 				if (!existsSync(packageJsonPath)) continue;
 				try {
 					if (!JSON.parse(readFileSync(packageJsonPath, "utf-8")).name?.startsWith("@happyvertical/smrt-")) continue;
-					const pkg = loadPackageInfo(packagePath, entry.name);
+					const pkg = loadPackageInfo(packagePath, entry.name, complete);
 					if (pkg) packages.push(pkg);
 				} catch {}
 			}
@@ -3289,32 +3286,22 @@ async function discoverInstalledPackages() {
 /**
 * Discover installed @happyvertical/* SDK packages (non-smrt).
 */
-async function discoverSdkPackages() {
+function discoverSdkPackages(installedDirectories, complete = false) {
 	const packages = [];
-	const { readdirSync } = await import("node:fs");
-	const nodeModulesPath = join(process.cwd(), "node_modules", "@happyvertical");
-	if (!existsSync(nodeModulesPath)) return packages;
-	const entries = readdirSync(nodeModulesPath, { withFileTypes: true });
-	for (const entry of entries) {
-		if (entry.name.startsWith("smrt-")) continue;
-		if (entry.name === "smrt") continue;
-		const entryPath = join(nodeModulesPath, entry.name);
-		let packagePath = entryPath;
-		try {
-			if (lstatSync(entryPath).isSymbolicLink()) packagePath = realpathSync(entryPath);
-		} catch {}
-		const pkg = loadPackageInfo(packagePath, entry.name);
+	for (const entry of installedDirectories) {
+		if (entry.name.startsWith("smrt-") || entry.name === "smrt") continue;
+		const pkg = loadPackageInfo(entry.realDirectory, entry.name, complete);
 		if (pkg) packages.push(pkg);
 	}
 	return packages.sort((a, b) => a.name.localeCompare(b.name));
 }
-function loadPackageInfo(packagePath, dirName) {
+function loadPackageInfo(packagePath, dirName, complete) {
 	const packageJsonPath = join(packagePath, "package.json");
 	if (!existsSync(packageJsonPath)) return null;
 	try {
 		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
 		const readmePath = join(packagePath, "README.md");
-		const agentDoc = loadAgentDoc(join(packagePath, "AGENTS.md"), join(packagePath, "CLAUDE.md"));
+		const agentDoc = readPackageAgentDoc(packagePath);
 		return {
 			name: packageJson.name,
 			version: packageJson.version,
@@ -3322,32 +3309,15 @@ function loadPackageInfo(packagePath, dirName) {
 			agentMd: agentDoc.content,
 			claudeMd: agentDoc.content,
 			docSource: agentDoc.source,
-			moduleDocs: agentDoc.source === "AGENTS.md" ? readAgentModuleDocs(packagePath, agentDoc.content ?? void 0) : []
+			directory: packagePath,
+			moduleDocPaths: agentDoc.source === "AGENTS.md" ? resolveAgentModuleDocPaths(packagePath, agentDoc.content ?? void 0) : [],
+			moduleDocs: complete && agentDoc.source === "AGENTS.md" ? readAgentModuleDocs(packagePath, agentDoc.content ?? void 0) : []
 		};
 	} catch {
 		console.warn(`   ⚠️  Could not read package.json for ${dirName}`);
 		return null;
 	}
 }
-function loadAgentDoc(agentsPath, claudePath) {
-	if (existsSync(agentsPath)) return {
-		content: readFileSync(agentsPath, "utf-8"),
-		source: "AGENTS.md"
-	};
-	if (!existsSync(claudePath)) return {
-		content: null,
-		source: null
-	};
-	const claude = readFileSync(claudePath, "utf-8");
-	if (claude.trim() === "@AGENTS.md") return {
-		content: null,
-		source: null
-	};
-	return {
-		content: claude,
-		source: "CLAUDE.md"
-	};
-}
 function detectMonorepoRoot() {
 	try {
 		let currentDir = realpathSync(process.cwd());
@@ -3401,28 +3371,27 @@ function renderAgentMd(content) {
 	if (h1Match) content = content.slice(h1Match[0].length);
 	return content.trim();
 }
-/**
-* The package's AGENTS.md followed by every module doc it links (#2108).
-* The links stay in the rendered text so a reader can still map a section back
-* to its source path; the bodies follow so nothing is lost downstream.
-*/
-function renderPackageDoc(pkg, lines) {
+/** Keep package orientation inline; load module bodies only on explicit request. */
+function renderPackageDoc(pkg, lines, complete) {
 	const content = pkg.agentMd ?? pkg.claudeMd;
 	if (!content) {
-		lines.push("*No AGENTS.md found for this package.*");
-		lines.push("");
+		lines.push("*No AGENTS.md found for this package.*", "");
 		return;
 	}
-	lines.push(renderAgentMd(content));
-	lines.push("");
-	for (const doc of pkg.moduleDocs ?? []) {
-		lines.push(`#### ${doc.path}`);
-		lines.push("");
-		lines.push(renderAgentMd(doc.content));
+	lines.push(renderAgentMd(content), "");
+	const paths = pkg.moduleDocPaths ?? pkg.moduleDocs?.map((doc) => doc.path) ?? [];
+	if (!complete && paths.length > 0) {
+		lines.push("#### Module documentation", "");
+		lines.push("Read the relevant source file on demand, or regenerate with `--complete`.", "");
+		for (const path of paths) {
+			const source = (pkg.directory ? join(pkg.directory, path) : path).replace(/\\/g, "/");
+			lines.push(`- [${path}](<${source}>)`);
+		}
 		lines.push("");
 	}
+	if (complete) for (const doc of pkg.moduleDocs ?? []) lines.push(`#### ${doc.path}`, "", renderAgentMd(doc.content), "");
 }
-function generateMarkdown(packages, rootDocs, sdkPackages, generatedBy = "smrt docs:agents") {
+function generateMarkdown(packages, rootDocs, sdkPackages, generatedBy = "smrt docs:agents", options = {}) {
 	const lines = [];
 	lines.push("# SMRT Framework Context");
 	lines.push("");
@@ -3465,7 +3434,7 @@ function generateMarkdown(packages, rootDocs, sdkPackages, generatedBy = "smrt d
 		lines.push("");
 		lines.push(`## ${pkg.name}`);
 		lines.push("");
-		renderPackageDoc(pkg, lines);
+		renderPackageDoc(pkg, lines, options.complete === true);
 	}
 	if (sdkPackages && sdkPackages.length > 0) {
 		lines.push("---");
@@ -3477,7 +3446,7 @@ function generateMarkdown(packages, rootDocs, sdkPackages, generatedBy = "smrt d
 			lines.push("");
 			lines.push(`### ${pkg.name}`);
 			lines.push("");
-			renderPackageDoc(pkg, lines);
+			renderPackageDoc(pkg, lines, options.complete === true);
 		}
 	}
 	lines.push("---");
@@ -3494,7 +3463,7 @@ function generateMarkdown(packages, rootDocs, sdkPackages, generatedBy = "smrt d
 	lines.push("- Example code if applicable");
 	lines.push("");
 	lines.push("---");
-	lines.push(`*Generated by \`${generatedBy}\` — regenerate after dependency updates*`);
+	lines.push(`*Generated by \`${generatedBy}${options.complete ? " --complete" : ""}\` — regenerate after dependency updates*`);
 	lines.push("");
 	return lines.join("\n");
 }
@@ -6836,10 +6805,10 @@ var devKnowledgeCommands = {
 				focus: args.join(" ") || options.focus,
 				scope: options.scope,
 				package: options.package,
-				detail: "full"
+				detail: options.complete ? "complete" : "full"
 			});
 			if ((options.json ? "json" : options.format) === "json") {
-				console.log(JSON.stringify(result, null, 2));
+				console.log(JSON.stringify(compactContextResult(result, options.complete ? "complete" : "full"), null, 2));
 				return;
 			}
 			console.log(renderContextMarkdown(result));
@@ -6857,10 +6826,10 @@ var devKnowledgeCommands = {
 				focus: options.focus,
 				scope: options.scope,
 				package: options.package,
-				detail: "full"
+				detail: options.complete ? "complete" : "full"
 			});
 			if ((options.json ? "json" : options.format) === "json") {
-				console.log(JSON.stringify(result, null, 2));
+				console.log(JSON.stringify(compactContextResult(result, options.complete ? "complete" : "full"), null, 2));
 				return;
 			}
 			console.log(renderContextMarkdown(result));
@@ -6869,6 +6838,11 @@ var devKnowledgeCommands = {
 };
 function contextOptions(defaultFormat) {
 	return {
+		complete: {
+			type: "boolean",
+			description: "Include all module documentation for selected packages",
+			default: false
+		},
 		format: {
 			type: "string",
 			description: "Output format: markdown or json",

package/dist/index.js

@@ -49,63 +49,63 @@ var _playgroundCommands = null;
 var _workbenchCommands = null;
 async function getGnodeCommands() {
 	if (!_gnodeCommands) {
-		const { gnodeCommands } = await import("./commands-DBnnqrFy.js");
+		const { gnodeCommands } = await import("./commands-COd77prj.js");
 		_gnodeCommands = gnodeCommands;
 	}
 	return _gnodeCommands;
 }
 async function getGitCommands() {
 	if (!_gitCommands) {
-		const { gitCommands } = await import("./commands-DBnnqrFy.js");
+		const { gitCommands } = await import("./commands-COd77prj.js");
 		_gitCommands = gitCommands;
 	}
 	return _gitCommands;
 }
 async function getGenerateCommands() {
 	if (!_generateCommands) {
-		const { generateCommands } = await import("./commands-DBnnqrFy.js");
+		const { generateCommands } = await import("./commands-COd77prj.js");
 		_generateCommands = generateCommands;
 	}
 	return _generateCommands;
 }
 async function getInitCommands() {
 	if (!_initCommands) {
-		const { initCommands } = await import("./commands-DBnnqrFy.js");
+		const { initCommands } = await import("./commands-COd77prj.js");
 		_initCommands = initCommands;
 	}
 	return _initCommands;
 }
 async function getUtilityCommands() {
 	if (!_utilityCommands) {
-		const { utilityCommands } = await import("./commands-DBnnqrFy.js");
+		const { utilityCommands } = await import("./commands-COd77prj.js");
 		_utilityCommands = utilityCommands;
 	}
 	return _utilityCommands;
 }
 async function getDispatchCommands() {
 	if (!_dispatchCommands) {
-		const { dispatchCommands } = await import("./commands-DBnnqrFy.js");
+		const { dispatchCommands } = await import("./commands-COd77prj.js");
 		_dispatchCommands = dispatchCommands;
 	}
 	return _dispatchCommands;
 }
 async function getDocsCommands() {
 	if (!_docsCommands) {
-		const { docsCommands } = await import("./commands-DBnnqrFy.js");
+		const { docsCommands } = await import("./commands-COd77prj.js");
 		_docsCommands = docsCommands;
 	}
 	return _docsCommands;
 }
 async function getPlaygroundCommands() {
 	if (!_playgroundCommands) {
-		const { playgroundCommands } = await import("./commands-DBnnqrFy.js");
+		const { playgroundCommands } = await import("./commands-COd77prj.js");
 		_playgroundCommands = playgroundCommands;
 	}
 	return _playgroundCommands;
 }
 async function getWorkbenchCommands() {
 	if (!_workbenchCommands) {
-		const { workbenchCommands } = await import("./commands-DBnnqrFy.js");
+		const { workbenchCommands } = await import("./commands-COd77prj.js");
 		_workbenchCommands = workbenchCommands;
 	}
 	return _workbenchCommands;
@@ -959,7 +959,7 @@ var CLIGenerator = class {
 							const methods = await ObjectRegistry.getAllMethods(objKey);
 							const methodNames = Array.from(methods.keys());
 							if (typeof cliConfig === "object" && cliConfig.include) cliMethods = methodNames.filter((m) => cliConfig.include?.includes(m) && methods.get(m)?.isPublic);
-							else if (cliConfig === true) cliMethods = methodNames.filter((m) => methods.get(m)?.isPublic);
+							else cliMethods = methodNames.filter((m) => methods.get(m)?.isPublic);
 						}
 						if (options.verbose) {
 							console.log(`    • ${objName}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-cli",
-  "version": "0.45.0",
+  "version": "0.45.2",
   "description": "Developer CLI for SMRT framework - introspection, testing, and project management",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,12 +32,12 @@
     "acorn": "^8.17.0",
     "fast-glob": "3.3.3",
     "tar": "^7.5.19",
-    "@happyvertical/smrt-dev-mcp": "0.45.0",
-    "@happyvertical/smrt-config": "0.45.0",
-    "@happyvertical/smrt-core": "0.45.0",
-    "@happyvertical/smrt-playground": "0.45.0",
-    "@happyvertical/smrt-types": "0.45.0",
-    "@happyvertical/smrt-agents": "0.45.0"
+    "@happyvertical/smrt-agents": "0.45.2",
+    "@happyvertical/smrt-config": "0.45.2",
+    "@happyvertical/smrt-core": "0.45.2",
+    "@happyvertical/smrt-playground": "0.45.2",
+    "@happyvertical/smrt-dev-mcp": "0.45.2",
+    "@happyvertical/smrt-types": "0.45.2"
   },
   "devDependencies": {
     "@types/node": "24.13.2",