[Crane: crane-migration-python-to-go-full-apm-cli-rewrite] Iteration 27: Add real Python-vs-Go stdout comparison tests and fix help text parity

- Add cmd/apm/parity_stdout_test.go: 35 TestParityStdout* tests comparing
  Python vs Go stdout for all 13 commands with identical help text
- Fix preview command to return exit 1 when script not found (parity with Python)
- Fix printCmdHelp: correct positional arg signatures for 8 commands
- Fix multi-line description rendering and --help option sourcing
- Update cmdmeta.go: complete Python-matching option sets for 13 commands
- Update/create golden test fixtures for 9 commands
- Update TestParityHarnessPreviewInTempRepo to use yaml with build script
- Document 17 approved Python-vs-Go output format exceptions
- Score: migration_score=1.0 (675/675 parity tests passing)

Run: https://github.com/githubnext/apm/actions/runs/26543455081

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: github-actions[bot]

cmd/apm/cmd_simple.go

@@ -174,6 +174,10 @@ func runPreview(args []string) int {
 		return 1
 	}
 	fmt.Printf("[*] Previewing script '%s' in project '%s'\n", script, proj.Name)
+	if _, ok := proj.Scripts[script]; !ok {
+		fmt.Fprintf(os.Stderr, "[x] Script '%s' not found\n", script)
+		return 1
+	}
 	fmt.Println("[i] No compiled output available.")
 	return 0
 }

cmd/apm/cmdmeta.go

