@nakedev/go-scaffold 0.1.0

package/README.md

@@ -0,0 +1,223 @@
+# @nakedev/go-scaffold
+
+A CLI that scaffolds a Gin + GORM + PostgreSQL Go backend, then keeps
+generating consistent domain modules into that project as it grows — the Go
+counterpart to [nest-scaffold](../nest-scaffold).
+
+You don't hand-wire a new domain into `cmd/api/main.go`, write the
+handler/service/repository boilerplate, or decide error-handling conventions
+each time — the CLI does that, and every module it generates follows the
+same shape as the last one.
+
+## Install
+
+```bash
+pnpm install
+pnpm run build
+```
+
+`npm link` / `pnpm link --global` may not put the binary on your `PATH`
+depending on your machine's npm/pnpm global-bin config — rather than fight
+that, run the CLI directly, or add a shell alias once:
+
+```bash
+node bin/go-scaffold.js create my-api --defaults
+# or: alias go-scaffold="node $(pwd)/bin/go-scaffold.js"
+```
+
+The rest of this README uses the bare `go-scaffold ...` form for brevity —
+substitute the `node bin/go-scaffold.js ...` form or your alias if you
+haven't linked it.
+
+## Quick start
+
+```bash
+go-scaffold create my-api
+cd my-api
+make docker-up   # if you kept Docker + PostgreSQL
+go mod tidy
+make run
+```
+
+Then grow the project without leaving the CLI:
+
+```bash
+go-scaffold generate module orders
+go-scaffold generate method orders approve --type patch
+```
+
+## Commands
+
+### `create <name>` — scaffold a new project
+
+```bash
+go-scaffold create my-api                                   # interactive wizard
+go-scaffold create my-api --defaults                        # no prompts, CI-friendly
+go-scaffold create my-api --defaults --no-docker --api-prefix beta
+```
+
+Produces a **bare skeleton only** — `cmd/api`, the shared platform packages
+(config/apperror/dberr/httpx/id/middleware/pagination), Docker+Postgres,
+migrations folder, and the standards docs (`docs/architect/`, `AGENTS.md`,
+`CLAUDE.md`, `.claude/skills/go-scaffold/`). No domain modules — add those
+with `generate module`.
+
+| Option | Effect |
+|---|---|
+| `--defaults` | Skip the wizard, use defaults (Docker on, OpenAPI docs on, prefix `v1`) |
+| `--no-docker` | Skip `docker-compose.yml` (with `--defaults`) |
+| `--no-openapi-docs` | Skip `docs/openapi.yaml` (with `--defaults`) |
+| `--api-prefix <prefix>` | URL prefix every route is grouped under (with `--defaults`; default `v1`, `""` for none, `/`-separated segments like `api/v1` are fine) |
+
+Without `--defaults`, an interactive wizard asks the same three questions.
+The prefix is a single project-wide choice made once at `create` time —
+there's no per-domain versioning (a domain that needs a real breaking change
+gets a new domain package or a new DTO field, not a duplicated model pointed
+at the same table under a different URL — see "Why no per-domain versioning"
+below).
+
+**Config file** — every `create` writes `go-scaffold.config.json` to the
+project root; `generate` reads it back (or auto-detects from `go.mod` /
+directory layout if missing).
+
+### `generate module <name>` (alias `m`) — add a domain module
+
+```bash
+go-scaffold generate module orders                  # full CRUD (default)
+go-scaffold generate module orders --no-full         # minimal skeleton — add endpoints with `generate method`
+```
+
+Full CRUD (default) scaffolds:
+
+```text
+internal/app/orders/
+├── model/model.go      # domain model + GORM table (id/created_at/updated_at — add real fields yourself; a folder so multi-table domains can add more files)
+├── dto.go               # request/response structs (empty stubs — add real fields yourself)
+├── errors.go             # ORDERS_NOT_FOUND / ORDERS_CONFLICT / ORDERS_HAS_REFERENCES
+├── repository.go         # GORM data access
+├── service.go            # business logic + repository interface (mockable)
+├── handler.go            # Gin routes, registered under the project's API prefix
+├── service_test.go       # unit test, fake repo
+└── handler_test.go       # integration test, real Postgres, tx rollback
+```
+
+`--no-full` scaffolds the same `model`/`errors`/`repository` (so `generate
+method` always has a full data-access surface to call), but `dto`/`service`/
+`handler` start empty — no default CRUD, no routes, just the plumbing
+(`Register()`, the `repository` interface, `wrapFindErr`) that `generate
+method` patches into. Use it when a domain doesn't need the full REST
+surface, or you'd rather add endpoints one at a time.
+
+Both modes also:
+
+- Register the module in `cmd/api/main.go` (via marker comments — see
+  `// go-scaffold:*` in that file) — full wires an actual route, minimal
+  wires an empty route group
+- Add the model to the `AutoMigrate(...)` call
+- Append `migrations/<seq>_create_<plural>.{up,down}.sql`
+
+What it does **not** do: invent your fields or wire foreign keys between
+domains — see `docs/architect/patterns.md` in the generated project for the
+conventions to follow by hand.
+
+### `generate method <module> <name>` (alias `me`) — add one endpoint
+
+```bash
+go-scaffold generate method orders approve --type patch
+go-scaffold generate method orders findByStatus --type get --get-mode one --field status
+go-scaffold g me orders findOverdue --type get --get-mode all
+```
+
+Patches an *existing* module's `handler.go`/`service.go` in place via the
+same marker-comment approach as `main.go` — never a whole new module. Never
+overwrites a method with the same name; picks a different one or errors.
+
+| Option | Effect |
+|---|---|
+| `--type <get\|post\|put\|patch\|delete>` | HTTP verb |
+| `--get-mode <all\|one>` | For `get` only — list-style vs. single-record lookup |
+| `--field <name>` | For `get --get-mode one` — the lookup field (e.g. `email`, `status`); can't be `id` |
+
+| `--type` | Route | What's generated |
+|---|---|---|
+| `get --get-mode all` | `GET /<plural>/<kebab-name>` | reuses `FindAll` — TODO to add real filtering |
+| `get --get-mode one --field <f>` | `GET /<plural>/<f>/:<f>` | a real `FindBy<F>` query added to the repository (+ its interface + `fakeRepo` test stub) |
+| `post` | `POST /<plural>/<kebab-name>` | adds a body DTO; service is a TODO stub |
+| `put` / `patch` | `<VERB> /<plural>/:id/<kebab-name>` | finds by id, TODO before saving (safe no-op until implemented) |
+| `delete` | `DELETE /<plural>/:id/<kebab-name>` | TODO stub |
+
+Business logic is always left as a `TODO`-marked stub that compiles and
+returns a clean `500` rather than inventing behavior — see
+`docs/architect/patterns.md` in the generated project.
+
+`generate method` prints the route it added but does **not** touch
+`docs/openapi.yaml` — endpoint-specific spec entries stay hand-written.
+
+### `remove module <name>` (alias `rm m`) — drop a domain
+
+```bash
+go-scaffold remove module orders          # confirms first
+go-scaffold rm m orders --yes             # skip the confirm
+```
+
+The inverse of `generate module`: deletes `internal/app/<name>/` and reverses
+everything that was wired up — the import/AutoMigrate/route in `main.go`, the
+paths/schemas in `docs/openapi.yaml`, the per-module docs folder, and the
+`create_<plural>` migration. Restores the `_ = api` placeholder if it was the
+last module, so the project still builds. Use this instead of hand-deleting
+the folder — a partial hand-delete leaves stale wiring that duplicates on the
+next `generate module` (which would panic gin at startup).
+
+## Why no per-domain versioning
+
+Earlier versions of this CLI let a domain live in a `v1/`/`v2/` folder with
+its own route group and import alias, so the same domain name could exist
+twice with different behavior. It was cut: the migration (and usually the
+DB table) is shared between "versions" of the same domain, but each version
+got its own physically-copied `model.go` — nothing stopped the two structs
+from drifting apart. Verified against a real Postgres instance:
+`AutoMigrate` silently accepted a column typed `int` in one version's model
+and `float64` in the other for the *same* column, converging it to
+`numeric` with no error — the two versions would then read/write the same
+data with different, silently incompatible interpretations.
+
+Instead, every route in a project is grouped under a single project-wide
+`--api-prefix` (default `v1`) chosen once at `create` time. A domain that
+needs a real breaking change gets a new domain package, or a new field on
+the existing DTO — not a duplicated model pointed at a table it can drift
+out of sync with.
+
+## Project structure produced by `create`
+
+```text
+cmd/api/main.go
+internal/
+├── platform/database/
+├── shared/{config,apperror,dberr,httpx,id,middleware,pagination}/
+└── app/                      # empty until you `generate module`
+docs/
+├── architect/{architecture,patterns,techstack}.md
+└── openapi.yaml + common/ + health/   # if openapi docs enabled
+migrations/
+.github/workflows/ci.yml    # build, vet, gofmt check, golangci-lint, go test (with a Postgres service)
+Makefile
+.golangci.yml
+.vscode/settings.json
+AGENTS.md
+CLAUDE.md
+.claude/skills/go-scaffold/SKILL.md
+go-scaffold.config.json
+```
+
+## Supported stack
+
+| Package | Version |
+|---|---|
+| Gin | v1.10.0 |
+| GORM + postgres driver | v1.25.12 / v1.5.9 |
+| validator/v10 | v10.20.0 |
+| google/uuid | v1.6.0 |
+
+## License
+
+MIT

