@broject/drill 0.0.0 → 0.2.3

package/README.md

@@ -1,3 +1,29 @@
 # @broject/drill
 
-Placeholder for @broject/drill published by @nx-devkit/prepare-for-release.
+Scoped descent frames behind `bro drill` — `drill down` opens a narrower
+investigation frame (materialized as a bead), `drill up` closes it with a
+mandatory result + prevention memo so a problem can't silently recur.
+
+> You probably want the CLI instead: `bro drill down --title …`.
+> Install this only when building agents that run drill frames.
+
+## Install
+
+```bash
+npm i @broject/drill
+```
+
+Requires Node ≥ 22 and `bd` (frames are beads). ESM only.
+
+## Surface
+
+- `drillConnector` — registers `bro drill *` subcommands
+- `PreventionPlan` — the required close-out artifact
+- `parseDrillPlan` / `DRILL_PLAN_KIND` — the unified drill plan payload
+- Re-exports `bd`/`taskStore` primitives from `@broject/core`
+
+## Links
+
+- Docs: https://broject.dev/docs/commands/drill
+- Source: https://github.com/ThePlenkov/bro/tree/main/packages/drill
+- CLI: https://www.npmjs.com/package/@broject/bro

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+import { Connector, bd, bdJson, checkBeads, refKind, taskStore } from "@broject/core";
+
+//#region src/types.d.ts
+interface DrillRow {
+  id: string;
+  title: string;
+  status: string;
+  priority?: number;
+  issue_type?: string;
+  created_at?: string;
+  updated_at?: string;
+  labels?: string[];
+  notes?: string;
+  ephemeral?: boolean;
+}
+interface DrillFrame extends DrillRow {
+  parentId?: string;
+  depth: number;
+}
+interface DownOptions {
+  under?: string;
+  /** Force a root frame — by default `down` nests under the current leaf. */
+  root?: boolean;
+  ephemeral?: boolean;
+  type?: string;
+  priority?: number;
+  description?: string;
+}
+interface UpOptions {
+  id?: string;
+  result: string;
+  prevent?: string[];
+  evidence?: string[];
+}
+interface UpResult {
+  closed: string;
+  preventionIds: string[];
+}
+//#endregion
+//#region src/frames.d.ts
+declare function listDrills(): DrillRow[];
+declare function childrenOf(id: string): DrillRow[];
+/**
+ * The active frame: an open drill leaf (no open drill children) on the
+ * deepest path. Ties break on most-recently-updated — the frame the agent
+ * touched last is almost always the live one.
+ */
+declare function currentFrame(): DrillFrame | undefined;
+/** Descend: create a child frame under `opts.under` or the current leaf;
+ *  `opts.root` forces a parentless frame even when a leaf is open. */
+declare function drillDown(title: string, opts?: DownOptions): DrillRow;
+interface PreventionPlan {
+  /** Normalized item key (`titleKey`) → existing bead id. */
+  reuse: Map<string, string>;
+  /** Item titles needing a new bead, in order, deduped, trimmed. */
+  create: string[];
+}
+/** Fold `--prevent` items against what the frame already recorded: an
+ * open prevention bead with the same title is reused, not recreated;
+ * repeated items within the list collapse to one bead. Pure — the
+ * retry-safety core of drillUp: a mid-flight failure followed by a
+ * retry converges instead of duplicating. */
+declare function planPreventions(items: string[], prior: DrillRow[]): PreventionPlan;
+/**
+ * Ascend: close the frame with a structured memo. `--result` is mandatory —
+ * a drill that returns nothing teaches nothing. Each `--prevent` item lands
+ * as a task on the parent frame so prevention work lives in the scope that
+ * spawned it.
+ */
+declare function drillUp(opts: UpOptions): UpResult;
+/** Root frames + rendered tree (indented, roots first). */
+declare function drillTree(): string;
+//#endregion
+//#region src/plan.d.ts
+/**
+ * Drill plans — a declared descent tree. The agent writes the
+ * investigation shape once, `bro run drill.toml` materializes the
+ * frames as beads; investigation fills each frame via `drill up`
+ * as usual.
+ *
+ *   kind = "drill"
+ *   title = "why does the cache miss"     # root frame
+ *
+ *   [[steps]]
+ *   title = "check the parser"            # child of root
+ *
+ *   [[steps]]
+ *   title = "narrow the repro"
+ *   under = 0                             # child of steps[0]
+ *   ephemeral = true
+ */
+interface DrillStep {
+  title: string;
+  /** index into `steps` — nested under that step; default = root */
+  under?: number;
+  ephemeral?: boolean;
+  description?: string;
+  priority?: number;
+  type?: string;
+}
+interface DrillPlan {
+  title: string;
+  steps: DrillStep[];
+}
+/** The `kind` value a drill plan must carry — `bro run` routes on it. */
+declare const PLAN_KIND = "drill";
+/** Validate an already-parsed plan document — the plugin planSchema.
+ *  Throws one error listing every problem. */
+declare function parseDrillPlan(doc: unknown, source?: string): DrillPlan;
+//#endregion
+//#region src/connector.d.ts
+declare const drillConnector: Connector;
+//#endregion
+export { PLAN_KIND as DRILL_PLAN_KIND, type DownOptions, type DrillFrame, type DrillPlan, type DrillRow, type DrillStep, type PreventionPlan, type UpOptions, type UpResult, bd, bdJson, checkBeads, childrenOf, currentFrame, drillConnector, drillDown, drillTree, drillUp, listDrills, parseDrillPlan, planPreventions, refKind, taskStore };

