feat(cli): embed core pack in wheel for offline/air-gapped deployment

[mnriem]

Summary

Closes #1711
Addresses #1752

Embeds templates, commands, and scripts inside the specify-cli Python wheel so that specify init --offline works with zero network access. A pre-built offline bundle ZIP (wheel + all dependencies) is also published as a GitHub release asset, providing a single-file installation path for enterprise/air-gapped environments.

---

Problem

Two related air-gapped blockers were addressed together:

1. Cannot install CLI (Unable to install CLI as wheel access is blocked by corp policy #1752) — PyPI is blocked (403); no .whl was available as a release asset
2. Cannot run specify init (feat(cli): Embed core template pack in CLI package for air-gapped deployment #1711) — api.github.com is blocked; the init command unconditionally calls download_template_from_github() to fetch a release ZIP

A user who solved problem 1 (offline pip install) would immediately hit problem 2 on first use.

---

Solution

1. Bundle core assets in the wheel (pyproject.toml)

[tool.hatch.build.targets.wheel.force-include]
"templates"           = "specify_cli/core_pack/templates"
"templates/commands"  = "specify_cli/core_pack/commands"
"scripts/bash"        = "specify_cli/core_pack/scripts/bash"
"scripts/powershell"  = "specify_cli/core_pack/scripts/powershell"

2. New --offline flag for specify init

By default, specify init downloads project files from the latest GitHub release (unchanged behavior). The new --offline flag opts in to using bundled assets instead:

# Default — downloads from GitHub:
specify init my-project --ai claude

# Opt-in offline — uses bundled assets, no network access:
specify init my-project --ai claude --offline

If --offline is specified but bundled assets cannot be found or scaffolding fails, the CLI errors out with a clear message rather than silently falling back to a network download.

3. Offline scaffold via release script (scaffold_from_core_pack)

• _locate_core_pack() — finds bundled assets (wheel install) or returns None
• _locate_release_script() — finds the platform-appropriate release script; on Windows requires pwsh (PowerShell 7+); Windows PowerShell 5.x (powershell.exe) is not supported
• scaffold_from_core_pack() — invokes the bundled create-release-packages.sh (or .ps1) in a temp directory to generate the exact same output as the GitHub release ZIPs, then copies the result to the project directory
• When scaffolding into an existing directory (--here), .vscode/settings.json is merged via handle_vscode_settings() (JSONC-safe) instead of overwritten

4. Offline dependency bundle (specify-bundle-v*.zip)

The release workflow builds a single ZIP containing the specify-cli wheel and all runtime dependencies (~2.5 MB). Air-gapped users download one file, unzip, and install with pip install --no-index. No pip download step required on the user's side.

5. Wheel published as release asset

• release.yml: build step added (python -m build --wheel) — runs after create-release-packages.sh so the script's rm -rf doesn't wipe the wheel
• create-github-release.sh: wheel found via glob (specify_cli-*-py3-none-any.whl) to avoid version mismatch issues; offline bundle ZIP attached conditionally

6. Shell script improvements

• GENRELEASES_DIR is now overridable via environment variable (defaults to .genreleases), enabling tests to write to temp dirs instead of polluting the repo
• validate_subset() hardened against glob injection in case patterns

7. Documentation

• docs/installation.md: new "Enterprise / Air-Gapped Installation" section — download one ZIP, unzip, install
• README.md: "Option 3: Enterprise / Air-Gapped Installation" with simplified instructions

---

Acceptance criteria from #1711

Criterion	Status
specify init --offline scaffolds from embedded assets with no network calls	✅
All supported agents produce correct command files (Markdown, TOML, agent.md)	✅ (byte-for-byte parity verified for all agents)
Default specify init (no --offline) retains current GitHub-download behavior	✅
pip install specify-cli includes all core templates, commands, and scripts	✅ (force-include in pyproject.toml)
Existing create-release-packages.sh continues to work	✅
Air-gapped deployment works end-to-end	✅ (install from bundle ZIP → specify init --offline)
Offline bundle ZIP published as release asset	✅
--here --offline merges settings.json instead of overwriting	✅
Windows requires pwsh (PowerShell 7+) only	✅

---

Testing

684 passed

Includes parity tests (one per agent) verifying byte-for-byte equivalence between scaffold_from_core_pack() output and the canonical release script ZIP.

[Copilot]

Pull request overview

This PR makes specify init work offline by bundling the core template pack (templates/commands/scripts) inside the specify-cli wheel, and updates the release workflow/docs to support air-gapped installation via a published .whl release asset.

Changes:

• Bundle core templates/commands/scripts into the wheel and scaffold from those assets by default (with --from-github to force network download).
• Add runtime generation of agent-specific command files (md/toml/agent.md + Copilot prompt companions).
• Publish the wheel as a GitHub release asset and document enterprise/air-gapped install steps.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/specify_cli/__init__.py	Adds core-pack discovery, offline scaffolding, and agent command generation; updates init to be offline-first with --from-github.
pyproject.toml	Bumps version and force-includes core assets into the wheel.
docs/installation.md	Adds enterprise/air-gapped installation instructions and offline init guidance.
README.md	Documents the new air-gapped installation option via wheel.
CHANGELOG.md	Notes offline-first init, --from-github, and wheel release asset.
.github/workflows/scripts/create-github-release.sh	Attaches the built wheel to GitHub releases.
.github/workflows/release.yml	Adds a wheel build step to the release workflow.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

src/specify_cli/init.py:1016

• The _generate_agent_commands() docstring states TOML output is for "Gemini/Qwen/Tabnine", but Qwen is configured/packaged as Markdown commands (not TOML). Please update the docstring to match the actual supported formats so it stays consistent with create-release-packages.sh and the existing tests.

    """Generate agent-specific command files from Markdown command templates.

    Python equivalent of the generate_commands() shell function in
    .github/workflows/scripts/create-release-packages.sh.  Handles Markdown,
    TOML (Gemini/Qwen/Tabnine), and .agent.md (Copilot) output formats.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (2)

src/specify_cli/init.py:1534

• PR description/docs indicate init should be offline-first with an explicit opt-in to GitHub (e.g. --from-github), but the current docstring/implementation says GitHub is the default and --offline is opt-in. Please align the CLI flags/defaults with the intended UX (or update the PR/docs accordingly) to avoid confusing air-gapped users.

    By default, project files are downloaded from the latest GitHub release.
    Use --offline to scaffold from assets bundled inside the specify-cli
    package instead (no internet access required, ideal for air-gapped or
    enterprise environments).

src/specify_cli/init.py:1526

• The new --offline init path isn't covered by CLI-level tests. Consider adding a CliRunner test that invokes specify init ... --offline with scaffold_from_core_pack mocked and asserts download_and_extract_template is not called (and that failures don't trigger network attempts when offline is requested).

    debug: bool = typer.Option(False, "--debug", help="Show verbose diagnostic output for network and extraction failures"),
    github_token: str = typer.Option(None, "--github-token", help="GitHub token to use for API requests (or set GH_TOKEN or GITHUB_TOKEN environment variable)"),
    ai_skills: bool = typer.Option(False, "--ai-skills", help="Install Prompt.MD templates as agent skills (requires --ai)"),
    offline: bool = typer.Option(False, "--offline", help="Use assets bundled in the specify-cli package instead of downloading from GitHub (no network access required)"),
    preset: str = typer.Option(None, "--preset", help="Install a preset during initialization (by preset ID)"),

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (3)

tests/test_core_pack_scaffold.py:216

• These tests call scaffold_from_core_pack() separately in many parametrized test cases, and that function spawns the release script each time. With ~N agents this becomes O(N * tests) subprocess invocations and can significantly slow CI. Consider a session-scoped fixture that scaffolds once per agent (per script type) into tmp dirs and reuses the resulting trees across invariant tests.

@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
def test_scaffold_creates_specify_scripts(tmp_path, agent):
    """scaffold_from_core_pack copies at least one script into .specify/scripts/."""
    project = tmp_path / "proj"
    ok = scaffold_from_core_pack(project, agent, "sh")
    assert ok, f"scaffold_from_core_pack returned False for agent '{agent}'"

    scripts_dir = project / ".specify" / "scripts" / "bash"
    assert scripts_dir.is_dir(), f".specify/scripts/bash/ missing for agent '{agent}'"
    assert any(scripts_dir.iterdir()), f".specify/scripts/bash/ is empty for agent '{agent}'"


@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
def test_scaffold_creates_specify_templates(tmp_path, agent):
    """scaffold_from_core_pack copies at least one page template into .specify/templates/."""
    project = tmp_path / "proj"
    ok = scaffold_from_core_pack(project, agent, "sh")
    assert ok

    tpl_dir = project / ".specify" / "templates"
    assert tpl_dir.is_dir(), f".specify/templates/ missing for agent '{agent}'"
    assert any(tpl_dir.iterdir()), ".specify/templates/ is empty"


@pytest.mark.parametrize("agent", _TESTABLE_AGENTS)
def test_scaffold_command_dir_location(tmp_path, agent, source_template_stems):
    """Command files land in the directory declared by AGENT_CONFIG."""
    project = tmp_path / "proj"
    ok = scaffold_from_core_pack(project, agent, "sh")
    assert ok

.github/workflows/release.yml:46

• The new wheel build writes into .genreleases/, but create-release-packages.sh clears .genreleases/* at the start of its run. With the current step order, the wheel will be deleted before the release is created, so create-github-release.sh won't be able to attach it. Build the wheel after create-release-packages.sh, or output the wheel to a different directory that isn’t wiped (or adjust the script to not delete unrelated artifacts).

      - name: Build Python wheel
        if: steps.check_release.outputs.exists == 'false'
        run: |
          pip install build
          python -m build --wheel --outdir .genreleases/

      - name: Create release package variants
        if: steps.check_release.outputs.exists == 'false'
        run: |
          chmod +x .github/workflows/scripts/create-release-packages.sh
          .github/workflows/scripts/create-release-packages.sh ${{ steps.version.outputs.tag }}

src/specify_cli/init.py:1002

• _locate_core_pack()’s docstring claims it falls back to source-checkout/editable install paths, but the implementation only checks Path(__file__).parent / "core_pack" and otherwise returns None. Either implement the documented fallback behavior here (e.g., detect repo-root assets) or update the docstring so callers don’t rely on behavior that doesn’t exist.

def _locate_core_pack() -> Path | None:
    """Return the filesystem path to the bundled core_pack directory.

    Works for wheel installs (hatchling force-include puts the directory next to
    __init__.py as specify_cli/core_pack/) and for source-checkout / editable
    installs (falls back to the repo-root templates/ and scripts/ trees).
    Returns None only when neither location exists.
    """
    # Wheel install: core_pack is a sibling directory of this file
    candidate = Path(__file__).parent / "core_pack"
    if candidate.is_dir():
        return candidate
    return None

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (1)

tests/test_core_pack_scaffold.py:503

• This fixture runs the release script for every agent and extracts ZIPs, but it does not clean up the generated .genreleases/spec-kit-template-*.zip artifacts in the repo. Please add teardown cleanup (e.g., delete the specific ZIPs or the .genreleases contents after extraction) so local test runs don’t accumulate large build outputs.

    tmp = tmp_path_factory.mktemp("release_script")
    extracted: dict[str, Path] = {}

    for agent in _TESTABLE_AGENTS:
        zip_path = _run_release_script(agent, "sh", tmp, bash)
        dest = tmp / f"extracted-{agent}"
        dest.mkdir()
        with zipfile.ZipFile(zip_path) as zf:
            zf.extractall(dest)
        extracted[agent] = dest

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

tests/test_core_pack_scaffold.py:276

• Several tests call scaffold_from_core_pack() but never assert it succeeded (or that the expected command directory exists). If scaffolding fails, cmd_dir.rglob(...) yields no files and the test can pass vacuously, masking regressions. Add an explicit assert ok and/or assert cmd_dir.is_dir() before iterating files here (and apply the same pattern to the other invariant tests in this file).

    project = tmp_path / "proj"
    scaffold_from_core_pack(project, agent, "sh")

    cmd_dir = _expected_cmd_dir(project, agent)
    for f in cmd_dir.rglob("*"):
        if f.is_file():
            content = f.read_text(encoding="utf-8")
            assert "{SCRIPT}" not in content, (

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.