Support user-driven templates

Author: bradcypert

.tool-versions

@@ -0,0 +1 @@
+zig 0.14.0

adr/00003-Support-Templates-Folder.md

@@ -0,0 +1,34 @@
+# 00003 - Support Templates Folder
+
+## Abstract
+
+Being able to provide your own templates for the README and the ADRs
+can be really useful. It allows you to customize this to your personal
+or team needs while still sticking with the tool and processes for
+maintaining proper ADRs.
+
+## Context and Problem Statement
+
+Currently, there is no way to deviate from the existing templates for
+the README and the ADRs. If you want to customize these, you will lose all
+changes upon regen of the README. Effectively, if you do not agree with
+the templates that are shipped with ADL, the tool may not be useful to you.
+
+## Considered Options
+
+### Do Nothing
+These templates are minimal and other additions can be captured elsewhere.
+
+### Support user-driven templates
+Create a templates directory and allow users to specify templates to be
+used on behalf of the CLI when generated READMEs and ADRs. Specify the fields
+via a templating language that the CLI can replace.
+
+## Decision Outcome
+
+We are going to support user-driven templates via a templates folder in the ADR directory. The templates folder should not be linked in the README contents.
+The templates folder will also have it's own README with information on the
+supported files that you can template, as well as the templating items that
+can be replaced by the CLI such as timestamp or contents.
+
+<!-- Add additional information here, comparison of options, research, etc -->

adr/README.md

@@ -4,13 +4,14 @@ This directory captures architecture decision records for this project.
 An architecture decision record is a justified software design choice 
 that addresses a functional or non-functional requirement of architectural significance.
 
