@nakedev/go-scaffold 0.1.0

package/dist/prompts/create-wizard.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promptProjectName = promptProjectName;
+exports.runCreateWizard = runCreateWizard;
+const prompts_1 = require("@inquirer/prompts");
+const naming_1 = require("../utils/naming");
+async function promptProjectName() {
+    const name = await (0, prompts_1.input)({
+        message: "Project name:",
+        validate: (value) => {
+            if (!value.trim())
+                return "project name is required";
+            return (0, naming_1.validateGoModulePath)(value.trim());
+        },
+    });
+    return name.trim();
+}
+async function runCreateWizard() {
+    console.log("\nConfigure your project:\n");
+    const docker = await (0, prompts_1.confirm)({
+        message: "Include Docker Compose (local Postgres)?",
+        default: true,
+    });
+    const openapiDocs = await (0, prompts_1.confirm)({
+        message: "Include hand-written OpenAPI docs (docs/openapi.yaml, whole docs/ tree served at /docs)?",
+        default: true,
+    });
+    const apiPrefixRaw = await (0, prompts_1.input)({
+        message: "API route prefix (e.g. v1, api/v1; leave blank for none):",
+        default: "v1",
+        validate: naming_1.validateApiPrefix,
+    });
+    const apiPrefix = (0, naming_1.normalizeApiPrefix)(apiPrefixRaw);
+    console.log("\nSummary:");
+    console.log(`  Docker + PostgreSQL: ${docker ? "yes" : "no"}`);
+    console.log(`  OpenAPI docs: ${openapiDocs ? "yes" : "no"}`);
+    console.log(`  Route prefix: ${apiPrefix ? `/${apiPrefix}` : "(none)"}`);
+    const proceed = await (0, prompts_1.confirm)({ message: "\nCreate project with these settings?", default: true });
+    if (!proceed) {
+        throw new Error("project creation cancelled");
+    }
+    return { features: { docker, openapiDocs }, apiPrefix };
+}

package/dist/prompts/generate-wizard.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.promptModuleName = promptModuleName;
+exports.promptMethodName = promptMethodName;
+exports.promptMethodType = promptMethodType;
+exports.promptGetMode = promptGetMode;
+exports.promptLookupField = promptLookupField;
+const prompts_1 = require("@inquirer/prompts");
+const naming_1 = require("../utils/naming");
+// wraps an assert-style validator into inquirer's true|string contract so a
+// reserved word re-prompts inline instead of aborting the whole command.
+function notKeyword(value, role) {
+    try {
+        (0, naming_1.assertNotGoKeyword)((0, naming_1.toCamelCase)(value.trim()), role);
+        return true;
+    }
+    catch (e) {
+        return e.message;
+    }
+}
+async function promptModuleName() {
+    const name = await (0, prompts_1.input)({
+        message: "Module name (singular, e.g. order, product):",
+        validate: (value) => (value.trim() ? (0, naming_1.validateModuleName)(value) : "module name is required"),
+    });
+    return name.trim();
+}
+async function promptMethodName() {
+    const name = await (0, prompts_1.input)({
+        message: "Method name (e.g. approve, findByStatus, resetPassword):",
+        validate: (value) => (value.trim() ? notKeyword(value, "method") : "method name is required"),
+    });
+    return name.trim();
+}
+async function promptMethodType() {
+    return (0, prompts_1.select)({
+        message: "Method type:",
+        choices: [
+            { name: "GET", value: "get" },
+            { name: "POST", value: "post" },
+            { name: "PUT", value: "put" },
+            { name: "PATCH", value: "patch" },
+            { name: "DELETE", value: "delete" },
+        ],
+    });
+}
+async function promptGetMode() {
+    return (0, prompts_1.select)({
+        message: "GET mode:",
+        choices: [
+            { name: "List (all) — a new list endpoint with its own filter", value: "all" },
+            { name: "Single record lookup (one) — find by a field other than id", value: "one" },
+        ],
+    });
+}
+async function promptLookupField() {
+    const field = await (0, prompts_1.input)({
+        message: "Lookup field (e.g. email, status, slug):",
+        validate: (value) => {
+            if (!value.trim())
+                return "field is required";
+            if (value.trim().toLowerCase() === "id")
+                return '"id" already has a lookup route — pick another field';
+            return notKeyword(value, "lookup field");
+        },
+    });
+    return field.trim();
+}

