@nakedev/go-scaffold 0.1.3 → 0.1.4

package/README.md

@@ -87,25 +87,26 @@ 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`
+go-scaffold generate module orders                  # safe minimal module (default)
+go-scaffold generate module orders --full           # opt-in CRUD skeleton
 ```
 
-Full CRUD (default) scaffolds:
+`--full` scaffolds:
 
 ```text
-internal/app/orders/
+internal/app/order/
 ├── 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
+├── errors.go             # ORDER_NOT_FOUND / ORDER_CONFLICT / ORDER_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
+├── service_test.go       # unit test, function-backed repository stub
+├── handler_test.go       # HTTP unit test, service stub, no DB
+└── repository_test.go    # Postgres integration test against migrated schema
 ```
 
-`--no-full` scaffolds the same `model`/`errors`/`repository` (so `generate
+The default minimal mode 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
@@ -145,7 +146,7 @@ overwrites a method with the same name; picks a different one or errors.
 | `--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) |
+| `get --get-mode one --field <f>` | `GET /<plural>/<f>/:<f>` | a real `FindBy<F>` query added to the repository (+ its interface + function-backed repository 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 |
@@ -154,8 +155,9 @@ 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.
+When OpenAPI docs are enabled, `generate method` also creates a valid TODO stub
+under `docs/<plural>/methods/` and wires the route into `docs/openapi.yaml`.
+Replace its placeholder request/response schemas while implementing the TODO.
 
 **Drift check** — `generate` type-checks the project (`go vet ./...`) before and
 after it writes. If the project was fine beforehand and the generated code
@@ -240,9 +242,11 @@ 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
+the import/AutoMigrate/route in `main.go`, paths/schemas in `docs/openapi.yaml`,
+and the per-module docs folder. **Existing migrations are preserved** because
+production may already have recorded those immutable versions. The table/data
+are also untouched; create a new `generate migration drop_<table>` migration
+when removal is intentional. 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).

package/dist/commands/generate.js

@@ -9,6 +9,7 @@ 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 module_location_1 = require("../utils/module-location");
 const template_renderer_1 = require("../utils/template-renderer");
 const module_manifest_1 = require("../templates/module-manifest");
 const main_patcher_1 = require("../utils/main-patcher");
@@ -36,7 +37,7 @@ async function generateModule(rawName, opts, projectDir = process.cwd()) {
             throw new Error(`invalid permission code "${opts.permission}" — must start with a lowercase letter and contain only lowercase letters, digits, ':', '_', or '-'`);
         }
     }
-    const naming = (0, naming_1.resolveModuleNaming)(rawName ?? (await (0, generate_wizard_1.promptModuleName)()));
+    const naming = (0, module_location_1.resolveProjectModuleNaming)(projectDir, 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) {

package/dist/commands/method.js

@@ -9,29 +9,61 @@ 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 module_location_1 = require("../utils/module-location");
 const method_patcher_1 = require("../utils/method-patcher");
 const gocheck_1 = require("../utils/gocheck");
 const template_renderer_1 = require("../utils/template-renderer");
+const openapi_patcher_1 = require("../utils/openapi-patcher");
 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}`;
+// URL path registered in method-patcher.ts, excluding the project-wide API
+// prefix so it can be passed directly to patchOpenapiIndexRaw.
+function methodRoutePath(naming, method, type, getMode, field) {
+    const base = `/${naming.plural}`;
     if (type === "get" && getMode === "all")
-        return `GET ${base}/${method.pathSegment}`;
+        return `${base}/${method.pathSegment}`;
     if (type === "get")
-        return `GET ${base}/${(0, naming_1.toDbName)(field ?? "")}/{${(0, naming_1.toCamelCase)(field ?? "")}}`;
+        return `${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}`;
+        return `${base}/${method.pathSegment}`;
+    return `${base}/{id}/${method.pathSegment}`;
+}
+function routeHint(naming, method, type, apiPrefix, getMode, field) {
+    const path = methodRoutePath(naming, method, type, getMode, field);
+    const prefixed = apiPrefix ? `/${apiPrefix}${path}` : path;
+    return `${type.toUpperCase()} ${prefixed}`;
+}
+function methodOpenapiDocument(naming, method, type, getMode, field) {
+    const pathParameters = [];
+    if (type === "get" && getMode === "one") {
+        const parameter = (0, naming_1.toCamelCase)(field ?? "");
+        pathParameters.push("parameters:", `  - name: ${parameter}`, "    in: path", "    required: true", "    schema:", "      type: string");
+    }
+    else if (type === "put" || type === "patch" || type === "delete") {
+        pathParameters.push("parameters:", "  - name: id", "    in: path", "    required: true", "    schema:", "      type: string", "      format: uuid");
+    }
+    const operation = [
+        `${type}:`,
+        `  summary: TODO document ${method.name}`,
+        `  operationId: ${method.handlerName}${naming.pascalName}`,
+        `  tags: [${naming.plural}]`,
+    ];
+    if (type === "post") {
+        operation.push("  requestBody:", "    required: true", "    content:", "      application/json:", "        schema:", "          type: object", "          description: TODO define request fields");
+    }
+    const status = type === "delete" ? "204" : type === "post" ? "201" : "200";
+    operation.push("  responses:", `    \"${status}\":`, `      description: ${type === "delete" ? "completed or already absent" : "TODO define response"}`);
+    if (type !== "delete") {
+        operation.push("      content:", "        application/json:", "          schema:", "            type: object", "            description: TODO replace with the method response schema");
+    }
+    operation.push("    \"400\": { $ref: '../../common/responses.yaml#/ValidationError' }");
+    if (type === "get" || type === "put" || type === "patch") {
+        operation.push("    \"404\": { $ref: '../../common/responses.yaml#/NotFoundError' }");
+    }
+    return [...pathParameters, ...operation, ""].join("\n");
 }
 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 naming = (0, module_location_1.resolveProjectModuleNaming)(projectDir, moduleNameArg ?? (await (0, generate_wizard_1.promptModuleName)()));
     const modulePath = naming.pkg;
     const moduleDir = path_1.default.join(projectDir, "internal", "app", modulePath);
     const paths = {
@@ -60,14 +92,30 @@ async function generateMethod(moduleNameArg, methodNameArg, opts, projectDir = p
     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)()));
+    const docsRelativePath = config.features.openapiDocs
+        ? `${naming.plural}/methods/${method.pathSegment}.yaml`
+        : undefined;
+    if (docsRelativePath && fs_extra_1.default.existsSync(path_1.default.join(projectDir, "docs", docsRelativePath))) {
+        throw new Error(`OpenAPI method document already exists: docs/${docsRelativePath}`);
+    }
     const checkBefore = (0, gocheck_1.typeChecks)(projectDir);
     (0, method_patcher_1.patchMethod)(paths, naming, method, { type, getMode, field }, config.goModule);
     (0, template_renderer_1.gofmtTree)(projectDir);
     (0, gocheck_1.assertNoDrift)(projectDir, checkBefore, config);
+    if (docsRelativePath) {
+        const docsPath = path_1.default.join(projectDir, "docs", docsRelativePath);
+        fs_extra_1.default.outputFileSync(docsPath, methodOpenapiDocument(naming, method, type, getMode, field));
+        (0, openapi_patcher_1.patchOpenapiIndexRaw)(path_1.default.join(projectDir, "docs", "openapi.yaml"), config.apiPrefix, [
+            {
+                urlPath: methodRoutePath(naming, method, type, getMode, field),
+                file: `./${docsRelativePath}`,
+            },
+        ]);
+    }
     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`));
+    if (docsRelativePath) {
+        console.log(picocolors_1.default.green(`docs: docs/${docsRelativePath} (wired into docs/openapi.yaml)`));
     }
     console.log(picocolors_1.default.dim(`\nnext: fill in the TODO in service.go, then \`go build ./...\` / \`go test ./...\``));
 }

