@1dot5/design-assistant 0.2.1 → 0.3.0

package/README.md

@@ -0,0 +1,98 @@
+# @1dot5/design-assistant
+
+Next.js 16 + React 19 プロジェクト向けに、シニアデザイナー兼フロントエンドエンジニアとしての規約・Skill・ワークフローを一式ばらまくための CLI。
+
+- `AGENTS.md` — エージェント共通の Single Source of Truth
+- `.agent/*.md` — Claude Code 以外のツール（Cursor / Codex / OpenHands 等）から参照するビュー
+- `.claude/skills/**/SKILL.md` — Claude Code 用の自動発火 Skill
+- `.claude/CLAUDE.md` — Claude Code 用のエントリ（`AGENTS.md` と同一内容）
+
+## 使い方
+
+既存プロジェクトの直下で一発で展開する。
+
+```sh
+# 現在のディレクトリに展開
+npx @1dot5/design-assistant
+
+# 別のディレクトリに展開
+npx @1dot5/design-assistant ./path/to/app
+
+# 何が書かれるかだけ確認
+npx @1dot5/design-assistant --dry-run
+
+# 既存ファイルを上書き（更新したいとき）
+npx @1dot5/design-assistant --force
+```
+
+pnpm / yarn / bun でも等価に動く。
+
+```sh
+pnpm dlx @1dot5/design-assistant
+yarn dlx @1dot5/design-assistant
+bunx @1dot5/design-assistant
+```
+
+## 動作
+
+- 既存ファイルがあり内容が同一なら **何もしない**（`unchanged`）。
+- 既存ファイルがあり内容が異なるなら **スキップ**し、末尾に差分一覧を表示する。`--force` で上書き可能。
+- `.agent/*.md` と `.claude/CLAUDE.md` は、リポジトリ上はシンボリックリンクだが、インストール時には **実ファイルとしてコピー**される。これにより npm tarball やクロスプラットフォーム環境で壊れない。
+
+### コマンド
+
+```
+Usage
+  npx @1dot5/design-assistant [dir] [options]
+
+Arguments
+  dir                Target directory (default: ".")
+
+Options
+  -f, --force        Overwrite existing files
+  -n, --dry-run      Show what would be written without writing
+  -h, --help         Show this help
+  -v, --version      Print version
+
+Exit codes
+  0  success (all files written, or already up to date)
+  1  some files were skipped due to conflicts (rerun with --force)
+  2  invalid arguments
+```
+
+## 展開後の構成
+
+```
+<target>/
+├── AGENTS.md
+├── .agent/
+│   ├── components.md
+│   ├── design-to-code.md
+│   ├── design.md
+│   ├── frontend-arch.md
+│   └── review.md
+└── .claude/
+    ├── CLAUDE.md
+    └── skills/
+        ├── component-architect/SKILL.md
+        ├── design-review/SKILL.md
+        ├── design-to-code/SKILL.md
+        ├── frontend-architecture/SKILL.md
+        ├── pencil-design-flow/SKILL.md
+        └── ui-designer/SKILL.md
+```
+
+## 更新
+
+このパッケージが更新されたら、プロジェクト側で再実行すれば差分だけ取り込める。
+
+```sh
+npx @1dot5/design-assistant --dry-run   # まずは差分確認
+npx @1dot5/design-assistant --force     # 納得したら上書き
+```
+
+プロジェクト側で `AGENTS.md` や Skill を **カスタマイズしている場合は `--force` を使わない**。デフォルト動作は安全側で、衝突時はスキップ＋exit 1 を返す。
+
+## ライセンス
+
+MIT

