get-tbd 0.1.13 → 0.1.14

package/dist/docs/shortcuts/standard/welcome-user.md

@@ -1,6 +1,7 @@
 ---
 title: Welcome User
 description: Welcome message for users after tbd installation or setup
+category: session
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 Welcome the user with the message below.
@@ -38,7 +39,7 @@ Here are examples of things you can say and what happens:
 | "Let's plan a new feature" | Walks you through creating a planning spec (`tbd shortcut new-plan-spec`) |
 | "Break the spec into issues" | Creates implementation beads from your spec (`tbd shortcut plan-implementation-with-beads`) |
 | "Implement these issues" | Works through beads systematically (`tbd shortcut implement-beads`) |
-| "Commit this code" | Reviews changes and commits properly (`tbd shortcut commit-code`) |
+| "Commit this code" | Reviews changes and commits properly (`tbd shortcut code-review-and-commit`) |
 | "Create a PR" | Creates a pull request with summary (`tbd shortcut create-or-update-pr-simple`) |
 | "Review this for best practices" | Performs a code review with guidelines |
 

package/dist/docs/shortcuts/system/skill-brief.md

@@ -27,7 +27,7 @@ tbd sync               # Sync with remote
 | --- | --- |
 | Found a bug | `tbd create "..." --type=bug` |
 | Plan a feature | `tbd shortcut new-plan-spec` |
-| Commit code | `tbd shortcut commit-code` |
+| Commit code | `tbd shortcut code-review-and-commit` |
 | Create a PR | `tbd shortcut create-or-update-pr-simple` |
 | TypeScript review | `tbd guidelines typescript-rules` |
 

package/dist/docs/shortcuts/system/skill.md

@@ -6,16 +6,19 @@ description: Full tbd workflow guide for agents
 
 1. **Beads**: Git-native issue tracking (tasks, bugs, features).
    Never lose work across sessions.
+   Drop-in replacement for `bd`.
 2. **Spec-Driven Workflows**: Plan features → break into beads → implement
    systematically.
-3. **Shortcuts**: Reusable instruction templates for common workflows.
-4. **Guidelines**: Coding rules and best practices.
+3. **Knowledge Injection**: 17+ engineering guidelines (TypeScript, Python, TDD,
+   testing, Convex, monorepos) available on demand.
+4. **Shortcuts**: Reusable instruction templates for common workflows (code review,
+   commits, PRs, cleanup, handoffs).
 
 ## Installation
 
 ```bash
 npm install -g get-tbd@latest
-tbd setup --auto --prefix=<name>   # Fresh project (--prefix is REQUIRED and should be short. For new project setup, ALWAYS ASK THE USER FOR THE PREFIX; do not guess it)
+tbd setup --auto --prefix=<name>   # Fresh project (--prefix is REQUIRED: 2-8 alphabetic chars recommended. ALWAYS ASK THE USER FOR THE PREFIX; do not guess it)
 tbd setup --auto                   # Existing tbd project (prefix already set)
 tbd setup --from-beads             # Migration from .beads/ if `bd` has been used
 ```
@@ -48,20 +51,42 @@ or want help → run `tbd shortcut welcome-user`
 
 | User Says | You (the Agent) Run |
 | --- | --- |
+| **Issues/Beads** |  |
 | "There's a bug where ..." | `tbd create "..." --type=bug` |
-| "Let's work on issues" | `tbd ready` |
-| "Build a TypeScript CLI" | `tbd guidelines typescript-cli-tool-rules` |
-| "Improve eslint/monorepo" | `tbd guidelines typescript-monorepo-patterns` |
-| "Add e2e/golden testing" | `tbd guidelines golden-testing-guidelines` |
-| "Review changes" (TS) | `tbd guidelines typescript-rules` |
-| "Review changes" (Python) | `tbd guidelines python-rules` |
-| "Plan a new feature" | `tbd shortcut new-plan-spec` |
+| "Create a task/feature for ..." | `tbd create "..." --type=task` or `--type=feature` |
+| "Let's work on issues/beads" | `tbd ready` |
+| "Show me issue X" | `tbd show <id>` |
+| "Close this issue" | `tbd close <id>` |
+| "Search issues for X" | `tbd search "X"` |
+| "Add label X to issue" | `tbd label add <id> <label>` |
+| "What issues are stale?" | `tbd stale` |
+| **Planning & Specs** |  |
+| "Plan a new feature" / "Create a spec" | `tbd shortcut new-plan-spec` |
 | "Break spec into beads" | `tbd shortcut plan-implementation-with-beads` |
 | "Implement these beads" | `tbd shortcut implement-beads` |
-| "Commit this" | `tbd shortcut commit-code` |
-| "Create a PR" | `tbd shortcut create-or-update-pr-simple` |
+| **Code Review & Commits** |  |
+| "Review this code" / "Code review" | `tbd shortcut review-code` |
+| "Review this PR" | `tbd shortcut review-github-pr` |
+| "Commit this" / "Use the commit shortcut" | `tbd shortcut code-review-and-commit` |
+| "Create a PR" / "File a PR" | `tbd shortcut create-or-update-pr-simple` |
+| "Merge main into my branch" | `tbd shortcut merge-upstream` |
+| **Guidelines & Knowledge** |  |
+| "Use TypeScript best practices" | `tbd guidelines typescript-rules` |
+| "Use Python best practices" | `tbd guidelines python-rules` |
+| "Build a TypeScript CLI" | `tbd guidelines typescript-cli-tool-rules` |
+| "Improve monorepo setup" | `tbd guidelines typescript-monorepo-patterns` |
+| "Add golden/e2e testing" | `tbd guidelines golden-testing-guidelines` |
+| "Use TDD" / "Test-driven development" | `tbd guidelines general-tdd-guidelines` |
+| "Convex best practices" | `tbd guidelines convex-rules` |
+| **Documentation** |  |
 | "Research this topic" | `tbd shortcut new-research-brief` |
 | "Document architecture" | `tbd shortcut new-architecture-doc` |
+| **Cleanup & Maintenance** |  |
+| "Clean up this code" / "Remove dead code" | `tbd shortcut code-cleanup-all` |
+| "Fix repository problems" | `tbd doctor --fix` |
+| **Sessions & Handoffs** |  |
+| "Hand off to another agent" | `tbd shortcut agent-handoff` |
+| "Check out this library's source" | `tbd shortcut checkout-third-party-repo` |
 | *(your choice whenever appropriate)* | `tbd list`, `tbd dep add`, `tbd close`, `tbd sync`, etc. |
 
 ## CRITICAL: Session Closing Protocol
@@ -115,6 +140,17 @@ or want help → run `tbd shortcut welcome-user`
 | `tbd sync` | Sync with git remote (run at session end) |
 | `tbd stats` | Project statistics |
 | `tbd doctor` | Check for problems |
+| `tbd doctor --fix` | Auto-fix repository problems |
+
+### Labels & Search
+
+| Command | Purpose |
+| --- | --- |
+| `tbd search <query>` | Search issues by text |
+| `tbd label add <id> <label>` | Add label to issue |
+| `tbd label remove <id> <label>` | Remove label from issue |
+| `tbd label list` | List all labels in use |
+| `tbd stale` | List issues not updated recently |
 
 ### Documentation
 

