kanon-cli 3.0.0__tar.gz → 3.1.0__tar.gz

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 
 
+## v3.1.0 (2026-06-27)
+
+### Feature
+
+* feat: resolve catalog entries by tag namespace and accept bare project revisions #83
+
+feat: resolve catalog entries by tag namespace and accept bare project revisions ([`6099846`](https://github.com/caylent-solutions/kanon/commit/6099846bbc1b3f5f0988564d00b05df055bb52a8))
+
+* feat: key install conflict detection on package destination path, not repo URL
+
+Allow the same repository to be installed at different commits for different
+destination paths -- the mono-repo catalog case: install any version of package
+A and any version of package B even when both live in the same repo under
+different per-package tags. Previously `kanon install` rejected this with a
+canonical-URL conflict whenever two sources (or two <project> entries) shared a
+repository URL at different SHAs, which blocked multi-entry installs from a
+per-entry-tagged mono-repo catalog.
+
+- Replace the URL-keyed pre-flight (_detect_canonical_url_conflicts,
+  ResolvedProject, CanonicalUrlConflictError, _gather_resolved_projects) with a
+  destination-path-keyed check (_detect_package_path_conflicts, PackagePin,
+  PackagePathConflictError, _gather_package_pins) sourced from the per-source
+  content pins. The genuine invariant: no two <project> entries may occupy the
+  same .packages/<path> slot with different content. Same path + same SHA is a
+  benign duplicate; different paths are always allowed. Source/catalog manifest
+  entries are excluded (they never occupy a .packages/ slot). No lockfile schema
+  bump -- content_pins already carry path + resolved_sha.
+- aggregate_symlinks remains the on-disk backstop for duplicate package names.
+- Rewrite the unit + integration conflict tests for the path-keyed semantics
+  (including the same-repo/different-path/different-SHA success case), rename the
+  integration file, update the CD scenarios and the conflict error snapshot, and
+  update the multi-source / lockfile / url-canonicalization / troubleshooting /
+  integration-testing docs. ([`6f4f9a8`](https://github.com/caylent-solutions/kanon/commit/6f4f9a891504e890076776f0be6785573e0f1f59))
+
+* feat: resolve catalog entries by tag namespace and accept bare project revisions
+
+Exercising the catalog surfaced resolution bugs and the need to support
+both a per-entry namespaced tag (refs/tags/<name>/<pep440>) and a bare
+PEP 440 tag (refs/tags/<pep440>) for single-purpose repos, for both
+`kanon add` resolution and a manifest `<project revision>` (kanon#82).
+
+- Add version.select_entry_namespace, the shared namespaced-if-present-
+  else-bare rule. Scope `kanon add` default/explicit resolution
+  (commands/add._resolve_spec) and `kanon search`
+  (commands/search._list_namespaced_version_tags) to the entry tag
+  namespace, so `kanon add history` resolves refs/tags/history/<pep440>
+  rather than an unrelated legacy tag and cross-entry versions never collide.
+- Accept a bare refs/tags/<pep440> `<project revision>`
+  (core/marketplace_validator._is_pinnable_revision, constants.REFS_TAGS_RE)
+  and update the invalid-revision hints. Resolves kanon#82.
+- Replace Path.read_text/write_text(newline=...) (3.13+) with
+  Path.open(newline=...) in core/kanonenv_writer so requires-python >=3.11 holds.
+- Write the .kanon dependency block NAME-first with a blank line after the
+  CLAUDE_MARKETPLACES_DIR header.
+- Tests, docs, and the kanon-add help snapshot updated. ([`7ed332c`](https://github.com/caylent-solutions/kanon/commit/7ed332c859e69cfd6635035a05c15c03339fdcd1))
+
+
 ## v3.0.0 (2026-06-26)
 
 ### Breaking
@@ -40,6 +97,10 @@ runs unit + integration + functional + scenario + `make test` as independent ste
 per-unit validation time substantially. pytest-xdist parallelism was evaluated and reverted:
 the suite's test collection is non-deterministic across xdist workers (gw collection mismatch). ([`a8b3441`](https://github.com/caylent-solutions/kanon/commit/a8b344134cb2eba39ed3f48aee812e27ce7167e1))
 
+### Chore
+
+* chore(release): 3.0.0 ([`a76fa87`](https://github.com/caylent-solutions/kanon/commit/a76fa8742ff8634d3e3ddbcdb797d230139ec5d2))
+
 ### Ci
 
 * ci: split CI into Linux + Windows sets with platform markers; fix cross-platform bugs
@@ -417,6 +478,10 @@ fixtures, so the functional `test_help_snapshot[kanon-add]` / `[kanon-remove]` b
 
 ### Unknown
 
+* Merge pull request #81 from caylent-solutions/release-3.0.0
+
+Release 3.0.0 ([`145232a`](https://github.com/caylent-solutions/kanon/commit/145232aae70aab56a8715fa195f09633798ff2fa))
+
 * P3: triple test coverage + --home/--store-dir flag + LockfileSchemaError fail-fast; ruff 0.11.13 format parity
 
 Coverage (P3 audit found 10 gaps of 35 change-inventory items; 25 already fully covered): add real

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kanon-cli
-Version: 3.0.0
+Version: 3.1.0
 Summary: Kanon (Kanon Package Manager) CLI tool
 Project-URL: Homepage, https://github.com/caylent-solutions/kanon
 Project-URL: Issues, https://github.com/caylent-solutions/kanon/issues
@@ -1245,7 +1245,10 @@ Constraints resolve to the best matching tag at sync time.
 
 The resolver splits the `revision` attribute at the last `/` into a tag-path
 prefix and a constraint. It filters available tags by that prefix, evaluates
-the constraint, and returns the highest matching version.
+the constraint, and returns the highest matching version. The prefix is
+optional: `refs/tags/<pep440>` (and a bare constraint such as `~=1.0.0`)
+resolves against the bare `refs/tags/` namespace for single-purpose repos,
+while `refs/tags/<name>/<pep440>` scopes to that namespace.
 
 ```text
 revision="refs/tags/example/development/dev-lint/~=1.2.0"

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/README.md

@@ -1223,7 +1223,10 @@ Constraints resolve to the best matching tag at sync time.
 
 The resolver splits the `revision` attribute at the last `/` into a tag-path
 prefix and a constraint. It filters available tags by that prefix, evaluates
-the constraint, and returns the highest matching version.
+the constraint, and returns the highest matching version. The prefix is
+optional: `refs/tags/<pep440>` (and a bare constraint such as `~=1.0.0`)
+resolves against the bare `refs/tags/` namespace for single-purpose repos,
+while `refs/tags/<name>/<pep440>` scopes to that namespace.
 
 ```text
 revision="refs/tags/example/development/dev-lint/~=1.2.0"

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/docs/cli/validate.md

@@ -76,8 +76,9 @@ manifest correctness.
 - Project path values (`<project path="...">`) are unique across all marketplace
   files.
 - Revision attributes (`<project revision="...">`) use one of the allowed
-  pinnable formats: an exact deep-path tag `refs/tags/<path>/<pep440>`, a
-  branch ref `refs/heads/<name>`, or a 40-hex commit SHA. The wildcard `*`,
+  pinnable formats: an exact tag `refs/tags/<path>/<pep440>` (namespaced) or
+  `refs/tags/<pep440>` (bare, for single-purpose repos), a branch ref
+  `refs/heads/<name>`, or a 40-hex commit SHA. The wildcard `*`,
   a bare branch name (e.g. `main` without the `refs/heads/` prefix), and
   version-range constraints (`>=X,<Y`, `~=`) are rejected. On install a tag
   or branch revision resolves to a content SHA pinned in `.kanon.lock`

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/docs/integration-testing.md

@@ -819,7 +819,7 @@ rm -rf "${MS01_DIR}"
 
 ## 7. Category 6: Collision Detection (2 tests)
 
-### CD-01: Two sources producing the same package name
+### CD-01: Two sources resolving the same destination path to different content
 
 ```bash
 export CD01_DIR="${KANON_TEST_ROOT}/test-cd01"
@@ -845,7 +845,7 @@ kanon install .kanon
 **Pass criteria:**
 
 - Exit code 1
-- stderr contains `Package collision` and `pkg-alpha`
+- stderr contains `Package destination conflict` and `.packages/pkg-alpha`
 
 **Cleanup:**
 
@@ -853,7 +853,7 @@ kanon install .kanon
 rm -rf "${CD01_DIR}"
 ```
 
-### CD-02: Three sources, collision between two
+### CD-02: Three sources, two resolving the same destination path to different content
 
 ```bash
 export CD02_DIR="${KANON_TEST_ROOT}/test-cd02"
@@ -884,8 +884,8 @@ kanon install .kanon
 **Pass criteria:**
 
 - Exit code 1
-- stderr contains `Package collision` and `pkg-alpha`
-- Sources are processed alphabetically: `aaa` processes first, then `bbb` collides on `pkg-alpha`
+- stderr contains `Package destination conflict` and `.packages/pkg-alpha`
+- The conflict names the sources resolving `.packages/pkg-alpha` to different content (`aaa`/`ccc` pin one commit, `bbb` pins another)
 
 **Cleanup:**
 
@@ -6194,8 +6194,8 @@ After running every scenario from §2 through §28, populate this spreadsheet-st
 | 018 | IC-03         | install-clean                      | Comments and blank lines                               |        |      |         |       |
 | 019 | IC-04         | install-clean                      | Marketplace install false                              |        |      |         |       |
 | 020 | MS-01         | multi-source                       | Two sources aggregate                                  |        |      |         |       |
-| 021 | CD-01         | collision                          | Same-name collision two sources                        |        |      |         |       |
-| 022 | CD-02         | collision                          | Three-source alphabetical collision                    |        |      |         |       |
+| 021 | CD-01         | collision                          | Two sources, same destination path, different content  |        |      |         |       |
+| 022 | CD-02         | collision                          | Three sources, two share a destination path            |        |      |         |       |
 | 023 | LF-01         | linkfile                           | linkfile creates symlinks                              |        |      |         |       |
 | 024 | EC-01         | error-cases                        | Missing .kanon                                         |        |      |         |       |
 | 025 | EC-02         | error-cases                        | Empty .kanon                                           |        |      |         |       |

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/docs/list-and-add.md

@@ -301,15 +301,17 @@ Those checks belong to `kanon catalog audit`. A successful
 - `<name>` must match a `<catalog-metadata><name>` value in
   the resolved manifest repo.
 - `@<spec>` is optional. Default: the highest PEP 440-valid git
-  tag on the manifest repo (see "Default spec resolution").
+  tag in the entry's tag namespace (see "Default spec resolution").
 - Multiple `<name>[@<spec>]` arguments may be supplied in one
   invocation.
 
 ### add -- Default spec resolution
 
 When `@<spec>` is omitted, `kanon add` queries the manifest
-repo for its highest PEP 440-valid git tag via
-`git ls-remote --tags`. If zero PEP 440-valid tags exist:
+repo via `git ls-remote --tags` for the highest PEP 440-valid
+git tag in the entry's `refs/tags/<name>/` namespace, falling
+back to the bare `refs/tags/<pep440>` namespace when the entry
+has no namespaced tags. If zero PEP 440-valid tags exist:
 
 ```text
 ERROR: manifest repo has no PEP 440-valid tags; pin to a

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/docs/lockfile.md

@@ -213,9 +213,9 @@ include.
 **`url`** (string) -- Raw project URL as declared in the catalog XML.
 
 **`canonical_url`** (string) -- Canonical form of `url` (output of
-`canonicalize_repo_url`). Used for conflict detection: two entries
-sharing a canonical URL but pinning different SHAs trigger a
-`CanonicalUrlConflictError`.
+`canonicalize_repo_url`). Used by `kanon why` for URL matching. (Install
+conflict detection is keyed on the package destination path, not the URL --
+see "Package destination conflict" below.)
 
 **`ref_spec`** (string) -- Version / ref constraint for this project (the
 v4 rename of the former `revision_spec`). Written at lock time.
@@ -276,9 +276,10 @@ Exception: `LockfileValidationError`.
 
 This `ref_spec` is the source / catalog ref-spec. It is distinct from a
 manifest `<project revision>` (the content revision validated by
-`kanon validate marketplace`), which accepts an exact deep-path tag
-(`refs/tags/<path>/<pep440>`), a branch ref (`refs/heads/<name>`), or a
-40-hex commit SHA, and rejects the `*` wildcard, a bare branch name, and
+`kanon validate marketplace`), which accepts an exact tag
+(`refs/tags/<path>/<pep440>` namespaced or `refs/tags/<pep440>` bare), a
+branch ref (`refs/heads/<name>`), or a 40-hex commit SHA, and rejects the
+`*` wildcard, a bare branch name, and
 version-range constraints. On install a tag or branch `<project revision>`
 resolves to a content SHA pinned in `[[sources.content_pins]]`, so a
 branch revision does not pin a moving target.
@@ -391,9 +392,10 @@ source's resolved manifest tree, captured after `repo sync`:
   lock time.
 
 A reinstall replays each locked content SHA byte-for-byte (npm-style
-content-SHA locking). A manifest `<project revision>` may be an exact
-deep-path tag (`refs/tags/<path>/<pep440>`), a branch ref
-(`refs/heads/<name>`), or a 40-hex commit SHA. On install a tag or branch
+content-SHA locking). A manifest `<project revision>` may be an exact tag
+(`refs/tags/<path>/<pep440>` namespaced or `refs/tags/<pep440>` bare), a
+branch ref (`refs/heads/<name>`), or a 40-hex commit SHA. On install a tag
+or branch
 revision resolves to a content SHA that is pinned here, so a branch
 revision does NOT pin a moving target: the locked SHA is replayed until an
 explicit `kanon install --refresh-lock` re-resolves it.
@@ -690,12 +692,15 @@ If a `resolved_sha` recorded in the lockfile is no longer reachable on
 the remote, `kanon install` exits with `LockfileUnreachableShaError`.
 This is a hard error.
 
-### Transitive canonical-URL conflict
+### Package destination conflict
 
-When two or more `[[sources.projects]]` entries resolve to the same
-canonical URL but pin different commit SHAs, `kanon install` exits with
-`CanonicalUrlConflictError`. This check runs both during fresh resolution
-and during `LOCKFILE_CONSISTENT` replay.
+When two or more sources resolve the same package destination path
+(`.packages/<name>`, recorded in `[[sources.content_pins]]`) to different
+content SHAs, `kanon install` exits with `PackagePathConflictError`. The same
+repository fetched at different commits for **different** destination paths is
+allowed (independent packages from a mono-repo); only a same-path /
+different-content clash is an error. This check runs both during fresh
+resolution and during `LOCKFILE_CONSISTENT` replay.
 
 ---
 

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/docs/multi-source-guide.md

@@ -308,15 +308,27 @@ which source provided them.
 
 ## Collision Detection
 
-When two sources produce a package with the same name, Kanon detects the
-collision and fails immediately with an actionable error message.
+Kanon's install conflict check is keyed on the package **destination path**
+(`.packages/<name>`), not on the repository URL. Two sources may fetch the
+**same repository at different commits** as long as their `<project>` entries
+land at **different** destination paths -- this is the mono-repo case: install
+any version of package A and any version of package B even when both live in the
+same repo under different per-package tags. The only hard error is two sources
+resolving the **same** `.packages/<name>` slot to **different content**.
+
+When two sources produce a package at the same destination with different
+content, Kanon detects the collision and fails immediately with an actionable
+error message.
 
 ### How It Works
 
-During symlink aggregation, Kanon tracks which source provided each
-package name. If a package name already exists from a previous source,
-aggregation aborts with an error identifying both the conflicting
-sources and the duplicate package name.
+A pre-flight check (`kanon install`) groups every source's resolved content pins
+by destination path; a path claimed with more than one content SHA is a
+`PackagePathConflictError` (the same path at the same SHA is a benign duplicate).
+During symlink aggregation, Kanon additionally tracks which source provided each
+package name as an on-disk backstop: if a package name already exists from a
+previous source, aggregation aborts with an error identifying both the
+conflicting sources and the duplicate package name.
 
 ### Example Error
 

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/docs/troubleshooting.md

@@ -568,41 +568,42 @@ The following documents provide broader context:
 
 ---
 
-## 12. Canonical-URL Conflict
+## 12. Package Destination Conflict
 
 ### Symptom
 
 `kanon install` exits non-zero with:
 
 ```text
-ERROR: Canonical-URL conflict -- two or more sources declare the same
-repository URL with different SHAs.
-  Conflict for canonical URL:
-    https://gitserver/org/example-package
-  source-a/manifest.xml:
-    git@gitserver:org/example-package.git @ aaaa...aaaa
-  source-b/manifest.xml:
-    https://gitserver/org/example-package.git @ bbbb...bbbb
-  both URLs canonicalize to:
-    https://gitserver/org/example-package
-  Remediation: Use 'kanon why https://gitserver/org/example-package'
-  to investigate; resolve by removing one source or aligning REVISION
-  values across sources.
+ERROR: Package destination conflict -- two or more sources resolve the
+same package path to different content.
+  Conflict for package path: .packages/shared-lib
+  source_a (shared-lib): .packages/shared-lib @ aaaa...aaaa
+  source_b (shared-lib): .packages/shared-lib @ bbbb...bbbb
+  Remediation: remove one source or align the project revisions so
+  '.packages/shared-lib' resolves to a single content SHA.
 ```
 
+This fires only when two sources resolve the **same** `.packages/<name>`
+slot to **different** content. Fetching the **same repository at different
+commits** is fine when the `<project>` entries land at **different**
+destination paths (the mono-repo case -- install any version of package A and
+any version of package B from one repo).
+
 ### Reproducer
 
 ```bash
-# Two sources pointing to the same repo with different SHAs:
+# Two sources whose <project path> both resolve to .packages/shared-lib
+# at different commits:
 kanon install
 ```
 
 ### Fix
 
-**Option 1: Align the revision specs.**
+**Option 1: Align the revisions.**
 
-Edit `.kanon` so that all declarations use the same `REVISION`
-value (e.g., `==1.2.0`) for the conflicting repository.
+Edit `.kanon` (or the catalog manifests) so both declarations resolve the
+shared `.packages/<name>` path to the same commit.
 
 **Option 2: Remove one conflicting source.**
 
@@ -611,11 +612,11 @@ kanon remove <source-name>
 kanon install
 ```
 
-**Option 3: Investigate with `kanon why`.**
+**Option 3: Give the packages distinct destination paths.**
 
-```bash
-kanon why https://gitserver/org/example-package
-```
+If the two `<project>` entries are genuinely different packages, set a
+distinct `<project path>` for each so they no longer share a `.packages/`
+slot.
 
 ### See also
 

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/docs/url-canonicalization.md

@@ -90,8 +90,6 @@ The following kanon features use `canonicalize_repo_url` for URL matching:
 
 - **Lockfile `canonical_url` field** (spec Section 5) -- every entry in the
   lockfile stores the canonical form of the dependency URL.
-- **Conflict detection** (spec Section 4.7) -- two sources conflict when their
-  canonical URLs are equal.
 - **`kanon why` URL matching** (spec Section 4.5) -- the query URL is
   canonicalized before comparison against lockfile entries.
 - **`kanon outdated` URL matching** -- canonical URLs are used to correlate

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kanon-cli"
-version = "3.0.0"
+version = "3.1.0"
 description = "Kanon (Kanon Package Manager) CLI tool"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
@@ -40,6 +40,7 @@ Issues = "https://github.com/caylent-solutions/kanon/issues"
 
 
 
+
 [tool.hatch.build.targets.wheel]
 packages = [
     "src/kanon_cli",
@@ -134,6 +135,7 @@ enabled = false
 [tool.pymarkdown.plugins.md024]
 siblings_only = true
 
+
 [dependency-groups]
 dev = [
     "build>=1.4.3",

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/src/kanon_cli/__init__.py

@@ -1,3 +1,3 @@
 """Kanon CLI -- Kanon Package Manager."""
 
-__version__ = "3.0.0"
+__version__ = "3.1.0"

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/src/kanon_cli/commands/add.py

@@ -77,7 +77,13 @@ from kanon_cli.core.metadata import (
     derive_source_name,
     find_catalog_entry_files,
 )
-from kanon_cli.version import _list_tags, _resolve_constraint_from_tags, is_version_constraint, resolve_version
+from kanon_cli.version import (
+    _list_tags,
+    _resolve_constraint_from_tags,
+    is_version_constraint,
+    resolve_version,
+    select_entry_namespace,
+)
 
 
 _ZERO_PEP440_TAGS_ERROR = (
@@ -119,7 +125,8 @@ def register(subparsers: "argparse._SubParsersAction[argparse.ArgumentParser]")
             "constraint (e.g. ==1.0.0, ~=1.2, >=1.0.0,<2.0.0). The last '@' in\n"
             "each argument is the delimiter -- see spec Section 4.0 resolver rules.\n"
             "When <spec> is omitted the highest PEP 440-valid git tag in the\n"
-            "manifest repo is selected automatically."
+            "entry's refs/tags/<name>/ namespace is selected, or the highest\n"
+            "bare refs/tags/<pep440> tag when the entry has no namespaced tags."
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog=(
@@ -790,10 +797,10 @@ def _build_source_block_lines(
     prefix = f"{SOURCE_PREFIX}{source_name}"
 
     lines = [
-        f"{prefix}_URL={url}",
+        f"{prefix}_NAME={name}",
         f"{prefix}_REF={ref}",
+        f"{prefix}_URL={url}",
         f"{prefix}_PATH={path}",
-        f"{prefix}_NAME={name}",
     ]
     lines.extend(env_var_lines)
     if marketplace:
@@ -941,37 +948,52 @@ def _find_entry_by_name(
     sys.exit(1)
 
 
-def _resolve_spec(url: str, spec: str | None) -> str:
-    """Resolve the version spec for a catalog entry.
+def _resolve_spec(entry_name: str, url: str, spec: str | None) -> str:
+    """Resolve the version spec for a catalog entry, scoped to its tag namespace.
+
+    A catalog may tag an entry under a per-entry namespace
+    (``refs/tags/<entry_name>/<pep440>``) or with bare ``refs/tags/<pep440>``
+    tags. Resolution scopes to the entry's namespace when such tags exist (so
+    ``kanon add history`` resolves the highest ``refs/tags/history/<pep440>`` and
+    never another entry's tag), and falls back to the bare namespace otherwise
+    (a single-purpose, poly repo). The chosen namespace comes from
+    :func:`kanon_cli.version.select_entry_namespace`, the rule shared with
+    ``kanon search``.
 
-    When spec is None (default-spec path), selects the highest PEP 440-valid
-    git tag on the manifest repo via git ls-remote --tags. Raises SystemExit
+    When spec is None (default-spec path), selects the highest PEP 440-valid git
+    tag in the resolved namespace via git ls-remote --tags. Raises SystemExit
     with the spec-verbatim error if:
 
     - The repo has zero tags total (AC-FUNC-002), or
-    - The repo has tags but none parse as ``packaging.version.Version``
-      (AC-FUNC-003). In this subcase the first up-to-10 skipped tag names
-      are printed so the operator can identify the offending tags.
+    - The resolved namespace has tags but none parse as
+      ``packaging.version.Version`` (AC-FUNC-003). In this subcase the first
+      up-to-10 skipped tag names are printed so the operator can identify the
+      offending tags.
 
-    When spec is a non-empty string, delegates to resolve_version() to
-    resolve the PEP 440 constraint against the available tags (AC-FUNC-005).
+    When spec is a non-empty string, delegates to resolve_version() to resolve
+    the PEP 440 constraint within the resolved namespace (AC-FUNC-005).
 
     Args:
+        entry_name: The catalog entry name (its per-entry tag namespace).
         url: The manifest repo git URL.
         spec: The version spec string (e.g. '==1.0.0', '~=1.2') or None.
 
     Returns:
-        A full tag ref string (e.g. 'refs/tags/1.2.0').
+        A full tag ref string (e.g. 'refs/tags/history/0.1.1').
     """
+    tags = _list_tags(url)
+    namespace = select_entry_namespace(tags, entry_name)
+    scope_prefix = f"refs/tags/{namespace}/" if namespace is not None else "refs/tags/"
+
     if spec is None:
-        tags = _list_tags(url)
         if not tags:
             print(f"ERROR: {_ZERO_PEP440_TAGS_ERROR}", file=sys.stderr)
             sys.exit(1)
 
+        scoped_tags = [tag for tag in tags if tag.startswith(scope_prefix)]
         skipped: list[str] = []
         has_pep440 = False
-        for tag in tags:
+        for tag in scoped_tags:
             last = tag.rsplit("/", 1)[-1]
             try:
                 Version(last)
@@ -991,9 +1013,11 @@ def _resolve_spec(url: str, spec: str | None) -> str:
             print("\n".join(lines), file=sys.stderr)
             sys.exit(1)
 
-        return _resolve_constraint_from_tags("*", tags)
+        constraint = f"refs/tags/{namespace}/*" if namespace is not None else "*"
+        return _resolve_constraint_from_tags(constraint, tags)
 
-    return resolve_version(url, spec)
+    namespaced_spec = f"refs/tags/{namespace}/{spec}" if namespace is not None else spec
+    return resolve_version(url, namespaced_spec)
 
 
 def _resolve_manifest_repo_for_add(
@@ -1457,7 +1481,7 @@ def run_add(args: argparse.Namespace) -> int:
 
         metadata, xml_path, entry_url = _find_entry_by_name(name, catalog)
 
-        resolved_revision = _resolve_spec(entry_url, spec)
+        resolved_revision = _resolve_spec(name, entry_url, spec)
 
         base_alias = derive_source_name(metadata.name)
 

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/src/kanon_cli/commands/catalog.py

@@ -655,7 +655,8 @@ def _check_project_revision_exact_tags(target_path: pathlib.Path) -> list[AuditF
                     ),
                     remediation=(
                         f"Pin {project_name!r} to an exact tag refs/tags/<path>/<pep440> "
-                        "(e.g. refs/tags/my-plugin/1.0.0), a branch ref refs/heads/<name>, "
+                        "or refs/tags/<pep440> (e.g. refs/tags/my-plugin/1.0.0 or "
+                        "refs/tags/1.0.0), a branch ref refs/heads/<name>, "
                         "or a 40-hex commit SHA. "
                         "Run 'kanon validate marketplace' to confirm the manifest is clean."
                     ),

{kanon_cli-3.0.0 → kanon_cli-3.1.0}/src/kanon_cli/commands/search.py

@@ -82,7 +82,7 @@ from kanon_cli.core.metadata import (
     _parse_catalog_metadata,
     find_catalog_entry_files,
 )
-from kanon_cli.version import _list_branch_head, is_version_constraint, resolve_version
+from kanon_cli.version import _list_branch_head, is_version_constraint, resolve_version, select_entry_namespace
 
 
 _LATEST_TIP_MARKER = "latest"
@@ -268,30 +268,33 @@ def _resolve_search_ttl() -> int:
 
 
 def _list_namespaced_version_tags(url: str, entry_name: str) -> list[str]:
-    """Return PEP 440 version strings under ``refs/tags/<entry_name>/`` for a repo.
+    """Return a catalog entry's PEP 440 version strings, newest-first.
 
-    Runs ``git ls-remote --tags <url> refs/tags/<entry_name>/*`` (a prefix filter,
-    no ancestry walk and no tree reads -- spec Section 4.1 / Section 6), strips the
-    ``refs/tags/<entry_name>/`` prefix, drops peeled ``^{}`` deref lines, keeps only
-    last components that parse as PEP 440, and returns them sorted newest-first.
+    Lists the manifest repo's tags once via ``git ls-remote --tags`` and scopes
+    them with :func:`kanon_cli.version.select_entry_namespace`, the rule shared
+    with ``kanon add`` (spec Section 4.1 / Section 6): when the entry has
+    ``refs/tags/<entry_name>/<pep440>`` tags those are used; otherwise the bare
+    ``refs/tags/<pep440>`` tags are used (a single-purpose, poly repo). Peeled
+    ``^{}`` deref lines, other entries' namespaced tags, and non-PEP-440 last
+    components are dropped. Listing once and selecting the namespace keeps
+    ``kanon search`` consistent with what ``kanon add`` would resolve.
 
     Args:
         url: Git repository URL of the catalog manifest repo.
-        entry_name: The catalog entry name whose tag namespace is enumerated.
+        entry_name: The catalog entry name whose versions are enumerated.
 
     Returns:
         Newest-first list of PEP 440 version strings. Empty when the entry has no
-        ``refs/tags/<entry_name>/*`` tags.
+        namespaced and no bare version tags.
 
     Raises:
         SourceUnreachableError: When the underlying ``git ls-remote`` exits
             non-zero or the git binary is missing (the caller decides whether to
             skip+warn or propagate).
     """
-    pattern = f"refs/tags/{entry_name}/*"
     try:
         result = subprocess.run(
-            ["git", "ls-remote", "--tags", url, pattern],
+            ["git", "ls-remote", "--tags", url],
             capture_output=True,
             text=True,
             check=False,
@@ -302,17 +305,26 @@ def _list_namespaced_version_tags(url: str, entry_name: str) -> list[str]:
     if result.returncode != 0:
         raise SourceUnreachableError(url, result.stderr.strip() or f"git ls-remote exited {result.returncode}")
 
-    prefix = f"refs/tags/{entry_name}/"
-    versions: list[Version] = []
+    refs: list[str] = []
     for line in result.stdout.splitlines():
         line = line.strip()
         if not line or "\t" not in line:
             continue
         _sha, ref = line.split("\t", 1)
         ref = ref.strip()
-        if ref.endswith("^{}") or not ref.startswith(prefix):
+        if ref.endswith("^{}") or not ref.startswith("refs/tags/"):
+            continue
+        refs.append(ref)
+
+    namespace = select_entry_namespace(refs, entry_name)
+    prefix = f"refs/tags/{namespace}/" if namespace is not None else "refs/tags/"
+    versions: list[Version] = []
+    for ref in refs:
+        if not ref.startswith(prefix):
             continue
         suffix = ref[len(prefix) :]
+        if namespace is None and "/" in suffix:
+            continue
         try:
             versions.append(Version(suffix))
         except InvalidVersion: