ilumin-cli 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -17
- package/dist/commands/mcp-add.d.ts.map +1 -1
- package/dist/commands/mcp-add.js +14 -8
- package/dist/commands/mcp-add.js.map +1 -1
- package/dist/commands/skills-install.d.ts +14 -0
- package/dist/commands/skills-install.d.ts.map +1 -0
- package/dist/commands/skills-install.js +40 -0
- package/dist/commands/skills-install.js.map +1 -0
- package/dist/index.js +12 -0
- package/dist/index.js.map +1 -1
- package/dist/utils/install-skills.d.ts +15 -0
- package/dist/utils/install-skills.d.ts.map +1 -0
- package/dist/utils/install-skills.js +59 -0
- package/dist/utils/install-skills.js.map +1 -0
- package/package.json +7 -3
- package/skills/ilumin-cloud/SKILL.md +217 -0
- package/skills/ilumin-cloud/references/compose.md +425 -0
- package/skills/ilumin-cloud/references/recommended-stack.md +179 -0
- package/skills/ilumin-security/SKILL.md +355 -0
package/README.md
CHANGED
|
@@ -1,43 +1,48 @@
|
|
|
1
|
-
#
|
|
1
|
+
# ilumin-cli
|
|
2
2
|
|
|
3
3
|
CLI oficial da [Ilumin Cloud](https://ilumin.app) para instalar o MCP server em clientes de IA com **um único comando**.
|
|
4
4
|
|
|
5
5
|
## Instalação rápida do MCP
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
|
-
npx -y
|
|
8
|
+
npx -y ilumin-cli@latest mcp add ilumin --client claude-code --x-api-key SUA_CHAVE
|
|
9
9
|
```
|
|
10
10
|
|
|
11
11
|
### Clientes suportados
|
|
12
12
|
|
|
13
|
-
| Flag `--client` | Cliente de IA
|
|
14
|
-
|
|
15
|
-
| `claude-code` | Claude Code (CLI)
|
|
16
|
-
| `claude-desktop` | Claude Desktop
|
|
17
|
-
|
|
|
18
|
-
|
|
|
19
|
-
| `
|
|
13
|
+
| Flag `--client` | Cliente de IA | Arquivo modificado |
|
|
14
|
+
|-------------------|----------------------------------|-----------------------------------------------------------------------|
|
|
15
|
+
| `claude-code` | Claude Code **(CLI de terminal)**| `~/.claude.json` |
|
|
16
|
+
| `claude-desktop` | Claude Desktop **(app GUI)** | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` |
|
|
17
|
+
| | | Windows: `%APPDATA%\Claude\claude_desktop_config.json` |
|
|
18
|
+
| | | Linux: `~/.config/Claude/claude_desktop_config.json` |
|
|
19
|
+
| `gemini` | Gemini CLI | `~/.gemini/settings.json` |
|
|
20
|
+
| `cursor` | Cursor Editor | `~/.cursor/mcp.json` |
|
|
21
|
+
| `codex` | OpenAI Codex | `~/.codex/config.toml` |
|
|
20
22
|
|
|
21
23
|
### Exemplos
|
|
22
24
|
|
|
23
25
|
```bash
|
|
24
|
-
# Claude Code
|
|
25
|
-
npx -y
|
|
26
|
+
# Claude Code (CLI de terminal)
|
|
27
|
+
npx -y ilumin-cli@latest mcp add ilumin --client claude-code --x-api-key ilu_...
|
|
26
28
|
|
|
27
|
-
#
|
|
28
|
-
npx -y
|
|
29
|
+
# Claude Desktop (app GUI)
|
|
30
|
+
npx -y ilumin-cli@latest mcp add ilumin --client claude-desktop --x-api-key ilu_...
|
|
31
|
+
|
|
32
|
+
# Gemini CLI
|
|
33
|
+
npx -y ilumin-cli@latest mcp add ilumin --client gemini --x-api-key ilu_...
|
|
29
34
|
|
|
30
35
|
# Cursor
|
|
31
|
-
npx -y
|
|
36
|
+
npx -y ilumin-cli@latest mcp add ilumin --client cursor --x-api-key ilu_...
|
|
32
37
|
|
|
33
38
|
# OpenAI Codex
|
|
34
|
-
npx -y
|
|
39
|
+
npx -y ilumin-cli@latest mcp add ilumin --client codex --x-api-key ilu_...
|
|
35
40
|
|
|
36
41
|
# Todos os clientes de uma vez
|
|
37
|
-
npx -y
|
|
42
|
+
npx -y ilumin-cli@latest mcp add ilumin --x-api-key ilu_...
|
|
38
43
|
|
|
39
44
|
# Múltiplos clientes específicos
|
|
40
|
-
npx -y
|
|
45
|
+
npx -y ilumin-cli@latest mcp add ilumin --client claude-code,gemini --x-api-key ilu_...
|
|
41
46
|
```
|
|
42
47
|
|
|
43
48
|
## O que o comando faz?
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"mcp-add.d.ts","sourceRoot":"","sources":["../../src/commands/mcp-add.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;
|
|
1
|
+
{"version":3,"file":"mcp-add.d.ts","sourceRoot":"","sources":["../../src/commands/mcp-add.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwBH,UAAU,aAAa;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAuEtE"}
|
package/dist/commands/mcp-add.js
CHANGED
|
@@ -11,6 +11,7 @@ import { installClaudeDesktop } from "../clients/claude-desktop.js";
|
|
|
11
11
|
import { installGemini } from "../clients/gemini.js";
|
|
12
12
|
import { installCursor } from "../clients/cursor.js";
|
|
13
13
|
import { installCodex } from "../clients/codex.js";
|
|
14
|
+
import { installSkillsForClient } from "../utils/install-skills.js";
|
|
14
15
|
// Clientes disponíveis com metadados
|
|
15
16
|
const SUPPORTED_CLIENTS = {
|
|
16
17
|
"claude-code": { label: "Claude Code" },
|
|
@@ -55,28 +56,33 @@ export function runMcpAdd(server, options) {
|
|
|
55
56
|
process.exit(1);
|
|
56
57
|
}
|
|
57
58
|
}
|
|
58
|
-
console.log();
|
|
59
|
-
console.log(kleur.bold(` Instalando ${kleur.magenta("IluminMCP")} para: ${targets.map((t) => SUPPORTED_CLIENTS[t].label).join(", ")}`));
|
|
60
|
-
console.log();
|
|
61
59
|
let hasError = false;
|
|
62
60
|
for (const client of targets) {
|
|
63
61
|
const label = SUPPORTED_CLIENTS[client].label;
|
|
64
62
|
try {
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
printSuccess(`${label}: ${action} em ${kleur.gray(result.filePath)}`);
|
|
63
|
+
installForClient(client, apiKey);
|
|
64
|
+
printSuccess(`IluminMCP instalado no ${label}`);
|
|
68
65
|
}
|
|
69
66
|
catch (err) {
|
|
70
67
|
hasError = true;
|
|
71
68
|
const msg = err instanceof Error ? err.message : String(err);
|
|
72
69
|
printError(`${label}: ${msg}`);
|
|
70
|
+
continue;
|
|
71
|
+
}
|
|
72
|
+
try {
|
|
73
|
+
const skillsDir = installSkillsForClient(client);
|
|
74
|
+
printSuccess(`Skills instaladas em ${skillsDir}`);
|
|
75
|
+
}
|
|
76
|
+
catch (err) {
|
|
77
|
+
const msg = err instanceof Error ? err.message : String(err);
|
|
78
|
+
printWarning(`${label}: skills não instaladas — ${msg}`);
|
|
73
79
|
}
|
|
74
80
|
}
|
|
75
81
|
console.log();
|
|
76
82
|
if (!hasError) {
|
|
77
|
-
printSuccess("
|
|
83
|
+
printSuccess("Reinicie seu cliente de IA para começar a usar.");
|
|
78
84
|
console.log();
|
|
79
|
-
console.log(kleur.
|
|
85
|
+
console.log(kleur.cyan(" https://ilumin.app"));
|
|
80
86
|
}
|
|
81
87
|
else {
|
|
82
88
|
printWarning("Instalação concluída com erros. Verifique as mensagens acima.");
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"mcp-add.js","sourceRoot":"","sources":["../../src/commands/mcp-add.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;
|
|
1
|
+
{"version":3,"file":"mcp-add.js","sourceRoot":"","sources":["../../src/commands/mcp-add.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* commands/skills-install.ts
|
|
3
|
+
*
|
|
4
|
+
* Implementa o subcomando: ilumin skills install [--agent <agent>]
|
|
5
|
+
*
|
|
6
|
+
* Delega para o pacote `skills` (npx skills add IluminClients/ilumin-cli --all -g)
|
|
7
|
+
* que já lida com todos os clientes de IA suportados.
|
|
8
|
+
*/
|
|
9
|
+
interface SkillsInstallOptions {
|
|
10
|
+
agent?: string;
|
|
11
|
+
}
|
|
12
|
+
export declare function runSkillsInstall(options: SkillsInstallOptions): void;
|
|
13
|
+
export {};
|
|
14
|
+
//# sourceMappingURL=skills-install.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"skills-install.d.ts","sourceRoot":"","sources":["../../src/commands/skills-install.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,UAAU,oBAAoB;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAgCpE"}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* commands/skills-install.ts
|
|
3
|
+
*
|
|
4
|
+
* Implementa o subcomando: ilumin skills install [--agent <agent>]
|
|
5
|
+
*
|
|
6
|
+
* Delega para o pacote `skills` (npx skills add IluminClients/ilumin-cli --all -g)
|
|
7
|
+
* que já lida com todos os clientes de IA suportados.
|
|
8
|
+
*/
|
|
9
|
+
import { spawnSync } from "child_process";
|
|
10
|
+
import kleur from "kleur";
|
|
11
|
+
import { printInfo, printSuccess, printError } from "../utils/logger.js";
|
|
12
|
+
export function runSkillsInstall(options) {
|
|
13
|
+
const repo = "IluminClients/ilumin-cli";
|
|
14
|
+
const args = ["skills", "add", repo, "-g", "-y"];
|
|
15
|
+
if (options.agent) {
|
|
16
|
+
for (const agent of options.agent.split(",").map(a => a.trim())) {
|
|
17
|
+
args.push("--agent", agent);
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
else {
|
|
21
|
+
args.push("--all");
|
|
22
|
+
}
|
|
23
|
+
printInfo(`Instalando skills da Ilumin via: npx ${args.join(" ")}`);
|
|
24
|
+
console.log();
|
|
25
|
+
const result = spawnSync("npx", args, {
|
|
26
|
+
stdio: "inherit",
|
|
27
|
+
shell: true,
|
|
28
|
+
});
|
|
29
|
+
if (result.status !== 0) {
|
|
30
|
+
printError("Falha ao instalar skills. Verifique sua conexão e tente novamente.");
|
|
31
|
+
process.exit(result.status ?? 1);
|
|
32
|
+
}
|
|
33
|
+
console.log();
|
|
34
|
+
printSuccess("Skills da Ilumin instaladas com sucesso!");
|
|
35
|
+
console.log();
|
|
36
|
+
console.log(kleur.gray(" Para atualizar as skills no futuro, execute:"));
|
|
37
|
+
console.log(kleur.cyan(" npx -y ilumin-cli@latest skills install"));
|
|
38
|
+
console.log();
|
|
39
|
+
}
|
|
40
|
+
//# sourceMappingURL=skills-install.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"skills-install.js","sourceRoot":"","sources":["../../src/commands/skills-install.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAMzE,MAAM,UAAU,gBAAgB,CAAC,OAA6B;IAC1D,MAAM,IAAI,GAAG,0BAA0B,CAAC;IAExC,MAAM,IAAI,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAEjD,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QAChB,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YAC9D,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;IACL,CAAC;SAAM,CAAC;QACJ,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC;IAED,SAAS,CAAC,wCAAwC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACpE,OAAO,CAAC,GAAG,EAAE,CAAC;IAEd,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE;QAClC,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,IAAI;KACd,CAAC,CAAC;IAEH,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,UAAU,CAAC,oEAAoE,CAAC,CAAC;QACjF,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,CAAC,GAAG,EAAE,CAAC;IACd,YAAY,CAAC,0CAA0C,CAAC,CAAC;IACzD,OAAO,CAAC,GAAG,EAAE,CAAC;IACd,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC,CAAC;IAC1E,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC,CAAC;IACrE,OAAO,CAAC,GAAG,EAAE,CAAC;AAClB,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
import { Command } from "commander";
|
|
12
12
|
import { printBrand } from "./utils/logger.js";
|
|
13
13
|
import { runMcpAdd } from "./commands/mcp-add.js";
|
|
14
|
+
import { runSkillsInstall } from "./commands/skills-install.js";
|
|
14
15
|
const program = new Command();
|
|
15
16
|
program
|
|
16
17
|
.name("ilumin")
|
|
@@ -28,5 +29,16 @@ mcp
|
|
|
28
29
|
printBrand();
|
|
29
30
|
runMcpAdd(server, options);
|
|
30
31
|
});
|
|
32
|
+
// Comando: ilumin skills
|
|
33
|
+
const skills = program.command("skills").description("Gerenciamento de skills de IA");
|
|
34
|
+
// Subcomando: ilumin skills install
|
|
35
|
+
skills
|
|
36
|
+
.command("install")
|
|
37
|
+
.description("Instala as skills da Ilumin em todos os clientes de IA detectados")
|
|
38
|
+
.option("--agent <agents>", "Cliente(s) alvo. Ex: claude-code, gemini, cursor. Use vírgula para múltiplos. Omita para instalar em todos.")
|
|
39
|
+
.action((options) => {
|
|
40
|
+
printBrand();
|
|
41
|
+
runSkillsInstall(options);
|
|
42
|
+
});
|
|
31
43
|
program.parse(process.argv);
|
|
32
44
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEhE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACF,IAAI,CAAC,QAAQ,CAAC;KACd,WAAW,CAAC,kBAAkB,CAAC;KAC/B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,sBAAsB;AACtB,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,8BAA8B,CAAC,CAAC;AAE/E,sCAAsC;AACtC,GAAG;KACE,OAAO,CAAC,cAAc,CAAC;KACvB,WAAW,CAAC,mDAAmD,CAAC;KAChE,MAAM,CACH,oBAAoB,EACpB,8IAA8I,CACjJ;KACA,MAAM,CAAC,mBAAmB,EAAE,gDAAgD,CAAC;KAC7E,MAAM,CAAC,CAAC,MAAc,EAAE,OAAO,EAAE,EAAE;IAChC,UAAU,EAAE,CAAC;IACb,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC,CAAC,CAAC;AAEP,yBAAyB;AACzB,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,CAAC,+BAA+B,CAAC,CAAC;AAEtF,oCAAoC;AACpC,MAAM;KACD,OAAO,CAAC,SAAS,CAAC;KAClB,WAAW,CAAC,mEAAmE,CAAC;KAChF,MAAM,CACH,kBAAkB,EAClB,6GAA6G,CAChH;KACA,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE;IAChB,UAAU,EAAE,CAAC;IACb,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC,CAAC,CAAC;AAEP,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC"}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* utils/install-skills.ts
|
|
3
|
+
*
|
|
4
|
+
* Instala todas as skills da Ilumin no diretório de skills do cliente de IA.
|
|
5
|
+
* Todas as pastas dentro de skills/ são instaladas dinamicamente.
|
|
6
|
+
*
|
|
7
|
+
* Caminhos por cliente:
|
|
8
|
+
* claude-code / claude-desktop → ~/.claude/skills/
|
|
9
|
+
* gemini → ~/.gemini/skills/
|
|
10
|
+
* cursor → ~/.cursor/skills/
|
|
11
|
+
* codex → ~/.agents/skills/
|
|
12
|
+
*/
|
|
13
|
+
import type { SupportedClient } from "../types.js";
|
|
14
|
+
export declare function installSkillsForClient(client: SupportedClient): string;
|
|
15
|
+
//# sourceMappingURL=install-skills.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"install-skills.d.ts","sourceRoot":"","sources":["../../src/utils/install-skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAmCnD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAYtE"}
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* utils/install-skills.ts
|
|
3
|
+
*
|
|
4
|
+
* Instala todas as skills da Ilumin no diretório de skills do cliente de IA.
|
|
5
|
+
* Todas as pastas dentro de skills/ são instaladas dinamicamente.
|
|
6
|
+
*
|
|
7
|
+
* Caminhos por cliente:
|
|
8
|
+
* claude-code / claude-desktop → ~/.claude/skills/
|
|
9
|
+
* gemini → ~/.gemini/skills/
|
|
10
|
+
* cursor → ~/.cursor/skills/
|
|
11
|
+
* codex → ~/.agents/skills/
|
|
12
|
+
*/
|
|
13
|
+
import fs from "fs";
|
|
14
|
+
import path from "path";
|
|
15
|
+
import os from "os";
|
|
16
|
+
import { fileURLToPath } from "url";
|
|
17
|
+
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
18
|
+
// dist/utils/ → ../../skills
|
|
19
|
+
const SKILLS_SOURCE_DIR = path.resolve(__dirname, "../../skills");
|
|
20
|
+
function skillsDirForClient(client) {
|
|
21
|
+
const home = os.homedir();
|
|
22
|
+
switch (client) {
|
|
23
|
+
case "claude-code":
|
|
24
|
+
case "claude-desktop":
|
|
25
|
+
return path.join(home, ".claude", "skills");
|
|
26
|
+
case "gemini":
|
|
27
|
+
return path.join(home, ".gemini", "skills");
|
|
28
|
+
case "cursor":
|
|
29
|
+
return path.join(home, ".cursor", "skills");
|
|
30
|
+
case "codex":
|
|
31
|
+
return path.join(home, ".agents", "skills");
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
function copyRecursive(src, dest) {
|
|
35
|
+
if (!fs.existsSync(src))
|
|
36
|
+
return;
|
|
37
|
+
fs.mkdirSync(dest, { recursive: true });
|
|
38
|
+
for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
|
|
39
|
+
const srcPath = path.join(src, entry.name);
|
|
40
|
+
const destPath = path.join(dest, entry.name);
|
|
41
|
+
if (entry.isDirectory()) {
|
|
42
|
+
copyRecursive(srcPath, destPath);
|
|
43
|
+
}
|
|
44
|
+
else {
|
|
45
|
+
fs.copyFileSync(srcPath, destPath);
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
export function installSkillsForClient(client) {
|
|
50
|
+
const destDir = skillsDirForClient(client);
|
|
51
|
+
const entries = fs.readdirSync(SKILLS_SOURCE_DIR, { withFileTypes: true });
|
|
52
|
+
for (const entry of entries) {
|
|
53
|
+
if (entry.isDirectory()) {
|
|
54
|
+
copyRecursive(path.join(SKILLS_SOURCE_DIR, entry.name), path.join(destDir, entry.name));
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
return destDir;
|
|
58
|
+
}
|
|
59
|
+
//# sourceMappingURL=install-skills.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"install-skills.js","sourceRoot":"","sources":["../../src/utils/install-skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAGpC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/D,6BAA6B;AAC7B,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AAElE,SAAS,kBAAkB,CAAC,MAAuB;IAC/C,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;IAC1B,QAAQ,MAAM,EAAE,CAAC;QACb,KAAK,aAAa,CAAC;QACnB,KAAK,gBAAgB;YACjB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAChD,KAAK,QAAQ;YACT,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAChD,KAAK,QAAQ;YACT,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QAChD,KAAK,OAAO;YACR,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IACpD,CAAC;AACL,CAAC;AAED,SAAS,aAAa,CAAC,GAAW,EAAE,IAAY;IAC5C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO;IAChC,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,KAAK,MAAM,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACtB,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACrC,CAAC;aAAM,CAAC;YACJ,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACvC,CAAC;IACL,CAAC;AACL,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,MAAuB;IAC1D,MAAM,OAAO,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,iBAAiB,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3E,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACtB,aAAa,CACT,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,KAAK,CAAC,IAAI,CAAC,EACxC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CACjC,CAAC;QACN,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACnB,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ilumin-cli",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Ilumin Cloud CLI — instala e gerencia o MCP da Ilumin em vários clientes de IA",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -9,10 +9,14 @@
|
|
|
9
9
|
"ilumin-cli": "dist/index.js"
|
|
10
10
|
},
|
|
11
11
|
"scripts": {
|
|
12
|
-
"build": "tsc && chmod +x dist/index.js",
|
|
12
|
+
"build": "tsc && chmod +x dist/index.js && node scripts/copy-skills.js",
|
|
13
13
|
"dev": "tsc --watch",
|
|
14
14
|
"start": "node dist/index.js"
|
|
15
15
|
},
|
|
16
|
+
"files": [
|
|
17
|
+
"dist",
|
|
18
|
+
"skills"
|
|
19
|
+
],
|
|
16
20
|
"dependencies": {
|
|
17
21
|
"commander": "^14.0.2",
|
|
18
22
|
"kleur": "^4.1.5",
|
|
@@ -37,6 +41,6 @@
|
|
|
37
41
|
"license": "MIT",
|
|
38
42
|
"repository": {
|
|
39
43
|
"type": "git",
|
|
40
|
-
"url": "https://github.com/iluminapp/ilumin-mcp"
|
|
44
|
+
"url": "git+https://github.com/iluminapp/ilumin-mcp.git"
|
|
41
45
|
}
|
|
42
46
|
}
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ilumin-cloud-developer
|
|
3
|
+
description: Use this skill when managing deployments, servers, custom domains, or installing and integrating applications using the Ilumin Cloud Model Context Protocol (MCP). Useful for building code, deploying, updating, and setting up catalog integrations like WhatsApp, databases, queues, and more.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Ilumin Cloud Developer
|
|
7
|
+
|
|
8
|
+
This skill provides the comprehensive workflow, tools, best practices, and contextual knowledge for interacting with Ilumin Cloud infrastructure via the Ilumin MCP Server.
|
|
9
|
+
|
|
10
|
+
## What is Ilumin Cloud?
|
|
11
|
+
|
|
12
|
+
**Ilumin Cloud** is a Brazilian PaaS (Platform as a Service) focused on simplifying self-hosted application deployment. It provides:
|
|
13
|
+
|
|
14
|
+
- **Managed VPS Servers** — The user has one or more cloud servers (e.g., `srv1.user.ilumin.app`) pre-configured with Docker, Traefik (reverse proxy), and SSL termination.
|
|
15
|
+
- **App Catalog** — A curated collection of ready-to-deploy open-source applications (databases, messaging APIs, automation tools, etc.) that can be installed with a single command — no Docker knowledge required from the user.
|
|
16
|
+
- **CI/CD Pipeline** — Users can push their own source code, which is built via Docker into an image, versioned with a timestamp tag, and deployed as a container.
|
|
17
|
+
- **Automatic HTTPS** — Every deployed app automatically gets a subdomain with SSL (e.g., `myapp.srv1.user.ilumin.app`), and custom domains can also be pointed via CNAME.
|
|
18
|
+
- **Traefik Routing** — All traffic is routed by a Traefik reverse proxy running on the server. Compose files must follow Ilumin's label conventions for routing to work correctly.
|
|
19
|
+
|
|
20
|
+
The Ilumin MCP connects AI agents directly to this infrastructure, enabling autonomous deployment, integration, and maintenance operations without requiring the user to use SSH or the Ilumin web dashboard manually.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## Common Use Cases
|
|
25
|
+
|
|
26
|
+
Understanding real-world scenarios where this skill is most valuable:
|
|
27
|
+
|
|
28
|
+
### Deploying a Custom Application
|
|
29
|
+
The user has a web app (Node.js, Python/FastAPI, Next.js, etc.) in a repository and wants it live on the internet. The AI uses `deploy_project` to build and push it, then `install_app` to deploy it for the first time, or `update_app` for subsequent deployments.
|
|
30
|
+
|
|
31
|
+
### Adding WhatsApp to a Project
|
|
32
|
+
The user wants to send/receive WhatsApp messages in their app. The AI installs the **Evolution API** from the catalog, then uses `get_catalog_app_documentation` to obtain its endpoint and API key, and writes the integration code into the user's project.
|
|
33
|
+
|
|
34
|
+
### Adding a Database
|
|
35
|
+
The user needs a PostgreSQL or Redis instance. The AI finds the appropriate app in the catalog and installs it on the same server, exposing the internal connection string for the user's application to consume.
|
|
36
|
+
|
|
37
|
+
### Integrating Automation Workflows
|
|
38
|
+
The user wants to automate tasks (email, webhooks, AI pipelines). The AI installs **n8n** or a similar tool from the catalog, which then connects to the user's app via webhooks or APIs.
|
|
39
|
+
|
|
40
|
+
### Connecting a Custom Domain
|
|
41
|
+
After deploying an app, the user wants it accessible at `app.mycompany.com` instead of the Ilumin subdomain. The AI uses `manage_domain` and instructs the user on configuring the CNAME at their DNS provider.
|
|
42
|
+
|
|
43
|
+
### Rolling Updates Without Downtime
|
|
44
|
+
The user has pushed new code. The AI runs `deploy_project` to build the new image, captures the timestamp tag, and runs `update_app` with the specific tag, ensuring Docker pulls the fresh layer and not a cached one.
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## App Catalog Overview
|
|
49
|
+
|
|
50
|
+
The catalog contains popular open-source services. When the user's need matches one of these, always prefer installing from the catalog instead of building from scratch:
|
|
51
|
+
|
|
52
|
+
| Category | Examples |
|
|
53
|
+
|---|---|
|
|
54
|
+
| **Messaging / WhatsApp** | Evolution API, Chatwoot |
|
|
55
|
+
| **Automation / Workflows** | n8n, Typebot |
|
|
56
|
+
| **Databases** | PostgreSQL, MySQL, Redis, MongoDB |
|
|
57
|
+
| **AI / LLMs** | Open WebUI, Flowise |
|
|
58
|
+
| **CMS / Web** | WordPress, Ghost, Strapi |
|
|
59
|
+
| **Analytics** | Metabase, Plausible |
|
|
60
|
+
| **Storage** | MinIO |
|
|
61
|
+
| **Email** | Mailu, Stalwart |
|
|
62
|
+
|
|
63
|
+
> Always run `list_catalog` to get the current up-to-date list and check if a specific app is available before suggesting a custom implementation.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Architecture Reference
|
|
68
|
+
|
|
69
|
+
Understanding Ilumin's infrastructure prevents misconfiguration:
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
[Internet] → [Traefik (reverse proxy on server)] → [Docker Containers]
|
|
73
|
+
↑
|
|
74
|
+
Reads routing rules from Docker labels
|
|
75
|
+
Handles SSL termination automatically
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
- **Each app is a Docker container** with a `docker-compose.yml` defining the service, network, and Traefik labels.
|
|
79
|
+
- **All containers** must be on the `network: ilumin-network` (or `external: true`) for Traefik to discover them and for containers to communicate internally.
|
|
80
|
+
- **Internal container-to-container communication** uses the container/service name as the hostname (e.g., a Python app connects to `postgres-service:5432` on the shared network).
|
|
81
|
+
- **`get_compose_guidelines`** returns the exact label templates and network definitions required — always use it before writing a compose file.
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## Available MCP Tools
|
|
86
|
+
|
|
87
|
+
The Ilumin MCP server exposes specialized tools for the complete application lifecycle. Prioritize these whenever the objective involves Ilumin Cloud resources:
|
|
88
|
+
|
|
89
|
+
### Information & Discovery
|
|
90
|
+
- **`list_servers`** — Discover the user's available servers, domains, and currently active applications. *Always use this to verify the environment state before proposing an installation.*
|
|
91
|
+
- **`list_deploys`** — Check historical build logs and image tags of past deployments.
|
|
92
|
+
- **`list_catalog`** — List official and community applications available for 1-click installation.
|
|
93
|
+
|
|
94
|
+
### Building & Versioning
|
|
95
|
+
- **`deploy_project`** — Zip and push the current project source code, triggering a Docker build in the cloud. Returns a specific image tag (timestamp format, e.g., `20260407130809`) on success.
|
|
96
|
+
- **`update_app`** — Update an existing application to a new version. **IMPORTANT**: Always use specific timestamp tags instead of `latest` to force Docker to pull the fresh image rather than using cached layers.
|
|
97
|
+
|
|
98
|
+
### Installation & Configuration
|
|
99
|
+
- **`install_app`** — Install a custom app onto a server for the first time. Requires a `docker-compose.yml` string formatted to Ilumin standards.
|
|
100
|
+
- **`get_compose_guidelines`** — **MANDATORY** before generating any Docker Compose file. Returns the Traefik labels, network standards, and variable placeholders required for correct domain mapping.
|
|
101
|
+
- **`manage_domain`** — Point a custom external domain (e.g., `app.mysite.com`) to an application. Always remind the user to create a CNAME at their DNS provider pointing to the server's primary domain.
|
|
102
|
+
- **`get_app_env`** — Fetches the detailed environment variables (ENVs) for a specific application. Essential when an AI needs to retrieve credentials (like an API Key, database password, or URL) natively configured in the application environment (e.g., retrieving Evolution API credentials).
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
### Catalog & Integrations
|
|
106
|
+
- **`install_catalog_app`** — Install a complete application from the catalog without building source code (e.g., installing a WhatsApp API or database).
|
|
107
|
+
- **`get_catalog_app_documentation`** — **MANDATORY** after installing a catalog app (or when integrating an existing one). Fetches connection data, API structure, and context needed to write integration code correctly. If this fails, fall back to Context7 or web search.
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## Core Best Practices and Workflows
|
|
112
|
+
|
|
113
|
+
### 1. The "Memory" File (`ilumin.md`)
|
|
114
|
+
|
|
115
|
+
Always act as the primary state manager for the project's deployment.
|
|
116
|
+
|
|
117
|
+
- **Always maintain a file named `ilumin.md` in the user's project root.**
|
|
118
|
+
- **Record**: Every successful installation, specific timestamp image tags used, the server domain (e.g., `srv1.user.ilumin.app`), custom domains configured, environment variables set, and any architectural notes.
|
|
119
|
+
- **Before any action**: Check `ilumin.md` first to determine whether to call `install_app` (first time) or `update_app` (subsequent deployments) — this prevents destructive duplicate installations.
|
|
120
|
+
|
|
121
|
+
### 2. Proactive Application Integrations Workflow
|
|
122
|
+
|
|
123
|
+
When the user asks to build features requiring complex backend services (WhatsApp, queues, databases, automation), follow this pattern:
|
|
124
|
+
|
|
125
|
+
1. Run `list_catalog` to check if an off-the-shelf app fulfills the requirement.
|
|
126
|
+
2. Present the finding to the user and request permission to install it.
|
|
127
|
+
3. If approved, run `install_catalog_app` to deploy the integration.
|
|
128
|
+
4. Run `get_catalog_app_documentation` with the app's slug to learn the exact integration endpoints, credentials, and variables exposed.
|
|
129
|
+
5. Use that documentation to write the precise integration code inside the user's main project.
|
|
130
|
+
6. Record the installation details in `ilumin.md`.
|
|
131
|
+
|
|
132
|
+
### 3. New Application Deployment Workflow
|
|
133
|
+
|
|
134
|
+
1. Check `ilumin.md` and/or `list_servers` to confirm the app doesn't already exist.
|
|
135
|
+
2. Run `deploy_project` to build the Docker image and obtain the image tag.
|
|
136
|
+
3. Run `get_compose_guidelines` to learn the Traefik standards and network config.
|
|
137
|
+
4. Run `install_app` using the obtained image tag and the generated compose file.
|
|
138
|
+
5. Record the server, tag, app name, and URL in `ilumin.md`.
|
|
139
|
+
|
|
140
|
+
### 4. Sending Environment Variables (ENVs) to Apps
|
|
141
|
+
|
|
142
|
+
**A) Catalog Apps — only the 4 predefined variables**
|
|
143
|
+
|
|
144
|
+
Catalog apps have their `docker-compose.yml` pre-built by the platform. The only ENVs you can pass are the 4 standard platform variables — and only the ones the app actually requires (as listed by `list_catalog`):
|
|
145
|
+
|
|
146
|
+
- `APP_USER` — username/login
|
|
147
|
+
- `APP_PASSWORD` — password
|
|
148
|
+
- `APP_EMAIL` — admin email
|
|
149
|
+
- `APP_API_KEY` — api key or token
|
|
150
|
+
|
|
151
|
+
Pass them via `envVars` in `install_catalog_app`. You **cannot** send arbitrary custom ENV names — they will be ignored. Always ask the user to provide the values; never invent them.
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
install_catalog_app(
|
|
155
|
+
serverDomain: "srv1.user.com",
|
|
156
|
+
slug: "waha",
|
|
157
|
+
envVars: {
|
|
158
|
+
"APP_USER": "admin",
|
|
159
|
+
"APP_PASSWORD": "strongpassword"
|
|
160
|
+
}
|
|
161
|
+
)
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
**B) Custom Apps — any ENVs via the compose `environment` block**
|
|
165
|
+
|
|
166
|
+
When using `install_app` with a custom `docker-compose.yml`, you can freely define any environment variables needed by the application in the `environment` section:
|
|
167
|
+
|
|
168
|
+
```yaml
|
|
169
|
+
services:
|
|
170
|
+
my-app:
|
|
171
|
+
image: ghcr.io/user/my-app:20260407130809
|
|
172
|
+
environment:
|
|
173
|
+
DATABASE_URL: "postgresql://user:pass@postgres:5432/mydb"
|
|
174
|
+
SECRET_KEY: "my-secret"
|
|
175
|
+
DEBUG: "false"
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Always ask the user for sensitive values before writing them into the compose. Never hardcode guessed values.
|
|
179
|
+
|
|
180
|
+
**C) Reading ENVs from an Existing App — via `get_app_env`**
|
|
181
|
+
|
|
182
|
+
If the AI needs credentials from an already-installed app (e.g., the Evolution API key or a database password), use `get_app_env` to fetch the live ENV values directly. This avoids asking the user for information they may not remember.
|
|
183
|
+
|
|
184
|
+
### 4. Updating an Existing Application
|
|
185
|
+
|
|
186
|
+
1. Verify it exists via `list_servers` or `ilumin.md`.
|
|
187
|
+
2. Run `deploy_project` to commit changes and obtain the new timestamp version tag (e.g., `20260407130809`).
|
|
188
|
+
3. Run `update_app` supplying the `app_name` and the new specific version tag. **Never use `latest`.**
|
|
189
|
+
4. Update `ilumin.md` with the new tag and date.
|
|
190
|
+
|
|
191
|
+
### 5. Custom Domain Configuration
|
|
192
|
+
|
|
193
|
+
When using `manage_domain`, always:
|
|
194
|
+
- Explicitly inform the user to create a **CNAME record** at their DNS provider pointing their custom domain to the server's primary domain (e.g., `srv1.user.ilumin.app`).
|
|
195
|
+
- Check `ilumin.md` to verify if a custom domain is already established, preventing accidental overwrites without user confirmation.
|
|
196
|
+
- Note that DNS propagation can take up to 24–48 hours, though it's typically much faster.
|
|
197
|
+
|
|
198
|
+
---
|
|
199
|
+
|
|
200
|
+
## Common Errors and Troubleshooting
|
|
201
|
+
|
|
202
|
+
| Symptom | Likely Cause | Resolution |
|
|
203
|
+
|---|---|---|
|
|
204
|
+
| App unreachable after install | Missing or incorrect Traefik labels | Re-run `get_compose_guidelines`, regenerate compose file |
|
|
205
|
+
| Docker pulls old image after update | Used `latest` tag instead of specific tag | Always use timestamp tags from `deploy_project` output |
|
|
206
|
+
| Container exits immediately | Missing required env var or misconfigured port | Review compose file; check logs via server SSH or Ilumin dashboard |
|
|
207
|
+
| Custom domain returns 404 | CNAME not yet propagated or `manage_domain` not called | Verify DNS, re-run `manage_domain` if needed |
|
|
208
|
+
| `install_app` fails with "already exists" | App installed previously | Use `update_app` instead |
|
|
209
|
+
| Catalog app missing credentials | Env vars not passed during `install_catalog_app` | Check `list_catalog` for required `env_vars`, provide them |
|
|
210
|
+
| Inter-container connection refused | Containers on different networks | Ensure all services share `ilumin-network` as an external network |
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## Additional Resources
|
|
215
|
+
|
|
216
|
+
- For Docker Compose formatting rules, Traefik labels, network configuration, and reference examples, see [references/compose.md](references/compose.md)
|
|
217
|
+
- For the recommended default stack (NocoDB, Redis, BullMQ) when the user hasn't specified infrastructure, see [references/recommended-stack.md](references/recommended-stack.md)
|