package/dist/docs/skill-brief.md

@@ -27,7 +27,7 @@ tbd sync               # Sync with remote
 | --- | --- |
 | Found a bug | `tbd create "..." --type=bug` |
 | Plan a feature | `tbd shortcut new-plan-spec` |
-| Commit code | `tbd shortcut commit-code` |
+| Commit code | `tbd shortcut code-review-and-commit` |
 | Create a PR | `tbd shortcut create-or-update-pr-simple` |
 | TypeScript review | `tbd guidelines typescript-rules` |
 

package/dist/docs/tbd-design.md

@@ -1143,6 +1143,8 @@ Lexicographically Sortable Identifier):
 - **Required prefix**: Project-specific (e.g., `proj`, `myapp`, `tk`) via
   `display.id_prefix`
   - Set during `tbd init --prefix=<name>` or automatically from beads import
+  - Recommended: 2-8 alphabetic characters (use `--force` for other formats)
+  - Must not contain dashes (would conflict with ID separator)
 - **Short code**: 1+ alphanumeric characters (a-z, 0-9)
   - Imported issues: Preserve original short ID (e.g., `100` from `tbd-100`)
   - New issues: Generate random 4-char base36
@@ -2348,7 +2350,8 @@ tbd <command> [subcommand] [args] [options]
 tbd init --prefix=<name> [options]
 
 Options:
-  --prefix=<name>       Required: project prefix for display IDs (e.g., "proj", "myapp")
+  --prefix=<name>       Required: project prefix for display IDs (2-8 alphabetic recommended)
+  --force               Allow non-recommended prefix format
   --sync-branch=<name>  Sync branch name (default: tbd-sync)
   --remote=<name>       Remote name (default: origin)
 ```
@@ -2356,6 +2359,15 @@ Options:
 The `--prefix` option is **required** unless you’re importing from an existing beads
 repository (which automatically detects and uses the beads prefix).
 
+**Prefix validation rules:**
+
+- **Recommended** (no --force needed): 2-8 alphabetic characters (e.g., `tbd`, `proj`,
+  `myapp`)
+- **Valid with --force**: 1-20 lowercase characters, starting with a letter, ending with
+  alphanumeric, middle characters can include dots (`.`) and underscores (`_`)
+- **Never allowed**: Dashes (`-`) are not allowed as they break ID syntax (e.g.,
+  `tbd-a1b2` would be ambiguous)
+
 **What it does:**
 
 1. Creates `.tbd/` directory with `config.yml` (including display.id_prefix) and

package/dist/index.d.mts

@@ -15,8 +15,16 @@ declare const IssueId: z.ZodString;
  * Short ID: 1+ base36 characters used for external/display IDs.
  * Typically 4 chars for new IDs (e.g., a7k2, b3m9).
  * Imports may preserve longer numeric IDs (e.g., "100" from "tbd-100").
+ * Legacy imports may include dots (e.g., "208.1" from hierarchical numbering).
+ * Imports may include dashes/underscores (e.g., "stat-in_progress" from JSONL).
  */
 declare const ShortId: z.ZodString;
+/**
+ * ULID: 26 lowercase alphanumeric characters.
+ * Used in internal IDs and ID mappings.
+ * Example: 01hx5zzkbkactav9wevgemmvrz
+ */
+declare const Ulid: z.ZodString;
 /**
  * External Issue ID input: accepts {prefix}-{short} or just {short}.
  * Examples: bd-a7k2, a7k2, bd-100, 100
@@ -198,15 +206,15 @@ declare const GitRemoteName: z.ZodString;
 /**
  * Doc cache configuration - maps destination paths to source locations.
  *
- * Keys are destination paths relative to .tbd/docs/ (e.g., "shortcuts/standard/commit-code.md")
+ * Keys are destination paths relative to .tbd/docs/ (e.g., "shortcuts/standard/code-review-and-commit.md")
  * Values are source locations:
- * - internal: prefix for bundled docs (e.g., "internal:shortcuts/standard/commit-code.md")
+ * - internal: prefix for bundled docs (e.g., "internal:shortcuts/standard/code-review-and-commit.md")
  * - Full URL for external docs (e.g., "https://raw.githubusercontent.com/org/repo/main/file.md")
  *
  * Example:
  * ```yaml
  * doc_cache:
