twagent 2.2.1__tar.gz → 2.3.0__tar.gz

{twagent-2.2.1/src/twagent.egg-info → twagent-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: twagent
-Version: 2.2.1
+Version: 2.3.0
 Summary: twagent CLI
 Author-email: sysid <sysid@gmx.de>
 License-Expression: BSD-3-Clause

{twagent-2.2.1 → twagent-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "twagent"
-version = "2.2.1"
+version = "2.3.0"
 description = "twagent CLI"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -86,7 +86,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.2.1"
+current_version = "2.3.0"
 commit = true
 tag = false
 tag_name = "v{new_version}"

twagent-2.3.0/src/twagent/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.3.0"

{twagent-2.2.1 → twagent-2.3.0}/src/twagent/cli.py

@@ -387,7 +387,17 @@ def apply(
         f"[green]Applied[/green] ({mode}): {n_written} {label}, "
         f"{len(result.warnings)} warning(s), {len(result.errors)} error(s)."
     )
-    if n_written == 0 and not result.warnings and not result.errors:
+    if result.skipped_optional:
+        summary += (
+            f" {len(result.skipped_optional)} optional source(s) absent "
+            f"— run `twagent doctor` to list them."
+        )
+    if (
+        n_written == 0
+        and not result.warnings
+        and not result.errors
+        and not result.skipped_optional
+    ):
         summary = (
             f"[yellow]No-op[/yellow] ({mode}): nothing to deploy. "
             f"Check `twagent agents` for paths.project.* coverage, "

{twagent-2.2.1 → twagent-2.3.0}/src/twagent/config.py

@@ -23,7 +23,7 @@ from pathlib import Path
 from typing import Final, Literal, overload
 
 from twagent.interpolate import contains_variable_default
-from twagent.plugins import discover_plugin
+from twagent.plugins import PluginSourceMissing, discover_plugin
 
 logger = logging.getLogger(__name__)
 
@@ -87,6 +87,9 @@ class FileArtifact:
     name: str
     source: Path
     description: str | None = None
+    #: Declared absent on some machines. A missing source is then a silent
+    #: skip at deploy rather than an error (one config, many machines).
+    optional: bool = False
 
 
 @dataclass(frozen=True)
@@ -130,6 +133,12 @@ class Plugin:
     subagents: list[str] = field(default_factory=list)
     prompts: list[str] = field(default_factory=list)
     servers: list[str] = field(default_factory=list)
+    #: See FileArtifact.optional.
+    optional: bool = False
+    #: False when the source dir is absent on this machine. The name stays
+    #: registered (profile refs and --select must still resolve) but the
+    #: member lists are empty, so it contributes nothing to any expansion.
+    available: bool = True
 
 
 @dataclass(frozen=True)
@@ -240,10 +249,10 @@ def _build(raw: dict, base_dir: Path) -> Configuration:
 
     common = _build_common(raw.get("common", {}))
     agents = _build_agents(raw.get("agents", {}))
-    instructions = _build_artifacts(raw.get("instructions", {}))
-    skills = _build_artifacts(raw.get("skills", {}))
-    subagents = _build_artifacts(raw.get("subagents", {}))
-    prompts = _build_artifacts(raw.get("prompts", {}))
+    instructions = _build_artifacts("instructions", raw.get("instructions", {}))
+    skills = _build_artifacts("skills", raw.get("skills", {}))
+    subagents = _build_artifacts("subagents", raw.get("subagents", {}))
+    prompts = _build_artifacts("prompts", raw.get("prompts", {}))
     servers = _build_servers(raw.get("servers", {}))
     profiles = _build_profiles(raw.get("profiles", {}))
     plugins = _build_plugins(
@@ -326,17 +335,27 @@ def _build_paths_section(raw: dict) -> dict[str, list[Path]]:
     return {cap: [Path(p).expanduser() for p in paths] for cap, paths in raw.items()}
 
 
-def _build_artifacts(raw: dict) -> dict[str, FileArtifact]:
+def _build_artifacts(kind: str, raw: dict) -> dict[str, FileArtifact]:
+    for name, blob in raw.items():
+        _check_unknown_keys(f"{kind}.{name}", blob, _ARTIFACT_KEYS)
     return {
         name: FileArtifact(
             name=name,
-            source=Path(blob["source"]).expanduser(),
+            source=_require_source(f"{kind}.{name}", blob),
             description=blob.get("description"),
+            optional=bool(blob.get("optional", False)),
         )
         for name, blob in raw.items()
     }
 
 
+def _require_source(where: str, blob: dict) -> Path:
+    """Read the mandatory `source` key as a ConfigError, not a bare KeyError."""
+    if "source" not in blob:
+        raise ConfigError(f"{where}: missing required key 'source'")
+    return Path(blob["source"]).expanduser()
+
+
 def _build_server(name: str, blob: dict) -> Server:
     server = Server(
         name=name,
@@ -374,6 +393,10 @@ def _build_servers(raw: dict) -> dict[str, Server]:
 # Keys a [profiles.<name>] block may contain. A misspelled key (e.g.
 # `pluings`) was previously dropped silently — turning a typo into a silent
 # no-op. Reject unknown keys so the failure is loud, per fail-fast.
+_ARTIFACT_KEYS: Final[frozenset[str]] = frozenset({"source", "description", "optional"})
+
+_PLUGIN_KEYS: Final[frozenset[str]] = frozenset({"source", "description", "optional"})
+
 _PROFILE_KEYS: Final[frozenset[str]] = frozenset(
     {
         "description",
@@ -446,9 +469,33 @@ def _build_plugins(
     out: dict[str, Plugin] = {}
     for plugin_name in sorted(raw):
         blob = raw[plugin_name]
-        source = Path(blob["source"]).expanduser()
+        _check_unknown_keys(f"plugins.{plugin_name}", blob, _PLUGIN_KEYS)
+        source = _require_source(f"plugins.{plugin_name}", blob)
+        optional = bool(blob.get("optional", False))
         try:
             contents = discover_plugin(plugin_name, source)
+        except PluginSourceMissing as exc:
+            # The dir simply isn't on this machine. Register a placeholder so
+            # profile refs and --select still resolve, but inject nothing.
+            # A present-but-broken plugin still falls through to the hard
+            # error below — that's a real defect, not a machine difference.
+            out[plugin_name] = Plugin(
+                name=plugin_name,
+                source=source,
+                description=blob.get("description"),
+                optional=optional,
+                available=False,
+            )
+            if optional:
+                logger.debug(
+                    "config._build_plugins: %s optional and absent, skipped",
+                    plugin_name,
+                )
+            else:
+                warnings.warn(
+                    f"plugins.{plugin_name}: {exc}", UserWarning, stacklevel=3
+                )
+            continue
         except (FileNotFoundError, ValueError) as exc:
             raise ConfigError(f"plugins.{plugin_name}: {exc}")
 
@@ -468,6 +515,7 @@ def _build_plugins(
         out[plugin_name] = Plugin(
             name=plugin_name,
             source=source,
+            optional=optional,
             description=description,
             skills=skill_names,
             subagents=subagent_names,
@@ -662,7 +710,12 @@ def _validate_no_name_shadow(config: Configuration) -> None:
 
 
 def _check_artifact_sources(config: Configuration) -> None:
-    """Missing source = warning, not hard error (FR-005)."""
+    """Missing source = warning, not hard error (FR-005).
+
+    `optional = true` entries are exempt: they are declared absent on some
+    machines, so their absence is expected rather than a warning. `doctor`
+    reports them instead.
+    """
     logger.debug("config._check_artifact_sources: scanning registries")
     for registry, kind in (
         (config.instructions, "instructions"),
@@ -671,9 +724,17 @@ def _check_artifact_sources(config: Configuration) -> None:
         (config.prompts, "prompts"),
     ):
         for name, art in registry.items():
-            if not art.source.exists():
-                warnings.warn(
-                    f"{kind}.{name}: source does not exist: {art.source}",
-                    UserWarning,
-                    stacklevel=3,
+            if art.source.exists():
+                continue
+            if art.optional:
+                logger.debug(
+                    "config._check_artifact_sources: %s.%s optional and absent",
+                    kind,
+                    name,
                 )
+                continue
+            warnings.warn(
+                f"{kind}.{name}: source does not exist: {art.source}",
+                UserWarning,
+                stacklevel=3,
+            )

{twagent-2.2.1 → twagent-2.3.0}/src/twagent/deploy.py

@@ -62,6 +62,10 @@ class ApplyResult:
     warnings: list[str] = field(default_factory=list)
     errors: list[str] = field(default_factory=list)
     dry_run_log: list[str] = field(default_factory=list)
+    #: Distinct artifact names declared `optional = true` whose source is
+    #: absent on this machine — one entry per artifact, however many agents
+    #: wanted it. Expected, so deliberately NOT part of `has_errors`.
+    skipped_optional: list[str] = field(default_factory=list)
 
     @property
     def has_errors(self) -> bool:
@@ -538,7 +542,31 @@ def _deploy_file_artifacts(
             if ctx.dry_run:
                 result.dry_run_log.append(f"dedup {label}")
             logger.debug("deploy.dedup: %s", label)
-    sources = {name: registry[name].source for name in members if name in registry}
+    sources: dict[str, Path] = {}
+    for name in members:
+        art = registry.get(name)
+        if art is None:
+            continue
+        if art.optional and not art.source.exists():
+            # Leave it out of `sources` entirely: link_artifacts reaps target
+            # symlinks it doesn't see, which also clears a stale link synced
+            # in from a machine where this artifact did exist.
+            #
+            # Recorded by artifact name, not per agent/capability slot: one
+            # absent skill wanted by four agents is one absent source, and
+            # that is the count the summary line reports. The slot detail
+            # stays in the debug log.
+            if name not in result.skipped_optional:
+                result.skipped_optional.append(name)
+            logger.debug(
+                "deploy.optional_absent: %s/%s/%s (%s)",
+                agent.id,
+                capability,
+                name,
+                art.source,
+            )
+            continue
+        sources[name] = art.source
     for target_dir in targets:
         link_result = link_artifacts(sources, target_dir, dry_run=ctx.dry_run)
         for name in link_result.created + link_result.relinked:

{twagent-2.2.1 → twagent-2.3.0}/src/twagent/doctor.py

@@ -26,6 +26,7 @@ def check(config: Configuration) -> DoctorReport:
     logger.debug("doctor.check: starting")
     report = DoctorReport()
     _check_artifact_sources(config, report)
+    _check_plugin_sources(config, report)
     _check_dangling_symlinks(config, report)
     _check_capability_mismatches(config, report)
     _check_agents_without_global_profile(config, report)
@@ -46,12 +47,40 @@ def _check_artifact_sources(config: Configuration, report: DoctorReport) -> None
         ("prompts", config.prompts),
     ):
         for name, art in registry.items():
-            if not art.source.exists():
+            if art.source.exists():
+                continue
+            if art.optional:
+                report.info.append(
+                    f"{kind}.{name}: expected absent on this machine "
+                    f"(optional): {art.source}"
+                )
+            else:
                 report.errors.append(
                     f"{kind}.{name}: source does not exist: {art.source}"
                 )
 
 
+def _check_plugin_sources(config: Configuration, report: DoctorReport) -> None:
+    """Plugins whose source dir isn't on this machine.
+
+    `_build_plugins` degrades these to placeholders so the config still
+    loads; doctor is where they surface.
+    """
+    logger.debug("doctor._check_plugin_sources")
+    for name, plugin in config.plugins.items():
+        if plugin.available:
+            continue
+        if plugin.optional:
+            report.info.append(
+                f"plugins.{name}: expected absent on this machine "
+                f"(optional): {plugin.source}"
+            )
+        else:
+            report.errors.append(
+                f"plugins.{name}: source dir does not exist: {plugin.source}"
+            )
+
+
 def _check_dangling_symlinks(config: Configuration, report: DoctorReport) -> None:
     """Walk every per-agent capability directory and warn on dangling links."""
     logger.debug("doctor._check_dangling_symlinks")

{twagent-2.2.1 → twagent-2.3.0}/src/twagent/plugins.py

@@ -20,6 +20,16 @@ from pathlib import Path
 logger = logging.getLogger(__name__)
 
 
+class PluginSourceMissing(FileNotFoundError):
+    """The plugin's source directory is not present on this machine.
+
+    Distinct from a present-but-broken plugin: an absent directory is the
+    expected case when one canonical config is shared across machines that
+    don't all check out the same repos. config.py degrades these to a
+    placeholder instead of failing the whole load.
+    """
+
+
 @dataclass(frozen=True)
 class PluginContents:
     """Pieces discovered in one plugin, keyed by on-disk basename.
@@ -41,10 +51,14 @@ class PluginContents:
 def discover_plugin(name: str, source: Path) -> PluginContents:
     """Parse `<source>/plugin.json` and discover all declared pieces.
 
-    Raises FileNotFoundError if the source dir or plugin.json is missing,
-    ValueError if the manifest is malformed or declares a non-existent dir.
+    Raises PluginSourceMissing if the source dir itself is absent (the
+    machine simply doesn't have it), plain FileNotFoundError if the dir is
+    there but holds no plugin.json, and ValueError if the manifest is
+    malformed or declares a non-existent dir.
     """
     logger.debug("plugins.discover_plugin: name=%s source=%s", name, source)
+    if not source.is_dir():
+        raise PluginSourceMissing(f"plugin {name!r}: source dir not found: {source}")
     manifest_path = source / "plugin.json"
     if not manifest_path.exists():
         raise FileNotFoundError(f"plugin {name!r}: no plugin.json at {manifest_path}")

{twagent-2.2.1 → twagent-2.3.0}/src/twagent/selector.py

@@ -17,7 +17,7 @@ from typing import TYPE_CHECKING
 
 from simple_term_menu import TerminalMenu
 
-from twagent.config import EXPANSION_KINDS, ProfileExpansion
+from twagent.config import EXPANSION_KINDS, FileArtifact, ProfileExpansion
 from twagent.expansion import expand_profile
 
 if TYPE_CHECKING:
@@ -118,12 +118,32 @@ def resolve_selection(names: list[str], config: "Configuration") -> ProfileExpan
                         buckets[kind].append(m)
         elif name in config.plugins:
             plugin = config.plugins[name]
+            if not plugin.available:
+                # Selected by name, so silence would be wrong even when the
+                # entry is marked optional — the user asked for this thing.
+                logger.warning(
+                    "--select %s: plugin source not on this machine (%s); "
+                    "it contributes nothing",
+                    name,
+                    plugin.source,
+                )
             for kind in buckets:
                 for m in getattr(plugin, kind, []):
                     if m not in buckets[kind]:
                         buckets[kind].append(m)
         elif name in artifact_kind_of:
             kind = artifact_kind_of[name]
+            art = config.registry(kind)[name]
+            if (
+                isinstance(art, FileArtifact)
+                and art.optional
+                and not art.source.exists()
+            ):
+                logger.warning(
+                    "--select %s: source not on this machine (%s); it will be skipped",
+                    name,
+                    art.source,
+                )
             if name not in buckets[kind]:
                 buckets[kind].append(name)
         else:

{twagent-2.2.1 → twagent-2.3.0/src/twagent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: twagent
-Version: 2.2.1
+Version: 2.3.0
 Summary: twagent CLI
 Author-email: sysid <sysid@gmx.de>
 License-Expression: BSD-3-Clause

{twagent-2.2.1 → twagent-2.3.0}/tests/test_config.py

@@ -4,6 +4,8 @@ Schema v2: scopes are gone. Global deployment is per-agent `global_profile`.
 Polymorphic --select forces a name-shadow validation rule across registries.
 """
 
+import warnings
+
 import pytest
 
 from twagent.config import (
@@ -12,6 +14,7 @@ from twagent.config import (
     ConfigError,
     load,
 )
+from twagent.expansion import expand_profile
 
 # ─── Helpers ────────────────────────────────────────────────────────────
 
@@ -565,14 +568,118 @@ source = "{FIXTURE_PLUGINS / "beta"}"
         _write_config(tmp_path, body)
 
 
-def test_plugin_missing_source_dir_is_hard_error(tmp_path):
+def test_plugin_missing_source_dir_warns_and_degrades(tmp_path):
+    """One config, many machines: an absent plugin dir must not brick load."""
+    body = f"""\
+schema_version = 3
+
+[plugins.ghost]
+source = "{tmp_path / "nonexistent"}"
+"""
+    with pytest.warns(UserWarning, match="ghost"):
+        config = _write_config(tmp_path, body)
+    assert config.plugins["ghost"].available is False
+    assert config.plugins["ghost"].optional is False
+    assert config.plugins["ghost"].skills == []
+
+
+def test_plugin_missing_source_dir_optional_is_silent(tmp_path):
+    body = f"""\
+schema_version = 3
+
+[plugins.ghost]
+source = "{tmp_path / "nonexistent"}"
+optional = true
+"""
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        config = _write_config(tmp_path, body)
+    assert config.plugins["ghost"].available is False
+    assert config.plugins["ghost"].optional is True
+
+
+def test_plugin_dir_present_but_no_manifest_is_still_hard_error(tmp_path):
+    """A broken plugin is a real defect, not a machine difference."""
+    (tmp_path / "broken").mkdir()
+    body = f"""\
+schema_version = 3
+
+[plugins.broken]
+source = "{tmp_path / "broken"}"
+"""
+    with pytest.raises(ConfigError, match="broken"):
+        _write_config(tmp_path, body)
+
+
+def test_plugin_dir_present_but_malformed_manifest_is_hard_error(tmp_path):
+    (tmp_path / "broken").mkdir()
+    (tmp_path / "broken" / "plugin.json").write_text("{not json")
+    body = f"""\
+schema_version = 3
+
+[plugins.broken]
+source = "{tmp_path / "broken"}"
+"""
+    with pytest.raises(ConfigError, match="cannot parse"):
+        _write_config(tmp_path, body)
+
+
+def test_profile_referencing_degraded_plugin_still_validates(tmp_path):
+    """Name stays registered, so profile refs and expansion keep working."""
     body = f"""\
 schema_version = 3
 
 [plugins.ghost]
 source = "{tmp_path / "nonexistent"}"
+optional = true
+
+[profiles.p]
+plugins = ["ghost"]
 """
-    with pytest.raises(ConfigError, match="ghost"):
+    config = _write_config(tmp_path, body)
+    expanded = expand_profile(config, "p")
+    assert expanded.skills == []
+    assert expanded.servers == []
+
+
+def test_optional_artifact_missing_source_does_not_warn(tmp_path):
+    body = (
+        MINIMAL_OK
+        + """
+[skills.s]
+source = "/nonexistent/path"
+optional = true
+"""
+    )
+    body = body.replace("[profiles.empty]\n", '[profiles.empty]\nskills = ["s"]\n')
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        config = _write_config(tmp_path, body)
+    assert config.skills["s"].optional is True
+
+
+def test_artifact_unknown_key_is_rejected_with_suggestion(tmp_path):
+    body = (
+        MINIMAL_OK
+        + """
+[skills.s]
+source = "/nonexistent/path"
+optinal = true
+"""
+    )
+    with pytest.raises(ConfigError, match="optinal.*did you mean 'optional'"):
+        _write_config(tmp_path, body)
+
+
+def test_artifact_missing_source_key_is_config_error(tmp_path):
+    body = (
+        MINIMAL_OK
+        + """
+[skills.s]
+description = "no source"
+"""
+    )
+    with pytest.raises(ConfigError, match="skills.s: missing required key 'source'"):
         _write_config(tmp_path, body)
 
 

twagent-2.3.0/tests/test_deploy_plugins.py

@@ -0,0 +1,222 @@
+"""Integration: a plugin-bearing profile deploys + reaps via the existing
+deploy machinery (Task 8). No production deploy code changes — if these pass,
+the "zero deploy changes" design claim holds.
+"""
+
+import textwrap
+import warnings
+from pathlib import Path
+
+from twagent.config import load
+from twagent.deploy import apply_here
+
+FIXTURE_PLUGINS = Path(__file__).parent / "fixtures" / "plugins"
+
+
+def _setup(tmp_path: Path):
+    """A config with one agent, the alpha plugin, and a plain `keeper` skill.
+
+    Profile `p` pulls the plugin atomically; profile `q` engages the skills
+    capability with a non-plugin skill, so switching p -> q exercises orphan
+    reaping of the plugin's deployed skill.
+    """
+    keeper = tmp_path / "keeper_skill"
+    keeper.mkdir()
+    (keeper / "SKILL.md").write_text("---\ndescription: keeper skill\n---\n")
+
+    cfg = tmp_path / "config.toml"
+    cfg.write_text(
+        textwrap.dedent(
+            f"""\
+            schema_version = 3
+
+            [agents.claude-code]
+            capabilities = ["skills", "subagents"]
+
+            [agents.claude-code.paths.global]
+            skills = ["~/.claude/skills"]
+            subagents = ["~/.claude/agents"]
+
+            [agents.claude-code.paths.project]
+            skills = [".claude/skills"]
+            subagents = [".claude/agents"]
+
+            [skills.keeper]
+            source = "{keeper}"
+
+            [plugins.alpha]
+            source = "{FIXTURE_PLUGINS / "alpha"}"
+
+            [profiles.p]
+            plugins = ["alpha"]
+
+            [profiles.q]
+            skills = ["keeper"]
+            """
+        )
+    )
+    return load(cfg)
+
+
+def test_apply_here_symlinks_plugin_pieces(tmp_path):
+    config = _setup(tmp_path)
+    cwd = tmp_path / "work"
+    cwd.mkdir()
+
+    apply_here(config, cwd, select=["p"])
+
+    assert (cwd / ".claude" / "skills" / "greet").is_symlink()
+    assert (cwd / ".claude" / "agents" / "helper.agent.md").is_symlink()
+
+
+def test_switching_profile_reaps_plugin_skill(tmp_path):
+    config = _setup(tmp_path)
+    cwd = tmp_path / "work"
+    cwd.mkdir()
+
+    apply_here(config, cwd, select=["p"])
+    assert (cwd / ".claude" / "skills" / "greet").is_symlink()
+
+    # Switch to a profile that still engages the skills capability but does
+    # not include the plugin: the plugin's skill is reaped as an orphan.
+    apply_here(config, cwd, select=["q"])
+    assert not (cwd / ".claude" / "skills" / "greet").exists()
+    assert (cwd / ".claude" / "skills" / "keeper").is_symlink()
+
+
+# ─── portability: sources absent on this machine ────────────────────────
+
+
+def _setup_optional(tmp_path: Path, *, optional: bool):
+    """`keeper` exists; `workonly` and plugin `ghost` point nowhere.
+
+    Mirrors one canonical config synced to a machine that doesn't check out
+    the work repos.
+    """
+    keeper = tmp_path / "keeper_skill"
+    keeper.mkdir()
+    (keeper / "SKILL.md").write_text("---\ndescription: keeper skill\n---\n")
+
+    flag = "\noptional = true" if optional else ""
+    cfg = tmp_path / "config.toml"
+    cfg.write_text(
+        textwrap.dedent(
+            f"""\
+            schema_version = 3
+
+            [agents.claude-code]
+            capabilities = ["skills"]
+
+            [agents.claude-code.paths.global]
+            skills = ["~/.claude/skills"]
+
+            [agents.claude-code.paths.project]
+            skills = [".claude/skills"]
+
+            [skills.keeper]
+            source = "{keeper}"
+
+            [skills.workonly]
+            source = "{tmp_path / "nope"}"{flag}
+
+            [plugins.ghost]
+            source = "{tmp_path / "no-plugin"}"{flag}
+
+            [profiles.p]
+            skills = ["keeper", "workonly"]
+            plugins = ["ghost"]
+            """
+        )
+    )
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        return load(cfg)
+
+
+def test_optional_absent_source_is_skipped_not_an_error(tmp_path):
+    config = _setup_optional(tmp_path, optional=True)
+    cwd = tmp_path / "work"
+    cwd.mkdir()
+
+    result = apply_here(config, cwd, select=["p"])
+
+    assert not result.has_errors
+    assert any("workonly" in s for s in result.skipped_optional)
+    assert (cwd / ".claude" / "skills" / "keeper").is_symlink()
+    assert not (cwd / ".claude" / "skills" / "workonly").exists()
+
+
+def test_non_optional_absent_source_still_errors(tmp_path):
+    config = _setup_optional(tmp_path, optional=False)
+    cwd = tmp_path / "work"
+    cwd.mkdir()
+
+    result = apply_here(config, cwd, select=["p"])
+
+    assert result.has_errors
+    assert any("workonly" in e for e in result.errors)
+    assert result.skipped_optional == []
+
+
+def test_optional_absent_source_reaps_stale_symlink(tmp_path):
+    """A broken link synced in from the machine where it did exist."""
+    config = _setup_optional(tmp_path, optional=True)
+    cwd = tmp_path / "work"
+    target = cwd / ".claude" / "skills"
+    target.mkdir(parents=True)
+    (target / "workonly").symlink_to(tmp_path / "gone-with-the-other-machine")
+
+    apply_here(config, cwd, select=["p"])
+
+    assert not (target / "workonly").is_symlink()
+
+
+def test_optional_skips_are_counted_per_artifact_not_per_agent(tmp_path):
+    """One absent skill wanted by three agents is ONE absent source.
+
+    The summary line reports what the user thinks in — artifacts — not the
+    agent x capability slots the deploy loop happens to iterate.
+    """
+    cfg = tmp_path / "config.toml"
+    cfg.write_text(
+        textwrap.dedent(
+            f"""\
+            schema_version = 3
+
+            [agents.a]
+            capabilities = ["skills"]
+            [agents.a.paths.global]
+            skills = ["~/.a/skills"]
+            [agents.a.paths.project]
+            skills = [".a/skills"]
+
+            [agents.b]
+            capabilities = ["skills"]
+            [agents.b.paths.global]
+            skills = ["~/.b/skills"]
+            [agents.b.paths.project]
+            skills = [".b/skills"]
+
+            [agents.c]
+            capabilities = ["skills"]
+            [agents.c.paths.global]
+            skills = ["~/.c/skills"]
+            [agents.c.paths.project]
+            skills = [".c/skills"]
+
+            [skills.workonly]
+            source = "{tmp_path / "nope"}"
+            optional = true
+
+            [profiles.p]
+            skills = ["workonly"]
+            """
+        )
+    )
+    config = load(cfg)
+    cwd = tmp_path / "work"
+    cwd.mkdir()
+
+    result = apply_here(config, cwd, select=["p"])
+
+    assert result.skipped_optional == ["workonly"]

{twagent-2.2.1 → twagent-2.3.0}/tests/test_doctor.py

@@ -1,5 +1,6 @@
 """US3: doctor reports introduced failures + clean state passes (v2)."""
 
+import warnings
 from pathlib import Path
 
 import pytest
@@ -106,3 +107,46 @@ subagents = ["reviewer"]
         config = load(config_path)
     report = check(config)
     assert any("subagents" in i and "lacks" in i for i in report.info)
+
+
+# ─── portability: doctor is where per-machine gaps surface ──────────────
+
+
+def _portable_config(tmp_path, *, optional: bool):
+    flag = "\noptional = true" if optional else ""
+    config_path = tmp_path / "config.toml"
+    config_path.write_text(
+        f"""\
+schema_version = 3
+[skills.workonly]
+source = "{tmp_path / "nope"}"{flag}
+[plugins.ghost]
+source = "{tmp_path / "no-plugin"}"{flag}
+[profiles.p]
+skills = ["workonly"]
+plugins = ["ghost"]
+"""
+    )
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        return load(config_path)
+
+
+def test_optional_absent_sources_are_info_not_errors(tmp_path):
+    report = check(_portable_config(tmp_path, optional=True))
+    assert not report.has_errors
+    assert any("skills.workonly" in i and "expected absent" in i for i in report.info)
+    assert any("plugins.ghost" in i and "expected absent" in i for i in report.info)
+
+
+def test_non_optional_absent_sources_are_errors(tmp_path):
+    report = check(_portable_config(tmp_path, optional=False))
+    assert report.has_errors
+    assert any("skills.workonly" in e for e in report.errors)
+    assert any("plugins.ghost" in e for e in report.errors)
+
+
+def test_doctor_loads_despite_absent_plugin_dir(tmp_path):
+    """Regression: an absent plugin dir used to make doctor itself unusable."""
+    report = check(_portable_config(tmp_path, optional=True))
+    assert report.info  # it ran at all

{twagent-2.2.1 → twagent-2.3.0}/tests/test_plugins.py

@@ -2,7 +2,7 @@ from pathlib import Path
 
 import pytest
 
-from twagent.plugins import PluginContents, discover_plugin
+from twagent.plugins import PluginContents, PluginSourceMissing, discover_plugin
 
 FIXTURES = Path(__file__).parent / "fixtures" / "plugins"
 
@@ -32,11 +32,19 @@ def test_discover_plugin_reads_all_kinds_from_manifest():
     assert contents.servers["alpha-server"]["command"] == "echo"
 
 
-def test_discover_plugin_missing_manifest_raises():
-    with pytest.raises(FileNotFoundError):
+def test_discover_plugin_absent_source_dir_raises_source_missing():
+    """Absent dir is its own error: config degrades it instead of failing."""
+    with pytest.raises(PluginSourceMissing):
         discover_plugin("nope", FIXTURES / "does-not-exist")
 
 
+def test_discover_plugin_missing_manifest_raises(tmp_path):
+    """Dir present but no plugin.json — broken, NOT PluginSourceMissing."""
+    with pytest.raises(FileNotFoundError) as exc:
+        discover_plugin("nope", tmp_path)
+    assert not isinstance(exc.value, PluginSourceMissing)
+
+
 def test_discover_plugin_declared_dir_absent_raises(tmp_path):
     (tmp_path / "plugin.json").write_text('{"name": "x", "skills": "skills/"}')
     with pytest.raises(ValueError, match="declares skills dir"):

{twagent-2.2.1 → twagent-2.3.0}/tests/test_selector.py

@@ -1,5 +1,7 @@
 """US5: selection across all four list-shaped artifact types + polymorphic --select."""
 
+import logging
+import warnings
 from types import SimpleNamespace
 
 import pytest
@@ -336,3 +338,41 @@ class TestResolveSelectionPlugins:
         config = self._config_with_plugin()
         with pytest.raises(ValueError, match="Unknown name"):
             resolve_selection(["nope"], config)
+
+
+# ─── portability: naming an absent thing explicitly stays loud ───────────
+
+
+def _absent_config(tmp_path):
+    config_path = tmp_path / "config.toml"
+    config_path.write_text(
+        f"""\
+schema_version = 3
+[skills.workonly]
+source = "{tmp_path / "nope"}"
+optional = true
+[plugins.ghost]
+source = "{tmp_path / "no-plugin"}"
+optional = true
+[profiles.p]
+"""
+    )
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+        return load(config_path)
+
+
+def test_select_absent_optional_skill_warns(tmp_path, caplog):
+    config = _absent_config(tmp_path)
+    with caplog.at_level(logging.WARNING):
+        expanded = resolve_selection(["workonly"], config)
+    assert expanded.skills == ["workonly"]
+    assert "not on this machine" in caplog.text
+
+
+def test_select_degraded_plugin_warns(tmp_path, caplog):
+    config = _absent_config(tmp_path)
+    with caplog.at_level(logging.WARNING):
+        expanded = resolve_selection(["ghost"], config)
+    assert expanded.skills == []
+    assert "not on this machine" in caplog.text

twagent-2.2.1/src/twagent/__init__.py

@@ -1 +0,0 @@
-__version__ = "2.2.1"

twagent-2.2.1/tests/test_deploy_plugins.py

@@ -1,83 +0,0 @@
-"""Integration: a plugin-bearing profile deploys + reaps via the existing
-deploy machinery (Task 8). No production deploy code changes — if these pass,
-the "zero deploy changes" design claim holds.
-"""
-
-import textwrap
-from pathlib import Path
-
-from twagent.config import load
-from twagent.deploy import apply_here
-
-FIXTURE_PLUGINS = Path(__file__).parent / "fixtures" / "plugins"
-
-
-def _setup(tmp_path: Path):
-    """A config with one agent, the alpha plugin, and a plain `keeper` skill.
-
-    Profile `p` pulls the plugin atomically; profile `q` engages the skills
-    capability with a non-plugin skill, so switching p -> q exercises orphan
-    reaping of the plugin's deployed skill.
-    """
-    keeper = tmp_path / "keeper_skill"
-    keeper.mkdir()
-    (keeper / "SKILL.md").write_text("---\ndescription: keeper skill\n---\n")
-
-    cfg = tmp_path / "config.toml"
-    cfg.write_text(
-        textwrap.dedent(
-            f"""\
-            schema_version = 3
-
-            [agents.claude-code]
-            capabilities = ["skills", "subagents"]
-
-            [agents.claude-code.paths.global]
-            skills = ["~/.claude/skills"]
-            subagents = ["~/.claude/agents"]
-
-            [agents.claude-code.paths.project]
-            skills = [".claude/skills"]
-            subagents = [".claude/agents"]
-
-            [skills.keeper]
-            source = "{keeper}"
-
-            [plugins.alpha]
-            source = "{FIXTURE_PLUGINS / "alpha"}"
-
-            [profiles.p]
-            plugins = ["alpha"]
-
-            [profiles.q]
-            skills = ["keeper"]
-            """
-        )
-    )
-    return load(cfg)
-
-
-def test_apply_here_symlinks_plugin_pieces(tmp_path):
-    config = _setup(tmp_path)
-    cwd = tmp_path / "work"
-    cwd.mkdir()
-
-    apply_here(config, cwd, select=["p"])
-
-    assert (cwd / ".claude" / "skills" / "greet").is_symlink()
-    assert (cwd / ".claude" / "agents" / "helper.agent.md").is_symlink()
-
-
-def test_switching_profile_reaps_plugin_skill(tmp_path):
-    config = _setup(tmp_path)
-    cwd = tmp_path / "work"
-    cwd.mkdir()
-
-    apply_here(config, cwd, select=["p"])
-    assert (cwd / ".claude" / "skills" / "greet").is_symlink()
-
-    # Switch to a profile that still engages the skills capability but does
-    # not include the plugin: the plugin's skill is reaped as an orphan.
-    apply_here(config, cwd, select=["q"])
-    assert not (cwd / ".claude" / "skills" / "greet").exists()
-    assert (cwd / ".claude" / "skills" / "keeper").is_symlink()