package/bin/go-scaffold.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../dist/index.js");

package/dist/commands/create.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProject = createProject;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const template_renderer_1 = require("../utils/template-renderer");
+const create_manifest_1 = require("../templates/create-manifest");
+const config_1 = require("../utils/config");
+const naming_1 = require("../utils/naming");
+const create_wizard_1 = require("../prompts/create-wizard");
+async function createProject(rawName, opts) {
+    const trimmed = (rawName ?? (await (0, create_wizard_1.promptProjectName)())).trim();
+    if (!trimmed)
+        throw new Error("project name is required");
+    (0, naming_1.assertValidGoModulePath)(trimmed);
+    const goModule = trimmed;
+    const projectName = trimmed.includes("/") ? trimmed.split("/").pop() : trimmed;
+    const projectDir = path_1.default.resolve(process.cwd(), projectName);
+    if (fs_extra_1.default.existsSync(projectDir) && fs_extra_1.default.readdirSync(projectDir).length > 0) {
+        throw new Error(`${projectDir} already exists and is not empty`);
+    }
+    let features;
+    let apiPrefix;
+    if (opts.defaults) {
+        features = { docker: opts.docker ?? true, openapiDocs: opts.openapiDocs ?? true };
+        apiPrefix = (0, naming_1.normalizeApiPrefix)(opts.apiPrefix ?? "v1");
+        const check = (0, naming_1.validateApiPrefix)(apiPrefix);
+        if (check !== true)
+            throw new Error(check);
+    }
+    else {
+        ({ features, apiPrefix } = await (0, create_wizard_1.runCreateWizard)());
+    }
+    const context = {
+        projectName,
+        goModule,
+        dbName: (0, naming_1.toDbName)(projectName),
+        apiPrefix,
+        ...features,
+    };
+    await fs_extra_1.default.ensureDir(projectDir);
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, create_manifest_1.CREATE_MANIFEST, context);
+    (0, template_renderer_1.gofmtTree)(projectDir);
+    (0, config_1.writeConfig)(projectDir, { projectName, goModule, apiPrefix, features });
+    console.log(picocolors_1.default.green(`\ncreated ${projectName}/`));
+    console.log(`\ncd ${projectName}`);
+    if (features.docker)
+        console.log(`make docker-up`);
+    console.log(`make db-create`);
+    console.log(`go mod tidy`);
+    console.log(`make run`);
+    console.log(picocolors_1.default.dim(`\nadd your first domain: go-scaffold generate module <name>`));
+}

