1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
# This code is licensed from CircleCI to the user under the MIT license.
# See here for details: https://circleci.com/developer/orbs/licensing
version: 2.1
description: |
    Core commands for Node.js projects, install dependencies with caching by default and run scripts, using npm or pnpm package manager. Tailored for use within Studion pipelines.
display:
    home_url: https://circleci.com/developer/orbs/orb/studion/core
    source_url: https://github.com/ExtensionEngine/pipeline-core-orb
commands:
    ensure_pkg_manager:
        description: |
            Ensure required package manager is in place, optionally specifing the exact version. Requires execution environment with Node.js >= 18.20 pre-installed.
        parameters:
            ref:
                default: ${DEFAULT_PKG_MANAGER}
                description: |
                    Choose Node.js package manager to use. Supports npm and pnpm.
                    The package manager must follow the format <name>[@<version|tag>].
                    Omitting the version implies
                    (for npm) use the version that comes with the target Node.js environment,
                    (for pnpm) use the existing version if found, otherwise use the latest version.
                type: string
        steps:
            - run:
                command: |
                    #!/bin/bash

                    NODE_VERSION_REGEX="v([0-9]+).([0-9]+).([0-9]+)"
                    NODE_VERSION=$(node -v)
                    MAJOR=""
                    MINOR=""

                    if [[ "${NODE_VERSION}" =~ ${NODE_VERSION_REGEX} ]]; then
                      MAJOR="${BASH_REMATCH[1]}"
                      MINOR="${BASH_REMATCH[2]}"

                      if [[ "${MAJOR}" -lt 18 || ("${MAJOR}" -eq 18 && "${MINOR}" -lt 20) ]]; then
                        echo "At least Node.js v18.20 is required!"

                        exit 1
                      fi
                    fi
                name: Check Node.js version
            - run:
                command: |
                    #!/bin/bash

                    PARAM_STR_REF=$(circleci env subst "${PARAM_STR_REF}")
                    PKG_MANAGER_REGEX="^(npm|pnpm)(@(([0-9]+.?){0,2}[0-9]+|[a-z]+-?([0-9]+)?))?$"
                    NAME=""
                    VERSION=""

                    if [[ "${PARAM_STR_REF}" =~ ${PKG_MANAGER_REGEX} ]]; then
                      NAME="${BASH_REMATCH[1]}"
                      VERSION="${BASH_REMATCH[3]}"
                    fi

                    if [[ -z "${NAME}" ]]; then
                      echo "Package manager '${NAME}' is not supported"
                      echo "Please specify supported package manager through parameter or environment"

                      exit 1
                    fi

                    echo "export CURRENT_PKG_MANAGER='${NAME}'" >>"${BASH_ENV}"
                    echo "export CURRENT_PKG_MANAGER_VERSION='${VERSION}'" >>"${BASH_ENV}"
                environment:
                    PARAM_STR_REF: <<parameters.ref>>
                name: Export package manager
            - run:
                command: |
                    #!/bin/bash

                    NAME="${CURRENT_PKG_MANAGER}"
                    VERSION="${CURRENT_PKG_MANAGER_VERSION}"
                    SUDO=""
                    NPM_SUDO=""

                    if [[ ${EUID} -ne 0 ]]; then
                      echo "Using sudo privileges, excluding npm commands, to finish the process"

                      SUDO="sudo"

                      if [[ ! -w "$(npm root -g)" ]]; then
                        echo "Missing write permission for global node_modules directory"
                        echo "Using sudo privileges for npm commands as well"

                        NPM_SUDO="sudo"
                      fi
                    fi

                    check_installation() {
                      local installed_version
                      local required_version
                      local tag_regex
                      local tag_mapping

                      installed_version=$(eval "$1" --version)
                      required_version="$2"
                      tag_regex=$(eval echo "$2":)
                      tag_mapping=$(eval npm dist-tag ls "$1" | grep "${tag_regex}" || true)

                      if [[ -n "${tag_mapping}" ]]; then
                        required_version=$(echo "${tag_mapping}" | awk '{print $2}')
                      fi

                      echo "Installed $1 version: ${installed_version}"
                      echo "Required $1 version: ${required_version}"

                      if [[ "${installed_version}" != "${required_version}" ]]; then
                        echo "Failed to install $1 '${required_version}'"

                        exit 2
                      fi
                    }

                    change_pnpm_store_dir_and_exit() {
                      local current_store_dir
                      local target_store_dir

                      current_store_dir=$(pnpm store path)
                      target_store_dir="${HOME}/.pnpm_store"

                      if [[ "${current_store_dir}" != "${target_store_dir}" ]]; then
                        echo "Changing the pnpm store directory"

                        set -x
                        pnpm config set store-dir "${target_store_dir}"
                        ${SUDO} rm -rf "${current_store_dir}"
                        set +x
                      fi

                      exit 0
                    }

                    echo "Starting to ensure '${NAME}' is set for usage"

                    cd ~ || echo "Cannot navigate to home, possible version mismatch"

                    if [[ "${NAME}" == "npm" ]]; then
                      echo "Detected npm $(npm --version)"

                      if [[ -n "${VERSION}" ]]; then
                        if npm --version | grep "${VERSION}" >/dev/null 2>&1; then
                          echo "Requested version of npm is already installed"
                        else
                          echo "Requested version of npm not found, updating detected version"

                          ${NPM_SUDO} npm i -g npm@"${VERSION}"
                          check_installation "${NAME}" "${VERSION}"
                        fi

                        exit 0
                      fi

                      echo "Using detected version of npm"

                      exit 0
                    fi

                    if [[ "${NAME}" == "pnpm" ]]; then
                      if command -v pnpm >/dev/null 2>&1; then
                        echo "Detected pnpm $(pnpm --version)"

                        if [[ -z "${VERSION}" ]]; then
                          echo "Using detected version of pnpm"

                          change_pnpm_store_dir_and_exit
                        elif pnpm --version | grep "${VERSION}" >/dev/null 2>&1; then
                          echo "Requested vesion of pnpm is already installed"

                          change_pnpm_store_dir_and_exit
                        fi

                        echo "Requested version of pnpm not found, removing detected version"

                        ${SUDO} rm -rf "$(pnpm store path)" >/dev/null 2>&1
                        ${SUDO} rm -rf "${PNPM_HOME}" >/dev/null 2>&1
                        ${NPM_SUDO} npm rm -g pnpm >/dev/null 2>&1
                      else
                        echo "Did not detect pnpm, proceeding with installation"
                      fi

                      if [[ -z "${VERSION}" ]]; then
                        VERSION=$(npm view pnpm version)

                        echo "Version not explicitly requested, opting for ${VERSION}"
                      fi

                      ${NPM_SUDO} npm i -g pnpm@"${VERSION}"
                      check_installation "${NAME}" "${VERSION}"

                      echo "Setting ~/.pnpm-store as the store directory"

                      pnpm config set store-dir ~/.pnpm-store

                      exit 0
                    fi

                    echo "Failed to ensure package manager"
                    echo "Please specify supported package manager through parameter or environment"

                    exit 1
                name: Ensure package manager
    install_dependencies:
        description: |
            Install dependencies with caching, optionally choose a package manager. Requires execution environment with Node.js >= 18.20 pre-installed.
        parameters:
            cache_version:
                default: v1
                description: Change the default cache version if the cache needs to be cleared for some reason.
                type: string
            install_command:
                default: ""
                description: |
                    Custom command to install dependencies. Useful when default commands, "npm ci" or "pnpm i --frozen-lockfile", are unsuitable.
                type: string
            pkg_json_dir:
                default: .
                description: |
                    Path to the directory containing package.json file. Not needed when package.json is in the root.
                type: string
            pkg_manager:
                default: ${DEFAULT_PKG_MANAGER}
                description: |
                    Choose Node.js package manager to use. Supports npm and pnpm.
                    The package manager must follow the format <name>[@<version|tag>].
                    Omitting the version implies that the npm version is determined by the target Node.js environment,
                    while pnpm will default to the latest version.
                type: string
        steps:
            - ensure_pkg_manager:
                ref: <<parameters.pkg_manager>>
            - run:
                command: |
                    #!/bin/bash

                    if [ ! -f "package.json" ]; then
                      echo "File package.json not found inside working directory: ${PWD}"
                      echo "Content of working directory:"

                      ls -al

                      exit 1
                    fi
                name: Check for package.json
                working_directory: <<parameters.pkg_json_dir>>
            - run:
                command: |
                    #!/bin/bash

                    DEST_FILE="/tmp/node-lockfile"

                    if [ -f "package-lock.json" ] && [[ "${CURRENT_PKG_MANAGER}" == "npm" ]]; then
                      echo "Found package-lock.json, assuming lockfile"

                      cp package-lock.json "${DEST_FILE}"

                      exit 0
                    elif [ -f "pnpm-lock.yaml" ] && [[ "${CURRENT_PKG_MANAGER}" == "pnpm" ]]; then
                      echo "Found pnpm-lock.ymal, assuming lockfile"

                      cp pnpm-lock.yaml "${DEST_FILE}"

                      exit 0
                    fi

                    echo "The lockfile not found!"
                    echo "Current package manager: ${CURRENT_PKG_MANAGER}"

                    exit 1
                name: Process lockfile
                working_directory: <<parameters.pkg_json_dir>>
            - restore_cache:
                keys:
                    - node-{{ arch }}-<<parameters.cache_version>>-{{ .Branch }}-{{ checksum "/tmp/node-lockfile" }}
                    - node-{{ arch }}-<<parameters.cache_version>>-{{ .Branch }}-
                    - node-{{ arch }}-<<parameters.cache_version>>-
            - run:
                command: |
                    #!/bin/bash

                    if [[ -n "${PARAM_STR_INSTALL_COMMAND}" ]]; then
                      echo "Running custom install command"

                      set -x
                      eval "${PARAM_STR_INSTALL_COMMAND}"
                      set +x
                    elif [[ "${CURRENT_PKG_MANAGER}" == "npm" ]]; then
                      echo "Running npm clean install"

                      npm ci
                    elif [[ "${CURRENT_PKG_MANAGER}" == "pnpm" ]]; then
                      echo "Running pnpm install with frozen lockfile"

                      pnpm i --frozen-lockfile
                    fi
                environment:
                    PARAM_STR_INSTALL_COMMAND: <<parameters.install_command>>
                name: Install dependencies
                working_directory: <<parameters.pkg_json_dir>>
            - when:
                condition:
                    matches:
                        pattern: ^npm(.{0,})?$
                        value: <<parameters.pkg_manager>>
                steps:
                    - save_cache:
                        key: node-{{ arch }}-<<parameters.cache_version>>-{{ .Branch }}-{{ checksum "/tmp/node-lockfile" }}
                        paths:
                            - ~/.npm
            - when:
                condition:
                    matches:
                        pattern: ^pnpm(.{0,})?$
                        value: <<parameters.pkg_manager>>
                steps:
                    - save_cache:
                        key: node-{{ arch }}-<<parameters.cache_version>>-{{ .Branch }}-{{ checksum "/tmp/node-lockfile" }}
                        paths:
                            - ~/.pnpm-store
            - run:
                command: rm -f /tmp/node-lockfile
                name: Remove temporary lockfile
    run_script:
        description: |
            Simple command that enables running scripts defined within package.json. Requires execution environment with Node.js >= 18.20 pre-installed.
        parameters:
            cache_version:
                default: v1
                description: Change the default cache version if the cache needs to be cleared for some reason.
                type: string
            install_command:
                default: ""
                description: |
                    Custom command to install dependencies. Useful when default commands, "npm ci" or "pnpm i --frozen-lockfile", are unsuitable.
                type: string
            no_output_timeout:
                default: 10m
                description: |
                    Elapsed time the command can run without output. The string is a decimal with unit suffix, such as "20m", "1.25h", "5s".
                type: string
            pkg_json_dir:
                default: .
                description: |
                    Path to the directory containing package.json file. Not needed when package.json is in the root.
                type: string
            pkg_manager:
                default: ${DEFAULT_PKG_MANAGER}
                description: |
                    Choose Node.js package manager to use. Supports npm and pnpm.
                    The package manager must follow the format <name>[@<version|tag>].
                    Omitting the version implies that the npm version is determined by the target Node.js environment,
                    while pnpm will default to the latest version.
                type: string
            script:
                default: ""
                description: |
                    Name of the script to execute. Passed as is to the run command of choosen pacakge manager, meaning it can contain arguments as well.
                type: string
            skip_install_dependencies:
                default: false
                description: |
                    The flag indicating whether to skip installing dependencies.
                    Useful in a case of multiple `run_script` commands inside a single job.
                type: boolean
        steps:
            - unless:
                condition: <<parameters.skip_install_dependencies>>
                steps:
                    - install_dependencies:
                        cache_version: <<parameters.cache_version>>
                        install_command: <<parameters.install_command>>
                        pkg_json_dir: <<parameters.pkg_json_dir>>
                        pkg_manager: <<parameters.pkg_manager>>
            - run:
                command: |
                    #!/bin/bash

                    echo "Running custom script from package.json at ${PWD}"

                    PKG_MANAGER=$(circleci env subst "${PARAM_STR_PKG_MANAGER}")
                    PKG_MANAGER_REGEX="^(npm|pnpm)(@.+)?$"

                    if [[ "${PKG_MANAGER}" =~ ${PKG_MANAGER_REGEX} ]]; then
                      PKG_MANAGER="${BASH_REMATCH[1]}"
                    else
                      echo "Cannot run script with unsupported package manager '${PKG_MANAGER}'"

                      exit 1
                    fi

                    set -x
                    eval "${PKG_MANAGER}" run "${PARAM_STR_SCRIPT}"
                    set +x
                environment:
                    PARAM_STR_PKG_MANAGER: <<parameters.pkg_manager>>
                    PARAM_STR_SCRIPT: <<parameters.script>>
                name: Run "<<parameters.script>>" with "<<parameters.pkg_manager>>"
                no_output_timeout: <<parameters.no_output_timeout>>
                working_directory: <<parameters.pkg_json_dir>>