package/dist/templates/create-manifest.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CREATE_MANIFEST = void 0;
+exports.CREATE_MANIFEST = [
+    { template: "create/base/go.mod.hbs", output: "go.mod" },
+    { template: "create/base/.gitignore.hbs", output: ".gitignore" },
+    { template: "create/base/.env.example.hbs", output: ".env.example" },
+    { template: "create/base/Makefile.hbs", output: "Makefile" },
+    { template: "create/base/.golangci.yml.hbs", output: ".golangci.yml" },
+    { template: "create/base/.vscode/settings.json.hbs", output: ".vscode/settings.json" },
+    { template: "create/base/.github/workflows/ci.yml.hbs", output: ".github/workflows/ci.yml" },
+    { template: "create/base/README.md.hbs", output: "README.md" },
+    { template: "create/base/AGENTS.md.hbs", output: "AGENTS.md" },
+    { template: "create/base/CLAUDE.md.hbs", output: "CLAUDE.md" },
+    {
+        template: "create/base/.claude/skills/go-scaffold/SKILL.md.hbs",
+        output: ".claude/skills/go-scaffold/SKILL.md",
+    },
+    { template: "create/base/cmd/api/main.go.hbs", output: "cmd/api/main.go" },
+    {
+        template: "create/base/internal/platform/database/database.go.hbs",
+        output: "internal/platform/database/database.go",
+    },
+    {
+        template: "create/base/internal/shared/config/config.go.hbs",
+        output: "internal/shared/config/config.go",
+    },
+    {
+        template: "create/base/internal/shared/apperror/apperror.go.hbs",
+        output: "internal/shared/apperror/apperror.go",
+    },
+    {
+        template: "create/base/internal/shared/dberr/dberr.go.hbs",
+        output: "internal/shared/dberr/dberr.go",
+    },
+    {
+        template: "create/base/internal/shared/httpx/httpx.go.hbs",
+        output: "internal/shared/httpx/httpx.go",
+    },
+    {
+        template: "create/base/internal/shared/id/id.go.hbs",
+        output: "internal/shared/id/id.go",
+    },
+    {
+        template: "create/base/internal/shared/pagination/pagination.go.hbs",
+        output: "internal/shared/pagination/pagination.go",
+    },
+    {
+        template: "create/base/internal/shared/middleware/error.go.hbs",
+        output: "internal/shared/middleware/error.go",
+    },
+    {
+        template: "create/base/internal/shared/middleware/logger.go.hbs",
+        output: "internal/shared/middleware/logger.go",
+    },
+    {
+        template: "create/base/internal/shared/middleware/requestid.go.hbs",
+        output: "internal/shared/middleware/requestid.go",
+    },
+    { template: "create/base/migrations/.gitkeep.hbs", output: "migrations/.gitkeep" },
+    // architecture standards docs — always included, this is the point of the CLI
+    {
+        template: "create/features/docs/architecture.md.hbs",
+        output: "docs/architect/architecture.md",
+    },
+    {
+        template: "create/features/docs/patterns.md.hbs",
+        output: "docs/architect/patterns.md",
+    },
+    {
+        template: "create/features/docs/techstack.md.hbs",
+        output: "docs/architect/techstack.md",
+    },
+    // opt-in features
+    {
+        template: "create/features/docker-compose.yml.hbs",
+        output: "docker-compose.yml",
+        when: (ctx) => ctx.docker,
+    },
+    {
+        template: "create/features/docs/openapi.yaml.hbs",
+        output: "docs/openapi.yaml",
+        when: (ctx) => ctx.openapiDocs,
+    },
+    {
+        template: "create/features/docs/common/parameters.yaml.hbs",
+        output: "docs/common/parameters.yaml",
+        when: (ctx) => ctx.openapiDocs,
+    },
+    {
+        template: "create/features/docs/common/responses.yaml.hbs",
+        output: "docs/common/responses.yaml",
+        when: (ctx) => ctx.openapiDocs,
+    },
+    {
+        template: "create/features/docs/common/schemas.yaml.hbs",
+        output: "docs/common/schemas.yaml",
+        when: (ctx) => ctx.openapiDocs,
+    },
+    {
+        template: "create/features/docs/health/health-livez.yaml.hbs",
+        output: "docs/health/health-livez.yaml",
+        when: (ctx) => ctx.openapiDocs,
+    },
+    {
+        template: "create/features/docs/health/health-readyz.yaml.hbs",
+        output: "docs/health/health-readyz.yaml",
+        when: (ctx) => ctx.openapiDocs,
+    },
+];

