@kosdev-code/kos-codegen-core 0.1.0-next.847 → 0.1.0-next.849

package/index.mjs

@@ -3,8 +3,8 @@ import * as path from "path";
 import * as ejs from "ejs";
 import fg from "fast-glob";
 import prettier from "prettier";
+import { Scope, Project, QuoteKind, IndentationText, VariableDeclarationKind, Node } from "ts-morph";
 import * as ts from "typescript";
-import { Scope, Project, QuoteKind, IndentationText, Node } from "ts-morph";
 class TrackingFileSystem {
   inner;
   _writtenPaths = [];
@@ -560,6 +560,72 @@ function generatePolyglotWorkspace(codegenFs, templateDir, options) {
   );
   return { executablePaths: [...BUILD_SCRIPTS] };
 }
+const KAB_OUTPUT_DIR = "target";
+const KAB_OUTPUT_PATH = `{projectRoot}/${KAB_OUTPUT_DIR}/`;
+function resolveKabPath(value, projectRoot) {
+  const root = projectRoot.replace(/\\/g, "/").replace(/\/+$/, "");
+  return value.replace(/\{projectRoot\}/g, root).replace(/\{workspaceRoot\}\/?/g, "");
+}
+const UPDATE_RELEASE_VERSION_SCRIPT_PATH = "tools/scripts/update-release-version.mjs";
+function buildKabTargets(options) {
+  const { name, descriptor = false, buildTarget = "build" } = options;
+  const outputPath = KAB_OUTPUT_PATH;
+  const zipPayloadDir = "dist/{projectRoot}";
+  const targets = {
+    kab: {
+      command: `node tools/scripts/kabtool.mjs build ${name} && node tools/scripts/kabtool.mjs list ${name} `,
+      options: {
+        outputPath,
+        zipName: "ui.zip",
+        kabName: `${name}.kab`
+      },
+      dependsOn: ["zip"]
+    },
+    zip: {
+      command: `node tools/scripts/archiver.js ${name}`,
+      options: {
+        outputPath,
+        zipName: "ui.zip"
+      },
+      // `sbom` is a zip dependency, not a kab one: kabtool packages an
+      // already-sealed ui.zip, so anything ordered after `zip` misses it.
+      dependsOn: descriptor ? [buildTarget, "descriptor", "sbom"] : [buildTarget, "sbom"]
+    }
+  };
+  if (descriptor) {
+    targets.descriptor = {
+      command: `node tools/scripts/descriptor.mjs ${name}`,
+      options: {
+        outputPath: zipPayloadDir,
+        fileName: "descriptor.json"
+      },
+      dependsOn: ["build"]
+    };
+  }
+  targets.version = {
+    command: `node ${UPDATE_RELEASE_VERSION_SCRIPT_PATH} ${name} {args.ver}`,
+    options: {},
+    dependsOn: []
+  };
+  targets.sbom = buildSbomTarget({ outputPath: zipPayloadDir });
+  return targets;
+}
+function buildSbomTarget({
+  outputPath
+}) {
+  const dir = outputPath.replace(/\/+$/, "");
+  const outputDir = dir.startsWith("{") ? dir : `{workspaceRoot}/${dir}`;
+  return {
+    executor: "@kosdev-code/kos-nx-plugin:sbom",
+    outputs: [
+      `${outputDir}/sbom.spdx.json`,
+      `${outputDir}/sbom.cyclonedx.json`
+    ],
+    cache: true,
+    inputs: ["production", "^production", "{workspaceRoot}/package-lock.json"],
+    options: { outputPath: dir, softFail: true }
+  };
+}
 const UI_PROJECT_DIRS = [
   "apps",
   "libs",
@@ -587,16 +653,25 @@ function discoverUiArtifacts(codegenFs) {
       }
       const name = project.name;
       if (!name) continue;
+      const projectRoot = file.slice("ui/".length, file.lastIndexOf("/"));
+      const resolve = (value) => resolveKabPath(value, projectRoot);
       const kabOptions = project.targets?.kab?.options;
       if (kabOptions?.outputPath && kabOptions?.kabName) {
         artifacts.push({
           id: name,
-          filename: `ui/${joinArtifactPath(kabOptions.outputPath, kabOptions.kabName)}`
+          filename: `ui/${joinArtifactPath(
+            resolve(kabOptions.outputPath),
+            kabOptions.kabName
+          )}`
         });
       } else if (project.targets?.splash) {
+        const splashOutput = project.targets.splash.options?.outputPath;
         artifacts.push({
           id: name,
-          filename: `ui/dist/archives/packages/${name}/${name}.kab`,
+          filename: `ui/${joinArtifactPath(
+            resolve(splashOutput ?? `{projectRoot}/${KAB_OUTPUT_DIR}`),
+            `${name}.kab`
+          )}`,
           layer: 1
         });
       }
@@ -851,67 +926,249 @@ function normalizeOptions(codegenFs, options, projects) {
     template: ""
   };
 }
