@tea-agent/loop-agent 0.12.0 → 0.13.0-beta.0

package/scripts/kb-graph-incremental-prepare.mjs

@@ -0,0 +1,386 @@
+#!/usr/bin/env node
+/**
+ * Prepare narrowed scope/status for incremental knowledge-graph updates.
+ * Reuses knowledge-graph-bootstrap DAG; does not call an LLM.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+
+function usage(code = 2) {
+	const text = `Usage: node scripts/kb-graph-incremental-prepare.mjs --root <dir> [options]
+
+Prepare an incremental graph-update run (same DAG as bootstrap, narrowed scope).
+
+  --root DIR              Repository root (required)
+  --feature F-id          Seed feature (repeatable)
+  --service NAME          Seed service (repeatable)
+  --domain NAME           Seed domain (repeatable)
+  --include GLOB          include_paths entry (repeatable)
+  --reset-staging         Clear knowledge/bootstrap/staging/**
+  --force-scope           Rewrite scope.yaml from seeds (default: merge seeds)
+  --product-name NAME     Used when creating missing B1 skeleton
+  -h, --help
+`;
+	if (code === 0) console.log(text);
+	else console.error(text);
+	process.exit(code);
+}
+
+function parseArgs(argv) {
+	const out = {
+		root: null,
+		features: [],
+		services: [],
+		domains: [],
+		includes: [],
+		resetStaging: false,
+		forceScope: false,
+		productName: null,
+	};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		const next = () => {
+			const v = argv[++i];
+			if (v === undefined) throw new Error(`missing value for ${a}`);
+			return v;
+		};
+		switch (a) {
+			case "--root":
+				out.root = path.resolve(next());
+				break;
+			case "--feature":
+				out.features.push(next());
+				break;
+			case "--service":
+				out.services.push(next());
+				break;
+			case "--domain":
+				out.domains.push(next());
+				break;
+			case "--include":
+				out.includes.push(next());
+				break;
+			case "--reset-staging":
+				out.resetStaging = true;
+				break;
+			case "--force-scope":
+				out.forceScope = true;
+				break;
+			case "--product-name":
+				out.productName = next();
+				break;
+			case "-h":
+			case "--help":
+				usage(0);
+				break;
+			default:
+				throw new Error(`unknown argument: ${a}`);
+		}
+	}
+	return out;
+}
+
+function ensureSkeleton(root, productName) {
+	const scope = path.join(root, "knowledge/bootstrap/scope.yaml");
+	const status = path.join(root, "knowledge/bootstrap/status.yaml");
+	if (fs.existsSync(scope) && fs.existsSync(status)) return;
+	const skeleton = path.join(scriptDir, "kb-bootstrap-init-skeleton.sh");
+	const args = ["bash", skeleton, "--root", root];
+	if (productName) args.push("--product-name", productName);
+	const r = spawnSync(args[0], args.slice(1), { encoding: "utf8" });
+	if (r.status !== 0) {
+		throw new Error(
+			`failed to init B1 skeleton: ${r.stderr || r.stdout || r.status}`,
+		);
+	}
+}
+
+function dumpYaml(obj, indent = 0) {
+	const sp = "  ".repeat(indent);
+	if (Array.isArray(obj)) {
+		if (obj.length === 0) return "[]";
+		return obj.map((item) => `${sp}- ${formatScalar(item)}`).join("\n");
+	}
+	if (obj && typeof obj === "object") {
+		return Object.entries(obj)
+			.map(([k, v]) => {
+				if (Array.isArray(v)) {
+					if (v.length === 0) return `${sp}${k}: []`;
+					return `${sp}${k}:\n${v.map((item) => `${sp}  - ${formatScalar(item)}`).join("\n")}`;
+				}
+				if (v && typeof v === "object") {
+					return `${sp}${k}:\n${dumpYaml(v, indent + 1)}`;
+				}
+				return `${sp}${k}: ${formatScalar(v)}`;
+			})
+			.join("\n");
+	}
+	return `${sp}${formatScalar(obj)}`;
+}
+
+function formatScalar(v) {
+	if (v === null || v === undefined) return "null";
+	if (typeof v === "boolean" || typeof v === "number") return String(v);
+	const s = String(v);
+	if (/[:#{}[\],&*?|>!%@`]/.test(s) || s === "" || /\s/.test(s)) {
+		return JSON.stringify(s);
+	}
+	return s;
+}
+
+function unique(list) {
+	return [...new Set(list.filter(Boolean))];
+}
+
+function buildIncludes(args) {
+	if (args.includes.length) return unique(args.includes);
+	const includes = ["features/**", "docs/**", "README.md"];
+	for (const f of args.features) includes.push(`features/${f}/**`);
+	for (const s of args.services) {
+		includes.push(
+			`services/${s}/**`,
+			`apps/${s}/**`,
+			`packages/${s}/**`,
+			"src/**",
+		);
+	}
+	return unique(includes);
+}
+
+function mergeSeedsIntoScopeText(text, args) {
+	let next = text;
+	if (!/update_mode:\s*incremental/.test(next)) {
+		if (/update_mode:\s*\S+/.test(next)) {
+			next = next.replace(/update_mode:\s*\S+/, "update_mode: incremental");
+		} else {
+			next = next.replace(
+				/(schema_version:\s*\d+)/,
+				"$1\nupdate_mode: incremental",
+			);
+		}
+	}
+	const upsert = (label, items) => {
+		if (!items.length) return;
+		const re = new RegExp(
+			`${label}:\\s*(\\[\\]|\\n(?:\\s+-\\s+[^\\n]+\\n)*)`,
+		);
+		const m = next.match(re);
+		const existing = new Set();
+		if (m) {
+			for (const line of m[1].split("\n")) {
+				const mm = line.match(/-\s+(.+?)\s*$/);
+				if (!mm) continue;
+				const scalar = mm[1];
+				if (scalar.startsWith('"')) {
+					try {
+						existing.add(JSON.parse(scalar));
+						continue;
+					} catch {
+						// Fall through to conservative quote trimming.
+					}
+				}
+				existing.add(scalar.replace(/^["']|["']$/g, ""));
+			}
+		}
+		for (const it of items) existing.add(it);
+		const body = [...existing]
+			.map((i) => `  - ${formatScalar(i)}`)
+			.join("\n");
+		const block = `${label}:\n${body}\n`;
+		if (m) next = next.replace(re, block);
+		else next += `\n${block}`;
+	};
+	upsert("seed_features", args.features);
+	upsert("seed_services", args.services);
+	upsert("seed_domains", args.domains);
+	upsert("include_paths", args.includes);
+	return next.endsWith("\n") ? next : `${next}\n`;
+}
+
+function resetStaging(root, bootstrapId) {
+	const staging = path.join(root, "knowledge/bootstrap/staging");
+	if (!fs.existsSync(staging)) {
+		fs.mkdirSync(staging, { recursive: true });
+	}
+	for (const ent of fs.readdirSync(staging, { withFileTypes: true })) {
+		if (ent.name === ".gitkeep") continue;
+		fs.rmSync(path.join(staging, ent.name), { recursive: true, force: true });
+	}
+	for (const d of [
+		"domains",
+		"services",
+		"modules",
+		"features-links.proposed",
+	]) {
+		fs.mkdirSync(path.join(staging, d), { recursive: true });
+	}
+	fs.writeFileSync(
+		path.join(staging, "notes.md"),
+		`# staging cleared for incremental run ${bootstrapId}\n`,
+	);
+	fs.writeFileSync(
+		path.join(staging, "edges.proposed.yaml"),
+		"schema_version: 1\nedges: []\n",
+	);
+	fs.writeFileSync(
+		path.join(staging, "coverage-notes.md"),
+		"# coverage notes (incremental)\n",
+	);
+}
+
+function main() {
+	let args;
+	try {
+		args = parseArgs(process.argv.slice(2));
+	} catch (e) {
+		console.error(String(e?.message || e));
+		usage(2);
+	}
+	if (!args.root) {
+		console.error("--root is required");
+		usage(2);
+	}
+	if (
+		!args.features.length &&
+		!args.services.length &&
+		!args.domains.length &&
+		!args.includes.length
+	) {
+		console.error(
+			"at least one of --feature / --service / --domain / --include is required",
+		);
+		process.exit(2);
+	}
+
+	ensureSkeleton(args.root, args.productName);
+	const ts = new Date().toISOString();
+	const bootstrapId = `BR-INC-${ts.replace(/[-:TZ.]/g, "").slice(0, 14)}`;
+	const scopePath = path.join(args.root, "knowledge/bootstrap/scope.yaml");
+	const statusPath = path.join(args.root, "knowledge/bootstrap/status.yaml");
+	const backupDir = path.join(
+		args.root,
+		"knowledge/bootstrap/runs",
+		bootstrapId,
+	);
+	fs.mkdirSync(backupDir, { recursive: true });
+	fs.copyFileSync(scopePath, path.join(backupDir, "scope.before.yaml"));
+	fs.copyFileSync(statusPath, path.join(backupDir, "status.before.yaml"));
+
+	const includes = buildIncludes(args);
+	const product =
+		args.productName || path.basename(args.root);
+
+	if (args.forceScope || !fs.existsSync(scopePath)) {
+		const data = {
+			schema_version: 1,
+			product_name: product,
+			primary_language: "zh-CN",
+			repo_kind: "single-service",
+			update_mode: "incremental",
+			include_paths: includes,
+			exclude_paths: ["node_modules/**", "dist/**", ".harness/**"],
+			id_namespace: {
+				domain_prefix: "DOM",
+				service_prefix: "SVC",
+				api_prefix: "API",
+			},
+			seed_domains: args.domains,
+			seed_services: args.services,
+			seed_features: args.features,
+			assumptions: [
+				"Incremental update: do not rebuild unrelated domains/services",
+			],
+			out_of_scope: ["full-repo bootstrap"],
+			human_owners: { architect: "", qa: "" },
+		};
+		fs.writeFileSync(
+			scopePath,
+			`# Incremental graph scope\n${dumpYaml(data)}\n`,
+		);
+	} else {
+		const merged = mergeSeedsIntoScopeText(
+			fs.readFileSync(scopePath, "utf8"),
+			args,
+		);
+		fs.writeFileSync(scopePath, merged);
+	}
+
+	const status = {
+		schema_version: 1,
+		bootstrap_id: bootstrapId,
+		repo_root: ".",
+		phase: "B2",
+		update_mode: "incremental",
+		updated_at: ts,
+		scope_ref: "knowledge/bootstrap/scope.yaml",
+		inventory_ref: "knowledge/bootstrap/inventory.json",
+		last_run_dir: `knowledge/bootstrap/runs/${bootstrapId}/`,
+		stats: {
+			entities_proposed: 0,
+			entities_asserted: 0,
+			edges_proposed: 0,
+			edges_asserted: 0,
+			features_linked: 0,
+		},
+		blockers: [],
+		next_actions: [
+			"Review knowledge/bootstrap/scope.yaml (update_mode: incremental)",
+			"Run knowledge-graph-bootstrap DAG (propose limited to scope seeds/includes)",
+			"Promote merge-new-only; materialize indexes",
+		],
+	};
+	fs.writeFileSync(
+		statusPath,
+		`# Incremental bootstrap status\n${dumpYaml(status)}\n`,
+	);
+
+	if (args.resetStaging) resetStaging(args.root, bootstrapId);
+
+	fs.writeFileSync(
+		path.join(backupDir, "README.md"),
+		[
+			`# Incremental prepare ${bootstrapId}`,
+			"",
+			`- update_mode: incremental`,
+			`- features: ${args.features.join(", ") || "(none)"}`,
+			`- services: ${args.services.join(", ") || "(none)"}`,
+			`- domains: ${args.domains.join(", ") || "(none)"}`,
+			"",
+			"Next:",
+			"```bash",
+			"# task.json: { \"taskKind\": \"knowledge-graph-bootstrap\", ... }",
+			"loop-agent dag run-task <task-id> --execute --cwd .",
+			`bash scripts/kb-graph-materialize.sh --root ${args.root}`,
+			"```",
+			"",
+		].join("\n"),
+	);
+
+	console.log(
+		JSON.stringify(
+			{
+				ok: true,
+				bootstrap_id: bootstrapId,
+				update_mode: "incremental",
+				scope: "knowledge/bootstrap/scope.yaml",
+				status: "knowledge/bootstrap/status.yaml",
+				backup: `knowledge/bootstrap/runs/${bootstrapId}/`,
+				seeds: {
+					features: args.features,
+					services: args.services,
+					domains: args.domains,
+				},
+				next: "set task.json.taskKind=knowledge-graph-bootstrap; dag run-task --execute",
+			},
+			null,
+			2,
+		),
+	);
+}
+
+main();

package/scripts/kb-graph-incremental-prepare.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Incremental knowledge-graph update prepare (narrowed scope for bootstrap DAG).
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+exec node "${ROOT_DIR}/scripts/kb-graph-incremental-prepare.mjs" "$@"

package/scripts/kb-graph-materialize.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * Standalone B6-ish materialize: rebuild knowledge/graph/entities-index.yaml
+ * and edges.yaml from formal trees + edges.manual.yaml.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+function parseArgs(argv) {
+	let root = process.cwd();
+	for (let i = 0; i < argv.length; i++) {
+		if (argv[i] === "--root") root = path.resolve(argv[++i]);
+		else if (argv[i] === "-h" || argv[i] === "--help") {
+			console.log("Usage: node scripts/kb-graph-materialize.mjs [--root <dir>]");
+			process.exit(0);
+		}
+	}
+	return { root };
+}
+
+function walk(dir, acc = []) {
+	if (!fs.existsSync(dir)) return acc;
+	for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+		const p = path.join(dir, ent.name);
+		if (ent.isDirectory()) walk(p, acc);
+		else acc.push(p);
+	}
+	return acc;
+}
+
+function main() {
+	const { root } = parseArgs(process.argv.slice(2));
+	const entities = [];
+	for (const base of ["knowledge/domains", "knowledge/services", "knowledge/modules"]) {
+		for (const f of walk(path.join(root, base))) {
+			if (!f.endsWith("meta.yaml") && !f.endsWith("meta.yml")) continue;
+			const rel = path.relative(root, f).split(path.sep).join("/");
+			const text = fs.readFileSync(f, "utf8");
+			const id = (text.match(/^id:\s*(\S+)/m) || [])[1];
+			const kind = (text.match(/^kind:\s*(\S+)/m) || [])[1] || "unknown";
+			if (id) entities.push({ kind, id, path: rel });
+		}
+	}
+	const featRoot = path.join(root, "features");
+	if (fs.existsSync(featRoot)) {
+		for (const name of fs.readdirSync(featRoot)) {
+			if (!/^F-/.test(name)) continue;
+			const dir = path.join(featRoot, name);
+			if (!fs.statSync(dir).isDirectory()) continue;
+			entities.push({ kind: "feature", id: name, path: `features/${name}/` });
+			const links = path.join(dir, "knowledge-links.yaml");
+			if (fs.existsSync(links)) {
+				entities.push({
+					kind: "knowledge-links",
+					id: `${name}:links`,
+					path: `features/${name}/knowledge-links.yaml`,
+				});
+			}
+		}
+	}
+
+	const graphDir = path.join(root, "knowledge/graph");
+	fs.mkdirSync(graphDir, { recursive: true });
+	const generatedAt = new Date().toISOString();
+	const indexBody = [
+		"# generated by kb-graph-materialize",
+		"schema_version: 1",
+		`generated_at: ${generatedAt}`,
+		"entities:",
+		...entities.flatMap((e) => [
+			`  - kind: ${e.kind}`,
+			`    id: ${e.id}`,
+			`    path: ${e.path}`,
+		]),
+		"",
+	].join("\n");
+	fs.writeFileSync(path.join(graphDir, "entities-index.yaml"), indexBody);
+
+	const manual = path.join(graphDir, "edges.manual.yaml");
+	const edgesOut = path.join(graphDir, "edges.yaml");
+	if (fs.existsSync(manual)) {
+		fs.copyFileSync(manual, edgesOut);
+	} else if (!fs.existsSync(edgesOut)) {
+		fs.writeFileSync(
+			edgesOut,
+			`schema_version: 1\nupdated_at: ${generatedAt}\nedges: []\n`,
+		);
+	}
+
+	console.log(
+		JSON.stringify(
+			{
+				ok: true,
+				entities: entities.length,
+				entities_index: "knowledge/graph/entities-index.yaml",
+				edges: "knowledge/graph/edges.yaml",
+			},
+			null,
+			2,
+		),
+	);
+}
+
+main();

package/scripts/kb-graph-materialize.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+exec node "${ROOT_DIR}/scripts/kb-graph-materialize.mjs" "$@"

package/scripts/kb-graph-promote.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * Promote knowledge/bootstrap/staging → formal trees (merge-new-only).
+ * Never overwrites existing formal files. Does not call an LLM.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+function parseArgs(argv) {
+	const out = {
+		root: process.cwd(),
+		from: "knowledge/bootstrap/staging",
+		dryRun: false,
+		json: true,
+	};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--root") out.root = path.resolve(argv[++i]);
+		else if (a === "--from") out.from = argv[++i];
+		else if (a === "--dry-run") out.dryRun = true;
+		else if (a === "--json") out.json = true;
+		else if (a === "--markdown") out.json = false;
+		else if (a === "-h" || a === "--help") {
+			console.log(
+				"Usage: node scripts/kb-graph-promote.mjs [--root <dir>] [--from <staging-rel>] [--dry-run] [--json|--markdown]",
+			);
+			process.exit(0);
+		} else {
+			throw new Error(`unknown argument: ${a}`);
+		}
+	}
+	return out;
+}
+
+function copyDirMergeNew(src, dest, dryRun, stats) {
+	if (!fs.existsSync(src)) return;
+	fs.mkdirSync(dest, { recursive: true });
+	for (const ent of fs.readdirSync(src, { withFileTypes: true })) {
+		const s = path.join(src, ent.name);
+		const d = path.join(dest, ent.name);
+		if (ent.isDirectory()) {
+			copyDirMergeNew(s, d, dryRun, stats);
+			continue;
+		}
+		if (fs.existsSync(d)) {
+			stats.skipped.push(path.relative(stats.root, d).split(path.sep).join("/"));
+			continue;
+		}
+		stats.copied.push(path.relative(stats.root, d).split(path.sep).join("/"));
+		if (!dryRun) {
+			fs.mkdirSync(path.dirname(d), { recursive: true });
+			fs.copyFileSync(s, d);
+		}
+	}
+}
+
+function featureIdFromProposalFile(fileName) {
+	if (!/^F-[A-Za-z0-9][A-Za-z0-9._-]*\.ya?ml$/.test(fileName)) {
+		throw new Error(`invalid feature link proposal filename: ${fileName}`);
+	}
+	const id = fileName.replace(/\.ya?ml$/, "");
+	if (id.includes("..")) {
+		throw new Error(`invalid feature link proposal filename: ${fileName}`);
+	}
+	return id;
+}
+
+function main() {
+	let args;
+	try {
+		args = parseArgs(process.argv.slice(2));
+	} catch (e) {
+		console.error(String(e?.message || e));
+		process.exit(2);
+	}
+	const root = args.root;
+	const staging = path.join(root, args.from);
+	if (!fs.existsSync(staging)) {
+		const err = {
+			ok: false,
+			error: `missing staging at ${args.from}`,
+		};
+		console.log(JSON.stringify(err, null, 2));
+		process.exit(1);
+	}
+
+	const stats = { root, copied: [], skipped: [] };
+	copyDirMergeNew(
+		path.join(staging, "domains"),
+		path.join(root, "knowledge/domains"),
+		args.dryRun,
+		stats,
+	);
+	copyDirMergeNew(
+		path.join(staging, "services"),
+		path.join(root, "knowledge/services"),
+		args.dryRun,
+		stats,
+	);
+	copyDirMergeNew(
+		path.join(staging, "modules"),
+		path.join(root, "knowledge/modules"),
+		args.dryRun,
+		stats,
+	);
+
+	const edgesSrc = path.join(staging, "edges.proposed.yaml");
+	const edgesManual = path.join(root, "knowledge/graph/edges.manual.yaml");
+	if (fs.existsSync(edgesSrc)) {
+		if (fs.existsSync(edgesManual)) {
+			stats.skipped.push("knowledge/graph/edges.manual.yaml");
+		} else {
+			stats.copied.push("knowledge/graph/edges.manual.yaml");
+			if (!args.dryRun) {
+				fs.mkdirSync(path.dirname(edgesManual), { recursive: true });
+				fs.copyFileSync(edgesSrc, edgesManual);
+			}
+		}
+	}
+
+	const linksDir = path.join(staging, "features-links.proposed");
+	if (fs.existsSync(linksDir)) {
+		for (const f of fs.readdirSync(linksDir)) {
+			if (!f.endsWith(".yaml") && !f.endsWith(".yml")) continue;
+			const id = featureIdFromProposalFile(f);
+			const featureDir = path.join(root, "features", id);
+			if (!fs.existsSync(featureDir)) continue;
+			const dest = path.join(featureDir, "knowledge-links.yaml");
+			const rel = `features/${id}/knowledge-links.yaml`;
+			if (fs.existsSync(dest)) {
+				stats.skipped.push(rel);
+			} else {
+				stats.copied.push(rel);
+				if (!args.dryRun) {
+					fs.mkdirSync(path.dirname(dest), { recursive: true });
+					fs.copyFileSync(path.join(linksDir, f), dest);
+				}
+			}
+		}
+	}
+
+	const result = {
+		ok: true,
+		dry_run: args.dryRun,
+		copied_count: stats.copied.length,
+		skipped_count: stats.skipped.length,
+		copied: stats.copied,
+		skipped_existing: stats.skipped,
+		policy: "merge-new-only",
+	};
+
+	if (args.json) {
+		console.log(JSON.stringify(result, null, 2));
+	} else {
+		console.log(`# kb-graph-promote${args.dryRun ? " (dry-run)" : ""}`);
+		console.log(`copied: ${result.copied_count}`);
+		console.log(`skipped_existing: ${result.skipped_count}`);
+		for (const c of stats.copied) console.log(`+ ${c}`);
+		for (const s of stats.skipped) console.log(`= ${s}`);
+	}
+}
+
+main();

package/scripts/kb-graph-promote.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+exec node "${ROOT_DIR}/scripts/kb-graph-promote.mjs" "$@"