CLI docs (#121)

* Start of cli docs

* Document the CLI

Also adds support for the `--config` option and `--port` option for the dev server.

* Add tests for --config and --port flags

* Add port to validateConfig

4 files changed, 43 insertions, 11 deletions

diff --git a/src/@types/astro.ts b/src/@types/astro.ts
index 4ecab847d..d991dbbcf 100644
--- a/src/@types/astro.ts
+++ b/src/@types/astro.ts
@@ -17,7 +17,23 @@ export interface AstroConfig {
   /** Public URL base (e.g. 'https://mysite.com'). Used in generating sitemaps and canonical URLs. */
   site?: string;
   /** Generate a sitemap? */
-  sitemap: boolean;
+  buildOptions: {
+    sitemap: boolean;
+  };
+  devOptions: {
+    port: number;
+    projectRoot?: string;
+  };
+}
+
+export type AstroUserConfig = Omit<AstroConfig, 'buildOptions' | 'devOptions'> & {
+  buildOptions: {
+    sitemap: boolean;
+  };
+  devOptions: {
+    port?: number;
+    projectRoot?: string;
+  };
 }
 
 export interface JsxItem {
diff --git a/src/cli.ts b/src/cli.ts
index c56a4c098..be0dfe27a 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -20,14 +20,20 @@ type cliCommand = 'help' | 'version' | 'dev' | 'build';
 interface CLIState {
   cmd: cliCommand;
   options: {
+    projectRoot?: string;
     sitemap?: boolean;
+    port?: number;
+    config?: string;
   };
 }
 
 /** Determine which action the user requested */
 function resolveArgs(flags: Arguments): CLIState {
   const options: CLIState['options'] = {
+    projectRoot: typeof flags.projectRoot === 'string' ? flags.projectRoot: undefined,
     sitemap: typeof flags.sitemap === 'boolean' ? flags.sitemap : undefined,
+    port: typeof flags.port === 'number' ? flags.port : undefined,
+    config: typeof flags.config === 'string' ? flags.config : undefined
   };
 
   if (flags.version) {
@@ -52,13 +58,15 @@ function printHelp() {
   console.error(`  ${colors.bold('astro')} - Futuristic web development tool.
 
   ${colors.bold('Commands:')}
-  astro dev         Run Astro in development mode.
-  astro build       Build a pre-compiled production version of your site.
+  astro dev             Run Astro in development mode.
+  astro build           Build a pre-compiled production version of your site.
 
   ${colors.bold('Flags:')}
-  --version         Show the version number and exit.
-  --help            Show this help message.
+  --config <path>       Specify the path to the Astro config file.
+  --project-root <path> Specify the path to the project root folder.
   --no-sitemap      Disable sitemap generation (build only).
+  --version             Show the version number and exit.
+  --help                Show this help message.
 `);
 }
 
@@ -70,14 +78,17 @@ async function printVersion() {
 
 /** Merge CLI flags & config options (CLI flags take priority) */
 function mergeCLIFlags(astroConfig: AstroConfig, flags: CLIState['options']) {
-  if (typeof flags.sitemap === 'boolean') astroConfig.sitemap = flags.sitemap;
+  if (typeof flags.sitemap === 'boolean') astroConfig.buildOptions.sitemap = flags.sitemap;
+  if (typeof flags.port === 'number') astroConfig.devOptions.port = flags.port;
 }
 
 /** Handle `astro run` command */
 async function runCommand(rawRoot: string, cmd: (a: AstroConfig) => Promise<void>, options: CLIState['options']) {
   try {
-    const astroConfig = await loadConfig(rawRoot);
+    const projectRoot = options.projectRoot || rawRoot;
+    const astroConfig = await loadConfig(projectRoot, options.config);
     mergeCLIFlags(astroConfig, options);
+
     return cmd(astroConfig);
   } catch (err) {
     console.error(colors.red(err.toString() || err));
diff --git a/src/config.ts b/src/config.ts
index 937499923..af618a27f 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -24,6 +24,10 @@ function validateConfig(config: any): void {
       throw new Error(`[astro config] ${key}: ${JSON.stringify(config[key])}\n  Expected boolean, received ${type(config[key])}.`);
     }
   }
+
+  if(config.devOptions?.port !== 'number') {
+    throw new Error(`[astro config] devOptions.port: Expected number, received ${type(config.devOptions?.port)}`)
+  }
 }
 
 /** Set default config values */
@@ -34,7 +38,8 @@ function configDefaults(userConfig?: any): any {
   if (!config.astroRoot) config.astroRoot = './astro';
   if (!config.dist) config.dist = './_site';
   if (!config.public) config.public = './public';
-
+  if (!config.devOptions) config.devOptions = {};
+  if (!config.devOptions.port) config.devOptions.port = 3000;
   if (typeof config.sitemap === 'undefined') config.sitemap = true;
 
   return config;
@@ -53,13 +58,13 @@ function normalizeConfig(userConfig: any, root: string): AstroConfig {
 }
 
 /** Attempt to load an `astro.config.mjs` file */
-export async function loadConfig(rawRoot: string | undefined): Promise<AstroConfig> {
+export async function loadConfig(rawRoot: string | undefined, configFileName = 'astro.config.mjs'): Promise<AstroConfig> {
   if (typeof rawRoot === 'undefined') {
     rawRoot = process.cwd();
   }
 
   const root = pathResolve(rawRoot);
-  const astroConfigPath = pathJoin(root, 'astro.config.mjs');
+  const astroConfigPath = pathJoin(root, configFileName);
 
   // load
   let config: any;
diff --git a/src/dev.ts b/src/dev.ts
index 8c4140259..8f93aabf6 100644
--- a/src/dev.ts
+++ b/src/dev.ts
@@ -8,7 +8,6 @@ import { defaultLogDestination, error, parseError } from './logger.js';
 import { createRuntime } from './runtime.js';
 
 const hostname = '127.0.0.1';
-const port = 3000;
 
 // Disable snowpack from writing to stdout/err.
 snowpackLogger.level = 'silent';
@@ -65,6 +64,7 @@ export default async function dev(astroConfig: AstroConfig) {
     }
   });
 
+  const port = astroConfig.devOptions.port;
   server.listen(port, hostname, () => {
     // eslint-disable-next-line no-console
     console.log(`Server running at http://${hostname}:${port}/`);