Merge pull request #9 from kuzzleio/v2

Version 2.x

package.json

@@ -1,7 +1,7 @@
 {
   "name": "kuzdoc",
   "description": "The CLI that helps build the Kuzzle Docs",
-  "version": "1.5.1",
+  "version": "2.4.2",
   "author": "The Kuzzle Team <[email protected]>",
   "bin": {
     "kuzdoc": "./bin/run"
@@ -17,6 +17,7 @@
     "cli-ux": "^5.5.1",
     "execa": "^5.0.0",
     "express": "^4.17.1",
+    "fs-extra": "^10.0.0",
     "inquirer": "^7.3.3",
     "listr": "^0.14.3",
     "tslib": "^2.1.0",
@@ -25,7 +26,9 @@
   "devDependencies": {
     "@oclif/dev-cli": "^1.26.0",
     "@types/express": "^4.17.11",
+    "@types/fs-extra": "^9.0.11",
     "@types/inquirer": "^7.3.1",
+    "@types/lodash": "^4.14.170",
     "@types/node": "^14.14.22",
     "eslint": "^7.18.0",
     "eslint-config-oclif": "^3.1.0",

src/commands/add-repo.ts

@@ -0,0 +1,29 @@
+import { Command, flags } from '@oclif/command'
+import { assertIsFrameworkRoot } from '../lib/assertions'
+import { addNewRepo } from '../lib/repo'
+
+export default class AddRepo extends Command {
+  static description = `Wizard to add a new repo to repositories.yml.
+  NOTE: This command must be executed from the root of the framework meta-repo.`
+
+  static flags = {
+    help: flags.help({ char: 'h' }),
+  }
+
+  async run() {
+    this.log('\n  📦 Add new repo to repositories.yml\n')
+
+    try {
+      assertIsFrameworkRoot(process.cwd())
+    } catch (error) {
+      this.log('⛔️ Aborting.')
+      this.log(`It doesn't seem that you are executing this command from the root of the framework repo ${process.cwd()}: ${error.message}`)
+      return
+    }
+
+    await addNewRepo(process.cwd())
+
+    this.log('\n  ✅ All done!')
+    this.log('  The new repo item has been added to the list in repositories.yml\n')
+  }
+}

src/commands/add-section.ts

@@ -0,0 +1,104 @@
+import { Command, flags } from '@oclif/command'
+import inquirer from 'inquirer'
+import path from 'path'
+import { assertIsFrameworkRoot } from '../lib/assertions'
+import { writeFileSync } from 'fs'
+
+export default class AddSection extends Command {
+  static description = `Wizard to add a new section in src/.vuepress/sections.json.
+  NOTE: This command must be executed from the root of the framework meta-repo.`
+
+  static flags = {
+    help: flags.help({ char: 'h' }),
+  }
+
+  async run() {
+    this.log('\n  📖 Add new section to the documentation\n')
+
+    try {
+      assertIsFrameworkRoot(process.cwd())
+    } catch (error) {
+      this.log('⛔️ Aborting.')
+      this.log(`It doesn't seem that you are executing this command from the root of the framework repo ${process.cwd()}: ${error.message}`)
+      return
+    }
+
+    const answers = await inquirer.prompt([{
+      message: 'What is the name of the section? (it will be probably shown in a menu or a list, e.g. "Dart Null Safety")',
+      type: 'input',
+      name: 'name'
+    }, {
+      message: 'Select the Kuzzle major version this section is part of',
+      type: 'list',
+      choices: ['v1.x', 'v2.x'],
+      name: 'kuzzleMajor',
+      default: 'v2.x'
+    }, {
+      message: 'What is the version of the product in this section? (e.g. "3" for the Dart SDK v3)',
+      type: 'number',
+      name: 'version'
+    }, {
+      message: 'What will be the path to the section? (e.g. /sdk/dart/3)',
+      type: 'input',
+      name: 'path'
+    }, {
+      message: 'What is the identifier of this section? (e.g. dart, or home)',
+      type: 'input',
+      name: 'id'
+    }, {
+      message: 'Is this section a child of a parent section? (e.g. the parent of "dart" would be "sdk"',
+      type: 'confirm',
+      name: 'hasParent'
+    }, {
+      message: 'Then what is the name of the parent section? (e.g. "sdk")',
+      type: 'input',
+      when: answers => answers.hasParent === true,
+      name: 'parentSection'
+    }, {
+      message: 'Does this section have an icon? (to be shown in index pages or dropdown menus)',
+      type: 'confirm',
+      name: 'hasIcon'
+    }, {
+      message: 'Then, what is the path to the icon? (e.g. /logos/dart.svg)',
+      type: 'input',
+      name: 'icon',
+      when: answers => answers.hasIcon === true
+    }, {
+      message: 'Do you want to release this section? (if not, the section will be created but will not be added to the docs indexes)',
+      type: 'confirm',
+      name: 'released',
+      default: true
+    }])
+
+    const sectionsFilePath = path.join(process.cwd(), 'src', '.vuepress', 'sections.json')
+    const sections = require(sectionsFilePath)
+
+    const newSection = {
+      name: answers.name,
+      version: answers.version,
+      kuzzleMajor: answers.kuzzleMajor,
+      released: answers.released,
+      icon: undefined,
+      section: undefined,
+      subsection: undefined
+    }
+
+    if (answers.hasIcon) {
+      newSection.icon = answers.icon
+    }
+
+    if (answers.hasParent) {
+      newSection.section = answers.parentSection
+      newSection.subsection = answers.id
+    } else {
+      newSection.section = answers.id
+    }
+
+    sections[answers.path] = newSection
+
+    writeFileSync(path.join(process.cwd(), 'src', '.vuepress', 'sections.json'), JSON.stringify(sections, null, 2))
+
+    this.log('\n  ✅ All done!')
+    this.log('  The new section item has been added to the list in src/.vuepress/sections.json\n')
+  }
+}

src/commands/build-and-deploy.ts

@@ -0,0 +1,96 @@
+import { Command, flags } from '@oclif/command'
+import Listr from 'listr'
+import { buildRepo, deployRepo, invalidateCloudfront } from '../lib/build'
+import { ENV_CLOUDFRONT_ID, ENV_REPO, ENV_S3_BUCKET, VALUE_ALL_REPOS } from '../lib/constants'
+import { assertIsFrameworkRoot } from '../lib/assertions'
+import { resolveRepoList } from '../lib/repo'
+
+export default class BuildAndDeploy extends Command {
+  static description = `Builds and deploys one or more repositories.
+  NOTE: This command must be executed from the root of the framework meta-repo.
+
+The repositories must be previously installed in the framework via the "install" command.
+The repositories to be built can be specified via the --repo flag, the KUZDOC_REPO environment
+variable, or via the interactive prompt (only the installed repositories are listed).
+The built repositories are deployed to the S3 bucket specified via the --s3Bucket flag,
+then the Cloudfront cache (specified via --cloufrtontId) is invalidated.
+This command needs the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables to
+be properly set.
+`
+
+  static flags = {
+    help: flags.help({ char: 'h' }),
+    repo: flags.string({
+      description: `The list of repositories to build, or the value ${VALUE_ALL_REPOS} to build all repos.
+If not specified, kuzdoc will ask a prompt.
+
+Environment variable: $${ENV_REPO}`,
+      default: process.env[ENV_REPO]
+    }),
+    s3Bucket: flags.string({
+      description: `The name of the S3 bucket to upload the repos to.
+
+Environment variable: $${ENV_S3_BUCKET}`,
+      default: process.env[ENV_S3_BUCKET],
+      required: true
+    }),
+    cloudfrontId: flags.string({
+      description: `The name of the Cloudfront distribution to invalidate after deploying each repo.
+
+Environment variable: $${ENV_CLOUDFRONT_ID}`,
+      default: process.env[ENV_CLOUDFRONT_ID],
+      required: true
+    }),
+    dryRun: flags.boolean({
+      description: 'Only builds the repo without deploying it',
+      default: false
+    })
+  }
+
+  async run() {
+    try {
+      assertIsFrameworkRoot(process.cwd())
+    } catch (error) {
+      this.log('⛔️ Aborting.')
+      this.log(`It doesn't seem that you are executing this command from the root of the framework repo ${process.cwd()}: ${error.message}`)
+      return
+    }
+    const { flags } = this.parse(BuildAndDeploy)
+    if (!flags.dryRun && !process.env.AWS_ACCESS_KEY_ID) {
+      throw new Error('AWS_ACCESS_KEY_ID environment variable not found.')
+    }
+    if (!flags.dryRun && !process.env.AWS_SECRET_ACCESS_KEY) {
+      throw new Error('AWS_SECRET_ACCESS_KEY environment variable not found.')
+    }
+    const repoList = await resolveRepoList(flags.repo, true)
+    if (repoList.length === 0) {
+      this.log(`\n  🤷‍♂️ No repo resolved from ${flags.repo}.\n`)
+      return
+    }
+
+    if (flags.repo) {
+      this.log(`\n  👉 Resolved repos ${repoList.map(r => r.name).join(', ')}\n`)
+    }
+
+    const tasks = new Listr(repoList.map(repo => ({
+      title: `Build & deploy ${repo.name}`,
+      task: () => new Listr([{
+        title: 'Build repo',
+        task: () => buildRepo(repo)
+      }, {
+        title: 'Deploy repo',
+        task: () => deployRepo(repo, flags.s3Bucket, flags.dryRun)
+      }, {
+        title: 'Invalidate Cloudfront distribution',
+        skip: () => {
+          if (flags.dryRun) {
+            return 'Not invalidating in dry-run'
+          }
+        },
+        task: () => invalidateCloudfront(repo.deployPath, flags.cloudfrontId)
+      }])
+    })))
+
+    await tasks.run()
+  }
+}