@kosdev-code/kos-codegen-core 0.1.0-next.871 → 0.1.0-next.894

package/index.mjs

@@ -3,7 +3,7 @@ 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 { Scope, Project, QuoteKind, IndentationText, VariableDeclarationKind, Node, SyntaxKind } from "ts-morph";
 import * as ts from "typescript";
 class TrackingFileSystem {
   inner;
@@ -474,6 +474,84 @@ function generateSplashProject(codegenFs, templateDir, options) {
     normalized
   );
 }
+const MODEL_PROJECT_SUFFIX = "-models";
+const DEFAULT_MODEL_LIBS_DIR = "libs";
+const JSONC_ESLINT_PARSER_VERSION = "^2.1.0";
+function resolveModelProjectLayout(codegenFs, options) {
+  const base = dashCase(options.name);
+  const projectName = base.endsWith(MODEL_PROJECT_SUFFIX) ? base : `${base}${MODEL_PROJECT_SUFFIX}`;
+  const libsDir = (options.libsDir || DEFAULT_MODEL_LIBS_DIR).replace(
+    /\\/g,
+    "/"
+  );
+  const scope = codegenFs ? readNpmScope(codegenFs) : void 0;
+  return {
+    projectName,
+    projectRoot: `${libsDir}/${projectName}`.replace(/^\/+/, ""),
+    importPath: scope ? `@${scope}/${projectName}` : projectName
+  };
+}
+function readNpmScope(codegenFs) {
+  if (!codegenFs.exists("package.json")) {
+    return void 0;
+  }
+  const name = readJson(codegenFs, "package.json").name;
+  if (!name?.startsWith("@")) {
+    return void 0;
+  }
+  return name.split("/")[0].slice(1);
+}
+function offsetFromRoot(projectRoot) {
+  return projectRoot.split("/").filter(Boolean).map(() => "../").join("");
+}
+function generateModelProject(codegenFs, templateDir, options) {
+  const layout = resolveModelProjectLayout(codegenFs, options);
+  generateFilesFromTemplates(
+    codegenFs,
+    path.join(templateDir, "project"),
+    layout.projectRoot,
+    {
+      ...layout,
+      projectNameCamelCase: camelCase(layout.projectName),
+      offsetFromRoot: offsetFromRoot(layout.projectRoot),
+      template: ""
+    }
+  );
+  registerTsconfigPath(codegenFs, layout);
+  ensureJsoncEslintParser(codegenFs);
+  return layout;
+}
+function registerTsconfigPath(codegenFs, layout) {
+  if (!codegenFs.exists("tsconfig.base.json")) {
+    return;
+  }
+  updateJson(codegenFs, "tsconfig.base.json", (json) => {
+    json.compilerOptions = json.compilerOptions ?? {};
+    json.compilerOptions.paths = json.compilerOptions.paths ?? {};
+    json.compilerOptions.paths[layout.importPath] = [
+      `${layout.projectRoot}/src/index.ts`
+    ];
+    return json;
+  });
+}
+function ensureJsoncEslintParser(codegenFs) {
+  if (!codegenFs.exists("package.json")) {
+    return;
+  }
+  const pkg = readJson(codegenFs, "package.json");
+  const devDependencies = pkg.devDependencies ?? {};
+  if ("jsonc-eslint-parser" in devDependencies) {
+    return;
+  }
+  devDependencies["jsonc-eslint-parser"] = JSONC_ESLINT_PARSER_VERSION;
+  pkg.devDependencies = Object.fromEntries(
+    // Codepoint order, matching what Nx's own dependency helper produces.
+    Object.entries(devDependencies).sort(
+      ([a], [b]) => a < b ? -1 : a > b ? 1 : 0
+    )
+  );
+  writeJson(codegenFs, "package.json", pkg);
+}
 function generateInit(codegenFs, options) {
   const logger = getCodegenLogger();
   const { appProject, modelProject, registrationProject } = options;
@@ -913,7 +991,8 @@ function normalizeOptions(codegenFs, options, projects) {
   const booleanDefaults = {
     companion: false,
     skipRegistration: false,
-    futureAware: "none"
+    futureAware: "none",
+    singleton: false
   };
   return {
     ...booleanDefaults,
@@ -925,6 +1004,58 @@ function normalizeOptions(codegenFs, options, projects) {
     template: ""
   };
 }
+const UPDATE_RELEASE_VERSION_SCRIPT = `import devkit from "@nx/devkit";
+import { resolve } from "path";
+import { readFileSync, writeFileSync } from "fs";
+import prettier from "prettier";
+
+// KOS artifact versioning: stamps the project's .kos.json "version" field
+// (which kabtool bakes into the KAB). Never touches package.json.
+// Driven by tag-based releases:
+//   nx run-many --target=version --args=--ver=$KOSBUILD_VERSION
+
+const { readCachedProjectGraph } = devkit;
+const [, , name, versionArg] = process.argv;
+
+// "{args.ver}" arrives literally when the target runs without --args=--ver=<v>;
+// treat that (or a missing arg) as "report current version, change nothing".
+const version =
+  versionArg && !versionArg.startsWith("{args") ? versionArg : undefined;
+
+if (!name) {
+  console.error("usage: update-release-version.mjs <project> <version>");
+  process.exit(1);
+}
+
+const graph = readCachedProjectGraph();
+const project = graph.nodes[name];
+if (!project) {
+  console.error("Unknown project: " + name);
+  process.exit(1);
+}
+
+const kosJsonPath = resolve(process.cwd(), project.data.root, ".kos.json");
+let kosJson;
+try {
+  kosJson = JSON.parse(readFileSync(kosJsonPath, "utf8"));
+} catch {
+  console.error("Missing or invalid .kos.json: " + kosJsonPath);
+  process.exit(1);
+}
+
+if (!version) {
+  console.log(name + ": " + kosJson.version + " (no --ver given; unchanged)");
+  process.exit(0);
+}
+
+const prettierOptions = await prettier.resolveConfig(kosJsonPath);
+const output = await prettier.format(
+  JSON.stringify({ ...kosJson, version }, null, 2),
+  { ...prettierOptions, parser: "json" }
+);
+writeFileSync(kosJsonPath, output);
+console.log(name + ": version -> " + version);
+`;
 function transformSourceFile(codegenFs, filePath, mutate) {
   const content = codegenFs.read(filePath);
   if (content === null) {
@@ -953,6 +1084,15 @@ function readSourceFile(codegenFs, filePath, inspect) {
     project.createSourceFile(filePath, content, { overwrite: true })
   );
 }
+function decoratorConfigText(sourceFile, cls, decoratorName) {
+  const arg = cls.getDecorator(decoratorName)?.getArguments()[0];
+  if (!arg) return void 0;
+  if (arg.getKindName() === "ObjectLiteralExpression") return arg.getText();
+  const text = arg.getText().trim();
+  if (!/^[A-Za-z_$][\w$]*$/.test(text)) return text;
+  const initializer = sourceFile.getVariableDeclaration(text)?.getInitializer()?.getText();
+  return initializer ? initializer.replace(/\s+as\s+const\s*$/, "") : text;
+}
 function ensureNamedImport(sourceFile, moduleSpecifier, names) {
   const decls = sourceFile.getImportDeclarations().filter((d) => d.getModuleSpecifierValue() === moduleSpecifier);
   const existing = /* @__PURE__ */ new Set();
@@ -1120,6 +1260,40 @@ function ensureBarrelExport(sourceFile, moduleSpecifier) {
   sourceFile.addExportDeclaration({ moduleSpecifier });
   return true;
 }
+function ensureNamedExports(sourceFile, moduleSpecifier, names, isTypeOnly = false) {
+  const existing = sourceFile.getExportDeclarations().find(
+    (d) => d.getModuleSpecifierValue() === moduleSpecifier && d.isTypeOnly() === isTypeOnly
+  );
+  if (!existing) {
+    sourceFile.addExportDeclaration({
+      moduleSpecifier,
+      isTypeOnly,
+      namedExports: names.map((name) => {
+        return { name };
+      })
+    });
+    return true;
+  }
+  const present = new Set(existing.getNamedExports().map((e) => e.getName()));
+  const missing = names.filter((name) => !present.has(name));
+  if (missing.length === 0) return false;
+  existing.addNamedExports(
+    missing.map((name) => {
+      return { name };
+    })
+  );
+  return true;
+}
+function ensureExportedInterface(sourceFile, name, properties = [], extendsTypes = []) {
+  if (sourceFile.getInterface(name)) return false;
+  sourceFile.addInterface({
+    name,
+    isExported: true,
+    extends: extendsTypes,
+    properties
+  });
+  return true;
+}
 function addDecoratedMethod(cls, spec) {
   if (cls.getMethod(spec.name)) return false;
   cls.addMethod({
@@ -1272,58 +1446,6 @@ function readSummary(methodProp) {
 function unquote(name) {
   return name.replace(/^["']|["']$/g, "");
 }
-const UPDATE_RELEASE_VERSION_SCRIPT = `import devkit from "@nx/devkit";
-import { resolve } from "path";
-import { readFileSync, writeFileSync } from "fs";
-import prettier from "prettier";
-
-// KOS artifact versioning: stamps the project's .kos.json "version" field
-// (which kabtool bakes into the KAB). Never touches package.json.
-// Driven by tag-based releases:
-//   nx run-many --target=version --args=--ver=$KOSBUILD_VERSION
-
-const { readCachedProjectGraph } = devkit;
-const [, , name, versionArg] = process.argv;
-
-// "{args.ver}" arrives literally when the target runs without --args=--ver=<v>;
-// treat that (or a missing arg) as "report current version, change nothing".
-const version =
-  versionArg && !versionArg.startsWith("{args") ? versionArg : undefined;
-
-if (!name) {
-  console.error("usage: update-release-version.mjs <project> <version>");
-  process.exit(1);
-}
-
-const graph = readCachedProjectGraph();
-const project = graph.nodes[name];
-if (!project) {
-  console.error("Unknown project: " + name);
-  process.exit(1);
-}
-
-const kosJsonPath = resolve(process.cwd(), project.data.root, ".kos.json");
-let kosJson;
-try {
-  kosJson = JSON.parse(readFileSync(kosJsonPath, "utf8"));
-} catch {
-  console.error("Missing or invalid .kos.json: " + kosJsonPath);
-  process.exit(1);
-}
-
-if (!version) {
-  console.log(name + ": " + kosJson.version + " (no --ver given; unchanged)");
-  process.exit(0);
-}
-
-const prettierOptions = await prettier.resolveConfig(kosJsonPath);
-const output = await prettier.format(
-  JSON.stringify({ ...kosJson, version }, null, 2),
-  { ...prettierOptions, parser: "json" }
-);
-writeFileSync(kosJsonPath, output);
-console.log(name + ": version -> " + version);
-`;
 function appendBarrelExport(codegenFs, indexPath, exportPath) {
   const exportLine = `export * from '${exportPath}'`;
   const content = codegenFs.read(indexPath) ?? "";
@@ -1370,10 +1492,57 @@ function updateModelIndex(codegenFs, indexPath, modelPath) {
   const newContents = printer.printFile(updatedSourceFile);
   codegenFs.write(indexPath, newContents);
 }
-function generateHook(codegenFs, templateDir, options, cwd, projects) {
-  if (!options.appProject) {
-    throw new Error("No app project specified");
+function generateCompanionModel(codegenFs, templateDir, options, projects) {
+  const logger = getCodegenLogger();
+  const normalized = normalizeAllValues({
+    companionModelName: options.companionModelName,
+    modelName: options.modelName
+  });
+  const companionChildKosConfig = getKosProjectConfiguration(
+    codegenFs,
+    options.companionModelProject,
+    projects
+  );
+  const parentProject = findProjectByName(
+    codegenFs.root,
+    options.modelProject,
+    projects
+  );
+  const childProject = findProjectByName(
+    codegenFs.root,
+    options.companionModelProject,
+    projects
+  );
+  const projectRoot = childProject?.sourceRoot;
+  if (!projectRoot) {
+    logger.warn(`Companion child project source root not found`);
+    return;
+  }
+  let importPath = "";
+  if (parentProject) {
+    const pkgJsonPath = path.join(parentProject.root, "package.json");
+    try {
+      const pkgJson = readJson(codegenFs, pkgJsonPath);
+      importPath = pkgJson.name || "";
+    } catch {
+      importPath = "";
+    }
   }
+  const modelLocation = companionChildKosConfig?.generator?.defaults?.model?.folder || "";
+  const filePath = path.join(
+    projectRoot,
+    modelLocation,
+    normalized.companionModelNameDashCase
+  );
+  logger.info(`Generating companion model in ${filePath}`);
+  generateFilesFromTemplates(codegenFs, templateDir, filePath, {
+    ...options,
+    ...normalized,
+    importPath
+  });
+}
+function generateContainerModel(codegenFs, templateDir, options, cwd, projects) {
+  const logger = getCodegenLogger();
   const currentProject = getProject(codegenFs, cwd);
   const modelProjectName = options.modelProject || currentProject?.name;
   if (!modelProjectName) {
@@ -1381,56 +1550,109 @@ function generateHook(codegenFs, templateDir, options, cwd, projects) {
       "No model project found. Please specify a model project with --modelProject."
     );
   }
-  const modelName = options.name || getCurrentDirectoryName(cwd);
+  const modelName = options.modelName || getCurrentDirectoryName(cwd);
   if (!modelName) {
     throw new Error(
       "No model name found. Please specify a model name with --name."
     );
   }
-  const kosModelConfig = getKosModelConfiguration(
-    codegenFs,
-    modelProjectName,
-    modelName,
-    projects
-  );
-  options.singleton = kosModelConfig ? !!kosModelConfig.singleton : false;
-  options.name = modelName;
-  options.modelProject = modelProjectName;
+  options.modelName = modelName;
+  options.name = `${modelName}-container`;
   const normalized = normalizeOptions(codegenFs, options, projects);
-  const appProject = findProjectByName(
+  const projectConfig = findProjectByName(
     codegenFs.root,
-    normalized.appProject,
+    normalized.modelProject,
     projects
   );
-  if (!appProject) {
-    throw new Error(`App project '${normalized.appProject}' not found`);
+  if (!projectConfig) {
+    throw new Error(`Model project '${normalized.modelProject}' not found`);
   }
+  addKosModelConfiguration({
+    codegenFs,
+    modelName: normalized.nameDashCase,
+    projectName: projectConfig.name,
+    projectRoot: projectConfig.root,
+    singleton: !!options.singleton,
+    container: true,
+    // The container's exported registration bean (`export const <ProperCase>`).
+    factory: normalized.nameProperCase
+  });
   const kosConfig = getKosProjectConfiguration(
     codegenFs,
-    appProject.name,
+    projectConfig.name,
     projects
   );
-  const componentLocation = kosConfig?.generator?.defaults?.component?.folder || "";
-  options.appDirectory = options.appDirectory || componentLocation;
-  const projectRoot = appProject.sourceRoot;
+  const modelLocation = kosConfig?.generator?.defaults?.model?.folder || "";
+  const internal = !!kosConfig?.generator?.internal;
+  options.modelDirectory = options.modelDirectory || modelLocation;
+  const projectRoot = projectConfig.sourceRoot;
   if (projectRoot) {
-    generateFilesFromTemplates(
-      codegenFs,
-      templateDir,
-      path.join(
-        projectRoot,
-        options.appDirectory,
-        "hooks",
-        normalized.nameDashCase
-      ),
-      normalized
+    logger.info(
+      `Generating container model ${normalized.nameDashCase} in ${projectRoot}`
     );
-    appendBarrelExport(
-      codegenFs,
-      path.join(projectRoot, options.appDirectory, "hooks", "index.ts"),
-      `./${normalized.nameDashCase}`
+    const modelNameDashCase = normalized.modelNameDashCase || normalized.nameDashCase;
+    const modelFolder = path.join(
+      projectRoot,
+      options.modelDirectory || "",
+      modelNameDashCase
     );
+    if (options.existingModel) {
+      addContainerToExistingModelFolder(codegenFs, templateDir, modelFolder, {
+        ...normalized,
+        internal
+      });
+    } else {
+      generateFilesFromTemplates(
+        codegenFs,
+        path.join(templateDir, "model"),
+        modelFolder,
+        { ...normalized, internal }
+      );
+    }
+    const modelIndex = path.join(projectRoot, "index.ts");
+    const modelPath = normalized.modelDirectory ? `${normalized.modelDirectory}/${modelNameDashCase}` : modelNameDashCase;
+    updateModelIndex(codegenFs, modelIndex, modelPath);
+  }
+}
+function addContainerToExistingModelFolder(codegenFs, templateDir, modelFolder, substitutions) {
+  const containerFileName = `${substitutions.nameDashCase}-model.ts`;
+  const containerTemplate = path.join(
+    templateDir,
+    "model",
+    "__nameDashCase__-model.ts.template"
+  );
+  const rendered = ejs.render(
+    fs.readFileSync(containerTemplate, "utf-8"),
+    substitutions,
+    { filename: containerTemplate }
+  );
+  codegenFs.write(path.join(modelFolder, containerFileName), rendered);
+  const typesPath = path.join(modelFolder, "types", "index.d.ts");
+  if (codegenFs.read(typesPath) === null) {
+    codegenFs.write(typesPath, "");
+  }
+  transformSourceFile(codegenFs, typesPath, (sourceFile) => {
+    ensureExportedInterface(
+      sourceFile,
+      `${substitutions.nameProperCase}Options`
+    );
+  });
+  const barrelPath = path.join(modelFolder, "index.ts");
+  if (codegenFs.read(barrelPath) === null) {
+    codegenFs.write(barrelPath, "");
   }
+  transformSourceFile(codegenFs, barrelPath, (sourceFile) => {
+    const moduleSpecifier = `./${containerFileName.replace(/\.ts$/, "")}`;
+    ensureNamedExports(sourceFile, moduleSpecifier, [
+      substitutions.nameProperCase
+    ]);
+    ensureNamedExports(
+      sourceFile,
+      moduleSpecifier,
+      [`${substitutions.nameProperCase}Model`],
+      true
+    );
+  });
 }
 function generateContext(codegenFs, templateDir, options, cwd, projects) {
   if (!options.appProject) {
@@ -1484,8 +1706,10 @@ function generateContext(codegenFs, templateDir, options, cwd, projects) {
     );
   }
 }
-function generateContainerModel(codegenFs, templateDir, options, cwd, projects) {
-  const logger = getCodegenLogger();
+function generateHook(codegenFs, templateDir, options, cwd, projects) {
+  if (!options.appProject) {
+    throw new Error("No app project specified");
+  }
   const currentProject = getProject(codegenFs, cwd);
   const modelProjectName = options.modelProject || currentProject?.name;
   if (!modelProjectName) {
@@ -1493,106 +1717,56 @@ function generateContainerModel(codegenFs, templateDir, options, cwd, projects)
       "No model project found. Please specify a model project with --modelProject."
     );
   }
-  const modelName = options.modelName || getCurrentDirectoryName(cwd);
+  const modelName = options.name || getCurrentDirectoryName(cwd);
   if (!modelName) {
     throw new Error(
       "No model name found. Please specify a model name with --name."
     );
   }
-  options.modelName = modelName;
-  options.name = `${modelName}-container`;
+  const kosModelConfig = getKosModelConfiguration(
+    codegenFs,
+    modelProjectName,
+    modelName,
+    projects
+  );
+  options.singleton = kosModelConfig ? !!kosModelConfig.singleton : false;
+  options.name = modelName;
+  options.modelProject = modelProjectName;
   const normalized = normalizeOptions(codegenFs, options, projects);
-  const projectConfig = findProjectByName(
+  const appProject = findProjectByName(
     codegenFs.root,
-    normalized.modelProject,
+    normalized.appProject,
     projects
   );
-  if (!projectConfig) {
-    throw new Error(`Model project '${normalized.modelProject}' not found`);
+  if (!appProject) {
+    throw new Error(`App project '${normalized.appProject}' not found`);
   }
-  addKosModelConfiguration({
-    codegenFs,
-    modelName: normalized.nameDashCase,
-    projectName: projectConfig.name,
-    projectRoot: projectConfig.root,
-    singleton: !!options.singleton,
-    container: true,
-    // The container's exported registration bean (`export const <ProperCase>`).
-    factory: normalized.nameProperCase
-  });
   const kosConfig = getKosProjectConfiguration(
     codegenFs,
-    projectConfig.name,
+    appProject.name,
     projects
   );
-  const modelLocation = kosConfig?.generator?.defaults?.model?.folder || "";
-  const internal = !!kosConfig?.generator?.internal;
-  options.modelDirectory = options.modelDirectory || modelLocation;
-  const projectRoot = projectConfig.sourceRoot;
+  const componentLocation = kosConfig?.generator?.defaults?.component?.folder || "";
+  options.appDirectory = options.appDirectory || componentLocation;
+  const projectRoot = appProject.sourceRoot;
   if (projectRoot) {
-    logger.info(
-      `Generating container model ${normalized.nameDashCase} in ${projectRoot}`
-    );
-    const modelNameDashCase = normalized.modelNameDashCase || normalized.nameDashCase;
     generateFilesFromTemplates(
       codegenFs,
-      path.join(templateDir, "model"),
-      path.join(projectRoot, options.modelDirectory || "", modelNameDashCase),
-      { ...normalized, internal }
+      templateDir,
+      path.join(
+        projectRoot,
+        options.appDirectory,
+        "hooks",
+        normalized.nameDashCase
+      ),
+      normalized
+    );
+    appendBarrelExport(
+      codegenFs,
+      path.join(projectRoot, options.appDirectory, "hooks", "index.ts"),
+      `./${normalized.nameDashCase}`
     );
-    const modelIndex = path.join(projectRoot, "index.ts");
-    const modelPath = normalized.modelDirectory ? `${normalized.modelDirectory}/${modelNameDashCase}` : modelNameDashCase;
-    updateModelIndex(codegenFs, modelIndex, modelPath);
-  }
-}
-function generateCompanionModel(codegenFs, templateDir, options, projects) {
-  const logger = getCodegenLogger();
-  const normalized = normalizeAllValues({
-    companionModelName: options.companionModelName,
-    modelName: options.modelName
-  });
-  const companionChildKosConfig = getKosProjectConfiguration(
-    codegenFs,
-    options.companionModelProject,
-    projects
-  );
-  const parentProject = findProjectByName(
-    codegenFs.root,
-    options.modelProject,
-    projects
-  );
-  const childProject = findProjectByName(
-    codegenFs.root,
-    options.companionModelProject,
-    projects
-  );
-  const projectRoot = childProject?.sourceRoot;
-  if (!projectRoot) {
-    logger.warn(`Companion child project source root not found`);
-    return;
-  }
-  let importPath = "";
-  if (parentProject) {
-    const pkgJsonPath = path.join(parentProject.root, "package.json");
-    try {
-      const pkgJson = readJson(codegenFs, pkgJsonPath);
-      importPath = pkgJson.name || "";
-    } catch {
-      importPath = "";
-    }
   }
-  const modelLocation = companionChildKosConfig?.generator?.defaults?.model?.folder || "";
-  const filePath = path.join(
-    projectRoot,
-    modelLocation,
-    normalized.companionModelNameDashCase
-  );
-  logger.info(`Generating companion model in ${filePath}`);
-  generateFilesFromTemplates(codegenFs, templateDir, filePath, {
-    ...options,
-    ...normalized,
-    importPath
-  });
 }
 function generateModel(params) {
   const {
@@ -1691,6 +1865,55 @@ function generateModel(params) {
     );
   }
 }
+const DECLARATION_MARKER = "@kosModel";
+function findModelDeclarationFile(codegenFs, searchRoot, typeIds) {
+  const wanted = new Set(typeIds.filter(Boolean));
+  if (wanted.size === 0) return null;
+  const matches = [];
+  for (const filePath of codegenFs.listFiles(searchRoot)) {
+    if (!filePath.endsWith(".ts") || filePath.endsWith(".d.ts")) continue;
+    const content = codegenFs.read(filePath);
+    if (!content || !content.includes(DECLARATION_MARKER)) continue;
+    const declared = readDeclaredModelType(codegenFs, filePath);
+    if (declared && wanted.has(declared)) matches.push(filePath);
+  }
+  if (matches.length === 0) return null;
+  if (matches.length > 1) {
+    throw new Error(
+      `Model type '${[...wanted].join("' / '")}' is declared in more than one file:
+` + matches.sort().map((c) => `  - ${c}`).join("\n") + `
+Pass modelPath to pick one.`
+    );
+  }
+  return matches[0];
+}
+function readDeclaredModelType(codegenFs, filePath) {
+  try {
+    return readSourceFile(codegenFs, filePath, (sf) => {
+      const cls = sf.getClasses().find((c) => c.getDecorator("kosModel"));
+      if (!cls) return void 0;
+      const config = decoratorConfigText(sf, cls, "kosModel");
+      const inner = config?.startsWith("{") ? modelTypeIdProperty(config) : config;
+      if (!inner) return void 0;
+      return resolveToStringLiteral(inner.trim(), sf.getFullText());
+    });
+  } catch {
+    return void 0;
+  }
+}
+function modelTypeIdProperty(objectText) {
+  const m = objectText.match(/\bmodelTypeId\s*:\s*([^,}]+)/);
+  return m ? m[1] : void 0;
+}
+function resolveToStringLiteral(expression, fileText) {
+  const literal = expression.match(/^["'`](.*)["'`]$/);
+  if (literal) return literal[1];
+  if (!/^[A-Za-z_$][\w$]*$/.test(expression)) return void 0;
+  const declared = fileText.match(
+    new RegExp(`\\b(?:const|let|var)\\s+${expression}\\s*(?::[^=]+)?=\\s*["'\`]([^"'\`]+)["'\`]`)
+  );
+  return declared ? declared[1] : void 0;
+}
 function resolveModelFilePath(codegenFs, query, projects) {
   const kosConfig = getKosProjectConfiguration(
     codegenFs,
@@ -1725,14 +1948,23 @@ function resolveModelFilePath(codegenFs, query, projects) {
   if (codegenFs.exists(modelFilePath)) {
     return { modelFilePath, internal, sourceRoot };
   }
+  const searchRoot = path.join(sourceRoot, modelLocation);
   const discovered = findModelFileByName(
     codegenFs,
-    path.join(sourceRoot, modelLocation),
+    searchRoot,
     modelNameDashCase
   );
   if (discovered) {
     return { modelFilePath: discovered, internal, sourceRoot };
   }
+  const declaredType = kosConfig?.models?.[query.modelName]?.type;
+  const byDeclaration = findModelDeclarationFile(codegenFs, searchRoot, [
+    query.modelName,
+    ...declaredType ? [declaredType] : []
+  ]);
+  if (byDeclaration) {
+    return { modelFilePath: byDeclaration, internal, sourceRoot };
+  }
   return { modelFilePath, internal, sourceRoot };
 }
 function findModelFileByName(codegenFs, searchRoot, modelNameDashCase) {
@@ -1748,6 +1980,150 @@ Pass modelPath to pick one.`
   }
   return candidates[0];
 }
+function resolveChildModelType(codegenFs, query, projects) {
+  const childProject = query.childModelProject || query.modelProject;
+  const childType = `${properCase(query.childModel)}Model`;
+  if (childProject !== query.modelProject) {
+    const project = findProjectByName(codegenFs.root, childProject, projects);
+    const pkgJson = project ? readJson(
+      codegenFs,
+      path.join(project.root, "package.json")
+    ) : void 0;
+    return { childType, childTypeModule: pkgJson?.name };
+  }
+  const { modelFilePath: childFilePath } = resolveModelFilePath(
+    codegenFs,
+    { modelName: query.childModel, modelProject: childProject },
+    projects
+  );
+  const relative = path.relative(path.dirname(query.modelFilePath), childFilePath).replace(/\.ts$/, "");
+  return {
+    childType,
+    childTypeModule: relative.startsWith(".") ? relative : `./${relative}`
+  };
+}
+function generateViewModel(codegenFs, templateDir, options, cwd, projects) {
+  const logger = getCodegenLogger();
+  if (!options.name) {
+    throw new Error(
+      "No ViewModel name found. Please specify a name with --name."
+    );
+  }
+  const currentProject = getProject(codegenFs, cwd);
+  const modelProjectName = options.modelProject || currentProject?.name;
+  if (!modelProjectName) {
+    throw new Error(
+      "No model project found. Please specify a model project with --project."
+    );
+  }
+  const normalized = normalizeOptions(
+    codegenFs,
+    { ...options, modelProject: modelProjectName },
+    projects
+  );
+  const projectConfig = findProjectByName(
+    codegenFs.root,
+    modelProjectName,
+    projects
+  );
+  if (!projectConfig) {
+    throw new Error(`Model project '${modelProjectName}' not found`);
+  }
+  const kosConfig = getKosProjectConfiguration(
+    codegenFs,
+    projectConfig.name,
+    projects
+  );
+  const modelDirectory = options.modelDirectory || kosConfig?.generator?.defaults?.model?.folder || "";
+  const internal = !!kosConfig?.generator?.internal;
+  const projectRoot = projectConfig.sourceRoot || path.join(projectConfig.root, "src");
+  const viewModelFolder = path.join(
+    projectRoot,
+    modelDirectory,
+    normalized.nameDashCase
+  );
+  const viewModelFilePath = path.join(
+    viewModelFolder,
+    `${normalized.nameDashCase}-view-model.ts`
+  );
+  if (codegenFs.exists(viewModelFilePath)) {
+    logger.info(`ViewModel already exists: ${viewModelFilePath}`);
+    return { viewModelFilePath, created: false };
+  }
+  const resolved = (options.models || []).map(
+    (source) => resolveSourceModel(
+      codegenFs,
+      source,
+      viewModelFilePath,
+      modelProjectName,
+      projects
+    )
+  );
+  logger.info(
+    `Generating ViewModel ${normalized.nameDashCase} in ${projectRoot}`
+  );
+  const constructorParams = resolved.map(({ name, type }) => ({ name, type }));
+  generateFilesFromTemplates(codegenFs, templateDir, viewModelFolder, {
+    ...normalized,
+    internal,
+    typeId: options.typeId || normalized.nameDashCase,
+    devToolsEnabled: !!options.devToolsEnabled,
+    constructorParams,
+    constructorArgs: constructorParams.map((param) => param.name).join(", "),
+    modelImports: groupImports(resolved)
+  });
+  updateModelIndex(
+    codegenFs,
+    path.join(projectRoot, "index.ts"),
+    modelDirectory ? `${modelDirectory}/${normalized.nameDashCase}` : normalized.nameDashCase
+  );
+  return { viewModelFilePath, created: true };
+}
+function resolveSourceModel(codegenFs, source, viewModelFilePath, modelProject, projects) {
+  const sourceProject = source.project || modelProject;
+  if (sourceProject === modelProject) {
+    const { modelFilePath } = resolveModelFilePath(
+      codegenFs,
+      { modelName: source.model, modelProject: sourceProject },
+      projects
+    );
+    if (!codegenFs.exists(modelFilePath)) {
+      throw new Error(
+        `Model '${source.model}' not found in project '${sourceProject}' (looked for ${modelFilePath})`
+      );
+    }
+  } else if (!findProjectByName(codegenFs.root, sourceProject, projects)) {
+    throw new Error(`Model project '${sourceProject}' not found`);
+  }
+  const { childType, childTypeModule } = resolveChildModelType(
+    codegenFs,
+    {
+      modelFilePath: viewModelFilePath,
+      modelProject,
+      childModel: source.model,
+      childModelProject: sourceProject
+    },
+    projects
+  );
+  return {
+    name: camelCase(source.model),
+    type: childType,
+    module: childTypeModule
+  };
+}
+function groupImports(resolved) {
+  const byModule = /* @__PURE__ */ new Map();
+  for (const { type, module } of resolved) {
+    if (!module) continue;
+    const types = byModule.get(module);
+    if (!types) {
+      byModule.set(module, [type]);
+    } else if (!types.includes(type)) {
+      types.push(type);
+    }
+  }
+  return [...byModule].map(([module, types]) => ({ module, types }));
+}
 function modelBaseName(modelFilePath, modelName) {
   const base = path.basename(modelFilePath);
   const match = base.match(/^(.*)-model\.ts$/);
@@ -2256,11 +2632,25 @@ function buildDecoratorArgs(options) {
 }
 function addContainerSupportToModel(codegenFs, options, projects) {
   const logger = getCodegenLogger();
-  const childType = options.childType?.trim() || "IKosDataModel";
   const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
   if (!codegenFs.exists(modelFilePath)) {
     throw new Error(`Model file not found: ${modelFilePath}`);
   }
+  const resolvedChild = options.childModel ? resolveChildModelType(
+    codegenFs,
+    {
+      modelFilePath,
+      modelProject: options.modelProject,
+      childModel: options.childModel,
+      childModelProject: options.childModelProject
+    },
+    projects
+  ) : {
+    childType: options.childType,
+    childTypeModule: options.childTypeModule
+  };
+  const childType = resolvedChild.childType?.trim() || "IKosDataModel";
+  const childTypeModule = resolvedChild.childTypeModule;
   logger.info(
     `Adding container support (<${childType}>) to model: ${options.modelName}`
   );
@@ -2272,6 +2662,10 @@ function addContainerSupportToModel(codegenFs, options, projects) {
     ]);
     if (childType === "IKosDataModel") {
       ensureNamedImport(sf, sdk, [{ name: "IKosDataModel", isTypeOnly: true }]);
+    } else if (childTypeModule) {
+      ensureNamedImport(sf, childTypeModule, [
+        { name: childType, isTypeOnly: true }
+      ]);
     }
     const cls = getModelClass(sf);
     const className = cls.getName();
@@ -2301,6 +2695,140 @@ function addContainerSupportToModel(codegenFs, options, projects) {
   });
   return { modelFilePath };
 }
+function addParentAwareToModel(codegenFs, options, projects) {
+  const logger = getCodegenLogger();
+  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
+  if (!codegenFs.exists(modelFilePath)) {
+    throw new Error(`Model file not found: ${modelFilePath}`);
+  }
+  logger.info(`Adding parent awareness to model: ${options.modelName}`);
+  let optionsTypeName;
+  transformSourceFile(codegenFs, modelFilePath, (sf) => {
+    const sdk = resolveSdkModuleSpecifier(sf);
+    ensureNamedImport(sf, sdk, [{ name: "kosParentAware" }]);
+    const cls = getModelClass(sf);
+    addClassDecorator(cls, "kosParentAware", {
+      argsText: options.parentId ? `{ parentId: ${JSON.stringify(options.parentId)} }` : ""
+    });
+    const ctor = cls.getConstructors()[0];
+    optionsTypeName = ctor?.getParameters()[1]?.getTypeNode()?.getText()?.replace(/<.*$/, "");
+  });
+  const optionsFilePath = optionsTypeName ? extendOptionsInterface(codegenFs, modelFilePath, optionsTypeName, logger) : void 0;
+  return { modelFilePath, optionsFilePath };
+}
+function extendOptionsInterface(codegenFs, modelFilePath, optionsTypeName, logger) {
+  const typesPath = path.join(
+    path.dirname(modelFilePath),
+    "types",
+    "index.d.ts"
+  );
+  const target = codegenFs.exists(typesPath) ? typesPath : modelFilePath;
+  let extended = false;
+  transformSourceFile(codegenFs, target, (sf) => {
+    const iface = sf.getInterface(optionsTypeName);
+    if (!iface) return;
+    const already = iface.getExtends().some((clause) => clause.getText().includes("KosParentAware"));
+    if (already) {
+      extended = true;
+      return;
+    }
+    ensureNamedImport(sf, "@kosdev-code/kos-ui-sdk", [
+      { name: "KosParentAware", isTypeOnly: true }
+    ]);
+    iface.addExtends("KosParentAware");
+    extended = true;
+  });
+  if (!extended) {
+    logger.warn(
+      `Could not find interface ${optionsTypeName}; add "extends KosParentAware" to it by hand.`
+    );
+    return void 0;
+  }
+  return target;
+}
+function firstDecoratorArg(decoratorText) {
+  const open = decoratorText.indexOf("(");
+  if (open === -1) return void 0;
+  const inner = decoratorText.slice(open + 1, decoratorText.lastIndexOf(")")).replace(/\s+/g, " ").trim();
+  return inner || void 0;
+}
+function collectDecorated(cls, decoratorName) {
+  const members = [];
+  const visit = (name, decoratorTextOf, typeText) => {
+    const text = decoratorTextOf();
+    if (text === void 0) return;
+    members.push({
+      name,
+      arg: firstDecoratorArg(text),
+      type: typeText || void 0
+    });
+  };
+  for (const m of cls.getMethods()) {
+    const dec = m.getDecorator(decoratorName);
+    if (dec) {
+      visit(m.getName(), () => dec.getText(), m.getReturnTypeNode()?.getText());
+    }
+  }
+  for (const p of cls.getProperties()) {
+    const dec = p.getDecorator(decoratorName);
+    if (dec) {
+      visit(p.getName(), () => dec.getText(), p.getTypeNode()?.getText());
+    }
+  }
+  return members;
+}
+function describeModel(codegenFs, options, projects) {
+  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
+  const content = codegenFs.read(modelFilePath);
+  if (content === null) {
+    throw new Error(`Model file not found: ${modelFilePath}`);
+  }
+  const project = new Project({ useInMemoryFileSystem: true });
+  const sf = project.createSourceFile(modelFilePath, content, {
+    overwrite: true
+  });
+  let modelType;
+  const modelTypeDecl = sf.getVariableDeclaration("MODEL_TYPE");
+  if (modelTypeDecl) {
+    const init = modelTypeDecl.getInitializer()?.getText();
+    if (init) modelType = init.replace(/^["'`]|["'`]$/g, "");
+  }
+  const cls = sf.getClasses().find((c) => c.getDecorator("kosModel")) ?? sf.getClasses().find((c) => c.isExported()) ?? sf.getClasses()[0];
+  if (!cls) {
+    return {
+      modelFilePath,
+      modelType,
+      classDecorators: [],
+      singleton: false,
+      isCompanion: false,
+      children: [],
+      dependencies: [],
+      topicHandlers: [],
+      configProperties: [],
+      serviceRequests: [],
+      effects: [],
+      futures: []
+    };
+  }
+  const classDecorators = cls.getDecorators().map((d) => d.getName());
+  const kosModelArg = decoratorConfigText(sf, cls, "kosModel");
+  const singleton = /\bsingleton\s*:\s*true\b/.test(kosModelArg ?? "");
+  return {
+    modelFilePath,
+    modelType,
+    className: cls.getName(),
+    classDecorators,
+    singleton,
+    isCompanion: classDecorators.includes("kosCompanion"),
+    children: collectDecorated(cls, "kosChild"),
+    dependencies: collectDecorated(cls, "kosDependency"),
+    topicHandlers: collectDecorated(cls, "kosTopicHandler"),
+    configProperties: collectDecorated(cls, "kosConfigProperty"),
+    serviceRequests: collectDecorated(cls, "kosServiceRequest"),
+    effects: collectDecorated(cls, "kosModelEffect"),
+    futures: collectDecorated(cls, "kosFuture")
+  };
+}
 function addModelEffectToModel(codegenFs, options, projects) {
   const logger = getCodegenLogger();
   const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
@@ -2376,7 +2904,18 @@ function addChildToModel(codegenFs, options, projects) {
   logger.info(
     `Adding @kosChild "${options.propertyName}" (${shape}) to ${options.modelName}`
   );
-  const childType = options.childType?.trim();
+  const resolvedChild = options.childModel ? resolveChildModelType(
+    codegenFs,
+    {
+      modelFilePath,
+      modelProject: options.modelProject,
+      childModel: options.childModel,
+      childModelProject: options.childModelProject
+    },
+    projects
+  ) : { childType: options.childType, childTypeModule: options.childPackage };
+  const childType = resolvedChild.childType?.trim();
+  const childTypeModule = resolvedChild.childTypeModule;
   transformSourceFile(codegenFs, modelFilePath, (sf) => {
     const sdk = resolveSdkModuleSpecifier(sf);
     const sdkImports = [
@@ -2384,8 +2923,8 @@ function addChildToModel(codegenFs, options, projects) {
     ];
     if (shape === "container") sdkImports.push({ name: "KosModelContainer" });
     ensureNamedImport(sf, sdk, sdkImports);
-    if (options.childPackage && childType && /^[A-Za-z_$][\w$]*$/.test(childType) && !FRAMEWORK_TYPES.has(childType)) {
-      ensureNamedImport(sf, options.childPackage, [
+    if (childTypeModule && childType && /^[A-Za-z_$][\w$]*$/.test(childType) && !FRAMEWORK_TYPES.has(childType)) {
+      ensureNamedImport(sf, childTypeModule, [
         { name: childType, isTypeOnly: true }
       ]);
     }
@@ -2703,6 +3242,13 @@ function assertServiceModuleAcceptsTransform(codegenFs, serviceModuleFile, model
     `${file} predates the transform-aware service layer (EndpointCtx takes ${typeParams} type parameter). Run \`kosui api:generate --project ${modelProject} --helpers-only\` to refresh the helper layer in place (no spec fetch, openapi.d.ts untouched), then add the service request.`
   );
 }
+const MUTATING_METHODS = /* @__PURE__ */ new Set(["post", "put", "delete", "patch"]);
+function assertLifecycleSuitsMethod(method, mode, methodName) {
+  if (mode !== "lifecycle" || !MUTATING_METHODS.has(method)) return;
+  throw new Error(
+    `${methodName} is a ${method.toUpperCase()} with a lifecycle, so it would run every time the model reaches that phase rather than when something calls it — a mutation on every load. Drop \`lifecycle\` to get the method-driven form (the default for ${method.toUpperCase()}), or pass \`mode: "method"\`. If the phase really is the trigger, the model calls the method from its own lifecycle hook, where the call is visible.`
+  );
+}
 function assertServiceModuleAcceptsProvisional(codegenFs, serviceModuleFile, modelProject) {
   const file = `${serviceModuleFile}.ts`;
   if (!codegenFs.exists(file)) return;
@@ -2884,6 +3430,7 @@ function addServiceRequestToModel(codegenFs, options, projects) {
   );
   const method = (options.method || "get").toLowerCase();
   const mode = options.mode ?? (options.lifecycle ? "lifecycle" : "method");
+  assertLifecycleSuitsMethod(method, mode, options.methodName);
   const lifecycle = options.lifecycle || "LOAD";
   const catalogName = `${pascalCase(modelBase)}Endpoints`;
   const mockMode = options.mock ?? "auto";
@@ -3094,165 +3641,6 @@ function addServiceRequestToModel(codegenFs, options, projects) {
     }) : void 0
   };
 }
-function modelElementType(typeText) {
-  let m;
-  if (m = typeText.match(/^([A-Za-z_]\w*Model)\s*\[\]$/)) return m[1];
-  if (m = typeText.match(/^Array<\s*([A-Za-z_]\w*Model)\s*>$/)) return m[1];
-  if (m = typeText.match(/^(?:Map|Set)<[^>]*?\b([A-Za-z_]\w*Model)\b[^>]*>$/))
-    return m[1];
-  return null;
-}
-function validateModel(codegenFs, options, projects) {
-  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
-  const content = codegenFs.read(modelFilePath);
-  if (content === null) {
-    throw new Error(`Model file not found: ${modelFilePath}`);
-  }
-  const project = new Project({ useInMemoryFileSystem: true });
-  const sf = project.createSourceFile(modelFilePath, content, {
-    overwrite: true
-  });
-  const findings = [];
-  const hasKosModel = sf.getClasses().some((c) => c.getDecorator("kosModel"));
-  if (!hasKosModel) {
-    findings.push({
-      level: "error",
-      rule: "missing-kosModel",
-      message: "No @kosModel decorator found — this is not a KOS model."
-    });
-  }
-  const imports = sf.getImportDeclarations();
-  const mobxImport = imports.find(
-    (d) => /^mobx(-react-lite)?$/.test(d.getModuleSpecifierValue())
-  );
-  if (mobxImport) {
-    findings.push({
-      level: "error",
-      rule: "mobx-import",
-      message: "Imports mobx directly. Reactivity is internal to KOS — remove the mobx import and use KOS reactivity / container models."
-    });
-  }
-  const barrelServiceRequest = imports.find(
-    (d) => d.getModuleSpecifierValue() === "@kosdev-code/kos-ui-sdk" && d.getNamedImports().some((n) => n.getName() === "kosServiceRequest")
-  );
-  if (barrelServiceRequest) {
-    findings.push({
-      level: "warning",
-      rule: "untyped-service-request",
-      message: "kosServiceRequest imported from the SDK barrel. Use the typed decorator from the api:generate'd service module so paths are validated against the OpenAPI types."
-    });
-  }
-  for (const cls of sf.getClasses()) {
-    for (const prop of cls.getProperties()) {
-      const name = prop.getName();
-      const typeText = (prop.getTypeNode()?.getText() ?? "").replace(/\s+/g, " ").trim();
-      const initText = prop.getInitializer()?.getText() ?? "";
-      const hasChild = !!prop.getDecorator("kosChild");
-      const isModelContainer = /\bI?KosModelContainer\s*</.test(typeText) || /new\s+KosModelContainer\b/.test(initText);
-      if (isModelContainer && !hasChild) {
-        findings.push({
-          level: "warning",
-          rule: "container-missing-kosChild",
-          message: `Property '${name}' is a model container but is not marked @kosChild — add @kosChild so its models join the model graph and lifecycle.`
-        });
-        continue;
-      }
-      const elem = modelElementType(typeText);
-      if (elem && !isModelContainer) {
-        findings.push({
-          level: "warning",
-          rule: "raw-model-collection",
-          message: `Property '${name}' is a raw ${typeText} of models — prefer a KosModelContainer<${elem}> (indexing, sorting, lifecycle, delta handling) marked @kosChild.`
-        });
-      }
-    }
-  }
-  const hasError = findings.some((f) => f.level === "error");
-  return { modelFilePath, ok: !hasError, findings };
-}
-function firstDecoratorArg(decoratorText) {
-  const open = decoratorText.indexOf("(");
-  if (open === -1) return void 0;
-  const inner = decoratorText.slice(open + 1, decoratorText.lastIndexOf(")")).replace(/\s+/g, " ").trim();
-  return inner || void 0;
-}
-function collectDecorated(cls, decoratorName) {
-  const members = [];
-  const visit = (name, decoratorTextOf, typeText) => {
-    const text = decoratorTextOf();
-    if (text === void 0) return;
-    members.push({
-      name,
-      arg: firstDecoratorArg(text),
-      type: typeText || void 0
-    });
-  };
-  for (const m of cls.getMethods()) {
-    const dec = m.getDecorator(decoratorName);
-    if (dec) {
-      visit(m.getName(), () => dec.getText(), m.getReturnTypeNode()?.getText());
-    }
-  }
-  for (const p of cls.getProperties()) {
-    const dec = p.getDecorator(decoratorName);
-    if (dec) {
-      visit(p.getName(), () => dec.getText(), p.getTypeNode()?.getText());
-    }
-  }
-  return members;
-}
-function describeModel(codegenFs, options, projects) {
-  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
-  const content = codegenFs.read(modelFilePath);
-  if (content === null) {
-    throw new Error(`Model file not found: ${modelFilePath}`);
-  }
-  const project = new Project({ useInMemoryFileSystem: true });
-  const sf = project.createSourceFile(modelFilePath, content, {
-    overwrite: true
-  });
-  let modelType;
-  const modelTypeDecl = sf.getVariableDeclaration("MODEL_TYPE");
-  if (modelTypeDecl) {
-    const init = modelTypeDecl.getInitializer()?.getText();
-    if (init) modelType = init.replace(/^["'`]|["'`]$/g, "");
-  }
-  const cls = sf.getClasses().find((c) => c.getDecorator("kosModel")) ?? sf.getClasses().find((c) => c.isExported()) ?? sf.getClasses()[0];
-  if (!cls) {
-    return {
-      modelFilePath,
-      modelType,
-      classDecorators: [],
-      singleton: false,
-      isCompanion: false,
-      children: [],
-      dependencies: [],
-      topicHandlers: [],
-      configProperties: [],
-      serviceRequests: [],
-      effects: [],
-      futures: []
-    };
-  }
-  const classDecorators = cls.getDecorators().map((d) => d.getName());
-  const kosModelArg = cls.getDecorator("kosModel") ? firstDecoratorArg(cls.getDecorator("kosModel").getText()) : void 0;
-  const singleton = /\bsingleton\s*:\s*true\b/.test(kosModelArg ?? "");
-  return {
-    modelFilePath,
-    modelType,
-    className: cls.getName(),
-    classDecorators,
-    singleton,
-    isCompanion: classDecorators.includes("kosCompanion"),
-    children: collectDecorated(cls, "kosChild"),
-    dependencies: collectDecorated(cls, "kosDependency"),
-    topicHandlers: collectDecorated(cls, "kosTopicHandler"),
-    configProperties: collectDecorated(cls, "kosConfigProperty"),
-    serviceRequests: collectDecorated(cls, "kosServiceRequest"),
-    effects: collectDecorated(cls, "kosModelEffect"),
-    futures: collectDecorated(cls, "kosFuture")
-  };
-}
 const DEFAULT_SDK_PACKAGE = "@kosdev-code/kos-ui-sdk";
 const MAX_SIGNATURE_CHARS = 2e3;
 function declarationEntryFromPackageJson(pkgDir) {
@@ -3436,6 +3824,82 @@ function lookupSdkType(codegenFs, options, projects) {
     )}). Check the name, or it may be internal / not part of the public surface.`
   };
 }
+function modelElementType(typeText) {
+  let m;
+  if (m = typeText.match(/^([A-Za-z_]\w*Model)\s*\[\]$/)) return m[1];
+  if (m = typeText.match(/^Array<\s*([A-Za-z_]\w*Model)\s*>$/)) return m[1];
+  if (m = typeText.match(/^(?:Map|Set)<[^>]*?\b([A-Za-z_]\w*Model)\b[^>]*>$/))
+    return m[1];
+  return null;
+}
+function validateModel(codegenFs, options, projects) {
+  const { modelFilePath } = resolveModelFilePath(codegenFs, options, projects);
+  const content = codegenFs.read(modelFilePath);
+  if (content === null) {
+    throw new Error(`Model file not found: ${modelFilePath}`);
+  }
+  const project = new Project({ useInMemoryFileSystem: true });
+  const sf = project.createSourceFile(modelFilePath, content, {
+    overwrite: true
+  });
+  const findings = [];
+  const hasKosModel = sf.getClasses().some((c) => c.getDecorator("kosModel"));
+  if (!hasKosModel) {
+    findings.push({
+      level: "error",
+      rule: "missing-kosModel",
+      message: "No @kosModel decorator found — this is not a KOS model."
+    });
+  }
+  const imports = sf.getImportDeclarations();
+  const mobxImport = imports.find(
+    (d) => /^mobx(-react-lite)?$/.test(d.getModuleSpecifierValue())
+  );
+  if (mobxImport) {
+    findings.push({
+      level: "error",
+      rule: "mobx-import",
+      message: "Imports mobx directly. Reactivity is internal to KOS — remove the mobx import and use KOS reactivity / container models."
+    });
+  }
+  const barrelServiceRequest = imports.find(
+    (d) => d.getModuleSpecifierValue() === "@kosdev-code/kos-ui-sdk" && d.getNamedImports().some((n) => n.getName() === "kosServiceRequest")
+  );
+  if (barrelServiceRequest) {
+    findings.push({
+      level: "warning",
+      rule: "untyped-service-request",
+      message: "kosServiceRequest imported from the SDK barrel. Use the typed decorator from the api:generate'd service module so paths are validated against the OpenAPI types."
+    });
+  }
+  for (const cls of sf.getClasses()) {
+    for (const prop of cls.getProperties()) {
+      const name = prop.getName();
+      const typeText = (prop.getTypeNode()?.getText() ?? "").replace(/\s+/g, " ").trim();
+      const initText = prop.getInitializer()?.getText() ?? "";
+      const hasChild = !!prop.getDecorator("kosChild");
+      const isModelContainer = /\bI?KosModelContainer\s*</.test(typeText) || /new\s+KosModelContainer\b/.test(initText);
+      if (isModelContainer && !hasChild) {
+        findings.push({
+          level: "warning",
+          rule: "container-missing-kosChild",
+          message: `Property '${name}' is a model container but is not marked @kosChild — add @kosChild so its models join the model graph and lifecycle.`
+        });
+        continue;
+      }
+      const elem = modelElementType(typeText);
+      if (elem && !isModelContainer) {
+        findings.push({
+          level: "warning",
+          rule: "raw-model-collection",
+          message: `Property '${name}' is a raw ${typeText} of models — prefer a KosModelContainer<${elem}> (indexing, sorting, lifecycle, delta handling) marked @kosChild.`
+        });
+      }
+    }
+  }
+  const hasError = findings.some((f) => f.level === "error");
+  return { modelFilePath, ok: !hasError, findings };
+}
 const PLUGIN_TYPES = {
   CUI: "cui",
   UTILITY: "utility",
@@ -3990,9 +4454,76 @@ function updatePluginConfiguration(codegenFs, projectConfig, options) {
     );
   }
 }
+function parse(content) {
+  const singleQuoted = /^\s*import\b[^"']*'/m.test(content);
+  const project = new Project({
+    useInMemoryFileSystem: true,
+    manipulationSettings: {
+      indentationText: IndentationText.TwoSpaces,
+      quoteKind: singleQuoted ? QuoteKind.Single : QuoteKind.Double
+    }
+  });
+  return project.createSourceFile("registration-chain.ts", content, {
+    overwrite: true
+  });
+}
+function chainCalls(sf, name) {
+  return sf.getDescendantsOfKind(SyntaxKind.CallExpression).filter((call) => {
+    const callee = call.getExpression();
+    return callee.getKind() === SyntaxKind.PropertyAccessExpression && callee.asKindOrThrow(SyntaxKind.PropertyAccessExpression).getName() === name;
+  });
+}
+function indentOfCall(sf, call) {
+  const text = sf.getFullText();
+  const nameNode = call.getExpression().asKindOrThrow(SyntaxKind.PropertyAccessExpression).getNameNode();
+  const lineStart = text.lastIndexOf("\n", nameNode.getStart()) + 1;
+  return text.slice(lineStart).match(/^[ \t]*/)?.[0] ?? "";
+}
+function countChainEntries(content) {
+  return chainCalls(parse(content), "model").length;
+}
+function upsertChainEntry(content, bean, importSpec) {
+  const sf = parse(content);
+  const modelCalls = chainCalls(sf, "model");
+  const registered = modelCalls.some((call) => {
+    const [arg, ...rest] = call.getArguments();
+    return rest.length === 0 && arg?.getText() === bean;
+  });
+  if (registered) return { changed: false, note: "already registered" };
+  let anchor;
+  let indent;
+  if (modelCalls.length > 0) {
+    anchor = modelCalls.reduce(
+      (last, call) => call.getEnd() > last.getEnd() ? call : last
+    );
+    indent = indentOfCall(sf, anchor);
+  } else {
+    const starts = chainCalls(sf, "models").filter(
+      (call) => call.getArguments().length === 0
+    );
+    anchor = starts[starts.length - 1];
+    if (!anchor) {
+      return {
+        changed: false,
+        error: "no .models() chain found in the registration file"
+      };
+    }
+    const text = sf.getFullText();
+    const lineStart = text.lastIndexOf("\n", anchor.getStart()) + 1;
+    indent = (text.slice(lineStart).match(/^[ \t]*/)?.[0] ?? "") + "  ";
+  }
+  anchor.replaceWithText(`${anchor.getText()}
+${indent}.model(${bean})`);
+  const imported = sf.getImportDeclarations().some(
+    (decl) => decl.getNamedImports().some((named) => named.getName() === bean)
+  );
+  if (!imported) ensureNamedImport(sf, importSpec, [{ name: bean }]);
+  return { changed: true, content: sf.getFullText(), importAdded: !imported };
+}
 export {
   BasePluginHandler,
   CONTRIBUTION_TYPE_MAP,
+  DEFAULT_MODEL_LIBS_DIR,
   DirectFileSystem,
   KAB_OUTPUT_DIR,
   KAB_OUTPUT_PATH,
@@ -4014,6 +4545,7 @@ export {
   addJavaArtifactToManifests,
   addKosModelConfiguration,
   addModelEffectToModel,
+  addParentAwareToModel,
   addPropertyToModel,
   addServiceRequestToModel,
   addTopicHandlerToModel,
@@ -4022,6 +4554,7 @@ export {
   buildSbomTarget,
   camelCase,
   constantCase,
+  countChainEntries,
   dashCase,
   describeModel,
   discoverJavaArtifacts,
@@ -4040,8 +4573,10 @@ export {
   generateHook,
   generateInit,
   generateModel,
+  generateModelProject,
   generatePolyglotWorkspace,
   generateSplashProject,
+  generateViewModel,
   getCodegenLogger,
   getCurrentDirectoryName,
   getKosModelConfigProp,
@@ -4059,10 +4594,12 @@ export {
   readNxJson,
   resolveKabPath,
   resolveModelFilePath,
+  resolveModelProjectLayout,
   setCodegenLogger,
   syncCiManifests,
   updateJson,
   updateModelIndex,
+  upsertChainEntry,
   validateModel,
   writeJson
 };