Add TypeScript checking via JSDoc type annotations

.gitignore

@@ -1,2 +1,3 @@
+.DS_Store
 output/
 node_modules/

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+  "typescript.preferences.importModuleSpecifier": "relative",
+  "typescript.preferences.importModuleSpecifierEnding": "auto",
+  "typescript.preferences.quoteStyle": "single",
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+}

package.json

@@ -1,4 +1,5 @@
 {
+  "name": "outline-app-maker",
   "dependencies": {
     "@ngrok/ngrok": "1.4.1",
     "archiver": "^7.0.1",
@@ -9,9 +10,12 @@
     "yaml": "^2.7.1"
   },
   "devDependencies": {
+    "@types/archiver": "^6.0.3",
+    "@types/minimist": "^1.2.5",
     "glob": "^11.0.1",
     "handlebars": "^4.7.8",
-    "vite": "^6.2.7"
+    "typescript": "^5.8.3",
+    "vite": "^6.2.0"
   },
   "license": "Apache-2.0",
   "scripts": {
@@ -20,7 +24,8 @@
     "clean": "npx rimraf node_modules/ output/",
     "doctor": "./doctor",
     "reset": "npm run clean && npm ci",
-    "start:navigator": "node ./basic_navigator_example/.scripts/start.mjs"
+    "start:navigator": "node ./basic_navigator_example/.scripts/start.mjs",
+    "typescript:check": "tsc --noEmit"
   },
   "private": true
 }

tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "noEmit": true,
+    "module": "node16",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "**/*.cjs",
+    "**/*.mjs",
+    "**/*.js",
+    "**/.*/**/*.cjs",
+    "**/.*/**/*.mjs",
+    "**/.*/**/*.js",
+  ],
+  "exclude": [
+    "basic_navigator_example", // TODO: Remove this exclusion?
+    "node_modules",
+    "output"
+  ]
+}

wrapper_app_project/.scripts/build.mjs

@@ -21,8 +21,8 @@ import chalk from 'chalk'
 import { glob } from 'glob'
 import handlebars from 'handlebars'
 
-import { getCliConfig, getYAMLFileConfig, DEFAULT_CONFIG } from './config.mjs'
-import { resolveConfiguration, zip } from './util.mjs'
+import { getCliConfig, getYAMLFileConfig, DEFAULT_CONFIG, validateAndNormalizeConfig } from './config.mjs'
+import { compress } from './zip.mjs'
 
 const TEMPLATE_DIR = path.join(process.cwd(), 'wrapper_app_project/template');
 
@@ -32,7 +32,7 @@ if (import.meta.url !== pathToFileURL(`${process.argv[1]}`).href) {
   throw new Error('Build script must be run from the cli')
 }
 
