kanon-cli 3.3.2__tar.gz → 3.3.3__tar.gz

{kanon_cli-3.3.2 → kanon_cli-3.3.3}/CHANGELOG.md

@@ -2,8 +2,137 @@
 
 
 
+## v3.3.3 (2026-08-06)
+
+### Fix
+
+* fix: scope linkfile dest rule by entry type, exempt direct-checkout marketplaces (#109)
+
+* fix: scope marketplace linkfile dest rule to claude-marketplace entries
+
+validate_linkfile_dest required every <linkfile dest> in every catalog
+entry to start with ${CLAUDE_MARKETPLACES_DIR}/, ignoring the declared
+<catalog-metadata><type>. Non-marketplace entries that install correctly
+could not pass validation.
+
+Closes #94
+
+* fix: exempt direct-checkout entries, de-duplicate errors, align tests
+
+Builds on ryano144's 0e75e27 (#99), which correctly identified issue #94:
+validate_linkfile_dest required every <linkfile dest> to start with
+${CLAUDE_MARKETPLACES_DIR}/ regardless of <catalog-metadata><type>, so a
+non-marketplace entry that `kanon install` places correctly could not pass
+validation. Scoping that rule by entry type is right and is kept as is.
+
+Three problems remained.
+
+1. The new "a claude-marketplace entry must land a dest under
+   ${CLAUDE_MARKETPLACES_DIR}/" rule rejected an entry that declares no
+   <linkfile> at all. That is the direct-checkout shape:
+   register_direct_checkout_marketplaces registers a project whose checkout
+   carries .claude-plugin/marketplace.json and which has no <linkfile>
+   children, covered end to end by test_marketplace_direct_checkout.py. The
+   old validator accepted it, so the rule as written was a regression, and it
+   reproduced the very validator/install contradiction #94 reports, aimed at a
+   different entry shape. The rule now applies only when the entry declares at
+   least one <linkfile>; an entry declaring none is exempt. The useful half is
+   unchanged: an entry whose links all land elsewhere is still caught, and the
+   diagnostic now names the direct-checkout way out.
+
+2. Linkfile checks follow each entry's <include> chain, so a defect in a
+   manifest shared by several entries was reported once per consumer. Three
+   entries including one broken packages.xml produced three identical errors
+   and a count of three for a single defect. Errors are de-duplicated within a
+   call (a manifest reachable by two include paths) and across the run.
+   Identical message text means the same file, project and reason, so
+   collapsing exact duplicates cannot hide a second real defect.
+
+3. tests/functional/test_validate_marketplace.py still asserted the old
+   contract and was not touched by #99, so three parametrized cases failed:
+   relative/path, CLAUDE_MARKETPLACES_DIR/missing-dollar-brace and
+   ${OTHER_VAR}/proj are contained dests on an entry with no <type> and are
+   now legal. Rather than delete the coverage, the class is split: the three
+   contained dests assert exit 0, and a new negative case asserts exit 1 for
+   the three shapes that escape the workspace (absolute, '..', empty).
+
+Adds docs/integration-testing.md Category 11b (ET-01..ET-07) with runnable
+manual reproductions, and tests/scenarios/test_et.py automating them through
+the real `kanon validate marketplace` subprocess: the full 3x4 entry-type by
+linkfile-shape matrix, containment across all three entry types, a linkfile
+inside an <include>, a marketplace dest supplied by an include, single
+reporting of a shared-include defect, and the mixed plugin-plus-standards
+package from #94 with its negative counterpart.
+
+Every documented scenario was also executed by hand against the built CLI and
+matched its stated pass criteria.
+
+Closes #94
+
+* test: guard the single dependency-resolution path
+
+Adds automated coverage for four invariants that were only ever verified by
+hand while diagnosing the shtab CI drift and the 3.3.1 publish failure. Each
+corresponds to a defect this repository actually hit, and none had a test.
+
+1. A tool invoked through `uv run` is declared in [dependency-groups].
+   `make security-scan` was `uv run bandit` while bandit was declared nowhere,
+   so uv fell through to PATH and silently ran a system-wide bandit -- an
+   undeclared dependency deciding a security gate. `uv run` does not fail on an
+   undeclared executable, so nothing surfaced it.
+
+2. No Make recipe invokes a tool directly. A bare `ruff check .` or
+   `pytest -m unit` resolves from PATH rather than uv.lock, which is precisely
+   the two-path split that let shtab 1.9.0 break the tiered CI jobs while the
+   uv-based jobs stayed green. Only the scenario target was previously guarded.
+
+3. A dependency whose generated output is byte-compared against a committed
+   fixture carries an upper bound. `shtab>=1.7.0` allowed 1.9.0 to change its
+   completion output and break CI with no change to this repository.
+
+4. The release job re-locks and stages uv.lock. semantic-release bumps
+   pyproject.toml and __init__.py but knows nothing about uv.lock, so without
+   the explicit refresh every release leaves the lock a version behind and
+   `uv sync --locked` fails on the tag -- how 3.3.1 failed to publish. Its
+   symptom is already guarded by test_uv_lock_records_the_declared_project_version;
+   this guards the mechanism that prevents it.
+
+Each was verified RED by reverting the invariant it protects: removing bandit
+from the dev group, rewriting `uv run ruff` as `ruff`, restoring `shtab>=1.7.0`,
+dropping `uv lock` from the release job, and dropping uv.lock from its `git add`.
+All five produce a message naming the file and the remedy.
+
+* fix(test): replace the uv-run regex with linear tokenization
+
+CodeQL flagged py/redos (high) on the pattern added in the previous commit:
+
+    \buv\s+run\s+(?:--[\w-]+(?:[= ]\S+)?\s+)*([A-Za-z][\w.-]*)
+
+The repeated group holds an optional sub-match, so input with many repetitions
+of ' --- ---' backtracks exponentially. Skipping uv's own flags is awkward to
+express as a pattern and easy to get wrong in exactly this way.
+
+Walking tokens does the same job in linear time and reads more plainly: find
+`uv run`, skip following tokens that begin with '-', take the next one. A flag
+with a detached value would misreport that value as the tool; no target uses
+that form, and the assertion names the offending line, so it would be obvious
+rather than silent. Documented on the helper.
+
+Not suppressed: CLAUDE.md forbids annotating away a security finding, and the
+finding was correct. Both guards were re-verified RED afterwards, and the
+tokenizer returns in single-digit milliseconds on 40k adversarial tokens.
+
+---------
+
+Co-authored-by: Ryan Gross <ryan.gross@caylent.com> ([`ccfdfec`](https://github.com/caylent-solutions/kanon/commit/ccfdfecdbd7b3e366e1ca9c0579bd84aa70e66ae))
+
+
 ## v3.3.2 (2026-08-05)
 
+### Chore
+
+* chore(release): 3.3.2 ([`6f5ffe7`](https://github.com/caylent-solutions/kanon/commit/6f5ffe7c01553820a2e091cdc996151b5100c6cb))
+
 ### Fix
 
 * fix(ci): refresh uv.lock during the release version bump (#107)
@@ -47,6 +176,12 @@ Note the existing 3.3.1 tag still points at a commit carrying the stale
 lock, so republishing that exact tag will keep failing until the tag is
 moved or a further release is cut. ([`00714e6`](https://github.com/caylent-solutions/kanon/commit/00714e648a42bea706945e7a38a66fa6dca8df28))
 
+### Unknown
+
+* Merge pull request #108 from caylent-solutions/release-3.3.2
+
+Release 3.3.2 ([`fc48540`](https://github.com/caylent-solutions/kanon/commit/fc48540a5fc082e64c81ef9809f68d583a3a16e8))
+
 
 ## v3.3.1 (2026-08-04)
 

{kanon_cli-3.3.2 → kanon_cli-3.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kanon-cli
-Version: 3.3.2
+Version: 3.3.3
 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

{kanon_cli-3.3.2 → kanon_cli-3.3.3}/docs/integration-testing.md

@@ -1521,6 +1521,197 @@ rm -rf "${VA06_DIR}"
 
 ---
 
+## 12b. Category 11b: Catalog Entry Type Validation (7 tests)
+
+`kanon validate marketplace` enforces two linkfile rules. **Containment** applies
+to every entry: a `<linkfile dest>` names a symlink created relative to the top of
+the consumer tree, so it must land inside that tree. **The marketplace-dest rule**
+applies only to an entry whose `<catalog-metadata><type>` is `claude-marketplace`
+*and* which declares at least one `<linkfile>`: one of those dests must sit under
+`${CLAUDE_MARKETPLACES_DIR}/`.
+
+The worked example throughout is a package of engineering standards containing a
+Claude Code plugin plus the repo-level assets a team expects at conventional
+paths: `.claude/rules/`, `.githooks/`, and a `.gitleaks.toml` at the repo root.
+
+**Shared setup for this category:**
+
+```bash
+export ET_DIR="${KANON_TEST_ROOT}/test-et"
+mkdir -p "${ET_DIR}"
+
+# Writes a catalog entry: $1 file, $2 <type> (empty for none), $3.. linkfile dests.
+et_entry() {
+  local file="$1" entry_type="$2"; shift 2
+  local links="" type_el=""
+  for dest in "$@"; do
+    links="${links}      <linkfile src=\"src\" dest=\"${dest}\" />
+"
+  done
+  [ -n "${entry_type}" ] && type_el="    <type>${entry_type}</type>
+"
+  mkdir -p "$(dirname "${file}")"
+  cat > "${file}" << ENTRYEOF
+<?xml version="1.0" encoding="UTF-8"?>
+<manifest>
+  <remote name="origin" fetch="https://example.com" />
+  <project name="standards" path=".packages/standards" remote="origin" revision="refs/tags/ex/standards/1.0.0">
+${links}  </project>
+  <catalog-metadata>
+    <name>standards</name>
+    <display-name>Engineering Standards</display-name>
+    <description>Plugin plus repo-level standards.</description>
+    <version>1.0.0</version>
+${type_el}    <owner-name>Example Org</owner-name>
+    <owner-email>eng@example.com</owner-email>
+    <keywords>standards</keywords>
+  </catalog-metadata>
+</manifest>
+ENTRYEOF
+}
+```
+
+### ET-01: Marketplace entry ships a plugin alongside repo-level standards
+
+The case issue #94 was filed to unblock. One entry registers a Claude plugin and
+also places rules, hooks, a root dotfile, and a plain relative config.
+
+```bash
+rm -rf "${ET_DIR}/c01" && et_entry "${ET_DIR}/c01/repo-specs/standards.xml" claude-marketplace \
+  '${CLAUDE_MARKETPLACES_DIR}/standards' \
+  '${PROJECT_ROOT}/.claude/rules' \
+  '${PROJECT_ROOT}/.githooks' \
+  '${PROJECT_ROOT}/.gitleaks.toml' \
+  'config/lint.toml'
+
+kanon validate marketplace --repo-root "${ET_DIR}/c01"
+```
+
+**Pass criteria:** Exit code 0, stderr empty. Before the fix each of the four
+non-marketplace dests produced one error.
+
+### ET-02: Non-marketplace entry links only into the project root
+
+An entry declaring `<type>library</type>` ships no plugin at all.
+
+```bash
+rm -rf "${ET_DIR}/c02" && et_entry "${ET_DIR}/c02/repo-specs/standards.xml" library \
+  '${PROJECT_ROOT}/.claude/rules' '${PROJECT_ROOT}/.gitleaks.toml'
+
+kanon validate marketplace --repo-root "${ET_DIR}/c02"
+```
+
+**Pass criteria:** Exit code 0, stderr empty. An entry with no `<type>` at all
+behaves identically.
+
+### ET-03: Direct-checkout marketplace entry declares no linkfiles
+
+A `claude-marketplace` entry registered from a checked-out
+`.claude-plugin/marketplace.json`, with no `<linkfile>` elements. The
+marketplace-dest rule must not fire, or validation would reject an entry that
+`kanon install` registers correctly.
+
+```bash
+rm -rf "${ET_DIR}/c03" && et_entry "${ET_DIR}/c03/repo-specs/standards.xml" claude-marketplace
+
+kanon validate marketplace --repo-root "${ET_DIR}/c03"
+```
+
+**Pass criteria:** Exit code 0, stderr empty.
+
+### ET-04: Marketplace entry whose linkfiles all miss the marketplace directory
+
+Declares itself a marketplace and uses linkfiles, but every dest lands elsewhere,
+so it registers nothing.
+
+```bash
+rm -rf "${ET_DIR}/c04" && et_entry "${ET_DIR}/c04/repo-specs/standards.xml" claude-marketplace \
+  '${PROJECT_ROOT}/.claude/rules' '${PROJECT_ROOT}/.githooks'
+
+set +e
+kanon validate marketplace --repo-root "${ET_DIR}/c04"
+exit_code=$?
+set -e
+```
+
+**Pass criteria:** Exit code non-zero. stderr contains `registers no marketplace`
+and names all three ways out, including `direct checkout`.
+
+### ET-05: A dest that escapes the consumer workspace is rejected
+
+Three shapes escape, for every entry type: an absolute path, a `..` component,
+and an empty dest.
+
+```bash
+for bad in '/etc/kanon/rules' '../../outside/workspace' ''; do
+  rm -rf "${ET_DIR}/c05" && et_entry "${ET_DIR}/c05/repo-specs/standards.xml" library "${bad}"
+  set +e
+  kanon validate marketplace --repo-root "${ET_DIR}/c05"
+  echo "dest=${bad} exit=$?"
+  set -e
+done
+```
+
+**Pass criteria:** Exit code non-zero for each. stderr names the specific reason:
+`absolute path`, `'..' component`, or `dest is empty`. No error text on stdout.
+
+### ET-06: A linkfile inside an `<include>` is validated like an inline one
+
+`kanon install` resolves the whole include chain, so validation must see the same
+projects. The entry below is clean; only the included manifest is not.
+
+```bash
+rm -rf "${ET_DIR}/c06" && mkdir -p "${ET_DIR}/c06/repo-specs"
+cat > "${ET_DIR}/c06/repo-specs/packages.xml" << 'INCEOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<manifest>
+  <project name="shared" path=".packages/shared" remote="origin" revision="refs/tags/ex/shared/1.0.0">
+    <linkfile src="src" dest="../escapes" />
+  </project>
+</manifest>
+INCEOF
+et_entry "${ET_DIR}/c06/repo-specs/standards.xml" claude-marketplace '${CLAUDE_MARKETPLACES_DIR}/standards'
+sed -i.bak 's|<remote name="origin" fetch="https://example.com" />|<remote name="origin" fetch="https://example.com" />\n  <include name="repo-specs/packages.xml" />|' \
+  "${ET_DIR}/c06/repo-specs/standards.xml"
+
+set +e
+kanon validate marketplace --repo-root "${ET_DIR}/c06"
+exit_code=$?
+set -e
+```
+
+**Pass criteria:** Exit code non-zero. stderr contains `'..' component` and names
+`packages.xml`.
+
+### ET-07: A defect in a shared `<include>` is reported once
+
+Three entries include the same broken manifest. Reporting the identical message
+once per consumer inflates the count and buries the distinct failures.
+
+```bash
+rm -rf "${ET_DIR}/c07" && mkdir -p "${ET_DIR}/c07/repo-specs"
+cp "${ET_DIR}/c06/repo-specs/packages.xml" "${ET_DIR}/c07/repo-specs/packages.xml"
+for name in alpha bravo charlie; do
+  cp "${ET_DIR}/c06/repo-specs/standards.xml" "${ET_DIR}/c07/repo-specs/${name}.xml"
+done
+
+set +e
+kanon validate marketplace --repo-root "${ET_DIR}/c07" 2>&1 | grep -c "'..' component"
+set -e
+```
+
+**Pass criteria:** Exactly `1` occurrence, and stderr reports
+`Found 1 validation error(s)` despite three entries including the defect.
+
+**Cleanup:**
+
+```bash
+cd "${KANON_TEST_ROOT}"
+rm -rf "${ET_DIR}"
+```
+
+---
+
 ## 13. Category 12: Entry Points (2 tests)
 
 ### EP-01: python -m kanon_cli --version

{kanon_cli-3.3.2 → kanon_cli-3.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kanon-cli"
-version = "3.3.2"
+version = "3.3.3"
 description = "Kanon (Kanon Package Manager) CLI tool"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

{kanon_cli-3.3.2 → kanon_cli-3.3.3}/src/kanon_cli/__init__.py

@@ -1,3 +1,3 @@
 """Kanon CLI -- Kanon Package Manager."""
 
-__version__ = "3.3.2"
+__version__ = "3.3.3"

{kanon_cli-3.3.2 → kanon_cli-3.3.3}/src/kanon_cli/core/marketplace_validator.py

@@ -1,8 +1,17 @@
 """Validate marketplace XML manifest files.
 
 Checks:
-  - All <linkfile dest> attributes use the ${CLAUDE_MARKETPLACES_DIR}
-    variable prefix, rejecting hard-coded or relative paths.
+  - Every <linkfile dest> resolves inside the consumer workspace: an absolute
+    path, an empty dest, and a '..' traversal component are rejected. A dest
+    rooted at ${CLAUDE_MARKETPLACES_DIR}/, at any other ${VAR}, or at a plain
+    workspace-relative path is accepted -- an entry may ship non-plugin content
+    (shared rules, lint config, git hooks) alongside a Claude plugin.
+  - An entry whose <catalog-metadata><type> is 'claude-marketplace' AND which
+    declares at least one <linkfile> lands one of them under
+    ${CLAUDE_MARKETPLACES_DIR}/, so an entry that declares itself a marketplace
+    actually registers one. An entry with no <linkfile> at all is exempt: that
+    is the direct-checkout shape that register_direct_checkout_marketplaces
+    handles. Entries of any other type (or none) carry no such requirement.
   - All <include> chains are unbroken (every referenced file exists).
   - All flattened project path names are unique across manifests.
   - All <project revision> attributes are pinnable refs: an exact existing git
@@ -27,6 +36,7 @@ from collections.abc import Callable
 from pathlib import Path
 
 from kanon_cli.constants import (
+    CATALOG_TYPE_CLAUDE_MARKETPLACE,
     GIT_RETRY_COUNT_DEFAULT,
     GIT_RETRY_COUNT_ENV_VAR,
     KANON_GIT_LS_REMOTE_TIMEOUT,
@@ -47,36 +57,196 @@ LsRemoteRunner = Callable[[str, str], tuple[int, str, str]]
 _FULL_SHA_RE = re.compile(r"^[0-9a-f]{40}$")
 
 
-def validate_linkfile_dest(xml_path: Path) -> list[str]:
-    """Validate all linkfile dest attributes in a manifest XML file.
+def read_entry_type(xml_path: Path) -> str | None:
+    """Return the entry's ``<catalog-metadata><type>`` text, or None.
 
-    Checks that every <linkfile> element's dest attribute starts with
-    ${CLAUDE_MARKETPLACES_DIR}/. Returns a list of error messages for
-    any violations found. An empty list means validation passed.
+    A lightweight, side-effect-free read of the one metadata field this module
+    needs. It deliberately does NOT reuse
+    :func:`kanon_cli.core.metadata._parse_catalog_metadata`: that parser raises
+    on any missing REQUIRED field and warns on stderr for missing RECOMMENDED
+    ones, which is ``kanon validate metadata``'s job (spec Section 3.5
+    soft-spot 1), not this module's. A metadata problem must be reported once,
+    by the command that owns it -- never as a spurious linkfile error here.
 
     Args:
-        xml_path: Path to the XML manifest file to validate.
+        xml_path: Path to the catalog entry manifest.
+
+    Returns:
+        The stripped ``<type>`` text, or None when the file is unparseable, has
+        no ``<catalog-metadata>`` block, or declares no non-empty ``<type>``.
+    """
+    try:
+        root = ET.parse(xml_path).getroot()
+    except ET.ParseError:
+        return None
+
+    for block in root.findall("catalog-metadata"):
+        type_el = block.find("type")
+        if type_el is not None and type_el.text and type_el.text.strip():
+            return type_el.text.strip()
+    return None
+
+
+def _dest_containment_error(dest: str) -> str | None:
+    """Return why *dest* escapes the consumer workspace, or None when it is safe.
+
+    A ``<linkfile dest>`` names a symlink created relative to the top of the
+    consumer tree. The property worth enforcing is containment -- the link must
+    land inside the workspace -- not which specific variable roots it. Three
+    shapes escape and are rejected:
+
+    - An empty dest (nothing to create).
+    - An absolute path (``/etc/...``), which writes outside the workspace
+      regardless of where kanon runs.
+    - Any ``..`` path component, which climbs out of the workspace.
+
+    A dest rooted at ``${CLAUDE_MARKETPLACES_DIR}/``, at another ``${VAR}``, or
+    at a plain relative path is contained and accepted. A ``${VAR}`` root is
+    resolved from the consumer's own ``.kanon``, so the consumer -- not the
+    catalog author -- chooses where it lands.
+
+    Args:
+        dest: The raw ``dest`` attribute value, before variable expansion.
+
+    Returns:
+        A short reason string when *dest* escapes; None when it is safe.
+    """
+    if not dest:
+        return "dest is empty"
+    if dest.startswith("/"):
+        return "dest is an absolute path; it must be relative to the consumer workspace root"
+    if ".." in dest.split("/"):
+        return "dest contains a '..' component that escapes the consumer workspace"
+    return None
+
+
+def _collect_manifest_chain(xml_path: Path, repo_root: Path) -> list[Path]:
+    """Return *xml_path* plus every manifest reachable through ``<include>``.
+
+    Depth-first and cycle-safe, mirroring the traversal in
+    :func:`validate_include_chain`. Linkfile checks must see the same set of
+    ``<project>`` elements that ``kanon install`` acts on, and install resolves
+    the full include chain -- so a ``<project>`` moved into an included
+    ``packages.xml`` is validated exactly like one written inline. Missing
+    includes are skipped here; :func:`validate_include_chain` owns that error.
+
+    Args:
+        xml_path: The catalog entry manifest to start from.
+        repo_root: Repository root used to resolve ``<include name>`` paths.
+
+    Returns:
+        The entry manifest followed by each reachable include, in visit order.
+    """
+    chain: list[Path] = []
+    visited: set[str] = set()
+
+    def _walk(current: Path) -> None:
+        resolved = str(current.resolve())
+        if resolved in visited:
+            return
+        visited.add(resolved)
+        chain.append(current)
+        try:
+            root = ET.parse(current).getroot()
+        except ET.ParseError:
+            return
+        for include in root.findall("include"):
+            name = include.get("name")
+            if not name:
+                continue
+            include_path = repo_root / name
+            if include_path.exists():
+                _walk(include_path)
+
+    _walk(xml_path)
+    return chain
+
+
+def validate_linkfile_dest(xml_path: Path, repo_root: Path) -> list[str]:
+    """Validate the ``<linkfile dest>`` attributes reachable from a catalog entry.
+
+    Two rules, applied across the entry and its whole ``<include>`` chain:
+
+    1. **Containment (every entry).** Each dest must stay inside the consumer
+       workspace -- see :func:`_dest_containment_error`. A dest rooted at
+       ``${CLAUDE_MARKETPLACES_DIR}/``, at another ``${VAR}``, or at a plain
+       relative path all pass. This is what the old blanket
+       ``${CLAUDE_MARKETPLACES_DIR}/`` prefix requirement was standing in for,
+       and it no longer forbids an entry from shipping non-plugin content
+       (shared rules, lint config, git hooks) next to a Claude plugin.
+
+    2. **A marketplace entry that uses linkfiles points one at the marketplace.**
+       When the entry declares ``<catalog-metadata><type>claude-marketplace</type>``
+       -- the same field ``kanon add`` reads to set
+       ``KANON_SOURCE_<alias>_MARKETPLACE`` -- and declares at least one
+       ``<linkfile>``, one of those dests must sit under
+       ``${CLAUDE_MARKETPLACES_DIR}/``. Otherwise the entry calls itself a
+       marketplace while every link it creates lands somewhere else.
+
+       An entry that declares **no** ``<linkfile>`` at all is exempt, because
+       that is the direct-checkout shape:
+       :func:`kanon_cli.core.marketplace.register_direct_checkout_marketplaces`
+       registers a project whose checkout carries
+       ``.claude-plugin/marketplace.json`` and which has no ``<linkfile>``
+       children. Requiring a marketplace dest there would reject an entry that
+       ``kanon install`` registers correctly -- the same validator/install
+       contradiction this function exists to remove, aimed at a different entry
+       shape. The catalog XML alone cannot prove that checkout carries a
+       ``marketplace.json``, so the absence of linkfiles is the only signal
+       available here and validation defers to install rather than guessing.
+
+       An entry of any other type, or with no ``<type>``, carries no such
+       requirement.
+
+    Errors are de-duplicated before returning. A ``<project>`` reached through
+    ``<include>`` is visited once per entry that includes it, so a single
+    defect in a shared include would otherwise be reported once per consumer.
+
+    Args:
+        xml_path: Path to the catalog entry manifest.
+        repo_root: Repository root used to resolve ``<include name>`` paths.
 
     Returns:
-        List of error messages. Empty if all dest attributes are valid.
-        Each error identifies the file, project name, and invalid dest.
+        List of error messages, each naming the file, project, and dest,
+        in first-seen order with duplicates removed. Empty when the entry
+        passes.
     """
     errors: list[str] = []
-    tree = ET.parse(xml_path)
-    root = tree.getroot()
+    is_marketplace = read_entry_type(xml_path) == CATALOG_TYPE_CLAUDE_MARKETPLACE
+    linkfile_count = 0
+    marketplace_dest_count = 0
 
-    for project in root.findall("project"):
-        project_name = project.get("name", "<unknown>")
-        for linkfile in project.findall("linkfile"):
-            dest = linkfile.get("dest", "")
-            if not dest.startswith(MARKETPLACE_DIR_PREFIX):
-                errors.append(
-                    f"{xml_path}: project '{project_name}' has "
-                    f"invalid linkfile dest='{dest}' -- "
-                    f"must start with {MARKETPLACE_DIR_PREFIX}"
-                )
+    for manifest_path in _collect_manifest_chain(xml_path, repo_root):
+        try:
+            root = ET.parse(manifest_path).getroot()
+        except ET.ParseError:
+            continue
+        for project in root.findall("project"):
+            project_name = project.get("name", "<unknown>")
+            for linkfile in project.findall("linkfile"):
+                linkfile_count += 1
+                dest = linkfile.get("dest", "")
+                if dest.startswith(MARKETPLACE_DIR_PREFIX):
+                    marketplace_dest_count += 1
+                    continue
+                reason = _dest_containment_error(dest)
+                if reason is not None:
+                    errors.append(
+                        f"{manifest_path}: project '{project_name}' has invalid linkfile dest='{dest}' -- {reason}"
+                    )
+
+    if is_marketplace and linkfile_count > 0 and marketplace_dest_count == 0:
+        errors.append(
+            f"{xml_path}: entry declares "
+            f"<catalog-metadata><type>{CATALOG_TYPE_CLAUDE_MARKETPLACE}</type> "
+            f"and declares <linkfile> elements, but none target "
+            f"{MARKETPLACE_DIR_PREFIX} -- such an entry registers no marketplace. "
+            f"Point one linkfile at {MARKETPLACE_DIR_PREFIX}, change <type> to a "
+            f"non-marketplace value, or drop the linkfiles to register the "
+            f"project as a direct checkout."
+        )
 
-    return errors
+    return list(dict.fromkeys(errors))
 
 
 def validate_include_chain(
@@ -593,12 +763,20 @@ def validate_marketplace(
     """Validate all marketplace XML files found under repo-specs/.
 
     Scans for catalog entry manifests (``*.xml`` with a ``<catalog-metadata>``
-    block) and validates each one for linkfile dest attributes, include chain
-    integrity, project path uniqueness, pinnable ``<project revision>`` format
-    (a deep-path tag, a ``refs/heads/<name>`` branch ref, or a 40-hex SHA;
-    covering revisions inherited from ``<default revision>``), and two-tier +
-    local-aware revision existence. Exits with a non-zero code if any validation
-    errors are found.
+    block) and validates each one for linkfile dest containment (plus the
+    marketplace-dest rule for ``claude-marketplace`` entries that use
+    linkfiles), include chain integrity, project path uniqueness, pinnable
+    ``<project revision>`` format (a deep-path tag, a ``refs/heads/<name>``
+    branch ref, or a 40-hex SHA; covering revisions inherited from
+    ``<default revision>``), and two-tier + local-aware revision existence.
+    Exits with a non-zero code if any validation errors are found.
+
+    Errors are de-duplicated across the whole run before reporting. Linkfile
+    and include checks follow each entry's ``<include>`` chain, so a defect in
+    a manifest shared by several entries is reached once per entry; reporting
+    it once per consumer would inflate the count and bury the distinct
+    failures. Identical message text means the same file, project, and reason,
+    so collapsing exact duplicates cannot hide a second real defect.
 
     Args:
         repo_root: Repository root directory.
@@ -626,13 +804,15 @@ def validate_marketplace(
     for xml_file in marketplace_files:
         rel_path = xml_file.relative_to(repo_root)
         print(f"Validating {rel_path}...")
-        all_errors.extend(validate_linkfile_dest(xml_file))
+        all_errors.extend(validate_linkfile_dest(xml_file, repo_root))
         all_errors.extend(validate_include_chain(xml_file, repo_root))
 
     all_errors.extend(validate_name_uniqueness(marketplace_files))
     all_errors.extend(validate_tag_format(marketplace_files, repo_root))
     all_errors.extend(validate_revision_existence(marketplace_files, repo_root, effective_env, runner))
 
+    all_errors = list(dict.fromkeys(all_errors))
+
     if all_errors:
         print(
             f"\nFound {len(all_errors)} validation error(s):",