@konce-pt/ui 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 konce.pt
+
+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

@@ -0,0 +1,32 @@
+# @konce-pt/ui
+
+CLI Koncept UI — instaluje **bloki** (gotowe fragmenty UI) do projektu Angular w modelu
+copy-paste. Po instalacji blok jest Twoim kodem.
+
+```bash
+npx @konce-pt/ui init
+npx @konce-pt/ui add nip-lookup-field
+```
+
+## Komendy
+
+| Komenda | Opis |
+|---|---|
+| `init` | Tworzy `konce.json` (`--registry --blocks-dir --alias --prefix --theme --force`) |
+| `add <nazwa...>` | Instaluje blok(i) + zależności registry (`--overwrite --dry-run --path --registry`) |
+| `list [--category=…]` | Lista dostępnych bloków |
+
+## Jak działa `add`
+
+1. Rozwiązuje zależności registry rekurencyjnie (wykrywa cykle).
+2. Sprawdza zależności npm — brak: ostrzega, za niska wersja: przerywa.
+3. Przepisuje `@/` → `alias`, selektory `kpt-` → `prefix` (tokeny `--kpt-*` zostają nietknięte).
+4. Konflikt pliku: identyczny pomija, różny zapisuje jako `.new` (lub `--overwrite`).
+5. Zapisuje dopiero po pobraniu wszystkich plików; odnotowuje `installedBlocks`.
+6. Wypisuje: dodane pliki, przykład użycia, porty do podpięcia, uwagi.
+
+`--dry-run` przechodzi całą ścieżkę bez zapisu — idealne dla agentów AI do podglądu skutków.
+
+## Licencja
+
+MIT © konce.pt

package/dist/commands/add.js

