@turboforge/sync 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 turboforge-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# @turboforge/sync
+
+Keep a real monorepo aligned with its upstream template after the repo has already diverged.
+
+<p className="flex gap-2">
+  <a href="https://github.com/turboforge-dev/turboforge/actions/workflows/ci.yml" rel="noopener noreferrer">
+    <img alt="CI" src="https://github.com/turboforge-dev/turboforge/actions/workflows/ci.yml/badge.svg" />
+  </a>
+  <a href="https://codecov.io/gh/turboforge-dev/turboforge/tree/main/packages/forge-sync" rel="noopener noreferrer">
+    <img alt="codecov" src="https://codecov.io/gh/turboforge-dev/turboforge/graph/badge.svg?flag=forge-sync" />
+  </a>
+  <a href="https://npmjs.com/package/forge-sync" rel="noopener noreferrer">
+    <img alt="npm version" src="https://img.shields.io/npm/v/forge-sync" />
+  </a>
+  <a href="https://npmjs.com/package/forge-sync" rel="noopener noreferrer">
+    <img alt="npm downloads" src="https://img.shields.io/npm/d18m/forge-sync" />
+  </a>
+  <a href="https://npmjs.com/package/forge-sync" rel="noopener noreferrer">
+    <img alt="npm bundle size" src="https://img.shields.io/bundlephobia/minzip/forge-sync" />
+  </a>
+  <img alt="license" src="https://img.shields.io/npm/l/forge-sync" />
+</p>
+
+`@turboforge/sync` exists because templates are great right up until the moment your repo becomes real. After that, every upstream improvement turns into manual diffing, selective copy-paste, and a quiet fear of breaking local customizations.
+
+This package is the maintenance story inside Turboforge.
+
+Part of the Turboforge system:
+
+- use `@turboforge/sync` to keep the repo shape current
+- use [`@turboforge/cli-kit`](/c:/Users/G/web/open-source/turbo-forge/packages/cli-kit/README.md) to build the repo-aware commands around that workflow
+
+## Highlights
+
+- Pull upstream template changes into a repo that has already diverged.
+- Preview upgrades before applying them.
+- Resolve `package.json` conflicts with package-aware merge rules.
+
+## Why It Exists
+
+Templates stop helping once you have edited them.
+
+From that point on, most teams choose one of two bad options:
+
+- never pull improvements from the source template again
+- manually replay changes and hope nothing important was missed
+
+`@turboforge/sync` gives you a third option: treat template updates as an explicit sync workflow.
+
+## Real Example
+
+Your monorepo started from an internal template six months ago.
+
+Since then, the template added:
+
+- a stricter Biome config
+- improved release automation
+- better docs generation
+
+Your repo also added custom apps, custom package scripts, and local dependency choices.
+
+Instead of copying files by hand, `@turboforge/sync` fetches the upstream template, computes the diff from your last sync point, applies a patch, and resolves `package.json` conflicts with package-aware rules.
+
+## When To Use It
+
+- You maintain a repo that started from a template and still wants to inherit template improvements.
+- You want upgrades to be repeatable, reviewable, and less dependent on one maintainer's memory.
+- You need a system for "template drift," not just a one-time scaffold.
+
+## When Not To Use It
+
+- Your repo has no upstream template relationship.
+- You want to generate a new repo from scratch; use a starter for that.
+- You need a full project migration across unrelated architectures.
+
+## Installation
+
+To use it as a CLI tool in your project:
+
+```bash
+pnpm add -D @turboforge/sync
+```
+
+Or run it directly with `npx`:
+
+```bash
+npx @turboforge/sync
+```
+
+## Example
+
+Preview what changed upstream before touching the repo:
+
+```bash
+npx @turboforge/sync --dry-run
+```
+
+Exclude heavily customized paths during sync:
+
+```bash
+npx @turboforge/sync --exclude "apps/web,tooling/custom"
+```
+
+## Mental Model
+
+`@turboforge/sync` is not a scaffolder.
+
+It is a bridge between:
+
+- the template you started from
+- the customized repo you run today
+
+That is the core Turboforge bet: monorepos need an upgrade path, not just a bootstrap command.

