chore(brain): ASTRA 성장 자산 동기화 — 기능 인벤토리·growth(약점프로필/학습큐)·일화기억·장기기억·회의록 원문

2026-06-12 16:37:41 +09:00
parent a97fc7be07
commit 89fb05a28a
781 changed files with 138546 additions and 47 deletions
@@ -0,0 +1,204 @@
+---
+id: wiki-2026-0508-scripts
+title: Scripts
+category: 10_Wiki/Topics
+status: verified
+canonical_id: self
+aliases: [npm scripts, package.json scripts, Build Scripts]
+duplicate_of: none
+source_trust_level: A
+confidence_score: 0.9
+verification_status: applied
+tags: [npm, build, automation, package-json]
+raw_sources: []
+last_reinforced: 2026-05-10
+github_commit: pending
+tech_stack:
+  language: TypeScript
+  framework: Node.js + npm
+---
+
+# Scripts
+
+## 매 한 줄
+> **"매 scripts는 package.json 의 entry point 인 명령어 alias"**. `npm run <name>` 으로 실행되며, dev/build/test/lint/deploy 등의 lifecycle automation 을 정의. 2026 기준 npm/pnpm/bun/yarn 호환, 매 monorepo 에서는 turbo/nx 가 orchestration.
+
+## 매 핵심
+
+### 매 lifecycle
+- **pre/post**: `prebuild` → `build` → `postbuild` 자동 실행
+- **special names**: `start`, `test`, `install`, `prepare`
+- **arbitrary**: 매 다른 이름 은 `npm run <name>`
+
+### 매 cross-platform
+- `cross-env`, `rimraf`, `mkdirp` 등으로 OS 차이 흡수
+- 매 modern 대안: zx, execa, tsx-based scripts
+
+### 매 응용
+1. Local dev: `dev`, `build`, `test`, `lint`.
+2. CI: `ci:test`, `ci:build`, `ci:deploy`.
+3. Tooling: `typecheck`, `format`, `analyze`.
+4. Release: `release`, `publish:dry`.
+
+## 💻 패턴
+
+### Modern package.json scripts
+```json
+{
+  "scripts": {
+    "dev": "next dev --turbo",
+    "build": "next build",
+    "start": "next start",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:e2e": "playwright test",
+    "test:coverage": "vitest run --coverage",
+    "format": "biome format --write .",
+    "clean": "rimraf .next dist coverage",
+    "prepare": "husky",
+    "release": "changeset publish"
+  }
+}
+```
+
+### Pre/post hooks
+```json
+{
+  "scripts": {
+    "prebuild": "npm run typecheck && npm run lint",
+    "build": "tsc -p tsconfig.build.json",
+    "postbuild": "node scripts/copy-assets.mjs"
+  }
+}
+```
+
+### Composing with `npm-run-all` or `concurrently`
+```json
+{
+  "scripts": {
+    "dev": "concurrently -n web,api -c blue,green \"npm:dev:web\" \"npm:dev:api\"",
+    "dev:web": "next dev",
+    "dev:api": "tsx watch server/index.ts",
+    "verify": "run-p typecheck lint test"
+  }
+}
+```
+
+### TypeScript script with tsx
+```typescript
+// scripts/seed.ts
+import { db } from "../src/lib/db";
+import { users } from "../src/lib/db/schema";
+
+await db.insert(users).values([
+  { email: "alice@example.com" },
+  { email: "bob@example.com" },
+]);
+console.log("매 seed complete");
+```
+
+```json
+{ "scripts": { "db:seed": "tsx scripts/seed.ts" } }
+```
+
+### zx automation
+```javascript
+#!/usr/bin/env zx
+import "zx/globals";
+
+const branches = (await $`git branch --merged main`).stdout
+  .split("\n")
+  .map((b) => b.trim())
+  .filter((b) => b && !b.startsWith("*") && b !== "main");
+
+for (const b of branches) {
+  await $`git branch -d ${b}`;
+}
+echo`매 deleted ${branches.length} merged branches`;
+```
+
+### Cross-platform env
+```json
+{
+  "scripts": {
+    "build:prod": "cross-env NODE_ENV=production webpack",
+    "test:debug": "cross-env DEBUG=app:* vitest"
+  }
+}
+```
+
+### Monorepo with pnpm + turbo
+```json
+// root package.json
+{
+  "scripts": {
+    "build": "turbo run build",
+    "dev": "turbo run dev --parallel",
+    "test": "turbo run test --filter=...[origin/main]"
+  }
+}
+```
+
+### Bun-native scripts (faster startup)
+```json
+{
+  "scripts": {
+    "dev": "bun --hot src/index.ts",
+    "test": "bun test",
+    "build": "bun build src/index.ts --outdir dist --target node"
+  }
+}
+```
+
+### CI matrix script
+```json
+{
+  "scripts": {
+    "ci:lint": "biome ci .",
+    "ci:typecheck": "tsc --noEmit",
+    "ci:test": "vitest run --coverage --reporter=verbose",
+    "ci:build": "next build",
+    "ci": "run-s ci:lint ci:typecheck ci:test ci:build"
+  }
+}
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| 매 simple alias | npm script directly |
+| 매 multi-step orchestration | npm-run-all / concurrently |
+| Complex shell scripting | zx / bash file |
+| TS logic | tsx / bun + TS file |
+| Monorepo | turbo / nx |
+
+**기본값**: npm scripts + tsx for TS + concurrently for parallel. 매 monorepo 면 turbo.
+
+## 🔗 Graph
+- 부모: [[Node.js]]
+- 변형: [[Task]] · [[Turbo]] · [[Nx]]
+- 응용: [[Husky Git Hooks]]
+- Adjacent: [[tsx]] · [[bun]]
+
+## 🤖 LLM 활용
+**언제**: package.json 의 standard automation, dev/build/test/lint pipeline.
+**언제 X**: 매 100+ lines of bash logic — 매 standalone script file 로 추출.
+
+## ❌ 안티패턴
+- **Inline complex shell**: `&& if [[ ... ]]; then ... fi` in JSON → 매 unreadable. zx / bash file.
+- **No clean script**: 매 stale build artifact debug 어려움. `clean` 필수.
+- **OS-specific commands**: `rm -rf` Windows 실패 → cross-platform 도구.
+- **Hidden side effects in postinstall**: 매 supply-chain risk. 신중.
+- **Duplicate scripts across packages**: 매 monorepo 면 turbo / shared config.
+
+## 🧪 검증 / 중복
+- Verified (npm docs, package.json spec).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — npm scripts full content |