@nakedev/go-scaffold 0.1.4 → 0.3.0

package/dist/utils/gomod-patcher.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.patchGoModRequires = patchGoModRequires;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+// Every `add` command pulls in third-party packages, and none of them used to
+// touch go.mod — the imports just appeared and `go mod tidy` was left to
+// resolve them. Tidy picks the latest release of anything it doesn't already
+// have a version for, so two people running `add auth` a month apart got
+// different builds from the same CLI, and nothing recorded which versions the
+// scaffold was actually written and tested against.
+//
+// Pinning here fixes that: tidy honours a version that's already in go.mod
+// rather than reaching for latest. It's a floor, not a ceiling — if another
+// feature needs something newer, tidy still resolves upward, which is why
+// golang.org/x/crypto can be pinned by `add auth` and later raised by
+// `add observability`.
+//
+// Users still need to run `go mod tidy` (every command says so): these lines
+// have no go.sum entries, and only tidy can add those.
+function patchGoModRequires(goModPath, requires) {
+    if (!fs_extra_1.default.existsSync(goModPath))
+        return;
+    let content = fs_extra_1.default.readFileSync(goModPath, "utf8");
+    // already-present modules are left at whatever version they're on: a
+    // re-run, or a version the user deliberately bumped, is not ours to reset
+    const missing = requires.filter((line) => !hasModule(content, modulePathOf(line)));
+    if (missing.length === 0)
+        return;
+    const block = content.match(/^require \(\n(?:.*\n)*?\)$/m);
+    if (!block) {
+        // no grouped require block (hand-edited, or single-line `require x y`
+        // form) — append one rather than trying to rewrite what's there
+        content = content.replace(/\n?$/, "\n") + `\nrequire (\n${missing.map((l) => `\t${l}`).join("\n")}\n)\n`;
+        fs_extra_1.default.writeFileSync(goModPath, content);
+        return;
+    }
+    const updated = block[0].replace(/\n\)$/, `\n${missing.map((l) => `\t${l}`).join("\n")}\n)`);
+    // function replacer: a version string can't contain $ today, but this is the
+    // same trap ensureImport documents and costs nothing to avoid
+    fs_extra_1.default.writeFileSync(goModPath, content.replace(block[0], () => updated));
+}
+function modulePathOf(requireLine) {
+    return requireLine.trim().split(/\s+/)[0];
+}
+// Word-boundary match on the module path, so `go.opentelemetry.io/otel`
+// doesn't count as already-present when only `go.opentelemetry.io/otel/sdk`
+// is there.
+function hasModule(goMod, modulePath) {
+    return goMod.split("\n").some((line) => modulePathOf(line) === modulePath);
+}

package/dist/utils/main-patcher.js

@@ -3,11 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertMainGoPatchable = assertMainGoPatchable;
 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 SCHEMA_MARKER = "// go-scaffold:schemas";
 const MODEL_MARKER = "// go-scaffold:models";
 const ROUTE_MARKER = "// go-scaffold:routes";
 // no leading tab: insertBeforeMarker re-indents, and removeLines matches by
@@ -15,9 +17,19 @@ const ROUTE_MARKER = "// go-scaffold:routes";
 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.
