fg-devkit 1.14.4 → 1.15.0

package/.cursor/rules/core-coding-standards.mdc

@@ -11,6 +11,13 @@ alwaysApply: true
 - Avoid unrelated refactors in the same task.
 - Preserve existing behavior unless a behavior change is requested.
 
+## Code comments
+
+- Do not add comments in code unless the user explicitly asks for them.
+- Prefer self-explanatory naming and structure over inline comments.
+- When updating existing code, do not add new comments or expand existing ones unless requested.
+- Exception: update comments only when they are required to keep an existing comment accurate after a behavior change in the same task.
+
 ## Communication efficiency
 
 - Do not waste tokens: keep responses concise, high-signal, and scoped to the request.
@@ -33,7 +40,7 @@ alwaysApply: true
 - Keep TypeScript and Vue template typing strict (`strict: true`, `strictTemplates: true`).
 - Do not introduce `any`; use `unknown` for unsafe input and narrow before use.
 - Type API boundaries explicitly (request payloads, response DTOs, mutation variables, callback contracts).
-- Prefer named reusable types (for example under `src/types`) for shared domain shapes.
+- Prefer named reusable types under `src/types/<domain>/` for shared domain shapes; re-export from `src/types/index.ts`. Do not keep shared interfaces in views, stores, or query files.
 - Avoid non-null assertions unless guarded by `enabled` checks or equivalent runtime guarantees.
 
 ## API boundaries
@@ -44,9 +51,10 @@ alwaysApply: true
 
 ## State-management boundaries
 
-- Use TanStack Query (or the project’s chosen data library) for server state and caching.
-- Use Pinia/Vuex only for client/app state that is not owned by the server.
-- Do not duplicate the same state across the query cache and global stores unless the project explicitly documents that pattern.
+- Use TanStack Query for server state and caching. Do not add Vuex for new work.
+- Use Pinia only for client/app state that is not owned by the server (for example `src/pinia/*`).
+- Do not duplicate the same state across the query cache and Pinia unless the project explicitly documents that pattern.
+- When a project is migrating Vuex → Query/Pinia, follow that repo’s local migration rules (if present) instead of expanding Vuex.
 
 ## TanStack Query server-state conventions
 
@@ -85,6 +93,7 @@ alwaysApply: true
 ## FDS-first component usage
 
 - Use `fds-vue-core` components as the default choice for UI building blocks.
+- Multi-step wizards use `FdsWizard` from `fds-vue-core`. Follow the project’s wizard rule file when one exists (for example `.cursor/rules/fds-wizard.md`).
 - Before adding custom UI, check whether an FDS component already solves the use case.
 - Prefer extending composition around FDS components over re-implementing design-system behavior.
 - Keep visual consistency by matching FDS variants, spacing patterns, and interaction styles.
@@ -113,6 +122,7 @@ alwaysApply: true
 - Keep spacing and typography explicit in class names; avoid hidden styling in deep selectors.
 - Use `!` utility overrides sparingly and only when a component default cannot be changed safely.
 - For Tailwind v4 important modifiers, use postfix-important utility syntax (for example `grid-cols-1!`) instead of prefix syntax (for example `!grid-cols-1`).
+- Stack repeated items with parent `flex flex-col gap-*` (or `space-y-*`). Do not use `mb-* last:mb-0` or `last-of-type:mb-*` — those variants often miss the last `v-for` item (extra Vue/FDS nodes) and trip Tailwind conflict lint.
 
 ## Figma MCP implementation workflow
 
@@ -166,9 +176,11 @@ alwaysApply: true
 
 ## Testing expectations
 
-- For non-trivial logic changes, add or update automated tests close to the affected feature.
-- Validate critical flows for changed views: loading, empty, error, and success states.
+- Do not add new automated tests unless the user explicitly asks for them.
+- Update existing tests when your change requires it (for example broken assertions, renamed APIs, or changed behavior covered by current tests).
+- When new tests are requested, add them close to the affected feature.
 - Keep tests behavior-focused and avoid brittle implementation-detail assertions.
+- When no new tests are requested, rely on lint, typecheck, and manual verification of critical flows where practical.
 
 ## CI/CD
 
@@ -178,7 +190,8 @@ alwaysApply: true
 
 ## Quality checks before finishing
 
-- Run relevant checks for touched code (lint, typecheck, or tests when practical).
+- Run relevant checks for touched code (lint and typecheck when practical).
+- Run and update existing tests when your change affects them; add new tests only when the user explicitly requests them.
 - Fix issues introduced by your change before handing off.
 - Call out anything you could not verify.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fg-devkit",
