create-task-ops 0.1.8 → 0.1.10

package/README.md

@@ -15,6 +15,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 --print-targets
 node packages/create-task-ops/bin/create-task-ops.js add --docs-only
 ```
 
@@ -25,6 +26,7 @@ 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
 ```
 
@@ -35,9 +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 파일 규약만 추가
 
@@ -61,9 +65,11 @@ npx create-task-ops add --docs-only
 - `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` 같은 루트 파일은 건드리지 않는다.
@@ -79,7 +85,7 @@ 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` 아래에 생성
+- `app/api/orbitops/*`, `lib/orbitops/auth.ts`, `lib/orbitops/task-api.ts` 는 `apps/server` 아래에 생성
 
 기본 동작에서 기존 `CLAUDE.md`, `AGENT.md`, `tasks/*`, `docs/*` 같은 운영 문서는 스킵한다.
 
@@ -88,6 +94,7 @@ npx create-task-ops add --target apps/server
 - `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` 를 쓴다.
@@ -104,6 +111,14 @@ 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,7 @@ function parseArgs(argv) {
     mode: "full",
     docsOnly: false,
     force: false,
+    printTargets: false,
     target: null,
   };
 
@@ -49,6 +51,10 @@ function parseArgs(argv) {
       index += 1;
       continue;
     }
+    if (arg === "--print-targets") {
+      options.printTargets = true;
+      continue;
+    }
     if (arg === "--force") {
       options.force = true;
       continue;
@@ -74,9 +80,81 @@ function printUsage() {
   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) => {
@@ -161,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") {
@@ -178,9 +279,18 @@ 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;
+  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}`);
@@ -194,6 +304,17 @@ function main() {
     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");
@@ -213,6 +334,12 @@ function main() {
     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") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-task-ops",
-  "version": "0.1.8",
+  "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,7 @@
 - `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
 
 ## 로컬 개발 연결 예시
@@ -35,3 +36,4 @@
 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

@@ -31,6 +31,8 @@ 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
 ```
 
 선택값:
@@ -40,17 +42,59 @@ ORBITOPS_HEARTBEAT_API_KEY=
 - `ORBITOPS_HOST`
 - `ORBITOPS_RUN_ID`
 
+이 스크립트는 heartbeat 성공 시 중앙이 내려준 runtime token 을 `ORBITOPS_RUNTIME_TOKEN_FILE` 에 저장한다.
+생성된 `OrbitOps` receiver API 는 이 파일을 읽어 `Authorization: Bearer <runtimeToken>` 을 검증한다.
+
 ## 실행 예시
 
 ```bash
 node scripts/orbitops-heartbeat.mjs
 ```
 
-## systemd 또는 tmux 사용 권장
+생성기 기준으로는 보통 아래 스크립트도 같이 들어간다.
+
+```bash
+npm run orbitops:heartbeat
+```
+
+## PM2 예시
+
+```bash
+pm2 start npm --name orbitops-heartbeat -- run orbitops:heartbeat
+pm2 save
+```
+
+## systemd 예시
 
-실서비스에서는 앱 프로세스와 따로 heartbeat sender 를 띄우기보다:
+`/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
+```
 
-- 앱이 직접 heartbeat 를 보내게 하거나
-- process manager 에서 sender 를 같이 올리는 방식이 낫다.
+## 운영 권장
 
-지금 스크립트는 파일럿 및 초기 운영용 기본 예제다.
+- 개발 중에는 `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

@@ -1,6 +1,8 @@
 #!/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;
@@ -14,12 +16,37 @@ 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",
@@ -31,6 +58,7 @@ async function sendHeartbeat(presence = heartbeatPresence) {
       agentId: heartbeatAgentId,
       sourceId: heartbeatSourceId,
       presence,
+      baseUrl: heartbeatBaseUrl || undefined,
       host: heartbeatHost,
       pid: process.pid,
       runId: heartbeatRunId || undefined,
@@ -45,6 +73,8 @@ async function sendHeartbeat(presence = heartbeatPresence) {
     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}`);
 }
 

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",