mlcl 1.0.0

package/src/environment.ts

@@ -0,0 +1,88 @@
+/**
+ * This module helps with various sets of environment variables,
+ * using both `dotenv` and `env-cmd`.
+ * 
+ * The `.env` file will be loaded via `dotenv.config()` and extended
+ * by the variables for the `NODE_ENV` key specified in `.env-cmdrc.json`.
+ * 
+ * This also allows you to combine various sets of env vars using e.g.:
+ * ```
+ * ./node_modules/.bin/env-cmd -e development,something,etc npm run dev
+ * ```
+ * 
+ * @see https://www.npmjs.com/package/dotenv
+ * @see https://www.npmjs.com/package/env-cmd
+ * 
+ * @module
+ */
+
+import 'dotenv/config'
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { pkg } from './pkg.js'
+
+const __dirname = fileURLToPath(path.dirname(import.meta.url))
+
+const defaultEnv = {
+  APP_ID: `mlcl`,
+  APP_NAME: pkg.name,
+  APP_VERSION: pkg.version,
+  APP_PLATFORM: `cli`,
+  API_ORIGIN: `https://api.molecule.dev`,
+  WEB_ORIGIN: `https://assemble.molecule.dev`,
+  LOG_LEVEL: `info`,
+}
+
+const defaultEnvCmdrc = {
+  'development': {
+    NODE_ENV: 'development',
+    API_ORIGIN: 'http://localhost:4000',
+    WEB_ORIGIN: 'http://localhost:3000',
+  },
+  'production': {
+    NODE_ENV: 'production',
+    API_ORIGIN: 'https://api.molecule.dev',
+    WEB_ORIGIN: 'https://assemble.molecule.dev',
+  },
+  'test': {
+    NODE_ENV: 'test',
+    LOG_LEVEL: 'silent',
+    API_ORIGIN: 'http://localhost:4000',
+    WEB_ORIGIN: 'http://localhost:3000',
+  }
+}
+
+if (!process.env.NODE_ENV) {
+  process.env.NODE_ENV = `production`
+}
+
+for (const key in defaultEnv) {
+  process.env[key] = defaultEnv[key]
+}
+
+/**
+ * Sets the variables specified within each environment within `.env-cmdrc.json`.
+ */
+export const setVariables = (environments: string[] = [ process.env.NODE_ENV || `production` ]) => {
+  try {
+    const envCmdrcPath = path.join(__dirname, '../.env-cmdrc.json')
+    const envCmdrc = fs.existsSync(envCmdrcPath)
+      ? JSON.parse(fs.readFileSync(envCmdrcPath, 'utf8'))
+      : defaultEnvCmdrc
+
+    for (const environment of environments) {
+      const variables = envCmdrc[environment]
+
+      if (variables) {
+        Object.assign(process.env, variables)
+      } else {
+        console.warn(`Environment "${environment}" not found within .env-cmdrc.`)
+      }
+    }
+  } catch (error) {
+  }
+}
+
+// Extend the environment variables using `.env-cmdrc.json`.
+setVariables()

package/src/index.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+/**
+ * Molecule.dev command line tools.
+ * 
+ * @module
+ */
+
+import './environment.js'
+import { program } from 'commander'
+import * as commands from './commands/index.js'
+
+export * as API from './API/index.js'
+export * as commands from './commands/index.js'
+export * as utilities from './utilities/index.js'
+
+export * from './logger.js'
+export * from './pkg.js'
+export * from './repoConfig.js'
+export * from './userConfig.js'
+
+export * as types from './types/index.js'
+
+for (const commandKey in commands) {
+  if (typeof commands[commandKey] === `function`) {
+    commands[commandKey](program)
+  }
+}
+
+program.parse()

package/src/logger.ts

@@ -0,0 +1,29 @@
+/**
+ * The logger, using `loglevel`.
+ * 
+ * @see https://www.npmjs.com/package/loglevel
+ * 
+ * @module
+ */
+
+import logger from 'loglevel'
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace NodeJS {
+    export interface ProcessEnv {
+      /**
+       * The log level.
+       *
+       * @default warn
+       */
+      LOG_LEVEL?: `trace` | `debug` | `info` | `warn` | `error` | `silent`
+    }
+  }
+}
+
+if (process.env.LOG_LEVEL) {
+  logger.setLevel(process.env.LOG_LEVEL)
+}
+
+export { logger }