executors:
    node:
        description: |
            Docker executor using CI-optimized Node.js image built to run on CircleCI.
        docker:
            - image: cimg/node:<<parameters.tag>>
        parameters:
            resource_class:
                default: medium
                description: Choose the executor resource class
                enum:
                    - small
                    - medium
                    - medium+
                    - large
                    - xlarge
                    - 2xlarge
                    - 2xlarge+
                type: enum
            tag:
                default: lts
                description: |
                    Choose a specific cimg/node image tag: https://hub.docker.com/r/cimg/node/tags
                type: string
        resource_class: <<parameters.resource_class>>
    node_secrets:
        description: |
            Docker executor integrating Infisical Open Source Secret Management for secure secret retrieval within CircleCI Node.js pipelines.
        docker:
            - image: studiondev/node-secrets:<<parameters.tag>>
        parameters:
            resource_class:
                default: medium
                description: Choose the executor resource class
                enum:
                    - small
                    - medium
                    - medium+
                    - large
                    - xlarge
                    - 2xlarge
                    - 2xlarge+
                type: enum
            tag:
                default: lts
                description: |
                    Choose a specific studiondev/node-secrets image tag: https://hub.docker.com/r/studiondev/node-secrets/tags
                type: string
        resource_class: <<parameters.resource_class>>
    ubuntu:
        description: |
            Docker executor using CI-optimized Ubuntu image built to run on CircleCI.
        docker:
            - image: cimg/base:<<parameters.tag>>
        parameters:
            resource_class:
                default: medium
                description: Choose the executor resource class
                enum:
                    - small
                    - medium
                    - medium+
                    - large
                    - xlarge
                    - 2xlarge
                    - 2xlarge+
                type: enum
            tag:
                default: current
                description: |
                    Choose a specific cimg/base image tag: https://hub.docker.com/r/cimg/base/tags
                type: string
        resource_class: <<parameters.resource_class>>