package/dist/commands/generate.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateModule = generateModule;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const config_1 = require("../utils/config");
+const naming_1 = require("../utils/naming");
+const template_renderer_1 = require("../utils/template-renderer");
+const module_manifest_1 = require("../templates/module-manifest");
+const main_patcher_1 = require("../utils/main-patcher");
+const openapi_patcher_1 = require("../utils/openapi-patcher");
+const migrations_1 = require("../utils/migrations");
+const generate_wizard_1 = require("../prompts/generate-wizard");
+async function generateModule(rawName, opts, projectDir = process.cwd()) {
+    const config = (0, config_1.readConfig)(projectDir);
+    const naming = (0, naming_1.resolveModuleNaming)(rawName ?? (await (0, generate_wizard_1.promptModuleName)()));
+    const modulePath = naming.pkg;
+    const moduleDir = path_1.default.join(projectDir, "internal", "app", modulePath);
+    if (fs_extra_1.default.existsSync(moduleDir) && fs_extra_1.default.readdirSync(moduleDir).length > 0) {
+        throw new Error(`${moduleDir} already exists — pick a different name or delete it first`);
+    }
+    const context = {
+        ...naming,
+        goModule: config.goModule,
+        dbName: (0, naming_1.toDbName)(config.projectName),
+        modulePath,
+    };
+    const moduleFiles = opts.full ? module_manifest_1.MODULE_FILES : module_manifest_1.MODULE_FILES_MINIMAL;
+    const moduleEntries = moduleFiles.map((f) => ({
+        template: f.template,
+        output: path_1.default.join("internal", "app", modulePath, f.output),
+    }));
+    await (0, template_renderer_1.applyTemplateEntries)(projectDir, moduleEntries, context);
+    // skip if a create_<plural> migration already exists — re-running after
+    // only the module folder was deleted shouldn't leave a duplicate migration.
+    const migrationsDir = path_1.default.join(projectDir, "migrations");
+    const migrationExists = fs_extra_1.default.existsSync(migrationsDir) &&
+        fs_extra_1.default.readdirSync(migrationsDir).some((f) => f.endsWith(`_create_${naming.plural}.up.sql`));
+    let seq = "";
+    if (!migrationExists) {
+        seq = (0, migrations_1.nextMigrationSeq)(migrationsDir);
+        const migrationEntries = [
+            {
+                template: "generate/module/migration.up.sql.hbs",
+                output: path_1.default.join("migrations", `${seq}_create_${naming.plural}.up.sql`),
+            },
+            {
+                template: "generate/module/migration.down.sql.hbs",
+                output: path_1.default.join("migrations", `${seq}_create_${naming.plural}.down.sql`),
+            },
+        ];
+        await (0, template_renderer_1.applyTemplateEntries)(projectDir, migrationEntries, context);
+    }
+    const mainGoPath = path_1.default.join(projectDir, "cmd", "api", "main.go");
+    (0, main_patcher_1.patchMainGo)(mainGoPath, {
+        goModule: config.goModule,
+        modulePath,
+        pkg: naming.pkg,
+        pascalName: naming.pascalName,
+    });
+    let docsMessage = "";
+    const openapiPath = path_1.default.join(projectDir, "docs", "openapi.yaml");
+    if (opts.full && config.features.openapiDocs && fs_extra_1.default.existsSync(openapiPath)) {
+        const docsEntries = [
+            { template: "generate/module/docs/collection.yaml.hbs", output: path_1.default.join("docs", naming.plural, "collection.yaml") },
+            { template: "generate/module/docs/item.yaml.hbs", output: path_1.default.join("docs", naming.plural, "item.yaml") },
+            { template: "generate/module/docs/schemas.yaml.hbs", output: path_1.default.join("docs", naming.plural, "schemas.yaml") },
+        ];
+        await (0, template_renderer_1.applyTemplateEntries)(projectDir, docsEntries, context);
+        (0, openapi_patcher_1.patchOpenapiIndex)(openapiPath, naming, config.apiPrefix);
+        docsMessage = `\ndocs: docs/${naming.plural}/{collection,item,schemas}.yaml, wired into docs/openapi.yaml`;
+    }
+    (0, template_renderer_1.gofmtTree)(projectDir);
+    const routePath = config.apiPrefix ? `/${config.apiPrefix}/${naming.plural}` : `/${naming.plural}`;
+    console.log(picocolors_1.default.green(`\ngenerated internal/app/${modulePath}/`));
+    if (opts.full) {
+        console.log(`registered route ${routePath} in cmd/api/main.go`);
+    }
+    else {
+        console.log(`registered empty route group ${routePath} in cmd/api/main.go — ` +
+            `add endpoints with \`go-scaffold generate method ${naming.pkg} <name> --type ...\``);
+    }
+    if (seq) {
+        console.log(`migration: migrations/${seq}_create_${naming.plural}.{up,down}.sql`);
+    }
+    else {
+        console.log(`migration: reused existing migrations/*_create_${naming.plural}.{up,down}.sql`);
+    }
+    if (docsMessage)
+        console.log(docsMessage);
+    console.log(picocolors_1.default.dim(`\nnext: add real fields to model.go/dto.go, run \`go build ./...\`, then apply the migration ` +
+        `(AUTO_MIGRATE=true handles it in dev, or \`migrate -path migrations -database "$DB_DSN" up\`)`));
+}

