@nakedev/go-scaffold 0.1.0

package/dist/utils/method-patcher.js

@@ -0,0 +1,271 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchMethod = patchMethod;
+exports.markersPresent = markersPresent;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const marker_patch_1 = require("./marker-patch");
+const naming_1 = require("./naming");
+const DTO_MARKER = "// go-scaffold:dto";
+const REPO_INTERFACE_MARKER = "// go-scaffold:repository-interface";
+const REPO_IMPL_MARKER = "// go-scaffold:repository-methods";
+const SERVICE_MARKER = "// go-scaffold:service-methods";
+const HANDLER_ROUTES_MARKER = "// go-scaffold:handler-routes";
+const HANDLER_FUNCS_MARKER = "// go-scaffold:handler-funcs";
+const FAKE_REPO_MARKER = "// go-scaffold:fake-repo-methods";
+const UNUSED_G_LINE = "\t_ = g\n";
+// writeHandler ensures whatever packages the new handler code references are
+// imported (a minimal module starts with only "gin" imported) and drops the
+// `_ = g` placeholder once a real route makes it unnecessary — a no-op on a
+// full module, which already imports everything and never has that line.
+function writeHandler(handlerPath, content, goModule, needs) {
+    for (const pkg of needs) {
+        const importPath = pkg.startsWith("net/") ? pkg : `${goModule}/internal/shared/${pkg}`;
+        content = (0, marker_patch_1.ensureImport)(content, importPath);
+    }
+    fs_extra_1.default.writeFileSync(handlerPath, content.replace(UNUSED_G_LINE, ""));
+}
+function assertNotDuplicate(content, needle, what) {
+    if (content.includes(needle)) {
+        throw new Error(`${what} already exists — pick a different method name`);
+    }
+}
+function routeCall(type) {
+    return { get: "GET", post: "POST", put: "PUT", patch: "PATCH", delete: "DELETE" }[type];
+}
+function patchMethod(paths, naming, method, opts, goModule) {
+    const handlerSig = `func (h *Handler) ${method.handlerName}(`;
+    const serviceSig = `func (s *Service) ${method.pascalName}(`;
+    const handlerContent = fs_extra_1.default.readFileSync(paths.handlerPath, "utf8");
+    const serviceContent = fs_extra_1.default.readFileSync(paths.servicePath, "utf8");
+    assertNotDuplicate(handlerContent, handlerSig, `handler method "${method.handlerName}"`);
+    assertNotDuplicate(serviceContent, serviceSig, `service method "${method.pascalName}"`);
+    if (opts.type === "get" && opts.getMode === "all") {
+        patchGetAll(paths, naming, method, goModule);
+    }
+    else if (opts.type === "get") {
+        if (!opts.field)
+            throw new Error("--field is required for --type get --get-mode one");
+        if (opts.field.toLowerCase() === "id") {
+            throw new Error('--field cannot be "id" — GET /:id already exists as the default lookup');
+        }
+        patchGetOne(paths, naming, method, opts.field, goModule);
+    }
+    else if (opts.type === "post") {
+        patchPost(paths, naming, method, goModule);
+    }
+    else if (opts.type === "put" || opts.type === "patch") {
+        patchResourceAction(paths, naming, method, opts.type, goModule);
+    }
+    else {
+        patchDelete(paths, method, goModule);
+    }
+}
+function patchGetAll(paths, naming, method, goModule) {
+    let handler = fs_extra_1.default.readFileSync(paths.handlerPath, "utf8");
+    handler = (0, marker_patch_1.insertBeforeMarker)(handler, HANDLER_ROUTES_MARKER, `g.GET("/${method.pathSegment}", h.${method.handlerName})`);
+    handler = (0, marker_patch_1.insertBeforeMarker)(handler, HANDLER_FUNCS_MARKER, [
+        `func (h *Handler) ${method.handlerName}(c *gin.Context) {`,
+        `\tp := pagination.Parse(c)`,
+        `\titems, err := h.svc.${method.pascalName}(c.Request.Context(), p.Limit, p.Offset)`,
+        `\tif err != nil {`,
+        `\t\tc.Error(err)`,
+        `\t\treturn`,
+        `\t}`,
+        `\tout := make([]response, len(items))`,
+        `\tfor i := range items {`,
+        `\t\tout[i] = toResponse(&items[i])`,
+        `\t}`,
+        `\tc.JSON(http.StatusOK, p.Response(out))`,
+        `}`,
+        ``,
+    ].join("\n"));
+    writeHandler(paths.handlerPath, handler, goModule, ["net/http", "pagination"]);
+    let service = fs_extra_1.default.readFileSync(paths.servicePath, "utf8");
+    service = (0, marker_patch_1.insertBeforeMarker)(service, SERVICE_MARKER, [
+        `func (s *Service) ${method.pascalName}(ctx context.Context, limit, offset int) ([]model.${naming.pascalName}, error) {`,
+        `\t// TODO: add real filtering for "${method.name}" — currently reuses FindAll`,
+        `\titems, err := s.repo.FindAll(ctx, limit, offset)`,
+        `\tif err != nil {`,
+        `\t\treturn nil, apperror.NewInternal()`,
+        `\t}`,
+        `\treturn items, nil`,
+        `}`,
+        ``,
+    ].join("\n"));
+    fs_extra_1.default.writeFileSync(paths.servicePath, service);
+}
+function patchGetOne(paths, naming, method, rawField, goModule) {
+    const fieldParam = (0, naming_1.toCamelCase)(rawField);
+    const fieldPascal = (0, naming_1.toPascalCase)(rawField);
+    const fieldColumn = (0, naming_1.toDbName)(rawField);
+    let repo = fs_extra_1.default.readFileSync(paths.repositoryPath, "utf8");
+    assertNotDuplicate(repo, `FindBy${fieldPascal}(`, `repository method "FindBy${fieldPascal}"`);
+    repo = (0, marker_patch_1.insertBeforeMarker)(repo, REPO_IMPL_MARKER, [
+        `func (r *Repository) FindBy${fieldPascal}(ctx context.Context, ${fieldParam} string) (*model.${naming.pascalName}, error) {`,
+        `\tvar m model.${naming.pascalName}`,
+        `\t// TODO: confirm "${fieldColumn}" is the real column name for ${fieldParam}`,
+        `\tif err := r.db.WithContext(ctx).First(&m, "${fieldColumn} = ?", ${fieldParam}).Error; err != nil {`,
+        `\t\treturn nil, err`,
+        `\t}`,
+        `\treturn &m, nil`,
+        `}`,
+        ``,
+    ].join("\n"));
+    fs_extra_1.default.writeFileSync(paths.repositoryPath, repo);
+    let service = fs_extra_1.default.readFileSync(paths.servicePath, "utf8");
+    service = (0, marker_patch_1.insertBeforeMarker)(service, REPO_INTERFACE_MARKER, `FindBy${fieldPascal}(ctx context.Context, ${fieldParam} string) (*model.${naming.pascalName}, error)`);
+    // the interface just grew, so the hand-written fakeRepo mock in
+    // service_test.go needs a matching stub or the test file stops compiling
+    let serviceTest = fs_extra_1.default.readFileSync(paths.serviceTestPath, "utf8");
+    serviceTest = (0, marker_patch_1.insertBeforeMarker)(serviceTest, FAKE_REPO_MARKER, [
+        // nolint: only matters for a minimal module (fakeRepo never instantiated
+        // yet, so unused flags every one of its methods individually); harmless
+        // no-op on a full module where fakeRepo is already in use.
+        `//nolint:unused`,
+        `func (f *fakeRepo) FindBy${fieldPascal}(context.Context, string) (*model.${naming.pascalName}, error) {`,
+        `\tif f.err != nil {`,
+        `\t\treturn nil, f.err`,
+        `\t}`,
+        `\treturn f.m, nil`,
+        `}`,
+        ``,
+    ].join("\n"));
+    fs_extra_1.default.writeFileSync(paths.serviceTestPath, serviceTest);
+    service = (0, marker_patch_1.insertBeforeMarker)(service, SERVICE_MARKER, [
+        `func (s *Service) ${method.pascalName}(ctx context.Context, ${fieldParam} string) (*model.${naming.pascalName}, error) {`,
+        `\tm, err := s.repo.FindBy${fieldPascal}(ctx, ${fieldParam})`,
+        `\tif err != nil {`,
+        `\t\treturn nil, wrapFindErr(err)`,
+        `\t}`,
+        `\treturn m, nil`,
+        `}`,
+        ``,
+    ].join("\n"));
+    fs_extra_1.default.writeFileSync(paths.servicePath, service);
+    let handler = fs_extra_1.default.readFileSync(paths.handlerPath, "utf8");
+    handler = (0, marker_patch_1.insertBeforeMarker)(handler, HANDLER_ROUTES_MARKER, `g.GET("/${fieldColumn}/:${fieldParam}", h.${method.handlerName})`);
+    handler = (0, marker_patch_1.insertBeforeMarker)(handler, HANDLER_FUNCS_MARKER, [
+        `func (h *Handler) ${method.handlerName}(c *gin.Context) {`,
+        `\t${fieldParam} := c.Param("${fieldParam}")`,
+        `\tm, err := h.svc.${method.pascalName}(c.Request.Context(), ${fieldParam})`,
+        `\tif err != nil {`,
+        `\t\tc.Error(err)`,
+        `\t\treturn`,
+        `\t}`,
+        `\tc.JSON(http.StatusOK, toResponse(m))`,
+        `}`,
+        ``,
+    ].join("\n"));
+    writeHandler(paths.handlerPath, handler, goModule, ["net/http"]);
+}
+function patchPost(paths, naming, method, goModule) {
+    const inputName = `${method.pascalName}Input`;
+    let dto = fs_extra_1.default.readFileSync(paths.dtoPath, "utf8");
+    assertNotDuplicate(dto, `type ${inputName} struct`, `DTO "${inputName}"`);
+    dto = (0, marker_patch_1.insertBeforeMarker)(dto, DTO_MARKER, [`type ${inputName} struct {`, `\t// TODO: add request fields`, `}`, ``].join("\n"));
+    fs_extra_1.default.writeFileSync(paths.dtoPath, dto);
+    let handler = fs_extra_1.default.readFileSync(paths.handlerPath, "utf8");
+    handler = (0, marker_patch_1.insertBeforeMarker)(handler, HANDLER_ROUTES_MARKER, `g.POST("/${method.pathSegment}", h.${method.handlerName})`);
+    handler = (0, marker_patch_1.insertBeforeMarker)(handler, HANDLER_FUNCS_MARKER, [
+        `func (h *Handler) ${method.handlerName}(c *gin.Context) {`,
+        `\tvar in ${inputName}`,
+        `\tif err := c.ShouldBindJSON(&in); err != nil {`,
+        `\t\tc.Error(httpx.BindErr(err))`,
+        `\t\treturn`,
+        `\t}`,
+        `\tm, err := h.svc.${method.pascalName}(c.Request.Context(), in)`,
+        `\tif err != nil {`,
+        `\t\tc.Error(err)`,
+        `\t\treturn`,
+        `\t}`,
+        `\tc.JSON(http.StatusCreated, toResponse(m))`,
+        `}`,
+        ``,
+    ].join("\n"));
+    writeHandler(paths.handlerPath, handler, goModule, ["net/http", "httpx"]);
+    let service = fs_extra_1.default.readFileSync(paths.servicePath, "utf8");
+    service = (0, marker_patch_1.insertBeforeMarker)(service, SERVICE_MARKER, [
+        `func (s *Service) ${method.pascalName}(ctx context.Context, in ${inputName}) (*model.${naming.pascalName}, error) {`,
+        `\t// TODO: implement "${method.name}" — this stub does nothing yet`,
+        `\t_ = in`,
+        `\treturn nil, apperror.NewInternal()`,
+        `}`,
+        ``,
+    ].join("\n"));
+    fs_extra_1.default.writeFileSync(paths.servicePath, service);
+}
+function patchResourceAction(paths, naming, method, type, goModule) {
+    let handler = fs_extra_1.default.readFileSync(paths.handlerPath, "utf8");
+    handler = (0, marker_patch_1.insertBeforeMarker)(handler, HANDLER_ROUTES_MARKER, `g.${routeCall(type)}("/:id/${method.pathSegment}", h.${method.handlerName})`);
+    handler = (0, marker_patch_1.insertBeforeMarker)(handler, HANDLER_FUNCS_MARKER, [
+        `func (h *Handler) ${method.handlerName}(c *gin.Context) {`,
+        `\tid, ok := httpx.ParseID(c)`,
+        `\tif !ok {`,
+        `\t\treturn`,
+        `\t}`,
+        `\tm, err := h.svc.${method.pascalName}(c.Request.Context(), id)`,
+        `\tif err != nil {`,
+        `\t\tc.Error(err)`,
+        `\t\treturn`,
+        `\t}`,
+        `\tc.JSON(http.StatusOK, toResponse(m))`,
+        `}`,
+        ``,
+    ].join("\n"));
+    writeHandler(paths.handlerPath, handler, goModule, ["net/http", "httpx"]);
+    let service = fs_extra_1.default.readFileSync(paths.servicePath, "utf8");
+    service = (0, marker_patch_1.insertBeforeMarker)(service, SERVICE_MARKER, [
+        `func (s *Service) ${method.pascalName}(ctx context.Context, id uuid.UUID) (*model.${naming.pascalName}, error) {`,
+        `\tm, err := s.repo.FindByID(ctx, id)`,
+        `\tif err != nil {`,
+        `\t\treturn nil, wrapFindErr(err)`,
+        `\t}`,
+        `\t// TODO: implement "${method.name}" — currently a no-op save`,
+        `\tif err := s.repo.Update(ctx, m); err != nil {`,
+        `\t\treturn nil, apperror.NewInternal()`,
+        `\t}`,
+        `\treturn m, nil`,
+        `}`,
+        ``,
+    ].join("\n"));
+    fs_extra_1.default.writeFileSync(paths.servicePath, service);
+}
+function patchDelete(paths, method, goModule) {
+    let handler = fs_extra_1.default.readFileSync(paths.handlerPath, "utf8");
+    handler = (0, marker_patch_1.insertBeforeMarker)(handler, HANDLER_ROUTES_MARKER, `g.DELETE("/:id/${method.pathSegment}", h.${method.handlerName})`);
+    handler = (0, marker_patch_1.insertBeforeMarker)(handler, HANDLER_FUNCS_MARKER, [
+        `func (h *Handler) ${method.handlerName}(c *gin.Context) {`,
+        `\tid, ok := httpx.ParseID(c)`,
+        `\tif !ok {`,
+        `\t\treturn`,
+        `\t}`,
+        `\tif err := h.svc.${method.pascalName}(c.Request.Context(), id); err != nil {`,
+        `\t\tc.Error(err)`,
+        `\t\treturn`,
+        `\t}`,
+        `\tc.Status(http.StatusNoContent)`,
+        `}`,
+        ``,
+    ].join("\n"));
+    writeHandler(paths.handlerPath, handler, goModule, ["net/http", "httpx"]);
+    let service = fs_extra_1.default.readFileSync(paths.servicePath, "utf8");
+    service = (0, marker_patch_1.insertBeforeMarker)(service, SERVICE_MARKER, [
+        `func (s *Service) ${method.pascalName}(ctx context.Context, id uuid.UUID) error {`,
+        `\t// TODO: implement "${method.name}" — this stub does nothing yet`,
+        `\treturn apperror.NewInternal()`,
+        `}`,
+        ``,
+    ].join("\n"));
+    fs_extra_1.default.writeFileSync(paths.servicePath, service);
+}
+function markersPresent(handlerPath, servicePath) {
+    const handler = fs_extra_1.default.readFileSync(handlerPath, "utf8");
+    const service = fs_extra_1.default.readFileSync(servicePath, "utf8");
+    return ((0, marker_patch_1.hasMarker)(handler, HANDLER_ROUTES_MARKER) &&
+        (0, marker_patch_1.hasMarker)(handler, HANDLER_FUNCS_MARKER) &&
+        (0, marker_patch_1.hasMarker)(service, SERVICE_MARKER) &&
+        (0, marker_patch_1.hasMarker)(service, REPO_INTERFACE_MARKER));
+}