- *   shortcuts/standard/commit-code.md: internal:shortcuts/standard/commit-code.md
+ *   shortcuts/standard/code-review-and-commit.md: internal:shortcuts/standard/code-review-and-commit.md
  *   shortcuts/custom/my-shortcut.md: https://raw.githubusercontent.com/org/repo/main/shortcuts/my-shortcut.md
  * ```
  */
@@ -222,7 +230,7 @@ declare const DocsCacheSchema: z.ZodObject<{
    * Files to sync: maps destination paths to source locations.
    * Keys are destination paths relative to .tbd/docs/
    * Values are source locations:
-   * - internal: prefix for bundled docs (e.g., "internal:shortcuts/standard/commit-code.md")
+   * - internal: prefix for bundled docs (e.g., "internal:shortcuts/standard/code-review-and-commit.md")
    * - Full URL for external docs (e.g., "https://raw.githubusercontent.com/org/repo/main/file.md")
    */
   files: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -318,7 +326,7 @@ declare const ConfigSchema: z.ZodObject<{
      * Files to sync: maps destination paths to source locations.
      * Keys are destination paths relative to .tbd/docs/
      * Values are source locations:
-     * - internal: prefix for bundled docs (e.g., "internal:shortcuts/standard/commit-code.md")
+     * - internal: prefix for bundled docs (e.g., "internal:shortcuts/standard/code-review-and-commit.md")
      * - Full URL for external docs (e.g., "https://raw.githubusercontent.com/org/repo/main/file.md")
      */
     files: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -456,6 +464,12 @@ declare const AtticEntrySchema: z.ZodObject<{
     remote_updated_at: string;
   };
 }>;
+/**
+ * ID mapping YAML file schema for ids.yml.
+ * Maps short IDs to ULIDs.
+ * Format: { "a7k2": "01hx5zzkbkactav9wevgemmvrz", ... }
+ */
+declare const IdMappingYamlSchema: z.ZodRecord<z.ZodString, z.ZodString>;
 //#endregion
 //#region src/lib/types.d.ts
 /**
@@ -580,5 +594,5 @@ declare function serializeIssue(issue: Issue): string;
  */
 declare const VERSION: string;
 //#endregion
-export { AtticEntry, AtticEntrySchema, BaseEntity, Config, ConfigSchema, CreateIssueOptions, Dependency, DependencyRelationType, DependencyType, DocCacheConfigSchema, DocSection, DocsCacheSchema, EntityType, ExternalIssueIdInput, GitBranchName, GitRemoteName, Issue, IssueId, IssueKind, IssueKindType, IssueSchema, IssueStatus, IssueStatusType, ListIssuesOptions, LocalState, LocalStateSchema, Meta, MetaSchema, Priority, PriorityType, SearchIssuesOptions, ShortId, Timestamp, UpdateIssueOptions, VERSION, Version, parseIssue, serializeIssue };
+export { AtticEntry, AtticEntrySchema, BaseEntity, Config, ConfigSchema, CreateIssueOptions, Dependency, DependencyRelationType, DependencyType, DocCacheConfigSchema, DocSection, DocsCacheSchema, EntityType, ExternalIssueIdInput, GitBranchName, GitRemoteName, IdMappingYamlSchema, Issue, IssueId, IssueKind, IssueKindType, IssueSchema, IssueStatus, IssueStatusType, ListIssuesOptions, LocalState, LocalStateSchema, Meta, MetaSchema, Priority, PriorityType, SearchIssuesOptions, ShortId, Timestamp, Ulid, UpdateIssueOptions, VERSION, Version, parseIssue, serializeIssue };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { C as MetaSchema, D as Version, E as Timestamp, S as LocalStateSchema, T as ShortId, _ as GitRemoteName, b as IssueSchema, c as BaseEntity, d as DependencyRelationType, f as DocCacheConfigSchema, g as GitBranchName, h as ExternalIssueIdInput, i as serializeIssue, l as ConfigSchema, m as EntityType, n as parseIssue, p as DocsCacheSchema, s as AtticEntrySchema, t as VERSION, u as Dependency, v as IssueId, w as Priority, x as IssueStatus, y as IssueKind } from "./src-BfhjLZXE.mjs";
+import { A as Ulid, C as IssueSchema, D as Priority, E as MetaSchema, O as ShortId, S as IssueKind, T as LocalStateSchema, _ as ExternalIssueIdInput, b as IdMappingYamlSchema, d as ConfigSchema, f as Dependency, g as EntityType, h as DocsCacheSchema, i as serializeIssue, j as Version, k as Timestamp, l as AtticEntrySchema, m as DocCacheConfigSchema, n as parseIssue, p as DependencyRelationType, t as VERSION, u as BaseEntity, v as GitBranchName, w as IssueStatus, x as IssueId, y as GitRemoteName } from "./src-DdSZ1dgK.mjs";
 
-export { AtticEntrySchema, BaseEntity, ConfigSchema, Dependency, DependencyRelationType, DocCacheConfigSchema, DocsCacheSchema, EntityType, ExternalIssueIdInput, GitBranchName, GitRemoteName, IssueId, IssueKind, IssueSchema, IssueStatus, LocalStateSchema, MetaSchema, Priority, ShortId, Timestamp, VERSION, Version, parseIssue, serializeIssue };
+export { AtticEntrySchema, BaseEntity, ConfigSchema, Dependency, DependencyRelationType, DocCacheConfigSchema, DocsCacheSchema, EntityType, ExternalIssueIdInput, GitBranchName, GitRemoteName, IdMappingYamlSchema, IssueId, IssueKind, IssueSchema, IssueStatus, LocalStateSchema, MetaSchema, Priority, ShortId, Timestamp, Ulid, VERSION, Version, parseIssue, serializeIssue };

package/dist/{src-BfhjLZXE.mjs → src-DdSZ1dgK.mjs}

@@ -23,8 +23,16 @@ const IssueId = z.string().regex(/^is-[0-9a-z]{26}$/);
 * Short ID: 1+ base36 characters used for external/display IDs.
 * Typically 4 chars for new IDs (e.g., a7k2, b3m9).
 * Imports may preserve longer numeric IDs (e.g., "100" from "tbd-100").
+* Legacy imports may include dots (e.g., "208.1" from hierarchical numbering).
+* Imports may include dashes/underscores (e.g., "stat-in_progress" from JSONL).
 */
-const ShortId = z.string().regex(/^[0-9a-z]+$/);
+const ShortId = z.string().regex(/^[0-9a-z._-]+$/);
+/**
+* ULID: 26 lowercase alphanumeric characters.
+* Used in internal IDs and ID mappings.
+* Example: 01hx5zzkbkactav9wevgemmvrz
+*/
+const Ulid = z.string().regex(/^[0-9a-z]{26}$/);
 /**
 * External Issue ID input: accepts {prefix}-{short} or just {short}.
 * Examples: bd-a7k2, a7k2, bd-100, 100
@@ -129,15 +137,15 @@ const GitRemoteName = z.string().min(1).max(255).regex(/^[a-zA-Z0-9._-]+$/, "Inv
 /**
 * Doc cache configuration - maps destination paths to source locations.
 *
-* Keys are destination paths relative to .tbd/docs/ (e.g., "shortcuts/standard/commit-code.md")
+* Keys are destination paths relative to .tbd/docs/ (e.g., "shortcuts/standard/code-review-and-commit.md")
 * Values are source locations:
-* - internal: prefix for bundled docs (e.g., "internal:shortcuts/standard/commit-code.md")
+* - internal: prefix for bundled docs (e.g., "internal:shortcuts/standard/code-review-and-commit.md")
 * - Full URL for external docs (e.g., "https://raw.githubusercontent.com/org/repo/main/file.md")
 *
 * Example:
 * ```yaml
 * doc_cache:
