@askewly/design 0.6.2 → 0.6.4

package/dist/index.js

@@ -2,8 +2,8 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { Command } from "commander";
-import { addRecipe, initProject, InjectError } from "./inject.js";
-import { runKickstart, KickstartError } from "./kickstart.js";
+import { addFromRegistry, addRecipe, defaultSrcRoot, initProject, InjectError } from "./inject.js";
+import { aliasStep, detectPathAlias, REGISTRY_BASE, runKickstart, KickstartError } from "./kickstart.js";
 import { DEFAULT_TYPOGRAPHY_THRESHOLD } from "./typography.js";
 import { MASCOT_POSES, renderMascot } from "./mascot.js";
 import { verifyDir } from "./verify.js";
@@ -143,17 +143,71 @@ program
 program
     .command("add")
     .argument("<recipe>", "recipe id, e.g. button")
-    .option("--out <dir>", "output directory for the component file", ".")
+    .option("--out <dir>", "directory for the component file (default: src/components, or . for --excerpt)")
     .option("--tokens <file>", "path to the project's tokens.css", "tokens.css")
-    .option("--force", "overwrite an existing file")
-    .description("inject a recipe's Code excerpt into the project")
-    .action((id, options) => {
+    .option("--registry <baseUrl>", "registry base URL", REGISTRY_BASE)
+    .option("--excerpt", "write only the recipe's Code excerpt (offline; the excerpt is a usage example)")
+    .option("--force", "overwrite existing files")
+    .description("add the published component (registry item + its libs and dependencies) to the project")
+    .action(async (id, options) => {
     const recipe = loadRecipes().find((r) => r.id === id);
+    // 1. 완성본 — 사이트가 공개한 registry 항목 그대로 (F6, 0.6.4)
+    let fallbackReason = null;
+    if (!options.excerpt) {
+        try {
+            const full = await addFromRegistry(id, {
+                registryBase: options.registry,
+                projectDir: process.cwd(),
+                componentDir: options.out ? path.resolve(options.out) : undefined,
+                force: Boolean(options.force),
+                tokensCssPath: path.resolve(options.tokens),
+            });
+            if (full) {
+                console.log(`added the full component from ${full.url}`);
+                for (const file of full.written)
+                    console.log(`wrote ${file}`);
+                for (const file of full.unchanged)
+                    console.log(`unchanged ${file} (already identical)`);
+                for (const file of full.conflicts)
+                    console.log(`⚠ kept ${file} - differs from the registry; not overwritten (use --force to replace)`);
+                const steps = [];
+                const srcRel = path.basename(defaultSrcRoot(process.cwd())) === "src" ? "./src" : ".";
+                const alias = aliasStep(detectPathAlias(process.cwd()), srcRel);
+                if (alias)
+                    steps.push(alias);
+                steps.push(`npm i ${full.npmDeps.join(" ")}`);
+                if (full.missingCssVars.length > 0) {
+                    steps.push(`define the CSS variables it needs (missing in ${options.tokens} — run \`askewly-design init\` first): ${full.missingCssVars.join(", ")}`);
+                }
+                console.log("\nNext steps:");
+                for (const [index, step] of steps.entries())
+                    console.log(`  ${index + 1}. ${step}`);
+                return;
+            }
+            fallbackReason = `no published component for "${id}" in ${options.registry}/r/`;
+        }
+        catch (error) {
+            if (!(error instanceof KickstartError))
+                throw error;
+            fallbackReason = error.message;
+        }
+    }
+    // 2. 폴백 — recipe 의 Code 발췌 (사용 예시라 그대로는 안 돌 수 있다)
     if (!recipe)
-        fail(`unknown recipe "${id}" — try: askewly-design recipes list`);
+        fail(fallbackReason ? `unknown recipe "${id}" (${fallbackReason}) — try: askewly-design recipes list` : `unknown recipe "${id}" — try: askewly-design recipes list`);
+    if (fallbackReason)
+        console.log(`⚠ ${fallbackReason} — writing the recipe's Code excerpt instead. It is a usage example, not the finished component; wire it up yourself.`);
     try {
-        const result = addRecipe(recipe, path.resolve(options.out), Boolean(options.force), path.resolve(options.tokens));
+        const result = addRecipe(recipe, path.resolve(options.out ?? "."), Boolean(options.force), path.resolve(options.tokens));
         console.log(`wrote ${result.file}`);
+        for (const lib of result.libs) {
+            if (lib.status === "written")
+                console.log(`wrote ${lib.file}`);
+            else if (lib.status === "unchanged")
+                console.log(`unchanged ${lib.file} (already identical)`);
+            else
+                console.log(`⚠ kept ${lib.file} - differs from the bundled lib; not overwritten. Diff it by hand if the component misbehaves.`);
+        }
         if (result.missingTokens.length > 0) {
             console.log(`\n⚠ tokens not found in ${options.tokens} — run \`askewly-design init\` first. Required:`);
             for (const token of result.missingTokens)
@@ -443,7 +497,7 @@ siteCmd
     try {
         const target = dir ?? slug;
         const n = await getSite(slug, target);
-        console.log(`${n} files -> ${target}
+        console.log(`${n} files -> ${target}
 ${siteNextStep(target)}`);
     }
     catch (error) {
@@ -452,4 +506,4 @@ ${siteNextStep(target)}`);
         throw error;
     }
 });
-program.parse();
+await program.parseAsync();

package/dist/inject.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
+import { fetchRegistryItem, missingRequiredVars, transplantBlock } from "./kickstart.js";
 export class InjectError extends Error {
 }
 function readBundled(relative) {
@@ -71,12 +72,40 @@ export function extractSectionNotes(recipe, title) {
         .filter((line) => line.trim().startsWith("- "))
         .map((line) => line.trim().slice(2));
 }
+/** kickstart 의 srcRoot 규칙과 같다: 프로젝트에 src/ 가 있으면 그 안, 없으면 프로젝트 루트. */
+export function defaultSrcRoot(projectDir) {
+    return existsSync(path.join(projectDir, "src")) ? path.join(projectDir, "src") : projectDir;
+}
+/**
+ * Writes the published component — the same item `npx shadcn add <url>` would
+ * install: its files, its registry:lib files, and registryDependencies resolved
+ * recursively (bare names from shadcn, URLs from ui.askewly.com). Returns null
+ * when the registry has no item for this id, so the caller can fall back to the
+ * recipe excerpt and say so (F6 — the excerpt alone does not typecheck).
+ */
+export async function addFromRegistry(id, opts) {
+    const registryBase = opts.registryBase.replace(/\/$/, "");
+    const item = await fetchRegistryItem(id, registryBase);
+    if (!item)
+        return null;
+    const result = await transplantBlock(item, opts.projectDir, { keepExisting: !opts.force, componentDir: opts.componentDir });
+    const css = opts.tokensCssPath && existsSync(opts.tokensCssPath) ? readFileSync(opts.tokensCssPath, "utf8") : "";
+    return {
+        url: `${registryBase}/r/${id}.json`,
+        written: result.written,
+        unchanged: result.unchanged,
+        conflicts: result.conflicts,
+        npmDeps: [...result.npmDeps].sort(),
+        requiredCssVars: result.requiredCssVars,
+        missingCssVars: missingRequiredVars(css, result.requiredCssVars),
+    };
+}
 /**
  * Writes the recipe's Code excerpt to <outDir>/<id>.tsx and reports which
  * tokens_used entries are not covered by an existing tokens.css in outDir's
  * project root (heuristic: tokens.css next to outDir or in cwd).
  */
-export function addRecipe(recipe, outDir, force, tokensCssPath) {
+export function addRecipe(recipe, outDir, force, tokensCssPath, srcRoot = defaultSrcRoot(process.cwd())) {
     const snippet = extractCodeSnippet(recipe);
     const file = path.join(outDir, `${recipe.id}.tsx`);
     if (existsSync(file) && !force) {
@@ -84,6 +113,20 @@ export function addRecipe(recipe, outDir, force, tokensCssPath) {
     }
     mkdirSync(outDir, { recursive: true });
     writeFileSync(file, snippet);
+    // 컴포넌트가 import 하는 로컬 lib(`@/lib/...`)도 함께 쓴다. 같은 내용이면 건너뛰고,
+    // 다르면 덮어쓰지 않고 알린다(사용자가 고친 lib 를 조용히 날리지 않는다).
+    const libs = [];
+    for (const lib of recipe.lib_files ?? []) {
+        const dest = path.join(srcRoot, lib.target);
+        if (existsSync(dest)) {
+            const same = readFileSync(dest, "utf8").replace(/\r\n/g, "\n") === lib.content;
+            libs.push({ file: dest, status: same ? "unchanged" : "conflict" });
+            continue;
+        }
+        mkdirSync(path.dirname(dest), { recursive: true });
+        writeFileSync(dest, lib.content);
+        libs.push({ file: dest, status: "written" });
+    }
     let missingTokens = [];
     const tokensUsed = recipe.tokens_used ?? [];
     if (tokensUsed.length > 0) {
@@ -101,6 +144,7 @@ export function addRecipe(recipe, outDir, force, tokensCssPath) {
     }
     return {
         file,
+        libs,
         missingTokens,
         checks: extractSectionNotes(recipe, "Checks"),
         antiPatterns: extractSectionNotes(recipe, "Anti-patterns"),

package/dist/kickstart.js

@@ -7,7 +7,7 @@ import { verifyDir } from "./verify.js";
 const BUILTIN_MODULES = new Set(builtinModules);
 export class KickstartError extends Error {
 }
-const REGISTRY_BASE = "https://ui.askewly.com";
+export const REGISTRY_BASE = "https://ui.askewly.com";
 const SHADCN_BASE = "https://ui.shadcn.com/r/styles/new-york-v4";
 const BRIEF_QUESTIONS = [
     {
@@ -516,21 +516,45 @@ export async function fetchBlock(blockName, registryBase) {
     }
     return block;
 }
-export async function transplantBlock(block, targetDir) {
+/** `add` 용 — 티어를 가리지 않는다. 공개 항목이 없으면(404) null, 그 밖의 실패는 던진다. */
+export async function fetchRegistryItem(name, registryBase) {
+    const url = `${registryBase}/r/${name}.json`;
+    let res;
+    try {
+        res = await fetch(url);
+    }
+    catch (error) {
+        throw new KickstartError(`fetch failed: ${url} — ${error.message}`);
+    }
+    if (res.status === 404)
+        return null;
+    if (!res.ok)
+        throw new KickstartError(`registry fetch ${res.status}: ${url}`);
+    return (await res.json());
+}
+export async function transplantBlock(block, targetDir, opts = {}) {
     const srcRoot = existsSync(path.join(targetDir, "src")) ? path.join(targetDir, "src") : targetDir;
     const written = [];
+    const unchanged = [];
+    const conflicts = [];
     const npmDeps = new Set(["clsx", "tailwind-merge"]);
     const visited = new Set();
     const requiredVars = new Set();
-    function write(file) {
-        const dest = destFor(file, srcRoot);
+    function write(file, top = false) {
+        const dest = top && opts.componentDir && !file.target ? path.join(opts.componentDir, path.basename(file.path)) : destFor(file, srcRoot);
         const content = rewriteImports(file.content);
+        // The file is the authority on what must be installed, written or not.
+        for (const pkg of importedPackages(content))
+            npmDeps.add(pkg);
+        if (opts.keepExisting && existsSync(dest)) {
+            // 사용자가 고친 파일을 조용히 날리지 않는다 — 같으면 건너뛰고 다르면 알린다.
+            const same = readFileSync(dest, "utf8").replace(/\r\n/g, "\n") === content.replace(/\r\n/g, "\n");
+            (same ? unchanged : conflicts).push(dest);
+            return;
+        }
         mkdirSync(path.dirname(dest), { recursive: true });
         writeFileSync(dest, content);
         written.push(dest);
-        // The file we just wrote is the authority on what must be installed.
-        for (const pkg of importedPackages(content))
-            npmDeps.add(pkg);
     }
     async function resolve(item) {
         // Required CSS vars are collected transitively, not just off the top-level
@@ -556,7 +580,7 @@ export async function transplantBlock(block, targetDir) {
     }
     await resolve(block);
     for (const file of block.files ?? [])
-        write(file);
+        write(file, true);
     // cn() — shadcn init would have created it; transplant guarantees it (M18 step-5 friction).
     const utils = path.join(srcRoot, "lib", "utils.ts");
     if (!existsSync(utils)) {
@@ -564,7 +588,7 @@ export async function transplantBlock(block, targetDir) {
         writeFileSync(utils, `import { clsx, type ClassValue } from "clsx"\nimport { twMerge } from "tailwind-merge"\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs))\n}\n`);
         written.push(utils);
     }
-    return { written, npmDeps, requiredCssVars: [...requiredVars] };
+    return { written, unchanged, conflicts, npmDeps, requiredCssVars: [...requiredVars] };
 }
 // ---------------------------------------------------------------------------
 // Orchestrator — brief → DESIGN.md → tokens → transplant → required-var check → verify

package/package.json

@@ -1,50 +1,50 @@
-{
-  "name": "@askewly/design",
-  "version": "0.6.2",
-  "description": "Query, inject, and verify the Askewly Design system (tokens, UI vocabulary, recipes) from your terminal or coding agent.",
-  "license": "MIT",
-  "homepage": "https://ui.askewly.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lumatic2/ui-dictionary.git",
-    "directory": "packages/cli"
-  },
-  "keywords": [
-    "design-system",
-    "design-tokens",
-    "linter",
-    "ui",
-    "coding-agent"
-  ],
-  "type": "module",
-  "bin": {
-    "askewly-design": "./dist/index.js"
-  },
-  "files": [
-    "dist",
-    "data",
-    "README.md",
-    "LICENSE"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "build:data": "node scripts/build-data.mjs",
-    "build": "npm run build:data && tsc",
-    "test": "vitest run",
-    "prepack": "npm run build"
-  },
-  "dependencies": {
-    "commander": "^13.1.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "typescript": "^5.7.0",
-    "vitest": "^3.0.0",
-    "yaml": "^2.6.0"
-  }
-}
+{
+  "name": "@askewly/design",
+  "version": "0.6.4",
+  "description": "Query, inject, and verify the Askewly Design system (tokens, UI vocabulary, recipes) from your terminal or coding agent.",
+  "license": "MIT",
+  "homepage": "https://ui.askewly.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lumatic2/ui-dictionary.git",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "linter",
+    "ui",
+    "coding-agent"
+  ],
+  "type": "module",
+  "bin": {
+    "askewly-design": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "data",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build:data": "node scripts/build-data.mjs",
+    "build": "npm run build:data && tsc",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "yaml": "^2.6.0"
+  }
+}