create-task-ops 0.1.6 → 0.1.8

package/README.md

@@ -14,6 +14,7 @@
 node packages/create-task-ops/bin/create-task-ops.js my-project
 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 --target apps/server
 node packages/create-task-ops/bin/create-task-ops.js add --docs-only
 ```
 
@@ -23,6 +24,7 @@ publish 후에는 아래처럼 쓸 수 있게 설계했다.
 npx create-task-ops my-project
 npx create-task-ops create my-project
 npx create-task-ops add
+npx create-task-ops add --target apps/server
 npx create-task-ops add --docs-only
 ```
 
@@ -34,6 +36,8 @@ npx create-task-ops add --docs-only
   위와 같지만 명시적으로 create를 적는 형태
 - `create-task-ops add`
   현재 리포에 task docs + OrbitOps API 추가
+- `create-task-ops add --target apps/server`
+  문서와 tasks는 리포 루트에 두고, OrbitOps receiver만 `apps/server` 아래에 추가
 - `create-task-ops add --docs-only`
   현재 리포에 문서와 task 파일 규약만 추가
 
@@ -55,6 +59,8 @@ npx create-task-ops add --docs-only
 - `AGENT.md`
 - `docs/TASK_API_CONTRACT.md`
 - `docs/DASHBOARD_CONNECTION.md`
+- `docs/HEARTBEAT_SETUP.md`
+- `scripts/orbitops-heartbeat.mjs`
 - `app/api/orbitops/health/route.ts`
 - `app/api/orbitops/tasks/route.ts`
 - `app/api/orbitops/tasks/[id]/route.ts`
@@ -62,6 +68,19 @@ npx create-task-ops add --docs-only
 
 즉 기존 `package.json`, `app/page.tsx`, `app/layout.tsx`, `tsconfig.json` 같은 루트 파일은 건드리지 않는다.
 
+모노레포라면 `--target` 으로 receiver를 실제 서버 앱에 넣는 편이 맞다.
+
+예:
+
+```bash
+npx create-task-ops add --target apps/server
+```
+
+이 경우:
+- `tasks/`, `CLAUDE.md`, `AGENT.md`, `docs/*` 는 리포 루트에 생성
+- `scripts/orbitops-heartbeat.mjs` 도 리포 루트에 생성
+- `app/api/orbitops/*`, `lib/orbitops/task-api.ts` 는 `apps/server` 아래에 생성
+
 기본 동작에서 기존 `CLAUDE.md`, `AGENT.md`, `tasks/*`, `docs/*` 같은 운영 문서는 스킵한다.
 
 대신 아래 receiver 경로가 이미 있으면 충돌 가능성이 크므로 경고 후 중단한다.
@@ -79,6 +98,7 @@ npx create-task-ops add --docs-only
 npm run create-task-ops -- my-project
 npm run create-task-ops -- create my-project
 npm run create-task-ops -- add
+npm run create-task-ops -- add --target apps/server
 npm run create-task-ops -- add --docs-only
 cd packages/create-task-ops
 npm run smoke:full

package/bin/create-task-ops.js

@@ -22,6 +22,7 @@ function parseArgs(argv) {
     mode: "full",
     docsOnly: false,
     force: false,
+    target: null,
   };
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -43,6 +44,11 @@ function parseArgs(argv) {
       options.docsOnly = true;
       continue;
     }