package/dist/templates/module-manifest.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODULE_FILES_MINIMAL = exports.MODULE_FILES = void 0;
+// output paths are relative to the module's own directory
+// (internal/app/<pkg> or internal/app/v<version>/<pkg>)
+exports.MODULE_FILES = [
+    { template: "generate/module/model/model.go.hbs", output: "model/model.go" },
+    { template: "generate/module/dto.go.hbs", output: "dto.go" },
+    { template: "generate/module/errors.go.hbs", output: "errors.go" },
+    { template: "generate/module/repository.go.hbs", output: "repository.go" },
+    { template: "generate/module/service.go.hbs", output: "service.go" },
+    { template: "generate/module/handler.go.hbs", output: "handler.go" },
+    { template: "generate/module/service_test.go.hbs", output: "service_test.go" },
+    { template: "generate/module/handler_test.go.hbs", output: "handler_test.go" },
+];
+// minimal: same model/errors/repository (generate method's patches assume the
+// full data-access surface exists), but no default CRUD in dto/service/handler
+// — add endpoints one at a time with `generate method`.
+exports.MODULE_FILES_MINIMAL = [
+    { template: "generate/module/model/model.go.hbs", output: "model/model.go" },
+    { template: "generate/module/minimal/dto.go.hbs", output: "dto.go" },
+    { template: "generate/module/errors.go.hbs", output: "errors.go" },
+    { template: "generate/module/repository.go.hbs", output: "repository.go" },
+    { template: "generate/module/minimal/service.go.hbs", output: "service.go" },
+    { template: "generate/module/minimal/handler.go.hbs", output: "handler.go" },
+    { template: "generate/module/minimal/service_test.go.hbs", output: "service_test.go" },
+    { template: "generate/module/minimal/handler_test.go.hbs", output: "handler_test.go" },
+];

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/config.js

