agent-codinglanguage-mapper 1.1.0__tar.gz → 1.1.1__tar.gz

{agent_codinglanguage_mapper-1.1.0 → agent_codinglanguage_mapper-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-codinglanguage-mapper
-Version: 1.1.0
+Version: 1.1.1
 Summary: Agent-focused semantic mapping and language services for mixed-language codebases.
 Author: Dark Light
 License-Expression: MPL-2.0
@@ -319,40 +319,37 @@ Example generic client configuration:
 
 ## OpenCode Integration
 
-Install the packaged skill, plugin, and restricted agent configuration into a repository:
+Install the package-named skill, Markdown agent, and plugin into a repository:
 
 ```bash
-codinglanguage-mapper opencode install --target . --write
+codinglanguage-mapper opencode install --target .
 ```
 
 This creates:
 
 ```text
-.agents/skills/mixed-codebase-navigator/SKILL.md
+.agents/skills/agent-codinglanguage-mapper/SKILL.md
+.opencode/agents/agent-codinglanguage-mapper.md
 .opencode/plugins/codebase_map.ts
-opencode.json
 ```
 
-The generated `mixed-codebase-navigator` agent denies all tools by default and permits only `skill`, `codebase_map`, and `code_guidelines`. The plugin maps the active OpenCode directory, serializes Protocol 3 requests through one worker, applies a hard timeout, reports bounded worker `stderr`, restarts after failure, and preserves focus plus warm parser indexes across short idle gaps. It stops the worker when the session is deleted or after 60 seconds without another mapper request.
+The generated `agent-codinglanguage-mapper` agent denies all tools by default and permits only its package-named skill, `codebase_map`, and `code_guidelines`. The plugin maps the active OpenCode directory, serializes Protocol 3 requests through one worker, applies a hard timeout, reports bounded worker `stderr`, restarts after failure, and preserves focus plus warm parser indexes across short idle gaps. It stops the worker when the session is deleted or after 60 seconds without another mapper request.
+
+The installer never reads or changes `opencode.json`; user configuration remains
+user-owned. The deprecated `--write`, `--write-config`, and `--write-agent`
+compatibility flags are accepted, but the Markdown agent is installed by
+default and those flags do not enable configuration writes.
 
 `code_guidelines` exposes four actions: `detect`, `audit`, `patch`, and `apply`. The first three are read-only. `apply` is rejected unless its request contains `write: true`, so the agent must inspect a patch before it can opt into mutation.
 
-```json
-{
-  "permission": {
-    "*": "deny",
-    "skill": "allow",
-    "codebase_map": "allow",
-    "code_guidelines": "allow"
-  }
-}
-```
+The agent's YAML frontmatter contains its restricted permissions; no matching
+JSON agent block is required.
 
 Run it with:
 
 ```bash
 opencode run \
-  --agent mixed-codebase-navigator \
+  --agent agent-codinglanguage-mapper \
   "Find PaymentService, inspect its implementation, and cite the callers. Use only the installed skill and codebase_map."
 ```
 

{agent_codinglanguage_mapper-1.1.0 → agent_codinglanguage_mapper-1.1.1}/README.md

@@ -272,40 +272,37 @@ Example generic client configuration:
 
 ## OpenCode Integration
 
-Install the packaged skill, plugin, and restricted agent configuration into a repository:
+Install the package-named skill, Markdown agent, and plugin into a repository:
 
 ```bash
-codinglanguage-mapper opencode install --target . --write
+codinglanguage-mapper opencode install --target .
 ```
 
 This creates:
 
 ```text
-.agents/skills/mixed-codebase-navigator/SKILL.md
+.agents/skills/agent-codinglanguage-mapper/SKILL.md
+.opencode/agents/agent-codinglanguage-mapper.md
 .opencode/plugins/codebase_map.ts
-opencode.json
 ```
 
-The generated `mixed-codebase-navigator` agent denies all tools by default and permits only `skill`, `codebase_map`, and `code_guidelines`. The plugin maps the active OpenCode directory, serializes Protocol 3 requests through one worker, applies a hard timeout, reports bounded worker `stderr`, restarts after failure, and preserves focus plus warm parser indexes across short idle gaps. It stops the worker when the session is deleted or after 60 seconds without another mapper request.
+The generated `agent-codinglanguage-mapper` agent denies all tools by default and permits only its package-named skill, `codebase_map`, and `code_guidelines`. The plugin maps the active OpenCode directory, serializes Protocol 3 requests through one worker, applies a hard timeout, reports bounded worker `stderr`, restarts after failure, and preserves focus plus warm parser indexes across short idle gaps. It stops the worker when the session is deleted or after 60 seconds without another mapper request.
+
+The installer never reads or changes `opencode.json`; user configuration remains
+user-owned. The deprecated `--write`, `--write-config`, and `--write-agent`
+compatibility flags are accepted, but the Markdown agent is installed by
+default and those flags do not enable configuration writes.
 
 `code_guidelines` exposes four actions: `detect`, `audit`, `patch`, and `apply`. The first three are read-only. `apply` is rejected unless its request contains `write: true`, so the agent must inspect a patch before it can opt into mutation.
 
-```json
-{
-  "permission": {
-    "*": "deny",
-    "skill": "allow",
-    "codebase_map": "allow",
-    "code_guidelines": "allow"
-  }
-}
-```
+The agent's YAML frontmatter contains its restricted permissions; no matching
+JSON agent block is required.
 
 Run it with:
 
 ```bash
 opencode run \
-  --agent mixed-codebase-navigator \
+  --agent agent-codinglanguage-mapper \
   "Find PaymentService, inspect its implementation, and cite the callers. Use only the installed skill and codebase_map."
 ```
 

{agent_codinglanguage_mapper-1.1.0 → agent_codinglanguage_mapper-1.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-codinglanguage-mapper"
-version = "1.1.0"
+version = "1.1.1"
 description = "Agent-focused semantic mapping and language services for mixed-language codebases."
 readme = "README.md"
 requires-python = ">=3.10,<3.15"

agent_codinglanguage_mapper-1.1.1/src/agent_codinglanguage_mapper/_version.py

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

{agent_codinglanguage_mapper-1.1.0 → agent_codinglanguage_mapper-1.1.1}/src/agent_codinglanguage_mapper/cli.py

@@ -84,7 +84,14 @@ def build_parser() -> argparse.ArgumentParser:
     opencode_install.add_argument("--target", type=Path, default=Path("."))
     opencode_install.add_argument("--python", default=sys.executable)
     opencode_install.add_argument("--force", action="store_true")
-    opencode_install.add_argument("--write", "--write-config", dest="write_config", action="store_true")
+    opencode_install.add_argument(
+        "--write-agent",
+        "--write",
+        "--write-config",
+        dest="write_config",
+        action="store_true",
+        help="deprecated compatibility flag; the Markdown agent is always installed",
+    )
     return parser
 
 

agent_codinglanguage_mapper-1.1.1/src/agent_codinglanguage_mapper/integration.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import stat
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Final
+
+PACKAGE_NAME: Final[str] = "agent-codinglanguage-mapper"
+
+SKILL_RELATIVE_PATH: Final[Path] = Path(
+    f".agents/skills/{PACKAGE_NAME}/SKILL.md"
+)
+LEGACY_SKILL_RELATIVE_PATH: Final[Path] = Path(
+    ".agents/skills/mixed-codebase-navigator/SKILL.md"
+)
+LEGACY_SKILL_SHA256: Final[str] = (
+    "bbacc23782ca97e54b2f65ddea9fb1bf816f23397dc8572e3d1ef7a60e2709d4"
+)
+OPENCODE_PLUGIN_RELATIVE_PATH: Final[Path] = Path(".opencode/plugins/codebase_map.ts")
+OPENCODE_AGENT_RELATIVE_PATH: Final[Path] = Path(
+    f".opencode/agents/{PACKAGE_NAME}.md"
+)
+
+SKILL_TEMPLATE_PATH: Final[Path] = Path("skill", "SKILL.md")
+OPENCODE_PLUGIN_TEMPLATE_PATH: Final[Path] = Path("opencode", "plugins", "codebase_map.ts")
+OPENCODE_AGENT_TEMPLATE_PATH: Final[Path] = Path(
+    "opencode", "agents", f"{PACKAGE_NAME}.md"
+)
+_TEMPLATES_ROOT: Final[Path] = Path(__file__).resolve().parent / "templates"
+
+
+def install_skill(target: Path, force: bool = False) -> Path:
+    target_root = _normalize_target(target)
+    legacy_path = _preflight_legacy_skill(target_root, force=force)
+    skill_path = _safe_join(target_root, SKILL_RELATIVE_PATH)
+    _preflight_overwrite((skill_path,), force=force)
+    snapshots = _snapshots(skill_path, legacy_path)
+    try:
+        _write_atomic_text(skill_path, _load_template(SKILL_TEMPLATE_PATH), force=True)
+        _remove_legacy_skill(legacy_path)
+    except BaseException:
+        _restore_snapshots(snapshots)
+        raise
+    return skill_path
+
+
+def install_opencode(
+    target: Path,
+    python_executable: str | os.PathLike[str],
+    force: bool = False,
+    write_config: bool = False,
+) -> tuple[Path, Path, Path]:
+    target_root = _normalize_target(target)
+    legacy_path = _preflight_legacy_skill(target_root, force=force)
+    skill_path = _safe_join(target_root, SKILL_RELATIVE_PATH)
+    plugin_path = _safe_join(target_root, OPENCODE_PLUGIN_RELATIVE_PATH)
+    agent_path = _safe_join(target_root, OPENCODE_AGENT_RELATIVE_PATH)
+    _preflight_overwrite((skill_path, plugin_path, agent_path), force=force)
+    rendered_skill = _load_template(SKILL_TEMPLATE_PATH)
+    rendered_plugin = _render_plugin(str(python_executable))
+    rendered_agent = _load_template(OPENCODE_AGENT_TEMPLATE_PATH)
+    snapshots = _snapshots(skill_path, plugin_path, agent_path, legacy_path)
+
+    try:
+        _write_atomic_text(skill_path, rendered_skill, force=True)
+        _write_atomic_text(plugin_path, rendered_plugin, force=True)
+        _write_atomic_text(agent_path, rendered_agent, force=True)
+        _remove_legacy_skill(legacy_path)
+    except BaseException:
+        _restore_snapshots(snapshots)
+        raise
+    _ = write_config  # Deprecated compatibility input; user configuration is never touched.
+    return skill_path, plugin_path, agent_path
+
+
+def _preflight_legacy_skill(target: Path, *, force: bool) -> Path | None:
+    legacy_path = target / LEGACY_SKILL_RELATIVE_PATH
+    legacy_path.relative_to(target)
+    _reject_symlink_components(legacy_path, target)
+    if not legacy_path.exists():
+        return None
+    if not legacy_path.is_file():
+        raise FileExistsError(f"Legacy skill path is not a file: {legacy_path}")
+    digest = hashlib.sha256(legacy_path.read_bytes()).hexdigest()
+    if digest != LEGACY_SKILL_SHA256 and not force:
+        raise FileExistsError(
+            f"Refusing to remove modified legacy skill without force: {legacy_path}"
+        )
+    return legacy_path
+
+
+def _remove_legacy_skill(path: Path | None) -> None:
+    if path is None:
+        return
+    path.unlink()
+    try:
+        path.parent.rmdir()
+    except OSError:
+        pass
+
+
+def _normalize_target(target: Path) -> Path:
+    normalized = target.expanduser().resolve()
+    if normalized.exists() and not normalized.is_dir():
+        raise NotADirectoryError(f"Target must be a directory: {normalized}")
+    normalized.mkdir(parents=True, exist_ok=True)
+    return normalized
+
+
+def _safe_join(target: Path, relative: Path) -> Path:
+    destination = target / relative
+    destination.relative_to(target)
+    _reject_symlink_components(destination, target)
+    return destination
+
+
+def _reject_symlink_components(path: Path, target: Path) -> None:
+    current = path
+    while current != target:
+        if current.is_symlink():
+            raise FileExistsError(f"Generated path must not contain a symbolic link: {current}")
+        current = current.parent
+
+
+def _preflight_overwrite(paths: tuple[Path, ...], *, force: bool) -> None:
+    for path in paths:
+        if path.is_symlink():
+            raise FileExistsError(f"Refusing to replace symbolic link: {path}")
+        if path.exists() and not path.is_file():
+            raise FileExistsError(f"Generated destination is not a file: {path}")
+        if path.exists() and not force:
+            raise FileExistsError(f"Refusing to overwrite existing file: {path}")
+
+
+_FileSnapshot = tuple[bytes, int] | None
+
+
+def _snapshots(*paths: Path | None) -> dict[Path, _FileSnapshot]:
+    snapshots: dict[Path, _FileSnapshot] = {}
+    for path in paths:
+        if path is None or path in snapshots:
+            continue
+        snapshots[path] = (
+            (path.read_bytes(), stat.S_IMODE(path.stat().st_mode))
+            if path.exists()
+            else None
+        )
+    return snapshots
+
+
+def _restore_snapshots(snapshots: dict[Path, _FileSnapshot]) -> None:
+    for path, snapshot in reversed(tuple(snapshots.items())):
+        if snapshot is None:
+            if path.is_symlink() or path.is_file():
+                path.unlink()
+            continue
+        content, mode = snapshot
+        _write_atomic_bytes(path, content, force=True, mode=mode)
+
+
+def _load_template(relative_path: Path) -> str:
+    template = _TEMPLATES_ROOT / relative_path
+    return template.read_text(encoding="utf-8")
+
+
+def _render_plugin(python_executable: str) -> str:
+    template = _load_template(OPENCODE_PLUGIN_TEMPLATE_PATH)
+    escaped_python_executable = json.dumps(str(python_executable))
+    return template.replace("{{PYTHON_EXECUTABLE}}", escaped_python_executable)
+
+
+def _write_atomic_text(path: Path, content: str, force: bool = False) -> None:
+    _write_atomic_bytes(path, content.encode(), force=force)
+
+
+def _write_atomic_bytes(
+    path: Path,
+    content: bytes,
+    *,
+    force: bool = False,
+    mode: int | None = None,
+) -> None:
+    if path.is_symlink():
+        raise FileExistsError(f"Refusing to replace symbolic link: {path}")
+    if path.exists() and not force:
+        raise FileExistsError(f"Refusing to overwrite existing file: {path}")
+    if path.exists() and not path.is_file():
+        raise FileExistsError(f"Generated destination is not a file: {path}")
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    installed_mode = (
+        mode
+        if mode is not None
+        else stat.S_IMODE(path.stat().st_mode)
+        if path.exists()
+        else 0o644
+    )
+    tmp_path: Path | None = None
+    try:
+        with NamedTemporaryFile("wb", dir=path.parent, delete=False) as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+            tmp_path = Path(handle.name)
+        os.chmod(tmp_path, installed_mode)
+        os.replace(tmp_path, path)
+    finally:
+        if tmp_path is not None and tmp_path.exists():
+            tmp_path.unlink()

agent_codinglanguage_mapper-1.1.1/src/agent_codinglanguage_mapper/templates/opencode/agents/agent-codinglanguage-mapper.md

@@ -0,0 +1,16 @@
+---
+description: Navigate mixed-language codebases through agent-codinglanguage-mapper.
+mode: subagent
+permission:
+  "*": deny
+  skill:
+    "*": deny
+    agent-codinglanguage-mapper: allow
+  codebase_map: allow
+  code_guidelines: allow
+---
+
+Load `agent-codinglanguage-mapper` first. Use only `skill`, `codebase_map`, and
+`code_guidelines` for source inspection and coding-guideline work. Preserve
+returned citations exactly, keep uncertainty explicit, and never replace
+semantic tool evidence with raw filesystem inspection.

{agent_codinglanguage_mapper-1.1.0 → agent_codinglanguage_mapper-1.1.1}/src/agent_codinglanguage_mapper/templates/skill/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: mixed-codebase-navigator
+name: agent-codinglanguage-mapper
 description: Inspect Python, Rust, C#, Delphi, C++, and mixed-language workspaces through a bounded semantic codebase map without raw filesystem search tools.
 license: MPL-2.0
 compatibility: opencode

{agent_codinglanguage_mapper-1.1.0 → agent_codinglanguage_mapper-1.1.1}/src/agent_codinglanguage_mapper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-codinglanguage-mapper
-Version: 1.1.0
+Version: 1.1.1
 Summary: Agent-focused semantic mapping and language services for mixed-language codebases.
 Author: Dark Light
 License-Expression: MPL-2.0
@@ -319,40 +319,37 @@ Example generic client configuration:
 
 ## OpenCode Integration
 
-Install the packaged skill, plugin, and restricted agent configuration into a repository:
+Install the package-named skill, Markdown agent, and plugin into a repository:
 
 ```bash
-codinglanguage-mapper opencode install --target . --write
+codinglanguage-mapper opencode install --target .
 ```
 
 This creates:
 
 ```text
-.agents/skills/mixed-codebase-navigator/SKILL.md
+.agents/skills/agent-codinglanguage-mapper/SKILL.md
+.opencode/agents/agent-codinglanguage-mapper.md
 .opencode/plugins/codebase_map.ts
-opencode.json
 ```
 
-The generated `mixed-codebase-navigator` agent denies all tools by default and permits only `skill`, `codebase_map`, and `code_guidelines`. The plugin maps the active OpenCode directory, serializes Protocol 3 requests through one worker, applies a hard timeout, reports bounded worker `stderr`, restarts after failure, and preserves focus plus warm parser indexes across short idle gaps. It stops the worker when the session is deleted or after 60 seconds without another mapper request.
+The generated `agent-codinglanguage-mapper` agent denies all tools by default and permits only its package-named skill, `codebase_map`, and `code_guidelines`. The plugin maps the active OpenCode directory, serializes Protocol 3 requests through one worker, applies a hard timeout, reports bounded worker `stderr`, restarts after failure, and preserves focus plus warm parser indexes across short idle gaps. It stops the worker when the session is deleted or after 60 seconds without another mapper request.
+
+The installer never reads or changes `opencode.json`; user configuration remains
+user-owned. The deprecated `--write`, `--write-config`, and `--write-agent`
+compatibility flags are accepted, but the Markdown agent is installed by
+default and those flags do not enable configuration writes.
 
 `code_guidelines` exposes four actions: `detect`, `audit`, `patch`, and `apply`. The first three are read-only. `apply` is rejected unless its request contains `write: true`, so the agent must inspect a patch before it can opt into mutation.
 
-```json
-{
-  "permission": {
-    "*": "deny",
-    "skill": "allow",
-    "codebase_map": "allow",
-    "code_guidelines": "allow"
-  }
-}
-```
+The agent's YAML frontmatter contains its restricted permissions; no matching
+JSON agent block is required.
 
 Run it with:
 
 ```bash
 opencode run \
-  --agent mixed-codebase-navigator \
+  --agent agent-codinglanguage-mapper \
   "Find PaymentService, inspect its implementation, and cite the callers. Use only the installed skill and codebase_map."
 ```
 

{agent_codinglanguage_mapper-1.1.0 → agent_codinglanguage_mapper-1.1.1}/src/agent_codinglanguage_mapper.egg-info/SOURCES.txt

@@ -43,6 +43,7 @@ src/agent_codinglanguage_mapper/adapters/delphi_frontend/semantic.py
 src/agent_codinglanguage_mapper/adapters/delphi_frontend/semantic_builder.py
 src/agent_codinglanguage_mapper/adapters/delphi_frontend/source_reader.py
 src/agent_codinglanguage_mapper/adapters/delphi_frontend/workspace.py
+src/agent_codinglanguage_mapper/templates/opencode/agents/agent-codinglanguage-mapper.md
 src/agent_codinglanguage_mapper/templates/opencode/plugins/codebase_map.ts
 src/agent_codinglanguage_mapper/templates/skill/SKILL.md
 tests/test_adapters.py

{agent_codinglanguage_mapper-1.1.0 → agent_codinglanguage_mapper-1.1.1}/tests/test_cli.py

@@ -26,6 +26,7 @@ def test_parser_exposes_mapper_commands_and_layer_choices() -> None:
     assert parser.parse_args(["skill", "install"]).skill_command == "install"
     assert parser.parse_args(["opencode", "install", "--write-config"]).write_config is True
     assert parser.parse_args(["opencode", "install", "--write"]).write_config is True
+    assert parser.parse_args(["opencode", "install", "--write-agent"]).write_config is True
 
 
 def test_cli_executes_view_index_doctor_and_installers(tmp_path: Path, capsys) -> None:
@@ -48,7 +49,8 @@ def test_cli_executes_view_index_doctor_and_installers(tmp_path: Path, capsys) -
     assert main(["opencode", "install", "--target", str(target), "--write"]) == 0
     installed = json.loads(capsys.readouterr().out)["installed"]
     assert any(path.endswith("codebase_map.ts") for path in installed)
-    assert (target / "opencode.json").is_file()
+    assert any(path.endswith("agents/agent-codinglanguage-mapper.md") for path in installed)
+    assert not (target / "opencode.json").exists()
 
 
 def test_cli_guidelines_detect_audit_patch_and_write(tmp_path: Path, capsys) -> None: