process-graph 1.3.0 → 1.4.0

package/dist/{dist-BI01yxFA.js → dist-C8zDuW-y.js}

@@ -1,19 +1,21 @@
 import { a as validateOverlay, d as overlayStatuses, f as participantKinds } from "./schema-BPT8fmfa.js";
 import { t as validate } from "./validate-DF3mQZww.js";
-import { n as parseModel, t as ModelParseError } from "./parse-C1Q1zsGt.js";
+import { f as terminalJson, h as parseModel, m as ModelParseError, n as viewText, p as terminalText } from "./view-DTeNUhGG.js";
 import { c as deriveStatuses, f as toStateMachine, g as handoffs, h as toFlowchart, i as readySet, n as criticalPath, p as toSwimlane, r as impact, s as explainStatus, t as blockedBy, u as toSequence } from "./queries-C8kIDRiY.js";
 import { S as UnknownNodeError, f as layeredFacts, n as illegalCycles, u as factsFrom, x as CycleError } from "./control-DiygoEhm.js";
-import { l as assembleSync, t as createGitHubIssuesSource, u as createGraphSourceRouter } from "./source-D51N7K3A.js";
+import { r as filterStates, s as orderFields } from "./schema-DVAttrJg.js";
+import { l as createGraphSourceRouter, t as createGitHubIssuesSource } from "./source-lTKshktI.js";
 import { t as GraphSourceError } from "./errors-BZe5WzCn.js";
 import { t as githubTokenFromEnvironment } from "./node-AchI1T-K.js";
 import { g as emptyModel } from "./store-DKzvLGgl.js";
 import { t as createGraphStoreRouter } from "./router-Dk91O_9p.js";
 import { i as openNodeGraphStore, t as prepareDataFile } from "./data-file-BVMxkTug.js";
+import { a as scopesBySource, i as InvalidScopeError, n as UnknownSourceError, r as syncScopes, t as InterruptedSyncError } from "./sync-CkaJO3OQ.js";
 import { t as exitCodes } from "./exit-codes-0ultCqdS.js";
 import { ORPCError, createRouterClient } from "@orpc/server";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { Argument, Command, CommanderError, Option } from "commander";
+import { Argument, Command, CommanderError, InvalidArgumentError, Option } from "commander";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 //#region ../graph-cli/dist/errors.js
@@ -417,6 +419,150 @@ const why = async (session, id) => {
 		chain
 	};
 };
+/**
+* An element's direct sub-tasks, from the `child-of` relations a sync keeps, as the store's hierarchy query answers.
+* @param session - The store and model.
+* @param id - The element asked about.
+* @throws CliError with `notFound` when the model or the element does not exist.
+*/
+const children = async (session, id) => {
+	const { model } = await loadRun(session);
+	const element = requireElement(model, id);
+	const found = await session.store.v1.query.children({
+		modelId: session.modelId,
+		element: id
+	}, callOptions(session.signal));
+	return {
+		element: {
+			id,
+			label: labelOf(element)
+		},
+		children: summarise(model, found.children)
+	};
+};
+/**
+* The elements an element is a sub-task of, nearest first, from the `child-of` relations a sync keeps, as the store's hierarchy query answers.
+* @param session - The store and model.
+* @param id - The element asked about.
+* @throws CliError with `notFound` when the model or the element does not exist.
+*/
+const ancestors = async (session, id) => {
+	const { model } = await loadRun(session);
+	const element = requireElement(model, id);
+	const found = await session.store.v1.query.ancestors({
+		modelId: session.modelId,
+		element: id
+	}, callOptions(session.signal));
+	return {
+		element: {
+			id,
+			label: labelOf(element)
+		},
+		ancestors: found.ancestors.map((link) => ({
+			id: link.element,
+			label: labelOf(requireElement(model, link.element)),
+			distance: link.distance
+		}))
+	};
+};
+//#endregion
+//#region ../graph-cli/dist/sync.js
+/** The short direction names the command line takes for an order's direction. */
+const directionNames = {
+	asc: "ascending",
+	desc: "descending"
+};
+/**
+* Thrown by `sync` when a source fails part way. Its exit status and message are the source's failure, classified as `failureOf` classifies it; its cause is the error underneath that failure, such as the token port's own error; and what to run next is data, in `resume` and `remaining`, never text.
+*/
+var SyncInterruptedError = class extends CliError {
+	resume;
+	remaining;
+	saved;
+	/**
+	* @param exitCode - The exit status the source's failure maps to.
+	* @param message - The source's failure.
+	* @param interruption - Where the sync carries on.
+	* @param options - The underlying error, kept as the cause.
+	*/
+	constructor(exitCode, message, interruption, options) {
+		super(exitCode, message, options);
+		this.name = "SyncInterruptedError";
+		this.resume = interruption.resume;
+		this.remaining = interruption.remaining;
+		this.saved = interruption.saved;
+	}
+};
+/** A usage error for a scope that names no source or a source nothing reads, or nothing for any other error. */
+const usageError = (error) => {
+	if (error instanceof InvalidScopeError) return new CliError(exitCodes.usage, error.message, { cause: error });
+	if (error instanceof UnknownSourceError) return new CliError(exitCodes.usage, `no source reads "${error.prefix}" scopes`, { cause: error });
+};
+/**
+* Reads every page of the scopes from their sources and merges each into the session's model as it is read, creating the model when the store has none: participants, bound activities, transitions, relations (sub-issues, assignees, repository membership) and run state. Records already in the model are replaced by identifier and the rest are kept, so syncing again refreshes what changed.
+*
+* When a source fails part way, the pages read before the failure are already written, and the error carries where to carry on: the request that resumes the failing source after the cursor of its last page read, and the scopes of the sources not reached.
+* @param session - The store and model.
+* @param sources - The source for each identifier prefix.
+* @param request - The scopes, a cursor to resume after, and a filter.
+* @returns What was written, and the gaps the sources reported.
+* @throws CliError with `usage` for a scope with no source prefix, a prefix no source serves, or `after` with scopes of more than one source; and SyncInterruptedError, with the source's failure and where to carry on, when a source fails part way.
+*/
+const sync = async (session, sources, request) => {
+	const { scopes, after, filter } = request;
+	let groups;
+	try {
+		groups = scopesBySource(scopes);
+	} catch (error) {
+		throw usageError(error) ?? error;
+	}
+	const [first] = groups;
+	if (after !== void 0 && groups.length > 1) throw new CliError(exitCodes.usage, "--after resumes one source's sync: give only that source's scopes");
+	const resume = after === void 0 || first === void 0 ? void 0 : {
+		modelId: session.modelId,
+		scopes,
+		...filter === void 0 ? {} : { filter },
+		source: first.prefix,
+		after
+	};
+	try {
+		const result = await syncScopes({
+			store: session.store,
+			sources,
+			modelId: session.modelId,
+			scopes,
+			filter,
+			resume,
+			signal: session.signal
+		});
+		return {
+			modelId: session.modelId,
+			revision: result.revision,
+			participants: result.participants,
+			activities: result.activities,
+			transitions: result.transitions,
+			relations: result.relations,
+			gaps: result.gaps
+		};
+	} catch (error) {
+		const usage = usageError(error);
+		if (usage !== void 0) throw usage;
+		if (!(error instanceof InterruptedSyncError)) throw error;
+		const failure = failureOf(error.cause);
+		const { resume: from, remaining, saved } = error;
+		const failing = groups.find((group) => group.prefix === from.source);
+		if (failing === void 0) throw new Error(`unreachable: the interrupted source "${from.source}" is one of the sync's own`, { cause: error });
+		throw new SyncInterruptedError(failure.exitCode, failure.message, {
+			resume: {
+				scopes: failing.scopes,
+				...from.after === void 0 ? {} : { after: from.after },
+				...filter === void 0 ? {} : { filter }
+			},
+			remaining,
+			saved
+		}, { cause: underlyingCause(error.cause) });
+	}
+};
 //#endregion
 //#region ../graph-cli/dist/render.js
 /**
@@ -430,6 +576,10 @@ const renderReady = (result) => lines(elementRows(result.elements));
 const renderBlocked = (result) => lines(elementRows(result.blockedBy));
 /** `impact`: each element that depends on the one asked about. */
 const renderImpact = (result) => lines(elementRows(result.impacted));
