create-task-ops 0.1.7 → 0.1.10

package/README.md

@@ -14,6 +14,8 @@
 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 --print-targets
 node packages/create-task-ops/bin/create-task-ops.js add --docs-only
 ```
 
@@ -23,6 +25,8 @@ 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 --print-targets
 npx create-task-ops add --docs-only
 ```
 
@@ -33,7 +37,11 @@ npx create-task-ops add --docs-only
 - `create-task-ops create my-project`
   위와 같지만 명시적으로 create를 적는 형태
 - `create-task-ops add`
-  현재 리포에 task docs + OrbitOps API 추가
+  현재 리포에 task docs + OrbitOps API 추가. `app`, `src/app`, `apps/*/app`, `packages/*/app` 를 스캔해 추천 경로를 고른다.
+- `create-task-ops add --target apps/server`
+  문서와 tasks는 리포 루트에 두고, OrbitOps receiver만 `apps/server` 아래에 추가
+- `create-task-ops add --print-targets`
+  감지된 receiver 후보 경로만 출력하고 종료
 - `create-task-ops add --docs-only`
   현재 리포에 문서와 task 파일 규약만 추가
 
@@ -55,13 +63,30 @@ 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`
+- 기존 `package.json` 이 있으면 `scripts.orbitops:heartbeat` 를 없을 때만 추가
 - `app/api/orbitops/health/route.ts`
 - `app/api/orbitops/tasks/route.ts`
 - `app/api/orbitops/tasks/[id]/route.ts`
+- `lib/orbitops/auth.ts`
 - `lib/orbitops/task-api.ts`
 
 즉 기존 `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/auth.ts`, `lib/orbitops/task-api.ts` 는 `apps/server` 아래에 생성
+
 기본 동작에서 기존 `CLAUDE.md`, `AGENT.md`, `tasks/*`, `docs/*` 같은 운영 문서는 스킵한다.
 
 대신 아래 receiver 경로가 이미 있으면 충돌 가능성이 크므로 경고 후 중단한다.
@@ -69,6 +94,7 @@ npx create-task-ops add --docs-only
 - `app/api/orbitops/health/route.ts`
 - `app/api/orbitops/tasks/route.ts`
 - `app/api/orbitops/tasks/[id]/route.ts`
+- `lib/orbitops/auth.ts`
 - `lib/orbitops/task-api.ts`
 
 이 receiver 파일까지 강제로 교체하려면 `--force` 를 쓴다.
@@ -79,11 +105,20 @@ 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
 ```
 
+## Runtime Token 흐름
+
+- 중앙 대시보드 heartbeat 응답은 짧은 수명 runtime token 을 반환한다.
+- `scripts/orbitops-heartbeat.mjs` 는 이 토큰을 기본적으로 `.orbitops-runtime-token` 에 저장한다.
+- 생성기 기준으로는 `npm run orbitops:heartbeat` 스크립트도 같이 잡아준다.
+- 생성된 `GET /api/orbitops/tasks` 와 `GET /api/orbitops/tasks/:id` 는 이 파일을 읽어 `Authorization: Bearer <runtimeToken>` 을 검증한다.
+- `GET /api/orbitops/health` 는 상태 확인용으로 열려 있다.
+
 ## 퍼블리시 전 체크
 
 ```bash

package/bin/create-task-ops.js

@@ -14,6 +14,7 @@ const addApiFiles = [
   "app/api/orbitops/tasks/[id]/route.ts",
   "lib/orbitops/task-api.ts",
 ];
+const targetCandidateRoots = ["app", "src/app"];
 
 function parseArgs(argv) {
   const options = {
@@ -22,6 +23,8 @@ function parseArgs(argv) {
     mode: "full",
     docsOnly: false,
     force: false,
+    printTargets: false,
+    target: null,
   };
 
   for (let index = 0; index < argv.length; index += 1) {
@@ -43,6 +46,15 @@ function parseArgs(argv) {
       options.docsOnly = true;
       continue;
     }
+    if (arg === "--target") {
+      options.target = argv[index + 1] ?? null;
+      index += 1;
+      continue;
+    }
+    if (arg === "--print-targets") {
+      options.printTargets = true;
+      continue;
+    }
     if (arg === "--force") {
       options.force = true;
       continue;
@@ -67,9 +79,82 @@ 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 --print-targets");
   console.log("  create-task-ops add --docs-only");
 }
 
+function listDirectories(dir) {
+  if (!existsSync(dir)) {
+    return [];
+  }
+
+  return readdirSync(dir).filter((entry) => statSync(path.join(dir, entry)).isDirectory());
+}
+
+function detectReceiverTargets(rootDir) {
+  const candidates = [];
+  const seen = new Set();
+
+  function pushCandidate(relativeAppPath, reason) {
+    const normalizedAppPath = relativeAppPath.replace(/\\/g, "/").replace(/\/+$/, "");
+    if (!normalizedAppPath || seen.has(normalizedAppPath)) {
+      return;
+    }
+
+    const absoluteAppPath = path.join(rootDir, normalizedAppPath);
+    if (!existsSync(absoluteAppPath) || !statSync(absoluteAppPath).isDirectory()) {
+      return;
+    }
+
+    seen.add(normalizedAppPath);
+
+    candidates.push({
+      appPath: normalizedAppPath,
+      reason,
+      targetPath: normalizedAppPath.endsWith("/app") ? normalizedAppPath.slice(0, -4) || "." : ".",
+      score:
+        normalizedAppPath === "app"
+          ? 100
+          : normalizedAppPath === "src/app"
+            ? 95
+            : normalizedAppPath.endsWith("/src/app")
+              ? 90
+              : normalizedAppPath.endsWith("/app")
+                ? 85
+                : 70,
+    });
+  }
+
+  for (const root of targetCandidateRoots) {
+    pushCandidate(root, "root");
+  }
+
+  for (const group of ["apps", "packages"]) {
+    const groupDir = path.join(rootDir, group);
+    for (const entry of listDirectories(groupDir)) {
+      pushCandidate(path.join(group, entry, "app"), `${group} app`);
+      pushCandidate(path.join(group, entry, "src/app"), `${group} src/app`);
+    }
+  }
+
+  return candidates.sort((left, right) => right.score - left.score || left.appPath.localeCompare(right.appPath));
+}
+
+function printDetectedTargets(targets) {
+  if (targets.length === 0) {
+    console.log("No Next.js app router path was detected.");
+    console.log("Tried: app, src/app, apps/*/app, apps/*/src/app, packages/*/app, packages/*/src/app");
+    return;
+  }
+
+  console.log("Detected receiver targets:");
+  for (const [index, target] of targets.entries()) {
+    const recommended = index === 0 ? " (recommended)" : "";
+    console.log(`- ${target.targetPath}  [${target.appPath}]${recommended}`);
+  }
+}
+
 function listFiles(dir, prefix = "") {
   const entries = readdirSync(dir);
   return entries.flatMap((entry) => {
@@ -154,6 +239,29 @@ function assertReceiverPathsAvailable(targetDir, force, selectedFiles) {
   }
 }
 
+function ensureHeartbeatScript(packageJsonPath) {
+  if (!existsSync(packageJsonPath)) {
+    return;
+  }
+
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    const scripts = parsed.scripts && typeof parsed.scripts === "object" ? parsed.scripts : {};
+
+    if (!scripts["orbitops:heartbeat"]) {
+      scripts["orbitops:heartbeat"] = "node scripts/orbitops-heartbeat.mjs";
+      parsed.scripts = scripts;
+      writeFileSync(packageJsonPath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+      console.log(`Added script orbitops:heartbeat to ${packageJsonPath}`);
+      return;
+    }
+
+    console.log(`Keeping existing script orbitops:heartbeat in ${packageJsonPath}`);
+  } catch (error) {
+    console.warn(`Could not update package.json scripts at ${packageJsonPath}: ${error instanceof Error ? error.message : "unknown error"}`);
+  }
+}
+
 function main() {
   const options = parseArgs(args);
   if (options.command === "add") {
@@ -171,6 +279,18 @@ function main() {
   const targetDir = options.command === "add"
     ? process.cwd()
     : path.resolve(process.cwd(), options.name ?? projectName);
+  const detectedTargets = options.command === "add" ? detectReceiverTargets(targetDir) : [];
+  const recommendedTarget = detectedTargets[0]?.targetPath ?? ".";
+
+  if (options.command === "add" && options.printTargets) {
+    printDetectedTargets(detectedTargets);
+    process.exit(0);
+  }
+
+  const receiverTargetDir =
+    options.command === "add"
+      ? path.resolve(process.cwd(), options.target ?? recommendedTarget)
+      : targetDir;
 
   if (options.command === "create" && existsSync(targetDir) && readdirSync(targetDir).length > 0 && !options.force) {
     console.error(`Target directory is not empty: ${targetDir}`);
@@ -178,6 +298,23 @@ 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);
+  }
+
+  if (options.command === "add" && options.mode === "api") {
+    printDetectedTargets(detectedTargets);
+    if (!options.target && detectedTargets.length > 0) {
+      console.log(`No --target provided. Using recommended receiver target: ${recommendedTarget}`);
+      console.log("Use --target <path> to override.");
+    }
+    if (!options.target && detectedTargets.length === 0) {
+      console.log("Falling back to current directory. Use --target <path> to set the receiver location manually.");
+    }
+  }
+
   mkdirSync(targetDir, { recursive: true });
 
   const commonDir = path.join(templatesRoot, "common");
@@ -186,19 +323,28 @@ function main() {
   const skipExistingDocs = options.command === "add";
 
   if (options.command === "add" && options.mode === "api") {
-    assertReceiverPathsAvailable(targetDir, options.force, addApiFiles);
+    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);
   }
 
+  if (options.command === "add") {
+    ensureHeartbeatScript(path.join(targetDir, "package.json"));
+  } else if (options.mode !== "docs") {
+    ensureHeartbeatScript(path.join(targetDir, "package.json"));
+  }
+
   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.7",
+  "version": "0.1.10",
   "description": "Next.js-first task-ops scaffold generator for task docs and task APIs",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "smoke:full": "node ./bin/create-task-ops.js /tmp/create-task-ops-full --mode full --force",
     "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"
+    "prepublishOnly": "npm run smoke:full && npm run smoke:add && npm run smoke:docs && npm run pack:dry-run"
   },
   "publishConfig": {
     "access": "public"

package/templates/api/app/api/orbitops/tasks/[id]/route.ts

@@ -1,13 +1,19 @@
 import { NextResponse } from "next/server";
+import { authorizeOrbitOpsRequest } from "@/lib/orbitops/auth";
 import { getTaskById } from "@/lib/orbitops/task-api";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
 export async function GET(
-  _request: Request,
+  request: Request,
   context: { params: Promise<{ id: string }> },
 ) {
+  const authorization = await authorizeOrbitOpsRequest(request);
+  if (!authorization.ok) {
+    return NextResponse.json({ error: authorization.error }, { status: authorization.status });
+  }
+
   const { id } = await context.params;
   const task = await getTaskById(id);
 

package/templates/api/app/api/orbitops/tasks/route.ts

@@ -1,10 +1,16 @@
 import { NextResponse } from "next/server";
+import { authorizeOrbitOpsRequest } from "@/lib/orbitops/auth";
 import { getTasks } from "@/lib/orbitops/task-api";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
-export async function GET() {
+export async function GET(request: Request) {
+  const authorization = await authorizeOrbitOpsRequest(request);
+  if (!authorization.ok) {
+    return NextResponse.json({ error: authorization.error }, { status: authorization.status });
+  }
+
   const tasks = await getTasks();
 
   return NextResponse.json({

package/templates/api/lib/orbitops/auth.ts

@@ -0,0 +1,95 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+
+type RuntimeTokenFile = {
+  sourceId?: string;
+  runtimeToken?: string;
+  expiresAt?: string;
+  updatedAt?: string;
+};
+
+async function fileExists(filePath: string) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveRuntimeTokenFile() {
+  const configuredPath = process.env.ORBITOPS_RUNTIME_TOKEN_FILE;
+  if (configuredPath) {
+    return configuredPath;
+  }
+
+  let currentDir = process.cwd();
+  const { root } = path.parse(currentDir);
+
+  while (true) {
+    const candidate = path.join(currentDir, ".orbitops-runtime-token");
+    if (await fileExists(candidate)) {
+      return candidate;
+    }
+
+    if (currentDir === root) {
+      return candidate;
+    }
+
+    currentDir = path.dirname(currentDir);
+  }
+}
+
+async function readRuntimeTokenFile() {
+  const filePath = await resolveRuntimeTokenFile();
+  const raw = await readFile(filePath, "utf8");
+  const parsed = JSON.parse(raw) as RuntimeTokenFile;
+
+  if (!parsed.runtimeToken || !parsed.expiresAt) {
+    throw new Error("Runtime token file is missing required fields");
+  }
+
+  return parsed;
+}
+
+export async function authorizeOrbitOpsRequest(request: Request) {
+  const authorization = request.headers.get("authorization");
+  if (!authorization?.startsWith("Bearer ")) {
+    return {
+      ok: false as const,
+      status: 401,
+      error: "Missing runtime token",
+    };
+  }
+
+  let tokenFile: RuntimeTokenFile;
+
+  try {
+    tokenFile = await readRuntimeTokenFile();
+  } catch (error) {
+    return {
+      ok: false as const,
+      status: 503,
+      error: error instanceof Error ? error.message : "Runtime token is unavailable",
+    };
+  }
+
+  const providedToken = authorization.slice("Bearer ".length).trim();
+  if (providedToken !== tokenFile.runtimeToken) {
+    return {
+      ok: false as const,
+      status: 401,
+      error: "Invalid runtime token",
+    };
+  }
+
+  if (new Date(tokenFile.expiresAt ?? "").getTime() <= Date.now()) {
+    return {
+      ok: false as const,
+      status: 401,
+      error: "Runtime token expired",
+    };
+  }
+
+  return { ok: true as const };
+}

package/templates/api/package.json

@@ -5,7 +5,8 @@
   "scripts": {
     "dev": "next dev",
     "build": "next build",
-    "start": "next start"
+    "start": "next start",
+    "orbitops:heartbeat": "node scripts/orbitops-heartbeat.mjs"
   },
   "dependencies": {
     "next": "15.2.4",

package/templates/common/docs/DASHBOARD_CONNECTION.md

@@ -7,6 +7,8 @@
 - `GET /api/orbitops/health`
 - `GET /api/orbitops/tasks`
 - `GET /api/orbitops/tasks/:id`
+- task endpoint 는 중앙 heartbeat 로 발급받은 runtime token 으로 보호된다.
+- `POST <central>/api/orbitops/agents/heartbeat` optional
 
 ## 로컬 개발 연결 예시
 
@@ -33,3 +35,5 @@
 2. `/api/orbitops/tasks` 응답이 정상인가
 3. source `id` 와 `label` 이 명확한가
 4. 필요하면 API key 또는 reverse proxy 를 설정했는가
+5. presence 가 필요하면 `docs/HEARTBEAT_SETUP.md` 를 따라 heartbeat sender 를 설정했는가
+6. receiver 가 `.orbitops-runtime-token` 파일을 읽을 수 있는가

package/templates/common/docs/HEARTBEAT_SETUP.md

@@ -0,0 +1,100 @@
+# 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_BASE_URL=http://127.0.0.1:3001
+ORBITOPS_RUNTIME_TOKEN_FILE=.orbitops-runtime-token
+```
+
+선택값:
+
+- `ORBITOPS_PRESENCE`
+  기본값 `online`
+- `ORBITOPS_HOST`
+- `ORBITOPS_RUN_ID`
+
+이 스크립트는 heartbeat 성공 시 중앙이 내려준 runtime token 을 `ORBITOPS_RUNTIME_TOKEN_FILE` 에 저장한다.
+생성된 `OrbitOps` receiver API 는 이 파일을 읽어 `Authorization: Bearer <runtimeToken>` 을 검증한다.
+
+## 실행 예시
+
+```bash
+node scripts/orbitops-heartbeat.mjs
+```
+
+생성기 기준으로는 보통 아래 스크립트도 같이 들어간다.
+
+```bash
+npm run orbitops:heartbeat
+```
+
+## PM2 예시
+
+```bash
+pm2 start npm --name orbitops-heartbeat -- run orbitops:heartbeat
+pm2 save
+```
+
+## systemd 예시
+
+`/etc/systemd/system/orbitops-heartbeat.service`
+
+```ini
+[Unit]
+Description=OrbitOps Heartbeat Sender
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=/path/to/your-repo
+EnvironmentFile=/path/to/your-repo/.env
+ExecStart=/usr/bin/npm run orbitops:heartbeat
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+적용:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now orbitops-heartbeat
+sudo systemctl status orbitops-heartbeat
+```
+
+## 운영 권장
+
+- 개발 중에는 `npm run orbitops:heartbeat`
+- 상시 서버는 `pm2` 또는 `systemd`
+- 앱 프로세스가 lifecycle 을 직접 알 수 있으면, 나중에는 앱 내부 heartbeat 로 옮기는 편이 더 단단하다

package/templates/common/docs/TASK_API_CONTRACT.md

@@ -8,6 +8,11 @@
 - `GET /api/orbitops/tasks`
 - `GET /api/orbitops/tasks/:id`
 
+주의:
+
+- 두 task endpoint 는 `Authorization: Bearer <runtimeToken>` 헤더를 요구한다.
+- runtime token 은 중앙 대시보드 heartbeat 응답으로 내려오며, 기본 sender 스크립트가 `.orbitops-runtime-token` 파일에 저장한다.
+
 ## Task Fields
 
 - `id`

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

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+import { mkdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+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 || "";
+const heartbeatBaseUrl = process.env.ORBITOPS_BASE_URL || "";
+const runtimeTokenFile =
+  process.env.ORBITOPS_RUNTIME_TOKEN_FILE || path.join(process.cwd(), ".orbitops-runtime-token");
+
+if (!heartbeatUrl) {
+  console.error("ORBITOPS_HEARTBEAT_URL is required");
+  process.exit(1);
+}
+
+async function persistRuntimeToken(runtimeToken, expiresAt) {
+  if (!runtimeToken || !expiresAt) {
+    return;
+  }
+
+  await mkdir(path.dirname(runtimeTokenFile), { recursive: true });
+  await writeFile(
+    runtimeTokenFile,
+    JSON.stringify(
+      {
+        sourceId: heartbeatSourceId,
+        runtimeToken,
+        expiresAt,
+        updatedAt: new Date().toISOString(),
+      },
+      null,
+      2,
+    ),
+    "utf8",
+  );
+}
+
+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,
+      baseUrl: heartbeatBaseUrl || undefined,
+      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}`);
+  }
+
+  const payload = await response.json().catch(() => ({}));
+  await persistRuntimeToken(payload.runtimeToken, payload.expiresAt);
+  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));
+  });
+}

package/templates/full/app/api/orbitops/tasks/[id]/route.ts

@@ -1,13 +1,19 @@
 import { NextResponse } from "next/server";
+import { authorizeOrbitOpsRequest } from "@/lib/orbitops/auth";
 import { getTaskById } from "@/lib/orbitops/task-api";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
 export async function GET(
-  _request: Request,
+  request: Request,
   context: { params: Promise<{ id: string }> },
 ) {
+  const authorization = await authorizeOrbitOpsRequest(request);
+  if (!authorization.ok) {
+    return NextResponse.json({ error: authorization.error }, { status: authorization.status });
+  }
+
   const { id } = await context.params;
   const task = await getTaskById(id);
 

package/templates/full/app/api/orbitops/tasks/route.ts

@@ -1,10 +1,16 @@
 import { NextResponse } from "next/server";
+import { authorizeOrbitOpsRequest } from "@/lib/orbitops/auth";
 import { getTasks } from "@/lib/orbitops/task-api";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
 
-export async function GET() {
+export async function GET(request: Request) {
+  const authorization = await authorizeOrbitOpsRequest(request);
+  if (!authorization.ok) {
+    return NextResponse.json({ error: authorization.error }, { status: authorization.status });
+  }
+
   const tasks = await getTasks();
 
   return NextResponse.json({

package/templates/full/lib/orbitops/auth.ts

@@ -0,0 +1,95 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+
+type RuntimeTokenFile = {
+  sourceId?: string;
+  runtimeToken?: string;
+  expiresAt?: string;
+  updatedAt?: string;
+};
+
+async function fileExists(filePath: string) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveRuntimeTokenFile() {
+  const configuredPath = process.env.ORBITOPS_RUNTIME_TOKEN_FILE;
+  if (configuredPath) {
+    return configuredPath;
+  }
+
+  let currentDir = process.cwd();
+  const { root } = path.parse(currentDir);
+
+  while (true) {
+    const candidate = path.join(currentDir, ".orbitops-runtime-token");
+    if (await fileExists(candidate)) {
+      return candidate;
+    }
+
+    if (currentDir === root) {
+      return candidate;
+    }
+
+    currentDir = path.dirname(currentDir);
+  }
+}
+
+async function readRuntimeTokenFile() {
+  const filePath = await resolveRuntimeTokenFile();
+  const raw = await readFile(filePath, "utf8");
+  const parsed = JSON.parse(raw) as RuntimeTokenFile;
+
+  if (!parsed.runtimeToken || !parsed.expiresAt) {
+    throw new Error("Runtime token file is missing required fields");
+  }
+
+  return parsed;
+}
+
+export async function authorizeOrbitOpsRequest(request: Request) {
+  const authorization = request.headers.get("authorization");
+  if (!authorization?.startsWith("Bearer ")) {
+    return {
+      ok: false as const,
+      status: 401,
+      error: "Missing runtime token",
+    };
+  }
+
+  let tokenFile: RuntimeTokenFile;
+
+  try {
+    tokenFile = await readRuntimeTokenFile();
+  } catch (error) {
+    return {
+      ok: false as const,
+      status: 503,
+      error: error instanceof Error ? error.message : "Runtime token is unavailable",
+    };
+  }
+
+  const providedToken = authorization.slice("Bearer ".length).trim();
+  if (providedToken !== tokenFile.runtimeToken) {
+    return {
+      ok: false as const,
+      status: 401,
+      error: "Invalid runtime token",
+    };
+  }
+
+  if (new Date(tokenFile.expiresAt ?? "").getTime() <= Date.now()) {
+    return {
+      ok: false as const,
+      status: 401,
+      error: "Runtime token expired",
+    };
+  }
+
+  return { ok: true as const };
+}

package/templates/full/package.json

@@ -5,7 +5,8 @@
   "scripts": {
     "dev": "next dev",
     "build": "next build",
-    "start": "next start"
+    "start": "next start",
+    "orbitops:heartbeat": "node scripts/orbitops-heartbeat.mjs"
   },
   "dependencies": {
     "next": "15.2.4",