get-tbd 0.1.20 → 0.1.21

package/README.md

@@ -1,5 +1,9 @@
 # tbd
 
+[![Follow @ojoshe on X](https://img.shields.io/badge/follow_%40ojoshe-black?logo=x&logoColor=white)](https://x.com/ojoshe)
+[![CI](https://github.com/jlevy/tbd/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/tbd/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/get-tbd)](https://www.npmjs.com/package/get-tbd)
+
 **Task tracking, spec-driven planning, and knowledge injection for AI coding agents.**
 
 **tbd** (short for “To Be Done,” or “TypeScript beads” if you prefer) combines four

package/dist/bin.mjs

@@ -6727,17 +6727,23 @@ const Dependency = objectType({
 /**
 * Full issue schema.
 *
+* Field order is canonical and mirrored by ISSUE_FIELD_ORDER below:
+* type, id, title, kind, status, priority, version (the "header seven"),
+* then linkages, assignment, hierarchy, scheduling, provenance,
+* timestamps, lifecycle, and extensions.
+*
 * Note: Fields use .nullable() in addition to .optional() because
 * YAML parses `field: null` as JavaScript null, not undefined.
 */
 const IssueSchema = BaseEntity.extend({
 	type: literalType("is"),
 	title: stringType().min(1).max(500),
-	description: stringType().max(5e4).nullable().optional(),
-	notes: stringType().max(5e4).nullable().optional(),
 	kind: IssueKind.default("task"),
 	status: IssueStatus.default("open"),
 	priority: Priority.default(2),
+	description: stringType().max(5e4).nullable().optional(),
+	notes: stringType().max(5e4).nullable().optional(),
+	spec_path: stringType().nullable().optional(),
 	assignee: stringType().nullable().optional(),
 	labels: arrayType(stringType()).default([]),
 	dependencies: arrayType(Dependency).default([]),
@@ -6747,8 +6753,7 @@ const IssueSchema = BaseEntity.extend({
 	deferred_until: Timestamp.nullable().optional(),
 	created_by: stringType().nullable().optional(),
 	closed_at: Timestamp.nullable().optional(),
-	close_reason: stringType().nullable().optional(),
-	spec_path: stringType().nullable().optional()
+	close_reason: stringType().nullable().optional()
 });
 /**
 * Git branch name - restricted to safe characters.
@@ -6862,6 +6867,64 @@ const AtticEntrySchema = objectType({
 * Format: { "a7k2": "01hx5zzkbkactav9wevgemmvrz", ... }
 */
 const IdMappingYamlSchema = recordType(ShortId, Ulid);
+/**
+* Canonical field order for issue YAML frontmatter.
+* (description and notes are body content, not frontmatter)
+*/
+const ISSUE_FIELD_ORDER = [
+	"type",
+	"id",
+	"title",
+	"kind",
+	"status",
+	"priority",
+	"version",
+	"spec_path",
+	"assignee",
+	"labels",
+	"dependencies",
+	"parent_id",
+	"child_order_hints",
+	"due_date",
+	"deferred_until",
+	"created_by",
+	"created_at",
+	"updated_at",
+	"closed_at",
+	"close_reason",
+	"extensions"
+];
+/**
+* Canonical field order for config YAML.
+*/
+const CONFIG_FIELD_ORDER = [
+	"tbd_format",
+	"tbd_version",
+	"display",
+	"sync",
+	"settings",
+	"docs_cache"
+];
+/**
+* Canonical field order for attic entry YAML.
+*/
+const ATTIC_ENTRY_FIELD_ORDER = [
+	"entity_id",
+	"timestamp",
+	"field",
+	"lost_value",
+	"winner_source",
+	"loser_source",
+	"context"
+];
+/**
+* Canonical field order for local state YAML.
+*/
+const LOCAL_STATE_FIELD_ORDER = [
+	"last_sync_at",
+	"last_doc_sync_at",
+	"welcome_seen"
+];
 
 //#endregion
 //#region src/lib/types.ts
@@ -13583,6 +13646,76 @@ const PAGINATION_LINE_THRESHOLD = 50;
 */
 const PARENT_CONTEXT_MAX_LINES = 50;
 
+//#endregion
+//#region src/lib/comparison-chain.ts
+const defaultCompare = (a, b) => {
+	if (typeof a === "string" && typeof b === "string") return a.localeCompare(b);
+	if (a < b) return -1;
+	if (a > b) return 1;
+	return 0;
+};
+const nullLastCompare = (a, b) => {
+	if (a == null) return b == null ? 0 : 1;
+	if (b == null) return -1;
+	return defaultCompare(a, b);
+};
+const nullFirstCompare = (a, b) => {
+	if (a == null) return b == null ? 0 : -1;
+	if (b == null) return 1;
+	return defaultCompare(a, b);
+};
+/**
+* A Google Guava-style comparison chain to make complex sorting, such as secondary
+* sorts, significantly easier.
+*
+* For example:
+*
+* items.sort(comparisonChain<Item>()
+*   .compare(item => item.title, ordering.nullsLast)
+*   .compare(item => item.url)
+*   .result());
+*/
+const comparisonChain = () => {
+	let compare = () => 0;
+	const chain = {
+		compare: (selector, comparator = defaultCompare) => {
+			const prevCompare = compare;
+			compare = (a, b) => prevCompare(a, b) || comparator(selector(a), selector(b));
+			return chain;
+		},
+		result: () => compare
+	};
+	return chain;
+};
+/**
+* Reverse a comparator's ordering.
+*/
+const reverse = (comparator) => (a, b) => comparator(b, a);
+/**
+* Create a comparator that sorts values in a manually specified order.
+* Values not in the order array are placed at the end.
+*/
+const manualOrderComparator = (order) => {
+	const orderMap = new Map(order.map((value, index) => [value, index]));
+	return (a, b) => {
+		const indexA = orderMap.get(a);
+		const indexB = orderMap.get(b);
+		if (indexA === void 0) return indexB === void 0 ? 0 : 1;
+		if (indexB === void 0) return -1;
+		return indexA - indexB;
+	};
+};
+/**
+* Common ordering strategies for use with comparisonChain.
+*/
+const ordering = {
+	nullsLast: nullLastCompare,
+	nullsFirst: nullFirstCompare,
+	default: defaultCompare,
+	reversed: reverse(defaultCompare),
+	manual: manualOrderComparator
+};
+
 //#endregion
 //#region src/utils/yaml-utils.ts
 /**
@@ -13626,6 +13759,17 @@ function stringifyYamlCompact(data) {
 	return (0, import_dist$2.stringify)(data, YAML_STRINGIFY_OPTIONS_COMPACT);
 }
 /**
+* Create a new object with keys sorted according to a manual field ordering.
+* Uses ordering.manual() from comparison-chain.ts, so fields not in the
+* order array are placed at the end.
+*/
+function sortKeys(obj, fieldOrder) {
+	const keyComparator = ordering.manual(fieldOrder);
+	const sorted = {};
+	for (const key of Object.keys(obj).sort(keyComparator)) sorted[key] = obj[key];
+	return sorted;
+}
+/**
 * Error thrown when YAML content contains unresolved merge conflict markers.
 */
 var MergeConflictError = class extends Error {
@@ -13858,13 +14002,12 @@ function parseIssue(content) {
 */
 function serializeIssue(issue) {
 	const { description, notes, ...metadata } = issue;
-	const sortedMetadata = {};
-	for (const key of Object.keys(metadata).sort()) sortedMetadata[key] = metadata[key];
 	const parts = [
 		"---",
-		stringifyYaml(sortedMetadata, {
+		stringifyYaml(sortKeys(metadata, ISSUE_FIELD_ORDER), {
 			lineWidth: 0,
-			nullStr: "null"
+			nullStr: "null",
+			sortMapEntries: false
 		}).trim(),
 		"---"
 	];
@@ -13884,7 +14027,7 @@ function serializeIssue(issue) {
 * Package version, derived from git at build time.
 * Format: X.Y.Z for releases, X.Y.Z-dev.N.hash for dev builds.
 */
-const VERSION$1 = "0.1.20";
+const VERSION$1 = "0.1.21";
 
 //#endregion
 //#region src/cli/lib/version.ts
@@ -97806,7 +97949,10 @@ async function readConfigWithMigration(baseDir) {
 */
 async function writeConfig(baseDir, config) {
 	const configPath = join(baseDir, CONFIG_FILE);
-	let content = stringifyYaml(config, { lineWidth: 0 });
+	let content = stringifyYaml(sortKeys(config, CONFIG_FIELD_ORDER), {
+		lineWidth: 0,
+		sortMapEntries: false
+	});
 	if (config.docs_cache && Object.keys(config.docs_cache).length > 0) content = content.replace("docs_cache:", "# Documentation cache configuration.\n# files: Maps destination paths (relative to .tbd/docs/) to source locations.\n#   Sources can be:\n#   - internal: prefix for bundled docs (e.g., \"internal:shortcuts/standard/code-review-and-commit.md\")\n#   - Full URL for external docs (e.g., \"https://raw.githubusercontent.com/org/repo/main/file.md\")\n# lookup_path: Search paths for doc lookup (like shell $PATH). Earlier paths take precedence.\n#\n# To sync docs: tbd sync --docs\n# To check status: tbd sync --status\n#\n# Auto-sync: Docs are automatically synced when stale (default: every 24 hours).\n# Configure with settings.doc_auto_sync_hours (0 = disabled).\ndocs_cache:");
 	await writeFile(configPath, content);
 }
@@ -97879,7 +98025,10 @@ async function writeLocalState(baseDir, state) {
 	} catch {
 		throw new Error(`Cannot write state: .tbd/ directory does not exist at ${baseDir}. Run 'tbd init' first or ensure the correct tbd root is being used.`);
 	}
-	await writeFile(join(baseDir, STATE_FILE), stringifyYaml(state, { lineWidth: 0 }));
+	await writeFile(join(baseDir, STATE_FILE), stringifyYaml(sortKeys(state, LOCAL_STATE_FIELD_ORDER), {
+		lineWidth: 0,
+		sortMapEntries: false
+	}));
 }
 /**
 * Update specific fields in local state (merge with existing).
@@ -98489,6 +98638,26 @@ const FIELD_STRATEGIES = {
 	extensions: "lww"
 };
 /**
+* Fields that are metadata-only and should be ignored when checking
+* for substantive changes between issues. These fields change on every
+* merge operation and don't represent meaningful content changes.
+*/
+const METADATA_ONLY_FIELDS = new Set(["version", "updated_at"]);
+/**
+* Check if two issues are substantively equal, ignoring metadata fields
+* (version, updated_at) that change on every merge.
+*
+* This prevents trivial timestamp/version bumps from being treated as
+* real changes during outbox saves and sync operations.
+*/
+function issuesSubstantivelyEqual(a, b) {
+	for (const key of Object.keys(FIELD_STRATEGIES)) {
+		if (METADATA_ONLY_FIELDS.has(key)) continue;
+		if (!deepEqual(a[key], b[key])) return false;
+	}
+	return true;
+}
+/**
 * Deep equality check for values.
 */
 function deepEqual(a, b) {
@@ -98596,6 +98765,11 @@ function mergeIssues(base, local, remote) {
 				break;
 		}
 	}
+	const latest = local.version >= remote.version ? local : remote;
+	if (issuesSubstantivelyEqual(merged, latest)) return {
+		merged: { ...latest },
+		conflicts
+	};
 	merged.version = Math.max(local.version, remote.version) + 1;
 	merged.updated_at = now();
 	return {
@@ -99233,6 +99407,26 @@ function randomChar(prng) {
 	const randomPosition = Math.floor(prng() * ENCODING_LEN) % ENCODING_LEN;
 	return ENCODING.charAt(randomPosition);
 }
+function replaceCharAt(str, index, char) {
+	if (index > str.length - 1) return str;
+	return str.substr(0, index) + char + str.substr(index + 1);
+}
+function incrementBase32(str) {
+	let done = void 0, index = str.length, char, charIndex, output = str;
+	const maxCharIndex = ENCODING_LEN - 1;
+	while (!done && index-- >= 0) {
+		char = output[index];
+		charIndex = ENCODING.indexOf(char);
+		if (charIndex === -1) throw new ULIDError(ULIDErrorCode.Base32IncorrectEncoding, "Incorrectly encoded string");
+		if (charIndex === maxCharIndex) {
+			output = replaceCharAt(output, index, ENCODING[0]);
+			continue;
+		}
+		done = replaceCharAt(output, index, ENCODING[charIndex + 1]);
+	}
+	if (typeof done === "string") return done;
+	throw new ULIDError(ULIDErrorCode.Base32IncorrectEncoding, "Failed incrementing string");
+}
 /**
 * Detect the best PRNG (pseudo-random number generator)
 * @param root The root to check from (global/window)
@@ -99285,16 +99479,27 @@ function inWebWorker() {
 	return typeof WorkerGlobalScope !== "undefined" && self instanceof WorkerGlobalScope;
 }
 /**
-* Generate a ULID
-* @param seedTime Optional time seed
-* @param prng Optional PRNG function
-* @returns A ULID string
+* Create a ULID factory to generate monotonically-increasing
+*  ULIDs
+* @param prng The PRNG to use
+* @returns A ulid factory
 * @example
+*  const ulid = monotonicFactory();
 *  ulid(); // "01HNZXD07M5CEN5XA66EMZSRZW"
 */
-function ulid(seedTime, prng) {
+function monotonicFactory(prng) {
 	const currentPRNG = prng || detectPRNG();
-	return encodeTime(!seedTime || isNaN(seedTime) ? Date.now() : seedTime, TIME_LEN) + encodeRandom(RANDOM_LEN, currentPRNG);
+	let lastTime = 0, lastRandom;
+	return function _ulid(seedTime) {
+		const seed = !seedTime || isNaN(seedTime) ? Date.now() : seedTime;
+		if (seed <= lastTime) {
+			const incrementedRandom = lastRandom = incrementBase32(lastRandom);
+			return encodeTime(lastTime, TIME_LEN) + incrementedRandom;
+		}
+		lastTime = seed;
+		const newRandom = lastRandom = encodeRandom(RANDOM_LEN, currentPRNG);
+		return encodeTime(seed, TIME_LEN) + newRandom;
+	};
 }
 
 //#endregion
@@ -99310,6 +99515,7 @@ function ulid(seedTime, prng) {
 *
 * See: tbd-design.md §2.5 ID Generation
 */
+const ulid = monotonicFactory();
 /**
 * Cast a string to InternalIssueId after validation.
 * Use this when you've validated that a string is a valid internal ID.
@@ -100214,76 +100420,6 @@ async function loadFullContext(command) {
 	};
 }
 
-//#endregion
-//#region src/lib/comparison-chain.ts
-const defaultCompare = (a, b) => {
-	if (typeof a === "string" && typeof b === "string") return a.localeCompare(b);
-	if (a < b) return -1;
-	if (a > b) return 1;
-	return 0;
-};
-const nullLastCompare = (a, b) => {
-	if (a == null) return b == null ? 0 : 1;
-	if (b == null) return -1;
-	return defaultCompare(a, b);
-};
-const nullFirstCompare = (a, b) => {
-	if (a == null) return b == null ? 0 : -1;
-	if (b == null) return 1;
-	return defaultCompare(a, b);
-};
-/**
-* A Google Guava-style comparison chain to make complex sorting, such as secondary
-* sorts, significantly easier.
-*
-* For example:
-*
-* items.sort(comparisonChain<Item>()
-*   .compare(item => item.title, ordering.nullsLast)
-*   .compare(item => item.url)
-*   .result());
-*/
-const comparisonChain = () => {
-	let compare = () => 0;
-	const chain = {
-		compare: (selector, comparator = defaultCompare) => {
-			const prevCompare = compare;
-			compare = (a, b) => prevCompare(a, b) || comparator(selector(a), selector(b));
-			return chain;
-		},
-		result: () => compare
-	};
-	return chain;
-};
-/**
-* Reverse a comparator's ordering.
-*/
-const reverse = (comparator) => (a, b) => comparator(b, a);
-/**
-* Create a comparator that sorts values in a manually specified order.
-* Values not in the order array are placed at the end.
-*/
-const manualOrderComparator = (order) => {
-	const orderMap = new Map(order.map((value, index) => [value, index]));
-	return (a, b) => {
-		const indexA = orderMap.get(a);
-		const indexB = orderMap.get(b);
-		if (indexA === void 0) return indexB === void 0 ? 0 : 1;
-		if (indexB === void 0) return -1;
-		return indexA - indexB;
-	};
-};
-/**
-* Common ordering strategies for use with comparisonChain.
-*/
-const ordering = {
-	nullsLast: nullLastCompare,
-	nullsFirst: nullFirstCompare,
-	default: defaultCompare,
-	reversed: reverse(defaultCompare),
-	manual: manualOrderComparator
-};
-
 //#endregion
 //#region src/lib/status.ts
 /**
@@ -100788,14 +100924,10 @@ var ListHandler = class extends BaseCommand {
 			return true;
 		});
 	}
-	sortIssues(issues, sortField, mapping) {
-		const getShortId = (issue) => {
-			const ulid = extractUlidFromInternalId(issue.id);
-			return mapping.ulidToShort.get(ulid) ?? ulid;
-		};
+	sortIssues(issues, sortField, _mapping) {
 		const primarySelector = sortField === "created" ? (i) => new Date(i.created_at).getTime() : sortField === "updated" ? (i) => new Date(i.updated_at).getTime() : (i) => i.priority;
 		const primaryOrdering = sortField === "created" || sortField === "updated" ? ordering.reversed : ordering.default;
-		return [...issues].sort(comparisonChain().compare(primarySelector, primaryOrdering).compare(getShortId, (a, b) => naturalCompare(a, b)).result());
+		return [...issues].sort(comparisonChain().compare(primarySelector, primaryOrdering).compare((i) => extractUlidFromInternalId(i.id)).result());
 	}
 };
 const listCommand = new Command("list").description("List issues").option("--status <status>", "Filter: open, in_progress, blocked, deferred, closed").option("--all", "Include closed issues").option("--type <type>", "Filter: bug, feature, task, epic").option("--priority <0-4>", "Filter by priority").option("--assignee <name>", "Filter by assignee").option("--label <label>", "Filter by label (repeatable)", (val, prev = []) => [...prev, val]).option("--parent <id>", "List children of parent").option("--spec <path>", "Filter by spec path (matches full path, partial path suffix, or filename)").option("--deferred", "Show only deferred issues").option("--defer-before <date>", "Deferred before date").option("--sort <field>", "Sort by: priority, created, updated", "priority").option("--limit <n>", "Limit results").option("--count", "Output only the count of matching issues").option("--long", "Show descriptions").option("--pretty", "Show tree view with parent-child relationships").option("--specs", "Group output by linked spec").action(async (options, command) => {
@@ -102380,11 +102512,15 @@ async function syncDocsWithDefaults(tbdRoot, options = {}) {
 *
 * An issue is considered "updated" if:
 * - It doesn't exist in the remote (new issue)
-* - Its content differs from the remote version (modified issue)
+* - Its substantive content differs from the remote version (modified issue)
+*
+* Uses issuesSubstantivelyEqual to ignore metadata-only changes (version, updated_at)
+* that don't represent meaningful content changes. This prevents trivial timestamp
+* bumps from causing thousands of issues to be saved to the outbox.
 *
 * @param localIssues - Issues from the local worktree
 * @param remoteIssues - Issues from the remote tbd-sync branch
-* @returns Issues that are new or modified compared to remote
+* @returns Issues that are new or substantively modified compared to remote
 */
 function getUpdatedIssues(localIssues, remoteIssues) {
 	const remoteById = /* @__PURE__ */ new Map();
@@ -102392,7 +102528,7 @@ function getUpdatedIssues(localIssues, remoteIssues) {
 	return localIssues.filter((local) => {
 		const remote = remoteById.get(local.id);
 		if (!remote) return true;
-		return !deepEqual(local, remote);
+		return !issuesSubstantivelyEqual(local, remote);
 	});
 }
 /**
@@ -102447,7 +102583,7 @@ async function saveConflictToAttic(atticDir, conflict, winnerSource) {
 		}
 	};
 	const safeTimestamp = timestamp.replace(/:/g, "-");
-	await writeFile(join(atticDir, `${conflict.issue_id}_${safeTimestamp}_${conflict.field}.yml`), stringifyYaml(entry));
+	await writeFile(join(atticDir, `${conflict.issue_id}_${safeTimestamp}_${conflict.field}.yml`), stringifyYaml(sortKeys(entry, ATTIC_ENTRY_FIELD_ORDER), { sortMapEntries: false }));
 }
 /**
 * Get the target/source directory for workspace operations.
@@ -102493,17 +102629,23 @@ async function saveToWorkspace(tbdRoot, dataSyncDir, options) {
 	log.info(`Loaded ${totalSource} issue(s) from worktree`);
 	let sourceIssues = allSourceIssues;
 	const isUpdatesOnly = options.updatesOnly ?? options.outbox;
-	if (isUpdatesOnly) try {
-		log.progress("Fetching remote for comparison...");
-		await git("-C", tbdRoot, "fetch", "origin", "tbd-sync");
-		log.debug("Fetch succeeded, reading remote issues...");
-		const remoteIssues = await readRemoteIssues(tbdRoot, "origin", "tbd-sync");
-		log.info(`Loaded ${remoteIssues.length} remote issue(s) for comparison`);
-		sourceIssues = getUpdatedIssues(allSourceIssues, remoteIssues);
-		log.info(`Filtered to ${sourceIssues.length} updated issue(s) (of ${totalSource} total)`);
-	} catch (fetchError) {
-		const fetchMsg = fetchError instanceof Error ? fetchError.message : String(fetchError);
-		log.info(`Fetch failed (${fetchMsg}), falling back to saving all ${totalSource} issues`);
+	if (isUpdatesOnly) {
+		try {
+			log.progress("Fetching remote for comparison...");
+			await git("-C", tbdRoot, "fetch", "origin", "tbd-sync");
+			log.debug("Fetch succeeded");
+		} catch (fetchError) {
+			const fetchMsg = fetchError instanceof Error ? fetchError.message : String(fetchError);
+			log.info(`Fetch failed (${fetchMsg}), using cached remote state for comparison`);
+		}
+		try {
+			const remoteIssues = await readRemoteIssues(tbdRoot, "origin", "tbd-sync");
+			log.info(`Loaded ${remoteIssues.length} remote issue(s) for comparison`);
+			sourceIssues = getUpdatedIssues(allSourceIssues, remoteIssues);
+			log.info(`Filtered to ${sourceIssues.length} updated issue(s) (of ${totalSource} total)`);
+		} catch {
+			log.info(`No remote state available, falling back to saving all ${totalSource} issues`);
+		}
 	}
 	let saved = 0;
 	let conflicts = 0;