package/src/pkg.ts

@@ -0,0 +1,11 @@
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = fileURLToPath(path.dirname(import.meta.url))
+
+export const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, `../package.json`), `utf8`)) as {
+  name: string
+  description: string
+  version: string
+}

package/src/repoConfig.ts

@@ -0,0 +1,6 @@
+import { readRepoConfig } from './utilities/readRepoConfig.js'
+
+/**
+ * The current repo's `mlcl` configuration state.
+ */
+export const repoConfig = readRepoConfig()

package/src/types/global.ts

@@ -0,0 +1,26 @@
+/**
+ * Global type definitions.
+ * 
+ * @module
+ */
+
+declare global {
+  /**
+   * Useful when specifying that some type is a JSON value. 
+   */
+  export type JSONValue = string | number | boolean | JSONObject | JSONArray | null | undefined
+
+  /**
+   * Useful when specifying that some type is a JSON object. 
+   */
+  export interface JSONObject {
+    [key: string]: JSONValue
+  }
+
+  /**
+   * Useful when specifying that some type is a JSON array. 
+   */
+  export type JSONArray = Array<JSONValue>
+}
+
+export {}

package/src/types/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Types used throughout `mlcl`.
+ * 
+ * @module
+ */
+
+import * as userTypes from '../API/resource/user/types.js'
+
+export * as global from './global.js'
+
+/**
+ * Molecule user configuration.
+ * 
+ * Mostly used for authenticating with the Molecule.dev API.
+ * 
+ * We'll be adding some really useful functionality surrounding this in the future.
+ */
+export interface UserConfig {
+  /**
+   * Stored authorization headers used for talking to the Molecule.dev API.
+   */
+  authorizationHeader?: string
+  /**
+   * Remember the user's device.
+   */
+  userIdsToDeviceIds?: { [userId: string]: string }
+  /**
+   * The current user's properties.
+   */
+  user?: userTypes.Props
+  /**
+   * This will be asynchronously set to the latest `mlcl` version number if available
+   * on the NPM registry. A message will be shown to the user, suggesting the update.
+   */
+  newVersion?: string
+}
+
+/**
+ * Molecule repository configuration.
+ * 
+ * We'll be adding some really useful functionality surrounding this in the future.
+ */
+export interface RepoConfig {
+  id: string
+}
+
+/**
+ * Git commit information.
+ */
+export interface Commit {
+  hash: string
+  subject?: string
+}

package/src/types/process.env.d.ts

@@ -0,0 +1,56 @@
+declare namespace NodeJS {
+  export interface ProcessEnv {
+    /**
+     * The current environment.
+     */
+    NODE_ENV?: `development` | `production` | `test`
+
+    /**
+     * A unique identifier for the app.
+     * 
+     * @default mlcl
+     */
+    APP_ID?: string
+
+    /**
+     * The name of the app, typically as specified within `package.json`.
+     *
+     * @default $npm_package_name
+     */
+    APP_NAME?: string
+
+    /**
+     * The version number of the app, typically as specified within `package.json`.
+     *
+     * @default $npm_package_version
+     */
+    APP_VERSION?: string
+
+    /**
+     * The available app platforms.
+     */
+    APP_PLATFORM?: undefined
+      | `android`
+      | `ios`
+      | `windows`
+      | `mac`
+      | `linux`
+      | `cli`
+
+    /**
+     * The API's origin.
+     *
+     * @example https://api.molecule.dev
+     * @example http://localhost:4000
+     */
+    API_ORIGIN?: string
+
+    /**
+     * The web app's origin.
+     *
+     * @example https://app.molecule.dev
+     * @example http://localhost:3000
+     */
+    WEB_ORIGIN?: string
+  }
+}

package/src/userConfig.ts

@@ -0,0 +1,6 @@
+import { readUserConfig } from './utilities/readUserConfig.js'
+
+/**
+ * The current user's `mlcl` configuration state.
+ */
+export const userConfig = readUserConfig()

package/src/utilities/__tests__/getErrorMessage.ts

