agentplugged 1.3.0 → 2.0.0

package/dist/project-command.js

@@ -0,0 +1,776 @@
+import { Vs as ErrorCode } from "./hash.js";
+import { B as AgentPluggedError, C as nameWords, F as PROFILE_PATH, I as acceptanceText, L as parseKept, P as ACCEPTANCE_PLACES, R as renderProfile, _ as findBricks, d as bricksOfMap, r as loadCodeMap, v as matchingSources, x as stem, y as searchWords, z as withSource } from "./map-cache.js";
+// ../../packages/core/dist/project-profile/repo-map.js
+/**
+* The map of a repository for one piece of work: the files that matter for a request, each with the
+* symbols it exports (functions, classes, types) and their signatures, within a budget of tokens.
+* It replaces the wide reads an agent makes to find its way. Pure and deterministic: the same
+* bricks and the same request always give the same text, and the text never exceeds the budget.
+*
+* Files are ranked the way a reader would: the files the request names come first, then those whose
+* path or symbols carry its words (a word that is everywhere weighs little), and the files the rest
+* of the code leans on break ties and fill what is left.
+*/
+/** Tokens the map takes by default, and the most a caller may ask. */
+const MAP_TOKENS = 1500;
+const MAP_MAX_TOKENS = 3e3;
+/** Characters per token assumed: low on purpose, code is dense, so the real count stays under. */
+const CHARS_PER_TOKEN = 3;
+/** Most symbols of one file, and of a file chosen only for its place in the code. */
+const SYMBOLS_PER_FILE = 10;
+const SYMBOLS_PER_FILLER = 3;
+/** The share of the budget the files unrelated to the request may take. */
+const FILLER_SHARE = .25;
+/** The words of a request read at most. */
+const REQUEST_CHARS = 8e3;
+const REQUEST_WORDS = 300;
+/** The tokens a text takes, estimated (never fewer than the real count for code). */
+function mapTokens(text) {
+	return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+const HEADER = "Repo map (files by relevance; line: exported declaration)";
+/** The words of a request: its identifiers split, folded to roots, each once. */
+function requestStems(request) {
+	const words = request.slice(0, REQUEST_CHARS).match(/[A-Za-z][A-Za-z0-9_$]{2,}/g) ?? [];
+	return [...new Set(searchWords(words.slice(0, REQUEST_WORDS * 4)))].slice(0, REQUEST_WORDS);
+}
+function candidatesOf(bricks, request) {
+	const byFile = /* @__PURE__ */ new Map();
+	for (const brick of bricks) {
+		if (!brick.exported) continue;
+		const list = byFile.get(brick.path);
+		if (list === void 0) byFile.set(brick.path, [brick]);
+		else list.push(brick);
+	}
+	const wanted = requestStems(request);
+	const stems = /* @__PURE__ */ new Map();
+	const spread = /* @__PURE__ */ new Map();
+	for (const [path, list] of byFile) {
+		const inPath = new Set(nameWords(path).map(stem));
+		const names = /* @__PURE__ */ new Map();
+		const all = new Set(inPath);
+		for (const brick of list) {
+			const own = new Set(nameWords(brick.name).map(stem));
+			names.set(brick, own);
+			for (const word of own) all.add(word);
+		}
+		stems.set(path, {
+			path: inPath,
+			names
+		});
+		for (const word of all) spread.set(word, (spread.get(word) ?? 0) + 1);
+	}
+	const total = Math.max(1, byFile.size);
+	const weight = (word) => Math.log(1 + total / (spread.get(word) ?? total));
+	const out = [];
+	const sameName = /* @__PURE__ */ new Map();
+	for (const path of byFile.keys()) {
+		const name = path.split("/").at(-1) ?? path;
+		sameName.set(name, (sameName.get(name) ?? 0) + 1);
+	}
+	for (const [path, list] of byFile) {
+		const known = stems.get(path);
+		let relevance = 0;
+		const matched = /* @__PURE__ */ new Map();
+		for (const word of wanted) {
+			if (known.path.has(word)) relevance += 2 * weight(word);
+			let named = false;
+			for (const [brick, own] of known.names) {
+				if (!own.has(word)) continue;
+				named = true;
+				matched.set(brick, (matched.get(brick) ?? 0) + weight(word));
+			}
+			if (named) relevance += 3 * weight(word);
+		}
+		const base = path.split("/").at(-1) ?? path;
+		const mentioned = request.includes(path) ? 12 : base.length >= 6 && sameName.get(base) === 1 && request.includes(base) ? 6 : 0;
+		const leaned = list.reduce((sum, brick) => sum + brick.refs, 0);
+		out.push({
+			path,
+			bricks: list,
+			relevance,
+			mentioned,
+			centrality: Math.log(1 + leaned),
+			matched
+		});
+	}
+	return out;
+}
+const scoreOf = (c) => c.relevance + c.mentioned + .3 * c.centrality;
+const byRank = (a, b) => scoreOf(b) - scoreOf(a) || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+/** The symbols of a file worth showing, best first: those the request names, then those most used. */
+function symbolsOf(candidate, cap) {
+	return [...candidate.bricks].sort((a, b) => (candidate.matched.get(b) ?? 0) - (candidate.matched.get(a) ?? 0) || b.refs - a.refs || a.line - b.line).slice(0, cap);
+}
+const lineOf = (brick) => `  ${brick.line}: ${brick.decl}`;
+/**
+* The map of `bricks` for `request` (a story's title and sheet, a sentence), within `budget` tokens.
+* Undefined when there is nothing exported to show.
+*/
+function repoMapOf(bricks, request, budget = MAP_TOKENS) {
+	const tokensLeft = Math.min(MAP_MAX_TOKENS, Math.max(0, Number.isFinite(budget) ? Math.floor(budget) : MAP_TOKENS));
+	const candidates = candidatesOf(bricks, request).sort(byRank);
+	if (candidates.length === 0 || tokensLeft === 0) return void 0;
+	const related = candidates.filter((c) => c.relevance > 0 || c.mentioned > 0);
+	const filler = candidates.filter((c) => c.relevance === 0 && c.mentioned === 0);
+	const room = tokensLeft * CHARS_PER_TOKEN - 57 - 64;
+	const fillerRoom = related.length === 0 ? room : Math.floor(room * FILLER_SHARE);
+	const blocks = [];
+	let chars = 0;
+	let shown = 0;
+	let fillerChars = 0;
+	let symbols = 0;
+	let left = candidates.length;
+	const take = (list, cap, limit, isFiller) => {
+		for (const candidate of list) {
+			const lines = symbolsOf(candidate, cap);
+			const fitting = [];
+			let size = candidate.path.length + 1;
+			for (const brick of lines) {
+				const add = lineOf(brick).length + 1;
+				if ((isFiller ? fillerChars : chars) + size + add > limit || chars + size + add > room) break;
+				fitting.push(brick);
+				size += add;
+			}
+			if (fitting.length === 0) continue;
+			fitting.sort((a, b) => a.line - b.line);
+			blocks.push(`${candidate.path}\n${fitting.map(lineOf).join("\n")}`);
+			chars += size;
+			if (isFiller) fillerChars += size;
+			shown += 1;
+			symbols += fitting.length;
+			left -= 1;
+		}
+	};
+	take(related, SYMBOLS_PER_FILE, room, false);
+	take(filler, SYMBOLS_PER_FILLER, fillerRoom, true);
+	if (shown === 0) return void 0;
+	const footer = left > 0 ? `\n+${left} more files` : "";
+	const text = `${HEADER}\n${blocks.join("\n")}${footer}`;
+	return {
+		text,
+		tokens: mapTokens(text),
+		files: shown,
+		symbols,
+		omitted_files: left
+	};
+}
+// ../../packages/core/dist/project-profile/scan.js
+/** Longest manifest read (bytes): a larger one is data, not a manifest. */
+const MAX_MANIFEST = 2e5;
+const MAX_LAYOUT = 12;
+/** Root entries that are not product folders. */
+const NOT_LAYOUT = /* @__PURE__ */ new Set([
+	"node_modules",
+	"dist",
+	"build",
+	"out",
+	"target",
+	"vendor",
+	"coverage",
+	"tmp",
+	"temp",
+	"bin",
+	"obj",
+	"venv",
+	"env",
+	"docs",
+	"doc",
+	"scripts",
+	"public",
+	"assets",
+	"images",
+	"licenses",
+	"license"
+]);
+const TEST_FOLDERS = /* @__PURE__ */ new Set([
+	"test",
+	"tests",
+	"__tests__",
+	"spec",
+	"specs",
+	"e2e"
+]);
+function lower(entries) {
+	return new Map(entries.map((entry) => [entry.toLowerCase(), entry]));
+}
+/** The script a manifest names `name`, as a command, or undefined. */
+const pick = (record, name) => {
+	const value = record?.[name];
+	return typeof value === "string" && value.trim() !== "" ? value : void 0;
+};
+const asRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+/** Libraries worth naming in the stack: a short, well-known set, found in a dependency list. */
+const KNOWN_PACKAGES = [
+	["react", "React"],
+	["vue", "Vue"],
+	["svelte", "Svelte"],
+	["next", "Next.js"],
+	["nuxt", "Nuxt"],
+	["@angular/core", "Angular"],
+	["express", "Express"],
+	["fastify", "Fastify"],
+	["@nestjs/core", "NestJS"],
+	["vitest", "Vitest"],
+	["jest", "Jest"],
+	["mocha", "Mocha"],
+	["@playwright/test", "Playwright"],
+	["cypress", "Cypress"],
+	["@biomejs/biome", "Biome"],
+	["eslint", "ESLint"],
+	["prettier", "Prettier"]
+];
+async function scanNode(reader, out) {
+	const raw = await reader.text("package.json");
+	if (raw === void 0) return;
+	let manifest;
+	try {
+		manifest = asRecord(JSON.parse(raw));
+	} catch {
+		out.stack.push("Node.js project (package.json is not valid JSON)");
+		return;
+	}
+	if (manifest === void 0) return;
+	const lockfiles = [
+		"pnpm-lock.yaml",
+		"yarn.lock",
+		"bun.lock",
+		"bun.lockb",
+		"package-lock.json"
+	].filter((name) => reader.entries.has(name));
+	const declared = pick(manifest, "packageManager")?.split("@")[0];
+	const manager = declared !== void 0 && declared !== "" ? declared : {
+		"pnpm-lock.yaml": "pnpm",
+		"yarn.lock": "yarn",
+		"bun.lock": "bun",
+		"bun.lockb": "bun",
+		"package-lock.json": "npm"
+	}[lockfiles[0] ?? ""] ?? "npm";
+	const typed = reader.entries.has("tsconfig.json");
+	const engines = pick(asRecord(manifest.engines), "node");
+	out.stack.push(`${typed ? "TypeScript" : "JavaScript"} on Node.js${engines === void 0 ? "" : ` ${engines}`}, ${manager} (package.json${lockfiles.length > 0 ? `, ${lockfiles[0]}` : ""})`);
+	const dependencies = {
+		...asRecord(manifest.dependencies),
+		...asRecord(manifest.devDependencies)
+	};
+	const known = KNOWN_PACKAGES.filter(([name]) => name in dependencies).map(([, label]) => label);
+	if (known.length > 0) out.stack.push(`Libraries: ${known.join(", ")} (package.json)`);
+	const scripts = asRecord(manifest.scripts);
+	const run = (name) => manager === "yarn" ? `yarn ${name}` : `${manager} run ${name}`;
+	const add = (kind, script, command = run(script)) => {
+		if (pick(scripts, script) !== void 0) out.commands.push({
+			name: kind,
+			command,
+			source: `package.json scripts.${script}`
+		});
+	};
+	add("test", "test", manager === "yarn" ? "yarn test" : `${manager} test`);
+	add("build", "build");
+	add("lint", "lint");
+	add("typecheck", "typecheck");
+	add("typecheck", "type-check");
+	add("format", "format");
+	add("run", "dev");
+	if (pick(scripts, "dev") === void 0) add("run", "start");
+	if (lockfiles.length > 1) out.advice.push({
+		advice: `Pick one package manager (${manager}) and delete the other lockfiles.`,
+		why: `${lockfiles.join(" and ")} are all committed: two managers rewrite each other's lockfile.`
+	});
+	else if (lockfiles.length === 1) out.advice.push({
+		advice: `Install with ${manager} only.`,
+		why: `${lockfiles[0]} is committed: another manager would rewrite it and change versions.`
+	});
+	if (manifest.workspaces !== void 0 || reader.entries.has("pnpm-workspace.yaml")) out.advice.push({
+		advice: "Run a package's commands from that package, not from the root, when you touch one.",
+		why: "the repository holds several packages (workspaces): the root command runs them all."
+	});
+}
+async function scanPython(reader, out) {
+	const pyproject = await reader.text("pyproject.toml");
+	const requirements = await reader.text("requirements.txt");
+	const hasSetup = reader.entries.has("setup.py") || reader.entries.has("pipfile");
+	if (pyproject === void 0 && requirements === void 0 && !hasSetup) return;
+	const runner = reader.entries.has("uv.lock") ? "uv run " : reader.entries.has("poetry.lock") ? "poetry run " : "";
+	const source = pyproject !== void 0 ? "pyproject.toml" : "requirements.txt";
+	const text = `${pyproject ?? ""}\n${requirements ?? ""}`.toLowerCase();
+	out.stack.push(`Python (${source}${runner === "" ? "" : `, ${runner.trim()}`})`);
+	if (/pytest/.test(text)) out.commands.push({
+		name: "test",
+		command: `${runner}pytest`,
+		source
+	});
+	if (/\[tool\.ruff|\bruff\b/.test(text)) out.commands.push({
+		name: "lint",
+		command: `${runner}ruff check`,
+		source
+	});
+	if (/\[tool\.mypy|\bmypy\b/.test(text)) out.commands.push({
+		name: "typecheck",
+		command: `${runner}mypy .`,
+		source
+	});
+	if (runner !== "") out.advice.push({
+		advice: `Run Python tools through \`${runner.trim()}\`.`,
+		why: `${runner.startsWith("uv") ? "uv.lock" : "poetry.lock"} is committed: a bare \`python\` or \`pytest\` runs outside the project environment.`
+	});
+}
+function scanSimple(reader, out) {
+	const has = (name) => reader.entries.has(name);
+	if (has("cargo.toml")) {
+		out.stack.push("Rust (Cargo.toml)");
+		out.commands.push({
+			name: "test",
+			command: "cargo test",
+			source: "Cargo.toml"
+		});
+		out.commands.push({
+			name: "build",
+			command: "cargo build",
+			source: "Cargo.toml"
+		});
+	}
+	if (has("go.mod")) {
+		out.stack.push("Go (go.mod)");
+		out.commands.push({
+			name: "test",
+			command: "go test ./...",
+			source: "go.mod"
+		});
+		out.commands.push({
+			name: "build",
+			command: "go build ./...",
+			source: "go.mod"
+		});
+		out.commands.push({
+			name: "lint",
+			command: "go vet ./...",
+			source: "go.mod"
+		});
+	}
+	if (has("pom.xml")) {
+		out.stack.push("Java (pom.xml)");
+		out.commands.push({
+			name: "test",
+			command: "mvn test",
+			source: "pom.xml"
+		});
+	}
+	const gradle = ["build.gradle", "build.gradle.kts"].find(has);
+	if (gradle !== void 0) {
+		const wrapper = has("gradlew") ? "./gradlew" : "gradle";
+		out.stack.push(`JVM, Gradle (${gradle})`);
+		out.commands.push({
+			name: "test",
+			command: `${wrapper} test`,
+			source: gradle
+		});
+		out.commands.push({
+			name: "build",
+			command: `${wrapper} build`,
+			source: gradle
+		});
+	}
+	const dotnet = [...reader.entries].find((name) => /\.(?:sln|slnx|csproj|fsproj)$/.test(name));
+	if (dotnet !== void 0) {
+		out.stack.push(`.NET (${dotnet})`);
+		out.commands.push({
+			name: "test",
+			command: "dotnet test",
+			source: dotnet
+		});
+		out.commands.push({
+			name: "build",
+			command: "dotnet build",
+			source: dotnet
+		});
+	}
+	if (has("gemfile")) {
+		out.stack.push("Ruby (Gemfile)");
+		if (has(".rspec")) out.commands.push({
+			name: "test",
+			command: "bundle exec rspec",
+			source: ".rspec"
+		});
+	}
+	if (has("mix.exs")) {
+		out.stack.push("Elixir (mix.exs)");
+		out.commands.push({
+			name: "test",
+			command: "mix test",
+			source: "mix.exs"
+		});
+	}
+	if (has("package.swift")) {
+		out.stack.push("Swift (Package.swift)");
+		out.commands.push({
+			name: "test",
+			command: "swift test",
+			source: "Package.swift"
+		});
+	}
+	if (has("pubspec.yaml")) out.stack.push("Dart (pubspec.yaml)");
+}
+async function scanComposer(reader, out) {
+	const raw = await reader.text("composer.json");
+	if (raw === void 0) return;
+	out.stack.push("PHP (composer.json)");
+	try {
+		if (asRecord(asRecord(JSON.parse(raw))?.scripts)?.test !== void 0) out.commands.push({
+			name: "test",
+			command: "composer test",
+			source: "composer.json scripts.test"
+		});
+	} catch {}
+}
+/** The targets of a Makefile the profile names (a target is a command only when it is written). */
+async function scanMake(reader, out) {
+	const text = await reader.text("Makefile");
+	if (text === void 0) return;
+	const targets = new Set([...text.matchAll(/^([a-z][\w-]*)\s*:(?!=)/gm)].map((match) => match[1]));
+	for (const [kind, target] of [
+		["test", "test"],
+		["build", "build"],
+		["lint", "lint"],
+		["format", "fmt"],
+		["format", "format"]
+	]) if (targets.has(target) && !out.commands.some((command) => command.name === kind)) out.commands.push({
+		name: kind,
+		command: `make ${target}`,
+		source: `Makefile ${target}:`
+	});
+}
+const TOOLING = [
+	[
+		["biome.json", "biome.jsonc"],
+		"Biome formats and lints",
+		"its config is committed"
+	],
+	[
+		[
+			".prettierrc",
+			".prettierrc.json",
+			".prettierrc.js",
+			"prettier.config.js"
+		],
+		"Prettier formats",
+		"its config is committed"
+	],
+	[
+		[
+			".eslintrc",
+			".eslintrc.json",
+			".eslintrc.js",
+			"eslint.config.js",
+			"eslint.config.mjs"
+		],
+		"ESLint lints",
+		"its config is committed"
+	],
+	[
+		["rustfmt.toml", ".rustfmt.toml"],
+		"rustfmt formats",
+		"its config is committed"
+	],
+	[
+		[".golangci.yml", ".golangci.yaml"],
+		"golangci-lint lints",
+		"its config is committed"
+	],
+	[
+		[".rubocop.yml"],
+		"RuboCop lints",
+		"its config is committed"
+	],
+	[
+		[".editorconfig"],
+		"EditorConfig sets indentation and line endings",
+		".editorconfig is committed"
+	]
+];
+const CI_FILES = [
+	".gitlab-ci.yml",
+	"azure-pipelines.yml",
+	"jenkinsfile",
+	".travis.yml",
+	"bitbucket-pipelines.yml",
+	"appveyor.yml"
+];
+async function scanConventions(reader, files, out) {
+	for (const [names, label, why] of TOOLING) {
+		const found = names.find((name) => reader.entries.has(name.toLowerCase()));
+		if (found === void 0) continue;
+		out.conventions.push(`${label} (${found}).`);
+		if (label.startsWith("Biome") || label.startsWith("Prettier") || label.startsWith("rustfmt")) out.advice.push({
+			advice: `Format with the project's formatter, not by hand.`,
+			why: `${found}: ${why}, and a style-only diff is noise in a review.`
+		});
+	}
+	for (const pinned of [
+		".nvmrc",
+		".node-version",
+		".python-version",
+		".tool-versions"
+	]) {
+		if (!reader.entries.has(pinned)) continue;
+		const value = (await reader.text(pinned))?.split("\n")[0]?.trim();
+		out.conventions.push(`Runtime version pinned: ${value ?? "see file"} (${pinned}).`);
+	}
+	let workflows = [];
+	try {
+		workflows = (await files.listEntries?.(".github/workflows") ?? []).filter((name) => /\.ya?ml$/i.test(name));
+	} catch {
+		workflows = [];
+	}
+	if (workflows.length > 0) out.conventions.push(`CI: GitHub Actions (${workflows.slice(0, 4).join(", ")}).`);
+	const ci = CI_FILES.find((name) => reader.entries.has(name));
+	if (ci !== void 0) out.conventions.push(`CI: ${ci}.`);
+	if (reader.entries.has("dockerfile") || reader.entries.has("docker-compose.yml")) out.conventions.push("Containers: Dockerfile or docker-compose.yml at the root.");
+	if (reader.entries.has("tsconfig.json")) out.conventions.push("TypeScript: tsconfig.json at the root.");
+}
+/** Reads the product's root and says what it is. Never throws: an unreadable file says nothing. */
+async function scanProject(files) {
+	const out = {
+		stack: [],
+		commands: [],
+		conventions: [],
+		layout: [],
+		advice: []
+	};
+	let names = [];
+	try {
+		names = await files.listEntries?.("") ?? [];
+	} catch {
+		names = [];
+	}
+	const byLower = lower(names);
+	const reader = {
+		entries: new Set(byLower.keys()),
+		async text(name) {
+			const actual = byLower.get(name.toLowerCase());
+			if (actual === void 0) return void 0;
+			try {
+				const text = await files.readText(actual);
+				return text.length > MAX_MANIFEST ? void 0 : text.replace(/\r\n/g, "\n");
+			} catch {
+				return;
+			}
+		}
+	};
+	await scanNode(reader, out);
+	await scanPython(reader, out);
+	scanSimple(reader, out);
+	await scanComposer(reader, out);
+	await scanMake(reader, out);
+	await scanConventions(reader, files, out);
+	const folders = [];
+	for (const name of names) {
+		if (name.includes(".") || name.startsWith("_") || NOT_LAYOUT.has(name.toLowerCase())) continue;
+		if (folders.length >= 30) break;
+		try {
+			if ((await files.listEntries?.(name) ?? []).length > 0) folders.push(name);
+		} catch {}
+	}
+	const tests = folders.filter((name) => TEST_FOLDERS.has(name.toLowerCase()));
+	const product = folders.filter((name) => !TEST_FOLDERS.has(name.toLowerCase()));
+	if (product.length > 0) out.layout.push(`Folders: ${product.slice(0, MAX_LAYOUT).join(", ")}.`);
+	if (tests.length > 0) out.layout.push(`Tests live in: ${tests.join(", ")}.`);
+	if (!out.commands.some((command) => command.name === "test") && out.stack.length > 0) out.advice.push({
+		advice: "No test command was found: ask the creator for it before inventing one.",
+		why: "no manifest or Makefile of the root defines it; a guessed command proves nothing."
+	});
+	return out;
+}
+// ../../packages/core/dist/project-profile/project-command.js
+const invalid = (reason) => new AgentPluggedError(ErrorCode.INVALID_ARGUMENTS, "error.invalid_arguments", { reason });
+async function readText(context, path) {
+	try {
+		return await context.files.exists(path) ? await context.files.readText(path) : void 0;
+	} catch {
+		return;
+	}
+}
+/** The single sources the team declared (the table of the profile), empty without a profile. */
+async function singleSourcesOf(context) {
+	const text = await readText(context, PROFILE_PATH);
+	return text === void 0 ? [] : parseKept(text).sources;
+}
+/** The profile file for a scan, the parts people wrote kept from `current`. */
+function profileFile(scan, current) {
+	const kept = current === void 0 ? {
+		sources: [],
+		acceptance: "",
+		notes: ""
+	} : parseKept(current);
+	return renderProfile(scan, kept);
+}
+/**
+* `docs profile [refresh]`: the project profile. Without `refresh`, the file as it would be written
+* now (and whether the file on disk still says the same); with it, the file is written. The profile
+* is read from the root files of the product, so it is never invented.
+*/
+async function showProfile(context, words) {
+	if (words[0] === "accept") return declareAcceptance(context, words.slice(1));
+	if (words.length > 1 || words.length === 1 && words[0] !== "refresh") return invalid(`docs profile ${words.join(" ")} (profile [refresh], or profile accept <preview|staging|local> [how])`);
+	const current = await readText(context, PROFILE_PATH);
+	const fresh = profileFile(await scanProject(context.files), current);
+	const same = current !== void 0 && current.replace(/\r\n/g, "\n") === fresh;
+	if (words[0] === "refresh") {
+		if (!same) await context.files.writeText(PROFILE_PATH, fresh);
+		return { profile: {
+			path: PROFILE_PATH,
+			written: !same,
+			state: current === void 0 ? "created" : same ? "current" : "refreshed",
+			lines: fresh.split("\n")
+		} };
+	}
+	return { profile: {
+		path: PROFILE_PATH,
+		written: false,
+		state: current === void 0 ? "absent" : same ? "current" : "stale",
+		lines: fresh.split("\n")
+	} };
+}
+/**
+* `docs profile accept <preview|staging|local> [how…]`: where the acceptance run happens, decided with the
+* creator and kept in the profile (a refresh never overwrites it).
+*/
+async function declareAcceptance(context, words) {
+	const [place, ...how] = words;
+	if (!ACCEPTANCE_PLACES.some((known) => known === place)) return invalid("docs profile accept <preview|staging|local> [how to reach it]");
+	const current = await readText(context, PROFILE_PATH);
+	const kept = current === void 0 ? {
+		sources: [],
+		acceptance: "",
+		notes: ""
+	} : parseKept(current);
+	const fresh = renderProfile(await scanProject(context.files), {
+		...kept,
+		acceptance: acceptanceText(place, how.join(" "))
+	});
+	await context.files.writeText(PROFILE_PATH, fresh);
+	return { profile: {
+		path: PROFILE_PATH,
+		written: true,
+		state: "refreshed",
+		lines: fresh.split("\n")
+	} };
+}
+/**
+* `docs bricks <words>`: does something like this already exist? The bricks (functions and types)
+* whose names carry the words, best first, and the single source that owns the concept if one is
+* declared. `docs bricks own <concept> <path> [rule…]` declares a single source: the concept then
+* has one home, and a second one added by a story is flagged at its review.
+*/
+async function findInRegistry(context, words) {
+	if (words[0] === "own") return declareSource(context, words.slice(1));
+	if (words.length === 0) return invalid("docs bricks <words> | docs bricks own <concept> <path>");
+	const sources = await singleSourcesOf(context);
+	const named = matchingSources(sources, words);
+	const loaded = await loadCodeMap(context);
+	if (typeof loaded === "string") return { bricks: {
+		query: words,
+		hits: [],
+		sources: named,
+		unavailable: loaded
+	} };
+	const bricks = bricksOfMap(loaded);
+	return { bricks: {
+		query: words,
+		hits: findBricks(bricks, words).map(({ brick }) => ({
+			name: brick.name,
+			kind: brick.kind,
+			path: brick.path,
+			line: brick.line,
+			sig: brick.sig
+		})),
+		sources: named,
+		searched: {
+			total: bricks.length,
+			commit: loaded.commit.slice(0, 12)
+		}
+	} };
+}
+async function declareSource(context, words) {
+	const [concept, owner, ...rule] = words;
+	if (concept === void 0 || owner === void 0 || concept.length < 2) return invalid("docs bricks own <concept> <path> [rule…]");
+	const bare = owner.replaceAll("\\", "/").split("/").filter((part) => part !== "" && part !== ".").join("/");
+	if (bare === "" || bare.startsWith("/") || bare.split("/").includes("..")) return invalid(`docs bricks own ${concept} ${owner} (a path of the product)`);
+	if (!await context.files.exists(bare)) return invalid(`docs bricks own ${concept} ${owner} (no such file or folder)`);
+	const source = {
+		concept: concept.replace(/[|\r\n]+/g, " ").trim(),
+		owner: (await context.files.listEntries?.(bare) ?? []).length > 0 ? `${bare}/` : bare,
+		rule: rule.join(" ").slice(0, 160)
+	};
+	const current = await readText(context, PROFILE_PATH);
+	const scan = await scanProject(context.files);
+	const kept = withSource(current === void 0 ? {
+		sources: [],
+		acceptance: "",
+		notes: ""
+	} : parseKept(current), source);
+	await context.files.writeText(PROFILE_PATH, renderProfile(scan, kept));
+	return { bricks: {
+		query: [concept],
+		hits: [],
+		sources: [source],
+		declared: source
+	} };
+}
+/** Longest list of each kind in the brief. */
+const BRIEF_ROWS = 6;
+/**
+* The profile brief for a story: read from the root files now (a stale file never misleads) with the
+* single sources of the profile. Undefined when the product has no stack to describe yet.
+*/
+async function profileBrief(context) {
+	try {
+		const scan = await scanProject(context.files);
+		if (scan.stack.length === 0 && scan.commands.length === 0) return void 0;
+		const sources = await singleSourcesOf(context);
+		return {
+			path: PROFILE_PATH,
+			stack: scan.stack.slice(0, BRIEF_ROWS).map((row) => row.slice(0, 140)),
+			commands: scan.commands.slice(0, 12).map((c) => `${c.name}: ${c.command}`),
+			single_sources: sources.slice(0, 10).map((s) => `${s.concept} -> ${s.owner}${s.rule === "" ? "" : ` (${s.rule})`}`),
+			advice: scan.advice.slice(0, 3).map((a) => `${a.advice} Why: ${a.why}`.slice(0, 220)),
+			ask: "npx agentplugged docs bricks <words>"
+		};
+	} catch {
+		return;
+	}
+}
+/**
+* `docs map <request…>`: the map of the code for a piece of work, the same one `start_story` hands
+* the agent for a story's sheet: the files that matter for the request and the signatures they
+* export, within the same budget. Without a request, the files the rest of the code leans on.
+*/
+async function showRepoMap(context, words) {
+	const loaded = await loadCodeMap(context);
+	if (typeof loaded === "string") return { map: {
+		tokens: 0,
+		files: 0,
+		symbols: 0,
+		omitted_files: 0,
+		unavailable: loaded
+	} };
+	return { map: repoMapOf(bricksOfMap(loaded), words.join(" "), 1500) ?? {
+		tokens: 0,
+		files: 0,
+		symbols: 0,
+		omitted_files: 0
+	} };
+}
+/**
+* The map of the repository for a request (a story's sheet), read from the registry of the commit
+* the folder is on: the files that matter and their exported signatures, within the budget.
+* Undefined when the code cannot be read or holds nothing to show; never a failure.
+*/
+async function repoMapFor(context, request, budget = MAP_TOKENS) {
+	try {
+		const loaded = await loadCodeMap(context);
+		return typeof loaded === "string" ? void 0 : repoMapOf(bricksOfMap(loaded), request, budget);
+	} catch {
+		return;
+	}
+}
+export { showProfile as a, scanProject as c, mapTokens as d, repoMapOf as f, repoMapFor as i, MAP_MAX_TOKENS as l, profileBrief as n, showRepoMap as o, profileFile as r, singleSourcesOf as s, findInRegistry as t, MAP_TOKENS as u };