Kit import: --method (submodule/subtree/copy), --pin (versioning), dz kit update

[djdarcy]

Summary

Three related items for dz kit add / dz kit update that together complete the registry-pointer schema for multi-method kit imports:

1. --method flag — dz kit add <url> --method submodule|subtree|copy (default: submodule); persists import_method field in registry pointer
2. --pin flag — dz kit add <url> --pin v1.0.0 (or SHA, or branch); hybrid semver + git-native versioning; persists pin field
3. dz kit update <name> — dispatches by import_method: git submodule update --remote for submodules, git subtree pull for subtrees, warn for copies; respects pin when set

These items are filed together because they share a registry-pointer schema change and overlapping CLI surface; splitting them across three issues would create churn in the same code path.

Motivation

Today dz add / dz kit add only supports git submodule add. Real-world adopters need:

• Subtree — when you want the kit's history vendored into your monorepo (no .gitmodules, no detached-HEAD pain)
• Copy — when you want a one-time snapshot with no upstream tracking (e.g., for vendoring third-party kits you don't trust to evolve)
• Pinning — when you want to depend on v1.0.0 (semver) or abc1234 (SHA) rather than tracking a branch

The design notes for these have existed since 2026-04-15:

• notes/cli/2026-04-15__00-51-26__both_kit-import-methods-submodule-vs-subtree-vs-copy.md
• notes/cli/2026-04-15__00-43-09__both_versioning-strategy-for-tools-kits-aggregators.md

Schema additions to registry pointer

Current registry pointer (kits/<kit>.kit.json):

{
    "kit": "wtf",
    "url": "https://github.com/DazzleTools/wtf-windows.git",
    "branch": "main",
    "path": "projects/wtf"
}

Proposed additions:

{
    "kit": "wtf",
    "url": "https://github.com/DazzleTools/wtf-windows.git",
    "branch": "main",
    "path": "projects/wtf",
    "import_method": "submodule",     // submodule | subtree | copy
    "pin": "v1.0.0"                   // semver tag, SHA, or branch name
}

Acceptance criteria

dz kit add --method

• dz kit add <url> --method submodule (default) — runs git submodule add (current behavior)
• dz kit add <url> --method subtree — runs git subtree add --prefix=<path> <url> <branch> --squash
• dz kit add <url> --method copy — does git clone --depth 1 then removes .git/ (snapshot mode)
• import_method field persists in kits/<kit>.kit.json
• dz kit info <kit> displays the import method
• User-configurable default in ~/.dazzlecmd/config.json: kit_import.default_method

dz kit add --pin

• dz kit add <url> --pin v1.0.0 resolves the tag and pins to that SHA
• dz kit add <url> --pin abc1234 (full or short SHA) pins to that commit
• dz kit add <url> --pin main (branch name) tracks the branch (no pin)
• pin field persists in registry pointer
• dz kit info <kit> displays the pin and resolved SHA
• dz tree (or similar) shows pin info per kit

dz kit update <name>

• dz kit update <kit> dispatches by import_method:
  • submodule: git submodule update --remote <path> (or git submodule update --init if not yet checked out)
  • subtree: git subtree pull --prefix=<path> <url> <branch> --squash
  • copy: prints Cannot auto-update copies. Re-import via: dz kit add <url> --method copy
• When pin is set: refuses to update past the pin (or prompts: "Pinned to v1.0.0; update bumps pin?")
• dz kit update --all updates all kits
• dz kit update --dry-run shows planned actions without running them

Estimated scope

~150-200 LOC across cli.py (new args, dispatch), loader.py (registry pointer schema), engine.py (validation), plus ~50 lines of tests.

Phasing

• Phase 1 (~1 day): --method flag + schema + dz kit info display
• Phase 2 (~1 day): --pin flag + schema + resolution
• Phase 3 (~1-2 days): dz kit update dispatching all three methods + --all + --dry-run

Related issues

• Refs EPIC: Phase 4 -- library extraction, polyglot dispatch, scaffolding redesign, ecosystem validation #30 — Phase 4 epic
• Refs Redesign dz new: sub-parser architecture with --language and --with composition #35 — dz new redesign (sibling: both touch dz import/scaffolding surface)
• Refs Kit-as-repo: standalone distributable kit repos with nested submodules #7 — Kit-as-repo (this issue completes the multi-method import vision from Kit-as-repo: standalone distributable kit repos with nested submodules #7's "standalone distributable kit repos with nested submodules")

Analysis

• Design notes: notes/cli/2026-04-15__00-51-26__both_kit-import-methods-submodule-vs-subtree-vs-copy.md, notes/cli/2026-04-15__00-43-09__both_versioning-strategy-for-tools-kits-aggregators.md
• Master closeout plan: 2026-04-29__07-41-11__claude-plan__0-7-x-closeout-ultraplan.md (4d-8 / 4d-9 / X-23 in Tier 2)