@@ -0,0 +1,32 @@
+import { getErrorMessage } from '../getErrorMessage.js'
+
+it(`returns a better "timed out" message`, () => {
+  expect(getErrorMessage({ code: `ETIMEDOUT` })).toBe(`Timed out`)
+})
+
+it(`returns a better "connection aborted" message`, () => {
+  expect(getErrorMessage({ code: `ECONNABORTED` })).toBe(`Connection aborted`)
+})
+
+it(`returns response data's error message`, () => {
+  expect(getErrorMessage({
+    response: {
+      data: {
+        error: `Username is required.`
+      }
+    }
+  })).toBe(`Username is required.`)
+})
+
+it(`returns error message`, () => {
+  expect(getErrorMessage(new Error(`Unexpected token`))).toBe(`Unexpected token`)
+})
+
+it(`returns the error if already a string`, () => {
+  expect(getErrorMessage(`Unexpected token`)).toBe(`Unexpected token`)
+})
+
+it(`returns null if no error`, () => {
+  expect(getErrorMessage()).toBe(null)
+  expect(getErrorMessage(null)).toBe(null)
+})

package/src/utilities/__tests__/timeAgo.ts

@@ -0,0 +1,46 @@
+import { timeAgo } from '../timeAgo.js'
+
+const MINUTE = 60000 + 1
+const HOUR = 3600000 + 1
+const DAY = 86400000 + 1
+const WEEK = 604800000 + 1
+const YEAR = 31557600000 + 1
+
+it(`returns "just now"`, () => {
+  expect(timeAgo(new Date().getTime())).toBe(`just now`)
+})
+
+it(`returns "minute(s)"`, () => {
+  expect(timeAgo(new Date().getTime() - MINUTE)).toBe(`1 minute ago`)
+  expect(timeAgo(new Date().getTime() - MINUTE*2)).toBe(`2 minutes ago`)
+  expect(timeAgo(new Date().getTime() - MINUTE, true)).toBe(`1m ago`)
+  expect(timeAgo(new Date().getTime() - MINUTE*2, true)).toBe(`2m ago`)
+})
+
+it(`returns "hour(s)"`, () => {
+  expect(timeAgo(new Date().getTime() - HOUR)).toBe(`1 hour ago`)
+  expect(timeAgo(new Date().getTime() - HOUR*2)).toBe(`2 hours ago`)
+  expect(timeAgo(new Date().getTime() - HOUR, true)).toBe(`1h ago`)
+  expect(timeAgo(new Date().getTime() - HOUR*2, true)).toBe(`2h ago`)
+})
+
+it(`returns "day(s)"`, () => {
+  expect(timeAgo(new Date().getTime() - DAY)).toBe(`1 day ago`)
+  expect(timeAgo(new Date().getTime() - DAY*2)).toBe(`2 days ago`)
+  expect(timeAgo(new Date().getTime() - DAY, true)).toBe(`1d ago`)
+  expect(timeAgo(new Date().getTime() - DAY*2, true)).toBe(`2d ago`)
+})
+
+it(`returns "week(s)"`, () => {
+  expect(timeAgo(new Date().getTime() - WEEK)).toBe(`1 week ago`)
+  expect(timeAgo(new Date().getTime() - WEEK*2)).toBe(`2 weeks ago`)
+  expect(timeAgo(new Date().getTime() - WEEK, true)).toBe(`1w ago`)
+  expect(timeAgo(new Date().getTime() - WEEK*2, true)).toBe(`2w ago`)
+})
+
+it(`returns "year(s)"`, () => {
+  expect(timeAgo(new Date().getTime() - YEAR)).toBe(`1 year ago`)
+  expect(timeAgo(new Date().getTime() - YEAR*2)).toBe(`2 years ago`)
+  expect(timeAgo(new Date().getTime() - YEAR, true)).toBe(`1y ago`)
+  expect(timeAgo(new Date().getTime() - YEAR*2, true)).toBe(`2y ago`)
+})

package/src/utilities/checkVersion.ts

