create-task-ops 0.1.2 → 0.1.4

package/README.md

@@ -8,36 +8,67 @@
 - 기존 리포에 task-ops 구조 주입
 - `tasks/*.md` 와 Task API 계약을 기본으로 포함
 
-## 모드
-
-- `full`
-  Next.js 앱, 기본 대시보드 페이지, Task API, tasks 문서 포함
-- `api`
-  Next.js 앱, Task API 중심, 최소 페이지 포함
-- `docs`
-  `tasks/`, `CLAUDE.md`, `AGENT.md`, 계약 문서만 포함
-
 ## 사용 예시
 
 ```bash
 node packages/create-task-ops/bin/create-task-ops.js my-project
-node packages/create-task-ops/bin/create-task-ops.js my-project --mode api
-node packages/create-task-ops/bin/create-task-ops.js --init --mode docs
+node packages/create-task-ops/bin/create-task-ops.js create my-project
+node packages/create-task-ops/bin/create-task-ops.js add
+node packages/create-task-ops/bin/create-task-ops.js add --docs-only
 ```
 
 publish 후에는 아래처럼 쓸 수 있게 설계했다.
 
 ```bash
 npx create-task-ops my-project
-npx create-task-ops my-project --mode api
-npx create-task-ops --init --mode docs
+npx create-task-ops create my-project
+npx create-task-ops add
+npx create-task-ops add --docs-only
 ```
 
+## 명령 의미
+
+- `create-task-ops my-project`
+  새 Next.js 기반 task-ops 프로젝트 생성
+- `create-task-ops create my-project`
+  위와 같지만 명시적으로 create를 적는 형태
+- `create-task-ops add`
+  현재 리포에 task docs + Task API 추가
+- `create-task-ops add --docs-only`
+  현재 리포에 문서와 task 파일 규약만 추가
+
+## 내부 생성 타입
+
+- `create`
+  내부적으로 `full` 템플릿을 사용한다.
+- `add`
+  내부적으로 `api` 수신기 파일만 선택적으로 추가한다.
+- `add --docs-only`
+  내부적으로 `docs` 템플릿을 사용한다.
+
+## add가 넣는 파일
+
+`add` 는 기존 리포를 통째로 덮어쓰지 않는다. 기본적으로 아래만 추가한다.
+
+- `tasks/example-task.md`
+- `CLAUDE.md`
+- `AGENT.md`
+- `docs/TASK_API_CONTRACT.md`
+- `docs/DASHBOARD_CONNECTION.md`
+- `app/api/health/route.ts`
+- `app/api/tasks/route.ts`
+- `app/api/tasks/[id]/route.ts`
+- `lib/task-api.ts`
+
+즉 기존 `package.json`, `app/page.tsx`, `app/layout.tsx`, `tsconfig.json` 같은 루트 파일은 건드리지 않는다.
+
 ## 로컬 테스트
 
 ```bash
 npm run create-task-ops -- my-project
-npm run create-task-ops -- --init --mode docs
+npm run create-task-ops -- create my-project
+npm run create-task-ops -- add
+npm run create-task-ops -- add --docs-only
 cd packages/create-task-ops
 npm run smoke:full
 ```

package/bin/create-task-ops.js

