feat(import): add Beads JSONL import with selective issue trees (#124)

Fixes #121 

Add --beads <path> and optional issue IDs to import selected issue
trees.
Map Beads metadata and dependency links into Dex task fields.
Preserve completed_at when closed issues are re-imported without
closed_at.
Add fixtures, parser coverage, and CLI/docs updates for this import
flow.

Author: gkze

docs/src/pages/cli.astro

@@ -243,15 +243,17 @@ dex sync --dry-run          # Preview sync`}
 
   <div class="command-card">
     <h3>dex import</h3>
-    <div class="synopsis">dex import &lt;ref&gt; [options]</div>
-    <p>Import a GitHub Issue or Shortcut Story as a dex task.</p>
+    <div class="synopsis">dex import &lt;ref&gt; [options] | dex import --beads &lt;path&gt; [issue-id...] [options]</div>
+    <p>Import a GitHub Issue, Shortcut Story, or Beads JSONL export as dex tasks.</p>
     <ul>
       <li><code>--all</code> — Import all items with the dex label</li>
+      <li><code>--beads &lt;path&gt;</code> — Import from Beads JSONL export file</li>
       <li><code>--github</code> — Filter <code>--all</code> to only GitHub</li>
       <li><code>--shortcut</code> — Filter <code>--all</code> to only Shortcut</li>
       <li><code>--update</code> — Update existing task if already imported</li>
       <li><code>--dry-run</code> — Preview what would be imported</li>
     </ul>
+    <p><strong>Beads selection:</strong> pass one or more issue IDs after <code>--beads &lt;path&gt;</code> to import only those issues and their descendants.</p>
     <p><strong>Reference formats:</strong></p>
     <ul>
       <li>GitHub: <code>#123</code>, <code>owner/repo#123</code>, or full URL</li>
@@ -261,6 +263,8 @@ dex sync --dry-run          # Preview sync`}
       <Code
         code={`dex import #42                    # Import GitHub issue #42
 dex import sc#123                 # Import Shortcut story #123
+dex import --beads ./beads.jsonl       # Import all from Beads export
+dex import --beads ./beads.jsonl issue-1 issue-2  # Import selected Beads issues + descendants
 dex import https://github.com/owner/repo/issues/42
 dex import https://app.shortcut.com/myorg/story/123
 dex import --all                  # Import all dex-labeled items

specs/beads-import.md

@@ -0,0 +1,69 @@
+# Beads Import (MVP)
+
+Add `dex import --beads <path> [issue-id...]` to ingest Beads JSONL exports into Dex tasks.
+
+## Goals
+
+- Import Beads issue graphs without adding a full sync integration.
+- Preserve Beads provenance in task metadata.
+- Keep imports idempotent and safe to re-run.
+- Keep existing GitHub/Shortcut import flows unchanged.
+
+## CLI Contract
+
+- New flag: `--beads <path>`
+- Supported with:
+  - `--dry-run`
+  - `--update`
+- Optional positional arguments in Beads mode:
+  - `[issue-id...]` to import one or more root Beads issues and all descendants
+- Invalid combinations:
+  - `--beads` with `--all`, `--github`, or `--shortcut`
+
+## Data Mapping
+
+- `id` -> task `id`
+- `title` -> task `name`
+- `description` -> task `description`
+- `priority` -> task `priority`
+- `status=closed` (or `closed_at` present) -> `completed=true`
+- `created_at`, `updated_at`, `closed_at` -> task timestamps
+- `status in {in_progress, hooked}` -> `started_at` (best-effort from `updated_at`)
+- Dependency type `parent-child` -> task `parent_id`
+- Dependency type `blocks` -> task `blockedBy`
+- Non-blocking dependency types are preserved in `metadata.beads` and not mapped to Dex relationships.
+
+## Implementation Shape
+
+- Add Beads parser/normalizer under `src/core/beads/`.
+- Extend task metadata schema with `metadata.beads` in `src/types.ts`.
+- Extend `src/cli/import.ts` to handle `--beads` branch.
+- Apply import in two passes:
+  1. Upsert task fields (create/update)
+  2. Apply relationships (parent + blockers)
+
+Relationship failures (depth/cycle/missing target) should produce warnings and continue.
+
+## Test Strategy
+
+- Parser tests in `src/core/beads/import.test.ts`:
+  - valid JSONL parsing
+  - dependency normalization
+  - malformed line handling (line number in error)
+- CLI tests in `src/cli/import.test.ts`:
+  - happy path import
+  - dry-run no writes
+  - update semantics
+  - invalid flag combinations
+  - relationship warnings do not abort import
+- Schema test in `src/types.test.ts` for `metadata.beads` compatibility.
+
+## Anonymized Fixtures
+
+- Add anonymized Beads-derived fixtures under `src/core/beads/fixtures/`.
+- Produce fixture data from local Beads exports via an external/local workflow that:
+  - pseudonymizes IDs/actors/labels/external refs
+  - redacts free-text fields
+  - preserves graph shape, status mix, priorities, and dependency semantics
+
+No raw Beads state or secret-bearing exports are committed.

src/cli/help.ts

@@ -50,6 +50,7 @@ ${colors.bold}COMMANDS:${colors.reset}
   import #N                        Import GitHub issue
   import sc#N                      Import Shortcut story
   import --all                     Import all dex-labeled items
+  import --beads <path>            Import tasks from Beads JSONL export
   export <id>...                   Export tasks to GitHub (no sync back)
   completion <shell>               Generate shell completion script
 
@@ -102,9 +103,11 @@ ${colors.bold}EXAMPLES:${colors.reset}
   dex sync --dry-run                # Preview what would be synced
 
   ${colors.dim}# Import from external services:${colors.reset}
-  dex import #42                    # Import GitHub issue #42
-  dex import sc#123                 # Import Shortcut story #123
-  dex import --all                  # Import all dex-labeled items
-  dex import --all --shortcut       # Import only from Shortcut
+  dex import #42                              # Import GitHub issue #42
+  dex import sc#123                           # Import Shortcut story #123
+  dex import --all                            # Import all dex-labeled items
+  dex import --all --shortcut                 # Import only from Shortcut
+  dex import --beads ./beads.jsonl            # Import all from Beads export
+  dex import --beads ./beads.jsonl id1 id2    # Import selected Beads trees
 `);
 }