+/** `children`: each direct sub-task's identifier and label. */
+const renderChildren = (result) => lines(elementRows(result.children));
+/** `ancestors`: each element above the one asked about, nearest first, with its distance. */
+const renderAncestors = (result) => lines(result.ancestors.map((link) => `${link.id}\t${link.label}\t${String(link.distance)}`));
 /** `path`: the critical path, one element per line in dependency order. */
 const renderPath = (result) => lines(elementRows(result.path));
 /** `cycles`: each illegal cycle as a closed path. */
@@ -481,7 +631,17 @@ const renderSetFact = (result) => lines([`set fact ${result.fact} to ${result.va
 /** `facts`: each recorded artefact as `artefact`, its id and `provided` or `absent`, then each named fact as `fact`, its name and its value, each sorted by id or name. */
 const renderFacts = (result) => lines([...Object.entries(result.facts.artefacts).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([id, provided]) => `artefact\t${id}\t${provided ? "provided" : "absent"}`), ...Object.entries(result.facts.values).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([name, value]) => `fact\t${name}\t${valueText(value)}`)]);
 /** `sync`: what was written, then each gap as its reason, target and message. */
-const renderSync = (result) => lines([`synced ${String(result.activities)} activities, ${String(result.transitions)} transitions and ${String(result.participants)} participants into "${result.modelId}" at revision ${String(result.revision)}`, ...result.gaps.map((gap) => `gap\t${gap.reason}\t${gap.target}\t${gap.message}`)]);
+const renderSync = (result) => lines([`synced ${String(result.activities)} activities, ${String(result.transitions)} transitions, ${String(result.relations)} relations and ${String(result.participants)} participants into "${result.modelId}" at revision ${String(result.revision)}`, ...result.gaps.map((gap) => `gap\t${gap.reason}\t${gap.target}\t${gap.message}`)]);
+/**
+* The `sync` options that give a filter, as they would be typed again to resume under it, since a cursor is valid only under the filter it was issued with.
+* @param filter - The filter, if any.
+* @returns The options, each with a leading space, or the empty string.
+*/
+const filterOptions = (filter) => [
+	...(filter?.states ?? []).map((state) => ` --state ${state}`),
+	...(filter?.labels ?? []).map((label) => ` --label ${label}`),
+	...filter?.order === void 0 ? [] : [` --order ${filter.order.field} --direction ${filter.order.direction === directionNames.desc ? "desc" : "asc"}`]
+].join("");
 /**
 * A sync a source interrupted: the source's failure, whether the pages read before it were saved, and the commands that carry on, `resume with: sync <scopes> --after <cursor>` for the failing source and `then: sync <scopes>` for the sources not reached.
 * @param message - The source's failure.
@@ -493,333 +653,13 @@ const renderSyncInterruption = (message, interruption) => {
 	return [
 		message,
 		...saved ? ["the pages read before the failure are saved"] : [],
-		`resume with: sync ${resume.scopes.join(" ")}${resume.after === void 0 ? "" : ` --after ${resume.after}`}`,
-		...remaining.length === 0 ? [] : [`then: sync ${remaining.join(" ")}`]
+		`resume with: sync ${resume.scopes.join(" ")}${resume.after === void 0 ? "" : ` --after ${resume.after}`}${filterOptions(resume.filter)}`,
+		...remaining.length === 0 ? [] : [`then: sync ${remaining.join(" ")}${filterOptions(resume.filter)}`]
 	].join("\n");
 };
 /** `validate`: `valid`, or each issue as its code, its JSON pointer when it has one, and its message. */
 const renderValidate = (result) => result.valid ? lines(["valid"]) : lines(result.issues.map((issue) => issue.pointer === void 0 ? `${issue.code}\t${issue.message}` : `${issue.code}\t${issue.pointer === "" ? "/" : issue.pointer}\t${issue.message}`));
 //#endregion
-//#region ../graph-cli/dist/terminal-text.js
-/**
-* The characters that must never reach a terminal as they are, by Unicode general category: controls (`Cc`, where ESC starts the sequences that clear the screen, move the cursor or, through OSC 52, set the clipboard, and the C1 controls some terminals read as the same sequences), format characters (`Cf`, which holds every bidirectional control, the invisible operators, the soft hyphen, the interlinear annotation characters and the tag characters, all of which reorder, hide or change what is shown), the line and paragraph separators (`Zl`, `Zp`), and the unassigned and private-use code points (`Cn`, `Co`), which no font shows reliably. Text from a source (an issue title, a label, an actor's name) can carry any of them. A category, not a list of ranges, so a character Unicode adds to one of them is covered without a change here.
-*
-* Three are allowed: line feed and tab, which every text output uses, and the zero-width non-joiner and joiner (U+200C, U+200D), formats that emoji sequences (a family, a profession) and scripts such as Persian, Hindi and Malayalam need to be written correctly, and that cannot reorder or hide text on their own.
-*/
-const unsafeCharacters = /[[\p{Cc}\p{Cf}\p{Zl}\p{Zp}\p{Cn}\p{Co}]--[\n\t\u200C\u200D]]/gv;
-/** Code points are written in hexadecimal. */
-const hexadecimal = 16;
-/** A JSON `\u` escape always has four hexadecimal digits. */
-const jsonEscapeDigits = 4;
-/**
-* A character's code point.
-* @param character - One character, as the unsafe-character pattern matches it.
-* @returns Its code point.
-* @throws Error when given an empty string, which the pattern never matches.
-*/
-const codePointOf = (character) => {
-	const point = character.codePointAt(0);
-	if (point === void 0) throw new Error("an unsafe character match was empty");
-	return point;
-};
-/**
-* Text made safe to write to a terminal. Each unsafe character (see `unsafeCharacters`) is written as the visible escape `\u{<hex>}` of its code point, such as `\u{1b}` for ESC, `\u{202e}` for a right-to-left override or `\u{e0041}` for a tag character, so nothing is lost and nothing acts on the terminal. Line feed, tab, the zero-width joiners and every other character, accented letters, CJK, Arabic and emoji included, pass through. A literal `\u{...}` already in the text is left as it is, so the escaped form is for reading, not for reversing.
-* @param text - The text as written.
-* @returns The text with every unsafe character escaped.
-*/
-const terminalText = (text) => text.replaceAll(unsafeCharacters, (character) => `\\u{${codePointOf(character).toString(hexadecimal)}}`);
-/**
-* A value as JSON that is also safe to write to a terminal. `JSON.stringify` escapes the C0 controls but writes every other unsafe character (see `unsafeCharacters`) as it is; this writes those as `\u` escapes too, a surrogate pair for a code point beyond the Basic Multilingual Plane, which leaves the JSON, and every value parsed from it, exactly the same.
-* @param value - The value to write.
-* @returns The JSON text, indented by two spaces and ending in a line break.
-*/
-const terminalJson = (value) => `${JSON.stringify(value, null, 2).replaceAll(unsafeCharacters, (character) => character.split("").map((unit) => `\\u${unit.charCodeAt(0).toString(hexadecimal).padStart(jsonEscapeDigits, "0")}`).join(""))}\n`;
-//#endregion
-//#region ../graph-cli/dist/emit/text.js
-/**
-* The Mermaid entity code for a character that would end or change the meaning of a label: quotes, statement and edge-label delimiters, the entity marker itself and HTML.
-*/
-const mermaidEntity = (character) => {
-	switch (character) {
-		case "#": return "#35;";
-		case "\"": return "#quot;";
-		case "<": return "#lt;";
-		case ">": return "#gt;";
-		case "&": return "#amp;";
-		case ";": return "#59;";
-		case "|": return "#124;";
-		case ":": return "#58;";
-		default: return character;
-	}
-};
-/**
-* Text made safe to place inside any Mermaid label: a line break becomes a space, every control and invisible format character is written as its visible `\u{<hex>}` escape (see `terminalText`), and every character that Mermaid reads as syntax is written as its entity code, so a label from a source (an issue title, a repository name) can never break the diagram or act on the terminal it is printed to.
-* @param text - The label as written.
-* @returns The label as Mermaid source.
-*/
-const mermaidText = (text) => terminalText(text.replaceAll(/[\r\n]/gu, " ")).replaceAll(/[#"<>&;|:]/gu, mermaidEntity);
-/**
-* A Graphviz DOT double-quoted string: line breaks written as DOT's own centred line break, every control and invisible format character as its visible `\u{<hex>}` escape (see `terminalText`), then backslashes, the escapes' included, and quotes escaped. Any identifier or label is valid DOT once quoted this way, and reads back as the escaped text.
-* @param text - The text as written.
-* @returns The quoted DOT string, quotes included.
-*/
-const dotString = (text) => `"${text.split(/\r?\n/u).map((line) => terminalText(line).replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")).join("\\n")}"`;
-//#endregion
-//#region ../graph-cli/dist/emit/mermaid.js
-/**
-* Model identifiers are free text (`github:org/repo#12`), which Mermaid does not accept as a node identifier, so every emitter names things by position in the view instead: a prefix and the index. The view's order is the model's order, so the same model always gives the same names.
-*/
-const positionalIds = (prefix, ids) => new Map(ids.map((id, index) => [id, `${prefix}${String(index)}`]));
-/** Reads a name the emitter itself assigned, which exists for every identifier the view lists. */
-const nameIn = (names, id) => {
-	const name = names.get(id);
-	if (name === void 0) throw new Error(`"${id}" is not part of the view being emitted`);
-	return name;
-};
-const indent$1 = "  ";
-/** Each flowchart shape in Mermaid's syntax around a node name and quoted label: a stadium for a terminator, a rectangle for a process, a rhombus for a decision and a fork bar for a fork or join. */
-const mermaidShapes = {
-	terminator: (name, label) => `${name}(["${label}"])`,
-	process: (name, label) => `${name}["${label}"]`,
-	decision: (name, label) => `${name}{"${label}"}`,
-	bar: (name, label) => `${name}@{ shape: fork, label: "${label}" }`
-};
-const mermaidNode = (name, node) => mermaidShapes[node.shape](name, mermaidText(node.label));
-/** The edges of a flowchart, a hand-off (an edge whose ends are in different lanes) drawn thick. */
-const mermaidEdges = (view, names, isHandoff) => view.edges.map((edge) => {
-	const arrow = isHandoff(edge.from, edge.to) ? "==>" : "-->";
-	const label = edge.label === void 0 ? "" : `|"${mermaidText(edge.label)}"|`;
-	return `${indent$1}${nameIn(names, edge.from)} ${arrow}${label} ${nameIn(names, edge.to)}`;
-});
-/**
-* A flowchart as a Mermaid `flowchart`, top to bottom. Nodes are declared in the view's order, then edges, each with its guard as the edge label.
-* @param view - The projected flowchart.
-* @returns Mermaid source, ending with a line break.
-*/
-const flowchartToMermaid = (view) => {
-	const names = positionalIds("n", view.nodes.map((node) => node.id));
-	return `${[
-		"flowchart TD",
-		...view.nodes.map((node) => `${indent$1}${mermaidNode(nameIn(names, node.id), node)}`),
-		...mermaidEdges(view, names, () => false)
-	].join("\n")}\n`;
-};
-/**
-* A swimlane as a Mermaid `flowchart`, left to right, with one subgraph per lane in the view's lane order (an empty lane is an empty subgraph, so it stays visible) and nodes with no actor outside every lane. Hand-offs, the edges that change lane, are drawn thick.
-* @param view - The projected swimlane.
-* @returns Mermaid source, ending with a line break.
-*/
-const swimlaneToMermaid = (view) => {
-	const names = positionalIds("n", view.nodes.map((node) => node.id));
-	const nodes = new Map(view.nodes.map((node) => [node.id, node]));
-	const laneOf = /* @__PURE__ */ new Map();
-	view.lanes.forEach((lane, index) => {
-		for (const id of lane.nodes) laneOf.set(id, index);
-	});
-	const declare = (id, depth) => {
-		const node = nodes.get(id);
-		if (node === void 0) throw new Error(`lane member "${id}" is not a node of the view`);
-		return `${depth}${mermaidNode(nameIn(names, id), node)}`;
-	};
-	return `${[
-		"flowchart LR",
-		...view.lanes.flatMap((lane, index) => [
-			`${indent$1}subgraph lane${String(index)}["${mermaidText(lane.label)}"]`,
-			...lane.nodes.map((id) => declare(id, indent$1.repeat(2))),
-			`${indent$1}end`
-		]),
-		...view.unassigned.map((id) => declare(id, indent$1)),
-		...mermaidEdges(view, names, (from, to) => {
-			const fromLane = laneOf.get(from);
-			const toLane = laneOf.get(to);
-			return fromLane !== void 0 && toLane !== void 0 && fromLane !== toLane;
-		})
-	].join("\n")}\n`;
-};
-/** A state machine transition's label: its event, its guard in brackets and its effect after a slash, each only when present. */
-const transitionLabel = (transition) => [
-	transition.event,
-	transition.guard === void 0 ? void 0 : `[${transition.guard}]`,
-	transition.effect === void 0 ? void 0 : `/ ${transition.effect}`
-].filter((part) => part !== void 0).join(" ");
-/**
-* A state machine as a Mermaid `stateDiagram-v2`. Initial and final pseudo-states are Mermaid's `[*]`; every other state is declared with its label. Each transition carries its event, guard and effect.
-* @param view - The projected state machine.
-* @returns Mermaid source, ending with a line break.
-*/
-const stateMachineToMermaid = (view) => {
-	const drawn = view.states.filter((state) => state.role === "state");
-	const names = new Map([...positionalIds("s", drawn.map((state) => state.id)), ...view.states.filter((state) => state.role !== "state").map((state) => [state.id, "[*]"])]);
-	return `${[
-		"stateDiagram-v2",
-		...drawn.map((state) => `${indent$1}state "${mermaidText(state.label)}" as ${nameIn(names, state.id)}`),
-		...view.transitions.map((transition) => {
-			const label = transitionLabel(transition);
-			return `${indent$1}${nameIn(names, transition.source)} --> ${nameIn(names, transition.target)}${label === "" ? "" : ` : ${mermaidText(label)}`}`;
-		})
-	].join("\n")}\n`;
-};
-/** The Mermaid keyword that separates one operand of a fragment from the next, for the operators with more than one operand. */
-const operandSeparator = (operator) => operator === "par" ? "and" : "else";
-/**
-* A sequence diagram as a Mermaid `sequenceDiagram`. Lifelines are declared in order of first appearance, labelled through `participantLabel`; messages follow in scenario order, wrapped in the fragments the projection drew (`alt` operands separated by `else`, `par` operands by `and`), each operand headed by its guard.
-* @param view - The projected sequence diagram.
-* @param participantLabel - The label of a lifeline's participant.
-* @returns Mermaid source, ending with a line break.
-*/
-const sequenceToMermaid = (view, participantLabel) => {
-	const names = positionalIds("p", view.lifelines);
-	const items = (list, depth) => list.flatMap((item) => {
-		const prefix = indent$1.repeat(depth);
-		if (item.kind === "message") {
-			const { message } = item;
-			return [`${prefix}${nameIn(names, message.from)}->>${nameIn(names, message.to)}: ${mermaidText(message.label)}`];
-		}
-		return [...item.operands.flatMap((operand, index) => {
-			const keyword = index === 0 ? item.operator : operandSeparator(item.operator);
-			const guard = operand.guard === void 0 ? "" : ` ${mermaidText(operand.guard)}`;
-			return [`${prefix}${keyword}${guard}`, ...items(operand.items, depth + 1)];
-		}), `${prefix}end`];
-	});
-	return `${[
-		"sequenceDiagram",
-		...view.lifelines.map((lifeline) => `${indent$1}participant ${nameIn(names, lifeline)} as ${mermaidText(participantLabel(lifeline))}`),
-		...items(view.items, 1)
-	].join("\n")}\n`;
-};
-//#endregion
-//#region ../graph-cli/dist/emit/dot.js
-const indent = "  ";
-/** A DOT attribute list from name and value pairs, each value quoted; empty when there are none. */
-const attributes = (pairs) => pairs.length === 0 ? "" : ` [${pairs.map(([name, value]) => `${name}=${dotString(value)}`).join(", ")}]`;
-/** A flowchart node's DOT shape: an oval terminator, a box process, a diamond decision, and a filled bar for a fork or join. */
-const nodeShapes = {
-	terminator: [["shape", "oval"]],
-	process: [["shape", "box"]],
-	decision: [["shape", "diamond"]],
-	bar: [
-		["shape", "box"],
-		["style", "filled"],
-		["fillcolor", "black"],
-		["fontcolor", "white"]
-	]
-};
-const dotNode = (node, depth) => `${depth}${dotString(node.id)}${attributes([["label", node.label], ...nodeShapes[node.shape]])};`;
-/** The edges of a flowchart, a hand-off (an edge whose ends are in different lanes) drawn bold. */
-const dotEdges = (view, isHandoff) => view.edges.map((edge) => `${indent}${dotString(edge.from)} -> ${dotString(edge.to)}${attributes([...edge.label === void 0 ? [] : [["label", edge.label]], ...isHandoff(edge.from, edge.to) ? [["style", "bold"]] : []])};`);
-/**
-* A flowchart as a Graphviz `digraph`, top to bottom. Nodes are named by their model identifiers, so the DOT source reads back to the model directly.
-* @param view - The projected flowchart.
-* @returns DOT source, ending with a line break.
-*/
-const flowchartToDot = (view) => `${[
-	`digraph ${dotString("flowchart")} {`,
-	`${indent}rankdir="TB";`,
-	...view.nodes.map((node) => dotNode(node, indent)),
-	...dotEdges(view, () => false),
-	"}"
-].join("\n")}\n`;
-/**
-* A swimlane as a Graphviz `digraph`, left to right, with one `cluster` subgraph per lane in the view's lane order and nodes with no actor outside every lane. An empty lane holds one invisible point so Graphviz still draws it. Hand-offs, the edges that change lane, are drawn bold.
-* @param view - The projected swimlane.
-* @returns DOT source, ending with a line break.
-*/
-const swimlaneToDot = (view) => {
-	const nodes = new Map(view.nodes.map((node) => [node.id, node]));
-	const laneOf = /* @__PURE__ */ new Map();
-	view.lanes.forEach((lane, index) => {
-		for (const id of lane.nodes) laneOf.set(id, index);
-	});
-	const declare = (id, depth) => {
-		const node = nodes.get(id);
-		if (node === void 0) throw new Error(`lane member "${id}" is not a node of the view`);
-		return dotNode(node, depth);
-	};
-	return `${[
-		`digraph ${dotString("swimlane")} {`,
-		`${indent}rankdir="LR";`,
-		...view.lanes.flatMap((lane, index) => {
-			const cluster = `cluster_lane${String(index)}`;
-			return [
-				`${indent}subgraph ${dotString(cluster)} {`,
-				`${indent.repeat(2)}label=${dotString(lane.label)};`,
-				...lane.nodes.length === 0 ? [`${indent.repeat(2)}${dotString(`${cluster}:empty`)}${attributes([["shape", "point"], ["style", "invis"]])};`] : lane.nodes.map((id) => declare(id, indent.repeat(2))),
-				`${indent}}`
-			];
-		}),
-		...view.unassigned.map((id) => declare(id, indent)),
-		...dotEdges(view, (from, to) => {
-			const fromLane = laneOf.get(from);
-			const toLane = laneOf.get(to);
-			return fromLane !== void 0 && toLane !== void 0 && fromLane !== toLane;
-		}),
-		"}"
-	].join("\n")}\n`;
-};
-/** A state's DOT shape: a filled point for an initial pseudo-state, a double circle for a final one, a rounded box for a state. */
-const stateShape = (state) => {
-	if (state.role === "initial") return [["label", ""], ["shape", "point"]];
-	if (state.role === "final") return [["label", ""], ["shape", "doublecircle"]];
-	return [
-		["label", state.label],
-		["shape", "box"],
-		["style", "rounded"]
-	];
-};
-/**
-* A state machine as a Graphviz `digraph`, left to right. Each transition is labelled with its event, guard and effect.
-* @param view - The projected state machine.
-* @returns DOT source, ending with a line break.
-*/
-const stateMachineToDot = (view) => `${[
-	`digraph ${dotString("state machine")} {`,
-	`${indent}rankdir="LR";`,
-	...view.states.map((state) => `${indent}${dotString(state.id)}${attributes(stateShape(state))};`),
-	...view.transitions.map((transition) => {
-		const label = transitionLabel(transition);
-		return `${indent}${dotString(transition.source)} -> ${dotString(transition.target)}${attributes(label === "" ? [] : [["label", label]])};`;
-	}),
-	"}"
-].join("\n")}\n`;
-const placeMessages = (items, fragments) => items.flatMap((item) => item.kind === "message" ? [{
-	message: item.message,
-	fragments
-}] : item.operands.flatMap((operand) => placeMessages(operand.items, [...fragments, operand.guard === void 0 ? item.operator : `${item.operator} [${operand.guard}]`])));
-/**
-* A sequence diagram as a Graphviz `digraph`. DOT has no sequence notation, so the diagram is drawn as a grid: a column per lifeline, headed by its participant's label, with one row per message in scenario order. Each message is an arrow across its row, numbered by its step and prefixed with the fragments around it (operator and guard, outermost first), since DOT cannot draw a box around arrows.
-* @param view - The projected sequence diagram.
-* @param participantLabel - The label of a lifeline's participant.
-* @returns DOT source, ending with a line break.
-*/
-const sequenceToDot = (view, participantLabel) => {
-	const columns = new Map(view.lifelines.map((lifeline, index) => [lifeline, index]));
-	const column = (lifeline) => {
-		const index = columns.get(lifeline);
-		if (index === void 0) throw new Error(`"${lifeline}" is not a lifeline of the view`);
-		return index;
-	};
-	const head = (index) => dotString(`p${String(index)}`);
-	const cell = (index, row) => dotString(`p${String(index)}.${String(row)}`);
-	const placed = placeMessages(view.items, []);
-	const rows = placed.map((_, row) => row + 1);
-	const pointAttributes = attributes([["shape", "point"], ["width", "0"]]);
-	return `${[
-		`digraph ${dotString("sequence")} {`,
-		`${indent}rankdir="TB";`,
-		...view.lifelines.map((lifeline, index) => `${indent}${head(index)}${attributes([["label", participantLabel(lifeline)], ["shape", "box"]])};`),
-		`${indent}{ rank="same"; ${view.lifelines.map((_, index) => `${head(index)};`).join(" ")} }`,
-		...view.lifelines.slice(1).map((_, index) => `${indent}${head(index)} -> ${head(index + 1)}${attributes([["style", "invis"]])};`),
-		...rows.flatMap((row) => [...view.lifelines.map((_, index) => `${indent}${cell(index, row)}${pointAttributes};`), `${indent}{ rank="same"; ${view.lifelines.map((_, index) => `${cell(index, row)};`).join(" ")} }`]),
-		...rows.length === 0 ? [] : view.lifelines.map((_, index) => `${indent}${[head(index), ...rows.map((row) => cell(index, row))].join(" -> ")}${attributes([["style", "dashed"], ["arrowhead", "none"]])};`),
-		...placed.map(({ message, fragments }, index) => {
-			const row = index + 1;
-			const text = fragments.length === 0 ? message.label : `${fragments.join(" / ")}: ${message.label}`;
-			return `${indent}${cell(column(message.from), row)} -> ${cell(column(message.to), row)}${attributes([["label", `${String(row)}. ${text}`], ["constraint", "false"]])};`;
-		}),
-		"}"
-	].join("\n")}\n`;
-};
-//#endregion
 //#region ../graph-cli/dist/show.js
 /** The views `show` draws, as named on the command line. */
 const viewNames = [
@@ -828,7 +668,7 @@ const viewNames = [
 	"state",
 	"sequence"
 ];
-/** The formats `show` writes. */
+/** The formats `show` writes, graph-export's, with JSON named first. */
 const formatNames = [
 	"json",
 	"mermaid",
@@ -875,22 +715,33 @@ const project = (model, request) => {
 		projection: toSequence(model, scenarioOf(model, request.scenario))
 	};
 };
+/** A view as `show` names it, as the projection layer names its notation. */
+const notationViewOf = (projected) => {
+	if (projected.view === "flowchart") return {
+		notation: "flowchart",
+		view: projected.projection
+	};
+	if (projected.view === "swimlane") return {
+		notation: "swimlane",
+		view: projected.projection
+	};
+	if (projected.view === "state") return {
+		notation: "stateMachine",
+		view: projected.projection
+	};
+	return {
+		notation: "sequence",
+		view: projected.projection
+	};
+};
 /**
-* Writes a projected view as Mermaid or DOT source.
+* Writes a projected view as Mermaid or DOT source, or as JSON, through graph-export's `viewText`, the writer the web app's downloads use too.
 * @param model - The model, for participant labels.
 * @param projected - The view.
-* @param format - `mermaid` or `dot`.
-* @returns The diagram source.
+* @param format - `mermaid`, `dot` or `json`.
+* @returns The text.
 */
-const emit = (model, projected, format) => {
-	const labels = new Map(model.participants.map((participant) => [participant.id, participant.label]));
-	const participantLabel = (id) => labels.get(id) ?? id;
-	const mermaid = format === "mermaid";
-	if (projected.view === "flowchart") return mermaid ? flowchartToMermaid(projected.projection) : flowchartToDot(projected.projection);
-	if (projected.view === "swimlane") return mermaid ? swimlaneToMermaid(projected.projection) : swimlaneToDot(projected.projection);
-	if (projected.view === "state") return mermaid ? stateMachineToMermaid(projected.projection) : stateMachineToDot(projected.projection);
-	return mermaid ? sequenceToMermaid(projected.projection, participantLabel) : sequenceToDot(projected.projection, participantLabel);
-};
+const emit = (model, projected, format) => viewText(model, notationViewOf(projected), format);
 /**
 * Draws the session's model as a view in a format.
 * @param session - The store and model.
@@ -899,7 +750,7 @@ const emit = (model, projected, format) => {
 const show = async (session, request) => {
 	const { model } = await loadRun(session);
 	const projected = project(model, request);
-	const text = request.format === "json" ? `${JSON.stringify(projected.projection, null, 2)}\n` : emit(model, projected, request.format);
+	const text = emit(model, projected, request.format);
 	return {
 		...projected,
 		format: request.format,
@@ -907,130 +758,6 @@ const show = async (session, request) => {
 	};
 };
 //#endregion
-//#region ../graph-cli/dist/sync.js
-/**
-* Thrown by `sync` when a source fails part way. Its exit status and message are the source's failure, classified as `failureOf` classifies it; its cause is the error underneath that failure, such as the token port's own error; and what to run next is data, in `resume` and `remaining`, never text.
-*/
-var SyncInterruptedError = class extends CliError {
-	resume;
-	remaining;
-	saved;
-	/**
-	* @param exitCode - The exit status the source's failure maps to.
-	* @param message - The source's failure.
-	* @param interruption - Where the sync carries on.
-	* @param options - The underlying error, kept as the cause.
-	*/
-	constructor(exitCode, message, interruption, options) {
-		super(exitCode, message, options);
-		this.name = "SyncInterruptedError";
-		this.resume = interruption.resume;
-		this.remaining = interruption.remaining;
-		this.saved = interruption.saved;
-	}
-};
-const scopeSeparator = ":";
-/** Groups scopes by their source prefix, keeping the order in which each prefix first appears. */
-const bySource = (scopes) => {
-	const groups = /* @__PURE__ */ new Map();
-	for (const scope of scopes) {
-		const separator = scope.indexOf(scopeSeparator);
-		if (separator <= 0) throw new CliError(exitCodes.usage, `"${scope}" is not a scope: write <source>:<scope>, such as github:owner/repo`);
-		const prefix = scope.slice(0, separator);
-		groups.set(prefix, [...groups.get(prefix) ?? [], scope]);
-	}
-	return [...groups].map(([prefix, grouped]) => ({
-		prefix,
-		scopes: grouped
-	}));
-};
-/** Bound activities are the only elements a sync assembles, since a page's activities are bound by schema. */
-const boundActivities = (pages) => {
-	const { model, overlay, gaps } = assembleSync(pages);
-	const activities = model.elements.flatMap((element) => element.kind === "activity" && element.source !== void 0 ? [{
-		...element,
-		source: element.source
-	}] : []);
-	return {
-		items: {
-			participants: model.participants,
-			activities,
-			transitions: model.transitions,
-			overlay
-		},
-		gaps
-	};
-};
-/**
-* Reads every page of the scopes from their sources and merges them into the session's model in one write, creating the model when the store has none. Records already in the model are replaced by identifier and the rest are kept, so syncing again refreshes what changed.
-*
-* When a source fails part way, the pages read before the failure are still written, and the error carries where to carry on: the request that resumes the failing source after the cursor of its last page read, and the scopes of the sources not reached.
-* @param session - The store and model.
-* @param sources - The source for each identifier prefix.
-* @param request - The scopes, and a cursor to resume after.
-* @returns What was written, and the gaps the sources reported.
-* @throws CliError with `usage` for a scope with no source prefix, a prefix no source serves, or `after` with scopes of more than one source; and SyncInterruptedError, with the source's failure and where to carry on, when a source fails part way.
-*/
-const sync = async (session, sources, request) => {
-	const groups = bySource(request.scopes);
-	if (request.after !== void 0 && groups.length > 1) throw new CliError(exitCodes.usage, "--after resumes one source's sync: give only that source's scopes");
-	const clients = groups.map((group) => {
-		const client = sources(group.prefix);
-		if (client === void 0) throw new CliError(exitCodes.usage, `no source reads "${group.prefix}" scopes`);
-		return {
-			...group,
-			client
-		};
-	});
-	const pages = [];
-	const write = async () => {
-		const { items, gaps } = boundActivities(pages);
-		const { revision } = await session.store.v1.items.upsert({
-			modelId: session.modelId,
-			items
-		}, callOptions(session.signal));
-		return {
-			modelId: session.modelId,
-			revision,
-			participants: items.participants.length,
-			activities: items.activities.length,
-			transitions: items.transitions.length,
-			gaps
-		};
-	};
-	/** Reads the sources in order, each only after the one before has finished, since a source's failure must stop the ones after it. */
-	const readFrom = async (index) => {
-		const group = clients.at(index);
-		if (group === void 0) return;
-		let cursor = index === 0 ? request.after : void 0;
-		try {
-			const stream = await group.client.v1.sync.stream(cursor === void 0 ? { scope: group.scopes } : {
-				scope: group.scopes,
-				after: cursor
-			}, callOptions(session.signal));
-			for await (const page of stream) {
-				pages.push(page);
-				cursor = page.next;
-			}
-		} catch (error) {
-			const failure = failureOf(error);
-			const saved = pages.length > 0;
-			if (saved) await write();
-			throw new SyncInterruptedError(failure.exitCode, failure.message, {
-				resume: cursor === void 0 ? { scopes: group.scopes } : {
-					scopes: group.scopes,
-					after: cursor
-				},
-				remaining: clients.slice(index + 1).flatMap((next) => next.scopes),
-				saved
-			}, { cause: underlyingCause(error) });
-		}
-		await readFrom(index + 1);
-	};
-	await readFrom(0);
-	return write();
-};
-//#endregion
 //#region ../graph-cli/dist/validate.js
 /** A cycle that no decision closes, as an issue: status is undefined on it. */
 const cycleIssues = (model) => illegalCycles(model).map((cycle) => ({
@@ -1112,6 +839,44 @@ const choice = (values, value, name) => {
 	if (!isOneOf(values, value)) throw new Error(`--${name} was not checked against its choices`);
 	return value;
 };
+/** The direction names `--direction` takes. */
+const directions = Object.keys(directionNames);
+const isDirection = (value) => isOneOf(directions, value);
+/**
+* A commander option parser that collects every occurrence of an option, in order, so the option can be repeated.
+* @param value - This occurrence's value.
+* @param previous - The values collected before it.
+*/
+const collect = (value, previous) => [...previous ?? [], value];
+/**
+* A commander option parser that checks each value against its choices and collects every occurrence, in order. Commander's own `choices` replaces an option's parser, so the two cannot be combined.
+* @param choices - The values allowed.
+*/
+const collectChoice = (choices) => (value, previous) => {
+	if (!isOneOf(choices, value)) throw new InvalidArgumentError(`Allowed choices are ${choices.join(", ")}.`);
+	return [...previous ?? [], value];
+};
+/**
+* Reads `sync`'s filter options into the source contract's filter, or nothing when none is given.
+* @param options - The `sync` command's options.
+* @returns The filter.
+* @throws CliError with `usage` for `--direction` without `--order`.
+*/
+const syncFilterOf = (options) => {
+	const { state, label, order, direction } = options;
+	const states = Array.isArray(state) ? state.filter((value) => isOneOf(filterStates, value)) : [];
+	const labels = Array.isArray(label) ? label.filter(isText) : [];
+	if (direction !== void 0 && order === void 0) throw new CliError(exitCodes.usage, "--direction orders by --order: give both");
+	const filter = {
+		...states.length === 0 ? {} : { states },
+		...labels.length === 0 ? {} : { labels },
+		...order === void 0 ? {} : { order: {
+			field: choice(orderFields, order, "order"),
+			direction: directionNames[isDirection(direction) ? direction : "asc"]
+		} }
+	};
+	return Object.keys(filter).length === 0 ? void 0 : filter;
+};
 /** The word that forgets a named fact rather than giving it a value. */
 const unknownValue = "unknown";
 /** A number as JSON writes one, so a value that reads as a number is never also meant as text. */
@@ -1182,14 +947,16 @@ const runCli = async (args, ports, identity) => {
 			await opened.close();
 		}
 	};
-	program.command("sync").description("read the scopes from their sources and merge them into the model").argument("<scope...>", "source-qualified scopes, such as github:owner or github:owner/repo").option("--after <cursor>", "resume an interrupted sync after this cursor").action(async (scopes, options, command) => {
+	program.command("sync").description("read the scopes from their sources and merge them into the model").argument("<scope...>", "source-qualified scopes, such as github:owner or github:owner/repo").option("--after <cursor>", "resume an interrupted sync after this cursor").addOption(new Option("--state <state>", `list only work in this state, one of ${filterStates.join(", ")}; repeat for more than one`).argParser(collectChoice(filterStates))).addOption(new Option("--label <label>", "list only work carrying this label; repeat to keep work carrying any of them").argParser(collect)).addOption(new Option("--order <field>", "list the work in this order").choices(orderFields)).addOption(new Option("--direction <direction>", "the direction of --order; ascending when not given").choices(directions)).addHelpText("after", "\nA filter narrows what each scope lists, not the work it depends on. A source that cannot filter a scope, such as a GitHub Projects v2 board, refuses the sync. A cursor from --after is valid only with the filter it was issued under.").action(async (scopes, options, command) => {
 		const { after } = options;
+		const filter = syncFilterOf(options);
 		await withSession(async (session) => {
 			try {
-				const result = await sync(session, ports.source, typeof after === "string" ? {
+				const result = await sync(session, ports.source, {
 					scopes,
-					after
-				} : { scopes });
+					...typeof after === "string" ? { after } : {},
+					...filter === void 0 ? {} : { filter }
+				});
 				return {
 					json: result,
 					text: renderSync(result)
@@ -1227,6 +994,24 @@ const runCli = async (args, ports, identity) => {
 			};
 		})(command);
 	});
+	program.command("children").description("list an element's sub-tasks: the work a source reports as its children").argument("<id>", "the element").action(async (id, _options, command) => {
+		await withSession(async (session) => {
+			const result = await children(session, id);
+			return {
+				json: result,
+				text: renderChildren(result)
+			};
+		})(command);
+	});
+	program.command("ancestors").description("list what an element is a sub-task of, nearest first, with how many levels up each is").argument("<id>", "the element").action(async (id, _options, command) => {
+		await withSession(async (session) => {
+			const result = await ancestors(session, id);
+			return {
+				json: result,
+				text: renderAncestors(result)
+			};
+		})(command);
+	});
 	program.command("path").description("list the critical path: the longest chain of work still ahead").action(async (_options, command) => {
 		await withSession(async (session) => {
 			const result = await path(session);
@@ -1538,4 +1323,4 @@ const runProcess = async (identity) => {
 	return runCli(process.argv.slice(2), nodePorts({ signal: controller.signal }), identity);
 };
 //#endregion
-export { why as A, CliError as B, swimlaneToMermaid as C, impactOf as D, handoffsOf as E, setFact as F, setState as I, findRun as L, artefactStates as M, factsOf as N, path as O, setArtefact as P, loadRun as R, stateMachineToMermaid as S, cycles as T, failureOf as V, sequenceToDot as _, defaultModelId as a, flowchartToMermaid as b, validateStored as c, emit as d, formatNames as f, flowchartToDot as g, viewNames as h, runProcess as i, add as j, ready as k, SyncInterruptedError as l, show as m, nodePorts as n, runCli as o, project as p, packageVersion as r, validateDocument as s, defaultDataPath as t, sync as u, stateMachineToDot as v, blocked as w, sequenceToMermaid as x, swimlaneToDot as y, runFacts as z };
+export { setState as A, ready as C, factsOf as D, artefactStates as E, failureOf as F, loadRun as M, runFacts as N, setArtefact as O, CliError as P, path as S, add as T, blocked as _, defaultModelId as a, handoffsOf as b, validateStored as c, project as d, show as f, ancestors as g, sync as h, runProcess as i, findRun as j, setFact as k, emit as l, SyncInterruptedError as m, nodePorts as n, runCli as o, viewNames as p, packageVersion as r, validateDocument as s, defaultDataPath as t, formatNames as u, children as v, why as w, impactOf as x, cycles as y };