+//
+// The service gets its own named variable rather than being constructed
+// inline inside NewHandler(...). docs/architect/patterns.md tells you to wire
+// one domain's service into another's constructor when it needs behaviour
+// from it, which means editing this block by hand — and an inline expression
+// has nowhere to hold the result. With a named variable the edit is "add an
+// argument to the end of line one", and unpatchMainGo can still find the line
+// afterwards because it matches on the `<pkg>Svc :=` prefix, not the whole
+// text.
 function mainGoLines(patch) {
     const modelAlias = `${patch.pkg}model`; // every domain's model subpackage is named "model"
-    const handlerArgs = [`${patch.pkg}.NewService(${patch.pkg}.NewRepository(db))`];
+    const svcVar = `${patch.pkg}Svc`;
+    const handlerArgs = [svcVar];
     if (patch.auth)
         handlerArgs.push("cfg.JWTSecret");
     if (patch.permission)
@@ -25,7 +37,20 @@ function mainGoLines(patch) {
     return {
         importLine: `"${patch.goModule}/internal/app/${patch.modulePath}"`,
         modelImportLine: `${modelAlias} "${patch.goModule}/internal/app/${patch.modulePath}/model"`,
+        // AutoMigrate (dev) creates tables but not the schema they live in — see
+        // the comment on go-scaffold:schemas in main.go.hbs. One Exec per schema,
+        // guarded by its own sentinel so two modules sharing a schema name only
+        // ever produce one line (not expected today, but cheap to keep safe).
+        schemaLines: [
+            `if err := db.Exec("CREATE SCHEMA IF NOT EXISTS ${patch.schemaName}").Error; err != nil {`,
+            `\treturn fmt.Errorf("create schema ${patch.schemaName}: %w", err)`,
+            `}`,
+        ].join("\n"),
+        schemaSentinel: `CREATE SCHEMA IF NOT EXISTS ${patch.schemaName}`,
         migrateLine: `&${modelAlias}.${patch.pascalName}{},`,
+        serviceLine: `${svcVar} := ${patch.pkg}.NewService(${patch.pkg}.NewRepository(db))`,
+        // matches the service line however the user has since extended it
+        servicePrefix: `${svcVar} :=`,
         // `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.
@@ -34,20 +59,43 @@ function mainGoLines(patch) {
         routeLine: `${patch.pkg}.NewHandler(${handlerArgs.join(", ")}).Register(api)`,
     };
 }
-// patchMainGo wires a newly generated module into cmd/api/main.go: its
+// assertMainGoPatchable is the pre-flight for it: every marker patchMainGo
+// needs, checked before the caller writes anything. Without it a missing
+// marker surfaced only once the module files and its migration were already
+// on disk, and the retry then hit "internal/app/<pkg> already exists" — a
+// dead end that pointed nowhere useful.
+function assertMainGoPatchable(mainGoPath) {
+    if (!fs_extra_1.default.existsSync(mainGoPath)) {
+        throw new Error(`${mainGoPath} not found — this doesn't look like a go-scaffold project`);
+    }
+    const content = fs_extra_1.default.readFileSync(mainGoPath, "utf8");
+    const missing = [IMPORT_MARKER, SCHEMA_MARKER, MODEL_MARKER, ROUTE_MARKER].filter((m) => !(0, marker_patch_1.hasMarker)(content, m));
+    if (missing.length) {
+        throw new Error(`cmd/api/wiring.go is missing the marker comment${missing.length > 1 ? "s" : ""} this command patches at:\n` +
+            missing.map((m) => `  ${m}`).join("\n") +
+            `\n\nEither the file was hand-edited, or it was scaffolded by an older go-scaffold that\n` +
+            `didn't emit ${missing.length > 1 ? "them" : "it"} yet. Add the marker${missing.length > 1 ? "s" : ""} back where the generated code should go, or\n` +
+            `wire this module into main.go by hand.`);
+    }
+}
+// patchMainGo wires a newly generated module into cmd/api/wiring.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);
+    const { importLine, modelImportLine, schemaLines, schemaSentinel, migrateLine, serviceLine, servicePrefix, 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, SCHEMA_MARKER, schemaLines, schemaSentinel);
     content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, MODEL_MARKER, migrateLine, migrateLine);
+    // sentinel is the prefix, not the whole line: a re-run must not add a
+    // second service line just because the first one gained a dependency.
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, ROUTE_MARKER, serviceLine, servicePrefix);
     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);
