@danmoisan/drm-copilot-mcp 0.0.1 → 0.0.5

package/resources/templates/push_down_claude_customizations.py

@@ -5,13 +5,71 @@ Purpose:
     workflow while reusing the shared publisher engine behind the existing
     `.github` customization flow. Settings-local configuration is excluded from
     push-down because it holds host-specific overrides that must not propagate.
+
+    Agent-memory files under `.claude/agent-memory/` are filtered by a
+    content-based scope check: only memories whose frontmatter declares
+    `metadata.scope: general` are distributed to a destination workspace. A
+    memory with an absent, malformed, or unrecognized scope is treated as
+    `repo` and excluded (fail-safe default), so repository-specific memories do
+    not leak into consumer workspaces. Files outside `.claude/agent-memory/`
+    are copied verbatim and are never affected by the scope filter.
 """
 
 from __future__ import annotations
 
 import argparse
+import re
+import sys
 from pathlib import Path
 
+AGENT_MEMORY_RELATIVE_ROOT = Path(".claude/agent-memory")
+GENERAL_MEMORY_SCOPE = "general"
+REPO_MEMORY_SCOPE = "repo"
+
+# Match a leading YAML frontmatter block: the first `---` line, the block body,
+# and the closing `---` line. DOTALL lets the body span multiple lines.
+_FRONTMATTER_PATTERN = re.compile(
+    r"\A---[ \t]*\r?\n(.*?)\r?\n---[ \t]*(?:\r?\n|\Z)", re.DOTALL
+)
+# Match a `metadata:` mapping key at column zero, then capture the indented
+# block lines that belong to it (lines that are more-indented or blank) until
+# the next column-zero key or end of the frontmatter body.
+_METADATA_BLOCK_PATTERN = re.compile(
+    r"^metadata:[ \t]*\r?\n((?:[ \t]+.*(?:\r?\n|\Z)|\r?\n)*)",
+    re.MULTILINE,
+)
+# Match a `scope:` leaf inside the metadata block, capturing its scalar value
+# up to an optional inline comment. Surrounding quotes are stripped later.
+_SCOPE_LEAF_PATTERN = re.compile(
+    r"^[ \t]+scope:[ \t]*([^\r\n#]*)",
+    re.MULTILINE,
+)
+
+
+def _ensure_bundled_scripts_import_path() -> None:
+    """Prepend bundled ``resources/scripts`` directory to ``sys.path``.
+
+    Purpose:
+        Make extension-bundled Python packages importable when this template is
+        invoked directly from ``resources/templates/`` rather than from the
+        repository root. Without this bootstrap, neither
+        ``scripts.dev_tools.push_down_copilot_customizations`` nor the fallback
+        ``dev_tools.push_down_copilot_customizations`` import resolves because
+        ``resources/scripts`` is not on ``sys.path`` by default.
+
+    Side Effects:
+        Mutates ``sys.path`` by inserting the bundled scripts directory at
+        index 0 when not already present.
+    """
+    scripts_dir = Path(__file__).resolve().parent.parent / "scripts"
+    scripts_dir_str = str(scripts_dir)
+
+    if scripts_dir_str not in sys.path:
+        sys.path.insert(0, scripts_dir_str)
+
+
+_ensure_bundled_scripts_import_path()
+
 try:
     from scripts.dev_tools.push_down_copilot_customizations import (
         PushDownFileSystem,
@@ -41,9 +99,12 @@ ROOT_FOLDERS: tuple[Path, ...] = (Path(".claude"),)
 EXCLUDED_RELATIVE_PATHS: tuple[Path, ...] = (Path(".claude/settings.local.json"),)
 
 __all__ = [
+    "AGENT_MEMORY_RELATIVE_ROOT",
     "ARTIFACT_DIRECTORY",
     "EXCLUDED_RELATIVE_PATHS",
+    "GENERAL_MEMORY_SCOPE",
     "PushDownSummary",
+    "REPO_MEMORY_SCOPE",
     "ROOT_FOLDERS",
     "main",
     "parse_args",
@@ -51,14 +112,113 @@ __all__ = [
 ]
 
 
+def _read_memory_scope(content: str) -> str:
+    """Return the declared memory scope from a file's YAML frontmatter.
+
+    Purpose:
+        Extract the `metadata.scope` leaf from the leading YAML frontmatter
+        block using a narrow `re`-based parser. This avoids adding a runtime
+        YAML dependency (PyYAML) while reading only the single leaf the
+        push-down scope filter requires.
+
+    Args:
+        content (str): The full text of a candidate memory file, including any
+            leading `---` frontmatter block.
+
+    Returns:
+        str: ``"general"`` only when the frontmatter contains a `metadata:`
+        mapping whose `scope:` leaf is exactly ``general`` (quotes and inline
+        comments stripped). In every other case — missing frontmatter, no
+        closing `---`, no `metadata:` block, no `scope:` leaf, or any value
+        other than exactly ``general`` — it returns ``"repo"`` as the fail-safe
+        default so nothing leaks by accident.
+
+    Raises:
+        None.
+
+    Side Effects:
+        None.
+    """
+
+    # Isolate the leading frontmatter block; absent or unterminated frontmatter
+    # fails safe to the repo scope so unmarked files are never distributed.
+    frontmatter_match = _FRONTMATTER_PATTERN.match(content)
+    if frontmatter_match is None:
+        return REPO_MEMORY_SCOPE
+    frontmatter_body = frontmatter_match.group(1)
+
+    # Locate the metadata mapping; without it there is no scope leaf to read.
+    metadata_match = _METADATA_BLOCK_PATTERN.search(frontmatter_body)
+    if metadata_match is None:
+        return REPO_MEMORY_SCOPE
+    metadata_block = metadata_match.group(1)
+
+    # Read the scope leaf from within the metadata block only; a top-level
+    # `scope:` outside `metadata:` is intentionally ignored.
+    scope_match = _SCOPE_LEAF_PATTERN.search(metadata_block)
+    if scope_match is None:
+        return REPO_MEMORY_SCOPE
+
+    # Strip surrounding whitespace and optional matching quotes before the
+    # exact-match comparison; only an exact `general` is treated as general.
+    scope_value = scope_match.group(1).strip()
+    if (
+        len(scope_value) >= 2
+        and scope_value[0] == scope_value[-1]
+        and scope_value[0] in {'"', "'"}
+    ):
+        scope_value = scope_value[1:-1].strip()
+    if scope_value == GENERAL_MEMORY_SCOPE:
+        return GENERAL_MEMORY_SCOPE
+    return REPO_MEMORY_SCOPE
+
+
+def _is_general_memory_file(relative_path: Path, content: str) -> bool:
+    """Return whether a candidate file may be distributed by push-down.
+
+    Purpose:
+        Decide inclusion for one source file. Files under
+        `.claude/agent-memory/` are distributed only when general-scoped;
+        every other file is always distributed and is unaffected by the scope
+        filter.
+
+    Args:
+        relative_path (Path): The file path relative to the repository root.
+        content (str): The full text of the file, used to read the memory
+            scope when the path is under the agent-memory subtree.
+
+    Returns:
+        bool: ``True`` when the path is outside `.claude/agent-memory/`, or when
+        the path is under that subtree and `_read_memory_scope(content)` is
+        exactly ``general``. ``False`` only for an agent-memory file whose
+        scope is not general (the fail-safe exclusion).
+
+    Raises:
+        None.
+
+    Side Effects:
+        None.
+    """
+
+    # Files outside the agent-memory subtree are always copied; the scope
+    # filter never applies to rules, skills, agents, hooks, or settings.
+    try:
+        relative_path.relative_to(AGENT_MEMORY_RELATIVE_ROOT)
+    except ValueError:
+        return True
+    return _read_memory_scope(content) == GENERAL_MEMORY_SCOPE
+
+
 class _ExcludingFileSystem:
     """Wrap a PushDownFileSystem and filter specified paths from list_files.
 
     Purpose:
         Prevent host-specific files (e.g. `settings.local.json`) from being
