From ebbc4e26580dd6d15f6a30e18ffd00c3524fc9ab Mon Sep 17 00:00:00 2001
From: Indra Gunawan <hello@indra.my.id>
Date: Thu, 26 Mar 2026 21:51:24 +0800
Subject: [PATCH] fix(ext-gen): skip `README.md` generation in extension-init
 command if it exists (#2283)

Currently, the `extension-init` command automatically generates a
boilerplate `README.md`. While helpful for initial setups, this behavior
becomes destructive during the iterative development phase. If a
developer has customized their README and later runs `extension-init` to
update function signatures or add new functions, their custom
documentation is overwritten without warning.
---
 internal/extgen/docs.go      |  6 ++++++
 internal/extgen/docs_test.go | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/internal/extgen/docs.go b/internal/extgen/docs.go
index 428507ef..434f3e78 100644
--- a/internal/extgen/docs.go
+++ b/internal/extgen/docs.go
@@ -3,6 +3,7 @@ package extgen
 import (
 	"bytes"
 	_ "embed"
+	"os"
 	"path/filepath"
 	"text/template"
 )
@@ -22,6 +23,11 @@ type DocTemplateData struct {
 
 func (dg *DocumentationGenerator) generate() error {
 	filename := filepath.Join(dg.generator.BuildDir, "README.md")
+
+	if _, err := os.Stat(filename); err == nil {
+		return nil
+	}
+
 	content, err := dg.generateMarkdown()
 	if err != nil {
 		return err
diff --git a/internal/extgen/docs_test.go b/internal/extgen/docs_test.go
index 27b2b6af..7d827252 100644
--- a/internal/extgen/docs_test.go
+++ b/internal/extgen/docs_test.go
@@ -383,3 +383,39 @@ func BenchmarkDocumentationGenerator_GenerateMarkdown(b *testing.B) {
 		assert.NoError(b, err)
 	}
 }
+
+func TestDocumentationGenerator_SkipExistingReadme(t *testing.T) {
+	tempDir := t.TempDir()
+	readmePath := filepath.Join(tempDir, "README.md")
+
+	err := os.WriteFile(readmePath, []byte("hello"), 0644)
+	require.NoError(t, err)
+
+	generator := &Generator{
+		BaseName: "testextension",
+		BuildDir: tempDir,
+		Functions: []phpFunction{
+			{
+				Name:       "greet",
+				ReturnType: phpString,
+				Params: []phpParameter{
+					{Name: "name", PhpType: phpString},
+				},
+				Signature: "greet(string $name): string",
+			},
+		},
+		Classes: []phpClass{},
+	}
+
+	docGen := &DocumentationGenerator{
+		generator: generator,
+	}
+
+	err = docGen.generate()
+	assert.NoError(t, err, "generate() unexpected error")
+
+	content, err := os.ReadFile(readmePath)
+	require.NoError(t, err, "Failed to read generated README.md")
+
+	assert.Equal(t, string(content), "hello")
+}