-const config = resolveConfiguration({
+const config = validateAndNormalizeConfig({
   ...DEFAULT_CONFIG,
   ...(await getYAMLFileConfig('config.yaml')),
   ...getCliConfig(process.argv)
@@ -88,7 +88,7 @@ await promisify(exec)(`
 `)
 
 console.log(chalk.green(`Zipping project to ${chalk.blue(APP_TARGET_ZIP)}...`))
-await zip(APP_TARGET_DIR, APP_TARGET_ZIP)
+await compress(APP_TARGET_DIR, APP_TARGET_ZIP)
 
 console.log(chalk.bgGreen('Project ready!'))
 

wrapper_app_project/.scripts/config.mjs

@@ -5,6 +5,19 @@ import minimist from 'minimist'
 import YAML from 'yaml'
 
 
+/**
+ * @typedef {{
+ *   additionalDomains: Array<string>;
+ *   appId: string;
+ *   appName: string;
+ *   domainList: string;
+ *   entryDomain: string;
+ *   output: string;
+ *   platform: string;
+ *   smartDialerConfig: string;
+ * }} Config
+ */
+
 export const DEFAULT_CONFIG = {
   output: path.join(process.cwd(), 'output'),
   smartDialerConfig: JSON.stringify({
@@ -22,24 +35,103 @@ export const DEFAULT_CONFIG = {
   })
 }
 
+/**
+ * Parse a provided YAML file, returning an object.
+ *
+ * If the YAML file doesn't parse as an object (e.g. if it contains a primitive
+ * or sequence/list) an empty object will be returned instead (and a warning
+ * will be output).
+ *
+ * @param {string} filepath
+ * @returns {Promise<{}>}
+ */
 export async function getYAMLFileConfig(filepath) {
   try {
     const data = await fs.readFile(filepath, 'utf8')
 
     if (data) {
-      return YAML.parse(data)
+      const parsedData = YAML.parse(data);
+
+      if (parsedData && typeof parsedData === 'object' && !Array.isArray(parsedData)) {
+        // This type assertion may not be 100% guaranteed but for the purposes
+        // of this use case should be correct
+        return /** @type {{}} */ (parsedData);
+      } else {
+        console.warn(`${filepath} contained invalid config data:`, parsedData)
+      }
+    } else {
+      console.warn(`${filepath} contained no data`)
     }
   } catch (e) {
-    if ('ENOENT' == e.code) {
-      return {}
-    }
+    console.warn(`Error loading ${filepath}:`, e)
   }
+
+  return {};
 }
 
+/**
+ * @param {NodeJS.Process["argv"]} args
+ */
 export function getCliConfig(args) {
   const dict = minimist(args)
   return {
     ...dict,
     additionalDomains: dict.additionalDomains?.split(',') ?? []
   }
-}
+}
+
+/**
+ * Validate and normalize a provided (unknown) config, throwing an error if
+ * required parameters are missing.
+ *
+ * @param {Record<string, unknown>} inputConfig
+ * @returns {Config}
+ */
+export function validateAndNormalizeConfig(inputConfig) {
+  const resolvedConfig = {};
+
+  if (typeof inputConfig.entryUrl !== "string") {
+    throw new Error(`"entryUrl" parameter not provided in parameters or YAML configuration.`);
+  }
+  if (typeof inputConfig.platform !== "string") {
+    throw new Error(`"platform" parameter not provided in parameters or YAML configuration.`);
+  }
+
+  resolvedConfig.entryDomain = new URL(inputConfig.entryUrl).hostname;
+  resolvedConfig.output = new URL(inputConfig.entryUrl).hostname;
+  resolvedConfig.platform = inputConfig.platform;
+
+
+  resolvedConfig.appId = typeof inputConfig.appId === "string"
+    ? inputConfig.appId
+    // Infer an app ID from the entry domain by reversing it (e.g. `www.example.com` becomes `com.example.www`)
+    // It must be lower case, and hyphens are not allowed.
+    : resolvedConfig.entryDomain
+      .replaceAll('-', '')
+      .toLocaleLowerCase()
+      .split('.')
+      .reverse()
+      .join('.')
+
+  if (!inputConfig.appName) {
+    // Infer an app name from the base entry domain part by title casing the root domain:
+    // (e.g. `www.my-example-app.com` becomes "My Example App")
+    resolvedConfig.appName = resolvedConfig.entryDomain
+      .split('.')
+      .reverse()[1]
+      .split(/[-_]+/)
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+      .join(' ')
+  }
+
+  resolvedConfig.additionalDomains = (
+    Array.isArray(inputConfig.additionaldomain) &&
+    inputConfig.additionaldomain.every((item) => typeof item === "string")
+  )
+    ? inputConfig.additionaldomain
+    : []
+  resolvedConfig.domainList = [resolvedConfig.entryDomain, ...resolvedConfig.additionalDomains].join('\n')
+  resolvedConfig.smartDialerConfig = Buffer.from(JSON.stringify(inputConfig.smartDialerConfig)).toString('base64')
+
+  return resolvedConfig;
+}