create-religion 0.3.0 → 0.4.0

package/dist/bin/religion.js

@@ -86,16 +86,33 @@ async function runInstall(options) {
         create: plan.filter((p) => p.action === "create").length,
         update: plan.filter((p) => p.action === "update").length,
         conflict: plan.filter((p) => p.action === "conflict").length,
-        kept: plan.filter((p) => p.action === "seed-skip").length
+        kept: plan.filter((p) => p.action === "seed-skip").length,
+        merge: plan.filter((p) => p.action === "merge").length,
+        remerge: plan.filter((p) => p.action === "remerge").length
     };
     console.log(`\nAdapters: ${adapters.map((a) => ADAPTERS[a].label).join(", ")}`);
     console.log(`  create   ${counts.create}`);
     console.log(`  update   ${counts.update}`);
     console.log(`  keep     ${counts.kept}  (your files, never overwritten)`);
     console.log(`  conflict ${counts.conflict}`);
+    if (counts.merge > 0)
+        console.log(`  merge    ${counts.merge}  (your file, awaiting a decision)`);
+    if (counts.remerge > 0)
+        console.log(`  merged   ${counts.remerge}  (your sections kept)`);
     for (const entry of plan.filter((p) => p.action === "conflict")) {
         console.log(`    ${entry.relative}`);
     }
