[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M699DEP6RCQ5N493WZA14HVV":3,"skill-same:01M699DEP6RCQ5N493WZA14HVV":82},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":26,"publishedAt":47,"linkOnly":48,"markdownContent":49,"markdownBody":50,"frontMatter":51,"refName":52,"commitSha":53,"skillDirectory":54,"forksCount":55,"repositoryHtmlUrl":56,"repositoryHomepageUrl":57,"ownerHtmlUrl":58,"ownerBlogUrl":59,"ownerDescription":60,"updatedAt":61,"install":62,"resources":75},"01M699DEP6RCQ5N493WZA14HVV","cli-logging-ux",null,"Use this skill when editing or creating CLI output, logging, warnings, error messages, progress indicators, or diagnostic summaries in the APM codebase. Activate whenever code touches console helpers (_rich_success, _rich_warning, _rich_error, _rich_info, _rich_echo), DiagnosticCollector, STATUS_SYMBOLS, CommandLogger, or any user-facing terminal output — even if the user doesn't mention \"logging\" or \"UX\" explicitly.","microsoft\u002Fapm","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M699CC41JR5QW38C9PDX6101",4369,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcli-logging-ux\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000032","设计师",[27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46],"cli logging ux","ux","logging","cli","editing","helpers","when","rich","error","progress","info","activate","Echo","use","messages","error messages","apm","code","status","terminal","2026-11-10 10:12:30",false,"---\nname: cli-logging-ux\ndescription: >\n  Use this skill when editing or creating CLI output, logging, warnings,\n  error messages, progress indicators, or diagnostic summaries in the APM\n  codebase. Activate whenever code touches console helpers (_rich_success,\n  _rich_warning, _rich_error, _rich_info, _rich_echo), DiagnosticCollector,\n  STATUS_SYMBOLS, CommandLogger, or any user-facing terminal output — even\n  if the user doesn't mention \"logging\" or \"UX\" explicitly.\n---\n\n[CLI Logging UX expert persona](..\u002F..\u002F..\u002F.apm\u002Fagents\u002Fcli-logging-expert.agent.md)\n\n# CLI Logging & Developer Experience\n\n## Decision framework\n\nApply these three tests to every piece of user-facing output. If a message fails any test, redesign it.\n\n### 1. The \"So What?\" Test\n\nEvery warning must answer: *what should the user do about this?*\n\n```\n# Fails — not actionable, user can't do anything\nSub-skill 'my-skill' from 'my-package' overwrites existing skill\n\n# Passes — tells the user exactly what to do\nSkipping my-skill — local file exists (not managed by APM). Use 'apm install --force' to overwrite.\n```\n\nIf the user can't act on it, it's not a warning — it's noise. Demote to `--verbose` or remove.\n\n### 2. The Traffic Light Rule\n\nUse color semantics consistently. Never use a warning color for an informational state.\n\n| Color | Helper | Meaning | When to use |\n|-------|--------|---------|-------------|\n| Green | `_rich_success()` | Success \u002F completed | Operation finished as expected |\n| Yellow | `_rich_warning()` | User action needed | Something requires user decision |\n| Red | `_rich_error()` | Error \u002F failure | Operation failed, cannot continue |\n| Blue | `_rich_info()` | Informational | Status updates, progress, summaries |\n| Dim | `_rich_echo(color=\"dim\")` | Secondary detail | Verbose-mode details, grouping headers |\n\n### 3. The Newspaper Test\n\nCan the user scan output like headlines? Top-level = what happened. Details = drill down.\n\n```\n# Bad — warnings break the visual flow between status and summary\n[checkmark] package-name\n[warning] something happened\n[warning] something else happened\n  [tree] 3 skill(s) integrated\n\n# Good — clean tree, diagnostics at the end\n[checkmark] package-name\n  [tree] 3 skill(s) integrated\n\n── Diagnostics ──\n  [warning] 2 skills replaced by a different package (last installed wins)\n    Run with --verbose to see details\n```\n\n## Inline output vs deferred diagnostics\n\n### Use inline output for:\n- Success confirmations (`_rich_success`)\n- Progress updates (`_rich_info` with indented `└─` prefix)\n- Errors that halt the current operation (`_rich_error`)\n\n### Use DiagnosticCollector for:\n- Warnings that apply across multiple packages (collisions, overwrites)\n- Issues the user should know about but that don't stop the operation\n- Anything that would repeat N times in a loop\n\n```python\n# Bad — inline warning repeated per file, clutters output\nfor file in files:\n    if collision:\n        _rich_warning(f\"Skipping {file}...\")\n\n# Good — collect during loop, render grouped summary at the end\nfor file in files:\n    if collision:\n        diagnostics.skip(file, package=pkg_name)\n\n# Later, after the loop:\nif diagnostics.has_diagnostics:\n    diagnostics.render_summary()\n```\n\nDiagnosticCollector categories: `skip()` for collisions, `overwrite()` for cross-package replacements, `warn()` for general warnings, `error()` for failures.\n\n## Console helper conventions\n\nAlways use the helpers from `apm_cli.utils.console` — never raw `print()` or bare `click.echo()`.\n\n**Emojis are banned.** Never use emoji characters anywhere in CLI output — not in messages, symbols, help text, or status indicators. Use ASCII text symbols exclusively via `STATUS_SYMBOLS`.\n\n```python\nfrom apm_cli.utils.console import (\n    _rich_success, _rich_error, _rich_warning, _rich_info, _rich_echo\n)\n\n_rich_success(\"Installed 3 APM dependencies\")        # green, bold\n_rich_info(\"  └─ 2 prompts integrated → .github\u002Fprompts\u002F\")  # blue\n_rich_warning(\"Config drift detected — re-run apm install\")  # yellow\n_rich_error(\"Failed to download package\")              # red\n_rich_echo(\"    [pkg-name]\", color=\"dim\")              # dim, for verbose details\n```\n\nUse `STATUS_SYMBOLS` dict with `symbol=` parameter for consistent ASCII prefixes:\n```python\n_rich_info(\"Starting operation...\", symbol=\"gear\")     # renders as \"[*] Starting operation...\"\n```\n\n## Output structure pattern\n\nFollow this visual hierarchy for multi-package operations:\n\n```\n[checkmark] package-name-1                      # _rich_success — download\u002Fcopy ok\n  [tree] 2 prompts integrated → .github\u002Fprompts\u002F     # _rich_info — indented summary\n  [tree] 1 skill(s) integrated → .github\u002Fskills\u002F\n[checkmark] package-name-2\n  [tree] 1 instruction(s) integrated → .github\u002Finstructions\u002F\n\n── Diagnostics ──                         # Only if diagnostics.has_diagnostics\n  [warning] N files skipped — ...                   # Grouped by category\n    Run with --verbose to see details\n\nInstalled 2 APM dependencies              # _rich_success — final summary\n```\n\n## Content-awareness principle\n\nBefore reporting changes, check if anything actually changed. Don't report no-ops.\n\n```python\n# Bad — always copies and reports, even when content is identical\nshutil.rmtree(target)\nshutil.copytree(source, target)\n_rich_info(f\"  └─ Skill updated\")\n\n# Good — skip when content matches\nif SkillIntegrator._dirs_equal(source, target):\n    continue  # Nothing changed, nothing to report\n```\n\n## CommandLogger Architecture\n\nAPM is a large and growing CLI with 10+ commands, 8+ integrators, and dozens of output sites. The logging architecture enforces **Separation of Concerns**: commands declare *what* happened; the logger decides *how* to render it. This keeps output consistent, testable, and evolvable without shotgun surgery across command files.\n\n### The three layers\n\n```\n┌─────────────────────────────────────────────────────┐\n│  Command layer  (install.py, pack.py, audit.py …)   │\n│  Calls: logger.success(), logger.tree_item(), …      │\n│  NEVER calls: _rich_*, click.echo(), print()         │\n├─────────────────────────────────────────────────────┤\n│  Logger layer   (command_logger.py)                  │\n│  CommandLogger ← InstallLogger, future subclasses    │\n│  Owns: verbose gating, symbol choice, indentation    │\n│  Delegates to: _rich_* helpers                       │\n├─────────────────────────────────────────────────────┤\n│  Rendering layer (console.py)                        │\n│  _rich_echo, _rich_success, _rich_error, …           │\n│  Owns: Rich\u002Fcolorama fallback, color, STATUS_SYMBOLS │\n└─────────────────────────────────────────────────────┘\n```\n\nChanges to output style (colors, symbols, indentation) happen in the **logger or rendering layer only** — command code is untouched. New output patterns (e.g. a tree sub-item, a package metadata line) become new logger methods, not ad-hoc format strings in commands.\n\n### Base class: `CommandLogger`\n\n`src\u002Fapm_cli\u002Fcore\u002Fcommand_logger.py` — base for all commands.\n\n| Method | Purpose | When to use |\n|--------|---------|-------------|\n| `start(msg, symbol=)` | Operation start | Beginning of a command |\n| `progress(msg, symbol=)` | Status update with `[i]` prefix | Mid-operation phase changes |\n| `success(msg, symbol=)` | Green success | Operation completed |\n| `warning(msg, symbol=)` | Yellow warning | User action needed |\n| `error(msg, symbol=)` | Red error | Operation failed |\n| `verbose_detail(msg)` | Dim text, verbose-only | Internal details (paths, hashes) |\n| `tree_item(msg)` | Green text, no symbol prefix | `└─` sub-items under a package |\n| `package_inline_warning(msg)` | Yellow text, verbose-only | Per-package diagnostic hints |\n| `dry_run_notice(msg)` | `[dry-run]` prefix | Dry-run explanation |\n| `auth_step(step, success, detail)` | Auth resolution step | Verbose auth tracing |\n| `render_summary()` | Render DiagnosticCollector | End of command |\n\n### Subclass: `InstallLogger(CommandLogger)`\n\nInstall-specific phases. Commands that don't need these use `CommandLogger` directly.\n\n| Method | Purpose | Output |\n|--------|---------|--------|\n| `validation_start(count)` | Start validation | `[*] Validating N package(s)...` |\n| `validation_pass(name, present)` | Package OK | `[+] name` or `name (already in apm.yml)` |\n| `validation_fail(name, reason)` | Package bad | `[x] name -- reason` |\n| `resolution_start(count, lockfile)` | Start resolution | Context-aware install\u002Fupdate message |\n| `download_complete(name, ref=, sha=, cached=)` | Package installed | `[+] name #tag @sha` or `(cached)` |\n| `download_failed(name, error)` | Download error | `[x] name -- error` |\n| `lockfile_entry(key, ref=, sha=)` | Lockfile verbose line | `key: locked at sha` \u002F `pinned to ref` \u002F omitted |\n| `package_auth(source, token_type=)` | Auth source verbose | `Auth: source (type)` |\n| `package_type_info(label)` | Package type verbose | `Package type: label` |\n| `install_summary(apm, mcp, errors)` | Final summary | `Installed N APM dependencies.` |\n\n### When to add a new logger method\n\nIf a command needs a new output pattern (new indentation level, new semantic meaning, new verbose gate), **add a method to CommandLogger or a subclass**. Signs you need a new method:\n\n- You're writing `_rich_echo(f\"    Something: {value}\", color=\"dim\")` in a command file\n- You're checking `if logger.verbose:` before calling `_rich_echo` in a command\n- You're formatting a string with specific indentation that other commands might reuse\n- Multiple commands emit the same kind of line (e.g., file lists, auth info)\n\n### Rule: No direct `_rich_*` in commands\n\nCommand functions must NOT call `_rich_info()`, `_rich_error()`, etc. directly. Use `logger.progress()`, `logger.error()`, etc. instead. The `_rich_*` helpers are **internal** to the logger and rendering layers.\n\n**Exception:** Rich tables and panels for display (not lifecycle logging) may use `console.print()` directly — these are data presentation, not status reporting.\n\n### Rule: Every command gets a `CommandLogger`\n\nEvery Click command function must instantiate a `CommandLogger` (or subclass) and pass it to helpers:\n\n```python\n@cli.command()\n@click.option(\"--verbose\", \"-v\", is_flag=True)\n@click.option(\"--dry-run\", is_flag=True)\ndef my_command(verbose, dry_run):\n    logger = CommandLogger(\"my-command\", verbose=verbose, dry_run=dry_run)\n    logger.start(\"Starting operation...\")\n    _do_work(logger=logger)\n    logger.render_summary()\n```\n\n### Rule: Verbose gating lives in the logger\n\nNever check `if verbose:` in command code. Use methods that gate internally:\n\n```python\n# Bad — manual verbose check in command\nif verbose:\n    _rich_echo(f\"    Auth: {source}\", color=\"dim\")\n\n# Good — logger handles the gate\nlogger.package_auth(source, token_type)  # No-ops when not verbose\nlogger.verbose_detail(f\"    Path: {path}\")  # No-ops when not verbose\n```\n\n### DiagnosticCollector integration\n\nAccess via `logger.diagnostics` (lazy-initialized). The collector owns the collect-then-render lifecycle:\n\n```python\n# During operation — collect\ndiagnostics.skip(file, package=pkg_name)          # Collision\ndiagnostics.overwrite(file, package=pkg_name)     # Cross-package replacement\ndiagnostics.error(msg, package=pkg_name)          # Failure\ndiagnostics.auth(msg, package=pkg_name)           # Auth issue\n\n# Query during operation (e.g., for inline verbose hints)\ncount = diagnostics.count_for_package(pkg_name, category=\"collision\")\nif count > 0:\n    logger.package_inline_warning(f\"    [!] {count} files skipped\")\n\n# After operation — render grouped summary\nlogger.render_summary()  # Delegates to diagnostics.render_summary()\n```\n\n### Visual hierarchy contract\n\nMulti-package operations follow this tree structure:\n\n```\n  [+] package-name #v1.0 @b0cbd3df                    # download_complete\n      Auth: git-credential-fill (oauth)                # package_auth (verbose)\n      Package type: Skill (SKILL.md detected)          # package_type_info (verbose)\n    └─ 3 skill(s) integrated -> .github\u002Fskills\u002F        # tree_item\n    └─ 1 prompt integrated -> .github\u002Fprompts\u002F         # tree_item\n      [!] 2 files skipped (local files exist)          # package_inline_warning (verbose)\n  [+] another-package (cached)                         # download_complete\n\n── Diagnostics ──                                      # render_summary\n  [!] 2 files skipped -- local files exist             # Grouped by category\n    Use 'apm install --force' to overwrite\n\n[*] Installed 2 APM dependencies.                      # install_summary\n```\n\nKey rules:\n- `[+]` package lines are the top-level anchors (green, no indent beyond 2-space)\n- Verbose metadata (Auth, Package type) uses 4-space indent, dim color\n- Tree items (`└─`) use 4-space indent, green color, no symbol prefix\n- Inline warnings use 4-space indent, yellow color, verbose-only\n- Diagnostics summary appears AFTER all packages, not inline (except verbose hints)\n\n### Scaling guidance\n\nAs the CLI grows, this architecture scales by:\n- **New commands**: Instantiate `CommandLogger`, use existing methods. Add subclass only if the command has distinct phases (like `InstallLogger`).\n- **New output patterns**: Add methods to `CommandLogger`. Every command benefits.\n- **New integrators**: Accept `diagnostics=` param, push to collector. No direct output.\n- **Theme changes**: Modify rendering layer (`console.py`). Zero command changes.\n- **Testing**: Mock `CommandLogger` in tests to assert semantic calls without parsing output strings.\n\n## Anti-patterns\n\n1. **Warning for non-actionable state** — If the user can't do anything about it, use `_rich_info` or defer to `--verbose`, not `_rich_warning`.\n\n2. **Inline warnings in loops** — Use `DiagnosticCollector` to collect, then render a grouped summary after the loop.\n\n3. **Missing `diagnostics` parameter** — When calling integrators, always pass `diagnostics=diagnostics` so warnings route to the deferred summary.\n\n4. **No emojis, ever** — Emojis are completely banned from all CLI output. Use ASCII text symbols from `STATUS_SYMBOLS` exclusively. This applies to messages, help text, status indicators, and table titles.\n\n5. **Inconsistent symbols** — Always use `STATUS_SYMBOLS` dict with `symbol=` param, not inline characters.\n\n6. **Walls of text** — Use Rich tables for structured data, panels for grouped content. Break up long output with visual hierarchy (indentation, `└─` tree connectors).\n\n7. **Direct `_rich_*` calls in commands** — Use `logger.start()`, `logger.progress()`, `logger.tree_item()` etc. The `_rich_*` helpers are internal to CommandLogger and console.py. Adding a `_rich_echo` call in a command file is a SoC violation.\n\n8. **Manual `if verbose:` checks** — Use `logger.verbose_detail()`, `logger.package_auth()`, or other verbose-gated methods. The logger owns the gate.\n\n9. **Manual `if dry_run:` checks** — Use `logger.should_execute` or `logger.dry_run_notice()`.\n\n10. **Format strings for indentation in commands** — Don't write `f\"    Auth: {source}\"` in command code. Use `logger.package_auth(source)` which owns the indent level. When a new indentation pattern is needed, add a method to CommandLogger.\n\n11. **Re-creating shared objects per iteration** — Expensive objects like `AuthResolver` should be created once before loops and reused per-package. The logger and diagnostics collector are already singletons per command invocation.\n\n12. **Using `logger.progress()` for tree sub-items** — `progress()` adds a `[i]` symbol prefix. Tree continuation lines (`└─`) should use `logger.tree_item()` which renders with no symbol.\n","[CLI Logging UX expert persona](..\u002F..\u002F..\u002F.apm\u002Fagents\u002Fcli-logging-expert.agent.md)\n\n# CLI Logging & Developer Experience\n\n## Decision framework\n\nApply these three tests to every piece of user-facing output. If a message fails any test, redesign it.\n\n### 1. The \"So What?\" Test\n\nEvery warning must answer: *what should the user do about this?*\n\n```\n# Fails — not actionable, user can't do anything\nSub-skill 'my-skill' from 'my-package' overwrites existing skill\n\n# Passes — tells the user exactly what to do\nSkipping my-skill — local file exists (not managed by APM). Use 'apm install --force' to overwrite.\n```\n\nIf the user can't act on it, it's not a warning — it's noise. Demote to `--verbose` or remove.\n\n### 2. The Traffic Light Rule\n\nUse color semantics consistently. Never use a warning color for an informational state.\n\n| Color | Helper | Meaning | When to use |\n|-------|--------|---------|-------------|\n| Green | `_rich_success()` | Success \u002F completed | Operation finished as expected |\n| Yellow | `_rich_warning()` | User action needed | Something requires user decision |\n| Red | `_rich_error()` | Error \u002F failure | Operation failed, cannot continue |\n| Blue | `_rich_info()` | Informational | Status updates, progress, summaries |\n| Dim | `_rich_echo(color=\"dim\")` | Secondary detail | Verbose-mode details, grouping headers |\n\n### 3. The Newspaper Test\n\nCan the user scan output like headlines? Top-level = what happened. Details = drill down.\n\n```\n# Bad — warnings break the visual flow between status and summary\n[checkmark] package-name\n[warning] something happened\n[warning] something else happened\n  [tree] 3 skill(s) integrated\n\n# Good — clean tree, diagnostics at the end\n[checkmark] package-name\n  [tree] 3 skill(s) integrated\n\n── Diagnostics ──\n  [warning] 2 skills replaced by a different package (last installed wins)\n    Run with --verbose to see details\n```\n\n## Inline output vs deferred diagnostics\n\n### Use inline output for:\n- Success confirmations (`_rich_success`)\n- Progress updates (`_rich_info` with indented `└─` prefix)\n- Errors that halt the current operation (`_rich_error`)\n\n### Use DiagnosticCollector for:\n- Warnings that apply across multiple packages (collisions, overwrites)\n- Issues the user should know about but that don't stop the operation\n- Anything that would repeat N times in a loop\n\n```python\n# Bad — inline warning repeated per file, clutters output\nfor file in files:\n    if collision:\n        _rich_warning(f\"Skipping {file}...\")\n\n# Good — collect during loop, render grouped summary at the end\nfor file in files:\n    if collision:\n        diagnostics.skip(file, package=pkg_name)\n\n# Later, after the loop:\nif diagnostics.has_diagnostics:\n    diagnostics.render_summary()\n```\n\nDiagnosticCollector categories: `skip()` for collisions, `overwrite()` for cross-package replacements, `warn()` for general warnings, `error()` for failures.\n\n## Console helper conventions\n\nAlways use the helpers from `apm_cli.utils.console` — never raw `print()` or bare `click.echo()`.\n\n**Emojis are banned.** Never use emoji characters anywhere in CLI output — not in messages, symbols, help text, or status indicators. Use ASCII text symbols exclusively via `STATUS_SYMBOLS`.\n\n```python\nfrom apm_cli.utils.console import (\n    _rich_success, _rich_error, _rich_warning, _rich_info, _rich_echo\n)\n\n_rich_success(\"Installed 3 APM dependencies\")        # green, bold\n_rich_info(\"  └─ 2 prompts integrated → .github\u002Fprompts\u002F\")  # blue\n_rich_warning(\"Config drift detected — re-run apm install\")  # yellow\n_rich_error(\"Failed to download package\")              # red\n_rich_echo(\"    [pkg-name]\", color=\"dim\")              # dim, for verbose details\n```\n\nUse `STATUS_SYMBOLS` dict with `symbol=` parameter for consistent ASCII prefixes:\n```python\n_rich_info(\"Starting operation...\", symbol=\"gear\")     # renders as \"[*] Starting operation...\"\n```\n\n## Output structure pattern\n\nFollow this visual hierarchy for multi-package operations:\n\n```\n[checkmark] package-name-1                      # _rich_success — download\u002Fcopy ok\n  [tree] 2 prompts integrated → .github\u002Fprompts\u002F     # _rich_info — indented summary\n  [tree] 1 skill(s) integrated → .github\u002Fskills\u002F\n[checkmark] package-name-2\n  [tree] 1 instruction(s) integrated → .github\u002Finstructions\u002F\n\n── Diagnostics ──                         # Only if diagnostics.has_diagnostics\n  [warning] N files skipped — ...                   # Grouped by category\n    Run with --verbose to see details\n\nInstalled 2 APM dependencies              # _rich_success — final summary\n```\n\n## Content-awareness principle\n\nBefore reporting changes, check if anything actually changed. Don't report no-ops.\n\n```python\n# Bad — always copies and reports, even when content is identical\nshutil.rmtree(target)\nshutil.copytree(source, target)\n_rich_info(f\"  └─ Skill updated\")\n\n# Good — skip when content matches\nif SkillIntegrator._dirs_equal(source, target):\n    continue  # Nothing changed, nothing to report\n```\n\n## CommandLogger Architecture\n\nAPM is a large and growing CLI with 10+ commands, 8+ integrators, and dozens of output sites. The logging architecture enforces **Separation of Concerns**: commands declare *what* happened; the logger decides *how* to render it. This keeps output consistent, testable, and evolvable without shotgun surgery across command files.\n\n### The three layers\n\n```\n┌─────────────────────────────────────────────────────┐\n│  Command layer  (install.py, pack.py, audit.py …)   │\n│  Calls: logger.success(), logger.tree_item(), …      │\n│  NEVER calls: _rich_*, click.echo(), print()         │\n├─────────────────────────────────────────────────────┤\n│  Logger layer   (command_logger.py)                  │\n│  CommandLogger ← InstallLogger, future subclasses    │\n│  Owns: verbose gating, symbol choice, indentation    │\n│  Delegates to: _rich_* helpers                       │\n├─────────────────────────────────────────────────────┤\n│  Rendering layer (console.py)                        │\n│  _rich_echo, _rich_success, _rich_error, …           │\n│  Owns: Rich\u002Fcolorama fallback, color, STATUS_SYMBOLS │\n└─────────────────────────────────────────────────────┘\n```\n\nChanges to output style (colors, symbols, indentation) happen in the **logger or rendering layer only** — command code is untouched. New output patterns (e.g. a tree sub-item, a package metadata line) become new logger methods, not ad-hoc format strings in commands.\n\n### Base class: `CommandLogger`\n\n`src\u002Fapm_cli\u002Fcore\u002Fcommand_logger.py` — base for all commands.\n\n| Method | Purpose | When to use |\n|--------|---------|-------------|\n| `start(msg, symbol=)` | Operation start | Beginning of a command |\n| `progress(msg, symbol=)` | Status update with `[i]` prefix | Mid-operation phase changes |\n| `success(msg, symbol=)` | Green success | Operation completed |\n| `warning(msg, symbol=)` | Yellow warning | User action needed |\n| `error(msg, symbol=)` | Red error | Operation failed |\n| `verbose_detail(msg)` | Dim text, verbose-only | Internal details (paths, hashes) |\n| `tree_item(msg)` | Green text, no symbol prefix | `└─` sub-items under a package |\n| `package_inline_warning(msg)` | Yellow text, verbose-only | Per-package diagnostic hints |\n| `dry_run_notice(msg)` | `[dry-run]` prefix | Dry-run explanation |\n| `auth_step(step, success, detail)` | Auth resolution step | Verbose auth tracing |\n| `render_summary()` | Render DiagnosticCollector | End of command |\n\n### Subclass: `InstallLogger(CommandLogger)`\n\nInstall-specific phases. Commands that don't need these use `CommandLogger` directly.\n\n| Method | Purpose | Output |\n|--------|---------|--------|\n| `validation_start(count)` | Start validation | `[*] Validating N package(s)...` |\n| `validation_pass(name, present)` | Package OK | `[+] name` or `name (already in apm.yml)` |\n| `validation_fail(name, reason)` | Package bad | `[x] name -- reason` |\n| `resolution_start(count, lockfile)` | Start resolution | Context-aware install\u002Fupdate message |\n| `download_complete(name, ref=, sha=, cached=)` | Package installed | `[+] name #tag @sha` or `(cached)` |\n| `download_failed(name, error)` | Download error | `[x] name -- error` |\n| `lockfile_entry(key, ref=, sha=)` | Lockfile verbose line | `key: locked at sha` \u002F `pinned to ref` \u002F omitted |\n| `package_auth(source, token_type=)` | Auth source verbose | `Auth: source (type)` |\n| `package_type_info(label)` | Package type verbose | `Package type: label` |\n| `install_summary(apm, mcp, errors)` | Final summary | `Installed N APM dependencies.` |\n\n### When to add a new logger method\n\nIf a command needs a new output pattern (new indentation level, new semantic meaning, new verbose gate), **add a method to CommandLogger or a subclass**. Signs you need a new method:\n\n- You're writing `_rich_echo(f\"    Something: {value}\", color=\"dim\")` in a command file\n- You're checking `if logger.verbose:` before calling `_rich_echo` in a command\n- You're formatting a string with specific indentation that other commands might reuse\n- Multiple commands emit the same kind of line (e.g., file lists, auth info)\n\n### Rule: No direct `_rich_*` in commands\n\nCommand functions must NOT call `_rich_info()`, `_rich_error()`, etc. directly. Use `logger.progress()`, `logger.error()`, etc. instead. The `_rich_*` helpers are **internal** to the logger and rendering layers.\n\n**Exception:** Rich tables and panels for display (not lifecycle logging) may use `console.print()` directly — these are data presentation, not status reporting.\n\n### Rule: Every command gets a `CommandLogger`\n\nEvery Click command function must instantiate a `CommandLogger` (or subclass) and pass it to helpers:\n\n```python\n@cli.command()\n@click.option(\"--verbose\", \"-v\", is_flag=True)\n@click.option(\"--dry-run\", is_flag=True)\ndef my_command(verbose, dry_run):\n    logger = CommandLogger(\"my-command\", verbose=verbose, dry_run=dry_run)\n    logger.start(\"Starting operation...\")\n    _do_work(logger=logger)\n    logger.render_summary()\n```\n\n### Rule: Verbose gating lives in the logger\n\nNever check `if verbose:` in command code. Use methods that gate internally:\n\n```python\n# Bad — manual verbose check in command\nif verbose:\n    _rich_echo(f\"    Auth: {source}\", color=\"dim\")\n\n# Good — logger handles the gate\nlogger.package_auth(source, token_type)  # No-ops when not verbose\nlogger.verbose_detail(f\"    Path: {path}\")  # No-ops when not verbose\n```\n\n### DiagnosticCollector integration\n\nAccess via `logger.diagnostics` (lazy-initialized). The collector owns the collect-then-render lifecycle:\n\n```python\n# During operation — collect\ndiagnostics.skip(file, package=pkg_name)          # Collision\ndiagnostics.overwrite(file, package=pkg_name)     # Cross-package replacement\ndiagnostics.error(msg, package=pkg_name)          # Failure\ndiagnostics.auth(msg, package=pkg_name)           # Auth issue\n\n# Query during operation (e.g., for inline verbose hints)\ncount = diagnostics.count_for_package(pkg_name, category=\"collision\")\nif count > 0:\n    logger.package_inline_warning(f\"    [!] {count} files skipped\")\n\n# After operation — render grouped summary\nlogger.render_summary()  # Delegates to diagnostics.render_summary()\n```\n\n### Visual hierarchy contract\n\nMulti-package operations follow this tree structure:\n\n```\n  [+] package-name #v1.0 @b0cbd3df                    # download_complete\n      Auth: git-credential-fill (oauth)                # package_auth (verbose)\n      Package type: Skill (SKILL.md detected)          # package_type_info (verbose)\n    └─ 3 skill(s) integrated -> .github\u002Fskills\u002F        # tree_item\n    └─ 1 prompt integrated -> .github\u002Fprompts\u002F         # tree_item\n      [!] 2 files skipped (local files exist)          # package_inline_warning (verbose)\n  [+] another-package (cached)                         # download_complete\n\n── Diagnostics ──                                      # render_summary\n  [!] 2 files skipped -- local files exist             # Grouped by category\n    Use 'apm install --force' to overwrite\n\n[*] Installed 2 APM dependencies.                      # install_summary\n```\n\nKey rules:\n- `[+]` package lines are the top-level anchors (green, no indent beyond 2-space)\n- Verbose metadata (Auth, Package type) uses 4-space indent, dim color\n- Tree items (`└─`) use 4-space indent, green color, no symbol prefix\n- Inline warnings use 4-space indent, yellow color, verbose-only\n- Diagnostics summary appears AFTER all packages, not inline (except verbose hints)\n\n### Scaling guidance\n\nAs the CLI grows, this architecture scales by:\n- **New commands**: Instantiate `CommandLogger`, use existing methods. Add subclass only if the command has distinct phases (like `InstallLogger`).\n- **New output patterns**: Add methods to `CommandLogger`. Every command benefits.\n- **New integrators**: Accept `diagnostics=` param, push to collector. No direct output.\n- **Theme changes**: Modify rendering layer (`console.py`). Zero command changes.\n- **Testing**: Mock `CommandLogger` in tests to assert semantic calls without parsing output strings.\n\n## Anti-patterns\n\n1. **Warning for non-actionable state** — If the user can't do anything about it, use `_rich_info` or defer to `--verbose`, not `_rich_warning`.\n\n2. **Inline warnings in loops** — Use `DiagnosticCollector` to collect, then render a grouped summary after the loop.\n\n3. **Missing `diagnostics` parameter** — When calling integrators, always pass `diagnostics=diagnostics` so warnings route to the deferred summary.\n\n4. **No emojis, ever** — Emojis are completely banned from all CLI output. Use ASCII text symbols from `STATUS_SYMBOLS` exclusively. This applies to messages, help text, status indicators, and table titles.\n\n5. **Inconsistent symbols** — Always use `STATUS_SYMBOLS` dict with `symbol=` param, not inline characters.\n\n6. **Walls of text** — Use Rich tables for structured data, panels for grouped content. Break up long output with visual hierarchy (indentation, `└─` tree connectors).\n\n7. **Direct `_rich_*` calls in commands** — Use `logger.start()`, `logger.progress()`, `logger.tree_item()` etc. The `_rich_*` helpers are internal to CommandLogger and console.py. Adding a `_rich_echo` call in a command file is a SoC violation.\n\n8. **Manual `if verbose:` checks** — Use `logger.verbose_detail()`, `logger.package_auth()`, or other verbose-gated methods. The logger owns the gate.\n\n9. **Manual `if dry_run:` checks** — Use `logger.should_execute` or `logger.dry_run_notice()`.\n\n10. **Format strings for indentation in commands** — Don't write `f\"    Auth: {source}\"` in command code. Use `logger.package_auth(source)` which owns the indent level. When a new indentation pattern is needed, add a method to CommandLogger.\n\n11. **Re-creating shared objects per iteration** — Expensive objects like `AuthResolver` should be created once before loops and reused per-package. The logger and diagnostics collector are already singletons per command invocation.\n\n12. **Using `logger.progress()` for tree sub-items** — `progress()` adds a `[i]` symbol prefix. Tree continuation lines (`└─`) should use `logger.tree_item()` which renders with no symbol.\n",{"name":5,"description":7},"main","2920043258932f0f67e6f01df7b9047eb42f358c",".agents\u002Fskills\u002Fcli-logging-ux",426,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm","https:\u002F\u002Fmicrosoft.github.io\u002Fapm\u002F","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-14 10:21:38",{"source":8,"skillName":5,"commands":63,"prompt":73,"zipAvailable":74},[64,67,70],{"tool":65,"command":66},"npx","npx skills add microsoft\u002Fapm --skill cli-logging-ux",{"tool":68,"command":69},"bunx","bunx skills add microsoft\u002Fapm --skill cli-logging-ux",{"tool":71,"command":72},"pnpm","pnpm dlx skills add microsoft\u002Fapm --skill cli-logging-ux","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcli-logging-ux\u002FSKILL.md",true,[76],{"path":77,"resourceType":78,"resourceTypeDesc":79,"sizeBytes":80,"sourceHtmlUrl":81},"agents\u002Fopenai.yaml","REFERENCE","参考文档",84,"https:\u002F\u002Fgithub.com\u002Fpapperrollinggery\u002Flazy-brain\u002Fblob\u002Fmain\u002Ftest\u002Ffixtures\u002Fmetadata-skill\u002Fagents\u002Fopenai.yaml",[83,92,97,103,109,114],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":87,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":91},"01M78JKQKRC85N30WT8HPN3EHM","autopilot-issue-accept","Use this skill to accept ONE microsoft\u002Fapm issue with a declared scope. The canvas Accept button, or a maintainer asking to accept an issue, starts it. Draft only from the latest triage proposed scope, get exact-text approval in this chat from a GOVERNANCE roster human, post that comment as that human, then add status\u002Faccepted. Do not invent scope, do not accept pull requests, and do not implement the issue.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002Fpackages\u002Fautopilot\u002Fautopilot-issue-accept\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":93,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":87,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":91},"01M78JK63ZWG0XX043NVHZHNH9","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fautopilot-issue-accept\u002FSKILL.md",[],[],{"skillNo":98,"name":99,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":47},"01M699JMZBYWPBT7JYWBSB95Z6","hello","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002Ftests\u002Fintegration\u002Ffixtures\u002Ftarget_resolution\u002Fshared\u002Fminimal_skill\u002F.apm\u002Fskills\u002Fhello\u002FSKILL.md",[],[99],{"skillNo":104,"name":105,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":108,"publishedAt":47},"01M699JKAMZ4DH1PYJMXHE4FG4","placeholder","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002Ftests\u002Fintegration\u002Ffixtures\u002Ftarget_resolution\u002Fs25_copilot_alias\u002F.apm\u002Fskills\u002Fplaceholder\u002FSKILL.md",[],[105],{"skillNo":110,"name":105,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":47},"01M699JHR9DKJ7BZHAPF6DZX2Z","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002Ftests\u002Fintegration\u002Ffixtures\u002Ftarget_resolution\u002Fs24_priority_override\u002F.apm\u002Fskills\u002Fplaceholder\u002FSKILL.md",[],[105],{"skillNo":115,"name":105,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":116,"categories":117,"keywords":118,"publishedAt":47},"01M699JG5BJBZSWM25F1VMJ2H6","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002Ftests\u002Fintegration\u002Ffixtures\u002Ftarget_resolution\u002Fs23_error_renderer\u002F.apm\u002Fskills\u002Fplaceholder\u002FSKILL.md",[],[105]]