-        included when the publisher enumerates source files. Chosen over a
-        post-enumeration filter so the exclusion travels with the filesystem
-        contract and is transparent to the shared engine.
+        included when the publisher enumerates source files, and exclude
+        repository-specific agent memories so only general-scoped memories are
+        distributed. Chosen over a post-enumeration filter so the exclusion
+        travels with the filesystem contract and is transparent to the shared
+        engine.
 
     Usage:
         Instantiate with the inner adapter and exclusion paths relative to
@@ -66,6 +226,8 @@ class _ExcludingFileSystem:
 
     Invariants / Constraints:
         Excluded paths are resolved once at construction time for O(1) checks.
+        The content-based scope filter reads file content only for candidates
+        under `.claude/agent-memory/`; all other files skip the read.
 
     Side Effects:
         Delegates all I/O to the inner adapter.
@@ -76,15 +238,65 @@ class _ExcludingFileSystem:
     ) -> None:
         """Set up the adapter; resolve exclusion paths relative to repo_root."""
         self._inner = inner
+        # Retain the resolved repo root so per-file scope checks can derive the
+        # repo-relative path needed by the agent-memory scope filter.
+        self._repo_root = repo_root.resolve()
         # Resolve once at init so list_files per-path checks are O(1).
         self._excluded: frozenset[Path] = frozenset(
             (repo_root / p).resolve() for p in excluded
         )
 
