get-tbd 0.1.27 → 0.1.29

package/dist/docs/guidelines/supply-chain-hardening.md

@@ -0,0 +1,237 @@
+---
+title: Supply-Chain Hardening
+description: Strongly recommended for EVERY repo — apply it if a repo has not been hardened yet. Cross-ecosystem policy for installing dependencies safely (the 14-day cool-off, disabled install scripts, lockfile discipline, untrusted-repo handling). Use whenever a user mentions hardening, security, supply chain, or setting up a new repo; before adding/upgrading dependencies; when auditing for compromised packages; or when reviewing install/build/run commands across npm/pnpm, PyPI, Cargo, or Go.
+author: Joshua Levy (github.com/jlevy) with LLM assistance
+---
+# Supply-Chain Hardening
+
+A concise, cross-ecosystem policy for reducing supply-chain risk when installing or
+upgrading dependencies.
+Open-source registries (npm, PyPI, crates.io, Go modules) are under sustained attack:
+malicious package versions are published, exfiltrate credentials or install persistence,
+and are usually yanked within minutes to days.
+
+**Strongly recommended for every repo.** If a project has not been hardened yet, apply
+this policy (and the per-ecosystem playbooks it links) as part of setup — it is
+especially worth doing when standing up a new repo or whenever security comes up.
+
+**This is the concise policy.** For the full playbooks (per-ecosystem ten-minute setups,
+a zero-dependency audit script, a curated watch list of named incidents, CI/publish-side
+hardening, and the threat-model research), see the **Supply Chain Hardening guidebook**:
+<https://github.com/jlevy/supply-chain-hardening>. For monorepo-specific enforcement,
+see `tbd guidelines bun-monorepo-patterns` or `tbd guidelines pnpm-monorepo-patterns`.
+
+**When to use this guideline**: before adding or upgrading any dependency; when
+hardening a workstation, repo, or CI pipeline; when assessing whether an installed
+package is compromised; or when reviewing any `install` / `build` / `run` command —
+especially in a freshly cloned third-party repo.
+
+## The Default: a 14-Day Cool-Off
+
+**Never install or upgrade to a package version less than 14 days old, unless a
+documented exception applies.** This is the single most effective default.
+It works because registries and researchers detect and yank malicious versions while
+legitimate versions keep accruing age — so the only cost of waiting is slightly staler
+dependencies.
+
+**14 days is a floor, not a ceiling.** A 30/60/90-day window is strictly safer; machines
+with publish tokens or production access should go higher.
+Scope: applies to `dependencies`, `devDependencies` (historically *more* dangerous —
+build tooling runs with full privileges), `peer`/`optionalDependencies`, new installs,
+and upgrades.
+Pins resolved before adopting the policy are grandfathered until their next
+planned upgrade.
+
+### Per-ecosystem control
+
+| Tool | 14-day control |
+| --- | --- |
+| npm (any) | `NPM_CONFIG_BEFORE=<now-14d>` (absolute ISO date) |
+| npm 11.10+ | `NPM_CONFIG_MIN_RELEASE_AGE=14` (days) |
+| pnpm 10.16–10.x | `NPM_CONFIG_MINIMUM_RELEASE_AGE=20160` (minutes) |
+| pnpm 11+ | `minimumReleaseAge: 20160` in `pnpm-workspace.yaml` (pnpm 11 ignores `NPM_CONFIG_*`; env prefix is `PNPM_CONFIG_*`) |
+| uv | `UV_EXCLUDE_NEWER="14 days"` |
+| pip 26.1+ | `PIP_UPLOADED_PRIOR_TO="P14D"` |
+| Cargo / Go | no native gate: commit the lockfile, pass `--locked` (Cargo) / keep `go.sum` + `-mod=readonly` (Go), and require human review before re-resolving; gate automated bumps with Renovate/Dependabot release-age policy |
+
+At upgrade-decision time, `npm-check-updates --cooldown 14` (pin the `ncu` version)
+gates which upgrades are even offered.
+To check one version’s age: `npm view <pkg> time.<ver>`.
+
+## The Other Install Rules
+
+1. **Never install unthinkingly.** Before any `pnpm add` / `npm i` / `uv add` /
+   `pip install` / `cargo install` / `go install`: confirm the package is needed, the
+   name is spelled correctly (typosquats are common), and the version clears the
+   cool-off (or is lockfile-pinned, or has a stated exception).
+2. **Disable install/lifecycle scripts by default** — the primary exfiltration vector in
+   worm-class attacks (`NPM_CONFIG_IGNORE_SCRIPTS=true`; pnpm `ignoreScripts: true` +
+   `allowBuilds` allowlist; refuse PyPI sdist builds with
+   `UV_NO_BUILD`/`PIP_ONLY_BINARY`).
+3. **Commit lockfiles; install frozen.** `pnpm install --frozen-lockfile` / `npm ci` /
+   `--locked`. Never auto-update without review.
+4. **Audit after every install** — `pnpm audit` / `npm audit` / `pip-audit` /
+   `cargo audit` / `govulncheck`; address findings before continuing.
+5. **Don’t update for its own sake.** The safest update is the one you skip — each bump
+   is fresh attack surface.
+   Bump only for a concrete reason ("show me the commit we need"); prefer fewer,
+   vendored/pinned dependencies; let audits + CVE monitoring tell you when a real update
+   is warranted.
+6. **No unpinned zero-install runners.** Avoid `npx` / `pnpm dlx` / `bunx` / `uvx` /
+   `go run <remote>` without an explicit `@version` pin and a review of the resolved
+   `package@version` — they fetch and execute the latest code, bypassing the cool-off.
+   (When a skill references a CLI via a runner, pin it — see
+   `tbd guidelines cli-agent-skill-patterns` §6.7.)
+7. **No `curl | sh` from untrusted sources.** Verify the installer URL belongs to the
+   documented project; check signatures/checksums where available.
+
+## The Exception Process
+
+When a version inside the 14-day window is genuinely needed (e.g. a CVE patch published
+yesterday), take the exception **explicitly and on the record**:
+
+- State the reason in the commit/PR: the CVE ID (or vulnerability description) and a
+  `Reviewed-by:` sign-off.
+- Pin the exact `package@version` (not a range); verify it against the authoritative
+  sources (OSV, GHSA, maintainer postmortem).
+- Log it, with a follow-up to confirm the version was not yanked afterward.
+
+No exception is “trivial” — the rule exists because we don’t trust ourselves to eyeball
+which fresh versions are safe.
+**Agents never self-approve an exception**: prepare the record and a human signs off.
+
+## Node / TypeScript Enforcement (npm, pnpm, Bun)
+
+The hands-on controls for the rules above in the Node ecosystem.
+Applies to **any** repo, not just new monorepos — drop these into an existing project.
+
+**Lifecycle-script hygiene (the highest-value control).** Block install/build scripts by
+default and allowlist only what you trust:
+
+- **pnpm 11**: declare allowed packages in `pnpm-workspace.yaml`; keep
+  `blockExoticSubdeps` on.
+  Everything else installs with no `postinstall`/`preinstall`.
+  ```yaml
+  # pnpm-workspace.yaml
+  minimumReleaseAge: 20160 # 14 days in minutes (pnpm 11 default is 1440 = 1 day)
+  allowBuilds:
+    - esbuild
+    - sharp
+  ```
+- **Bun**: blocks lifecycle scripts by default via an internal allowlist; extend it with
+  `trustedDependencies` in `package.json`. Bun has **no native release-age gate** yet,
+  so enforce the cool-off at the upgrade-tool layer (below).
+  ```json
+  { "trustedDependencies": ["esbuild", "sharp"] }
+  ```
+- **npm**: `NPM_CONFIG_IGNORE_SCRIPTS=true` (or `.npmrc` `ignore-scripts=true`).
+
+**Release-age gate** (resolution time): pnpm `minimumReleaseAge` (above); npm
+`NPM_CONFIG_BEFORE` / `NPM_CONFIG_MIN_RELEASE_AGE` (npm 11.10+); Bun none.
+
+**Upgrade-time check** (complements resolution-time gating): `npm-check-updates`
+`--cooldown` works on npm/pnpm/Bun/yarn projects.
+Pin the `ncu` version.
+
+```bash
+pnpm dlx npm-check-updates@<ver> --cooldown 14                 # or: bunx / npx
+pnpm dlx npm-check-updates@<ver> --cooldown 14 --errorLevel 2  # CI: non-zero if fresh upgrades exist
+npm view <pkg> time.<version>                                  # one version's publish time; if < 14d, wait
+```
+
+**Lockfile discipline**: always commit the lockfile (`pnpm-lock.yaml` / `bun.lock` /
+`package-lock.json`); install frozen in CI (`pnpm install --frozen-lockfile` /
+`bun install --frozen-lockfile` / `npm ci`); never `pnpm update` / `bun update` without
+reviewing the lockfile diff like a code diff.
+One root lockfile in a monorepo.
+
+**Provenance**: prefer deps that publish
+[npm provenance attestations](https://docs.npmjs.com/generating-provenance-statements)
+(TypeScript, Vitest, Prettier, ESLint do).
+Run `pnpm audit signatures` / `npm audit signatures` periodically.
+A provenance badge is necessary, not sufficient — the @antv worm forged one.
+
+**CI audit gate** (alongside lint/test):
+
+```yaml
+audit:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v6
+    - run: pnpm install --frozen-lockfile # or: bun install --frozen-lockfile / npm ci
+    - run: pnpm audit --audit-level=moderate # or: bun audit / npm audit
+    - run: pnpm audit signatures # provenance check where supported
+    - run: pnpm dlx npm-check-updates@<ver> --cooldown 14 --errorLevel 0
+      # errorLevel 0 logs but doesn't fail — flip to 2 once the backlog is cleared
+```
+
+**Pre-push age guard** — a zero-dependency Node script wired into lefthook/husky:
+
+```ts
+#!/usr/bin/env tsx
+// Fails if any direct dependency was published < 14 days ago.
+import pkg from '../package.json' with { type: 'json' };
+const COOLDOWN_MS = 14 * 24 * 60 * 60 * 1000;
+const now = Date.now();
+let violations = 0;
+for (const [name, spec] of Object.entries({ ...pkg.dependencies, ...pkg.devDependencies })) {
+  const version = String(spec).replace(/^[\^~=<>]+/, '');
+  const meta = await (await fetch(`https://registry.npmjs.org/${name}`)).json();
+  const publishedAt = meta.time?.[version];
+  if (!publishedAt) continue;
+  if (now - new Date(publishedAt).getTime() < COOLDOWN_MS) {
+    console.error(`✗ ${name}@${version} is < 14 days old`);
+    violations++;
+  }
+}
+process.exit(violations > 0 ? 1 : 0);
+```
+
+**Exception bookkeeping**: when you pin a fresh version under the exception process,
+leave a marker next to the pin (JSONC comment in `package.json`, or a `CHANGELOG.md`
+note for strict JSON parsers): `// Exception: CVE-2026-XXXX patch within 14d window.
+Reviewed <date>.`
+
+## Untrusted Repos & Modes
+
+- **Treat any freshly-cloned third-party repo as untrusted.** Do not run
+  `install`/`build`/`test`/`run`/`npx`/`uvx`/`cargo run`/`go run <remote>` against it on
+  a machine with ambient credentials until you’ve reviewed it — ideally in a container
+  or namespace-isolated sandbox.
+  (`build.rs`, proc-macros, `require()`-time payloads, and test files all execute code.)
+- **Modes**: default to **Balanced** (the policy above).
+  Enter **Strict** (no upgrade without reviewing the change set; build-script allowlist
+  required; mandatory sandbox; CI scanners checksum-verified) when the repo declares it,
+  when the repo is untrusted, or on a machine with publish tokens / production access.
+  **Emergency Exception** is a single logged per-command bypass — never self-approved by
+  an agent.
+
+## What This Does and Doesn’t Cover
+
+A cool-off + disabled scripts neutralizes the dominant **fast-yanked-incident** pattern.
+It does **not** stop: long-lived typosquats that survive past the window; a lockfile
+that already captured a bad version; payloads that fire on import/build rather than
+install; or **publish-pipeline compromises** (the May 2026 @antv worm shipped from
+legitimate CI with a forged “verified” provenance badge — a green badge is not proof).
+Those need lockfile review, typosquat checks, build-time controls, and — if you publish
+packages — the publish-side controls in the guidebook’s `hardening-ci-cd.md` (OIDC
+trusted publishing, staged publishing, SHA-pinned actions, runner egress limits,
+provenance monitoring).
+
+## Apply It Here (tbd)
+
+- The repo root carries `SUPPLY-CHAIN-SECURITY.md` (the portable flag file) referenced
+  from `AGENTS.md`/`CLAUDE.md`, so any agent sees the install rules before adding deps.
+- tbd is a pnpm project: the 14-day rule, `ncu --cooldown 14`, and the
+  `scripts/check-package-age.mjs` pre-push guard are covered in
+  `tbd guidelines pnpm-monorepo-patterns` → Supply-Chain Mitigation.
+
+## References
+
+- **Supply Chain Hardening guidebook** (full playbooks, audit script, watch list,
+  CI/publish hardening, research): <https://github.com/jlevy/supply-chain-hardening>
+- Authoritative sources: [OSV.dev](https://osv.dev), GitHub Advisory DB, `npm audit` /
+  `pip-audit` / `cargo audit` / `govulncheck`; incident feeds (Aikido Intel,
+  StepSecurity, Socket, Unit 42).
+- Monorepo enforcement: `tbd guidelines pnpm-monorepo-patterns`,
+  `tbd guidelines bun-monorepo-patterns`.

package/dist/docs/guidelines/typescript-cli-tool-rules.md

@@ -5,6 +5,20 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 # CLI Tool Development Rules
 
+**Last Updated**: 2026-05-21
+
+**Tracks**: Commander.js `^15.0.0` (ESM-only, requires Node v22.12.0+),
+picocolors `^1.1.1` (stable; no recent changes), Node.js 24 LTS / Node 26 Current.
+Commander 14 moves to security-only maintenance until May 2027.
+
+**Related**:
+
+- [TypeScript Rules](./typescript-rules.md)
+- [Supply-Chain Mitigation](./pnpm-monorepo-patterns.md#supply-chain-mitigation) —
+  follow the 14-day package-age rule for every CLI dependency. Bundlers and
+  CLI dependencies that execute at install time (`postinstall` scripts) are a
+  primary attack surface.
+
 These rules apply to all CLI tools, command-line scripts, and terminal utilities.
 Examples may be inspired by modern TypeScript repos, but guidance here is intentionally
 generic and reusable across projects.
@@ -93,7 +107,9 @@ generic and reusable across projects.
 ## Commander.js Patterns
 
 - **Use Commander.js for all CLI tools:** Import from `commander` and follow established
-  patterns for command registration and option handling.
+  patterns for command registration and option handling. **Target Commander 15+
+  (ESM-only, requires Node v22.12.0+).** Commander 14 is security-maintenance
+  only until May 2027; do not start new projects on it.
 
 - **Apply colored help globally, not per-command:** Use Commander v14+ `configureHelp()`
   with style functions, applied recursively to all commands at program initialization.
@@ -549,15 +565,30 @@ When supporting environment variables, especially those used by SDK libraries (l
 `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.), also support `.env` loading so CLIs work
 seamlessly in local dev and in remote environments.
 
