claude-dev-env 8.21.0 → 8.22.0

package/.agents/skills/sync-dev-env/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: sync-dev-env
+description: Install or update claude-dev-env in a running session, link the skills of every enabled plugin so a running session loads them, and schedule a daily re-sync at 6:00 AM local by default. Use when the user asks to sync claude-dev-env into a session, to load the skills of a plugin without a restart, or to set up the daily sync.
+argument-hint: "[HH:MM] [IANA time zone]"
+---
+
+# /sync-dev-env
+
+An always-on session starts once, so a SessionStart hook runs once and never again. Claude Code reads plugins only at session start, and a running session has no plugin reload. The skills directory is read live, so one symlink per skill makes each skill of a plugin load at once.
+
+## 1. Install or update the package
+
+Run `npx --yes claude-dev-env@latest --update --target ~/.claude`.
+
+The installer leaves symlinks in the skills directory in place.
+
+## 2. Link the plugin skills
+
+Run `python3 "${CLAUDE_SKILL_DIR}/scripts/link_plugin_skills.py"`.
+
+The script reads `enabledPlugins` from `~/.claude/settings.json` and the newest install of each plugin from `~/.claude/plugins/installed_plugins.json`. It links each plugin skill by its bare name. A link it owns points inside `~/.claude/plugins/cache`. On each run it re-points an owned link at the current plugin version and removes an owned link whose skill is gone or whose plugin is disabled. A name some other skill already holds is skipped and reported.
+
+Tell the user the summary line. Report each skipped name, because a plugin skill that refers to a skipped sibling by `../<name>` reaches the other skill.
+
+## 3. Schedule the daily sync
+
+Skip this step when `list_triggers` already shows a routine named `Daily dev env sync` bound to this session.
+
+The time defaults to 6:00 AM in the user's time zone. Take the time and the IANA zone from the arguments. With no zone given and none known, ask for it.
+
+In a Claude Code cloud session, call `create_trigger`:
+
+- `name`: `Daily dev env sync`
+- `cron_expression`: `CRON_TZ=<zone> <minute> <hour> * * *`, with the minute jittered a few minutes early per the tool's guidance
+- `prompt`: `/sync-dev-env`
+- `initiation`: `human_request`
+
+Bind the routine to the session whose container needs the sync. Called from that session, leave `persistent_session_id` unset. Called from another session, set `persistent_session_id` to the session that needs the sync. Never set `create_new_session_on_fire`, because a fresh session gets its own container and syncs nothing the running session reads.
+
+Then call `list_triggers` and tell the user the routine name and its `next_run_at` in their time zone. The schedule counts as armed only once that listing shows it.
+
+In a local Claude Code session, `CronCreate` jobs expire after 7 days. Use `/loop` or an operating system scheduler for a local daily sync.
+
+## Layout
+
+| File | Role |
+|---|---|
+| `SKILL.md` | This flow: install, link, schedule |
+| `scripts/link_plugin_skills.py` | Converges the skills directory on one link per enabled plugin skill |
+| `scripts/test_link_plugin_skills.py` | Behavior tests for link, skip, re-point, remove, and a second run |
+| `scripts/sync_dev_env_constants/config/constants.py` | Plugin file paths, settings keys, outcome names, report lines |