package/dist/commands/remove.js

@@ -9,18 +9,17 @@ 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 module_location_1 = require("../utils/module-location");
 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).
+// removeModule deletes application code and reverses generated wiring while
+// preserving immutable migration history and table data. Destructive schema
+// removal must be an explicit new migration, never a deletion of an applied one.
 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 naming = (0, module_location_1.resolveProjectModuleNaming)(projectDir, 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)) {
@@ -28,7 +27,8 @@ async function removeModule(rawName, opts, projectDir = process.cwd()) {
     }
     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`,
+            message: `Remove module "${naming.pkg}"? Deletes internal/app/${modulePath}/ and its docs, ` +
+                `then un-wires main.go/openapi.yaml. Existing migrations, table, and data are preserved.`,
             default: false,
         });
         if (!ok)
@@ -62,28 +62,27 @@ async function removeModule(rawName, opts, projectDir = process.cwd()) {
         (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) — including the --permission seed
-    // migration, if this module was generated with one.
+    // 4. Migration history is immutable. A migration may already be recorded in
+    // schema_migrations on production databases, so deleting its file would make
+    // existing and fresh environments disagree and can prevent the app booting.
+    // Re-generating the same module reuses this create migration.
     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`) ||
-                f.endsWith(`_add_${naming.plural}_permission.up.sql`) ||
-                f.endsWith(`_add_${naming.plural}_permission.down.sql`)) {
-                fs_extra_1.default.removeSync(path_1.default.join(migrationsDir, f));
-                removedMigrations.push(f);
-            }
-        }
-    }
+    const preservedMigrations = fs_extra_1.default.existsSync(migrationsDir)
+        ? fs_extra_1.default.readdirSync(migrationsDir).filter((f) => f.endsWith(`_create_${naming.plural}.up.sql`) ||
+            f.endsWith(`_create_${naming.plural}.down.sql`) ||
+            f.endsWith(`_add_${naming.plural}_permission.up.sql`) ||
+            f.endsWith(`_add_${naming.plural}_permission.down.sql`))
+        : [];
     (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`));
+    if (preservedMigrations.length) {
+        console.log(`  preserved migration history: ${preservedMigrations.join(", ")}`);
+    }
+    console.log(picocolors_1.default.yellow(`\nnote: the ${naming.tableName} table and its data are untouched. ` +
+        `To remove them safely, run \`go-scaffold generate migration drop_${naming.tableName}\` ` +
+        `and write an explicit up/down migration.`));
 }

package/dist/index.js