examples:
    npm_run:
        description: |
            Run any script defined inside a "package.json" using the targeted package manager.
            Before running the specified script, the command will fetch the code and install dependencies.
        usage:
            version: "2.1"
            orbs:
                core: studion/core@x.y.z
            jobs:
                test:
                    executor: core/node
                    steps:
                        - checkout
                        - core/run_script:
                            pkg_manager: npm
                            script: test
            workflows:
                test_app:
                    jobs:
                        - test
    pnpm_ensure:
        description: |
            Ensure the desired package manager, including the version, is installed on the system.
            If desired, the package manager can be set through the DEFAULT_PKG_MANAGER environment variable.
            The npm is used to update itself and to install pnpm when required.
        usage:
            version: "2.1"
            orbs:
                core: studion/core@x.y.z
            jobs:
                audit:
                    executor: core/node
                    steps:
                        - core/ensure_pkg_manager:
                            ref: pnpm@9.0.1
                        - run: pnpm audit --prod
            workflows:
                audit_deps:
                    jobs:
                        - audit
    pnpm_install:
        description: |
            By default, the "install_dependencies" command respects automated environments
            and installs dependencies consistently and predictably.
            There is an option to override the install command, package manager, and root directory.
        usage:
            version: "2.1"
            orbs:
                core: studion/core@x.y.z
            jobs:
                build:
                    executor:
                        name: core/node
                        resource_class: xlarge
                        tag: 20.11.0
                    steps:
                        - checkout
                        - core/install_dependencies:
                            cache_version: v3
                            install_command: pnpm i
                            pkg_json_dir: ~/workspace/project
                            pkg_manager: pnpm
                        - run: cd ~/workspace/project && pnpm run build
            workflows:
                build_app:
                    jobs:
                        - build