@foldspace_npm/harness 0.1.10 → 0.1.12

package/src/upgrade.mjs

@@ -0,0 +1,469 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input } from "node:process";
+import { fileURLToPath } from "node:url";
+
+export const HARNESS_PACKAGE = "@foldspace_npm/harness";
+export const INSTRUCTION_IMPORT = `@node_modules/${HARNESS_PACKAGE}/CLAUDE.md`;
+export const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
+export const NPM_VIEW_TIMEOUT_MS = 2000;
+export const UPGRADE_NEXT = "Ask the user, then run foldspace upgrade --yes";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const instructionTemplatePath = path.join(
+  packageRoot,
+  "templates",
+  "agent-starter",
+  "CLAUDE.md",
+);
+const tokenPattern = /\{\{([A-Z0-9_]+)\}\}/g;
+
+export function resolveProjectDir(env = process.env, cwd = process.cwd()) {
+  return env.FOLDSPACE_PROJECT_DIR || cwd;
+}
+
+export function parseUpgradeArgs(argv) {
+  const flags = new Set();
+  for (const token of argv) {
+    if (token === "--check" || token === "--yes" || token === "--refresh-instructions") {
+      if (flags.has(token)) {
+        throw new Error(`option '${token}' was provided twice`);
+      }
+      flags.add(token);
+      continue;
+    }
+    throw new Error(`unknown option '${token}'`);
+  }
+  if (flags.has("--check") && flags.has("--yes")) {
+    throw new Error("options '--check' and '--yes' cannot be used together");
+  }
+  if (flags.has("--check") && flags.has("--refresh-instructions")) {
+    throw new Error(
+      "options '--check' and '--refresh-instructions' cannot be used together",
+    );
+  }
+  return {
+    checkOnly: flags.has("--check"),
+    yes: flags.has("--yes"),
+    refreshInstructions: flags.has("--refresh-instructions"),
+  };
+}
+
+export function normalizeVersion(spec) {
+  if (typeof spec !== "string" || !spec.trim()) return null;
+  const trimmed = spec.trim();
+  if (trimmed.startsWith("file:") || trimmed.startsWith("link:") || trimmed.startsWith("github:")) {
+    return null;
+  }
+  const match = trimmed.match(/^[~^]?(\d+\.\d+\.\d+)/);
+  return match ? match[1] : null;
+}
+
+export function compareVersions(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return 0;
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] > b[index]) return 1;
+    if (a[index] < b[index]) return -1;
+  }
+  return 0;
+}
+
+function parseSemver(value) {
+  const version = normalizeVersion(value);
+  if (!version) return null;
+  return version.split(".").map((part) => Number(part));
+}
+
+export function isBehind(current, latest) {
+  if (!current || !latest) return false;
+  return compareVersions(current, latest) < 0;
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function readPackageManifest(projectDir) {
+  const manifestPath = path.join(projectDir, "package.json");
+  if (!fs.existsSync(manifestPath)) return null;
+  try {
+    return readJson(manifestPath);
+  } catch {
+    return null;
+  }
+}
+
+export function isHarnessSourceTree(projectDir) {
+  const manifest = readPackageManifest(projectDir);
+  return Boolean(
+    manifest?.name === HARNESS_PACKAGE &&
+      fs.existsSync(path.join(projectDir, "templates", "agent-starter")),
+  );
+}
+
+export function readPinnedVersion(manifest) {
+  if (!manifest || typeof manifest !== "object") return null;
+  const spec =
+    manifest.devDependencies?.[HARNESS_PACKAGE] ||
+    manifest.dependencies?.[HARNESS_PACKAGE] ||
+    null;
+  return normalizeVersion(spec);
+}
+
+export function readInstalledVersion(projectDir) {
+  const installedPath = path.join(
+    projectDir,
+    "node_modules",
+    HARNESS_PACKAGE,
+    "package.json",
+  );
+  if (!fs.existsSync(installedPath)) return null;
+  try {
+    return normalizeVersion(readJson(installedPath).version);
+  } catch {
+    return null;
+  }
+}
+
+export function hasLiveInstructionImport(content) {
+  return typeof content === "string" && content.includes(INSTRUCTION_IMPORT);
+}
+
+export function instructionValuesFromProject(projectDir) {
+  const configPath = path.join(projectDir, "foldspace.dev.json");
+  if (!fs.existsSync(configPath)) {
+    throw new Error("foldspace.dev.json is required to refresh CLAUDE.md");
+  }
+  const config = readJson(configPath);
+  const targetName = config.defaultTarget;
+  const target = config.targets?.[targetName];
+  if (!target?.productId || !target?.agentApiName) {
+    throw new Error(
+      `foldspace.dev.json target '${targetName || "default"}' is missing productId or agentApiName`,
+    );
+  }
+  let domain = null;
+  if (typeof target.startUrl === "string") {
+    try {
+      domain = new URL(target.startUrl).hostname;
+    } catch {
+      domain = null;
+    }
+  }
+  if (!domain && Array.isArray(target.hosts) && target.hosts[0]) {
+    domain = String(target.hosts[0]).replace(/^\*\./, "");
+  }
+  if (!domain) {
+    throw new Error("Could not resolve the app domain from foldspace.dev.json");
+  }
+  const manifest = readPackageManifest(projectDir);
+  return {
+    DISPLAY_NAME: manifest?.name || path.basename(projectDir),
+    PRODUCT_ID: String(target.productId),
+    AGENT_API_NAME: String(target.agentApiName),
+    APP_DOMAIN: domain,
+  };
+}
+
+export function renderInstructionStub(values, template = fs.readFileSync(instructionTemplatePath, "utf8")) {
+  const rendered = template.replace(tokenPattern, (_match, key) => {
+    if (!(key in values)) {
+      throw new Error(`Missing value for {{${key}}} in CLAUDE.md stub`);
+    }
+    return values[key];
+  });
+  const unresolved = rendered.match(tokenPattern);
+  if (unresolved) {
+    throw new Error(`Unresolved template token ${unresolved[0]} in CLAUDE.md stub`);
+  }
+  return rendered;
+}
+
+export function refreshInstructionStub(projectDir, options = {}) {
+  const claudePath = path.join(projectDir, "CLAUDE.md");
+  const previous = fs.existsSync(claudePath)
+    ? fs.readFileSync(claudePath, "utf8")
+    : null;
+  const next = renderInstructionStub(
+    options.values || instructionValuesFromProject(projectDir),
+    options.template,
+  );
+  if (previous === next) {
+    return { written: false, backedUp: false, importPresent: true };
+  }
+  let backedUp = false;
+  if (previous !== null) {
+    fs.writeFileSync(path.join(projectDir, "CLAUDE.md.bak"), previous);
+    backedUp = true;
+  }
+  fs.writeFileSync(claudePath, next);
+  return { written: true, backedUp, importPresent: true };
+}
+
+function cachePath(projectDir) {
+  return path.join(projectDir, ".foldspace-dev", "harness-update.json");
+}
+
+function readCache(projectDir, now) {
+  const filePath = cachePath(projectDir);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    const cached = readJson(filePath);
+    if (typeof cached.checkedAt !== "number" || typeof cached.latest !== "string") {
+      return null;
+    }
+    if (now - cached.checkedAt > CACHE_TTL_MS) return null;
+    return cached;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(projectDir, latest, now) {
+  const dir = path.dirname(cachePath(projectDir));
+  fs.mkdirSync(dir, { recursive: true });
+  writeJson(cachePath(projectDir), { checkedAt: now, latest });
+}
+
+export function fetchLatestFromNpm(options = {}) {
+  const spawn = options.spawnSyncFn || spawnSync;
+  const result = spawn("npm", ["view", HARNESS_PACKAGE, "version"], {
+    encoding: "utf8",
+    timeout: options.timeoutMs ?? NPM_VIEW_TIMEOUT_MS,
+    env: options.env || process.env,
+  });
+  if (result.error || result.status !== 0) return null;
+  return normalizeVersion(result.stdout);
+}
+
+function nextAction(report) {
+  if (report.status === "outdated") {
+    return report.instructionsImport === false
+      ? `${UPGRADE_NEXT}. If CLAUDE.md is still a snapshot, also pass --refresh-instructions`
+      : UPGRADE_NEXT;
+  }
+  if (report.status === "upgraded") {
+    return "Run npm run build. Deploy only if product users should receive the rebuilt runtime.";
+  }
+  return null;
+}
+
+export function checkForUpdate(projectDir, options = {}) {
+  const env = options.env || process.env;
+  const now = options.now ?? Date.now();
+  const manifest = readPackageManifest(projectDir);
+  const harnessSource = isHarnessSourceTree(projectDir);
+  const pinned = harnessSource ? null : readPinnedVersion(manifest);
+  const installed = harnessSource
+    ? normalizeVersion(manifest?.version)
+    : readInstalledVersion(projectDir);
+  const claudePath = path.join(projectDir, "CLAUDE.md");
+  const instructionsImport = fs.existsSync(claudePath)
+    ? hasLiveInstructionImport(fs.readFileSync(claudePath, "utf8"))
+    : false;
+
+  const skipped =
+    options.skipCheck === true ||
+    (options.skipCheck !== false && env.FOLDSPACE_SKIP_UPDATE_CHECK === "1");
+  const consumer = !harnessSource && Boolean(pinned || installed);
+
+  let latest = null;
+  let status = "current";
+
+  if (!consumer) {
+    status = "not_a_consumer";
+  } else if (skipped) {
+    status = "check_skipped";
+  } else {
+    const cached = options.cache === false ? null : readCache(projectDir, now);
+    if (cached?.latest) {
+      latest = cached.latest;
+    } else {
+      const fetched =
+        typeof options.fetchLatest === "function"
+          ? options.fetchLatest()
+          : fetchLatestFromNpm(options);
+      latest = normalizeVersion(fetched);
+      if (latest && options.cache !== false) {
+        writeCache(projectDir, latest, now);
+      }
+    }
+    if (!latest) {
+      status = "check_skipped";
+    } else {
+      const outdated = isBehind(pinned, latest) || isBehind(installed, latest);
+      status = outdated ? "outdated" : "current";
+    }
+  }
+
+  const report = {
+    kind: "foldspace.cli.update",
+    package: HARNESS_PACKAGE,
+    pinned,
+    installed,
+    latest,
+    outdated: status === "outdated",
+    status,
+    instructionsImport,
+    next: null,
+  };
+  report.next = nextAction(report);
+  return report;
+}
+
+export function writeExactPin(projectDir, version) {
+  const manifestPath = path.join(projectDir, "package.json");
+  const manifest = readPackageManifest(projectDir);
+  if (!manifest) {
+    throw new Error(`package.json not found in ${projectDir}`);
+  }
+  if (manifest.dependencies?.[HARNESS_PACKAGE] !== undefined) {
+    manifest.dependencies[HARNESS_PACKAGE] = version;
+  } else {
+    manifest.devDependencies = manifest.devDependencies || {};
+    manifest.devDependencies[HARNESS_PACKAGE] = version;
+  }
+  writeJson(manifestPath, manifest);
+}
+
+function defaultInstall(projectDir) {
+  execFileSync("npm", ["install", "--ignore-scripts"], {
+    cwd: projectDir,
+    stdio: "inherit",
+    env: process.env,
+  });
+}
+
+function isInteractive(options = {}) {
+  if (typeof options.interactive === "boolean") return options.interactive;
+  return Boolean(options.stdin?.isTTY ?? input.isTTY);
+}
+
+function isAffirmative(value) {
+  const normalized = value.trim().toLowerCase();
+  return normalized === "" || normalized === "y" || normalized === "yes";
+}
+
+async function ask(question, options = {}) {
+  if (typeof options.ask === "function") return options.ask(question);
+  const rl = readline.createInterface({
+    input: options.stdin || input,
+    output: options.stderr || process.stderr,
+  });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+export async function runUpgrade(argv, options = {}) {
+  const parsed = parseUpgradeArgs(argv);
+  const projectDir = options.projectDir || resolveProjectDir(options.env);
+  const log = options.log || ((message) => {
+    console.error(message);
+  });
+
+  if (isHarnessSourceTree(projectDir) && (parsed.yes || parsed.refreshInstructions)) {
+    throw new Error(
+      "this directory is the harness source, not a consumer project",
+    );
+  }
+
+  const report = checkForUpdate(projectDir, options);
+
+  if (parsed.checkOnly || (!parsed.yes && !isInteractive(options) && !parsed.refreshInstructions)) {
+    return report;
+  }
+
+  if (parsed.refreshInstructions && !parsed.yes && report.status !== "outdated") {
+    const refreshed = refreshInstructionStub(projectDir, options);
+    return {
+      ...report,
+      status: refreshed.written ? "instructions_refreshed" : "current",
+      instructionsImport: true,
+      refreshed: refreshed.written,
+      backedUp: refreshed.backedUp,
+      next: refreshed.written
+        ? "Imported platform instructions from the installed harness."
+        : report.next,
+    };
+  }
+
+  if (report.status === "not_a_consumer") {
+    throw new Error(
+      `no ${HARNESS_PACKAGE} dependency found in ${projectDir}`,
+    );
+  }
+
+  if (parsed.yes && report.status === "check_skipped") {
+    throw new Error("cannot upgrade without a registry version");
+  }
+
+  let shouldInstall = parsed.yes && report.status === "outdated";
+  let shouldRefresh = parsed.refreshInstructions;
+
+  if (!parsed.yes && !parsed.checkOnly && isInteractive(options) && report.status === "outdated") {
+    log(
+      `${HARNESS_PACKAGE} ${report.pinned || report.installed} -> ${report.latest} is available`,
+    );
+    const answer = await ask("Upgrade the exact pin in this project? [Y/n] ", options);
+    shouldInstall = isAffirmative(answer);
+    if (!shouldInstall) {
+      return { ...report, status: "declined", next: UPGRADE_NEXT };
+    }
+    if (!report.instructionsImport && !shouldRefresh) {
+      const refreshAnswer = await ask(
+        "Replace CLAUDE.md with an import of the package instructions? [Y/n] ",
+        options,
+      );
+      shouldRefresh = isAffirmative(refreshAnswer);
+    }
+  }
+
+  if (!shouldInstall && !shouldRefresh) {
+    return report;
+  }
+
+  if (shouldInstall) {
+    if (!report.latest) {
+      throw new Error("cannot upgrade without a registry version");
+    }
+    writeExactPin(projectDir, report.latest);
+    const install = options.install || defaultInstall;
+    install(projectDir, report.latest);
+  }
+
+  let refreshed = { written: false, backedUp: false, importPresent: report.instructionsImport };
+  if (shouldRefresh) {
+    refreshed = refreshInstructionStub(projectDir, options);
+  }
+
+  const nextReport = {
+    ...report,
+    pinned: shouldInstall ? report.latest : report.pinned,
+    installed: shouldInstall ? report.latest : report.installed,
+    outdated: false,
+    status: shouldInstall ? "upgraded" : refreshed.written ? "instructions_refreshed" : report.status,
+    instructionsImport: shouldRefresh ? true : report.instructionsImport,
+    refreshed: refreshed.written,
+    backedUp: refreshed.backedUp,
+  };
+  nextReport.next = nextAction(nextReport);
+  return nextReport;
+}
+
+export function nagIfOutdated(report, write = (message) => console.error(message)) {
+  if (!report?.outdated) return;
+  write(
+    `foldspace: ${HARNESS_PACKAGE} ${report.pinned || report.installed} is behind ${report.latest}. ${UPGRADE_NEXT}.`,
+  );
+}