package/dist/chunk-P3TVCV3U.mjs

@@ -0,0 +1,6 @@
+import{access as ye,readFile as H,writeFile as V}from"fs/promises";import{resolve as xe}from"path";import{exec as _,execFile as U}from"child_process";import{randomUUID as re}from"crypto";import{access as J,readFile as M,rename as oe,rm as ie,writeFile as se}from"fs/promises";import{dirname as G,join as W,parse as q,resolve as B}from"path";import{promisify as k}from"util";var f=k(_),y=k(U),A=async e=>{try{return await J(e),!0}catch(t){if(t.code==="ENOENT")return!1;throw t}},h=new Map,P=200,le=async(e,t)=>{let n=B(e),r=`${n}:${[...t].sort().join(",")}`;if(h.has(r))return h.get(r);let o=n,{root:i}=q(o);for(;;){for(let c of t)if(await A(W(o,c)))return h.set(r,o),h.size>P&&h.clear(),o;if(o===i)break;o=G(o)}return h.set(r,null),h.size>P&&h.clear(),null},ge=async(e,t={})=>{try{let n=await M(e,"utf-8");return JSON.parse(n)}catch(n){if(n.code==="ENOENT")return null;if(t.strict)throw n;return null}},pe=async(e,t={})=>{if(!await A(e))return null;try{let n=await import("./jiti-7K72E5ZK.mjs"),o=(n.createJiti?n.createJiti(process.cwd()):n.default(process.cwd()))(e);return o.default??o}catch{try{let n=await import(e);return n.default??n}catch(n){if(t.strict)throw/\.(ts|mts)$/.test(e)?new Error(`Failed to load TypeScript config at ${e}. Install 'jiti' to load TS configs. Original error: ${n}`):n;return null}}},L=(e,t)=>{if(typeof e!="object"||e===null||typeof t!="object"||t===null||Array.isArray(e)&&Array.isArray(t))return t;let n={...e};for(let r of Object.keys(t))r==="__proto__"||r==="constructor"||r==="prototype"||Object.hasOwn(t,r)&&(n[r]=r in e?L(e[r],t[r]):t[r]);return n};import{createWriteStream as Y}from"fs";import Z from"os";var w="\x1B[",S={gray:e=>`${w}90m${e}${w}39m`,blue:e=>`${w}34m${e}${w}39m`,yellow:e=>`${w}33m${e}${w}39m`,red:e=>`${w}31m${e}${w}39m`},F={debug:20,info:30,warn:40,error:50},N={debug:S.gray,info:S.blue,warn:S.yellow,error:S.red},T=e=>{let t=F[e.level],n=e.logFormat??"text",r=e.name,o=r?{debug:`${r}:DEBUG`,info:`${r}:INFO`,warn:`${r}:WARN`,error:`${e.name}:ERROR`}:{debug:"DEBUG",info:"INFO",warn:"WARN",error:"ERROR"},i=null,c=!1,m=process.stdout.isTTY&&!process.env.NO_COLOR||!!process.env.FORCE_COLOR;if(e.logFile)try{i=Y(e.logFile,{flags:"a"}),i.on("error",()=>{i=null})}catch{i=null}let p=()=>{if(!c&&(c=!0,i)){try{i.end()}catch{}i=null}};process.once("exit",p),process.once("SIGINT",()=>{p(),process.exit(0)}),process.once("SIGTERM",()=>{p(),process.exit(0)});let x=process.pid,v=Z.hostname(),l=(a,...s)=>{if(F[a]<t)return;let g=new Date().toISOString(),u=s.map(String).join(" "),d=n==="json"?JSON.stringify({ts:g,level:a,message:u,pid:x,hostname:v,name:r}):`[${g}] [${o[a]}] ${u}`,b=m&&N[a]?N[a](d):d;if((a==="warn"||a==="error"?process.stderr:process.stdout).write(`${b}
+`),i)try{i.write(`${d}
+`)}catch{i=null}};return{debug:(...a)=>l("debug",...a),info:(...a)=>l("info",...a),warn:(...a)=>l("warn",...a),error:(...a)=>l("error",...a),close:p}};import{resolveConflicts as j}from"git-json-resolver";var D=()=>Promise.all([f("git diff --quiet"),f("git diff --cached --quiet")]);var O=e=>e.replace(/[^a-zA-Z0-9._/-]/g,""),I=e=>{let t=e.replace(/\s+/g,"-").replace(/[^a-zA-Z0-9_-]/g,"");if(!t||!/^[a-zA-Z0-9_]/.test(t)||t.startsWith("-"))throw new Error(`Invalid remote name: "${e}". Remote names may only contain letters, numbers, underscore, and hyphen, and cannot start with '-'.`);return t},$=e=>e.replace(/[\r\n]/g,""),C=async({remoteName:e,baseRef:t,targetRef:n,exclusions:r,logger:o,maxRetries:i=3,errorLogs:c=[]},m=0)=>{if(m>i){o.warn(`Max patch recursion reached (${i}), stopping`);return}let p=`git diff ${t} ${e}/main -- ${r.join(" ")} .`;o.debug(`Running: ${p}`);let{stdout:x}=await y("git",["diff",t,`${e}/${n}`,"--",...r,"."],{encoding:"utf8"});await V(".template.patch",x),o.debug(`Patch written to .template.patch (${x.length} chars)`);try{o.debug("Applying patch with 3-way merge"),await f("git apply --3way --ignore-space-change --ignore-whitespace .template.patch",{encoding:"utf8"}),o.debug("Patch applied successfully")}catch(v){let l=v.stderr?.split(`
+`).filter(a=>a.startsWith("error"));o.debug(`Patch failed with ${l.length} errors`),l.forEach(a=>{let s=a.split(":")[1]?.trim();s&&(r.push(`:!${s}`),o.debug(`Added to exclusions: ${$(s)}`))}),c.push("Applied patch with errors: "),c.push({errorLines:l,exclusions:r}),c.push("^^^---Applied patch with errors"),l.length&&await C({remoteName:e,baseRef:t,targetRef:n,exclusions:r,logger:o,maxRetries:i,errorLogs:c},m+1)}},z=async e=>{await j({include:["package.json"],defaultStrategy:["merge","theirs"],rules:{name:["ours"],"devDependencies.*":["ignore-removed","theirs"],"dependencies.*":["ignore-removed","theirs"]},debug:e}),await j({include:["**/package.json"],exclude:["package.json","**/dist/**","**/.next/**"],defaultStrategy:["merge","non-empty","ours"],rules:{"devDependencies.*":["semver-max"],"dependencies.*":["semver-max"]},loggerConfig:{logDir:".logs2",levels:{stdout:[]}},plugins:["git-json-resolver-semver"],pluginConfig:{"git-json-resolver-semver":{preferValid:!0}},includeNonConflicted:!0,debug:e})},ve=async e=>{try{let c=await H(e,"utf8");return JSON.parse(c).lastSyncedCommit}catch{}let[{stdout:t},{stdout:n}]=await Promise.all([f("git log --reverse --format=%ai | head -n 1",{encoding:"utf8"}),f("git log --format=%H::%ai template/main",{encoding:"utf8"})]),r=new Date(t.trim()),i=n.trim().split(`
+`).map(c=>{let[m,p]=c.split("::");return{hash:m,date:new Date(p?.trim())}}).reverse().find(c=>c.date>=r);if(i)return console.info("Applying changes from ",i.hash," dated ",i.date),i.hash};import{writeFile as X}from"fs/promises";var K={logLevel:"info",dryRun:!1,templateUrl:"https://github.com/turboforge/forge-template.git",excludePaths:[],remoteName:"template",maxPatchRetries:3,backupDir:".forge-backup",skipCleanCheck:!1,targetRef:"main",metaFile:".forge-meta.json",baseRef:"",postSync:["pnpm install","pnpm biome check --write --no-errors-on-unmatched $(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.(ts|tsx|js|json)$' || true)"]},Q=[],Ce=async e=>{let{logLevel:t,skipCleanCheck:n,dryRun:r,remoteName:o,templateUrl:i,backupDir:c,baseRef:m,excludePaths:p,targetRef:x,metaFile:v,postSync:l,maxPatchRetries:a}=L(K,e),s=T({level:t});if(!m){s.error("\u274C Error: Base ref is required");return}if(n)s.info("Skipping git clean check");else try{await D(),s.info("Git tree is clean")}catch{s.error("\u274C Error: Please commit or stash your changes before upgrading.");return}r&&s.info("Dry run mode - no changes will be applied");let g=I(o);try{await Promise.all([y("git",["remote","add",g,i]),f(`rm -rf ${c}`)])}catch{s.debug(`${$(g)} remote already exists`)}finally{s.debug(`Added ${$(g)} remote: ${$(i)}`)}try{await y("git",["fetch",g]),s.debug(`Fetched latest changes from ${$(g)}`);let u=O(m),d=O(x),b=[...p].map(R=>`:!${R}`);if(s.debug(`Base exclusions: ${b.length} items`),s.debug(`Generating patch from ${u} to ${d}`),s.debug(`Total exclusions: ${b.length}`),r){let{stdout:R}=await y("git",["diff",u,`${g}/${d}`,"--",...b,"."],{encoding:"utf8"});s.info("\u{1F4CB} Patch preview:"),s.info(R||"No changes to apply");return}await C({remoteName:g,baseRef:u,targetRef:d,exclusions:b,logger:s,maxRetries:a,errorLogs:Q});let{stdout:E}=await y("git",["rev-parse",`${g}/${d}`],{encoding:"utf8"});await X(v,JSON.stringify({lastSyncedCommit:E.trim(),baseRef:u,targetRef:d,generatedAt:new Date().toISOString()},null,2)),await z(t==="debug"),console.log("\u2705 Upgrade applied successfully."),r||(s.info("Running post-sync commands..."),s.info(l.join(`
+`)),await Promise.all(l.map(R=>f(R))))}catch(u){console.error("\u274C Upgrade failed:",u)}try{await y("git",["remote","remove",g])}catch{}};export{le as a,ge as b,pe as c,L as d,ve as e,K as f,Ce as g};

