diff --git a/COMMERCIAL_LICENSE.md b/COMMERCIAL_LICENSE.md index b03306a06e..7a6303f3f1 100644 --- a/COMMERCIAL_LICENSE.md +++ b/COMMERCIAL_LICENSE.md @@ -41,6 +41,10 @@ Allowed uses include: ## Requires a Separate Written Agreement +The redistribution allowance above covers unmodified official releases only. A +package, image, service, extension, or fork that is renamed or positioned as a +substitute for CodeIndex falls under the competing-product boundary below. + A separate written agreement with Widthdom is required if you make CodeIndex, a modified version of CodeIndex, or a derivative work of CodeIndex available to third parties as a commercial product or service whose primary or substantial diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 8d8b5c8d9a..3cad85b806 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -17,6 +17,18 @@ target frameworks when validating the full CI-equivalent test matrix. For test suite structure, shared helpers, and test-writing conventions, see [TESTING_GUIDE.md](TESTING_GUIDE.md). +## Release Distribution Checklist + +When preparing a release, verify every supported distribution channel documented +in [DISTRIBUTION.md](DISTRIBUTION.md): + +- `install.sh` latest install, explicit-version install, `--doctor`, and local + mirror self-test. +- NuGet global tool install/update on a clean .NET 8 tool environment. +- Published release assets for every advertised RID. +- Package metadata for license, repository URL, tags, and runtime prerequisites. +- Documentation links from README, USER_GUIDE, and package metadata. + ### NuGet lock files `Directory.Build.props` sets `RestorePackagesWithLockFile=true`, so every project under this solution writes a `packages.lock.json` next to its `.csproj`. The lock file pins exact resolved versions and `contentHash` for every direct **and transitive** package, including the native-bearing `SQLitePCLRaw.bundle_e_sqlite3` that ships under `Microsoft.Data.Sqlite`. This keeps builds reproducible across machines, CI lanes, and release artifacts, and turns a silent transitive bump (or downgrade attack) into a loud, build-breaking diff. diff --git a/DISTRIBUTION.md b/DISTRIBUTION.md new file mode 100644 index 0000000000..d26e50239f --- /dev/null +++ b/DISTRIBUTION.md @@ -0,0 +1,56 @@ +# Distribution Channels + +This document compares supported and planned ways to install `cdidx`. + +## Supported Channels + +| Channel | Platform support | Prerequisites | Update path | Offline or mirrored use | Lifecycle policy | +|---|---|---|---|---|---| +| `install.sh` release assets | Linux/macOS self-contained tarballs for `linux-x64`, `linux-arm64`, and `osx-arm64` where a matching release asset exists | POSIX shell, `curl`, `tar`, and network access to the configured release host | Re-run the installer without a version for latest, or pass `vX.Y.Z` for an exact release | Supports `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, `CDIDX_GITHUB_BASE_URL`, `CDIDX_GITHUB_API_BASE_URL`, and local mirror self-tests | Primary self-contained installer for terminals, CI, containers, and ARM64 Unix hosts without .NET | +| Windows release ZIP assets | Windows self-contained ZIPs for `win-x64` and `win-arm64` where published | PowerShell or another ZIP extraction workflow | Download and replace with the desired release ZIP | Mirror the GitHub release ZIP and checksum assets through the same artifact controls | Supported release-asset path for Windows users who do not use NuGet | +| NuGet global tool | Any platform supported by .NET 8 global tools | .NET 8 SDK for `dotnet tool install/update`; .NET 8 runtime to run the installed tool | `dotnet tool update -g cdidx` | Use standard NuGet feeds, caches, and enterprise mirrors | Portable framework-dependent tool package; not RID-specific or self-contained | +| Container or manual image build | Any base image that can run the selected install path | Either `install.sh` prerequisites or a .NET SDK for source builds | Rebuild the image with a pinned release or source revision | Mirror release assets or NuGet feeds inside the image build network | Supported as a deployment pattern, not as an official published container image | +| Build from source | Windows, macOS, and Linux with a supported .NET SDK | .NET 8 SDK for production target; .NET 9 SDK if running the full test matrix | Pull source and rebuild | Works with restored package caches and internal NuGet mirrors | Contributor and advanced-user path | + +## Planned or Community Channels + +| Channel | Status | Notes | +|---|---|---| +| Homebrew | Available via `widthdom/tap/codeindex` when published for a release | Prefer this on macOS/Linux when you already use Homebrew. | +| winget | Planned | Should point at unmodified official binaries and preserve notices. | +| apt / rpm | Planned | Package metadata should make the license and update cadence clear. | +| Snap / Flatpak | Planned | Must document filesystem and sandbox implications for `.cdidx` databases. | + +## Choosing a Channel + +Use `install.sh` when you want a self-contained binary, especially in ARM64 +cloud sessions, CI containers, or machines where .NET is not already managed. +Use the NuGet global tool when your workstation already has a managed .NET 8 +toolchain and you want standard `dotnet tool` update behavior. + +If both are installed, whichever `cdidx` appears first on `PATH` wins. Check +with: + +```bash +command -v cdidx +cdidx --version +``` + +## Package Maintainers and Mirrors + +Third-party package recipes, manifests, and mirrors may redistribute unmodified +official CodeIndex releases when required notices are preserved. Do not market a +renamed binary, fork, or service as a substitute for CodeIndex without a +separate written agreement. See [INTEGRATION_POLICY.md](INTEGRATION_POLICY.md) +and [COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md). + +## Release Verification Checklist + +Before publishing or updating a channel, verify: + +- `install.sh` can install the latest release and an explicit `vX.Y.Z` release. +- `install.sh --doctor vX.Y.Z` reports the configured release and API hosts. +- `dotnet tool install -g cdidx --version ` succeeds on a clean .NET 8 tool environment. +- `cdidx --version` runs from each installed channel. +- `cdidx status --help` or another lightweight command runs without requiring a repository. +- Package metadata preserves license, homepage, and repository links. diff --git a/INTEGRATION_POLICY.md b/INTEGRATION_POLICY.md index dde2179837..ef7c25118b 100644 --- a/INTEGRATION_POLICY.md +++ b/INTEGRATION_POLICY.md @@ -107,6 +107,12 @@ Version markers for these fields: The integration is allowed when it helps users operate official CodeIndex releases or permissively licensed integration materials. +Third-party package maintainers may publish formulas, manifests, recipes, or +internal mirrors for unmodified official CodeIndex release artifacts when the +license, copyright, repository, and trademark notices are preserved and the +package does not imply official endorsement. See [DISTRIBUTION.md](DISTRIBUTION.md) +for channel expectations. + The integration may require a separate written agreement when it makes CodeIndex, a modified CodeIndex engine, or a derivative work of CodeIndex available to third parties as a commercial product or service that substitutes for CodeIndex diff --git a/README.md b/README.md index 87df9e57bc..063c658d8c 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,18 @@ Output controls: Use `cdidx` when a repository will be searched repeatedly from terminals, scripts, CI, or AI tools. Use `rg` when you only need a one-off text scan. +Install choice and network notes: + +| Need | Use | +|---|---| +| Self-contained binary with no .NET runtime | `install.sh` | +| .NET global tool workflow | `dotnet tool install -g cdidx` with .NET 8 installed | +| ARM64 host without a preinstalled .NET 8 runtime | `install.sh` | +| Proxy or mirrored GitHub access | `install.sh --doctor` and `CDIDX_GITHUB_BASE_URL` / `CDIDX_GITHUB_API_BASE_URL` | + +See [DISTRIBUTION.md](DISTRIBUTION.md) for the full channel matrix and +[isolated network install notes](USER_GUIDE.md#isolated-networks-and-proxies). + ### Shell Completion Generate completion scripts with `cdidx --completions `. @@ -138,6 +150,7 @@ version 2. | Document | Contents | |---|---| | [User Guide](USER_GUIDE.md) | Detailed installation, command examples, options, supported languages, MCP setup, and troubleshooting. | +| [Distribution Channels](DISTRIBUTION.md) | Install channel comparison, update paths, platform support, and package maintainer policy. | | [Cloud Bootstrap](CLOUD_BOOTSTRAP_PROMPT.md) | Install guidance for restricted cloud agent sessions. | | [Platform Support](docs/platform-support.md) | Official release asset RIDs, unsupported platforms, and source-build alternatives. | | [Developer Guide](DEVELOPER_GUIDE.md) | Architecture, implementation notes, release workflow, and the [`reference_kind` filtering matrix](DEVELOPER_GUIDE.md#reference-kind-filtering-matrix) for `callers` / `impact` / `deps` count reconciliation. | diff --git a/USER_GUIDE.md b/USER_GUIDE.md index 66aacaff56..a1ae36eff2 100644 --- a/USER_GUIDE.md +++ b/USER_GUIDE.md @@ -425,6 +425,17 @@ or `cdidx . --json` refresh so stale paths are purged. ## Installation +Choose the install channel based on runtime ownership and network shape: + +| Channel | Best fit | Prerequisites | Update path | +|---|---|---|---| +| `install.sh` | Self-contained installs, CI, containers, ARM64 hosts without managed .NET | Shell tools and release-asset network access | Re-run the installer, optionally with `vX.Y.Z` | +| NuGet global tool | Workstations already using .NET global tools | .NET 8 SDK for install/update; .NET 8 runtime to run | `dotnet tool update -g cdidx` | +| Build from source | Contributors and custom local builds | .NET 8 SDK | Pull source and rebuild | + +For a full comparison, package maintainer guidance, and planned channels such +as winget, apt, rpm, Snap, and Flatpak, see [DISTRIBUTION.md](DISTRIBUTION.md). + ### Option A: One-liner install (no .NET required) Works in containers, CI, and any Linux/macOS environment — no .NET SDK needed. @@ -467,12 +478,45 @@ RUN export CDIDX_INSTALL_DIR=/usr/local/bin \ && curl -fsSL https://raw.githubusercontent.com/Widthdom/CodeIndex/main/install.sh | bash ``` +#### Isolated networks and proxies + +Use `--doctor` before installing when a corporate proxy, egress allowlist, or +GitHub mirror is involved: + +```bash +bash ./install.sh --doctor +HTTPS_PROXY=http://proxy.example:8080 bash ./install.sh --doctor v1.5.0 +``` + +To point the installer at a mirror, set both release and API base URLs: + +```bash +export CDIDX_GITHUB_BASE_URL=https://github.example.internal +export CDIDX_GITHUB_API_BASE_URL=https://github.example.internal/api/v3 +curl -fsSL "$CDIDX_GITHUB_BASE_URL/Widthdom/CodeIndex/raw/main/install.sh" | bash +``` + +The local mirror self-test verifies the mirror code path without touching real +release assets. It installs a mock `cdidx` into the selected install directory, +so use an isolated directory unless you explicitly pass the overwrite guard: + +```bash +export CDIDX_INSTALL_DIR="$(mktemp -d)" +bash ./install.sh --self-test-local-mirror +``` + +If the default local self-test port is busy, set +`CDIDX_LOCAL_MIRROR_PORT=18766`. + ### Option B: NuGet Global Tool -Requires the [.NET 8.x SDK](https://dotnet.microsoft.com/download/dotnet/8.0). -CodeIndex targets `net8.0`; .NET 8.x is the supported SDK/runtime line for the -published tool, while the CI test suite also covers the test project on -`net9.0`. +Requires the [.NET 8.x SDK](https://dotnet.microsoft.com/download/dotnet/8.0) +for `dotnet tool install` / `dotnet tool update`. CodeIndex targets `net8.0`; +.NET 8.x is the supported runtime line for the published tool, while the CI +test suite also covers the test project on `net9.0`. The NuGet package is +framework-dependent rather than RID-specific or self-contained. On Apple +Silicon, Linux ARM64, and Windows ARM64, prefer `install.sh` when the host does +not already manage a .NET 8 runtime. ```bash dotnet tool install -g cdidx @@ -2281,6 +2325,17 @@ freshness が曖昧になった場合は、stale paths を purge できるよう ## インストール +runtime の管理方法とネットワーク条件に合わせて install channel を選んでください。 + +| Channel | 向いている用途 | 前提条件 | 更新方法 | +|---|---|---|---| +| `install.sh` | self-contained install、CI、container、managed .NET が無い ARM64 host | shell tools と release asset へ到達できるネットワーク | installer を再実行。必要なら `vX.Y.Z` を指定 | +| NuGet global tool | 既に .NET global tool を使う workstation | install/update には .NET 8 SDK、実行には .NET 8 runtime | `dotnet tool update -g cdidx` | +| source build | contributor と custom local build | .NET 8 SDK | source を pull して rebuild | + +完全な比較、package maintainer guidance、winget / apt / rpm / Snap / +Flatpak などの予定チャネルは [DISTRIBUTION.md](DISTRIBUTION.md) を参照してください。 + ### 方法A: ワンライナーインストール（.NET 不要） コンテナ、CI、Linux/macOS 環境で .NET SDK なしで使えます。 @@ -2323,12 +2378,46 @@ RUN export CDIDX_INSTALL_DIR=/usr/local/bin \ && curl -fsSL https://raw.githubusercontent.com/Widthdom/CodeIndex/main/install.sh | bash ``` +#### 隔離ネットワークと proxy + +企業 proxy、egress allowlist、GitHub mirror が関係する環境では、install 前に +`--doctor` で経路を確認してください。 + +```bash +bash ./install.sh --doctor +HTTPS_PROXY=http://proxy.example:8080 bash ./install.sh --doctor v1.5.0 +``` + +installer を mirror に向ける場合は、release host と API host の両方を設定します。 + +```bash +export CDIDX_GITHUB_BASE_URL=https://github.example.internal +export CDIDX_GITHUB_API_BASE_URL=https://github.example.internal/api/v3 +curl -fsSL "$CDIDX_GITHUB_BASE_URL/Widthdom/CodeIndex/raw/main/install.sh" | bash +``` + +local mirror self-test は、実リリース資産に触れずに mirror 経路を検証します。 +選択した install directory に mock `cdidx` を配置するため、明示的に +overwrite guard を渡す場合を除き、隔離ディレクトリを使ってください。 + +```bash +export CDIDX_INSTALL_DIR="$(mktemp -d)" +bash ./install.sh --self-test-local-mirror +``` + +既定の local self-test port が埋まっている場合は +`CDIDX_LOCAL_MIRROR_PORT=18766` を設定してください。 + ### 方法B: NuGet グローバルツール +`dotnet tool install` / `dotnet tool update` には [.NET 8.x SDK](https://dotnet.microsoft.com/download/dotnet/8.0) が必要です。 -CodeIndex は `net8.0` を対象にしており、公開ツールのサポート対象 -SDK/runtime 系列は .NET 8.x です。一方で、CI のテストスイートは -テストプロジェクトを `net9.0` でも検証します。 +CodeIndex は `net8.0` を対象にしており、公開ツールのサポート対象 runtime +系列は .NET 8.x です。一方で、CI のテストスイートはテストプロジェクトを +`net9.0` でも検証します。NuGet package は framework-dependent であり、 +RID-specific / self-contained ではありません。Apple Silicon、Linux ARM64、 +Windows ARM64 で host 側が .NET 8 runtime を管理していない場合は、 +`install.sh` を優先してください。 ```bash dotnet tool install -g cdidx diff --git a/changelog.d/unreleased/1951.docs.md b/changelog.d/unreleased/1951.docs.md new file mode 100644 index 0000000000..f9a67b494b --- /dev/null +++ b/changelog.d/unreleased/1951.docs.md @@ -0,0 +1,17 @@ +--- +category: docs +issues: + - 1951 +affected: + - README.md + - USER_GUIDE.md + - DISTRIBUTION.md +--- + +## English + +- **NuGet global tool docs now call out the .NET 8 runtime requirement on ARM64 (#1951)** - The install guidance distinguishes the framework-dependent NuGet path from the self-contained `install.sh` path. + +## 日本語 + +- **NuGet global tool の ARM64 向け .NET 8 ランタイム要件を明記しました (#1951)** - framework-dependent な NuGet 経路と self-contained な `install.sh` 経路の違いをインストール案内で区別しました。 diff --git a/changelog.d/unreleased/1952.docs.md b/changelog.d/unreleased/1952.docs.md new file mode 100644 index 0000000000..687b556c97 --- /dev/null +++ b/changelog.d/unreleased/1952.docs.md @@ -0,0 +1,20 @@ +--- +category: docs +issues: + - 1952 +affected: + - README.md + - USER_GUIDE.md + - DISTRIBUTION.md + - INTEGRATION_POLICY.md + - COMMERCIAL_LICENSE.md + - DEVELOPER_GUIDE.md +--- + +## English + +- **Distribution channel documentation now has a comparison matrix (#1952)** - `DISTRIBUTION.md` documents supported and planned install channels, update paths, prerequisites, package maintainer boundaries, and release verification checks. + +## 日本語 + +- **配布チャネルの比較表を追加しました (#1952)** - `DISTRIBUTION.md` に、対応済み/予定中のインストール経路、更新方法、前提条件、パッケージメンテナー向け境界、リリース検証項目をまとめました。 diff --git a/changelog.d/unreleased/1957.docs.md b/changelog.d/unreleased/1957.docs.md new file mode 100644 index 0000000000..d8e90b1b40 --- /dev/null +++ b/changelog.d/unreleased/1957.docs.md @@ -0,0 +1,17 @@ +--- +category: docs +issues: + - 1957 +affected: + - README.md + - USER_GUIDE.md + - install.sh +--- + +## English + +- **Installer mirror and proxy recovery paths are now documented (#1957)** - README and USER_GUIDE link to `--doctor`, GitHub base URL overrides, and the local mirror self-test for restricted networks. + +## 日本語 + +- **installer の mirror/proxy 復旧経路を文書化しました (#1957)** - README と USER_GUIDE から、制限ネットワーク向けの `--doctor`、GitHub base URL override、local mirror self-test を参照できるようにしました。 diff --git a/install.sh b/install.sh index 3334b19cea..32e2be5504 100755 --- a/install.sh +++ b/install.sh @@ -9,11 +9,17 @@ # bash ./install.sh --self-test-local-mirror [--self-test-allow-overwrite] [vX.Y.Z] # bash ./install.sh --reinstall-real vX.Y.Z # bash ./install.sh --doctor [vX.Y.Z] +# HTTPS_PROXY=http://proxy.example:8080 bash ./install.sh --doctor +# CDIDX_GITHUB_BASE_URL=https://github.example.internal \ +# CDIDX_GITHUB_API_BASE_URL=https://github.example.internal/api/v3 \ +# bash ./install.sh --doctor vX.Y.Z # # Optional env vars / 任意環境変数: # CDIDX_GITHUB_BASE_URL Release download base URL override # CDIDX_GITHUB_API_BASE_URL API base URL override for latest-release lookup # CDIDX_LOCAL_MIRROR_PORT Local self-test HTTP server port (default: 18765) +# HTTPS_PROXY / HTTP_PROXY Proxy used by curl for release and API probes +# NO_PROXY Hosts that should bypass the proxy # # Self-test mock payload safety / セルフテスト mock 上書き防止: # The --self-test-local-mirror path installs a **mock** cdidx that only