@celerity-sdk/cli 0.2.0

package/dist/index.js

@@ -0,0 +1,307 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/extract/metadata-app.ts
+import "reflect-metadata";
+import createDebug from "debug";
+import { buildModuleGraph, getClassDependencyTokens, getProviderDependencyTokens } from "@celerity-sdk/core";
+var debug = createDebug("celerity:cli");
+function scanProvider(provider, seenTokens) {
+  if (typeof provider === "function") {
+    if (seenTokens.has(provider)) return null;
+    seenTokens.add(provider);
+    return {
+      token: provider,
+      providerType: "class",
+      dependencies: getClassDependencyTokens(provider)
+    };
+  }
+  const typed = provider;
+  if (seenTokens.has(typed.provide)) return null;
+  seenTokens.add(typed.provide);
+  return {
+    token: typed.provide,
+    providerType: "useFactory" in typed ? "factory" : "useClass" in typed ? "class" : "value",
+    dependencies: getProviderDependencyTokens(typed)
+  };
+}
+__name(scanProvider, "scanProvider");
+function buildScannedModule(rootModule) {
+  const graph = buildModuleGraph(rootModule);
+  const controllerClasses = [];
+  const functionHandlers = [];
+  const providers = [];
+  const seenTokens = /* @__PURE__ */ new Set();
+  for (const [moduleClass, node] of graph) {
+    debug("scan: module %s \u2014 %d providers, %d controllers", moduleClass.name, node.providers.length, node.controllers.length);
+    for (const provider of node.providers) {
+      const scanned = scanProvider(provider, seenTokens);
+      if (scanned) providers.push(scanned);
+    }
+    for (const controller of node.controllers) {
+      controllerClasses.push(controller);
+      if (!seenTokens.has(controller)) {
+        seenTokens.add(controller);
+        providers.push({
+          token: controller,
+          providerType: "class",
+          dependencies: getClassDependencyTokens(controller)
+        });
+      }
+    }
+    functionHandlers.push(...node.functionHandlers);
+  }
+  return {
+    controllerClasses,
+    functionHandlers,
+    providers
+  };
+}
+__name(buildScannedModule, "buildScannedModule");
+function validateScannedDependencies(scanned) {
+  const registeredTokens = new Set(scanned.providers.map((p) => p.token));
+  const diagnostics = [];
+  const visited = /* @__PURE__ */ new Set();
+  function walk(token, deps) {
+    if (visited.has(token)) return;
+    visited.add(token);
+    for (const dep of deps) {
+      if (registeredTokens.has(dep)) {
+        const provider = scanned.providers.find((p) => p.token === dep);
+        if (provider) {
+          walk(dep, provider.dependencies);
+        }
+      } else if (typeof dep === "function") {
+        walk(dep, getClassDependencyTokens(dep));
+      } else {
+        diagnostics.push({
+          consumer: serializeToken(token),
+          dependency: serializeToken(dep)
+        });
+      }
+    }
+  }
+  __name(walk, "walk");
+  for (const provider of scanned.providers) {
+    walk(provider.token, provider.dependencies);
+  }
+  return diagnostics;
+}
+__name(validateScannedDependencies, "validateScannedDependencies");
+function serializeToken(token) {
+  if (typeof token === "function") return token.name;
+  if (typeof token === "symbol") return token.description ?? "Symbol()";
+  return String(token);
+}
+__name(serializeToken, "serializeToken");
+
+// src/extract/serializer.ts
+import "reflect-metadata";
+import { CONTROLLER_METADATA, HTTP_METHOD_METADATA, ROUTE_PATH_METADATA, GUARD_PROTECTEDBY_METADATA, GUARD_CUSTOM_METADATA, PUBLIC_METADATA, CUSTOM_METADATA } from "@celerity-sdk/core";
+
+// src/extract/path-utils.ts
+import { joinHandlerPath } from "@celerity-sdk/common";
+
+// src/extract/identity.ts
+import { basename, dirname, relative } from "path";
+function deriveClassResourceName(className, methodName) {
+  const camelClass = className.charAt(0).toLowerCase() + className.slice(1);
+  return `${camelClass}_${methodName}`;
+}
+__name(deriveClassResourceName, "deriveClassResourceName");
+function deriveClassHandlerName(className, methodName) {
+  return `${className}-${methodName}`;
+}
+__name(deriveClassHandlerName, "deriveClassHandlerName");
+function deriveClassHandlerFunction(sourceFile, className, methodName) {
+  const base = basename(sourceFile).replace(/\.[^.]+$/, "");
+  return `${base}.${className}.${methodName}`;
+}
+__name(deriveClassHandlerFunction, "deriveClassHandlerFunction");
+function deriveFunctionResourceName(exportName) {
+  return exportName;
+}
+__name(deriveFunctionResourceName, "deriveFunctionResourceName");
+function deriveFunctionHandlerFunction(sourceFile, exportName) {
+  const base = basename(sourceFile).replace(/\.[^.]+$/, "");
+  return `${base}.${exportName}`;
+}
+__name(deriveFunctionHandlerFunction, "deriveFunctionHandlerFunction");
+function deriveCodeLocation(sourceFile, projectRoot) {
+  const rel = relative(projectRoot, sourceFile);
+  const dir = dirname(rel);
+  return dir === "." ? "./" : `./${dir}`;
+}
+__name(deriveCodeLocation, "deriveCodeLocation");
+
+// src/extract/serializer.ts
+function serializeManifest(scanned, sourceFile, options) {
+  const handlers = [];
+  const functionHandlers = [];
+  for (const controllerClass of scanned.controllerClasses) {
+    const entries = serializeClassHandler(controllerClass, sourceFile, options);
+    handlers.push(...entries);
+  }
+  for (const fnHandler of scanned.functionHandlers) {
+    const entry = serializeFunctionHandler(fnHandler, sourceFile, options);
+    if (entry) {
+      functionHandlers.push(entry);
+    }
+  }
+  return {
+    version: "1.0.0",
+    handlers,
+    functionHandlers,
+    dependencyGraph: serializeDependencyGraph(scanned)
+  };
+}
+__name(serializeManifest, "serializeManifest");
+function extractClassMeta(controllerClass) {
+  const controllerMeta = Reflect.getOwnMetadata(CONTROLLER_METADATA, controllerClass);
+  if (!controllerMeta) return null;
+  return {
+    prefix: controllerMeta.prefix ?? "",
+    protectedBy: Reflect.getOwnMetadata(GUARD_PROTECTEDBY_METADATA, controllerClass) ?? [],
+    customGuardName: Reflect.getOwnMetadata(GUARD_CUSTOM_METADATA, controllerClass),
+    customMetadata: Reflect.getOwnMetadata(CUSTOM_METADATA, controllerClass) ?? {}
+  };
+}
+__name(extractClassMeta, "extractClassMeta");
+function buildMethodAnnotations(classMeta, prototype, methodName, httpMethod, fullPath) {
+  const annotations = {};
+  annotations["celerity.handler.http"] = true;
+  annotations["celerity.handler.http.method"] = httpMethod;
+  annotations["celerity.handler.http.path"] = fullPath;
+  const methodProtectedBy = Reflect.getOwnMetadata(GUARD_PROTECTEDBY_METADATA, prototype, methodName) ?? [];
+  const allProtectedBy = [
+    ...classMeta.protectedBy,
+    ...methodProtectedBy
+  ];
+  if (allProtectedBy.length > 0) {
+    annotations["celerity.handler.guard.protectedBy"] = allProtectedBy;
+  }
+  if (classMeta.customGuardName) {
+    annotations["celerity.handler.guard.custom"] = classMeta.customGuardName;
+  }
+  const isPublic = Reflect.getOwnMetadata(PUBLIC_METADATA, prototype, methodName) === true;
+  if (isPublic) {
+    annotations["celerity.handler.public"] = true;
+  }
+  const methodCustomMetadata = Reflect.getOwnMetadata(CUSTOM_METADATA, prototype, methodName) ?? {};
+  const customMetadata = {
+    ...classMeta.customMetadata,
+    ...methodCustomMetadata
+  };
+  for (const [key, value] of Object.entries(customMetadata)) {
+    if (value === void 0) continue;
+    annotations[`celerity.handler.metadata.${key}`] = serializeAnnotationValue(value);
+  }
+  return annotations;
+}
+__name(buildMethodAnnotations, "buildMethodAnnotations");
+function serializeClassHandler(controllerClass, sourceFile, options) {
+  const classMeta = extractClassMeta(controllerClass);
+  if (!classMeta) return [];
+  const className = controllerClass.name;
+  const prototype = controllerClass.prototype;
+  const methods = Object.getOwnPropertyNames(prototype).filter((n) => n !== "constructor");
+  const entries = [];
+  for (const methodName of methods) {
+    const httpMethod = Reflect.getOwnMetadata(HTTP_METHOD_METADATA, prototype, methodName);
+    if (!httpMethod) continue;
+    const routePath = Reflect.getOwnMetadata(ROUTE_PATH_METADATA, prototype, methodName) ?? "/";
+    const fullPath = joinHandlerPath(classMeta.prefix, routePath);
+    const annotations = buildMethodAnnotations(classMeta, prototype, methodName, httpMethod, fullPath);
+    entries.push({
+      resourceName: deriveClassResourceName(className, methodName),
+      className,
+      methodName,
+      sourceFile,
+      handlerType: "http",
+      annotations,
+      spec: {
+        handlerName: deriveClassHandlerName(className, methodName),
+        codeLocation: deriveCodeLocation(sourceFile, options.projectRoot),
+        handler: deriveClassHandlerFunction(sourceFile, className, methodName)
+      }
+    });
+  }
+  return entries;
+}
+__name(serializeClassHandler, "serializeClassHandler");
+function serializeFunctionHandler(definition, sourceFile, options) {
+  const exportName = definition.metadata.handlerName ?? "handler";
+  const customMetadata = definition.metadata.customMetadata ?? {};
+  const annotations = {};
+  const path = definition.metadata.path;
+  const method = definition.metadata.method;
+  if (path !== void 0 && method !== void 0) {
+    annotations["celerity.handler.http"] = true;
+    annotations["celerity.handler.http.method"] = method;
+    annotations["celerity.handler.http.path"] = path;
+  }
+  for (const [key, value] of Object.entries(customMetadata)) {
+    if (value === void 0) continue;
+    annotations[`celerity.handler.metadata.${key}`] = serializeAnnotationValue(value);
+  }
+  return {
+    resourceName: deriveFunctionResourceName(exportName),
+    exportName,
+    sourceFile,
+    ...Object.keys(annotations).length > 0 ? {
+      annotations
+    } : {},
+    spec: {
+      handlerName: exportName,
+      codeLocation: deriveCodeLocation(sourceFile, options.projectRoot),
+      handler: deriveFunctionHandlerFunction(sourceFile, exportName)
+    }
+  };
+}
+__name(serializeFunctionHandler, "serializeFunctionHandler");
+function serializeAnnotationValue(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") return value;
+  if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+    return value;
+  }
+  return JSON.stringify(value);
+}
+__name(serializeAnnotationValue, "serializeAnnotationValue");
+function serializeToken2(token) {
+  if (typeof token === "function") return token.name;
+  if (typeof token === "symbol") return token.description ?? "Symbol()";
+  return token;
+}
+__name(serializeToken2, "serializeToken");
+function tokenType(token) {
+  if (typeof token === "function") return "class";
+  if (typeof token === "symbol") return "symbol";
+  return "string";
+}
+__name(tokenType, "tokenType");
+function serializeDependencyGraph(scanned) {
+  const nodes = scanned.providers.map((provider) => ({
+    token: serializeToken2(provider.token),
+    tokenType: tokenType(provider.token),
+    providerType: provider.providerType,
+    dependencies: provider.dependencies.map(serializeToken2)
+  }));
+  return {
+    nodes
+  };
+}
+__name(serializeDependencyGraph, "serializeDependencyGraph");
+export {
+  buildScannedModule,
+  deriveClassHandlerFunction,
+  deriveClassHandlerName,
+  deriveClassResourceName,
+  deriveCodeLocation,
+  deriveFunctionHandlerFunction,
+  deriveFunctionResourceName,
+  joinHandlerPath,
+  serializeManifest,
+  validateScannedDependencies
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/extract/metadata-app.ts","../src/extract/serializer.ts","../src/extract/path-utils.ts","../src/extract/identity.ts"],"sourcesContent":["import \"reflect-metadata\";\nimport createDebug from \"debug\";\nimport type {\n  Type,\n  InjectionToken,\n  Provider,\n  FunctionHandlerDefinition,\n} from \"@celerity-sdk/types\";\nimport {\n  buildModuleGraph,\n  getClassDependencyTokens,\n  getProviderDependencyTokens,\n} from \"@celerity-sdk/core\";\nimport type { ModuleGraph } from \"@celerity-sdk/core\";\n\nconst debug = createDebug(\"celerity:cli\");\n\nexport type ScannedProvider = {\n  token: InjectionToken;\n  providerType: \"class\" | \"factory\" | \"value\";\n  dependencies: InjectionToken[];\n};\n\nexport type ScannedModule = {\n  controllerClasses: Type[];\n  functionHandlers: FunctionHandlerDefinition[];\n  providers: ScannedProvider[];\n};\n\nfunction scanProvider(\n  provider: Type | (Provider & { provide: InjectionToken }),\n  seenTokens: Set<InjectionToken>,\n): ScannedProvider | null {\n  if (typeof provider === \"function\") {\n    if (seenTokens.has(provider)) return null;\n    seenTokens.add(provider);\n    return {\n      token: provider,\n      providerType: \"class\",\n      dependencies: getClassDependencyTokens(provider),\n    };\n  }\n\n  const typed = provider as Provider & { provide: InjectionToken };\n  if (seenTokens.has(typed.provide)) return null;\n  seenTokens.add(typed.provide);\n\n  return {\n    token: typed.provide,\n    providerType: \"useFactory\" in typed ? \"factory\" : \"useClass\" in typed ? \"class\" : \"value\",\n    dependencies: getProviderDependencyTokens(typed),\n  };\n}\n\n/**\n * Builds a scanned module from the root module class using the shared\n * `buildModuleGraph` from core. Collects all handler classes, function\n * handler definitions, and provider dependency information without\n * instantiating anything.\n *\n * Inherits circular import detection from the shared graph builder.\n */\nexport function buildScannedModule(rootModule: Type): ScannedModule {\n  const graph: ModuleGraph = buildModuleGraph(rootModule);\n  const controllerClasses: Type[] = [];\n  const functionHandlers: FunctionHandlerDefinition[] = [];\n  const providers: ScannedProvider[] = [];\n  const seenTokens = new Set<InjectionToken>();\n\n  for (const [moduleClass, node] of graph) {\n    debug(\n      \"scan: module %s — %d providers, %d controllers\",\n      moduleClass.name,\n      node.providers.length,\n      node.controllers.length,\n    );\n    for (const provider of node.providers) {\n      const scanned = scanProvider(provider, seenTokens);\n      if (scanned) providers.push(scanned);\n    }\n\n    for (const controller of node.controllers) {\n      controllerClasses.push(controller);\n      if (!seenTokens.has(controller)) {\n        seenTokens.add(controller);\n        providers.push({\n          token: controller,\n          providerType: \"class\",\n          dependencies: getClassDependencyTokens(controller),\n        });\n      }\n    }\n\n    functionHandlers.push(...node.functionHandlers);\n  }\n\n  return { controllerClasses, functionHandlers, providers };\n}\n\nexport type DependencyDiagnostic = {\n  consumer: string;\n  dependency: string;\n};\n\n/**\n * Validates that all scanned providers have resolvable dependencies.\n * Returns an array of diagnostics for each unresolvable dependency.\n * A token is resolvable if it's registered or is a class (implicitly constructable).\n */\nexport function validateScannedDependencies(scanned: ScannedModule): DependencyDiagnostic[] {\n  const registeredTokens = new Set<InjectionToken>(scanned.providers.map((p) => p.token));\n  const diagnostics: DependencyDiagnostic[] = [];\n  const visited = new Set<InjectionToken>();\n\n  function walk(token: InjectionToken, deps: InjectionToken[]): void {\n    if (visited.has(token)) return;\n    visited.add(token);\n\n    for (const dep of deps) {\n      if (registeredTokens.has(dep)) {\n        const provider = scanned.providers.find((p) => p.token === dep);\n        if (provider) {\n          walk(dep, provider.dependencies);\n        }\n      } else if (typeof dep === \"function\") {\n        walk(dep, getClassDependencyTokens(dep as Type));\n      } else {\n        diagnostics.push({\n          consumer: serializeToken(token),\n          dependency: serializeToken(dep),\n        });\n      }\n    }\n  }\n\n  for (const provider of scanned.providers) {\n    walk(provider.token, provider.dependencies);\n  }\n\n  return diagnostics;\n}\n\nfunction serializeToken(token: InjectionToken): string {\n  if (typeof token === \"function\") return token.name;\n  if (typeof token === \"symbol\") return token.description ?? \"Symbol()\";\n  return String(token);\n}\n","import \"reflect-metadata\";\nimport type { Type, HttpMethod, InjectionToken } from \"@celerity-sdk/types\";\nimport {\n  CONTROLLER_METADATA,\n  HTTP_METHOD_METADATA,\n  ROUTE_PATH_METADATA,\n  GUARD_PROTECTEDBY_METADATA,\n  GUARD_CUSTOM_METADATA,\n  PUBLIC_METADATA,\n  CUSTOM_METADATA,\n} from \"@celerity-sdk/core\";\nimport type { ControllerMetadata } from \"@celerity-sdk/core\";\nimport type { ScannedModule } from \"./metadata-app\";\nimport type {\n  HandlerManifest,\n  ClassHandlerEntry,\n  FunctionHandlerEntry,\n  DependencyGraph,\n  DependencyNode,\n} from \"./types\";\nimport { joinHandlerPath } from \"./path-utils\";\nimport {\n  deriveClassResourceName,\n  deriveClassHandlerName,\n  deriveClassHandlerFunction,\n  deriveCodeLocation,\n  deriveFunctionResourceName,\n  deriveFunctionHandlerFunction,\n} from \"./identity\";\n\nexport type SerializeOptions = {\n  projectRoot: string;\n};\n\nexport function serializeManifest(\n  scanned: ScannedModule,\n  sourceFile: string,\n  options: SerializeOptions,\n): HandlerManifest {\n  const handlers: ClassHandlerEntry[] = [];\n  const functionHandlers: FunctionHandlerEntry[] = [];\n\n  for (const controllerClass of scanned.controllerClasses) {\n    const entries = serializeClassHandler(controllerClass, sourceFile, options);\n    handlers.push(...entries);\n  }\n\n  for (const fnHandler of scanned.functionHandlers) {\n    const entry = serializeFunctionHandler(fnHandler, sourceFile, options);\n    if (entry) {\n      functionHandlers.push(entry);\n    }\n  }\n\n  return {\n    version: \"1.0.0\",\n    handlers,\n    functionHandlers,\n    dependencyGraph: serializeDependencyGraph(scanned),\n  };\n}\n\ntype ClassMeta = {\n  prefix: string;\n  protectedBy: string[];\n  customGuardName: string | undefined;\n  customMetadata: Record<string, unknown>;\n};\n\nfunction extractClassMeta(controllerClass: Type): ClassMeta | null {\n  const controllerMeta: ControllerMetadata | undefined = Reflect.getOwnMetadata(\n    CONTROLLER_METADATA,\n    controllerClass,\n  );\n  if (!controllerMeta) return null;\n\n  return {\n    prefix: controllerMeta.prefix ?? \"\",\n    protectedBy: Reflect.getOwnMetadata(GUARD_PROTECTEDBY_METADATA, controllerClass) ?? [],\n    customGuardName: Reflect.getOwnMetadata(GUARD_CUSTOM_METADATA, controllerClass),\n    customMetadata: Reflect.getOwnMetadata(CUSTOM_METADATA, controllerClass) ?? {},\n  };\n}\n\nfunction buildMethodAnnotations(\n  classMeta: ClassMeta,\n  prototype: object,\n  methodName: string,\n  httpMethod: HttpMethod,\n  fullPath: string,\n): Record<string, string | string[] | boolean> {\n  const annotations: Record<string, string | string[] | boolean> = {};\n\n  annotations[\"celerity.handler.http\"] = true;\n  annotations[\"celerity.handler.http.method\"] = httpMethod;\n  annotations[\"celerity.handler.http.path\"] = fullPath;\n\n  const methodProtectedBy: string[] =\n    Reflect.getOwnMetadata(GUARD_PROTECTEDBY_METADATA, prototype, methodName) ?? [];\n  const allProtectedBy = [...classMeta.protectedBy, ...methodProtectedBy];\n  if (allProtectedBy.length > 0) {\n    annotations[\"celerity.handler.guard.protectedBy\"] = allProtectedBy;\n  }\n  if (classMeta.customGuardName) {\n    annotations[\"celerity.handler.guard.custom\"] = classMeta.customGuardName;\n  }\n\n  const isPublic: boolean = Reflect.getOwnMetadata(PUBLIC_METADATA, prototype, methodName) === true;\n  if (isPublic) {\n    annotations[\"celerity.handler.public\"] = true;\n  }\n\n  const methodCustomMetadata: Record<string, unknown> =\n    Reflect.getOwnMetadata(CUSTOM_METADATA, prototype, methodName) ?? {};\n  const customMetadata = { ...classMeta.customMetadata, ...methodCustomMetadata };\n  for (const [key, value] of Object.entries(customMetadata)) {\n    if (value === undefined) continue;\n    annotations[`celerity.handler.metadata.${key}`] = serializeAnnotationValue(value);\n  }\n\n  return annotations;\n}\n\nfunction serializeClassHandler(\n  controllerClass: Type,\n  sourceFile: string,\n  options: SerializeOptions,\n): ClassHandlerEntry[] {\n  const classMeta = extractClassMeta(controllerClass);\n  if (!classMeta) return [];\n\n  const className = controllerClass.name;\n  const prototype = controllerClass.prototype as object;\n  const methods = Object.getOwnPropertyNames(prototype).filter((n) => n !== \"constructor\");\n  const entries: ClassHandlerEntry[] = [];\n\n  for (const methodName of methods) {\n    const httpMethod: HttpMethod | undefined = Reflect.getOwnMetadata(\n      HTTP_METHOD_METADATA,\n      prototype,\n      methodName,\n    );\n    if (!httpMethod) continue;\n\n    const routePath: string =\n      Reflect.getOwnMetadata(ROUTE_PATH_METADATA, prototype, methodName) ?? \"/\";\n    const fullPath = joinHandlerPath(classMeta.prefix, routePath);\n    const annotations = buildMethodAnnotations(\n      classMeta,\n      prototype,\n      methodName,\n      httpMethod,\n      fullPath,\n    );\n\n    entries.push({\n      resourceName: deriveClassResourceName(className, methodName),\n      className,\n      methodName,\n      sourceFile,\n      handlerType: \"http\",\n      annotations,\n      spec: {\n        handlerName: deriveClassHandlerName(className, methodName),\n        codeLocation: deriveCodeLocation(sourceFile, options.projectRoot),\n        handler: deriveClassHandlerFunction(sourceFile, className, methodName),\n      },\n    });\n  }\n\n  return entries;\n}\n\nfunction serializeFunctionHandler(\n  definition: { metadata: Record<string, unknown>; handler: (...args: unknown[]) => unknown },\n  sourceFile: string,\n  options: SerializeOptions,\n): FunctionHandlerEntry | null {\n  // Function handlers don't have a reliable export name from the definition alone.\n  // The CLI entry point will need to derive this from the module's named exports.\n  // For now, use \"handler\" as a placeholder — the CLI enriches this.\n  const exportName = (definition.metadata.handlerName as string) ?? \"handler\";\n  const customMetadata = (definition.metadata.customMetadata as Record<string, unknown>) ?? {};\n\n  const annotations: Record<string, string | string[] | boolean> = {};\n\n  const path = definition.metadata.path as string | undefined;\n  const method = definition.metadata.method as string | undefined;\n  if (path !== undefined && method !== undefined) {\n    annotations[\"celerity.handler.http\"] = true;\n    annotations[\"celerity.handler.http.method\"] = method;\n    annotations[\"celerity.handler.http.path\"] = path;\n  }\n\n  for (const [key, value] of Object.entries(customMetadata)) {\n    if (value === undefined) continue;\n    annotations[`celerity.handler.metadata.${key}`] = serializeAnnotationValue(value);\n  }\n\n  return {\n    resourceName: deriveFunctionResourceName(exportName),\n    exportName,\n    sourceFile,\n    ...(Object.keys(annotations).length > 0 ? { annotations } : {}),\n    spec: {\n      handlerName: exportName,\n      codeLocation: deriveCodeLocation(sourceFile, options.projectRoot),\n      handler: deriveFunctionHandlerFunction(sourceFile, exportName),\n    },\n  };\n}\n\nfunction serializeAnnotationValue(value: unknown): string | string[] | boolean {\n  if (typeof value === \"boolean\") return value;\n  if (typeof value === \"string\") return value;\n  if (Array.isArray(value) && value.every((v) => typeof v === \"string\")) {\n    return value as string[];\n  }\n  return JSON.stringify(value);\n}\n\nexport function serializeToken(token: InjectionToken): string {\n  if (typeof token === \"function\") return token.name;\n  if (typeof token === \"symbol\") return token.description ?? \"Symbol()\";\n  return token;\n}\n\nexport function tokenType(token: InjectionToken): \"class\" | \"string\" | \"symbol\" {\n  if (typeof token === \"function\") return \"class\";\n  if (typeof token === \"symbol\") return \"symbol\";\n  return \"string\";\n}\n\nfunction serializeDependencyGraph(scanned: ScannedModule): DependencyGraph {\n  const nodes: DependencyNode[] = scanned.providers.map((provider) => ({\n    token: serializeToken(provider.token),\n    tokenType: tokenType(provider.token),\n    providerType: provider.providerType,\n    dependencies: provider.dependencies.map(serializeToken),\n  }));\n\n  return { nodes };\n}\n","export { joinHandlerPath } from \"@celerity-sdk/common\";\n","import { basename, dirname, relative } from \"node:path\";\n\n/**\n * Derives a resource name for a class-based handler method.\n * Format: camelCase(className) + \"_\" + methodName\n *\n * @example deriveClassResourceName(\"OrdersHandler\", \"getOrder\") => \"ordersHandler_getOrder\"\n */\nexport function deriveClassResourceName(className: string, methodName: string): string {\n  const camelClass = className.charAt(0).toLowerCase() + className.slice(1);\n  return `${camelClass}_${methodName}`;\n}\n\n/**\n * Derives a handler name for a class-based handler method.\n * Format: className + \"-\" + methodName\n *\n * @example deriveClassHandlerName(\"OrdersHandler\", \"getOrder\") => \"OrdersHandler-getOrder\"\n */\nexport function deriveClassHandlerName(className: string, methodName: string): string {\n  return `${className}-${methodName}`;\n}\n\n/**\n * Derives the handler function reference for a class-based handler.\n * Format: moduleBaseName + \".\" + className + \".\" + methodName\n *\n * @example deriveClassHandlerFunction(\"src/handlers/orders.ts\", \"OrdersHandler\", \"getOrder\")\n *          => \"orders.OrdersHandler.getOrder\"\n */\nexport function deriveClassHandlerFunction(\n  sourceFile: string,\n  className: string,\n  methodName: string,\n): string {\n  const base = basename(sourceFile).replace(/\\.[^.]+$/, \"\");\n  return `${base}.${className}.${methodName}`;\n}\n\n/**\n * Derives a resource name for a function-based handler.\n * Uses the export name directly.\n *\n * @example deriveFunctionResourceName(\"getOrder\") => \"getOrder\"\n */\nexport function deriveFunctionResourceName(exportName: string): string {\n  return exportName;\n}\n\n/**\n * Derives the handler function reference for a function-based handler.\n * Format: moduleBaseName + \".\" + exportName\n *\n * @example deriveFunctionHandlerFunction(\"src/handlers/orders.ts\", \"getOrder\")\n *          => \"orders.getOrder\"\n */\nexport function deriveFunctionHandlerFunction(sourceFile: string, exportName: string): string {\n  const base = basename(sourceFile).replace(/\\.[^.]+$/, \"\");\n  return `${base}.${exportName}`;\n}\n\n/**\n * Derives the code location from a source file path relative to the project root.\n * Returns the directory prefixed with \"./\"\n *\n * @example deriveCodeLocation(\"src/handlers/orders.ts\", \"/project\") => \"./src/handlers\"\n */\nexport function deriveCodeLocation(sourceFile: string, projectRoot: string): string {\n  const rel = relative(projectRoot, sourceFile);\n  const dir = dirname(rel);\n  return dir === \".\" ? \"./\" : `./${dir}`;\n}\n"],"mappings":"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","names":["createDebug","buildModuleGraph","getClassDependencyTokens","getProviderDependencyTokens","debug","createDebug","scanProvider","provider","seenTokens","has","add","token","providerType","dependencies","getClassDependencyTokens","typed","provide","getProviderDependencyTokens","buildScannedModule","rootModule","graph","buildModuleGraph","controllerClasses","functionHandlers","providers","Set","moduleClass","node","name","length","controllers","scanned","push","controller","validateScannedDependencies","registeredTokens","map","p","diagnostics","visited","walk","deps","dep","find","consumer","serializeToken","dependency","description","String","CONTROLLER_METADATA","HTTP_METHOD_METADATA","ROUTE_PATH_METADATA","GUARD_PROTECTEDBY_METADATA","GUARD_CUSTOM_METADATA","PUBLIC_METADATA","CUSTOM_METADATA","joinHandlerPath","basename","dirname","relative","deriveClassResourceName","className","methodName","camelClass","charAt","toLowerCase","slice","deriveClassHandlerName","deriveClassHandlerFunction","sourceFile","base","basename","replace","deriveFunctionResourceName","exportName","deriveFunctionHandlerFunction","deriveCodeLocation","projectRoot","rel","relative","dir","dirname","serializeManifest","scanned","sourceFile","options","handlers","functionHandlers","controllerClass","controllerClasses","entries","serializeClassHandler","push","fnHandler","entry","serializeFunctionHandler","version","dependencyGraph","serializeDependencyGraph","extractClassMeta","controllerMeta","Reflect","getOwnMetadata","CONTROLLER_METADATA","prefix","protectedBy","GUARD_PROTECTEDBY_METADATA","customGuardName","GUARD_CUSTOM_METADATA","customMetadata","CUSTOM_METADATA","buildMethodAnnotations","classMeta","prototype","methodName","httpMethod","fullPath","annotations","methodProtectedBy","allProtectedBy","length","isPublic","PUBLIC_METADATA","methodCustomMetadata","key","value","Object","undefined","serializeAnnotationValue","className","name","methods","getOwnPropertyNames","filter","n","HTTP_METHOD_METADATA","routePath","ROUTE_PATH_METADATA","joinHandlerPath","resourceName","deriveClassResourceName","handlerType","spec","handlerName","deriveClassHandlerName","codeLocation","deriveCodeLocation","projectRoot","handler","deriveClassHandlerFunction","definition","exportName","metadata","path","method","deriveFunctionResourceName","keys","deriveFunctionHandlerFunction","Array","isArray","every","v","JSON","stringify","serializeToken","token","description","tokenType","nodes","providers","map","provider","providerType","dependencies"]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@celerity-sdk/cli",
+  "version": "0.2.0",
+  "description": "Build-time extraction tool for Celerity decorator metadata",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/newstack-cloud/celerity-node-sdk.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "celerity-extract": "./dist/extract/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./schemas/handler-manifest.v1.schema.json": "./schemas/handler-manifest.v1.schema.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "schemas"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "debug": "^4.4.0",
+    "reflect-metadata": "^0.2.0",
+    "@celerity-sdk/common": "^0.2.0",
+    "@celerity-sdk/types": "^0.2.0",
+    "@celerity-sdk/core": "^0.2.0"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}