package/dist/utils/migrations.js

@@ -0,0 +1,17 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nextMigrationSeq = nextMigrationSeq;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+// golang-migrate sequential numbering: 000001, 000002, ...
+function nextMigrationSeq(migrationsDir) {
+    const files = fs_extra_1.default.existsSync(migrationsDir) ? fs_extra_1.default.readdirSync(migrationsDir) : [];
+    const nums = files
+        .map((f) => f.match(/^(\d+)_/))
+        .filter((m) => m !== null)
+        .map((m) => parseInt(m[1], 10));
+    const next = (nums.length ? Math.max(...nums) : 0) + 1;
+    return String(next).padStart(6, "0");
+}

package/dist/utils/module-paths.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listVersionFolders = listVersionFolders;
+exports.versionsContainingModule = versionsContainingModule;
+exports.nextVersionName = nextVersionName;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+// folder-based domain versioning lays modules out as internal/app/v<n>/<pkg>.
+// listVersionFolders returns the existing v<n> dirs, sorted ascending.
+function listVersionFolders(projectDir) {
+    const appDir = path_1.default.join(projectDir, "internal", "app");
+    if (!fs_extra_1.default.existsSync(appDir))
+        return [];
+    return fs_extra_1.default
+        .readdirSync(appDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && /^v\d+$/.test(e.name))
+        .map((e) => e.name)
+        .sort((a, b) => parseInt(a.slice(1), 10) - parseInt(b.slice(1), 10));
+}
+// version folders that actually contain the given module (identified by its
+// handler.go) — a module can legitimately live in more than one version at
+// once (that's the point of versioning), so callers that need exactly one
+// (generate method, remove module) must pick among the matches.
+function versionsContainingModule(projectDir, pkg) {
+    return listVersionFolders(projectDir).filter((v) => fs_extra_1.default.existsSync(path_1.default.join(projectDir, "internal", "app", v, pkg, "handler.go")));
+}
+function nextVersionName(versions) {
+    const max = versions.reduce((m, v) => Math.max(m, parseInt(v.slice(1), 10) || 0), 0);
+    return `v${max + 1}`;
+}