@@ -0,0 +1,31 @@
+import semver from 'semver'
+import axios from 'axios'
+import { pkg } from '../pkg.js'
+import { userConfig } from '../userConfig.js'
+import { writeUserConfig } from '../utilities/writeUserConfig.js'
+import { logger } from '../logger.js'
+
+export const checkVersion = async () => {
+  if (userConfig.newVersion) {
+    if (semver.gt(userConfig.newVersion, pkg.version)) {
+      logger.info(`A new version (${userConfig.newVersion}) of \`mlcl\` is available.`)
+      logger.info(`You are currently on version ${pkg.version}.`)
+    } else {
+      delete userConfig.newVersion
+      writeUserConfig()
+    }
+  }
+
+  try {
+    const { version } = (await axios.get(`https://registry.npmjs.org/mlcl/latest`)).data
+
+    if (version && semver.gt(version, pkg.version)) {
+      userConfig.newVersion = version
+      writeUserConfig()
+    }
+  } catch (error) {
+  }
+}
+
+// Check every time `mlcl` is run.
+checkVersion()

package/src/utilities/getErrorMessage.ts

@@ -0,0 +1,30 @@
+export type VariableError = null | string | {
+  code?: string | number
+  message?: string
+  response?: {
+    statusText?: string
+    data?: {
+      error?: string
+    }
+  }
+}
+
+/**
+ * Attempts to return a human readable message based on some `Error`.
+ */
+export const getErrorMessage = (error?: VariableError): string | null => {
+  if (!error) {
+    return null
+  }
+
+  if (typeof error === `string`) {
+    return error
+  }
+
+  return (
+    ({ ETIMEDOUT: `Timed out`, ECONNABORTED: `Connection aborted` })[error.code || -1]
+      || error.response?.data?.error
+      || error.message
+      || null
+  )
+}

package/src/utilities/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Various utilities used throughout the application.
+ * 
+ * @module
+ */
+
+export * from './checkVersion.js'
+export * from './getErrorMessage.js'
+export * from './readRepoConfig.js'
+export * from './readUserConfig.js'
+export * from './synchronizeUserConfig.js'
+export * from './timeAgo.js'
+export * from './writeRepoConfig.js'
+export * from './writeUserConfig.js'

package/src/utilities/readRepoConfig.ts

@@ -0,0 +1,22 @@
+import fs from 'fs'
+import path from 'path'
+import { RepoConfig } from '../types/index.js'
+import { getRepoRootPathSync } from '../commands/utilities/getRepoRootPathSync.js'
+import { logger } from '../logger.js'
+
+/**
+ * Reads and returns the current repo's config.
+ */
+export const readRepoConfig = (repoConfigPath = path.join(getRepoRootPathSync(), `.mlclrc.json`)) => {
+  try {
+    if (fs.existsSync(repoConfigPath)) {
+      const config = JSON.parse(fs.readFileSync(repoConfigPath, `utf8`))
+
+      return config as RepoConfig
+    }
+  } catch (error) {
+    logger.error(error)
+  }
+
+  return {} as RepoConfig
+}

package/src/utilities/readUserConfig.ts

@@ -0,0 +1,24 @@
+import os from 'os'
+import fs from 'fs'
+import path from 'path'
+import { UserConfig } from '../types/index.js'
+import { logger } from '../logger.js'
+
+const homeDir = os.homedir()
+
+/**
+ * Reads and returns the current user's config.
+ */
+export const readUserConfig = (userConfigPath = path.join(homeDir, `.mlclrc.json`)) => {
+  try {
+    if (fs.existsSync(userConfigPath)) {
+      const config = JSON.parse(fs.readFileSync(userConfigPath, `utf8`))
+
+      return config as UserConfig
+    }
+  } catch (error) {
+    logger.error(error)
+  }
+
+  return {} as UserConfig
+}

package/src/utilities/synchronizeUserConfig.ts

@@ -0,0 +1,26 @@
+import { read as readUser } from '../API/resource/user/index.js'
+import { userConfig } from '../userConfig.js'
+import { writeUserConfig } from '../utilities/writeUserConfig.js'
+import { logger } from '../logger.js'
+import { getErrorMessage } from '../utilities/getErrorMessage.js'
+
+export const synchronizeUserConfig = async () => {
+  if (userConfig.user) {
+    try {
+      const { props: user } = (await readUser(userConfig.user.id)).data
+
+      if (!user) {
+        throw new Error(`No user was returned by the Molecule.dev API.`)
+      }
+
+      if (userConfig.user?.id === user.id) {
+        userConfig.user = user
+        writeUserConfig()
+      } else {
+        logger.warn(`The Molecule.dev API returned an unexpected response when synchronizing the user.`)
+      }
+    } catch (error) {
+      logger.warn(`Error fetching user: ${getErrorMessage(error) || `Unknown error`}`)
+    }
+  }
+}