-  "version": "1.14.4",
+  "version": "1.15.0",
   "description": "Shared configs, scripts, and DX tooling for Vue / TypeScript frontend repos",
   "type": "module",
   "license": "UNLICENSED",

package/scaffold/vue/package.json

@@ -33,7 +33,7 @@
     "@tanstack/vue-query-devtools": "6.1.38",
     "@types/node": "22.16.5",
     "@vitejs/plugin-vue": "6.0.8",
-    "fg-devkit": "1.14.4",
+    "fg-devkit": "1.15.0",
     "tailwindcss": "4.3.3",
     "tsx": "4.23.12",
     "vite": "7.3.5"

package/scripts/fg-devkit.mjs

@@ -559,7 +559,7 @@ Commands:
   fallow [fallow-args...]           Run Fallow using fg-devkit bundled package
   dead-code [fallow-args...]        Run Fallow dead code analysis (shortcut for: fallow dead-code)
   poeditor-download [args...]       Download locale files via PoEditor (reads poeditor/.poeditor.json by default)
-  poeditor-upload [args...]         Upload locale file via PoEditor (reads poeditor/.poeditor.json by default)
+  poeditor-upload [args...]         Upload locale file via PoEditor (reads poeditor/.poeditor.json by default; --sync-terms deletes missing terms)
   scaffold-vue <target-dir> [--name …] [--slug …] [--force] …
                                  Copy the bundled Vue scaffold into target-dir (see script header)
   sync-scaffold-vue-deps [policy-file]
@@ -589,11 +589,14 @@ function isFgDevkitMaintainerContext() {
 
 async function runInteractiveMenu() {
   let selectPrompt
+  let confirmPrompt
   try {
     const inquirerSelect = await import('@inquirer/select')
+    const inquirerConfirm = await import('@inquirer/confirm')
     selectPrompt = inquirerSelect.default
+    confirmPrompt = inquirerConfirm.default
   } catch {
-    console.error('[fg-devkit] Interactive menu requires @inquirer/select but it is not available.')
+    console.error('[fg-devkit] Interactive menu requires @inquirer/select and @inquirer/confirm but they are not available.')
     console.error('[fg-devkit] Run pnpm install in your project and try again.')
     return 1
   }
@@ -769,7 +772,34 @@ async function runInteractiveMenu() {
         loop: false,
       })
       if (choice === 'cancel') continue
-      return runSelectedAction(() => runNode(choice === 'download' ? 'poeditor-download.mjs' : 'poeditor-upload.mjs'))
+      if (choice === 'download') {
+        return runSelectedAction(() => runNode('poeditor-download.mjs'))
+      }
+
+      const uploadMode = await selectPrompt({
+        message: 'Upload mode',
+        choices: [
+          { name: 'Upload (keep terms missing from file)', value: 'upload' },
+          {
+            name: 'Upload + sync terms (delete terms missing from file)',
+            value: 'upload-sync',
+          },
+          { name: 'Cancel', value: 'cancel' },
+        ],
+        default: 'upload',
+        loop: false,
+      })
+      if (uploadMode === 'cancel') continue
+      if (uploadMode === 'upload-sync') {
+        const confirmed = await confirmPrompt({
+          message:
+            'This is a destructive POEditor action: terms not present in the uploaded file will be permanently deleted from the project (including all language translations). Continue?',
+          default: false,
+        })
+        if (!confirmed) continue
+      }
+      const uploadArgs = uploadMode === 'upload-sync' ? ['--sync-terms'] : []
+      return runSelectedAction(() => runNode('poeditor-upload.mjs', uploadArgs))
     }
 
     if (group === 'dependency-policy') {

package/scripts/poeditor-upload.mjs

@@ -4,7 +4,10 @@
  *
  * Usage:
  *   pnpm exec fg-devkit poeditor-upload [--config ./poeditor/.poeditor.json] [--project-id 123]
- *     [--language sv] [--file ./src/lang/sv.json] [--api-token xxx]
+ *     [--language sv] [--file ./src/lang/sv.json] [--api-token xxx] [--sync-terms]
+ *
+ * --sync-terms: Pass sync_terms=1 to PoEditor so terms missing from the uploaded file
+ *               are deleted from the project (destructive; use with care).
  */
 
 import fs from 'node:fs'
@@ -22,6 +25,12 @@ function sleep(ms) {
   })
 }
 
