feat: compose templates and new devx template (#9)

- Adds the ability to compose templates via `extend` keyword in manifest files.
- Composed templates compose by merging their files and dependencies.
- Broke out shared parts of template into `base` template.
- Refactored `default` to extend `base`.
- Added new `devx-experimental` template which extends `base`.

Co-authored-by: Tyler van Hensbergen <tyler@functionless.org>

Author: tvanhens

src/index.ts

@@ -7,6 +7,7 @@ import mustache from "mustache";
 import path from "path";
 
 import packageJson from "../package.json";
+import { loadTemplatePlan } from "./plan";
 import {
   askProjectName,
   failOnError,
@@ -17,15 +18,23 @@ import {
 const program = new Command();
 
 let projectName: string | undefined;
+let templateName = "default";
 
 program
   .name(packageJson.name)
   .version(packageJson.version)
   .arguments("[projectName]")
-  .action((name) => {
+  .option(
+    "-t --template [templateName]",
+    "name of the template to use [default]"
+  )
+  .action((name, options) => {
     if (typeof name === "string") {
       projectName = name;
     }
+    if (typeof options.template === "string") {
+      templateName = options.template;
+    }
   })
   .parse(process.argv);
 
@@ -37,12 +46,7 @@ run().catch((err) => {
 async function run() {
   const packageMangager = getPackageManager();
 
-  const templateName = "default";
-  const templateRoot = path.join(__dirname, "..", "templates", templateName);
-  const templateManifestPath = path.join(templateRoot, "manifest.json");
-  const templateManifest: string[] = JSON.parse(
-    await fs.promises.readFile(templateManifestPath, "utf-8")
-  );
+  const templatePlan = await loadTemplatePlan(templateName);
 
   if (!projectName) {
     projectName = await askProjectName();
@@ -63,12 +67,12 @@ async function run() {
   }
 
   const renderTemplate = async (
+    sourcePath: string,
     localPath: string,
     data: Record<string, unknown>
   ) => {
-    const templateFilePath = path.join(templateRoot, localPath);
     const templateContent = mustache.render(
-      await fs.promises.readFile(templateFilePath, "utf-8"),
+      await fs.promises.readFile(sourcePath, "utf-8"),
       data
     );
     // Npm won't include `.gitignore` files in a package.
@@ -86,34 +90,19 @@ async function run() {
     projectName,
   };
 
-  await Promise.all(
-    templateManifest.map((path) => renderTemplate(path, templateData))
-  );
+  for (const mapping of templatePlan.fileMappings) {
+    // Sequential because order of file rendering matters
+    // for templates that extend other templates.
+    await renderTemplate(mapping.sourcePath, mapping.localPath, templateData);
+  }
 
   process.chdir(root);
 
   console.log();
   console.log("Installing packages...");
   console.log();
 
-  const dependencies = [
-    "@aws-cdk/aws-appsync-alpha",
-    "@functionless/ast-reflection",
-    "@functionless/language-service",
-    "@types/jest",
-    "@types/node",
-    "aws-cdk",
-    "aws-cdk-lib",
-    "aws-sdk",
-    "constructs",
-    "esbuild",
-    "functionless",
-    "jest",
-    "typesafe-dynamodb",
-    "typescript",
-  ];
-
-  installPackages(packageMangager, dependencies);
+  installPackages(packageMangager, templatePlan.devDependencies);
 
   console.log();
   console.log("Initializing git repository...");

src/plan.ts

@@ -0,0 +1,70 @@
+import path from "path";
+import fs from "fs";
+
+interface TemplateManifest {
+  root: string;
+  extend?: string;
+  devDependencies?: string[];
+  files?: string[];
+}
+
+interface FileMapping {
+  sourcePath: string;
+  localPath: string;
+}
+
+interface TemplatePlan {
+  devDependencies: string[];
+  fileMappings: FileMapping[];
+}
+
+async function loadTemplateManifest(templateName: string) {
+  const templateRoot = path.join(__dirname, "..", "templates", templateName);
+  const templateManifestPath = path.join(templateRoot, "manifest.json");
+  try {
+    const templateManifest: TemplateManifest = {
+      ...JSON.parse(await fs.promises.readFile(templateManifestPath, "utf-8")),
+      root: templateRoot,
+    };
+    return templateManifest;
+  } catch (err) {
+    throw new Error(`Unable to load template: ${templateName}`);
+  }
+}
+
+function applyManifest(
+  plan: TemplatePlan,
+  manifest: TemplateManifest
+): TemplatePlan {
+  return {
+    devDependencies: [
+      ...plan.devDependencies,
+      ...(manifest.devDependencies ?? []),
+    ],
+    fileMappings: [
+      ...plan.fileMappings,
+      ...(manifest.files?.map((filePath) => {
+        return {
+          sourcePath: path.join(manifest.root, filePath),
+          localPath: filePath,
+        };
+      }) ?? []),
+    ],
+  };
+}
+
+export async function loadTemplatePlan(templateName: string) {
+  let generatedPlan: TemplatePlan = {
+    devDependencies: [],
+    fileMappings: [],
+  };
+  const targetManifest = await loadTemplateManifest(templateName);
+
+  if (targetManifest.extend) {
+    const baseManifest = await loadTemplateManifest(targetManifest.extend);
+
+    generatedPlan = applyManifest(generatedPlan, baseManifest);
+  }
+
+  return applyManifest(generatedPlan, targetManifest);
+}

templates/default/.gitignore.template renamed to templates/base/.gitignore.template

@@ -0,0 +1,24 @@
+{
+  "devDependencies": [
+    "@aws-cdk/aws-appsync-alpha",
+    "@functionless/ast-reflection",
+    "@functionless/language-service",
+    "@types/jest",
+    "@types/node",
+    "aws-cdk",
+    "aws-cdk-lib",
+    "aws-sdk",
+    "constructs",
+    "esbuild",
+    "functionless",
+    "jest",
+    "typesafe-dynamodb",
+    "typescript"
+  ],
+  "files": [
+    "package.json",
+    "cdk.json",
+    "tsconfig.json",
+    ".gitignore.template"
+  ]
+}

templates/default/cdk.json renamed to templates/base/cdk.json

@@ -1,7 +1,6 @@
-[
-  "package.json",
-  "cdk.json",
-  "tsconfig.json",
-  ".gitignore.template",
-  "src/app.ts"
-]
+{
+  "extend": "base",
+  "files": [
+    "src/app.ts"
+  ]
+}

templates/base/manifest.json

@@ -0,0 +1,3 @@
+{
+  "app": "fl-exp cdk-synth"
+}

templates/default/package.json renamed to templates/base/package.json

@@ -0,0 +1,5 @@
+{
+  "extend": "base",
+  "devDependencies": ["fl-exp"],
+  "files": ["cdk.json", "src/my-stack/_stack.ts"]
+}