@dittowords/cli 2.0.0 → 2.2.0

package/README.md

@@ -16,9 +16,50 @@ npm install --global @dittowords/cli
 
 The installed binary is named `ditto-cli`. You can execute it directly in `node_modules/.bin/ditto-cli` or using [npx](https://www.npmjs.com/package/npx) (with or without installation) like `npx @dittowords/cli`.
 
-The first time you run the CLI, you'll be asked to provide an API key (found at [https://beta.dittowords.com/account/user](https://beta.dittowords.com/account/user) under **API Keys**).
+The first time you run the CLI, you'll be asked to provide an API key (found at [https://beta.dittowords.com/account/user](https://beta.dittowords.com/account/user) under **API Keys**):
 
-Once you've successfully authenticated, you’re ready to start fetching copy! You can set up the CLI in multiple directories by running `ditto-cli` and choosing an initial project to sync from.
+```
+$ npx @dittowords/cli
+
+┌──────────────────────────────────┐
+│                                  │
+│   Welcome to the Ditto CLI.      │
+│                                  │
+│   We're glad to have you here.   │
+│                                  │
+└──────────────────────────────────┘
+
+What is your API key? > xxx-xxx-xxx
+
+Thanks for authenticating.
+We'll save the key to: /Users/{username}/.config/ditto
+```
+
+Once you've successfully authenticated, you'll be asked to configure the CLI with an initial project from your workspace:
+
+```
+Looks like there are no Ditto projects selected for your current directory.
+
+? Choose the project you'd like to sync text from:
+- Ditto Component Library https://beta.dittowords.com/components/all
+- NUX Onboarding Flow https://beta.dittowords.com/doc/609e9981c313f8018d0c346a
+...
+```
+
+After selecting a project, a configuration file will automatically be created at the path `./ditto/config.yml`, relative to your current working directory. The CLI will attempt to read from this file every time a command is executed. See the [documentation on config.yml](#files) further down in this README for a full reference of how the CLI can be configured.
+
+Once you've successfully authenticated and a config file has been created, you’re ready to start fetching copy! You can set up the CLI in multiple directories by running `ditto-cli` and choosing an initial project to sync from.
+
+## API Keys
+
+The CLI will not prompt for an API key if a value is provided in the environment variable `DITTO_API_KEY`.
+
+If the `DITTO_API_KEY` environment variable is not set, then the CLI will attempt to parse a token from a file at the
+path `~/.config/ditto`. If this file does not exist or does not contain a valid API key, then the CLI will prompt
+for one.
+
+We don't recommend editing the file manually; if you need to remove a saved API key and put another one in its place,
+it's better to fully delete the file and then re-run the CLI so that a new key is prompted for.
 
 ## Commands
 
@@ -52,7 +93,7 @@ This folder houses the configuration file (`ditto/config.yml`) used by the CLI a
 
 If you run the CLI in a directory that does not contain a `ditto/` folder, the folder and a `config.yml` file will be automatically created.
 
-- #### `config.yml`
+- #### config.yml
 
   This is the source of truth for a given directory about how the CLI should fetch and store data from Ditto. It includes information about which Ditto projects the CLI should pull text from and in what format the text should be stored.
 
@@ -60,16 +101,62 @@ If you run the CLI in a directory that does not contain a `ditto/` folder, the f
 
   **Supported properties**
 
-  - `projects` (required) - a list of project names and ids to pull text from (see example)
-  - `variants` (optional) - a `true` or `false` value indicating whether or not variant data should be pulled for the specified projects. Defaults to `false` if not specified (will likely default to `true` in future major releases).
-  - `format` (optional) - the format the specified projects should be stored in. Acceptable values are `structured` or `flat`. If not specified, the default format containing block and frame data will be used.
+  ##### `projects`
+
+  A list of project names and ids to pull text from. R
+
+  equired if `components: true` is not specified.
+
+  **Note**: the `name` property is used for display purposes when referencing a project in the CLI, but does not have to be an
+  exact match with the project name in Ditto.
 
-  **Example**:
+  ```yml
+  projects:
+    - name: Landing Page Copy
+      id: 61b8d26105f8f400e97fdd14
+    - name: User Settings
+      id: 606cb89ac55041013d552f8b
+  ```
+
+  ##### `components`
+
+  If included with a value of `true`, data from the component library will be fetched and included in the CLI's output.
+
+  Required if `projects` is not specified with a valid list of projects.
 
+  ```yml
+  components: true
   ```
+
+  ##### `variants`
+
+  If included with a value of `true`, variant data will be pulled for the specified projects and/or the component library.
+
+  Defaults to `false`.
+
+  ```yml
+  variants: true
+  ```
+
+  ##### `format`
+
+  The format the specified projects should be stored in. Acceptable values are `structured` or `flat`.
+
+  If not specified, the default format containing block and frame data will be used.
+
+  ```yml
+  format: flat
+  ```
+
+  **Full Example**
+
+  ```yml
   projects:
-    - name: Ditto Component Library
-      id: ditto_component_library
+    - name: Landing Page Copy
+      id: 61b8d26105f8f400e97fdd14
+    - name: User Settings
+      id: 606cb89ac55041013d552f8b
+  components: true
   variants: true
   format: flat
   ```

package/lib/config.js

@@ -1,9 +1,10 @@
 const fs = require("fs");
 const path = require("path");
 const url = require("url");
-
 const yaml = require("js-yaml");
 
+const consts = require("./consts");
+
 function createFileIfMissing(filename) {
   const dir = path.dirname(filename);
 
@@ -14,7 +15,13 @@ function createFileIfMissing(filename) {
   }
 }
 
-function readData(file, defaultData = {}) {
+/**
+ * Read data from a file
+ * @param {string} file defaults to `PROJECT_CONFIG_FILE` defined in `constants.js`
+ * @param {*} defaultData defaults to `{}`
+ * @returns
+ */
+function readData(file = consts.PROJECT_CONFIG_FILE, defaultData = {}) {
   createFileIfMissing(file);
   const fileContents = fs.readFileSync(file, "utf8");
   return yaml.safeLoad(fileContents) || defaultData;
@@ -50,7 +57,16 @@ function saveToken(file, host, token) {
   writeData(file, data);
 }
 
+function getTokenFromEnv() {
+  return process.env.DITTO_API_KEY;
+}
+
 function getToken(file, host) {
+  const tokenFromEnv = getTokenFromEnv();
+  if (tokenFromEnv) {
+    return tokenFromEnv;
+  }
+
   const data = readData(file);
   const hostEntry = data[justTheHost(host)];
   if (!hostEntry) return undefined;
@@ -72,6 +88,73 @@ function save(file, key, value) {
   writeData(file, data);
 }
 
+const IS_DUPLICATE = /-(\d+$)/;
+function dedupeProjectName(projectNames, projectName) {
+  let dedupedName = projectName;
+
+  if (projectNames.has(dedupedName)) {
+    while (projectNames.has(dedupedName)) {
+      const [_, numberStr] = dedupedName.match(IS_DUPLICATE) || [];
+      if (numberStr && !isNaN(parseInt(numberStr))) {
+        dedupedName = `${dedupedName.replace(IS_DUPLICATE, "")}-${
+          parseInt(numberStr) + 1
+        }`;
+      } else {
+        dedupedName = `${dedupedName}-1`;
+      }
+    }
+  }
+
+  return dedupedName;
+}
+
+/**
+ * Reads from the config file, filters out
+ * invalid projects, dedupes those remaining, and returns:
+ * - whether or not the data required to `pull` is present
+ * - whether or not the component library should be fetched
+ * - an array of valid, deduped projects
+ * - the `variants` and `format` config options
+ */
+function parseSourceInformation() {
+  const { projects, components, variants, format } = readData();
+
+  const projectNames = new Set();
+  const validProjects = [];
+
+  let componentLibraryInProjects = false;
+
+  (projects || []).forEach((project) => {
+    const isValid = project.id && project.name;
+    if (!isValid) {
+      return;
+    }
+
+    if (project.id === "ditto_component_library") {
+      componentLibraryInProjects = true;
+      return;
+    }
+
+    project.fileName = dedupeProjectName(projectNames, project.name);
+    projectNames.add(project.fileName);
+
+    validProjects.push(project);
+  });
+
+  const shouldFetchComponentLibrary =
+    !!components || componentLibraryInProjects;
+
+  const hasSourceData = validProjects.length || shouldFetchComponentLibrary;
+
+  return {
+    hasSourceData,
+    validProjects,
+    shouldFetchComponentLibrary,
+    variants,
+    format,
+  };
+}
+
 module.exports = {
   createFileIfMissing,
   readData,
@@ -80,5 +163,7 @@ module.exports = {
   saveToken,
   deleteToken,
   getToken,
+  getTokenFromEnv,
   save,
+  parseSourceInformation,
 };

package/lib/init/init.js

@@ -2,13 +2,16 @@
 // expected to be run once per project.
 const boxen = require("boxen");
 const chalk = require("chalk");
-const getSelectedProjects = require("../utils/getSelectedProjects");
 const projectsToText = require("../utils/projectsToText");
 
-const { needsProjects, collectAndSaveProject } = require("./project");
+const { needsSource, collectAndSaveProject } = require("./project");
 const { needsToken, collectAndSaveToken } = require("./token");
 
-const needsInit = () => needsToken() || needsProjects();
+const config = require("../config");
+const output = require("../output");
+const sourcesToText = require("../utils/sourcesToText");
+
+const needsInit = () => needsToken() || needsSource();
 
 function welcome() {
   const msg = chalk.white(`${chalk.bold(
@@ -22,19 +25,24 @@ We're glad to have you here.`);
 
 async function init() {
   welcome();
+
   if (needsToken()) {
     await collectAndSaveToken();
   }
-  const selectedProjects = getSelectedProjects();
-  if (selectedProjects.length) {
-    console.log(
-      `You're currently set up to sync text from the following projects: ${projectsToText(
-        selectedProjects
-      )}\n`
-    );
-  } else {
+
+  const { hasSourceData, validProjects, shouldFetchComponentLibrary } =
+    config.parseSourceInformation();
+
+  if (!hasSourceData) {
     await collectAndSaveProject(true);
+    return;
   }
+
+  const message =
+    "You're currently set up to sync text from " +
+    sourcesToText(validProjects, shouldFetchComponentLibrary);
+
+  console.log(message);
 }
 
 module.exports = { needsInit, init };

package/lib/init/project.js

@@ -15,14 +15,21 @@ function quit(exitCode = 2) {
 }
 
 function saveProject(file, name, id) {
+  // old functionality included "ditto_component_library" in the `projects`
+  // array, but we want to always treat the component library as a separate
+  // entity and use the new notation of a top-level `components` key
+  if (id === "ditto_component_library") {
+    config.writeData(file, { components: true });
+    return;
+  }
+
   const projects = [...getSelectedProjects(), { name, id }];
 
   config.writeData(file, { projects });
 }
 
-function needsProjects(configFile) {
-  const projects = getSelectedProjects(configFile);
-  return !(projects && projects.length);
+function needsSource() {
+  return !config.parseSourceInformation().hasSourceData;
 }
 
 async function askForAnotherToken() {
@@ -60,7 +67,7 @@ async function collectProject(token, initialize) {
   const path = process.cwd();
   if (initialize) {
     console.log(
-      `Looks like are no Ditto projects selected for your current directory: ${output.info(
+      `Looks like there are no Ditto projects selected for your current directory: ${output.info(
         path
       )}.`
     );
@@ -113,4 +120,4 @@ async function collectAndSaveProject(initialize = false) {
   }
 }
 
-module.exports = { needsProjects, collectAndSaveProject };
+module.exports = { needsSource, collectAndSaveProject };

package/lib/init/token.js

@@ -10,6 +10,10 @@ const output = require("../output");
 const config = require("../config");
 
 function needsToken(configFile, host = consts.API_HOST) {
+  if (config.getTokenFromEnv()) {
+    return false;
+  }
+
   const file = configFile || consts.CONFIG_FILE;
   if (!fs.existsSync(file)) return true;
   const configData = config.readData(file);

package/lib/pull.js

@@ -9,6 +9,7 @@ const consts = require("./consts");
 const output = require("./output");
 const { collectAndSaveToken } = require("./init/token");
 const projectsToText = require("./utils/projectsToText");
+const sourcesToText = require("./utils/sourcesToText");
 
 const NON_DEFAULT_FORMATS = ["flat", "structured"];
 
@@ -30,54 +31,6 @@ async function askForAnotherToken() {
   await collectAndSaveToken(message);
 }
 
-function cleanProjectName(projectName) {
-  return (
-    projectName
-      .replace(/\s/g, "-")
-      // replace double underscore since this is what we use
-      // to separate project names and API IDs
-      .replace(/__/g, "_")
-      .toLowerCase()
-      .trim()
-  );
-}
-
-/**
- * Return the passed array of projects with `project.name` modified
- * to be `${project.name}-${duplicate_number}` for each project
- * that has the same name as another project in the original array.
- */
-const IS_DUPLICATE = /-(\d+$)/;
-function getProjectsWithDedupedNames(projects) {
-  const projectsWithDedupedNames = [];
-  const projectNames = {};
-
-  projects.forEach(({ id, name }) => {
-    let dedupedName = name;
-
-    if (projectNames[dedupedName]) {
-      while (projectNames[dedupedName]) {
-        const [_, numberStr] = dedupedName.match(IS_DUPLICATE) || [];
-        if (numberStr && !isNaN(parseInt(numberStr))) {
-          dedupedName = `${dedupedName.replace(IS_DUPLICATE, "")}-${
-            parseInt(numberStr) + 1
-          }`;
-        } else {
-          dedupedName = `${dedupedName}-1`;
-        }
-      }
-    }
-
-    projectNames[dedupedName] = true;
-    projectsWithDedupedNames.push({
-      id,
-      name: cleanProjectName(dedupedName),
-    });
-  });
-
-  return projectsWithDedupedNames;
-}
-
 /**
  * For a given variant:
  * - if format is unspecified, fetch data for all projects from `/projects` and
@@ -93,7 +46,7 @@ async function downloadAndSaveVariant(variantApiId, projects, format, token) {
 
   if (NON_DEFAULT_FORMATS.includes(format)) {
     const savedMessages = await Promise.all(
-      projects.map(async ({ id, name }) => {
+      projects.map(async ({ id, fileName }) => {
         const { data } = await api.get(`/projects/${id}`, {
           params,
           headers: { Authorization: `token ${token}` },
@@ -103,7 +56,7 @@ async function downloadAndSaveVariant(variantApiId, projects, format, token) {
           return "";
         }
 
-        const filename = name + ("__" + (variantApiId || "base")) + ".json";
+        const filename = fileName + ("__" + (variantApiId || "base")) + ".json";
         const filepath = path.join(consts.TEXT_DIR, filename);
 
         const dataString = JSON.stringify(data, null, 2);
@@ -162,13 +115,13 @@ async function downloadAndSaveBase(projects, format, token) {
 
   if (NON_DEFAULT_FORMATS.includes(format)) {
     const savedMessages = await Promise.all(
-      projects.map(async ({ id, name }) => {
+      projects.map(async ({ id, fileName }) => {
         const { data } = await api.get(`/projects/${id}`, {
           params,
           headers: { Authorization: `token ${token}` },
         });
 
-        const filename = `${name}.json`;
+        const filename = `${fileName}.json`;
         const filepath = path.join(consts.TEXT_DIR, filename);
 
         const dataString = JSON.stringify(data, null, 2);
@@ -195,7 +148,7 @@ async function downloadAndSaveBase(projects, format, token) {
 }
 
 function getSavedMessage(file) {
-  return `Successfully saved to ${output.info(file)}.\n`;
+  return `Successfully saved to ${output.info(file)}\n`;
 }
 
 function cleanOutputFiles() {
@@ -235,7 +188,7 @@ function generateJsDriver(projects, variants, format) {
     .filter((fileName) => /\.json$/.test(fileName));
 
   const projectIdsByName = projects.reduce(
-    (agg, project) => ({ ...agg, [project.name]: project.id }),
+    (agg, project) => ({ ...agg, [project.fileName]: project.id }),
     {}
   );
 
@@ -305,28 +258,40 @@ function generateJsDriver(projects, variants, format) {
   const filePath = path.resolve(consts.TEXT_DIR, "index.js");
   fs.writeFileSync(filePath, dataString, { encoding: "utf8" });
 
-  return `Generated .js SDK driver at ${output.info(filePath)}..`;
+  return `Generated .js SDK driver at ${output.info(filePath)}`;
 }
 
-async function downloadAndSave(projectConfig, token) {
-  const { projects, variants, format } = projectConfig;
-  const projectsDeduped = getProjectsWithDedupedNames(projects);
+async function downloadAndSave(sourceInformation, token) {
+  const { validProjects, variants, format, shouldFetchComponentLibrary } =
+    sourceInformation;
 
-  let msg = `\nFetching the latest text from your selected projects: ${projectsToText(
-    projects
+  let msg = `\nFetching the latest text from ${sourcesToText(
+    validProjects,
+    shouldFetchComponentLibrary
   )}\n`;
 
   const spinner = ora(msg);
   spinner.start();
 
+  // We'll need to move away from this solution if at some
+  // point down the road we stop allowing the component
+  // library to be returned from the /projects endpoint
+  if (shouldFetchComponentLibrary) {
+    validProjects.push({
+      id: "ditto_component_library",
+      name: "Ditto Component Library",
+      fileName: "ditto-component-library",
+    });
+  }
+
   try {
     msg += cleanOutputFiles();
 
     msg += variants
-      ? await downloadAndSaveVariants(projectsDeduped, format, token)
-      : await downloadAndSaveBase(projectsDeduped, format, token);
+      ? await downloadAndSaveVariants(validProjects, format, token)
+      : await downloadAndSaveBase(validProjects, format, token);
 
-    msg += generateJsDriver(projectsDeduped, variants, format);
+    msg += generateJsDriver(validProjects, variants, format);
 
     msg += `\n${output.success("Done")}!`;
 
@@ -371,15 +336,15 @@ async function downloadAndSave(projectConfig, token) {
 
 function pull() {
   const token = config.getToken(consts.CONFIG_FILE, consts.API_HOST);
-  const pConfig = config.readData(consts.PROJECT_CONFIG_FILE);
-  return downloadAndSave(pConfig, token);
+  const sourceInformation = config.parseSourceInformation();
+
+  return downloadAndSave(sourceInformation, token);
 }
 
 module.exports = {
   pull,
   _testing: {
     cleanOutputFiles,
-    getProjectsWithDedupedNames,
     downloadAndSaveVariant,
     downloadAndSaveVariants,
     downloadAndSaveBase,

package/lib/utils/projectsToText.js

@@ -2,7 +2,7 @@ const output = require("../output");
 
 function projectsToText(projects) {
   return (
-    projects.reduce(
+    (projects || []).reduce(
       (outputString, { name, id }) =>
         outputString +
         ("\n" +

package/lib/utils/sourcesToText.js

@@ -0,0 +1,24 @@
+const output = require("../output");
+const projectsToText = require("./projectsToText");
+
+function sourcesToText(projects, componentLibrary) {
+  let message = "";
+
+  if (componentLibrary) {
+    message += `the ${output.info("Ditto Component Library")}`;
+
+    if ((projects || []).length) {
+      message += " and ";
+    } else {
+      message += "..";
+    }
+  }
+
+  if ((projects || []).length) {
+    message += `the following projects: ${projectsToText(projects)}\n`;
+  }
+
+  return message;
+}
+
+module.exports = sourcesToText;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dittowords/cli",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Command Line Interface for Ditto (dittowords.com).",
   "main": "bin/index.js",
   "scripts": {