@agent-native/core 0.121.2 → 0.122.1

package/src/cli/template-sync.ts

@@ -0,0 +1,1004 @@
+/**
+ * `agent-native template` — pull later upstream template changes into an app
+ * that was generated from a first-party template.
+ *
+ * The model is a real 3-way merge:
+ *
+ *   base   = the pristine upstream tree the app was generated from
+ *            (stored as a git ref, see template-baseline.ts)
+ *   theirs = the same template re-materialized at a newer ref, through the
+ *            exact transform pipeline `create` runs
+ *   ours   = the app's working tree
+ *
+ * Materialization fidelity is the whole feature: any divergence from what
+ * `create` produced turns into phantom conflicts on every sync, so this file
+ * reuses `create.ts`'s own transforms rather than reimplementing them.
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  detectWorkspace,
+  _REPO,
+  _TEMPLATES_DIR,
+  _appTitleForScaffold,
+  _copyDir,
+  _downloadGitHubSubdir,
+  _findLocalTemplate,
+  _fixPackageJsonName,
+  _fixWebManifestName,
+  _getCoreDependencyVersion,
+  _getCorePackageVersion,
+  _getDispatchDependencyVersion,
+  _getGitHubTemplateRefCandidates,
+  _getToolkitDependencyVersion,
+  _localTemplateSourceKind,
+  _normalizeTemplateName,
+  _postProcessStandalone,
+  _renameGitignore,
+  _replacePlaceholders,
+  _rewriteNetlifyToml,
+  _rewriteTrackingAppId,
+  _shouldSkipScaffoldEntry,
+  _templateSourceName,
+} from "./create.js";
+import {
+  appDirtyPaths,
+  baselineDescription,
+  baselineExists,
+  clearBaseline,
+  materializeBaseline,
+  promoteBaseline,
+  resolveBaselineStore,
+  writeBaseline,
+} from "./template-baseline.js";
+import { workspacifyApp } from "./workspacify.js";
+
+export interface TemplateIO {
+  out: (message: string) => void;
+  err: (message: string) => void;
+}
+
+const defaultIO: TemplateIO = {
+  out: (message) => console.log(message),
+  err: (message) => console.error(message),
+};
+
+const CONFLICT_MARKER = "<<<<<<<";
+
+/** Never merged: user secrets, lockfiles, generated output, personal memory. */
+const NEVER_TOUCH_NAMES = new Set([
+  ".git",
+  "learnings.md",
+  "pnpm-lock.yaml",
+  "package-lock.json",
+  "yarn.lock",
+  "bun.lockb",
+]);
+
+export interface TemplateProvenance {
+  template?: string;
+  frameworkSkills?: string;
+  templateRef?: string;
+  templateSource?: "github" | "bundled" | "local-checkout";
+  coreVersion?: string;
+  shape?: "workspace" | "standalone";
+}
+
+export interface AppTarget {
+  appDir: string;
+  appName: string;
+  shape: "workspace" | "standalone";
+  workspaceRoot?: string;
+  workspaceCoreName?: string;
+  provenance: TemplateProvenance;
+}
+
+export interface MaterializeOptions {
+  appName: string;
+  template: string;
+  /** Git ref to fetch from, or null to use the bundled/local template copy. */
+  ref: string | null;
+  shape: "workspace" | "standalone";
+  workspaceRoot?: string;
+  workspaceCoreName?: string;
+  destDir?: string;
+}
+
+export interface MaterializeResult {
+  dir: string;
+  ref: string;
+  source: "github" | "bundled" | "local-checkout";
+}
+
+export interface TemplateMergeResult {
+  added: string[];
+  updated: string[];
+  deleted: string[];
+  conflicted: string[];
+  manual: string[];
+  keptLocal: string[];
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Materialization
+ * ───────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Reproduce, in a temp directory, the exact bytes `create` would have written
+ * for this (template, ref, app name, shape, workspace scope).
+ */
+export async function materializeTemplate(
+  opts: MaterializeOptions,
+): Promise<MaterializeResult> {
+  const dest =
+    opts.destDir ?? fs.mkdtempSync(path.join(os.tmpdir(), "an-template-new-"));
+  fs.mkdirSync(dest, { recursive: true });
+
+  const resolved = _normalizeTemplateName(opts.template);
+  const sourceTemplate = _templateSourceName(resolved);
+  const fallbackRef = _getGitHubTemplateRefCandidates()[0];
+
+  let usedRef: string;
+  let source: MaterializeResult["source"];
+  if (opts.ref === null || resolved === "headless") {
+    const local = _findLocalTemplate(
+      resolved === "headless" ? "headless" : sourceTemplate,
+    );
+    if (!local) {
+      throw new Error(
+        `No local copy of the "${resolved}" template is available. Pass --to <ref> to fetch it from GitHub.`,
+      );
+    }
+    _copyDir(local, dest);
+    usedRef = opts.ref ?? fallbackRef ?? "unknown";
+    source = _localTemplateSourceKind(local);
+  } else {
+    usedRef = await _downloadGitHubSubdir(
+      _REPO,
+      `${_TEMPLATES_DIR}/${sourceTemplate}`,
+      dest,
+      [opts.ref],
+    );
+    source = "github";
+  }
+
+  const provenance = { templateRef: usedRef, templateSource: source };
+
+  if (opts.shape === "workspace") {
+    if (!opts.workspaceRoot || !opts.workspaceCoreName) {
+      throw new Error(
+        "Workspace apps need a workspace root and shared package name to materialize.",
+      );
+    }
+    _replacePlaceholders(
+      dest,
+      opts.appName,
+      _appTitleForScaffold(opts.appName),
+      path.basename(opts.workspaceRoot),
+    );
+    _rewriteTrackingAppId(dest, opts.appName, opts.template);
+    workspacifyApp({
+      appDir: dest,
+      appName: opts.appName,
+      templateName: opts.template,
+      workspaceRoot: opts.workspaceRoot,
+      workspaceCoreName: opts.workspaceCoreName,
+      coreDependencyVersion: _getCoreDependencyVersion(),
+      dispatchDependencyVersion: _getDispatchDependencyVersion(),
+      toolkitDependencyVersion: _getToolkitDependencyVersion(),
+    });
+    _fixPackageJsonName(dest, opts.appName, opts.template, {
+      ...provenance,
+      shape: "workspace",
+    });
+    _fixWebManifestName(dest, opts.appName, opts.template);
+    _rewriteNetlifyToml(dest, opts.appName, "workspace");
+    _renameGitignore(dest);
+  } else {
+    _postProcessStandalone(opts.appName, dest, opts.template, provenance);
+  }
+
+  return { dir: dest, ref: usedRef, source };
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Merge
+ * ───────────────────────────────────────────────────────────────────────── */
+
+export function isMergeExcluded(rel: string): boolean {
+  const segments = rel.split("/");
+  if (segments[0] === "changelog") return true;
+  for (const name of segments) {
+    if (!name || name === "." || name === "..") return true;
+    if (NEVER_TOUCH_NAMES.has(name)) return true;
+    if (name.startsWith(".env")) return true;
+    if (_shouldSkipScaffoldEntry(name)) return true;
+  }
+  return false;
+}
+
+export function listMergeableFiles(root: string): Set<string> {
+  const found = new Set<string>();
+  const walk = (dir: string, prefix: string): void => {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (isMergeExcluded(rel)) continue;
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) walk(path.join(dir, entry.name), rel);
+      else if (entry.isFile()) found.add(rel);
+    }
+  };
+  walk(root, "");
+  return found;
+}
+
+export function mergeTemplateTrees(
+  appDir: string,
+  baseDir: string,
+  theirsDir: string,
+  options: { dryRun?: boolean } = {},
+): TemplateMergeResult {
+  const result: TemplateMergeResult = {
+    added: [],
+    updated: [],
+    deleted: [],
+    conflicted: [],
+    manual: [],
+    keptLocal: [],
+  };
+  const paths = new Set<string>([
+    ...listMergeableFiles(baseDir),
+    ...listMergeableFiles(theirsDir),
+    ...listMergeableFiles(appDir),
+  ]);
+
+  for (const rel of Array.from(paths).sort()) {
+    const oursPath = path.join(appDir, rel);
+    if (isLocalSymlink(oursPath)) {
+      result.manual.push(`${rel} (local symlink)`);
+      continue;
+    }
+    const base = readFileOrNull(path.join(baseDir, rel));
+    const theirs = readFileOrNull(path.join(theirsDir, rel));
+    const ours = readFileOrNull(oursPath);
+
+    if (equalBuffers(base, theirs)) continue;
+
+    if (theirs === null) {
+      if (ours === null) continue;
+      if (equalBuffers(ours, base)) {
+        if (!options.dryRun) removeFile(oursPath);
+        result.deleted.push(rel);
+      } else {
+        result.keptLocal.push(rel);
+      }
+      continue;
+    }
+
+    if (ours === null) {
+      if (base === null) {
+        if (!options.dryRun) writeFile(oursPath, theirs);
+        result.added.push(rel);
+      } else {
+        result.manual.push(`${rel} (deleted locally, changed upstream)`);
+      }
+      continue;
+    }
+
+    if (equalBuffers(ours, theirs)) continue;
+    if (equalBuffers(ours, base)) {
+      if (!options.dryRun) writeFile(oursPath, theirs);
+      result.updated.push(rel);
+      continue;
+    }
+
+    if (!isTextBuffer(ours) || !isTextBuffer(theirs) || !isTextBuffer(base)) {
+      result.manual.push(`${rel} (binary changed on both sides)`);
+      continue;
+    }
+
+    const merged = gitMergeFile(ours, base ?? Buffer.alloc(0), theirs);
+    if (!merged) {
+      result.manual.push(`${rel} (merge failed)`);
+      continue;
+    }
+    if (!options.dryRun) writeFile(oursPath, merged.content);
+    if (merged.conflicts > 0) result.conflicted.push(rel);
+    else result.updated.push(rel);
+  }
+
+  return result;
+}
+
+function gitMergeFile(
+  ours: Buffer,
+  base: Buffer,
+  theirs: Buffer,
+): { content: Buffer; conflicts: number } | null {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "an-template-merge-"));
+  try {
+    const oursFile = path.join(dir, "ours");
+    const baseFile = path.join(dir, "base");
+    const theirsFile = path.join(dir, "theirs");
+    fs.writeFileSync(oursFile, ours);
+    fs.writeFileSync(baseFile, base);
+    fs.writeFileSync(theirsFile, theirs);
+    const res = spawnSync(
+      "git",
+      [
+        "merge-file",
+        "-p",
+        "-L",
+        "ours",
+        "-L",
+        "base",
+        "-L",
+        "theirs",
+        oursFile,
+        baseFile,
+        theirsFile,
+      ],
+      { maxBuffer: 64 * 1024 * 1024 },
+    );
+    if (res.status === null || res.status < 0) return null;
+    return { content: res.stdout as Buffer, conflicts: res.status };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Target resolution
+ * ───────────────────────────────────────────────────────────────────────── */
+
+export function readProvenance(appDir: string): TemplateProvenance {
+  const pkg = readJson(path.join(appDir, "package.json"));
+  const scaffold = (
+    pkg?.["agent-native"] as Record<string, unknown> | undefined
+  )?.scaffold;
+  if (!scaffold || typeof scaffold !== "object") return {};
+  return scaffold as TemplateProvenance;
+}
+
+export function resolveTargets(cwd: string, appArg?: string): AppTarget[] {
+  const workspace = detectWorkspace(cwd);
+
+  if (appArg) {
+    const candidates = [path.resolve(cwd, appArg)];
+    if (workspace)
+      candidates.push(path.join(workspace.workspaceRoot, "apps", appArg));
+    for (const candidate of candidates) {
+      if (fs.existsSync(path.join(candidate, "package.json"))) {
+        return [toTarget(candidate)];
+      }
+    }
+    throw new Error(`No app found for "${appArg}".`);
+  }
+
+  const appDir = findAppDir(cwd);
+  if (appDir) return [toTarget(appDir)];
+
+  if (workspace && path.resolve(cwd) === workspace.workspaceRoot) {
+    const appsDir = path.join(workspace.workspaceRoot, "apps");
+    if (fs.existsSync(appsDir)) {
+      const targets = fs
+        .readdirSync(appsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path.join(appsDir, entry.name))
+        .filter((dir) => fs.existsSync(path.join(dir, "package.json")))
+        .map((dir) => toTarget(dir));
+      if (targets.length > 0) return targets;
+    }
+  }
+
+  throw new Error(
+    "No Agent Native app found. Run from an app directory, or pass an app name from a workspace root.",
+  );
+}
+
+function toTarget(appDir: string): AppTarget {
+  const resolved = path.resolve(appDir);
+  const provenance = readProvenance(resolved);
+  const workspace = detectWorkspace(resolved);
+  const insideWorkspaceApps =
+    !!workspace &&
+    path.dirname(resolved) === path.join(workspace.workspaceRoot, "apps");
+  const shape =
+    provenance.shape ?? (insideWorkspaceApps ? "workspace" : "standalone");
+  return {
+    appDir: resolved,
+    appName: readAppName(resolved),
+    shape,
+    workspaceRoot: workspace?.workspaceRoot,
+    workspaceCoreName: workspace?.workspaceCoreName,
+    provenance,
+  };
+}
+
+function readAppName(appDir: string): string {
+  const pkg = readJson(path.join(appDir, "package.json"));
+  const name = typeof pkg?.name === "string" ? pkg.name : "";
+  return name || path.basename(appDir);
+}
+
+function findAppDir(cwd: string): string | null {
+  let dir = path.resolve(cwd);
+  for (let i = 0; i < 20; i++) {
+    const pkg = readJson(path.join(dir, "package.json"));
+    if (pkg) {
+      const agentNative = pkg["agent-native"] as
+        | Record<string, unknown>
+        | undefined;
+      if (agentNative?.workspaceCore) return null;
+      const deps = (pkg.dependencies ?? {}) as Record<string, string>;
+      const devDeps = (pkg.devDependencies ?? {}) as Record<string, string>;
+      if (
+        agentNative?.scaffold ||
+        deps["@agent-native/core"] ||
+        devDeps["@agent-native/core"]
+      ) {
+        return dir;
+      }
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Commands
+ * ───────────────────────────────────────────────────────────────────────── */
+
+export async function runTemplate(
+  args: string[],
+  io: TemplateIO = defaultIO,
+): Promise<number> {
+  const command = args[0];
+  if (
+    !command ||
+    command === "help" ||
+    command === "--help" ||
+    command === "-h"
+  ) {
+    io.out(templateUsage());
+    return command ? 0 : 1;
+  }
+
+  const rest = args.slice(1);
+  const appArg = positionalArgs(rest)[0];
+  const flags = {
+    to: flagValue(rest, "--to"),
+    ref: flagValue(rest, "--ref"),
+    template: flagValue(rest, "--template"),
+    dryRun: rest.includes("--dry-run"),
+    force: rest.includes("--force"),
+  };
+
+  let targets: AppTarget[];
+  try {
+    targets = resolveTargets(process.cwd(), appArg);
+  } catch (err) {
+    io.err(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  let exitCode = 0;
+  for (const target of targets) {
+    try {
+      const code = await runForTarget(command, target, flags, io);
+      if (code !== 0) exitCode = code;
+    } catch (err) {
+      io.err(
+        `${target.appName}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      exitCode = 1;
+    }
+  }
+  return exitCode;
+}
+
+interface TemplateFlags {
+  to?: string;
+  ref?: string;
+  template?: string;
+  dryRun: boolean;
+  force: boolean;
+}
+
+async function runForTarget(
+  command: string,
+  target: AppTarget,
+  flags: TemplateFlags,
+  io: TemplateIO,
+): Promise<number> {
+  switch (command) {
+    case "status":
+      return statusCommand(target, flags, io);
+    case "diff":
+      return diffCommand(target, flags, io);
+    case "sync":
+      return syncCommand(target, flags, io);
+    case "baseline":
+      return baselineCommand(target, flags, io);
+    case "accept":
+      return acceptCommand(target, io);
+    default:
+      io.err(`Unknown template command "${command}".`);
+      io.err(templateUsage());
+      return 1;
+  }
+}
+
+function templateName(target: AppTarget, flags: TemplateFlags): string {
+  const name = flags.template ?? target.provenance.template;
+  if (!name) {
+    throw new Error(
+      `${target.appName} has no recorded template. Pass --template <name> to record one.`,
+    );
+  }
+  return name;
+}
+
+async function statusCommand(
+  target: AppTarget,
+  flags: TemplateFlags,
+  io: TemplateIO,
+): Promise<number> {
+  const store = resolveBaselineStore(target.appDir);
+  const latest = _getGitHubTemplateRefCandidates()[0] ?? "(unknown)";
+  const lines = [
+    `${target.appName} (${target.shape})`,
+    `  template:       ${target.provenance.template ?? "(unrecorded)"}`,
+    `  recorded ref:   ${target.provenance.templateRef ?? "(unrecorded)"}`,
+    `  recorded source:${target.provenance.templateSource ? ` ${target.provenance.templateSource}` : " (unrecorded)"}`,
+    `  latest ref:     ${flags.to ?? latest}`,
+    `  baseline:       ${baselineDescription(store, "baseline") ?? "missing — run `agent-native template baseline`"}`,
+  ];
+  const pending = baselineDescription(store, "pending");
+  if (pending) lines.push(`  pending accept: ${pending}`);
+
+  const baseDir = materializeBaseline(store, "baseline");
+  if (baseDir) {
+    try {
+      const local = countLocallyModified(target.appDir, baseDir);
+      lines.push(`  locally modified files: ${local}`);
+      const targetRef = flags.to ?? target.provenance.templateRef ?? latest;
+      const theirs = await materializeForTarget(target, flags, targetRef);
+      try {
+        const changed = countUpstreamChanged(baseDir, theirs.dir);
+        lines.push(`  upstream-changed files: ${changed} (at ${theirs.ref})`);
+      } finally {
+        fs.rmSync(theirs.dir, { recursive: true, force: true });
+      }
+    } catch (err) {
+      lines.push(
+        `  upstream-changed files: unavailable (${err instanceof Error ? err.message.split("\n")[0] : String(err)})`,
+      );
+    } finally {
+      fs.rmSync(baseDir, { recursive: true, force: true });
+    }
+  }
+
+  io.out(lines.join("\n"));
+  return 0;
+}
+
+async function diffCommand(
+  target: AppTarget,
+  flags: TemplateFlags,
+  io: TemplateIO,
+): Promise<number> {
+  const store = resolveBaselineStore(target.appDir);
+  const baseDir = materializeBaseline(store, "baseline");
+  if (!baseDir) {
+    io.err(
+      `${target.appName}: no baseline recorded. Run \`agent-native template baseline ${target.appName}\` first.`,
+    );
+    return 1;
+  }
+  const theirs = await materializeForTarget(
+    target,
+    flags,
+    flags.to ?? _getGitHubTemplateRefCandidates()[0] ?? null,
+  );
+  try {
+    io.out(renderTreeDiff(baseDir, theirs.dir));
+    return 0;
+  } finally {
+    fs.rmSync(baseDir, { recursive: true, force: true });
+    fs.rmSync(theirs.dir, { recursive: true, force: true });
+  }
+}
+
+async function syncCommand(
+  target: AppTarget,
+  flags: TemplateFlags,
+  io: TemplateIO,
+): Promise<number> {
+  const store = resolveBaselineStore(target.appDir);
+  const baseDir = materializeBaseline(store, "baseline");
+  if (!baseDir) {
+    io.err(
+      `${target.appName}: no baseline recorded. Run \`agent-native template baseline ${target.appName}\` first.`,
+    );
+    return 1;
+  }
+
+  const dirty = appDirtyPaths(store);
+  if (dirty.length > 0 && !flags.force && !flags.dryRun) {
+    fs.rmSync(baseDir, { recursive: true, force: true });
+    io.err(
+      "Sync refused because the app directory has uncommitted changes. Review this diff and preserve your edits before syncing, or pass --force.",
+    );
+    for (const line of dirty.slice(0, 20)) io.err(`  ${line}`);
+    if (dirty.length > 20) io.err(`  … ${dirty.length - 20} more`);
+    return 1;
+  }
+
+  const theirs = await materializeForTarget(
+    target,
+    flags,
+    flags.to ?? _getGitHubTemplateRefCandidates()[0] ?? null,
+  );
+  try {
+    const result = mergeTemplateTrees(target.appDir, baseDir, theirs.dir, {
+      dryRun: flags.dryRun,
+    });
+    io.out(formatMergeResult(target, theirs.ref, result, flags.dryRun));
+
+    if (flags.dryRun) return 0;
+
+    const meta = {
+      template: templateName(target, flags),
+      templateRef: theirs.ref,
+      coreVersion: _getCorePackageVersion(),
+    };
+    if (result.conflicted.length === 0 && result.manual.length === 0) {
+      const written = writeBaseline(store, theirs.dir, "baseline", meta);
+      clearBaseline(store, "pending");
+      io.out(`Baseline advanced to ${written.location}.`);
+      reportRefspecs(written.configuredRefspecs, io);
+      return 0;
+    }
+
+    const written = writeBaseline(store, theirs.dir, "pending", meta);
+    reportRefspecs(written.configuredRefspecs, io);
+    io.out("");
+    io.out(
+      `Baseline not advanced — resolve the items above, then run:\n  agent-native template accept ${target.appName}`,
+    );
+    return 1;
+  } finally {
+    fs.rmSync(baseDir, { recursive: true, force: true });
+    fs.rmSync(theirs.dir, { recursive: true, force: true });
+  }
+}
+
+async function baselineCommand(
+  target: AppTarget,
+  flags: TemplateFlags,
+  io: TemplateIO,
+): Promise<number> {
+  const store = resolveBaselineStore(target.appDir);
+  const name = templateName(target, flags);
+  const ref =
+    flags.ref ??
+    target.provenance.templateRef ??
+    _getGitHubTemplateRefCandidates()[0] ??
+    null;
+  const materialized = await materializeTemplate({
+    appName: target.appName,
+    template: name,
+    ref: useLocalTemplate(target, ref) ? null : ref,
+    shape: target.shape,
+    workspaceRoot: target.workspaceRoot,
+    workspaceCoreName: target.workspaceCoreName,
+  });
+  try {
+    const written = writeBaseline(store, materialized.dir, "baseline", {
+      template: name,
+      templateRef: materialized.ref,
+      coreVersion: _getCorePackageVersion(),
+    });
+    backfillProvenance(target, name, materialized);
+    io.out(
+      `${target.appName}: baseline recorded at ${written.location} (${name} @ ${materialized.ref}).`,
+    );
+    reportRefspecs(written.configuredRefspecs, io);
+    return 0;
+  } finally {
+    fs.rmSync(materialized.dir, { recursive: true, force: true });
+  }
+}
+
+function acceptCommand(target: AppTarget, io: TemplateIO): number {
+  const store = resolveBaselineStore(target.appDir);
+  if (!baselineExists(store, "pending")) {
+    io.err(`${target.appName}: nothing to accept — no pending sync recorded.`);
+    return 1;
+  }
+  const markers = findConflictMarkers(target.appDir);
+  if (markers.length > 0) {
+    io.err(
+      `${target.appName}: accept refused because conflict markers remain. Resolve them first:`,
+    );
+    for (const file of markers.slice(0, 20)) io.err(`  ${file}`);
+    if (markers.length > 20) io.err(`  … ${markers.length - 20} more`);
+    return 1;
+  }
+  promoteBaseline(store, "pending", "baseline");
+  io.out(
+    `${target.appName}: baseline advanced to the last synced template tree.`,
+  );
+  return 0;
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Helpers
+ * ───────────────────────────────────────────────────────────────────────── */
+
+function useLocalTemplate(target: AppTarget, ref: string | null): boolean {
+  if (!ref) return true;
+  const source = target.provenance.templateSource;
+  if (source !== "bundled" && source !== "local-checkout") return false;
+  return ref === target.provenance.templateRef;
+}
+
+async function materializeForTarget(
+  target: AppTarget,
+  flags: TemplateFlags,
+  ref: string | null,
+): Promise<MaterializeResult> {
+  return materializeTemplate({
+    appName: target.appName,
+    template: templateName(target, flags),
+    ref: useLocalTemplate(target, ref) ? null : ref,
+    shape: target.shape,
+    workspaceRoot: target.workspaceRoot,
+    workspaceCoreName: target.workspaceCoreName,
+  });
+}
+
+function backfillProvenance(
+  target: AppTarget,
+  template: string,
+  materialized: MaterializeResult,
+): void {
+  const pkgPath = path.join(target.appDir, "package.json");
+  const pkg = readJson(pkgPath);
+  if (!pkg) return;
+  const agentNative =
+    pkg["agent-native"] && typeof pkg["agent-native"] === "object"
+      ? (pkg["agent-native"] as Record<string, unknown>)
+      : {};
+  const scaffold =
+    agentNative.scaffold && typeof agentNative.scaffold === "object"
+      ? (agentNative.scaffold as Record<string, unknown>)
+      : {};
+  agentNative.scaffold = {
+    ...scaffold,
+    template: scaffold.template ?? template,
+    templateRef: materialized.ref,
+    templateSource: materialized.source,
+    coreVersion: _getCorePackageVersion(),
+    shape: target.shape,
+  };
+  pkg["agent-native"] = agentNative;
+  fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+}
+
+function countLocallyModified(appDir: string, baseDir: string): number {
+  let count = 0;
+  for (const rel of listMergeableFiles(baseDir)) {
+    const base = readFileOrNull(path.join(baseDir, rel));
+    const ours = readFileOrNull(path.join(appDir, rel));
+    if (!equalBuffers(base, ours)) count++;
+  }
+  return count;
+}
+
+function countUpstreamChanged(baseDir: string, theirsDir: string): number {
+  const paths = new Set([
+    ...listMergeableFiles(baseDir),
+    ...listMergeableFiles(theirsDir),
+  ]);
+  let count = 0;
+  for (const rel of paths) {
+    const base = readFileOrNull(path.join(baseDir, rel));
+    const theirs = readFileOrNull(path.join(theirsDir, rel));
+    if (!equalBuffers(base, theirs)) count++;
+  }
+  return count;
+}
+
+function renderTreeDiff(baseDir: string, theirsDir: string): string {
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), "an-template-diff-"));
+  try {
+    const a = path.join(staging, "a");
+    const b = path.join(staging, "b");
+    copyMergeable(baseDir, a);
+    copyMergeable(theirsDir, b);
+    const res = spawnSync(
+      "git",
+      [
+        "diff",
+        "--no-index",
+        "--src-prefix=upstream-base/",
+        "--dst-prefix=upstream-new/",
+        "--",
+        "a",
+        "b",
+      ],
+      { cwd: staging, encoding: "utf-8", maxBuffer: 128 * 1024 * 1024 },
+    );
+    const output = (res.stdout ?? "").toString();
+    // Only the staging dir names leak into headers; content lines cannot
+    // contain the prefixed form, so this rewrite is safe.
+    return output.trim()
+      ? output
+          .replaceAll("upstream-base/a/", "upstream-base/")
+          .replaceAll("upstream-new/b/", "upstream-new/")
+      : "No upstream changes.";
+  } finally {
+    fs.rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+function copyMergeable(from: string, to: string): void {
+  fs.mkdirSync(to, { recursive: true });
+  for (const rel of listMergeableFiles(from)) {
+    const dest = path.join(to, rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(path.join(from, rel), dest);
+  }
+}
+
+function findConflictMarkers(appDir: string): string[] {
+  const hits: string[] = [];
+  for (const rel of listMergeableFiles(appDir)) {
+    const buf = readFileOrNull(path.join(appDir, rel));
+    if (!buf || !isTextBuffer(buf)) continue;
+    if (buf.toString("utf-8").includes(`${CONFLICT_MARKER} `)) hits.push(rel);
+  }
+  return hits;
+}
+
+function formatMergeResult(
+  target: AppTarget,
+  ref: string,
+  result: TemplateMergeResult,
+  dryRun: boolean,
+): string {
+  const lines = [
+    `${target.appName}: ${dryRun ? "would sync" : "synced"} template at ${ref}`,
+    `  added:      ${result.added.length}`,
+    `  updated:    ${result.updated.length}`,
+    `  deleted:    ${result.deleted.length}`,
+    `  conflicted: ${result.conflicted.length}`,
+  ];
+  for (const [label, items] of [
+    ["added", result.added],
+    ["updated", result.updated],
+    ["deleted", result.deleted],
+    ["conflicted", result.conflicted],
+    ["manual", result.manual],
+    ["kept local (deleted upstream)", result.keptLocal],
+  ] as const) {
+    if (items.length === 0) continue;
+    lines.push(`  ${label}:`);
+    for (const item of items) lines.push(`    ${item}`);
+  }
+  return lines.join("\n");
+}
+
+function reportRefspecs(configured: string[], io: TemplateIO): void {
+  if (configured.length === 0) return;
+  io.out(
+    `Configured ${configured.join(" and ")} to carry refs/agent-native/* so the baseline survives clone and push.`,
+  );
+}
+
+const VALUE_FLAGS = new Set(["--to", "--ref", "--template"]);
+
+/** A flag's value must never be mistaken for the [app] positional. */
+function positionalArgs(args: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg.startsWith("-")) {
+      if (VALUE_FLAGS.has(arg)) i++;
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+}
+
+function flagValue(args: string[], flag: string): string | undefined {
+  const index = args.indexOf(flag);
+  if (index >= 0 && args[index + 1]) return args[index + 1];
+  const inline = args.find((arg) => arg.startsWith(`${flag}=`));
+  return inline?.slice(flag.length + 1);
+}
+
+function readJson(file: string): Record<string, any> | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function readFileOrNull(file: string): Buffer | null {
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile()) return null;
+    return fs.readFileSync(file);
+  } catch {
+    return null;
+  }
+}
+
+function isLocalSymlink(file: string): boolean {
+  try {
+    return fs.lstatSync(file).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function writeFile(file: string, content: Buffer): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+}
+
+function removeFile(file: string): void {
+  fs.rmSync(file, { force: true });
+}
+
+function equalBuffers(a: Buffer | null, b: Buffer | null): boolean {
+  if (a === null || b === null) return a === b;
+  return a.equals(b);
+}
+
+function isTextBuffer(buf: Buffer | null): boolean {
+  if (buf === null) return true;
+  const isUtf8 = (Buffer as unknown as { isUtf8?: (b: Buffer) => boolean })
+    .isUtf8;
+  if (isUtf8) return isUtf8(buf) && !buf.includes(0);
+  return !buf.includes(0);
+}
+
+function templateUsage(): string {
+  return [
+    "agent-native template <command> [app] [options]",
+    "",
+    "Pull later upstream first-party template changes into a generated app",
+    "with a real 3-way merge against the tree it was scaffolded from.",
+    "",
+    "Commands:",
+    "  status [app]            Recorded ref, latest ref, baseline health, change counts",
+    "  diff [app] [--to <ref>] Unified diff of what upstream changed (read-only)",
+    "  sync [app] [--to <ref>] 3-way merge upstream changes into the app",
+    "                          [--dry-run] [--force]",
+    "  baseline [app]          Record a baseline for an app scaffolded before",
+    "                          provenance existed [--ref <ref>] [--template <name>]",
+    "  accept [app]            Advance the baseline after resolving conflicts",
+    "",
+    "With no [app], operates on the current app, or on every app in a workspace",
+    "when run from the workspace root. --to defaults to the ref matching the",
+    "installed @agent-native/core, so `agent-native upgrade` then",
+    "`agent-native template sync` is the coherent story.",
+  ].join("\n");
+}