@askewly/design 0.6.3 → 0.7.0

package/dist/data.js

@@ -1,14 +1,14 @@
-// M110 앞단 — 레포 자산 조회 통합 (`data recall`).
+// M110 앞단 — 레포 자산 조회 통합. 정식 이름 `find`, `data recall` 은 영구 별칭(cs724).
 // design-intake.md §5단계와 askewly-design SKILL §2.7 이 약속해 온 `askewly data recall`
 // 이 유령 명령이었다(이 기기 어디에도 `data` 커맨드가 없었다) — 그 약속을 실재하게 만든다.
 //
 // 번들된 두 축(terms · recipes) + knowledge 축을 한 번에 훑는다. methodology/ 는
 // build-data.mjs 가 애초에 번들하지 않으므로(knowledge/*.md 만 읽는다) 여기서도 다루지
 // 않는다 — 새 데이터 로더를 만들지 않고 기존 load.ts 만 재사용한다는 이 step 의 원칙.
-// methodology 를 포함한 5축 통합 회수가 필요하면 `python ~/projects/second-brain/bin/data.py recall`
-// 로 보완한다(design-intake.md 가 그 경계를 함께 적는다).
+// 여러 축을 넓게 찾는 일은 `askda recall` 소관이다(design-intake.md 가 그 경계를 함께 적는다).
 import { loadKnowledge, loadRecipes, loadTerms, searchKnowledge, searchTerms, } from "./load.js";
-export const RECALL_AXES = ["terms", "recipes", "knowledge"];
+import { assetUrl, loadAssets, searchAssets } from "./assets.js";
+export const RECALL_AXES = ["terms", "recipes", "assets", "knowledge"];
 function summarize(text, max = 120) {
     if (!text)
         return "";
@@ -46,6 +46,7 @@ function termHit(term) {
         id: term.id,
         path: `docs/ui-vocabulary/terms.yml#${term.id}`,
         summary: summarize(term.one_liner ?? term.en?.name ?? term.id),
+        next: `terms show ${term.id}`,
     };
 }
 function recipeHit(recipe) {
@@ -54,35 +55,53 @@ function recipeHit(recipe) {
         id: recipe.id,
         path: recipe.source_path,
         summary: summarize(`${recipe.name ? `${recipe.name} (${recipe.pattern_group ?? "-"})` : recipe.id}${recipe.status ? ` [${recipe.status}]` : ""}`),
+        next: `recipes show ${recipe.id}`,
         status: recipe.status,
     };
 }