@@ -8,24 +8,39 @@ import process from "node:process";
 const args = process.argv.slice(2);
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const templatesRoot = path.join(packageRoot, "templates");
+const addApiFiles = [
+  "app/api/health/route.ts",
+  "app/api/tasks/route.ts",
+  "app/api/tasks/[id]/route.ts",
+  "lib/task-api.ts",
+];
 
 function parseArgs(argv) {
   const options = {
+    command: "create",
     name: null,
     mode: "full",
-    init: false,
+    docsOnly: false,
     force: false,
   };
 
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
+    if (arg === "create") {
+      options.command = "create";
+      continue;
+    }
+    if (arg === "add") {
+      options.command = "add";
+      continue;
+    }
     if (arg === "--mode") {
       options.mode = argv[index + 1] ?? "full";
       index += 1;
       continue;
     }
-    if (arg === "--init") {
-      options.init = true;
+    if (arg === "--docs-only") {
+      options.docsOnly = true;
       continue;
     }
     if (arg === "--force") {
@@ -47,6 +62,14 @@ function ensureMode(mode) {
   }
 }
 
+function printUsage() {
+  console.log("Usage:");
+  console.log("  create-task-ops <project-name>");
+  console.log("  create-task-ops create <project-name>");
+  console.log("  create-task-ops add");
+  console.log("  create-task-ops add --docs-only");
+}
+
 function listFiles(dir, prefix = "") {
   const entries = readdirSync(dir);
   return entries.flatMap((entry) => {
@@ -84,17 +107,45 @@ function copyTemplateTree(sourceDir, targetDir, projectName, force) {
   }
 }
 
+function copySelectedFiles(sourceDir, targetDir, projectName, force, selectedFiles) {
+  mkdirSync(targetDir, { recursive: true });
+
+  for (const relativeFile of selectedFiles) {
+    const sourcePath = path.join(sourceDir, relativeFile);
+    const targetPath = path.join(targetDir, relativeFile);
+    const targetFolder = path.dirname(targetPath);
+    mkdirSync(targetFolder, { recursive: true });
+
+    if (existsSync(targetPath) && !force) {
+      console.error(`Refusing to overwrite existing file: ${targetPath}`);
+      console.error("Use --force if you want to replace scaffolded files.");
+      process.exit(1);
+    }
+
+    const content = readFileSync(sourcePath, "utf8");
+    writeFileSync(targetPath, renderTemplate(content, projectName), "utf8");
+  }
+}
+
 function main() {
   const options = parseArgs(args);
+  if (options.command === "add") {
+    options.mode = options.docsOnly ? "docs" : "api";
+  }
   ensureMode(options.mode);
 
+  if (options.command === "create" && !options.name) {
+    printUsage();
+    process.exit(1);
+  }
+
   const inferredName = options.name ? path.basename(path.resolve(process.cwd(), options.name)) : path.basename(process.cwd());
   const projectName = inferredName || "task-ops-project";
-  const targetDir = options.init
+  const targetDir = options.command === "add"
     ? process.cwd()
     : path.resolve(process.cwd(), options.name ?? projectName);
 
-  if (!options.init && existsSync(targetDir) && readdirSync(targetDir).length > 0 && !options.force) {
+  if (options.command === "create" && existsSync(targetDir) && readdirSync(targetDir).length > 0 && !options.force) {
     console.error(`Target directory is not empty: ${targetDir}`);
     console.error("Use --force if you want to write scaffold files there.");
     process.exit(1);
@@ -106,14 +157,20 @@ function main() {
   const modeDir = path.join(templatesRoot, options.mode);
 
   copyTemplateTree(commonDir, targetDir, projectName, options.force);
-  copyTemplateTree(modeDir, targetDir, projectName, options.force);
+
+  if (options.command === "add" && options.mode === "api") {
+    copySelectedFiles(modeDir, targetDir, projectName, options.force, addApiFiles);
+  } else {
+    copyTemplateTree(modeDir, targetDir, projectName, options.force);
+  }
 
   console.log(`create-task-ops completed`);
   console.log(`target: ${targetDir}`);
+  console.log(`command: ${options.command}`);
   console.log(`mode: ${options.mode}`);
   console.log(`project: ${projectName}`);
   console.log(`next steps:`);
-  console.log(`1. cd ${options.init ? "." : projectName}`);
+  console.log(`1. cd ${options.command === "add" ? "." : projectName}`);
   if (options.mode !== "docs") {
     console.log(`2. npm install`);
     console.log(`3. npm run dev`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-task-ops",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Next.js-first task-ops scaffold generator for task docs and task APIs",
   "license": "MIT",
   "type": "module",
@@ -28,9 +28,9 @@
   "scripts": {
     "pack:dry-run": "npm_config_cache=/tmp/npm-cache npm pack --dry-run",
     "smoke:full": "node ./bin/create-task-ops.js /tmp/create-task-ops-full --mode full --force",
-    "smoke:api": "node ./bin/create-task-ops.js /tmp/create-task-ops-api --mode api --force",
-    "smoke:docs": "node ./bin/create-task-ops.js /tmp/create-task-ops-docs --mode docs --force",
-    "prepublishOnly": "npm run smoke:docs && npm run pack:dry-run"
+    "smoke:add": "PACKAGE_DIR=\"$PWD\"; mkdir -p /tmp/create-task-ops-add && cd /tmp/create-task-ops-add && node \"$PACKAGE_DIR/bin/create-task-ops.js\" add --force",
+    "smoke:docs": "PACKAGE_DIR=\"$PWD\"; mkdir -p /tmp/create-task-ops-docs && cd /tmp/create-task-ops-docs && node \"$PACKAGE_DIR/bin/create-task-ops.js\" add --docs-only --force",
+    "prepublishOnly": "npm run smoke:add && npm run smoke:docs && npm run pack:dry-run"
   },
   "publishConfig": {
     "access": "public"

package/templates/common/docs/DASHBOARD_CONNECTION.md

@@ -0,0 +1,35 @@
+# Dashboard Connection
+
+이 프로젝트를 중앙 task dashboard에 연결하려면 이 리포의 Task API를 외부에서 읽을 수 있어야 한다.
+
+## 제공 엔드포인트
+
+- `GET /api/health`
+- `GET /api/tasks`
+- `GET /api/tasks/:id`
+
+## 로컬 개발 연결 예시
+
+프로젝트를 `3000` 포트에서 띄운 경우, 중앙 대시보드의 `task-sources.json` 에 아래처럼 추가한다.
+
+```json
+{
+  "sources": [
+    {
+      "id": "__PROJECT_NAME__",
+      "label": "__PROJECT_NAME__",
+      "type": "remote",
+      "baseUrl": "http://127.0.0.1:3000",
+      "enabled": true,
+      "timeoutMs": 3000
+    }
+  ]
+}
+```
+
+## 체크리스트
+
+1. `tasks/*.md` 가 최신 상태인가
+2. `/api/tasks` 응답이 정상인가
+3. source `id` 와 `label` 이 명확한가
+4. 필요하면 API key 또는 reverse proxy 를 설정했는가