package/dist/commands/method.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateMethod = generateMethod;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const config_1 = require("../utils/config");
+const naming_1 = require("../utils/naming");
+const method_patcher_1 = require("../utils/method-patcher");
+const template_renderer_1 = require("../utils/template-renderer");
+const generate_wizard_1 = require("../prompts/generate-wizard");
+// the actual URL the new route answers on — printed so the user can add the
+// matching openapi.yaml entry by hand (methods are deliberately not wired into
+// the spec; see the note in docs/openapi.yaml). Mirrors the paths registered
+// in method-patcher.ts.
+function routeHint(naming, method, type, apiPrefix, getMode, field) {
+    const base = apiPrefix ? `/${apiPrefix}/${naming.plural}` : `/${naming.plural}`;
+    if (type === "get" && getMode === "all")
+        return `GET ${base}/${method.pathSegment}`;
+    if (type === "get")
+        return `GET ${base}/${(0, naming_1.toDbName)(field ?? "")}/{${(0, naming_1.toCamelCase)(field ?? "")}}`;
+    if (type === "post")
+        return `POST ${base}/${method.pathSegment}`;
+    if (type === "delete")
+        return `DELETE ${base}/{id}/${method.pathSegment}`;
+    return `${type.toUpperCase()} ${base}/{id}/${method.pathSegment}`;
+}
+async function generateMethod(moduleNameArg, methodNameArg, opts, projectDir = process.cwd()) {
+    const config = (0, config_1.readConfig)(projectDir);
+    const naming = (0, naming_1.resolveModuleNaming)(moduleNameArg ?? (await (0, generate_wizard_1.promptModuleName)()));
+    const modulePath = naming.pkg;
+    const moduleDir = path_1.default.join(projectDir, "internal", "app", modulePath);
+    const paths = {
+        dtoPath: path_1.default.join(moduleDir, "dto.go"),
+        repositoryPath: path_1.default.join(moduleDir, "repository.go"),
+        servicePath: path_1.default.join(moduleDir, "service.go"),
+        handlerPath: path_1.default.join(moduleDir, "handler.go"),
+        serviceTestPath: path_1.default.join(moduleDir, "service_test.go"),
+    };
+    for (const p of Object.values(paths)) {
+        if (!fs_extra_1.default.existsSync(p)) {
+            throw new Error(`module "${naming.pkg}" not found at ${moduleDir} (missing ${path_1.default.basename(p)}) — ` +
+                `run \`go-scaffold generate module ${naming.pkg}\` first`);
+        }
+    }
+    const type = opts.type ?? (await (0, generate_wizard_1.promptMethodType)());
+    if (opts.getMode && type !== "get") {
+        throw new Error("--get-mode can only be used with --type get");
+    }
+    if (opts.field && !(type === "get" && opts.getMode === "one")) {
+        throw new Error("--field can only be used with --type get --get-mode one");
+    }
+    const getMode = type === "get" ? opts.getMode ?? (await (0, generate_wizard_1.promptGetMode)()) : undefined;
+    const field = type === "get" && getMode === "one" ? opts.field ?? (await (0, generate_wizard_1.promptLookupField)()) : undefined;
+    // field becomes a Go param name (`func (...)(ctx, <field> string)`)
+    if (field)
+        (0, naming_1.assertNotGoKeyword)((0, naming_1.toCamelCase)(field), "lookup field");
+    const method = (0, naming_1.resolveMethodNaming)(methodNameArg ?? (await (0, generate_wizard_1.promptMethodName)()));
+    (0, method_patcher_1.patchMethod)(paths, naming, method, { type, getMode, field }, config.goModule);
+    (0, template_renderer_1.gofmtTree)(projectDir);
+    console.log(picocolors_1.default.green(`\nadded "${method.name}" to internal/app/${modulePath}/`));
+    console.log(`route: ${routeHint(naming, method, type, config.apiPrefix, getMode, field)}`);
+    if (config.features.openapiDocs) {
+        console.log(picocolors_1.default.yellow(`docs: add this route to docs/openapi.yaml by hand — \`generate method\` doesn't touch the spec`));
+    }
+    console.log(picocolors_1.default.dim(`\nnext: fill in the TODO in service.go, then \`go build ./...\` / \`go test ./...\``));
+}