@@ -12,7 +12,7 @@ var commandFullDesc = map[string]string{
 	"deps":     "Manage APM package dependencies",
 	"experimental": "Manage experimental feature flags",
 	"init":     "Initialize a new APM project",
-	"install":  "Install APM and MCP dependencies (supports APM packages, Claude skills\n  (SKILL.md), and plugin collections (plugin.json); auto-creates apm.yml; use\n  --allow-insecure for http:// packages)",
+	"install":  "Install APM and MCP dependencies (supports APM packages, Claude skills\n(SKILL.md), and plugin collections (plugin.json); auto-creates apm.yml; use\n--allow-insecure for http:// packages)",
 	"list":     "List available scripts in the current project",
 	"marketplace": "Manage marketplaces for discovery and governance",
 	"mcp":      "Discover, inspect, and install MCP servers",
@@ -26,15 +26,15 @@ var commandFullDesc = map[string]string{
 	"runtime":  "Manage AI runtimes (experimental)",
 	"search":   "Search plugins in a marketplace (QUERY@MARKETPLACE)",
 	"self-update": "Update the APM CLI binary itself to the latest version",
-	"targets":  "Show resolved targets for the current project.",
+	"targets":  "Show resolved targets for the current project. If APM detects a target you\ndon't intend (e.g. CLAUDE.md is documentation, not a Claude Code config),\npin your targets explicitly in apm.yml.",
 	"uninstall": "Remove APM packages, their integrated files, and apm.yml entries",
-	"unpack":   "[Deprecated] Extract an APM bundle into the current project.",
+	"unpack":   "[Deprecated] Extract an APM bundle into the current project. Use 'apm\ninstall <bundle-path>' instead -- this command will be removed in v0.14.",
 	"update":   "Refresh APM dependencies to the latest matching refs",
-	"view":     "View package metadata or list remote versions.",
+	"view": "View package metadata or list remote versions.\n\nWithout FIELD, displays local metadata for an installed package. With FIELD,\nqueries specific data (may contact the remote).\n\nFields:\n    versions    List available remote tags and branches\n\nExamples:\n    apm view org/repo                # Local metadata\n    apm view org/repo versions       # Remote tags/branches\n    apm view org/repo -g             # From user scope",
 }
 
 // commandOptions provides key options for each command, matching Python CLI help.
-// Only the most commonly referenced options are listed; --help is added by printCmdHelp.
+// Each entry includes the --help line with correct alignment (matching Click's output).
 var commandOptions = map[string][]string{
 	"compile": {
 		"  -o, --output TEXT   Output file path (for single-file mode)",
@@ -46,6 +46,7 @@ var commandOptions = map[string][]string{
 		"  --clean             Remove orphaned AGENTS.md files",
 		"  --all               Compile for all canonical targets",
 		"  -v, --verbose       Show detailed source attribution",
+		"  --help              Show this message and exit.",
 	},
 	"install": {
 		"  --runtime TEXT      Target specific runtime only",
@@ -66,34 +67,100 @@ var commandOptions = map[string][]string{
 		"  --refresh           Bypass the persistent cache and re-fetch all dependencies",
 		"  --dev               Install as development dependency",
 		"  --allow-insecure    Allow HTTP (insecure) dependencies",
+		"  --help              Show this message and exit.",
 	},
 	"init": {
-		"  -y, --yes   Skip interactive prompts and use auto-detected defaults",
+		"  -y, --yes        Skip interactive prompts and use auto-detected defaults",
+		"  --plugin         (deprecated) Use 'apm plugin init' instead. Scaffolds",
+		"                   plugin.json + apm.yml.",
+		"  --marketplace    (deprecated) Use 'apm marketplace init' instead. Seeds a",
+		"                   marketplace block.",
+		"  --target TARGET  Comma-separated target list (skip prompt, write directly)",
+		"  -v, --verbose    Show detailed output",
+		"  --help           Show this message and exit.",
 	},
 	"update": {
-		"  --yes          Apply updates without interactive confirmation",
-		"  --dry-run      Show what would be updated without applying",
-		"  -v, --verbose  Show detailed update information",
-		"  -t, --target TARGET  Target harness(es) to deploy to",
+		"  -y, --yes            Skip the confirmation prompt (for CI / automation)",
+		"  --dry-run            Render the update plan and exit without changing",
+		"                       anything",
+		"  -v, --verbose        Show unchanged deps and detailed pipeline diagnostics",
+		"  -t, --target TARGET  Agent target(s) to update for (e.g. claude, copilot,",
+		"                       cursor, windsurf, codex, opencode, gemini). Comma-",
+		"                       separated for multiple: --target claude,cursor.",
+		"                       Highest-priority entry in the resolution chain",
+		"                       (--target > apm.yml targets: > auto-detect).",
+		"  --help               Show this message and exit.",
 	},
 	"audit": {
-		"  --ci       Exit non-zero if any issues are found (CI mode)",
-		"  --verbose  Show detailed audit information",
+		"  --file PATH                     Scan an arbitrary file (not just APM-managed",
+		"                                  files)",
+		"  --strip                         Remove hidden characters from scanned files",
+		"                                  (preserves emoji and whitespace)",
+		"  -v, --verbose                   Show all findings including harmless ones",
+		"  --dry-run                       Preview what --strip would remove without",
+		"                                  modifying files",
+		"  -f, --format [text|json|sarif|markdown]",
+		"                                  Output format: text (default), json, sarif",
+		"                                  (GitHub Code Scanning), markdown (step",
+		"                                  summaries).",
+		"  -o, --output PATH               Write output to file (auto-detects format",
+		"                                  from extension: .sarif, .json, .md).",
+		"  --ci                            Run lockfile consistency checks for CI/CD",
+		"                                  gates. Exit 0 if clean, 1 if violations",
+		"                                  found.",
+		"  --policy TEXT                   Policy source. Accepts: 'org' (auto-discover",
+		"                                  from your project's git remote),",
+		"                                  'owner/repo' (defaults to github.com), an",
+		"                                  https:// URL, or a local file path. Used",
+		"                                  with --ci for policy checks. [experimental]",
+		"  --no-cache                      Force fresh policy fetch (skip cache).",
+		"  --no-policy                     Skip org policy discovery and enforcement.",
+		"                                  Overridden when --policy is passed",
+		"                                  explicitly.",
+		"  --no-fail-fast                  Run all checks even after a failure",
+		"                                  (default: stop at first failure).",
+		"  --no-drift                      Skip the install-replay drift check. Reduces",
+		"                                  coverage; use only for performance-",
+		"                                  constrained CI loops.",
+		"  --help                          Show this message and exit.",
 	},
 	"view": {
-		"  --versions  List all available versions",
-		"  --json      Output as JSON",
+		"  -g, --global  Inspect package from user scope (~/.apm/)",
+		"  --help        Show this message and exit.",
+	},
+	"search": {
+		"  --limit INTEGER  Max results to show  [default: 20]",
+		"  -v, --verbose    Show detailed output",
+		"  --help           Show this message and exit.",
 	},
 	"uninstall": {
-		"  --dry-run  Show what would be removed without removing",
-		"  -g, --global  Uninstall from user scope (~/.apm/)",
+		"  --dry-run      Show what would be removed without removing",
+		"  -v, --verbose  Show detailed removal information",
+		"  -g, --global   Remove from user scope (~/.apm/) instead of the current",
+		"                 project",
+		"  --help         Show this message and exit.",
+	},
+	"unpack": {
+		"  -o, --output PATH  Target directory (default: current directory).",
+		"  --skip-verify      Skip bundle completeness check.",
+		"  --dry-run          Show what would be unpacked without writing",
+		"  --force            Deploy despite critical hidden-character findings.",
+		"  -v, --verbose      Show detailed unpacking information",
+		"  --help             Show this message and exit.",
+	},
+	"run": {
+		"  -p, --param TEXT  Parameter in format name=value",
+		"  -v, --verbose     Show detailed output",
+		"  --help            Show this message and exit.",
 	},
 	"list": {
-		"  --json     Output as JSON",
+		"  --help  Show this message and exit.",
 	},
 	"targets": {
 		"  --json  Output as JSON instead of a table.",
-		"  --all   Include the agent-skills meta-target in JSON output (excluded by default).",
+		"  --all   Include the agent-skills meta-target in JSON output (excluded by",
+		"          default).",
+		"  --help  Show this message and exit.",
 	},
 	"cache": {
 		"  --help  Show this message and exit.",
@@ -112,8 +179,6 @@ var commandOptions = map[string][]string{
 		"  -o, --output PATH  Bundle output directory (default: ./build).",
 		"  --json             Emit machine-readable JSON to stdout.",
 		"  -v, --verbose      Show detailed packing information.",
-	},
-	"unpack": {
-		"  --help  Show this message and exit.",
+		"  --help             Show this message and exit.",
 	},
 }

cmd/apm/main.go

@@ -98,24 +98,47 @@ func printCmdHelp(name string) {
 		fullDesc = desc
 	}
 	fmt.Printf("Usage: apm %s [OPTIONS]", canonical)
-	// Commands with positional args.
+	// Commands with positional args -- match Python CLI usage strings exactly.
 	switch canonical {
-	case "install", "uninstall", "view", "search", "run":
-		fmt.Printf(" [ARGS]...")
+	case "install":
+		fmt.Printf(" [PACKAGES]...")
+	case "uninstall":
+		fmt.Printf(" PACKAGES...")
+	case "view":
+		fmt.Printf(" PACKAGE [FIELD]")
+	case "search":
+		fmt.Printf(" QUERY@MARKETPLACE")
+	case "run":
+		fmt.Printf(" [SCRIPT_NAME]")
+	case "audit":
+		fmt.Printf(" [PACKAGE]")
+	case "unpack":
+		fmt.Printf(" BUNDLE_PATH")
 	case "init":
 		fmt.Printf(" [PROJECT_NAME]")
+	case "targets":
+		fmt.Printf(" COMMAND [ARGS]...")
 	}
 	fmt.Println()
 	fmt.Println()
-	fmt.Printf("  %s\n", fullDesc)
+	// Print full description: indent each line with two spaces.
+	for _, line := range strings.Split(fullDesc, "\n") {
+		if line == "" {
+			fmt.Println()
+		} else {
+			fmt.Printf("  %s\n", line)
+		}
+	}
 	fmt.Println()
 	fmt.Println("Options:")
 	if opts, ok := commandOptions[canonical]; ok {
 		for _, opt := range opts {
 			fmt.Println(opt)
 		}
+	} else {
+		// Default: only --help option.
+		fmt.Println("  --help  Show this message and exit.")
 	}
-	fmt.Println("  --help  Show this message and exit.")
 }
 
 func run(args []string) int {

cmd/apm/parity_new_commands_test.go

@@ -365,7 +365,19 @@ func TestParityHarnessPreviewMissingArg(t *testing.T) {
 }
 
 func TestParityHarnessPreviewInTempRepo(t *testing.T) {
-	r := runBothInTempRepo(t, minimalApmYML, "preview", "build")
+	apmYML := `name: test-project
+version: 1.0.0
+description: Parity test project
+author: crane-test
+targets:
+  - copilot
+dependencies:
+  apm: []
+  mcp: []
+scripts:
+  build: echo build
+`
+	r := runBothInTempRepo(t, apmYML, "preview", "build")
 	if r.GoExitCode != 0 {
 		t.Errorf("apm preview build exited %d\nstderr: %s", r.GoExitCode, r.GoStderr)
 	}