+    def _is_scope_included(self, path: Path) -> bool:
+        """Return whether a candidate file passes the agent-memory scope filter.
+
+        Purpose:
+            Apply the general-vs-repo memory scope decision to one enumerated
+            file, reading its content only when the path is under the
+            agent-memory subtree.
+
+        Args:
+            path (Path): The absolute candidate path returned by the inner
+                adapter's ``list_files``.
+
+        Returns:
+            bool: ``True`` when the file is outside `.claude/agent-memory/` or
+            is a general-scoped memory; ``False`` for a non-general memory.
+
+        Raises:
+            None.
+
+        Side Effects:
+            Reads file content via the inner adapter for agent-memory
+            candidates only.
+        """
+
+        # Derive the repo-relative path so the agent-memory check matches the
+        # `.claude/agent-memory/` prefix regardless of the absolute location.
+        try:
+            relative_path = path.resolve().relative_to(self._repo_root)
+        except ValueError:
+            # A path outside the repo root cannot be an agent memory; include it.
+            return True
+
+        # Skip the content read entirely for files outside the memory subtree.
+        try:
+            relative_path.relative_to(AGENT_MEMORY_RELATIVE_ROOT)
+        except ValueError:
+            return True
+
+        content = self._inner.read_text(path)
+        return _is_general_memory_file(relative_path, content)
+
     def list_files(self, root: Path) -> list[Path]:
-        """Return inner list_files output with excluded paths removed."""
+        """Return inner list_files output with excluded paths removed.
+
+        Drops paths in ``EXCLUDED_RELATIVE_PATHS`` and any agent-memory file
+        that is not general-scoped per the content-based scope filter.
+        """
         return [
-            p for p in self._inner.list_files(root) if p.resolve() not in self._excluded
+            p
+            for p in self._inner.list_files(root)
+            if p.resolve() not in self._excluded and self._is_scope_included(p)
         ]
 
     def is_dir(self, path: Path) -> bool:
@@ -170,7 +382,16 @@ def main(
     """Run the Claude customization push-down publisher CLI."""
 
     args = parse_args(argv)
-    resolved_repo_root = resolve_cli_path(repo_root or Path.cwd())
+    # Resolve the source root to the bundled customizations directory so the
+    # template distributes the bundled `.claude` payload rather than copying a
+    # destination workspace's existing `.claude` back onto itself. This mirrors
+    # the codex template (`push_down_codex_and_agents_customizations.py`), which
+    # sets its source root to the sibling bundled directory. The optional
+    # `repo_root` argument still allows tests to inject an explicit root.
+    customizations_root = (
+        Path(__file__).resolve().parent.parent / "claude-customizations"
+    )
+    resolved_repo_root = resolve_cli_path(repo_root or customizations_root)
     resolved_destination = resolve_cli_path(args.destination)
     resolved_fs = fs or RealPushDownFileSystem()
     summary = push_down_customizations(

package/resources/claude-customizations/.claude/agent-memory/orchestrator/feedback_repo_root_is_source_of_truth.md

@@ -1,11 +0,0 @@
----
-name: repo-root-is-source-of-truth-for-codex-bundle
-description: When repo-root .codex/.agents/AGENTS.md/etc differ from the extension's bundled customizations, treat the repo root as authoritative and update the bundle to match — not the other way around.
-type: feedback
----
-
-When repo-root files such as `.codex/agents/*.toml`, `.codex/config.toml`, `.codex/hooks/*.ps1`, `.agents/skills/**`, and `AGENTS.md` differ from their bundled copies under `extensions/drm-copilot/resources/codex-and-agents-customizations/` and `extensions/drm-copilot/resources/claude-customizations/`, the repo-root version is the source of truth. Update the bundle to mirror the repo root.
-
-**Why:** The user actively overwrites repo-root files (e.g., by running the codex-native-converter in apply mode) and expects the bundle to reflect those changes. Reverting repo-root files to match the bundle is the wrong direction. Confirmed 2026-05-02 after a converter apply run regenerated `.codex/`, `.agents/`, and `AGENTS.md`.
-
-**How to apply:** When contract tests like `test_push_down_claude_resource_contracts`, `test_push_down_codex_and_agents_resource_contracts`, `test_codex_agent_wrapper_contracts`, `test_codex_full_migration_inventory`, `test_codex_handoff_contract_parity`, or `test_orchestration_guardrail_contracts` fail with diffs between repo and bundle, copy from repo → bundle. Never propose `git checkout HEAD --` on the repo-root file.

package/resources/claude-customizations/.claude/agent-memory/orchestrator/feedback_vsce_verify_package_location.md

@@ -1,19 +0,0 @@
----
-name: Verify which package.json is the VS Code extension before any vsce work
-description: In multi-package repos, never assume the repo root is the publishable extension. Verify location before vsce package/publish/.vscodeignore work.
-type: feedback
----
-
-Before doing any `vsce` packaging, publishing, or `.vscodeignore` work, verify which directory contains the actual VS Code extension. Do not assume the repo root.
-
-**Why:** On 2026-05-02, I spent multiple troubleshooting rounds (`.vscodeignore` rewrites, allow-list strategy, esbuild bundling) treating the repo root `package.json` as the publishable extension. The real extension lives at `extensions/drm-copilot/` with its own `package.json`, `src/`, `tsconfig.json`, `node_modules/`, and existing build pipeline. The user had been side-loading shipping `.vsix` builds for ~4 months from the correct location. The root `package.json` is a workspace orchestrator, not a publishable extension. My misdiagnosis caused the user to push back: "I have been side-loading this extension for a significant period of time and it functions properly." All the changes I made to the root (main, activationEvents, esbuild.config.cjs, bundle script, root .vscodeignore) were applied to the wrong package and produced no value for the actual extension.
-
-**How to apply:** When the user mentions `vsce`, packaging, publishing, `.vscodeignore`, extension manifests, or "the extension":
-
-1. First, locate every `package.json` in the workspace that declares `engines.vscode` or `contributes` or has `@types/vscode` as a dep. Use `Grep` for `"engines"` or `"contributes"` across all `package.json` files.
-2. If multiple candidates exist, identify the one with `main`, `activationEvents`, and `contributes` populated — that is the real extension.
-3. If shipping `.vsix` artifacts exist (e.g., under `artifacts/vsix/`), inspect the most recent one with `unzip -l` and read the included `extension/package.json` to see what is actually being shipped. The directory whose source matches the shipped `out/` files is the real extension.
-4. Run `vsce ls` only from that directory.
-5. State explicitly which directory you identified before making any edits.
-
-This rule applies even when the user opens a root `package.json` in the IDE. The `ide_opened_file` hint indicates focus, not authority over which package is the extension.

package/resources/claude-customizations/.claude/agent-memory/orchestrator/project_extension_location.md

@@ -1,11 +0,0 @@
----
-name: VS Code extension location in this repo
-description: The publishable VS Code extension lives at extensions/drm-copilot/, not at the repo root.
-type: project
----
-
-The publishable VS Code extension lives at `extensions/drm-copilot/`, not at the repo root.
-
-**Why:** This repo is a workspace orchestrator that contains multiple parallel toolchains (Python, PowerShell, TypeScript) plus a Claude/Copilot agent runtime. The VS Code extension is one component among several. Its source is at `extensions/drm-copilot/src/`, its build output is at `extensions/drm-copilot/out/`, its manifest is `extensions/drm-copilot/package.json`, and shipping `.vsix` artifacts go to `artifacts/vsix/` with timestamped filenames. Confirmed 2026-05-02 by inspecting the most recent shipping `.vsix` (`drm-copilot-20260501-114515.vsix`), whose `extension.vsixmanifest` description reads "Extension-side bundled workflow execution utilities and MCP bridge."
-
-**How to apply:** All `vsce` commands (`ls`, `package`, `publish`) must run from `extensions/drm-copilot/`. The repo root `package.json` is not a publishable extension and should not declare `main`, `activationEvents`, or be passed to `vsce`. When the user asks about extension packaging, install paths, the manifest, or the `.vsix`, default to inspecting `extensions/drm-copilot/` first. Verify the location is still current before acting (the layout could change).

package/resources/claude-customizations/.claude/agent-memory/prd-feature/MEMORY.md

@@ -1 +0,0 @@
-- [push-down command pattern](project_push_down_pattern.md) — 10-file change map for adding a new push-down command; reference impl is pushDownCodexAndAgentsCustomizations

package/resources/claude-customizations/.claude/agent-memory/prd-feature/project_push_down_pattern.md

@@ -1,13 +0,0 @@
----
-name: push-down command pattern
-description: The established 10-file pattern for adding a new push-down command to the drm-copilot extension, as used by pushDownCodexAndAgentsCustomizations and pushDownClaudeDir.
-type: project
----
-
-All push-down commands follow a zero-argument pattern across five layers: bundled resource directory, Python dev-tools publisher, Python entry-point template, TypeScript service, and MCP surface.
-
-The reference implementation is `pushDownCodexAndAgentsCustomizations`. New push-down commands clone it, changing only the resource path, tool name, and artifact directory string.
-
-**Why:** Consistency across the extension's automation surface and test coverage.
-
-**How to apply:** When speccing or implementing any new push-down command, the 10-file change map is: (1) resource bundle directory, (2) dev_tools publisher .py, (3) templates entry-point .py, (4) repo-automation-service.ts (REPO_AUTOMATION_TOOLS tuple, interface, implementation), (5) mcp-tool-inputs.ts (input resolver), (6) mcp-tools.ts (definition, dispatch, import), (7) extension.ts (register + subscriptions), (8) package.json (commands entry), (9) extension.workflow-commands.test.ts (registration test), (10) mcp-server.test.ts (mock + tool list assertion). The tool list assertion is an exact ordered array — insert new tool name at the correct position.

package/resources/claude-customizations/.claude/agent-memory/task-researcher/MEMORY.md

@@ -1,3 +0,0 @@
-# Task Researcher Memory Index
-
-- [push-down-claude-dir-149](project_push_down_claude_dir.md) — Issue #149: pushDownClaudeDir command research completed 2026-04-16

package/resources/claude-customizations/.claude/agent-memory/task-researcher/project_push_down_claude_dir.md

@@ -1,11 +0,0 @@
----
-name: push-down-claude-dir-149
-description: Research for Issue #149 — pushDownClaudeDir command. Pattern, file map, and risks documented.
-type: project
----
-
-Issue #149 adds `drmCopilotExtension.pushDownClaudeDir` / MCP tool `push_down_claude_dir`.
-
-**Why:** Developers opening new workspaces lack the `.claude/` runtime directory. The extension has push-down commands for `.github/` and `.codex/.agents/` but not `.claude/`.
-
-**How to apply:** When implementing, clone the `pushDownCodexAndAgentsCustomizations` pattern exactly. Full file change map is in `artifacts/research/push-down-claude-dir-149.md`. Key constraint: exclude `settings.local.json` and `agent-memory/` from the bundled resource directory at `resources/claude-dir-customizations/.claude/`.