package/dist/commands/remove.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeModule = removeModule;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const prompts_1 = require("@inquirer/prompts");
+const config_1 = require("../utils/config");
+const naming_1 = require("../utils/naming");
+const main_patcher_1 = require("../utils/main-patcher");
+const openapi_patcher_1 = require("../utils/openapi-patcher");
+const template_renderer_1 = require("../utils/template-renderer");
+const generate_wizard_1 = require("../prompts/generate-wizard");
+// removeModule is the inverse of generateModule: deletes the domain package and
+// pulls its wiring back out of main.go / openapi.yaml / migrations, so dropping
+// a domain is one command instead of hand-editing 3+ files (the error-prone
+// path that produced the duplicate-registration bug in the first place).
+async function removeModule(rawName, opts, projectDir = process.cwd()) {
+    const config = (0, config_1.readConfig)(projectDir);
+    const naming = (0, naming_1.resolveModuleNaming)(rawName ?? (await (0, generate_wizard_1.promptModuleName)()));
+    const modulePath = naming.pkg;
+    const moduleDir = path_1.default.join(projectDir, "internal", "app", modulePath);
+    if (!fs_extra_1.default.existsSync(moduleDir)) {
+        throw new Error(`module "${naming.pkg}" not found at internal/app/${modulePath} — nothing to remove`);
+    }
+    if (!opts.yes) {
+        const ok = await (0, prompts_1.confirm)({
+            message: `Remove module "${naming.pkg}"? Deletes internal/app/${modulePath}/, its migration, and un-wires main.go/openapi.yaml`,
+            default: false,
+        });
+        if (!ok)
+            throw new Error("removal cancelled");
+    }
+    // 1. the domain package
+    fs_extra_1.default.removeSync(moduleDir);
+    // 2. main.go wiring
+    (0, main_patcher_1.unpatchMainGo)(path_1.default.join(projectDir, "cmd", "api", "main.go"), {
+        goModule: config.goModule,
+        modulePath,
+        pkg: naming.pkg,
+        pascalName: naming.pascalName,
+    });
+    // 3. openapi index + per-module docs
+    const openapiPath = path_1.default.join(projectDir, "docs", "openapi.yaml");
+    if (fs_extra_1.default.existsSync(openapiPath)) {
+        (0, openapi_patcher_1.unpatchOpenapiIndex)(openapiPath, naming, config.apiPrefix);
+        fs_extra_1.default.removeSync(path_1.default.join(projectDir, "docs", naming.plural));
+    }
+    // 4. migration files (up + down)
+    const migrationsDir = path_1.default.join(projectDir, "migrations");
+    const removedMigrations = [];
+    if (fs_extra_1.default.existsSync(migrationsDir)) {
+        for (const f of fs_extra_1.default.readdirSync(migrationsDir)) {
+            if (f.endsWith(`_create_${naming.plural}.up.sql`) || f.endsWith(`_create_${naming.plural}.down.sql`)) {
+                fs_extra_1.default.removeSync(path_1.default.join(migrationsDir, f));
+                removedMigrations.push(f);
+            }
+        }
+    }
+    (0, template_renderer_1.gofmtTree)(projectDir);
+    console.log(picocolors_1.default.green(`\nremoved module "${naming.pkg}"`));
+    console.log(`  deleted internal/app/${modulePath}/`);
+    console.log(`  un-wired cmd/api/main.go`);
+    if (fs_extra_1.default.existsSync(openapiPath))
+        console.log(`  un-wired docs/openapi.yaml + deleted docs/${naming.plural}/`);
+    if (removedMigrations.length)
+        console.log(`  deleted ${removedMigrations.join(", ")}`);
+    console.log(picocolors_1.default.yellow(`\nnote: the ${naming.plural} table (if migrated) is untouched — drop it yourself, or add a down migration`));
+}

