@nzz/q-cli 1.10.3 → 2.0.0-beta.10

package/README.md

@@ -1,14 +1,4 @@
-# Q cli [![Build Status](https://travis-ci.com/nzzdev/Q-cli.svg?branch=dev)](https://travis-ci.com/nzzdev/Q-cli)
-
-**Maintainer**: [Nicolas Staub](https://github.com/fromdusttilldawn)
-
-## Table of contents
-
-- [Installation](#installation)
-- [Development](#development)
-- [Github Actions](#github-actions)
-- [Functionality](#functionality)
-- [License](#license)
+# Q cli
 
 ## Installation
 
@@ -16,39 +6,23 @@
 npm install -g @nzz/q-cli
 ```
 
-## Development
-
-```
-git clone git@github.com:nzzdev/Q-cli.git
-cd Q-cli
-nvm use
-npm install
-```
-
-For testing local changes of Q-cli, one can link the local package to the global installation of Q-cli:
+Some commands require certain environment variables. If you do not provide them, q cli tries to get them from your local 1Password installation. Make sure, that you have [1Password](https://1password.com/downloads/mac) installed.
 
-```bash
-cd Q-cli
-npm link
-```
-
-Q commands will now use the local Q-cli.
-
-To unlink, simply install Q-cli again globally:
+## Development
 
 ```bash
-npm install @nzz/q-cli -g
+pnpm i
 ```
 
-## Github actions
+There is a test script for each command in the `package.json`.
 
-To use the q-cli in github actions there are special access tokens provided. You can find them in 1password (LivingDocs Public API Access Tokens).
+## GitHub Actions
 
-There is an entire [thread](https://3.basecamp.com/3500782/buckets/1333707/documents/2903809795#__recording_3878674488) in basecamp on how this solution works.
+To use the q cli in GitHub Actions there are special access tokens provided. You can find them in 1Password (vault: Q CLI). Editorial Tech manages those access tokens.
 
-Example code for a github action to update on all environments. You can check the functionality section if you only want to update a specific environment.
+You will need to set the secrets in your GitHub repository under: `Settings > Secrets & variables > Actions > New repository secret`
 
-You will need to set the secrets in github unders **settings > secrets & variables > actions > New repository secret**
+Example:
 
 ```
 - name: Run Q cli
@@ -60,301 +34,36 @@ You will need to set the secrets in github unders **settings > secrets & variabl
     Q_PRODUCTION_ACCESSTOKEN: ${{ secrets.Q_PRODUCTION_ACCESSTOKEN }}
 ```
 
-[to the top](#table-of-contents)
-
 ## Functionality
 
-### Q dev server
-
-Once `Q` cli installed one can start Q dev server by running:
-
-```bash
-Q server
-```
-
-With the Q dev server running one can now test a tool with fixture data. Of course the respective tool has to be started as well.
-
-- Default port is 5000 and can be overwritten by using `-p` or `--port` as option while starting Q dev server:
-
-```bash
-Q server -p 4001
-```
-
-- Default base url of the tool your are currently developing is `http://localhost:3000`, this can also be changed by passing the option `-b` or `--tool-base-url` while starting Q dev server.
-
-```bash
-Q server -b http://localhost:4000
-```
-
-- Default target is `nzz_ch` and can be overwritten by using `-t` or `--target`.
-
-```bash
-Q server -t your_target
-```
-
-- One can optionally specify a path to a config file by using option `-c` or `--config`, e.g.
-
-```bash
-Q server -c ./config-file-name.js
-```
-
-A config file should export an async function returning a config object. The config object has to contain an object for each target. Target objects can contain
-
-- tool specific additionalRenderingInfo like additional stylesheets and scripts to load
-- a target specific context which can also contain stylesheets, scripts or background information
-- toolRuntimeConfig containing information which a tool might need at runtime
-  Config file example:
-
-```js
-async function getConfig() {
-  return {
-    nzz_ch: {
-      // target name
-      additionalRenderingInfo: {
-        // additionalRenderingInfo is tool based
-        stylesheets: [
-          {
-            url: "https://service.sophie.nzz.ch/bundle/sophie-q@1,sophie-font@1,sophie-color@1,sophie-viz-color@1,sophie-input@1.css",
-          },
-        ],
-      },
-      context: {
-        // context is target based
-        stylesheets: [
-          {
-            url: "https://context-service.st.nzz.ch/stylesheet/all/nzz.ch.css",
-          },
-        ],
-        background: {
-          color: "#fff",
-        },
-      },
-      toolRuntimeConfig: {
-        displayOptions: {
-          hideTitle: true,
-        },
-      },
-    },
-  };
-}
-
-module.exports = getConfig;
-```
-
-### Creating new Q server implementation
-
-Once `Q` cli is installed one can create the skeleton of a Q server implementation by executing
-
-```bash
-Q new-server my-server-name
-```
-
-- The directory name where the server implementation is being created defaults to the server name and can be overwritten by using option `-d` or `--dir`
-
-```bash
-Q new-server my-server-name -d my-server-directory
-```
-
-### Creating new tool
-
-Once `Q` cli is installed one can create the skeleton of a new tool by executing
-
-```bash
-Q new-tool my-tool-name
-```
-
-- The directory name where the new tool is being created defaults to the tool name and can be overwritten by using option `-d` or `--dir`
-
-```bash
-Q new-tool my-tool-name -d my-tool-directory
-```
-
-### Creating new custom code project
-
-Once `Q` cli is installed one can create the skeleton of a new custom code project by executing
-
-```bash
-Q new-custom-code my-project-name
-```
+### Creating a new custom code project
 
-- The directory name where the new custom-code project is being created defaults to the project name and can be overwritten by using option `-d` or `--dir`
+Creates a new custom code project.
 
 ```bash
-Q new-custom-code my-project-name -d my-project-directory
+Q new-custom-code -d my-custom-code-project
 ```
 
-### Creating new ed-tech utility package project
+### Creating a new custom code item
 
-Once `Q` cli is installed one can create the skeleton of a new ed-tech utility package project by executing
+Creates a new custom code item on the specified environment and adds the id of the newly created item to the specified `q.config.json`.
 
-```bash
-Q new-et-utils-package package-name package-author package-description
-```
+`q.config.json`: By default q cli will look for the config file in the current directory, if no path is specified.
 
-- The directory name where the new ed-tech utility package project is being created defaults to the project name and can be overwritten by using option `-d` or `--dir`
+This command requires the environment variables `Q_[ENVIRONMENT]_SERVER` and `Q_[ENVIRONMENT]_ACCESSTOKEN`.
 
 ```bash
-Q new-et-utils-package package-name -d my-project-directory
+Q create-custom-code-item -e local -c ./tests/q.config.json -t 'TEST CUSTOM CODE ITEM'
 ```
 
-#### Notes
-
-New utility package projects should only be created inside the [ed-tech-utilities](https://github.com/nzzdev/ed-tech-utilities) repository.
-
-### Q item actions
-
-The `Q` cli can copy and/or update existing Q items.
-
-#### Updating existing Q items
+### Updating existing Q items
 
-Once `Q` cli installed one can update one or many Q items by executing:
+Reads the specified `q.config.json` and updates all q items there.
 
-```bash
-Q update-item
-```
-
-- The path to the config file can be set by using option `-c` or `--config`. By default the `update-item` command will look for a config file called `q.config.json` in the current directory
-
-```bash
-Q update-item -c [path]
-```
+`q.config.json`: By default q cli will look for the config file in the current directory, if no path is specified.
 
-- Items of a specified environment can be updated by using the option `-e` or `--environment`. By default the `update-item` command updates all item specified in the config file
+This command requires the environment variables `Q_[ENVIRONMENT]_SERVER` and `Q_[ENVIRONMENT]_ACCESSTOKEN`.
 
 ```bash
-Q update-item -e [env]
+Q update-item -e local -c ./tests/q.config.json
 ```
-
-- Stored configuration properties like Q-Server url or access tokens can be reset by using option `-r` or `--reset`
-
-```bash
-Q update-item -r
-```
-
-- Credentials can be provided as environment variables to avoid user prompts. The variable names are `Q_ENV_SERVER`, `Q_ENV_USERNAME`, `Q_ENV_PASSWORD`, `Q_ENV_ACCESSTOKEN`, where `ENV` is the uppercase version of the environment name.
-
-```bash
-Q_TEST_SERVER=[server_route] Q_TEST_USERNAME=[username] Q_TEST_PASSWORD=[password] Q update-item
-```
-
-or
-
-```bash
-Q_TEST_SERVER=[server_route] Q_TEST_ACCESSTOKEN=[accessToken] Q update-item
-```
-
-The config file has to follow [this json-schema](./bin/commands/qItem/updateItem/updateSchema.json). This schema will be extended by the respective tool schema of your Q item.
-Here's an example:
-
-```json
-{
-  "items": [
-    {
-      "environments": [
-        // "environments" references the desired q items to be updated, at least 1 environment is required
-        {
-          "name": "production",
-          "id": "6dcf203a5c5f74b61aeea0cb0eef7e0b" // Id of your q item in the production environment
-        },
-        {
-          "name": "staging",
-          "id": "6dcf203a5c5f74b61aeea0cb0ef2ca9f" // Id of your q item in the staging environment
-        }
-      ],
-      "item": {
-        // The actual content you want to update for your referenced q items listed in "environments"
-        "title": "Der Konsum in der Schweiz springt wieder an",
-        "subtitle": "Wöchentliche Ausgaben mittels Bankkarten in Mio. Fr. im Jahr 2020, zum Vergleich 2019",
-        "data": [
-          // "data" represents the data table of your q item inside the q-editor
-          ["Datum", "2020", "2019"],
-          ["2020-01-06", "690004302", "641528028"],
-          ["2020-01-13", "662122373", "617653790"],
-          ["2020-01-20", "688208667", "654303249"]
-        ]
-      }
-    }
-  ]
-}
-```
-
-#### Copy existing Q items
-
-Once `Q` cli installed one can copy one or many Q items by executing:
-
-```bash
-Q copy-item
-```
-
-- The path to the config file can be set by using option `-c` or `--config`. By default the `copy-item` command will look for a config file called `q.config.json` in the current directory
-
-```bash
-Q copy-item -c [path]
-```
-
-- Items of a specified environment can be updated by using the option `-e` or `--environment`. By default the `copy-item` command updates all item specified in the config file
-
-```bash
-Q copy-item -e [env]
-```
-
-- Stored configuration properties like Q-Server url or access tokens can be reset by using option `-r` or `--reset`
-
-```bash
-Q copy-item -r
-```
-
-- Credentials can be provided as environment variables to avoid user prompts. The variable names are `Q_ENV_SERVER`, `Q_ENV_USERNAME`, `Q_ENV_PASSWORD`, `Q_ENV_ACCESSTOKEN`, where `ENV` is the uppercase version of the environment name.
-
-```bash
-Q_TEST_SERVER=[server_route] Q_TEST_USERNAME=[username] Q_TEST_PASSWORD=[password] Q update-item
-```
-
-or
-
-```bash
-Q_TEST_SERVER=[server_route] Q_TEST_ACCESSTOKEN=[accessToken] Q update-item
-```
-
-The config file has to follow [this json-schema](./bin/commands/qItem/updateItem/updateSchema.json). This schema will be extended by the respective tool schema of your Q item.
-Here's an example:
-
-```json
-{
-  "items": [
-    {
-      "environments": [
-        {
-          "name": "production",
-          "id": "6dcf203a5c5f74b61aeea0cb0eef7e0b" // Id of your q item in the production environment
-        },
-        {
-          "name": "staging",
-          "id": "6dcf203a5c5f74b61aeea0cb0ef2ca9f" // Id of your q item in the staging environment
-        }
-      ],
-      "item": {
-        "title": "Russische Angriffe auf die Ukraine",
-        "subtitle": "Verzeichnete Angriffe in der ganzen Ukraine",
-        "files": [
-          // Adds or overwrites the listed files in your q item
-          {
-            "loadSyncBeforeInit": false, // Has to be set for the file upload to work
-            "file": {
-              "path": "./angriffsFlaechen.json" // Your local path to your file. The path is relative to where you execute the command.
-            }
-          }
-        ]
-      }
-    }
-  ]
-}
-```
-
-[to the top](#table-of-contents)
-
-## License
-
-Copyright (c) Neue Zürcher Zeitung.
-
-This software is licensed under the [MIT](LICENSE) License.

package/dist/createCustomCodeItem.js

@@ -0,0 +1,70 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { logSuccess, logError, updateItem, getAccessToken, getQServerUrl } from './utils.js';
+import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+export default function (command) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const qConfigPath = resolve(command.config);
+        if (!existsSync(qConfigPath)) {
+            logError(`Couldn't find config file: '${qConfigPath}'.\nCreate a config file in the current directory or pass the path to the config file with the option -c <path>`);
+            return;
+        }
+        // Get the Q server URL and access token from the environment variables or 1Password
+        const qServerUrl = getQServerUrl(command.environment);
+        const accessToken = getAccessToken(command.environment);
+        const newCustomCodeDoc = {
+            acronym: 'Visuals',
+            assetGroups: [],
+            createdDate: '', // Will be set when saved
+            createdBy: 'editorial-tech@nzz.ch',
+            data: [],
+            // @ts-ignore
+            department: 'Visuals',
+            files: [],
+            options: {
+                previewDisabled: true,
+            },
+            // @ts-ignore
+            publication: 'nzz',
+            sophieModules: [],
+            title: command.title,
+            // @ts-ignore
+            tool: 'custom_code',
+            updatedDate: '', // Will be set when saved
+            updatedBy: 'editorial-tech@nzz.ch',
+        };
+        // Create the item on the Q server
+        const result = yield updateItem(newCustomCodeDoc, qServerUrl, accessToken);
+        if (!result.success) {
+            logError(result.msg);
+            process.exit(1);
+        }
+        const newCustomCodeDocId = result.id;
+        // Update the config file with the new item
+        const qConfig = JSON.parse(readFileSync(qConfigPath, 'utf-8'));
+        if (!qConfig.items) {
+            qConfig.items = [];
+        }
+        if (qConfig.items.length === 0) {
+            qConfig.items.push({
+                environments: [],
+                item: {}, // User needs to add the item later
+            });
+        }
+        const firstItem = qConfig.items[0];
+        firstItem.environments.push({
+            id: newCustomCodeDocId,
+            name: command.environment,
+        });
+        writeFileSync(qConfigPath, JSON.stringify(qConfig, null, 2));
+        logSuccess(`Successfully created item with id ${newCustomCodeDocId} on ${command.environment} environment`);
+    });
+}

package/dist/enums.js

@@ -0,0 +1,6 @@
+export var Environment;
+(function (Environment) {
+    Environment["PRODUCTION"] = "production";
+    Environment["STAGING"] = "staging";
+    Environment["TEST"] = "test";
+})(Environment || (Environment = {}));

package/dist/index.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { Command } from 'commander';
+import packageJson from '../package.json' with { type: 'json' };
+import updateItem from './updateItem.js';
+import newCustomCode from './newCustomCode.js';
+import createCustomCodeItem from './createCustomCodeItem.js';
+const program = new Command();
+// Get the version from the package.json file
+const version = packageJson.version;
+function main() {
+    return __awaiter(this, void 0, void 0, function* () {
+        program.version(version).description('Q Toolbox cli');
+        program
+            .command('new-custom-code')
+            .option('-d, --dir [path]', 'the base directory to bootstrap the new custom code project in')
+            .description('bootstrap a new custom code project')
+            .action((command) => {
+            newCustomCode(command);
+        });
+        program
+            .command('new-et-utils-package')
+            .option('-d, --dir [path]', 'the base directory to bootstrap the new tool in, defaults to the tools name')
+            .description('bootstrap a new ed-tech utility package')
+            .action(() => __awaiter(this, void 0, void 0, function* () {
+            //   const name = program.args[1];
+            //   const author = program.args[2] || 'TODO: Set package author name';
+            //   const description = program.args[3] || 'TODO: Write a package description';
+            //   if (!name) {
+            //     console.error(errorColor('no package name given'));
+            //     process.exit(1);
+            //   }
+            //   const baseDir = program.dir || name;
+            //   const textReplacements = [
+            //     { regex: new RegExp('<package-name>', 'g'), replaceWith: name },
+            //     { regex: new RegExp('<author-name>', 'g'), replaceWith: author },
+            //     {
+            //       regex: new RegExp('<package-description>', 'g'),
+            //       replaceWith: description,
+            //     },
+            //   ];
+            //   await bootstrap('et-utils-package', baseDir, textReplacements);
+        }));
+        program
+            .command('update-item')
+            .description('update q item')
+            .option('-c, --config [path]', 'set config path which defines the q items to be updated. defaults to ./q.config.json', `${process.cwd()}/q.config.json`)
+            .option('-e, --environment [env]', 'set environment which should be updated, defaults to update all items of all environments defined in config')
+            .action((command) => __awaiter(this, void 0, void 0, function* () {
+            yield updateItem(command);
+        }));
+        program
+            .command('copy-item')
+            .description('copies an existing q item')
+            .option('-c, --config [path]', 'set config path which defines the q items to be copied. defaults to ./q.config.json', `${process.cwd()}/q.config.json`)
+            .option('-e, --environment [env]', 'set environment where the existing q item is found, defaults to copy all items of all environments defined in config')
+            .action((command) => __awaiter(this, void 0, void 0, function* () {
+            // await copyItem(command);
+        }));
+        program
+            .command('create-custom-code-item')
+            .description('creates a new q custom code item in the db and adds it to the q config file')
+            .option('-c, --config [path]', 'set config path to q.config.json. defaults to ./q.config.json', `${process.cwd()}/q.config.json`)
+            .option('-e, --environment [env]', 'set environment where the new q custom code item should be created in')
+            .option('-t, --title [title]', 'set title of the new q custom code item')
+            .action((command) => __awaiter(this, void 0, void 0, function* () {
+            yield createCustomCodeItem(command);
+        }));
+        yield program.parseAsync(process.argv);
+    });
+}
+main();

package/dist/interfaces.js

@@ -0,0 +1 @@
+export {};

package/dist/newCustomCode.js

@@ -0,0 +1,107 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { logError, logSuccess } from './utils.js';
+export default function (command) {
+    const { dir } = command;
+    if (!dir) {
+        logError('No custom-code project name/directory given');
+        process.exit(1);
+    }
+    if (fs.existsSync(dir)) {
+        logError(`Directory ${dir} already exists`);
+        process.exit(1);
+    }
+    const skeletonDir = 'skeletons';
+    const skeletonCustomCodeDir = path.join(skeletonDir, 'custom-code-project');
+    try {
+        // Create the target directory
+        fs.mkdirSync(dir);
+        // Change to the target directory
+        process.chdir(dir);
+        // Initialize git repository to pull the skeletons/custom-code-project content into a separate directory
+        console.log('Initializing git repository...');
+        execSync('git init');
+        execSync('git remote add origin https://github.com/nzzdev/Q.git');
+        // Enable sparse checkout and pull the content from remote
+        console.log(`Sparse checkout ${skeletonCustomCodeDir}...`);
+        execSync('git sparse-checkout init --cone');
+        execSync(`git sparse-checkout set ${skeletonCustomCodeDir}`);
+        console.log('Pulling content from remote...');
+        execSync('git pull origin main');
+        // Remove all files, except the skeletons directory
+        console.log('Cleaning up...');
+        const cwdFiles = fs.readdirSync(process.cwd());
+        for (const file of cwdFiles) {
+            if (file === skeletonDir)
+                continue; // Skip the skeletons directory
+            const filePath = path.join(process.cwd(), file);
+            if (fs.statSync(filePath).isDirectory()) {
+                fs.rmSync(filePath, { recursive: true, force: true });
+            }
+            else {
+                fs.unlinkSync(filePath);
+            }
+        }
+        // Copy the skeletons/custom-code-project content to the root
+        const cwdSkeletonCustomCodeDir = path.join(process.cwd(), skeletonCustomCodeDir);
+        const skeletonFiles = fs.readdirSync(cwdSkeletonCustomCodeDir);
+        for (const file of skeletonFiles) {
+            const srcFilePath = path.join(cwdSkeletonCustomCodeDir, file);
+            const targetFilePath = path.join(process.cwd(), file);
+            if (fs.statSync(srcFilePath).isDirectory()) {
+                fs.cpSync(srcFilePath, targetFilePath, { recursive: true });
+            }
+            else {
+                fs.copyFileSync(srcFilePath, targetFilePath);
+            }
+        }
+        // Remove the now empty skeletons directory
+        fs.rmSync(path.join(process.cwd(), skeletonDir), { recursive: true, force: true });
+        // Update the package.json and q.config.json files with the custom code project name
+        const customCodeProjectName = path.basename(dir);
+        updateJsonValue(path.join(process.cwd(), 'package.json'), 'name', customCodeProjectName);
+        updateJsonValue(path.join(process.cwd(), 'q.config.json'), 'items.0.item.trackingComponent.componentInfo.componentName', customCodeProjectName);
+        logSuccess(`Successfully created new custom code project '${dir}'`);
+    }
+    catch (error) {
+        logError(error.message);
+        process.exit(1);
+    }
+}
+/**
+ * Reads a JSON file, updates a specific value, and writes the changes back to the file
+ * @param filePath - Path to the JSON file
+ * @param keyPath - Path to the key to update (use dot notation for nested objects, e.g., 'parent.child')
+ * @param newValue - New value to set
+ * @returns boolean indicating success
+ */
+function updateJsonValue(filePath, keyPath, newValue) {
+    try {
+        // Read the JSON file
+        const jsonContent = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        // Split the key path into parts for nested objects
+        const keys = keyPath.split('.');
+        let current = jsonContent;
+        // Navigate to the parent of the target property
+        for (let i = 0; i < keys.length - 1; i++) {
+            if (!(keys[i] in current)) {
+                throw new Error(`Key path ${keyPath} not found in JSON file`);
+            }
+            current = current[keys[i]];
+        }
+        // Update the value
+        const lastKey = keys[keys.length - 1];
+        if (!(lastKey in current)) {
+            throw new Error(`Key ${lastKey} not found in JSON file`);
+        }
+        current[lastKey] = newValue;
+        // Write the updated JSON back to the file
+        fs.writeFileSync(filePath, JSON.stringify(jsonContent, null, 2));
+        return true;
+    }
+    catch (error) {
+        logError('Error updating JSON file:' + error.message);
+        return false;
+    }
+}