-const UPDATE_RELEASE_VERSION_SCRIPT_PATH = "tools/scripts/update-release-version.mjs";
-function buildKabTargets(options) {
-  const {
-    name,
-    archiveDir = "packages",
-    descriptorDir,
-    buildTarget = "build"
-  } = options;
-  const outputPath = `dist/archives/${archiveDir}/${name}/`;
-  const targets = {
-    kab: {
-      command: `node tools/scripts/kabtool.mjs build ${name} && node tools/scripts/kabtool.mjs list ${name} `,
-      options: {
-        outputPath,
-        zipName: "ui.zip",
-        kabName: `${name}.kab`
-      },
-      dependsOn: ["zip"]
-    },
-    zip: {
-      command: `node tools/scripts/archiver.js ${name}`,
-      options: {
-        outputPath,
-        zipName: "ui.zip"
-      },
-      dependsOn: descriptorDir ? [buildTarget, "descriptor"] : [buildTarget]
+function transformSourceFile(codegenFs, filePath, mutate) {
+  const content = codegenFs.read(filePath);
+  if (content === null) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+  const project = new Project({
+    useInMemoryFileSystem: true,
+    manipulationSettings: {
+      indentationText: IndentationText.TwoSpaces,
+      quoteKind: QuoteKind.Double
     }
-  };
-  if (descriptorDir) {
-    targets.descriptor = {
-      command: `node tools/scripts/descriptor.mjs ${name}`,
-      options: {
-        outputPath: `dist/${descriptorDir}`,
-        fileName: "descriptor.json"
-      },
-      dependsOn: ["build"]
-    };
+  });
+  const sourceFile = project.createSourceFile(filePath, content, {
+    overwrite: true
+  });
+  mutate(sourceFile);
+  codegenFs.write(filePath, sourceFile.getFullText());
+}
+function readSourceFile(codegenFs, filePath, inspect) {
+  const content = codegenFs.read(filePath);
+  if (content === null) {
+    throw new Error(`File not found: ${filePath}`);
   }
-  targets.version = {
-    command: `node ${UPDATE_RELEASE_VERSION_SCRIPT_PATH} ${name} {args.ver}`,
-    options: {},
-    dependsOn: []
-  };
-  targets.sbom = buildSbomTarget({ outputPath });
-  targets.kab.dependsOn = [...targets.kab.dependsOn ?? [], "sbom"];
-  return targets;
+  const project = new Project({ useInMemoryFileSystem: true });
+  return inspect(
+    project.createSourceFile(filePath, content, { overwrite: true })
+  );
 }
-function buildSbomTarget({
-  outputPath
-}) {
-  const dir = outputPath.replace(/\/+$/, "");
-  return {
-    executor: "@kosdev-code/kos-nx-plugin:sbom",
-    outputs: [
-      `{workspaceRoot}/${dir}/sbom.spdx.json`,
-      `{workspaceRoot}/${dir}/sbom.cyclonedx.json`
-    ],
-    cache: true,
-    inputs: ["production", "^production", "{workspaceRoot}/package-lock.json"],
-    options: { outputPath: dir, softFail: true }
-  };
+function ensureNamedImport(sourceFile, moduleSpecifier, names) {
+  const decls = sourceFile.getImportDeclarations().filter((d) => d.getModuleSpecifierValue() === moduleSpecifier);
+  const existing = /* @__PURE__ */ new Set();
+  for (const d of decls) {
+    for (const n of d.getNamedImports()) existing.add(n.getName());
+  }
+  let target = decls.find((d) => !d.isTypeOnly());
+  if (!target) {
+    target = sourceFile.addImportDeclaration({ moduleSpecifier });
+  }
+  for (const { name, isTypeOnly } of names) {
+    if (existing.has(name)) continue;
+    target.addNamedImport({ name, isTypeOnly: !!isTypeOnly });
+    existing.add(name);
+  }
+}
+function resolveSdkModuleSpecifier(sourceFile) {
+  const decl = sourceFile.getImportDeclarations().find((d) => d.getNamedImports().some((n) => n.getName() === "kosModel"));
+  return decl?.getModuleSpecifierValue() ?? "@kosdev-code/kos-ui-sdk";
+}
+function getModelClass(sourceFile, preferName) {
+  const classes = sourceFile.getClasses();
+  const byName = preferName ? classes.find((c) => c.getName() === preferName) : void 0;
+  if (byName) return byName;
+  const impl = classes.find((c) => /ModelImpl$/.test(c.getName() ?? ""));
+  if (impl) return impl;
+  const exported = classes.find((c) => c.isExported());
+  if (exported) return exported;
+  if (classes.length > 0) return classes[0];
+  throw new Error("No class declaration found in model file.");
+}
+function addClassDecorator(cls, name, opts) {
+  if (cls.getDecorator(name)) return;
+  const typeArgs = opts?.typeArgs?.length ? `<${opts.typeArgs.join(", ")}>` : "";
+  const args = opts?.argsText ?? "";
+  const decorators = cls.getDecorators();
+  const kosModelIdx = decorators.findIndex((d) => d.getName() === "kosModel");
+  const insertIdx = kosModelIdx >= 0 ? kosModelIdx + 1 : decorators.length;
+  cls.insertDecorator(insertIdx, {
+    name: `${name}${typeArgs}`,
+    arguments: args ? [args] : []
+  });
+}
+function ensureDeclarationMerge(sourceFile, interfaceName, extendsExpr, typeParameters = []) {
+  const baseType = extendsExpr.split("<")[0].trim();
+  let iface = sourceFile.getInterface(interfaceName);
+  if (iface) {
+    const already = iface.getExtends().some((e) => e.getText().split("<")[0].trim() === baseType);
+    if (!already) iface.addExtends(extendsExpr);
+    return;
+  }
+  iface = sourceFile.addInterface({
+    name: interfaceName,
+    isExported: true,
+    typeParameters,
+    extends: [extendsExpr]
+  });
+  sourceFile.insertText(
+    iface.getStart(),
+    "// eslint-disable-next-line @typescript-eslint/no-empty-interface\n"
+  );
+}
+function ensureFileEslintDisable(sourceFile, rule) {
+  if (sourceFile.getFullText().includes(rule)) return;
+  sourceFile.insertText(0, `/* eslint-disable ${rule} */
+`);
+}
+function ensureModuleConst(sourceFile, spec) {
+  if (sourceFile.getVariableDeclaration(spec.name)) return false;
+  const imports = sourceFile.getImportDeclarations();
+  const index = imports.length > 0 ? imports[imports.length - 1].getChildIndex() + 1 : 0;
+  sourceFile.insertVariableStatement(index, {
+    declarationKind: VariableDeclarationKind.Const,
+    declarations: [{ name: spec.name, initializer: spec.initializer }]
+  });
+  return true;
+}
+function addDecoratedMethod(cls, spec) {
+  if (cls.getMethod(spec.name)) return false;
+  cls.addMethod({
+    name: spec.name,
+    isAsync: spec.isAsync,
+    returnType: spec.returnType,
+    parameters: spec.parameters?.map((p) => {
+      return { name: p.name, type: p.type, hasQuestionToken: p.optional };
+    }),
+    statements: spec.statements,
+    decorators: [
+      {
+        name: spec.decoratorName,
+        arguments: spec.decoratorArgsText ? [spec.decoratorArgsText] : []
+      }
+    ]
+  });
+  return true;
+}
+function propertyInsertIndex(cls) {
+  const props = cls.getProperties();
+  if (props.length === 0) return 0;
+  return props[props.length - 1].getChildIndex() + 1;
+}
+function addPlainProperty(cls, spec) {
+  if (cls.getProperty(spec.name)) return false;
+  cls.insertProperty(propertyInsertIndex(cls), {
+    name: spec.name,
+    type: spec.type,
+    initializer: spec.initializer,
+    isReadonly: !!spec.readonly,
+    scope: spec.scope ? SCOPE_MAP[spec.scope] : void 0,
+    hasExclamationToken: spec.initializer ? false : !!spec.hasExclamation
+  });
+  return true;
+}
+const SCOPE_MAP = {
+  private: Scope.Private,
+  protected: Scope.Protected,
+  public: Scope.Public
+};
+function addDecoratedProperty(cls, spec) {
+  if (cls.getProperty(spec.name)) return false;
+  cls.insertProperty(propertyInsertIndex(cls), {
+    name: spec.name,
+    type: spec.type,
+    initializer: spec.initializer,
+    scope: spec.scope ? SCOPE_MAP[spec.scope] : void 0,
+    hasExclamationToken: spec.initializer ? false : !!spec.hasExclamation,
+    decorators: [
+      spec.bare && !spec.decoratorArgsText ? { name: spec.decoratorName } : {
+        name: spec.decoratorName,
+        arguments: spec.decoratorArgsText ? [spec.decoratorArgsText] : []
+      }
+    ]
+  });
+  return true;
+}
+function addGetter(cls, spec) {
+  if (cls.getGetAccessor(spec.name)) return false;
+  const ctor = cls.getConstructors()[0];
+  const index = ctor ? ctor.getChildIndex() + 1 : propertyInsertIndex(cls);
+  cls.insertGetAccessor(index, {
+    name: spec.name,
+    returnType: spec.returnType,
+    statements: spec.statements ?? "// TODO: derive and return the computed value"
+  });
+  return true;
+}
+const CATALOG_METHODS = ["get", "put", "post", "delete", "patch"];
+const SERVICE_MODULE_RE$1 = /\/utils\/services\/([^/]+)\/([^/]+)\/service\.ts$/;
+function listServiceCatalog(codegenFs, query, projects) {
+  const project = findProjectByName(
+    codegenFs.root,
+    query.modelProject,
+    projects
+  );
+  if (!project) {
+    throw new Error(`Project not found: ${query.modelProject}`);
+  }
+  const sourceRoot = project.sourceRoot || path.join(project.root, "src");
+  const entries = [];
+  for (const file of codegenFs.listFiles(sourceRoot)) {
+    const posix = file.split(path.sep).join("/");
+    const match = SERVICE_MODULE_RE$1.exec(posix);
+    if (!match) continue;
+    const [, app, version] = match;
+    if (query.app && app !== query.app) continue;
+    if (query.version && version !== query.version) continue;
+    const openapiPath = posix.replace(/service\.ts$/, "openapi.d.ts");
+    if (!codegenFs.exists(openapiPath)) continue;
+    entries.push({
+      app,
+      version,
+      serviceModulePath: posix,
+      operations: readOperations(codegenFs, openapiPath)
+    });
+  }
+  return entries.sort(
+    (a, b) => a.app.localeCompare(b.app) || a.version.localeCompare(b.version)
+  );
+}
+function readOperations(codegenFs, openapiPath) {
+  return readSourceFile(codegenFs, openapiPath, (sf) => {
+    const paths = sf.getInterface("paths");
+    if (!paths) return [];
+    const operations = [];
+    for (const pathProp of paths.getProperties()) {
+      const servicePath = unquote(pathProp.getName());
+      const literal = pathProp.getTypeNode();
+      if (!literal || !("getProperties" in literal)) continue;
+      for (const methodProp of literal.getProperties()) {
+        const method = methodProp.getName();
+        if (!isCatalogMethod(method)) continue;
+        const typeText = methodProp.getTypeNode()?.getText() ?? "";
+        if (methodProp.hasQuestionToken() && typeText === "never") continue;
+        operations.push({
+          path: servicePath,
+          method,
+          summary: readSummary(methodProp),
+          pathParams: [...servicePath.matchAll(/\{([^}]+)\}/g)].map(
+            (m) => m[1]
+          )
+        });
+      }
+    }
+    return operations;
+  });
+}
+function isCatalogMethod(value) {
+  return CATALOG_METHODS.includes(value);
+}
+function readSummary(methodProp) {
+  const text = methodProp.getLeadingCommentRanges().map((c) => c.getText()).join(" ").replace(/^\/\*+/, "").replace(/\*+\/$/, "").replace(/^\s*\*\s?/gm, "").replace(/\s+/g, " ").trim();
+  return text || void 0;
+}
+function unquote(name) {
+  return name.replace(/^["']|["']$/g, "");
 }
 const UPDATE_RELEASE_VERSION_SCRIPT = `import devkit from "@nx/devkit";
 import { resolve } from "path";
@@ -1473,160 +1730,6 @@ function normalizeAddFutureOptions(codegenFs, options, projects) {
     internal
   };
 }
-function transformSourceFile(codegenFs, filePath, mutate) {
-  const content = codegenFs.read(filePath);
-  if (content === null) {
-    throw new Error(`File not found: ${filePath}`);
-  }
-  const project = new Project({
-    useInMemoryFileSystem: true,
-    manipulationSettings: {
-      indentationText: IndentationText.TwoSpaces,
-      quoteKind: QuoteKind.Double
-    }
-  });
-  const sourceFile = project.createSourceFile(filePath, content, {
-    overwrite: true
-  });
-  mutate(sourceFile);
-  codegenFs.write(filePath, sourceFile.getFullText());
-}
-function ensureNamedImport(sourceFile, moduleSpecifier, names) {
-  const decls = sourceFile.getImportDeclarations().filter((d) => d.getModuleSpecifierValue() === moduleSpecifier);
-  const existing = /* @__PURE__ */ new Set();
-  for (const d of decls) {
-    for (const n of d.getNamedImports()) existing.add(n.getName());
-  }
-  let target = decls.find((d) => !d.isTypeOnly());
-  if (!target) {
-    target = sourceFile.addImportDeclaration({ moduleSpecifier });
-  }
-  for (const { name, isTypeOnly } of names) {
-    if (existing.has(name)) continue;
-    target.addNamedImport({ name, isTypeOnly: !!isTypeOnly });
-    existing.add(name);
-  }
-}
-function resolveSdkModuleSpecifier(sourceFile) {
-  const decl = sourceFile.getImportDeclarations().find((d) => d.getNamedImports().some((n) => n.getName() === "kosModel"));
-  return decl?.getModuleSpecifierValue() ?? "@kosdev-code/kos-ui-sdk";
-}
-function getModelClass(sourceFile, preferName) {
-  const classes = sourceFile.getClasses();
-  const byName = preferName ? classes.find((c) => c.getName() === preferName) : void 0;
-  if (byName) return byName;
-  const impl = classes.find((c) => /ModelImpl$/.test(c.getName() ?? ""));
-  if (impl) return impl;
-  const exported = classes.find((c) => c.isExported());
-  if (exported) return exported;
-  if (classes.length > 0) return classes[0];
-  throw new Error("No class declaration found in model file.");
-}
-function addClassDecorator(cls, name, opts) {
-  if (cls.getDecorator(name)) return;
-  const typeArgs = opts?.typeArgs?.length ? `<${opts.typeArgs.join(", ")}>` : "";
-  const args = opts?.argsText ?? "";
-  const decorators = cls.getDecorators();
-  const kosModelIdx = decorators.findIndex((d) => d.getName() === "kosModel");
-  const insertIdx = kosModelIdx >= 0 ? kosModelIdx + 1 : decorators.length;
-  cls.insertDecorator(insertIdx, {
-    name: `${name}${typeArgs}`,
-    arguments: args ? [args] : []
-  });
-}
-function ensureDeclarationMerge(sourceFile, interfaceName, extendsExpr, typeParameters = []) {
-  const baseType = extendsExpr.split("<")[0].trim();
-  let iface = sourceFile.getInterface(interfaceName);
-  if (iface) {
-    const already = iface.getExtends().some((e) => e.getText().split("<")[0].trim() === baseType);
-    if (!already) iface.addExtends(extendsExpr);
-    return;
-  }
-  iface = sourceFile.addInterface({
-    name: interfaceName,
-    isExported: true,
-    typeParameters,
-    extends: [extendsExpr]
-  });
-  sourceFile.insertText(
-    iface.getStart(),
-    "// eslint-disable-next-line @typescript-eslint/no-empty-interface\n"
-  );
-}
-function ensureFileEslintDisable(sourceFile, rule) {
-  if (sourceFile.getFullText().includes(rule)) return;
-  sourceFile.insertText(0, `/* eslint-disable ${rule} */
-`);
-}
-function addDecoratedMethod(cls, spec) {
-  if (cls.getMethod(spec.name)) return false;
-  cls.addMethod({
-    name: spec.name,
-    isAsync: spec.isAsync,
-    returnType: spec.returnType,
-    parameters: spec.parameters?.map((p) => {
-      return { name: p.name, type: p.type };
-    }),
-    statements: spec.statements,
-    decorators: [
-      {
-        name: spec.decoratorName,
-        arguments: spec.decoratorArgsText ? [spec.decoratorArgsText] : []
-      }
-    ]
-  });
-  return true;
-}
-function propertyInsertIndex(cls) {
-  const props = cls.getProperties();
-  if (props.length === 0) return 0;
-  return props[props.length - 1].getChildIndex() + 1;
-}
-function addPlainProperty(cls, spec) {
-  if (cls.getProperty(spec.name)) return false;
-  cls.insertProperty(propertyInsertIndex(cls), {
-    name: spec.name,
-    type: spec.type,
-    initializer: spec.initializer,
-    isReadonly: !!spec.readonly,
-    scope: spec.scope ? SCOPE_MAP[spec.scope] : void 0,
-    hasExclamationToken: spec.initializer ? false : !!spec.hasExclamation
-  });
-  return true;
-}
-const SCOPE_MAP = {
-  private: Scope.Private,
-  protected: Scope.Protected,
-  public: Scope.Public
-};
-function addDecoratedProperty(cls, spec) {
-  if (cls.getProperty(spec.name)) return false;
-  cls.insertProperty(propertyInsertIndex(cls), {
-    name: spec.name,
-    type: spec.type,
-    initializer: spec.initializer,
-    scope: spec.scope ? SCOPE_MAP[spec.scope] : void 0,
-    hasExclamationToken: spec.initializer ? false : !!spec.hasExclamation,
-    decorators: [
-      spec.bare && !spec.decoratorArgsText ? { name: spec.decoratorName } : {
-        name: spec.decoratorName,
-        arguments: spec.decoratorArgsText ? [spec.decoratorArgsText] : []
-      }
-    ]
-  });
-  return true;
-}
-function addGetter(cls, spec) {
-  if (cls.getGetAccessor(spec.name)) return false;
-  const ctor = cls.getConstructors()[0];
-  const index = ctor ? ctor.getChildIndex() + 1 : propertyInsertIndex(cls);
-  cls.insertGetAccessor(index, {
-    name: spec.name,
-    returnType: spec.returnType,
-    statements: spec.statements ?? "// TODO: derive and return the computed value"
-  });
-  return true;
-}
 const LEGACY_IMPORTS = /* @__PURE__ */ new Set([
   "setupCompleteFutureSupport",
   "setupMinimalFutureSupport",
@@ -2433,6 +2536,12 @@ function addServiceRequestToModel(codegenFs, options, projects) {
     throw new Error(`Model file not found: ${modelFilePath}`);
   }
   let serviceImport = options.serviceModule;
+  if (!serviceImport && options.serviceModulePath) {
+    serviceImport = toImportSpecifier(
+      modelFilePath,
+      options.serviceModulePath.replace(/\.ts$/, "")
+    );
+  }
   if (!serviceImport) {
     if (!sourceRoot) {
       throw new Error(
@@ -2458,31 +2567,93 @@ function addServiceRequestToModel(codegenFs, options, projects) {
     serviceImport = specifiers[0];
   }
   const method = options.method || "get";
+  const mode = options.mode ?? (options.lifecycle ? "lifecycle" : "method");
   const lifecycle = options.lifecycle || "LOAD";
   logger.info(
-    `Adding @kosServiceRequest "${options.methodName}" (${method} ${options.servicePath}) to ${options.modelName}`
+    `Adding ${mode}-driven @kosServiceRequest "${options.methodName}" (${method} ${options.servicePath}) to ${options.modelName}`
   );
   transformSourceFile(codegenFs, modelFilePath, (sf) => {
+    const endpointConst = endpointConstName(options.methodName);
+    const className = getModelClass(sf).getName();
+    if (!className) throw new Error("Model class has no name.");
+    const typeParams = getModelClass(sf).getTypeParameters().map((tp) => tp.getText());
+    ensureNamedImport(sf, serviceImport, [
+      { name: "endpoint" },
+      { name: "serviceRequest" }
+    ]);
+    ensureModuleConst(sf, {
+      name: endpointConst,
+      initializer: `endpoint(${JSON.stringify(
+        options.servicePath
+      )}, ${JSON.stringify(method)})`
+    });
+    if (mode === "lifecycle") {
+      ensureNamedImport(sf, serviceImport, [
+        { name: "EndpointResponse", isTypeOnly: true }
+      ]);
+      ensureNamedImport(sf, resolveSdkModuleSpecifier(sf), [
+        { name: "DependencyLifecycle" }
+      ]);
+      addDecoratedMethod(getModelClass(sf), {
+        name: options.methodName,
+        decoratorName: "serviceRequest",
+        decoratorArgsText: `${endpointConst}, { lifecycle: DependencyLifecycle.${lifecycle} }`,
+        // The manager invokes phase handlers error-first, passing (null, data)
+        // on success. The `error` half is only ever reached because
+        // `serviceRequest` supplies an errorHandler — the bare decorator
+        // defaults to `throw`, which fails the phase instead of calling back.
+        parameters: [
+          { name: "error", type: "string | null" },
+          {
+            name: "data",
+            type: `EndpointResponse<typeof ${endpointConst}>`
+          }
+        ],
+        returnType: "void",
+        statements: "// TODO: apply `data` to the model"
+      });
+      return;
+    }
     ensureNamedImport(sf, serviceImport, [
-      { name: "kosServiceRequest" }
+      { name: "EndpointCtx", isTypeOnly: true }
     ]);
     ensureNamedImport(sf, resolveSdkModuleSpecifier(sf), [
-      { name: "DependencyLifecycle" }
+      { name: "executeServiceRequest" },
+      { name: "kosLoggerAware" },
+      { name: "KosLoggerAware", isTypeOnly: true }
     ]);
-    const cls = getModelClass(sf);
-    addDecoratedMethod(cls, {
+    ensureFileEslintDisable(
+      sf,
+      "@typescript-eslint/no-unsafe-declaration-merging"
+    );
+    ensureDeclarationMerge(sf, className, "KosLoggerAware", typeParams);
+    addClassDecorator(getModelClass(sf), "kosLoggerAware", { argsText: "" });
+    addDecoratedMethod(getModelClass(sf), {
       name: options.methodName,
-      decoratorName: "kosServiceRequest",
-      decoratorArgsText: `{ path: ${JSON.stringify(
-        options.servicePath
-      )}, method: ${JSON.stringify(
-        method
-      )}, lifecycle: DependencyLifecycle.${lifecycle} }`,
-      returnType: "void",
-      statements: "// TODO: handle the typed response"
+      decoratorName: "serviceRequest",
+      decoratorArgsText: endpointConst,
+      // Optional: the framework appends the context, callers never pass it.
+      parameters: [
+        {
+          name: "$ctx",
+          type: `EndpointCtx<typeof ${endpointConst}>`,
+          optional: true
+        }
+      ],
+      isAsync: true,
+      returnType: "Promise<void>",
+      statements: [
+        "const data = await executeServiceRequest(this, $ctx);",
+        "if (!data) return;",
+        "// TODO: apply `data` to the model"
+      ].join("\n")
     });
   });
-  return { modelFilePath, serviceModule: serviceImport };
+  return { modelFilePath, serviceModule: serviceImport, mode };
+}
+function endpointConstName(methodName) {
+  const snake = methodName.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^A-Za-z0-9]+/g, "_").toUpperCase();
+  return `ENDPOINT_${snake}`;
 }
 function modelElementType(typeText) {
   let m;
@@ -3384,6 +3555,8 @@ export {
   BasePluginHandler,
   CONTRIBUTION_TYPE_MAP,
   DirectFileSystem,
+  KAB_OUTPUT_DIR,
+  KAB_OUTPUT_PATH,
   KOS_JSON_PATHS,
   KosConfigBuilder,
   LOCALIZED_PLUGIN_TYPES,
@@ -3437,6 +3610,7 @@ export {
   getKosProjectConfiguration,
   getProject,
   getTemplateDir,
+  listServiceCatalog,
   lookupSdkType,
   normalizeAllValues,
   normalizeOptions,
@@ -3444,6 +3618,7 @@ export {
   properCase,
   readJson,
   readNxJson,
+  resolveKabPath,
   resolveModelFilePath,
   setCodegenLogger,
   syncCiManifests,