@agent-native/core 0.121.2 → 0.122.1

package/corpus/core/src/checkpoints/route-match.ts

@@ -0,0 +1,13 @@
+/**
+ * The framework mount shim normally rewrites `event.path` to the mount-relative
+ * remainder ("/restore"), but it falls back to the unstripped request path when
+ * `event.url` is read-only on the host runtime. Accept both so a restore POST
+ * never silently 405s.
+ */
+export function isCheckpointRestorePath(path: string | undefined): boolean {
+  if (!path) return false;
+  return (
+    /(^|\/)checkpoints\/restore(?:[/?]|$)/.test(path) ||
+    /^\/?restore(?:[/?]|$)/.test(path)
+  );
+}

package/corpus/core/src/cli/create.ts

@@ -637,7 +637,7 @@ async function scaffoldOneAppIntoWorkspace(
   );
 
   try {
-    await scaffoldAppTemplate(appDir, templateName);
+    const resolution = await scaffoldAppTemplate(appDir, templateName);
     replacePlaceholders(
       appDir,
       appName,
@@ -655,7 +655,10 @@ async function scaffoldOneAppIntoWorkspace(
       dispatchDependencyVersion: getDispatchDependencyVersion(),
       toolkitDependencyVersion: getToolkitDependencyVersion(),
     });
-    fixPackageJsonName(appDir, appName, templateName);
+    fixPackageJsonName(appDir, appName, templateName, {
+      ...resolution,
+      shape: "workspace",
+    });
     fixWebManifestName(appDir, appName, templateName);
     rewriteNetlifyToml(appDir, appName, "workspace");
     renameGitignore(appDir);
@@ -736,9 +739,9 @@ async function createStandaloneApp(
       : `Downloading the ${template} template from GitHub...`,
   );
   try {
-    await scaffoldAppTemplate(targetDir, template);
+    const resolution = await scaffoldAppTemplate(targetDir, template);
     s.message(`Setting up ${name}…`);
-    postProcessStandalone(name, targetDir, template);
+    postProcessStandalone(name, targetDir, template, resolution);
     s.stop("App created!");
   } catch (err: any) {
     s.stop("Failed to create app.");
@@ -789,6 +792,17 @@ function cleanupOnFailure(targetDir: string): void {
  * Shared scaffolding helpers
  * ───────────────────────────────────────────────────────────────────────── */
 
+/** Where a scaffolded template's bytes came from, recorded so
+ *  `agent-native template sync` can reproduce them later. */
+export interface ScaffoldTemplateResolution {
+  templateRef?: string;
+  templateSource?: "github" | "bundled" | "local-checkout";
+}
+
+export interface ScaffoldProvenance extends ScaffoldTemplateResolution {
+  shape?: "workspace" | "standalone";
+}
+
 /**
  * Scaffold a single app template into `targetDir`. Resolves:
  *   - "headless" / legacy "blank" → bundled action-first template
@@ -799,7 +813,7 @@ function cleanupOnFailure(targetDir: string): void {
 async function scaffoldAppTemplate(
   targetDir: string,
   template: string,
-): Promise<void> {
+): Promise<ScaffoldTemplateResolution> {
   fs.mkdirSync(path.dirname(targetDir), { recursive: true });
 
   // Normalize legacy / renamed aliases.
@@ -814,13 +828,16 @@ async function scaffoldAppTemplate(
       );
     }
     copyDir(headlessDir, targetDir);
-    return;
+    return {
+      templateSource: "bundled",
+      templateRef: getGitHubTemplateRefCandidates()[0],
+    };
   }
 
   if (resolved.startsWith("github:")) {
     const repo = resolved.slice("github:".length);
     await downloadGitHubRepo(repo, targetDir);
-    return;
+    return {};
   }
 
   if (!getTemplate(resolved)) {
@@ -836,13 +853,29 @@ async function scaffoldAppTemplate(
   const localTemplate = findLocalTemplate(sourceTemplate);
   if (localTemplate) {
     copyDir(localTemplate, targetDir);
-  } else {
-    await downloadGitHubSubdir(
-      REPO,
-      `${TEMPLATES_DIR}/${sourceTemplate}`,
-      targetDir,
-    );
+    return {
+      templateSource: localTemplateSourceKind(localTemplate),
+      templateRef: getGitHubTemplateRefCandidates()[0],
+    };
   }
+  const templateRef = await downloadGitHubSubdir(
+    REPO,
+    `${TEMPLATES_DIR}/${sourceTemplate}`,
+    targetDir,
+  );
+  return { templateSource: "github", templateRef };
+}
+
+/** A template dir inside the installed core package ships with the CLI;
+ *  anything above it belongs to a framework checkout. */
+function localTemplateSourceKind(
+  localTemplate: string,
+): "bundled" | "local-checkout" {
+  const packageRoot = path.resolve(__dirname, "../..");
+  const rel = path.relative(packageRoot, path.resolve(localTemplate));
+  return rel && !rel.startsWith("..") && !path.isAbsolute(rel)
+    ? "bundled"
+    : "local-checkout";
 }
 
 function templateSourceName(name: string): string {
@@ -1000,6 +1033,17 @@ async function scaffoldRequiredPackages(
             }
           }
         }
+        // These packages' `exports` maps point at `./dist/*`, and `dist/` is
+        // gitignored (never committed), so a scaffolded workspace must build
+        // it on install. pnpm always runs `prepare` for workspace packages,
+        // unlike `postinstall`, so this is the reliable hook.
+        if (
+          pkg.scripts &&
+          typeof pkg.scripts.build === "string" &&
+          !pkg.scripts.prepare
+        ) {
+          pkg.scripts.prepare = "npm run build";
+        }
         fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + "\n");
       } catch {}
     }