package/.agents/skills/sync-dev-env/scripts/link_plugin_skills.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""Link every enabled plugin's skills into the user skills directory.
+
+::
+
+    ~/.claude/skills/tdd -> ~/.claude/plugins/cache/<market>/<plugin>/<version>/skills/tdd
+    ok:   no entry named tdd           -> link created
+    ok:   owned link at an old version -> link re-pointed
+    ok:   owned link, skill now gone   -> link removed
+    flag: a user skill named tdd       -> left in place, reported as skipped
+
+A link is owned when it points inside the plugin cache.
+A running session reads the skills directory live, so the linked skills load at once.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections import Counter
+from pathlib import Path
+
+scripts_directory = str(Path(__file__).resolve().parent)
+if scripts_directory not in sys.path:
+    sys.path.insert(0, scripts_directory)
+
+from sync_dev_env_constants.config.constants import (
+    CREATED_REPORT,
+    DEFAULT_CLAUDE_HOME,
+    ENABLED_PLUGINS_KEY,
+    INSTALL_PATH_KEY,
+    INSTALLED_PLUGINS_RELATIVE_PATH,
+    KEPT_OUTCOME,
+    LAST_UPDATED_KEY,
+    LINKED_OUTCOME,
+    PLUGIN_CACHE_RELATIVE_PATH,
+    PLUGINS_KEY,
+    REMOVED_OUTCOME,
+    REMOVED_REPORT,
+    REPOINTED_OUTCOME,
+    REPOINTED_REPORT,
+    SETTINGS_FILE_NAME,
+    SKILL_MANIFEST_FILE_NAME,
+    SKILLS_DIRECTORY_NAME,
+    SKIPPED_OUTCOME,
+    SKIPPED_REPORT,
+    SUMMARY_REPORT,
+)
+
+
+def read_json_file(from_path: Path) -> dict:
+    """Read one JSON settings file.
+
+    Args:
+        from_path: The JSON file to read.
+
+    Returns:
+        The parsed object, or an empty dict when the file is absent.
+    """
+    if not from_path.is_file():
+        return {}
+    return json.loads(from_path.read_text(encoding="utf-8"))
+
+
+def enabled_install_paths(claude_home: Path) -> list[Path]:
+    """List the newest install directory of every plugin the user settings enable.
+
+    Args:
+        claude_home: The Claude Code home directory.
+
+    Returns:
+        One install directory per enabled plugin that has an install record.
+    """
+    enabled_by_plugin = read_json_file(claude_home / SETTINGS_FILE_NAME).get(ENABLED_PLUGINS_KEY, {})
+    records_by_plugin = read_json_file(claude_home / INSTALLED_PLUGINS_RELATIVE_PATH).get(PLUGINS_KEY, {})
+    all_install_paths = []
+    for each_plugin, each_record_list in records_by_plugin.items():
+        if enabled_by_plugin.get(each_plugin) is not True or not each_record_list:
+            continue
+        newest_record = max(each_record_list, key=lambda each_record: each_record.get(LAST_UPDATED_KEY, ""))
+        all_install_paths.append(Path(newest_record[INSTALL_PATH_KEY]))
+    return all_install_paths
+
+
+def skill_directories_of(install_path: Path) -> list[Path]:
+    """List the skill directories one plugin install ships.
+
+    Args:
+        install_path: The plugin install directory.
+
+    Returns:
+        Each subdirectory of the install's skills directory that holds a SKILL.md.
+    """
+    skills_root = install_path / SKILLS_DIRECTORY_NAME
+    if not skills_root.is_dir():
+        return []
+    return [
+        each_directory
+        for each_directory in sorted(skills_root.iterdir())
+        if (each_directory / SKILL_MANIFEST_FILE_NAME).is_file()
+    ]
+
+
+def desired_skill_targets(claude_home: Path) -> dict[str, Path]:
+    """Map each enabled plugin skill name to the directory its link points at.
+
+    Args:
+        claude_home: The Claude Code home directory.
+
+    Returns:
+        The target directory by skill name. The first plugin to ship a name keeps it.
+    """
+    target_by_name: dict[str, Path] = {}
+    for each_install_path in enabled_install_paths(claude_home):
+        for each_directory in skill_directories_of(each_install_path):
+            target_by_name.setdefault(each_directory.name, each_directory)
+    return target_by_name
+
+
+def is_owned_link(entry: Path, plugin_cache: Path) -> bool:
+    """Report whether an entry is a symlink that points inside the plugin cache.
+
+    Args:
+        entry: One entry of the skills directory.
+        plugin_cache: The resolved plugin cache directory.
+
+    Returns:
+        True when the entry is a symlink whose target lies under the plugin cache.
+    """
+    if not entry.is_symlink():
+        return False
+    link_target = Path(os.path.normpath(entry.parent / os.readlink(entry)))
+    return link_target.is_relative_to(plugin_cache)
+
+
+def sync_links(claude_home: Path) -> Counter:
+    """Converge the skills directory on one link per enabled plugin skill.
+
+    Args:
+        claude_home: The Claude Code home directory.
+
+    Returns:
+        The count of each outcome name across every entry the run touched.
+    """
+    skills_directory = Path(os.path.realpath(claude_home / SKILLS_DIRECTORY_NAME))
+    skills_directory.mkdir(parents=True, exist_ok=True)
+    plugin_cache = Path(os.path.realpath(claude_home / PLUGIN_CACHE_RELATIVE_PATH))
+    target_by_name = desired_skill_targets(claude_home)
+    outcome_counts: Counter = Counter()
+    for each_entry in sorted(skills_directory.iterdir()):
+        if is_owned_link(each_entry, plugin_cache) and each_entry.name not in target_by_name:
+            each_entry.unlink()
+            print(REMOVED_REPORT.format(name=each_entry.name))
+            outcome_counts[REMOVED_OUTCOME] += 1
+    for each_name, each_target in sorted(target_by_name.items()):
+        outcome_counts[link_one_skill(skills_directory / each_name, each_target, plugin_cache)] += 1
+    return outcome_counts
+
+
+def link_one_skill(link_path: Path, target: Path, plugin_cache: Path) -> str:
+    """Create or re-point one owned link, leaving any other entry of that name alone.
+
+    Args:
+        link_path: Where the link belongs in the skills directory.
+        target: The plugin skill directory the link points at.
+        plugin_cache: The resolved plugin cache directory.
+
+    Returns:
+        The outcome name: linked, repointed, kept, or skipped.
+    """
+    if is_owned_link(link_path, plugin_cache):
+        if os.readlink(link_path) == str(target):
+            return KEPT_OUTCOME
+        link_path.unlink()
+        link_path.symlink_to(target, target_is_directory=True)
+        print(REPOINTED_REPORT.format(name=link_path.name, target=target))
+        return REPOINTED_OUTCOME
+    if link_path.exists() or link_path.is_symlink():
+        print(SKIPPED_REPORT.format(name=link_path.name))
+        return SKIPPED_OUTCOME
+    link_path.symlink_to(target, target_is_directory=True)
+    print(CREATED_REPORT.format(name=link_path.name, target=target))
+    return LINKED_OUTCOME
+
+
+def main() -> int:
+    """Parse the Claude home from the command line, sync the links, and print a summary.
+
+    Returns:
+        0 after printing the summary line.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--claude-home", type=Path, default=DEFAULT_CLAUDE_HOME)
+    parsed_arguments = parser.parse_args()
+    outcome_counts = sync_links(parsed_arguments.claude_home)
+    print(
+        SUMMARY_REPORT.format(
+            linked=outcome_counts[LINKED_OUTCOME],
+            repointed=outcome_counts[REPOINTED_OUTCOME],
+            removed=outcome_counts[REMOVED_OUTCOME],
+            skipped=outcome_counts[SKIPPED_OUTCOME],
+            kept=outcome_counts[KEPT_OUTCOME],
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.agents/skills/sync-dev-env/scripts/sync_dev_env_constants/config/__init__.py

@@ -0,0 +1 @@
+"""Config package for the link_plugin_skills constants."""

package/.agents/skills/sync-dev-env/scripts/sync_dev_env_constants/config/constants.py

@@ -0,0 +1,26 @@
+"""Paths, file keys, and report lines for the link_plugin_skills script."""
+
+from pathlib import Path
+
+DEFAULT_CLAUDE_HOME = Path.home() / ".claude"
+INSTALLED_PLUGINS_RELATIVE_PATH = Path("plugins") / "installed_plugins.json"
+PLUGIN_CACHE_RELATIVE_PATH = Path("plugins") / "cache"
+SETTINGS_FILE_NAME = "settings.json"
+SKILLS_DIRECTORY_NAME = "skills"
+SKILL_MANIFEST_FILE_NAME = "SKILL.md"
+ENABLED_PLUGINS_KEY = "enabledPlugins"
+PLUGINS_KEY = "plugins"
+INSTALL_PATH_KEY = "installPath"
+LAST_UPDATED_KEY = "lastUpdated"
+CREATED_REPORT = "linked {name} -> {target}"
+REPOINTED_REPORT = "re-pointed {name} -> {target}"
+REMOVED_REPORT = "removed {name} (its skill left the plugin or the plugin is off)"
+SKIPPED_REPORT = (
+    "skipped {name}: a skill the plugin does not own already uses that name"
+)
+SUMMARY_REPORT = "{linked} linked, {repointed} re-pointed, {removed} removed, {skipped} skipped, {kept} unchanged"
+LINKED_OUTCOME = "linked"
+REPOINTED_OUTCOME = "repointed"
+REMOVED_OUTCOME = "removed"
+SKIPPED_OUTCOME = "skipped"
+KEPT_OUTCOME = "kept"

package/.agents/skills/sync-dev-env/scripts/sync_dev_env_constants/config/test_constants.py

@@ -0,0 +1,19 @@
+from sync_dev_env_constants.config import constants
+
+
+def test_paths_match_the_claude_code_plugin_layout() -> None:
+    assert constants.INSTALLED_PLUGINS_RELATIVE_PATH.parts == (
+        "plugins",
+        "installed_plugins.json",
+    )
+    assert constants.PLUGIN_CACHE_RELATIVE_PATH.parts == ("plugins", "cache")
+    assert constants.DEFAULT_CLAUDE_HOME.name == ".claude"
+
+
+def test_keys_match_the_claude_code_settings_files() -> None:
+    assert (
+        constants.ENABLED_PLUGINS_KEY,
+        constants.PLUGINS_KEY,
+        constants.INSTALL_PATH_KEY,
+        constants.LAST_UPDATED_KEY,
+    ) == ("enabledPlugins", "plugins", "installPath", "lastUpdated")

package/.agents/skills/sync-dev-env/scripts/sync_dev_env_constants/test___init__.py

@@ -0,0 +1,5 @@
+import sync_dev_env_constants
+
+
+def test_sync_dev_env_constants_loads_as_package() -> None:
+    assert sync_dev_env_constants.__path__

package/.agents/skills/sync-dev-env/scripts/test_link_plugin_skills.py

@@ -0,0 +1,142 @@
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+scripts_directory = str(Path(__file__).resolve().parent)
+if scripts_directory not in sys.path:
+    sys.path.insert(0, scripts_directory)
+
+import link_plugin_skills
+
+PLUGIN_KEY = "kit@market"
+
+
+def install_plugin(
+    claude_home: Path, version: str, all_skill_names: tuple[str, ...]
+) -> Path:
+    install_path = claude_home / "plugins" / "cache" / "market" / "kit" / version
+    for each_name in all_skill_names:
+        skill_directory = install_path / "skills" / each_name
+        skill_directory.mkdir(parents=True)
+        (skill_directory / "SKILL.md").write_text("---\nname: x\n---\n")
+    record = {
+        "installPath": str(install_path),
+        "version": version,
+        "lastUpdated": version,
+    }
+    (claude_home / "plugins" / "installed_plugins.json").write_text(
+        json.dumps({"version": 2, "plugins": {PLUGIN_KEY: [record]}})
+    )
+    return install_path
+
+
+def enable_plugin(claude_home: Path, is_enabled: bool) -> None:
+    (claude_home / "settings.json").write_text(
+        json.dumps({"enabledPlugins": {PLUGIN_KEY: is_enabled}})
+    )
+
+
+@pytest.fixture
+def claude_home(tmp_path: Path) -> Path:
+    home = tmp_path / ".claude"
+    (home / "plugins").mkdir(parents=True)
+    agents_skills = tmp_path / ".agents" / "skills"
+    agents_skills.mkdir(parents=True)
+    (home / "skills").symlink_to(agents_skills, target_is_directory=True)
+    enable_plugin(home, True)
+    return home
+
+
+def run_sync(claude_home: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(
+        sys, "argv", ["link_plugin_skills.py", "--claude-home", str(claude_home)]
+    )
+    link_plugin_skills.main()
+
+
+def test_should_link_each_plugin_skill_through_the_skills_pointer(
+    claude_home: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    install_path = install_plugin(claude_home, "1.0.0", ("tdd", "how"))
+
+    run_sync(claude_home, monkeypatch)
+
+    assert (claude_home / "skills" / "tdd").resolve() == install_path / "skills" / "tdd"
+    assert (claude_home / "skills" / "how" / "SKILL.md").is_file()
+
+
+def test_should_leave_an_existing_skill_of_the_same_name_untouched(
+    claude_home: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    install_plugin(claude_home, "1.0.0", ("tdd",))
+    own_skill = claude_home / "skills" / "tdd"
+    own_skill.mkdir()
+    (own_skill / "SKILL.md").write_text("mine")
+
+    run_sync(claude_home, monkeypatch)
+
+    assert not own_skill.is_symlink()
+    assert (own_skill / "SKILL.md").read_text() == "mine"
+    assert "skipped tdd" in capsys.readouterr().out
+
+
+def test_should_repoint_links_and_drop_vanished_skills_when_the_version_changes(
+    claude_home: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    install_plugin(claude_home, "1.0.0", ("tdd", "old"))
+    run_sync(claude_home, monkeypatch)
+    new_install_path = install_plugin(claude_home, "2.0.0", ("tdd",))
+
+    run_sync(claude_home, monkeypatch)
+
+    assert (
+        claude_home / "skills" / "tdd"
+    ).resolve() == new_install_path / "skills" / "tdd"
+    assert not (claude_home / "skills" / "old").is_symlink()
+
+
+def test_should_remove_owned_links_when_the_plugin_is_disabled(
+    claude_home: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    install_plugin(claude_home, "1.0.0", ("tdd",))
+    run_sync(claude_home, monkeypatch)
+    enable_plugin(claude_home, False)
+
+    run_sync(claude_home, monkeypatch)
+
+    assert list((claude_home / "skills").iterdir()) == []
+
+
+def test_should_keep_a_user_link_that_points_outside_the_plugin_cache(
+    claude_home: Path, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    install_plugin(claude_home, "1.0.0", ())
+    elsewhere = tmp_path / "elsewhere"
+    elsewhere.mkdir()
+    user_link = claude_home / "skills" / "mine"
+    user_link.symlink_to(elsewhere, target_is_directory=True)
+
+    run_sync(claude_home, monkeypatch)
+
+    assert user_link.resolve() == elsewhere
+
+
+def test_should_change_nothing_on_a_second_run(
+    claude_home: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    install_plugin(claude_home, "1.0.0", ("tdd", "how"))
+    run_sync(claude_home, monkeypatch)
+    capsys.readouterr()
+
+    run_sync(claude_home, monkeypatch)
+
+    assert (
+        capsys.readouterr().out.strip()
+        == "0 linked, 0 re-pointed, 0 removed, 0 skipped, 2 unchanged"
+    )

package/bin/ever-shipped-skills.mjs

@@ -104,6 +104,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'split-pr',
     'step-notes',
     'structure-prompt',
+    'sync-dev-env',
     'syncing-submodules',
     'task-build',
     'team-advisor',

package/bin/merge_settings_defaults.test.mjs

@@ -0,0 +1,43 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+
+import {
+    mergeMissingSettingsDefaults,
+    settingsDefaultsFromPackageSettings,
+} from './merge_settings_defaults.mjs';
+
+test('settingsDefaultsFromPackageSettings excludes managed lists', () => {
+    const packageSettings = {
+        permissions: { allow: ['Read'] },
+        advisorModel: 'fable',
+        env: { EDITOR: 'code' },
+    };
+
+    assert.deepEqual(settingsDefaultsFromPackageSettings(packageSettings), {
+        advisorModel: 'fable',
+        env: { EDITOR: 'code' },
+    });
+});
+
+test('settingsDefaultsFromPackageSettings ignores non-object sources', () => {
+    for (const packageSettings of [null, undefined, [], 'settings']) {
+        assert.deepEqual(settingsDefaultsFromPackageSettings(packageSettings), {});
+    }
+});
+
+test('mergeMissingSettingsDefaults adds absent keys and keeps present values', () => {
+    const targetSettings = { advisorModel: null, permissions: { allow: ['Read'] } };
+
+    assert.deepEqual(
+        mergeMissingSettingsDefaults(targetSettings, {
+            advisorModel: 'fable',
+            theme: 'dark',
+        }),
+        { addedKeys: ['theme'] },
+    );
+    assert.deepEqual(targetSettings, {
+        advisorModel: null,
+        permissions: { allow: ['Read'] },
+        theme: 'dark',
+    });
+});

package/hooks/blocking/edit_marker_gate.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that keeps edit markers out of an edited chat message.
+
+The gate reads the whole input of a tool whose name ends in
+MESSAGE_EDIT_TOOL_SUFFIX, including the text and any replacement card. It
+denies the call when the input holds strikethrough or an "[Edit:" note. The
+reader of an edited message sees only its new text, so the model resends
+that clean text.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.edit_marker_gate_constants import (
+    ALLOW_EXIT_CODE,
+    BLOCK_EXIT_CODE,
+    EDIT_NOTE_MESSAGE,
+    EDIT_NOTE_PATTERN,
+    HOOK_EVENT_NAME,
+    MESSAGE_EDIT_TOOL_SUFFIX,
+    RETRY_INSTRUCTION,
+    STRIKETHROUGH_MESSAGE,
+    STRIKETHROUGH_PATTERN,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+)
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+
+
+def edit_marker_violation(all_tool_input: dict[str, object]) -> str | None:
+    """Return the deny reason for an edit that keeps old text, or None when clean."""
+    serialized_input = json.dumps(all_tool_input, ensure_ascii=False)
+    if STRIKETHROUGH_PATTERN.search(serialized_input):
+        return STRIKETHROUGH_MESSAGE
+    if EDIT_NOTE_PATTERN.search(serialized_input):
+        return EDIT_NOTE_MESSAGE
+    return None
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return ALLOW_EXIT_CODE
+    tool_name = hook_input.get(TOOL_NAME_KEY)
+    if not isinstance(tool_name, str) or not tool_name.endswith(MESSAGE_EDIT_TOOL_SUFFIX):
+        return ALLOW_EXIT_CODE
+    tool_input = hook_input.get(TOOL_INPUT_KEY)
+    if not isinstance(tool_input, dict):
+        return ALLOW_EXIT_CODE
+    violation = edit_marker_violation(tool_input)
+    if violation is None:
+        return ALLOW_EXIT_CODE
+    block_reason = violation + RETRY_INSTRUCTION
+    log_hook_block(
+        Path(__file__).name,
+        HOOK_EVENT_NAME,
+        block_reason,
+        tool_name=tool_name,
+        offending_input_preview=str(tool_input),
+    )
+    sys.stderr.write(block_reason)
+    return BLOCK_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())