package/schemas/handler-manifest.v1.schema.json

@@ -0,0 +1,181 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://celerityframework.com/schemas/handler-manifest.v1.schema.json",
+  "title": "Celerity Handler Manifest",
+  "description": "Output schema for the celerity-extract CLI tool. Describes all handlers discovered in a Celerity application module via decorator/metadata scanning. Consumed by the Celerity CLI to merge with blueprint infrastructure configuration.",
+  "type": "object",
+  "required": ["version", "handlers", "functionHandlers", "dependencyGraph"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "const": "1.0.0",
+      "description": "Schema version. Consumers should check this field to ensure compatibility."
+    },
+    "handlers": {
+      "type": "array",
+      "description": "Class-based handlers discovered from @Controller-decorated classes.",
+      "items": { "$ref": "#/$defs/ClassHandlerEntry" }
+    },
+    "functionHandlers": {
+      "type": "array",
+      "description": "Function-based handlers registered via createHttpHandler / httpGet / httpPost / etc.",
+      "items": { "$ref": "#/$defs/FunctionHandlerEntry" }
+    },
+    "dependencyGraph": { "$ref": "#/$defs/DependencyGraph" }
+  },
+  "$defs": {
+    "AnnotationValue": {
+      "description": "Annotation values are serialized as strings, string arrays, or booleans. Complex objects are JSON-stringified into a string.",
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        { "type": "boolean" }
+      ]
+    },
+    "Annotations": {
+      "type": "object",
+      "description": "Key-value annotations using the 'celerity.handler.*' namespace. Well-known keys:\n- celerity.handler.http (boolean) — true if this is an HTTP handler\n- celerity.handler.http.method (string) — HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)\n- celerity.handler.http.path (string) — full route path using {param} format\n- celerity.handler.guard.protectedBy (string[]) — guard names protecting this handler\n- celerity.handler.guard.custom (string) — custom guard name from @Guard decorator\n- celerity.handler.public (boolean) — true if handler opts out of guards via @Public\n- celerity.handler.metadata.* (any annotation value) — user-defined metadata from @SetMetadata / @Action",
+      "additionalProperties": { "$ref": "#/$defs/AnnotationValue" }
+    },
+    "ClassHandlerSpec": {
+      "type": "object",
+      "description": "Deployment specification for a class-based handler.",
+      "required": ["handlerName", "codeLocation", "handler"],
+      "additionalProperties": false,
+      "properties": {
+        "handlerName": {
+          "type": "string",
+          "description": "Unique handler identifier. Format: ClassName-methodName (e.g. 'OrdersHandler-getOrder')."
+        },
+        "codeLocation": {
+          "type": "string",
+          "description": "Relative directory path from project root, prefixed with './' (e.g. './src/handlers')."
+        },
+        "handler": {
+          "type": "string",
+          "description": "Fully qualified handler function reference. Format: moduleBaseName.ClassName.methodName (e.g. 'app.module.OrdersHandler.getOrder')."
+        },
+        "timeout": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Handler timeout in seconds. Optional — omitted when not explicitly configured."
+        }
+      }
+    },
+    "FunctionHandlerSpec": {
+      "type": "object",
+      "description": "Deployment specification for a function-based handler.",
+      "required": ["handlerName", "codeLocation", "handler"],
+      "additionalProperties": false,
+      "properties": {
+        "handlerName": {
+          "type": "string",
+          "description": "Handler identifier derived from the export name."
+        },
+        "codeLocation": {
+          "type": "string",
+          "description": "Relative directory path from project root, prefixed with './' (e.g. './src')."
+        },
+        "handler": {
+          "type": "string",
+          "description": "Fully qualified handler function reference. Format: moduleBaseName.exportName (e.g. 'app.module.getOrder')."
+        }
+      }
+    },
+    "ClassHandlerEntry": {
+      "type": "object",
+      "description": "A single handler method discovered from a @Controller-decorated class.",
+      "required": ["resourceName", "className", "methodName", "sourceFile", "handlerType", "annotations", "spec"],
+      "additionalProperties": false,
+      "properties": {
+        "resourceName": {
+          "type": "string",
+          "description": "Blueprint resource name. Format: camelCase(className)_methodName (e.g. 'ordersHandler_getOrder')."
+        },
+        "className": {
+          "type": "string",
+          "description": "Name of the controller class (e.g. 'OrdersHandler')."
+        },
+        "methodName": {
+          "type": "string",
+          "description": "Name of the handler method (e.g. 'getOrder')."
+        },
+        "sourceFile": {
+          "type": "string",
+          "description": "Absolute path to the source file containing the handler."
+        },
+        "handlerType": {
+          "type": "string",
+          "enum": ["http", "websocket", "consumer", "schedule"],
+          "description": "The type of handler, derived from the method decorators."
+        },
+        "annotations": { "$ref": "#/$defs/Annotations" },
+        "spec": { "$ref": "#/$defs/ClassHandlerSpec" }
+      }
+    },
+    "FunctionHandlerEntry": {
+      "type": "object",
+      "description": "A function-based handler registered via createHttpHandler or shorthand helpers. Function handlers provide identity only — routing configuration comes from the blueprint.",
+      "required": ["resourceName", "exportName", "sourceFile", "spec"],
+      "additionalProperties": false,
+      "properties": {
+        "resourceName": {
+          "type": "string",
+          "description": "Blueprint resource name derived from the export name."
+        },
+        "exportName": {
+          "type": "string",
+          "description": "The named export used to register this handler."
+        },
+        "sourceFile": {
+          "type": "string",
+          "description": "Absolute path to the source file containing the handler."
+        },
+        "annotations": { "$ref": "#/$defs/Annotations" },
+        "spec": { "$ref": "#/$defs/FunctionHandlerSpec" }
+      }
+    },
+    "DependencyNode": {
+      "type": "object",
+      "description": "A provider or controller in the DI dependency graph.",
+      "required": ["token", "tokenType", "providerType", "dependencies"],
+      "additionalProperties": false,
+      "properties": {
+        "token": {
+          "type": "string",
+          "description": "Serialized DI token. Class name for class tokens, raw string for string tokens, description for symbol tokens."
+        },
+        "tokenType": {
+          "type": "string",
+          "enum": ["class", "string", "symbol"],
+          "description": "The kind of DI token."
+        },
+        "providerType": {
+          "type": "string",
+          "enum": ["class", "factory", "value"],
+          "description": "How this provider is registered (useClass, useFactory, or useValue)."
+        },
+        "dependencies": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Serialized tokens of direct dependencies. Derived from constructor params (class) or inject array (factory)."
+        }
+      }
+    },
+    "DependencyGraph": {
+      "type": "object",
+      "description": "Full service dependency graph extracted from module metadata. Includes all providers and controllers with their DI dependencies.",
+      "required": ["nodes"],
+      "additionalProperties": false,
+      "properties": {
+        "nodes": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/DependencyNode" }
+        }
+      }
+    }
+  }
+}