@@ -0,0 +1,193 @@
+import path from 'node:path';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { requireConfig, writeConfig } from "../config.js";
+import { loadIndex, loadBlockMeta, loadBlockFile } from "../registry.js";
+import { flag, hasFlag, log, UserError } from "../util.js";
+export async function addCommand(args) {
+    const requested = args.positionals;
+    if (requested.length === 0)
+        throw new UserError('Podaj nazwę bloku: add <nazwa...>');
+    const { path: configPath, config } = requireConfig(process.cwd());
+    const projectRoot = path.dirname(configPath);
+    const base = flag(args, 'registry') ?? config.registry;
+    const overwrite = hasFlag(args, 'overwrite');
+    const dryRun = hasFlag(args, 'dry-run');
+    const targetDirRel = flag(args, 'path') ?? config.blocksDir;
+    const index = await loadIndex(base);
+    // 1) Rozwiąż zależności registry rekurencyjnie (kolejność zależnościowa, wykryj cykle).
+    const order = [];
+    const done = new Set();
+    const stack = new Set();
+    const visit = (name) => {
+        if (done.has(name))
+            return;
+        if (stack.has(name))
+            throw new UserError(`Cykl zależności registry wokół bloku "${name}".`);
+        const entry = index.blocks.find((b) => b.name === name);
+        if (!entry)
+            throw new UserError(unknownBlockMessage(name, index));
+        stack.add(name);
+        for (const dep of entry.registryDependencies)
+            visit(dep);
+        stack.delete(name);
+        done.add(name);
+        order.push(name);
+    };
+    for (const name of requested)
+        visit(name);
+    // 2) Pomiń już zainstalowane (chyba że --overwrite).
+    const toInstall = order.filter((name) => overwrite || !config.installedBlocks[name]);
+    const skippedInstalled = order.filter((name) => !overwrite && config.installedBlocks[name]);
+    for (const name of skippedInstalled)
+        log.step(`${name} — już zainstalowany (pomijam; --overwrite by nadpisać)`);
+    if (toInstall.length === 0) {
+        log.info('Nic do zrobienia.');
+        return;
+    }
+    // 3) Wczytaj definicje, sprawdź zależności npm.
+    const metas = new Map();
+    for (const name of toInstall)
+        metas.set(name, await loadBlockMeta(base, name));
+    checkNpmDependencies(metas, projectRoot);
+    // 4) Pobierz WSZYSTKIE pliki i zaplanuj zapis (instalacja atomowa — nic nie zapisujemy wcześniej).
+    const plan = [];
+    for (const name of toInstall) {
+        const meta = metas.get(name);
+        for (const file of meta.files) {
+            const raw = await loadBlockFile(base, name, file.path);
+            const content = rewriteImports(raw, config);
+            const absolute = path.resolve(projectRoot, targetDirRel, name, file.path);
+            plan.push(planWrite(name, absolute, content, projectRoot, overwrite));
+        }
+    }
+    // 5) Zapis (albo raport dry-run).
+    if (dryRun) {
+        log.info('— dry-run: żadnych zapisów —');
+        for (const p of plan)
+            log.step(`${labelFor(p.action)}  ${p.target}`);
+    }
+    else {
+        for (const p of plan) {
+            if (p.action === 'skip-identical') {
+                log.step(`bez zmian  ${p.target}`);
+                continue;
+            }
+            const dest = p.action === 'conflict-new' ? `${p.absolute}.new` : p.absolute;
+            mkdirSync(path.dirname(dest), { recursive: true });
+            writeFileSync(dest, p.content);
+            log.step(`${labelFor(p.action)}  ${path.relative(projectRoot, dest)}`);
+        }
+        const now = new Date().toISOString().slice(0, 10);
+        for (const name of toInstall) {
+            config.installedBlocks[name] = { version: index.libraryVersion, installedAt: now };
+        }
+        writeConfig(configPath, config);
+    }
+    printSummary(toInstall, metas, dryRun);
+}
+// — pomocnicze —
+function planWrite(block, absolute, content, projectRoot, overwrite) {
+    const target = path.relative(projectRoot, absolute);
+    if (!existsSync(absolute))
+        return { block, target, absolute, content, action: 'write' };
+    const current = readFileSync(absolute, 'utf8');
+    if (current === content)
+        return { block, target, absolute, content, action: 'skip-identical' };
+    if (overwrite)
+        return { block, target, absolute, content, action: 'overwrite' };
+    return { block, target, absolute, content, action: 'conflict-new' };
+}
+function labelFor(action) {
+    switch (action) {
+        case 'write': return 'nowy     ';
+        case 'overwrite': return 'nadpisano';
+        case 'conflict-new': return 'konflikt→.new';
+        case 'skip-identical': return 'bez zmian';
+    }
+}
+/** Przepisuje placeholdery: `@/` → alias, selektory `kpt-` → prefix (nie rusza `--kpt-`). */
+function rewriteImports(content, config) {
+    let out = content.replaceAll('@/', `${config.alias}/`);
+    if (config.prefix !== 'kpt') {
+        out = out.replace(/(?<![-\w])kpt-/g, `${config.prefix}-`);
+    }
+    return out;
+}
+function checkNpmDependencies(metas, projectRoot) {
+    const pkgPath = path.join(projectRoot, 'package.json');
+    const installed = {};
+    if (existsSync(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        Object.assign(installed, pkg.dependencies ?? {}, pkg.devDependencies ?? {});
+    }
+    const missing = new Set();
+    for (const meta of metas.values()) {
+        for (const [name, range] of Object.entries(meta.dependencies?.npm ?? {})) {
+            const have = installed[name];
+            if (!have) {
+                missing.add(`${name}@${range}`);
+                continue;
+            }
+            // Specyfikatory bez konkretnej wersji (workspace:*, *, latest, git/file:) — nie oceniamy.
+            if (!/\d/.test(have))
+                continue;
+            if (belowMinimum(have, range)) {
+                throw new UserError(`Zależność ${name} jest w wersji ${have}, blok wymaga ${range}. ` +
+                    `Zaktualizuj ją samodzielnie i uruchom ponownie.`);
+            }
+        }
+    }
+    if (missing.size > 0) {
+        log.warn(`Brakujące zależności npm — zainstaluj je: ${[...missing].join(' ')}`);
+    }
+}
+function toTuple(version) {
+    const [maj = 0, min = 0, patch = 0] = version.replace(/^[^\d]*/, '').split('.').map((n) => parseInt(n, 10) || 0);
+    return [maj, min, patch];
+}
+/** Prosty test: czy `have` jest poniżej minimum z zakresu (`^`, `~`, `>=`). */
+function belowMinimum(have, range) {
+    const [hM, hm, hp] = toTuple(have);
+    const [rM, rm, rp] = toTuple(range);
+    if (hM !== rM)
+        return hM < rM;
+    if (hm !== rm)
+        return hm < rm;
+    return hp < rp;
+}
+function printSummary(installed, metas, dryRun) {
+    log.info(`\n${dryRun ? 'Zainstalowałbym' : 'Zainstalowano'}: ${installed.join(', ')}`);
+    for (const name of installed) {
+        const meta = metas.get(name);
+        if (meta.usage) {
+            log.info(`\n${name}:`);
+            log.step(meta.usage.replace(/\n/g, '\n  '));
+        }
+        const ports = meta.api?.ports ?? [];
+        for (const port of ports) {
+            log.warn(`port do podpięcia: ${port.token} — ${port.signature}${port.stubProvided ? ' (stub w komplecie)' : ''}`);
+        }
+        if (meta.notes)
+            log.step(`uwaga: ${meta.notes}`);
+    }
+}
+function unknownBlockMessage(name, index) {
+    const nearest = index.blocks
+        .map((b) => ({ name: b.name, d: levenshtein(name, b.name) }))
+        .sort((a, b) => a.d - b.d)[0];
+    const hint = nearest && nearest.d <= 3 ? ` Czy chodziło o "${nearest.name}"?` : '';
+    return `Nie znam bloku "${name}".${hint} Zobacz: npx @konce-pt/ui list`;
+}
+function levenshtein(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, (_, i) => i);
+    for (let j = 1; j <= b.length; j++) {
+        let prev = dp[0];
+        dp[0] = j;
+        for (let i = 1; i <= a.length; i++) {
+            const tmp = dp[i];
+            dp[i] = Math.min(dp[i] + 1, dp[i - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = tmp;
+        }
+    }
+    return dp[a.length];
+}

package/dist/commands/init.js

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { CONFIG_FILE, DEFAULT_CONFIG, writeConfig } from "../config.js";
+import { flag, hasFlag, log, UserError } from "../util.js";
+export function initCommand(args) {
+    const cwd = process.cwd();
+    const configPath = path.join(cwd, CONFIG_FILE);
+    if (existsSync(configPath) && !hasFlag(args, 'force')) {
+        throw new UserError(`${CONFIG_FILE} już istnieje. Użyj --force, aby nadpisać.`);
+    }
+    const config = {
+        ...DEFAULT_CONFIG,
+        registry: flag(args, 'registry') ?? DEFAULT_CONFIG.registry,
+        blocksDir: flag(args, 'blocks-dir') ?? DEFAULT_CONFIG.blocksDir,
+        alias: flag(args, 'alias') ?? DEFAULT_CONFIG.alias,
+        prefix: flag(args, 'prefix') ?? DEFAULT_CONFIG.prefix,
+        theme: flag(args, 'theme') ?? DEFAULT_CONFIG.theme,
+        installedBlocks: {},
+    };
+    writeConfig(configPath, config);
+    log.ok(`Utworzono ${CONFIG_FILE}`);
+    log.step(`registry:  ${config.registry}`);
+    log.step(`blocksDir: ${config.blocksDir}`);
+    log.step(`alias:     ${config.alias}`);
+    log.step(`prefix:    ${config.prefix}`);
+    log.info('\nDodaj blok: npx @konce-pt/ui add <nazwa>');
+}

package/dist/commands/list.js

@@ -0,0 +1,30 @@
+import { DEFAULT_CONFIG, findConfigPath, readConfig } from "../config.js";
+import { loadIndex } from "../registry.js";
+import { flag, log } from "../util.js";
+/** Baza registry: flaga --registry > konce.json > domyślna. */
+function resolveRegistry(args) {
+    const explicit = flag(args, 'registry');
+    if (explicit)
+        return explicit;
+    const configPath = findConfigPath(process.cwd());
+    if (configPath)
+        return readConfig(configPath).registry;
+    return DEFAULT_CONFIG.registry;
+}
+export async function listCommand(args) {
+    const base = resolveRegistry(args);
+    const category = flag(args, 'category');
+    const index = await loadIndex(base);
+    const blocks = category ? index.blocks.filter((b) => b.category === category) : index.blocks;
+    if (blocks.length === 0) {
+        log.warn(category ? `Brak bloków w kategorii "${category}".` : 'Registry nie zawiera bloków.');
+        return;
+    }
+    log.info(`Bloki @konce-pt (biblioteka ${index.libraryVersion}):\n`);
+    const width = Math.max(...blocks.map((b) => b.name.length));
+    for (const b of blocks) {
+        log.info(`  ${b.name.padEnd(width)}  ${b.title}  [${b.category}]`);
+        log.info(`  ${' '.repeat(width)}  ${b.description}`);
+    }
+    log.info('\nZainstaluj: npx @konce-pt/ui add <nazwa>');
+}

package/dist/config.js

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { UserError } from "./util.js";
+export const CONFIG_FILE = 'konce.json';
+export const DEFAULT_CONFIG = {
+    $schema: 'https://ui.konce.pt/cli/konce-config-schema.json',
+    registry: 'https://ui.konce.pt/cli',
+    blocksDir: 'src/app/shared/blocks',
+    alias: '@shared/blocks',
+    prefix: 'kpt',
+};
+/** Szuka konce.json w górę drzewa od `start`. Zwraca ścieżkę lub null. */
+export function findConfigPath(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        const candidate = path.join(dir, CONFIG_FILE);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+export function readConfig(configPath) {
+    const cfg = JSON.parse(readFileSync(configPath, 'utf8'));
+    cfg.installedBlocks ??= {};
+    return cfg;
+}
+export function writeConfig(configPath, cfg) {
+    writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n');
+}
+/** Wczytuje konfigurację albo przerywa z podpowiedzią o `init`. */
+export function requireConfig(cwd) {
+    const configPath = findConfigPath(cwd);
+    if (!configPath) {
+        throw new UserError(`Brak ${CONFIG_FILE}. Uruchom najpierw: npx @konce-pt/ui init`);
+    }
+    return { path: configPath, config: readConfig(configPath) };
+}

package/dist/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { parseArgs, log, UserError } from "./util.js";
+import { initCommand } from "./commands/init.js";
+import { listCommand } from "./commands/list.js";
+import { addCommand } from "./commands/add.js";
+const HELP = `Koncept UI — CLI bloków.
+
+Użycie:
+  npx @konce-pt/ui <komenda> [opcje]
+
+Komendy:
+  init                     utwórz konce.json (--registry --blocks-dir --alias --prefix --theme --force)
+  add <nazwa...>           zainstaluj blok(i) + zależności (--overwrite --dry-run --path --registry)
+  list [--category=...]    pokaż dostępne bloki (--registry)
+
+Kody wyjścia: 0 ok, 1 błąd.`;
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    const args = parseArgs(rest);
+    switch (command) {
+        case 'init':
+            initCommand(args);
+            break;
+        case 'add':
+            await addCommand(args);
+            break;
+        case 'list':
+            await listCommand(args);
+            break;
+        case undefined:
+        case '--help':
+        case '-h':
+        case 'help':
+            log.info(HELP);
+            break;
+        default:
+            throw new UserError(`Nieznana komenda "${command}". Zobacz: npx @konce-pt/ui --help`);
+    }
+}
+main().catch((err) => {
+    if (err instanceof UserError)
+        log.error(err.message);
+    else
+        log.error(err?.stack ?? String(err));
+    process.exitCode = 1;
+});

package/dist/registry.js

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { UserError } from "./util.js";
+const isHttp = (base) => /^https?:\/\//.test(base);
+async function fetchText(base, relPath) {
+    if (isHttp(base)) {
+        const url = `${base.replace(/\/$/, '')}/${relPath}`;
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new UserError(`Nie udało się pobrać ${url} (HTTP ${res.status}).`);
+        return res.text();
+    }
+    const file = path.resolve(base, relPath);
+    if (!existsSync(file))
+        throw new UserError(`Brak pliku w registry: ${file}`);
+    return readFileSync(file, 'utf8');
+}
+export async function loadIndex(base) {
+    return JSON.parse(await fetchText(base, 'index.json'));
+}
+export async function loadBlockMeta(base, name) {
+    return JSON.parse(await fetchText(base, `blocks/${name}.json`));
+}
+export async function loadBlockFile(base, name, filePath) {
+    return fetchText(base, `blocks/${name}/${filePath}`);
+}

package/dist/util.js

@@ -0,0 +1,35 @@
+// Drobne narzędzia CLI: parsowanie flag i logowanie. Zero zależności.
+export function parseArgs(argv) {
+    const positionals = [];
+    const flags = new Map();
+    for (const arg of argv) {
+        if (arg.startsWith('--')) {
+            const eq = arg.indexOf('=');
+            if (eq === -1)
+                flags.set(arg.slice(2), true);
+            else
+                flags.set(arg.slice(2, eq), arg.slice(eq + 1));
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    return { positionals, flags };
+}
+export function flag(args, name) {
+    const value = args.flags.get(name);
+    return typeof value === 'string' ? value : undefined;
+}
+export function hasFlag(args, name) {
+    return args.flags.has(name);
+}
+export const log = {
+    info: (msg) => console.log(msg),
+    step: (msg) => console.log(`  ${msg}`),
+    ok: (msg) => console.log(`✓ ${msg}`),
+    warn: (msg) => console.warn(`! ${msg}`),
+    error: (msg) => console.error(`✗ ${msg}`),
+};
+/** Błąd, którego komunikat wystarczy pokazać userowi (bez stack trace). */
+export class UserError extends Error {
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@konce-pt/ui",
+  "version": "0.2.0",
+  "description": "CLI Koncept UI — instaluje bloki (copy-paste) do projektu Angular: init, add, list.",
+  "license": "MIT",
+  "author": "konce.pt",
+  "homepage": "https://gitlab.com/konce-pt/koncept-ui#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/konce-pt/koncept-ui.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/konce-pt/koncept-ui/-/issues"
+  },
+  "keywords": [
+    "angular",
+    "cli",
+    "blocks",
+    "registry",
+    "koncept-ui"
+  ],
+  "type": "module",
+  "bin": {
+    "konce": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "typescript": "~6.0.3"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "outputs": [
+          "{projectRoot}/dist"
+        ],
+        "cache": true
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json --noCheck",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  }
+}