@@ -57,8 +105,14 @@ function patchMainGo(mainGoPath, patch) {
 // 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);
+    const { importLine, modelImportLine, schemaLines, migrateLine, servicePrefix, routeLine } = mainGoLines(patch);
     content = (0, marker_patch_1.removeLines)(content, [importLine, modelImportLine, migrateLine, routeLine]);
+    // by prefix: the service line may have grown arguments since it was written
+    content = (0, marker_patch_1.removeLinesByPrefix)(content, [servicePrefix]);
+    // by contiguous block, not removeLines: every module's schema block is
+    // identical except the schema name, so a line-by-line removal would also
+    // strip another module's matching lines.
+    content = (0, marker_patch_1.removeBlock)(content, schemaLines);
     if (!content.includes(".Register(api)") && !content.includes(UNUSED_API_LINE)) {
         content = (0, marker_patch_1.insertBeforeMarker)(content, ROUTE_MARKER, UNUSED_API_LINE);
     }

package/dist/utils/marker-patch.js

@@ -10,6 +10,8 @@ exports.hasMarker = hasMarker;
 exports.ensureImport = ensureImport;
 exports.insertBeforeMarkerOnce = insertBeforeMarkerOnce;
 exports.removeLines = removeLines;
+exports.removeBlock = removeBlock;
+exports.removeLinesByPrefix = removeLinesByPrefix;
 exports.insertBeforeMarker = insertBeforeMarker;
 function hasMarker(content, marker) {
     return content.split("\n").some((l) => l.trim() === marker);
@@ -24,7 +26,12 @@ function ensureImport(content, importPath) {
     const importLine = `"${importPath}"`;
     if (content.includes(importLine))
         return content;
-    return content.replace(/import \(\n/, `import (\n\t${importLine}\n`);
+    // A function replacer, not a string one: String.replace treats "$$", "$&",
+    // digit-groups etc. in a *string* replacement as special patterns even when
+    // the search argument is a plain string, not a regex — collapsing any "$$"
+    // that happens to appear in importLine. A function's return value is spliced
+    // in literally, so this holds regardless of what importPath contains.
+    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
@@ -38,7 +45,7 @@ function insertBeforeMarkerOnce(content, marker, block, sentinel) {
     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
+// given lines — the inverse of insertBeforeMarker for `undo 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) {
@@ -48,6 +55,116 @@ function removeLines(content, trimmedLines) {
         .filter((l) => !drop.has(l.trim()))
         .join("\n");
 }
+// removeBlock removes a multi-line block inserted by insertBeforeMarker,
+// matched as one contiguous run (each line compared trimmed) rather than
+// line-by-line like removeLines. Needed when a block's individual lines
+// aren't unique on their own — two modules' schema-creation blocks in
+// main.go are identical except for the schema name itself, and removeLines
+// would delete the shared lines from both when asked to remove just one.
+function removeBlock(content, block) {
+    const blockLines = block.split("\n").map((l) => l.trim());
+    const lines = content.split("\n");
+    const out = [];
+    for (let i = 0; i < lines.length;) {
+        const matches = blockLines.every((bl, j) => lines[i + j]?.trim() === bl);
+        if (matches) {
+            i += blockLines.length;
+        }
+        else {
+            out.push(lines[i]);
+            i += 1;
+        }
+    }
+    return out.join("\n");
+}
+// removeLinesByPrefix is removeLines for a line the user is expected to edit
+// after it was generated — a service constructor that has since gained a
+// dependency, say. Matching the whole line would miss it and leave the
+// project un-compilable after `undo module`; matching a distinctive prefix
+// (`orderSvc :=`) still finds it. Only use it where the prefix is unique.
+//
+// A match consumes lines until its brackets balance, not just the first one:
+// docs/architect/patterns.md tells you to expand that single wiring line into
+// a multi-line adapter literal, and dropping only line one leaves an orphaned
+// func body behind — a main.go that no longer parses, reported by the Go
+// compiler long after `undo module` has printed success.
+function removeLinesByPrefix(content, prefixes) {
+    const lines = content.split("\n");
+    const out = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        if (!prefixes.some((p) => lines[i].trim().startsWith(p))) {
+            out.push(lines[i]);
+            continue;
+        }
+        const start = i;
+        let depth = 0;
+        let overran = false;
+        do {
+            // A marker comment is a structural anchor — no wiring statement can
+            // contain one. Reaching it with brackets still open means the count is
+            // wrong (a malformed line above), and carrying on would swallow the
+            // marker plus every module wired after it. Stop at the boundary.
+            if (i > start && lines[i].trim().startsWith("// go-scaffold:")) {
+                overran = true;
+                break;
+            }
+            depth += bracketDelta(lines[i]);
+            i += 1;
+        } while (depth > 0 && i < lines.length);
+        // Either we hit a marker or ran out of file with brackets still open.
+        // Consuming anyway deletes everything in between — in main.go that's the
+        // other modules' wiring and the closing brace, from a command whose whole
+        // job is to touch one module. Refuse: undo un-wires before it deletes
+        // anything, so throwing here costs the user nothing.
+        if (overran || depth > 0) {
+            throw new Error(`the statement starting at line ${start + 1} never closes its brackets:\n` +
+                `  ${lines[start].trim()}\n\n` +
+                `Refusing to guess where it ends — removing through to where the count finally balances\n` +
+                `would take the lines in between with it. Fix the brackets, or remove it by hand.`);
+        }
+        i -= 1; // the for's own increment steps past the last consumed line
+    }
+    return out.join("\n");
+}
+// bracketDelta counts on code only. Brackets inside a string literal or a
+// trailing comment are text, not structure — `order.WithPrefix("(")` on the
+// wiring line would otherwise leave the count permanently open.
+//
+// ponytail: a raw string that spans lines is still counted wrong, since this
+// works a line at a time. Nothing generated produces one; reach for go/ast if
+// that ever changes.
+function bracketDelta(line) {
+    let delta = 0;
+    for (const ch of stripLiteralsAndComments(line)) {
+        if (ch === "(" || ch === "{" || ch === "[")
+            delta += 1;
+        else if (ch === ")" || ch === "}" || ch === "]")
+            delta -= 1;
+    }
+    return delta;
+}
+function stripLiteralsAndComments(line) {
+    let out = "";
+    for (let i = 0; i < line.length; i += 1) {
+        const ch = line[i];
+        if (ch === "/" && line[i + 1] === "/")
+            break; // rest of the line is a comment
+        if (ch !== '"' && ch !== "'" && ch !== "`") {
+            out += ch;
+            continue;
+        }
+        // skip to the closing quote; \" doesn't close an interpreted string, but
+        // a backslash is literal inside a raw one
+        const quote = ch;
+        i += 1;
+        while (i < line.length && line[i] !== quote) {
+            if (quote !== "`" && line[i] === "\\")
+                i += 1;
+            i += 1;
+        }
+    }
+    return out;
+}
 function insertBeforeMarker(content, marker, block) {
     const lines = content.split("\n");
     const markerLine = lines.find((l) => l.trim() === marker);
@@ -59,5 +176,10 @@ function insertBeforeMarker(content, marker, block) {
         .split("\n")
         .map((line) => (line ? `${indent}${line}` : line))
         .join("\n");
-    return content.replace(markerLine, `${indentedBlock}\n${markerLine}`);
+    // Function replacer, not a string one — see the comment on ensureImport.
+    // Every caller of this — main.go/patterns.md route and import wiring,
+    // depguard rules, rbac's main.go patches — funnels through here, so fixing
+    // it here is what actually closes the bug off, rather than auditing every
+    // block a caller happens to pass in today.
+    return content.replace(markerLine, () => `${indentedBlock}\n${markerLine}`);
 }

package/dist/utils/method-patcher.js

@@ -151,8 +151,13 @@ function patchGetOne(paths, naming, method, rawField, goModule) {
     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// TODO: add the "${fieldColumn}" column and an index on it — this query`,
+        `\t// compiles against any table and only fails when it runs.`,
+        `\t//`,
+        `\t// tx.From, like every other method here: a lookup that reached for r.db`,
+        `\t// directly would read outside a transaction its caller had opened, and`,
+        `\t// so miss that transaction's own uncommitted writes.`,
+        `\tif err := tx.From(ctx, r.db).WithContext(ctx).First(&m, "${fieldColumn} = ?", ${fieldParam}).Error; err != nil {`,
         `\t\treturn nil, err`,
         `\t}`,
         `\treturn &m, nil`,
@@ -287,7 +292,17 @@ function patchResourceAction(paths, naming, method, type, goModule) {
         `\t\treturn nil, wrapFindErr(err)`,
         `\t}`,
         `\t// TODO: implement "${method.name}" — currently a no-op save`,
+        `\t// The version compared here is the one just read, so this only`,
+        `\t// catches a writer that lands between the read above and this write.`,
+        `\t// It is NOT the check Update does: that one compares against the version`,
+        `\t// the *client* last saw, which is what catches someone submitting a`,
+        `\t// form built from a copy that has since gone stale. If this endpoint`,
+        `\t// needs that, give it an input struct carrying Version and assign it`,
+        `\t// to m.Version here, the way service.go's Update does.`,
         `\tif err := s.repo.Update(ctx, m); err != nil {`,
+        `\t\tif errors.Is(err, ErrStaleVersion) {`,
+        `\t\t\treturn nil, errStale()`,
+        `\t\t}`,
         `\t\treturn nil, apperror.NewInternal()`,
         `\t}`,
         `\treturn m, nil`,

package/dist/utils/module-location.js

@@ -17,6 +17,42 @@ function existingModulePackages(projectDir) {
         .filter((entry) => entry.isDirectory())
         .map((entry) => entry.name);
 }
+// A Go package name has no word boundaries: "orderitem" cannot tell you it
+// came from "order-items". Everything else a command derives — the model type
+// (OrderItem), the route (/order-items), the table (order_items), the
+// migration filename — does depend on those boundaries, so re-deriving them
+// from the package name yields Orderitem/orderitems and code that doesn't
+// compile.
+//
+// That mattered because the package name is the one form of the name the user
+// actually sees: it's the folder on disk, and it's what `generate module`
+// prints as the next command to run. Following that instruction produced
+// `undefined: model.Orderitem (but have OrderItem)`.
+//
+// model/model.go is where the boundaries survive — the struct name is
+// PascalCase, so kebab-casing it recovers the exact string `generate module`
+// was originally given.
+function pascalNameOnDisk(projectDir, pkg) {
+    const modelPath = path_1.default.join(projectDir, "internal", "app", pkg, "model", "model.go");
+    if (!fs_extra_1.default.existsSync(modelPath))
+        return null;
+    const match = fs_extra_1.default.readFileSync(modelPath, "utf8").match(/^type\s+([A-Z]\w*)\s+struct\b/m);
+    return match ? match[1] : null;
+}
 function resolveProjectModuleNaming(projectDir, rawName) {
-    return (0, naming_1.resolveExistingModuleNaming)(rawName, existingModulePackages(projectDir));
+    const located = (0, naming_1.resolveExistingModuleNaming)(rawName, existingModulePackages(projectDir));
+    const pascal = pascalNameOnDisk(projectDir, located.pkg);
+    if (!pascal || pascal === located.pascalName)
+        return located;
+    let fromDisk;
+    try {
+        fromDisk = (0, naming_1.resolveModuleNaming)((0, naming_1.toKebabCase)(pascal));
+    }
+    catch {
+        return located; // model.go holds something we can't derive a module name from
+    }
+    // Only trust the correction when it still points at the same package.
+    // A hand-renamed struct, or a legacy module whose type never matched its
+    // folder, would otherwise silently retarget the command at another module.
+    return fromDisk.pkg === located.pkg ? fromDisk : located;
 }

package/dist/utils/naming.js

@@ -12,11 +12,14 @@ exports.toDbName = toDbName;
 exports.validateGoModulePath = validateGoModulePath;
 exports.assertValidGoModulePath = assertValidGoModulePath;
 exports.assertNotGoKeyword = assertNotGoKeyword;
+exports.assertGoIdentifier = assertGoIdentifier;
 exports.validateModuleName = validateModuleName;
 exports.normalizeApiPrefix = normalizeApiPrefix;
 exports.validateApiPrefix = validateApiPrefix;
 exports.resolveModuleNaming = resolveModuleNaming;
 exports.resolveExistingModuleNaming = resolveExistingModuleNaming;
+exports.migrationSlug = migrationSlug;
+exports.migrationSlugAliases = migrationSlugAliases;
 exports.resolveMethodNaming = resolveMethodNaming;
 const pluralize_1 = __importDefault(require("pluralize"));
 // Pluralization must be idempotent because module names may come from the
@@ -85,6 +88,13 @@ const GO_PREDECLARED_TYPES = new Set([
     "float32", "float64", "int", "int8", "int16", "int32", "int64", "rune",
     "string", "uint", "uint8", "uint16", "uint32", "uint64", "uintptr",
 ]);
+// Directory names the go tool reserves. A module named "vendors" singularises
+// to "vendor", and internal/app/vendor is then treated as a vendor directory:
+// the build fails with "use of vendored package not allowed" and "must be
+// imported as model", for a project that was generated, not hand-written.
+// Not caught by the drift check either — that compares before and after, and
+// this breaks the whole module at once.
+const GO_RESERVED_DIRS = new Set(["vendor", "testdata"]);
 // 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) {
@@ -92,6 +102,19 @@ function assertNotGoKeyword(ident, role) {
         throw new Error(`"${ident}" is a Go keyword — can't use it as a ${role} name; pick another`);
     }
 }
+// Anything that ends up spliced into a Go declaration has to be a legal
+// identifier first. Without this, `generate method thing 2fa` exits 0 over a
+// `func (s *Service) 2fa(...)` spread across four files, and a --field like
+// `x string) error { panic(0) } // ` is injected straight into the generated
+// signatures. Neither is caught later: gofmt's failure is only advisory and
+// go vet needs a project that compiled a moment ago.
+function assertGoIdentifier(ident, role) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(ident)) {
+        throw new Error(`"${ident}" is not a valid Go identifier — can't use it as a ${role} name.\n` +
+            `Letters, digits and underscores only, and it can't start with a digit.`);
+    }
+    assertNotGoKeyword(ident, role);
+}
 // 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
@@ -106,6 +129,9 @@ function validateModuleName(rawName) {
     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`;
     }
+    if (GO_RESERVED_DIRS.has(pkg)) {
+        return `"${pkg}" is a directory name the go tool reserves — internal/app/${pkg} would be treated as a ${pkg} directory and the project wouldn't build; pick another module name`;
+    }
     return true;
 }
 // strips whitespace and leading/trailing slashes so "/api/v1/" and "api/v1"
@@ -142,6 +168,7 @@ function resolveModuleNaming(rawName) {
         pascalName: toPascalCase(singular),
         plural,
         tableName: toDbName(plural),
+        schemaName: `${pkg}_svc`,
         errorPrefix: toDbName(singular).toUpperCase(),
     };
 }
@@ -163,6 +190,12 @@ function resolveLegacyModuleNaming(rawName) {
         pascalName: toPascalCase(pkg),
         plural,
         tableName: toDbName(plural),
+        // Not meaningful for a legacy match: its table already exists in
+        // whatever schema the project's own migrations put it in (usually
+        // "public", from before this field existed), and nothing re-renders its
+        // model/migration templates to move it. Every consumer of this result is
+        // generate method/undo module, neither of which reads schemaName.
+        schemaName: `${pkg}_svc`,
         errorPrefix: pkg.toUpperCase(),
     };
 }
@@ -206,14 +239,29 @@ function resolveExistingModuleNaming(rawName, existingPackages) {
         return resolveLegacyModuleNaming(matches[0]);
     return canonical;
 }
+// Migration filenames read like the thing they create, so they use the
+// snake_case table name: create_order_items.up.sql for order_svc.order_items.
+// Older projects were written with the kebab-case route slug instead
+// (create_order-items.up.sql), so anything that *looks up* an existing pair
+// has to accept both — upgrading the CLI must not strand a module's
+// migrations where `undo` can no longer see them. Identical for the
+// single-word names that are the common case.
+function migrationSlug(naming) {
+    return naming.tableName;
+}
+function migrationSlugAliases(naming) {
+    return naming.tableName === naming.plural ? [naming.tableName] : [naming.tableName, naming.plural];
+}
 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");
+    // both become Go identifiers: handlerName as a method name
+    // (`func (h *Handler) <name>`), pascalName as a DTO type (`<Name>Input`)
+    assertGoIdentifier(toCamelCase(cleaned), "method");
+    assertGoIdentifier(pascalName, "method");
     return {
         name: cleaned,
         pascalName,

package/dist/utils/observability-patcher.js

@@ -0,0 +1,107 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.patchMainGoForObservability = patchMainGoForObservability;
+exports.patchDatabaseGoForObservability = patchDatabaseGoForObservability;
+exports.patchConfigForObservability = patchConfigForObservability;
+exports.patchEnvExampleForObservability = patchEnvExampleForObservability;
+exports.patchOpenapiIndexForObservability = patchOpenapiIndexForObservability;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const marker_patch_1 = require("./marker-patch");
+const IMPORT_MARKER = "// go-scaffold:imports";
+const PLATFORM_INIT_MARKER = "// go-scaffold:platform-init";
+const EXTRA_ROUTES_MARKER = "// go-scaffold:extra-routes";
+const CONFIG_FIELDS_MARKER = "// go-scaffold:config-fields";
+const CONFIG_LOAD_MARKER = "// go-scaffold:config-load";
+const OPENAPI_PATHS_MARKER = "# go-scaffold:paths";
+// The exact line `create` renders — matched literally rather than through a
+// marker because it's a single call in the middle of other middleware, not a
+// standalone line a marker comment can sit next to.
+const USE_LINE = "r.Use(gin.Recovery(), middleware.CORS(cfg.CORSAllowedOrigins), middleware.RequestID(), middleware.Logger(logger), middleware.Error(!cfg.IsProd()))";
+// patchMainGoForObservability wires telemetry init, the tracing/metrics
+// middleware, and the /metrics route into cmd/api/wiring.go — the same
+// text-marker approach every other `add` command uses, since main.go is a
+// real file a human may have already edited by the time this runs, not a
+// template rendered fresh.
+function patchMainGoForObservability(mainGoPath, goModule, projectName) {
+    let content = fs_extra_1.default.readFileSync(mainGoPath, "utf8");
+    const telemetryImport = `"${goModule}/internal/platform/telemetry"`;
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, telemetryImport, telemetryImport);
+    const promhttpImport = `"github.com/prometheus/client_golang/prometheus/promhttp"`;
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, promhttpImport, promhttpImport);
+    // telemetry.go's GORM plugin looks up otel.Tracer() fresh on every query
+    // rather than once at registration, so it doesn't matter that this runs
+    // after database.Open has already called db.Use(NewGormPlugin()) — no
+    // query happens between here and the server actually accepting traffic.
+    const initBlock = [
+        `shutdownTelemetry, err := telemetry.Init(context.Background(), "${projectName}", cfg.OTELExporterEndpoint)`,
+        "if err != nil {",
+        '\treturn fmt.Errorf("init telemetry: %w", err)',
+        "}",
+        "defer func() { _ = shutdownTelemetry(context.Background()) }()",
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, PLATFORM_INIT_MARKER, initBlock, "shutdownTelemetry, err := telemetry.Init(");
+    if (!content.includes(USE_LINE)) {
+        throw new Error("cmd/api/wiring.go's r.Use(...) call doesn't match the text this command expects — " +
+            "it looks like it's been hand-edited. Add middleware.Metrics() and middleware.Tracing(\"<project>\") to it yourself.");
+    }
+    const newUseLine = `${USE_LINE.slice(0, -1)}, middleware.Metrics(), middleware.Tracing("${projectName}"))`;
+    content = content.replace(USE_LINE, () => newUseLine);
+    // Not gated on APP_ENV the way /docs is: production is exactly where you
+    // want a scrape target, and Prometheus reaches it in-cluster. It is still
+    // unauthenticated and does disclose your route list and traffic shape, so
+    // block /metrics at the ingress rather than publishing it to the internet.
+    const metricsRoute = 'r.GET("/metrics", gin.WrapH(promhttp.Handler()))';
+    const metricsBlock = [
+        "// Unauthenticated on purpose (Prometheus scrapes it in-cluster) — block",
+        "// /metrics at your ingress so it isn't reachable from the internet.",
+        metricsRoute,
+    ].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, EXTRA_ROUTES_MARKER, metricsBlock, metricsRoute);
+    fs_extra_1.default.writeFileSync(mainGoPath, content);
+}
+// patchDatabaseGoForObservability wires the GORM OpenTelemetry plugin into
+// database.Open, so every query gets a span alongside the HTTP request it
+// came from.
+function patchDatabaseGoForObservability(databaseGoPath, goModule) {
+    let content = fs_extra_1.default.readFileSync(databaseGoPath, "utf8");
+    const telemetryImport = `"${goModule}/internal/platform/telemetry"`;
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, IMPORT_MARKER, telemetryImport, telemetryImport);
+    const pluginBlock = ["if err := db.Use(telemetry.NewGormPlugin()); err != nil {", "\treturn nil, err", "}"].join("\n");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, PLATFORM_INIT_MARKER, pluginBlock, "if err := db.Use(telemetry.NewGormPlugin())");
+    fs_extra_1.default.writeFileSync(databaseGoPath, content);
+}
+// patchConfigForObservability adds OTELExporterEndpoint to Config and its
+// env() load — the same marker-based approach patchConfigForWorker uses.
+function patchConfigForObservability(configGoPath) {
+    let content = fs_extra_1.default.readFileSync(configGoPath, "utf8");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_FIELDS_MARKER, "OTELExporterEndpoint string", "OTELExporterEndpoint");
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, CONFIG_LOAD_MARKER, 'OTELExporterEndpoint: env("OTEL_EXPORTER_OTLP_ENDPOINT", ""),', 'env("OTEL_EXPORTER_OTLP_ENDPOINT"');
+    fs_extra_1.default.writeFileSync(configGoPath, content);
+}
+// patchEnvExampleForObservability appends OTEL_EXPORTER_OTLP_ENDPOINT —
+// .env.example has no marker infrastructure of its own, so this follows the
+// same append-once pattern as add worker/add auth's env patchers.
+function patchEnvExampleForObservability(envExamplePath) {
+    if (!fs_extra_1.default.existsSync(envExamplePath))
+        return;
+    const content = fs_extra_1.default.readFileSync(envExamplePath, "utf8");
+    if (content.includes("OTEL_EXPORTER_OTLP_ENDPOINT"))
+        return;
+    fs_extra_1.default.writeFileSync(envExamplePath, content.replace(/\n?$/, "\n") +
+        "\n# OTLP/HTTP endpoint for trace export (e.g. localhost:4318) — empty disables\n" +
+        "# tracing entirely: no exporter is created, no network calls are made\n" +
+        "OTEL_EXPORTER_OTLP_ENDPOINT=\n");
+}
+// patchOpenapiIndexForObservability wires /metrics into docs/openapi.yaml.
+// Not routed through patchOpenapiIndexRaw (used for auth/rbac's paths):
+// /metrics is registered directly on the router like /livez and /readyz, not
+// under the api prefix group, so it must never be prefixed.
+function patchOpenapiIndexForObservability(openapiPath) {
+    let content = fs_extra_1.default.readFileSync(openapiPath, "utf8");
+    const block = "/metrics:\n  $ref: './observability/metrics.yaml'";
+    content = (0, marker_patch_1.insertBeforeMarkerOnce)(content, OPENAPI_PATHS_MARKER, block, "/metrics:");
+    fs_extra_1.default.writeFileSync(openapiPath, content);
+}