package/src/utilities/timeAgo.ts

@@ -0,0 +1,39 @@
+const MINUTE = 60000
+const HOUR = 3600000
+const DAY = 86400000
+const WEEK = 604800000
+const YEAR = 31557600000
+
+/**
+ * Returns how long ago some time (date) was.
+ */
+export const timeAgo = (time: number | string, abbreviate?: boolean): string => {
+  if (typeof time !== `number`) {
+    try {
+      time = new Date(time).getTime()
+    } catch (error) {
+    }
+  }
+
+  const diff = Math.max(0, Date.now() - Number(time))
+  let count = 0
+
+  if (diff < MINUTE) {
+    return `just now`
+  } else if (diff < HOUR) {
+    count = Math.round(diff / MINUTE)
+    return `${count}${abbreviate ? `m` : ` minute${count === 1 ? `` : `s`}`} ago`
+  } else if (diff < DAY) {
+    count = Math.round(diff / HOUR)
+    return `${count}${abbreviate ? `h` : ` hour${count === 1 ? `` : `s`}`} ago`
+  } else if (diff < WEEK) {
+    count = Math.round(diff / DAY)
+    return `${count}${abbreviate ? `d` : ` day${count === 1 ? `` : `s`}`} ago`
+  } else if (diff < YEAR) {
+    count = Math.round(diff / WEEK)
+    return `${count}${abbreviate ? `w` : ` week${count === 1 ? `` : `s`}`} ago`
+  } else {
+    count = Math.round(diff / YEAR)
+    return `${count}${abbreviate ? `y` : ` year${count === 1 ? `` : `s`}`} ago`
+  }
+}

package/src/utilities/userLoggedIn.ts

@@ -0,0 +1,28 @@
+import { userConfig } from '../userConfig.js'
+import { synchronizeUserConfig } from './synchronizeUserConfig.js'
+import * as API from '../API/index.js'
+import { logger } from '../logger.js'
+
+/**
+ * Ensures the user is logged in before continuing.
+ * 
+ * If the user is not logged in, automatically runs the `login` command.
+ */
+export const userLoggedIn = async () => {
+  await synchronizeUserConfig()
+
+  if (userConfig?.user?.id) {
+    logger.info(`Hello, ${userConfig.user.name || userConfig.user.username}!`)
+  } else {
+    logger.info(`Not logged into \`mlcl\`. Logging in...`)
+
+    await API.resource.user.utilities.logIn()
+
+    if (!userConfig.user?.id) {
+      logger.warn(`Not logged in. Run \`mlcl login\` first.`)
+      return null
+    }
+  }
+
+  return userConfig.user
+}

package/src/utilities/writeRepoConfig.ts

@@ -0,0 +1,11 @@
+import fs from 'fs'
+import path from 'path'
+import { repoConfig as currentRepoConfig } from '../repoConfig.js'
+import { getRepoRootPathSync } from '../commands/utilities/getRepoRootPathSync.js'
+
+/**
+ * Writes the current repo's config to disk.
+ */
+export const writeRepoConfig = (repoConfig = currentRepoConfig, repoConfigPath = path.join(getRepoRootPathSync(), `.mlclrc.json`)) => {
+  fs.writeFileSync(repoConfigPath, JSON.stringify(repoConfig, null, 2))
+}

package/src/utilities/writeUserConfig.ts

@@ -0,0 +1,13 @@
+import os from 'os'
+import fs from 'fs'
+import path from 'path'
+import { userConfig as currentUserConfig } from '../userConfig.js'
+
+const homeDir = os.homedir()
+
+/**
+ * Writes the current user's config to disk.
+ */
+export const writeUserConfig = (userConfig = currentUserConfig, userConfigPath = path.join(homeDir, `.mlclrc.json`)) => {
+  fs.writeFileSync(userConfigPath, JSON.stringify(userConfig, null, 2))
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./build",
+    "target": "ES2020",
+    "lib": [
+      "ESNext"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "Node",
+    "esModuleInterop": true,
+    "strictNullChecks": true
+  },
+  "include": [
+    "./src"
+  ],
+  "exclude": [
+    "./node_modules",
+    "./build",
+    "./docs"
+  ],
+  "ts-node": {
+    "files": true
+  }
+}