package/dist/index.js

@@ -0,0 +1,431 @@
+import { bd, bd as bd$1, bdJson, bdJson as bdJson$1, checkBeads, evidenceKind, refKind, refKind as refKind$1, taskStore, taskStore as taskStore$1 } from "@broject/core";
+
+//#region src/frames.ts
+const DRILL_LABEL = "drill";
+const PREVENTION_LABEL = "prevention";
+function isDrill(row) {
+	return row.labels?.includes(DRILL_LABEL) ?? false;
+}
+function isOpen(row) {
+	return row.status !== "closed" && row.status !== "done";
+}
+function listDrills() {
+	const persistent = taskStore$1().list({
+		labels: [DRILL_LABEL],
+		all: true,
+		limit: 0
+	});
+	let wisps = [];
+	try {
+		wisps = (bdJson$1([
+			"mol",
+			"wisp",
+			"list",
+			"--all"
+		]).wisps ?? []).filter(isDrill);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		if (!/unknown command|unrecognized command/i.test(msg)) throw err;
+	}
+	return [...persistent, ...wisps];
+}
+function childrenOf(id) {
+	return taskStore$1().children(id);
+}
+/** One `bd dep list` sweep: parent→kids and kid→parent in a single call
+* (was N+1 `bd children`). kids holds DRILL children only — every
+* consumer filters on isDrill anyway; drillUp's any-child close check
+* still uses childrenOf directly. */
+function drillRelations(rows) {
+	const kids = /* @__PURE__ */ new Map();
+	const parents = /* @__PURE__ */ new Map();
+	if (rows.length === 0) return {
+		kids,
+		parents
+	};
+	const byId = new Map(rows.map((r) => [r.id, r]));
+	const edges = taskStore$1().deps(rows.map((r) => r.id), { type: "parent-child" });
+	for (const e of edges) {
+		const kid = byId.get(e.issue_id);
+		const parent = byId.get(e.depends_on_id);
+		if (e.type !== "parent-child" || !kid || !parent) continue;
+		kids.set(parent.id, [...kids.get(parent.id) ?? [], kid]);
+		parents.set(kid.id, parent.id);
+	}
+	return {
+		kids,
+		parents
+	};
+}
+/**
+* The active frame: an open drill leaf (no open drill children) on the
+* deepest path. Ties break on most-recently-updated — the frame the agent
+* touched last is almost always the live one.
+*/
+function currentFrame() {
+	const rows = listDrills().filter(isOpen);
+	if (rows.length === 0) return;
+	const { kids, parents } = drillRelations(rows);
+	const depthOf = (id) => {
+		let d = 0;
+		let cur = id;
+		while ((cur = parents.get(cur)) !== void 0) d += 1;
+		return d;
+	};
+	const leaves = rows.filter((r) => !(kids.get(r.id) ?? []).some((k) => isOpen(k) && isDrill(k)));
+	leaves.sort((a, b) => {
+		const d = depthOf(b.id) - depthOf(a.id);
+		return d !== 0 ? d : (b.updated_at ?? "").localeCompare(a.updated_at ?? "");
+	});
+	const leaf = leaves[0];
+	if (!leaf) return;
+	return {
+		...leaf,
+		parentId: parents.get(leaf.id),
+		depth: depthOf(leaf.id)
+	};
+}
+/** The bead must be an open drill frame, or an explicit selector is wrong. */
+function requireOpenDrill(id, flag) {
+	const row = taskStore$1().get(id);
+	if (!row || !isDrill(row) || !isOpen(row)) throw new Error(`${flag} ${id} is not an open drill frame`);
+	return row;
+}
+/** Record the claim provenance; on failure, delete the frame — an
+* unclaimed frame violates the claim-on-down invariant, and a retry would
+* create a duplicate. A failed cleanup must not swallow the claim error. */
+function claimFrame(id) {
+	try {
+		bd$1([
+			"provenance",
+			"record",
+			"--issue",
+			id,
+			"--kind",
+			"claim",
+			"--source",
+			"bro drill down",
+			"--at",
+			(/* @__PURE__ */ new Date()).toISOString()
+		]);
+	} catch (err) {
+		try {
+			taskStore$1().remove(id);
+		} catch (cleanupErr) {
+			throw new Error(`claim failed: ${err instanceof Error ? err.message : err}; cleanup of ${id} also failed (frame left unclaimed): ${cleanupErr instanceof Error ? cleanupErr.message : cleanupErr}`);
+		}
+		throw err;
+	}
+}
+/** Descend: create a child frame under `opts.under` or the current leaf;
+*  `opts.root` forces a parentless frame even when a leaf is open. */
+function drillDown(title, opts = {}) {
+	let parent;
+	if (opts.under) parent = requireOpenDrill(opts.under, "--under").id;
+	else if (!opts.root) parent = currentFrame()?.id;
+	const row = taskStore$1().create({
+		title,
+		labels: [DRILL_LABEL],
+		parent,
+		ephemeral: opts.ephemeral,
+		type: opts.type,
+		priority: opts.priority,
+		description: opts.description
+	});
+	if (!opts.ephemeral) claimFrame(row.id);
+	return row;
+}
+/** Open prevention beads already discovered-from this frame — the
+* dedupe set that makes prevention creation retry-safe. Throws when bd
+* returns an unexpected row shape (e.g. dependency-edge objects instead
+* of hydrated issues): a wrong shape would mask as "no priors" and
+* silently resurrect the duplicate-on-retry bug this query prevents. */
+function priorPreventionRows(frameId) {
+	const rows = taskStore$1().deps([frameId], {
+		direction: "up",
+		type: "discovered-from"
+	});
+	assertHydratedRows(rows, `bd dep list for ${frameId}`);
+	return rows;
+}
+/** Fail loudly when a bd listing returns rows without `id`/`title`/`status` —
+* e.g. dependency-edge objects after a bd upgrade. `context` names the
+* query so the error identifies its source. Exported for tests. */
+function assertHydratedRows(rows, context) {
+	for (const row of rows) if (typeof row?.id !== "string" || typeof row?.title !== "string" || typeof row?.status !== "string") throw new Error(`${context} returned an unexpected row shape (expected hydrated issue rows): ${JSON.stringify(row).slice(0, 160)}`);
+}
+/** Same-title dedupe key: "handle race" and "  Handle Race " are the
+* same prevention — exact-match would duplicate the bead on retry. */
+function titleKey(title) {
+	return title.trim().toLowerCase();
+}
+/** Fold `--prevent` items against what the frame already recorded: an
+* open prevention bead with the same title is reused, not recreated;
+* repeated items within the list collapse to one bead. Pure — the
+* retry-safety core of drillUp: a mid-flight failure followed by a
+* retry converges instead of duplicating. */
+function planPreventions(items, prior) {
+	const reuse = /* @__PURE__ */ new Map();
+	for (const row of prior) {
+		const key = titleKey(row.title ?? "");
+		if (key && isOpen(row) && row.labels?.includes(PREVENTION_LABEL) && !reuse.has(key)) reuse.set(key, row.id);
+	}
+	const seen = /* @__PURE__ */ new Set();
+	const create = [];
+	for (const item of items) {
+		const key = titleKey(item);
+		if (!key || reuse.has(key) || seen.has(key)) continue;
+		seen.add(key);
+		create.push(item.trim());
+	}
+	return {
+		create,
+		reuse
+	};
+}
+/** One prevention bead per item — discovered-from, not --parent:
+* prevention is follow-up work found by the frame, and a child would
+* block the parent's own close. `--title` keeps a `--`-leading item as
+* data, not a flag. `created` holds only beads this call made — the
+* compensation set; `ids` is the full per-item result (reused + new). */
+function createPreventions(frameId, items) {
+	const { create, reuse } = planPreventions(items, priorPreventionRows(frameId));
+	const created = [];
+	const newIds = /* @__PURE__ */ new Map();
+	for (const item of create) {
+		const row = taskStore$1().create({
+			title: item,
+			labels: [PREVENTION_LABEL],
+			noInheritLabels: true,
+			deps: [`discovered-from:${frameId}`]
+		});
+		created.push(row.id);
+		newIds.set(titleKey(item), row.id);
+	}
+	const ids = [];
+	for (const item of items) {
+		const key = titleKey(item);
+		if (!key) continue;
+		const id = reuse.get(key) ?? newIds.get(key);
+		if (!id) throw new Error(`internal error: no bead id for prevention item "${item}"`);
+		ids.push(id);
+	}
+	return {
+		created,
+		ids
+	};
+}
+/** `bd note` appends — check the stored notes first so a retry after a
+* later failure can't duplicate the memo. */
+function noteOnce(frameId, memo) {
+	if (taskStore$1().get(frameId)?.notes?.includes(memo)) return;
+	taskStore$1().note(frameId, memo);
+}
+/** Evidence refs + handoff event — skipped for wisps (no audit trail).
+* Ref'd events are idempotent in bd (deterministic id); the ref-less
+* handoff gets a fresh `--at` each run, so skip it when already logged. */
+function recordHandoff(frame, evidence) {
+	for (const ref of evidence) {
+		const kind = refKind$1(ref);
+		bd$1([
+			"provenance",
+			"record",
+			"--issue",
+			frame.id,
+			"--kind",
+			evidenceKind(ref),
+			"--source",
+			"bro drill up",
+			"--ref",
+			ref,
+			"--ref-kind",
+			kind
+		]);
+	}
+	if (bdJson$1([
+		"provenance",
+		"log",
+		frame.id
+	]).some((e) => e.kind === "handoff" && e.source === "bro drill up")) return;
+	bd$1([
+		"provenance",
+		"record",
+		"--issue",
+		frame.id,
+		"--kind",
+		"handoff",
+		"--source",
+		"bro drill up",
+		"--at",
+		(/* @__PURE__ */ new Date()).toISOString()
+	]);
+}
+/**
+* Ascend: close the frame with a structured memo. `--result` is mandatory —
+* a drill that returns nothing teaches nothing. Each `--prevent` item lands
+* as a task on the parent frame so prevention work lives in the scope that
+* spawned it.
+*/
+function drillUp(opts) {
+	if (!opts.result.trim()) throw new Error("drill up requires --result — a frame must return a curated finding");
+	const frame = opts.id ? requireOpenDrill(opts.id, "--id") : (() => {
+		const leaf = currentFrame();
+		if (!leaf) throw new Error("no open drill frame — nothing to ascend from");
+		return requireOpenDrill(leaf.id, "--id");
+	})();
+	const openKids = childrenOf(frame.id).filter(isOpen);
+	if (openKids.length > 0) throw new Error(`frame ${frame.id} has open child issue(s): ${openKids.map((k) => k.id).join(", ")} — close them first`);
+	const prevents = (opts.prevent ?? []).map((p) => p.trim()).filter((p) => p !== "");
+	const memo = [
+		"## Result",
+		"",
+		opts.result,
+		...prevents.length ? [
+			"",
+			"## Prevention",
+			"",
+			...prevents.map((p) => `- ${p}`)
+		] : []
+	].join("\n");
+	let created = [];
+	let preventionIds = [];
+	try {
+		noteOnce(frame.id, memo);
+		const prev = createPreventions(frame.id, prevents);
+		created = prev.created;
+		preventionIds = prev.ids;
+		if (!frame.ephemeral) recordHandoff(frame, opts.evidence ?? []);
+		taskStore$1().close(frame.id, "drill up — result handed to parent");
+	} catch (err) {
+		const orphans = [];
+		for (const id of created) try {
+			taskStore$1().remove(id);
+		} catch {
+			orphans.push(id);
+		}
+		if (orphans.length === 0) throw err;
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new Error(`${msg} — cleanup incomplete: prevention bead(s) left behind: ${orphans.join(", ")}`, { cause: err });
+	}
+	return {
+		closed: frame.id,
+		preventionIds
+	};
+}
+/** Root frames + rendered tree (indented, roots first). */
+function drillTree() {
+	const rows = listDrills();
+	if (rows.length === 0) return "no drill frames";
+	const { kids, parents } = drillRelations(rows);
+	const roots = rows.filter((r) => !parents.has(r.id));
+	const lines = [];
+	const walk = (row, depth) => {
+		const mark = isOpen(row) ? "●" : "○";
+		lines.push(`${"  ".repeat(depth)}${mark} ${row.id} ${row.title} [${row.status}]`);
+		for (const kid of (kids.get(row.id) ?? []).filter(isDrill)) walk(kid, depth + 1);
+	};
+	for (const root of roots) walk(root, 0);
+	return lines.join("\n");
+}
+
+//#endregion
+//#region src/plan.ts
+/** The `kind` value a drill plan must carry — `bro run` routes on it. */
+const PLAN_KIND = "drill";
+const STEP_KEYS = new Set([
+	"title",
+	"under",
+	"ephemeral",
+	"description",
+	"priority",
+	"type"
+]);
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+const isPosInt = (v) => typeof v === "number" && Number.isInteger(v) && v > 0;
+const isInt = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+function checkStep(raw, where, errors) {
+	for (const key of Object.keys(raw)) if (!STEP_KEYS.has(key)) errors.push(`${where}: unknown key "${key}"`);
+	if (!nonEmpty(raw.title)) errors.push(`${where}: title is required`);
+	if (raw.under !== void 0 && !isInt(raw.under)) errors.push(`${where}: under must be a non-negative step index`);
+	for (const f of ["description", "type"]) if (raw[f] !== void 0 && typeof raw[f] !== "string") errors.push(`${where}: ${f} must be a string`);
+	if (raw.ephemeral !== void 0 && typeof raw.ephemeral !== "boolean") errors.push(`${where}: ephemeral must be a boolean`);
+	if (raw.priority !== void 0 && !isPosInt(raw.priority)) errors.push(`${where}: priority must be a positive integer`);
+}
+function parseStep(raw, i, errors) {
+	const where = `steps[${i}]`;
+	if (!isRecord(raw)) {
+		errors.push(`${where}: must be a table`);
+		return;
+	}
+	checkStep(raw, where, errors);
+	if (!nonEmpty(raw.title)) return;
+	return {
+		title: raw.title.trim(),
+		under: typeof raw.under === "number" ? raw.under : void 0,
+		ephemeral: raw.ephemeral === true ? true : void 0,
+		description: typeof raw.description === "string" ? raw.description : void 0,
+		priority: isPosInt(raw.priority) ? raw.priority : void 0,
+		type: typeof raw.type === "string" ? raw.type : void 0
+	};
+}
+/** Validate an already-parsed plan document — the plugin planSchema.
+*  Throws one error listing every problem. */
+function parseDrillPlan(doc, source = "plan") {
+	const errors = [];
+	if (!isRecord(doc)) throw new Error(`${source}: expected a TOML table`);
+	for (const key of Object.keys(doc)) if (key !== "steps" && key !== "kind" && key !== "title") errors.push(`unknown top-level key "${key}"`);
+	if (doc.kind !== void 0 && doc.kind !== PLAN_KIND) errors.push(`kind: expected "${PLAN_KIND}", got ${JSON.stringify(doc.kind)}`);
+	if (!nonEmpty(doc.title)) errors.push("title: the root frame title is required");
+	const steps = [];
+	if (doc.steps !== void 0 && !Array.isArray(doc.steps)) errors.push("steps: must be an array of tables ([[steps]])");
+	else if (Array.isArray(doc.steps)) doc.steps.forEach((raw, i) => {
+		const s = parseStep(raw, i, errors);
+		if (!s) return;
+		if (s.under !== void 0 && s.under >= steps.length) errors.push(`steps[${i}]: under must index a previous step`);
+		steps.push(s);
+	});
+	if (errors.length > 0) throw new Error(`${source}:\n  ${errors.join("\n  ")}`);
+	return {
+		title: doc.title.trim(),
+		steps
+	};
+}
+
+//#endregion
+//#region src/connector.ts
+/** The open-frame line, or null — the same text every surface shares. */
+function frameLine() {
+	try {
+		const frame = currentFrame();
+		if (!frame) return null;
+		return `drill frame open: ${frame.id} "${frame.title}" [depth=${frame.depth}] — close with \`bro drill up --result "…"\``;
+	} catch {
+		return null;
+	}
+}
+const drillConnector = {
+	name: "drill",
+	hooks: () => ({
+		sessionStart() {
+			const line = frameLine();
+			return line ? [line] : [];
+		},
+		promptSubmit() {
+			const line = frameLine();
+			return line ? [line] : [];
+		},
+		stopGate() {
+			const line = frameLine();
+			if (!line) return [];
+			return [{
+				aspect: "drill",
+				block: `bro: ${line}`,
+				passive: `bro: ${line} (opened outside this session — informational)`
+			}];
+		}
+	})
+};
+
+//#endregion
+export { PLAN_KIND as DRILL_PLAN_KIND, bd, bdJson, checkBeads, childrenOf, currentFrame, drillConnector, drillDown, drillTree, drillUp, listDrills, parseDrillPlan, planPreventions, refKind, taskStore };

package/package.json

@@ -1,16 +1,47 @@
 {
-  "description": "Placeholder for @broject/drill published by @nx-devkit/prepare-for-release.",
-  "license": "MIT",
   "name": "@broject/drill",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+  "version": "0.2.3",
+  "type": "module",
+  "dependencies": {
+    "@broject/core": "^0.2.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "tsx --test src/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsdown": "^0.15.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0",
+    "smol-toml": "1.7.1"
   },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ThePlenkov/bro.git",
     "directory": "packages/drill"
   },
-  "type": "module",
-  "version": "0.0.0"
-}
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Scoped descent frames for bro — drill down/up over beads with result + prevention memos",
+  "keywords": [
+    "beads",
+    "investigation",
+    "agent",
+    "bro"
+  ],
+  "homepage": "https://broject.dev/docs"
+}