+    const mergeable = plan.filter((p) => p.action === "merge").map((p) => p.relative);
+    let merge = false;
+    if (mergeable.length > 0) {
+        console.log(`\nThese already exist and were written by you:`);
+        for (const relative of mergeable)
+            console.log(`    ${relative}`);
+        console.log("\nReligion can append its own sections to them inside markers, keeping everything" +
+            "\nyou wrote exactly where it is. Later updates then replace only what is between" +
+            "\nthose markers. The originals are backed up either way.");
+        merge = await confirmMerge(options.yes);
+    }
     if (options.dryRun) {
         console.log("\nDry run. Nothing written.");
         return;
@@ -103,9 +120,12 @@ async function runInstall(options) {
     if (plan.length === 0) {
         throw new Error(`No template files found under ${templateRoot}. Nothing would be installed, which is never correct.`);
     }
-    const result = await applyInstall(templateRoot, target, plan, { force: options.force });
+    const result = await applyInstall(templateRoot, target, plan, { force: options.force, merge });
     await writeManifest(target, await version(), adapters, templateRoot, previous, result.conflicts);
     console.log(`\nWrote ${result.written.length} file(s).`);
+    if (result.merged.length > 0) {
+        console.log(`Merged ${result.merged.length} entry file(s), keeping what you wrote.`);
+    }
     if (result.backups.length > 0)
         console.log(`Backed up ${result.backups.length} conflicting file(s).`);
     if (result.conflicts.length > 0) {
@@ -126,6 +146,21 @@ async function runInstall(options) {
         console.log("\nNext: run the setup skill in your AI tool, then fill in the two plans.");
     }
 }
+/**
+ * Ask before rewriting a file the user wrote.
+ *
+ * Defaults to yes because the merge is additive and reversible: nothing of theirs moves and
+ * the original is backed up first. Declining leaves the file untouched and reported as a
+ * conflict, which is the old behaviour.
+ */
+async function confirmMerge(assumeYes) {
+    if (assumeYes || !process.stdin.isTTY)
+        return assumeYes;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await rl.question("\nMerge them? [Y/n] ")).trim().toLowerCase();
+    rl.close();
+    return answer === "" || answer === "y" || answer === "yes";
+}
 async function chooseAdapters(assumeYes) {
     const all = Object.keys(ADAPTERS);
     if (assumeYes || !process.stdin.isTTY)

package/dist/lib/install.js

@@ -10,6 +10,7 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { exists, STATE_DIR } from "./paths.js";
+import { hasDamagedMarkers, hasMarkers, replaceManagedBlock, spliceEntry } from "./merge.js";
 export const ADAPTERS = {
     claude: { label: "Claude Code", trees: [".claude/skills", ".claude/hooks"], entry: ["CLAUDE.md"] },
     codex: { label: "Codex", trees: [".agents/skills"], entry: ["AGENTS.md"] },
@@ -24,8 +25,13 @@ export function hash(contents) {
 export function isManaged(relative) {
     return !relative.startsWith(`${STATE_DIR}/`);
 }
+/** The entry files for the chosen adapters, which are the only files merging applies to. */
+function entryFiles(adapters) {
+    return new Set(adapters.flatMap((a) => ADAPTERS[a].entry));
+}
 export async function planInstall(templateRoot, target, adapters, previous) {
     const wanted = wantedPaths(adapters);
+    const entries = entryFiles(adapters);
     const plan = [];
     for (const relative of await walk(templateRoot)) {
         if (!wanted(relative))
@@ -50,7 +56,22 @@ export async function planInstall(templateRoot, target, adapters, previous) {
         // installed. Anything else is a local edit, and overwriting it silently is the failure
         // this manifest exists to prevent.
         const recorded = previous?.managed[relative];
-        plan.push({ relative, action: recorded && recorded === hash(current) ? "update" : "conflict" });
+        if (recorded && recorded === hash(current)) {
+            plan.push({ relative, action: "update" });
+            continue;
+        }
+        // An entry file is the one place where "differs from the template" is the normal case
+        // rather than a problem: a repository that already tells agents how to work has one, and
+        // it is usually the most carefully written file in the project.
+        if (entries.has(relative)) {
+            const text = current.toString("utf8");
+            // A damaged marker pair is a conflict, never a fresh merge: splicing a second block
+            // into a file that already has one is worse than the damage.
+            const action = hasMarkers(text) ? "remerge" : hasDamagedMarkers(text) ? "conflict" : "merge";
+            plan.push({ relative, action });
+            continue;
+        }
+        plan.push({ relative, action: "conflict" });
     }
     return plan;
 }
@@ -58,6 +79,7 @@ export async function applyInstall(templateRoot, target, plan, options) {
     const written = [];
     const conflicts = [];
     const backups = [];
+    const merged = [];
     for (const entry of plan) {
         if (entry.action === "unchanged" || entry.action === "seed-skip")
             continue;
@@ -65,6 +87,33 @@ export async function applyInstall(templateRoot, target, plan, options) {
             conflicts.push(entry.relative);
             continue;
         }
+        // Replacing only what is between the markers is the whole point of having merged: the
+        // user's own prose sits outside them and is never read, let alone rewritten.
+        if (entry.action === "remerge" || (entry.action === "merge" && options.merge)) {
+            const destination = path.join(target, entry.relative);
+            const template = await fs.readFile(path.join(templateRoot, entry.relative), "utf8");
+            const current = await fs.readFile(destination, "utf8");
+            if (entry.action === "merge") {
+                const backup = path.join(target, STATE_DIR, ".state", "backups", entry.relative);
+                await fs.mkdir(path.dirname(backup), { recursive: true });
+                await fs.copyFile(destination, backup);
+                backups.push(entry.relative);
+            }
+            const next = entry.action === "merge" ? spliceEntry(current, template) : replaceManagedBlock(current, template);
+            if (next === null) {
+                // Markers went missing between planning and writing, or were edited into an order
+                // this cannot reason about. Leaving it alone is the only safe answer.
+                conflicts.push(entry.relative);
+                continue;
+            }
+            await fs.writeFile(destination, next, "utf8");
+            merged.push(entry.relative);
+            continue;
+        }
+        if (entry.action === "merge") {
+            conflicts.push(entry.relative);
+            continue;
+        }
         const destination = path.join(target, entry.relative);
         if (entry.action === "conflict") {
             const backup = path.join(target, STATE_DIR, ".state", "backups", entry.relative);
@@ -76,7 +125,7 @@ export async function applyInstall(templateRoot, target, plan, options) {
         await fs.copyFile(path.join(templateRoot, entry.relative), destination);
         written.push(entry.relative);
     }
-    return { written, conflicts, backups };
+    return { written, conflicts, backups, merged };
 }
 /**
  * Records what was *installed*, not what is currently on disk.

package/dist/lib/merge.js

@@ -0,0 +1,119 @@
+/**
+ * Merging Religion's entry-file sections into a file the project already had.
+ *
+ * A repository that already carries agent instructions is the normal case, not the odd one,
+ * and the previous behaviour left those installs with the workflow on disk but nothing
+ * telling the agent it existed. Overwriting was never an option: those files are often the
+ * most carefully written thing in the repository.
+ *
+ * So the user's file stays exactly where it is and Religion's sections are appended inside
+ * markers. The markers are what make the result maintainable rather than a one-time paste:
+ * a later update replaces what is between them and never reads what is outside.
+ *
+ * Two sections are deliberately left outside the block. "What this is" is what the user's own
+ * file already says, and Commands is filled in by the setup skill with the project's real
+ * commands. Both would be destroyed by an update that replaced them.
+ */
+export const MANAGED_START = "<!-- religion:managed:start -->";
+export const MANAGED_END = "<!-- religion:managed:end -->";
+/** Sections the user owns. They never enter the managed block. */
+const USER_OWNED = new Set(["What this is", "Commands"]);
+const BLOCK_NOTE = "Everything between these markers is generated by Religion and replaced on update.\n" +
+    "Edit the files it points at, or the sections outside this block, rather than editing here.";
+/** Split a rendered entry file into its leading lines and its `## ` sections. */
+function parse(entry) {
+    const lines = entry.split(/\r?\n/);
+    const lead = [];
+    const sections = [];
+    let current = null;
+    for (const line of lines) {
+        const heading = /^## (.+)$/.exec(line);
+        if (heading?.[1]) {
+            current = { heading: heading[1].trim(), body: "" };
+            sections.push(current);
+            continue;
+        }
+        if (current)
+            current.body += line + "\n";
+        else
+            lead.push(line);
+    }
+    return { lead, sections };
+}
+function render(sections) {
+    return sections.map((s) => `## ${s.heading}\n${s.body.replace(/\n+$/, "")}\n`).join("\n");
+}
+/**
+ * The part of a rendered entry file that Religion owns.
+ *
+ * Includes the import lines, which is what makes a merged install keep receiving new context
+ * files: leaving them outside the block would freeze the set of loaded files at whatever
+ * shipped on the day of the merge.
+ */
+export function managedBlock(templateEntry) {
+    const { lead, sections } = parse(templateEntry);
+    const imports = lead.filter((line) => line.startsWith("@")).join("\n");
+    const owned = sections.filter((s) => !USER_OWNED.has(s.heading));
+    return [
+        MANAGED_START,
+        "",
+        BLOCK_NOTE,
+        "",
+        ...(imports ? [imports, ""] : []),
+        render(owned).replace(/\n+$/, ""),
+        "",
+        MANAGED_END
+    ].join("\n");
+}
+/** The sections the user owns, taken from the template as a starting point. */
+export function userOwnedSections(templateEntry) {
+    const { sections } = parse(templateEntry);
+    const owned = sections.filter((s) => USER_OWNED.has(s.heading) && s.heading !== "What this is");
+    return render(owned).replace(/\n+$/, "");
+}
+export function hasMarkers(contents) {
+    return contents.includes(MANAGED_START) && contents.includes(MANAGED_END);
+}
+/**
+ * A file carrying one marker but not both, or them in the wrong order.
+ *
+ * This must be told apart from a file that was never merged. Treating it as unmerged splices
+ * a second block into a file that already had one, which is a worse state than the damage it
+ * was trying to repair.
+ */
+export function hasDamagedMarkers(contents) {
+    const start = contents.indexOf(MANAGED_START);
+    const end = contents.indexOf(MANAGED_END);
+    if (start < 0 && end < 0)
+        return false;
+    return start < 0 || end < 0 || end < start;
+}
+/**
+ * Build the merged file: their content, then Religion's block, then the sections they own.
+ *
+ * Nothing of theirs moves. That is the property that makes this safe to accept without
+ * reading the diff, and the reason the block is appended rather than woven in.
+ */
+export function spliceEntry(existing, templateEntry) {
+    const body = existing.replace(/\n+$/, "");
+    const commands = userOwnedSections(templateEntry);
+    const parts = [body, "", managedBlock(templateEntry)];
+    // Only add Commands when their file has no section by that name; theirs is more accurate
+    // than the placeholder, and setup will find either one.
+    if (commands && !/^## Commands\s*$/m.test(existing))
+        parts.push("", commands);
+    return parts.join("\n") + "\n";
+}
+/**
+ * Replace the managed block in a merged file, leaving everything outside it untouched.
+ *
+ * Returns null when the markers are missing or out of order, which is treated as a conflict
+ * rather than repaired: a file whose markers were edited is one whose owner had a reason.
+ */
+export function replaceManagedBlock(existing, templateEntry) {
+    const start = existing.indexOf(MANAGED_START);
+    const end = existing.indexOf(MANAGED_END);
+    if (start < 0 || end < 0 || end < start)
+        return null;
+    return existing.slice(0, start) + managedBlock(templateEntry) + existing.slice(end + MANAGED_END.length);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-religion",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A file-backed, spec-driven AI development workflow. Spec before code, small reviewed diffs, and project state in markdown so a cleared context costs nothing.",
   "license": "MIT",
   "author": "Nate",