+function assetHit(asset) {
+    return {
+        axis: "assets",
+        id: asset.id,
+        path: assetUrl(asset),
+        summary: summarize(`${asset.definition} [${asset.install ? "installable" : "recipe only"}]`),
+        next: `assets show ${asset.id}`,
+    };
+}
 function knowledgeHit(doc) {
     return {
         axis: "knowledge",
         id: doc.id,
         path: doc.source_path,
         summary: summarize(doc.description),
+        next: `knowledge show ${doc.id}`,
     };
 }
 /**
- * Search terms + recipes + knowledge in one pass and return path + one-line
+ * Search terms + recipes + assets + knowledge in one pass and return path + one-line
  * summary per hit. This is an index, not the source text — the caller must
  * still open `path` and read the body before judging.
  */
 export function recall(query, limit) {
     const terms = searchTerms(loadTerms(), query).map(termHit);
     const recipes = searchRecipes(loadRecipes(), query).map(recipeHit);
+    // Most assets share an id with a recipe; keep one row so duplicates don't eat the --limit window.
+    const recipeIds = new Set(recipes.map((hit) => hit.id));
+    const assets = searchAssets(loadAssets(), query)
+        .filter((asset) => !recipeIds.has(asset.id))
+        .map(assetHit);
     const knowledge = searchKnowledge(loadKnowledge(), query).map(knowledgeHit);
     // Interleave by axis (round-robin) so a query that happens to match many
     // terms doesn't crowd recipes/knowledge out of a small --limit window.
     const merged = [];
-    const maxLen = Math.max(terms.length, recipes.length, knowledge.length);
+    const maxLen = Math.max(terms.length, recipes.length, assets.length, knowledge.length);
     for (let i = 0; i < maxLen; i++) {
         if (terms[i])
             merged.push(terms[i]);
         if (recipes[i])
             merged.push(recipes[i]);
+        if (assets[i])
+            merged.push(assets[i]);
         if (knowledge[i])
             merged.push(knowledge[i]);
     }

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";
@@ -11,10 +11,13 @@ import { loadKnowledge, loadRecipes, loadTerms, loadTokens, loadTokensCss, searc
 import { recall, RECALL_AXES } from "./data.js";
 import { assetUrl, buildPrompt, loadAssets, searchAssets, suggestAssets } from "./assets.js";
 import { getSite, listSites, siteNextStep, SiteError } from "./site.js";
+import { localRepo, LocalToolError, siteFind, siteResolve } from "./local.js";
 const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+// Set only by the local `askde` shim; npm and npx users never see the repo-only commands.
+const repo = localRepo();
 const program = new Command();
 program
-    .name("askewly-design")
+    .name(repo ? "askde" : "askewly-design")
     .description("Query the Askewly Design system: UI vocabulary terms, design tokens, and component recipes.")
     .version(pkg.version);
 function fail(message) {
@@ -143,16 +146,62 @@ 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")
@@ -342,37 +391,40 @@ program
     const color = options.color && Boolean(process.stdout.isTTY);
     console.log(renderMascot(pose, { color }));
 });
-const data = program
-    .command("data")
-    .description("query bundled repo assets across axes (terms, recipes, knowledge) in one pass");
-data
-    .command("recall")
-    .argument("<query>", "text to match across terms / recipes / knowledge")
-    .option("--limit <n>", "max results", "5")
-    .option("--json", "machine-readable output")
-    .description("search terms + recipes + knowledge in one pass — an index of paths, not the source text")
-    .action((query, options) => {
-    const limit = Number(options.limit) || 5;
-    const hits = recall(query, limit);
-    if (options.json) {
-        console.log(JSON.stringify({
-            note: "index only — read `path` before judging",
-            axes: RECALL_AXES,
-            query,
-            hits,
-        }, null, 2));
-        return;
-    }
-    console.log("색인이지 본문이 아니다 — 후보 경로를 받은 뒤 판단은 본문을 읽고 한다.");
-    if (hits.length === 0) {
-        console.log(`no matches for "${query}" across axes: ${RECALL_AXES.join(", ")} (methodology/ is not bundled here — try: python ~/projects/second-brain/bin/data.py recall "${query}")`);
-        return;
-    }
-    for (const hit of hits) {
-        console.log(`[${hit.axis}] ${hit.id}  —  ${hit.path}`);
-        console.log(`    ${hit.summary}`);
-    }
-});
+function addFindCommand(parent, name) {
+    parent
+        .command(name)
+        .argument("<query>", "text to match across terms / recipes / assets / knowledge")
+        .option("--limit <n>", "max results", "5")
+        .option("--json", "machine-readable output")
+        .description("search terms + recipes + assets + knowledge in one pass — an index of paths, not the source text")
+        .action((query, options) => {
+        const limit = Number(options.limit) || 5;
+        const hits = recall(query, limit);
+        if (options.json) {
+            console.log(JSON.stringify({
+                note: "index only — read `path` before judging",
+                axes: RECALL_AXES,
+                query,
+                hits,
+            }, null, 2));
+            return;
+        }
+        console.log("색인이지 본문이 아니다 — 후보 경로를 받은 뒤 판단은 본문을 읽고 한다.");
+        if (hits.length === 0) {
+            console.log(`no matches for "${query}" across axes: ${RECALL_AXES.join(", ")} (methodology/ is not bundled here)`);
+            return;
+        }
+        for (const hit of hits) {
+            console.log(`[${hit.axis}] ${hit.id}  —  ${hit.path}`);
+            console.log(`    ${hit.summary}`);
+            console.log(`    next: ${hit.next}`);
+        }
+    });
+}
+addFindCommand(program, "find");
+// Permanent alias: 0.5.1+ users and published docs call `data recall`.
+addFindCommand(program.command("data").description("alias of `find`, kept for existing callers"), "recall");
 // step-11 (M141): 자산별 md(공개 URL https://ui.askewly.com/llms/assets/<id>.md) 를 번들에서 오프라인으로 읽는다.
 const assetsCmd = program.command("assets").description("registry + recipe assets (one md per asset: definition, usage rules, install command)");
 assetsCmd
@@ -460,4 +512,40 @@ ${siteNextStep(target)}`);
         throw error;
     }
 });
-program.parse();
+if (repo) {
+    siteCmd
+        .command("find")
+        .argument("<query>", "element or site, e.g. menu")
+        .option("--limit <n>", "max results", "5")
+        .description("local: search approved recreated-site modules in this repo")
+        .action((query, options) => {
+        const limit = Number(options.limit);
+        if (!Number.isInteger(limit) || limit < 1)
+            fail("--limit must be a positive integer");
+        try {
+            process.exitCode = siteFind(repo, query, limit);
+        }
+        catch (error) {
+            if (error instanceof LocalToolError)
+                fail(error.message);
+            throw error;
+        }
+    });
+    siteCmd
+        .command("resolve")
+        .argument("<reference>", "copied site pointer or URL")
+        .option("--file <path>", "save this manifest file under tmp/site-references after verifying its hash")
+        .option("--local", "read the same revision from the local snapshot")
+        .description("local: verify a copied site pointer and optionally fetch one pinned source file")
+        .action((reference, options) => {
+        try {
+            process.exitCode = siteResolve(repo, reference, options);
+        }
+        catch (error) {
+            if (error instanceof LocalToolError)
+                fail(error.message);
+            throw error;
+        }
+    });
+}
+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) {
@@ -75,6 +76,30 @@ export function extractSectionNotes(recipe, title) {
 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

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/dist/local.js

@@ -0,0 +1,36 @@
+// Repo-only commands for the local `askde` shim (cs724). They run the existing scripts, so the
+// repo keeps one source of truth, and they never appear for npm users.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+export class LocalToolError extends Error {
+}
+export function localRepo() {
+    return process.env.ASKDE_REPO?.trim() || null;
+}
+function runRepoTool(repo, command, script, args) {
+    const file = path.join(repo, script);
+    if (!existsSync(file))
+        throw new LocalToolError(`${script} not found under ASKDE_REPO=${repo}`);
+    const result = spawnSync(command, [file, ...args], {
+        cwd: repo,
+        stdio: "inherit",
+        env: { ...process.env, PYTHONUTF8: "1" },
+    });
+    if (result.error)
+        throw new LocalToolError(`could not run ${command}: ${result.error.message}`);
+    return result.status ?? 1;
+}
+export function siteFind(repo, query, limit) {
+    const python = process.platform === "win32" ? "python" : "python3";
+    // `--` keeps a query like "--approve" from reaching catalog.py's write options.
+    return runRepoTool(repo, python, "scripts/recreate/catalog.py", ["--limit", String(limit), "--", query]);
+}
+export function siteResolve(repo, reference, options) {
+    const args = [reference];
+    if (options.local)
+        args.push("--local");
+    if (options.file)
+        args.push("--file", options.file);
+    return runRepoTool(repo, process.execPath, "scripts/recreate/resolve-site-reference.mjs", args);
+}

package/dist/mascot.js

@@ -4,34 +4,34 @@
 // 사용 규칙(정본 §3): 라벤더 #B298DC 단색 고정 · 등폭 전제 · 기계 소비 출력 금지.
 export const MASCOT_POSES = ["lying", "standing", "sleepy", "mini"];
 const ART = {
-    lying: `         ▄██▄   ▄██▄
-         █ ██   █ ██
-       ▄██████████████████▄
-█▄    █████████████████████
- ▀█▄  ████  ████  █████████
-  ▀██▄████  ████  █████████
-      ▀███████████████████▀
+    lying: `         ▄██▄   ▄██▄
+         █ ██   █ ██
+       ▄██████████████████▄
+█▄    █████████████████████
+ ▀█▄  ████  ████  █████████
+  ▀██▄████  ████  █████████
+      ▀███████████████████▀
         ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀`,
-    standing: `    ▄██▄   ▄██▄
-    █ ██   █ ██
-  ▄██████████████▄
-  ███  ████  █████
-  ███  ████  █████
-  ████████████████
-  ████████████████
-  ▀████▀▀▀████▀▀██
+    standing: `    ▄██▄   ▄██▄
+    █ ██   █ ██
+  ▄██████████████▄
+  ███  ████  █████
+  ███  ████  █████
+  ████████████████
+  ████████████████
+  ▀████▀▀▀████▀▀██
    ████   ████  ▀███▄▄▄`,
-    sleepy: `         ▄██▄   ▄██▄
-         █ ██   █ ██
-       ▄██████████████████▄
-█▄    █████████████████████
- ▀█▄  █████████████████████
-  ▀██▄███    ██    ████████
-      ▀███████████████████▀
+    sleepy: `         ▄██▄   ▄██▄
+         █ ██   █ ██
+       ▄██████████████████▄
+█▄    █████████████████████
+ ▀█▄  █████████████████████
+  ▀██▄███    ██    ████████
+      ▀███████████████████▀
         ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀`,
-    mini: `  ▄██▄▄▄▄██▄
-  ██████████
-  ██  ██  ██
+    mini: `  ▄██▄▄▄▄██▄
+  ██████████
+  ██  ██  ██
   ▀████████▀`,
 };
 /** askewly.lavender #B298DC — ANSI 24-bit. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askewly/design",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "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",