@@ -56,13 +56,13 @@ const generate = program
         const target = await (0, prompts_1.select)({
             message: "What do you want to generate?",
             choices: [
-                { name: "Module (full CRUD domain)", value: "module" },
+                { name: "Module (safe minimal domain; add methods explicitly)", value: "module" },
                 { name: "Method (add one endpoint to an existing module)", value: "method" },
                 { name: "Migration (reserve a timestamped up/down SQL file pair)", value: "migration" },
             ],
         });
         if (target === "module") {
-            await (0, generate_1.generateModule)(undefined, { full: true });
+            await (0, generate_1.generateModule)(undefined, { full: false });
         }
         else if (target === "method") {
             await (0, method_1.generateMethod)(undefined, undefined, {});
@@ -79,8 +79,9 @@ const generate = program
 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`")
+    .description("scaffold a safe minimal domain module; opt into a CRUD skeleton with --full")
+    .option("--full", "generate a CRUD skeleton (DTO fields/business rules remain TODO); minimal is the safe default")
+    .option("--no-full", "deprecated compatibility alias; minimal is already the default")
     .option("--auth", "require a valid access token for this module's routes (needs `add auth`)")
     .option("--permission <code>", "also require this permission via authz.Require (needs `add rbac`; implies --auth)")
     .action(async (name, opts) => {

package/dist/templates/module-manifest.js

@@ -12,6 +12,7 @@ exports.MODULE_FILES = [
     { 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" },
+    { template: "generate/module/repository_test.go.hbs", output: "repository_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
@@ -25,4 +26,5 @@ exports.MODULE_FILES_MINIMAL = [
     { 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" },
+    { template: "generate/module/repository_test.go.hbs", output: "repository_test.go" },
 ];

package/dist/utils/method-patcher.js

@@ -12,9 +12,12 @@ 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 SERVICE_INTERFACE_MARKER = "// go-scaffold:service-interface";
 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 REPOSITORY_STUB_FIELDS_MARKER = "// go-scaffold:repository-stub-fields";
+const REPOSITORY_STUB_METHODS_MARKER = "// go-scaffold:repository-stub-methods";
+const LEGACY_FAKE_REPO_METHODS_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
@@ -62,6 +65,48 @@ function patchMethod(paths, naming, method, opts, goModule) {
     else {
         patchDelete(paths, method, goModule);
     }
+    patchHandlerServiceInterface(paths.handlerPath, naming, method, opts, goModule);
+}
+function patchHandlerServiceInterface(handlerPath, naming, method, opts, goModule) {
+    let signature;
+    let needsModel = true;
+    let needsUUID = false;
+    if (opts.type === "get" && opts.getMode === "all") {
+        signature = `${method.pascalName}(context.Context, int, int) ([]model.${naming.pascalName}, error)`;
+    }
+    else if (opts.type === "get") {
+        signature = `${method.pascalName}(context.Context, string) (*model.${naming.pascalName}, error)`;
+    }
+    else if (opts.type === "post") {
+        signature = `${method.pascalName}(context.Context, ${method.pascalName}Input) (*model.${naming.pascalName}, error)`;
+    }
+    else if (opts.type === "put" || opts.type === "patch") {
+        signature = `${method.pascalName}(context.Context, uuid.UUID) (*model.${naming.pascalName}, error)`;
+        needsUUID = true;
+    }
+    else {
+        signature = `${method.pascalName}(context.Context, uuid.UUID) error`;
+        needsModel = false;
+        needsUUID = true;
+    }
+    let handler = fs_extra_1.default.readFileSync(handlerPath, "utf8");
+    if (!(0, marker_patch_1.hasMarker)(handler, SERVICE_INTERFACE_MARKER)) {
+        // Projects scaffolded before the narrow service interface stored *Service
+        // directly. The concrete type already exposes generated methods, so there
+        // is no interface declaration to patch and no migration is required.
+        if (handler.includes("svc *Service"))
+            return;
+        throw new Error(`marker "${SERVICE_INTERFACE_MARKER}" not found and Handler does not use legacy *Service wiring`);
+    }
+    handler = (0, marker_patch_1.insertBeforeMarker)(handler, SERVICE_INTERFACE_MARKER, signature);
+    handler = (0, marker_patch_1.ensureImport)(handler, "context");
+    if (needsModel) {
+        handler = (0, marker_patch_1.ensureImport)(handler, `${goModule}/internal/app/${naming.pkg}/model`);
+    }
+    if (needsUUID) {
+        handler = (0, marker_patch_1.ensureImport)(handler, "github.com/google/uuid");
+    }
+    fs_extra_1.default.writeFileSync(handlerPath, handler);
 }
 function patchGetAll(paths, naming, method, goModule) {
     let handler = fs_extra_1.default.readFileSync(paths.handlerPath, "utf8");
@@ -117,22 +162,40 @@ function patchGetOne(paths, naming, method, rawField, goModule) {
     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
+    // The repository interface just grew, so the test double needs a matching
+    // method or focused service tests stop compiling. New projects use a
+    // function-backed stub; projects scaffolded before that refactor retain the
+    // old fakeRepo marker and error behavior.
     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"));
+    if ((0, marker_patch_1.hasMarker)(serviceTest, REPOSITORY_STUB_FIELDS_MARKER) &&
+        (0, marker_patch_1.hasMarker)(serviceTest, REPOSITORY_STUB_METHODS_MARKER)) {
+        serviceTest = (0, marker_patch_1.insertBeforeMarker)(serviceTest, REPOSITORY_STUB_FIELDS_MARKER, `findBy${fieldPascal}Fn func(context.Context, string) (*model.${naming.pascalName}, error)`);
+        serviceTest = (0, marker_patch_1.insertBeforeMarker)(serviceTest, REPOSITORY_STUB_METHODS_MARKER, [
+            `//nolint:unused`,
+            `func (s *repositoryStub) FindBy${fieldPascal}(ctx context.Context, value string) (*model.${naming.pascalName}, error) {`,
+            `\tif s.findBy${fieldPascal}Fn == nil {`,
+            `\t\tpanic("unexpected repository.FindBy${fieldPascal} call")`,
+            `\t}`,
+            `\treturn s.findBy${fieldPascal}Fn(ctx, value)`,
+            `}`,
+            ``,
+        ].join("\n"));
+    }
+    else if ((0, marker_patch_1.hasMarker)(serviceTest, LEGACY_FAKE_REPO_METHODS_MARKER)) {
+        serviceTest = (0, marker_patch_1.insertBeforeMarker)(serviceTest, LEGACY_FAKE_REPO_METHODS_MARKER, [
+            `//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"));
+    }
+    else {
+        throw new Error(`neither current repository stub markers nor legacy "${LEGACY_FAKE_REPO_METHODS_MARKER}" found in ${paths.serviceTestPath}`);
+    }
     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) {`,
@@ -266,6 +329,7 @@ function markersPresent(handlerPath, servicePath) {
     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)(handler, SERVICE_INTERFACE_MARKER) || handler.includes("svc *Service")) &&
         (0, marker_patch_1.hasMarker)(service, SERVICE_MARKER) &&
         (0, marker_patch_1.hasMarker)(service, REPO_INTERFACE_MARKER));
 }