-*   shortcuts/standard/commit-code.md: internal:shortcuts/standard/commit-code.md
+*   shortcuts/standard/code-review-and-commit.md: internal:shortcuts/standard/code-review-and-commit.md
 *   shortcuts/custom/my-shortcut.md: https://raw.githubusercontent.com/org/repo/main/shortcuts/my-shortcut.md
 * ```
 */
@@ -220,13 +228,147 @@ const AtticEntrySchema = z.object({
 		remote_updated_at: Timestamp
 	})
 });
+/**
+* ID mapping YAML file schema for ids.yml.
+* Maps short IDs to ULIDs.
+* Format: { "a7k2": "01hx5zzkbkactav9wevgemmvrz", ... }
+*/
+const IdMappingYamlSchema = z.record(ShortId, Ulid);
+
+//#endregion
+//#region src/lib/settings.ts
+/**
+* Default line width for YAML serialization.
+* 88 characters is a good balance between readability and avoiding excessive wrapping.
+* (Matches Python's Black formatter default.)
+*/
+const YAML_LINE_WIDTH = 88;
+/**
+* Default string type for YAML serialization.
+* 'PLAIN' means no forced quoting - YAML only quotes when necessary.
+*/
+const YAML_DEFAULT_STRING_TYPE = "PLAIN";
+/**
+* Default key type for YAML serialization.
+* 'PLAIN' means object keys are unquoted unless required.
+*/
+const YAML_DEFAULT_KEY_TYPE = "PLAIN";
+/**
+* Default YAML serialization options for readable output.
+*
+* Design principles:
+* - No forced quoting: YAML only quotes when necessary for special characters
+* - Reasonable line wrapping: 88 chars prevents overly long lines
+* - Plain keys: No unnecessary quotes around object keys
+* - Sorted keys: Deterministic output for diffs and version control
+*/
+const YAML_STRINGIFY_OPTIONS = {
+	lineWidth: YAML_LINE_WIDTH,
+	defaultStringType: YAML_DEFAULT_STRING_TYPE,
+	defaultKeyType: YAML_DEFAULT_KEY_TYPE,
+	sortMapEntries: true
+};
+/**
+* YAML serialization options for compact output (e.g., frontmatter).
+* Uses lineWidth: 0 to prevent wrapping within values.
+*/
+const YAML_STRINGIFY_OPTIONS_COMPACT = {
+	lineWidth: 0,
+	defaultStringType: YAML_DEFAULT_STRING_TYPE,
+	defaultKeyType: YAML_DEFAULT_KEY_TYPE,
+	sortMapEntries: true
+};
+
+//#endregion
+//#region src/utils/yaml-utils.ts
+/**
+* YAML utility functions.
+*
+* Provides centralized YAML parsing and serialization with:
+* - Merge conflict detection for user-editable files
+* - Consistent, readable formatting defaults
+* - Proper handling of special characters (colons, quotes, etc.)
+*
+* IMPORTANT: Always use these utilities instead of raw yaml package functions.
+* This ensures consistent formatting and proper error handling across the codebase.
+*/
+/**
+* Serialize data to YAML with readable formatting.
+*
+* Uses consistent defaults:
+* - No forced quoting (YAML only quotes when necessary)
+* - lineWidth of 88 provides reasonable wrapping for long strings
+* - Plain keys without quotes
+* - Sorted keys for deterministic output
+*
+* @param data - Data to serialize
+* @param options - Optional overrides for default options
+* @returns YAML string
+*/
+function stringifyYaml(data, options) {
+	return stringify(data, {
+		...YAML_STRINGIFY_OPTIONS,
+		...options
+	});
+}
+/**
+* Serialize data to YAML without line wrapping (compact mode).
+* Useful for frontmatter where values should stay on single lines.
+*
+* @param data - Data to serialize
+* @returns YAML string with no line wrapping
+*/
+function stringifyYamlCompact(data) {
+	return stringify(data, YAML_STRINGIFY_OPTIONS_COMPACT);
+}
+/**
+* Error thrown when YAML content contains unresolved merge conflict markers.
+*/
+var MergeConflictError = class extends Error {
+	constructor(message, filePath) {
+		super(message);
+		this.filePath = filePath;
+		this.name = "MergeConflictError";
+	}
+};
+/**
+* Regex patterns for git merge conflict markers.
+*/
+const CONFLICT_PATTERNS = {
+	start: /^<<<<<<< /m,
+	separator: /^=======/m,
+	end: /^>>>>>>> /m
+};
+/**
+* Check if content contains git merge conflict markers.
+*/
+function hasMergeConflictMarkers(content) {
+	return CONFLICT_PATTERNS.start.test(content) || CONFLICT_PATTERNS.separator.test(content) || CONFLICT_PATTERNS.end.test(content);
+}
+/**
+* Parse YAML content with merge conflict detection.
+*
+* If the content contains merge conflict markers, throws a MergeConflictError
+* with a helpful message instead of a cryptic YAML parse error.
+*
+* @param content - The YAML content to parse
+* @param filePath - Optional file path for error messages
+* @returns Parsed YAML data
+* @throws MergeConflictError if content has conflict markers
+* @throws Error if YAML is invalid for other reasons
+*/
+function parseYamlWithConflictDetection(content, filePath) {
+	if (hasMergeConflictMarkers(content)) throw new MergeConflictError(`File${filePath ? ` in ${filePath}` : ""} contains unresolved git merge conflict markers.\nThis usually happens when 'tbd sync' encountered conflicts that weren't properly resolved.\nTo fix: manually edit the file to resolve conflicts, or run 'tbd doctor --fix'.`, filePath);
+	return parse(content);
+}
 
 //#endregion
 //#region src/utils/markdown-utils.ts
 /**
 * Markdown utilities for processing markdown content.
 *
-* Uses gray-matter for consistent frontmatter parsing across the codebase.
+* Uses gray-matter for parsing and centralized yaml-utils for stringify to ensure
+* proper handling of special YAML characters (colons, quotes, etc.).
 */
 /**
 * Normalize line endings to LF.
@@ -250,17 +392,8 @@ function parseMarkdown(content) {
 		const parsed = matter(normalized);
 		const data = parsed.data;
 		let frontmatter = null;
-		if (data && Object.keys(data).length > 0) {
-			const lines = [];
-			for (const [key, value] of Object.entries(data)) if (Array.isArray(value)) {
-				lines.push(`${key}:`);
-				for (const item of value) lines.push(`  - ${String(item)}`);
-			} else if (typeof value === "object" && value !== null) {
-				lines.push(`${key}:`);
-				for (const [subKey, subValue] of Object.entries(value)) lines.push(`  ${subKey}: ${String(subValue)}`);
-			} else lines.push(`${key}: ${String(value)}`);
-			frontmatter = lines.join("\n");
-		} else frontmatter = "";
+		if (data && Object.keys(data).length > 0) frontmatter = stringifyYamlCompact(data).trimEnd();
+		else frontmatter = "";
 		const body = parsed.content.replace(/^\n+/, "");
 		return {
 			frontmatter,
@@ -318,7 +451,7 @@ function insertAfterFrontmatter(content, toInsert) {
 */
 const matterOptions = { engines: { yaml: {
 	parse: (str) => parse(str),
-	stringify: (obj) => stringify(obj)
+	stringify: (obj) => stringifyYaml(obj)
 } } };
 /**
 * Parse a Markdown file with YAML front matter.
@@ -375,8 +508,7 @@ function serializeIssue(issue) {
 	for (const key of Object.keys(metadata).sort()) sortedMetadata[key] = metadata[key];
 	const parts = [
 		"---",
-		stringify(sortedMetadata, {
-			sortMapEntries: true,
+		stringifyYaml(sortedMetadata, {
 			lineWidth: 0,
 			nullStr: "null"
 		}).trim(),
@@ -398,8 +530,8 @@ 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 = "0.1.13";
+const VERSION = "0.1.14";
 
 //#endregion
-export { MetaSchema as C, Version as D, Timestamp as E, LocalStateSchema as S, ShortId as T, GitRemoteName as _, insertAfterFrontmatter as a, IssueSchema as b, BaseEntity as c, DependencyRelationType as d, DocCacheConfigSchema as f, GitBranchName as g, ExternalIssueIdInput as h, serializeIssue as i, ConfigSchema as l, EntityType as m, parseIssue as n, stripFrontmatter as o, DocsCacheSchema as p, parseMarkdownWithFrontmatter as r, AtticEntrySchema as s, VERSION as t, Dependency as u, IssueId as v, Priority as w, IssueStatus as x, IssueKind as y };
-//# sourceMappingURL=src-BfhjLZXE.mjs.map
+export { Ulid as A, IssueSchema as C, Priority as D, MetaSchema as E, ShortId as O, IssueKind as S, LocalStateSchema as T, ExternalIssueIdInput as _, insertAfterFrontmatter as a, IdMappingYamlSchema as b, stringifyYaml as c, ConfigSchema as d, Dependency as f, EntityType as g, DocsCacheSchema as h, serializeIssue as i, Version as j, Timestamp as k, AtticEntrySchema as l, DocCacheConfigSchema as m, parseIssue as n, stripFrontmatter as o, DependencyRelationType as p, parseMarkdownWithFrontmatter as r, parseYamlWithConflictDetection as s, VERSION as t, BaseEntity as u, GitBranchName as v, IssueStatus as w, IssueId as x, GitRemoteName as y };
+//# sourceMappingURL=src-DdSZ1dgK.mjs.map

package/dist/src-DdSZ1dgK.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"src-DdSZ1dgK.mjs","names":["parseYaml","parseYaml"],"sources":["../src/lib/schemas.ts","../src/lib/settings.ts","../src/utils/yaml-utils.ts","../src/utils/markdown-utils.ts","../src/file/parser.ts","../src/index.ts"],"sourcesContent":["/**\n * Zod schemas for tbd entities.\n *\n * These schemas are the normative specification for the file format.\n * See: tbd-design.md §2.6 Schemas\n */\n\nimport { z } from 'zod';\n\n// =============================================================================\n// Common Types (§2.6.1)\n// =============================================================================\n\n/**\n * ISO8601 timestamp with Z suffix (UTC).\n */\nexport const Timestamp = z.string().datetime();\n\n/**\n * Issue ID: prefix + 26 lowercase alphanumeric characters (ULID format).\n * Format: is-{ulid} where ulid is 26 chars (a-z, 0-9).\n * Example: is-01hx5zzkbkactav9wevgemmvrz\n */\nexport const IssueId = z.string().regex(/^is-[0-9a-z]{26}$/);\n\n/**\n * Short ID: 1+ base36 characters used for external/display IDs.\n * Typically 4 chars for new IDs (e.g., a7k2, b3m9).\n * Imports may preserve longer numeric IDs (e.g., \"100\" from \"tbd-100\").\n * Legacy imports may include dots (e.g., \"208.1\" from hierarchical numbering).\n * Imports may include dashes/underscores (e.g., \"stat-in_progress\" from JSONL).\n */\nexport const ShortId = z.string().regex(/^[0-9a-z._-]+$/);\n\n/**\n * ULID: 26 lowercase alphanumeric characters.\n * Used in internal IDs and ID mappings.\n * Example: 01hx5zzkbkactav9wevgemmvrz\n */\nexport const Ulid = z.string().regex(/^[0-9a-z]{26}$/);\n\n/**\n * External Issue ID input: accepts {prefix}-{short} or just {short}.\n * Examples: bd-a7k2, a7k2, bd-100, 100\n */\nexport const ExternalIssueIdInput = z.string().regex(/^([a-z]+-)?[0-9a-z]+$/);\n\n/**\n * Edit counter - incremented on every local change.\n * NOTE: Version is NOT used for conflict detection (Git push rejection is used).\n * Content hash is used as tiebreaker during merge resolution.\n * Version is informational only - set to max(local, remote) + 1 after merges.\n */\nexport const Version = z.number().int().nonnegative();\n\n/**\n * Entity type discriminator.\n */\nexport const EntityType = z.literal('is');\n\n// =============================================================================\n// BaseEntity (§2.6.2)\n// =============================================================================\n\n/**\n * All entities share common fields.\n */\nexport const BaseEntity = z.object({\n  type: EntityType,\n  id: IssueId,\n  version: Version,\n  created_at: Timestamp,\n  updated_at: Timestamp,\n\n  // Extensibility namespace for third-party data\n  extensions: z.record(z.string(), z.unknown()).optional(),\n});\n\n// =============================================================================\n// Issue Schema (§2.6.3)\n// =============================================================================\n\n/**\n * Issue status values matching Beads.\n */\nexport const IssueStatus = z.enum(['open', 'in_progress', 'blocked', 'deferred', 'closed']);\n\n/**\n * Issue kind/type values matching Beads.\n * Note: CLI uses --type flag, which maps to this `kind` field.\n */\nexport const IssueKind = z.enum(['bug', 'feature', 'task', 'epic', 'chore']);\n\n/**\n * Priority: 0 (highest/critical) to 4 (lowest).\n */\nexport const Priority = z.number().int().min(0).max(4);\n\n/**\n * Dependency types - only \"blocks\" supported initially.\n */\nexport const DependencyRelationType = z.enum(['blocks']);\n\n/**\n * A dependency relationship.\n */\nexport const Dependency = z.object({\n  type: DependencyRelationType,\n  target: IssueId,\n});\n\n/**\n * Full issue schema.\n *\n * Note: Fields use .nullable() in addition to .optional() because\n * YAML parses `field: null` as JavaScript null, not undefined.\n */\nexport const IssueSchema = BaseEntity.extend({\n  type: z.literal('is'),\n\n  title: z.string().min(1).max(500),\n  description: z.string().max(50000).nullable().optional(),\n  notes: z.string().max(50000).nullable().optional(),\n\n  kind: IssueKind.default('task'),\n  status: IssueStatus.default('open'),\n  priority: Priority.default(2),\n\n  assignee: z.string().nullable().optional(),\n  labels: z.array(z.string()).default([]),\n  dependencies: z.array(Dependency).default([]),\n\n  // Hierarchical issues\n  parent_id: IssueId.nullable().optional(),\n\n  // Child ordering hints - soft ordering for children under this parent.\n  // Array of internal IssueIds in preferred display order.\n  // May contain stale IDs; display logic filters for actual children.\n  child_order_hints: z.array(IssueId).nullable().optional(),\n\n  // Beads compatibility\n  due_date: Timestamp.nullable().optional(),\n  deferred_until: Timestamp.nullable().optional(),\n\n  created_by: z.string().nullable().optional(),\n  closed_at: Timestamp.nullable().optional(),\n  close_reason: z.string().nullable().optional(),\n\n  // Spec linking - path to related spec/doc (relative to repo root)\n  spec_path: z.string().nullable().optional(),\n});\n\n// =============================================================================\n// Config Schema (§2.6.4)\n// =============================================================================\n\n/**\n * Git branch name - restricted to safe characters.\n * Allows: alphanumeric, hyphens, underscores, forward slashes, and dots.\n * Prevents shell injection in git commands.\n */\nexport const GitBranchName = z\n  .string()\n  .min(1)\n  .max(255)\n  .regex(\n    /^[a-zA-Z0-9._/-]+$/,\n    'Invalid branch name: only alphanumeric, dots, underscores, hyphens, and slashes allowed',\n  );\n\n/**\n * Git remote name - restricted to safe characters.\n * Allows: alphanumeric, hyphens, underscores, and dots.\n * Prevents shell injection in git commands.\n */\nexport const GitRemoteName = z\n  .string()\n  .min(1)\n  .max(255)\n  .regex(\n    /^[a-zA-Z0-9._-]+$/,\n    'Invalid remote name: only alphanumeric, dots, underscores, and hyphens allowed',\n  );\n\n/**\n * Doc cache configuration - maps destination paths to source locations.\n *\n * Keys are destination paths relative to .tbd/docs/ (e.g., \"shortcuts/standard/code-review-and-commit.md\")\n * Values are source locations:\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 *\n * Example:\n * ```yaml\n * doc_cache:\n *   shortcuts/standard/code-review-and-commit.md: internal:shortcuts/standard/code-review-and-commit.md\n *   shortcuts/custom/my-shortcut.md: https://raw.githubusercontent.com/org/repo/main/shortcuts/my-shortcut.md\n * ```\n */\nexport const DocCacheConfigSchema = z.record(z.string(), z.string());\n\n/**\n * Documentation cache configuration (consolidated structure).\n *\n * Combines file sync mappings and lookup paths into a single config block.\n * See: docs/project/specs/active/plan-2026-01-26-docs-cache-config-restructure.md\n */\nexport const DocsCacheSchema = z.object({\n  /**\n   * Files to sync: maps destination paths to source locations.\n   * Keys are destination paths relative to .tbd/docs/\n   * Values are source locations:\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   */\n  files: z.record(z.string(), z.string()).optional(),\n  /**\n   * Search paths for doc lookup (like shell $PATH).\n   * Earlier paths take precedence when names conflict.\n   */\n  lookup_path: z\n    .array(z.string())\n    .default(['.tbd/docs/shortcuts/system', '.tbd/docs/shortcuts/standard']),\n});\n\n/**\n * Project configuration stored in .tbd/config.yml\n *\n * ⚠️ FORMAT VERSIONING: See tbd-format.ts for version history and migration rules.\n * The tbd_format field tracks breaking changes to this schema.\n *\n * ⚠️ FORWARD COMPATIBILITY POLICY:\n * This schema uses Zod's default strip() mode, which discards unknown fields.\n * To prevent data loss when users mix tbd versions:\n *\n * 1. **When changing config schema (adding, removing, or modifying fields), ALWAYS\n *    bump the format version** (e.g., f03 → f04)\n * 2. Older tbd versions will error when they see an unknown format version\n * 3. The error message tells users to upgrade tbd\n *\n * This ensures older versions fail fast rather than silently corrupting config.\n * The format version check happens in config.ts via isCompatibleFormat().\n *\n * See tbd-format.ts for format version history and migration rules.\n */\nexport const ConfigSchema = z.object({\n  /**\n   * Format version for the .tbd/ directory structure.\n   * See tbd-format.ts for version history and migration rules.\n   * Only bumped for breaking changes that require migration.\n   */\n  tbd_format: z.string().default('f01'),\n\n  tbd_version: z.string(),\n  sync: z\n    .object({\n      branch: GitBranchName.default('tbd-sync'),\n      remote: GitRemoteName.default('origin'),\n    })\n    .default({}),\n  display: z.object({\n    id_prefix: z.string().min(1).max(20), // Required: set during init --prefix or import\n  }),\n  settings: z\n    .object({\n      auto_sync: z.boolean().default(false),\n      /**\n       * How often to automatically sync documentation cache (in hours).\n       * - Default: 24 (sync once per day when actively using tbd)\n       * - Set to 0 to disable auto-sync\n       * - Only triggers when accessing docs (shortcut, guidelines, template commands)\n       */\n      doc_auto_sync_hours: z.number().default(24),\n      /**\n       * Whether to install the ensure-gh-cli.sh hook script during setup.\n       * When true (default), `tbd setup` installs a SessionStart hook that\n       * ensures the GitHub CLI is available in agent sessions.\n       * Set to false or use `tbd setup --no-gh-cli` to disable.\n       */\n      use_gh_cli: z.boolean().default(true),\n    })\n    .default({}),\n  /**\n   * Documentation cache configuration (consolidated).\n   * Contains files to sync and lookup paths.\n   * See DocsCacheSchema for structure details.\n   */\n  docs_cache: DocsCacheSchema.optional(),\n});\n\n// =============================================================================\n// Meta Schema (§2.6.5)\n// =============================================================================\n\n/**\n * Shared metadata stored in .tbd/data-sync/meta.yml\n */\nexport const MetaSchema = z.object({\n  schema_version: z.number().int(),\n  created_at: Timestamp,\n});\n\n// =============================================================================\n// Local State Schema (§2.6.6)\n// =============================================================================\n\n/**\n * Per-node state stored in .tbd/state.yml (gitignored).\n * Tracks local timing information that shouldn't be shared across nodes.\n */\nexport const LocalStateSchema = z.object({\n  /** When this node last synced issues successfully */\n  last_sync_at: Timestamp.optional(),\n  /** When this node last synced the doc cache successfully */\n  last_doc_sync_at: Timestamp.optional(),\n  /** Whether the user has seen the welcome message */\n  welcome_seen: z.boolean().optional(),\n});\n\n// =============================================================================\n// Attic Entry Schema (§2.6.7)\n// =============================================================================\n\n/**\n * Preserved conflict losers.\n */\nexport const AtticEntrySchema = z.object({\n  entity_id: IssueId,\n  timestamp: Timestamp,\n  field: z.string(),\n  lost_value: z.string(),\n  winner_source: z.enum(['local', 'remote']),\n  loser_source: z.enum(['local', 'remote']),\n  context: z.object({\n    local_version: Version,\n    remote_version: Version,\n    local_updated_at: Timestamp,\n    remote_updated_at: Timestamp,\n  }),\n});\n\n// =============================================================================\n// ID Mapping Schema (§2.6.8)\n// =============================================================================\n\n/**\n * ID mapping YAML file schema for ids.yml.\n * Maps short IDs to ULIDs.\n * Format: { \"a7k2\": \"01hx5zzkbkactav9wevgemmvrz\", ... }\n */\nexport const IdMappingYamlSchema = z.record(ShortId, Ulid);\n","/**\n * Global settings and configuration constants.\n *\n * Centralized location for project-wide defaults that may need tuning.\n * These are compile-time constants, not runtime configuration.\n */\n\nimport type { DocumentOptions, SchemaOptions, ToStringOptions } from 'yaml';\n\n// =============================================================================\n// YAML Formatting\n// =============================================================================\n\n/**\n * Default line width for YAML serialization.\n * 88 characters is a good balance between readability and avoiding excessive wrapping.\n * (Matches Python's Black formatter default.)\n */\nexport const YAML_LINE_WIDTH = 88;\n\n/**\n * Default string type for YAML serialization.\n * 'PLAIN' means no forced quoting - YAML only quotes when necessary.\n */\nexport const YAML_DEFAULT_STRING_TYPE = 'PLAIN' as const;\n\n/**\n * Default key type for YAML serialization.\n * 'PLAIN' means object keys are unquoted unless required.\n */\nexport const YAML_DEFAULT_KEY_TYPE = 'PLAIN' as const;\n\n/**\n * Combined options type for YAML stringify.\n */\nexport type YamlStringifyOptions = DocumentOptions & SchemaOptions & ToStringOptions;\n\n/**\n * Default YAML serialization options for readable output.\n *\n * Design principles:\n * - No forced quoting: YAML only quotes when necessary for special characters\n * - Reasonable line wrapping: 88 chars prevents overly long lines\n * - Plain keys: No unnecessary quotes around object keys\n * - Sorted keys: Deterministic output for diffs and version control\n */\nexport const YAML_STRINGIFY_OPTIONS: YamlStringifyOptions = {\n  lineWidth: YAML_LINE_WIDTH,\n  defaultStringType: YAML_DEFAULT_STRING_TYPE,\n  defaultKeyType: YAML_DEFAULT_KEY_TYPE,\n  sortMapEntries: true,\n};\n\n/**\n * YAML serialization options for compact output (e.g., frontmatter).\n * Uses lineWidth: 0 to prevent wrapping within values.\n */\nexport const YAML_STRINGIFY_OPTIONS_COMPACT: YamlStringifyOptions = {\n  lineWidth: 0, // No wrapping\n  defaultStringType: YAML_DEFAULT_STRING_TYPE,\n  defaultKeyType: YAML_DEFAULT_KEY_TYPE,\n  sortMapEntries: true,\n};\n\n// =============================================================================\n// Text Formatting\n// =============================================================================\n\n/**\n * Default line width for text output (terminal, markdown).\n * Same as YAML for consistency.\n */\nexport const TEXT_LINE_WIDTH = 88;\n","/**\n * YAML utility functions.\n *\n * Provides centralized YAML parsing and serialization with:\n * - Merge conflict detection for user-editable files\n * - Consistent, readable formatting defaults\n * - Proper handling of special characters (colons, quotes, etc.)\n *\n * IMPORTANT: Always use these utilities instead of raw yaml package functions.\n * This ensures consistent formatting and proper error handling across the codebase.\n */\n\nimport { parse as parseYaml, stringify } from 'yaml';\n\nimport {\n  YAML_LINE_WIDTH,\n  YAML_STRINGIFY_OPTIONS,\n  YAML_STRINGIFY_OPTIONS_COMPACT,\n  type YamlStringifyOptions,\n} from '../lib/settings.js';\n\n// Re-export for convenience\nexport { YAML_LINE_WIDTH, YAML_STRINGIFY_OPTIONS, YAML_STRINGIFY_OPTIONS_COMPACT };\n\n// =============================================================================\n// Serialization Functions\n// =============================================================================\n\n/**\n * Serialize data to YAML with readable formatting.\n *\n * Uses consistent defaults:\n * - No forced quoting (YAML only quotes when necessary)\n * - lineWidth of 88 provides reasonable wrapping for long strings\n * - Plain keys without quotes\n * - Sorted keys for deterministic output\n *\n * @param data - Data to serialize\n * @param options - Optional overrides for default options\n * @returns YAML string\n */\nexport function stringifyYaml(data: unknown, options?: Partial<YamlStringifyOptions>): string {\n  return stringify(data, { ...YAML_STRINGIFY_OPTIONS, ...options });\n}\n\n/**\n * Serialize data to YAML without line wrapping (compact mode).\n * Useful for frontmatter where values should stay on single lines.\n *\n * @param data - Data to serialize\n * @returns YAML string with no line wrapping\n */\nexport function stringifyYamlCompact(data: unknown): string {\n  return stringify(data, YAML_STRINGIFY_OPTIONS_COMPACT);\n}\n\n/**\n * Error thrown when YAML content contains unresolved merge conflict markers.\n */\nexport class MergeConflictError extends Error {\n  constructor(\n    message: string,\n    public readonly filePath?: string,\n  ) {\n    super(message);\n    this.name = 'MergeConflictError';\n  }\n}\n\n/**\n * Regex patterns for git merge conflict markers.\n */\nconst CONFLICT_PATTERNS = {\n  start: /^<<<<<<< /m,\n  separator: /^=======/m,\n  end: /^>>>>>>> /m,\n};\n\n/**\n * Check if content contains git merge conflict markers.\n */\nexport function hasMergeConflictMarkers(content: string): boolean {\n  return (\n    CONFLICT_PATTERNS.start.test(content) ||\n    CONFLICT_PATTERNS.separator.test(content) ||\n    CONFLICT_PATTERNS.end.test(content)\n  );\n}\n\n/**\n * Parse YAML content with merge conflict detection.\n *\n * If the content contains merge conflict markers, throws a MergeConflictError\n * with a helpful message instead of a cryptic YAML parse error.\n *\n * @param content - The YAML content to parse\n * @param filePath - Optional file path for error messages\n * @returns Parsed YAML data\n * @throws MergeConflictError if content has conflict markers\n * @throws Error if YAML is invalid for other reasons\n */\nexport function parseYamlWithConflictDetection<T = unknown>(content: string, filePath?: string): T {\n  // Check for merge conflict markers first\n  if (hasMergeConflictMarkers(content)) {\n    const location = filePath ? ` in ${filePath}` : '';\n    throw new MergeConflictError(\n      `File${location} contains unresolved git merge conflict markers.\\n` +\n        `This usually happens when 'tbd sync' encountered conflicts that weren't properly resolved.\\n` +\n        `To fix: manually edit the file to resolve conflicts, or run 'tbd doctor --fix'.`,\n      filePath,\n    );\n  }\n\n  return parseYaml(content) as T;\n}\n","/**\n * Markdown utilities for processing markdown content.\n *\n * Uses gray-matter for parsing and centralized yaml-utils for stringify to ensure\n * proper handling of special YAML characters (colons, quotes, etc.).\n */\n\nimport matter from 'gray-matter';\n\nimport { stringifyYamlCompact } from './yaml-utils.js';\n\nexport interface ParsedMarkdown {\n  /** Raw frontmatter string (without --- delimiters), or null if no frontmatter */\n  frontmatter: string | null;\n  /** Body content after frontmatter, with leading newlines trimmed */\n  body: string;\n}\n\n/**\n * Normalize line endings to LF.\n */\nexport function normalizeLineEndings(content: string): string {\n  return content.replace(/\\r\\n/g, '\\n').replace(/\\r/g, '\\n');\n}\n\n/**\n * Parse markdown content into frontmatter and body.\n * Handles both LF and CRLF line endings.\n *\n * @returns Object with frontmatter (null if none) and body\n */\nexport function parseMarkdown(content: string): ParsedMarkdown {\n  const normalized = normalizeLineEndings(content);\n\n  if (!matter.test(normalized)) {\n    return { frontmatter: null, body: content };\n  }\n\n  try {\n    const parsed = matter(normalized);\n\n    // Extract frontmatter from parsed.data by stringifying back to YAML\n    // The matter property is unreliable, so we reconstruct from data\n    const data = parsed.data;\n    let frontmatter: string | null = null;\n\n    if (data && Object.keys(data).length > 0) {\n      // Use centralized yaml-utils for proper handling of special characters\n      // (colons, quotes, multiline strings, etc.)\n      frontmatter = stringifyYamlCompact(data).trimEnd();\n    } else {\n      // Empty frontmatter (just --- followed by ---)\n      frontmatter = '';\n    }\n\n    // Body with leading newlines trimmed\n    const body = parsed.content.replace(/^\\n+/, '');\n\n    return { frontmatter, body };\n  } catch {\n    // Invalid/unclosed frontmatter - treat as no frontmatter\n    return { frontmatter: null, body: content };\n  }\n}\n\n/**\n * Parse YAML frontmatter from markdown content.\n * Returns the frontmatter content (without delimiters) or null if no valid frontmatter.\n * Handles both LF and CRLF line endings.\n */\nexport function parseFrontmatter(content: string): string | null {\n  return parseMarkdown(content).frontmatter;\n}\n\n/**\n * Strip YAML frontmatter from markdown content.\n * Returns the body content without frontmatter, with leading newlines trimmed.\n * Handles both LF and CRLF line endings.\n */\nexport function stripFrontmatter(content: string): string {\n  return parseMarkdown(content).body;\n}\n\n/**\n * Insert content after YAML frontmatter.\n * If no frontmatter exists, prepends the content.\n * Content is inserted directly after ---. Include leading newlines in toInsert if needed.\n */\nexport function insertAfterFrontmatter(content: string, toInsert: string): string {\n  const { frontmatter, body } = parseMarkdown(content);\n\n  if (frontmatter === null) {\n    return toInsert + content;\n  }\n\n  const frontmatterBlock = frontmatter ? `---\\n${frontmatter}\\n---` : '---\\n---';\n  return `${frontmatterBlock}\\n${toInsert}\\n\\n${body}`;\n}\n","/**\n * YAML front matter parser and serializer for issue files.\n *\n * Issues are stored as Markdown files with YAML front matter:\n * ---\n * type: is\n * id: is-a1b2c3\n * ...\n * ---\n *\n * Description body here.\n *\n * ## Notes\n *\n * Working notes here.\n *\n * See: tbd-design.md §2.1 Markdown + YAML Front Matter Format\n */\n\nimport matter from 'gray-matter';\nimport { parse as parseYaml } from 'yaml';\n\nimport { normalizeLineEndings } from '../utils/markdown-utils.js';\nimport { stringifyYaml } from '../utils/yaml-utils.js';\nimport type { Issue } from '../lib/types.js';\nimport { IssueSchema } from '../lib/schemas.js';\n\n/**\n * gray-matter options using the 'yaml' package as engine.\n * This preserves date strings instead of converting them to Date objects.\n */\nexport const matterOptions = {\n  engines: {\n    yaml: {\n      parse: (str: string): object => parseYaml(str) as object,\n      stringify: (obj: object): string => stringifyYaml(obj),\n    },\n  },\n};\n\n/**\n * Parsed issue file content.\n */\nexport interface ParsedIssueFile {\n  frontmatter: Record<string, unknown>;\n  description: string;\n  notes: string;\n}\n\n/**\n * Parse a Markdown file with YAML front matter.\n * Uses gray-matter for consistent frontmatter parsing.\n * Handles both LF and CRLF line endings.\n */\nexport function parseMarkdownWithFrontmatter(content: string): ParsedIssueFile {\n  // Normalize CRLF to LF before parsing\n  const normalizedContent = normalizeLineEndings(content);\n\n  // Check for valid frontmatter\n  if (!matter.test(normalizedContent)) {\n    throw new Error('Invalid format: missing front matter opening delimiter');\n  }\n\n  const parsed = matter(normalizedContent, matterOptions);\n\n  // gray-matter returns empty object if no closing delimiter found\n  // but the raw matter string will be empty if parsing failed\n  if (parsed.matter === '' && !normalizedContent.includes('---\\n---')) {\n    // Check if there's actually a closing delimiter\n    const lines = normalizedContent.split('\\n');\n    let hasClosing = false;\n    for (let i = 1; i < lines.length; i++) {\n      if (lines[i]?.trim() === '---') {\n        hasClosing = true;\n        break;\n      }\n    }\n    if (!hasClosing) {\n      throw new Error('Invalid format: missing front matter closing delimiter');\n    }\n  }\n\n  const frontmatter = parsed.data as Record<string, unknown>;\n\n  // Parse body - split into description and notes\n  const body = parsed.content.trim();\n\n  // Find notes section\n  const notesMatch = /\\n## Notes\\n/i.exec(body);\n  let description = body;\n  let notes = '';\n\n  if (notesMatch?.index !== undefined) {\n    description = body.slice(0, notesMatch.index).trim();\n    notes = body.slice(notesMatch.index + notesMatch[0].length).trim();\n  }\n\n  return { frontmatter, description, notes };\n}\n\n/**\n * Parse an issue from Markdown file content.\n */\nexport function parseIssue(content: string): Issue {\n  const { frontmatter, description, notes } = parseMarkdownWithFrontmatter(content);\n\n  // Merge body content into frontmatter\n  const data = {\n    ...frontmatter,\n    description: description || undefined,\n    notes: notes || undefined,\n  };\n\n  // Validate and parse with Zod\n  return IssueSchema.parse(data);\n}\n\n/**\n * Serialize an issue to Markdown file content.\n * Uses canonical serialization for deterministic output.\n */\nexport function serializeIssue(issue: Issue): string {\n  // Extract body fields\n  const { description, notes, ...metadata } = issue;\n\n  // Sort keys alphabetically for canonical output\n  const sortedMetadata: Record<string, unknown> = {};\n  for (const key of Object.keys(metadata).sort()) {\n    sortedMetadata[key] = metadata[key as keyof typeof metadata];\n  }\n\n  // Serialize YAML with compact output for frontmatter (sortMapEntries is in defaults)\n  const yaml = stringifyYaml(sortedMetadata, {\n    lineWidth: 0, // No wrapping\n    nullStr: 'null',\n  });\n\n  // Build the file content\n  // Note: No blank line between closing --- and body content\n  const parts = ['---', yaml.trim(), '---'];\n\n  if (description) {\n    parts.push(description.trim());\n  }\n\n  if (notes) {\n    parts.push('');\n    parts.push('## Notes');\n    parts.push('');\n    parts.push(notes.trim());\n  }\n\n  // Single newline at end\n  return parts.join('\\n') + '\\n';\n}\n","/**\n * tbd: Git-native issue tracking for AI agents and humans\n *\n * This is the library entry point. All exports here should be node-free\n * to support browser/edge runtime usage. CLI-specific code is in ./cli/.\n */\n\n// Version injected at build time\ndeclare const __TBD_VERSION__: string;\n\n/**\n * Package version, derived from git at build time.\n * Format: X.Y.Z for releases, X.Y.Z-dev.N.hash for dev builds.\n */\nexport const VERSION: string =\n  typeof __TBD_VERSION__ !== 'undefined' ? __TBD_VERSION__ : 'development';\n\n// Re-export schemas for library consumers\nexport * from './lib/schemas.js';\nexport * from './lib/types.js';\n\n// Re-export core operations (these should be node-free)\nexport { parseIssue, serializeIssue } from './file/parser.js';\n"],"mappings":"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"}