package/bin/cli.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import {
+  access,
+  copyFile,
+  mkdir,
+  readdir,
+  readFile,
+  realpath,
+  stat,
+} from "node:fs/promises";
+import { constants } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const FILE_SOURCES = ["AGENTS.md"];
+const DIR_SOURCES = [".claude/skills"];
+
+// dest path (in target project) -> source path (in this package).
+// Repo uses symlinks for these; tarballs don't preserve symlinks reliably, so
+// the installer synthesizes them by copying from the underlying source.
+export const ALIASES = {
+  ".agent/components.md": ".claude/skills/component-architect/SKILL.md",
+  ".agent/design-to-code.md": ".claude/skills/design-to-code/SKILL.md",
+  ".agent/design.md": ".claude/skills/ui-designer/SKILL.md",
+  ".agent/frontend-arch.md": ".claude/skills/frontend-architecture/SKILL.md",
+  ".agent/review.md": ".claude/skills/design-review/SKILL.md",
+  ".claude/CLAUDE.md": "AGENTS.md",
+};
+
+const HELP = `${pkg.name} v${pkg.version}
+${pkg.description}
+
+Usage
+  npx ${pkg.name} [dir] [options]
+
+Arguments
+  dir                Target directory (default: ".")
+
+Options
+  -f, --force        Overwrite existing files
+  -n, --dry-run      Show what would be written without writing
+  -h, --help         Show this help
+  -v, --version      Print version
+
+Examples
+  npx ${pkg.name}                 Install into the current directory
+  npx ${pkg.name} ./my-app        Install into ./my-app
+  npx ${pkg.name} --dry-run       Preview the file list
+  npx ${pkg.name} --force         Overwrite existing files
+
+Exit codes
+  0  success (all files written, or already up to date)
+  1  some files were skipped due to conflicts (rerun with --force)
+  2  invalid arguments
+`;
+
+function parse() {
+  try {
+    return parseArgs({
+      allowPositionals: true,
+      options: {
+        force: { type: "boolean", short: "f", default: false },
+        "dry-run": { type: "boolean", short: "n", default: false },
+        help: { type: "boolean", short: "h", default: false },
+        version: { type: "boolean", short: "v", default: false },
+      },
+    });
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n\n${HELP}`);
+    process.exit(2);
+  }
+}
+
+async function walk(absRoot, rel = "") {
+  const abs = rel ? join(absRoot, rel) : absRoot;
+  const st = await stat(abs);
+  if (st.isFile()) return [rel];
+  if (!st.isDirectory()) return [];
+  const out = [];
+  for (const entry of await readdir(abs)) {
+    out.push(...(await walk(absRoot, rel ? join(rel, entry) : entry)));
+  }
+  return out;
+}
+
+async function collectOps() {
+  const ops = [];
+  for (const rel of FILE_SOURCES) ops.push({ src: rel, dst: rel });
+  for (const dir of DIR_SOURCES) {
+    const inner = await walk(join(PKG_ROOT, dir));
+    for (const rel of inner) {
+      const full = join(dir, rel);
+      ops.push({ src: full, dst: full });
+    }
+  }
+  for (const [dst, src] of Object.entries(ALIASES)) {
+    ops.push({ src, dst });
+  }
+  return ops;
+}
+
+async function exists(p) {
+  try {
+    await access(p, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function sameContent(a, b) {
+  const [bufA, bufB] = await Promise.all([readFile(a), readFile(b)]);
+  return bufA.equals(bufB);
+}
+
+async function main() {
+  const { values, positionals } = parse();
+
+  if (values.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (values.version) {
+    process.stdout.write(`${pkg.version}\n`);
+    return 0;
+  }
+
+  const target = resolve(process.cwd(), positionals[0] ?? ".");
+  const dryRun = values["dry-run"];
+  const force = values.force;
+
+  const ops = await collectOps();
+
+  const toWrite = [];
+  const toSkip = [];
+  const unchanged = [];
+
+  for (const op of ops) {
+    const srcAbs = join(PKG_ROOT, op.src);
+    const dstAbs = join(target, op.dst);
+    if (!(await exists(dstAbs))) {
+      toWrite.push({ ...op, srcAbs, dstAbs, kind: "create" });
+      continue;
+    }
+    if (await sameContent(srcAbs, dstAbs)) {
+      unchanged.push(op.dst);
+      continue;
+    }
+    if (force) toWrite.push({ ...op, srcAbs, dstAbs, kind: "overwrite" });
+    else toSkip.push(op.dst);
+  }
+
+  process.stdout.write(`target: ${target}\n`);
+
+  if (toSkip.length) {
+    process.stdout.write(
+      `\nskipped ${toSkip.length} existing file(s) (use --force to overwrite):\n`,
+    );
+    for (const rel of toSkip) process.stdout.write(`  - ${rel}\n`);
+  }
+
+  if (unchanged.length) {
+    process.stdout.write(`\nunchanged: ${unchanged.length} file(s)\n`);
+  }
+
+  if (toWrite.length === 0) {
+    process.stdout.write(
+      toSkip.length ? "\nnothing to write.\n" : "\nalready up to date.\n",
+    );
+    return toSkip.length ? 1 : 0;
+  }
+
+  process.stdout.write(
+    `\n${dryRun ? "would write" : "writing"} ${toWrite.length} file(s):\n`,
+  );
+  for (const op of toWrite) {
+    process.stdout.write(`  ${op.kind === "overwrite" ? "*" : "+"} ${op.dst}\n`);
+  }
+
+  if (dryRun) return 0;
+
+  for (const op of toWrite) {
+    await mkdir(dirname(op.dstAbs), { recursive: true });
+    await copyFile(op.srcAbs, op.dstAbs);
+  }
+
+  process.stdout.write(`\ndone.\n`);
+  return toSkip.length ? 1 : 0;
+}
+
+// Only run main() when invoked as a script, not when imported by tests.
+// realpath normalizes /tmp → /private/tmp on macOS so this works via npx too.
+const invokedAs = process.argv[1]
+  ? await realpath(process.argv[1]).catch(() => process.argv[1])
+  : "";
+if (invokedAs === fileURLToPath(import.meta.url)) {
+  try {
+    process.exit((await main()) ?? 0);
+  } catch (err) {
+    process.stderr.write(`error: ${err.stack ?? err.message ?? err}\n`);
+    process.exit(1);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1dot5/design-assistant",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Design assistant agents, skills, and conventions for Next.js 16 + React 19 projects",
   "homepage": "https://github.com/1dot5/da#readme",
   "bugs": {
@@ -12,15 +12,23 @@
   },
   "license": "MIT",
   "type": "module",
+  "bin": {
+    "design-assistant": "./bin/cli.js"
+  },
   "files": [
     "AGENTS.md",
-    ".agent",
-    ".claude/skills"
+    "README.md",
+    ".claude/skills",
+    "bin"
   ],
   "engines": {
     "node": ">=20"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "verify:aliases": "node scripts/verify-aliases.mjs",
+    "smoke": "rm -rf .smoke && node bin/cli.js .smoke && rm -rf .smoke"
   }
 }