feat(extensions): support .extensionignore to exclude files during install (#1781)

* feat(extensions): support .extensionignore to exclude files during install

Add .extensionignore support so extension authors can exclude files and
folders from being copied when users run 'specify extension add'.

The file uses glob-style patterns (one per line), supports comments (#),
blank lines, trailing-slash directory patterns, and relative path matching.
The .extensionignore file itself is always excluded from the copy.

- Add _load_extensionignore() to ExtensionManager
- Integrate ignore function into shutil.copytree in install_from_directory
- Document .extensionignore in EXTENSION-DEVELOPMENT-GUIDE.md
- Add 6 tests covering all pattern matching scenarios
- Bump version to 0.1.14

* fix(extensions): use pathspec for gitignore-compatible .extensionignore matching

Replace fnmatch with pathspec.GitIgnoreSpec to get proper .gitignore
semantics where * does not cross directory boundaries. This addresses
review feedback on #1781.

Changes:
- Switch from fnmatch to pathspec>=0.12.0 (GitIgnoreSpec.from_lines)
- Normalize backslashes in patterns for cross-platform compatibility
- Distinguish directories from files for trailing-slash patterns
- Update docs to accurately describe supported pattern semantics
- Add edge-case tests: .., absolute paths, empty file, backslashes,
  * vs ** boundary behavior, and ! negation
- Move changelog entry to [Unreleased] section

Author: Rubiss

CHANGELOG.md

@@ -7,6 +7,12 @@ Recent changes to the Specify CLI and templates are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- feat(extensions): support `.extensionignore` to exclude files/folders during `specify extension add` (#1781)
+
 ## [0.2.0] - 2026-03-09
 
 ### Changed
@@ -43,7 +49,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - fix: release-trigger uses release branch + PR instead of direct push to main (#1733)
 - fix: Split release process to sync pyproject.toml version with git tags (#1732)
 
-
 ## [0.1.14] - 2026-03-09
 
 ### Added

extensions/EXTENSION-DEVELOPMENT-GUIDE.md

@@ -332,6 +332,67 @@ echo "$config"
 
 ---
 
+## Excluding Files with `.extensionignore`
+
+Extension authors can create a `.extensionignore` file in the extension root to exclude files and folders from being copied when a user installs the extension with `specify extension add`. This is useful for keeping development-only files (tests, CI configs, docs source, etc.) out of the installed copy.
+
+### Format
+
+The file uses `.gitignore`-compatible patterns (one per line), powered by the [`pathspec`](https://pypi.org/project/pathspec/) library:
+
+- Blank lines are ignored
+- Lines starting with `#` are comments
+- `*` matches anything **except** `/` (does not cross directory boundaries)
+- `**` matches zero or more directories (e.g., `docs/**/*.draft.md`)
+- `?` matches any single character except `/`
+- A trailing `/` restricts a pattern to directories only
+- Patterns containing `/` (other than a trailing slash) are anchored to the extension root
+- Patterns without `/` match at any depth in the tree
+- `!` negates a previously excluded pattern (re-includes a file)
+- Backslashes in patterns are normalised to forward slashes for cross-platform compatibility
+- The `.extensionignore` file itself is always excluded automatically
+
+### Example
+
+```gitignore
+# .extensionignore
+
+# Development files
+tests/
+.github/
+.gitignore
+
+# Build artifacts
+__pycache__/
+*.pyc
+dist/
+
+# Documentation source (keep only the built README)
+docs/
+CONTRIBUTING.md
+```
+
+### Pattern Matching
+
+| Pattern | Matches | Does NOT match |
+|---------|---------|----------------|
+| `*.pyc` | Any `.pyc` file in any directory | — |
+| `tests/` | The `tests` directory (and all its contents) | A file named `tests` |
+| `docs/*.draft.md` | `docs/api.draft.md` (directly inside `docs/`) | `docs/sub/api.draft.md` (nested) |
+| `.env` | The `.env` file at any level | — |
+| `!README.md` | Re-includes `README.md` even if matched by an earlier pattern | — |
+| `docs/**/*.draft.md` | `docs/api.draft.md`, `docs/sub/api.draft.md` | — |
+
+### Unsupported Features
+
+The following `.gitignore` features are **not applicable** in this context:
+
+- **Multiple `.extensionignore` files**: Only a single file at the extension root is supported (`.gitignore` supports files in subdirectories)
+- **`$GIT_DIR/info/exclude` and `core.excludesFile`**: These are Git-specific and have no equivalent here
+- **Negation inside excluded directories**: Because file copying uses `shutil.copytree`, excluding a directory prevents recursion into it entirely. A negation pattern cannot re-include a file inside a directory that was itself excluded. For example, the combination `tests/` followed by `!tests/important.py` will **not** preserve `tests/important.py` — the `tests/` directory is skipped at the root level and its contents are never evaluated. To work around this, exclude the directory's contents individually instead of the directory itself (e.g., `tests/*.pyc` and `tests/.cache/` rather than `tests/`).
+
+---
+
 ## Validation Rules
 
 ### Extension ID

pyproject.toml

@@ -13,6 +13,7 @@ dependencies = [
     "truststore>=0.10.4",
     "pyyaml>=6.0",
     "packaging>=23.0",
+    "pathspec>=0.12.0",
 ]
 
 [project.scripts]

src/specify_cli/extensions.py

@@ -14,10 +14,12 @@
 import shutil
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Optional, Dict, List, Any
+from typing import Optional, Dict, List, Any, Callable, Set
 from datetime import datetime, timezone
 import re
 
+import pathspec
+
 import yaml
 from packaging import version as pkg_version
 from packaging.specifiers import SpecifierSet, InvalidSpecifier
@@ -280,6 +282,70 @@ def __init__(self, project_root: Path):
         self.extensions_dir = project_root / ".specify" / "extensions"
         self.registry = ExtensionRegistry(self.extensions_dir)
 
+    @staticmethod
+    def _load_extensionignore(source_dir: Path) -> Optional[Callable[[str, List[str]], Set[str]]]:
+        """Load .extensionignore and return an ignore function for shutil.copytree.
+
+        The .extensionignore file uses .gitignore-compatible patterns (one per line).
+        Lines starting with '#' are comments. Blank lines are ignored.
+        The .extensionignore file itself is always excluded.
+
+        Pattern semantics mirror .gitignore:
+        - '*' matches anything except '/'
+        - '**' matches zero or more directories
+        - '?' matches any single character except '/'
+        - Trailing '/' restricts a pattern to directories only
+        - Patterns with '/' (other than trailing) are anchored to the root
+        - '!' negates a previously excluded pattern
+
+        Args:
+            source_dir: Path to the extension source directory
+
+        Returns:
+            An ignore function compatible with shutil.copytree, or None
+            if no .extensionignore file exists.
+        """
+        ignore_file = source_dir / ".extensionignore"
+        if not ignore_file.exists():
+            return None
+
+        lines: List[str] = ignore_file.read_text().splitlines()
+
+        # Normalise backslashes in patterns so Windows-authored files work
+        normalised: List[str] = []
+        for line in lines:
+            stripped = line.strip()
+            if stripped and not stripped.startswith("#"):
+                normalised.append(stripped.replace("\\", "/"))
+            else:
+                # Preserve blanks/comments so pathspec line numbers stay stable
+                normalised.append(line)
+
+        # Always ignore the .extensionignore file itself
+        normalised.append(".extensionignore")
+
+        spec = pathspec.GitIgnoreSpec.from_lines(normalised)
+
+        def _ignore(directory: str, entries: List[str]) -> Set[str]:
+            ignored: Set[str] = set()
+            rel_dir = Path(directory).relative_to(source_dir)
+            for entry in entries:
+                rel_path = str(rel_dir / entry) if str(rel_dir) != "." else entry
+                # Normalise to forward slashes for consistent matching
+                rel_path_fwd = rel_path.replace("\\", "/")
+
+                entry_full = Path(directory) / entry
+                if entry_full.is_dir():
+                    # Append '/' so directory-only patterns (e.g. tests/) match
+                    if spec.match_file(rel_path_fwd + "/"):
+                        ignored.add(entry)
+                else:
+                    if spec.match_file(rel_path_fwd):
+                        ignored.add(entry)
+            return ignored
+
+        return _ignore
+
     def check_compatibility(
         self,
         manifest: ExtensionManifest,
@@ -353,7 +419,8 @@ def install_from_directory(
         if dest_dir.exists():
             shutil.rmtree(dest_dir)
 
-        shutil.copytree(source_dir, dest_dir)
+        ignore_fn = self._load_extensionignore(source_dir)
+        shutil.copytree(source_dir, dest_dir, ignore=ignore_fn)
 
         # Register commands with AI agents
         registered_commands = {}