package/dist/chunk-WVOQBBD4.mjs

@@ -0,0 +1 @@
+var g=Object.create;var f=Object.defineProperty;var h=Object.getOwnPropertyDescriptor;var i=Object.getOwnPropertyNames;var j=Object.getPrototypeOf,k=Object.prototype.hasOwnProperty;var m=(a=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(a,{get:(b,c)=>(typeof require<"u"?require:b)[c]}):a)(function(a){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+a+'" is not supported')});var n=(a,b)=>()=>(b||a((b={exports:{}}).exports,b),b.exports);var l=(a,b,c,e)=>{if(b&&typeof b=="object"||typeof b=="function")for(let d of i(b))!k.call(a,d)&&d!==c&&f(a,d,{get:()=>b[d],enumerable:!(e=h(b,d))||e.enumerable});return a};var o=(a,b,c)=>(c=a!=null?g(j(a)):{},l(b||!a||!a.__esModule?f(c,"default",{value:a,enumerable:!0}):c,a));export{m as a,n as b,o as c};

package/dist/cli.d.mts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { ForgeSyncOptions } from './index.mjs';
+
+interface CliOptions extends ForgeSyncOptions {
+    help?: boolean;
+    init?: boolean;
+    config?: string;
+}
+declare const parseArgs: (args: string[]) => Partial<CliOptions>;
+declare const showHelp: () => void;
+declare const main: (args?: string[]) => Promise<void>;
+
+export { main, parseArgs, showHelp };

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { ForgeSyncOptions } from './index.js';
+
+interface CliOptions extends ForgeSyncOptions {
+    help?: boolean;
+    init?: boolean;
+    config?: string;
+}
+declare const parseArgs: (args: string[]) => Partial<CliOptions>;
+declare const showHelp: () => void;
+declare const main: (args?: string[]) => Promise<void>;
+
+export { main, parseArgs, showHelp };