@@ -0,0 +1,53 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configPath = configPath;
+exports.writeConfig = writeConfig;
+exports.readConfig = readConfig;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const CONFIG_FILE = "go-scaffold.config.json";
+function configPath(projectDir) {
+    return path_1.default.join(projectDir, CONFIG_FILE);
+}
+function writeConfig(projectDir, config) {
+    fs_extra_1.default.writeJsonSync(configPath(projectDir), config, { spaces: 2 });
+}
+// readConfig falls back to detecting from go.mod when the config file is
+// missing (e.g. a project scaffolded before this file existed).
+function readConfig(projectDir) {
+    const file = configPath(projectDir);
+    if (fs_extra_1.default.existsSync(file)) {
+        return fs_extra_1.default.readJsonSync(file);
+    }
+    return detectConfig(projectDir);
+}
+function detectConfig(projectDir) {
+    const goModPath = path_1.default.join(projectDir, "go.mod");
+    if (!fs_extra_1.default.existsSync(goModPath)) {
+        throw new Error(`no ${CONFIG_FILE} and no go.mod found in ${projectDir} — run this inside a go-scaffold project`);
+    }
+    const goMod = fs_extra_1.default.readFileSync(goModPath, "utf8");
+    const moduleMatch = goMod.match(/^module\s+(\S+)/m);
+    const goModule = moduleMatch ? moduleMatch[1] : path_1.default.basename(projectDir);
+    // parse the chosen prefix back out of `api := r.Group("/v1")` in main.go;
+    // an empty group (`r.Group("")`) or no match at all means no prefix.
+    let apiPrefix = "";
+    const mainGoPath = path_1.default.join(projectDir, "cmd", "api", "main.go");
+    if (fs_extra_1.default.existsSync(mainGoPath)) {
+        const groupMatch = fs_extra_1.default.readFileSync(mainGoPath, "utf8").match(/api\s*:=\s*r\.Group\("\/?([a-z0-9/]*)"\)/);
+        if (groupMatch)
+            apiPrefix = groupMatch[1];
+    }
+    return {
+        projectName: path_1.default.basename(projectDir),
+        goModule,
+        apiPrefix,
+        features: {
+            docker: fs_extra_1.default.existsSync(path_1.default.join(projectDir, "docker-compose.yml")),
+            openapiDocs: fs_extra_1.default.existsSync(path_1.default.join(projectDir, "docs", "openapi.yaml")),
+        },
+    };
+}

package/dist/utils/main-patcher.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchMainGo = patchMainGo;
+exports.unpatchMainGo = unpatchMainGo;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const marker_patch_1 = require("./marker-patch");
+const IMPORT_MARKER = "// go-scaffold:imports";
+const MODEL_MARKER = "// go-scaffold:models";
+const ROUTE_MARKER = "// go-scaffold:routes";
+// no leading tab: insertBeforeMarker re-indents, and removeLines matches by
+// trimmed text — so this stays correct regardless of gofmt's indentation.
+const UNUSED_API_LINE = "_ = api // dropped once `generate module` registers the first route";
+// the exact lines patchMainGo inserts for a module — one source of truth so
+// unpatchMainGo removes precisely what patch added.
+function mainGoLines(patch) {
+    const modelAlias = `${patch.pkg}model`; // every domain's model subpackage is named "model"
+    return {
+        importLine: `"${patch.goModule}/internal/app/${patch.modulePath}"`,
+        modelImportLine: `${modelAlias} "${patch.goModule}/internal/app/${patch.modulePath}/model"`,
+        migrateLine: `&${modelAlias}.${patch.pascalName}{},`,
+        // `api` is the one route group declared by main.go.hbs, prefixed with
+        // whatever apiPrefix the project chose at create time (e.g. /v1, /api,
+        // or none) — every module registers on it, there is no per-module choice.
+        routeLine: `${patch.pkg}.NewHandler(${patch.pkg}.NewService(${patch.pkg}.NewRepository(db))).Register(api)`,
+    };
+}
+// patchMainGo wires a newly generated module into cmd/api/main.go: its
+// import, its model in the AutoMigrate call, and its route registration —
+// via marker comments rather than a Go AST rewrite (ponytail: text insertion
+// at a fixed marker is enough here; reach for go/ast if main.go ever needs
+// edits markers can't express).
+function patchMainGo(mainGoPath, patch) {
+    let content = fs_extra_1.default.readFileSync(mainGoPath, "utf8");
+    const { importLine, modelImportLine, migrateLine, routeLine } = mainGoLines(patch);
+    // each guarded by its own sentinel so re-running after only the module
+    // folder was deleted (main.go still wired) is a no-op, not a dup that
+    // panics gin at startup.
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, importLine, importLine);
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, modelImportLine, modelImportLine);
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, migrateLine, migrateLine);
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, ROUTE_MARKER, routeLine, routeLine);
+    content = (0, marker_patch_1.removeLines)(content, [UNUSED_API_LINE]);
+    fs_extra_1.default.writeFileSync(mainGoPath, content);
+}
+// unpatchMainGo removes a module's wiring — the inverse of patchMainGo. If it
+// leaves no registered routes, it restores the `_ = api` placeholder so
+// main.go still compiles (api would otherwise be declared-and-unused).
+function unpatchMainGo(mainGoPath, patch) {
+    let content = fs_extra_1.default.readFileSync(mainGoPath, "utf8");
+    const { importLine, modelImportLine, migrateLine, routeLine } = mainGoLines(patch);
+    content = (0, marker_patch_1.removeLines)(content, [importLine, modelImportLine, migrateLine, routeLine]);
+    if (!content.includes(".Register(api)") && !content.includes(UNUSED_API_LINE)) {
+        content = (0, marker_patch_1.insertBeforeMarker)(content, ROUTE_MARKER, UNUSED_API_LINE);
+    }
+    fs_extra_1.default.writeFileSync(mainGoPath, content);
+}