+    if (arg === "--target") {
+      options.target = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
     if (arg === "--force") {
       options.force = true;
       continue;
@@ -67,6 +73,7 @@ function printUsage() {
   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 --target apps/server");
   console.log("  create-task-ops add --docs-only");
 }
 
@@ -138,6 +145,22 @@ function copySelectedFiles(sourceDir, targetDir, projectName, force, selectedFil
   }
 }
 
+function assertReceiverPathsAvailable(targetDir, force, selectedFiles) {
+  if (force) {
+    return;
+  }
+
+  for (const relativeFile of selectedFiles) {
+    const targetPath = path.join(targetDir, relativeFile);
+    if (existsSync(targetPath)) {
+      console.error(`Refusing to overwrite existing receiver file: ${targetPath}`);
+      console.error("This path is reserved for task API integration.");
+      console.error("Use --force if you want to replace the existing receiver files.");
+      process.exit(1);
+    }
+  }
+}
+
 function main() {
   const options = parseArgs(args);
   if (options.command === "add") {
@@ -155,6 +178,9 @@ function main() {
   const targetDir = options.command === "add"
     ? process.cwd()
     : path.resolve(process.cwd(), options.name ?? projectName);
+  const receiverTargetDir = options.command === "add" && options.target
+    ? path.resolve(process.cwd(), options.target)
+    : targetDir;
 
   if (options.command === "create" && existsSync(targetDir) && readdirSync(targetDir).length > 0 && !options.force) {
     console.error(`Target directory is not empty: ${targetDir}`);
@@ -162,6 +188,12 @@ function main() {
     process.exit(1);
   }
 
+  if (options.command === "add" && options.target && !existsSync(receiverTargetDir)) {
+    console.error(`Receiver target does not exist: ${receiverTargetDir}`);
+    console.error("Create the app directory first, then run add with --target.");
+    process.exit(1);
+  }
+
   mkdirSync(targetDir, { recursive: true });
 
   const commonDir = path.join(templatesRoot, "common");
@@ -169,16 +201,23 @@ function main() {
 
   const skipExistingDocs = options.command === "add";
 
+  if (options.command === "add" && options.mode === "api") {
+    assertReceiverPathsAvailable(receiverTargetDir, options.force, addApiFiles);
+  }
+
   copyTemplateTree(commonDir, targetDir, projectName, options.force, skipExistingDocs);
 
   if (options.command === "add" && options.mode === "api") {
-    copySelectedFiles(modeDir, targetDir, projectName, options.force, addApiFiles, false);
+    copySelectedFiles(modeDir, receiverTargetDir, projectName, options.force, addApiFiles, false);
   } else {
     copyTemplateTree(modeDir, targetDir, projectName, options.force, skipExistingDocs);
   }
 
   console.log(`create-task-ops completed`);
   console.log(`target: ${targetDir}`);
+  if (options.command === "add" && options.mode === "api") {
+    console.log(`receiver target: ${receiverTargetDir}`);
+  }
   console.log(`command: ${options.command}`);
   console.log(`mode: ${options.mode}`);
   console.log(`project: ${projectName}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-task-ops",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Next.js-first task-ops scaffold generator for task docs and task APIs",
   "license": "MIT",
   "type": "module",

package/templates/common/docs/DASHBOARD_CONNECTION.md

@@ -7,6 +7,7 @@
 - `GET /api/orbitops/health`
 - `GET /api/orbitops/tasks`
 - `GET /api/orbitops/tasks/:id`
+- `POST <central>/api/orbitops/agents/heartbeat` optional
 
 ## 로컬 개발 연결 예시
 
@@ -33,3 +34,4 @@
 2. `/api/orbitops/tasks` 응답이 정상인가
 3. source `id` 와 `label` 이 명확한가
 4. 필요하면 API key 또는 reverse proxy 를 설정했는가
+5. presence 가 필요하면 `docs/HEARTBEAT_SETUP.md` 를 따라 heartbeat sender 를 설정했는가

package/templates/common/docs/HEARTBEAT_SETUP.md

@@ -0,0 +1,56 @@
+# Heartbeat Setup
+
+이 프로젝트는 중앙 대시보드로 `presence` heartbeat 를 보낼 수 있다.
+
+## 목적
+
+- 리모트 에이전트가 현재 `online`, `idle`, `paused`, `offline` 인지 중앙에서 본다.
+- heartbeat 가 끊기면 중앙은 일정 시간 뒤 `unreachable` 로 처리한다.
+
+## 중앙 대시보드 엔드포인트
+
+- `POST /api/orbitops/agents/heartbeat`
+
+## 포함된 sender 스크립트
+
+- `scripts/orbitops-heartbeat.mjs`
+
+이 스크립트는:
+
+- 시작 시 즉시 heartbeat 전송
+- 이후 주기적으로 heartbeat 반복 전송
+- 프로세스 종료 시 `offline` 전송 시도
+
+## 필요한 환경 변수
+
+```bash
+ORBITOPS_HEARTBEAT_URL=http://127.0.0.1:3000/api/orbitops/agents/heartbeat
+ORBITOPS_SOURCE_ID=__PROJECT_NAME__
+ORBITOPS_AGENT_ID=__PROJECT_NAME__-server-01
+ORBITOPS_AGENT=codex
+ORBITOPS_NOTE=Task API receiver is online
+ORBITOPS_HEARTBEAT_INTERVAL_MS=15000
+ORBITOPS_HEARTBEAT_API_KEY=
+```
+
+선택값:
+
+- `ORBITOPS_PRESENCE`
+  기본값 `online`
+- `ORBITOPS_HOST`
+- `ORBITOPS_RUN_ID`
+
+## 실행 예시
+
+```bash
+node scripts/orbitops-heartbeat.mjs
+```
+
+## systemd 또는 tmux 사용 권장
+
+실서비스에서는 앱 프로세스와 따로 heartbeat sender 를 띄우기보다:
+
+- 앱이 직접 heartbeat 를 보내게 하거나
+- process manager 에서 sender 를 같이 올리는 방식이 낫다.
+
+지금 스크립트는 파일럿 및 초기 운영용 기본 예제다.

package/templates/common/scripts/orbitops-heartbeat.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import os from "node:os";
+import process from "node:process";
+
+const heartbeatUrl = process.env.ORBITOPS_HEARTBEAT_URL;
+const heartbeatSourceId = process.env.ORBITOPS_SOURCE_ID || "__PROJECT_NAME__";
+const heartbeatAgentId =
+  process.env.ORBITOPS_AGENT_ID || `${heartbeatSourceId}-${os.hostname()}-${process.pid}`;
+const heartbeatPresence = process.env.ORBITOPS_PRESENCE || "online";
+const heartbeatAgent = process.env.ORBITOPS_AGENT || "codex";
+const heartbeatNote = process.env.ORBITOPS_NOTE || "Task API receiver is online";
+const heartbeatHost = process.env.ORBITOPS_HOST || os.hostname();
+const heartbeatRunId = process.env.ORBITOPS_RUN_ID || "";
+const heartbeatIntervalMs = Number.parseInt(process.env.ORBITOPS_HEARTBEAT_INTERVAL_MS || "15000", 10);
+const heartbeatApiKey = process.env.ORBITOPS_HEARTBEAT_API_KEY || "";
+
+if (!heartbeatUrl) {
+  console.error("ORBITOPS_HEARTBEAT_URL is required");
+  process.exit(1);
+}
+
+async function sendHeartbeat(presence = heartbeatPresence) {
+  const response = await fetch(heartbeatUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...(heartbeatApiKey ? { Authorization: `Bearer ${heartbeatApiKey}` } : {}),
+    },
+    body: JSON.stringify({
+      agentId: heartbeatAgentId,
+      sourceId: heartbeatSourceId,
+      presence,
+      host: heartbeatHost,
+      pid: process.pid,
+      runId: heartbeatRunId || undefined,
+      agent: heartbeatAgent,
+      note: heartbeatNote,
+      sentAt: new Date().toISOString(),
+    }),
+  });
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => "");
+    throw new Error(`Heartbeat failed: ${response.status} ${detail}`);
+  }
+
+  console.log(`[orbitops] heartbeat sent: ${presence}`);
+}
+
+await sendHeartbeat();
+const timer = setInterval(() => {
+  void sendHeartbeat().catch((error) => {
+    console.error("[orbitops] heartbeat error", error);
+  });
+}, heartbeatIntervalMs);
+
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, () => {
+    clearInterval(timer);
+    void sendHeartbeat("offline")
+      .catch(() => null)
+      .finally(() => process.exit(0));
+  });
+}