agentplane 0.3.2 → 0.3.4

package/bin/agentplane.js

@@ -4,7 +4,9 @@ import path from "node:path";
 import { stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { distExists, isPackageBuildFresh } from "./dist-guard.js";
-import { resolveFrameworkBinaryContext } from "./runtime-context.js";
+import { getWatchedRuntimePathsForPackage } from "./runtime-watch.js";
+import { classifyStaleDistPolicy } from "./stale-dist-policy.js";
+import { isPathInside, resolveFrameworkBinaryContext } from "./runtime-context.js";
 
 async function exists(p) {
   try {
@@ -43,6 +45,27 @@ function isRepoLocalHandoffInvocation() {
   return (process.env.AGENTPLANE_REPO_LOCAL_HANDOFF ?? "").trim() === "1";
 }
 
+function inferRuntimeMode(context) {
+  if (context.inFrameworkCheckout && context.isRepoLocalRuntime) {
+    return isRepoLocalHandoffInvocation() ? "repo-local-handoff" : "repo-local";
+  }
+  if (context.inFrameworkCheckout && shouldUseGlobalBinaryInFramework()) {
+    return "global-forced-in-framework";
+  }
+  if (context.inFrameworkCheckout) {
+    return "global-in-framework";
+  }
+  return "global-installed";
+}
+
+function primeRuntimeEnv(context) {
+  process.env.AGENTPLANE_RUNTIME_ACTIVE_BIN = context.thisBin;
+  process.env.AGENTPLANE_RUNTIME_MODE = inferRuntimeMode(context);
+  if (!isRepoLocalHandoffInvocation()) {
+    delete process.env.AGENTPLANE_RUNTIME_HANDOFF_FROM;
+  }
+}
+
 function handoffToRepoLocalBinary(context) {
   const repoBin = context.checkout?.repoBin;
   if (!repoBin) return false;
@@ -57,6 +80,9 @@ function handoffToRepoLocalBinary(context) {
     env: {
       ...process.env,
       AGENTPLANE_REPO_LOCAL_HANDOFF: "1",
+      AGENTPLANE_RUNTIME_MODE: "repo-local-handoff",
+      AGENTPLANE_RUNTIME_ACTIVE_BIN: path.resolve(repoBin),
+      AGENTPLANE_RUNTIME_HANDOFF_FROM: context.thisBin,
     },
   });
 
@@ -91,11 +117,6 @@ function isHooksRunCommitMsgInvocation(argv) {
   return false;
 }
 
-function isPathInside(baseDir, targetPath) {
-  const rel = path.relative(path.resolve(baseDir), path.resolve(targetPath));
-  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
-}
-
 async function assertDistUpToDate() {
   const here = path.dirname(fileURLToPath(import.meta.url));
   const agentplaneRoot = path.resolve(here, "..");
@@ -120,11 +141,16 @@ async function assertDistUpToDate() {
     {
       name: "agentplane",
       root: agentplaneRoot,
-      watchedPaths: ["src", "bin/agentplane.js", "bin/dist-guard.js"],
+      watchedPaths: getWatchedRuntimePathsForPackage("agentplane"),
     },
   ];
-  if (await exists(path.join(coreRoot, "src")))
-    checks.push({ name: "core", root: coreRoot, watchedPaths: ["src"] });
+  if (await exists(path.join(coreRoot, "src"))) {
+    checks.push({
+      name: "core",
+      root: coreRoot,
+      watchedPaths: getWatchedRuntimePathsForPackage("@agentplaneorg/core"),
+    });
+  }
 
   const staleReasons = [];
   for (const check of checks) {
@@ -150,6 +176,24 @@ async function assertDistUpToDate() {
       return true;
     }
 
+    const commandPolicy = classifyStaleDistPolicy(process.argv);
+    if (commandPolicy.mode === "warn_and_run") {
+      const commandText = process.argv
+        .slice(2)
+        .map((value) => String(value ?? "").trim())
+        .filter(Boolean)
+        .join(" ");
+      process.stderr.write(
+        "warning: allowing read-only diagnostic command to run with a stale repo build inside the framework checkout.\n" +
+          `command: ${commandText || "<unknown>"}\n` +
+          `detected: ${staleReasons.join(", ")}\n` +
+          "rebuild recommended:\n" +
+          "  bun run --filter=@agentplaneorg/core build\n" +
+          "  bun run --filter=agentplane build\n",
+      );
+      return true;
+    }
+
     process.stderr.write(
       "error: refusing to run a stale repo build (manifest/git quick-check failed).\n" +
         "Fix:\n" +
@@ -165,6 +209,12 @@ async function assertDistUpToDate() {
   return true;
 }
 
+const runtimeContext = resolveFrameworkBinaryContext({
+  cwd: process.cwd(),
+  thisBin: fileURLToPath(import.meta.url),
+});
+primeRuntimeEnv(runtimeContext);
+
 if (!maybeHandoffToRepoLocalBinary()) {
   await maybeWarnGlobalBinaryInRepoCheckout();
   const ok = isHooksRunCommitMsgInvocation(process.argv) ? true : await assertDistUpToDate();

package/bin/dist-guard.js

@@ -1,6 +1,7 @@
 import { execFileSync } from "node:child_process";
 import path from "node:path";
 import { readFile, stat } from "node:fs/promises";
+import { collectWatchedRuntimeSnapshot, compareWatchedRuntimeSnapshots } from "./runtime-watch.js";
 
 async function exists(p) {
   try {
@@ -33,12 +34,13 @@ function resolveGitHead(cwd) {
   }
 }
 
-function listGitPaths(cwd, args) {
+function listGitPaths(cwd, args, options = {}) {
+  const trimLines = options.trimLines ?? true;
   try {
     const out = execFileSync("git", args, { cwd, encoding: "utf8" });
     return out
       .split(/\r?\n/u)
-      .map((line) => line.trim())
+      .map((line) => (trimLines ? line.trim() : line))
       .filter(Boolean);
   } catch {
     return [];
@@ -50,14 +52,19 @@ function uniqueSorted(values) {
 }
 
 function workingTreeChangedPaths(cwd, watchedPaths) {
-  const lines = listGitPaths(cwd, [
-    "status",
-    "--porcelain",
-    "--untracked-files=all",
-    "--",
-    ...watchedPaths,
-  ]);
-  return uniqueSorted(lines.map((line) => line.slice(3).trim()).filter(Boolean));
+  const lines = listGitPaths(
+    cwd,
+    ["status", "--porcelain", "--untracked-files=all", "--", ...watchedPaths],
+    { trimLines: false },
+  );
+  return uniqueSorted(
+    lines
+      .map((line) => {
+        const normalized = String(line ?? "");
+        return normalized.length > 3 ? normalized.slice(3).trim() : "";
+      })
+      .filter(Boolean),
+  );
 }
 
 function committedChangedPathsSince(cwd, fromGitHead, watchedPaths) {
@@ -77,6 +84,45 @@ async function fileMtimeMs(p) {
   }
 }
 
+function parseManifestSnapshot(manifest) {
+  if (
+    !Array.isArray(manifest?.watched_runtime_paths) ||
+    !Array.isArray(manifest?.watched_runtime_files) ||
+    typeof manifest?.watched_runtime_snapshot_hash !== "string"
+  ) {
+    return null;
+  }
+
+  const watchedPaths = manifest.watched_runtime_paths.filter((value) => typeof value === "string");
+  const files = manifest.watched_runtime_files
+    .filter(
+      (value) =>
+        value &&
+        typeof value === "object" &&
+        typeof value.path === "string" &&
+        typeof value.sha256 === "string" &&
+        typeof value.size_bytes === "number",
+    )
+    .map((value) => ({
+      path: value.path,
+      sha256: value.sha256,
+      size_bytes: value.size_bytes,
+    }));
+
+  if (
+    watchedPaths.length !== manifest.watched_runtime_paths.length ||
+    files.length !== manifest.watched_runtime_files.length
+  ) {
+    return null;
+  }
+
+  return {
+    watchedPaths,
+    files,
+    snapshotHash: manifest.watched_runtime_snapshot_hash,
+  };
+}
+
 export async function isPackageBuildFresh(packageRoot, options = {}) {
   const watchedPaths = options.watchedPaths ?? ["src"];
   const manifestPath = path.join(packageRoot, "dist", ".build-manifest.json");
@@ -86,6 +132,28 @@ export async function isPackageBuildFresh(packageRoot, options = {}) {
   }
 
   const currentHead = resolveGitHead(packageRoot);
+  const manifestSnapshot = parseManifestSnapshot(manifest);
+  if (manifestSnapshot) {
+    const currentSnapshot = await collectWatchedRuntimeSnapshot(
+      packageRoot,
+      manifestSnapshot.watchedPaths,
+    );
+    const comparison = compareWatchedRuntimeSnapshots(manifestSnapshot, currentSnapshot);
+    if (!comparison.ok) {
+      return {
+        ok: false,
+        reason: "watched_runtime_snapshot_changed",
+        changedPaths: comparison.changedPaths,
+      };
+    }
+
+    if (manifest.git_head && currentHead && manifest.git_head !== currentHead) {
+      return { ok: true, reason: "fresh_after_snapshot_match", changedPaths: [] };
+    }
+
+    return { ok: true, reason: "fresh", changedPaths: [] };
+  }
+
   const changedPaths = uniqueSorted([
     ...committedChangedPathsSince(packageRoot, manifest.git_head, watchedPaths),
     ...workingTreeChangedPaths(packageRoot, watchedPaths),

package/bin/runtime-context.d.ts

@@ -8,12 +8,15 @@ export type FrameworkCheckout = {
 export type FrameworkBinaryContext = {
   inFrameworkCheckout: boolean;
   isRepoLocalBinary: boolean;
+  isRepoLocalRuntime: boolean;
   checkout: FrameworkCheckout | null;
   thisBin: string;
 };
 
 export function findFrameworkCheckout(startDir: string): FrameworkCheckout | null;
 
+export function isPathInside(baseDir: string, targetPath: string): boolean;
+
 export function resolveFrameworkBinaryContext(options: {
   cwd: string;
   thisBin: string;

package/bin/runtime-context.js

@@ -21,6 +21,7 @@ import path from "node:path";
  * @typedef {{
  *   inFrameworkCheckout: boolean;
  *   isRepoLocalBinary: boolean;
+ *   isRepoLocalRuntime: boolean;
  *   checkout: FrameworkCheckout | null;
  *   thisBin: string;
  * }} FrameworkBinaryContext
@@ -55,6 +56,16 @@ export function findFrameworkCheckout(startDir) {
   }
 }
 
+/**
+ * @param {string} baseDir
+ * @param {string} targetPath
+ * @returns {boolean}
+ */
+export function isPathInside(baseDir, targetPath) {
+  const rel = path.relative(path.resolve(baseDir), path.resolve(targetPath));
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
 /**
  * @param {FrameworkBinaryContextOptions} options
  * @returns {FrameworkBinaryContext}
@@ -67,6 +78,7 @@ export function resolveFrameworkBinaryContext(options) {
     return {
       inFrameworkCheckout: false,
       isRepoLocalBinary: false,
+      isRepoLocalRuntime: false,
       checkout: null,
       thisBin,
     };
@@ -75,6 +87,7 @@ export function resolveFrameworkBinaryContext(options) {
   return {
     inFrameworkCheckout: true,
     isRepoLocalBinary: path.resolve(checkout.repoBin) === thisBin,
+    isRepoLocalRuntime: isPathInside(checkout.packageRoot, thisBin),
     checkout,
     thisBin,
   };

package/bin/runtime-watch.d.ts

@@ -0,0 +1,26 @@
+export type WatchedRuntimeSnapshotFile = {
+  path: string;
+  sha256: string;
+  size_bytes: number;
+};
+
+export type WatchedRuntimeSnapshot = {
+  watchedPaths: string[];
+  files: WatchedRuntimeSnapshotFile[];
+  snapshotHash: string;
+};
+
+export type WatchedRuntimeSnapshotComparison = {
+  ok: boolean;
+  changedPaths: string[];
+};
+
+export function getWatchedRuntimePathsForPackage(packageName: string): string[];
+export function collectWatchedRuntimeSnapshot(
+  packageDir: string,
+  watchedPaths: string[],
+): Promise<WatchedRuntimeSnapshot>;
+export function compareWatchedRuntimeSnapshots(
+  recordedSnapshot: WatchedRuntimeSnapshot,
+  currentSnapshot: WatchedRuntimeSnapshot,
+): WatchedRuntimeSnapshotComparison;

package/bin/runtime-watch.js

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+
+const WATCHED_RUNTIME_PATHS = {
+  agentplane: [
+    "src",
+    "bin/agentplane.js",
+    "bin/dist-guard.js",
+    "bin/runtime-context.js",
+    "bin/stale-dist-policy.js",
+  ],
+  "@agentplaneorg/core": ["src"],
+};
+
+function normalizePath(value) {
+  return value.split(path.sep).join("/");
+}
+
+async function exists(targetPath) {
+  try {
+    await stat(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function walkFiles(targetPath) {
+  const targetStat = await stat(targetPath);
+  if (targetStat.isFile()) return [targetPath];
+  if (!targetStat.isDirectory()) return [];
+
+  const entries = await readdir(targetPath, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries.toSorted((a, b) => a.name.localeCompare(b.name))) {
+    const childPath = path.join(targetPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walkFiles(childPath)));
+      continue;
+    }
+    if (entry.isFile()) files.push(childPath);
+  }
+  return files;
+}
+
+function fileHash(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function snapshotHash(files) {
+  const digest = createHash("sha256");
+  for (const file of files) {
+    digest.update(file.path);
+    digest.update(":");
+    digest.update(file.sha256);
+    digest.update("\n");
+  }
+  return digest.digest("hex");
+}
+
+export function getWatchedRuntimePathsForPackage(packageName) {
+  return [...(WATCHED_RUNTIME_PATHS[packageName] ?? ["src"])];
+}
+
+export async function collectWatchedRuntimeSnapshot(packageDir, watchedPaths) {
+  const normalizedWatchedPaths = [...new Set(watchedPaths.map((entry) => normalizePath(entry)))];
+
+  const absoluteFiles = [];
+  for (const watchedPath of normalizedWatchedPaths) {
+    const absolutePath = path.join(packageDir, watchedPath);
+    if (!(await exists(absolutePath))) continue;
+    absoluteFiles.push(...(await walkFiles(absolutePath)));
+  }
+
+  const uniqueAbsoluteFiles = [...new Set(absoluteFiles)].toSorted((a, b) => a.localeCompare(b));
+  const files = [];
+  for (const absolutePath of uniqueAbsoluteFiles) {
+    const content = await readFile(absolutePath);
+    files.push({
+      path: normalizePath(path.relative(packageDir, absolutePath)),
+      sha256: fileHash(content),
+      size_bytes: content.byteLength,
+    });
+  }
+
+  return {
+    watchedPaths: normalizedWatchedPaths,
+    files,
+    snapshotHash: snapshotHash(files),
+  };
+}
+
+function snapshotFileMap(snapshot) {
+  return new Map(snapshot.files.map((file) => [file.path, file.sha256]));
+}
+
+export function compareWatchedRuntimeSnapshots(recordedSnapshot, currentSnapshot) {
+  if (
+    recordedSnapshot.snapshotHash === currentSnapshot.snapshotHash &&
+    recordedSnapshot.files.length === currentSnapshot.files.length
+  ) {
+    return { ok: true, changedPaths: [] };
+  }
+
+  const recordedMap = snapshotFileMap(recordedSnapshot);
+  const currentMap = snapshotFileMap(currentSnapshot);
+  const changedPaths = [...new Set([...recordedMap.keys(), ...currentMap.keys()])]
+    .filter((filePath) => recordedMap.get(filePath) !== currentMap.get(filePath))
+    .toSorted((a, b) => a.localeCompare(b));
+
+  return {
+    ok: changedPaths.length === 0,
+    changedPaths,
+  };
+}

package/bin/stale-dist-policy.d.ts

@@ -0,0 +1,6 @@
+export type StaleDistPolicy = {
+  mode: "warn_and_run" | "strict";
+  reason: "read_only_diagnostic" | "default";
+};
+
+export function classifyStaleDistPolicy(argv?: string[]): StaleDistPolicy;

package/bin/stale-dist-policy.js

@@ -0,0 +1,44 @@
+function normalizeArgs(argv) {
+  return argv
+    .slice(2)
+    .map((value) => String(value ?? "").trim())
+    .filter(Boolean);
+}
+
+function isHelpOrVersionCommand(args) {
+  return (
+    args.length === 0 ||
+    args[0] === "--help" ||
+    args[0] === "-h" ||
+    args[0] === "--version" ||
+    args[0] === "-v" ||
+    args[0] === "help"
+  );
+}
+
+function isConfigInspectionCommand(args) {
+  return args[0] === "config" && args[1] === "show";
+}
+
+function isTaskInspectionCommand(args) {
+  return args[0] === "task" && ["list", "show", "verify-show"].includes(args[1] ?? "");
+}
+
+function isRoleOrQuickstartCommand(args) {
+  return args[0] === "quickstart" || args[0] === "role";
+}
+
+export function classifyStaleDistPolicy(argv = process.argv) {
+  const args = normalizeArgs(argv);
+  if (
+    args[0] === "doctor" ||
+    (args[0] === "runtime" && args[1] === "explain") ||
+    isHelpOrVersionCommand(args) ||
+    isRoleOrQuickstartCommand(args) ||
+    isConfigInspectionCommand(args) ||
+    isTaskInspectionCommand(args)
+  ) {
+    return { mode: "warn_and_run", reason: "read_only_diagnostic" };
+  }
+  return { mode: "strict", reason: "default" };
+}