package/dist/utils/module-location.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.existingModulePackages = existingModulePackages;
+exports.resolveProjectModuleNaming = resolveProjectModuleNaming;
+const path_1 = __importDefault(require("path"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const naming_1 = require("./naming");
+function existingModulePackages(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((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+}
+function resolveProjectModuleNaming(projectDir, rawName) {
+    return (0, naming_1.resolveExistingModuleNaming)(rawName, existingModulePackages(projectDir));
+}

package/dist/utils/naming.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.pluralize = pluralize;
 exports.toPascalCase = toPascalCase;
@@ -13,18 +16,14 @@ exports.validateModuleName = validateModuleName;
 exports.normalizeApiPrefix = normalizeApiPrefix;
 exports.validateApiPrefix = validateApiPrefix;
 exports.resolveModuleNaming = resolveModuleNaming;
+exports.resolveExistingModuleNaming = resolveExistingModuleNaming;
 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.
+const pluralize_1 = __importDefault(require("pluralize"));
+// Pluralization must be idempotent because module names may come from the
+// interactive prompt (singular) or a documented/scripted command (often
+// plural). Keep this wrapper exported for callers that only need inflection.
 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";
+    return pluralize_1.default.plural(word);
 }
 function toPascalCase(value) {
     return value
@@ -98,7 +97,7 @@ function assertNotGoKeyword(ident, role) {
 // 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);
+    const pkg = toPackageName(pluralize_1.default.singular(toKebabCase(rawName)));
     if (!pkg)
         return `invalid module name: "${rawName}" (must contain letters/numbers)`;
     if (/^[0-9]/.test(pkg)) {
@@ -134,15 +133,79 @@ function resolveModuleNaming(rawName) {
     const check = validateModuleName(rawName);
     if (check !== true)
         throw new Error(check);
+    const singular = pluralize_1.default.singular(toKebabCase(rawName));
+    const pkg = toPackageName(singular);
+    const plural = pluralize_1.default.plural(singular);
+    return {
+        name: singular,
+        pkg,
+        pascalName: toPascalCase(singular),
+        plural,
+        tableName: toDbName(plural),
+        errorPrefix: toDbName(singular).toUpperCase(),
+    };
+}
+function legacyPluralize(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 resolveLegacyModuleNaming(rawName) {
     const pkg = toPackageName(rawName);
+    const plural = legacyPluralize(pkg);
     return {
         name: pkg,
         pkg,
         pascalName: toPascalCase(pkg),
-        plural: pluralize(pkg),
+        plural,
+        tableName: toDbName(plural),
         errorPrefix: pkg.toUpperCase(),
     };
 }
+// Projects generated before canonical inflection used the raw input as the Go
+// package name. Prefer the canonical package when present, but keep locating
+// legacy plural packages so upgrade does not make method/remove commands lose
+// sight of existing code. Two matches are unsafe: silently choosing one can
+// patch or delete the wrong module.
+function resolveExistingModuleNaming(rawName, existingPackages) {
+    const requestedLegacy = resolveLegacyModuleNaming(rawName);
+    const existing = new Set(existingPackages);
+    let canonical;
+    try {
+        canonical = resolveModuleNaming(rawName);
+    }
+    catch (error) {
+        if (existing.has(requestedLegacy.pkg))
+            return requestedLegacy;
+        throw error;
+    }
+    const aliases = existingPackages.filter((pkg) => {
+        if (pkg === canonical.pkg)
+            return false;
+        try {
+            return resolveModuleNaming(pkg).pkg === canonical.pkg;
+        }
+        catch {
+            return false;
+        }
+    });
+    const matches = [
+        ...(existing.has(canonical.pkg) ? [canonical.pkg] : []),
+        ...aliases,
+    ];
+    if (matches.length > 1) {
+        throw new Error(`ambiguous module "${rawName}": ${matches.map((pkg) => `internal/app/${pkg}`).join(" and ")} exist`);
+    }
+    if (matches[0] === canonical.pkg)
+        return canonical;
+    if (matches[0])
+        return resolveLegacyModuleNaming(matches[0]);
+    return canonical;
+}
 function resolveMethodNaming(rawName) {
     const cleaned = rawName.trim();
     const pascalName = toPascalCase(cleaned);

package/dist/utils/openapi-patcher.js

@@ -44,7 +44,25 @@ function patchOpenapiIndex(openapiPath, naming, apiPrefix) {
 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]));
+    const withoutKnownEntries = (0, marker_patch_1.removeLines)(content, [...paths, ...schemas]);
+    // `generate method` can add any number of module-specific path documents.
+    // Remove every two-line path/$ref block owned by this module, otherwise the
+    // index keeps dangling references after the docs folder is deleted.
+    const lines = withoutKnownEntries.split("\n");
+    const moduleRefPrefix = `./${naming.plural}/`;
+    const kept = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const current = lines[i];
+        const next = lines[i + 1];
+        const isPathKey = /^\s*\/[^:]+:\s*$/.test(current);
+        const refMatch = next?.match(/^\s*\$ref:\s*['"]([^'"]+)['"]\s*$/);
+        if (isPathKey && refMatch?.[1].startsWith(moduleRefPrefix)) {
+            i += 1;
+            continue;
+        }
+        kept.push(current);
+    }
+    fs_extra_1.default.writeFileSync(openapiPath, kept.join("\n"));
 }
 // patchOpenapiIndexRaw wires hand-written path docs into the index — used by
 // `add auth`/`add rbac`, whose endpoints aren't a single CRUD resource so