-This directory and README is managed by adl. Please use \`adl create\` to create a new ADR.
+This directory and README is managed by [adl](https://github.com/bradcypert/adl). Please use \`adl create\` to create a new ADR.
 If you need to regenerate this readme without creating a new ADR, please use \`adl regen\`.
 
 ## Contents 
 
  - [00000-Use-Deno.md](./00000-Use-Deno.md)
  - [00001-Support-an-assets-folder.md](./00001-Support-an-assets-folder.md)
  - [00002-Migrate-to-Zig.md](./00002-Migrate-to-Zig.md)
+ - [00003-Support-Templates-Folder.md](./00003-Support-Templates-Folder.md)
 
-Last generated Wed, 1 Jan 2025 21:48:03 UTC
+Last generated Fri, 23 May 2025 18:56:25 UTC

adr/templates/README.md

@@ -0,0 +1,28 @@
+# Templates and the Template Folder
+
+The templates contained in this template folder will be used
+if they are defined. If they are not defined, we will default
+to the embedded templates used by the CLI.
+
+This gives you the ability to customize your ADRs and READMEs
+to meet your personal or team needs.
+
+## Supported Template Filenames
+
+### template_readme.md
+This template is used to generate the README in the ADR folder.
+It supports the following items.
+
+| Field                 | Purpose        |
+|-----------------------|--------------------------------------------------------------------------------|
+| {{timestamp}}         | The timestamp at which the README was last generated|
+| {{contents}}          | The contents of the ADR folder, structured as an ordered list, sorted by name. |
+
+### template_adr.md
+This template is used to generate a specific ADR.
+It supports the following items:
+
+| Field                | Purpose|
+|-----------------------|-------------------------------|
+| {{name}}              | The name of the generated ADR |
+

deno.json

@@ -3,19 +3,28 @@ const Datetime = @import("zig-datetime");
 const readmeContents = @embedFile("./templates/readme_template.md");
 const adrContents = @embedFile("./templates/adr_template.md");
 const helpContents = @embedFile("./templates/help.txt");
+const templateReadmeContents = @embedFile("./templates/readme_templates_folder.md");
 
 fn compareStrings(_: void, lhs: []const u8, rhs: []const u8) bool {
     return std.mem.order(u8, lhs, rhs).compare(std.math.CompareOperator.lt);
 }
 
-fn rebuildReadme(allocator: std.mem.Allocator) !void {
+fn readFileIfExists(allocator: std.mem.Allocator, filepath: []const u8) ![]u8 {
+    const templateFile = try std.fs.cwd().openFile(filepath, .{});
+    defer templateFile.close();
+
+    const fileContents = try templateFile.readToEndAlloc(allocator, std.math.maxInt(usize));
+    return fileContents;
+}
 
+fn rebuildReadme(allocator: std.mem.Allocator) !void {
+    const templateContents = readFileIfExists(allocator, "./adr/templates/template_readme.md") catch readmeContents;
     // TODO: Too many "Datetime"s
     const now = Datetime.datetime.Datetime.now();
     const date = try now.formatHttp(allocator);
     defer allocator.free(date);
 
-    const output = std.mem.replaceOwned(u8, allocator, readmeContents, "{{timestamp}}", date) catch @panic("out of memory");
+    const output = std.mem.replaceOwned(u8, allocator, templateContents, "{{timestamp}}", date) catch @panic("out of memory");
     defer allocator.free(output);
 
     const files = try getAllFilesInADRDir(allocator);
@@ -65,17 +74,22 @@ fn generateADR(allocator: std.mem.Allocator, n: u64, name: []u8) !void {
     );
     defer allocator.free(heading);
 
-    const contents = std.mem.replaceOwned(u8, allocator, adrContents, "{{name}}", heading) catch @panic("Out of memory");
+    const templateContents = readFileIfExists(allocator, "./adr/templates/template_adr.md") catch adrContents;
+    const contents = std.mem.replaceOwned(u8, allocator, templateContents, "{{name}}", heading) catch @panic("Out of memory");
     defer allocator.free(contents);
 
     const f = try std.fs.cwd().createFile(fileName, .{ .read = true });
     defer f.close();
     try f.writeAll(contents);
 }
 
-fn ensureDirsExist() !void {
+fn establishCoreFiles() !void {
     const cwd = std.fs.cwd();
     try cwd.makePath("./adr/assets");
+    try cwd.makePath("./adr/templates");
+
+    const f = try std.fs.cwd().createFile("./adr/templates/README.md", .{});
+    try f.writeAll(templateReadmeContents);
 }
 
 fn getAllFilesInADRDir(allocator: std.mem.Allocator) !std.ArrayList([]const u8) {
@@ -89,7 +103,7 @@ fn getAllFilesInADRDir(allocator: std.mem.Allocator) !std.ArrayList([]const u8)
     var dirIterator = dir.iterate();
     while (try dirIterator.next()) |dirContent| {
         // Append the file name to the ArrayList
-        if (!std.mem.eql(u8, dirContent.name, "README.md") and !std.mem.eql(u8, dirContent.name, "assets")) {
+        if (!std.mem.eql(u8, dirContent.name, "README.md") and !std.mem.eql(u8, dirContent.name, "assets") and !std.mem.eql(u8, dirContent.name, "templates")) {
             const fileName = try allocator.dupe(u8, dirContent.name);
             try file_list.append(fileName);
         }
@@ -111,7 +125,7 @@ pub fn main() !void {
 
     const action = if (args.len > 1) args[1] else "";
     if (std.mem.eql(u8, action, "create")) {
-        try ensureDirsExist();
+        try establishCoreFiles();
         const name = std.mem.join(allocator, " ", args[2..]) catch unreachable;
         if (name.len == 0) {
             _ = try stderr_file.write("No name supplied for the ADR. Command should be: adl create Name of ADR here\n");
@@ -123,7 +137,7 @@ pub fn main() !void {
         }
         allocator.free(name);
     } else if (std.mem.eql(u8, action, "regen")) {
-        try ensureDirsExist();
+        try establishCoreFiles();
         try rebuildReadme(allocator);
     } else {
         _ = bw.write(helpContents) catch @panic("Unable to write help contents");

deno.lock

@@ -0,0 +1,28 @@
+# Templates and the Template Folder
+
+The templates contained in this template folder will be used
+if they are defined. If they are not defined, we will default
+to the embedded templates used by the CLI.
+
+This gives you the ability to customize your ADRs and READMEs
+to meet your personal or team needs.
+
+## Supported Template Filenames
+
+### template_readme.md
+This template is used to generate the README in the ADR folder.
+It supports the following items.
+
+| Field                 | Purpose        |
+|-----------------------|--------------------------------------------------------------------------------|
+| {{timestamp}}         | The timestamp at which the README was last generated|
+| {{contents}}          | The contents of the ADR folder, structured as an ordered list, sorted by name. |
+
+### template_adr.md
+This template is used to generate a specific ADR.
+It supports the following items:
+
+| Field                | Purpose|
+|-----------------------|-------------------------------|
+| {{name}}              | The name of the generated ADR |
+