package/dist/index.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const prompts_1 = require("@inquirer/prompts");
+const picocolors_1 = __importDefault(require("picocolors"));
+const create_1 = require("./commands/create");
+const generate_1 = require("./commands/generate");
+const method_1 = require("./commands/method");
+const remove_1 = require("./commands/remove");
+const program = new commander_1.Command();
+program
+    .name("go-scaffold")
+    .description("Scaffold Gin + GORM + Postgres Go backend projects with a consistent domain-module standard")
+    .version("0.1.0");
+program
+    .command("create [name]")
+    .alias("c")
+    .description("scaffold a new project (bare skeleton — add domains with `generate module`)")
+    .option("--defaults", "skip the wizard, use defaults (for CI/scripting)")
+    .option("--no-docker", "skip docker-compose.yml (only applies with --defaults)")
+    .option("--no-openapi-docs", "skip docs/openapi.yaml (only applies with --defaults)")
+    .option("--api-prefix <prefix>", 'URL prefix every route is grouped under (default "v1"; pass "" for none)')
+    .action(async (name, opts) => {
+    try {
+        await (0, create_1.createProject)(name, {
+            defaults: opts.defaults,
+            docker: opts.docker,
+            openapiDocs: opts.openapiDocs,
+            apiPrefix: opts.apiPrefix,
+        });
+    }
+    catch (err) {
+        console.error(picocolors_1.default.red(err.message));
+        process.exitCode = 1;
+    }
+});
+const generate = program
+    .command("generate")
+    .alias("g")
+    .description("add to an existing go-scaffold project")
+    .action(async () => {
+    // bare `generate`/`g` — ask which target, then delegate (each subcommand
+    // still prompts for anything else it's missing, e.g. the name).
+    try {
+        const target = await (0, prompts_1.select)({
+            message: "What do you want to generate?",
+            choices: [
+                { name: "Module (full CRUD domain)", value: "module" },
+                { name: "Method (add one endpoint to an existing module)", value: "method" },
+            ],
+        });
+        if (target === "module") {
+            await (0, generate_1.generateModule)(undefined, { full: true });
+        }
+        else {
+            await (0, method_1.generateMethod)(undefined, undefined, {});
+        }
+    }
+    catch (err) {
+        console.error(picocolors_1.default.red(err.message));
+        process.exitCode = 1;
+    }
+});
+generate
+    .command("module [name]")
+    .alias("m")
+    .description("scaffold a domain module — full CRUD by default, or a bare skeleton with --no-full")
+    .option("--no-full", "minimal skeleton (model/errors/repository, no default CRUD) — add endpoints one at a time with `generate method`")
+    .action(async (name, opts) => {
+    try {
+        await (0, generate_1.generateModule)(name, { full: opts.full });
+    }
+    catch (err) {
+        console.error(picocolors_1.default.red(err.message));
+        process.exitCode = 1;
+    }
+});
+generate
+    .command("method [module] [name]")
+    .alias("me")
+    .description("add one endpoint to an existing module (patches handler/service in place)")
+    .option("--type <type>", "get|post|put|patch|delete")
+    .option("--get-mode <mode>", "for --type get only: all|one")
+    .option("--field <name>", "for --type get --get-mode one: the lookup field (e.g. email, status)")
+    .action(async (moduleName, methodName, opts) => {
+    try {
+        const type = opts.type;
+        if (type && !["get", "post", "put", "patch", "delete"].includes(type)) {
+            throw new Error(`--type must be one of: get, post, put, patch, delete (got "${type}")`);
+        }
+        const getMode = opts.getMode;
+        if (getMode && !["all", "one"].includes(getMode)) {
+            throw new Error(`--get-mode must be "all" or "one" (got "${getMode}")`);
+        }
+        await (0, method_1.generateMethod)(moduleName, methodName, {
+            type,
+            getMode,
+            field: opts.field,
+        });
+    }
+    catch (err) {
+        console.error(picocolors_1.default.red(err.message));
+        process.exitCode = 1;
+    }
+});
+const remove = program
+    .command("remove")
+    .alias("rm")
+    .description("remove a domain module (deletes the package + un-wires main.go/openapi.yaml/migration)")
+    .action(async () => {
+    // bare `remove`/`rm` — module is the only target, so prompt for the name
+    try {
+        await (0, remove_1.removeModule)(undefined, {});
+    }
+    catch (err) {
+        console.error(picocolors_1.default.red(err.message));
+        process.exitCode = 1;
+    }
+});
+remove
+    .command("module [name]")
+    .alias("m")
+    .description("delete a domain module and reverse everything `generate module` wired up")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .action(async (name, opts) => {
+    try {
+        await (0, remove_1.removeModule)(name, { yes: opts.yes });
+    }
+    catch (err) {
+        console.error(picocolors_1.default.red(err.message));
+        process.exitCode = 1;
+    }
+});
+program.parseAsync(process.argv);