@lyda/kilo-ui 0.1.1 → 0.1.4

package/README.md

@@ -13,11 +13,12 @@ After you **publish** this project to npm, install the **exact** `name` from its
 
 ```bash
 npm install -D @lyda/kilo-ui
-npx kilo-ui init
 npx kilo-ui add data-table
 ```
 
-If the package was published with an installer hook, `npm install -D ...` will run `kilo-ui init` automatically once. If you use `--ignore-scripts`, run `npx kilo-ui init` manually.
+**First install in a new project:** the package **postinstall** runs `kilo-ui init` once (unless `kilo.config.ts` already exists). That creates **`kilo.config.ts` in your app root** (next to `package.json`) — not inside `node_modules`. Edit it for **aliases**, **`ui.componentsDir`** (folder prefix under `src/components`, default `ui`), and **Tailwind CSS path**. An annotated example ships with the library at **`node_modules/@lyda/kilo-ui/config/kilo.config.example.ts`**. If install used **`--ignore-scripts`**, run **`npx kilo-ui init`** once yourself.
+
+You can still run **`npx kilo-ui init`** anytime to add missing scaffold files; use **`init --force`** to reset **`kilo.config.ts`** to defaults (back up first if you customized it).
 
 **Note:** The public npm name `kilo-ui` may point to a different project (not this Vue CLI). If `npm install -D kilo-ui` pulls SvelteKit or other wrong peers, use a scoped name or install from `file:` / Git. See [Installation](docs/docs/installation.md) in the docs site.
 
@@ -25,9 +26,10 @@ If the package was published with an installer hook, `npm install -D ...` will r
 
 `npx kilo-ui init` creates:
 
-- `components.json` - config and aliases
+- **`kilo.config.ts`** - TypeScript project config (`defineConfig` from `@lyda/kilo-ui/config`), aliases, and **`ui.componentsDir`** (subfolder for installed components, default `ui`)
 - `src/styles/teamwork-ui.css` - Tailwind v4 import + Kilo UI theme tokens
 - `src/lib/utils.ts` - shared helper utilities
+- `env.d.ts` (project root) - Vue + Vite TypeScript declarations for `*.vue` modules (skip if the file already exists); `init` also updates `tsconfig.app.json` / `tsconfig.json` with `paths` for `@/*` when possible
 
 Add the stylesheet once in your app entry, usually `src/main.ts`:
 

package/bin/kilo-ui.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createJiti } from 'jiti'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, relative, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -6,15 +7,24 @@ import { fileURLToPath } from 'node:url'
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const packageRoot = resolve(__dirname, '..')
 const registryRoot = join(packageRoot, 'registry')
+const cliEntry = fileURLToPath(import.meta.url)
 
 const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8'))
 const cliName = typeof pkg.name === 'string' ? pkg.name : 'kilo-ui'
+const pkgName = cliName
 
 const commands = new Set(['init', 'add', 'list', 'help'])
 const [, , maybeCommand, ...args] = process.argv
 const command = commands.has(maybeCommand) ? maybeCommand : 'help'
 
