@lucashw68/nsdb 1.0.0-rc.2

package/README.md

@@ -0,0 +1,159 @@
+# NSDB — Nuxt Supabase Data Bridge
+
+NSDB transforme les types d'une base Supabase en modèles Nuxt typés, stores Pinia optionnels et composants CRUD génériques. Supabase reste la source de vérité pour les données, Auth et RLS.
+
+> **Statut de publication :** `1.0.0-rc.2` est la release candidate actuelle. Elle n'a pas encore été publiée sur npm. Les commandes d'installation ci-dessous s'appliqueront après publication.
+
+## Quick start
+
+Prérequis validés pour la RC : Node 22.14+, Nuxt 4.2.1+, Vue 3.5.24+, `@nuxtjs/supabase` 1.6.1 ou 2.x, `@pinia/nuxt` 0.11.2+, Pinia 3.0.3+, un projet Supabase et ses policies RLS. Le CLI Supabase est requis pour générer les types ; une URL PostgreSQL directe est recommandée pour les métadonnées exactes.
+
+```bash
+npm install @lucashw68/nsdb @nuxtjs/supabase @pinia/nuxt pinia
+npm install --save-dev supabase
+npx nsdb init
+npx nsdb generate:all
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+	modules: ['@lucashw68/nsdb', '@pinia/nuxt', '@nuxtjs/supabase'],
+})
+```
+
+```ts
+const playlists = usePlaylists()
+
+await playlists.fetch()
+const playlist = await playlists.create({ title: 'Nouvelle playlist' })
+
+await playlists.update(playlist, { title: 'Renommée' })
+await playlists.remove(playlist)
+```
+
+```vue
+<NsdbList model="playlists" />
+<NsdbForm model="playlists" />
+```
+
+Le guide d'installation complet est dans [GET_STARTED.md](./GET_STARTED.md).
+
+## Modèles générés
+
+Le modèle est l'API recommandée. Les opérations asynchrones rejettent leur Promise en cas d'erreur et `error` expose également la dernière erreur réactive.
+
+```ts
+const playlists = usePlaylists({ store: true })
+
+await playlists.fetch()
+await playlists.refresh()
+playlists.invalidate()
+
+await playlists.create({ title: 'Rock' })
+await playlists.update(id, { title: 'Jazz' })
+await playlists.remove(id)
+
+playlists.subscribe()
+await playlists.unsubscribe()
+```
+
+`update()` et `remove()` acceptent soit la valeur de clé primaire, soit une ligne du même modèle. Lorsque la ligne est déjà disponible, NSDB en extrait la clé primaire générée sans envoyer le reste de la ligne dans la mutation.
+
+`{ store: true }` active l'état partagé, le TTL et éventuellement la persistance. Sans store, chaque handle possède sa collection et contacte Supabase à chaque `fetch()`.
+
+## Requêtes
+
+`fetch(options)` est l'unique syntaxe canonique pour les listes filtrées :
+
+```ts
+await playlists.fetch({
+	where: {
+		active: true,
+		created_at: { op: 'gte', value: '2026-01-01' },
+	},
+	search: 'rock',
+	searchColumns: ['title', 'provider'],
+	orderBy: 'created_at',
+	orderDirection: 'desc',
+	limit: 20,
+	offset: 0,
+})
+```
+
+Relations courantes :
+
+```ts
+const posts = await usePosts().fetch({ include: ['author', 'tags'] })
+```
+
+`select` et `orderForeignTable` restent disponibles comme échappatoires PostgREST avancées.
+
+## Composants
+
+```vue
+<NsdbList model="playlists" searchable :search-columns="['title']" :page-size="20">
+	<template #cell="{ column, row, value }">
+		<strong v-if="column.key === 'title'">{{ row.title }}</strong>
+		<span v-else>{{ value }}</span>
+	</template>
+</NsdbList>
+```
+
+```vue
+<NsdbForm model="playlists" @saved="onSaved">
+	<template #field-cover_url="{ value, update }">
+		<MyUploader :model-value="value" @update:model-value="update" />
+	</template>
+</NsdbForm>
+```
+
+Les slots permettent de remplacer le rendu sans introduire un framework UI.
+
+## API bas niveau
+
+Pour les cas qui dépassent les modèles générés :
+
+```ts
+const api = useSupabaseApi()
+const result = await api.all('playlists', { where: { active: true }, limit: 20 })
+const row = await api.getById('playlists', id)
+await api.remove('playlists', id)
+```
+
+Cette couche renvoie des objets discriminés `{ success, data, error, count }` au lieu de rejeter les erreurs Supabase.
+
+Storage conserve son vocabulaire métier :
+
+```ts
+const storage = useSupabaseApiStorage()
+await storage.upload('avatars', 'users/me.png', file)
+const signed = await storage.createSignedUrl('avatars', 'users/me.png', 300)
+await storage.remove('avatars', 'users/me.png')
+```
+
+## Configuration et sécurité
+
+La configuration minimale générée par `nsdb init` suffit pour un projet standard. Les options avancées couvrent les chemins, la génération distante, les tables exposées et les politiques de colonnes.
+
+```ts
+import type { NsdbConfig } from '@lucashw68/nsdb/types'
+
+export default {
+	supabase: { schema: 'public', linked: true },
+	tables: {
+		include: ['playlists'],
+		columns: { playlists: { internal_note: { serverOnly: true } } },
+	},
+} satisfies NsdbConfig
+```
+
+Les règles `serverOnly`, `hidden` et `editable` réduisent la surface client ; elles ne remplacent jamais les policies RLS.
+
+## Documentation
+
+La documentation publique officielle est maintenue dans le dossier [`website/`](https://github.com/Lucashw68/nsdb/tree/main/website) du repository. Consultez notamment les guides d'API publique, de migration, de cache/Realtime et de sécurité/RLS avant d'adopter la prochaine release candidate.
+
+## Licence
+
+NSDB est distribué sous [licence MIT](./LICENSE).

package/cli/index.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+import { execSync } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const currentFilePath = fileURLToPath(import.meta.url)
+const currentDirectoryPath = path.dirname(currentFilePath)
+
+const commands = {
+	'clear': path.resolve(currentDirectoryPath, '../scripts/clear.js'),
+	'init': path.resolve(currentDirectoryPath, '../scripts/init.js'),
+	'generate:types': path.resolve(currentDirectoryPath, '../scripts/generate-types.js'),
+	'generate:metadata': path.resolve(currentDirectoryPath, '../scripts/generate-metadata.js'),
+	'generate:enums': path.resolve(currentDirectoryPath, '../scripts/generate-enums.js'),
+	'generate:schemas': path.resolve(currentDirectoryPath, '../scripts/generate-schemas.js'),
+	'generate:models': path.resolve(currentDirectoryPath, '../scripts/generate-models.js'),
+	'generate:composables': path.resolve(currentDirectoryPath, '../scripts/generate-composables.js'),
+	'generate:stores': path.resolve(currentDirectoryPath, '../scripts/generate-stores.js'),
+	'generate:all': [
+		path.resolve(currentDirectoryPath, '../scripts/generate-types.js'),
+		path.resolve(currentDirectoryPath, '../scripts/generate-metadata.js'),
+		path.resolve(currentDirectoryPath, '../scripts/generate-enums.js'),
+		path.resolve(currentDirectoryPath, '../scripts/generate-schemas.js'),
+		path.resolve(currentDirectoryPath, '../scripts/generate-models.js'),
+		path.resolve(currentDirectoryPath, '../scripts/generate-stores.js'),
+		path.resolve(currentDirectoryPath, '../scripts/generate-models.js'),
+		path.resolve(currentDirectoryPath, '../scripts/generate-composables.js'),
+	],
+}
+
+const help = `NSDB — Nuxt Supabase Data Bridge
+
+Usage:
+  nsdb init [options]
+  nsdb generate:all [options]
+  nsdb generate:types|metadata|enums|schemas|models|stores|composables [options]
+  nsdb clear [--dry-run]
+
+Run "nsdb init --help" is not required: init options are documented in GET_STARTED.md.`
+
+if (!process.argv[2] || ['help', '--help', '-h'].includes(process.argv[2])) {
+	console.log(help)
+	process.exit(0)
+}
+
+const command = commands[process.argv[2]]
+const forwardedArguments = process.argv.slice(3)
+
+function quoteShellArgument(argument) {
+	return `"${String(argument).replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`
+}
+
+function buildCommandLine(command) {
+	const forwardedCommandLine = forwardedArguments.map(quoteShellArgument).join(' ')
+
+	if (Array.isArray(command)) {
+		return command
+			.map(scriptPath => {
+				const baseCommandLine = `node "${scriptPath}"`
+				return forwardedCommandLine ? `${baseCommandLine} ${forwardedCommandLine}` : baseCommandLine
+			})
+			.join(' && ')
+	}
+
+	const baseCommandLine = `node "${command}"`
+	return forwardedCommandLine ? `${baseCommandLine} ${forwardedCommandLine}` : baseCommandLine
+}
+
+if (!command) {
+	console.error(`❌ Command not found: ${process.argv[2]}`)
+	process.exit(1)
+}
+
+try {
+	execSync(buildCommandLine(command), {
+		stdio: 'inherit',
+		shell: true
+	})
+} catch (err) {
+	console.error(`❌ Failed to execute command: ${process.argv[2]}`)
+	process.exit(1)
+}

package/helpers/args.js

@@ -0,0 +1,22 @@
+// helpers/args.js
+export function parseArgs(argv = process.argv.slice(2)) {
+	const args = [...argv]
+
+	const get = (name, def = '') => {
+		const i = args.findIndex(a => a === `--${name}`)
+		return i !== -1 && args[i + 1] ? args[i + 1] : def
+	}
+
+	const getBool = (name, def = false) => {
+		const i = args.findIndex(a => a === `--${name}`)
+		if (i === -1) return def
+		const next = args[i + 1]
+		if (next === 'true') return true
+		if (next === 'false') return false
+		return true
+	}
+
+	const rest = () => args.filter(a => !a.startsWith('--') && !a.startsWith('-'))
+
+	return { get, getBool, rest, raw: args }
+}

package/helpers/config.js

@@ -0,0 +1,142 @@
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { exists, readText } from './io.js'
+
+export const defaultNsdbConfig = {
+	supabase: {
+		schema: 'public',
+		projectId: '',
+		dbUrl: '',
+		linked: false,
+		remoteTypes: {
+			sshHost: '',
+			projectPath: '',
+			dbUrl: '',
+			remoteOutput: '/tmp/database.types.ts',
+			beforeCommand: '',
+			supabaseCommand: 'npx supabase',
+		},
+	},
+	paths: {
+		types: 'types/database.types.ts',
+		metadata: 'nsdb/database.metadata.json',
+		enums: 'nsdb/enums.ts',
+		schemas: 'nsdb/schemas',
+		models: 'nsdb/models',
+		composables: 'nsdb/composables',
+		stores: 'stores',
+	},
+	imports: {
+		databaseTypes: '~~/types/database.types',
+	},
+	tables: {
+		include: [],
+		exclude: [],
+		columns: {},
+	},
+	templates: {
+		model: 'node_modules/@lucashw68/nsdb/templates/model.template.ts',
+		schema: 'node_modules/@lucashw68/nsdb/templates/schema.template.ts',
+		useNsdbModel: 'node_modules/@lucashw68/nsdb/templates/useNsdbModel.template.ts',
+		store: 'node_modules/@lucashw68/nsdb/templates/store.template.ts',
+	},
+}
+
+function isPlainObject(value) {
+	return value != null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function mergeConfig(baseConfig, overrideConfig) {
+	const mergedConfig = { ...baseConfig }
+
+	for (const [key, overrideValue] of Object.entries(overrideConfig ?? {})) {
+		const baseValue = mergedConfig[key]
+		if (isPlainObject(baseValue) && isPlainObject(overrideValue)) {
+			mergedConfig[key] = mergeConfig(baseValue, overrideValue)
+			continue
+		}
+
+		mergedConfig[key] = overrideValue
+	}
+
+	return mergedConfig
+}
+
+function findConfigFile(currentWorkingDirectory, explicitConfigPath) {
+	if (explicitConfigPath) {
+		const absoluteConfigPath = path.resolve(currentWorkingDirectory, explicitConfigPath)
+		return exists(absoluteConfigPath) ? absoluteConfigPath : null
+	}
+
+	const candidates = [
+		'nsdb.config.ts',
+		'nsdb.config.mts',
+		'nsdb.config.mjs',
+		'nsdb.config.js',
+		'nsdb.config.cjs',
+		'nsdb.config.cts',
+		'nsdb.config.json',
+	]
+
+	return candidates
+		.map(candidate => path.resolve(currentWorkingDirectory, candidate))
+		.find(candidatePath => exists(candidatePath)) ?? null
+}
+
+async function readConfigFile(configFilePath) {
+	if (!configFilePath) return {}
+
+	if (configFilePath.endsWith('.json')) {
+		return JSON.parse(readText(configFilePath))
+	}
+
+	if (configFilePath.endsWith('.ts') || configFilePath.endsWith('.mts') || configFilePath.endsWith('.cts')) {
+		const { tsImport } = await import('tsx/esm/api')
+		const importedConfig = await tsImport(pathToFileURL(configFilePath).href, import.meta.url)
+		return resolveConfigExport(importedConfig)
+	}
+
+	const importedConfig = await import(pathToFileURL(configFilePath).href)
+	return resolveConfigExport(importedConfig)
+}
+
+function resolveConfigExport(importedConfig) {
+	const configExport = importedConfig.default ?? importedConfig.nsdb ?? importedConfig
+
+	if (
+		configExport &&
+		typeof configExport === 'object' &&
+		configExport.__esModule &&
+		configExport.default
+	) {
+		return configExport.default
+	}
+
+	return configExport
+}
+
+export async function loadNsdbConfig(currentWorkingDirectory, explicitConfigPath = '') {
+	const configFilePath = findConfigFile(currentWorkingDirectory, explicitConfigPath)
+	const fileConfig = await readConfigFile(configFilePath)
+
+	return {
+		config: mergeConfig(defaultNsdbConfig, fileConfig),
+		configFilePath,
+	}
+}
+
+export function getConfigValue(config, dottedPath, fallbackValue = undefined) {
+	return dottedPath
+		.split('.')
+		.reduce((currentValue, pathPart) => currentValue?.[pathPart], config) ?? fallbackValue
+}
+
+export function getOption(parsedArguments, config, argumentName, configPath, fallbackValue = '') {
+	const configValue = getConfigValue(config, configPath, fallbackValue)
+	return parsedArguments.get(argumentName, configValue)
+}
+
+export function getBoolOption(parsedArguments, config, argumentName, configPath, fallbackValue = false) {
+	const configValue = getConfigValue(config, configPath, fallbackValue)
+	return parsedArguments.getBool(argumentName, configValue)
+}

package/helpers/generated.js

@@ -0,0 +1,48 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+export const GENERATED_FILE_MARKER = '// @generated by @lucashw68/nsdb - DO NOT EDIT.'
+
+export function markGenerated(content) {
+	const normalizedContent = String(content).replace(/^\uFEFF/, '')
+	if (normalizedContent.startsWith(GENERATED_FILE_MARKER)) return normalizedContent
+	return `${GENERATED_FILE_MARKER}\n${normalizedContent}`
+}
+
+export function isNsdbGeneratedFile(filePath) {
+	if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) return false
+	const descriptor = fs.openSync(filePath, 'r')
+	try {
+		const buffer = Buffer.alloc(256)
+		const bytesRead = fs.readSync(descriptor, buffer, 0, buffer.length, 0)
+		return buffer.subarray(0, bytesRead).toString('utf8').includes(GENERATED_FILE_MARKER)
+	} finally {
+		fs.closeSync(descriptor)
+	}
+}
+
+export function listGeneratedFiles(directoryPath) {
+	if (!fs.existsSync(directoryPath) || !fs.statSync(directoryPath).isDirectory()) return []
+
+	return fs.readdirSync(directoryPath, { withFileTypes: true }).flatMap((entry) => {
+		const entryPath = path.join(directoryPath, entry.name)
+		if (entry.isDirectory()) return listGeneratedFiles(entryPath)
+		return entry.isFile() && isNsdbGeneratedFile(entryPath) ? [entryPath] : []
+	})
+}
+
+export function removeGeneratedFile(filePath, { dryRun = false, verbose = false } = {}) {
+	if (!isNsdbGeneratedFile(filePath)) return false
+	if (!dryRun) fs.unlinkSync(filePath)
+	if (verbose || dryRun) {
+		console.log(`${dryRun ? 'Would remove' : 'Removed'} generated file: ${path.relative(process.cwd(), filePath)}`)
+	}
+	return true
+}
+
+export function removeStaleGeneratedFiles(directoryPath, retainedFileNames) {
+	const retained = new Set(retainedFileNames)
+	for (const filePath of listGeneratedFiles(directoryPath)) {
+		if (!retained.has(path.basename(filePath))) fs.unlinkSync(filePath)
+	}
+}

package/helpers/io.js

@@ -0,0 +1,39 @@
+// helpers/io.js
+import fs from 'fs'
+import path from 'path'
+
+export function ensureDir(dirPath) {
+	if (!fs.existsSync(dirPath)) fs.mkdirSync(dirPath, { recursive: true })
+}
+
+export function writeText(filePath, content, verbose = false) {
+	ensureDir(path.dirname(filePath))
+	fs.writeFileSync(filePath, content, 'utf8')
+	if (verbose) console.log(`✍️  Wrote: ${path.relative(process.cwd(), filePath)}`)
+}
+
+export function readText(filePath) {
+	return fs.readFileSync(filePath, 'utf8')
+}
+
+export function removeDirIfExists(dirPath, verbose = false) {
+	if (!fs.existsSync(dirPath)) return false
+	fs.rmSync(dirPath, { recursive: true, force: true })
+	if (verbose) console.log(`🗑️  Removed dir: ${path.relative(process.cwd(), dirPath)}`)
+	return true
+}
+
+export function removeFileIfExists(filePath, verbose = false) {
+	if (!fs.existsSync(filePath)) return false
+	fs.unlinkSync(filePath)
+	if (verbose) console.log(`🗑️  Removed file: ${path.relative(process.cwd(), filePath)}`)
+	return true
+}
+
+export function listFiles(dirPath) {
+	return fs.existsSync(dirPath) ? fs.readdirSync(dirPath) : []
+}
+
+export function exists(p) {
+	return fs.existsSync(p)
+}

package/helpers/metadata.js

@@ -0,0 +1,19 @@
+import path from 'node:path'
+import { exists, readText } from './io.js'
+
+export function loadDatabaseMetadata(currentWorkingDirectory, config) {
+	const configuredPath = config?.paths?.metadata
+	if (!configuredPath) return null
+	const metadataPath = path.resolve(currentWorkingDirectory, configuredPath)
+	if (!exists(metadataPath)) return null
+
+	const metadata = JSON.parse(readText(metadataPath))
+	if (metadata?.version !== 1 || !metadata.tables || typeof metadata.tables !== 'object') {
+		throw new Error(`[nsdb] Invalid database metadata file: ${metadataPath}`)
+	}
+	return metadata
+}
+
+export function getTableMetadata(metadata, tableName) {
+	return metadata?.tables?.[tableName] ?? null
+}

package/helpers/names.js

@@ -0,0 +1,16 @@
+// helpers/names.js
+export const toPascal = (s) => (
+	String(s)
+		.replace(/[_\-./\s]+/g, ' ')
+		.trim()
+		.replace(/(^|\s)([a-zA-Z])/g, (_, __, c) => c.toUpperCase())
+		.replace(/\s+/g, '')
+)
+
+export const singular = (s) => (
+	String(s).endsWith('s') ? s.slice(0, -1) : s
+)
+
+export const modelHookName = (table) => `use${toPascal(table)}`
+export const storeName = (table) => `use${toPascal(singular(table))}Store`
+export const schemaName = (table) => `${toPascal(singular(table))}Schema`

package/helpers/relations.js

@@ -0,0 +1,101 @@
+function singular(value) {
+	return value.endsWith('ies') ? `${value.slice(0, -3)}y` : value.replace(/s$/, '')
+}
+
+function forwardAlias(relation) {
+	const raw = relation.columns.join('_').replace(/_id(?:_|$)/g, '_').replace(/_+$/, '')
+	return raw || singular(relation.referencedRelation)
+}
+
+function addUnique(catalog, tableName, relation) {
+	const entries = catalog[tableName] ??= []
+	let alias = relation.alias
+	if (entries.some(entry => entry.alias === alias)) {
+		alias = `${alias}_${relation.foreignKeyName}`.replace(/[^a-zA-Z0-9_]/g, '_')
+	}
+	entries.push({ ...relation, alias })
+}
+
+function isJoinTable(table) {
+	if (table.relationships.length !== 2) return false
+	const relationColumns = table.relationships.flatMap(relation => relation.columns)
+	const uniqueRelationColumns = [...new Set(relationColumns)].sort()
+	const constrained = [table.primaryKey, ...table.uniqueConstraints.map(item => item.columns)]
+		.some(columns => [...columns].sort().join('\0') === uniqueRelationColumns.join('\0'))
+	if (!constrained) return false
+
+	return Object.entries(table.columns).every(([column, metadata]) =>
+		uniqueRelationColumns.includes(column) || metadata.nullable || metadata.hasDefault || metadata.generated,
+	)
+}
+
+export function buildRelationCatalog(databaseMetadata, exposedTableNames) {
+	const catalog = Object.fromEntries([...exposedTableNames].map(tableName => [tableName, []]))
+	if (!databaseMetadata) return catalog
+
+	for (const [sourceTable, table] of Object.entries(databaseMetadata.tables)) {
+		if (!exposedTableNames.has(sourceTable)) continue
+		for (const relation of table.relationships) {
+			if (!exposedTableNames.has(relation.referencedRelation)) continue
+			const alias = forwardAlias(relation)
+			const nullable = relation.columns.some(column => table.columns[column]?.nullable)
+			addUnique(catalog, sourceTable, {
+				alias,
+				kind: relation.isOneToOne ? 'hasOne' : 'belongsTo',
+				direction: 'forward',
+				nullable,
+				referencedTable: relation.referencedRelation,
+				embedResource: sourceTable === relation.referencedRelation && relation.columns.length === 1
+					? relation.columns[0]
+					: relation.referencedRelation,
+				localColumns: relation.columns,
+				referencedColumns: relation.referencedColumns,
+				foreignKeyName: relation.foreignKeyName,
+				composite: relation.columns.length > 1,
+			})
+
+			const duplicates = table.relationships.filter(item => item.referencedRelation === relation.referencedRelation).length
+			const inverseAlias = sourceTable === relation.referencedRelation && alias === 'parent'
+				? 'children'
+				: duplicates > 1 ? `${alias}_${sourceTable}` : sourceTable
+			addUnique(catalog, relation.referencedRelation, {
+				alias: inverseAlias,
+				kind: relation.isOneToOne ? 'hasOne' : 'hasMany',
+				direction: 'inverse',
+				nullable: false,
+				referencedTable: sourceTable,
+				embedResource: sourceTable,
+				localColumns: relation.referencedColumns,
+				referencedColumns: relation.columns,
+				foreignKeyName: relation.foreignKeyName,
+				composite: relation.columns.length > 1,
+			})
+		}
+	}
+
+	for (const [joinTableName, table] of Object.entries(databaseMetadata.tables)) {
+		if (!exposedTableNames.has(joinTableName) || !isJoinTable(table)) continue
+		const [left, right] = table.relationships
+		if (!exposedTableNames.has(left.referencedRelation) || !exposedTableNames.has(right.referencedRelation)) continue
+		addUnique(catalog, left.referencedRelation, {
+			alias: right.referencedRelation,
+			kind: 'manyToMany', direction: 'through', nullable: false,
+			referencedTable: right.referencedRelation,
+			embedResource: right.referencedRelation,
+			localColumns: left.referencedColumns,
+			referencedColumns: right.referencedColumns,
+			throughTable: joinTableName,
+		})
+		addUnique(catalog, right.referencedRelation, {
+			alias: left.referencedRelation,
+			kind: 'manyToMany', direction: 'through', nullable: false,
+			referencedTable: left.referencedRelation,
+			embedResource: left.referencedRelation,
+			localColumns: right.referencedColumns,
+			referencedColumns: left.referencedColumns,
+			throughTable: joinTableName,
+		})
+	}
+
+	return catalog
+}

package/helpers/shell.js

@@ -0,0 +1,15 @@
+// helpers/shell.js
+import { execSync } from 'node:child_process'
+
+export function run(cmd, { inherit = true, env = process.env } = {}) {
+	execSync(cmd, { stdio: inherit ? 'inherit' : 'pipe', shell: true, env })
+}
+
+export function isAvailable(cmd) {
+	try {
+		execSync(cmd, { stdio: 'ignore' })
+		return true
+	} catch {
+		return false
+	}
+}