+function isTruthyFlag(value) {
+  if (value === undefined) return false
+  const normalized = String(value).trim().toLowerCase()
+  return normalized === 'true' || normalized === '1' || normalized === 'yes'
+}
+
 function parsePoeditorError(err) {
   const message = err instanceof Error ? err.message : String(err)
   const match = message.match(/Upload failed:\s*(\{.*\})$/)
@@ -46,7 +55,7 @@ function getUploadType(filePath) {
   return extension
 }
 
-async function uploadFile({ token, projectId, language, filePath }) {
+async function uploadFile({ token, projectId, language, filePath, syncTerms = false }) {
   const fileBuffer = fs.readFileSync(filePath)
   const fileName = path.basename(filePath)
   const uploadType = getUploadType(filePath)
@@ -56,6 +65,7 @@ async function uploadFile({ token, projectId, language, filePath }) {
   form.append('updating', 'terms_translations')
   form.append('language', language)
   form.append('overwrite', '1')
+  form.append('sync_terms', syncTerms ? '1' : '0')
   form.append('type', uploadType)
   form.append('file', new Blob([fileBuffer]), fileName)
 
@@ -70,18 +80,20 @@ async function uploadFile({ token, projectId, language, filePath }) {
   if (data?.response?.status !== 'success') {
     throw new Error(`Upload failed: ${JSON.stringify(data)}`)
   }
+  const terms = data?.result?.terms
   const translations = data?.result?.translations
+  const syncNote = syncTerms ? `, terms deleted: ${terms?.deleted ?? 0}` : ''
   console.log(
-    `[poeditor-upload] Upload complete for "${language}" (parsed: ${translations?.parsed ?? 0}, updated: ${translations?.updated ?? 0}, added: ${translations?.added ?? 0})`,
+    `[poeditor-upload] Upload complete for "${language}" (parsed: ${translations?.parsed ?? 0}, updated: ${translations?.updated ?? 0}, added: ${translations?.added ?? 0}${syncNote})`,
   )
 }
 
-async function uploadFileWithRetry({ token, projectId, language, filePath }) {
+async function uploadFileWithRetry({ token, projectId, language, filePath, syncTerms = false }) {
   let attempt = 0
   while (true) {
     attempt += 1
     try {
-      await uploadFile({ token, projectId, language, filePath })
+      await uploadFile({ token, projectId, language, filePath, syncTerms })
       return
     } catch (err) {
       const errorCode = parsePoeditorError(err)
@@ -111,20 +123,32 @@ async function main() {
   }
 
   const projectId = getFlagValue(flags, 'project-id', cfg.projectId)
+  const syncTerms = isTruthyFlag(getFlagValue(flags, 'sync-terms'))
+  if (syncTerms) {
+    console.warn(
+      '[poeditor-upload] --sync-terms enabled: terms not present in the uploaded file will be deleted from PoEditor.',
+    )
+  }
+
   const hasExplicitLanguage = flags.has('language')
   const hasExplicitFile = flags.has('file')
   if (hasExplicitLanguage || hasExplicitFile) {
     const language = getFlagValue(flags, 'language', cfg.defaultLanguage)
     const filePath = resolvePathFromCwd(getFlagValue(flags, 'file', cfg.uploadFile))
-    await uploadFile({ token, projectId, language, filePath })
+    await uploadFile({ token, projectId, language, filePath, syncTerms })
     console.log(`[poeditor-upload] Upload completed for ${language}: ${filePath}`)
     return
   }
 
   const uploads = cfg.uploadFiles && typeof cfg.uploadFiles === 'object' ? Object.entries(cfg.uploadFiles) : []
   if (uploads.length > 0) {
+    if (syncTerms && uploads.length > 1) {
+      console.warn(
+        '[poeditor-upload] --sync-terms with multiple uploadFiles: syncing only on the first file to avoid deleting terms present in other language files.',
+      )
+    }
     let nextUploadAt = 0
-    for (const [language, file] of uploads) {
+    for (const [index, [language, file]] of uploads.entries()) {
       const now = Date.now()
       const waitBeforeUploadMs = Math.max(0, nextUploadAt - now)
       if (waitBeforeUploadMs > 0) {
@@ -133,7 +157,8 @@ async function main() {
       }
 
       const filePath = resolvePathFromCwd(file)
-      await uploadFileWithRetry({ token, projectId, language, filePath })
+      const shouldSyncTerms = syncTerms && index === 0
+      await uploadFileWithRetry({ token, projectId, language, filePath, syncTerms: shouldSyncTerms })
       console.log(`[poeditor-upload] Upload completed for ${language}: ${filePath}`)
       nextUploadAt = Date.now() + MIN_UPLOAD_INTERVAL_MS
     }
@@ -142,7 +167,7 @@ async function main() {
 
   const language = cfg.defaultLanguage
   const filePath = resolvePathFromCwd(cfg.uploadFile)
-  await uploadFileWithRetry({ token, projectId, language, filePath })
+  await uploadFileWithRetry({ token, projectId, language, filePath, syncTerms })
   console.log(`[poeditor-upload] Upload completed for ${language}: ${filePath}`)
 }