@@ -1039,12 +1083,16 @@ function postProcessStandalone(
   name: string,
   targetDir: string,
   templateName?: string,
+  resolution?: ScaffoldTemplateResolution,
 ): void {
   const appTitle = appTitleForScaffold(name);
   replacePlaceholders(targetDir, name, appTitle);
   rewriteTrackingAppId(targetDir, name, templateName);
   rewriteAgentChatAppId(targetDir, name, templateName);
-  fixPackageJsonName(targetDir, name, templateName);
+  fixPackageJsonName(targetDir, name, templateName, {
+    ...resolution,
+    shape: "standalone",
+  });
   fixWebManifestName(targetDir, name, templateName);
   rewriteNetlifyToml(targetDir, name, "standalone");
 
@@ -1393,6 +1441,19 @@ export {
   startShapePromptOptions as _startShapePromptOptions,
   shouldSkipScaffoldEntry as _shouldSkipScaffoldEntry,
   tarExtractArgs as _tarExtractArgs,
+  downloadGitHubSubdir as _downloadGitHubSubdir,
+  findLocalTemplate as _findLocalTemplate,
+  templateSourceName as _templateSourceName,
+  normalizeTemplateName as _normalizeTemplateName,
+  appTitleForScaffold as _appTitleForScaffold,
+  replacePlaceholders as _replacePlaceholders,
+  rewriteTrackingAppId as _rewriteTrackingAppId,
+  rewriteAgentChatAppId as _rewriteAgentChatAppId,
+  fixWebManifestName as _fixWebManifestName,
+  copyDir as _copyDir,
+  localTemplateSourceKind as _localTemplateSourceKind,
+  REPO as _REPO,
+  TEMPLATES_DIR as _TEMPLATES_DIR,
 };
 
 /* ─────────────────────────────────────────────────────────────────────────
@@ -1479,13 +1540,17 @@ async function downloadAndExtract(
   }
 }
 
+/** Resolves to the ref that actually succeeded so callers can record it. */
 async function downloadGitHubSubdir(
   repo: string,
   subdir: string,
   targetDir: string,
-): Promise<void> {
+  refOverride?: string[],
+): Promise<string> {
   validateRepoName(repo);
-  const refs = getGitHubTemplateRefCandidates();
+  const refs = refOverride?.length
+    ? refOverride
+    : getGitHubTemplateRefCandidates();
   if (refs.length === 0) {
     throw new Error(
       "Cannot download first-party scaffold files without a versioned @agent-native/core package.",
@@ -1510,7 +1575,7 @@ async function downloadGitHubSubdir(
         );
       }
       copyDir(srcDir, targetDir);
-      return;
+      return ref;
     } catch (err) {
       errors.push(
         `  ${ref}: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
@@ -1678,6 +1743,7 @@ function fixPackageJsonName(
   appDir: string,
   name: string,
   templateName?: string,
+  provenance?: ScaffoldProvenance,
 ): void {
   const pkgPath = path.join(appDir, "package.json");
   if (!fs.existsSync(pkgPath)) return;
@@ -1706,9 +1772,18 @@ function fixPackageJsonName(
         !Array.isArray(pkg["agent-native"])
           ? pkg["agent-native"]
           : {};
+      const coreVersion = getCorePackageVersion();
       agentNative.scaffold = {
         template: trackingTemplateName(templateName),
         frameworkSkills: scaffoldGuidance,
+        ...(provenance?.templateRef
+          ? { templateRef: provenance.templateRef }
+          : {}),
+        ...(provenance?.templateSource
+          ? { templateSource: provenance.templateSource }
+          : {}),
+        ...(coreVersion ? { coreVersion } : {}),
+        ...(provenance?.shape ? { shape: provenance.shape } : {}),
       };
       pkg["agent-native"] = agentNative;
     }
@@ -2286,6 +2361,19 @@ function shouldSkipScaffoldEntry(name: string, srcPath?: string): boolean {
   ) {
     return true;
   }
+  // `.generated/bridge` is committed source, not a build artifact: the design
+  // app imports it at module load, so skipping it yields a workspace that 500s
+  // on every page. Everything else under `.generated` is regenerated at dev time.
+  if (pathParts?.at(-2) === ".generated") {
+    return name !== "bridge";
+  }
+  if (
+    name === ".generated" &&
+    srcPath &&
+    fs.existsSync(path.join(srcPath, "bridge"))
+  ) {
+    return false;
+  }
   if (
     name === "node_modules" ||
     name === ".agent-native" ||

package/corpus/core/src/cli/index.ts

@@ -884,6 +884,21 @@ switch (command) {
     break;
   }
 
+  case "template": {
+    // Pull later upstream first-party template changes into a generated app
+    // via a 3-way merge against the tree it was scaffolded from.
+    import("./template-sync.js")
+      .then(async (m) => {
+        const code = await m.runTemplate(args);
+        process.exit(code);
+      })
+      .catch((err) => {
+        console.error(err?.message ?? err);
+        process.exit(1);
+      });
+    break;
+  }
+
   case "doctor": {
     // Scan app source for security-critical guard invariants (see
     // `agent-native doctor --help`). For dependency-pin health, see
@@ -1243,6 +1258,11 @@ Usage:
                                 skills, and typecheck. Prefer this over
                                 patching core/dispatch. 'upgrade check' is
                                 doctor-only.
+  agent-native template <cmd>   Pull later upstream template changes into an
+                                app generated from a first-party template, via
+                                a 3-way merge against the tree it was
+                                scaffolded from. cmds: status | diff | sync |
+                                baseline | accept. Run after 'upgrade'.
   agent-native add-app [name]   Add one or more apps to the current workspace
   agent-native workspace-dev    Start the multi-app workspace gateway
   agent-native deploy           Build & deploy every app in the workspace to

package/corpus/core/src/cli/template-baseline.ts

@@ -0,0 +1,410 @@
+/**
+ * Baseline store for `agent-native template`.
+ *
+ * A baseline is the pristine upstream tree an app was generated from — the
+ * "base" side of the 3-way merge. It is stored as a git ref under
+ * `refs/agent-native/template-baseline/<app-path>` so it never shows up as
+ * working-tree files, and as a gzipped tar under `.agent-native/` only when
+ * the app is not inside a git repository at all.
+ *
+ * Every git operation here is plumbing driven by a throwaway `GIT_INDEX_FILE`
+ * and an out-of-tree `--work-tree`. Nothing in this file may move HEAD, touch
+ * the user's index, or write into their working tree.
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type BaselineSlot = "baseline" | "pending";
+
+export interface BaselineStore {
+  appDir: string;
+  /** Absolute `.git` directory, or null when the app is not in a repo. */
+  gitDir: string | null;
+  /** Absolute work-tree root, or null when the app is not in a repo. */
+  repoRoot: string | null;
+  /** Repo-relative posix prefix the app lives at ("" when app === repo root). */
+  prefix: string;
+  /** Stable id used in ref names and tarball filenames. */
+  slug: string;
+}
+
+export interface BaselineWriteMeta {
+  template: string;
+  templateRef: string;
+  coreVersion?: string;
+}
+
+export interface BaselineWriteResult {
+  kind: "git-ref" | "tarball";
+  /** Ref name or tarball path. */
+  location: string;
+  /** Commit sha for git refs. */
+  commit?: string;
+  configuredRefspecs: string[];
+}
+
+const REF_NAMESPACE = "refs/agent-native";
+const GIT_IDENTITY = {
+  GIT_AUTHOR_NAME: "agent-native",
+  GIT_AUTHOR_EMAIL: "noreply@agent-native.com",
+  GIT_COMMITTER_NAME: "agent-native",
+  GIT_COMMITTER_EMAIL: "noreply@agent-native.com",
+};
+
+export function resolveBaselineStore(appDir: string): BaselineStore {
+  // git reports realpaths; comparing against a symlinked temp path (macOS
+  // /var → /private/var) would compute a nonsense repo-relative prefix.
+  const resolved = realpath(path.resolve(appDir));
+  const gitDir = findGitDir(resolved);
+  const repoRoot = gitDir ? findRepoRoot(resolved) : null;
+  const prefix =
+    repoRoot && repoRoot !== resolved
+      ? path.relative(repoRoot, resolved).split(path.sep).join("/")
+      : "";
+  return {
+    appDir: resolved,
+    gitDir,
+    repoRoot,
+    prefix,
+    slug: sanitizeRefPath(prefix || path.basename(resolved)),
+  };
+}
+
+export function baselineRefName(
+  store: BaselineStore,
+  slot: BaselineSlot,
+): string {
+  return `${REF_NAMESPACE}/template-${slot}/${store.slug}`;
+}
+
+export function baselineTarballPath(
+  store: BaselineStore,
+  slot: BaselineSlot,
+): string {
+  return path.join(
+    store.appDir,
+    ".agent-native",
+    `template-${slot}`,
+    `${path.basename(store.appDir)}.tar.gz`,
+  );
+}
+
+export function baselineExists(
+  store: BaselineStore,
+  slot: BaselineSlot,
+): boolean {
+  if (store.gitDir)
+    return revParse(store, baselineRefName(store, slot)) !== null;
+  return fs.existsSync(baselineTarballPath(store, slot));
+}
+
+export function baselineDescription(
+  store: BaselineStore,
+  slot: BaselineSlot,
+): string | null {
+  if (!store.gitDir) {
+    const file = baselineTarballPath(store, slot);
+    return fs.existsSync(file) ? file : null;
+  }
+  const ref = baselineRefName(store, slot);
+  const commit = revParse(store, ref);
+  if (!commit) return null;
+  const subject = git(store, ["log", "-1", "--format=%s", commit]).trim();
+  return `${ref} (${commit.slice(0, 12)}) ${subject}`;
+}
+
+/**
+ * Snapshot `sourceDir` into the baseline store. Writes through a temporary
+ * index and an out-of-tree work-tree so HEAD, the real index, and the working
+ * tree are untouched.
+ */
+export function writeBaseline(
+  store: BaselineStore,
+  sourceDir: string,
+  slot: BaselineSlot,
+  meta: BaselineWriteMeta,
+): BaselineWriteResult {
+  if (!store.gitDir) {
+    const file = baselineTarballPath(store, slot);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    execFileSync("tar", ["-czf", file, "-C", sourceDir, "."], {
+      stdio: "pipe",
+    });
+    return { kind: "tarball", location: file, configuredRefspecs: [] };
+  }
+
+  const stage = fs.mkdtempSync(path.join(os.tmpdir(), "an-template-baseline-"));
+  try {
+    const stageRoot = path.join(stage, "tree");
+    const target = store.prefix
+      ? path.join(stageRoot, ...store.prefix.split("/"))
+      : stageRoot;
+    fs.mkdirSync(target, { recursive: true });
+    copyPlainTree(sourceDir, target);
+
+    const indexFile = path.join(stage, "index");
+    const env = { ...process.env, ...GIT_IDENTITY, GIT_INDEX_FILE: indexFile };
+    // --force: the app's own .gitignore lives inside the staged tree and would
+    // otherwise drop scaffolded files from the baseline.
+    git(store, ["--work-tree", stageRoot, "add", "-A", "--force", "."], {
+      cwd: stageRoot,
+      env,
+    });
+    const tree = git(store, ["write-tree"], { cwd: stageRoot, env }).trim();
+
+    const ref = baselineRefName(store, slot);
+    const parent = revParse(store, ref);
+    const message = [
+      `agent-native template ${slot}: ${meta.template}`,
+      "",
+      `template: ${meta.template}`,
+      `templateRef: ${meta.templateRef}`,
+      `coreVersion: ${meta.coreVersion ?? "unknown"}`,
+      `path: ${store.prefix || "."}`,
+    ].join("\n");
+    const commit = git(
+      store,
+      ["commit-tree", tree, ...(parent ? ["-p", parent] : []), "-m", message],
+      { cwd: stageRoot, env },
+    ).trim();
+
+    git(store, ["update-ref", ref, commit, ...(parent ? [parent] : [])]);
+    return {
+      kind: "git-ref",
+      location: ref,
+      commit,
+      configuredRefspecs: parent ? [] : ensureBaselineRefspecs(store),
+    };
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
+  }
+}
+
+/** Point `slot` at whatever `from` currently points at. */
+export function promoteBaseline(
+  store: BaselineStore,
+  from: BaselineSlot,
+  to: BaselineSlot,
+): boolean {
+  if (!store.gitDir) {
+    const src = baselineTarballPath(store, from);
+    if (!fs.existsSync(src)) return false;
+    const dst = baselineTarballPath(store, to);
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    fs.copyFileSync(src, dst);
+    fs.rmSync(src, { force: true });
+    return true;
+  }
+  const commit = revParse(store, baselineRefName(store, from));
+  if (!commit) return false;
+  git(store, ["update-ref", baselineRefName(store, to), commit]);
+  git(store, ["update-ref", "-d", baselineRefName(store, from)]);
+  return true;
+}
+
+export function clearBaseline(store: BaselineStore, slot: BaselineSlot): void {
+  if (!store.gitDir) {
+    fs.rmSync(baselineTarballPath(store, slot), { force: true });
+    return;
+  }
+  if (revParse(store, baselineRefName(store, slot))) {
+    git(store, ["update-ref", "-d", baselineRefName(store, slot)]);
+  }
+}
+
+/**
+ * Extract a stored baseline into a fresh temp directory whose root is the app
+ * root. Returns null when the slot is empty. Callers own the returned dir.
+ */
+export function materializeBaseline(
+  store: BaselineStore,
+  slot: BaselineSlot,
+): string | null {
+  const out = fs.mkdtempSync(path.join(os.tmpdir(), "an-template-base-"));
+  try {
+    if (!store.gitDir) {
+      const file = baselineTarballPath(store, slot);
+      if (!fs.existsSync(file)) {
+        fs.rmSync(out, { recursive: true, force: true });
+        return null;
+      }
+      execFileSync("tar", ["-xzf", file, "-C", out], { stdio: "pipe" });
+      return out;
+    }
+
+    const ref = baselineRefName(store, slot);
+    if (!revParse(store, ref)) {
+      fs.rmSync(out, { recursive: true, force: true });
+      return null;
+    }
+    const tarPath = path.join(out, ".baseline.tar");
+    const args = ["archive", "--format=tar", "-o", tarPath, ref];
+    if (store.prefix) args.push("--", store.prefix);
+    git(store, args);
+    const strip = store.prefix ? store.prefix.split("/").length : 0;
+    execFileSync(
+      "tar",
+      [
+        "-xf",
+        tarPath,
+        "-C",
+        out,
+        ...(strip ? [`--strip-components=${strip}`] : []),
+      ],
+      { stdio: "pipe" },
+    );
+    fs.rmSync(tarPath, { force: true });
+    return out;
+  } catch (err) {
+    fs.rmSync(out, { recursive: true, force: true });
+    throw err;
+  }
+}
+
+/**
+ * Teach the repo's remote to carry `refs/agent-native/*` so baselines survive
+ * clone and push. Returns the refspecs it actually added.
+ */
+export function ensureBaselineRefspecs(store: BaselineStore): string[] {
+  if (!store.gitDir) return [];
+  const remotes = git(store, ["remote"])
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+  if (remotes.length === 0) return [];
+  const remote = remotes.includes("origin") ? "origin" : remotes[0]!;
+  const spec = "+refs/agent-native/*:refs/agent-native/*";
+  const added: string[] = [];
+  for (const key of ["fetch", "push"] as const) {
+    const existing = gitAllowFail(store, [
+      "config",
+      "--get-all",
+      `remote.${remote}.${key}`,
+    ]);
+    if (existing.split("\n").some((line) => line.trim() === spec)) continue;
+    git(store, ["config", "--add", `remote.${remote}.${key}`, spec]);
+    added.push(`remote.${remote}.${key}`);
+  }
+  return added;
+}
+
+/** Uncommitted changes under the app dir, as porcelain lines. */
+export function appDirtyPaths(store: BaselineStore): string[] {
+  if (!store.gitDir) return [];
+  const out = gitAllowFail(store, [
+    "status",
+    "--porcelain",
+    "--",
+    store.prefix || ".",
+  ]);
+  return out
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Internals
+ * ───────────────────────────────────────────────────────────────────────── */
+
+function git(
+  store: BaselineStore,
+  args: string[],
+  options: { cwd?: string; env?: NodeJS.ProcessEnv } = {},
+): string {
+  return execFileSync("git", ["--git-dir", store.gitDir!, ...args], {
+    // Without an explicit work tree, `--git-dir` makes git treat cwd as the
+    // work-tree root, which turns every sibling path into a phantom deletion.
+    cwd: options.cwd ?? store.repoRoot ?? store.appDir,
+    encoding: "utf-8",
+    env: options.env ?? { ...process.env, ...GIT_IDENTITY },
+    stdio: ["ignore", "pipe", "pipe"],
+    maxBuffer: 256 * 1024 * 1024,
+  });
+}
+
+function gitAllowFail(store: BaselineStore, args: string[]): string {
+  try {
+    return git(store, args);
+  } catch {
+    return "";
+  }
+}
+
+function revParse(store: BaselineStore, ref: string): string | null {
+  if (!store.gitDir) return null;
+  const out = gitAllowFail(store, ["rev-parse", "--verify", "--quiet", ref]);
+  return out.trim() || null;
+}
+
+function realpath(dir: string): string {
+  try {
+    return fs.realpathSync(dir);
+  } catch {
+    return dir;
+  }
+}
+
+function findGitDir(dir: string): string | null {
+  try {
+    return execFileSync("git", ["rev-parse", "--absolute-git-dir"], {
+      cwd: dir,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function findRepoRoot(dir: string): string | null {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: dir,
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Copy regular files and directories only. Symlinks are never part of a
+ *  baseline: they are agent-tool conveniences, not upstream content. */
+function copyPlainTree(src: string, dest: string): void {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) continue;
+    const from = path.join(src, entry.name);
+    const to = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === ".git") continue;
+      copyPlainTree(from, to);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(from, to);
+    }
+  }
+}
+
+/** Make each path segment safe for `git check-ref-format`. */
+export function sanitizeRefPath(value: string): string {
+  const segments = value
+    .split("/")
+    .map((segment) => sanitizeRefSegment(segment))
+    .filter(Boolean);
+  return segments.length > 0 ? segments.join("/") : "app";
+}
+
+function sanitizeRefSegment(segment: string): string {
+  let out = segment
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\u0000-\u0020\u007f~^:?*\[\\]/g, "-")
+    .replace(/\.\.+/g, "-")
+    .replace(/@\{/g, "-");
+  while (out.startsWith(".")) out = out.slice(1);
+  while (out.endsWith(".")) out = out.slice(0, -1);
+  if (out.endsWith(".lock")) out = `${out.slice(0, -".lock".length)}-lock`;
+  return out;
+}