Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Fixed

- `apm install` for Claude now keeps the command frontmatter Claude Code documents for `.claude/commands/*.md` (`disable-model-invocation`, `user-invocable`, `when_to_use`, `effort`, `disallowed-tools`, `context`, `agent`, `background`, `shell`, and an authored `arguments` when there is no `input:`) instead of dropping it with a warning. Inline `hooks` are still withheld, now with their own warning, until they go through executable consent; `name` and `paths` are still dropped, and other targets are unchanged. -- by @abhishekacharya200 (#3748)

- `APM_HOME` is now the single root for APM-owned user state: global `apm.yml`, `apm.lock.yaml` and `apm_modules/`, `config.json`, marketplace registrations, lifecycle trust and logs, and deployment receipts all follow it, so two `APM_HOME` values no longer share or leak into `~/.apm`. Unset keeps `~/.apm`; a relative value resolves against the starting directory; target deployment destinations are unchanged, and state-changing commands still serialize across `APM_HOME` values. -- by @WilliamK112 (#3614, #3707)
- `apm install` no longer rewrites a JSONC or trailing-comma MCP config (`.vscode/mcp.json`, `.github/mcp.json`, Gemini, Kiro, Claude) from scratch, which deleted user servers; it leaves the file unchanged, reports the server as not configured and exits 1. All JSON MCP configs are now written through the shared atomic, symlink-safe writer, and project MCP config files that are symbolic links are refused like user-scope ones. (#PRNUM)
- Interrupting an APM command (Ctrl+C) now stops a running lifecycle script, such as `pre-compile`, before APM exits. (#PRNUM)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -359,7 +359,13 @@ your-package/
Frontmatter the command integrator preserves: `description`,
`allowed-tools`, `model`, `argument-hint`, `input`. Other keys (for
example `author`, `mcp`, `parameters`) are dropped during the
transform and surfaced as install-time diagnostics.
transform and surfaced as install-time diagnostics. For Claude, the
command also keeps the fields Claude Code documents for command files
(`when_to_use`, `disable-model-invocation`, `user-invocable`,
`disallowed-tools`, `effort`, `context`, `agent`, `background`, `shell`,
and `arguments` without `input`); inline `hooks` are withheld with a
warning until APM routes them through executable consent. See
[Prompts](../prompts/#frontmatter).

```markdown
---
Expand Down
11 changes: 11 additions & 0 deletions docs/src/content/docs/producer/author-primitives/prompts.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,17 @@ on lossy targets see a warning, not silent data loss.
| `model` | string | Preferred model slug (Claude/Cursor only). |
| `argument-hint` | string | Free-form hint shown in the picker; auto-derived from `input` when omitted. |

On the `claude` target, `.claude/commands/<name>.md` also keeps the other
fields Claude Code
[documents for command files](https://code.claude.com/docs/en/skills#frontmatter-reference):
`when_to_use`, `disable-model-invocation`, `user-invocable`,
`disallowed-tools`, `effort`, `context`, `agent`, `background`, `shell`,
and `arguments` when no `input` is set. `name` and `paths` are not
supported on command files and are dropped. Inline `hooks` are withheld
with a warning: Claude Code supports them, but APM does not yet run
frontmatter hooks through executable consent, so the deployed command
does not get them. Other targets keep only the five keys above.

Reference inputs in the body with `${input:name}`. The compiler
rewrites these per target (for example, `$name` for Claude
commands).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -564,6 +564,11 @@ Review ${input:pr_url} focusing on ${input:focus_areas}.
When installed as a Claude Code slash command, APM maps `input:` to
Claude's `arguments:` frontmatter and converts `${input:name}` to `$name`
placeholders. An `argument-hint` is auto-generated unless one is already set.
Claude commands also keep `when_to_use`, `disable-model-invocation`,
`user-invocable`, `disallowed-tools`, `effort`, `context`, `agent`,
`background`, `shell`, and an authored `arguments` when there is no `input:`.
`name` and `paths` are dropped, and inline `hooks` are withheld with a warning
because APM does not yet run frontmatter hooks through executable consent.

For the `copilot` target, prompts deploy to `.github/prompts/<name>.prompt.md`.
In VS Code, only Local harness sessions load prompt files; the Copilot harness
Expand Down
70 changes: 65 additions & 5 deletions src/apm_cli/integration/command_integrator.py
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,28 @@
}
)

# Extra keys kept only on the Claude target. Claude Code documents that
# ``.claude/commands/*.md`` accept the skill frontmatter except ``name``
# and ``paths`` (https://code.claude.com/docs/en/skills#frontmatter-reference).
# ``arguments`` is handled separately because ``input`` also maps to it.
# ``hooks`` is withheld on purpose: frontmatter hooks are not routed through
# APM's executable consent yet (see #3067 and #3227).
_CLAUDE_NATIVE_COMMAND_KEYS = frozenset(
{
"when_to_use",
"disable-model-invocation",
"user-invocable",
"disallowed-tools",
"effort",
"context",
"agent",
"background",
"shell",
}
)

_CLAUDE_WITHHELD_COMMAND_KEYS = frozenset({"hooks"})


def _is_valid_input_name(name: str) -> bool:
"""Return True if *name* is a safe argument identifier."""
Expand Down Expand Up @@ -196,18 +218,23 @@ def find_prompt_files(self, package_path: Path, source_plan=None) -> list[Path]:
def _transform_prompt_to_command(
self,
source: Path,
target_name: str | None = None,
) -> tuple[str, frontmatter.Post, list[str], list[str]]:
"""Transform a .prompt.md file into Claude command format.

Args:
source: Path to the .prompt.md file
target_name: Deployment target. Only ``"claude"`` keeps the
Claude-native keys in ``_CLAUDE_NATIVE_COMMAND_KEYS`` and an
authored ``arguments``; other targets keep the shared subset.

Returns:
Tuple of (command_name, post, warnings, dropped_keys).
``dropped_keys`` lists source frontmatter keys that the shared
command transformer does not preserve (e.g. ``author``,
``mcp``, ``parameters`` for Cursor-specific frontmatter).
"""
is_claude = target_name == "claude"
warnings: list[str] = []

post = load_frontmatter(source)
Expand Down Expand Up @@ -239,6 +266,11 @@ def _transform_prompt_to_command(
elif "argumentHint" in post.metadata:
claude_metadata["argument-hint"] = post.metadata["argumentHint"]

if is_claude:
for key in sorted(_CLAUDE_NATIVE_COMMAND_KEYS):
if key in post.metadata:
claude_metadata[key] = post.metadata[key]

# Map APM 'input' to Claude 'arguments' and 'argument-hint'
input_names, rejected_names = _extract_input_names(post.metadata.get("input"))
if rejected_names:
Expand All @@ -251,6 +283,9 @@ def _transform_prompt_to_command(
claude_metadata["arguments"] = input_names
if "argument-hint" not in claude_metadata:
claude_metadata["argument-hint"] = " ".join(f"<{name}>" for name in input_names)
elif is_claude and "arguments" in post.metadata:
# No 'input' mapping: keep the author's native Claude 'arguments'.
claude_metadata["arguments"] = post.metadata["arguments"]

# Convert APM input references to Claude $name placeholders
content = post.content
Expand All @@ -268,7 +303,12 @@ def _transform_prompt_to_command(
# Compute keys present in source frontmatter but not preserved by
# the shared command transformer. Surfaced by integrate_command()
# via diagnostics so users see the lossy transform at install time.
dropped_keys = sorted(set(post.metadata.keys()) - _PRESERVED_COMMAND_KEYS)
preserved = _PRESERVED_COMMAND_KEYS
if is_claude:
preserved = preserved | _CLAUDE_NATIVE_COMMAND_KEYS
if not input_names:
preserved = preserved | {"arguments"}
dropped_keys = sorted(set(post.metadata.keys()) - preserved)

return (command_name, new_post, warnings, dropped_keys)

Expand Down Expand Up @@ -321,7 +361,9 @@ def integrate_command(
decide whether to surface the one-shot passthrough notice.
"""
# Transform to command format
command_name, post, warnings, dropped_keys = self._transform_prompt_to_command(source)
command_name, post, warnings, dropped_keys = self._transform_prompt_to_command(
source, target_name
)

# Resolve context links in content
post.content, links_resolved = self.resolve_links(post.content, source, target)
Expand All @@ -337,17 +379,35 @@ def integrate_command(
# frontmatter; any other source key is silently discarded by the
# transformer. Warn so users see the lossy transform at install
# time -- core "install adds, never silently mutates" contract.
if dropped_keys and diagnostics is not None:
preserved_list = ", ".join(sorted(_PRESERVED_COMMAND_KEYS_DISPLAY))
withheld_keys: list[str] = []
unsupported_keys = dropped_keys
display_keys = _PRESERVED_COMMAND_KEYS_DISPLAY
if target_name == "claude":
withheld_keys = [k for k in dropped_keys if k in _CLAUDE_WITHHELD_COMMAND_KEYS]
unsupported_keys = [k for k in dropped_keys if k not in _CLAUDE_WITHHELD_COMMAND_KEYS]
display_keys = display_keys | _CLAUDE_NATIVE_COMMAND_KEYS | {"arguments"}
if unsupported_keys and diagnostics is not None:
preserved_list = ", ".join(sorted(display_keys))
diagnostics.warn(
message=(
f"{target_name.capitalize()} command {command_name}: "
f"frontmatter keys not supported for {target_name} commands "
f"and were dropped: {', '.join(dropped_keys)}. "
f"and were dropped: {', '.join(unsupported_keys)}. "
f"Supported keys: {preserved_list}."
),
package=pkg_name,
)
if withheld_keys and diagnostics is not None:
diagnostics.warn(
message=(
f"Claude command {command_name}: frontmatter "
f"{', '.join(withheld_keys)} withheld. Claude Code supports "
f"inline hooks on commands, but APM does not yet run them "
f"through executable consent, so the command was deployed "
f"without them and may not behave as authored."
),
package=pkg_name,
)

# Surface install-time info when input -> arguments mapping happened so
# users aren't surprised by content that differs from the source package.
Expand Down
130 changes: 130 additions & 0 deletions tests/unit/integration/test_command_integrator.py
Original file line number Diff line number Diff line change
Expand Up @@ -1718,3 +1718,133 @@ def test_critical_security_finding_blocks_write(self, temp_project):
assert any(i.severity == "critical" for i in sec_items), (
f"expected critical security diagnostic, got: {[(i.severity, i.message) for i in sec_items]}"
)


class TestClaudeNativeCommandFrontmatter:
"""Claude-target commands keep the frontmatter Claude Code documents (#3067)."""

_NATIVE_PROMPT = (
"---\n"
"description: d\n"
"disable-model-invocation: true\n"
"user-invocable: false\n"
"when_to_use: x\n"
"effort: low\n"
"disallowed-tools: [AskUserQuestion]\n"
"context: fork\n"
"agent: Explore\n"
"background: false\n"
"shell: powershell\n"
"---\n"
"Run it.\n"
)

@pytest.fixture
def temp_project(self):
temp_dir = tempfile.mkdtemp()
temp_path = Path(temp_dir)
(temp_path / ".claude").mkdir()
(temp_path / ".cursor").mkdir()
yield temp_path
shutil.rmtree(temp_dir, ignore_errors=True)

def _install(self, project, prompts, target_name):
from apm_cli.integration.targets import KNOWN_TARGETS
from apm_cli.utils.diagnostics import DiagnosticCollector

pkg_info = _make_package(project, prompts)
diag = DiagnosticCollector()
CommandIntegrator().integrate_commands_for_target(
KNOWN_TARGETS[target_name],
pkg_info,
project,
diagnostics=diag,
)
warnings = [w.message for w in diag.by_category().get("warning", [])]
return warnings

def test_claude_keeps_documented_command_keys(self, temp_project):
warnings = self._install(temp_project, {"p.prompt.md": self._NATIVE_PROMPT}, "claude")

post = frontmatter.load(temp_project / ".claude" / "commands" / "p.md")
assert post.metadata == {
"description": "d",
"disable-model-invocation": True,
"user-invocable": False,
"when_to_use": "x",
"effort": "low",
"disallowed-tools": ["AskUserQuestion"],
"context": "fork",
"agent": "Explore",
"background": False,
"shell": "powershell",
}
assert not any("frontmatter keys not supported" in w for w in warnings), warnings

def test_claude_keeps_authored_arguments_without_input(self, temp_project):
self._install(
temp_project,
{"p.prompt.md": "---\ndescription: d\narguments: [issue, branch]\n---\n$issue\n"},
"claude",
)

post = frontmatter.load(temp_project / ".claude" / "commands" / "p.md")
assert post.metadata["arguments"] == ["issue", "branch"]

def test_claude_input_mapping_wins_over_authored_arguments(self, temp_project):
warnings = self._install(
temp_project,
{
"p.prompt.md": (
"---\ndescription: d\ninput: [feature]\narguments: [other]\n---\n"
"${input:feature}\n"
),
},
"claude",
)

post = frontmatter.load(temp_project / ".claude" / "commands" / "p.md")
assert post.metadata["arguments"] == ["feature"]
assert any("were dropped: arguments" in w for w in warnings), warnings

def test_claude_still_drops_name_and_paths(self, temp_project):
warnings = self._install(
temp_project,
{"p.prompt.md": "---\ndescription: d\nname: other\npaths: ['*.py']\n---\nRun.\n"},
"claude",
)

post = frontmatter.load(temp_project / ".claude" / "commands" / "p.md")
assert post.metadata == {"description": "d"}
assert any(
"not supported for claude commands" in w and "name, paths" in w for w in warnings
), warnings

def test_claude_withholds_inline_hooks_with_explicit_warning(self, temp_project):
warnings = self._install(
temp_project,
{
"p.prompt.md": (
"---\ndescription: d\nhooks:\n PreToolUse:\n"
" - matcher: Bash\n hooks:\n"
" - type: command\n command: ./check.sh\n"
"---\nRun.\n"
),
},
"claude",
)

post = frontmatter.load(temp_project / ".claude" / "commands" / "p.md")
assert "hooks" not in post.metadata
assert any("hooks withheld" in w and "executable consent" in w for w in warnings), warnings
assert not any("frontmatter keys not supported" in w for w in warnings), warnings

def test_cursor_output_unchanged(self, temp_project):
warnings = self._install(temp_project, {"p.prompt.md": self._NATIVE_PROMPT}, "cursor")

post = frontmatter.load(temp_project / ".cursor" / "commands" / "p.md")
assert post.metadata == {"description": "d"}
assert any(
"not supported for cursor commands" in w and "disable-model-invocation" in w
for w in warnings
), warnings