-- **Use dotenv only when needed:** Add `dotenv` only if your CLI should load local env
-  files automatically.
+- **Prefer Node.js native `--env-file` for Node ≥20.6**: Production-ready on
+  Node 24 LTS. Pass `--env-file=.env.local --env-file=.env` on the CLI
+  invocation; later files do not override earlier ones, so list higher-priority
+  first. No dependency required:
+
+  ```bash
+  node --env-file=.env.local --env-file=.env ./dist/bin.js
+  ```
+
+  Make this the default for new projects. Reserve `dotenv` for advanced needs
+  (variable expansion, multiline values, custom precedence logic, or runtime
+  conditional loading from inside the CLI).
+
+- **Use `dotenv` only when needed:** Add `dotenv` only if your CLI must load
+  env files programmatically — e.g., it reads them after parsing command-line
+  flags, performs variable expansion, or supports custom file paths the user
+  cannot pre-bake into the `node` invocation.
 
-- **Load `.env.local` and `.env` automatically (recommended):** Support both
-  `.env.local` and `.env` automatically, with `.env.local` taking precedence over
-  `.env`.
+- **Load `.env.local` and `.env` automatically (recommended):** Whichever
+  mechanism you use, support both `.env.local` (higher priority, gitignored)
+  and `.env` (lower priority, committed defaults only).
 
-- **Manual dotenv loading:** For runtimes that don’t already load env files, load
-  environment files manually with explicit precedence:
+- **Manual `dotenv` loading:** When you do need `dotenv`, load with explicit
+  precedence:
 
   ```ts
   import dotenv from 'dotenv';

package/dist/docs/guidelines/typescript-code-coverage.md

@@ -5,6 +5,18 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 # Code Coverage Best Practices for TypeScript with Vitest
 
+**Last Updated**: 2026-05-21
+
+**Tracks**: Vitest `^4.1.7`, `@vitest/coverage-v8` `^4.1.7`. Vitest 5.0 is in
+beta — do not adopt yet.
+
+**Related**:
+
+- [Companion: pnpm Monorepo Patterns — Testing](./pnpm-monorepo-patterns.md#8-testing)
+- [Supply-Chain Mitigation](./pnpm-monorepo-patterns.md#supply-chain-mitigation) —
+  follow the 14-day package-age rule when installing or upgrading `vitest` and
+  `@vitest/coverage-v8`.
+
 ## Coverage Metrics
 
 ### Essential Metrics
@@ -70,9 +82,21 @@ Low branch coverage often indicates untested error paths and edge cases.
 ### Installation
 
 ```bash
-pnpm add -D vitest @vitest/coverage-v8
+# Pin to a specific minor to stay on a stable line; align both packages.
+pnpm add -D vitest@^4.1 @vitest/coverage-v8@^4.1
 ```
 
+Follow the [14-day package-age rule](./pnpm-monorepo-patterns.md#supply-chain-mitigation)
+on every upgrade: use `ncu --cooldown 14` or
+`pnpm install --frozen-lockfile`.
+
+### Vitest 4.x changes that affect coverage
+
+- **`coverage.all` was removed** in Vitest 4. Use `coverage.include` and
+  `coverage.exclude` to define exactly which files are reported.
+- Coverage reporters and v8 provider now ship as part of `@vitest/coverage-v8`
+  aligned with the Vitest major version — pin them together.
+
 ### Example Configuration
 
 ```typescript
@@ -131,10 +155,10 @@ export default defineConfig({
 
 ```yaml
 - name: Run tests with coverage
-  run: npm run test:coverage
+  run: pnpm run test:coverage
 
 - name: Upload coverage to Codecov
-  uses: codecov/codecov-action@v4
+  uses: codecov/codecov-action@v5
   with:
     files: ./coverage/lcov.info
     fail_ci_if_error: true

package/dist/docs/guidelines/typescript-rules.md

@@ -7,6 +7,24 @@ alwaysApply: true
 ---
 # TypeScript Rules
 
+**Last Updated**: 2026-05-21
+
+**Tracks**: TypeScript `^6.0.3` (stable). TypeScript 7.0 Beta
+(`@typescript/native-preview`, binary `tsgo`) is available but **not yet
+production-ready** — do not adopt for shipped builds.
+
+**Related**:
+
+- [TypeScript CLI Tool Rules](./typescript-cli-tool-rules.md)
+- [TypeScript Sorting Patterns](./typescript-sorting-patterns.md)
+- [TypeScript YAML Handling Rules](./typescript-yaml-handling-rules.md)
+- [TypeScript Code Coverage](./typescript-code-coverage.md)
+- [pnpm Monorepo Patterns](./pnpm-monorepo-patterns.md) and
+  [Bun Monorepo Patterns](./bun-monorepo-patterns.md)
+- [Supply-Chain Mitigation](./pnpm-monorepo-patterns.md#supply-chain-mitigation) —
+  the 14-day package-age rule applies to every TypeScript dependency
+  (`zod`, `commander`, `vitest`, `eslint`, type packages, etc.).
+
 ## Coding Style
 
 - Use clear lowerCamelCase or UpperCamelCase names for functions and variables, per

package/dist/docs/guidelines/typescript-yaml-handling-rules.md

@@ -6,6 +6,18 @@ globs: "*.ts"
 ---
 # TypeScript YAML Handling Rules
 
+**Last Updated**: 2026-05-21
+
+**Tracks**: `yaml@^2.8.4` (latest stable; 2026-05-02). The `yaml@3.0.0-1`
+release is tagged `next` (pre-release) — do not adopt yet. Zod 4.x is the
+recommended validation companion.
+
+**Related**:
+
+- [TypeScript Rules](./typescript-rules.md)
+- [Supply-Chain Mitigation](./pnpm-monorepo-patterns.md#supply-chain-mitigation) —
+  follow the 14-day package-age rule for `yaml`, `zod`, and `gray-matter`.
+
 These guidelines ensure consistent, safe, and readable YAML handling across TypeScript
 codebases. YAML is deceptively tricky—inconsistent quoting, serialization differences,
 and lack of validation cause subtle bugs.

package/dist/docs/shortcuts/standard/new-validation-plan.md

@@ -1,6 +1,6 @@
 ---
 title: New Validation Plan
-description: Create a validation/test plan showing what's tested and what remains
+description: Create a validation/test plan showing what’s tested and what remains
 category: planning
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---

package/dist/docs/tbd-design.md

@@ -2631,9 +2631,24 @@ Options:
 
 **Output:**
 
-The `show` command outputs the issue in the exact storage format (YAML frontmatter +
+The `show` command outputs the issue in a storage-compatible format (YAML frontmatter +
 Markdown body). This format is both human-readable and machine-parseable, enabling
 round-trip editing workflows.
+For dependency direction, text output may include YAML comments immediately above the
+`dependencies` field:
+
+```yaml
+# Blocks: proj-c3d4
+# Blocked by: proj-f14c
+dependencies:
+  - type: blocks
+    target: is-c3d4...
+```
+
+These comments are ignored by `tbd update --from-file` and exist only to clarify the raw
+edge list. In storage, `type: blocks` means the shown issue blocks the target.
+For dependency-direction checks, prefer `tbd dep list <id>`, which renders the
+human-facing `Blocks:` and `Blocked by:` sections directly.
 
 **Parent context (auto-displayed for child issues):**
 

package/dist/docs/tbd-docs.md

@@ -292,8 +292,13 @@ tbd show proj-a7k2 --no-parent                # Suppress parent context
 
 Output includes all fields: title, description, status, priority, labels, dependencies,
 timestamps, and working notes.
-For child issues, the parent’s details (ID, title, status, priority, description) are
-automatically displayed below the child for context.
+The raw `dependencies` field is a storage-format edge list: an entry with `type: blocks`
+means the shown issue blocks the target.
+When dependency directions exist, text output adds YAML comments above `dependencies`
+with human-facing `Blocks:` and `Blocked by:` sections using display IDs.
+For dependency-direction checks, prefer `tbd dep list <id>`. For child issues, the
+parent’s details (ID, title, status, priority, description) are automatically displayed
+below the child for context.
 
 ### update
 
@@ -450,6 +455,10 @@ Subcommands:
 - `remove <issue> <depends-on>` - Remove dependency
 - `list <id>` - List dependencies for an issue (what it blocks and what blocks it)
 
+Use `tbd dep list <id>` when checking dependency direction.
+The raw `dependencies` frontmatter in `tbd show` stores graph edges where `type: blocks`
+means the shown issue blocks the target.
+
 ### sync
 
 Synchronize issues with remote repository.

package/dist/index.mjs

@@ -1,4 +1,4 @@
 import { A as Ulid, C as LOCAL_STATE_FIELD_ORDER, D as Priority, E as MetaSchema, O as ShortId, S as IssueTitle, T as META_FIELD_ORDER, _ as IdMappingYamlSchema, a as ConfigSchema, b as IssueSchema, c as DocCacheConfigSchema, d as ExternalIssueIdInput, f as GitBranchName, g as ISSUE_TITLE_MAX_LENGTH, h as ISSUE_FIELD_ORDER, i as CONFIG_FIELD_ORDER, j as Version, k as Timestamp, l as DocsCacheSchema, m as ISSUE_BODY_MAX_LENGTH, n as AtticEntrySchema, o as Dependency, p as GitRemoteName, r as BaseEntity, s as DependencyRelationType, t as ATTIC_ENTRY_FIELD_ORDER, u as EntityType, v as IssueId, w as LocalStateSchema, x as IssueStatus, y as IssueKind } from "./schemas-C8mOQykE.mjs";
-import { c as noopLogger, i as serializeIssue, n as parseIssue, t as VERSION } from "./src-BIE27KDA.mjs";
+import { c as noopLogger, i as serializeIssue, n as parseIssue, t as VERSION } from "./src-CJyVkC3V.mjs";
 
 export { ATTIC_ENTRY_FIELD_ORDER, AtticEntrySchema, BaseEntity, CONFIG_FIELD_ORDER, ConfigSchema, Dependency, DependencyRelationType, DocCacheConfigSchema, DocsCacheSchema, EntityType, ExternalIssueIdInput, GitBranchName, GitRemoteName, ISSUE_BODY_MAX_LENGTH, ISSUE_FIELD_ORDER, ISSUE_TITLE_MAX_LENGTH, IdMappingYamlSchema, IssueId, IssueKind, IssueSchema, IssueStatus, IssueTitle, LOCAL_STATE_FIELD_ORDER, LocalStateSchema, META_FIELD_ORDER, MetaSchema, Priority, ShortId, Timestamp, Ulid, VERSION, Version, noopLogger, parseIssue, serializeIssue };

package/dist/{src-BIE27KDA.mjs → src-CJyVkC3V.mjs}

@@ -183,8 +183,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.27";
+const VERSION = "0.1.29";
 
 //#endregion
 export { insertAfterFrontmatter as a, noopLogger as c, serializeIssue as i, parseIssue as n, parseMarkdown as o, parseMarkdownWithFrontmatter as r, stripFrontmatter as s, VERSION as t };
-//# sourceMappingURL=src-BIE27KDA.mjs.map
+//# sourceMappingURL=src-CJyVkC3V.mjs.map

package/dist/{src-BIE27KDA.mjs.map → src-CJyVkC3V.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"src-BIE27KDA.mjs","names":["parseYaml"],"sources":["../src/lib/types.ts","../src/utils/markdown-utils.ts","../src/file/parser.ts","../src/index.ts"],"sourcesContent":["/**\n * TypeScript types derived from Zod schemas.\n *\n * These types are the canonical TypeScript interface for tbd entities.\n */\n\nimport type { z } from 'zod';\n\nimport type {\n  IssueSchema,\n  IssueStatus,\n  IssueKind,\n  Priority,\n  Dependency,\n  ConfigSchema,\n  MetaSchema,\n  LocalStateSchema,\n  AtticEntrySchema,\n} from './schemas.js';\n\n// =============================================================================\n// Entity Types\n// =============================================================================\n\n/**\n * A tbd issue entity.\n */\nexport type Issue = z.infer<typeof IssueSchema>;\n\n/**\n * Issue status enum values.\n */\nexport type IssueStatusType = z.infer<typeof IssueStatus>;\n\n/**\n * Issue kind enum values.\n */\nexport type IssueKindType = z.infer<typeof IssueKind>;\n\n/**\n * Priority level (0-4).\n */\nexport type PriorityType = z.infer<typeof Priority>;\n\n/**\n * A dependency relationship.\n */\nexport type DependencyType = z.infer<typeof Dependency>;\n\n// =============================================================================\n// Configuration Types\n// =============================================================================\n\n/**\n * Project configuration.\n */\nexport type Config = z.infer<typeof ConfigSchema>;\n\n/**\n * Shared metadata.\n */\nexport type Meta = z.infer<typeof MetaSchema>;\n\n/**\n * Per-node local state.\n */\nexport type LocalState = z.infer<typeof LocalStateSchema>;\n\n/**\n * Attic entry for conflict losers.\n */\nexport type AtticEntry = z.infer<typeof AtticEntrySchema>;\n\n// =============================================================================\n// Input Types for Commands\n// =============================================================================\n\n/**\n * Options for creating an issue.\n */\nexport interface CreateIssueOptions {\n  title: string;\n  description?: string;\n  kind?: IssueKindType;\n  priority?: PriorityType;\n  assignee?: string;\n  labels?: string[];\n  parent_id?: string;\n  due_date?: string;\n  deferred_until?: string;\n}\n\n/**\n * Options for updating an issue.\n */\nexport interface UpdateIssueOptions {\n  title?: string;\n  description?: string;\n  notes?: string;\n  kind?: IssueKindType;\n  status?: IssueStatusType;\n  priority?: PriorityType;\n  assignee?: string | null;\n  addLabels?: string[];\n  removeLabels?: string[];\n  parent_id?: string | null;\n  due_date?: string | null;\n  deferred_until?: string | null;\n}\n\n/**\n * Options for listing issues.\n */\nexport interface ListIssuesOptions {\n  status?: IssueStatusType | IssueStatusType[];\n  kind?: IssueKindType | IssueKindType[];\n  priority?: PriorityType;\n  assignee?: string;\n  labels?: string[];\n  parent?: string;\n  all?: boolean;\n  sort?: 'priority' | 'created' | 'updated';\n  limit?: number;\n}\n\n/**\n * Options for searching issues.\n */\nexport interface SearchIssuesOptions {\n  query: string;\n  status?: IssueStatusType | IssueStatusType[];\n  limit?: number;\n}\n\n// =============================================================================\n// CLI Utility Types\n// =============================================================================\n\n/**\n * A documentation section with title and slug.\n * Used by docs and design commands.\n */\nexport interface DocSection {\n  title: string;\n  slug: string;\n}\n\n/**\n * Logger interface for long-running operations in non-CLI layers.\n *\n * Allows core logic (file/, lib/) to report progress without depending on\n * the CLI output layer. CLI commands create an OperationLogger via\n * `OutputManager.logger(spinner)` and pass it to core functions.\n *\n * All methods are required. Use `noopLogger` when no logging is needed.\n */\nexport interface OperationLogger {\n  /** Key milestones — drives the spinner in CLI context */\n  progress: (message: string) => void;\n  /** Operational detail (shown with --verbose or --debug) */\n  info: (message: string) => void;\n  /** Non-fatal warnings */\n  warn: (message: string) => void;\n  /** Internal state for troubleshooting (shown with --debug only) */\n  debug: (message: string) => void;\n}\n\n/**\n * No-op logger for when no logging is needed.\n * Analogous to noopSpinner in the CLI layer.\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-function\nconst noop = () => {};\nexport const noopLogger: OperationLogger = {\n  progress: noop,\n  info: noop,\n  warn: noop,\n  debug: noop,\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 { sortKeys, stringifyYaml } from '../utils/yaml-utils.js';\nimport type { Issue } from '../lib/types.js';\nimport { IssueSchema, ISSUE_FIELD_ORDER } 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 using canonical field order (not alphabetical)\n  const sortedMetadata = sortKeys(metadata, ISSUE_FIELD_ORDER);\n\n  // Serialize YAML with compact output for frontmatter.\n  // sortMapEntries: false preserves our manual ordering.\n  const yaml = stringifyYaml(sortedMetadata, {\n    lineWidth: 0,\n    nullStr: 'null',\n    sortMapEntries: false,\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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"}
+{"version":3,"file":"src-CJyVkC3V.mjs","names":["parseYaml"],"sources":["../src/lib/types.ts","../src/utils/markdown-utils.ts","../src/file/parser.ts","../src/index.ts"],"sourcesContent":["/**\n * TypeScript types derived from Zod schemas.\n *\n * These types are the canonical TypeScript interface for tbd entities.\n */\n\nimport type { z } from 'zod';\n\nimport type {\n  IssueSchema,\n  IssueStatus,\n  IssueKind,\n  Priority,\n  Dependency,\n  ConfigSchema,\n  MetaSchema,\n  LocalStateSchema,\n  AtticEntrySchema,\n} from './schemas.js';\n\n// =============================================================================\n// Entity Types\n// =============================================================================\n\n/**\n * A tbd issue entity.\n */\nexport type Issue = z.infer<typeof IssueSchema>;\n\n/**\n * Issue status enum values.\n */\nexport type IssueStatusType = z.infer<typeof IssueStatus>;\n\n/**\n * Issue kind enum values.\n */\nexport type IssueKindType = z.infer<typeof IssueKind>;\n\n/**\n * Priority level (0-4).\n */\nexport type PriorityType = z.infer<typeof Priority>;\n\n/**\n * A dependency relationship.\n */\nexport type DependencyType = z.infer<typeof Dependency>;\n\n// =============================================================================\n// Configuration Types\n// =============================================================================\n\n/**\n * Project configuration.\n */\nexport type Config = z.infer<typeof ConfigSchema>;\n\n/**\n * Shared metadata.\n */\nexport type Meta = z.infer<typeof MetaSchema>;\n\n/**\n * Per-node local state.\n */\nexport type LocalState = z.infer<typeof LocalStateSchema>;\n\n/**\n * Attic entry for conflict losers.\n */\nexport type AtticEntry = z.infer<typeof AtticEntrySchema>;\n\n// =============================================================================\n// Input Types for Commands\n// =============================================================================\n\n/**\n * Options for creating an issue.\n */\nexport interface CreateIssueOptions {\n  title: string;\n  description?: string;\n  kind?: IssueKindType;\n  priority?: PriorityType;\n  assignee?: string;\n  labels?: string[];\n  parent_id?: string;\n  due_date?: string;\n  deferred_until?: string;\n}\n\n/**\n * Options for updating an issue.\n */\nexport interface UpdateIssueOptions {\n  title?: string;\n  description?: string;\n  notes?: string;\n  kind?: IssueKindType;\n  status?: IssueStatusType;\n  priority?: PriorityType;\n  assignee?: string | null;\n  addLabels?: string[];\n  removeLabels?: string[];\n  parent_id?: string | null;\n  due_date?: string | null;\n  deferred_until?: string | null;\n}\n\n/**\n * Options for listing issues.\n */\nexport interface ListIssuesOptions {\n  status?: IssueStatusType | IssueStatusType[];\n  kind?: IssueKindType | IssueKindType[];\n  priority?: PriorityType;\n  assignee?: string;\n  labels?: string[];\n  parent?: string;\n  all?: boolean;\n  sort?: 'priority' | 'created' | 'updated';\n  limit?: number;\n}\n\n/**\n * Options for searching issues.\n */\nexport interface SearchIssuesOptions {\n  query: string;\n  status?: IssueStatusType | IssueStatusType[];\n  limit?: number;\n}\n\n// =============================================================================\n// CLI Utility Types\n// =============================================================================\n\n/**\n * A documentation section with title and slug.\n * Used by docs and design commands.\n */\nexport interface DocSection {\n  title: string;\n  slug: string;\n}\n\n/**\n * Logger interface for long-running operations in non-CLI layers.\n *\n * Allows core logic (file/, lib/) to report progress without depending on\n * the CLI output layer. CLI commands create an OperationLogger via\n * `OutputManager.logger(spinner)` and pass it to core functions.\n *\n * All methods are required. Use `noopLogger` when no logging is needed.\n */\nexport interface OperationLogger {\n  /** Key milestones — drives the spinner in CLI context */\n  progress: (message: string) => void;\n  /** Operational detail (shown with --verbose or --debug) */\n  info: (message: string) => void;\n  /** Non-fatal warnings */\n  warn: (message: string) => void;\n  /** Internal state for troubleshooting (shown with --debug only) */\n  debug: (message: string) => void;\n}\n\n/**\n * No-op logger for when no logging is needed.\n * Analogous to noopSpinner in the CLI layer.\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-function\nconst noop = () => {};\nexport const noopLogger: OperationLogger = {\n  progress: noop,\n  info: noop,\n  warn: noop,\n  debug: noop,\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 { sortKeys, stringifyYaml } from '../utils/yaml-utils.js';\nimport type { Issue } from '../lib/types.js';\nimport { IssueSchema, ISSUE_FIELD_ORDER } 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 using canonical field order (not alphabetical)\n  const sortedMetadata = sortKeys(metadata, ISSUE_FIELD_ORDER);\n\n  // Serialize YAML with compact output for frontmatter.\n  // sortMapEntries: false preserves our manual ordering.\n  const yaml = stringifyYaml(sortedMetadata, {\n    lineWidth: 0,\n    nullStr: 'null',\n    sortMapEntries: false,\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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"}