[SalesForce] Deploy/retrieve lightning community page variations with metadata API

DOH! It was a PEBKAC error.

The 4 metadata XML files were indeed missing from source control and my local src folder that the Force.com migration tool was pointed at. I was getting confused with MavensMate pointing at a different directory that had directly pulled metadata from the project rather than source control.

I'll leave this Q&A here as there aren't many search results coming up for

"Error: Must specify the metadata file"

I'll try to answer this question in part by adding some historical context and also by framing it in terms of User context and an evolving Lightning framework. The answer to your question isn't a simple answer that only involves a single context.

First, as we all are hopefully aware, the Lightning framework itself is still evolving and isn't completely defined. We'll be seeing more of it further defined and more changes to come with the SP16 Release. With that release there will be new functionalities and I wouldn't be surprised to see some things deprecated as we saw with the release of W16. In essence, the platform is incomplete and, for all practical purposes, is in what many would consider a "public beta".

Next, to develop Lightning components, the only tool available from the start has been the Developer Console. Components can be bundled into a single page "App" for use in Salesforce 1 mobile. When that happens, the "wrapper" they're put in is called a "Lightning app". Off-hand, I believe those apps can be used as mobile pages or as components in the App Builder as part of a Flexipage. Why it was done that way, is somewhat beyond me. It's unfortunate that this terminology got intermixed and creates such confusion.

Now we come to the Lightning App Builder. This UI was originally created for developers and admins so they could take standard and custom components, then drag and drop them on a page layout, while designing page mark-ups from which they could create applications to run in Salesforce Mobile as Lightning Pages/Applications. It's a multi-page size WYSIWYG type of GUI that helps avoid some of the coding that would otherwise be necessary if all the work were done in the Developer Console. It uses the Lightning Design System where Grids change the CSS that's applied to accommodate different page sizes. Thus, the reason it creates what are called flexipages.

Community Builder is there for a reason. If you're building a community, you're creating pages for a specific namespace: the one that your Community resides in. You can create components from the Developer Console that are enabled for Communities using aura:component implements="forceCommunity:availableForAllPageTypes" See Make Your Lightning Components Available For Communities from the W16 Release notes for more on this.

Further down on the aforementioned page, you'll see "Add a Design Resource to Your Component Bundle". You can mark your resource with access="global" to make the resource usable outside of your own org if you want it to be in an installed package or used either by a Lightning App Builder user or a Community Builder user in another org simply by adding a Design Resource to Your Component Bundle. A design resource describes the design-time behavior of Lightning component—information that visual tools need to allow adding the component to a page or app. A design resource supports only attributes of type int, string, or boolean. Design resources must be named componentName.design. Of most importance to your question, an attribute marked as required in the component definition automatically appears for users in the Community Builder, unless it has a default value assigned to it.

If you're building a Community, it's essential to have the ability to set attributes on Lightning Components you might use in those pages. You certainly don't want to be going into the Developer Console to try and edit them; something a page designer can't possibly do if the components are from a managed package.

As you can readily see, there's a rhyme and a reason for Salesforce to have all of these tools available. They each have a purpose and a use. It's also important that users with different skill sets or needs have tools available to them that suit their use cases. To make an analogy, not everyone needs Photoshop, yet graphic artists would be very limited in what they can do if they were limited to only having the default Windows Paint program available to them. Another analogy would be Notepad or Wordpad vs a full featured Editor like MS Office Word, Corel Wordperfect or LibreOffice. There are those of us who use Eclipse with the Force.com IDE or Sublime Text with MavensMate instead of the Developer Console. We all use tools that suit our needs and purposes. All the tools you've mentioned have a different purpose and serve a different audience.