package/dist/utils/marker-patch.js

@@ -0,0 +1,63 @@
+"use strict";
+// Shared text-marker patching: find a line that's exactly a marker comment,
+// insert a block right above it (re-indented to match), and leave the marker
+// in place so the next generate call can insert above it again.
+// ponytail: text insertion at a fixed marker, not a Go AST rewrite — good
+// enough for appending declarations; reach for go/ast if a patch ever needs
+// to understand existing code, not just append next to it.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasMarker = hasMarker;
+exports.ensureImport = ensureImport;
+exports.insertBeforeMarkerOnce = insertBeforeMarkerOnce;
+exports.removeLines = removeLines;
+exports.insertBeforeMarker = insertBeforeMarker;
+function hasMarker(content, marker) {
+    return content.split("\n").some((l) => l.trim() === marker);
+}
+// ensureImport adds an import line if it's not already present — needed
+// because a minimal module's handler.go starts without net/http/httpx/
+// pagination, and generate method's patches are the first thing to need
+// them. Idempotent, so repeat calls (e.g. two generate method calls) are
+// safe; doesn't attempt import grouping/sorting, just validity — run
+// goimports separately if you want that tidied up.
+function ensureImport(content, importPath) {
+    const importLine = `"${importPath}"`;
+    if (content.includes(importLine))
+        return content;
+    return content.replace(/import \(\n/, `import (\n\t${importLine}\n`);
+}
+// insertBeforeMarkerOnce: like insertBeforeMarker but a no-op if `sentinel`
+// already appears in the file. Makes module wiring idempotent — re-running
+// `generate module` after deleting just the module folder (leaving main.go /
+// openapi.yaml still referencing it) won't duplicate the import/route/path.
+// A duplicate route silently passes build+vet, then panics gin at startup
+// ("handlers are already registered"), so this guard matters.
+function insertBeforeMarkerOnce(content, marker, block, sentinel) {
+    if (content.includes(sentinel))
+        return content;
+    return insertBeforeMarker(content, marker, block);
+}
+// removeLines drops every line whose trimmed text exactly equals one of the
+// given lines — the inverse of insertBeforeMarker for `remove module`, which
+// needs to pull a module's import/route/path entries back out. Exact-trim
+// match so it can't clip an unrelated line that merely contains the text.
+function removeLines(content, trimmedLines) {
+    const drop = new Set(trimmedLines.map((l) => l.trim()));
+    return content
+        .split("\n")
+        .filter((l) => !drop.has(l.trim()))
+        .join("\n");
+}
+function insertBeforeMarker(content, marker, block) {
+    const lines = content.split("\n");
+    const markerLine = lines.find((l) => l.trim() === marker);
+    if (markerLine === undefined) {
+        throw new Error(`marker "${marker}" not found — the file may have been hand-edited; add the marker back or edit it by hand`);
+    }
+    const indent = markerLine.match(/^\s*/)?.[0] ?? "";
+    const indentedBlock = block
+        .split("\n")
+        .map((line) => (line ? `${indent}${line}` : line))
+        .join("\n");
+    return content.replace(markerLine, `${indentedBlock}\n${markerLine}`);
+}