feat: adiciona uma Interface de Linha de Comando (CLI) para criar novos conceitos

.gitignore

@@ -75,4 +75,7 @@ $RECYCLE.BIN/
 # Windows shortcuts
 *.lnk
 
+# Node.js
+node_modules/
+
 # End of https://www.toptal.com/developers/gitignore/api/windows,macos,linux

cli/README.md

@@ -0,0 +1,75 @@
+# Diciotech Command Line Interface (CLI)
+
+A **CLI do Diciotech** permite que você crie novos termos de forma interativa através de um terminal. Esta ferramenta foi desenvolvida usando o framework Node.js. Portanto, é necessário ter o Node.js instalado em sua máquina para utilizar a CLI.
+
+## Sumário
+
+- [Diciotech Command Line Interface (CLI)](#diciotech-command-line-interface-cli)
+  - [Sumário](#sumário)
+  - [Introdução](#introdução)
+  - [Instalação](#instalação)
+  - [Clonando o Repositório](#clonando-o-repositório)
+  - [Criando um novo termo](#criando-um-novo-termo)
+  - [Criando um novo termo com código](#criando-um-novo-termo-com-código)
+  - [Visualização](#visualização)
+  - [Contribuição](#contribuição)
+
+## Introdução
+
+A CLI do Diciotech é projetada para facilitar a criação e a gestão de termos de maneira eficiente. Este documento guiará você pelo processo de instalação, configuração e uso da ferramenta, garantindo que você possa contribuir com novos termos para o repositório do Diciotech.
+
+## Instalação
+
+Para começar, você precisa instalar o Node.js. Acesse o guia de instalação para diversos sistemas operacionais na [documentação oficial do Node.js](https://nodejs.org/en/download/) e instale uma versão a partir da `18.17.1`.
+
+## Clonando o Repositório
+
+Após instalar o Node.js, você precisa fazer um fork do projeto. Consulte o guia para [criar um fork de um repositório](https://docs.github.com/pt/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo).
+
+Feito isso, você pode clonar o fork do diciotech que está em seu perfil do GitHub e começar a contribuir com novos termos. Siga os passos abaixo para clonar o fork:
+
+1. Por exemplo, para clonar o fork, execute o seguinte comando em seu terminal (substitua `<my-user>` pelo seu nome de usuário do GitHub):
+    ```bash
+    git clone https://github.com/<my-user>/diciotech.git
+    ```
+
+2. Navegue até o diretório do projeto:
+    ```bash
+    cd diciotech
+    ```
+
+3. Crie uma nova branch para adicionar o termo:
+    ```bash
+    git checkout -b my-branch-name # ou git switch -c my-branch-name
+    ```
+
+## Criando um novo termo
+
+Para criar um novo termo, execute o comando `npm run new` em seu terminal. A CLI fará uma série de perguntas:
+
+1. Nome do termo que você deseja criar.
+2. Definição que descreve o termo.
+3. Categoria(s) do termo (tecla `Space` para selecionar).
+4. Visualização prévia do termo antes de criá-lo.
+5. Confirmação para gravar o termo.
+
+Após responder às perguntas, o termo será criado. Em seguida, você pode fazer um pull request para o repositório do [Diciotech](https://github.com/levxyca/diciotech.git). Consulte o guia [CONTRIBUTING](https://github.com/levxyca/diciotech/blob/main/CONTRIBUTING.md) para mais detalhes sobre como contribuir.
+
+## Criando um novo termo com código
+
+Para criar um novo termo com um exemplo de código:
+
+1. Localize o arquivo **code** na raiz do projeto.
+2. Abra o arquivo e adicione o código que deseja incluir, devidamente indentado.
+3. Execute o comando `npm run new` no seu terminal e siga os passos mencionados anteriormente.
+4. Quando a CLI perguntar se você deseja visualizar o termo, selecione `Sim` para ver o termo com o código que você adicionou.
+
+## Visualização
+
+<img src="https://i.imgur.com/RXHCynd.png"  width="100%" />
+
+## Contribuição
+
+Quer contribuir para o Diciotech? Confira nosso guia de contribuição para aprender como você pode ajudar a melhorar e expandir o projeto. Seu feedback e suas contribuições são muito bem-vindos!
+
+Para mais informações, consulte o [guia de contribuição](https://github.com/levxyca/diciotech/blob/main/CONTRIBUTING.md).

cli/commands/new-term.ts

@@ -0,0 +1,140 @@
+import { intro, outro } from '@clack/prompts';
+import crypto from "node:crypto";
+import c from 'ansi-colors';
+
+import { subjectivePromptQuestions } from "../core/questions";
+import { availableTags } from "../core/available-tags";
+
+import { multiSelect } from "../io/prompts/multiselect";
+import { subjectiveQuestion } from "../io/prompts/text";
+import { readFileContents } from "../io/read-file-sync";
+import { confirmPrompt } from "../io/prompts/confirm";
+import { writeToFile } from "../io/write-to-file";
+import { notePrompt } from "../io/prompts/note";
+
+import { cardsPath } from "../config/cards_pt-br-path";
+import { codePath } from "../config/code-path";
+
+import { parseJSONTerms } from "../utils/parse-terms";
+import { merge } from "../utils/merge-item";
+
+import { Term } from "../types";
+import fs from "node:fs";
+
+/**
+ * Prompts the user for the term's information.
+ */
+export const createNewTerm = async (): Promise<Term> => {
+  intro(c.bold.bgCyanBright.black(" Olá, boas-vindas ao Diciotech CLI! "))
+
+  fs.stat(codePath, (err) => {
+    if (err) {
+      fs.writeFileSync(codePath, "")
+    }
+  })
+
+  notePrompt(
+    c.cyanBright(`Antes de começar, precisamos saber se o seu conceito ${c.bold.yellow("possui algum trecho de código")}.\nSe sim, você pode ${c.bold.yellow("escrever o código no arquivo")} ${c.bold.magenta(codePath)}.\nCaso contrário, ${c.bold.yellow("apenas ignore isso e continue")}.`),
+    c.bold.bgYellow.black(" Importante ")
+  )
+
+  const [promptTitle, promptDescription] = subjectivePromptQuestions
+
+  const title = await subjectiveQuestion({
+    message: c.cyanBright(promptTitle.message),
+    validation: promptTitle.validation,
+  })
+  const description = await subjectiveQuestion({
+    message: c.cyanBright(promptDescription.message),
+    validation: promptDescription.validation,
+  })
+
+  const tags = await multiSelect(
+    "Selecione a(s) (tag)s relacionada(s) ao conceito",
+    availableTags,
+    (tags: symbol | string[]) => {
+      if (typeof tags !== 'symbol' && tags.length < 1) {
+        outro(c.bgRed.black(" Você precisa selecionar pelo menos uma tag. Tente novamente. "))
+        process.exit(0);
+      }
+    }
+  )
+
+  const code = readFileContents(codePath)
+
+  const card = {
+    id: crypto.randomBytes(16).toString("hex"),
+    title: title.toString(),
+    description: description.toString(),
+    tags: Array.isArray(tags) ? tags as string[] : [],
+    content: {
+      code: code?.trim(),
+    },
+  };
+
+  const shouldVisualizeTerm = await confirmPrompt(
+    c.cyanBright(`Deseja ${c.bold("visualizar")} o novo termo ?`)
+  );
+
+  const truncatedDescription = card.description.length > 60 ? `${card.description.slice(0, 60)}...` : card.description
+
+  if (shouldVisualizeTerm) {
+    notePrompt(
+      JSON.stringify({
+        title: card.title,
+        description: truncatedDescription,
+        tags: card.tags,
+        content: {
+          code: card.content.code.split("\n").filter(line => line !== "")
+        }
+      }, null, 2),
+      c.bold.bgCyanBright.black(" Termo ")
+    )
+  }
+
+  const shouldContinue = await confirmPrompt(
+    c.cyanBright(`Show! Agora vamos gravar o conceito. ${c.bold("Deseja continuar")} ?`)
+  )
+
+  if (!shouldContinue) {
+    outro(c.bgYellow.black(` Tudo bem! Se quiser tentar novamente, é só rodar o comando ${c.bold('npm run new')}. `))
+    process.exit(0);
+  }
+
+  return card;
+};
+
+/**
+ * Compounds all the steps to write a new term to a file.
+ */
+const compose = (
+  newTerm: Term,
+  filepath: string
+) =>
+  writeToFile(
+    filepath,
+    JSON.stringify({
+      cards: merge(parseJSONTerms(readFileContents(filepath)), newTerm)
+    }, null, 2)
+  );
+
+export const newTerm = async () => {
+  try {
+    const newTerm = await createNewTerm();
+    compose(newTerm, cardsPath);
+
+    writeToFile(codePath, ""); // clear code file
+
+    notePrompt(c.cyanBright(`Se você quiser adicionar mais termos, é só rodar o comando ${c.bold('npm run new')}`), c.bold.bgGreen.black(" Feito "));
+    outro(c.green(`Tudo certo! você pode abrir um ${c.bold("Pull Request")} em <${c.bold("https://github.com/levxyca/diciotech/pulls")}>`))
+  } catch (error: unknown) {
+    notePrompt(
+      c.italic.red(`- Ocorreu um erro ao adicionar o novo termo.\n- Tente novamente seguindo as instruções.\n- Caso o erro persista, abra uma issue em https://github.com/levxyca/diciotech/issues.`),
+      c.bold.bgRedBright.black(" Eita! Algo deu errado :( ")
+    )
+
+    if (error instanceof Error) {
+      outro(c.red(`❌ ${error.message}`));
+    }
+  }
+};

cli/config/cards_pt-br-path.ts

@@ -0,0 +1,10 @@
+import path from "node:path";
+
+export const cardsPath = path.join(
+  __dirname,
+  "..",
+  "..",
+  "assets",
+  "data",
+  "cards_pt-br.json"
+);

cli/config/code-path.ts

@@ -0,0 +1,3 @@
+import path from "path";
+
+export const codePath = path.join(__dirname, "..", "..", "code");

cli/core/available-tags.ts

@@ -0,0 +1,14 @@
+import { AvailableTags } from "../types";
+
+export const availableTags: AvailableTags[] = [
+  { value: "Back-end", label: "Back-end" },
+  { value: "Biblioteca", label: "Biblioteca" },
+  { value: "Conceito", label: "Conceito", hint: "recommended" },
+  { value: "Design", label: "Design" },
+  { value: "Ferramenta", label: "Ferramenta" },
+  { value: "Framework", label: "Framework" },
+  { value: "Front-end", label: "Front-end" },
+  { value: "Mobile", label: "Mobile" },
+  { value: "Paradigma", label: "Paradigma" },
+  { value: "Versionamento", label: "Versionamento" },
+];

cli/core/prompt-validations.ts

@@ -0,0 +1,21 @@
+export const validations = {
+  title: (input: string) => {
+    const raw = input.trim();
+
+    if (raw.trim().length < 1) {
+      return `O título precisa ter pelo menos 1 caractere. Você digitou ${raw.length} caracteres.`
+    }
+  },
+  description: (input: string) => {
+    const raw = input.trim();
+
+    if (raw.length < 10) {
+      return `A descrição precisa ter pelo menos 10 caracteres. Você digitou ${raw.length} caracteres.`;
+    }
+  },
+  tags: (input: string[]) => {
+    if (input.length < 1) {
+      return `Você precisa selecionar pelo menos uma tag. Você selecionou ${input.length} opções.`
+    }
+  },
+};

cli/core/questions.ts

@@ -0,0 +1,18 @@
+import { validations } from "./prompt-validations";
+
+export const inputBase = {
+  required: true,
+};
+
+export const subjectivePromptQuestions = [
+  {
+    message: "Digite o nome do conceito",
+    validation: validations.title,
+    required: true,
+  },
+  {
+    ...inputBase,
+    message: "Digite a descrição do conceito",
+    validation: validations.description
+  },
+];

cli/index.ts

@@ -0,0 +1,5 @@
+import { newTerm } from "./commands/new-term";
+
+const main = () => newTerm();
+
+main();

cli/io/prompts/confirm.ts

@@ -0,0 +1,18 @@
+import { confirm } from "@clack/prompts";
+
+import { handleCancelation } from "../../utils/handle-cancel";
+
+/**
+ * Generic multiselect prompt. Prompts the user for multiple options.
+ */
+export const confirmPrompt = async (message: string): Promise<symbol | boolean> => {
+  const shouldContinue = await confirm({
+    message: message,
+    active: 'Sim',
+    inactive: 'Não',
+    initialValue: true,
+  });
+
+  handleCancelation(shouldContinue); // handle the user cancelation
+  return shouldContinue;
+};

cli/io/prompts/multiselect.ts

@@ -0,0 +1,26 @@
+import c from "ansi-colors";
+import { multiselect } from "@clack/prompts";
+
+import { handleCancelation } from "../../utils/handle-cancel";
+
+import { AvailableTags } from "../../types";
+
+
+/**
+ * Generic multiselect prompt. Prompts the user for multiple options.
+ */
+export const multiSelect = async (
+  message: string,
+  availableTags: AvailableTags[],
+  cb: Function
+): Promise<symbol | unknown[] | void> => {
+  const tags = await multiselect({
+    message: c.cyanBright(message),
+    options: availableTags,
+    required: true,
+  });
+
+  cb(tags); // callback to validate the tags
+  handleCancelation(tags); // handle the user cancelation
+  return tags;
+};

cli/io/prompts/note.ts

@@ -0,0 +1,6 @@
+import { note as prompt } from "@clack/prompts"
+
+export const notePrompt = (message: string, title: string) => {
+  const note = prompt(message, title)
+  return note
+}

cli/io/prompts/text.ts

@@ -0,0 +1,21 @@
+
+import { text } from "@clack/prompts";
+
+import { handleCancelation } from "../../utils/handle-cancel";
+
+import { SubjectiveQuestion } from "../../types";
+
+interface QuestionProps {
+  message: string;
+  validation: (value: string) => void | string;
+}
+
+export const subjectiveQuestion = async (props: QuestionProps): Promise<SubjectiveQuestion> => {
+   const prompt = await text({
+    message: props.message,
+    validate: props.validation
+  });
+
+  handleCancelation(prompt);
+  return prompt;
+};

cli/io/read-file-sync.ts

@@ -0,0 +1,6 @@
+import fs from 'node:fs';
+
+/**
+ * Reads the content of a file.
+ */
+export const readFileContents = (path: string) => fs.readFileSync(path).toString();

cli/io/write-to-file.ts

@@ -0,0 +1,9 @@
+import fs from 'node:fs';
+
+/**
+ * Writes updated terms to a file.
+ */
+export const writeToFile = (path: string, content: string): void => {
+  fs.writeFileSync(path, content);
+  return;
+};