package/dist/utils/naming.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluralize = pluralize;
+exports.toPascalCase = toPascalCase;
+exports.toPackageName = toPackageName;
+exports.toCamelCase = toCamelCase;
+exports.toKebabCase = toKebabCase;
+exports.toDbName = toDbName;
+exports.validateGoModulePath = validateGoModulePath;
+exports.assertValidGoModulePath = assertValidGoModulePath;
+exports.assertNotGoKeyword = assertNotGoKeyword;
+exports.validateModuleName = validateModuleName;
+exports.normalizeApiPrefix = normalizeApiPrefix;
+exports.validateApiPrefix = validateApiPrefix;
+exports.resolveModuleNaming = resolveModuleNaming;
+exports.resolveMethodNaming = resolveMethodNaming;
+// ponytail: heuristic pluralizer, not a dependency — covers common English
+// nouns (order/user/category/address); irregular plurals still need a manual
+// rename in the generated file, add a dictionary if that becomes frequent.
+function pluralize(word) {
+    if (/[sxz]$/.test(word) || /[^aeiou](ch|sh)$/.test(word))
+        return word + "es";
+    if (/[^aeiou]y$/.test(word))
+        return word.slice(0, -1) + "ies";
+    if (word.endsWith("s"))
+        return word;
+    return word + "s";
+}
+function toPascalCase(value) {
+    return value
+        .replace(/[-_\s]+(.)?/g, (_, char) => (char ? char.toUpperCase() : ""))
+        .replace(/^(.)/, (char) => char.toUpperCase());
+}
+// Go package names: lowercase, single word, no separators (effective Go).
+function toPackageName(value) {
+    return value.trim().toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function toCamelCase(value) {
+    const pascal = toPascalCase(value);
+    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+// URL path segment: "findActive" -> "find-active", "reset_password" -> "reset-password".
+function toKebabCase(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/[_\s]+/g, "-")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+// Postgres database/identifier name: lowercase snake_case.
+function toDbName(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+// Go module path: each '/'-separated segment is letters/digits, optionally
+// with . _ - in the middle — this is what go.mod's `module` line accepts.
+// Rejects spaces and other punctuation that would produce a go.mod that
+// fails to parse (go: errors parsing go.mod: usage: module module/path).
+const VALID_GO_MODULE_PATH = /^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?(\/[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?)*$/;
+function validateGoModulePath(name) {
+    return VALID_GO_MODULE_PATH.test(name)
+        ? true
+        : `invalid project name "${name}" — go.mod module paths can't contain spaces; use letters, numbers, ., _, -, / only (e.g. "my-api" or "github.com/org/my-api")`;
+}
+function assertValidGoModulePath(name) {
+    const result = validateGoModulePath(name);
+    if (result !== true)
+        throw new Error(result);
+}
+// Go's 25 reserved words — a package/func/param named any of these produces
+// code that won't parse (`package func`, `func (h *Handler) type(...)`).
+const GO_KEYWORDS = new Set([
+    "break", "case", "chan", "const", "continue", "default", "defer", "else",
+    "fallthrough", "for", "func", "go", "goto", "if", "import", "interface",
+    "map", "package", "range", "return", "select", "struct", "switch", "type", "var",
+]);
+// predeclared type names — legal as identifiers, but a *package* named one of
+// these shadows the builtin in generated code that uses it as a type (main.go
+// has `s string`), so reject them for module names specifically.
+const GO_PREDECLARED_TYPES = new Set([
+    "any", "bool", "byte", "comparable", "complex64", "complex128", "error",
+    "float32", "float64", "int", "int8", "int16", "int32", "int64", "rune",
+    "string", "uint", "uint8", "uint16", "uint32", "uint64", "uintptr",
+]);
+// method/handler/param identifier: only keywords are hard-illegal (a param or
+// func named `string` is legal Go, just shadows the builtin locally).
+function assertNotGoKeyword(ident, role) {
+    if (GO_KEYWORDS.has(ident.toLowerCase())) {
+        throw new Error(`"${ident}" is a Go keyword — can't use it as a ${role} name; pick another`);
+    }
+}
+// module name becomes a Go package name; keywords and predeclared type names
+// both produce code that won't compile (`package func`, or a `string` package
+// shadowing the builtin in main.go). Returns true|message for inquirer, and
+// backs the assert in resolveModuleNaming — one source of truth for both.
+function validateModuleName(rawName) {
+    const pkg = toPackageName(rawName);
+    if (!pkg)
+        return `invalid module name: "${rawName}" (must contain letters/numbers)`;
+    if (/^[0-9]/.test(pkg)) {
+        return `"${pkg}" starts with a digit — a Go package name can't, so it won't compile; pick another module name`;
+    }
+    if (GO_KEYWORDS.has(pkg) || GO_PREDECLARED_TYPES.has(pkg)) {
+        return `"${pkg}" is a reserved Go word — a package named it won't compile; pick another module name`;
+    }
+    return true;
+}
+// strips whitespace and leading/trailing slashes so "/api/v1/" and "api/v1"
+// store identically — callers should normalize once and use the result
+// everywhere (config, templates), not just for validation.
+function normalizeApiPrefix(raw) {
+    return raw.trim().replace(/^\/+|\/+$/g, "");
+}
+// apiPrefix becomes a URL path (/api/v1/orders) — multiple slash-separated
+// segments are fine (gin's r.Group() joins paths natively, confirmed against
+// gin directly: r.Group("/api/v1") produces /api/v1/orders as expected). The
+// `api := r.Group(...)` variable is always named "api" regardless of the
+// prefix's value, so the prefix itself never needs to be a valid Go
+// identifier — just clean URL segments. Empty string is valid on purpose: it
+// means "no prefix", routes register directly at /orders.
+function validateApiPrefix(raw) {
+    const trimmed = normalizeApiPrefix(raw);
+    if (trimmed === "")
+        return true;
+    return /^[a-z][a-z0-9]*(\/[a-z][a-z0-9]*)*$/.test(trimmed)
+        ? true
+        : `invalid API prefix "${trimmed}" — use lowercase letters/numbers per segment, separated by "/" (e.g. "v1", "api/v1"), or leave blank for none`;
+}
+function resolveModuleNaming(rawName) {
+    const check = validateModuleName(rawName);
+    if (check !== true)
+        throw new Error(check);
+    const pkg = toPackageName(rawName);
+    return {
+        name: pkg,
+        pkg,
+        pascalName: toPascalCase(pkg),
+        plural: pluralize(pkg),
+        errorPrefix: pkg.toUpperCase(),
+    };
+}
+function resolveMethodNaming(rawName) {
+    const cleaned = rawName.trim();
+    const pascalName = toPascalCase(cleaned);
+    if (!pascalName) {
+        throw new Error(`invalid method name: "${rawName}" (must contain letters/numbers)`);
+    }
+    // handlerName becomes a Go method name (`func (h *Handler) <name>`)
+    assertNotGoKeyword(toCamelCase(cleaned), "method");
+    return {
+        name: cleaned,
+        pascalName,
+        handlerName: toCamelCase(cleaned),
+        pathSegment: toKebabCase(cleaned),
+    };
+}

package/dist/utils/openapi-patcher.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchOpenapiIndex = patchOpenapiIndex;
+exports.unpatchOpenapiIndex = unpatchOpenapiIndex;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const marker_patch_1 = require("./marker-patch");
+const PATHS_MARKER = "# go-scaffold:paths";
+const SCHEMAS_MARKER = "# go-scaffold:schemas";
+// exact lines a module contributes to docs/openapi.yaml — shared by patch and
+// unpatch so removal pulls out precisely what was added. apiPrefix is the
+// project-wide prefix chosen at create time (e.g. "v1", "" for none).
+function openapiLines(naming, apiPrefix) {
+    const base = apiPrefix ? `/${apiPrefix}/${naming.plural}` : `/${naming.plural}`;
+    return {
+        paths: [
+            `${base}:`,
+            `  $ref: './${naming.plural}/collection.yaml'`,
+            `${base}/{id}:`,
+            `  $ref: './${naming.plural}/item.yaml'`,
+        ],
+        schemas: [
+            `${naming.pascalName}CreateInput: { $ref: './${naming.plural}/schemas.yaml#/${naming.pascalName}CreateInput' }`,
+            `${naming.pascalName}UpdateInput: { $ref: './${naming.plural}/schemas.yaml#/${naming.pascalName}UpdateInput' }`,
+            `${naming.pascalName}Response: { $ref: './${naming.plural}/schemas.yaml#/${naming.pascalName}Response' }`,
+        ],
+    };
+}
+// patchOpenapiIndex wires a new module's collection/item docs into the
+// docs/openapi.yaml index — same marker-comment approach as main.go.
+function patchOpenapiIndex(openapiPath, naming, apiPrefix) {
+    let content = fs_extra_1.default.readFileSync(openapiPath, "utf8");
+    const { paths, schemas } = openapiLines(naming, apiPrefix);
+    // sentinels keep re-runs idempotent (same reason as main-patcher)
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, PATHS_MARKER, paths.join("\n"), paths[0]);
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, SCHEMAS_MARKER, schemas.join("\n"), schemas[2]);
+    fs_extra_1.default.writeFileSync(openapiPath, content);
+}
+// unpatchOpenapiIndex removes a module's paths/schemas from the index — inverse
+// of patchOpenapiIndex.
+function unpatchOpenapiIndex(openapiPath, naming, apiPrefix) {
+    const content = fs_extra_1.default.readFileSync(openapiPath, "utf8");
+    const { paths, schemas } = openapiLines(naming, apiPrefix);
+    fs_extra_1.default.writeFileSync(openapiPath, (0, marker_patch_1.removeLines)(content, [...paths, ...schemas]));
+}

package/dist/utils/template-renderer.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTemplatesRoot = getTemplatesRoot;
+exports.renderString = renderString;
+exports.applyTemplateEntries = applyTemplateEntries;
+exports.gofmtTree = gofmtTree;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const child_process_1 = require("child_process");
+const handlebars_1 = __importDefault(require("handlebars"));
+handlebars_1.default.registerHelper("eq", (a, b) => a === b);
+function getTemplatesRoot() {
+    const candidates = [
+        path_1.default.join(__dirname, "..", "..", "templates"),
+        path_1.default.join(__dirname, "..", "..", "..", "templates"),
+    ];
+    const resolved = candidates.find((candidate) => fs_1.default.existsSync(path_1.default.join(candidate, "create", "base", "go.mod.hbs")));
+    if (!resolved) {
+        throw new Error("unable to locate templates directory");
+    }
+    return resolved;
+}
+function renderString(source, context) {
+    return handlebars_1.default.compile(source, { noEscape: true })(context);
+}
+async function applyTemplateEntries(projectRoot, entries, context) {
+    const root = getTemplatesRoot();
+    for (const entry of entries) {
+        if (entry.when && !entry.when(context))
+            continue;
+        const source = await fs_extra_1.default.readFile(path_1.default.join(root, entry.template), "utf8");
+        const rendered = renderString(source, context);
+        const outputPath = path_1.default.join(projectRoot, entry.output);
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(outputPath));
+        await fs_extra_1.default.writeFile(outputPath, rendered);
+    }
+}
+// gofmt the whole project tree; a missing gofmt (no local Go toolchain) is
+// non-fatal — generated files are already hand-formatted templates.
+function gofmtTree(projectRoot) {
+    try {
+        (0, child_process_1.execFileSync)("gofmt", ["-w", "."], { cwd: projectRoot, stdio: "ignore" });
+    }
+    catch {
+        // ponytail: no Go toolchain on this machine, skip formatting
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@nakedev/go-scaffold",
+  "version": "0.1.0",
+  "description": "Scaffold Gin + GORM + Postgres Go backend projects with a consistent domain-module standard",
+  "bin": {
+    "go-scaffold": "./bin/go-scaffold.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "bin"
+  ],
+  "type": "commonjs",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node scripts/smoke-test.mjs",
+    "verify": "pnpm run build && pnpm run test",
+    "prepublishOnly": "pnpm run verify"
+  },
+  "keywords": [
+    "go",
+    "gin",
+    "gorm",
+    "scaffold",
+    "cli",
+    "generator"
+  ],
+  "author": "nakedev",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.5.1",
+    "commander": "^15.0.0",
+    "fs-extra": "^11.3.0",
+    "handlebars": "^4.7.8",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}