-const configFile = 'components.json'
+const KILO_TS = 'kilo.config.ts'
+const KILO_MTS = 'kilo.config.mts'
+const KILO_JS = 'kilo.config.js'
+const KILO_MJS = 'kilo.config.mjs'
+const CONFIG_MODULES = [KILO_TS, KILO_MTS, KILO_JS, KILO_MJS]
+
+const UI_JSON = 'ui.json'
+const LEGACY_JSON = 'components.json'
 
 function log(message = '') {
   console.log(message)
@@ -26,7 +36,8 @@ function fail(message) {
 }
 
 function readJson(path) {
-  return JSON.parse(readFileSync(path, 'utf8'))
+  const raw = readFileSync(path, 'utf8').replace(/^\uFEFF/, '')
+  return JSON.parse(raw)
 }
 
 function writeJson(path, value) {
@@ -51,17 +62,82 @@ function registry() {
   return readJson(join(registryRoot, 'index.json'))
 }
 
+const defaultAliases = {
+  components: '@/components',
+  composables: '@/composables',
+  lib: '@/lib',
+  types: '@/types',
+}
+
+function normalizeConfig(raw) {
+  const c = typeof raw === 'object' && raw !== null ? { ...raw } : {}
+  c.srcDir = c.srcDir || 'src'
+  c.aliases = { ...defaultAliases, ...(c.aliases || {}) }
+  c.tailwind = c.tailwind || { css: `${c.srcDir}/styles/teamwork-ui.css` }
+  const uiRaw =
+    typeof c.ui === 'object' && c.ui !== null ? { ...c.ui } : {}
+  const componentsPrefix = uiRaw.componentsPrefix
+  delete uiRaw.componentsPrefix
+  c.ui = { componentsDir: 'ui', ...uiRaw }
+  if (
+    (c.ui.componentsDir === undefined || c.ui.componentsDir === null) &&
+    componentsPrefix !== undefined &&
+    componentsPrefix !== null
+  ) {
+    c.ui.componentsDir = componentsPrefix
+  }
+  if (c.ui.componentsDir === undefined || c.ui.componentsDir === null) {
+    c.ui.componentsDir = 'ui'
+  }
+  return c
+}
+
+function hasKiloModuleConfig(cwd) {
+  return CONFIG_MODULES.some((name) => existsSync(join(cwd, name)))
+}
+
+function loadProjectConfigFromDisk(cwd) {
+  const jiti = createJiti(cliEntry, { interopDefault: true, cwd })
+
+  for (const name of CONFIG_MODULES) {
+    const p = join(cwd, name)
+    if (!existsSync(p)) continue
+    try {
+      const mod = jiti(p)
+      const raw = mod?.default ?? mod
+      if (!raw || typeof raw !== 'object') {
+        fail(`${name} must default-export a config object.`)
+      }
+      return normalizeConfig(raw)
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      fail(`Failed to load ${name}: ${msg}`)
+    }
+  }
+
+  const uiPath = join(cwd, UI_JSON)
+  if (existsSync(uiPath)) return normalizeConfig(readJson(uiPath))
+
+  const legacyPath = join(cwd, LEGACY_JSON)
+  if (existsSync(legacyPath)) return normalizeConfig(readJson(legacyPath))
+
+  return null
+}
+
 function projectConfig() {
-  const path = join(process.cwd(), configFile)
-  if (!existsSync(path)) {
-    fail(`Missing ${configFile}. Run "npx ${cliName} init" first.`)
+  const cwd = process.cwd()
+  const config = loadProjectConfigFromDisk(cwd)
+  if (!config) {
+    fail(
+      `Missing kilo.config.ts (or kilo.config.mjs, ${UI_JSON}, ${LEGACY_JSON}). Run "npx ${cliName} init" first.`,
+    )
   }
-  return readJson(path)
+  return config
 }
 
 function aliasPath(config, key) {
   const value = config.aliases?.[key]
-  if (!value) fail(`Missing aliases.${key} in ${configFile}`)
+  if (!value) fail(`Missing aliases.${key} in kilo.config / ${UI_JSON} / ${LEGACY_JSON}`)
   return value.replace(/^@\//, config.srcDir ? `${config.srcDir}/` : 'src/')
 }
 
@@ -69,8 +145,22 @@ function resolveTarget(config, alias, fileName) {
   return join(process.cwd(), aliasPath(config, alias), fileName)
 }
 
+/** Path segments under the components alias (e.g. ["ui"] → …/components/ui/…). Empty string = no extra folder. */
+function componentDirSegments(config) {
+  const dir = config.ui?.componentsDir
+  if (dir === '') return []
+  if (dir === undefined) return ['ui']
+  return String(dir).replace(/\\/g, '/').split('/').filter(Boolean)
+}
+
 function componentFilePath(config, componentName, fileName) {
-  return join(process.cwd(), aliasPath(config, 'components'), 'ui', componentName, fileName)
+  return join(
+    process.cwd(),
+    aliasPath(config, 'components'),
+    ...componentDirSegments(config),
+    componentName,
+    fileName,
+  )
 }
 
 function copyRegistryFile(sourceRelative, targetPath, config, force) {
@@ -84,13 +174,105 @@ function copyRegistryFile(sourceRelative, targetPath, config, force) {
   writeFile(targetPath, content, force)
 }
 
+/**
+ * Vite resolves `@` from vite.config; TypeScript needs matching paths or `@/…` imports fail in the editor / vue-tsc.
+ * Vue templates usually keep env.d.ts at the project root next to tsconfig.app.json (not under src/).
+ */
+function kiloConfigSerializable(config) {
+  const n = normalizeConfig(config)
+  return {
+    style: n.style ?? 'default',
+    srcDir: n.srcDir,
+    ui: n.ui,
+    tailwind: n.tailwind,
+    aliases: n.aliases,
+  }
+}
+
+function buildKiloConfigFileContent(config) {
+  const obj = kiloConfigSerializable(config)
+  const body = JSON.stringify(obj, null, 2)
+  const header = `// Kilo UI — app config (generated in your project root by ${pkgName}, not inside the library package)\n// ui.componentsDir = folder prefix under aliases.components (default "ui" → …/components/ui/<component>/)\n// Use "" for no prefix: …/components/<component>/\n\n`
+  return `${header}import { defineConfig } from '${pkgName}/config'\n\nexport default defineConfig(${body})\n`
+}
+
+/** Create kilo.config.ts when missing, or overwrite when force (unless a non-.ts kilo module is the only config). */
+function writeKiloConfigTs(cwd, config, force) {
+  const kiloPath = join(cwd, KILO_TS)
+  if (hasKiloModuleConfig(cwd) && !force) return
+  if (!force && existsSync(kiloPath)) return
+
+  const rel = relative(cwd, kiloPath)
+  const existed = existsSync(kiloPath)
+  ensureDir(dirname(kiloPath))
+  writeFileSync(kiloPath, buildKiloConfigFileContent(config), 'utf8')
+  log(`${force || existed ? 'write' : 'add'} ${rel}`)
+}
+
+function mergeTsconfigForAliases(cwd, srcDir = 'src') {
+  const srcNorm = String(srcDir || 'src').replace(/\\/g, '/').replace(/\/$/, '') || 'src'
+  const pathPattern = `./${srcNorm}/*`
+  const appPath = join(cwd, 'tsconfig.app.json')
+  const rootPath = join(cwd, 'tsconfig.json')
+
+  function tryMerge(filePath) {
+    if (!existsSync(filePath)) return false
+    let parsed
+    try {
+      parsed = readJson(filePath)
+    } catch {
+      log(`skip ${relative(cwd, filePath)} (invalid JSON — fix or add paths manually)`)
+      return false
+    }
+    const relName = relative(cwd, filePath)
+    if (relName === 'tsconfig.json' && parsed.references?.length && !parsed.compilerOptions) {
+      return false
+    }
+    parsed.compilerOptions = parsed.compilerOptions || {}
+    const co = parsed.compilerOptions
+    const paths = { ...(co.paths || {}) }
+    const key = '@/*'
+    if (paths[key]?.[0] === pathPattern) {
+      log(`skip ${relName} (paths "@/*" already set)`)
+      return true
+    }
+    if (paths[key]?.length) {
+      log(
+        `skip ${relName} (paths "@/*" already defined — ensure it points at your ${srcNorm}/ folder for kilo-ui imports)`,
+      )
+      return true
+    }
+    paths[key] = [pathPattern]
+    co.paths = paths
+    if (co.baseUrl === undefined) co.baseUrl = '.'
+
+    if (Array.isArray(parsed.include)) {
+      const hasEnv = parsed.include.some((entry) => String(entry).includes('env.d.ts'))
+      if (!hasEnv) parsed.include.unshift('env.d.ts')
+    }
+
+    writeJson(filePath, parsed)
+    log(`update ${relName} (TypeScript paths for @ + env.d.ts in include)`)
+    return true
+  }
+
+  if (tryMerge(appPath)) return
+  if (tryMerge(rootPath)) return
+
+  log('\nTip: Add TypeScript paths so editors resolve @ imports (same folder as vite alias):')
+  log(`  "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["${pathPattern}"] } }`)
+}
+
 function init(args) {
   const force = args.includes('--force')
-  const configPath = join(process.cwd(), configFile)
-  const defaultConfig = {
-    $schema: 'https://kilo-ui.local/schema.json',
+  const cwd = process.cwd()
+  const uiPath = join(cwd, UI_JSON)
+  const legacyPath = join(cwd, LEGACY_JSON)
+
+  const defaultConfig = normalizeConfig({
     style: 'default',
     srcDir: 'src',
+    ui: { componentsDir: 'ui' },
     tailwind: {
       css: 'src/styles/teamwork-ui.css',
     },
@@ -100,23 +282,43 @@ function init(args) {
       lib: '@/lib',
       types: '@/types',
     },
-  }
-  const config = existsSync(configPath) && !force ? readJson(configPath) : defaultConfig
+  })
+
+  let config
 
-  if (existsSync(configPath) && !force) {
-    log(`skip ${configFile} (already exists)`)
+  if (!force) {
+    if (hasKiloModuleConfig(cwd)) {
+      config = loadProjectConfigFromDisk(cwd)
+      if (!config) fail('Could not read kilo config.')
+      log(`skip kilo.config.* (already exists)`)
+    } else if (existsSync(uiPath)) {
+      config = normalizeConfig(readJson(uiPath))
+      log(`using ${UI_JSON} (legacy). Prefer ${KILO_TS} — run init on a fresh branch or add the file from docs.`)
+    } else if (existsSync(legacyPath)) {
+      config = normalizeConfig(readJson(legacyPath))
+      log(`using ${LEGACY_JSON} (legacy fields). Adding ${KILO_TS} if missing.`)
+    } else {
+      config = defaultConfig
+    }
   } else {
-    writeJson(configPath, config)
-    log(`write ${configFile}`)
+    config = defaultConfig
   }
 
+  writeKiloConfigTs(cwd, config, force)
+
   copyRegistryFile('styles/teamwork-ui.css', join(process.cwd(), config.tailwind.css), config, force)
   copyRegistryFile('lib/utils.ts', resolveTarget(config, 'lib', 'utils.ts'), config, force)
+  copyRegistryFile('vue/env.d.ts', join(process.cwd(), 'env.d.ts'), config, force)
+
+  mergeTsconfigForAliases(process.cwd(), config.srcDir || 'src')
 
+  const sub = componentDirSegments(config).join('/') || '(components root)'
   log('\nDone. Add this once in your app entry or main stylesheet:')
   log(`  import './styles/${config.tailwind.css.replace(/^.*\//, '')}'`)
+  log(`\nComponents install under: ${aliasPath(config, 'components').replace(/\\/g, '/')}/${sub}/<name>/`)
   log('\nThen add components:')
   log(`  npx ${cliName} add data-table app-navbar activity-log`)
+  log(`\nEdit ${KILO_TS} to change where components install (aliases, ui.componentsDir).`)
 }
 
 function add(args) {
@@ -163,6 +365,8 @@ Usage:
   npx ${cliName} add <component...> [--force]
   npx ${cliName} list
 
+Config: ${KILO_TS} (or ${KILO_MJS}, legacy ${UI_JSON} / ${LEGACY_JSON}). Use defineConfig from "${pkgName}/config". Set ui.componentsDir for the folder under your components alias (default "ui").
+
 Examples:
   npx ${cliName} init
   npx ${cliName} add data-table app-navbar

package/bin/postinstall.mjs

@@ -1,20 +1,23 @@
 #!/usr/bin/env node
 import { existsSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { spawnSync } from 'node:child_process'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const packageRoot = resolve(__dirname, '..')
 
-const initCwd = process.env.INIT_CWD
+const initCwd = resolveConsumerProjectRoot()
 if (!initCwd) process.exit(0)
 
 // Avoid running when installing this repo itself.
-if (resolve(initCwd) === packageRoot) process.exit(0)
+if (resolve(initCwd) === resolve(packageRoot)) process.exit(0)
 
-// Only run once; if the user already initialized, do nothing.
-if (existsSync(join(initCwd, 'components.json'))) process.exit(0)
+// Only skip auto-init when a kilo config module already exists.
+// Do not treat components.json / ui.json as "done" — shadcn and other tools use those too,
+// and we still need to add kilo.config.ts.
+const kiloModuleNames = ['kilo.config.ts', 'kilo.config.mts', 'kilo.config.js', 'kilo.config.mjs']
+if (kiloModuleNames.some((name) => existsSync(join(initCwd, name)))) process.exit(0)
 
 const cliEntry = join(packageRoot, 'bin', 'kilo-ui.mjs')
 
@@ -24,3 +27,21 @@ const result = spawnSync(process.execPath, [cliEntry, 'init'], {
 })
 
 process.exit(result.status ?? 1)
+
+/**
+ * Prefer npm's INIT_CWD or npm_config_local_prefix. If missing, infer the app root only when
+ * this package lives under node_modules (never guess from a bare repo path).
+ */
+function resolveConsumerProjectRoot() {
+  const fromEnv = process.env.INIT_CWD || process.env.npm_config_local_prefix
+  if (fromEnv) return resolve(fromEnv)
+
+  const norm = packageRoot.replace(/\\/g, '/')
+  if (!norm.includes('/node_modules/')) return null
+
+  const parent = dirname(packageRoot)
+  if (basename(parent).startsWith('@')) {
+    return resolve(parent, '..', '..')
+  }
+  return resolve(parent, '..')
+}

package/config/define-config.d.ts

@@ -0,0 +1,26 @@
+export interface KiloUiUserConfig {
+  /** @deprecated informational only */
+  $schema?: string
+  style?: string
+  srcDir?: string
+  ui?: {
+    /**
+     * Folder prefix under `aliases.components` where `kilo-ui add` places each component
+     * (default `"ui"` → e.g. `src/components/ui/<name>/`). Use `""` for `…/components/<name>/`.
+     */
+    componentsDir?: string
+    /** Same as `componentsDir` if you prefer the name “prefix”. */
+    componentsPrefix?: string
+  }
+  tailwind?: {
+    css: string
+  }
+  aliases: {
+    components: string
+    composables: string
+    lib: string
+    types: string
+  }
+}
+
+export function defineConfig(config: KiloUiUserConfig): KiloUiUserConfig

package/config/define-config.mjs

@@ -0,0 +1,4 @@
+/** @param {import('./define-config.d.ts').KiloUiUserConfig} config */
+export function defineConfig(config) {
+  return config
+}

package/config/kilo.config.example.ts

@@ -0,0 +1,29 @@
+/**
+ * Example config shipped with the npm package at:
+ *   node_modules/@lyda/kilo-ui/config/kilo.config.example.ts
+ *
+ * Your Vue app does NOT edit this file. On `npm install`, the CLI creates
+ * **`kilo.config.ts` in your project root** (next to package.json).
+ *
+ * Change **`ui.componentsDir`** to set the folder prefix under your components path
+ * (e.g. `"ui"` → src/components/ui/data-table/…). Use `componentsPrefix` as an alias.
+ */
+import { defineConfig } from '@lyda/kilo-ui/config'
+
+export default defineConfig({
+  style: 'default',
+  srcDir: 'src',
+  ui: {
+    /** Folder prefix under `aliases.components` for copied registry components */
+    componentsDir: 'ui',
+  },
+  tailwind: {
+    css: 'src/styles/teamwork-ui.css',
+  },
+  aliases: {
+    components: '@/components',
+    composables: '@/composables',
+    lib: '@/lib',
+    types: '@/types',
+  },
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyda/kilo-ui",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "shadcn-style Vue component registry for team CRUD apps",
   "type": "module",
   "repository": {
@@ -17,8 +17,15 @@
   "bin": {
     "kilo-ui": "bin/kilo-ui.mjs"
   },
+  "exports": {
+    "./config": {
+      "types": "./config/define-config.d.ts",
+      "default": "./config/define-config.mjs"
+    }
+  },
   "files": [
     "bin",
+    "config",
     "registry",
     "README.md"
   ],
@@ -49,5 +56,8 @@
     "crud",
     "ui"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "jiti": "^2.7.0"
+  }
 }

package/registry/vue/env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<object, object, any>
+  export default component
+}