@lpdjs/firestore-repo-service 2.6.11 → 2.6.13

package/dist/servers/hono/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
-import {existsSync,mkdirSync,writeFileSync,readFileSync,readdirSync,statSync}from'fs';import {resolve,dirname,relative,join,sep}from'path';import {stdin,stdout}from'process';import {createInterface}from'readline/promises';var O={skipSegments:["useCases","useCase","use-cases","use-case"],casing:"preserve"};function M(e,t=O){let s=new Set(t.skipSegments.map(o=>o.toLowerCase()));return "/"+e.split("/").filter(Boolean).filter(o=>!s.has(o.toLowerCase())).map(o=>t.casing==="kebab"?oe(o):o).join("/")}function oe(e){return e.replace(/([a-z0-9])([A-Z])/g,"$1-$2").replace(/[\s_]+/g,"-").toLowerCase()}function W(e,t,s){let r=H(e),o=H(t),i=0;for(;i<r.length&&i<o.length&&r[i]===o[i];)i++;let c=r.length-i,n=o.slice(i),d=(n[n.length-1]??"").replace(/\.[mc]?[tj]sx?$/i,""),f=s===""?d:`${d}${s}`;return n[n.length-1]=f,(c===0?"./":"../".repeat(c))+n.join("/")}function H(e){return e.replace(/\\/g,"/").replace(/\/+$/,"").split("/").filter((s,r)=>!(r===0&&s===""))}var ae="/**\n * AUTO-GENERATED by `@lpdjs/firestore-repo-service` Hono codegen.\n * Do not edit by hand \u2014 re-run `hono:gen` after adding / removing route files.\n */\n";function J(e,t){let s=dirname(t.outFile);mkdirSync(s,{recursive:true});let r=t.banner??ae,o=(t.now??new Date).toISOString(),i=t.importExtension,c=[],n=[],a=[];e.forEach((f,p)=>{let P=W(s,f.absPath,i),y=M(f.relDir,t.derive);c.push(`import mod${p} from ${JSON.stringify(P)};`),n.push(`  { __derivedPath: ${JSON.stringify(y)}, mod: mod${p} },`),a.push({source:f.relPath,url:y});});let d=`${r}// Generated at ${o} \u2014 ${e.length} route file${e.length===1?"":"s"}.
+import {existsSync,mkdirSync,writeFileSync,readFileSync,readdirSync,statSync}from'fs';import {resolve,dirname,relative,join,sep}from'path';import {stdin,stdout}from'process';import {createInterface}from'readline/promises';var _={skipSegments:["useCases","useCase","use-cases","use-case"],casing:"preserve"};function J(e,r=_){let s=new Set(r.skipSegments.map(o=>o.toLowerCase()));return "/"+e.split("/").filter(Boolean).filter(o=>!s.has(o.toLowerCase())).map(o=>r.casing==="kebab"?ne(o):o).join("/")}function ne(e){return e.replace(/([a-z0-9])([A-Z])/g,"$1-$2").replace(/[\s_]+/g,"-").toLowerCase()}function Z(e,r,s){let t=W(e),o=W(r),i=0;for(;i<t.length&&i<o.length&&t[i]===o[i];)i++;let a=t.length-i,n=o.slice(i),f=(n[n.length-1]??"").replace(/\.[mc]?[tj]sx?$/i,""),g=s===""?f:`${f}${s}`;return n[n.length-1]=g,(a===0?"./":"../".repeat(a))+n.join("/")}function W(e){return e.replace(/\\/g,"/").replace(/\/+$/,"").split("/").filter((s,t)=>!(t===0&&s===""))}var pe="/**\n * AUTO-GENERATED by `@lpdjs/firestore-repo-service` Hono codegen.\n * Do not edit by hand \u2014 re-run `hono:gen` after adding / removing route files.\n */\n";function K(e,r){let s=dirname(r.outFile);mkdirSync(s,{recursive:true});let t=r.banner??pe,o=(r.now??new Date).toISOString(),i=r.importExtension,a=[],n=[],c=[];e.forEach((g,p)=>{let b=Z(s,g.absPath,i),h=J(g.relDir,r.derive);a.push(`import mod${p} from ${JSON.stringify(b)};`),n.push(`  { __derivedPath: ${JSON.stringify(h)}, mod: mod${p} },`),c.push({source:g.relPath,url:h});});let f=`${t}// Generated at ${o} \u2014 ${e.length} route file${e.length===1?"":"s"}.
 
 import type { AnyRouteDef, RouteModuleDefault } from "@lpdjs/firestore-repo-service/servers/hono";
 
-`+c.join(`
-`)+(c.length?`
+`+a.join(`
+`)+(a.length?`
 
 `:`
 `)+`const __defs: { __derivedPath: string; mod: RouteModuleDefault }[] = [
@@ -16,8 +16,8 @@ export const routes: AnyRouteDef[] = __defs.flatMap(({ __derivedPath, mod }) =>
   const list = Array.isArray(mod) ? mod : [mod];
   return list.map((route) => ({ ...route, path: route.path ?? __derivedPath }));
 });
-`;return writeFileSync(t.outFile,d,"utf8"),{outFile:t.outFile,routeCount:e.length,derivedPaths:a}}var E={routesFile:"routes.ts",excludeSegments:["node_modules","__generated__","tests","__tests__",".turbo","dist","build",".next"]};function K(e,t=E){let s=[];return V(e,e,t,s),s.sort((r,o)=>r.relPath.localeCompare(o.relPath)),s}function V(e,t,s,r){let o;try{o=readdirSync(t);}catch{return}for(let i of o){if(s.excludeSegments.includes(i))continue;let c=join(t,i),n;try{n=statSync(c);}catch{continue}if(n.isDirectory())V(e,c,s,r);else if(n.isFile()&&i===s.routesFile){let a=relative(e,c).split(sep).join("/"),d=a.replace(/\/?[^/]+$/,"");r.push({absPath:c,relPath:a,relDir:d});}}}var ee=".frsrc.json";function T(e=process.cwd()){let t=resolve(e,ee);if(!existsSync(t))return {};try{return JSON.parse(readFileSync(t,"utf8"))}catch{return {}}}function he(e,t=process.cwd()){let s=resolve(t,ee),o={...T(t),...e};return writeFileSync(s,`${JSON.stringify(o,null,2)}
-`,"utf8"),s}function ve(e){let[t,...s]=e,r={};for(let o=0;o<s.length;o++){let i=s[o];if(!i.startsWith("--"))continue;let c=i.slice(2),n=s[o+1];n&&!n.startsWith("--")?(r[c]=n,o++):r[c]=true;}return {command:t??"help",flags:r}}function Z(){console.log(`frs \u2014 Hono file-based codegen
+`;return writeFileSync(r.outFile,f,"utf8"),{outFile:r.outFile,routeCount:e.length,derivedPaths:c}}var I={routesFile:"routes.ts",excludeSegments:["node_modules","__generated__","tests","__tests__",".turbo","dist","build",".next"]};function V(e,r=I){let s=[];return Y(e,e,r,s),s.sort((t,o)=>t.relPath.localeCompare(o.relPath)),s}function Y(e,r,s,t){let o;try{o=readdirSync(r);}catch{return}for(let i of o){if(s.excludeSegments.includes(i))continue;let a=join(r,i),n;try{n=statSync(a);}catch{continue}if(n.isDirectory())Y(e,a,s,t);else if(n.isFile()&&i===s.routesFile){let c=relative(e,a).split(sep).join("/"),f=c.replace(/\/?[^/]+$/,"");t.push({absPath:a,relPath:c,relDir:f});}}}var se=".frsrc.json";function z(e=process.cwd()){let r=resolve(e,se);if(!existsSync(r))return {};try{return JSON.parse(readFileSync(r,"utf8"))}catch{return {}}}function ve(e,r=process.cwd()){let s=resolve(r,se),o={...z(r),...e};return writeFileSync(s,`${JSON.stringify(o,null,2)}
+`,"utf8"),s}function ye(e){let[r,...s]=e,t={};for(let o=0;o<s.length;o++){let i=s[o];if(!i.startsWith("--"))continue;let a=i.slice(2),n=s[o+1];n&&!n.startsWith("--")?(t[a]=n,o++):t[a]=true;}return {command:r??"help",flags:t}}function X(){console.log(`frs \u2014 Hono file-based codegen
 
 Usage:
   frs init [flags]
@@ -83,21 +83,20 @@ Examples:
   frs new createPost --domain posts --method post
   frs new listPosts  --domain posts --method get --api v1
   frs add service postRepo
-`);}function Q(e){if(typeof e=="string")return e.split(",").map(t=>t.trim()).filter(Boolean)}function m(e){return typeof e=="string"?e:void 0}function te(e){if(e||!stdin.isTTY)return {ask:async(s,r)=>r??"",askChoice:async(s,r,o)=>o??"",askBool:async(s,r)=>r,close:()=>{}};let t=createInterface({input:stdin,output:stdout});return {async ask(s,r){let o=r?` (${r})`:"";return (await t.question(`? ${s}${o} \u203A `)).trim()||r||""},async askChoice(s,r,o){let i=` [${r.join("/")}${o?`, default: ${o}`:""}]`;for(;;){let c=(await t.question(`? ${s}${i} \u203A `)).trim().toLowerCase();if(!c&&o)return o;if(r.includes(c))return c;console.log(`  invalid choice \u2014 pick one of: ${r.join(", ")}`);}},async askBool(s,r){let o=` (${r?"Y/n":"y/N"})`,i=(await t.question(`? ${s}${o} \u203A `)).trim().toLowerCase();return i?i==="y"||i==="yes"||i==="true":r},close:()=>t.close()}}async function ye(e){let t=T(),s=m(e.root)??t.root;s||(console.error("[frs] --root is required (or run `frs init` to write it to .frsrc.json)"),process.exit(2));let r=resolve(process.cwd(),s);existsSync(r)||(console.error(`[frs] root not found: ${r}`),process.exit(2));let o=m(e.out)??t.out??"__generated__/routes.ts",i=Q(e.skip)??O.skipSegments,c=m(e.casing)==="kebab"?"kebab":O.casing,n={skipSegments:i,casing:c},a=m(e.ext)??".js",d=Q(e.exclude)??E.excludeSegments,f=m(e["routes-file"])??E.routesFile,P=K(r,{routesFile:f,excludeSegments:d});P.length===0&&console.warn(`[frs] no "${f}" files found under ${r} \u2014 generated an empty manifest.`);let y=J(P,{outFile:resolve(r,o),derive:n,importExtension:a});if(!e.silent){console.log(`[frs] wrote ${y.outFile}  (${y.routeCount} route${y.routeCount===1?"":"s"})`);for(let{source:S,url:g}of y.derivedPaths)console.log(`  ${g.padEnd(48)}  \u2190  ${S}`);}}async function $e(e,t){let s=t.yes===true,r=te(s),o=T();try{let i=e&&!e.startsWith("--")?e:void 0;i||(i=(await r.ask("Route name (e.g. createPost)")).trim(),i||(console.error("[frs] route name is required"),process.exit(2)));let c=m(t.domain);c||(c=(await r.ask("Domain name (e.g. posts)")).trim(),c||(console.error("[frs] --domain is required"),process.exit(2)));let n=m(t.root)??o.root??"src/domains",a=m(t.method)?.toLowerCase();a||(a=await r.askChoice("HTTP method",["get","post","put","patch","delete"],"post")),["get","post","put","patch","delete"].includes(a)||(console.error(`[frs] invalid --method: ${a}`),process.exit(2));let d=m(t.api);if(!d){let v=o.apis?.[0]??"v1";d=(await r.ask("API tag",v)).trim()||v;}let f=m(t["usecase-folder"])??o.useCaseFolder??"useCases",p=t["with-usecase"]===void 0?s?!0:await r.askBool("Scaffold useCase.ts?",!0):t["with-usecase"]!==!1,P=t["with-test"]===void 0?s||!p?p:await r.askBool("Scaffold useCase.test.ts (Vitest)?",!0):t["with-test"]!==!1,y=t.force===!0,S=resolve(process.cwd(),n),g=resolve(S,c,f,i),A=resolve(g,"routes.ts"),$=`${c}.${i}.useCase`,R=resolve(g,`${$}.ts`),k=resolve(g,`${$}.test.ts`);mkdirSync(g,{recursive:!0});let F=v=>v.charAt(0).toUpperCase()+v.slice(1),w=`${F(c)}${F(i)}UseCase`,D="@lpdjs/firestore-repo-service/servers/hono",h=Se(S,g),b=a==="get"?"// GET \u2192 lu depuis les query params":`// ${a.toUpperCase()} \u2192 lu depuis le body JSON`,L=`/**
- * ${w} \u2014 pure business logic, no HTTP awareness.
+`);}function ee(e){if(typeof e=="string")return e.split(",").map(r=>r.trim()).filter(Boolean)}function m(e){return typeof e=="string"?e:void 0}function te(e){if(e||!stdin.isTTY)return {ask:async(s,t)=>t??"",askChoice:async(s,t,o)=>o??"",askBool:async(s,t)=>t,close:()=>{}};let r=createInterface({input:stdin,output:stdout});return {async ask(s,t){let o=t?` (${t})`:"";return (await r.question(`? ${s}${o} \u203A `)).trim()||t||""},async askChoice(s,t,o){let i=` [${t.join("/")}${o?`, default: ${o}`:""}]`;for(;;){let a=(await r.question(`? ${s}${i} \u203A `)).trim().toLowerCase();if(!a&&o)return o;if(t.includes(a))return a;console.log(`  invalid choice \u2014 pick one of: ${t.join(", ")}`);}},async askBool(s,t){let o=` (${t?"Y/n":"y/N"})`,i=(await r.question(`? ${s}${o} \u203A `)).trim().toLowerCase();return i?i==="y"||i==="yes"||i==="true":t},close:()=>r.close()}}async function xe(e){let r=z(),s=m(e.root)??r.root;s||(console.error("[frs] --root is required (or run `frs init` to write it to .frsrc.json)"),process.exit(2));let t=resolve(process.cwd(),s);existsSync(t)||(console.error(`[frs] root not found: ${t}`),process.exit(2));let o=m(e.out)??r.out??"__generated__/routes.ts",i=ee(e.skip)??_.skipSegments,a=m(e.casing)==="kebab"?"kebab":_.casing,n={skipSegments:i,casing:a},c=m(e.ext)??".js",f=ee(e.exclude)??I.excludeSegments,g=m(e["routes-file"])??I.routesFile,b=V(t,{routesFile:g,excludeSegments:f});b.length===0&&console.warn(`[frs] no "${g}" files found under ${t} \u2014 generated an empty manifest.`);let h=K(b,{outFile:resolve(t,o),derive:n,importExtension:c});if(!e.silent){console.log(`[frs] wrote ${h.outFile}  (${h.routeCount} route${h.routeCount===1?"":"s"})`);for(let{source:P,url:y}of h.derivedPaths)console.log(`  ${y.padEnd(48)}  \u2190  ${P}`);}}async function we(e,r){let s=r.yes===true,t=te(s),o=z();try{let i=e&&!e.startsWith("--")?e:void 0;i||(i=(await t.ask("Route name (e.g. createPost)")).trim(),i||(console.error("[frs] route name is required"),process.exit(2)));let a=m(r.domain);a||(a=(await t.ask("Domain name (e.g. posts)")).trim(),a||(console.error("[frs] --domain is required"),process.exit(2)));let n=m(r.root)??o.root??"src/domains",c=m(r.method)?.toLowerCase();c||(c=await t.askChoice("HTTP method",["get","post","put","patch","delete"],"post")),["get","post","put","patch","delete"].includes(c)||(console.error(`[frs] invalid --method: ${c}`),process.exit(2));let f=m(r.api);if(!f){let v=o.apis?.[0]??"v1";f=(await t.ask("API tag",v)).trim()||v;}let g=m(r["usecase-folder"])??o.useCaseFolder??"useCases",p=r["with-usecase"]===void 0?s?!0:await t.askBool("Scaffold useCase.ts?",!0):r["with-usecase"]!==!1,b=r["with-test"]===void 0?s||!p?p:await t.askBool("Scaffold useCase.test.ts (Vitest)?",!0):r["with-test"]!==!1,h=r.force===!0,P=resolve(process.cwd(),n),y=resolve(P,a,g,i),F=resolve(y,"routes.ts"),x=`${a}.${i}.useCase`,A=resolve(y,`${x}.ts`),C=resolve(y,`${x}.test.ts`);mkdirSync(y,{recursive:!0});let k=v=>v.charAt(0).toUpperCase()+v.slice(1),$=`${k(a)}${k(i)}UseCase`,D="@lpdjs/firestore-repo-service/servers/hono",w=Ce(P,y),E=Se(P,y),L=c==="get"?"// GET \u2192 lu depuis les query params":`// ${c.toUpperCase()} \u2192 lu depuis le body JSON`,U=`/**
+ * ${$} \u2014 pure business logic, no HTTP awareness.
  *
  * Owns its Zod \`input\` / \`output\` schemas (declared as \`static\` members, the
  * single source of truth shared with \`routes.ts\`) and runs the logic in
- * \`execute\`. The shared \`services\` container is injected by the \`UseCase\` base
- * class via the constructor.
+ * \`execute\`. Extends \`AppUseCase\`, so \`this.services\`, \`this.logger\` and
+ * \`this.error\` are all available.
  */
 
 import { z } from "zod";
-import { UseCase } from "${D}";
-import type { Services } from "${h}";
+import { AppUseCase } from "${E}";
 
 const input = z.object({
-  ${b}
+  ${L}
   example: z.string(),
 });
 
@@ -105,41 +104,45 @@ const output = z.object({
   id: z.string(),
 });
 
-export class ${w} extends UseCase<typeof input, typeof output, Services> {
+export class ${$} extends AppUseCase<typeof input, typeof output> {
   static readonly input = input;
   static readonly output = output;
 
   async execute(
     payload: z.infer<typeof input>,
   ): Promise<z.infer<typeof output>> {
+    this.logger.info("${$} called", { example: payload.example });
+    // Guard example \u2014 mapped to HTTP by the AppErrorHandler:
+    // if (!payload.example) throw this.error.badRequest("example is required");
+
     // TODO: implement using \`this.services\`
     return { id: payload.example };
   }
 }
-`,l=a==="get"?`
-    source: "query",`:"",_=p?`import { ${w} } from "./${$}.js";
-`:"",U=m(t["apis-import"])??Pe(S,g),se=p?`import { defineRoutes } from "${D}";
-import { useCaseRoute } from "${U}";
-${_}
+`,H=c==="get"?`
+    source: "query",`:"",N=p?`import { ${$} } from "./${x}.js";
+`:"",O=m(r["apis-import"])??Pe(P,y),u=p?`import { defineRoutes } from "${D}";
+import { useCaseRoute } from "${O}";
+${N}
 export default defineRoutes([
-  useCaseRoute(${w}, {
-    api: "${d}",
-    method: "${a}",${l}
+  useCaseRoute(${$}, {
+    api: "${f}",
+    method: "${c}",${H}
     summary: "TODO: ${i}",
-    tags: ["${c}"],
+    tags: ["${a}"],
   }),
 ]);
 `:`import { z } from "zod";
 import { defineRoutes } from "${D}";
-import { defineRoute } from "${U}";
+import { defineRoute } from "${O}";
 
 export default defineRoutes([
   defineRoute({
-    api: "${d}",
-    method: "${a}",
+    api: "${f}",
+    method: "${c}",
 
     input: z.object({
-      ${b}
+      ${L}
       example: z.string(),
     }),
 
@@ -148,7 +151,7 @@ export default defineRoutes([
     }),
 
     summary: "TODO: ${i}",
-    tags: ["${c}"],
+    tags: ["${a}"],
 
     handler: async ({ input }) => {
       // TODO: business logic
@@ -156,38 +159,40 @@ export default defineRoutes([
     },
   }),
 ]);
-`,z=[],G=[],N=(v,re)=>{if(existsSync(v)&&!y){G.push(v);return}writeFileSync(v,re,"utf8"),z.push(v);};if(N(A,se),p&&N(R,L),p&&P){let v=`import { describe, it, expect } from "vitest";
-import type { Services } from "${h}";
-import { ${w} } from "./${$}.js";
+`,j=[],G=[],M=(v,oe)=>{if(existsSync(v)&&!h){G.push(v);return}writeFileSync(v,oe,"utf8"),j.push(v);};if(M(F,u),p&&M(A,U),p&&b){let v=`import { describe, it, expect } from "vitest";
+import type { Services } from "${w}";
+import { ${$} } from "./${x}.js";
 
-describe("${w}", () => {
+describe("${$}", () => {
   it("returns a response shaped like the output schema", async () => {
     // TODO: replace with real mocks for the services the useCase consumes.
     const services = {} as unknown as Services;
 
-    const useCase = new ${w}(services);
+    const useCase = new ${$}(services);
     const result = await useCase.execute({ example: "hello" });
     expect(result).toMatchObject({ id: expect.any(String) });
   });
 
   // TODO: add error-path tests, repository mocks, etc.
 });
-`;N(k,v);}for(let v of z)console.log(`[frs] wrote   ${v}`);for(let v of G)console.log(`[frs] skipped ${v} (use --force to overwrite)`);console.log(`
-[frs] reminder: run "frs gen --root ${n}" to refresh the manifest.`);}finally{r.close();}}async function we(e){let t=e.yes===true,s=te(t);try{let r=e.force===!0,o=m(e.root);o||(o=(await s.ask("Domain root","src/domains")).trim()||"src/domains");let i=m(e["apis-file"]);i||(i=(await s.ask("apis.ts location","src/apis.ts")).trim()||"src/apis.ts");let c=m(e["services-file"]);if(!c){let l=i.replace(/apis\.ts$/,"services.ts")||"src/services.ts";c=(await s.ask("services.ts location",l)).trim()||l;}let n=m(e.apis);n||(n=(await s.ask("API tags (comma-separated)","v1")).trim()||"v1");let a=n.split(",").map(l=>l.trim()).filter(Boolean);a.length===0&&(console.error("[frs] at least one API tag is required"),process.exit(2));let d=m(e["base-path"]),f=resolve(process.cwd(),o),p=resolve(process.cwd(),i),P=resolve(process.cwd(),c),y=resolve(f,"__generated__"),S=resolve(y,"routes.ts"),g=[],A=[],$=(l,_)=>{if(mkdirSync(dirname(l),{recursive:!0}),existsSync(l)&&!r){A.push(l);return}writeFileSync(l,_,"utf8"),g.push(l);},R=a.map(l=>{let _=d??`/${l}`;return `    ${l}: {
-      basePath: "${_}",
+`;M(C,v);}for(let v of j)console.log(`[frs] wrote   ${v}`);for(let v of G)console.log(`[frs] skipped ${v} (use --force to overwrite)`);console.log(`
+[frs] reminder: run "frs gen --root ${n}" to refresh the manifest.`);}finally{t.close();}}async function $e(e){let r=e.yes===true,s=te(r);try{let t=e.force===!0,o=m(e.root);o||(o=(await s.ask("Domain root","src/domains")).trim()||"src/domains");let i=m(e["apis-file"]);i||(i=(await s.ask("apis.ts location","src/apis.ts")).trim()||"src/apis.ts");let a=m(e["services-file"]);if(!a){let u=i.replace(/apis\.ts$/,"services.ts")||"src/services.ts";a=(await s.ask("services.ts location",u)).trim()||u;}let n=m(e.apis);n||(n=(await s.ask("API tags (comma-separated)","v1")).trim()||"v1");let c=n.split(",").map(u=>u.trim()).filter(Boolean);c.length===0&&(console.error("[frs] at least one API tag is required"),process.exit(2));let f=m(e["base-path"]),g=resolve(process.cwd(),o),p=resolve(process.cwd(),i),b=resolve(process.cwd(),a),h=resolve(dirname(p),"app-error.ts"),P=resolve(dirname(p),"base-usecase.ts"),y=resolve(g,"__generated__"),F=resolve(y,"routes.ts"),x=[],A=[],C=(u,j)=>{if(mkdirSync(dirname(u),{recursive:!0}),existsSync(u)&&!t){A.push(u);return}writeFileSync(u,j,"utf8"),x.push(u);},k=c.map(u=>{let j=f??`/${u}`;return `    ${u}: {
+      basePath: "${j}",
       openapi: {
-        info: { title: "${l.toUpperCase()} API", version: "1.0.0", description: "" },
+        info: { title: "${u.toUpperCase()} API", version: "1.0.0", description: "" },
       },
-      // Built-in error mapping. Extend BaseErrorHandler to map your own
-      // domain errors, then swap it in here (per API).
-      errorHandler: new BaseErrorHandler(),
-      // Structured console logger. Extend BaseLogger (override \`write\`) to
-      // route to your sink, then swap it in here (per API).
-      logger: new BaseLogger(),
+      // Maps your AppError \u2192 HTTP (extend it in app-error.ts). \`gcpLogs\` adds a
+      // dev-only deep link to the matching GCP log in the error response.
+      errorHandler: new AppErrorHandler({
+        gcpLogs: { enabled: process.env["NODE_ENV"] !== "production" },
+      }),
+      // Shared structured logger (same instance exposed as \`this.logger\`).
+      logger: appLogger,
       verbose: process.env["NODE_ENV"] !== "production",
     },`}).join(`
-`),k=`import { BaseErrorHandler, BaseLogger, createApiRegistry } from "@lpdjs/firestore-repo-service/servers/hono";
-import { services } from "${I(dirname(p),P)}";
+`),$=`import { createApiRegistry } from "@lpdjs/firestore-repo-service/servers/hono";
+import { AppErrorHandler, appLogger } from "${R(dirname(p),h)}";
+import { services } from "${R(dirname(p),b)}";
 
 /**
  * Single source of truth for every API exposed by this project.
@@ -196,12 +201,12 @@ import { services } from "${I(dirname(p),P)}";
  * Per-API resources injected into every handler / interceptor / error-handler
  * context (override them per API above):
  *   - \`services\`     \u2014 shared DI container (\`services.ctx.c\` = current request);
- *   - \`errorHandler\` \u2014 maps thrown errors \u2192 HTTP (extend \`BaseErrorHandler\`);
- *   - \`logger\`       \u2014 structured logging (extend \`BaseLogger\`).
+ *   - \`errorHandler\` \u2014 maps thrown \`AppError\`s \u2192 HTTP (see app-error.ts);
+ *   - \`logger\`       \u2014 structured logging (also \`this.logger\` in useCases).
  */
 export const apis = createApiRegistry(
   {
-${R}
+${k}
   },
   { services },
 );
@@ -209,7 +214,7 @@ ${R}
 /** Typed helpers used inside every route file. */
 export const defineRoute = apis.defineRoute;
 export const useCaseRoute = apis.useCaseRoute;
-`;$(p,k),$(P,`import { createServices } from "@lpdjs/firestore-repo-service/servers/hono";
+`;C(p,$),C(b,`import { createServices } from "@lpdjs/firestore-repo-service/servers/hono";
 
 /**
  * Global DI container \u2014 declare every singleton (repositories, SDK
@@ -242,43 +247,230 @@ export const services = createServices({
 
 /** Convenience type \u2014 \`function fn(svc: Services) { ... }\`. */
 export type Services = typeof services;
-`);let w=`// AUTO-GENERATED by frs \u2014 do not edit.
+`),C(h,`import {
+  BaseErrorHandler,
+  BaseLogger,
+  type ErrorHandlerContext,
+  type LogSeverity,
+} from "@lpdjs/firestore-repo-service/servers/hono";
+
+/** Supported locales \u2014 the single source of truth (runtime + type). */
+export const LOCALES = ["en", "fr"] as const;
+
+/** A supported locale, derived from {@link LOCALES}. */
+export type Locale = (typeof LOCALES)[number];
+
+/** Localized message \u2014 one string per supported locale. */
+export type LocalizedMessage = Record<Locale, string>;
+
+/**
+ * Domain error \u2014 pure business semantics, zero HTTP awareness. Thrown anywhere
+ * in useCases / handlers; the \`AppErrorHandler\` below maps it to an HTTP
+ * response. Carries a localized message; add your own factory methods as your
+ * domain grows.
+ */
+export class AppError extends Error {
+  readonly statusCode: number;
+  readonly userFacing: boolean;
+  readonly errorId: string;
+  readonly localizedMessage: LocalizedMessage;
+
+  private constructor(
+    localizedMessage: LocalizedMessage,
+    statusCode: number,
+    userFacing = false,
+  ) {
+    super(localizedMessage.en);
+    this.name = "AppError";
+    this.statusCode = statusCode;
+    this.userFacing = userFacing;
+    this.localizedMessage = localizedMessage;
+    this.errorId = Math.random().toString(36).slice(2, 12);
+  }
+
+  /** Business message shown directly to the user \u2014 HTTP 412. */
+  static userMessage(message: LocalizedMessage): AppError {
+    return new AppError(message, 412, true);
+  }
+
+  /** Resource not found \u2014 HTTP 404. */
+  static notFound(resource?: string): AppError {
+    return new AppError(
+      {
+        en: \`\${resource ?? "Resource"} not found\`,
+        fr: \`\${resource ?? "Ressource"} introuvable\`,
+      },
+      404,
+    );
+  }
+
+  /** Malformed request / invalid data \u2014 HTTP 400. */
+  static badRequest(detail?: string): AppError {
+    return new AppError(
+      {
+        en: \`Bad request: \${detail ?? "invalid parameters"}\`,
+        fr: \`Requ\xEAte invalide : \${detail ?? "param\xE8tres incorrects"}\`,
+      },
+      400,
+    );
+  }
+
+  /** Generic fallback message for non-user-facing errors. */
+  static default(locale: Locale): string {
+    return locale === "fr" ? "Une erreur est survenue" : "An error occurred";
+  }
+}
+
+/**
+ * Pick the response locale from the \`Accept-Language\` header.
+ *
+ * Parses the comma-separated, q-weighted list (e.g.
+ * \`fr-FR,fr;q=0.9,en;q=0.8\`), keeps the supported locales, and returns the one
+ * with the highest quality. Falls back to \`"en"\`.
+ */
+function pickLocale(c: {
+  req: { header(name: string): string | undefined };
+}): Locale {
+  const header = c.req.header("accept-language");
+  if (!header) return "en";
+
+  const ranked = header
+    .split(",")
+    .map((part) => {
+      const [tag = "", ...params] = part.trim().split(";");
+      const qParam = params.find((p) => p.trim().startsWith("q="));
+      const q = qParam ? Number.parseFloat(qParam.split("=")[1] ?? "") : 1;
+      return {
+        lang: tag.trim().toLowerCase().split("-")[0] ?? "",
+        quality: Number.isFinite(q) ? q : 1,
+      };
+    })
+    .filter((x): x is { lang: Locale; quality: number } =>
+      (LOCALES as readonly string[]).includes(x.lang),
+    )
+    .sort((a, b) => b.quality - a.quality);
+
+  return ranked[0]?.lang ?? "en";
+}
+
+/**
+ * Project logger \u2014 extends \`BaseLogger\` and overrides the single \`write\` hook.
+ * Swap \`console\` for \`firebase-functions/v2\` \`logger\` in real code.
+ */
+export class AppLogger extends BaseLogger {
+  protected override write(
+    severity: LogSeverity,
+    payload: Record<string, unknown>,
+  ): void {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify({ severity, ...payload }));
+  }
+}
+
+/** Shared logger instance (per-API \`logger\` + \`this.logger\` in useCases). */
+export const appLogger = new AppLogger();
+
+/**
+ * Project error strategy \u2014 extends \`BaseErrorHandler\`: \`mapError\` localizes our
+ * \`AppError\` (user-facing aware, with an optional GCP logs deep link),
+ * \`logError\` routes through the logger, and unmatched errors fall back to the
+ * built-in mapping via \`super\`. Wired per API in apis.ts.
+ */
+export class AppErrorHandler extends BaseErrorHandler {
+  protected override mapError({
+    error,
+    c,
+  }: ErrorHandlerContext): Response | null {
+    if (!(error instanceof AppError)) return null; // \u2192 built-in mapping
+
+    const locale = pickLocale(c);
+    const logsUrl = this.gcpLogsUrl(error.errorId); // undefined when disabled
+    return c.json(
+      {
+        // expose the localized message only when it is meant for the user
+        error: error.userFacing
+          ? error.localizedMessage[locale]
+          : AppError.default(locale),
+        errorId: error.errorId,
+        ...(logsUrl ? { logsUrl } : {}),
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      error.statusCode as any,
+    );
+  }
+
+  protected override logError({ error, logger }: ErrorHandlerContext): void {
+    const log = logger ?? appLogger;
+    if (error instanceof AppError && error.statusCode < 500) {
+      log.warn(error.message);
+    } else {
+      log.error(error);
+    }
+  }
+}
+`);let E=`import { UseCase } from "@lpdjs/firestore-repo-service/servers/hono";
+import type { z } from "zod";
+import { AppError, appLogger } from "${R(dirname(P),h)}";
+import type { Services } from "${R(dirname(P),b)}";
+
+/**
+ * Project base class for every useCase \u2014 extends the package's {@link UseCase}
+ * (which injects \`this.services\` via the constructor) and adds two shared
+ * ergonomics: \`this.logger\` (structured logger) and \`this.error\` (the
+ * {@link AppError} factory, mapped to HTTP by the \`AppErrorHandler\`).
+ * Subclasses still declare \`static input\` / \`static output\`.
+ */
+export abstract class AppUseCase<
+  TInput extends z.ZodTypeAny = z.ZodTypeAny,
+  TOutput extends z.ZodTypeAny = z.ZodTypeAny,
+> extends UseCase<TInput, TOutput, Services> {
+  /** Shared structured logger instance (same one injected per-API). */
+  protected readonly logger = appLogger;
+
+  /**
+   * Domain error factory \u2014 \`throw this.error.notFound(...)\` /
+   * \`this.error.badRequest(...)\` / \`this.error.userMessage(...)\`. The thrown
+   * {@link AppError} is mapped to an HTTP response by the \`AppErrorHandler\`.
+   */
+  protected readonly error = AppError;
+}
+`;C(P,E);let L=`// AUTO-GENERATED by frs \u2014 do not edit.
 // Run \`frs gen --root ${o}\` to refresh.
 
 import type { AnyRouteDef } from "@lpdjs/firestore-repo-service/servers/hono";
 
 export const routes: AnyRouteDef[] = [];
-`;$(S,w);let D=he({root:o,apisFile:i,servicesFile:c,apis:a});g.push(D);let h=I(dirname(p),p),b=I(dirname(p),S),L=a.length===1?`export const { ${a[0]} } = apis.toFunctions(routes, onRequest, {`:`export const { ${a.join(", ")} } = apis.toFunctions(routes, onRequest, {`;for(let l of g)console.log(`[frs] wrote   ${l}`);for(let l of A)console.log(`[frs] skipped ${l} (use --force to overwrite)`);console.log(`
+`;C(F,L);let U=ve({root:o,apisFile:i,servicesFile:a,apis:c});x.push(U);let H=R(dirname(p),p),N=R(dirname(p),F),O=c.length===1?`export const { ${c[0]} } = apis.toFunctions(routes, onRequest, {`:`export const { ${c.join(", ")} } = apis.toFunctions(routes, onRequest, {`;for(let u of x)console.log(`[frs] wrote   ${u}`);for(let u of A)console.log(`[frs] skipped ${u} (use --force to overwrite)`);console.log(`
 Next steps:
 
 1. Wire the registry in your Functions entrypoint (e.g. src/index.ts):
 
    import { onRequest } from "firebase-functions/v2/https";
-   import { apis } from "${h}";
-   import { routes } from "${b}";
+   import { apis } from "${H}";
+   import { routes } from "${N}";
 
-   ${L}
+   ${O}
      defaults: { region: "us-central1", invoker: "public" },
    });
 
 2. Scaffold a first route:
 
-   frs new createPost --domain posts --method post --api ${a[0]}
+   frs new createPost --domain posts --method post --api ${c[0]}
 
 3. Refresh the manifest before each build:
 
    frs gen --root ${o}
-`);}finally{s.close();}}function I(e,t){let s=relative(e,t).replace(/\\/g,"/");return s=s.replace(/\.ts$/,".js"),s.startsWith(".")||(s=`./${s}`),s}async function xe(e,t,s){e!=="service"&&(console.error(`[frs] unknown "add" target: ${e??"(missing)"} \u2014 supported: service`),process.exit(2)),t||(console.error("[frs] service name is required: frs add service <name>"),process.exit(2));let r=s.force===true,o=T(),c=[m(s["services-file"]),o.servicesFile,"src/services.ts","services.ts"].filter(h=>typeof h=="string"&&h.length>0),n;for(let h of c){let b=resolve(process.cwd(),h);if(existsSync(b)){n=b;break}}if(!n){let h=c.map(b=>resolve(process.cwd(),b)).join(`
+`);}finally{s.close();}}function R(e,r){let s=relative(e,r).replace(/\\/g,"/");return s=s.replace(/\.ts$/,".js"),s.startsWith(".")||(s=`./${s}`),s}async function be(e,r,s){e!=="service"&&(console.error(`[frs] unknown "add" target: ${e??"(missing)"} \u2014 supported: service`),process.exit(2)),r||(console.error("[frs] service name is required: frs add service <name>"),process.exit(2));let t=s.force===true,o=z(),a=[m(s["services-file"]),o.servicesFile,"src/services.ts","services.ts"].filter(w=>typeof w=="string"&&w.length>0),n;for(let w of a){let E=resolve(process.cwd(),w);if(existsSync(E)){n=E;break}}if(!n){let w=a.map(E=>resolve(process.cwd(),E)).join(`
         `);console.error(`[frs] services file not found. Tried:
-        ${h}
-      Run \`frs init\` first or pass --services-file <path>.`),process.exit(2);}let a=m(s["services-dir"])??o.servicesDir??resolve(dirname(n),"services"),d=resolve(process.cwd(),a);mkdirSync(d,{recursive:true});let f=`${t.charAt(0).toUpperCase()}${t.slice(1)}Service`,p=resolve(d,`${t}.ts`),P=`import type { RequestContext } from "@lpdjs/firestore-repo-service/servers/hono";
+        ${w}
+      Run \`frs init\` first or pass --services-file <path>.`),process.exit(2);}let c=m(s["services-dir"])??o.servicesDir??resolve(dirname(n),"services"),f=resolve(process.cwd(),c);mkdirSync(f,{recursive:true});let g=`${r.charAt(0).toUpperCase()}${r.slice(1)}Service`,p=resolve(f,`${r}.ts`),b=`import type { RequestContext } from "@lpdjs/firestore-repo-service/servers/hono";
 
 /**
- * ${f} \u2014 generated by \`frs add service ${t}\`.
+ * ${g} \u2014 generated by \`frs add service ${r}\`.
  *
  * Registered with a **factory** in \`services.ts\` so dependencies are
  * destructured at registration time. Add new constructor parameters here
- * and update the factory line (\`({ ctx, otherSvc }) => new ${f}(ctx, otherSvc)\`)
+ * and update the factory line (\`({ ctx, otherSvc }) => new ${g}(ctx, otherSvc)\`)
  * \u2014 TypeScript will tell you when something is missing.
  *
  * Async resources (DB connections, SDK clients) should stay lazy-loaded
@@ -292,17 +484,17 @@ Next steps:
  * }
  * \`\`\`
  */
-export class ${f} {
+export class ${g} {
   // eslint-disable-next-line @typescript-eslint/no-useless-constructor
   constructor(private readonly ctx: RequestContext) {}
 
   hello(): string {
-    return \`hello from ${t} \u2014 user=\${this.ctx.maybeC?.get("user")?.id ?? "anonymous"}\`;
+    return \`hello from ${r} \u2014 user=\${this.ctx.maybeC?.get("user")?.id ?? "anonymous"}\`;
   }
 }
-`;existsSync(p)&&!r?console.log(`[frs] skipped ${p} (use --force to overwrite)`):(writeFileSync(p,P,"utf8"),console.log(`[frs] wrote   ${p}`));let y=readFileSync(n,"utf8"),S=I(dirname(n),p),g=`import { ${f} } from "${S}";`,A=`  ${t}: ({ ctx }) => new ${f}(ctx),`;if(y.includes(g)){console.log(`[frs] services.ts already registers "${t}" \u2014 skipping.`);return}let $=y.split(`
-`),R=-1;for(let h=0;h<$.length;h++)/^import\s/.test($[h])&&(R=h);R>=0?$.splice(R+1,0,g):$.unshift(g);let k=$.join(`
-`),F=k.match(/createServices\s*\(\s*\{/);if(!F){console.error(`[frs] could not find \`createServices({\` in ${n} \u2014 register "${t}" manually.`);return}let w=F.index+F[0].length,D=k.slice(0,w)+`
-`+A+k.slice(w);writeFileSync(n,D,"utf8"),console.log(`[frs] updated ${n}  (+ ${t})`);}function Pe(e,t){let s=["apis.ts","apis.js","api.ts","api.js"],r=[e,dirname(e),dirname(dirname(e))];for(let o of r)for(let i of s){let c=resolve(o,i);if(existsSync(c)){let n=relative(t,c).replace(/\\/g,"/");return n=n.replace(/\.ts$/,".js").replace(/\.js$/,".js"),n.startsWith(".")||(n=`./${n}`),n}}return "../../../../apis.js"}function Se(e,t){let s=["services.ts","services.js"],r=[e,dirname(e),dirname(dirname(e))];for(let o of r)for(let i of s){let c=resolve(o,i);if(existsSync(c)){let n=relative(t,c).replace(/\\/g,"/");return n=n.replace(/\.ts$/,".js"),n.startsWith(".")||(n=`./${n}`),n}}return "../../../../services.js"}async function be(){let e=process.argv.slice(2),{command:t,flags:s}=ve(e);switch(t){case "init":await we(s);return;case "gen":await ye(s);return;case "new":await $e(e[1],s);return;case "add":await xe(e[1],e[2],s);return;case "help":case "--help":case "-h":Z();return;default:console.error(`[frs] unknown command: ${t}
-`),Z(),process.exit(2);}}be().catch(e=>{console.error(e),process.exit(1);});//# sourceMappingURL=cli.js.map
+`;existsSync(p)&&!t?console.log(`[frs] skipped ${p} (use --force to overwrite)`):(writeFileSync(p,b,"utf8"),console.log(`[frs] wrote   ${p}`));let h=readFileSync(n,"utf8"),P=R(dirname(n),p),y=`import { ${g} } from "${P}";`,F=`  ${r}: ({ ctx }) => new ${g}(ctx),`;if(h.includes(y)){console.log(`[frs] services.ts already registers "${r}" \u2014 skipping.`);return}let x=h.split(`
+`),A=-1;for(let w=0;w<x.length;w++)/^import\s/.test(x[w])&&(A=w);A>=0?x.splice(A+1,0,y):x.unshift(y);let C=x.join(`
+`),k=C.match(/createServices\s*\(\s*\{/);if(!k){console.error(`[frs] could not find \`createServices({\` in ${n} \u2014 register "${r}" manually.`);return}let $=k.index+k[0].length,D=C.slice(0,$)+`
+`+F+C.slice($);writeFileSync(n,D,"utf8"),console.log(`[frs] updated ${n}  (+ ${r})`);}function Pe(e,r){let s=["apis.ts","apis.js","api.ts","api.js"],t=[e,dirname(e),dirname(dirname(e))];for(let o of t)for(let i of s){let a=resolve(o,i);if(existsSync(a)){let n=relative(r,a).replace(/\\/g,"/");return n=n.replace(/\.ts$/,".js").replace(/\.js$/,".js"),n.startsWith(".")||(n=`./${n}`),n}}return "../../../../apis.js"}function Ce(e,r){let s=["services.ts","services.js"],t=[e,dirname(e),dirname(dirname(e))];for(let o of t)for(let i of s){let a=resolve(o,i);if(existsSync(a)){let n=relative(r,a).replace(/\\/g,"/");return n=n.replace(/\.ts$/,".js"),n.startsWith(".")||(n=`./${n}`),n}}return "../../../../services.js"}function Se(e,r){let s=["base-usecase.ts","base-usecase.js"],t=[e,dirname(e),dirname(dirname(e))];for(let o of t)for(let i of s){let a=resolve(o,i);if(existsSync(a)){let n=relative(r,a).replace(/\\/g,"/");return n=n.replace(/\.ts$/,".js"),n.startsWith(".")||(n=`./${n}`),n}}return "../../../../base-usecase.js"}async function Ae(){let e=process.argv.slice(2),{command:r,flags:s}=ye(e);switch(r){case "init":await $e(s);return;case "gen":await xe(s);return;case "new":await we(e[1],s);return;case "add":await be(e[1],e[2],s);return;case "help":case "--help":case "-h":X();return;default:console.error(`[frs] unknown command: ${r}
+`),X(),process.exit(2);}}Ae().catch(e=>{console.error(e),process.exit(1);});//# sourceMappingURL=cli.js.map
 //# sourceMappingURL=cli.js.map