nuxt-spec 0.3.4 → 0.4.0-alpha.2

package/LICENSE

@@ -1,21 +1,21 @@
-# MIT License
-
-Copyright (c) 2025-present Alois Sečkár
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+# MIT License
+
+Copyright (c) 2025-present Alois Sečkár
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,13 +1,13 @@
-# Nuxt Spec
-
-![Nuxt Spec](https://github.com/AloisSeckar/nuxt-spec/blob/main/public/nuxt-spec.png)
-
-A _"testing done right"_ Nuxt base layer.
-
-## How to use
-
-See [ONLINE DOCS](https://nuxt-spec.netlify.app) for all the necessary information.
-
-See [CHANGELOG](https://nuxt-spec.netlify.app/3-1-changelog.html) for the full list of changes.
-
-See [CONTRIBUTING](https://nuxt-spec.netlify.app/4-1-contributing.html) if you want to help.
+# Nuxt Spec
+
+![Nuxt Spec](https://github.com/AloisSeckar/nuxt-spec/blob/main/public/nuxt-spec.png)
+
+A _"testing done right"_ Nuxt base layer.
+
+## How to use
+
+See [ONLINE DOCS](https://nuxt-spec.netlify.app) for all the necessary information.
+
+See [CHANGELOG](https://nuxt-spec.netlify.app/3-1-changelog.html) for the full list of changes.
+
+See [CONTRIBUTING](https://nuxt-spec.netlify.app/4-1-contributing.html) if you want to help.

package/app/app.vue

@@ -1,10 +1,10 @@
-<template>
-  <div>
-    <NuxtWelcome />
-    <div>
-      Test-pack layer for <a href="https://nuxt.com/">Nuxt</a> applications
-    </div>
-    <NuxtSpecTestComponent id="test" text="Test Component" />
-    <NuxtSpecApiTestComponent />
-  </div>
-</template>
+<template>
+  <div>
+    <NuxtWelcome />
+    <div>
+      Test-pack layer for <a href="https://nuxt.com/">Nuxt</a> applications
+    </div>
+    <NuxtSpecTestComponent id="test" text="Test Component" />
+    <NuxtSpecApiTestComponent />
+  </div>
+</template>

package/app/components/NuxtSpecApiTestComponent.vue

@@ -1,24 +1,24 @@
-<template>
-  <div>
-    <h2>API Test</h2>
-    <button id="api-fetch" @click="fetchData">
-      Fetch Data
-    </button>
-    <div id="api-result">
-      {{ data }}
-    </div>
-  </div>
-</template>
-
-<script setup lang="ts">
-const data = ref('')
-const fetchData = async () => {
-  try {
-    data.value = await $fetch('https://jsonplaceholder.typicode.com/posts/1')
-    console.debug('Fetched data:', data.value)
-  } catch (error) {
-    data.value = 'Error fetching data'
-    console.error('API fetch error:', error)
-  }
-}
-</script>
+<template>
+  <div>
+    <h2>API Test</h2>
+    <button id="api-fetch" @click="fetchData">
+      Fetch Data
+    </button>
+    <div id="api-result">
+      {{ data }}
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+const data = ref('')
+const fetchData = async () => {
+  try {
+    data.value = await $fetch('https://jsonplaceholder.typicode.com/posts/1')
+    console.debug('Fetched data:', data.value)
+  } catch (error) {
+    data.value = 'Error fetching data'
+    console.error('API fetch error:', error)
+  }
+}
+</script>

package/app/components/NuxtSpecTestComponent.vue

@@ -1,9 +1,9 @@
-<template>
-  <div data-testid="test-component" style="margin: 1rem 0; padding: 0.5rem; border: 1px solid black;">
-    {{ text }}
-  </div>
-</template>
-
-<script setup lang="ts">
-defineProps({ text: { type: String, default: 'nuxt-spec' } })
-</script>
+<template>
+  <div data-testid="test-component" style="margin: 1rem 0; padding: 0.5rem; border: 1px solid black;">
+    {{ text }}
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps({ text: { type: String, default: 'nuxt-spec' } })
+</script>

package/app/components/index.d.ts

@@ -1,7 +1,7 @@
-// type hint for tsconfig.nuxt-spec.json
-declare module '*.vue' {
-  import type { DefineComponent } from 'vue'
-
-  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
-  export default component
-}
+// type hint for tsconfig.nuxt-spec.json
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+
+  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+  export default component
+}

package/app/components/index.ts

@@ -1,2 +1,2 @@
-export { default as NuxtSpecTestComponent } from './NuxtSpecTestComponent.vue'
-export { default as NuxtSpecApiTestComponent } from './NuxtSpecApiTestComponent.vue'
+export { default as NuxtSpecTestComponent } from './NuxtSpecTestComponent.vue'
+export { default as NuxtSpecApiTestComponent } from './NuxtSpecApiTestComponent.vue'

package/app/utils/vitest-utils.ts

@@ -1,5 +1,5 @@
-// Element.checkVisibility() is not available in Vitest
-global.Element.prototype.checkVisibility = function () {
-  // in tests we always just assume the element is visible
-  return true
-}
+// Element.checkVisibility() is not available in Vitest
+global.Element.prototype.checkVisibility = function () {
+  // in tests we always just assume the element is visible
+  return true
+}

package/bin/_internal/prepublish-check.js

@@ -1,16 +1,16 @@
-#!/usr/bin/env node
-
-import { createInterface } from 'node:readline'
-
-const rl = createInterface({ input: process.stdin, output: process.stdout })
-
-rl.question('Are you sure the current solution was properly tested and verified? (y/n) ', (answer) => {
-  rl.close()
-  if (answer.trim().toLowerCase().startsWith('y')) {
-    console.log('Proceeding with publish...')
-    process.exit(0)
-  } else {
-    console.error('Publish aborted. Please run the tests and try again.')
-    process.exit(1)
-  }
-})
+#!/usr/bin/env node
+
+import { createInterface } from 'node:readline'
+
+const rl = createInterface({ input: process.stdin, output: process.stdout })
+
+rl.question('Are you sure the current solution was properly tested and verified? (y/n) ', (answer) => {
+  rl.close()
+  if (answer.trim().toLowerCase().startsWith('y')) {
+    console.log('Proceeding with publish...')
+    process.exit(0)
+  } else {
+    console.error('Publish aborted. Please run the tests and try again.')
+    process.exit(1)
+  }
+})

package/bin/cli.js

@@ -1,44 +1,53 @@
-#!/usr/bin/env node
-
-import { getCmd, resolvePackageManager } from './helpers/commands.js'
-
-/**
- * CLI tool to scaffold necessary adjustments in project folder.
- *
- * Allows `setup` or `update` to be passed as parameter.
- *
- * Second (optional) parameter might be a boolean to indicate auto mode
- * (no prompts, force = true) or manual mode (with prompts, force = false).
- *
- * Third (optional) parameter allows explicitly passing the package manager
- * (`npm`, `pnpm`, `yarn`, `bun` or `deno`), bypassing auto-detection.
- */
-
-// get parameters passed by user
-const args = process.argv.slice(2);
-
-// execute actions based on first param
-// additional params might be passed into the called functions
-(async () => {
-  let status = 0
-  try {
-    const packageManager = resolvePackageManager(args[2])
-    // CLI args are always strings, so 'false' must be parsed explicitly rather than treated as truthy
-    const autoRun = args[1] === 'true'
-    switch (args[0]) {
-      case 'setup':
-        await (await import('./setup.js')).specSetup(autoRun, packageManager)
-        break
-      case 'update':
-        await (await import('./update.js')).specUpdate(autoRun, packageManager)
-        break
-      default:
-        console.log(`Usage: \`${getCmd(packageManager)} setup [true|false] [npm|pnpm|yarn|bun|deno]\` or \`${getCmd(packageManager)} update [true|false] [npm|pnpm|yarn|bun|deno]\``)
-        status = 1
-    }
-  } catch (error) {
-    console.error('nuxt-spec CLI failed:', error.message)
-    status = 1
-  }
-  process.exit(status)
-})()
+#!/usr/bin/env node
+
+import { getCmd, resolvePackageManager } from './helpers/commands.js'
+
+/**
+ * CLI tool to scaffold necessary adjustments in project folder.
+ *
+ * Allows `setup`, `update` or `ci` to be passed as parameter.
+ *
+ * `ci` requires the target Git host (`github` or `gitlab`) as the next parameter,
+ * the remaining optional parameters are shifted by one position (package manager is not used yet).
+ *
+ * Next (optional) parameter might be a boolean to indicate auto mode
+ * (no prompts, force = true) or manual mode (with prompts, force = false).
+ *
+ * Next (optional) parameter allows explicitly passing the package manager
+ * (`npm`, `pnpm`, `yarn`, `bun` or `deno`), bypassing auto-detection.
+ */
+
+// get parameters passed by user
+const args = process.argv.slice(2);
+
+// execute actions based on first param
+// additional params might be passed into the called functions
+(async () => {
+  let status = 0
+  try {
+    const command = args[0]
+    const host = command === 'ci' ? args[1] : undefined
+    const [autoRunArg, packageManagerArg] = args.slice(command === 'ci' ? 2 : 1)
+    const packageManager = resolvePackageManager(packageManagerArg)
+    // CLI args are always strings, so 'false' must be parsed explicitly rather than treated as truthy
+    const autoRun = autoRunArg === 'true'
+    switch (command) {
+      case 'setup':
+        await (await import('./commands/setup.js')).specSetup(autoRun, packageManager)
+        break
+      case 'update':
+        await (await import('./commands/update.js')).specUpdate(autoRun, packageManager)
+        break
+      case 'ci':
+        await (await import('./commands/ci.js')).specCi(host, autoRun)
+        break
+      default:
+        console.log(`[Nuxt Spec] Usage: \`${getCmd(packageManager)} setup [true|false] [npm|pnpm|yarn|bun|deno]\`, \`${getCmd(packageManager)} update [true|false] [npm|pnpm|yarn|bun|deno]\` or \`${getCmd(packageManager)} ci <github|gitlab> [true|false]\``)
+        status = 1
+    }
+  } catch (error) {
+    console.error('[Nuxt Spec] CLI failed:', error.message)
+    status = 1
+  }
+  process.exit(status)
+})()

package/bin/commands/ci.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import {
+  createFileFromWebTemplate, pathExists, promptUser, showMessage, updateYamlFile,
+} from 'elrh-cosca'
+import { isGitRepo, resolveDefaultBranch } from '../helpers/git.js'
+import { COSCA_URL, PLAYWRIGHT_VERSION } from '../helpers/constants.js'
+
+const SUPPORTED_CI_HOSTS = ['github', 'gitlab']
+
+const GITLAB_ROOT_FILE = '.gitlab-ci.yml'
+
+export const CI_TEMPLATES = {
+  github: [
+    { template: '.github/workflows/ci-test-verify.yml.template', targetFile: '.github/workflows/ci-test-verify.yml' },
+    { template: '.github/workflows/ci-test-update.yml.template', targetFile: '.github/workflows/ci-test-update.yml' },
+  ],
+  gitlab: [
+    { template: '.gitlab/ci/ci-test-verify.yml.template', targetFile: '.gitlab/ci/ci-test-verify.yml' },
+    { template: '.gitlab/ci/ci-test-update.yml.template', targetFile: '.gitlab/ci/ci-test-update.yml' },
+  ],
+}
+
+function getDefaultBranch() {
+  if (!isGitRepo()) {
+    console.warn('[Nuxt Spec] Current folder is not a Git repository.')
+  }
+  const { branch, source } = resolveDefaultBranch()
+  // value is inserted into YAML unquoted
+  if (!/^[\w./+-]+$/.test(branch)) {
+    throw new Error(`Default branch name '${branch}' (resolved from ${source}) contains unsupported characters.`)
+  }
+  showMessage({ message: `[Nuxt Spec] Using '${branch}' as the default branch (resolved from ${source}).` })
+  return branch
+}
+
+/**
+ * CLI tool to scaffold CI test workflows for selected Git host.
+ *
+ * It first asks whether to run in "auto" mode (no prompts, force = true) or "manual" mode (with prompts, force = false).
+ *
+ * Then it:
+ *  1) creates CI workflow files for the selected host
+ *  2) fills in placeholders - Playwright version and default branch of the Git repository in the current folder (resolved only if used)
+ *  3) (GitLab only) adds CI files into `include` section of `.gitlab-ci.yml` (scaffolded from template if missing)
+ *
+ * @param {string} host - Target Git host (`github` or `gitlab`).
+ * @param {boolean} autoRun - Whether to run the scaffolding automatically without any prompts (defaults to false).
+ */
+export async function specCi(host, autoRun = false) {
+  showMessage({ message: 'NUXT SPEC CI' })
+  showMessage({ message: `This CLI tool will help you scaffold CI test workflows for '${host}'.` })
+  showMessage({ message: 'Refer to the documentation for more information.', linesAfter: 2 })
+
+  if (!SUPPORTED_CI_HOSTS.includes(host)) {
+    throw new Error(`${host ? `Unsupported CI host '${host}'` : 'Missing CI host'}. Use one of: ${SUPPORTED_CI_HOSTS.join(', ')}`)
+  }
+
+  const templates = CI_TEMPLATES[host]
+
+  const isAutoRun = autoRun || await promptUser({ question: '[Nuxt Spec] Do you want to scaffold everything automatically (no more prompts)?' })
+  showMessage({ message: '' })
+
+  let branch
+  const created = []
+  for (const { template, targetFile } of templates) {
+    // 1) create workflow files
+    const exists = pathExists({ targetPath: targetFile })
+    const proceed = isAutoRun || await promptUser({
+      question: exists
+        ? `[Nuxt Spec] File '${targetFile}' already exists. Overwrite?`
+        : `[Nuxt Spec] This will create '${targetFile}' file. Continue?`,
+    })
+    if (!proceed) {
+      if (!exists) {
+        throw new Error(`Creation of '${targetFile}' declined - CI setup cannot be completed without it.`)
+      }
+      console.log(`[Nuxt Spec] Existing '${targetFile}' kept.`)
+      continue
+    }
+    await createFileFromWebTemplate({ url: `${COSCA_URL}/config/templates/${template}`, targetFile, force: true })
+
+    // 2) fill in placeholders
+    let content = readFileSync(targetFile, 'utf8').replaceAll('__PLAYWRIGHT_VERSION__', PLAYWRIGHT_VERSION)
+    if (content.includes('__DEFAULT_BRANCH__')) {
+      branch ??= getDefaultBranch()
+      content = content.replaceAll('__DEFAULT_BRANCH__', branch)
+    }
+    writeFileSync(targetFile, content)
+    created.push(targetFile)
+  }
+
+  // 3) (GitLab only) register CI files in root pipeline
+  if (host === 'gitlab') {
+    if (pathExists({ targetPath: GITLAB_ROOT_FILE })) {
+      await updateYamlFile({
+        targetFile: GITLAB_ROOT_FILE,
+        yamlKey: 'include',
+        patch: templates.map(({ targetFile }) => ({ local: targetFile })),
+        force: isAutoRun,
+        prompt: `[Nuxt Spec] This will add CI files into 'include' section of your '${GITLAB_ROOT_FILE}'. Continue?`,
+      })
+    } else {
+      await createFileFromWebTemplate({
+        url: `${COSCA_URL}/config/templates/${GITLAB_ROOT_FILE}.template`,
+        targetFile: GITLAB_ROOT_FILE,
+        force: isAutoRun,
+        prompt: `[Nuxt Spec] This will create '${GITLAB_ROOT_FILE}' file including the CI files. Continue?`,
+      })
+    }
+  }
+
+  // 4) inform user
+  showMessage({ message: '' })
+  showMessage({ message: 'NUXT SPEC CI COMPLETE', linesAfter: 2 })
+  if (created.length > 0) {
+    showMessage({ message: 'Review the created files and complete the prerequisites described in their headers.' })
+  }
+  if (branch) {
+    showMessage({ message: `Verify '${branch}' is the correct default branch.` })
+    showMessage({ message: `If not, run \`git remote set-head origin --auto\` and re-run this command, or adjust the files manually.` })
+  }
+}